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, 2019 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019 Maxim Cournoyer@*
+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{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2019 Alex Griffin@*
Copyright @copyright{} 2019 Guillaume Le Vaillant@*
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
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
* PAM Mount Service:: Service to mount volumes when logging in.
+* Linux Services:: Services tied to the Linux kernel.
* Miscellaneous Services:: Other services.
Defining Services
GNU Guix depends on the following packages:
@itemize
-@item @url{https://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x or
+2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
@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
@command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
@example
-$ lsh-export-key --openssh < /etc/lsh/host-key.pub
+$ lsh-export-key --openssh < /etc/lsh/host-key.pub
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
@end example
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
Once this is done, you should be able to reboot the system and boot from
the USB stick or DVD. The latter usually requires you to get in the
BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
+In order to boot from Libreboot, switch to the command mode by pressing
+the @kbd{c} key and type @command{search_grub usb}.
@xref{Installing Guix in a VM}, if, instead, you would like to install
Guix System in a virtual machine (VM).
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
@noindent
-This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are usable and
-will be downloaded, when possible, for future builds.
+The text changed from ``The following derivations would be built'' to
+``112.3 MB would be downloaded''. This indicates that substitutes from
+@code{@value{SUBSTITUTE-SERVER}} are usable and will be downloaded, when
+possible, for future builds.
@cindex substitutes, how to disable
The substitute mechanism can be disabled globally by running
(channel
(name 'my-personal-packages)
(url "https://example.org/personal-packages.git")
- (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
+ (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
The @command{guix describe --format=channels} command can even generate this
@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}
the following command:
@example
-guix pack -f docker guile emacs geiser
+guix pack -f docker -S /bin=bin guile guile-readline
@end example
@noindent
The result is a tarball that can be passed to the @command{docker load}
-command. See the
+command, followed by @code{docker run}:
+
+@example
+docker load < @var{file}
+docker run -ti guile-guile-readline /bin/guile
+@end example
+
+@noindent
+where @var{file} is the image returned by @var{guix pack}, and
+@code{guile-guile-readline} is its ``image tag''. See the
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
documentation} for more information.
evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
by the daemon (@pxref{Derivations}).
-The main build system is @var{gnu-build-system}, which implements the
+The main build system is @code{gnu-build-system}, which implements the
standard build procedure for GNU and many other packages. It
is provided by the @code{(guix build-system gnu)} module.
@defvr {Scheme Variable} gnu-build-system
-@var{gnu-build-system} represents the GNU Build System, and variants
+@code{gnu-build-system} represents the GNU Build System, and variants
thereof (@pxref{Configuration, configuration and makefile conventions,,
standards, GNU Coding Standards}).
@vindex %standard-phases
The build-side module @code{(guix build gnu-build-system)} defines
-@var{%standard-phases} as the default list of build phases.
-@var{%standard-phases} is a list of symbol/procedure pairs, where the
+@code{%standard-phases} as the default list of build phases.
+@code{%standard-phases} is a list of symbol/procedure pairs, where the
procedure implements the actual phase.
The list of phases used for a particular package can be changed with the
Other @code{<build-system>} objects are defined to support other
conventions and tools used by free software packages. They inherit most
-of @var{gnu-build-system}, and differ mainly in the set of inputs
+of @code{gnu-build-system}, and differ mainly in the set of inputs
implicitly added to the build process, and in the list of phases
executed. Some of these build systems are listed below.
archive. In this case the parameter @code{#:source-dir} can be used to
specify the source sub-directory, defaulting to ``src''.
-The @code{#:main-class} parameter can be used with the minimal ant
-buildfile to specify the main class of the resulting jar. This makes the
-jar file executable. The @code{#:test-include} parameter can be used to
+The @code{#:main-class} parameter can be used with the minimal ant
+buildfile to specify the main class of the resulting jar. This makes the
+jar file executable. The @code{#:test-include} parameter can be used to
specify the list of junit tests to run. It defaults to
@code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
disable some tests. It defaults to @code{(list "**/Abstract*.java")},
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
with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
Other parameters are documented below.
-This build system is an extension of @var{ant-build-system}, but with the
+This build system is an extension of @code{ant-build-system}, but with the
following phases changed:
@table @code
@item install-doc
This phase installs all top-level files with base name matching
-@var{%doc-regex}. A different regex can be specified with the
+@code{%doc-regex}. A different regex can be specified with the
@code{#:doc-regex} parameter. All files (recursively) inside the documentation
directories specified in @code{#:doc-dirs} are installed as well.
@end table
is intended for use with packages making use of GLib or GTK+.
This build system adds the following two phases to the ones defined by
-@var{gnu-build-system}:
+@code{gnu-build-system}:
@table @code
@item glib-or-gtk-wrap
This variable is exported by @code{(guix build-system qt)}. It
is intended for use with applications using Qt or KDE.
-This build system adds the phase @code{qt-wrap} to the ones defined by
-@var{cmake-build-system}, after the @code{install} phase.
+This build system adds the following two phases to the ones defined by
+@code{cmake-build-system}:
-This phase searches for Qt5 plugin paths, QML paths and some XDG in the inputs
+@table @code
+@item check-setup
+The phase @code{check-setup} prepares the environment for running
+the checks as commonly used by Qt test programs.
+For now this only sets some environment variables:
+@code{QT_QPA_PLATFORM=offscreen},
+@code{DBUS_FATAL_WARNINGS=0} and
+@code{CTEST_OUTPUT_ON_FAILURE=1}.
+
+This phase is added before the @code{check} phase.
+It's a separate phase to ease adjusting if necessary.
+
+@item qt-wrap
+The phase @code{qt-wrap}
+searches for Qt5 plugin paths, QML paths and some XDG in the inputs
and output. In case some path is found, all programs in the output's
@file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
are wrapped in scripts defining the necessary environment variables.
This is useful when an output is known not to contain any Qt binaries, and
where wrapping would gratuitously add a dependency of that output on Qt, KDE,
or such.
+
+This phase is added after the @code{install} phase.
+@end table
@end defvr
@defvr {Scheme Variable} r-build-system
implements an installation procedure similar to the packaging system
of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
-It first creates the @code{@var{package}-autoloads.el} file, then it
+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
@code{meson-for-build}, which is special because it doesn't clear the
@code{RUNPATH} of binaries and libraries when they are installed.
-This build system is an extension of @var{gnu-build-system}, but with the
+This build system is an extension of @code{gnu-build-system}, but with the
following phases changed to some specific for Meson:
@table @code
@end defvr
@defvr {Scheme Variable} linux-module-build-system
-@var{linux-module-build-system} allows building Linux kernel modules.
+@code{linux-module-build-system} allows building Linux kernel modules.
@cindex build phases
-This build system is an extension of @var{gnu-build-system}, but with the
+This build system is an extension of @code{gnu-build-system}, but with the
following phases changed:
@table @code
@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
@item --listen=unix:/tmp/socket
Accept connections on the Unix-domain socket @file{/tmp/socket}.
@end table
+
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tool.
+
+@item -q
+Inhibit loading of the @file{~/.guile} file. By default, that
+configuration file is loaded when spawning a @code{guile} REPL.
@end table
@c *********************************************************************
@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.
recipes. In other cases, you will be able to examine the read-only recipes
for packages currently in the store.
+Instead of @code{GUIX_PACKAGE_PATH}, the command-line option
+@code{--load-path=@var{directory}} (or in short @code{-L
+@var{directory}}) allows you to add @var{directory} to the front of the
+package module search path and so make your own packages visible.
@node Invoking guix download
@section Invoking @command{guix download}
@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.
+@item --load-path=@var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
+
@end table
The @code{github} updater uses the
@itemx -s @var{system}
Consider packages for @var{system}---e.g., @code{x86_64-linux}.
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
@end table
@node Invoking guix graph
The package dependency graph is largely architecture-independent, but there
are some architecture-dependent bits that this option allows you to visualize.
+
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
@end table
On top of that, @command{guix graph} supports all the usual package
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")}.
* Game Services:: Game servers.
* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
+* Linux Services:: Services tied to the Linux kernel.
* Miscellaneous Services:: Other services.
@end menu
@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
means that all users are allowed.
@end deffn
+@cindex scanner access
+@deffn {Scheme Procedure} sane-service-type
+This service provides access to scanners @i{via}
+@uref{http://www.sane-project.org, SANE} by installing the necessary udev
+rules.
+@end deffn
+
@defvr {Scheme Variable} %standard-geoclue-applications
The standard list of well-known GeoClue application configurations,
granting authority to the GNOME date-and-time utility to ask for the
@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.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string server
-Space separated list of arguments to the userdb driver.
+Username to login to the mail server with.
Defaults to @samp{unset}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string username
-Space separated list of arguments to the userdb driver.
+Username to login to the mail server with.
Defaults to @samp{unset}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
-Space separated list of arguments to the userdb driver.
+Port number to connect to.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
-PEM-formatted key file to use for the TLS negotiation
+PEM-formatted key file to use for the TLS negotiation.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
-PEM-formatted certificate file to use for the TLS negotiation
+PEM-formatted certificate file to use for the TLS negotiation.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
-CA certificates to use
+CA certificates to use.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
-Extra retriever parameters
+Extra retriever parameters.
Defaults to @samp{()}.
If true, getmail will record a log of its actions using the system
logger.
-Defaults to @samp{#t}.
+Defaults to @samp{#f}.
@end deftypevr
the reason for not retrieving them, as well as starting and ending
information lines.
-Defaults to @samp{#t}.
+Defaults to @samp{#f}.
@end deftypevr
@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
+
+@node Linux Services
+@subsubheading Linux Services
+
+@cindex oom
+@cindex out of memory killer
+@cindex earlyoom
+@cindex early out of memory daemon
+@subsection Early OOM Service
+
+@uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
+Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user
+space and provides a more responsive and configurable alternative to the
+in-kernel OOM killer. It is useful to prevent the system from becoming
+unresponsive when it runs out of memory.
+
+@deffn {Scheme Variable} earlyoom-service-type
+The service type for running @command{earlyoom}, the Early OOM daemon.
+Its value must be a @code{earlyoom-configuration} object, described
+below. The service can be instantiated in its default configuration
+with:
+
+@lisp
+(service earlyoom-service-type)
+@end lisp
+@end deffn
+
+@deftp {Data Type} earlyoom-configuration
+This is the configuration record for the @code{earlyoom-service-type}.
+
+@table @asis
+@item @code{earlyoom} (default: @var{earlyoom})
+The Earlyoom package to use.
+
+@item @code{minimum-available-memory} (default: @code{10})
+The threshold for the minimum @emph{available} memory, in percentages.
+
+@item @code{minimum-free-swap} (default: @code{10})
+The threshold for the minimum free swap memory, in percentages.
+
+@item @code{prefer-regexp} (default: @code{#f})
+A regular expression (as a string) to match the names of the processes
+that should be preferably killed.
+
+@item @code{avoid-regexp} (default: @code{#f})
+A regular expression (as a string) to match the names of the processes
+that should @emph{not} be killed.
+
+@item @code{memory-report-interval} (default: @code{0})
+The interval in seconds at which a memory report is printed. It is
+disabled by default.
+
+@item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
+A boolean indicating whether the positive adjustments set in
+@file{/proc/*/oom_score_adj}.
+
+@item @code{show-debug-messages?} (default: @code{#f})
+A boolean indicating whether debug messages should be printed. The logs
+are saved at @file{/var/log/earlyoom.log}.
+
+@item @code{send-notification-command} (default: @code{#f})
+This can be used to provide a custom command used for sending
+notifications.
@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}:
@end table
@end deftp
+@cindex HDPI
+@cindex HiDPI
+@cindex resolution
@c FIXME: Write documentation once it's stable.
-For now only GRUB has theme support. GRUB themes are created using
-the @code{grub-theme} form, which is not documented yet.
+For now only GRUB has theme support. GRUB themes are created using
+the @code{grub-theme} form, which is not fully documented yet.
+
+@deftp {Data Type} grub-theme
+Data type representing the configuration of the GRUB theme.
+
+@table @asis
+@item @code{gfxmode} (default: @code{'("auto")})
+The GRUB @code{gfxmode} to set (a list of screen resolution strings, see
+@pxref{gfxmode,,, grub, GNU GRUB manual}).
+@end table
+@end deftp
@defvr {Scheme Variable} %default-theme
This is the default GRUB theme used by the operating system if no
logos.
@end defvr
+For example, to override the default resolution, you may use something
+like
+
+@lisp
+(bootloader
+ (grub-configuration
+ ;; @dots{}
+ (theme (grub-theme
+ (inherit %default-theme)
+ (gfxmode '("1024x786x32" "auto"))))))
+@end lisp
@node Invoking guix system
@section Invoking @code{guix system}
+ virtual console on GNU/Linux). The value of this service is a list of
+ tty/font pairs. The font can be the name of a font provided by the `kbd'
+ package or any valid argument to `setfont', as in this example:
-+
++
+ '(("tty1" . "LatGrkCyr-8x16")
+ ("tty2" . (file-append
+ font-tamzen
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