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, 2020 Leo Famulari@*
+Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 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, 2020 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
-Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
-Copyright @copyright{} 2017 Christopher Allan Webber@*
+Copyright @copyright{} 2017, 2021 Christopher Lemmer Webber@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
-Copyright @copyright{} 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
Copyright @copyright{} 2020 Pierre Langlois@*
Copyright @copyright{} 2020 pinoaffe@*
Copyright @copyright{} 2020 André Batista@*
-Copyright @copyright{} 2020 Alexandru-Sergiu Marton@*
+Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@*
Copyright @copyright{} 2020 raingloom@*
Copyright @copyright{} 2020 Daniel Brooks@*
Copyright @copyright{} 2020 John Soo@*
Copyright @copyright{} 2020 Jonathan Brielmaier@*
+Copyright @copyright{} 2020 Edgar Vincent@*
+Copyright @copyright{} 2021 Maxime Devos@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Using a Custom Guix Channel:: Using a customized Guix.
* Replicating Guix:: Running the @emph{exact same} Guix.
* Channel Authentication:: How Guix verifies what it fetches.
+* Channels with Substitutes:: Using channels with available substitutes.
* Creating a Channel:: How to write your custom channel.
* Package Modules in a Sub-directory:: Specifying the channel's package modules location.
* Declaring Channel Dependencies:: How to depend on other channels.
* Specifying Channel Authorizations:: Defining channel authors authorizations.
* Primary URL:: Distinguishing mirror to original.
* Writing Channel News:: Communicating information to channel's users.
-* Channels with Substitutes:: Using channels with available substitutes.
Development
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
-* Continuous Integration:: The Cuirass service.
+* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
* Virtualization Services:: Virtualization services.
architecture still works. Should someone decide they wish to revive this
architecture then the code is still available.
+@item powerpc64le-linux
+little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
+includes POWER9 systems such as the
+@uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
+RYF Talos II mainboard}. This platform is available as a "technology
+preview": although it is supported, substitutes are not yet available
+from the build farm (@pxref{Substitutes}), and some packages may fail to
+build (@pxref{Tracking Bugs and Patches}). That said, the Guix
+community is actively working on improving this support, and now is a
+great time to try it and get involved!
+
@end table
With Guix@tie{}System, you @emph{declare} all aspects of the operating system
graphical environment or system services of your choice.
Guix System is available on all the above platforms except
-@code{mips64el-linux}.
+@code{mips64el-linux} and @code{powerpc64le-linux}.
@noindent
For information on porting to other architectures or kernels,
then run this command to import it:
@example
-$ wget @value{OPENPGP-SIGNING-KEY-URL} \
+$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-qO - | gpg --import -
@end example
@item
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
-@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib};
+@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
+version 0.1.0 or later;
@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
@item
-@c FIXME: Specify a version number once a release has been made.
+@c FIXME: We need the #:fetch-options parameter of 'submodule-update',
+@c which appeared in 0.5.0. Change below after string freeze.
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.3.0
or later;
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
the @code{crate} importer (@pxref{Invoking guix import}).
+@item
+@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
+the @code{go} importer (@pxref{Invoking guix import}) and for some of
+the ``updaters'' (@pxref{Invoking guix refresh}).
+
@item
When @url{http://www.bzip.org, libbz2} is available,
@command{guix-daemon} can use it to compress build logs.
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
-# for i in `seq -w 1 10`;
+# for i in $(seq -w 1 10);
do
useradd -g guixbuild -G guixbuild \
- -d /var/empty -s `which nologin` \
+ -d /var/empty -s $(which nologin) \
-c "Guix build user $i" --system \
guixbuilder$i;
done
@code{guix_daemon_socket_t} isn’t actually used. None of the socket
operations involve contexts that have anything to do with
@code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label,
-but it would be preferrable to define socket rules for only this label.
+but it would be preferable to define socket rules for only this label.
@item
@code{guix gc} cannot access arbitrary links to profiles. By design,
The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
-(@pxref{Invoking guix build, @option{--keep-failed}}).
+(@pxref{Common Build Options, @option{--keep-failed}}).
The daemon listens for connections and spawns one sub-process for each session
started by a client (one of the @command{guix} sub-commands). The
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
+the @command{guix} command and package definitions only for the user it is run
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
guix install emacs
@end example
-You've installed your first package, congrats! In the process, you've
+@cindex profile
+You've installed your first package, congrats! The package is now
+visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
+profile is a directory containing installed packages.
+In the process, you've
probably noticed that Guix downloaded pre-built binaries; or, if you
explicitly chose to @emph{not} use pre-built binaries, then probably
Guix is still building software (@pxref{Substitutes}, for more info).
@cindex removing packages
@cindex package installation
@cindex package removal
+@cindex profile
The @command{guix package} command is the tool that allows users to
install, upgrade, and remove packages, as well as rolling back to
-previous configurations. It operates only on the user's own profile,
+previous configurations. These operations work on a user
+@dfn{profile}---a directory of installed packages. Each user has a
+default profile in @file{$HOME/.guix-profile}.
+The command operates only on the user's own profile,
and works with normal user privileges (@pxref{Features}). Its syntax
is:
@file{bar} would lead to that recommendation.
+@cindex profile, choosing
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
For example, this command:
@example
-guix gc --derivers `guix package -I ^emacs$ | cut -f4`
+guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
@end example
@noindent
Inferior packages can be used transparently like any other package or
file-like object in G-expressions (@pxref{G-Expressions}). They are also
transparently handled by the @code{packages->manifest} procedure, which is
-commonly use in manifests (@pxref{Invoking guix package, the
+commonly used in manifests (@pxref{Invoking guix package, the
@option{--manifest} option of @command{guix package}}). Thus you can insert
an inferior package pretty much anywhere you would insert a regular package:
in manifests, in the @code{packages} field of your @code{operating-system}
* Using a Custom Guix Channel:: Using a customized Guix.
* Replicating Guix:: Running the @emph{exact same} Guix.
* Channel Authentication:: How Guix verifies what it fetches.
+* Channels with Substitutes:: Using channels with available substitutes.
* Creating a Channel:: How to write your custom channel.
* Package Modules in a Sub-directory:: Specifying the channel's package modules location.
* Declaring Channel Dependencies:: How to depend on other channels.
* Specifying Channel Authorizations:: Defining channel authors authorizations.
* Primary URL:: Distinguishing mirror to original.
* Writing Channel News:: Communicating information to channel's users.
-* Channels with Substitutes:: Using channels with available substitutes.
@end menu
@node Specifying Additional Channels
If you're curious about the authentication mechanics, read on!
+@node Channels with Substitutes
+@section Channels with Substitutes
+
+When running @command{guix pull}, Guix will first compile the
+definitions of every available package. This is an expensive operation
+for which substitutes (@pxref{Substitutes}) may be available. The
+following snippet in @file{channels.scm} will ensure that @command{guix
+pull} uses the latest commit with available substitutes for the package
+definitions: this is done by querying the continuous integration
+server at @url{https://ci.guix.gnu.org}.
+
+@lisp
+(use-modules (guix ci))
+
+(list (channel-with-substitutes-available
+ %default-guix-channel
+ "https://ci.guix.gnu.org"))
+@end lisp
+
+Note that this does not mean that all the packages that you will
+install after running @command{guix pull} will have available
+substitutes. It only ensures that @command{guix pull} will not try to
+compile package definitions. This is particularly useful when using
+machines with limited resources.
+
@node Creating a Channel
@section Creating a Channel
(version 0)
(dependencies
(channel
- (name 'some-collection)
+ (name some-collection)
(url "https://example.org/first-collection.git")
;; The 'introduction' bit below is optional: you would
(commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
(signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
(channel
- (name 'some-other-collection)
+ (name some-other-collection)
(url "https://example.org/second-collection.git")
(branch "testing"))))
@end lisp
To sum up, yes, you could use your channel as a blog. But beware, this
is @emph{not quite} what your users might expect.
-@node Channels with Substitutes
-@section Channels with Substitutes
-
-When running @command{guix pull}, Guix will first compile the
-definitions of every available package. This is an expensive operation
-for which substitutes (@pxref{Substitutes}) may be available. The
-following snippet in @file{channels.scm} will ensure that @command{guix
-pull} uses the latest commit with available substitutes for the package
-definitions: this is done by querying the continuous integration
-server at @url{https://ci.guix.gnu.org}.
-
-@lisp
-(use-modules (guix ci))
-
-(list (channel-with-substitutes-available
- %default-guix-channel
- "https://ci.guix.gnu.org"))
-@end lisp
-
-Note that this does not mean that all the packages that you will
-install after running @command{guix pull} will have available
-substitutes. It only ensures that @command{guix pull} will not try to
-compile package definitions. This is particularly useful when using
-machines with limited resources.
-
@c *********************************************************************
@node Development
@chapter Development
log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference
Manual}, for details on Bash start-up files.}.
+Exiting from a Guix environment is the same as exiting from the shell,
+and will place the user back in the old environment before @command{guix
+environment} was invoked. The next garbage collection (@pxref{Invoking
+guix gc}) will clean up packages that were installed from within the
+environment and are no longer used outside of it.
+
@vindex GUIX_ENVIRONMENT
@command{guix environment} defines the @env{GUIX_ENVIRONMENT}
variable in the shell it spawns; its value is the file name of the
In a nutshell, packages using it are configured, built, and installed with
the usual @code{./configure && make && make check && make install}
command sequence. In practice, a few additional steps are often needed.
-All these steps are split up in separate @dfn{phases},
-notably@footnote{Please see the @code{(guix build gnu-build-system)}
-modules for more details about the build phases.}:
-
-@table @code
-@item unpack
-Unpack the source tarball, and change the current directory to the
-extracted source tree. If the source is actually a directory, copy it
-to the build tree, and enter that directory.
-
-@item patch-source-shebangs
-Patch shebangs encountered in source files so they refer to the right
-store file names. For instance, this changes @code{#!/bin/sh} to
-@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
-
-@item configure
-Run the @file{configure} script with a number of default options, such
-as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
-by the @code{#:configure-flags} argument.
-
-@item build
-Run @code{make} with the list of flags specified with
-@code{#:make-flags}. If the @code{#:parallel-build?} argument is true
-(the default), build with @code{make -j}.
-
-@item check
-Run @code{make check}, or some other target specified with
-@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
-@code{#:parallel-tests?} argument is true (the default), run @code{make
-check -j}.
-
-@item install
-Run @code{make install} with the flags listed in @code{#:make-flags}.
-
-@item patch-shebangs
-Patch shebangs on the installed executable files.
-
-@item strip
-Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
-is false), copying them to the @code{debug} output when available
-(@pxref{Installing Debugging Files}).
-@end table
-
-@vindex %standard-phases
-The build-side module @code{(guix build gnu-build-system)} defines
-@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.
-
+All these steps are split up in separate @dfn{phases}.
@xref{Build Phases}, for more info on build phases and ways to customize
them.
build-system gnu)} module for a complete list). We call these the
@dfn{implicit inputs} of a package, because package definitions do not
have to mention them.
+
+This build system supports a number of keyword arguments, which can be
+passed @i{via} the @code{arguments} field of a package. Here are some
+of the main parameters:
+
+@table @code
+@item #:phases
+This argument specifies build-side code that evaluates to an alist of
+build phases. @xref{Build Phases}, for more information.
+
+@item #:configure-flags
+This is a list of flags (strings) passed to the @command{configure}
+script. @xref{Defining Packages}, for an example.
+
+@item #:make-flags
+This list of strings contains flags passed as arguments to
+@command{make} invocations in the @code{build}, @code{check}, and
+@code{install} phases.
+
+@item #:out-of-source?
+This Boolean, @code{#f} by default, indicates whether to run builds in a
+build directory separate from the source tree.
+
+When it is true, the @code{configure} phase creates a separate build
+directory, changes to that directory, and runs the @code{configure}
+script from there. This is useful for packages that require it, such as
+@code{glibc}.
+
+@item #:tests?
+This Boolean, @code{#t} by default, indicates whether the @code{check}
+phase should run the package's test suite.
+
+@item #:test-target
+This string, @code{"check"} by default, gives the name of the makefile
+target used by the @code{check} phase.
+
+@item #:parallel-build?
+@itemx #:parallel-tests?
+These Boolean values specify whether to build, respectively run the test
+suite, in parallel, with the @code{-j} flag of @command{make}. When
+they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
+the number specified as the @option{--cores} option of
+@command{guix-daemon} or that of the @command{guix} client command
+(@pxref{Common Build Options, @option{--cores}}).
+
+@cindex RUNPATH, validation
+@item #:validate-runpath?
+This Boolean, @code{#t} by default, determines whether to ``validate''
+the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
+as executables) previously installed by the @code{install} phase.
+
+This validation step consists in making sure that all the shared
+libraries needed by an ELF binaries, which are listed as
+@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
+@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
+running or using those binaries will not result in a ``file not found''
+error at run time. @xref{Options, @option{-rpath},, ld, The GNU
+Linker}, for more information on @code{RUNPATH}.
+
+@item #:substitutable?
+This Boolean, @code{#t} by default, tells whether the package outputs
+should be substitutable---i.e., whether users should be able to obtain
+substitutes for them instead of building locally (@pxref{Substitutes}).
+
+@item #:allowed-references
+@itemx #:disallowed-references
+When true, these arguments must be a list of dependencies that must not
+appear among the references of the build results. If, upon build
+completion, some of these references are retained, the build process
+fails.
+
+This is useful to ensure that a package does not erroneously keep a
+reference to some of it build-time inputs, in cases where doing so
+would, for example, unnecessarily increase its size (@pxref{Invoking
+guix size}).
+@end table
+
+Most other build systems support these keyword arguments.
@end defvr
Other @code{<build-system>} objects are defined to support other
It adds @code{rustc} and @code{cargo} to the set of inputs.
A different Rust package can be specified with the @code{#:rust} parameter.
-Regular cargo dependencies should be added to the package definition via the
-@code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
+Regular cargo dependencies should be added to the package definition similarly
+to other packages; those needed only at build time to native-inputs, others to
+inputs. If you need to add source-only crates then you should add them to via
+the @code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
spec can be a package or a source definition. Note that the spec must
evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
file at its root, or it will be ignored. Similarly, cargo dev-dependencies
specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
parameters available to cargo. It will also remove an included
@code{Cargo.lock} file to be recreated by @code{cargo} during the
-@code{build} phase. The @code{install} phase installs the binaries
-defined by the crate.
+@code{build} phase. The @code{package} phase will run @code{cargo package}
+to create a source crate for future use. The @code{install} phase installs
+the binaries defined by the crate. Unless @code{install-source? #f} is
+defined it will also install a source crate repository of itself and unpacked
+sources, to ease in future hacking on rust packages.
@end defvr
@defvr {Scheme Variable} chicken-build-system
Tests are run by calling @code{/test/runtests.jl}.
The Julia package name is read from the file @file{Project.toml}. This
-value can be overridden by passing the argument @code{#:julia-file-name}
+value can be overridden by passing the argument @code{#:julia-package-name}
(which must be correctly capitalized).
-For packages requiring shared library dependencies, you may need to write the
-@file{/deps/deps.jl} file manually. It's usually a line of @code{const
-variable = /gnu/store/library.so} for each dependency, plus a void function
-@code{check_deps() = nothing}.
+Julia packages usually manage their binary dependencies via
+@code{JLLWrappers.jl}, a Julia package that creates a module (named
+after the wrapped library followed by @code{_jll.jl}.
+
+To add the binary path @code{_jll.jl} packages, you need to patch the
+files under @file{src/wrappers/}, replacing the call to the macro
+@code{JLLWrappers.@@generate_wrapper_header}, adding as a second
+argument containing the store path the binary.
+
+As an example, in the MbedTLS Julia package, we add a build phase
+(@pxref{Build Phases}) to insert the absolute file name of the wrapped
+MbedTLS package:
+
+@lisp
+(add-after 'unpack 'override-binary-path
+ (lambda* (#:key inputs #:allow-other-keys)
+ (for-each (lambda (wrapper)
+ (substitute* wrapper
+ (("generate_wrapper_header.*")
+ (string-append
+ "generate_wrapper_header(\"MbedTLS\", \""
+ (assoc-ref inputs "mbedtls-apache") "\")\n"))))
+ ;; There's a Julia file for each platform, override them all.
+ (find-files "src/wrappers/" "\\.jl$"))))
+@end lisp
Some older packages that aren't using @file{Package.toml} yet, will require
this file to be created, too. The function @code{julia-create-package-toml}
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
+@defvr {Scheme Variable} renpy-build-system
+This variable is exported by @code{(guix build-system renpy)}. It implements
+the more or less standard build procedure used by Ren'py games, which consists
+of loading @code{#:game} once, thereby creating bytecode for it.
+
+It further creates a wrapper script in @code{bin/} and a desktop entry in
+@code{share/applications}, both of which can be used to launch the game.
+
+Which Ren'py package is used can be specified with @code{#:renpy}.
+Games can also be installed in outputs other than ``out'' by using
+@code{#:output}.
+@end defvr
+
@defvr {Scheme Variable} qt-build-system
This variable is exported by @code{(guix build-system qt)}. It
is intended for use with applications using Qt or KDE.
(@pxref{Build Systems}).
As discussed in the previous section, those build systems provide a
-standard list of phases. For @code{gnu-build-system}, the standard
-phases include an @code{unpack} phase to unpack the source code tarball,
-a @command{configure} phase to run @code{./configure}, a @code{build}
-phase to run @command{make}, and (among others) an @code{install} phase
-to run @command{make install}; @pxref{Build Systems}, for a more
-detailed view of these phases. Likewise, @code{cmake-build-system}
-inherits these phases, but its @code{configure} phase runs
-@command{cmake} instead of @command{./configure}. Other build systems,
-such as @code{python-build-system}, have a wholly different list of
-standard phases. All this code runs on the @dfn{build side}: it is
+standard list of phases. For @code{gnu-build-system}, the main build
+phases are the following:
+
+@table @code
+@item unpack
+Unpack the source tarball, and change the current directory to the
+extracted source tree. If the source is actually a directory, copy it
+to the build tree, and enter that directory.
+
+@item patch-source-shebangs
+Patch shebangs encountered in source files so they refer to the right
+store file names. For instance, this changes @code{#!/bin/sh} to
+@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
+
+@item configure
+Run the @file{configure} script with a number of default options, such
+as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
+by the @code{#:configure-flags} argument.
+
+@item build
+Run @code{make} with the list of flags specified with
+@code{#:make-flags}. If the @code{#:parallel-build?} argument is true
+(the default), build with @code{make -j}.
+
+@item check
+Run @code{make check}, or some other target specified with
+@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
+@code{#:parallel-tests?} argument is true (the default), run @code{make
+check -j}.
+
+@item install
+Run @code{make install} with the flags listed in @code{#:make-flags}.
+
+@item patch-shebangs
+Patch shebangs on the installed executable files.
+
+@item strip
+Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
+is false), copying them to the @code{debug} output when available
+(@pxref{Installing Debugging Files}).
+@end table
+
+Other build systems have similar phases, with some variations. For
+example, @code{cmake-build-system} has same-named phases but its
+@code{configure} phases runs @code{cmake} instead of @code{./configure}.
+Others, such as @code{python-build-system}, have a wholly different list
+of standard phases. All this code runs on the @dfn{build side}: it is
evaluated when you actually build the package, in a dedicated build
process spawned by the build daemon (@pxref{Invoking guix-daemon}).
convention, those procedures receive information about the build in the
form of @dfn{keyword parameters}, which they can use or ignore.
+@vindex %standard-phases
For example, here is how @code{(guix build gnu-build-system)} defines
@code{%standard-phases}, the variable holding its alist of build
phases@footnote{We present a simplified view of those build phases, but
@example
guix build --quiet --keep-going \
- `guix package -A | cut -f1,2 --output-delimiter=@@`
+ $(guix package -A | cut -f1,2 --output-delimiter=@@)
@end example
@var{package-or-derivation} may be either the name of a package found in
@cindex build logs, verbosity
@item -v @var{level}
@itemx --verbosity=@var{level}
-Use the given verbosity @var{level}, an integer. Choosing 0 means that no
-output is produced, 1 is for quiet output, and 2 shows all the build log
-output on standard error.
+Use the given verbosity @var{level}, an integer. Choosing 0 means that
+no output is produced, 1 is for quiet output; 2 is similar to 1 but it
+additionally displays download URLs; 3 shows all the build log output on
+standard error.
@item --cores=@var{n}
@itemx -c @var{n}
instance, the following invocations are equivalent:
@example
-guix build --log-file `guix build -d guile`
-guix build --log-file `guix build guile`
+guix build --log-file $(guix build -d guile)
+guix build --log-file $(guix build guile)
guix build --log-file guile
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example
To that end, the first thing to do is to use the @option{--keep-failed}
or @option{-K} option of @command{guix build}, which will keep the
failed build tree in @file{/tmp} or whatever directory you specified as
-@env{TMPDIR} (@pxref{Invoking guix build, @option{--keep-failed}}).
+@env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}).
From there on, you can @command{cd} to the failed build tree and source
the @file{environment-variables} file, which contains all the
guix import json hello.json
@end example
-@item nix
-Import metadata from a local copy of the source of the
-@uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
-relies on the @command{nix-instantiate} command of
-@uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
-typically written in a mixture of Nix-language and Bash code. This
-command only imports the high-level package structure that is written in
-the Nix language. It normally includes all the basic fields of a
-package definition.
-
-When importing a GNU package, the synopsis and descriptions are replaced
-by their canonical upstream variant.
-
-Usually, you will first need to do:
-
-@example
-export NIX_REMOTE=daemon
-@end example
-
-@noindent
-so that @command{nix-instantiate} does not try to open the Nix database.
-
-As an example, the command below imports the package definition of
-LibreOffice (more precisely, it imports the definition of the package
-bound to the @code{libreoffice} top-level attribute):
-
-@example
-guix import nix ~/path/to/nixpkgs libreoffice
-@end example
-
@item hackage
@cindex hackage
Import metadata from the Haskell community's central package archive
of coq packages.
@end itemize
@end table
+
+@item go
+@cindex go
+Import metadata for a Go module using
+@uref{https://proxy.golang.org, proxy.golang.org}.
+
+@example
+guix import go gopkg.in/yaml.v2
+@end example
+
+It is possible to use a package specification with a @code{@@VERSION}
+suffix to import a specific version.
+
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@item --pin-versions
+When using this option, the importer preserves the exact versions of the
+Go modules dependencies instead of using their latest available
+versions. This can be useful when attempting to import packages that
+recursively depend on former versions of themselves to build. When
+using this mode, the symbol of the package is made by appending the
+version to its name, so that multiple versions of the same package can
+coexist.
+@end table
@end table
The structure of the @command{guix import} code is modular. It would be
@section Invoking @command{guix refresh}
@cindex @command {guix refresh}
-The primary audience of the @command{guix refresh} command is developers
-of the GNU software distribution. By default, it reports any packages
-provided by the distribution that are outdated compared to the latest
-upstream version, like this:
+The primary audience of the @command{guix refresh} command is packagers.
+As a user, you may be interested in the @option{--with-latest} option,
+which can bring you package update superpowers built upon @command{guix
+refresh} (@pxref{Package Transformation Options,
+@option{--with-latest}}). By default, @command{guix refresh} reports
+any packages provided by the distribution that are outdated compared to
+the latest upstream version, like this:
@example
$ guix refresh
@example
$ guix refresh --recursive coreutils
-gnu/packages/acl.scm:35:2: warning: no updater for acl
-gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
+gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
+gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
gnu/packages/xml.scm:68:2: warning: no updater for expat
-gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp
+gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
@dots{}
@end example
the updater for GNU packages;
@item savannah
the updater for packages hosted at @uref{https://savannah.gnu.org, Savannah};
+@item sourceforge
+the updater for packages hosted at @uref{https://sourceforge.net, SourceForge};
@item gnome
the updater for GNOME packages;
@item kde
the updater for @uref{https://crates.io, Crates} packages.
@item launchpad
the updater for @uref{https://launchpad.net, Launchpad} packages.
+@item generic-html
+a generic updater that crawls the HTML page where the source tarball of
+the package is hosted, when applicable.
@end table
For instance, the following command only checks for updates of Emacs
gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
@end example
+@item --list-updaters
+@itemx -L
+List available updaters and exit (see @option{--type} above).
+
+For each updater, display the fraction of packages it covers; at the
+end, display the fraction of packages covered by all these updaters.
@end table
In addition, @command{guix refresh} can be passed one or more package
@noindent
The command above specifically updates the @code{emacs} and
@code{idutils} packages. The @option{--select} option would have no
-effect in this case.
+effect in this case. You might also want to update definitions that
+correspond to the packages installed in your profile:
+
+@example
+$ ./pre-inst-env guix refresh -u \
+ $(guix package --list-installed | cut -f1)
+@end example
When considering whether to upgrade a package, it is sometimes
convenient to know which packages would be affected by the upgrade and
@table @code
-@item --list-updaters
-@itemx -L
-List available updaters and exit (see @option{--type} above).
-
-For each updater, display the fraction of packages it covers; at the
-end, display the fraction of packages covered by all these updaters.
-
@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
--recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
-@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
+@xref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
Privacy Guard}, for more information on GPG's @option{--keyring} option.
@item --key-download=@var{policy}
name instead of a package name, as in:
@example
-guix graph -t derivation `guix system build -d my-config.scm`
+guix graph -t derivation $(guix system build -d my-config.scm)
@end example
@item module
(which can be big!):
@example
-guix graph -t references `readlink -f ~/.guix-profile`
+guix graph -t references $(readlink -f ~/.guix-profile)
@end example
@item referrers
@example
guix copy --to=@var{user}@@@var{host} \
- coreutils `readlink -f ~/.guix-profile`
+ coreutils $(readlink -f ~/.guix-profile)
@end example
If some of the items to be copied are already present on @var{host},
%desktop-services)
@end lisp
+Alternatively, the @code{modify-services} macro can be used:
+
+@lisp
+(modify-services %desktop-services
+ (delete avahi-service-type))
+@end lisp
+
+
@unnumberedsubsec Instantiating the System
Assuming the @code{operating-system} declaration
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
* Telephony Services:: Telephony services.
+* File-Sharing Services:: File-sharing services.
* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
* LDAP Services:: LDAP services.
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
-* Continuous Integration:: The Cuirass service.
+* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
* Virtualization Services:: Virtualization services.
@item @code{hardware-acceleration?} (default: #f)
Whether to use hardware acceleration.
+@item @code{font-engine} (default: @code{"pango"})
+Font engine used in Kmscon.
+
+@item @code{font-size} (default: @code{12})
+Font size used in Kmscon.
+
@item @code{kmscon} (default: @var{kmscon})
The Kmscon package to use.
@code{guix-configuration} above) to discover this @command{guix publish}
instance and to automatically download substitutes from it.
-@item @code{compression} (default: @code{'(("gzip" 3))})
+@item @code{compression} (default: @code{'(("gzip" 3) ("zstd" 3))})
This is a list of compression method/level tuple used when compressing
substitutes. For example, to compress all substitutes with @emph{both} lzip
at level 7 and gzip at level 9, write:
@cindex priority
@cindex realtime
@cindex jackd
+@cindex nofile
+@cindex open file descriptors
@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
Return a service that installs a configuration file for the
@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
@code{pam_limits} module}. The procedure optionally takes a list of
@code{pam-limits-entry} values, which can be used to specify
-@code{ulimit} limits and nice priority limits to user sessions.
+@code{ulimit} limits and @code{nice} priority limits to user sessions.
The following limits definition sets two hard and soft limits for all
login sessions of users in the @code{realtime} group:
non-privileged processes; the second entry lifts any restriction of the
maximum address space that can be locked in memory. These settings are
commonly used for real-time audio systems.
+
+Another useful example is raising the maximum number of open file
+descriptors that can be used:
+
+@lisp
+(pam-limits-service
+ (list
+ (pam-limits-entry "*" 'both 'nofile 100000)))
+@end lisp
+
+In the above example, the asterisk means the limit should apply to any
+user. It is important to ensure the chosen value doesn't exceed the
+maximum system value visible in the @file{/proc/sys/fs/file-max} file,
+else the users would be prevented from login in. For more information
+about the Pluggable Authentication Module (PAM) limits, refer to the
+@samp{pam_limits} man page from the @code{linux-pam} package.
@end deffn
@node Scheduled Job Execution
arptables and ebtables framework. It provides a new packet filtering
framework, a new user-space utility @command{nft}, and a compatibility layer
for iptables. This service comes with a default ruleset
-@code{%default-nftables-ruleset} that rejecting all incomming connections
+@code{%default-nftables-ruleset} that rejecting all incoming connections
except those to the ssh port 22. To use it, simply write:
@lisp
@code{socks-socket-type} at its default value of @code{'tcp} and use
@code{config-file} to override the default by providing your own
@code{SocksPort} option.
+
+@item @code{control-socket?} (default: @code{#f})
+Whether or not to provide a ``control socket'' by which Tor can be
+controlled to, for instance, dynamically instantiate tor onion services.
+If @code{#t}, Tor will listen for control commands on the UNIX domain socket
+@file{/var/run/tor/control-sock}, which will be made writable by members of the
+@code{tor} group.
+
@end table
@end deftp
List of command-line arguments passing to @code{syncthing} binary.
@item @code{logflags} (default: @var{0})
-Sum of loging flags, see
+Sum of logging flags, see
@uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}.
@item @code{user} (default: @var{#f})
@end table
@end deftp
+@cindex IPFS
+@defvr {Scheme Variable} ipfs-service-type
+The service type for connecting to the @uref{https://ipfs.io,IPFS network},
+a global, versioned, peer-to-peer file system. Pass it a
+@code{ipfs-configuration} to change the ports used for the gateway and API.
+
+Here's an example configuration, using some non-standard ports:
+
+@lisp
+(service ipfs-service-type
+ (ipfs-configuration
+ (gateway "/ip4/127.0.0.1/tcp/8880")
+ (api "/ip4/127.0.0.1/tcp/8881")))
+@end lisp
+@end defvr
+
+@deftp {Data Type} ipfs-configuration
+Data type representing the configuration of IPFS.
+
+@table @asis
+@item @code{package} (default: @code{go-ipfs})
+Package object of IPFS.
+
+@item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"})
+Address of the gateway, in ‘multiaddress’ format.
+
+@item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"})
+Address of the API endpoint, in ‘multiaddress’ format.
+@end table
+@end deftp
+
@cindex keepalived
@deffn {Scheme Variable} keepalived-service-type
This is the type for the @uref{https://www.keepalived.org/, Keepalived}
(service slim-service-type (slim-configuration
(display ":1")
(vt "vt8")))
- (remove (lambda (service)
- (eq? (service-kind service) gdm-service-type))
- %desktop-services))))
+ (modify-services %desktop-services
+ (delete gdm-service-type)))))
@end lisp
@end defvr
site} for more information.
@end deffn
+@cindex scanner access
+@defvr {Scheme Variable} sane-service-type
+This service provides access to scanners @i{via}
+@uref{http://www.sane-project.org, SANE} by installing the necessary
+udev rules. It is included in @code{%desktop-services} (@pxref{Desktop
+Services}) and relies by default on @code{sane-backends-minimal} package
+(see below) for hardware support.
+@end defvr
+
+@defvr {Scheme Variable} sane-backends-minimal
+The default package which the @code{sane-service-type} installs. It
+supports many recent scanners.
+@end defvr
+
+@defvr {Scheme Variable} sane-backends
+This package includes support for all scanners that
+@code{sane-backends-minimal} supports, plus older Hewlett-Packard
+scanners supported by @code{hplip} package. In order to use this on
+a system which relies on @code{%desktop-services}, you may use
+@code{modify-services} (@pxref{Service Reference,
+@code{modify-services}}) as illustrated below:
+
+@lisp
+(use-modules (gnu))
+(use-service-modules
+ @dots{}
+ desktop)
+(use-package-modules
+ @dots{}
+ scanner)
+
+(define %my-desktop-services
+ ;; List of desktop services that supports a broader range of scanners.
+ (modify-services %desktop-services
+ (sane-service-type _ => sane-backends)))
+
+(operating-system
+ @dots{}
+ (services %my-desktop-services)
+@end lisp
+@end defvr
+
@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
Return a configuration allowing an application to access GeoClue
location data. @var{name} is the Desktop ID of the application, without
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{ident-file} (default: @code{%default-postgres-ident})
Filename or G-expression for the user name mapping configuration.
-@item @code{socket-directory} (default: @code{"/var/lib/postgresql"})
+@item @code{socket-directory} (default: @code{#false})
Specifies the directory of the Unix-domain socket(s) on which PostgreSQL
-is to listen for connections from client applications. If set to
-@code{#false} PostgreSQL does not listen on any Unix-domain sockets, in
+is to listen for connections from client applications. If set to
+@code{""} PostgreSQL does not listen on any Unix-domain sockets, in
which case only TCP/IP sockets can be used to connect to the server.
+By default, the @code{#false} value means the PostgreSQL default value
+will be used, which is currently @samp{/tmp}.
+
@item @code{extra-config} (default: @code{'()})
List of additional keys and values to include in the PostgreSQL config
file. Each entry in the list should be a list where the first element
@end table
@end deftp
-@subsubheading MongoDB
-
-@defvr {Scheme Variable} mongodb-service-type
-This is the service type for @uref{https://www.mongodb.com/, MongoDB}.
-The value for the service type is a @code{mongodb-configuration} object.
-@end defvr
-
-@lisp
-(service mongodb-service-type)
-@end lisp
-
-@deftp {Data Type} mongodb-configuration
-Data type representing the configuration of mongodb.
-
-@table @asis
-@item @code{mongodb} (default: @code{mongodb})
-The MongoDB package to use.
-
-@item @code{config-file} (default: @code{%default-mongodb-configuration-file})
-The configuration file for MongoDB.
-
-@item @code{data-directory} (default: @code{"/var/lib/mongodb"})
-This value is used to create the directory, so that it exists and is
-owned by the mongodb user. It should match the data-directory which
-MongoDB is configured to use through the configuration file.
-@end table
-@end deftp
-
@subsubheading Redis
@defvr {Scheme Variable} redis-service-type
+@node File-Sharing Services
+@subsection File-Sharing Services
+
+The @code{(gnu services file-sharing)} module provides services that
+assist with transferring files over peer-to-peer file-sharing networks.
+
+@subsubheading Transmission Daemon Service
+
+@uref{https://transmissionbt.com/, Transmission} is a flexible
+BitTorrent client that offers a variety of graphical and command-line
+interfaces. A @code{transmission-daemon-service-type} service provides
+Transmission's headless variant, @command{transmission-daemon}, as a
+system service, allowing users to share files via BitTorrent even when
+they are not logged in.
+
+@deffn {Scheme Variable} transmission-daemon-service-type
+The service type for the Transmission Daemon BitTorrent client. Its
+value must be a @code{transmission-daemon-configuration} object as in
+this example:
+
+@lisp
+(service transmission-daemon-service-type
+ (transmission-daemon-configuration
+ ;; Restrict access to the RPC ("control") interface
+ (rpc-authentication-required? #t)
+ (rpc-username "transmission")
+ (rpc-password
+ (transmission-password-hash
+ "transmission" ; desired password
+ "uKd1uMs9")) ; arbitrary salt value
+
+ ;; Accept requests from this and other hosts on the
+ ;; local network
+ (rpc-whitelist-enabled? #t)
+ (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))
+
+ ;; Limit bandwidth use during work hours
+ (alt-speed-down (* 1024 2)) ; 2 MB/s
+ (alt-speed-up 512) ; 512 kB/s
+
+ (alt-speed-time-enabled? #t)
+ (alt-speed-time-day 'weekdays)
+ (alt-speed-time-begin
+ (+ (* 60 8) 30)) ; 8:30 am
+ (alt-speed-time-end
+ (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
+@end lisp
+@end deffn
+
+Once the service is started, users can interact with the daemon through
+its Web interface (at @code{http://localhost:9091/}) or by using the
+@command{transmission-remote} command-line tool, available in the
+@code{transmission} package. (Emacs users may want to also consider the
+@code{emacs-transmission} package.) Both communicate with the daemon
+through its remote procedure call (RPC) interface, which by default is
+available to all users on the system; you may wish to change this by
+assigning values to the @code{rpc-authentication-required?},
+@code{rpc-username} and @code{rpc-password} settings, as shown in the
+example above and documented further below.
+
+The value for @code{rpc-password} must be a password hash of the type
+generated and used by Transmission clients. This can be copied verbatim
+from an existing @file{settings.json} file, if another Transmission
+client is already being used. Otherwise, the
+@code{transmission-password-hash} and @code{transmission-random-salt}
+procedures provided by this module can be used to obtain a suitable hash
+value.
+
+@deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt}
+Returns a string containing the result of hashing @var{password}
+together with @var{salt}, in the format recognized by Transmission
+clients for their @code{rpc-password} configuration setting.
+
+@var{salt} must be an eight-character string. The
+@code{transmission-random-salt} procedure can be used to generate a
+suitable salt value at random.
+@end deffn
+
+@deffn {Scheme Procedure} transmission-random-salt
+Returns a string containing a random, eight-character salt value of the
+type generated and used by Transmission clients, suitable for passing to
+the @code{transmission-password-hash} procedure.
+@end deffn
+
+These procedures are accessible from within a Guile REPL started with
+the @command{guix repl} command (@pxref{Invoking guix repl}). This is
+useful for obtaining a random salt value to provide as the second
+parameter to `transmission-password-hash`, as in this example session:
+
+@example
+$ guix repl
+scheme@@(guix-user)> ,use (gnu services file-sharing)
+scheme@@(guix-user)> (transmission-random-salt)
+$1 = "uKd1uMs9"
+@end example
+
+Alternatively, a complete password hash can generated in a single step:
+
+@example
+scheme@@(guix-user)> (transmission-password-hash "transmission"
+(transmission-random-salt))
+$2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
+@end example
+
+The resulting string can be used as-is for the value of
+@code{rpc-password}, allowing the password to be kept hidden even in the
+operating-system configuration.
+
+Torrent files downloaded by the daemon are directly accessible only to
+users in the ``transmission'' user group, who receive read-only access
+to the directory specified by the @code{download-dir} configuration
+setting (and also the directory specified by @code{incomplete-dir}, if
+@code{incomplete-dir-enabled?} is @code{#t}). Downloaded files can be
+moved to another directory or deleted altogether using
+@command{transmission-remote} with its @code{--move} and
+@code{--remove-and-delete} options.
+
+If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in
+the ``transmission'' group are able also to place @file{.torrent} files
+in the directory specified by @code{watch-dir} to have the corresponding
+torrents added by the daemon. (The @code{trash-original-torrent-files?}
+setting controls whether the daemon deletes these files after processing
+them.)
+
+Some of the daemon's configuration settings can be changed temporarily
+by @command{transmission-remote} and similar tools. To undo these
+changes, use the service's @code{reload} action to have the daemon
+reload its settings from disk:
+
+@example
+# herd reload transmission-daemon
+@end example
+
+The full set of available configuration settings is defined by the
+@code{transmission-daemon-configuration} data type.
+
+@deftp {Data Type} transmission-daemon-configuration
+The data type representing configuration settings for Transmission
+Daemon. These correspond directly to the settings recognized by
+Transmission clients in their @file{settings.json} file.
+@end deftp
+
+@c The following documentation was initially generated by
+@c (generate-transmission-daemon-documentation) in (gnu services
+@c file-sharing). Manually maintained documentation is better, so we
+@c shouldn't hesitate to edit below as needed. However if the change
+@c you want to make to this documentation can be done in an automated
+@c way, it's probably easier to change (generate-documentation) than to
+@c make it below and have to deal with the churn as Transmission Daemon
+@c updates.
+
+@c %start of fragment
+
+Available @code{transmission-daemon-configuration} fields are:
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} package transmission
+The Transmission package to use.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period
+The period, in seconds, to wait when stopping the service for
+@command{transmission-daemon} to exit before killing its process. This
+allows the daemon time to complete its housekeeping and send a final
+update to trackers as it shuts down. On slow hosts, or hosts with a
+slow network connection, this value may need to be increased.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir
+The directory to which torrent files are downloaded.
+
+Defaults to @samp{"/var/lib/transmission-daemon/downloads"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled?
+If @code{#t}, files will be held in @code{incomplete-dir} while their
+torrent is being downloaded, then moved to @code{download-dir} once the
+torrent is complete. Otherwise, files for all torrents (including those
+still being downloaded) will be placed in @code{download-dir}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir
+The directory in which files from incompletely downloaded torrents will
+be held when @code{incomplete-dir-enabled?} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} umask umask
+The file mode creation mask used for downloaded files. (See the
+@command{umask} man page for more information.)
+
+Defaults to @samp{18}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files?
+When @code{#t}, ``.part'' is appended to the name of partially
+downloaded files.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation
+The mode by which space should be preallocated for downloaded files, one
+of @code{none}, @code{fast} (or @code{sparse}) and @code{full}.
+Specifying @code{full} will minimize disk fragmentation at a cost to
+file-creation speed.
+
+Defaults to @samp{fast}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled?
+If @code{#t}, the directory specified by @code{watch-dir} will be
+watched for new @file{.torrent} files and the torrents they describe
+added automatically (and the original files removed, if
+@code{trash-original-torrent-files?} is @code{#t}).
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir
+The directory to be watched for @file{.torrent} files indicating new
+torrents to be added, when @code{watch-dir-enabled} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files?
+When @code{#t}, @file{.torrent} files will be deleted from the watch
+directory once their torrent has been added (see
+@code{watch-directory-enabled?}).
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled?
+When @code{#t}, the daemon's download speed will be limited to the rate
+specified by @code{speed-limit-down}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down
+The default global-maximum download speed, in kilobytes per second.
+
+Defaults to @samp{100}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled?
+When @code{#t}, the daemon's upload speed will be limited to the rate
+specified by @code{speed-limit-up}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up
+The default global-maximum upload speed, in kilobytes per second.
+
+Defaults to @samp{100}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled?
+When @code{#t}, the alternate speed limits @code{alt-speed-down} and
+@code{alt-speed-up} are used (in place of @code{speed-limit-down} and
+@code{speed-limit-up}, if they are enabled) to constrain the daemon's
+bandwidth usage. This can be scheduled to occur automatically at
+certain times during the week; see @code{alt-speed-time-enabled?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down
+The alternate global-maximum download speed, in kilobytes per second.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up
+The alternate global-maximum upload speed, in kilobytes per second.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled?
+When @code{#t}, the alternate speed limits @code{alt-speed-down} and
+@code{alt-speed-up} will be enabled automatically during the periods
+specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and
+@code{alt-time-speed-end}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day
+The days of the week on which the alternate-speed schedule should be
+used, specified either as a list of days (@code{sunday}, @code{monday},
+and so on) or using one of the symbols @code{weekdays}, @code{weekends}
+or @code{all}.
+
+Defaults to @samp{all}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin
+The time of day at which to enable the alternate speed limits, expressed
+as a number of minutes since midnight.
+
+Defaults to @samp{540}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end
+The time of day at which to disable the alternate speed limits,
+expressed as a number of minutes since midnight.
+
+Defaults to @samp{1020}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4
+The IP address at which to listen for peer connections, or ``0.0.0.0''
+to listen at all available IP addresses.
+
+Defaults to @samp{"0.0.0.0"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6
+The IPv6 address at which to listen for peer connections, or ``::'' to
+listen at all available IPv6 addresses.
+
+Defaults to @samp{"::"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start?
+If @code{#t}, when the daemon starts it will select a port at random on
+which to listen for peer connections, from the range specified
+(inclusively) by @code{peer-port-random-low} and
+@code{peer-port-random-high}. Otherwise, it listens on the port
+specified by @code{peer-port}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low
+The lowest selectable port number when @code{peer-port-random-on-start?}
+is @code{#t}.
+
+Defaults to @samp{49152}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high
+The highest selectable port number when @code{peer-port-random-on-start}
+is @code{#t}.
+
+Defaults to @samp{65535}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port
+The port on which to listen for peer connections when
+@code{peer-port-random-on-start?} is @code{#f}.
+
+Defaults to @samp{51413}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled?
+If @code{#t}, the daemon will attempt to configure port-forwarding on an
+upstream gateway automatically using @acronym{UPnP} and
+@acronym{NAT-PMP}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption
+The encryption preference for peer connections, one of
+@code{prefer-unencrypted-connections},
+@code{prefer-encrypted-connections} or
+@code{require-encrypted-connections}.
+
+Defaults to @samp{prefer-encrypted-connections}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
+The TCP congestion-control algorithm to use for peer connections,
+specified using a string recognized by the operating system in calls to
+@code{setsockopt} (or set to @code{disabled}, in which case the
+operating-system default is used).
+
+Note that on GNU/Linux systems, the kernel must be configured to allow
+processes to use a congestion-control algorithm not in the default set;
+otherwise, it will deny these requests with ``Operation not permitted''.
+To see which algorithms are available on your system and which are
+currently permitted for use, look at the contents of the files
+@file{tcp_available_congestion_control} and
+@file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4}
+directory.
+
+As an example, to have Transmission Daemon use
+@uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority
+congestion-control algorithm}, you'll need to modify your kernel
+configuration to build in support for the algorithm, then update your
+operating-system configuration to allow its use by adding a
+@code{sysctl-service-type} service (or updating the existing one's
+configuration) with lines like the following:
+
+@lisp
+(service sysctl-service-type
+ (sysctl-configuration
+ (settings
+ ("net.ipv4.tcp_allowed_congestion_control" .
+ "reno cubic lp"))))
+@end lisp
+
+The Transmission Daemon configuration can then be updated with
+
+@lisp
+(peer-congestion-algorithm "lp")
+@end lisp
+
+and the system reconfigured to have the changes take effect.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos
+The type of service to request in outgoing @acronym{TCP} packets, one of
+@code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and
+@code{reliability}.
+
+Defaults to @samp{default}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global
+The global limit on the number of connected peers.
+
+Defaults to @samp{200}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent
+The per-torrent limit on the number of connected peers.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent
+The maximum number of peers to which the daemon will upload data
+simultaneously for each torrent.
+
+Defaults to @samp{14}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours
+The maximum lifespan, in hours, of the peer ID associated with each
+public torrent before it is regenerated.
+
+Defaults to @samp{6}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled?
+When @code{#t}, the daemon will ignore peers mentioned in the blocklist
+it has most recently downloaded from @code{blocklist-url}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url
+The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule
+@file{.dat} format) to be periodically downloaded and applied when
+@code{blocklist-enabled?} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled?
+If @code{#t}, the daemon will be limited to downloading at most
+@code{download-queue-size} non-stalled torrents simultaneously.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size
+The size of the daemon's download queue, which limits the number of
+non-stalled torrents it will download at any one time when
+@code{download-queue-enabled?} is @code{#t}.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled?
+If @code{#t}, the daemon will be limited to seeding at most
+@code{seed-queue-size} non-stalled torrents simultaneously.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size
+The size of the daemon's seed queue, which limits the number of
+non-stalled torrents it will seed at any one time when
+@code{seed-queue-enabled?} is @code{#t}.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled?
+When @code{#t}, the daemon will consider torrents for which it has not
+shared data in the past @code{queue-stalled-minutes} minutes to be
+stalled and not count them against its @code{download-queue-size} and
+@code{seed-queue-size} limits.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes
+The maximum period, in minutes, a torrent may be idle before it is
+considered to be stalled, when @code{queue-stalled-enabled?} is
+@code{#t}.
+
+Defaults to @samp{30}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled?
+When @code{#t}, a torrent being seeded will automatically be paused once
+it reaches the ratio specified by @code{ratio-limit}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit
+The ratio at which a torrent being seeded will be paused, when
+@code{ratio-limit-enabled?} is @code{#t}.
+
+Defaults to @samp{2.0}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled?
+When @code{#t}, a torrent being seeded will automatically be paused once
+it has been idle for @code{idle-seeding-limit} minutes.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit
+The maximum period, in minutes, a torrent being seeded may be idle
+before it is paused, when @code{idle-seeding-limit-enabled?} is
+@code{#t}.
+
+Defaults to @samp{30}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled?
+Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed
+hash table (@acronym{DHT}) protocol}, which supports the use of
+trackerless torrents.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled?
+Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local
+peer discovery} (@acronym{LPD}), which allows the discovery of peers on
+the local network and may reduce the amount of data sent over the public
+Internet.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled?
+Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange}
+(@acronym{PEX}), which reduces the daemon's reliance on external
+trackers and may improve its performance.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled?
+Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro
+transport protocol} (@acronym{uTP}), which aims to reduce the impact of
+BitTorrent traffic on other users of the local network while maintaining
+full utilization of the available bandwidth.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled?
+If @code{#t}, enable the remote procedure call (@acronym{RPC})
+interface, which allows remote control of the daemon via its Web
+interface, the @command{transmission-remote} command-line client, and
+similar tools.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address
+The IP address at which to listen for @acronym{RPC} connections, or
+``0.0.0.0'' to listen at all available IP addresses.
+
+Defaults to @samp{"0.0.0.0"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port
+The port on which to listen for @acronym{RPC} connections.
+
+Defaults to @samp{9091}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url
+The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}.
+
+Defaults to @samp{"/transmission/"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required?
+When @code{#t}, clients must authenticate (see @code{rpc-username} and
+@code{rpc-password}) when using the @acronym{RPC} interface. Note this
+has the side effect of disabling host-name whitelisting (see
+@code{rpc-host-whitelist-enabled?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username
+The username required by clients to access the @acronym{RPC} interface
+when @code{rpc-authentication-required?} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password
+The password required by clients to access the @acronym{RPC} interface
+when @code{rpc-authentication-required?} is @code{#t}. This must be
+specified using a password hash in the format recognized by Transmission
+clients, either copied from an existing @file{settings.json} file or
+generated using the @code{transmission-password-hash} procedure.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled?
+When @code{#t}, @acronym{RPC} requests will be accepted only when they
+originate from an address specified in @code{rpc-whitelist}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist
+The list of IP and IPv6 addresses from which @acronym{RPC} requests will
+be accepted when @code{rpc-whitelist-enabled?} is @code{#t}. Wildcards
+may be specified using @samp{*}.
+
+Defaults to @samp{("127.0.0.1" "::1")}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled?
+When @code{#t}, @acronym{RPC} requests will be accepted only when they
+are addressed to a host named in @code{rpc-host-whitelist}. Note that
+requests to ``localhost'' or ``localhost.'', or to a numeric address,
+are always accepted regardless of these settings.
+
+Note also this functionality is disabled when
+@code{rpc-authentication-required?} is @code{#t}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist
+The list of host names recognized by the @acronym{RPC} server when
+@code{rpc-host-whitelist-enabled?} is @code{#t}.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level
+The minimum severity level of messages to be logged (to
+@file{/var/log/transmission.log}) by the daemon, one of @code{none} (no
+logging), @code{error}, @code{info} and @code{debug}.
+
+Defaults to @samp{info}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents?
+When @code{#t}, torrents are started as soon as they are added;
+otherwise, they are added in ``paused'' state.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled?
+When @code{#t}, the script specified by
+@code{script-torrent-done-filename} will be invoked each time a torrent
+completes.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename
+A file name or file-like object specifying a script to run each time a
+torrent completes, when @code{script-torrent-done-enabled?} is
+@code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled?
+When @code{#t}, the daemon will scrape trackers for a torrent even when
+the torrent is paused.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb
+The amount of memory, in megabytes, to allocate for the daemon's
+in-memory cache. A larger value may increase performance by reducing
+the frequency of disk I/O.
+
+Defaults to @samp{4}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled?
+When @code{#t}, the daemon will try to improve I/O performance by
+hinting to the operating system which data is likely to be read next
+from disk to satisfy requests from peers.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+
+@c %end of fragment
+
+
+
@node Monitoring Services
@subsection Monitoring Services
@end table
@end deftp
+@subsubheading Agate
+
+@cindex agate
+The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate}
+(@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS})
+program is a simple @uref{https://gemini.circumlunar.space/, Gemini}
+protocol server written in Rust.
+
+@deffn {Scheme Variable} agate-service-type
+This is the type of the agate service, whose value should be an
+@code{agate-service-type} object, as in this example:
+
+@lisp
+(service agate-service-type
+ (agate-configuration
+ (content "/srv/gemini")
+ (cert "/srv/cert.pem")
+ (key "/srv/key.rsa")))
+@end lisp
+
+The example above represents the minimal tweaking necessary to get Agate
+up and running. Specifying the path to the certificate and key is
+always necessary, as the Gemini protocol requires TLS by default.
+
+To obtain a certificate and a key, you could, for example, use OpenSSL,
+running a command similar to the following example:
+
+@example
+openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
+ -days 3650 -nodes -subj "/CN=example.com"
+@end example
+
+Of course, you'll have to replace @i{example.com} with your own domain
+name, and then point the Agate configuration towards the path of the
+generated key and certificate.
+
+@end deffn
+
+@deftp {Data Type} agate-configuration
+Data type representing the configuration of Agate.
+
+@table @asis
+@item @code{package} (default: @code{agate})
+The package object of the Agate server.
+
+@item @code{content} (default: @file{"/srv/gemini"})
+The directory from which Agate will serve files.
+
+@item @code{cert} (default: @code{#f})
+The path to the TLS certificate PEM file to be used for encrypted
+connections. Must be filled in with a value from the user.
+
+@item @code{key} (default: @code{#f})
+The path to the PKCS8 private key file to be used for encrypted
+connections. Must be filled in with a value from the user.
+
+@item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")})
+A list of the addresses to listen on.
+
+@item @code{hostname} (default: @code{#f})
+The domain name of this Gemini server. Optional.
+
+@item @code{lang} (default: @code{#f})
+RFC 4646 language code(s) for text/gemini documents. Optional.
+
+@item @code{silent?} (default: @code{#f})
+Set to @code{#t} to disable logging output.
+
+@item @code{serve-secret?} (default: @code{#f})
+Set to @code{#t} to serve secret files (files/directories starting with
+a dot).
+
+@item @code{log-ip?} (default: @code{#t})
+Whether or not to output IP addresses when logging.
+
+@item @code{user} (default: @code{"agate"})
+Owner of the @code{agate} process.
+
+@item @code{group} (default: @code{"agate"})
+Owner's group of the @code{agate} process.
+
+@item @code{log-file} (default: @file{"/var/log/agate.log"})
+The file which should store the logging output of Agate.
+
+@end table
+@end deftp
+
@node Certificate Services
@subsection Certificate Services
and check again that it still exists.
@item @code{nx} (default: @code{3600})
-Default TTL of inexistant records. This delay is usually short because you want
+Default TTL of inexistent records. This delay is usually short because you want
your new domains to reach everyone quickly.
@end table
@cindex virtual private network (VPN)
The @code{(gnu services vpn)} module provides services related to
-@dfn{virtual private networks} (VPNs). It provides a @emph{client} service for
-your machine to connect to a VPN, and a @emph{server} service for your machine
-to host a VPN@. Both services use @uref{https://openvpn.net/, OpenVPN}.
+@dfn{virtual private networks} (VPNs).
+
+@subsubheading OpenVPN
+
+It provides a @emph{client} service for your machine to connect to a
+VPN, and a @emph{server} service for your machine to host a VPN@.
@deffn {Scheme Procedure} openvpn-client-service @
[#:config (openvpn-client-configuration)]
@c %end of automatic openvpn-server documentation
+@subsubheading Wireguard
+
+@defvr {Scheme Variable} wireguard-service-type
+A service type for a Wireguard tunnel interface. Its value must be a
+@code{wireguard-configuration} record as in this example:
+
+@lisp
+(service wireguard-service-type
+ (wireguard-configuration
+ (peers
+ (list
+ (wireguard-peer
+ (name "my-peer")
+ (endpoint "my.wireguard.com:51820")
+ (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
+ (allowed-ips '("10.0.0.2/32")))))))
+@end lisp
+
+@end defvr
+
+@deftp {Data Type} wireguard-configuration
+Data type representing the configuration of the Wireguard service.
+
+@table @asis
+@item @code{wireguard}
+The wireguard package to use for this service.
+
+@item @code{interface} (default: @code{"wg0"})
+The interface name for the VPN.
+
+@item @code{addresses} (default: @code{'("10.0.0.1/32")})
+The IP addresses to be assigned to the above interface.
+
+@item @code{private-key} (default: @code{"/etc/wireguard/private.key"})
+The private key file for the interface. It is automatically generated if
+the file does not exist.
+
+@item @code{peers} (default: @code{'()})
+The authorized peers on this interface. This is a list of
+@var{wireguard-peer} records.
+
+@end table
+@end deftp
+
+@deftp {Data Type} wireguard-peer
+Data type representing a Wireguard peer attached to a given interface.
+
+@table @asis
+@item @code{name}
+The peer name.
+
+@item @code{endpoint} (default: @code{#f})
+The optional endpoint for the peer, such as
+@code{"demo.wireguard.com:51820"}.
+
+@item @code{public-key}
+The peer public-key represented as a base64 string.
+
+@item @code{allowed-ips}
+A list of IP addresses from which incoming traffic for this peer is
+allowed and to which incoming traffic for this peer is directed.
+
+@end table
+@end deftp
@node Network File System
@subsection Network File System
@subsection Continuous Integration
@cindex continuous integration
-@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a
-continuous integration tool for Guix. It can be used both for development and
-for providing substitutes to others (@pxref{Substitutes}).
+@uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
+integration tool for Guix. It can be used both for development and for
+providing substitutes to others (@pxref{Substitutes}).
The @code{(gnu services cuirass)} module provides the following service.
@code{cuirass-configuration} object, as described below.
@end defvr
-To add build jobs, you have to set the @code{specifications} field of the
-configuration. Here is an example of a service that polls the Guix repository
-and builds the packages from a manifest. Some of the packages are defined in
-the @code{"custom-packages"} input, which is the equivalent of
-@env{GUIX_PACKAGE_PATH}.
+To add build jobs, you have to set the @code{specifications} field of
+the configuration. For instance, the following example will build all
+the packages provided by the @code{my-channel} channel.
+
+@lisp
+(define %cuirass-specs
+ #~(list (specification
+ (name "my-channel")
+ (build '(channels my-channel))
+ (channels
+ (cons (channel
+ (name 'my-channel)
+ (url "https://my-channel.git"))
+ %default-channels)))))
+
+(service cuirass-service-type
+ (cuirass-configuration
+ (specifications %cuirass-specs)))
+@end lisp
+
+To build the @code{linux-libre} package defined by the default Guix
+channel, one can use the following configuration.
@lisp
(define %cuirass-specs
- #~(list
- '((#:name . "my-manifest")
- (#:load-path-inputs . ("guix"))
- (#:package-path-inputs . ("custom-packages"))
- (#:proc-input . "guix")
- (#:proc-file . "build-aux/cuirass/gnu-system.scm")
- (#:proc . cuirass-jobs)
- (#:proc-args . ((subset . "manifests")
- (systems . ("x86_64-linux"))
- (manifests . (("config" . "guix/manifest.scm")))))
- (#:inputs . (((#:name . "guix")
- (#:url . "git://git.savannah.gnu.org/guix.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t))
- ((#:name . "config")
- (#:url . "https://git.example.org/config.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t))
- ((#:name . "custom-packages")
- (#:url . "https://git.example.org/custom-packages.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t)))))))
+ #~(list (specification
+ (name "my-linux")
+ (build '(packages "linux-libre")))))
(service cuirass-service-type
(cuirass-configuration
(specifications %cuirass-specs)))
@end lisp
+The other configuration possibilities, as well as the specification
+record itself are described in the Cuirass manual
+(@pxref{Specifications,,, cuirass, Cuirass}).
+
While information related to build jobs is located directly in the
specifications, global settings for the @command{cuirass} process are
accessible in other @code{cuirass-configuration} fields.
Data type representing the configuration of Cuirass.
@table @asis
+@item @code{cuirass} (default: @code{cuirass})
+The Cuirass package to use.
+
@item @code{log-file} (default: @code{"/var/log/cuirass.log"})
Location of the log file.
@item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
Location of the log file used by the web interface.
-@item @code{queries-log-file} (default: @code{#f})
-Location of the SQL queries log file. By default, SQL queries logging is
-disabled.
-
-@item @code{web-queries-log-file} (default: @code{#f})
-Location of the web SQL queries log file. By default, web SQL queries
-logging is disabled.
-
@item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
Location of the repository cache.
Number of seconds between the poll of the repositories followed by the
Cuirass jobs.
-@item @code{queue-size} (default: @code{1})
-Size of the database writer queue.
+@item @code{parameters} (default: @code{#f})
+Read parameters from the given @var{parameters} file. The supported
+parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
-@item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"})
-Location of sqlite database which contains the build results and previously
-added specifications.
+@item @code{remote-server} (default: @code{#f})
+A @code{cuirass-remote-server-configuration} record to use the build
+remote mechanism or @code{#f} to use the default build mechanism.
-@item @code{ttl} (default: @code{(* 30 24 3600)})
-Specifies the time-to-live (TTL) in seconds of garbage collector roots that
-are registered for build results. This means that build results are protected
-from garbage collection for at least @var{ttl} seconds.
+@item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
+Use @var{database} as the database containing the jobs and the past
+build results. Since Cuirass uses PostgreSQL as a database engine,
+@var{database} must be a string such as @code{"dbname=cuirass
+host=localhost"}.
@item @code{port} (default: @code{8081})
Port number used by the HTTP server.
accept connections from localhost.
@item @code{specifications} (default: @code{#~'()})
-A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications,
-where a specification is an association list
-(@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) whose
-keys are keywords (@code{#:keyword-example}) as shown in the example
-above.
+A gexp (@pxref{G-Expressions}) that evaluates to a list of
+specifications records. The specification record is described in the
+Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
@item @code{use-substitutes?} (default: @code{#f})
This allows using substitutes to avoid building every dependencies of a job
@item @code{extra-options} (default: @code{'()})
Extra options to pass when running the Cuirass processes.
+@end table
+@end deftp
+
+@cindex remote build
+@subsubheading Cuirass remote building
+
+Cuirass supports two mechanisms to build derivations.
+
+@itemize
+@item Using the local Guix daemon.
+This is the default build mechanism. Once the build jobs are
+evaluated, they are sent to the local Guix daemon. Cuirass then
+listens to the Guix daemon output to detect the various build events.
+
+@item Using the remote build mechanism.
+The build jobs are not submitted to the local Guix daemon. Instead, a
+remote server dispatches build requests to the connect remote workers,
+according to the build priorities.
+
+@end itemize
+
+To enable this build mode a @code{cuirass-remote-server-configuration}
+record must be passed as @code{remote-server} argument of the
+@code{cuirass-configuration} record. The
+@code{cuirass-remote-server-configuration} record is described below.
+
+This build mode scales way better than the default build mode. This is
+the build mode that is used on the GNU Guix build farm at
+@url{https://ci.guix.gnu.org}. It should be preferred when using
+Cuirass to build large amount of packages.
+
+@deftp {Data Type} cuirass-remote-server-configuration
+Data type representing the configuration of the Cuirass remote-server.
+
+@table @asis
+@item @code{backend-port} (default: @code{5555})
+The TCP port for communicating with @code{remote-worker} processes
+using ZMQ. It defaults to @code{5555}.
+
+@item @code{log-port} (default: @code{5556})
+The TCP port of the log server. It defaults to @code{5556}.
+
+@item @code{publish-port} (default: @code{5557})
+The TCP port of the publish server. It defaults to @code{5557}.
+
+@item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
+Location of the log file.
+
+@item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
+Use @var{cache} directory to cache build log files.
+
+@item @code{trigger-url} (default: @code{#f})
+Once a substitute is successfully fetched, trigger substitute baking at
+@var{trigger-url}.
+
+@item @code{public-key}
+@item @code{private-key}
+Use the specific @var{file}s as the public/private key pair used to sign
+the store items being published.
+
+@end table
+@end deftp
+
+At least one remote worker must also be started on any machine of the
+local network to actually perform the builds and report their status.
+
+@deftp {Data Type} cuirass-remote-worker-configuration
+Data type representing the configuration of the Cuirass remote-worker.
+
+@table @asis
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.
+
+@item @code{workers} (default: @code{1})
+Start @var{workers} parallel workers.
+
+@item @code{server} (default: @code{#f})
+Do not use Avahi discovery and connect to the given @code{server} IP
+address instead.
+
+@item @code{systems} (default: @code{(list (%current-system))})
+Only request builds for the given @var{systems}.
+
+@item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
+Location of the log file.
+
+@item @code{publish-port} (default: @code{5558})
+The TCP port of the publish server. It defaults to @code{5558}.
+
+@item @code{public-key}
+@item @code{private-key}
+Use the specific @var{file}s as the public/private key pair used to sign
+the store items being published.
+
+@end table
+@end deftp
+
+@subsubheading Laminar
+
+@uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular
+Continuous Integration service. It doesn't have a configuration web UI
+instead uses version-controllable configuration files and scripts.
+
+Laminar encourages the use of existing tools such as bash and cron
+instead of reinventing them.
+
+@defvr {Scheme Procedure} laminar-service-type
+The type of the Laminar service. Its value must be a
+@code{laminar-configuration} object, as described below.
+
+All configuration values have defaults, a minimal configuration to get
+Laminar running is shown below. By default, the web interface is
+available on port 8080.
+
+@lisp
+(service laminar-service-type)
+@end lisp
+@end defvr
+
+@deftp {Data Type} laminar-configuration
+Data type representing the configuration of Laminar.
+
+@table @asis
+@item @code{laminar} (default: @code{laminar})
+The Laminar package to use.
+
+@item @code{home-directory} (default: @code{"/var/lib/laminar"})
+The directory for job configurations and run directories.
+
+@item @code{bind-http} (default: @code{"*:8080"})
+The interface/port or unix socket on which laminard should listen for
+incoming connections to the web frontend.
+
+@item @code{bind-rpc} (default: @code{"unix-abstract:laminar"})
+The interface/port or unix socket on which laminard should listen for
+incoming commands such as build triggers.
+
+@item @code{title} (default: @code{"Laminar"})
+The page title to show in the web frontend.
+
+@item @code{keep-rundirs} (default: @code{0})
+Set to an integer defining how many rundirs to keep per job. The
+lowest-numbered ones will be deleted. The default is 0, meaning all run
+dirs will be immediately deleted.
+
+@item @code{archive-url} (default: @code{#f})
+The web frontend served by laminard will use this URL to form links to
+artefacts archived jobs.
+
+@item @code{base-url} (default: @code{#f})
+Base URL to use for links to laminar itself.
+
@end table
@end deftp
The list of emulated QEMU platforms. Each item must be a @dfn{platform
object} as returned by @code{lookup-qemu-platforms} (see below).
-@item @code{guix-support?} (default: @code{#t})
-When it is true, QEMU and all its dependencies are added to the build
-environment of @command{guix-daemon} (@pxref{Invoking guix-daemon,
-@option{--chroot-directory} option}). This allows the @code{binfmt_misc}
-handlers to be used within the build environment, which in turn means
-that you can transparently build programs for another architecture.
-
For example, let's suppose you're on an x86_64 machine and you have this
service:
@lisp
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm"))
- (guix-support? #t)))
+ (platforms (lookup-qemu-platforms "arm"))))
@end lisp
You can run:
if you'd like to test a package build for an architecture you don't have
access to!
-When @code{guix-support?} is set to @code{#f}, programs for other
-architectures can still be executed transparently, but invoking commands
-like @command{guix build -s armhf-linux @dots{}} will fail.
-
@item @code{qemu} (default: @code{qemu})
The QEMU package to use.
@end table
@item @code{coordinator} (default: @code{"http://localhost:8745"})
The URI to use when connecting to the coordinator.
-@item @code{uuid}
-The UUID of the agent. This should be generated by the coordinator
-process, stored in the coordinator database, and used by the intended
-agent.
-
-@item @code{password} (default: @code{#f})
-The password to use when connecting to the coordinator. A file to read
-the password from can also be specified, and this is more secure.
-
-@item @code{password-file} (default: @code{#f})
-A file containing the password to use when connecting to the
-coordinator.
+@item @code{authentication}
+Record describing how this agent should authenticate with the
+coordinator. Possible record types are described below.
@item @code{systems} (default: @code{#f})
The systems for which this agent should fetch builds. The agent process
@end table
@end deftp
+@deftp {Data Type} guix-build-coordinator-agent-password-auth
+Data type representing an agent authenticating with a coordinator via a
+UUID and password.
+
+@table @asis
+@item @code{uuid}
+The UUID of the agent. This should be generated by the coordinator
+process, stored in the coordinator database, and used by the intended
+agent.
+
+@item @code{password}
+The password to use when connecting to the coordinator.
+
+@end table
+@end deftp
+
+@deftp {Data Type} guix-build-coordinator-agent-password-file-auth
+Data type representing an agent authenticating with a coordinator via a
+UUID and password read from a file.
+
+@table @asis
+@item @code{uuid}
+The UUID of the agent. This should be generated by the coordinator
+process, stored in the coordinator database, and used by the intended
+agent.
+
+@item @code{password-file}
+A file containing the password to use when connecting to the
+coordinator.
+
+@end table
+@end deftp
+
+@deftp {Data Type} guix-build-coordinator-agent-dynamic-auth
+Data type representing an agent authenticating with a coordinator via a
+dynamic auth token and agent name.
+
+@table @asis
+@item @code{agent-name}
+Name of an agent, this is used to match up to an existing entry in the
+database if there is one. When no existing entry is found, a new entry
+is automatically added.
+
+@item @code{token}
+Dynamic auth token, this is created and stored in the coordinator
+database, and is used by the agent to authenticate.
+
+@end table
+@end deftp
+
+@deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file
+Data type representing an agent authenticating with a coordinator via a
+dynamic auth token read from a file and agent name.
+
+@table @asis
+@item @code{agent-name}
+Name of an agent, this is used to match up to an existing entry in the
+database if there is one. When no existing entry is found, a new entry
+is automatically added.
+
+@item @code{token-file}
+File containing the dynamic auth token, this is created and stored in
+the coordinator database, and is used by the agent to authenticate.
+
+@end table
+@end deftp
+
The Guix Build Coordinator package contains a script to query an
instance of the Guix Data Service for derivations to build, and then
submit builds for those derivations to the coordinator. The service
(sysctl-configuration
(settings '(("net.ipv4.ip_forward" . "1")))))
@end lisp
+
+Since @code{sysctl-service-type} is used in the default lists of
+services, @code{%base-services} and @code{%desktop-services}, you can
+use @code{modify-services} to change its configuration and add the
+kernel parameters that you want (@pxref{Service Reference,
+@code{modify-services}}).
+
+@lisp
+(modify-services %base-services
+ (sysctl-service-type config =>
+ (sysctl-configuration
+ (settings (append '(("net.ipv4.ip_forward" . "1"))
+ %default-sysctl-settings)))))
+@end lisp
+
@end defvr
@deftp {Data Type} sysctl-configuration
@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
The @command{sysctl} executable to use.
-@item @code{settings} (default: @code{'()})
+@item @code{settings} (default: @code{%default-sysctl-settings})
An association list specifies kernel parameters and their values.
@end table
@end deftp
+@defvr {Scheme Variable} %default-sysctl-settings
+An association list specifying the default @command{sysctl} parameters
+on Guix System.
+@end defvr
+
@cindex pcscd
@subsubheading PC/SC Smart Card Daemon Service
@cindex System images, creation in various formats
@cindex Creating system images in various formats
-@item vm-image
-@itemx image
+@item image
@itemx docker-image
Return a virtual machine, disk image, or Docker image of the operating
system declared in @var{file} that stands alone. By default,
The @code{--list-image-types} command lists all the available image
types.
-@cindex vm-image, creating virtual machine images
-When using @code{vm-image}, the returned image is in qcow2 format, which
-the QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for
-more information on how to run the image in a virtual machine. The
-@code{grub-bootloader} bootloader is always used independently of what
-is declared in the @code{operating-system} file passed as argument.
-This is to make it easier to work with QEMU, which uses the SeaBIOS BIOS
-by default, expecting a bootloader to be installed in the Master Boot
-Record (MBR).
+@cindex creating virtual machine images
+When using the @code{qcow2} image type, the returned image is in qcow2
+format, which the QEMU emulator can efficiently use. @xref{Running Guix
+in a VM}, for more information on how to run the image in a virtual
+machine. The @code{grub-bootloader} bootloader is always used
+independently of what is declared in the @code{operating-system} file
+passed as argument. This is to make it easier to work with QEMU, which
+uses the SeaBIOS BIOS by default, expecting a bootloader to be installed
+in the Master Boot Record (MBR).
@cindex docker-image, creating docker images
When using @code{docker-image}, a Docker image is produced. Guix builds
Docker container using commands like the following:
@example
-image_id="`docker load < guix-system-docker-image.tar.gz`"
-container_id="`docker create $image_id`"
+image_id="$(docker load < guix-system-docker-image.tar.gz)"
+container_id="$(docker create $image_id)"
docker start $container_id
@end example
can run:
@example
-guix system vm-image --save-provenance config.scm
+guix system image -t qcow2 --save-provenance config.scm
@end example
That way, the resulting image will effectively ``embed its own source''
for burning on CDs and DVDs.
@item --image-size=@var{size}
-For the @code{vm-image} and @code{image} actions, create an image
-of the given @var{size}. @var{size} may be a number of bytes, or it may
-include a unit as a suffix (@pxref{Block size, size specifications,,
-coreutils, GNU Coreutils}).
+For the @code{image} action, create an image of the given @var{size}.
+@var{size} may be a number of bytes, or it may include a unit as a
+suffix (@pxref{Block size, size specifications,, coreutils, GNU
+Coreutils}).
When this option is omitted, @command{guix system} computes an estimate
of the image size as a function of the size of the system declared in
before you can use it. When invoking QEMU, you must choose a system
emulator that is suitable for your hardware platform. Here is a minimal
QEMU invocation that will boot the result of @command{guix system
-vm-image} on x86_64 hardware:
+image -t qcow2} on x86_64 hardware:
@example
$ qemu-system-x86_64 \
@command{guix system vm} does not add a @command{-nic user} flag by default.
To get network access from within the vm add the @code{(dhcp-client-service)}
to your system definition and start the VM using
-@command{`guix system vm config.scm` -nic user}. An important caveat of using
+@command{$(guix system vm config.scm) -nic user}. An important caveat of using
@command{-nic user} for networking is that @command{ping} will not work, because
it uses the ICMP protocol. You'll have to use a different command to check for
network connectivity, for example @command{guix download}.
22 by default, to the host. You can do this with
@example
-`guix system vm config.scm` -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
+$(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
@end example
To connect to the VM you can run
@example
-ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022
+ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
@end example
The @command{-p} tells @command{ssh} the port you want to connect to.
@end table
@end deftp
+The example below defines a Shepherd service that spawns
+@command{syslogd}, the system logger from the GNU Networking Utilities
+(@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU
+Inetutils}):
+
+@example
+(let ((config (plain-file "syslogd.conf" "@dots{}")))
+ (shepherd-service
+ (documentation "Run the syslog daemon (syslogd).")
+ (provision '(syslogd))
+ (requirement '(user-processes))
+ (start #~(make-forkexec-constructor
+ (list #$(file-append inetutils "/libexec/syslogd")
+ "--rcfile" #$config)
+ #:pid-file "/var/run/syslog.pid"))
+ (stop #~(make-kill-destructor))))
+@end example
+
+Key elements in this example are the @code{start} and @code{stop}
+fields: they are @dfn{staged} code snippets that use the
+@code{make-forkexec-constructor} procedure provided by the Shepherd and
+its dual, @code{make-kill-destructor} (@pxref{Service De- and
+Constructors,,, shepherd, The GNU Shepherd Manual}). The @code{start}
+field will have @command{shepherd} spawn @command{syslogd} with the
+given option; note that we pass @code{config} after @option{--rcfile},
+which is a configuration file declared above (contents of this file are
+omitted). Likewise, the @code{stop} field tells how this service is to
+be stopped; in this case, it is stopped by making the @code{kill} system
+call on its PID@. Code staging is achieved using G-expressions:
+@code{#~} stages code, while @code{#$} ``escapes'' back to host code
+(@pxref{G-Expressions}).
+
@deftp {Data Type} shepherd-action
This is the data type that defines additional actions implemented by a
Shepherd service (see above).
@cindex man pages
@cindex manual pages
In most cases packages installed with Guix come with documentation.
-There are two main documentation formats: ``Info'', a browseable
+There are two main documentation formats: ``Info'', a browsable
hypertext format used for GNU software, and ``manual pages'' (or ``man
pages''), the linear documentation format traditionally found on Unix.
Info manuals are accessed with the @command{info} command or with Emacs,
(@pxref{Invoking guix gc}):
@example
-guix gc -R `readlink -f ~/.guix-profile` | grep bash
+guix gc -R $(readlink -f ~/.guix-profile) | grep bash
@end example
@noindent
Likewise for a complete Guix system generation:
@example
-guix gc -R `guix system build my-config.scm` | grep bash
+guix gc -R $(guix system build my-config.scm) | grep bash
@end example
Lastly, to check which Bash running processes are using, you can use the
Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were
removed are now built from source.
-Building the GNU System from source is currently only possibly by adding
+Building the GNU System from source is currently only possible by adding
some historical GNU packages as intermediate steps@footnote{Packages
such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
@code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see
The only significant binary bootstrap seeds that remain@footnote{
Ignoring the 68KB @code{mescc-tools}; that will be removed later,
-together with @code{mes}.} are a Scheme intepreter and a Scheme
+together with @code{mes}.} are a Scheme interpreter and a Scheme
compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
to get Guile running.}.