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{} 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
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
@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
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.
@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
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
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
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