diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 81 | ||||
| -rw-r--r-- | doc/guix.texi | 136 |
2 files changed, 188 insertions, 29 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index a0da871f1a..ce4b9db366 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -77,6 +77,12 @@ hack on Guix: guix shell -D guix --pure @end example +or even, from within a Git worktree for Guix: + +@example +guix shell --pure +@end example + @xref{Invoking guix shell}, for more information on that command. If you are unable to use Guix when building Guix from a checkout, the @@ -204,12 +210,11 @@ To that end, all the command-line tools can be used even if you have not run @code{make install}. To do that, you first need to have an environment with all the dependencies available (@pxref{Building from Git}), and then simply prefix each command with @command{./pre-inst-env} -(the @file{pre-inst-env} script lives in the top build tree of Guix; it -is generated by running @command{./bootstrap} followed by -@command{./configure}). As an example, here is how you would build the -@code{hello} package as defined in your working tree (this assumes -@command{guix-daemon} is already running on your system; it's OK if it's -a different version): +(the @file{pre-inst-env} script lives in the top build tree of Guix; +@pxref{Building from Git} to generate it). As an example, here is how you +would build the @code{hello} package as defined in your working tree (this +assumes @command{guix-daemon} is already running on your system; it's OK if +it's a different version): @example $ ./pre-inst-env guix build hello @@ -379,6 +384,70 @@ copyright-update}. If you want to do it automatically after each buffer save then add @code{(add-hook 'after-save-hook 'copyright-update)} in Emacs. +@subsection Viewing Bugs within Emacs + +Emacs has a nice minor mode called @code{bug-reference}, which, when +combined with @samp{emacs-debbugs} (the Emacs package), can be used to +open links such as @samp{<https://bugs.gnu.org/58697>} or +@samp{<https://issues.guix.gnu.org/58697>} as bug report buffers. From +there you can easily consult the email thread via the Gnus interface, +reply or modify the bug status, all without leaving the comfort of +Emacs! Below is a sample configuration to add to your @file{~/.emacs} +configuration file: + +@lisp +;;; Bug references. +(add-hook 'prog-mode-hook #'bug-reference-prog-mode) +(add-hook 'gnus-mode-hook #'bug-reference-mode) +(add-hook 'erc-mode-hook #'bug-reference-mode) +(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode) +(add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode) +(add-hook 'gnus-summary-mode-hook 'bug-reference-mode) +(add-hook 'gnus-article-mode-hook 'bug-reference-mode) + +;;; This extends the default expression (the top-most, first expression +;;; provided to 'or') to also match URLs such as +;;; <https://issues.guix.gnu.org/58697> or <https://bugs.gnu.org/58697>. +;;; It is also extended to detect "Fixes: #NNNNN" git trailers. +(setq bug-reference-bug-regexp + (rx (group (or (seq word-boundary + (or (seq (char "Bb") "ug" + (zero-or-one " ") + (zero-or-one "#")) + (seq (char "Pp") "atch" + (zero-or-one " ") + "#") + (seq (char "Ff") "ixes" + (zero-or-one ":") + (zero-or-one " ") "#") + (seq "RFE" + (zero-or-one " ") "#") + (seq "PR " + (one-or-more (char "a-z+-")) "/")) + (group (one-or-more (char "0-9")) + (zero-or-one + (seq "#" (one-or-more + (char "0-9")))))) + (seq "<https://bugs.gnu.org/" + (group-n 2 (one-or-more (char "0-9"))) + ">"))))) + +;; The following allows Emacs Debbugs user to open the issue directly within +;; Emacs. +(setq debbugs-browse-url-regexp + (rx line-start + "http" (zero-or-one "s") "://" + (or "debbugs" "issues.guix" "bugs") + ".gnu.org" (one-or-more "/") + (group (zero-or-one "cgi/bugreport.cgi?bug=")) + (group-n 3 (one-or-more digit)) + line-end)) +@end lisp + +For more information, refer to @ref{Bug Reference,,, emacs, The GNU +Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User +Guide}. + @node Packaging Guidelines @section Packaging Guidelines diff --git a/doc/guix.texi b/doc/guix.texi index fd72761c92..46591b2f64 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -6117,7 +6117,7 @@ the fingerprint of the OpenPGP used to sign it. @end enumerate Before pushing to your public Git repository, you can run @command{guix -git-authenticate} to verify that you did sign all the commits you are +git authenticate} to verify that you did sign all the commits you are about to push with an authorized key: @example @@ -16837,24 +16837,37 @@ instance to support new system services. The operating system is configured by providing an @code{operating-system} declaration in a file that can then be passed to the @command{guix system} command (@pxref{Invoking guix system}). A -simple setup, with the default system services, the default Linux-Libre -kernel, initial RAM disk, and boot loader looks like this: +simple setup, with the default Linux-Libre +kernel, initial RAM disk, and a couple of system services added to those +provided by default looks like this: @findex operating-system @lisp @include os-config-bare-bones.texi @end lisp -This example should be self-describing. Some of the fields defined +The configuration is declarative and hopefully mostly self-describing. +It is actually code in the Scheme programming language; the whole +@code{(operating-system @dots{})} expression produces a @dfn{record} +with a number of @dfn{fields}. +Some of the fields defined above, such as @code{host-name} and @code{bootloader}, are mandatory. Others, such as @code{packages} and @code{services}, can be omitted, in -which case they get a default value. +which case they get a default value. @xref{operating-system Reference}, +for details about all the available fields. -Below we discuss the effect of some of the most important fields -(@pxref{operating-system Reference}, for details about all the available -fields), and how to @dfn{instantiate} the operating system using +Below we discuss the effect of some of the most important fields, +and how to @dfn{instantiate} the operating system using @command{guix system}. +@quotation Do not panic +@cindex Scheme programming language, getting started +Intimidated by the Scheme language or curious about it? The Cookbook +has a short section to get started that explains the fundamentals, which +you will find helpful when hacking your configuration. @xref{A Scheme +Crash Course,,, guix-cookbook, GNU Guix Cookbook}. +@end quotation + @unnumberedsubsec Bootloader @cindex legacy boot, on Intel machines @@ -17028,14 +17041,6 @@ Alternatively, the @code{modify-services} macro can be used: (delete avahi-service-type)) @end lisp -@quotation Do not panic -@cindex Scheme programming language, getting started -Intimidated by the Scheme language or curious about it? The Cookbook -has a short section to get started that explains the fundamentals, which -you will find helpful when hacking your configuration. @xref{A Scheme -Crash Course,,, guix-cookbook, GNU Guix Cookbook}. -@end quotation - @unnumberedsubsec Instantiating the System Assuming the @code{operating-system} declaration @@ -20459,10 +20464,16 @@ non-loopback interfaces that can be activated. Otherwise the DHCP client listens only on the specified interfaces. @item @code{shepherd-requirement} (default: @code{'()}) +@itemx @code{shepherd-provision} (default: @code{'(networking)}) This option can be used to provide a list of symbols naming Shepherd services that this service will depend on, such as @code{'wpa-supplicant} or @code{'iwd} if you require authenticated access for encrypted WiFi or Ethernet networks. + +Likewise, @code{shepherd-provision} is a list of Shepherd service names +(symbols) provided by this service. You might want to change the +default value if you intend to run several DHCP clients, only one of +which provides the @code{networking} Shepherd service. @end table @end deftp @@ -38086,6 +38097,65 @@ File name of the file system key for the target volume. @node Guix Services @subsection Guix Services +@subsubheading Build Farm Front-End (BFFE) +The @uref{https://git.cbaines.net/guix/bffe/,Build Farm Front-End} +assists with building Guix packages in bulk. It's responsible for +submitting builds and displaying the status of the build farm. + +@defvar bffe-service-type +Service type for the Build Farm Front-End. Its value must be a +@code{bffe-configuration} object. +@end defvar + +@deftp {Data Type} bffe-configuration +Data type representing the configuration of the Build Farm Front-End. + +@table @asis +@item @code{package} (default: @code{bffe}) +The Build Farm Front-End package to use. + +@item @code{user} (default: @code{"bffe"}) +The system user to run the service as. + +@item @code{group} (default: @code{"bffe"}) +The system group to run the service as. + +@item @code{arguments} +A list of arguments to the Build Farm Front-End. These are passed to +the @code{run-bffe-service} procedure when starting the service. + +For example, the following value directs the Build Farm Front-End to +submit builds for derivations available from @code{data.guix.gnu.org} to +the Build Coordinator instance assumed to be running on the same +machine. + +@example +(list + #:build + (list + (build-from-guix-data-service + (data-service-url "https://data.guix.gnu.org") + (build-coordinator-url "http://127.0.0.1:8746") + (branches '("master")) + (systems '("x86_64-linux" "i686-linux")) + (systems-and-targets + (map (lambda (target) + (cons "x86_64-linux" target)) + '("aarch64-linux-gnu" + "i586-pc-gnu"))) + (build-priority (const 0)))) + #:web-server-args + '(#:event-source "https://example.com" + #:controller-args + (#:title "example.com build farm"))) +@end example + +@item @code{extra-environment-variables} (default: @var{'()}) +Extra environment variables to set via the shepherd service. + +@end table +@end deftp + @subsubheading Guix Build Coordinator The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build Coordinator} aids in distributing derivation builds among machines @@ -40915,8 +40985,8 @@ QEMU monitor and the VM. @cindex image, creating disk images The @code{image} command can produce various image types. The image type can be selected using the @option{--image-type} option. It -defaults to @code{mbr-raw}. When its value is @code{iso9660}, the -@option{--label} option can be used to specify a volume ID with +defaults to @code{mbr-hybrid-raw}. When its value is @code{iso9660}, +the @option{--label} option can be used to specify a volume ID with @code{image}. By default, the root file system of a disk image is mounted non-volatile; the @option{--volatile} option can be provided to make it volatile instead. When using @code{image}, the bootloader @@ -40934,8 +41004,8 @@ qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \ -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin @end example -When using the @code{mbr-raw} image type, a raw disk image is produced; -it can be copied as is to a USB stick, for instance. Assuming +When using the @code{mbr-hybrid-raw} image type, a raw disk image is +produced; it can be copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is the device corresponding to a USB stick, one can copy the image to it using the following command: @@ -41072,7 +41142,7 @@ of the image. For the @code{image} action, create an image with given @var{type}. When this option is omitted, @command{guix system} uses the -@code{mbr-raw} image type. +@code{mbr-hybrid-raw} image type. @cindex ISO-9660 format @cindex CD image format @@ -45280,7 +45350,7 @@ then directly boot from it, without any kind of installation procedure. The @command{guix system image} command is able to turn an operating system definition into a bootable image. This command supports -different image types, such as @code{mbr-raw}, @code{iso9660} and +different image types, such as @code{mbr-hybrid-raw}, @code{iso9660} and @code{docker}. Any modern @code{x86_64} machine will probably be able to boot from an @code{iso9660} image. However, there are a few machines out there that require specific image types. Those machines, in general @@ -45544,8 +45614,24 @@ from them to simplify the @code{image} definition. The @code{(gnu system image)} module provides the following @code{image} definition variables. +@defvar mbr-disk-image +An MBR disk-image composed of a single ROOT partition. The ROOT +partition starts at a 1@tie{}MiB offset so that the bootloader can +install itself in the post-MBR gap. +@end defvar + +@defvar mbr-hybrid-disk-image +An MBR disk-image composed of two partitions: a 64 bits ESP partition +and a ROOT boot partition. The ESP partition starts at a 1@tie{}MiB +offset so that a BIOS compatible bootloader can install itself in the +post-MBR gap. The image can be used by @code{x86_64} and @code{i686} +machines supporting only legacy BIOS booting. The ESP partition ensures +that it can also be used by newer machines relying on UEFI booting, +hence the @emph{hybrid} denomination. +@end defvar + @defvar efi-disk-image -A MBR disk-image composed of two partitions: a 64 bits ESP partition and +A GPT disk-image composed of two partitions: a 64 bits ESP partition and a ROOT boot partition. This image can be used on most @code{x86_64} and @code{i686} machines, supporting BIOS or UEFI booting. @end defvar @@ -45636,6 +45722,10 @@ system image)} and the @code{(gnu system images @dots{})} modules. Build an image based on the @code{mbr-disk-image} image. @end defvar +@defvar mbr-hybrid-raw-image-type +Build an image based on the @code{mbr-hybrid-disk-image} image. +@end defvar + @defvar efi-raw-image-type Build an image based on the @code{efi-disk-image} image. @end defvar |