Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
-Copyright @copyright{} 2015, 2016, 2017, 2019 Leo Famulari@*
+Copyright @copyright{} 2015, 2016, 2017, 2019, 2020 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
-Copyright @copyright{} 2016, 2017, 2018, 2019 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 ng0@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Jan Nieuwenhuizen@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
-Copyright @copyright{} 2017, 2018, 2019 Marius Bakke@*
+Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019, 2020 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2020 Leo Prikler@*
Copyright @copyright{} 2019, 2020 Simon Tournier@*
Copyright @copyright{} 2020 Wiktor Żelazny@*
+Copyright @copyright{} 2020 Damien Cassou@*
+Copyright @copyright{} 2020 Jakub Kądziołka@*
+Copyright @copyright{} 2020 Jack Hill@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@itemize
@item
-@c Note: We need at least 0.10.2 for 'channel-send-eof'.
+@c Note: We need at least 0.12.0 for 'userauth-gssapi!'.
Support for build offloading (@pxref{Daemon Offload Setup}) and
@command{guix copy} (@pxref{Invoking guix copy}) depends on
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
-version 0.10.2 or later.
+version 0.12.0 or later.
@item
When @url{https://www.nongnu.org/lzip/lzlib.html, lzlib} is available, lzlib
Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
-110@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
+917@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
@subsection Emacs Packages
@cindex @code{emacs}
-When you install Emacs packages with Guix, the elisp files may be placed
-either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
-sub-directories of
-@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter
-directory exists because potentially there may exist thousands of Emacs
-packages and storing all their files in a single directory may not be
-reliable (because of name conflicts). So we think using a separate
-directory for each package is a good idea. It is very similar to how
-the Emacs package system organizes the file structure (@pxref{Package
-Files,,, emacs, The GNU Emacs Manual}).
-
-By default, Emacs (installed with Guix) ``knows'' where these packages
-are placed, so you do not need to perform any configuration. If, for
-some reason, you want to avoid auto-loading Emacs packages installed
-with Guix, you can do so by running Emacs with @code{--no-site-file}
-option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
+When you install Emacs packages with Guix, the Elisp files are placed
+under the @file{share/emacs/site-lisp/} directory of the profile in
+which they are installed. The Elisp libraries are made available to
+Emacs through the @code{EMACSLOADPATH} environment variable, which is
+set when installing Emacs itself.
+
+Additionally, autoload definitions are automatically evaluated at the
+initialization of Emacs, by the Guix-specific
+@code{guix-emacs-autoload-packages} procedure. If, for some reason, you
+want to avoid auto-loading the Emacs packages installed with Guix, you
+can do so by running Emacs with the @code{--no-site-file} option
+(@pxref{Init File,,, emacs, The GNU Emacs Manual}).
@subsection The GCC toolchain
Note that @command{sudo guix} runs your user's @command{guix} command and
@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To
explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
+
+The difference matters here, because @command{guix pull} updates
+the @command{guix} command and package definitions only for the user it is ran
+as. This means that if you choose to use @command{guix system reconfigure} in
+root's login shell, you'll need to @command{guix pull} separately.
@end quotation
Join us on @code{#guix} on the Freenode IRC network or on
@itemx -A [@var{regexp}]
List packages currently available in the distribution for this system
(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
-installed packages whose name matches @var{regexp}.
+available packages whose name matches @var{regexp}.
For each package, print the following items separated by tabs: its name,
its version string, the parts of the package (@pxref{Packages with
@end example
will thus build the package @code{hello} as defined in the master branch,
-which is in general a newer revison of Guix than you have installed.
+which is in general a newer revision of Guix than you have installed.
Time travel works in both directions!
Note that @command{guix time-machine} can trigger builds of channels and
instead. See also @code{--user}.
@item --expose=@var{source}[=@var{target}]
-For containers, expose the file system @var{source} from the host system
-as the read-only file system @var{target} within the container. If
+@itemx --share=@var{source}[=@var{target}]
+For containers, @code{--expose} (resp. @code{--share}) exposes the file
+system @var{source} from the host system as the read-only
+(resp. writable) file system @var{target} within the container. If
@var{target} is not specified, @var{source} is used as the target mount
point in the container.
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example
-@item --share=@var{source}[=@var{target}]
-For containers, share the file system @var{source} from the host system
-as the writable file system @var{target} within the container. If
-@var{target} is not specified, @var{source} is used as the target mount
-point in the container.
-
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible for both reading and writing via the
-@file{/exchange} directory:
-
-@example
-guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
-@end example
@end table
@command{guix environment}
if they are defined by the crate.
@end defvr
+
+@defvr {Scheme Variable} copy-build-system
+@cindex (copy build system)
+This variable is exported by @code{(guix build-system copy)}. It
+supports builds of simple packages that don't require much compiling,
+mostly just moving files around.
+
+It adds much of the @code{gnu-build-system} packages to the set of
+inputs. Because of this, the @code{copy-build-system} does not require
+all the boilerplate code often needed for the
+@code{trivial-build-system}.
+
+To further simplify the file installation process, an
+@code{#:install-plan} argument is exposed to let the packager specify
+which files go where. The install plan is a list of @code{(@var{source}
+@var{target} [@var{filters}])}. @var{filters} are optional.
+
+@itemize
+@item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
+@itemize
+@item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
+@item Otherwise install @var{source} as @var{target}.
+@end itemize
+
+@item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
+the trailing slash of @var{target} is implied with the same meaning
+as above.
+@itemize
+@item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
+@item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
+@code{#:exclude-regexp}, only select files are installed depending on
+the filters. Each filters is specified by a list of strings.
+@itemize
+@item With @code{#:include}, install all the files which the path suffix matches
+at least one of the elements in the given list.
+@item With @code{#:include-regexp}, install all the files which the
+subpaths match at least one of the regular expressions in the given
+list.
+@item The @code{#:exclude} and @code{#:exclude-regexp} filters
+are the complement of their inclusion counterpart. Without @code{#:include} flags,
+install all files but those matching the exclusion filters.
+If both inclusions and exclusions are specified, the exclusions are done
+on top of the inclusions.
+@end itemize
+@end itemize
+In all cases, the paths relative to @var{source} are preserved within
+@var{target}.
+@end itemize
+
+Examples:
+
+@itemize
+@item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
+@item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
+@item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
+e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
+@item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
+@file{share/my-app/sub/file}.
+@item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
+@file{share/my-app/file}.
+@end itemize
+@end defvr
+
+
@cindex Clojure (programming language)
@cindex simple Clojure build system
@defvr {Scheme Variable} clojure-build-system
It first creates the @code{@code{package}-autoloads.el} file, then it
byte compiles all Emacs Lisp files. Differently from the Emacs
packaging system, the Info documentation files are moved to the standard
-documentation directory and the @file{dir} file is deleted. Each
-package is installed in its own directory under
-@file{share/emacs/site-lisp/guix.d}.
+documentation directory and the @file{dir} file is deleted. The Elisp
+package files are installed directly under @file{share/emacs/site-lisp}.
@end defvr
@defvr {Scheme Variable} font-build-system
@defvr {Scheme Variable} node-build-system
This variable is exported by @code{(guix build-system node)}. It
-implements the build procedure used by @uref{http://nodejs.org,
+implements the build procedure used by @uref{https://nodejs.org,
Node.js}, which implements an approximation of the @code{npm install}
command, followed by an @code{npm test} command.
@item ssh
@cindex SSH access to build daemons
-These URIs allow you to connect to a remote daemon over
-SSH@footnote{This feature requires Guile-SSH (@pxref{Requirements}).}.
-A typical URL might look like this:
+These URIs allow you to connect to a remote daemon over SSH. This
+feature requires Guile-SSH (@pxref{Requirements}) and a working
+@code{guile} binary in @code{PATH} on the destination machine. It
+supports public key and GSSAPI authentication. A typical URL might look
+like this:
@example
ssh://charlie@@guix.example.org:22
@dots{})} expression to construct the file name @emph{at run time}.
@end deffn
+@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
+This macro is similar to the @code{parameterize} form for
+dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
+Guile Reference Manual}). The key difference is that it takes effect
+when the file-like object returned by @var{exp} is lowered to a
+derivation or store item.
+
+A typical use of @code{with-parameters} is to force the system in effect
+for a given object:
+
+@lisp
+(with-parameters ((%current-system "i686-linux"))
+ coreutils)
+@end lisp
+
+The example above returns an object that corresponds to the i686 build
+of Coreutils, regardless of the current value of @code{%current-system}.
+@end deffn
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
@include package-hello.scm
@end lisp
+@item --manifest=@var{manifest}
+@itemx -m @var{manifest}
+Build all packages listed in the given @var{manifest}
+(@pxref{profile-manifest, @option{--manifest}}).
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package or derivation @var{expr} evaluates to.
When @var{packages} is omitted, @command{guix weather} checks the availability
of substitutes for @emph{all} the packages, or for those specified with
@option{--manifest}; otherwise it only considers the specified packages. It
-is also possible to query specific system types with @option{--system}. The
-available options are listed below.
+is also possible to query specific system types with @option{--system}.
+@command{guix weather} exits with a non-zero code when the fraction of
+available substitutes is below 100%.
+
+The available options are listed below.
@table @code
@item --substitute-urls=@var{urls}
with the @code{-m} option of @command{guix package} (@pxref{Invoking
guix package}).
+This option can be repeated several times, in which case the manifests
+are concatenated.
+
@item --coverage[=@var{count}]
@itemx -c [@var{count}]
Report on substitute coverage for packages: list packages with at least
If you are a Guix developer, or if you are taking care of this build farm,
you'll probably want to have a closer look at these packages: they may simply
fail to build.
+
+@item --display-missing
+Display the list of store items for which substitutes are missing.
@end table
@node Invoking guix processes
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
+@item @code{kernel-loadable-modules} (default: '())
+A list of objects (usually packages) to collect loadable kernel modules
+from--e.g. @code{(list ddcci-driver-linux)}.
+
@item @code{kernel-arguments} (default: @code{'("quiet")})
List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
@defvr {Scheme Variable} usb-modeswitch-service-type
This is the service type for the
-@uref{http://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service. The
+@uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service. The
value for this service type is a @code{usb-modeswitch-configuration} record.
When plugged in, some USB modems (and other USB devices) initially present
@cindex ntpd, service for the Network Time Protocol daemon
@cindex real time clock
@defvr {Scheme Variable} ntp-service-type
-This is the type of the service running the @uref{http://www.ntp.org,
+This is the type of the service running the @uref{https://www.ntp.org,
Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
system clock synchronized with that of the specified NTP servers.
This example allows ssh-clients to export the @code{COLORTERM} variable.
It is set by terminal emulators, which support colors. You can use it in
-your shell's ressource file to enable colors for the prompt and commands
+your shell's resource file to enable colors for the prompt and commands
if this variable is set.
@lisp
This service extends the name service cache daemon (nscd) so that it can
resolve @code{.local} host names using
-@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
+@uref{https://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
Service Switch}, for information on host name resolution.
Additionally, add the @var{avahi} package to the system profile so that
Command to run when rebooting.
@item @code{theme} (default "maldives")
-Theme to use. Default themes provided by SDDM are "elarun" or "maldives".
+Theme to use. Default themes provided by SDDM are "elarun", "maldives" or "maya".
@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
Directory to look for themes.
@cindex X11 login
@defvr {Scheme Variable} sddm-service-type
This is the type of the service to run the
-@uref{https://github.com/sddm/sddm,SSDM display manager}. Its value
+@uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
must be a @code{sddm-configuration} record (see below).
Here's an example use:
metapackage to the system profile. ``Adding Enlightenment'' means that
@code{dbus} is extended appropriately, and several of Enlightenment's binaries
are set as setuid, allowing Enlightenment's screen locker and other
-functionality to work as expetected.
+functionality to work as expected.
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
@item @code{pulseaudio?} (default: @var{#t})
Whether ALSA applications should transparently be made to use the
-@uref{http://www.pulseaudio.org/, PulseAudio} sound server.
+@uref{https://www.pulseaudio.org/, PulseAudio} sound server.
Using PulseAudio allows you to run several sound-producing applications
at the same time and to individual control them @i{via}
details.
@deffn {Scheme Variable} pulseaudio-service-type
-This is the type for the @uref{http://www.pulseaudio.org/, PulseAudio}
+This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio}
sound server. It exists to allow system overrides of the default settings
via @code{pulseaudio-configuration}, see below.
@lisp
(service prosody-service-type
(prosody-configuration
- (modules-enabled (cons "groups" "mam" %default-modules-enabled))
+ (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
(int-components
(list
(int-component-configuration
request scheme, hostname and port that the server uses to identify
itself.
-This doesn't need to be set in the server config, and can be specifyed
+This doesn't need to be set in the server config, and can be specified
in virtual hosts. The default is @code{#f} to not specify a
@code{ServerName}.
/etc/nginx/modules/ngx_http_accept_language_module.so")))
@end lisp
+@item @code{global-directives} (default: @code{'((events . ()))})
+Association list of global directives for the top level of the nginx
+configuration. Values may themselves be association lists.
+
+@lisp
+(global-directives
+ `((worker_processes . 16)
+ (pcre_jit . on)
+ (events . ((worker_connections . 1024)))))
+@end lisp
+
@item @code{extra-content} (default: @code{""})
Extra content for the @code{http} block. Should be string or a string
valued G-expression.
VCL syntax.
@c Varnish does not support HTTPS, so keep this URL to avoid confusion.
-For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you
+For example, to mirror @url{https://www.gnu.org,www.gnu.org} with VCL you
can do something along these lines:
@lisp
Mandatory email used for registration, recovery contact, and important
account notifications.
+@item @code{server} (default: @code{#f})
+Optional URL of ACME server. Setting this overrides certbot's default,
+which is the Let's Encrypt server.
+
@item @code{rsa-key-size} (default: @code{2048})
Size of the RSA key.
@end deftp
@deftp {Data Type} zone-entry
-Data type represnting a record entry in a zone file.
+Data type representing a record entry in a zone file.
This type has the following parameters:
@table @asis
@item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
The configuration string of the backend. An example for the PKCS#11 is:
@code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
-For the pem backend, the string reprensents a path in the file system.
+For the pem backend, the string represents a path in the file system.
@end table
@end deftp
@end deftypevr
+@deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
Verbosity level.
@end deftypevr
+@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
+Authenticate with server using username/password. The option is a file
+containing username/password on 2 lines. Do not use a file-like object as it
+would be added to the store and readable by any user.
+
+Defaults to @samp{'disabled}.
+@end deftypevr
+
@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
Whether to check the server certificate has server usage extension.
@end deftypevr
+@deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
Verbosity level.
When substituting a pre-built binary fails, fall back to building
packages locally.
+@item @code{extra-options} (default: @code{'()})
+Extra options to pass when running the Cuirass processes.
+
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.
@end table
@deftypevr {@code{cgit-configuration} parameter} string root-readme
The content of the file specified with this option will be included
-verbatim below thef "about" link on the repository index page.
+verbatim below the "about" link on the repository index page.
Defaults to @samp{""}.
which to configure getmail to fetch mail from the guix-commits mailing
list.
+@item @code{extra-options} (default: @var{'()})
+Extra command line options for @code{guix-data-service}.
+
+@item @code{extra-process-jobs-options} (default: @var{'()})
+Extra command line options for @code{guix-data-service-process-jobs}.
+
@end table
@end deftp
The optional @var{config} argument specifies the configuration for
@command{dicod}, which should be a @code{<dicod-configuration>} object, by
-default it serves the GNU Collaborative International Dictonary of English.
+default it serves the GNU Collaborative International Dictionary of English.
You can add @command{open localhost} to your @file{~/.dico} file to make
@code{localhost} the default server for @command{dico} client
@cindex nss-mdns
@cindex .local, host name lookup
As an example, the declaration below configures the NSS to use the
-@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
+@uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
back-end}, which supports host name lookups over multicast DNS (mDNS)
for host names ending in @code{.local}:
switches the system profile to the specified system generation. It
also rearranges the system's existing bootloader menu entries. It
makes the menu entry for the specified system generation the default,
-and it moves the entries for the other generatiors to a submenu, if
+and it moves the entries for the other generations to a submenu, if
supported by the bootloader being used. The next time the system
boots, it will use the specified system generation.
@command{guix deploy} can log in as an unprivileged user and employ
@code{sudo} to escalate privileges. This will only work if @code{sudo} is
currently installed on the remote and can be invoked non-interactively as
-@code{user}. That is: the line in @code{sudoers} granting @code{user} the
-ability to use @code{sudo} must contain the @code{NOPASSWD} tag.
+@code{user}. That is, the line in @code{sudoers} granting @code{user} the
+ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
+be accomplished with the following operating system configuration snippet:
+
+@lisp
+(use-modules ...
+ (gnu system)) ;for %sudoers-specification
+
+(define %user "username")
+
+(operating-system
+ ...
+ (sudoers-file
+ (plain-file "sudoers"
+ (string-append (plain-file-content %sudoers-specification)
+ (format #f "~a ALL = NOPASSWD: ALL~%"
+ %username)))))
+
+@end lisp
+
+For more information regarding the format of the @file{sudoers} file,
+consult @command{man sudoers}.
@deftp {Data Type} machine
This is the data type representing a single machine in a heterogeneous Guix
where Guix always gives us a source-to-binary mapping. Thus, our goal
is to reduce the set of bootstrap binaries to the bare minimum.
-The @uref{http://bootstrappable.org, Bootstrappable.org web site} lists
+The @uref{https://bootstrappable.org, Bootstrappable.org web site} lists
on-going projects to do that. One of these is about replacing the
bootstrap GCC with a sequence of assemblers, interpreters, and compilers
of increasing complexity, which could be built from source starting from
HCoop / jackhill / guix / guix.git / blobdiff