@include version.texi
@c Identifier of the OpenPGP key used to sign tarballs and such.
-@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
-@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145
+@set OPENPGP-SIGNING-KEY-ID 27D586A4F8900854329FF09F1260E46482E63562
+@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=127547
@c Base URL for downloads.
@set BASE-URL https://ftp.gnu.org/gnu/guix
@c The official substitute server used by default.
-@set SUBSTITUTE-SERVER ci.guix.gnu.org
-@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
+@set SUBSTITUTE-SERVER-1 ci.guix.gnu.org
+@set SUBSTITUTE-SERVER-2 bordeaux.guix.gnu.org
+@set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
-Copyright @copyright{} 2017, 2021 Christopher Lemmer Webber@*
-Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
+Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Marius Bakke@*
Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2020 Jakub Kądziołka@*
Copyright @copyright{} 2020 Jack Hill@*
Copyright @copyright{} 2020 Naga Malleswari@*
-Copyright @copyright{} 2020 Brice Waegeneire@*
+Copyright @copyright{} 2020, 2021 Brice Waegeneire@*
Copyright @copyright{} 2020 R Veera Kumar@*
Copyright @copyright{} 2020 Pierre Langlois@*
Copyright @copyright{} 2020 pinoaffe@*
Copyright @copyright{} 2020 Edgar Vincent@*
Copyright @copyright{} 2021 Maxime Devos@*
Copyright @copyright{} 2021 B. Wilson@*
+Copyright @copyright{} 2021 Xinglu Chen@*
+Copyright @copyright{} 2021 Raghav Gururajan@*
+Copyright @copyright{} 2021 Domagoj Stolfa@*
+Copyright @copyright{} 2021 Hui Lu@*
+Copyright @copyright{} 2021 pukkamustard@*
+Copyright @copyright{} 2021 Alice Brenon@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
Substitutes
-* Official Substitute Server:: One particular source of substitutes.
+* Official Substitute Servers:: One particular source of substitutes.
* Substitute Server Authorization:: How to enable or disable substitutes.
* Getting Substitutes from Other Servers:: Substitute diversity.
* Substitute Authentication:: How Guix verifies substitutes.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
+* Invoking guix style:: Styling package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix size:: Profiling disk usage.
* Invoking guix graph:: Visualizing the graph of packages.
@item
@cindex substitutes, authorization thereof
-To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its mirrors
-(@pxref{Substitutes}), authorize them:
+To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
+@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
+authorize them:
@example
# guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub
+ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
+# guix archive --authorize < \
+ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
@end example
+@quotation Note
+If you do not enable substitutes, Guix will end up building
+@emph{everything} from source on your machine, making each installation
+and upgrade very expensive. @xref{On Trusting Binaries}, for a
+discussion of reasons why one might want do disable substitutes.
+@end quotation
+
@item
Each user may need to perform a few additional steps to make their Guix
environment ready for use, @pxref{Application Setup}.
GNU Guix depends on the following packages:
@itemize
-@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x or
-2.2.x;
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
@item
-@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
+@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
or later;
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
4.3.0 or later;
@item --substitute-urls=@var{urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs. When this option is omitted,
-@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used.
+@indicateurl{@value{SUBSTITUTE-URLS}} is used.
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
@subsection X11 Fonts
@cindex fonts
-The majority of graphical applications use Fontconfig to locate and
-load fonts and perform X11-client-side rendering. The @code{fontconfig}
-package in Guix looks for fonts in @file{$HOME/.guix-profile}
-by default. Thus, to allow graphical applications installed with Guix
-to display fonts, you have to install fonts with Guix as well.
-Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
+The majority of graphical applications use Fontconfig to locate and load
+fonts and perform X11-client-side rendering. The @code{fontconfig}
+package in Guix looks for fonts in @file{$HOME/.guix-profile} by
+default. Thus, to allow graphical applications installed with Guix to
+display fonts, you have to install fonts with Guix as well. Essential
+font packages include @code{font-ghostscript}, @code{font-dejavu}, and
@code{font-gnu-freefont}.
@cindex @code{fc-cache}
An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
-@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz},
+@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso},
where you can replace @code{x86_64-linux} with one of:
@table @code
authenticity of the image against it, along these lines:
@example
-$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz.sig
-$ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.xz.sig
+$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
+$ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
@end example
If that command fails because you do not have the required public key,
@unnumberedsubsec Copying to a USB Stick
-To copy the image to a USB stick, follow these steps:
-
-@enumerate
-@item
-Decompress the image using the @command{xz} command:
-
-@example
-xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz
-@end example
-
-@item
Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
its device name. Assuming that the USB stick is known as @file{/dev/sdX},
copy the image with:
@end example
Access to @file{/dev/sdX} usually requires root privileges.
-@end enumerate
@unnumberedsubsec Burning on a DVD
-To copy the image to a DVD, follow these steps:
-
-@enumerate
-@item
-Decompress the image using the @command{xz} command:
-
-@example
-xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz
-@end example
-
-@item
Insert a blank DVD into your machine, and determine
its device name. Assuming that the DVD drive is known as @file{/dev/srX},
copy the image with:
@end example
Access to @file{/dev/srX} usually requires root privileges.
-@end enumerate
@unnumberedsubsec Booting
that end, the installation system comes with three text editors. We
recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
supports syntax highlighting and parentheses matching; other editors
-include GNU Zile (an Emacs clone), and
+include mg (an Emacs clone), and
nvi (a clone of the original BSD @command{vi} editor).
We strongly recommend storing that file on the target root file system, say,
as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
@itemize
@item
-Make sure the @code{bootloader-configuration} form refers to the target
-you want to install GRUB on. It should mention @code{grub-bootloader} if
-you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
-for newer UEFI systems. For legacy systems, the @code{target} field
-names a device, like @code{/dev/sda}; for UEFI systems it names a path
-to a mounted EFI partition, like @code{/boot/efi}; do make sure the path is
-currently mounted and a @code{file-system} entry is specified in your
-configuration.
+Make sure the @code{bootloader-configuration} form refers to the targets
+you want to install GRUB on. It should mention @code{grub-bootloader}
+if you are installing GRUB in the legacy way, or
+@code{grub-efi-bootloader} for newer UEFI systems. For legacy systems,
+the @code{targets} field contain the names of the devices, like
+@code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
+EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
+are currently mounted and a @code{file-system} entry is specified in
+your configuration.
@item
Be sure that your file system labels match the value of their respective
@end quotation
Now, @pxref{Getting Started}, and
-join us on @code{#guix} on the Freenode IRC network or on
+join us on @code{#guix} on the Libera Chat IRC network or on
@email{guix-devel@@gnu.org} to share your experience!
do not use Bash) so that environment variables are set next time you
spawn a shell. You only need to do this once and other search paths
environment variables will be taken care of similarly---e.g., if you
-eventually install @code{python} and Python libraries, @code{PYTHONPATH}
-will be defined.
+eventually install @code{python} and Python libraries,
+@env{GUIX_PYTHONPATH} will be defined.
You can go on installing packages at your will. To list installed
packages, run:
recutils manual}).
@example
-$ guix package --show=python | recsel -p name,version
-name: python
-version: 2.7.6
+$ guix package --show=guile | recsel -p name,version
+name: guile
+version: 3.0.5
+
+name: guile
+version: 3.0.2
-name: python
-version: 3.3.5
+name: guile
+version: 2.2.7
+@dots{}
@end example
You may also specify the full name of a package to only get details about a
specific version of it (this time using the @command{guix show} alias):
@example
-$ guix show python@@3.4 | recsel -p name,version
-name: python
-version: 3.4.3
+$ guix show guile@@3.0.5 | recsel -p name,version
+name: guile
+version: 3.0.5
@end example
-
-
@item --list-installed[=@var{regexp}]
@itemx -I [@var{regexp}]
List the currently installed packages in the specified profile, with the
also result from derivation builds, can be available as substitutes.
@menu
-* Official Substitute Server:: One particular source of substitutes.
+* Official Substitute Servers:: One particular source of substitutes.
* Substitute Server Authorization:: How to enable or disable substitutes.
* Getting Substitutes from Other Servers:: Substitute diversity.
* Substitute Authentication:: How Guix verifies substitutes.
* On Trusting Binaries:: How can you trust that binary blob?
@end menu
-@node Official Substitute Server
-@subsection Official Substitute Server
+@node Official Substitute Servers
+@subsection Official Substitute Servers
@cindex build farm
-The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
-that builds packages from Guix continuously for some
-architectures, and makes them available as substitutes. This is the
-default source of substitutes; it can be overridden by passing the
+@code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
+farms that build packages from Guix continuously for some architectures,
+and make them available as substitutes. These are the default source of
+substitutes; which can be overridden by passing the
@option{--substitute-urls} option either to @command{guix-daemon}
(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
or to client tools such as @command{guix package}
could use the information gathered to determine, for instance, whether
your system has unpatched security vulnerabilities.
-Substitutes from the official build farm are enabled by default when
+Substitutes from the official build farms are enabled by default when
using Guix System (@pxref{GNU Distribution}). However,
they are disabled by default when using Guix on a foreign distribution,
unless you have explicitly enabled them via one of the recommended
@cindex substitutes, authorization thereof
@cindex access control list (ACL), for substitutes
@cindex ACL (access control list), for substitutes
-To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} or a
-mirror thereof, you
-must add its public key to the access control list (ACL) of archive
+To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
+must add the relevant public key to the access control list (ACL) of archive
imports, using the @command{guix archive} command (@pxref{Invoking guix
-archive}). Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not
+archive}). Doing so implies that you trust the substitute server to not
be compromised and to serve genuine substitutes.
@quotation Note
If you are using Guix System, you can skip this section: Guix System
-authorizes substitutes from @code{@value{SUBSTITUTE-SERVER}} by default.
+authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} by default.
@end quotation
-The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in
-@code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where @var{prefix} is
-the installation prefix of Guix. If you installed Guix from source,
-make sure you checked the GPG signature of
+The public keys for each of the project maintained substitute servers
+are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
+@var{prefix} is the installation prefix of Guix. If you installed Guix
+from source, make sure you checked the GPG signature of
@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
Then, you can run something like this:
@example
-# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
+# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
+# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
@end example
Once this is in place, the output of a command like @code{guix build}
@noindent
The text changed from ``The following derivations would be built'' to
``112.3 MB would be downloaded''. This indicates that substitutes from
-@code{@value{SUBSTITUTE-SERVER}} are usable and will be downloaded, when
-possible, for future builds.
+the configured substitute servers are usable and will be downloaded,
+when possible, for future builds.
@cindex substitutes, how to disable
The substitute mechanism can be disabled globally by running
As an example, suppose you want to fetch substitutes from
@code{guix.example.org} and to authorize the signing key of that server,
-in addition to the default @code{@value{SUBSTITUTE-SERVER}}. The
-resulting operating system configuration will look something like:
+in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system
+configuration will look something like:
@lisp
(operating-system
@code{guix-daemon --substitute-urls}}):
@example
-@dots{} --substitute-urls='https://guix.example.org https://@value{SUBSTITUTE-SERVER}'
+@dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
@end example
@item
@end enumerate
Now you're all set! Substitutes will be preferably taken from
-@code{https://guix.example.org}, using @code{@value{SUBSTITUTE-SERVER}}
-as a fallback. Of course you can list as many substitute servers as you
-like, with the caveat that substitute lookup can be slowed down if too
-many servers need to be contacted.
+@code{https://guix.example.org}, using
+@code{@value{SUBSTITUTE-SERVER-1}} then
+@code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you
+can list as many substitute servers as you like, with the caveat that
+substitute lookup can be slowed down if too many servers need to be
+contacted.
Note that there are also situations where one may want to add the URL of
a substitute server @emph{without} authorizing its key.
Today, each individual's control over their own computing is at the
mercy of institutions, corporations, and groups with enough power and
determination to subvert the computing infrastructure and exploit its
-weaknesses. While using @code{@value{SUBSTITUTE-SERVER}} substitutes can be
-convenient, we encourage users to also build on their own, or even run
-their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an
-interesting target. One way to help is by publishing the software you
-build using @command{guix publish} so that others have one more choice
-of server to download substitutes from (@pxref{Invoking guix publish}).
+weaknesses. While using substitutes can be convenient, we encourage
+users to also build on their own, or even run their own build farm, such
+that the project run substitute servers are less of an interesting
+target. One way to help is by publishing the software you build using
+@command{guix publish} so that others have one more choice of server to
+download substitutes from (@pxref{Invoking guix publish}).
Guix has the foundations to maximize build reproducibility
(@pxref{Features}). In most cases, independent builds of a given
low-level operation needed in only very narrow use cases; see below.
For example, the following command extracts the substitute for Emacs
-served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
+served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}:
@example
$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
+ https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
| gunzip | guix archive -x /tmp/emacs
@end example
@example
$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
+ https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
| lzip -d | guix archive -t
@end example
In other situations, it is more convenient to specify the list of
packages needed in the environment. For example, the following command
-runs @command{python} from an environment containing Python@tie{}2.7 and
+runs @command{python} from an environment containing Python@tie{}3 and
NumPy:
@example
-guix environment --ad-hoc python2-numpy python-2.7 -- python
+guix environment --ad-hoc python-numpy python -- python3
@end example
Furthermore, one might want the dependencies of a package and also some
their dependencies, you can run:
@example
-$ guix pack guile emacs geiser
+$ guix pack guile emacs emacs-geiser
@dots{}
/gnu/store/@dots{}-pack.tar.gz
@end example
@file{/opt/gnu/bin} symlink to the profile:
@example
-guix pack -S /opt/gnu/bin=bin guile emacs geiser
+guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser
@end example
@noindent
command:
@example
-guix pack -f squashfs bash guile emacs geiser
+guix pack -f squashfs bash guile emacs emacs-geiser
@end example
@noindent
run} and @command{singularity exec} will fail with an unhelpful ``no
such file or directory'' message.
@end quotation
+
+@item deb
+This produces a Debian archive (a package with the @samp{.deb} file
+extension) containing all the specified binaries and symbolic links,
+that can be installed on top of any dpkg-based GNU(/Linux) distribution.
+Advanced options can be revealed via the @option{--help-deb-format}
+option. They allow embedding control files for more fine-grained
+control, such as activating specific triggers or providing a maintainer
+configure script to run arbitrary setup code upon installation.
+
+@example
+guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello
+@end example
+
+@quotation Note
+Because archives produced with @command{guix pack} contain a collection
+of store items and because each @command{dpkg} package must not have
+conflicting files, in practice that means you likely won't be able to
+install more than one such archive on a given system.
+@end quotation
+
+@quotation Warning
+@command{dpkg} will assume ownership of any files contained in the pack
+that it does @emph{not} know about. It is unwise to install
+Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is
+shared by other software, such as a Guix installation or other, non-deb
+packs.
+@end quotation
+
@end table
@cindex relocatable binaries
"0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
(build-system gnu-build-system)
(arguments '(#:configure-flags '("--enable-silent-rules")))
- (inputs `(("gawk" ,gawk)))
+ (inputs (list gawk))
(synopsis "Hello, GNU world: An example GNU package")
(description "Guess what GNU Hello prints!")
(home-page "https://www.gnu.org/software/hello/")
@item
The @code{inputs} field specifies inputs to the build process---i.e.,
-build-time or run-time dependencies of the package. Here, we define an
-input called @code{"gawk"} whose value is that of the @code{gawk}
+build-time or run-time dependencies of the package. Here, we add
+an input, a reference to the @code{gawk}
variable; @code{gawk} is itself bound to a @code{<package>} object.
@cindex backquote (quasiquote)
The name of the package, as a string.
@item @code{version}
-The version of the package, as a string.
+The version of the package, as a string. @xref{Version Numbers}, for
+guidelines.
@item @code{source}
An object telling how the source code for the package should be
@itemx @code{native-inputs} (default: @code{'()})
@itemx @code{propagated-inputs} (default: @code{'()})
@cindex inputs, of packages
-These fields list dependencies of the package. Each one is a list of
-tuples, where each tuple has a label for the input (a string) as its
+These fields list dependencies of the package. Each element of these
+lists is either a package, origin, or other ``file-like object''
+(@pxref{G-Expressions}); to specify the output of that file-like object
+that should be used, pass a two-element list where the second element is
+the output (@pxref{Packages with Multiple Outputs}, for more on package
+outputs). For example, the list below specifies three inputs:
+
+@lisp
+(list libffi libunistring
+ `(,glib "bin")) ;the "bin" output of GLib
+@end lisp
+
+In the example above, the @code{"out"} output of @code{libffi} and
+@code{libunistring} is used.
+
+@quotation Compatibility Note
+Until version 1.3.0, input lists were a list of tuples,
+where each tuple has a label for the input (a string) as its
first element, a package, origin, or derivation as its second element,
and optionally the name of the output thereof that should be used, which
-defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
-more on package outputs). For example, the list below specifies three
-inputs:
+defaults to @code{"out"}. For example, the list below is equivalent to
+the one above, but using the @dfn{old input style}:
@lisp
+;; Old input style (deprecated).
`(("libffi" ,libffi)
("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
+ ("glib:bin" ,glib "bin")) ;the "bin" output of GLib
@end lisp
+This style is now deprecated; it is still supported but support will be
+removed in a future version. It should not be used for new package
+definitions. @xref{Invoking guix style}, on how to migrate to the new
+style.
+@end quotation
+
@cindex cross compilation, package dependencies
The distinction between @code{native-inputs} and @code{inputs} is
necessary when considering cross-compilation. When cross-compiling,
;; When cross-compiled, Guile, for example, depends on
;; a native version of itself. Add it here.
(native-inputs (if (%current-target-system)
- `(("self" ,this-package))
+ (list this-package)
'())))
@end lisp
It is an error to refer to @code{this-package} outside a package definition.
@end deffn
+The following helper procedures are provided to help deal with package
+inputs.
+
+@deffn {Scheme Procedure} lookup-package-input @var{package} @var{name}
+@deffnx {Scheme Procedure} lookup-package-native-input @var{package} @var{name}
+@deffnx {Scheme Procedure} lookup-package-propagated-input @var{package} @var{name}
+@deffnx {Scheme Procedure} lookup-package-direct-input @var{package} @var{name}
+Look up @var{name} among @var{package}'s inputs (or native, propagated,
+or direct inputs). Return it if found, @code{#f} otherwise.
+
+@var{name} is the name of a package depended on. Here's how you might
+use it:
+
+@lisp
+(use-modules (guix packages) (gnu packages base))
+
+(lookup-package-direct-input coreutils "gmp")
+@result{} #<package gmp@@6.2.1 @dots{}>
+@end lisp
+
+In this example we obtain the @code{gmp} package that is among the
+direct inputs of @code{coreutils}.
+@end deffn
+
Because packages are regular Scheme objects that capture a complete
dependency graph and associated build procedures, it is often useful to
write procedures that take a package and return a modified version
The URL of the Git repository to clone.
@item @code{commit}
-This string denotes either the commit to fetch (a hexadecimal string,
-either the full SHA1 commit or a ``short'' commit string; the latter is
-not recommended) or the tag to fetch.
+This string denotes either the commit to fetch (a hexadecimal string),
+or the tag to fetch. You can also use a ``short'' commit ID or a
+@command{git describe} style identifier such as
+@code{v1.0.1-10-g58d7909c97}.
@item @code{recursive?} (default: @code{#f})
This Boolean indicates whether to recursively fetch Git sub-modules.
dependency like so:
@lisp
-(use-modules (gnu packages gdb) ;for 'gdb'
- (srfi srfi-1)) ;for 'alist-delete'
+(use-modules (gnu packages gdb)) ;for 'gdb'
(define gdb-sans-guile
(package
(inherit gdb)
- (inputs (alist-delete "guile"
- (package-inputs gdb)))))
+ (inputs (modify-inputs (package-inputs gdb)
+ (delete "guile")))))
@end lisp
-The @code{alist-delete} call above removes the tuple from the
-@code{inputs} field that has @code{"guile"} as its first element
-(@pxref{SRFI-1 Association Lists,,, guile, GNU Guile Reference
-Manual}).
+The @code{modify-inputs} form above removes the @code{"guile"} package
+from the @code{inputs} field of @code{gdb}. The @code{modify-inputs}
+macro is a helper that can prove useful anytime you want to remove, add,
+or replace package inputs.
+
+@deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses}
+Modify the given package inputs, as returned by @code{package-inputs} & co.,
+according to the given clauses. The example below removes the GMP and ACL
+inputs of Coreutils and adds libcap to the back of the input list:
+
+@lisp
+(modify-inputs (package-inputs coreutils)
+ (delete "gmp" "acl")
+ (append libcap))
+@end lisp
+
+The example below replaces the @code{guile} package from the inputs of
+@code{guile-redis} with @code{guile-2.2}:
+
+@lisp
+(modify-inputs (package-inputs guile-redis)
+ (replace "guile" guile-2.2))
+@end lisp
+
+The last type of clause is @code{prepend}, to add inputs to the front of
+the list.
+@end deffn
In some cases, you may find it useful to write functions
(``procedures'', in Scheme parlance) that return a package based on some
(name name)
(version "3.0")
;; several fields omitted
- (inputs
- `(("lua" ,lua)))
+ (inputs (list lua))
(synopsis "Socket library for Lua")))
(define-public lua5.1-socket
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
+libraries needed by an ELF binary, 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''
is useful when a package contains multiple packages and you want to build
only one of them. This is equivalent to passing the @code{-p} argument to
@code{dune}.
+
@end defvr
@defvr {Scheme Variable} go-build-system
the built output. The key @code{#:install-source?}, which defaults to
@code{#t}, controls whether or not the source code is installed. It can
be set to @code{#f} for packages that only provide executable files.
+
+Packages can be cross-built, and if a specific architecture or operating
+system is desired then the keywords @code{#:goarch} and @code{#:goos}
+can be used to force the package to be built for that architecture and
+operating system. The combinations known to Go can be found
+@url{"https://golang.org/doc/install/source#environment", in their
+documentation}.
@end defvr
@defvr {Scheme Variable} glib-or-gtk-build-system
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}
helps creating the file. You need to pass the outputs and the source of the
-package, it's name (the same as the @code{file-name} parameter), the package
+package, its name (the same as the @code{file-name} parameter), the package
uuid, the package version, and a list of dependencies specified by their name
and their uuid.
@end defvr
also exported.
@end defvr
+@defvr {Scheme Variable} minetest-mod-build-system
+This variable is exported by @code{(guix build-system minetest)}. It
+implements a build procedure for @uref{https://www.minetest.net, Minetest}
+mods, which consists of copying Lua code, images and other resources to
+the location Minetest searches for mods. The build system also minimises
+PNG images and verifies that Minetest can load the mod without errors.
+@end defvr
+
@defvr {Scheme Variable} minify-build-system
This variable is exported by @code{(guix build-system minify)}. It
implements a minification procedure for simple JavaScript packages.
then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
For packages that install stand-alone Python programs under @code{bin/},
-it takes care of wrapping these programs so that their @env{PYTHONPATH}
-environment variable points to all the Python libraries they depend on.
+it takes care of wrapping these programs so that their
+@env{GUIX_PYTHONPATH} environment variable points to all the Python
+libraries they depend on.
Which Python package is used to perform the build can be specified with
the @code{#:python} parameter. This is a useful way to force a package
@code{setuptools}, much like @command{pip} does. Some packages are not
compatible with setuptools (and pip), thus you can disable this by
setting the @code{#:use-setuptools?} parameter to @code{#f}.
+
+If a @code{"python"} output is available, the package is installed into it
+instead of the default @code{"out"} output. This is useful for packages that
+include a Python package as only a part of the software, and thus want to
+combine the phases of @code{python-build-system} with another build system.
+Python bindings are a common usecase.
+
@end defvr
@defvr {Scheme Variable} perl-build-system
It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
of inputs, and they can be changed with the parameters @code{#:meson}
-and @code{#:ninja} if needed. The default Meson is
-@code{meson-for-build}, which is special because it doesn't clear the
-@code{RUNPATH} of binaries and libraries when they are installed.
+and @code{#:ninja} if needed.
This build system is an extension of @code{gnu-build-system}, but with the
following phases changed to some specific for Meson:
@item fix-runpath
This phase ensures that all binaries can find the libraries they need.
-It searches for required libraries in subdirectories of the package being
-built, and adds those to @code{RUNPATH} where needed. It also removes
-references to libraries left over from the build phase by
-@code{meson-for-build}, such as test dependencies, that aren't actually
-required for the program to run.
+It searches for required libraries in subdirectories of the package
+being built, and adds those to @code{RUNPATH} where needed. It also
+removes references to libraries left over from the build phase by
+@code{meson}, such as test dependencies, that aren't actually required
+for the program to run.
@item glib-or-gtk-wrap
This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
@end deffn
@deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
- [#:log (current-output-port)] [#:follow-symlinks? #f] [#:keep-mtime? #f]
+ [#:log (current-output-port)] [#:follow-symlinks? #f] @
+ [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
Copy @var{source} directory to @var{destination}. Follow symlinks if
-@var{follow-symlinks?} is true; otherwise, just preserve them. When
-@var{keep-mtime?} is true, keep the modification time of the files in
-@var{source} on those of @var{destination}. Write verbose output to the
-@var{log} port.
+@var{follow-symlinks?} is true; otherwise, just preserve them. Call
+@var{copy-file} to copy regular files. When @var{keep-mtime?} is true,
+keep the modification time of the files in @var{source} on those of
+@var{destination}. When @var{keep-permissions?} is true, preserve file
+permissions. Write verbose output to the @var{log} port.
@end deffn
@deffn {Scheme Procedure} delete-file-recursively @var{dir} @
@code{$PATH}, or @code{#f} if @var{program} could not be found.
@end deffn
+@deffn {Scheme Procedure} search-input-file @var{inputs} @var{name}
+@deffnx {Scheme Procedure} search-input-directory @var{inputs} @var{name}
+Return the complete file name for @var{name} as found in @var{inputs};
+@code{search-input-file} searches for a regular file and
+@code{search-input-directory} searches for a directory. If @var{name}
+could not be found, an exception is raised.
+
+Here, @var{inputs} must be an association list like @code{inputs} and
+@code{native-inputs} as available to build phases (@pxref{Build
+Phases}).
+@end deffn
+
+Here is a (simplified) example of how @code{search-input-file} is used
+in a build phase of the @code{wireguard-tools} package:
+
+@lisp
+(add-after 'install 'wrap-wg-quick
+ (lambda* (#:key inputs outputs #:allow-other-keys)
+ (let ((coreutils (string-append (assoc-ref inputs "coreutils")
+ "/bin")))
+ (wrap-program (search-input-file outputs "bin/wg-quick")
+ #:sh (search-input-file inputs "bin/bash")
+ `("PATH" ":" prefix ,(list coreutils))))))
+@end lisp
+
@subsection Build Phases
@cindex build phases
has an associated gexp compiler, such as a @code{<package>}.
@end deffn
+@deffn {Procedure} gexp->approximate-sexp @var{gexp}
+Sometimes, it may be useful to convert a G-exp into a S-exp. For
+example, some linters (@pxref{Invoking guix lint}) peek into the build
+phases of a package to detect potential problems. This conversion can
+be achieved with this procedure. However, some information can be lost
+in the process. More specifically, lowerable objects will be silently
+replaced with some arbitrary object -- currently the list
+@code{(*approximate*)}, but this may change.
+@end deffn
+
@node Invoking guix repl
@section Invoking @command{guix repl}
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
+* Invoking guix style:: Styling package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix size:: Profiling disk usage.
* Invoking guix graph:: Visualizing the graph of packages.
@example
guix build --quiet --keep-going \
- $(guix package -A | cut -f1,2 --output-delimiter=@@)
+ $(guix package -A | awk '@{ print $1 "@@" $2 @}')
@end example
@var{package-or-derivation} may be either the name of a package found in
@item --with-commit=@var{package}=@var{commit}
This is similar to @option{--with-branch}, except that it builds from
@var{commit} rather than the tip of a branch. @var{commit} must be a valid
-Git commit SHA1 identifier or a tag.
+Git commit SHA1 identifier, a tag, or a @command{git describe} style
+identifier such as @code{1.0-3-gabc123}.
@item --with-patch=@var{package}=@var{file}
Add @var{file} to the list of patches applied to @var{package}, where
@example
$ guix build --log-file gdb -s aarch64-linux
-https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
+https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
@end example
You can freely access a huge library of build logs!
in Guix.
@end table
+@item minetest
+@cindex minetest
+@cindex ContentDB
+Import metadata from @uref{https://content.minetest.net, ContentDB}.
+Information is taken from the JSON-formatted metadata provided through
+@uref{https://content.minetest.net/help/api/, ContentDB's API} and
+includes most relevant information, including dependencies. There are
+some caveats, however. The license information is often incomplete.
+The commit hash is sometimes missing. The descriptions are in the
+Markdown format, but Guix uses Texinfo instead. Texture packs and
+subgames are unsupported.
+
+The command below imports metadata for the Mesecons mod by Jeija:
+
+@example
+guix import minetest Jeija/mesecons
+@end example
+
+The author name can also be left out:
+
+@example
+guix import minetest mesecons
+@end example
+
+@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.
+@end table
+
@item cpan
@cindex CPAN
Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
@code{emacs} package (@pxref{Package Installation, ELPA package
signatures,, emacs, The GNU Emacs Manual}).
+@item
+@uref{https://elpa.nongnu.org/nongnu/, NonGNU}, selected by the
+@code{nongnu} identifier.
+
@item
@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
@code{melpa-stable} identifier.
and generate package expressions for all those packages that are not yet
in Guix.
@item --repo
-Select the given repository (a repository name). Possible values include:
+By default, packages are searched in the official OPAM repository. This
+option, which can be used more than once, lets you add other repositories
+which will be searched for packages. It accepts as valid arguments:
+
@itemize
-@item @code{opam}, the default opam repository,
-@item @code{coq} or @code{coq-released}, the stable repository for coq packages,
-@item @code{coq-core-dev}, the repository that contains development versions of coq,
-@item @code{coq-extra-dev}, the repository that contains development versions
- of coq packages.
+@item the name of a known repository - can be one of @code{opam},
+ @code{coq} (equivalent to @code{coq-released}),
+ @code{coq-core-dev}, @code{coq-extra-dev} or @code{grew}.
+@item the URL of a repository as expected by the
+ @code{opam repository add} command (for instance, the URL equivalent
+ of the above @code{opam} name would be
+ @uref{https://opam.ocaml.org}).
+@item the path to a local copy of a repository (a directory containing a
+ @file{packages/} sub-directory).
@end itemize
+
+Repositories are assumed to be passed to this option by order of
+preference. The additional repositories will not replace the default
+@code{opam} repository, which is always kept as a fallback.
+
+Also, please note that versions are not compared accross repositories.
+The first repository (from left to right) that has at least one version
+of a given package will prevail over any others, and the version
+imported will be the latest one found @emph{in this repository only}.
+
@end table
@item go
version to its name, so that multiple versions of the same package can
coexist.
@end table
+
+@item egg
+@cindex egg
+Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.
+The information is taken from @file{PACKAGE.egg} files found in the
+@uref{git://code.call-cc.org/eggs-5-latest, eggs-5-latest} Git
+repository. However, it does not provide all the information that we
+need, there is no ``description'' field, and the licenses used are not
+always precise (BSD is often used instead of BSD-N).
+
+@example
+guix import egg sourcehut
+@end example
+
+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.
+@end table
@end table
The structure of the @command{guix import} code is modular. It would be
the updater for X.org packages;
@item kernel.org
the updater for packages hosted on kernel.org;
+@item egg
+the updater for @uref{https://wiki.call-cc.org/eggs/, Egg} packages;
@item elpa
the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
@item cran
@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
-hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
+hop@@2.4.0 emacs-geiser@@0.13 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
@end example
The command above lists a set of packages that could be built to check
otherwise.
+@node Invoking guix style
+@section Invoking @command{guix style}
+
+The @command{guix style} command helps packagers style their package
+definitions according to the latest fashionable trends. The command
+currently focuses on one aspect: the style of package inputs. It may
+eventually be extended to handle other stylistic matters.
+
+The way package inputs are written is going through a transition
+(@pxref{package Reference}, for more on package inputs). Until version
+1.3.0, package inputs were written using the ``old style'', where each
+input was given an explicit label, most of the time the package name:
+
+@lisp
+(package
+ ;; @dots{}
+ ;; The "old style" (deprecated).
+ (inputs `(("libunistring" ,libunistring)
+ ("libffi" ,libffi))))
+@end lisp
+
+Today, the old style is deprecated and the preferred style looks like
+this:
+
+@lisp
+(package
+ ;; @dots{}
+ ;; The "new style".
+ (inputs (list libunistring libffi)))
+@end lisp
+
+Likewise, uses of @code{alist-delete} and friends to manipulate inputs
+is now deprecated in favor of @code{modify-inputs} (@pxref{Defining
+Package Variants}, for more info on @code{modify-inputs}).
+
+In the vast majority of cases, this is a purely mechanical change on the
+surface syntax that does not even incur a package rebuild. Running
+@command{guix style} can do that for you, whether you're working on
+packages in Guix proper or in an external channel.
+
+The general syntax is:
+
+@example
+guix style [@var{options}] @var{package}@dots{}
+@end example
+
+This causes @command{guix style} to analyze and rewrite the definition
+of @var{package}@dots{}. It does so in a conservative way: preserving
+comments and bailing out if it cannot make sense of the code that
+appears in an inputs field. The available options are listed below.
+
+@table @code
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Style the package @var{expr} evaluates to.
+
+For example, running:
+
+@example
+guix style -e '(@@ (gnu packages gcc) gcc-5)'
+@end example
+
+styles the @code{gcc-5} package definition.
+
+@item --input-simplification=@var{policy}
+Specify the package input simplification policy for cases where an input
+label does not match the corresponding package name. @var{policy} may
+be one of the following:
+
+@table @code
+@item silent
+Simplify inputs only when the change is ``silent'', meaning that the
+package does not need to be rebuilt (its derivation is unchanged).
+
+@item safe
+Simplify inputs only when that is ``safe'' to do: the package might need
+to be rebuilt, but the change is known to have no observable effect.
+
+@item always
+Simplify inputs even when input labels do not match package names, and
+even if that might have an observable effect.
+@end table
+
+The default is @code{silent}, meaning that input simplifications do not
+trigger any package rebuild.
+@end table
+
@node Invoking guix lint
@section Invoking @command{guix lint}
@item formatting
Warn about obvious source code formatting issues: trailing white space,
use of tabulations, etc.
+
+@item input-labels
+Report old-style input labels that do not match the name of the
+corresponding package. This aims to help migrate from the ``old input
+style''. @xref{package Reference}, for more information on package
+inputs and input styles. @xref{Invoking guix style}, on how to migrate
+to the new style.
@end table
The general syntax is:
anyone with network access to obtain substitutes from it. This means
that any machine running Guix can also act as if it were a build farm,
since the HTTP interface is compatible with Cuirass, the software behind
-the @code{@value{SUBSTITUTE-SERVER}} build farm.
+the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (@pxref{Substitutes}). Because
not been accessed for @var{ttl} and that no longer have a corresponding
item in the store, may be deleted.
+@item --negative-ttl=@var{ttl}
+Similarly produce @code{Cache-Control} HTTP headers to advertise the
+time-to-live (TTL) of @emph{negative} lookups---missing store items, for
+which the HTTP 404 code is returned. By default, no negative TTL is
+advertised.
+
+This parameter can help adjust server load and substitute latency by
+instructing cooperating clients to be more or less patient when a store
+item is missing.
+
@item --cache-bypass-threshold=@var{size}
When used in conjunction with @option{--cache}, store items smaller than
@var{size} are immediately available, even when they are not yet in
The command output looks like this:
@smallexample
-$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
-updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0%
+$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
+updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
updating list of substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
+ https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
differing files:
/lib/libcrypto.so.1.1
/gnu/store/@dots{}-git-2.5.0 contents differ:
local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
+ https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
differing file:
/libexec/git-core/git-fsck
/gnu/store/@dots{}-pius-2.1.1 contents differ:
local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
+ https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
differing file:
/share/man/man1/pius.1.gz
@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
-Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the
+Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds, except in the
case of Git. This might indicate that the build process of Git is
non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
@example
guix challenge git \
--diff=diffoscope \
- --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
+ --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
@end example
This automatically invokes @command{diffoscope}, which displays detailed
archive}):
@example
-$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-git-2.5.0 \
+$ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
| lzip -d | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
@end example
This command shows the difference between the files resulting from the
local build, and the files resulting from the build on
-@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,,
+@code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging Files,,
diffutils, Comparing and Merging Files}). The @command{diff} command
works great for text files. When binary files differ, a better option
is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
the problem.
If you are writing packages for Guix, you are encouraged to check
-whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the
+whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
same build result as you did with:
@example
@var{b} usually lacks substitutes as well. The result looks like this:
@example
-$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10
+$ guix weather --substitute-urls=@value{SUBSTITUTE-URLS} -c 10
computing 8,983 package derivations for x86_64-linux...
-looking for 9,343 store items on @value{SUBSTITUTE-URL}...
-updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
-@value{SUBSTITUTE-URL}
+looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
+updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
+@value{SUBSTITUTE-URLS}
64.7% substitutes available (6,047 out of 9,343)
@dots{}
-2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which:
+2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
What this example shows is that @code{kcoreaddons} and presumably the 58
packages that depend on it have no substitutes at
-@code{@value{SUBSTITUTE-SERVER}}; likewise for @code{qgpgme} and the 46
+@code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
packages that depend on it.
If you are a Guix developer, or if you are taking care of this build farm,
@lisp
(bootloader-configuration
(bootloader grub-efi-bootloader)
- (target "/boot/efi"))
+ (targets '("/boot/efi")))
@end lisp
@xref{Bootloader Configuration}, for more information on the available
(@pxref{Invoking guix package}). The @code{%base-packages} variable
provides all the tools one would expect for basic user and administrator
tasks---including the GNU Core Utilities, the GNU Networking Utilities,
-the GNU Zile lightweight text editor, @command{find}, @command{grep},
+the @command{mg} lightweight text editor, @command{find}, @command{grep},
etc. The example above adds GNU@tie{}Screen to those,
taken from the @code{(gnu packages screen)}
module (@pxref{Package Modules}). The
(operating-system
;; ...
- (packages (cons (list bind "utils")
+ (packages (cons (list isc-bind "utils")
%base-packages)))
@end lisp
@findex specification->package
-Referring to packages by variable name, like @code{bind} above, has
+Referring to packages by variable name, like @code{isc-bind} above, has
the advantage of being unambiguous; it also allows typos and such to be
diagnosed right away as ``unbound variables''. The downside is that one
needs to know which module defines which package, and to augment the
customize them. To do this, use @code{modify-services} (@pxref{Service
Reference, @code{modify-services}}) to modify the list.
-For example, suppose you want to modify @code{guix-daemon} and Mingetty
-(the console log-in) in the @code{%base-services} list (@pxref{Base
-Services, @code{%base-services}}). To do that, you can write the
-following in your operating system declaration:
+@anchor{auto-login to TTY} For example, suppose you want to modify
+@code{guix-daemon} and Mingetty (the console log-in) in the
+@code{%base-services} list (@pxref{Base Services,
+@code{%base-services}}). To do that, you can write the following in
+your operating system declaration:
@lisp
(define %my-services
This changes the configuration---i.e., the service parameters---of the
@code{guix-service-type} instance, and that of all the
-@code{mingetty-service-type} instances in the @code{%base-services} list.
+@code{mingetty-service-type} instances in the @code{%base-services} list
+(@pxref{Auto-Login to a Specific TTY, see the cookbook for how to
+auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).
Observe how this is accomplished: first, we arrange for the original
configuration to be bound to the identifier @code{config} in the
@var{body}, and then we write the @var{body} so that it evaluates to the
@c FIXME: Add xref to PAM services section.
@item @code{setuid-programs} (default: @code{%setuid-programs})
-List of string-valued G-expressions denoting setuid programs.
-@xref{Setuid Programs}.
+List of @code{<setuid-program>}. @xref{Setuid Programs}, for more
+information.
@item @code{sudoers-file} (default: @code{%sudoers-specification})
@cindex sudoers file
(keyboard-layout (keyboard-layout "tr")) ;for the console
(bootloader (bootloader-configuration
(bootloader grub-efi-bootloader)
- (target "/boot/efi")
+ (targets '("/boot/efi"))
(keyboard-layout keyboard-layout))) ;for GRUB
(services (cons (set-xorg-configuration
(xorg-configuration ;for Xorg
@item @code{font-size} (default: @code{12})
Font size used in Kmscon.
+@item @code{keyboard-layout} (default: @code{#f})
+If this is @code{#f}, Kmscon uses the default keyboard layout---usually US
+English (``qwerty'') for a 105-key PC keyboard.
+
+Otherwise this must be a @code{keyboard-layout} object specifying the
+keyboard layout. @xref{Keyboard Layout}, for more information on how to
+specify the keyboard layout.
+
@item @code{kmscon} (default: @var{kmscon})
The Kmscon package to use.
@item @code{authorize-key?} (default: @code{#t})
@cindex substitutes, authorization thereof
Whether to authorize the substitute keys listed in
-@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}}
+@code{authorized-keys}---by default that of
+@code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}}
(@pxref{Substitutes}).
When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
@item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
The list of authorized key files for archive imports, as a list of
string-valued gexps (@pxref{Invoking guix archive}). By default, it
-contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}).
-See @code{substitute-urls} below for an example on how to change it.
+contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}). See
+@code{substitute-urls} below for an example on how to change it.
@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.
The list of URLs where to look for substitutes by default.
Suppose you would like to fetch substitutes from @code{guix.example.org}
-in addition to @code{@value{SUBSTITUTE-SERVER}}. You will need to do
+in addition to @code{@value{SUBSTITUTE-SERVER-1}}. You will need to do
two things: (1) add @code{guix.example.org} to @code{substitute-urls},
and (2) authorize its signing key, having done appropriate checks
(@pxref{Substitute Server Authorization}). The configuration below does
(lambda ()
(execl (string-append #$findutils "/bin/updatedb")
"updatedb"
- "--prunepaths=/tmp /var/tmp /gnu/store"))))
+ "--prunepaths=/tmp /var/tmp /gnu/store"))
+ "updatedb"))
(define garbage-collector-job
;; Collect garbage 5 minutes after midnight every day.
%base-services)))
@end lisp
+@quotation Tip
+When providing the action of a job specification as a procedure, you
+should provide an explicit name for the job via the optional 3rd
+argument as done in the @code{updatedb-job} example above. Otherwise,
+the job would appear as ``Lambda function'' in the output of
+@command{herd schedule mcron}, which is not nearly descriptive enough!
+@end quotation
+
For more complex jobs defined in Scheme where you need control over the top
level, for instance to introduce a @code{use-modules} form, you can move your
code to a separate program using the @code{program-file} procedure of the
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
+-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-port-unreachable
COMMIT
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
+-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp6-port-unreachable
COMMIT
detailed discussion of each configuration field.
@end deftp
+@cindex opendht, distributed hash table network service
+@cindex dhtproxy, for use with jami
+@defvr {Scheme Variable} opendht-service-type
+This is the type of the service running a @uref{https://opendht.net,
+OpenDHT} node, @command{dhtnode}. The daemon can be used to host your
+own proxy service to the distributed hash table (DHT), for example to
+connect to with Jami, among other applications.
+
+@quotation Important
+When using the OpenDHT proxy server, the IP addresses it ``sees'' from
+the clients should be addresses reachable from other peers. In practice
+this means that a publicly reachable address is best suited for a proxy
+server, outside of your private network. For example, hosting the proxy
+server on a IPv4 private local network and exposing it via port
+forwarding could work for external peers, but peers local to the proxy
+would have their private addresses shared with the external peers,
+leading to connectivity problems.
+@end quotation
+
+The value of this service is a @code{opendht-configuration} object, as
+described below.
+@end defvr
+
+@deftp {Data Type} opendht-configuration
+This is the data type for the OpenDHT service configuration.
+
+@c The fields documentation has been auto-generated using the
+@c configuration->documentation procedure from
+@c (gnu services configuration).
+Available @code{opendht-configuration} fields are:
+
+@deftypevr {@code{opendht-configuration} parameter} package opendht
+The @code{opendht} package to use.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} boolean peer-discovery?
+Whether to enable the multicast local peer discovery mechanism.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} boolean enable-logging?
+Whether to enable logging messages to syslog. It is disabled by default
+as it is rather verbose.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} boolean debug?
+Whether to enable debug-level logging messages. This has no effect if
+logging is disabled.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-string bootstrap-host
+The node host name that is used to make the first connection to the
+network. A specific port value can be provided by appending the
+@code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
+any host can be specified here. It's also possible to disable
+bootsrapping by setting this to the @code{'disabled} symbol.
+
+Defaults to @samp{"bootstrap.jami.net:4222"}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-number port
+The UDP port to bind to. When set to @code{'disabled}, an available
+port is automatically selected.
+
+Defaults to @samp{4222}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port
+Spawn a proxy server listening on the specified port.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port-tls
+Spawn a proxy server listening to TLS connections on the specified port.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+@end deftp
+
@cindex Tor
@defvr {Scheme Variable} tor-service-type
This is the type for a service that runs the @uref{https://torproject.org,
(service openssh-service-type
(openssh-configuration
(x11-forwarding? #t)
- (permit-root-login 'without-password)
+ (permit-root-login 'prohibit-password)
(authorized-keys
`(("alice" ,(local-file "alice.pub"))
("bob" ,(local-file "bob.pub"))))))
@item @code{permit-root-login} (default: @code{#f})
This field determines whether and when to allow logins as root. If
@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
-If it's the symbol @code{'without-password}, then root logins are
+If it's the symbol @code{'prohibit-password}, then root logins are
permitted but not with password-based authentication.
@item @code{allow-empty-passwords?} (default: @code{#f})
@item @code{allow-empty-passwords?} (default: @code{#t})
Whether to allow logins with empty passwords.
+@item @code{gnupg?} (default: @code{#f})
+If enabled, @code{pam-gnupg} will attempt to automatically unlock the
+user's GPG keys with the login password via @code{gpg-agent}. The
+keygrips of all keys to be unlocked should be written to
+@file{~/.pam-gnupg}, and can be queried with @code{gpg -K
+--with-keygrip}. Presetting passphrases must be enabled by adding
+@code{allow-preset-passphrase} in @file{~/.gnupg/gpg-agent.conf}.
+
@item @code{auto-login?} (default: @code{#f})
@itemx @code{default-user} (default: @code{""})
When @code{auto-login?} is false, SLiM presents a log-in screen.
Defaults to @samp{"lp"}.
@end deftypevr
+@deftypevr {@code{files-configuration} parameter} string log-file-group
+Specifies the group name or ID that will be used for log files.
+
+Defaults to @samp{"lpadmin"}.
+@end deftypevr
+
@deftypevr {@code{files-configuration} parameter} string log-file-perm
Specifies the permissions for all log files that the scheduler writes.
Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
-Specifies how long an idle client connection remains open, in seconds.
-
-Defaults to @samp{30}.
-@end deftypevr
-
@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
Specifies the maximum size of print files, IPP requests, and HTML form
data. A limit of 0 disables the limit check.
to the printer's requesting-user-name-allowed or
requesting-user-name-denied values. @code{@@OWNER} maps to the job's
owner. @code{@@SYSTEM} maps to the groups listed for the
-@code{system-group} field of the @code{files-config} configuration,
+@code{system-group} field of the @code{files-configuration},
which is reified into the @code{cups-files.conf(5)} file. Other
possible elements of the access list include specific user names, and
@code{@@@var{group}} to indicate members of a specific group. The
@code{@@ACL} maps to the printer's requesting-user-name-allowed or
requesting-user-name-denied values. @code{@@OWNER} maps to the job's
owner. @code{@@SYSTEM} maps to the groups listed for the
-@code{system-group} field of the @code{files-config} configuration,
+@code{system-group} field of the @code{files-configuration},
which is reified into the @code{cups-files.conf(5)} file. Other
possible elements of the access list include specific user names, and
@code{@@@var{group}} to indicate members of a specific group. The
@end deftp
@deffn {Scheme Variable} lxqt-desktop-service-type
-This is the type of the service that runs the @uref{https://lxqt.github.io,
+This is the type of the service that runs the @uref{https://lxqt-project.org,
LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
object (see below).
If set to @samp{0}, getmail will only print warnings and errors. A
value of @samp{1} means that messages will be printed about retrieving
and deleting messages. If set to @samp{2}, getmail will print messages
-about each of it's actions.
+about each of its actions.
Defaults to @samp{1}.
@node Telephony Services
@subsection Telephony Services
+@cindex telephony, services
+The @code{(gnu services telephony)} module contains Guix service
+definitions for telephony services. Currently it provides the following
+services:
+
+@subsubheading Jami
+
+@cindex jami, service
+
+This section describes how to configure a Jami server that can be used
+to host video (or audio) conferences, among other uses. The following
+example demonstrates how to specify Jami account archives (backups) to
+be provisioned automatically:
+
+@lisp
+(service jami-service-type
+ (jami-configuration
+ (accounts
+ (list (jami-account
+ (archive "/etc/jami/unencrypted-account-1.gz"))
+ (jami-account
+ (archive "/etc/jami/unencrypted-account-2.gz"))))))
+@end lisp
+
+When the accounts field is specified, the Jami account files of the
+service found under @file{/var/lib/jami} are recreated every time the
+service starts.
+
+Jami accounts and their corresponding backup archives can be generated
+using either the @code{jami-qt} or @code{jami-gnome} Jami clients. The
+accounts should not be password-protected, but it is wise to ensure
+their files are only readable by @samp{root}.
+
+The next example shows how to declare that only some contacts should be
+allowed to communicate with a given account:
+
+@lisp
+(service jami-service-type
+ (jami-configuration
+ (accounts
+ (list (jami-account
+ (archive "/etc/jami/unencrypted-account-1.gz")
+ (peer-discovery? #t)
+ (rendezvous-point? #t)
+ (allowed-contacts
+ '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
+ "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
+@end lisp
+
+In this mode, only the declared @code{allowed-contacts} can initiate
+communication with the Jami account. This can be used, for example,
+with rendezvous point accounts to create a private video conferencing
+space.
+
+To put the system administrator in full control of the conferences
+hosted on their system, the Jami service supports the following actions:
+
+@example sh
+# herd doc jami list-actions
+(list-accounts
+ list-account-details
+ list-banned-contacts
+ list-contacts
+ list-moderators
+ add-moderator
+ ban-contact
+ enable-account
+ disable-account)
+@end example
+
+The above actions aim to provide the most valuable actions for
+moderation purposes, not to cover the whole Jami API. Users wanting to
+interact with the Jami daemon from Guile may be interested in
+experimenting with the @code{(gnu build jami-service)} module, which
+powers the above Shepherd actions.
+
+@c TODO: This should be auto-generated from the doc already defined on
+@c the shepherd-actions themselves in (gnu services telephony).
+The @code{add-moderator} and @code{ban-contact} actions accept a contact
+@emph{fingerprint} (40 characters long hash) as first argument and an
+account fingerprint or username as second argument:
+
+@example sh
+# herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
+ f3345f2775ddfe07a4b0d95daea111d15fbc1199
+
+# herd list-moderators jami
+Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
+ - 1dbcb0f5f37324228235564b79f2b9737e9a008f
+
+@end example
+
+In the case of @code{ban-contact}, the second username argument is
+optional; when omitted, the account is banned from all Jami accounts:
+
+@example sh
+# herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f
+
+# herd list-banned-contacts jami
+Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
+ - 1dbcb0f5f37324228235564b79f2b9737e9a008f
+
+@end example
+
+Banned contacts are also stripped from their moderation privileges.
+
+The @code{disable-account} action allows to completely disconnect an
+account from the network, making it unreachable, while
+@code{enable-account} does the inverse. They accept a single account
+username or fingerprint as first argument:
+
+@example sh
+# herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199
+
+# herd list-accounts jami
+The following Jami accounts are available:
+ - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]
+
+@end example
+
+The @code{list-account-details} action prints the detailed parameters of
+each accounts in the Recutils format, which means the @command{recsel}
+command can be used to select accounts of interest (@pxref{Selection
+Expressions,,,recutils, GNU recutils manual}). Note that period
+characters (@samp{.}) found in the account parameter keys are mapped to
+underscores (@samp{_}) in the output, to meet the requirements of the
+Recutils format. The following example shows how to print the account
+fingerprints for all accounts operating in the rendezvous point mode:
+
+@example sh
+# herd list-account-details jami | \
+ recsel -p Account.username -e 'Account.rendezVous ~ "true"'
+Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
+@end example
+
+The remaining actions should be self-explanatory.
+
+The complete set of available configuration options is detailed below.
+
+@c TODO: Ideally, the following fragments would be auto-generated at
+@c build time, so that they needn't be manually duplicated.
+@c Auto-generated via (configuration->documentation 'jami-configuration)
+@deftp {Data Type} jami-configuration
+Available @code{jami-configuration} fields are:
+
+@table @asis
+@item @code{jamid} (default: @code{libring}) (type: package)
+The Jami daemon package to use.
+
+@item @code{dbus} (default: @code{dbus}) (type: package)
+The D-Bus package to use to start the required D-Bus session.
+
+@item @code{nss-certs} (default: @code{nss-certs}) (type: package)
+The nss-certs package to use to provide TLS certificates.
+
+@item @code{enable-logging?} (default: @code{#t}) (type: boolean)
+Whether to enable logging to syslog.
+
+@item @code{debug?} (default: @code{#f}) (type: boolean)
+Whether to enable debug level messages.
+
+@item @code{auto-answer?} (default: @code{#f}) (type: boolean)
+Whether to force automatic answer to incoming calls.
+
+@item @code{accounts} (default: @code{disabled}) (type: maybe-jami-account-list)
+A list of Jami accounts to be (re-)provisioned every time the Jami
+daemon service starts. When providing this field, the account
+directories under @file{/var/lib/jami/} are recreated every time the
+service starts, ensuring a consistent state.
+
+@end table
+
+@end deftp
+
+@c Auto-generated via (configuration->documentation 'jami-account)
+@deftp {Data Type} jami-account
+Available @code{jami-account} fields are:
+
+@table @asis
+@item @code{archive} (type: string-or-computed-file)
+The account archive (backup) file name of the account. This is used to
+provision the account when the service starts. The account archive
+should @emph{not} be encrypted. It is highly recommended to make it
+readable only to the @samp{root} user (i.e., not in the store), to guard
+against leaking the secret key material of the Jami account it contains.
+
+@item @code{allowed-contacts} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
+The list of allowed contacts for the account, entered as their 40
+characters long fingerprint. Messages or calls from accounts not in
+that list will be rejected. When unspecified, the configuration of the
+account archive is used as-is with respect to contacts and public
+inbound calls/messaging allowance, which typically defaults to allow any
+contact to communicate with the account.
+
+@item @code{moderators} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
+The list of contacts that should have moderation privileges (to ban,
+mute, etc. other users) in rendezvous conferences, entered as their 40
+characters long fingerprint. When unspecified, the configuration of the
+account archive is used as-is with respect to moderation, which
+typically defaults to allow anyone to moderate.
+
+@item @code{rendezvous-point?} (default: @code{disabled}) (type: maybe-boolean)
+Whether the account should operate in the rendezvous mode. In this
+mode, all the incoming audio/video calls are mixed into a conference.
+When left unspecified, the value from the account archive prevails.
+
+@item @code{peer-discovery?} (default: @code{disabled}) (type: maybe-boolean)
+Whether peer discovery should be enabled. Peer discovery is used to
+discover other OpenDHT nodes on the local network, which can be useful
+to maintain communication between devices on such network even when the
+connection to the the Internet has been lost. When left unspecified,
+the value from the account archive prevails.
+
+@item @code{bootstrap-hostnames} (default: @code{disabled}) (type: maybe-string-list)
+A list of hostnames or IPs pointing to OpenDHT nodes, that should be
+used to initially join the OpenDHT network. When left unspecified, the
+value from the account archive prevails.
+
+@item @code{name-server-uri} (default: @code{disabled}) (type: maybe-string)
+The URI of the name server to use, that can be used to retrieve the
+account fingerprint for a registered username.
+
+@end table
+
+@end deftp
+
+@subsubheading Murmur (VoIP server)
+
@cindex Murmur (VoIP server)
@cindex VoIP server
This section describes how to set up and run a Murmur server. Murmur is
@end table
@end deffn
+@anchor{NGINX}
@subsubheading NGINX
@deffn {Scheme Variable} nginx-service-type
@deftp {Data type} php-fpm-dynamic-process-manager-configuration
Data Type for the @code{dynamic} php-fpm process manager. With the
@code{dynamic} process manager, spare worker processes are kept around
-based on it's configured limits.
+based on its configured limits.
@table @asis
@item @code{max-children} (default: @code{5})
Maximum of worker processes.
and gives Let's Encrypt permission to log the public IP address of the
requesting machine.
+@item @code{csr} (default: @code{#f})
+File name of Certificate Signing Request (CSR) in DER or PEM format.
+If @code{#f} is specified, this argument will not be passed to certbot.
+If a value is specified, certbot will use it to obtain a certificate, instead of
+using a self-generated CSR.
+The domain-name(s) mentioned in @code{domains}, must be consistent with the
+domain-name(s) mentioned in CSR file.
+
@item @code{authentication-hook} (default: @code{#f})
Command to be run in a shell once for each certificate challenge to be
answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
The @code{(gnu services vpn)} module provides services related to
@dfn{virtual private networks} (VPNs).
+@subsubheading Bitmask
+
+@defvr {Scheme Variable} bitmask-service-type
+A service type for the @uref{https://bitmask.net, Bitmask} VPN client. It makes
+the client available in the system and loads its polkit policy. Please note that
+the client expects an active polkit-agent, which is either run by your
+desktop-environment or should be run manually.
+@end defvr
+
@subsubheading OpenVPN
It provides a @emph{client} service for your machine to connect to a
@end deftypevr
-
@c %end of automatic openvpn-server documentation
+@subheading strongSwan
+
+Currently, the strongSwan service only provides legacy-style configuration with
+@file{ipsec.conf} and @file{ipsec.secrets} files.
+
+@defvr {Scheme Variable} strongswan-service-type
+A service type for configuring strongSwan for IPsec @acronym{VPN,
+Virtual Private Networking}. Its value must be a
+@code{strongswan-configuration} record as in this example:
+
+@lisp
+(service strongswan-service-type
+ (strongswan-configuration
+ (ipsec-conf "/etc/ipsec.conf")
+ (ipsec-secrets "/etc/ipsec.secrets")))
+@end lisp
+
+@end defvr
+
+@deftp {Data Type} strongswan-configuration
+Data type representing the configuration of the StrongSwan service.
+
+@table @asis
+@item @code{strongswan}
+The strongSwan package to use for this service.
+
+@item @code{ipsec-conf} (default: @code{#f})
+The file name of your @file{ipsec.conf}. If not @code{#f}, then this and
+@code{ipsec-secrets} must both be strings.
+
+@item @code{ipsec-secrets} (default @code{#f})
+The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and
+@code{ipsec-conf} must both be strings.
+
+@end table
+@end deftp
+
@subsubheading Wireguard
@defvr {Scheme Variable} wireguard-service-type
Once a substitute is successfully fetched, trigger substitute baking at
@var{trigger-url}.
+@item @code{publish?} (default: @code{#t})
+If set to false, do not start a publish server and ignore the
+@code{publish-port} argument. This can be useful if there is already a
+standalone publish server standing next to the remote server.
+
@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign
@item @code{publish-port} (default: @code{5558})
The TCP port of the publish server. It defaults to @code{5558}.
+@item @code{substitute-urls} (default: @code{%default-substitute-urls})
+The list of URLs where to look for substitutes by default.
+
@item @code{public-key}
@item @code{private-key}
Use the specific @var{file}s as the public/private key pair used to sign
;; Ganeti uses SSH to communicate between nodes.
(service openssh-service-type
(openssh-configuration
- (permit-root-login 'without-password)))
+ (permit-root-login 'prohibit-password)))
(service ganeti-service-type
(ganeti-configuration
(by default: @code{git}). This is necessary when using Gitolite with software
like cgit or gitweb.
+@item @code{unsafe-pattern} (default: @code{#f})
+An optional Perl regular expression for catching unsafe configurations in
+the configuration file. See
+@uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
+Gitolite's documentation} for more information.
+
+When the value is not @code{#f}, it should be a string containing a Perl
+regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
+value used by gitolite. It rejects any special character in configuration
+that might be interpreted by a shell, which is useful when sharing the
+administration burden with other people that do not otherwise have shell
+access on the server.
+
@item @code{git-config-keys} (default: @code{""})
Gitolite allows you to set git config values using the @samp{config}
keyword. This setting allows control over the config keys to accept.
@end deftp
+@subsubheading Gitile Service
+
+@cindex Gitile service
+@cindex Git, forge
+@uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
+public git repository contents from a web browser.
+
+Gitile works best in collaboration with Gitolite, and will serve the public
+repositories from Gitolite by default. The service should listen only on
+a local port, and a webserver should be configured to serve static resources.
+The gitile service provides an easy way to extend the Nginx service for
+that purpose (@pxref{NGINX}).
+
+The following example will configure Gitile to serve repositories from a
+custom location, with some default messages for the home page and the
+footers.
+
+@lisp
+(service gitile-service-type
+ (gitile-configuration
+ (repositories "/srv/git")
+ (base-git-url "https://myweb.site/git")
+ (index-title "My git repositories")
+ (intro '((p "This is all my public work!")))
+ (footer '((p "This is the end")))
+ (nginx-server-block
+ (nginx-server-configuration
+ (ssl-certificate
+ "/etc/letsencrypt/live/myweb.site/fullchain.pem")
+ (ssl-certificate-key
+ "/etc/letsencrypt/live/myweb.site/privkey.pem")
+ (listen '("443 ssl http2" "[::]:443 ssl http2"))
+ (locations
+ (list
+ ;; Allow for https anonymous fetch on /git/ urls.
+ (git-http-nginx-location-configuration
+ (git-http-configuration
+ (uri-path "/git/")
+ (git-root "/var/lib/gitolite/repositories")))))))))
+@end lisp
+
+In addition to the configuration record, you should configure your git
+repositories to contain some optional information. First, your public
+repositories need to contain the @file{git-daemon-export-ok} magic file
+that allows Git to export the repository. Gitile uses the presence of this
+file to detect public repositories it should make accessible. To do so with
+Gitolite for instance, modify your @file{conf/gitolite.conf} to include
+this in the repositories you want to make public:
+
+@example
+repo foo
+ R = daemon
+@end example
+
+In addition, Gitile can read the repository configuration to display more
+infomation on the repository. Gitile uses the gitweb namespace for its
+configuration. As an example, you can use the following in your
+@file{conf/gitolite.conf}:
+
+@example
+repo foo
+ R = daemon
+ desc = A long description, optionally with <i>HTML</i>, shown on the index page
+ config gitweb.name = The Foo Project
+ config gitweb.synopsis = A short description, shown on the main page of the project
+@end example
+
+Do not forget to commit and push these changes once you are satisfied. You
+may need to change your gitolite configuration to allow the previous
+configuration options to be set. One way to do that is to add the
+following service definition:
+
+@lisp
+(service gitolite-service-type
+ (gitolite-configuration
+ (admin-pubkey (local-file "key.pub"))
+ (rc-file
+ (gitolite-rc-file
+ (umask #o0027)
+ ;; Allow to set any configuration key
+ (git-config-keys ".*")
+ ;; Allow any text as a valid configuration value
+ (unsafe-patt "^$")))))
+@end lisp
+
+@deftp {Data Type} gitile-configuration
+Data type representing the configuration for @code{gitile-service-type}.
+
+@table @asis
+@item @code{package} (default: @var{gitile})
+Gitile package to use.
+
+@item @code{host} (default: @code{"localhost"})
+The host on which gitile is listening.
+
+@item @code{port} (default: @code{8080})
+The port on which gitile is listening.
+
+@item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
+The location of the database.
+
+@item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
+The location of the repositories. Note that only public repositories will
+be shown by Gitile. To make a repository public, add an empty
+@file{git-daemon-export-ok} file at the root of that repository.
+
+@item @code{base-git-url}
+The base git url that will be used to show clone commands.
+
+@item @code{index-title} (default: @code{"Index"})
+The page title for the index page that lists all the available repositories.
+
+@item @code{intro} (default: @code{'()})
+The intro content, as a list of sxml expressions. This is shown above the list
+of repositories, on the index page.
+
+@item @code{footer} (default: @code{'()})
+The footer content, as a list of sxml expressions. This is shown on every
+page served by Gitile.
+
+@item @code{nginx-server-block}
+An nginx server block that will be extended and used as a reverse proxy by
+Gitile to serve its pages, and as a normal web server to serve its assets.
+
+You can use this block to add more custom URLs to your domain, such as a
+@code{/git/} URL for anonymous clones, or serving any other files you would
+like to serve.
+@end table
+@end deftp
+
+
@node Game Services
@subsection Game Services
The kernel module loader service allows one to load loadable kernel
modules at boot. This is especially useful for modules that don't
-autoload and need to be manually loaded, as it's the case with
+autoload and need to be manually loaded, as is the case with
@code{ddcci}.
@deffn {Scheme Variable} kernel-module-loader-service-type
@table @asis
-@item @code{package} (default: @code{docker})
+@item @code{docker} (default: @code{docker})
The Docker daemon package to use.
-@item @code{package} (default: @code{docker-cli})
+@item @code{docker-cli} (default: @code{docker-cli})
The Docker client package to use.
@item @code{containerd} (default: @var{containerd})
should be setuid root.
The @code{setuid-programs} field of an @code{operating-system}
-declaration contains a list of G-expressions denoting the names of
-programs to be setuid-root (@pxref{Using the Configuration System}).
-For instance, the @command{passwd} program, which is part of the Shadow
-package, can be designated by this G-expression (@pxref{G-Expressions}):
+declaration contains a list of @code{<setuid-program>} denoting the
+names of programs to have a setuid or setgid bit set (@pxref{Using the
+Configuration System}). For instance, the @command{passwd} program,
+which is part of the Shadow package, with a setuid root can be
+designated like this:
@example
-#~(string-append #$shadow "/bin/passwd")
+(setuid-program
+ (program (file-append #$shadow "/bin/passwd")))
@end example
+@deftp {Data Type} setuid-program
+This data type represents a program with a setuid or setgid bit set.
+
+@table @asis
+@item @code{program}
+A file-like object having its setuid and/or setgid bit set.
+
+@item @code{setuid?} (default: @code{#t})
+Whether to set user setuid bit.
+
+@item @code{setgid?} (default: @code{#f})
+Whether to set group setgid bit.
+
+@item @code{user} (default: @code{0})
+UID (integer) or user name (string) for the user owner of the program,
+defaults to root.
+
+@item @code{group} (default: @code{0})
+GID (integer) goup name (string) for the group owner of the program,
+defaults to root.
+
+@end table
+@end deftp
+
A default set of setuid programs is defined by the
@code{%setuid-programs} variable of the @code{(gnu system)} module.
@defvr {Scheme Variable} %setuid-programs
-A list of G-expressions denoting common programs that are setuid-root.
+A list of @code{<setuid-program>} denoting common programs that are
+setuid-root.
The list includes commands such as @command{passwd}, @command{ping},
@command{su}, and @command{sudo}.
program to run in that initrd.
@deffn {Scheme Procedure} expression->initrd @var{exp} @
- [#:guile %guile-3.0-static-stripped] [#:name "guile-initrd"]
+ [#:guile %guile-static-stripped] [#:name "guile-initrd"]
Return as a file-like object a Linux initrd (a gzipped cpio archive)
containing @var{guile} and that evaluates @var{exp}, a G-expression,
upon booting. All the derivations referenced by @var{exp} are
through TFTP@. In combination with an NFS root file system this allows you to
build a diskless Guix system.
-The installation of the @code{grub-efi-netboot-bootloader} generates the content
-of the TFTP root directory at @code{target}
-(@pxref{Bootloader Configuration, @code{target}}), to be served by a TFTP server.
- You may want to mount your TFTP server directory onto @code{target} to move the
-required files to the TFTP server automatically.
+The installation of the @code{grub-efi-netboot-bootloader} generates the
+content of the TFTP root directory at @code{targets} (@pxref{Bootloader
+Configuration, @code{targets}}), to be served by a TFTP server. You may
+want to mount your TFTP server directories onto the @code{targets} to
+move the required files to the TFTP server automatically.
If you plan to use an NFS root file system as well (actually if you mount the
store from an NFS share), then the TFTP server needs to serve the file
store path, for example as
@file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
-Two symlinks are created to make this possible. The first symlink is
-@code{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
-@file{../../../boot/grub/grub.cfg},
-where @code{target} may be @file{/boot}. In this case the link is not leaving
-the served TFTP root directory, but otherwise it does. The second link is
-@code{target}@file{/gnu/store} and points to @file{../gnu/store}. This link
-is leaving the served TFTP root directory.
-
-The assumption behind all this is that you have an NFS server exporting the root
-file system for your Guix system, and additionally a TFTP server exporting your
-@code{target} directory—usually @file{/boot}—from that same root file system for
-your Guix system. In this constellation the symlinks will work.
-
-For other constellations you will have to program your own bootloader installer,
-which then takes care to make necessary files from the store accessible through
-TFTP, for example by copying them into the TFTP root directory at @code{target}.
+Two symlinks are created to make this possible. For each target in the
+@code{targets} field, the first symlink is
+@samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
+@file{../../../boot/grub/grub.cfg}, where @samp{target} may be
+@file{/boot}. In this case the link is not leaving the served TFTP root
+directory, but otherwise it does. The second link is
+@samp{target}@file{/gnu/store} and points to @file{../gnu/store}. This
+link is leaving the served TFTP root directory.
+
+The assumption behind all this is that you have an NFS server exporting
+the root file system for your Guix system, and additionally a TFTP
+server exporting your @code{targets} directories—usually a single
+@file{/boot}—from that same root file system for your Guix system. In
+this constellation the symlinks will work.
+
+For other constellations you will have to program your own bootloader
+installer, which then takes care to make necessary files from the store
+accessible through TFTP, for example by copying them into the TFTP root
+directory to your @code{targets}.
It is important to note that symlinks pointing outside the TFTP root directory
may need to be allowed in the configuration of your TFTP server. Further the
over netboot possible. For all this we can currently only recommend you to look
for instructions about @acronym{PXE, Preboot eXecution Environment}.
-@item @code{target}
-This is a string denoting the target onto which to install the
+@item @code{targets}
+This is a list of strings denoting the targets onto which to install the
bootloader.
-The interpretation depends on the bootloader in question. For
-@code{grub-bootloader}, for example, it should be a device name understood by
-the bootloader @command{installer} command, such as @code{/dev/sda} or
-@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}). For
-@code{grub-efi-bootloader}, it should be the mount point of the EFI file
-system, usually @file{/boot/efi}. For @code{grub-efi-netboot-bootloader},
-@code{target} should be the mount point corresponding to the TFTP root
-directory of your TFTP server.
+The interpretation of targets depends on the bootloader in question.
+For @code{grub-bootloader}, for example, they should be device names
+understood by the bootloader @command{installer} command, such as
+@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
+GNU GRUB Manual}). For @code{grub-efi-bootloader}, they should be mount
+points of the EFI file system, usually @file{/boot/efi}. For
+@code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
+points corresponding to TFTP root directories served by your TFTP
+server.
@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
needed for the system to operate correctly---e.g., the @file{/etc},
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
-This command also installs bootloader on the target specified in
+This command also installs bootloader on the targets specified in
@file{my-os-config}, unless the @option{--no-bootloader} option was
passed.
emulated machine:
@example
-$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -net user,model=virtio-net-pci
+$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
@end example
The VM shares its store with the host system.
(timezone "Etc/UTC")
(bootloader (bootloader-configuration
(bootloader grub-bootloader)
- (target "/dev/vda")
+ (targets '("/dev/vda"))
(terminal-outputs '(console))))
(file-systems (cons (file-system
(mount-point "/")
@section Running Guix in a Virtual Machine
@cindex virtual machine
-To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image
-distributed at
-@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz}.
-This image is a compressed image in QCOW format. You will first need to
-decompress with @command{xz -d}, and then you can pass it to an emulator such
-as QEMU (see below for details).
+To run Guix in a virtual machine (VM), one can use the pre-built Guix VM
+image distributed at
+@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}.
+This image is a compressed image in QCOW format. You can pass it to an
+emulator such as @uref{https://qemu.org/, QEMU} (see below for details).
This image boots the Xfce graphical environment and it contains some
commonly used tools. You can install more software in the image by running
as @file{/run/current-system/configuration.scm} (@pxref{Using the
Configuration System}).
-Instead of using this pre-built image, one can also build their own virtual
-machine image using @command{guix system vm-image} (@pxref{Invoking guix
-system}). The returned image is in qcow2 format, which the
-@uref{https://qemu.org/, QEMU emulator} can efficiently use.
+Instead of using this pre-built image, one can also build their own
+image using @command{guix system image} (@pxref{Invoking guix system}).
@cindex QEMU
If you built your own image, you must copy it out of the store
@command{-o StrictHostKeyChecking=no} prevents you from having to allow a
connection to an unknown host every time you connect.
+@quotation Note
+If you find the above @samp{hostfwd} example not to be working (e.g.,
+your SSH client hangs attempting to connect to the mapped port of your
+VM), make sure that your Guix System VM has networking support, such as
+by using the @code{dhcp-client-service-type} service type.
+@end quotation
+
@subsection Using @command{virt-viewer} with Spice
As an alternative to the default @command{qemu} graphical client you can
@command{guix system init}, or @command{guix deploy}.
@end defvr
+@defvr {Scheme Variable} linux-loadable-module-service-type
+Type of the service that collects lists of packages containing
+kernel-loadable modules, and adds them to the set of kernel-loadable
+modules.
+
+This service type is intended to be extended by other service types,
+such as below:
+
+@lisp
+(simple-service 'installing-module
+ linux-loadable-module-service-type
+ (list module-to-install-1
+ module-to-install-2))
+@end lisp
+
+This does not actually load modules at bootup, only adds it to the
+kernel profile so that it @emph{can} be loaded by other means.
+@end defvr
+
@node Shepherd Services
@subsection Shepherd Services
From there on, GDB will pick up debugging information from the
@file{.debug} files under @file{~/.guix-profile/lib/debug}.
+Below is an alternative GDB script which is useful when working with
+other profiles. It takes advantage of the optional Guile integration in
+GDB. This snippet is included by default on Guix System in the
+@file{~/.gdbinit} file.
+
+@example
+guile
+(use-modules (gdb))
+(execute (string-append "set debug-file-directory "
+ (or (getenv "GDB_DEBUG_FILE_DIRECTORY")
+ "~/.guix-profile/lib/debug")))
+end
+@end example
+
In addition, you will most likely want GDB to be able to show the source
code being debugged. To do that, you will have to unpack the source
code of the package of interest (obtained with @code{guix build
HCoop / jackhill / guix / guix.git / blobdiff