Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
-Copyright @copyright{} 2017, 2018 Mathieu Othacehe@*
+Copyright @copyright{} 2017, 2018, 2020 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018, 2019 Gábor Boskovits@*
-Copyright @copyright{} 2018, 2019 Florian Pelz@*
+Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*
Copyright @copyright{} 2019 Josh Holland@*
Copyright @copyright{} 2020 R Veera Kumar@*
Copyright @copyright{} 2020 Pierre Langlois@*
Copyright @copyright{} 2020 pinoaffe@*
+Copyright @copyright{} 2020 André Batista@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* System Installation:: Installing the whole operating system.
+* Getting Started:: Your first steps.
* Package Management:: Package installation, upgrade, etc.
+* Channels:: Customizing the package collection.
* Development:: Guix-aided software development.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
+* Upgrading Guix:: Upgrading Guix and its build daemon.
Setting Up the Daemon
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
-* Channels:: Customizing the package collection.
* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Substitution Failure:: What happens when substitution fails.
* On Trusting Binaries:: How can you trust that binary blob?
+Channels
+
+* Specifying Additional Channels:: Extending the package collection.
+* Using a Custom Guix Channel:: Using a customized Guix.
+* Replicating Guix:: Running the @emph{exact same} Guix.
+* Channel Authentication:: How Guix verifies what it fetches.
+* Creating a Channel:: How to write your custom channel.
+* Package Modules in a Sub-directory:: Specifying the channel's package modules location.
+* Declaring Channel Dependencies:: How to depend on other channels.
+* Specifying Channel Authorizations:: Defining channel authors authorizations.
+* Primary URL:: Distinguishing mirror to original.
+* Writing Channel News:: Communicating information to channel's users.
+
Development
* Invoking guix environment:: Setting up development environments.
* Invoking guix pack:: Creating software bundles.
* The GCC toolchain:: Working with languages supported by GCC.
+* Invoking guix git authenticate:: Authenticating Git repositories.
Programming Interface
* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
+* Build Phases:: Phases of the build process of a package.
+* Build Utilities:: Helpers for your package definitions and more.
* The Store:: Manipulating the package store.
* Derivations:: Low-level interface to package derivations.
* The Store Monad:: Purely functional interface to the store.
* Scheduled Job Execution:: The mcron service.
* Log Rotation:: The rottlog service.
* Networking Services:: Network setup, SSH daemon, etc.
+* Unattended Upgrades:: Automated system upgrades.
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
* Telephony Services:: Telephony services.
* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
+* LDAP Services:: LDAP services.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
* Linux Services:: Services tied to the Linux kernel.
-* Hurd Services:: Services specific to a Hurd System.
+* Hurd Services:: Services specific for a Hurd System.
* Miscellaneous Services:: Other services.
Defining Services
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
+Installing Debugging Files
+
+* Separate Debug Info:: Installing 'debug' outputs.
+* Rebuilding Debug Info:: Building missing debug info.
+
+Bootstrapping
+
+* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
+* Preparing to Use the Bootstrap Binaries:: Building that what matters most.
+
@end detailmenu
@end menu
@table @code
@item x86_64-linux
-Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
+Intel/AMD @code{x86_64} architecture, Linux-Libre kernel.
@item i686-linux
-Intel 32-bit architecture (IA32), Linux-Libre kernel;
+Intel 32-bit architecture (IA32), Linux-Libre kernel.
@item armhf-linux
ARMv7-A architecture with hard float, Thumb-2 and NEON,
@item aarch64-linux
little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
+@item i586-gnu
+@uref{https://hurd.gnu.org, GNU/Hurd} on the Intel 32-bit architecture
+(IA32).
+
+This configuration is experimental and under development. The easiest
+way for you to give it a try is by setting up an instance of
+@code{hurd-vm-service-type} on your GNU/Linux machine
+(@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}).
+@xref{Contributing}, on how to help!
+
@item mips64el-linux (deprecated)
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
chmod +x guix-install.sh
./guix-install.sh
@end example
+
+When you're done, @pxref{Application Setup} for extra configuration you
+might need, and @ref{Getting Started} for your first steps!
@end quotation
Installing goes along these lines:
@item
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
+@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib};
+@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
@item
@c FIXME: Specify a version number once a release has been made.
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August
2017 or later;
-@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} 3.x;
-@item @url{https://zlib.net, zlib};
+@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
+4.3.0 or later;
@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize
other machines running Guix, using the @code{offload} @dfn{build
hook}@footnote{This feature is available only when
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
-present.}. When that
-feature is enabled, a list of user-specified build machines is read from
-@file{/etc/guix/machines.scm}; every time a build is requested, for
-instance via @code{guix build}, the daemon attempts to offload it to one
-of the machines that satisfy the constraints of the derivation, in
-particular its system type---e.g., @file{x86_64-linux}. Missing
-prerequisites for the build are copied over SSH to the target machine,
-which then proceeds with the build; upon success the output(s) of the
-build are copied back to the initial machine.
+present.}. When that feature is enabled, a list of user-specified build
+machines is read from @file{/etc/guix/machines.scm}; every time a build
+is requested, for instance via @code{guix build}, the daemon attempts to
+offload it to one of the machines that satisfy the constraints of the
+derivation, in particular its system types---e.g., @code{x86_64-linux}.
+A single machine can have multiple system types, either because its
+architecture natively supports it, via emulation
+(@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}),
+or both. Missing prerequisites for the build are
+copied over SSH to the target machine, which then proceeds with the
+build; upon success the output(s) of the build are copied back to the
+initial machine. The offload facility comes with a basic scheduler that
+attempts to select the best machine. The best machine is chosen among
+the available machines based on criteria such as:
+
+@enumerate
+@item
+The availability of a build slot. A build machine can have as many
+build slots (connections) as the value of the @code{parallel-builds}
+field of its @code{build-machine} object.
+
+@item
+Its relative speed, as defined via the @code{speed} field of its
+@code{build-machine} object.
+
+@item
+Its load. The normalized machine load must be lower than a threshold
+value, configurable via the @code{overload-threshold} field of its
+@code{build-machine} object.
+
+@item
+Disk space availability. More than a 100 MiB must be available.
+@end enumerate
The @file{/etc/guix/machines.scm} file typically looks like this:
@lisp
(list (build-machine
(name "eightysix.example.org")
- (system "x86_64-linux")
+ (systems (list "x86_64-linux" "i686-linux"))
(host-key "ssh-ed25519 AAAAC3Nza@dots{}")
(user "bob")
(speed 2.)) ;incredibly fast!
(build-machine
(name "armeight.example.org")
- (system "aarch64-linux")
+ (systems (list "aarch64-linux"))
(host-key "ssh-rsa AAAAB3Nza@dots{}")
(user "alice")
(private-key
@noindent
In the example above we specify a list of two build machines, one for
-the @code{x86_64} architecture and one for the @code{aarch64}
-architecture.
+the @code{x86_64} and @code{i686} architectures and one for the
+@code{aarch64} architecture.
In fact, this file is---not surprisingly!---a Scheme file that is
evaluated when the @code{offload} hook is started. Its return value
@item name
The host name of the remote machine.
-@item system
-The system type of the remote machine---e.g., @code{"x86_64-linux"}.
+@item systems
+The system types the remote machine supports---e.g., @code{(list
+"x86_64-linux" "i686-linux")}.
@item user
The user account to use when connecting to the remote machine over SSH.
File name of the Unix-domain socket @command{guix-daemon} is listening
to on that machine.
+@item @code{overload-threshold} (default: @code{0.6})
+The load threshold above which a potential offload machine is
+disregarded by the offload scheduler. The value roughly translates to
+the total processor usage of the build machine, ranging from 0.0 (0%) to
+1.0 (100%). It can also be disabled by setting
+@code{overload-threshold} to @code{#f}.
+
@item @code{parallel-builds} (default: @code{1})
The number of builds that may run in parallel on the machine.
root's login shell, you'll need to @command{guix pull} separately.
@end quotation
-Join us on @code{#guix} on the Freenode IRC network or on
+Now, @pxref{Getting Started}, and
+join us on @code{#guix} on the Freenode IRC network or on
@email{guix-devel@@gnu.org} to share your experience!
system} command, specifically:
@example
-guix system disk-image --file-system-type=iso9660 \
- gnu/system/install.scm
+guix system disk-image -t iso9660 gnu/system/install.scm
@end example
Have a look at @file{gnu/system/install.scm} in the source tree,
@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
board, a list of possible boards will be printed.
+@c *********************************************************************
+@node Getting Started
+@chapter Getting Started
+
+Presumably, you've reached this section because either you have
+installed Guix on top of another distribution (@pxref{Installation}), or
+you've installed the standalone Guix System (@pxref{System
+Installation}). It's time for you to get started using Guix and this
+section aims to help you do that and give you a feel of what it's like.
+
+Guix is about installing software, so probably the first thing you'll
+want to do is to actually look for software. Let's say you're looking
+for a text editor, you can run:
+
+@example
+guix search text editor
+@end example
+
+This command shows you a number of matching @dfn{packages}, each time
+showing the package's name, version, a description, and additional info.
+Once you've found out the one you want to use, let's say Emacs (ah ha!),
+you can go ahead and install it (run this command as a regular user,
+@emph{no need for root privileges}!):
+
+@example
+guix install emacs
+@end example
+
+You've installed your first package, congrats! In the process, you've
+probably noticed that Guix downloaded pre-built binaries; or, if you
+explicitly chose to @emph{not} use pre-built binaries, then probably
+Guix is still building software (@pxref{Substitutes}, for more info).
+
+Unless you're using Guix System, the @command{guix install} command must
+have printed this hint:
+
+@example
+hint: Consider setting the necessary environment variables by running:
+
+ GUIX_PROFILE="$HOME/.guix-profile"
+ . "$GUIX_PROFILE/etc/profile"
+
+Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.
+@end example
+
+Indeed, you must now tell your shell where @command{emacs} and other
+programs installed with Guix are to be found. Pasting the two lines
+above will do just that: it will add
+@code{$HOME/.guix-profile/bin}---which is where the installed package
+is---to the @code{PATH} environment variable. You can paste these two
+lines in your shell so they take effect right away, but more importantly
+you should add them to @file{~/.bash_profile} (or equivalent file if you
+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.
+
+You can go on installing packages at your will. To list installed
+packages, run:
+
+@example
+guix package --list-installed
+@end example
+
+To remove a package, you would unsurprisingly run @command{guix remove}.
+A distinguishing feature is the ability to @dfn{roll back} any operation
+you made---installation, removal, upgrade---by simply typing:
+
+@example
+guix package --roll-back
+@end example
+
+This is because each operation is in fact a @dfn{transaction} that
+creates a new @dfn{generation}. These generations and the difference
+between them can be displayed by running:
+
+@example
+guix package --list-generations
+@end example
+
+Now you know the basics of package management!
+
+@quotation Going further
+@xref{Package Management}, for more about package management. You may
+like @dfn{declarative} package management with @command{guix package
+--manifest}, managing separate @dfn{profiles} with @option{--profile},
+deleting old generations, collecting garbage, and other nifty features
+that will come in handy as you become more familiar with Guix. If you
+are a developer, @pxref{Development} for additional tools. And if
+you're curious, @pxref{Features}, to peek under the hood.
+@end quotation
+
+Once you've installed a set of packages, you will want to periodically
+@emph{upgrade} them to the latest and greatest version. To do that, you
+will first pull the latest revision of Guix and its package collection:
+
+@example
+guix pull
+@end example
+
+The end result is a new @command{guix} command, under
+@file{~/.config/guix/current/bin}. Unless you're on Guix System, the
+first time you run @command{guix pull}, be sure to follow the hint that
+the command prints and, similar to what we saw above, paste these two
+lines in your terminal and @file{.bash_profile}:
+
+@example
+GUIX_PROFILE="$HOME/.config/guix/current/etc/profile"
+. "$GUIX_PROFILE/etc/profile"
+@end example
+
+@noindent
+You must also instruct your shell to point to this new @command{guix}:
+
+@example
+hash guix
+@end example
+
+At this point, you're running a brand new Guix. You can thus go ahead
+and actually upgrade all the packages you previously installed:
+
+@example
+guix upgrade
+@end example
+
+As you run this command, you will see that binaries are downloaded (or
+perhaps some packages are built), and eventually you end up with the
+upgraded packages. Should one of these upgraded packages not be to your
+liking, remember you can always roll back!
+
+You can display the exact revision of Guix you're currently using by
+running:
+
+@example
+guix describe
+@end example
+
+The information it displays is @emph{all it takes to reproduce the exact
+same Guix}, be it at a different point in time or on a different
+machine.
+
+@quotation Going further
+@xref{Invoking guix pull}, for more information. @xref{Channels}, on
+how to specify additional @dfn{channels} to pull packages from, how to
+replicate Guix, and more. You may also find @command{time-machine}
+handy (@pxref{Invoking guix time-machine}).
+@end quotation
+
+If you installed Guix System, one of the first things you'll want to do
+is to upgrade your system. Once you've run @command{guix pull} to get
+the latest Guix, you can upgrade the system like this:
+
+@example
+sudo guix system reconfigure /etc/config.scm
+@end example
+
+Upon completion, the system runs the latest versions of its software
+packages. When you eventually reboot, you'll notice a sub-menu in the
+bootloader that reads ``Old system generations'': it's what allows you
+to boot @emph{an older generation of your system}, should the latest
+generation be ``broken'' or otherwise unsatisfying. Just like for
+packages, you can always @emph{roll back} to a previous generation
+@emph{of the whole system}:
+
+@example
+sudo guix system roll-back
+@end example
+
+There are many things you'll probably want to tweak on your system:
+adding new user accounts, adding new system services, fiddling with the
+configuration of those services, etc. The system configuration is
+@emph{entirely} described in the @file{/etc/config.scm} file.
+@xref{Using the Configuration System}, to learn how to change it.
+
+Now you know enough to get started!
+
+@quotation Resources
+The rest of this manual provides a reference for all things Guix. Here
+are some additional resources you may find useful:
+
+@itemize
+@item
+@xref{Top,,, guix-cookbook, The GNU Guix Cookbook}, for a list of
+``how-to'' style of recipes for a variety of applications.
+
+@item
+The @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference
+Card} lists in two pages most of the commands and options you'll ever
+need.
+
+@item
+The web site contains @uref{https://guix.gnu.org/en/videos/,
+instructional videos} covering topics such as everyday use of Guix, how
+to get help, and how to become a contributor.
+
+@item
+@xref{Documentation}, to learn how to access documentation on your
+computer.
+@end itemize
+
+We hope you will enjoy Guix as much as the community enjoys building it!
+@end quotation
+
@c *********************************************************************
@node Package Management
@chapter Package Management
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
-* Channels:: Customizing the package collection.
* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
@node Features
@section Features
+Here we assume you've already made your first steps with Guix
+(@pxref{Getting Started}) and would like to get an overview about what's
+going on under the hood.
+
When using Guix, each package ends up in the @dfn{package store}, in its
own directory---something that resembles
@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
you should regularly run @command{guix pull} (@pxref{Invoking guix
pull}).
+@cindex package transformations, upgrades
+When upgrading, package transformations that were originally applied
+when creating the profile are automatically re-applied (@pxref{Package
+Transformation Options}). For example, assume you first installed Emacs
+from the tip of its development branch with:
+
+@example
+guix install emacs-next --with-branch=emacs-next=master
+@end example
+
+Next time you run @command{guix upgrade}, Guix will again pull the tip
+of the Emacs development branch and build @code{emacs-next} from that
+checkout.
+
+Note that transformation options such as @option{--with-branch} and
+@option{--with-source} depend on external state; it is up to you to
+ensure that they work as expected. You can also discard a
+transformations that apply to a package by running:
+
+@example
+guix install @var{package}
+@end example
+
@item --do-not-upgrade[=@var{regexp} @dots{}]
When used together with the @option{--upgrade} option, do @emph{not}
upgrade any packages whose name matches a @var{regexp}. For example, to
In addition, @command{guix pull} supports all the common build options
(@pxref{Common Build Options}).
-@node Channels
-@section Channels
+@node Invoking guix time-machine
+@section Invoking @command{guix time-machine}
-@cindex channels
-@cindex @file{channels.scm}, configuration file
-@cindex configuration file for channels
-@cindex @command{guix pull}, configuration file
-@cindex configuration of @command{guix pull}
-Guix and its package collection are updated by running @command{guix pull}
-(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
-deploys Guix itself from the official GNU@tie{}Guix repository. This can be
-customized by defining @dfn{channels} in the
-@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
-of a Git repository to be deployed, and @command{guix pull} can be instructed
-to pull from one or more channels. In other words, channels can be used
-to @emph{customize} and to @emph{extend} Guix, as we will see below.
-Before that, some security considerations.
+@cindex @command{guix time-machine}
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
-@subsection Channel Authentication
+The @command{guix time-machine} command provides access to other
+revisions of Guix, for example to install older versions of packages,
+or to reproduce a computation in an identical environment. The revision
+of Guix to be used is defined by a commit or by a channel
+description file created by @command{guix describe}
+(@pxref{Invoking guix describe}).
-@anchor{channel-authentication}
-@cindex authentication, of channel code
-The @command{guix pull} and @command{guix time-machine} commands
-@dfn{authenticate} the code retrieved from channels: they make sure each
-commit that is fetched is signed by an authorized developer. The goal
-is to protect from unauthorized modifications to the channel that would
-lead users to run malicious code.
+The general syntax is:
-As a user, you must provide a @dfn{channel introduction} in your
-channels file so that Guix knows how to authenticate its first commit.
-A channel specification, including its introduction, looks something
-along these lines:
+@example
+guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
+@end example
-@lisp
-(channel
- (name 'my-channel)
- (url "https://example.org/my-channel.git")
- (introduction
- (make-channel-introduction
- "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
- (openpgp-fingerprint
- "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
-@end lisp
+where @var{command} and @var{arg}@dots{} are passed unmodified to the
+@command{guix} command of the specified revision. The @var{options} that define
+this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
-The specification above shows the name and URL of the channel. The call
-to @code{make-channel-introduction} above specifies that authentication
-of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
-by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
+@table @code
+@item --url=@var{url}
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Use the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
-For the main channel, called @code{guix}, you automatically get that
-information from your Guix installation. For other channels, include
-the channel introduction provided by the channel authors in your
-@file{channels.scm} file. Make sure you retrieve the channel
-introduction from a trusted source since that is the root of your trust.
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file}. @var{file} must contain
+Scheme code that evaluates to a list of channel objects.
+@xref{Channels} for more information.
+@end table
-If you're curious about the authentication mechanics, read on!
+As for @command{guix pull}, the absence of any options means that the
+the latest commit on the master branch will be used. The command
-@subsection Using a Custom Guix Channel
+@example
+guix time-machine -- build hello
+@end example
-The channel called @code{guix} specifies where Guix itself---its command-line
-tools as well as its package collection---should be downloaded. For instance,
-suppose you want to update from your own copy of the Guix repository at
-@code{example.org}, and specifically the @code{super-hacks} branch, you can
-write in @code{~/.config/guix/channels.scm} this specification:
+will thus build the package @code{hello} as defined in the master branch,
+which is in general a newer revision of Guix than you have installed.
+Time travel works in both directions!
-@lisp
-;; Tell 'guix pull' to use my own repo.
-(list (channel
- (name 'guix)
- (url "https://example.org/my-guix.git")
- (branch "super-hacks")))
-@end lisp
+Note that @command{guix time-machine} can trigger builds of channels and
+their dependencies, and these are controlled by the standard build
+options (@pxref{Common Build Options}).
-@noindent
-From there on, @command{guix pull} will fetch code from the @code{super-hacks}
-branch of the repository at @code{example.org}.
+@node Inferiors
+@section Inferiors
-@subsection Specifying Additional Channels
+@c TODO: Remove this once we're more confident about API stability.
+@quotation Note
+The functionality described here is a ``technology preview'' as of version
+@value{VERSION}. As such, the interface is subject to change.
+@end quotation
-@cindex extending the package collection (channels)
-@cindex personal packages (channels)
-@cindex channels, for personal packages
-You can also specify @emph{additional channels} to pull from. Let's say you
-have a bunch of custom package variants or personal packages that you think
-would make little sense to contribute to the Guix project, but would like to
-have these packages transparently available to you at the command line. You
-would first write modules containing those package definitions (@pxref{Package
-Modules}), maintain them in a Git repository, and then you and anyone else can
-use it as an additional channel to get packages from. Neat, no?
+@cindex inferiors
+@cindex composition of Guix revisions
+Sometimes you might need to mix packages from the revision of Guix you're
+currently running with packages available in a different revision of Guix.
+Guix @dfn{inferiors} allow you to achieve that by composing different Guix
+revisions in arbitrary ways.
-@c What follows stems from discussions at
-@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
-@c earlier discussions on guix-devel@gnu.org.
-@quotation Warning
-Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
-publish your personal channel to the world, we would like to share a few words
-of caution:
+@cindex inferior packages
+Technically, an ``inferior'' is essentially a separate Guix process connected
+to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
+@code{(guix inferior)} module allows you to create inferiors and to
+communicate with them. It also provides a high-level interface to browse and
+manipulate the packages that an inferior provides---@dfn{inferior packages}.
-@itemize
-@item
-Before publishing a channel, please consider contributing your package
-definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
-to free software of all sorts, and packages in Guix proper are readily
-available to all Guix users and benefit from the project's quality assurance
-process.
-
-@item
-When you maintain package definitions outside Guix, we, Guix developers,
-consider that @emph{the compatibility burden is on you}. Remember that
-package modules and package definitions are just Scheme code that uses various
-programming interfaces (APIs). We want to remain free to change these APIs to
-keep improving Guix, possibly in ways that break your channel. We never
-change APIs gratuitously, but we will @emph{not} commit to freezing APIs
-either.
+When combined with channels (@pxref{Channels}), inferiors provide a simple way
+to interact with a separate revision of Guix. For example, let's assume you
+want to install in your profile the current @code{guile} package, along with
+the @code{guile-json} as it existed in an older revision of Guix---perhaps
+because the newer @code{guile-json} has an incompatible API and you want to
+run your code against the old API@. To do that, you could write a manifest for
+use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
+manifest, you would create an inferior for that old Guix revision you care
+about, and you would look up the @code{guile-json} package in the inferior:
-@item
-Corollary: if you're using an external channel and that channel breaks, please
-@emph{report the issue to the channel authors}, not to the Guix project.
-@end itemize
+@lisp
+(use-modules (guix inferior) (guix channels)
+ (srfi srfi-1)) ;for 'first'
-You've been warned! Having said this, we believe external channels are a
-practical way to exert your freedom to augment Guix' package collection and to
-share your improvements, which are basic tenets of
-@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
-email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
-@end quotation
+(define channels
+ ;; This is the old revision from which we want to
+ ;; extract guile-json.
+ (list (channel
+ (name 'guix)
+ (url "https://git.savannah.gnu.org/git/guix.git")
+ (commit
+ "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
-To use a channel, write @code{~/.config/guix/channels.scm} to instruct
-@command{guix pull} to pull from it @emph{in addition} to the default Guix
-channel(s):
+(define inferior
+ ;; An inferior representing the above revision.
+ (inferior-for-channels channels))
-@vindex %default-channels
-@lisp
-;; Add my personal packages to those Guix provides.
-(cons (channel
- (name 'my-personal-packages)
- (url "https://example.org/personal-packages.git"))
- %default-channels)
+;; Now create a manifest with the current "guile" package
+;; and the old "guile-json" package.
+(packages->manifest
+ (list (first (lookup-inferior-packages inferior "guile-json"))
+ (specification->package "guile")))
@end lisp
-@noindent
-Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
-add a channel the list of channels that the variable @code{%default-channels}
-is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
-Manual}). With this file in place, @command{guix pull} builds not only Guix
-but also the package modules from your own repository. The result in
-@file{~/.config/guix/current} is the union of Guix with your own package
-modules:
+On its first run, @command{guix package --manifest} might have to build the
+channel you specified before it can create the inferior; subsequent runs will
+be much faster because the Guix revision will be cached.
+
+The @code{(guix inferior)} module provides the following procedures to open an
+inferior:
+
+@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
+ [#:cache-directory] [#:ttl]
+Return an inferior for @var{channels}, a list of channels. Use the cache at
+@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
+This procedure opens a new connection to the build daemon.
+
+As a side effect, this procedure may build or substitute binaries for
+@var{channels}, which can take time.
+@end deffn
+
+@deffn {Scheme Procedure} open-inferior @var{directory} @
+ [#:command "bin/guix"]
+Open the inferior Guix in @var{directory}, running
+@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
+the inferior could not be launched.
+@end deffn
+
+@cindex inferior packages
+The procedures listed below allow you to obtain and manipulate inferior
+packages.
+
+@deffn {Scheme Procedure} inferior-packages @var{inferior}
+Return the list of packages known to @var{inferior}.
+@end deffn
+
+@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
+ [@var{version}]
+Return the sorted list of inferior packages matching @var{name} in
+@var{inferior}, with highest version numbers first. If @var{version} is true,
+return only packages with a version number prefixed by @var{version}.
+@end deffn
+
+@deffn {Scheme Procedure} inferior-package? @var{obj}
+Return true if @var{obj} is an inferior package.
+@end deffn
+
+@deffn {Scheme Procedure} inferior-package-name @var{package}
+@deffnx {Scheme Procedure} inferior-package-version @var{package}
+@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
+@deffnx {Scheme Procedure} inferior-package-description @var{package}
+@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
+@deffnx {Scheme Procedure} inferior-package-location @var{package}
+@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
+@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
+These procedures are the counterpart of package record accessors
+(@pxref{package Reference}). Most of them work by querying the inferior
+@var{package} comes from, so the inferior must still be live when you call
+these procedures.
+@end deffn
+
+Inferior packages can be used transparently like any other package or
+file-like object in G-expressions (@pxref{G-Expressions}). They are also
+transparently handled by the @code{packages->manifest} procedure, which is
+commonly use in manifests (@pxref{Invoking guix package, the
+@option{--manifest} option of @command{guix package}}). Thus you can insert
+an inferior package pretty much anywhere you would insert a regular package:
+in manifests, in the @code{packages} field of your @code{operating-system}
+declaration, and so on.
+
+@node Invoking guix describe
+@section Invoking @command{guix describe}
+
+@cindex reproducibility
+@cindex replicating Guix
+Often you may want to answer questions like: ``Which revision of Guix am I
+using?'' or ``Which channels am I using?'' This is useful information in many
+situations: if you want to @emph{replicate} an environment on a different
+machine or user account, if you want to report a bug or to determine what
+change in the channels you are using caused it, or if you want to record your
+system state for reproducibility purposes. The @command{guix describe}
+command answers these questions.
+
+When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
+displays the channel(s) that it was built from, including their repository URL
+and commit IDs (@pxref{Channels}):
@example
-$ guix pull --list-generations
-@dots{}
-Generation 19 Aug 27 2018 16:20:48
- guix d894ab8
+$ guix describe
+Generation 10 Sep 03 2018 17:32:44 (current)
+ guix e0fa68c
repository URL: https://git.savannah.gnu.org/git/guix.git
branch: master
- commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
- my-personal-packages dd3df5e
- repository URL: https://example.org/personal-packages.git
- branch: master
- commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
- 11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
- 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
+ commit: e0fa68c7718fffd33d81af415279d6ddb518f727
+@end example
+
+If you're familiar with the Git version control system, this is similar in
+spirit to @command{git describe}; the output is also similar to that of
+@command{guix pull --list-generations}, but limited to the current generation
+(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
+the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
+information is all it takes to describe the revision of Guix you're using, and
+also to replicate it.
+
+To make it easier to replicate Guix, @command{guix describe} can also be asked
+to return a list of channels instead of the human-readable description above:
+
+@example
+$ guix describe -f channels
+(list (channel
+ (name 'guix)
+ (url "https://git.savannah.gnu.org/git/guix.git")
+ (commit
+ "e0fa68c7718fffd33d81af415279d6ddb518f727")
+ (introduction
+ (make-channel-introduction
+ "9edb3f66fd807b096b48283debdcddccfea34bad"
+ (openpgp-fingerprint
+ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA")))))
@end example
@noindent
-The output of @command{guix pull} above shows that Generation@tie{}19 includes
-both Guix and packages from the @code{my-personal-packages} channel. Among
-the new and upgraded packages that are listed, some like @code{my-gimp} and
-@code{my-emacs-with-cool-features} might come from
-@code{my-personal-packages}, while others come from the Guix default channel.
+You can save this to a file and feed it to @command{guix pull -C} on some
+other machine or at a later point in time, which will instantiate @emph{this
+exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
+From there on, since you're able to deploy the same revision of Guix, you can
+just as well @emph{replicate a complete software environment}. We humbly
+think that this is @emph{awesome}, and we hope you'll like it too!
-To create a channel, create a Git repository containing your own package
-modules and make it available. The repository can contain anything, but a
-useful channel will contain Guile modules that export packages. Once you
-start using a channel, Guix will behave as if the root directory of that
-channel's Git repository has been added to the Guile load path (@pxref{Load
-Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
-contains a file at @file{my-packages/my-tools.scm} that defines a Guile
-module, then the module will be available under the name @code{(my-packages
-my-tools)}, and you will be able to use it like any other module
-(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
+The details of the options supported by @command{guix describe} are as
+follows:
-@cindex dependencies, channels
-@cindex meta-data, channels
-@subsection Declaring Channel Dependencies
+@table @code
+@item --format=@var{format}
+@itemx -f @var{format}
+Produce output in the specified @var{format}, one of:
-Channel authors may decide to augment a package collection provided by other
-channels. They can declare their channel to be dependent on other channels in
-a meta-data file @file{.guix-channel}, which is to be placed in the root of
-the channel repository.
+@table @code
+@item human
+produce human-readable output;
+@item channels
+produce a list of channel specifications that can be passed to @command{guix
+pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
+guix pull});
+@item channels-sans-intro
+like @code{channels}, but omit the @code{introduction} field; use it to
+produce a channel specification suitable for Guix version 1.1.0 or
+earlier---the @code{introduction} field has to do with channel
+authentication (@pxref{Channels, Channel Authentication}) and is not
+supported by these older versions;
+@item json
+@cindex JSON
+produce a list of channel specifications in JSON format;
+@item recutils
+produce a list of channel specifications in Recutils format.
+@end table
-The meta-data file should contain a simple S-expression like this:
+@item --list-formats
+Display available formats for @option{--format} option.
-@lisp
-(channel
- (version 0)
- (dependencies
- (channel
- (name some-collection)
- (url "https://example.org/first-collection.git")
+@item --profile=@var{profile}
+@itemx -p @var{profile}
+Display information about @var{profile}.
+@end table
- ;; The 'introduction' bit below is optional: you would
- ;; provide it for dependencies that can be authenticated.
- (introduction
- (channel-introduction
- (version 0)
- (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
- (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
- (channel
- (name some-other-collection)
- (url "https://example.org/second-collection.git")
- (branch "testing"))))
-@end lisp
+@node Invoking guix archive
+@section Invoking @command{guix archive}
-In the above example this channel is declared to depend on two other channels,
-which will both be fetched automatically. The modules provided by the channel
-will be compiled in an environment where the modules of all these declared
-channels are available.
+@cindex @command{guix archive}
+@cindex archive
+The @command{guix archive} command allows users to @dfn{export} files
+from the store into a single archive, and to later @dfn{import} them on
+a machine that runs Guix.
+In particular, it allows store files to be transferred from one machine
+to the store on another machine.
-For the sake of reliability and maintainability, you should avoid dependencies
-on channels that you don't control, and you should aim to keep the number of
-dependencies to a minimum.
+@quotation Note
+If you're looking for a way to produce archives in a format suitable for
+tools other than Guix, @pxref{Invoking guix pack}.
+@end quotation
-@cindex subdirectory, channels
-@subsection Package Modules in a Sub-directory
+@cindex exporting store items
+To export store files as an archive to standard output, run:
-As a channel author, you may want to keep your channel modules in a
-sub-directory. If your modules are in the sub-directory @file{guix}, you must
-add a meta-data file @file{.guix-channel} that contains:
+@example
+guix archive --export @var{options} @var{specifications}...
+@end example
-@lisp
-(channel
- (version 0)
- (directory "guix"))
-@end lisp
+@var{specifications} may be either store file names or package
+specifications, as for @command{guix package} (@pxref{Invoking guix
+package}). For instance, the following command creates an archive
+containing the @code{gui} output of the @code{git} package and the main
+output of @code{emacs}:
-@cindex channel authorizations
-@subsection Specifying Channel Authorizations
+@example
+guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
+@end example
-@anchor{channel-authorizations}
-As we saw above, Guix ensures the source code it pulls from channels
-comes from authorized developers. As a channel author, you need to
-specify the list of authorized developers in the
-@file{.guix-authorizations} file in the channel's Git repository. The
-authentication rule is simple: each commit must be signed by a key
-listed in the @file{.guix-authorizations} file of its parent
-commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
-(DAG). Each commit can have zero or more parents; ``regular'' commits
-have one parent and merge commits have two parent commits. Read
-@uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
-for Computer Scientists}} for a great overview.} The
-@file{.guix-authorizations} file looks like this:
+If the specified packages are not built yet, @command{guix archive}
+automatically builds them. The build process may be controlled with the
+common build options (@pxref{Common Build Options}).
-@lisp
-;; Example '.guix-authorizations' file.
+To transfer the @code{emacs} package to a machine connected over SSH,
+one would run:
-(authorizations
- (version 0) ;current file format version
+@example
+guix archive --export -r emacs | ssh the-machine guix archive --import
+@end example
- (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
- (name "alice"))
- ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
- (name "bob"))
- ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
- (name "charlie"))))
-@end lisp
+@noindent
+Similarly, a complete user profile may be transferred from one machine
+to another like this:
-Each fingerprint is followed by optional key/value pairs, as in the
-example above. Currently these key/value pairs are ignored.
+@example
+guix archive --export -r $(readlink -f ~/.guix-profile) | \
+ ssh the-machine guix archive --import
+@end example
-This authentication rule creates a chicken-and-egg issue: how do we
-authenticate the first commit? Related to that: how do we deal with
-channels whose repository history contains unsigned commits and lack
-@file{.guix-authorizations}? And how do we fork existing channels?
+@noindent
+However, note that, in both examples, all of @code{emacs} and the
+profile as well as all of their dependencies are transferred (due to
+@option{-r}), regardless of what is already available in the store on
+the target machine. The @option{--missing} option can help figure out
+which items are missing from the target store. The @command{guix copy}
+command simplifies and optimizes this whole process, so this is probably
+what you should use in this case (@pxref{Invoking guix copy}).
-@cindex channel introduction
-Channel introductions answer these questions by describing the first
-commit of a channel that should be authenticated. The first time a
-channel is fetched with @command{guix pull} or @command{guix
-time-machine}, the command looks up the introductory commit and verifies
-that it is signed by the specified OpenPGP key. From then on, it
-authenticates commits according to the rule above.
+@cindex nar, archive format
+@cindex normalized archive (nar)
+@cindex nar bundle, archive format
+Each store item is written in the @dfn{normalized archive} or @dfn{nar}
+format (described below), and the output of @command{guix archive
+--export} (and input of @command{guix archive --import}) is a @dfn{nar
+bundle}.
-Additionally, your channel must provide all the OpenPGP keys that were
-ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
-files, which can be either binary or ``ASCII-armored''. By default,
-those @file{.key} files are searched for in the branch named
-@code{keyring} but you can specify a different branch name in
-@code{.guix-channel} like so:
+The nar format is
+comparable in spirit to `tar', but with differences
+that make it more appropriate for our purposes. First, rather than
+recording all Unix metadata for each file, the nar format only mentions
+the file type (regular, directory, or symbolic link); Unix permissions
+and owner/group are dismissed. Second, the order in which directory
+entries are stored always follows the order of file names according to
+the C locale collation order. This makes archive production fully
+deterministic.
-@lisp
-(channel
- (version 0)
- (keyring-reference "my-keyring-branch"))
-@end lisp
+That nar bundle format is essentially the concatenation of zero or more
+nars along with metadata for each store item it contains: its file name,
+references, corresponding derivation, and a digital signature.
-To summarize, as the author of a channel, there are three things you have
-to do to allow users to authenticate your code:
+When exporting, the daemon digitally signs the contents of the archive,
+and that digital signature is appended. When importing, the daemon
+verifies the signature and rejects the import in case of an invalid
+signature or if the signing key is not authorized.
+@c FIXME: Add xref to daemon doc about signatures.
-@enumerate
-@item
-Export the OpenPGP keys of past and present committers with @command{gpg
---export} and store them in @file{.key} files, by default in a branch
-named @code{keyring} (we recommend making it an @dfn{orphan branch}).
+The main options are:
-@item
-Introduce an initial @file{.guix-authorizations} in the channel's
-repository. Do that in a signed commit (@pxref{Commit Access}, for
-information on how to sign Git commits.)
+@table @code
+@item --export
+Export the specified store files or packages (see below). Write the
+resulting archive to the standard output.
-@item
-Advertise the channel introduction, for instance on your channel's web
-page. The channel introduction, as we saw above, is the commit/key
-pair---i.e., the commit that introduced @file{.guix-authorizations}, and
-the fingerprint of the OpenPGP used to sign it.
-@end enumerate
+Dependencies are @emph{not} included in the output, unless
+@option{--recursive} is passed.
-Before pushing to your public Git repository, you can run @command{guix
-git-authenticate} to verify that you did sign all the commits you are
-about to push with an authorized key:
+@item -r
+@itemx --recursive
+When combined with @option{--export}, this instructs @command{guix archive}
+to include dependencies of the given items in the archive. Thus, the
+resulting archive is self-contained: it contains the closure of the
+exported store items.
+
+@item --import
+Read an archive from the standard input, and import the files listed
+therein into the store. Abort if the archive has an invalid digital
+signature, or if it is signed by a public key not among the authorized
+keys (see @option{--authorize} below).
+
+@item --missing
+Read a list of store file names from the standard input, one per line,
+and write on the standard output the subset of these files missing from
+the store.
+
+@item --generate-key[=@var{parameters}]
+@cindex signing, archives
+Generate a new key pair for the daemon. This is a prerequisite before
+archives can be exported with @option{--export}. This
+operation is usually instantaneous but it can take time if the system's
+entropy pool needs to be refilled. On Guix System,
+@code{guix-service-type} takes care of generating this key pair the
+first boot.
+
+The generated key pair is typically stored under @file{/etc/guix}, in
+@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
+key, which must be kept secret). When @var{parameters} is omitted,
+an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
+versions before 1.6.0, it is a 4096-bit RSA key.
+Alternatively, @var{parameters} can specify
+@code{genkey} parameters suitable for Libgcrypt (@pxref{General
+public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
+Libgcrypt Reference Manual}).
+
+@item --authorize
+@cindex authorizing, archives
+Authorize imports signed by the public key passed on standard input.
+The public key must be in ``s-expression advanced format''---i.e., the
+same format as the @file{signing-key.pub} file.
+
+The list of authorized keys is kept in the human-editable file
+@file{/etc/guix/acl}. The file contains
+@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+s-expressions''} and is structured as an access-control list in the
+@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+(SPKI)}.
+
+@item --extract=@var{directory}
+@itemx -x @var{directory}
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and extract it to @var{directory}. This is a
+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}:
@example
-guix git authenticate @var{commit} @var{signer}
+$ wget -O - \
+ https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
+ | gunzip | guix archive -x /tmp/emacs
@end example
-@noindent
-where @var{commit} and @var{signer} are your channel introduction.
-@xref{Invoking guix git authenticate}, for details.
-
-Publishing a signed channel requires discipline: any mistake, such as an
-unsigned commit or a commit signed by an unauthorized key, will prevent
-users from pulling from your channel---well, that's the whole point of
-authentication! Pay attention to merges in particular: merge commits
-are considered authentic if and only if they are signed by a key present
-in the @file{.guix-authorizations} file of @emph{both} branches.
+Single-item archives are different from multiple-item archives produced
+by @command{guix archive --export}; they contain a single store item,
+and they do @emph{not} embed a signature. Thus this operation does
+@emph{no} signature verification and its output should be considered
+unsafe.
-@cindex primary URL, channels
-@subsection Primary URL
+The primary purpose of this operation is to facilitate inspection of
+archive contents coming from possibly untrusted substitute servers
+(@pxref{Invoking guix challenge}).
-Channel authors can indicate the primary URL of their channel's Git
-repository in the @file{.guix-channel} file, like so:
+@item --list
+@itemx -t
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and print the list of files it contains, as in
+this example:
-@lisp
-(channel
- (version 0)
- (url "https://example.org/guix.git"))
-@end lisp
+@example
+$ wget -O - \
+ https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
+ | lzip -d | guix archive -t
+@end example
-This allows @command{guix pull} to determine whether it is pulling code
-from a mirror of the channel; when that is the case, it warns the user
-that the mirror might be stale and displays the primary URL. That way,
-users cannot be tricked into fetching code from a stale mirror that does
-not receive security updates.
+@end table
-This feature only makes sense for authenticated repositories, such as
-the official @code{guix} channel, for which @command{guix pull} ensures
-the code it fetches is authentic.
+@c *********************************************************************
+@node Channels
+@chapter Channels
-@cindex news, for channels
-@subsection Writing Channel News
+@cindex channels
+@cindex @file{channels.scm}, configuration file
+@cindex configuration file for channels
+@cindex @command{guix pull}, configuration file
+@cindex configuration of @command{guix pull}
+Guix and its package collection are updated by running @command{guix pull}
+(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
+deploys Guix itself from the official GNU@tie{}Guix repository. This can be
+customized by defining @dfn{channels} in the
+@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
+of a Git repository to be deployed, and @command{guix pull} can be instructed
+to pull from one or more channels. In other words, channels can be used
+to @emph{customize} and to @emph{extend} Guix, as we will see below.
+Guix is able to take into account security concerns and deal with authenticated
+updates.
-Channel authors may occasionally want to communicate to their users
-information about important changes in the channel. You'd send them all
-an email, but that's not convenient.
+@menu
+* Specifying Additional Channels:: Extending the package collection.
+* Using a Custom Guix Channel:: Using a customized Guix.
+* Replicating Guix:: Running the @emph{exact same} Guix.
+* Channel Authentication:: How Guix verifies what it fetches.
+* Creating a Channel:: How to write your custom channel.
+* Package Modules in a Sub-directory:: Specifying the channel's package modules location.
+* Declaring Channel Dependencies:: How to depend on other channels.
+* Specifying Channel Authorizations:: Defining channel authors authorizations.
+* Primary URL:: Distinguishing mirror to original.
+* Writing Channel News:: Communicating information to channel's users.
+@end menu
-Instead, channels can provide a @dfn{news file}; when the channel users
-run @command{guix pull}, that news file is automatically read and
-@command{guix pull --news} can display the announcements that correspond
-to the new commits that have been pulled, if any.
+@node Specifying Additional Channels
+@section Specifying Additional Channels
-To do that, channel authors must first declare the name of the news file
-in their @file{.guix-channel} file:
+@cindex extending the package collection (channels)
+@cindex variant packages (channels)
+You can specify @emph{additional channels} to pull from. To use a channel, write
+@code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
+@emph{in addition} to the default Guix channel(s):
+@vindex %default-channels
@lisp
-(channel
- (version 0)
- (news-file "etc/news.txt"))
+;; Add variant packages to those Guix provides.
+(cons (channel
+ (name 'variant-packages)
+ (url "https://example.org/variant-packages.git"))
+ %default-channels)
@end lisp
-The news file itself, @file{etc/news.txt} in this example, must look
-something like this:
+@noindent
+Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
+add a channel the list of channels that the variable @code{%default-channels}
+is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
+Manual}). With this file in place, @command{guix pull} builds not only Guix
+but also the package modules from your own repository. The result in
+@file{~/.config/guix/current} is the union of Guix with your own package
+modules:
-@lisp
-(channel-news
- (version 0)
- (entry (tag "the-bug-fix")
- (title (en "Fixed terrible bug")
- (fr "Oh la la"))
- (body (en "@@emph@{Good news@}! It's fixed!")
- (eo "Certe ĝi pli bone funkcias nun!")))
- (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
- (title (en "Added a great package")
- (ca "Què vol dir guix?"))
- (body (en "Don't miss the @@code@{hello@} package!"))))
-@end lisp
+@example
+$ guix pull --list-generations
+@dots{}
+Generation 19 Aug 27 2018 16:20:48
+ guix d894ab8
+ repository URL: https://git.savannah.gnu.org/git/guix.git
+ branch: master
+ commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
+ variant-packages dd3df5e
+ repository URL: https://example.org/variant-packages.git
+ branch: master
+ commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
+ 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
+ 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
+@end example
-The file consists of a list of @dfn{news entries}. Each entry is
-associated with a commit or tag: it describes changes made in this
-commit, possibly in preceding commits as well. Users see entries only
-the first time they obtain the commit the entry refers to.
+@noindent
+The output of @command{guix pull} above shows that Generation@tie{}19 includes
+both Guix and packages from the @code{variant-personal-packages} channel. Among
+the new and upgraded packages that are listed, some like @code{variant-gimp} and
+@code{variant-emacs-with-cool-features} might come from
+@code{variant-packages}, while others come from the Guix default channel.
-The @code{title} field should be a one-line summary while @code{body}
-can be arbitrarily long, and both can contain Texinfo markup
-(@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
-a list of language tag/message tuples, which allows @command{guix pull}
-to display news in the language that corresponds to the user's locale.
+@node Using a Custom Guix Channel
+@section Using a Custom Guix Channel
-If you want to translate news using a gettext-based workflow, you can
-extract translatable strings with @command{xgettext} (@pxref{xgettext
-Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
-you write news entries in English first, the command below creates a PO
-file containing the strings to translate:
+The channel called @code{guix} specifies where Guix itself---its command-line
+tools as well as its package collection---should be downloaded. For instance,
+suppose you want to update from another copy of the Guix repository at
+@code{example.org}, and specifically the @code{super-hacks} branch, you can
+write in @code{~/.config/guix/channels.scm} this specification:
-@example
-xgettext -o news.po -l scheme -ken etc/news.scm
-@end example
+@lisp
+;; Tell 'guix pull' to use another repo.
+(list (channel
+ (name 'guix)
+ (url "https://example.org/another-guix.git")
+ (branch "super-hacks")))
+@end lisp
-To sum up, yes, you could use your channel as a blog. But beware, this
-is @emph{not quite} what your users might expect.
+@noindent
+From there on, @command{guix pull} will fetch code from the @code{super-hacks}
+branch of the repository at @code{example.org}. The authentication concern is
+addressed below ((@pxref{Channel Authentication}).
-@subsection Replicating Guix
+@node Replicating Guix
+@section Replicating Guix
@cindex pinning, channels
@cindex replicating Guix
(url "https://git.savannah.gnu.org/git/guix.git")
(commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
(channel
- (name 'my-personal-packages)
- (url "https://example.org/personal-packages.git")
+ (name 'variant-packages)
+ (url "https://example.org/variant-packages.git")
(commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
will---some sort of ``meta reproducibility'' capabilities, if you will.
@xref{Inferiors}, for another way to take advantage of these super powers.
-@node Invoking guix time-machine
-@section Invoking @command{guix time-machine}
-
-@cindex @command{guix time-machine}
-@cindex pinning, channels
-@cindex replicating Guix
-@cindex reproducibility, of Guix
-
-The @command{guix time-machine} command provides access to other
-revisions of Guix, for example to install older versions of packages,
-or to reproduce a computation in an identical environment. The revision
-of Guix to be used is defined by a commit or by a channel
-description file created by @command{guix describe}
-(@pxref{Invoking guix describe}).
-
-The general syntax is:
-
-@example
-guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
-@end example
-
-where @var{command} and @var{arg}@dots{} are passed unmodified to the
-@command{guix} command of the specified revision. The @var{options} that define
-this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
-
-@table @code
-@item --url=@var{url}
-@itemx --commit=@var{commit}
-@itemx --branch=@var{branch}
-Use the @code{guix} channel from the specified @var{url}, at the
-given @var{commit} (a valid Git commit ID represented as a hexadecimal
-string), or @var{branch}.
-
-@item --channels=@var{file}
-@itemx -C @var{file}
-Read the list of channels from @var{file}. @var{file} must contain
-Scheme code that evaluates to a list of channel objects.
-@xref{Channels} for more information.
-@end table
-
-As for @command{guix pull}, the absence of any options means that the
-the latest commit on the master branch will be used. The command
-
-@example
-guix time-machine -- build hello
-@end example
-
-will thus build the package @code{hello} as defined in the master branch,
-which is in general a newer revision of Guix than you have installed.
-Time travel works in both directions!
-
-Note that @command{guix time-machine} can trigger builds of channels and
-their dependencies, and these are controlled by the standard build
-options (@pxref{Common Build Options}).
-
-@node Inferiors
-@section Inferiors
-
-@c TODO: Remove this once we're more confident about API stability.
-@quotation Note
-The functionality described here is a ``technology preview'' as of version
-@value{VERSION}. As such, the interface is subject to change.
-@end quotation
-
-@cindex inferiors
-@cindex composition of Guix revisions
-Sometimes you might need to mix packages from the revision of Guix you're
-currently running with packages available in a different revision of Guix.
-Guix @dfn{inferiors} allow you to achieve that by composing different Guix
-revisions in arbitrary ways.
+@node Channel Authentication
+@section Channel Authentication
-@cindex inferior packages
-Technically, an ``inferior'' is essentially a separate Guix process connected
-to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
-@code{(guix inferior)} module allows you to create inferiors and to
-communicate with them. It also provides a high-level interface to browse and
-manipulate the packages that an inferior provides---@dfn{inferior packages}.
+@anchor{channel-authentication}
+@cindex authentication, of channel code
+The @command{guix pull} and @command{guix time-machine} commands
+@dfn{authenticate} the code retrieved from channels: they make sure each
+commit that is fetched is signed by an authorized developer. The goal
+is to protect from unauthorized modifications to the channel that would
+lead users to run malicious code.
-When combined with channels (@pxref{Channels}), inferiors provide a simple way
-to interact with a separate revision of Guix. For example, let's assume you
-want to install in your profile the current @code{guile} package, along with
-the @code{guile-json} as it existed in an older revision of Guix---perhaps
-because the newer @code{guile-json} has an incompatible API and you want to
-run your code against the old API@. To do that, you could write a manifest for
-use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
-manifest, you would create an inferior for that old Guix revision you care
-about, and you would look up the @code{guile-json} package in the inferior:
+As a user, you must provide a @dfn{channel introduction} in your
+channels file so that Guix knows how to authenticate its first commit.
+A channel specification, including its introduction, looks something
+along these lines:
@lisp
-(use-modules (guix inferior) (guix channels)
- (srfi srfi-1)) ;for 'first'
+(channel
+ (name 'some-channel)
+ (url "https://example.org/some-channel.git")
+ (introduction
+ (make-channel-introduction
+ "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
+ (openpgp-fingerprint
+ "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
+@end lisp
-(define channels
- ;; This is the old revision from which we want to
- ;; extract guile-json.
- (list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit
- "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
+The specification above shows the name and URL of the channel. The call
+to @code{make-channel-introduction} above specifies that authentication
+of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
+by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
-(define inferior
- ;; An inferior representing the above revision.
- (inferior-for-channels channels))
+For the main channel, called @code{guix}, you automatically get that
+information from your Guix installation. For other channels, include
+the channel introduction provided by the channel authors in your
+@file{channels.scm} file. Make sure you retrieve the channel
+introduction from a trusted source since that is the root of your trust.
-;; Now create a manifest with the current "guile" package
-;; and the old "guile-json" package.
-(packages->manifest
- (list (first (lookup-inferior-packages inferior "guile-json"))
- (specification->package "guile")))
-@end lisp
+If you're curious about the authentication mechanics, read on!
-On its first run, @command{guix package --manifest} might have to build the
-channel you specified before it can create the inferior; subsequent runs will
-be much faster because the Guix revision will be cached.
+@node Creating a Channel
+@section Creating a Channel
-The @code{(guix inferior)} module provides the following procedures to open an
-inferior:
+@cindex personal packages (channels)
+@cindex channels, for personal packages
+Let's say you have a bunch of custom package variants or personal packages
+that you think would make little sense to contribute to the Guix project, but
+would like to have these packages transparently available to you at the
+command line. You would first write modules containing those package
+definitions (@pxref{Package Modules}), maintain them in a Git repository, and
+then you and anyone else can use it as an additional channel to get packages
+from. Neat, no?
-@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
- [#:cache-directory] [#:ttl]
-Return an inferior for @var{channels}, a list of channels. Use the cache at
-@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
-This procedure opens a new connection to the build daemon.
+@c What follows stems from discussions at
+@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
+@c earlier discussions on guix-devel@gnu.org.
+@quotation Warning
+Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
+publish your personal channel to the world, we would like to share a few words
+of caution:
-As a side effect, this procedure may build or substitute binaries for
-@var{channels}, which can take time.
-@end deffn
+@itemize
+@item
+Before publishing a channel, please consider contributing your package
+definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
+to free software of all sorts, and packages in Guix proper are readily
+available to all Guix users and benefit from the project's quality assurance
+process.
-@deffn {Scheme Procedure} open-inferior @var{directory} @
- [#:command "bin/guix"]
-Open the inferior Guix in @var{directory}, running
-@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
-the inferior could not be launched.
-@end deffn
+@item
+When you maintain package definitions outside Guix, we, Guix developers,
+consider that @emph{the compatibility burden is on you}. Remember that
+package modules and package definitions are just Scheme code that uses various
+programming interfaces (APIs). We want to remain free to change these APIs to
+keep improving Guix, possibly in ways that break your channel. We never
+change APIs gratuitously, but we will @emph{not} commit to freezing APIs
+either.
-@cindex inferior packages
-The procedures listed below allow you to obtain and manipulate inferior
-packages.
+@item
+Corollary: if you're using an external channel and that channel breaks, please
+@emph{report the issue to the channel authors}, not to the Guix project.
+@end itemize
-@deffn {Scheme Procedure} inferior-packages @var{inferior}
-Return the list of packages known to @var{inferior}.
-@end deffn
+You've been warned! Having said this, we believe external channels are a
+practical way to exert your freedom to augment Guix' package collection and to
+share your improvements, which are basic tenets of
+@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
+email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
+@end quotation
-@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
- [@var{version}]
-Return the sorted list of inferior packages matching @var{name} in
-@var{inferior}, with highest version numbers first. If @var{version} is true,
-return only packages with a version number prefixed by @var{version}.
-@end deffn
+To create a channel, create a Git repository containing your own package
+modules and make it available. The repository can contain anything, but a
+useful channel will contain Guile modules that export packages. Once you
+start using a channel, Guix will behave as if the root directory of that
+channel's Git repository has been added to the Guile load path (@pxref{Load
+Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
+contains a file at @file{my-packages/my-tools.scm} that defines a Guile
+module, then the module will be available under the name @code{(my-packages
+my-tools)}, and you will be able to use it like any other module
+(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
-@deffn {Scheme Procedure} inferior-package? @var{obj}
-Return true if @var{obj} is an inferior package.
-@end deffn
+As a channel author, consider bundling authentication material with your
+channel so that users can authenticate it. @xref{Channel
+Authentication}, and @ref{Specifying Channel Authorizations}, for info
+on how to do it.
-@deffn {Scheme Procedure} inferior-package-name @var{package}
-@deffnx {Scheme Procedure} inferior-package-version @var{package}
-@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
-@deffnx {Scheme Procedure} inferior-package-description @var{package}
-@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
-@deffnx {Scheme Procedure} inferior-package-location @var{package}
-@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
-These procedures are the counterpart of package record accessors
-(@pxref{package Reference}). Most of them work by querying the inferior
-@var{package} comes from, so the inferior must still be live when you call
-these procedures.
-@end deffn
-Inferior packages can be used transparently like any other package or
-file-like object in G-expressions (@pxref{G-Expressions}). They are also
-transparently handled by the @code{packages->manifest} procedure, which is
-commonly use in manifests (@pxref{Invoking guix package, the
-@option{--manifest} option of @command{guix package}}). Thus you can insert
-an inferior package pretty much anywhere you would insert a regular package:
-in manifests, in the @code{packages} field of your @code{operating-system}
-declaration, and so on.
+@node Package Modules in a Sub-directory
+@section Package Modules in a Sub-directory
-@node Invoking guix describe
-@section Invoking @command{guix describe}
+@cindex subdirectory, channels
+As a channel author, you may want to keep your channel modules in a
+sub-directory. If your modules are in the sub-directory @file{guix}, you must
+add a meta-data file @file{.guix-channel} that contains:
-@cindex reproducibility
-@cindex replicating Guix
-Often you may want to answer questions like: ``Which revision of Guix am I
-using?'' or ``Which channels am I using?'' This is useful information in many
-situations: if you want to @emph{replicate} an environment on a different
-machine or user account, if you want to report a bug or to determine what
-change in the channels you are using caused it, or if you want to record your
-system state for reproducibility purposes. The @command{guix describe}
-command answers these questions.
+@lisp
+(channel
+ (version 0)
+ (directory "guix"))
+@end lisp
-When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
-displays the channel(s) that it was built from, including their repository URL
-and commit IDs (@pxref{Channels}):
+@node Declaring Channel Dependencies
+@section Declaring Channel Dependencies
-@example
-$ guix describe
-Generation 10 Sep 03 2018 17:32:44 (current)
- guix e0fa68c
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: master
- commit: e0fa68c7718fffd33d81af415279d6ddb518f727
-@end example
+@cindex dependencies, channels
+@cindex meta-data, channels
+Channel authors may decide to augment a package collection provided by other
+channels. They can declare their channel to be dependent on other channels in
+a meta-data file @file{.guix-channel}, which is to be placed in the root of
+the channel repository.
-If you're familiar with the Git version control system, this is similar in
-spirit to @command{git describe}; the output is also similar to that of
-@command{guix pull --list-generations}, but limited to the current generation
-(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
-the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
-information is all it takes to describe the revision of Guix you're using, and
-also to replicate it.
+The meta-data file should contain a simple S-expression like this:
-To make it easier to replicate Guix, @command{guix describe} can also be asked
-to return a list of channels instead of the human-readable description above:
+@lisp
+(channel
+ (version 0)
+ (dependencies
+ (channel
+ (name 'some-collection)
+ (url "https://example.org/first-collection.git")
-@example
-$ guix describe -f channels
-(list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit
- "e0fa68c7718fffd33d81af415279d6ddb518f727")
- (introduction
- (make-channel-introduction
- "9edb3f66fd807b096b48283debdcddccfea34bad"
- (openpgp-fingerprint
- "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA")))))
-@end example
+ ;; The 'introduction' bit below is optional: you would
+ ;; provide it for dependencies that can be authenticated.
+ (introduction
+ (channel-introduction
+ (version 0)
+ (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
+ (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
+ (channel
+ (name 'some-other-collection)
+ (url "https://example.org/second-collection.git")
+ (branch "testing"))))
+@end lisp
-@noindent
-You can save this to a file and feed it to @command{guix pull -C} on some
-other machine or at a later point in time, which will instantiate @emph{this
-exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
-From there on, since you're able to deploy the same revision of Guix, you can
-just as well @emph{replicate a complete software environment}. We humbly
-think that this is @emph{awesome}, and we hope you'll like it too!
+In the above example this channel is declared to depend on two other channels,
+which will both be fetched automatically. The modules provided by the channel
+will be compiled in an environment where the modules of all these declared
+channels are available.
-The details of the options supported by @command{guix describe} are as
-follows:
+For the sake of reliability and maintainability, you should avoid dependencies
+on channels that you don't control, and you should aim to keep the number of
+dependencies to a minimum.
-@table @code
-@item --format=@var{format}
-@itemx -f @var{format}
-Produce output in the specified @var{format}, one of:
+@node Specifying Channel Authorizations
+@section Specifying Channel Authorizations
-@table @code
-@item human
-produce human-readable output;
-@item channels
-produce a list of channel specifications that can be passed to @command{guix
-pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
-guix pull});
-@item channels-sans-intro
-like @code{channels}, but omit the @code{introduction} field; use it to
-produce a channel specification suitable for Guix version 1.1.0 or
-earlier---the @code{introduction} field has to do with channel
-authentication (@pxref{Channels, Channel Authentication}) and is not
-supported by these older versions;
-@item json
-@cindex JSON
-produce a list of channel specifications in JSON format;
-@item recutils
-produce a list of channel specifications in Recutils format.
-@end table
+@cindex channel authorizations
+@anchor{channel-authorizations}
+As we saw above, Guix ensures the source code it pulls from channels
+comes from authorized developers. As a channel author, you need to
+specify the list of authorized developers in the
+@file{.guix-authorizations} file in the channel's Git repository. The
+authentication rule is simple: each commit must be signed by a key
+listed in the @file{.guix-authorizations} file of its parent
+commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
+(DAG). Each commit can have zero or more parents; ``regular'' commits
+have one parent and merge commits have two parent commits. Read
+@uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
+for Computer Scientists}} for a great overview.} The
+@file{.guix-authorizations} file looks like this:
-@item --list-formats
-Display available formats for @option{--format} option.
+@lisp
+;; Example '.guix-authorizations' file.
-@item --profile=@var{profile}
-@itemx -p @var{profile}
-Display information about @var{profile}.
-@end table
+(authorizations
+ (version 0) ;current file format version
-@node Invoking guix archive
-@section Invoking @command{guix archive}
+ (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
+ (name "alice"))
+ ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
+ (name "bob"))
+ ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
+ (name "charlie"))))
+@end lisp
-@cindex @command{guix archive}
-@cindex archive
-The @command{guix archive} command allows users to @dfn{export} files
-from the store into a single archive, and to later @dfn{import} them on
-a machine that runs Guix.
-In particular, it allows store files to be transferred from one machine
-to the store on another machine.
+Each fingerprint is followed by optional key/value pairs, as in the
+example above. Currently these key/value pairs are ignored.
-@quotation Note
-If you're looking for a way to produce archives in a format suitable for
-tools other than Guix, @pxref{Invoking guix pack}.
-@end quotation
+This authentication rule creates a chicken-and-egg issue: how do we
+authenticate the first commit? Related to that: how do we deal with
+channels whose repository history contains unsigned commits and lack
+@file{.guix-authorizations}? And how do we fork existing channels?
-@cindex exporting store items
-To export store files as an archive to standard output, run:
+@cindex channel introduction
+Channel introductions answer these questions by describing the first
+commit of a channel that should be authenticated. The first time a
+channel is fetched with @command{guix pull} or @command{guix
+time-machine}, the command looks up the introductory commit and verifies
+that it is signed by the specified OpenPGP key. From then on, it
+authenticates commits according to the rule above.
-@example
-guix archive --export @var{options} @var{specifications}...
-@end example
+Additionally, your channel must provide all the OpenPGP keys that were
+ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
+files, which can be either binary or ``ASCII-armored''. By default,
+those @file{.key} files are searched for in the branch named
+@code{keyring} but you can specify a different branch name in
+@code{.guix-channel} like so:
-@var{specifications} may be either store file names or package
-specifications, as for @command{guix package} (@pxref{Invoking guix
-package}). For instance, the following command creates an archive
-containing the @code{gui} output of the @code{git} package and the main
-output of @code{emacs}:
+@lisp
+(channel
+ (version 0)
+ (keyring-reference "my-keyring-branch"))
+@end lisp
-@example
-guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
-@end example
+To summarize, as the author of a channel, there are three things you have
+to do to allow users to authenticate your code:
-If the specified packages are not built yet, @command{guix archive}
-automatically builds them. The build process may be controlled with the
-common build options (@pxref{Common Build Options}).
+@enumerate
+@item
+Export the OpenPGP keys of past and present committers with @command{gpg
+--export} and store them in @file{.key} files, by default in a branch
+named @code{keyring} (we recommend making it an @dfn{orphan branch}).
-To transfer the @code{emacs} package to a machine connected over SSH,
-one would run:
+@item
+Introduce an initial @file{.guix-authorizations} in the channel's
+repository. Do that in a signed commit (@pxref{Commit Access}, for
+information on how to sign Git commits.)
-@example
-guix archive --export -r emacs | ssh the-machine guix archive --import
-@end example
+@item
+Advertise the channel introduction, for instance on your channel's web
+page. The channel introduction, as we saw above, is the commit/key
+pair---i.e., the commit that introduced @file{.guix-authorizations}, and
+the fingerprint of the OpenPGP used to sign it.
+@end enumerate
-@noindent
-Similarly, a complete user profile may be transferred from one machine
-to another like this:
+Before pushing to your public Git repository, you can run @command{guix
+git-authenticate} to verify that you did sign all the commits you are
+about to push with an authorized key:
@example
-guix archive --export -r $(readlink -f ~/.guix-profile) | \
- ssh the-machine guix archive --import
+guix git authenticate @var{commit} @var{signer}
@end example
@noindent
-However, note that, in both examples, all of @code{emacs} and the
-profile as well as all of their dependencies are transferred (due to
-@option{-r}), regardless of what is already available in the store on
-the target machine. The @option{--missing} option can help figure out
-which items are missing from the target store. The @command{guix copy}
-command simplifies and optimizes this whole process, so this is probably
-what you should use in this case (@pxref{Invoking guix copy}).
-
-@cindex nar, archive format
-@cindex normalized archive (nar)
-Archives are stored in the ``normalized archive'' or ``nar'' format, which is
-comparable in spirit to `tar', but with differences
-that make it more appropriate for our purposes. First, rather than
-recording all Unix metadata for each file, the nar format only mentions
-the file type (regular, directory, or symbolic link); Unix permissions
-and owner/group are dismissed. Second, the order in which directory
-entries are stored always follows the order of file names according to
-the C locale collation order. This makes archive production fully
-deterministic.
+where @var{commit} and @var{signer} are your channel introduction.
+@xref{Invoking guix git authenticate}, for details.
-When exporting, the daemon digitally signs the contents of the archive,
-and that digital signature is appended. When importing, the daemon
-verifies the signature and rejects the import in case of an invalid
-signature or if the signing key is not authorized.
-@c FIXME: Add xref to daemon doc about signatures.
+Publishing a signed channel requires discipline: any mistake, such as an
+unsigned commit or a commit signed by an unauthorized key, will prevent
+users from pulling from your channel---well, that's the whole point of
+authentication! Pay attention to merges in particular: merge commits
+are considered authentic if and only if they are signed by a key present
+in the @file{.guix-authorizations} file of @emph{both} branches.
-The main options are:
+@node Primary URL
+@section Primary URL
-@table @code
-@item --export
-Export the specified store files or packages (see below). Write the
-resulting archive to the standard output.
+@cindex primary URL, channels
+Channel authors can indicate the primary URL of their channel's Git
+repository in the @file{.guix-channel} file, like so:
-Dependencies are @emph{not} included in the output, unless
-@option{--recursive} is passed.
+@lisp
+(channel
+ (version 0)
+ (url "https://example.org/guix.git"))
+@end lisp
-@item -r
-@itemx --recursive
-When combined with @option{--export}, this instructs @command{guix archive}
-to include dependencies of the given items in the archive. Thus, the
-resulting archive is self-contained: it contains the closure of the
-exported store items.
+This allows @command{guix pull} to determine whether it is pulling code
+from a mirror of the channel; when that is the case, it warns the user
+that the mirror might be stale and displays the primary URL. That way,
+users cannot be tricked into fetching code from a stale mirror that does
+not receive security updates.
-@item --import
-Read an archive from the standard input, and import the files listed
-therein into the store. Abort if the archive has an invalid digital
-signature, or if it is signed by a public key not among the authorized
-keys (see @option{--authorize} below).
+This feature only makes sense for authenticated repositories, such as
+the official @code{guix} channel, for which @command{guix pull} ensures
+the code it fetches is authentic.
-@item --missing
-Read a list of store file names from the standard input, one per line,
-and write on the standard output the subset of these files missing from
-the store.
+@node Writing Channel News
+@section Writing Channel News
-@item --generate-key[=@var{parameters}]
-@cindex signing, archives
-Generate a new key pair for the daemon. This is a prerequisite before
-archives can be exported with @option{--export}. Note that this
-operation usually takes time, because it needs to gather enough entropy
-to generate the key pair.
+@cindex news, for channels
+Channel authors may occasionally want to communicate to their users
+information about important changes in the channel. You'd send them all
+an email, but that's not convenient.
-The generated key pair is typically stored under @file{/etc/guix}, in
-@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
-key, which must be kept secret). When @var{parameters} is omitted,
-an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
-versions before 1.6.0, it is a 4096-bit RSA key.
-Alternatively, @var{parameters} can specify
-@code{genkey} parameters suitable for Libgcrypt (@pxref{General
-public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
-Libgcrypt Reference Manual}).
+Instead, channels can provide a @dfn{news file}; when the channel users
+run @command{guix pull}, that news file is automatically read and
+@command{guix pull --news} can display the announcements that correspond
+to the new commits that have been pulled, if any.
-@item --authorize
-@cindex authorizing, archives
-Authorize imports signed by the public key passed on standard input.
-The public key must be in ``s-expression advanced format''---i.e., the
-same format as the @file{signing-key.pub} file.
+To do that, channel authors must first declare the name of the news file
+in their @file{.guix-channel} file:
-The list of authorized keys is kept in the human-editable file
-@file{/etc/guix/acl}. The file contains
-@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
-s-expressions''} and is structured as an access-control list in the
-@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
-(SPKI)}.
+@lisp
+(channel
+ (version 0)
+ (news-file "etc/news.txt"))
+@end lisp
-@item --extract=@var{directory}
-@itemx -x @var{directory}
-Read a single-item archive as served by substitute servers
-(@pxref{Substitutes}) and extract it to @var{directory}. This is a
-low-level operation needed in only very narrow use cases; see below.
+The news file itself, @file{etc/news.txt} in this example, must look
+something like this:
-For example, the following command extracts the substitute for Emacs
-served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
+@lisp
+(channel-news
+ (version 0)
+ (entry (tag "the-bug-fix")
+ (title (en "Fixed terrible bug")
+ (fr "Oh la la"))
+ (body (en "@@emph@{Good news@}! It's fixed!")
+ (eo "Certe ĝi pli bone funkcias nun!")))
+ (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
+ (title (en "Added a great package")
+ (ca "Què vol dir guix?"))
+ (body (en "Don't miss the @@code@{hello@} package!"))))
+@end lisp
-@example
-$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
- | gunzip | guix archive -x /tmp/emacs
-@end example
+While the news file is using the Scheme syntax, avoid naming it with a
+@file{.scm} extension or else it will get picked up when building the
+channel and yield an error since it is not a valid module.
+Alternatively, you can move the channel module to a subdirectory and
+store the news file in another directory.
-Single-item archives are different from multiple-item archives produced
-by @command{guix archive --export}; they contain a single store item,
-and they do @emph{not} embed a signature. Thus this operation does
-@emph{no} signature verification and its output should be considered
-unsafe.
+The file consists of a list of @dfn{news entries}. Each entry is
+associated with a commit or tag: it describes changes made in this
+commit, possibly in preceding commits as well. Users see entries only
+the first time they obtain the commit the entry refers to.
-The primary purpose of this operation is to facilitate inspection of
-archive contents coming from possibly untrusted substitute servers
-(@pxref{Invoking guix challenge}).
+The @code{title} field should be a one-line summary while @code{body}
+can be arbitrarily long, and both can contain Texinfo markup
+(@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
+a list of language tag/message tuples, which allows @command{guix pull}
+to display news in the language that corresponds to the user's locale.
-@item --list
-@itemx -t
-Read a single-item archive as served by substitute servers
-(@pxref{Substitutes}) and print the list of files it contains, as in
-this example:
+If you want to translate news using a gettext-based workflow, you can
+extract translatable strings with @command{xgettext} (@pxref{xgettext
+Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
+you write news entries in English first, the command below creates a PO
+file containing the strings to translate:
@example
-$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
- | lzip -d | guix archive -t
+xgettext -o news.po -l scheme -ken etc/news.txt
@end example
-@end table
+To sum up, yes, you could use your channel as a blog. But beware, this
+is @emph{not quite} what your users might expect.
@c *********************************************************************
@item --link-profile
@itemx -P
For containers, link the environment profile to @file{~/.guix-profile}
-within the container. This is equivalent to running the command
-@samp{ln -s $GUIX_ENVIRONMENT ~/.guix-profile} within the container.
+within the container and set @code{GUIX_ENVIRONMENT} to that.
+This is equivalent to making @file{~/.guix-profile} a symlink to the
+actual profile within the container.
Linking will fail and abort the environment if the directory already
exists, which will certainly be the case if @command{guix environment}
was invoked in the user's home directory.
@vindex GUIX_EXECUTION_ENGINE
When running a wrapped program, you can explicitly request one of the
execution engines listed above by setting the
-@code{GUIX_EXECUTION_ENGINE} environment variable accordingly.
+@env{GUIX_EXECUTION_ENGINE} environment variable accordingly.
@end quotation
@cindex entry point, for Docker images
* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
+* Build Phases:: Phases of the build process of a package.
+* Build Utilities:: Helpers for your package definitions and more.
* The Store:: Manipulating the package store.
* Derivations:: Low-level interface to package derivations.
* The Store Monad:: Purely functional interface to the store.
the package you are interested in from another repository, using the
@code{guix import} command (@pxref{Invoking guix import}).
-In the example above, @var{hello} is defined in a module of its own,
+In the example above, @code{hello} is defined in a module of its own,
@code{(gnu packages hello)}. Technically, this is not strictly
necessary, but it is convenient to do so: all the packages defined in
modules under @code{(gnu packages @dots{})} are automatically known to
@item
@cindex GNU Build System
The @code{build-system} field specifies the procedure to build the
-package (@pxref{Build Systems}). Here, @var{gnu-build-system}
+package (@pxref{Build Systems}). Here, @code{gnu-build-system}
represents the familiar GNU Build System, where packages may be
configured, built, and installed with the usual @code{./configure &&
make && make check && make install} command sequence.
+When you start packaging non-trivial software, you may need tools to
+manipulate those build phases, manipulate files, and so on. @xref{Build
+Utilities}, for more on this.
+
@item
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}). Here it is interpreted by
-@var{gnu-build-system} as a request run @file{configure} with the
+@code{gnu-build-system} as a request run @file{configure} with the
@option{--enable-silent-rules} flag.
@cindex quote
@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 @var{gawk}
-variable; @
var{gawk} is itself bound to a @code{<package>} object.
+input called @code{"gawk"} whose value is that of the @code{gawk}
+variable; @
code{gawk} is itself bound to a @code{<package>} object.
@cindex backquote (quasiquote)
@findex `
Reference Manual}).
Note that GCC, Coreutils, Bash, and other essential tools do not need to
-be specified as inputs here. Instead, @var{gnu-build-system} takes care
+be specified as inputs here. Instead, @code{gnu-build-system} takes care
of ensuring that they are present (@pxref{Build Systems}).
However, any other dependencies need to be specified in the
a package is rewritten by replacing specific inputs by others:
@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
- [@var{rewrite-name}]
+ [@var{rewrite-name}] [#:deep? #t]
Return a procedure that, when passed a package, replaces its direct and
-indirect dependencies (but not its implicit inputs) according to
-@var{replacements}. @var{replacements} is a list of package pairs; the
-first element of each pair is the package to replace, and the second one
-is the replacement.
+indirect dependencies, including implicit inputs when @var{deep?} is
+true, according to @var{replacements}. @var{replacements} is a list of
+package pairs; the first element of each pair is the package to replace,
+and the second one is the replacement.
Optionally, @var{rewrite-name} is a one-argument procedure that takes
the name of a package and returns its new name after rewrite.
The following variant of @code{package-input-rewriting} can match packages to
be replaced by name rather than by identity.
-@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements}
-Return a procedure that, given a package, applies the given @var{replacements} to
-all the package graph (excluding implicit inputs). @var{replacements} is a list of
-spec/procedures pair; each spec is a package specification such as @code{"gcc"} or
-@code{"guile@@2"}, and each procedure takes a matching package and returns a
-replacement for that package.
+@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t]
+Return a procedure that, given a package, applies the given
+@var{replacements} to all the package graph, including implicit inputs
+unless @var{deep?} is false. @var{replacements} is a list of
+spec/procedures pair; each spec is a package specification such as
+@code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching
+package and returns a replacement for that package.
@end deffn
The example above could be rewritten this way:
@code{package-mapping}: it supports arbitrary changes to nodes in the
graph.
-@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
+@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] [#:deep? #f]
Return a procedure that, given a package, applies @var{proc} to all the packages
depended on and returns the resulting package. The procedure stops recursion
-when @var{cut?} returns true for a given package.
+when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is
+applied to implicit inputs as well.
@end deffn
@menu
@anchor{package-propagated-inputs}
Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
-specified packages will be automatically installed alongside the package
+specified packages will be automatically installed to profiles
+(@pxref{Features, the role of profiles in Guix}) alongside the package
they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
package}}, for information on how @command{guix package} deals with
propagated inputs).
-For example this is necessary when a C/C++ library needs headers of
-another library to compile, or when a pkg-config file refers to another
-one @i{via} its @code{Requires} field.
+For example this is necessary when packaging a C/C++ library that needs
+headers of another library to compile, or when a pkg-config file refers
+to another one @i{via} its @code{Requires} field.
Another example where @code{propagated-inputs} is useful is for languages
that lack a facility to record the run-time search path akin to the
@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
-more. To ensure that libraries written in those languages can find
-library code they depend on at run time, run-time dependencies must be
-listed in @code{propagated-inputs} rather than @code{inputs}.
+more. When packaging libraries written in those languages, ensure they
+can find library code they depend on at run time by listing run-time
+dependencies in @code{propagated-inputs} rather than @code{inputs}.
@item @code{outputs} (default: @code{'("out")})
The list of output names of the package. @xref{Packages with Multiple
It is an error to refer to @code{this-package} outside a package definition.
@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
+thereof according to some parameters. Below are a few examples.
+
+@cindex tool chain, choosing a package's tool chain
+@deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain}
+Return a variant of @var{package} that uses @var{toolchain} instead of
+the default GNU C/C++ toolchain. @var{toolchain} must be a list of
+inputs (label/package tuples) providing equivalent functionality, such
+as the @code{gcc-toolchain} package.
+
+The example below returns a variant of the @code{hello} package built
+with GCC@tie{}10.x and the rest of the GNU tool chain (Binutils and the
+GNU C Library) instead of the default tool chain:
+
+@lisp
+(let ((toolchain (specification->package "gcc-toolchain@@10")))
+ (package-with-c-toolchain hello `(("toolchain" ,toolchain))))
+@end lisp
+
+The build tool chain is part of the @dfn{implicit inputs} of
+packages---it's usually not listed as part of the various ``inputs''
+fields and is instead pulled in by the build system. Consequently, this
+procedure works by changing the build system of @var{package} so that it
+pulls in @var{toolchain} instead of the defaults. @ref{Build Systems},
+for more on build systems.
+@end deffn
+
@node origin Reference
@subsection @code{origin} Reference
-This section summarizes all the options available in @code{origin}
-declarations (@pxref{Defining Packages}).
+This section documents @dfn{origins}. An @code{origin} declaration
+specifies data that must be ``produced''---downloaded, usually---and
+whose content hash is known in advance. Origins are primarily used to
+represent the source code of packages (@pxref{Defining Packages}). For
+that reason, the @code{origin} form allows you to declare patches to
+apply to the original source code as well as code snippets to modify it.
@deftp {Data Type} origin
This is the data type representing a source code origin.
@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
values are: a URL represented as a string, or a list thereof.
-@item @code{method}
-A procedure that handles the URI.
-
-Examples include:
-
-@table @asis
-@item @var{url-fetch} from @code{(guix download)}
-download a file from the HTTP, HTTPS, or FTP URL specified in the
-@code{uri} field;
-
-@vindex git-fetch
-@item @var{git-fetch} from @code{(guix git-download)}
-clone the Git version control repository, and check out the revision
-specified in the @code{uri} field as a @code{git-reference} object; a
-@code{git-reference} looks like this:
+@cindex fixed-output derivations, for download
+@item @code{method}
+A monadic procedure that handles the given URI. The procedure must
+accept at least three arguments: the value of the @code{uri} field and
+the hash algorithm and hash value specified by the @code{hash} field.
+It must return a store item or a derivation in the store monad
+(@pxref{The Store Monad}); most methods return a fixed-output derivation
+(@pxref{Derivations}).
-@lisp
-(git-reference
- (url "https://git.savannah.gnu.org/git/hello.git")
- (commit "v2.10"))
-@end lisp
-@end table
+Commonly used methods include @code{url-fetch}, which fetches data from
+a URL, and @code{git-fetch}, which fetches data from a Git repository
+(see below).
@item @code{sha256}
A bytevector containing the SHA-256 hash of the source. This is
as ensuring that @var{value} has the right size for @var{algorithm}.
@end deftp
+As we have seen above, how exactly the data an origin refers to is
+retrieved is determined by its @code{method} field. The @code{(guix
+download)} module provides the most common method, @code{url-fetch},
+described below.
+
+@deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
+ [name] [#:executable? #f]
+Return a fixed-output derivation that fetches data from @var{url} (a
+string, or a list of strings denoting alternate URLs), which is expected
+to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,
+the file name is the base name of URL; optionally, @var{name} can
+specify a different file name. When @var{executable?} is true, make the
+downloaded file executable.
+
+When one of the URL starts with @code{mirror://}, then its host part is
+interpreted as the name of a mirror scheme, taken from @file{%mirror-file}.
+
+Alternatively, when URL starts with @code{file://}, return the
+corresponding file name in the store.
+@end deffn
+
+Likewise, the @code{(guix git-download)} module defines the
+@code{git-download} origin method, which fetches data from a Git version
+control repository, and the @code{git-reference} data type to describe
+the repository and revision to fetch.
+
+@deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
+Return a fixed-output derivation that fetches @var{ref}, a
+@code{<git-reference>} object. The output is expected to have recursive
+hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
+the file name, or a generic name if @code{#f}.
+@end deffn
+
+@deftp {Data Type} git-reference
+This data type represents a Git reference for @code{git-fetch} to
+retrieve.
+
+@table @asis
+@item @code{url}
+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.
+
+@item @code{recursive?} (default: @code{#f})
+This Boolean indicates whether to recursively fetch Git sub-modules.
+@end table
+
+The example below denotes the @code{v2.10} tag of the GNU@tie{}Hello
+repository:
+
+@lisp
+(git-reference
+ (url "https://git.savannah.gnu.org/git/hello.git")
+ (commit "v2.10"))
+@end lisp
+
+This is equivalent to the reference below, which explicitly names the
+commit:
+
+@lisp
+(git-reference
+ (url "https://git.savannah.gnu.org/git/hello.git")
+ (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
+@end lisp
+@end deftp
+
@node Build Systems
@section Build Systems
a package, which includes all the inputs of that package, including some
that were implicitly added by the build system. This intermediate
representation is then compiled to a derivation (@pxref{Derivations}).
+The @code{package-with-c-toolchain} is an example of a way to change the
+implicit inputs that a package's build system pulls in (@pxref{package
+Reference, @code{package-with-c-toolchain}}).
Build systems accept an optional list of @dfn{arguments}. In package
definitions, these are passed @i{via} the @code{arguments} field
@code{%standard-phases} is a list of symbol/procedure pairs, where the
procedure implements the actual phase.
-The list of phases used for a particular package can be changed with the
-@code{#:phases} parameter. For instance, passing:
-
-@example
-#:phases (modify-phases %standard-phases (delete 'configure))
-@end example
-
-means that all the phases described above will be used, except the
-@code{configure} phase.
+@xref{Build Phases}, for more info on build phases and ways to customize
+them.
In addition, this build system ensures that the ``standard'' environment
for GNU packages is available. This includes tools such as GCC, libc,
specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
parameters available to cargo. It will also remove an included
@code{Cargo.lock} file to be recreated by @code{cargo} during the
-@code{build} phase. The @code{install} phase installs any crate the binaries
-if they are defined by the crate.
+@code{build} phase. The @code{install} phase installs the binaries
+defined by the crate.
@end defvr
julia} packages, which essentially is similar to running @samp{julia -e
'using Pkg; Pkg.add(package)'} in an environment where
@env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
-Tests are run not run.
+Tests are run with @code{Pkg.test}.
Julia packages require the source @code{file-name} to be the real name of the
package, correctly capitalized.
@code{build-expression->derivation}}).
@end defvr
+@node Build Phases
+@section Build Phases
+
+@cindex build phases, for packages
+Almost all package build systems implement a notion @dfn{build phases}:
+a sequence of actions that the build system executes, when you build the
+package, leading to the installed byproducts in the store. A notable
+exception is the ``bare-bones'' @code{trivial-build-system}
+(@pxref{Build Systems}).
+
+As discussed in the previous section, those build systems provide a
+standard list of phases. For @code{gnu-build-system}, the standard
+phases include an @code{unpack} phase to unpack the source code tarball,
+a @command{configure} phase to run @code{./configure}, a @code{build}
+phase to run @command{make}, and (among others) an @code{install} phase
+to run @command{make install}; @pxref{Build Systems}, for a more
+detailed view of these phases. Likewise, @code{cmake-build-system}
+inherits these phases, but its @code{configure} phase runs
+@command{cmake} instead of @command{./configure}. Other build systems,
+such as @code{python-build-system}, have a wholly different list of
+standard phases. All this code runs on the @dfn{build side}: it is
+evaluated when you actually build the package, in a dedicated build
+process spawned by the build daemon (@pxref{Invoking guix-daemon}).
+
+Build phases are represented as association lists or ``alists''
+(@pxref{Association Lists,,, guile, GNU Guile Reference Manual}) where
+each key is a symbol for the name of the phase and the associated value
+is a procedure that accepts an arbitrary number of arguments. By
+convention, those procedures receive information about the build in the
+form of @dfn{keyword parameters}, which they can use or ignore.
+
+For example, here is how @code{(guix build gnu-build-system)} defines
+@code{%standard-phases}, the variable holding its alist of build
+phases@footnote{We present a simplified view of those build phases, but
+do take a look at @code{(guix build gnu-build-system)} to see all the
+details!}:
+
+@lisp
+;; The build phases of 'gnu-build-system'.
+
+(define* (unpack #:key source #:allow-other-keys)
+ ;; Extract the source tarball.
+ (invoke "tar" "xvf" source))
+
+(define* (configure #:key outputs #:allow-other-keys)
+ ;; Run the 'configure' script. Install to output "out".
+ (let ((out (assoc-ref outputs "out")))
+ (invoke "./configure"
+ (string-append "--prefix=" out))))
+
+(define* (build #:allow-other-keys)
+ ;; Compile.
+ (invoke "make"))
+
+(define* (check #:key (test-target "check") (tests? #true)
+ #:allow-other-keys)
+ ;; Run the test suite.
+ (if tests?
+ (invoke "make" test-target)
+ (display "test suite not run\n")))
+
+(define* (install #:allow-other-keys)
+ ;; Install files to the prefix 'configure' specified.
+ (invoke "make" "install"))
+
+(define %standard-phases
+ ;; The list of standard phases (quite a few are omitted
+ ;; for brevity). Each element is a symbol/procedure pair.
+ (list (cons 'unpack unpack)
+ (cons 'configure configure)
+ (cons 'build build)
+ (cons 'check check)
+ (cons 'install install)))
+@end lisp
+
+This shows how @code{%standard-phases} is defined as a list of
+symbol/procedure pairs (@pxref{Pairs,,, guile, GNU Guile Reference
+Manual}). The first pair associates the @code{unpack} procedure with
+the @code{unpack} symbol---a name; the second pair defines the
+@code{configure} phase similarly, and so on. When building a package
+that uses @code{gnu-build-system} with its default list of phases, those
+phases are executed sequentially. You can see the name of each phase
+started and completed in the build log of packages that you build.
+
+Let's now look at the procedures themselves. Each one is defined with
+@code{define*}: @code{#:key} lists keyword parameters the procedure
+accepts, possibly with a default value, and @code{#:allow-other-keys}
+specifies that other keyword parameters are ignored (@pxref{Optional
+Arguments,,, guile, GNU Guile Reference Manual}).
+
+The @code{unpack} procedure honors the @code{source} parameter, which
+the build system uses to pass the file name of the source tarball (or
+version control checkout), and it ignores other parameters. The
+@code{configure} phase only cares about the @code{outputs} parameter, an
+alist mapping package output names to their store file name
+(@pxref{Packages with Multiple Outputs}). It extracts the file name of
+for @code{out}, the default output, and passes it to
+@command{./configure} as the installation prefix, meaning that
+@command{make install} will eventually copy all the files in that
+directory (@pxref{Configuration, configuration and makefile
+conventions,, standards, GNU Coding Standards}). @code{build} and
+@code{install} ignore all their arguments. @code{check} honors the
+@code{test-target} argument, which specifies the name of the Makefile
+target to run tests; it prints a message and skips tests when
+@code{tests?} is false.
+
+@cindex build phases, customizing
+The list of phases used for a particular package can be changed with the
+@code{#:phases} parameter of the build system. Changing the set of
+build phases boils down to building a new alist of phases based on the
+@code{%standard-phases} alist described above. This can be done with
+standard alist procedures such as @code{alist-delete} (@pxref{SRFI-1
+Association Lists,,, guile, GNU Guile Reference Manual}); however, it is
+more convenient to do so with @code{modify-phases} (@pxref{Build
+Utilities, @code{modify-phases}}).
+
+Here is an example of a package definition that removes the
+@code{configure} phase of @code{%standard-phases} and inserts a new
+phase before the @code{build} phase, called
+@code{set-prefix-in-makefile}:
+
+@lisp
+(define-public example
+ (package
+ (name "example")
+ ;; other fields omitted
+ (build-system gnu-build-system)
+ (arguments
+ '(#:phases (modify-phases %standard-phases
+ (delete 'configure)
+ (add-before 'build 'set-prefix-in-makefile
+ (lambda* (#:key outputs #:allow-other-keys)
+ ;; Modify the makefile so that its
+ ;; 'PREFIX' variable points to "out".
+ (let ((out (assoc-ref outputs "out")))
+ (substitute* "Makefile"
+ (("PREFIX =.*")
+ (string-append "PREFIX = "
+ out "\n")))
+ #true))))))))
+@end lisp
+
+The new phase that is inserted is written as an anonymous procedure,
+introduced with @code{lambda*}; it honors the @code{outputs} parameter
+we have seen before. @xref{Build Utilities}, for more about the helpers
+used by this phase, and for more examples of @code{modify-phases}.
+
+@cindex code staging
+@cindex staging, of code
+Keep in mind that build phases are code evaluated at the time the
+package is actually built. This explains why the whole
+@code{modify-phases} expression above is quoted (it comes after the
+@code{'} or apostrophe): it is @dfn{staged} for later execution.
+@xref{G-Expressions}, for an explanation of code staging and the
+@dfn{code strata} involved.
+
+@node Build Utilities
+@section Build Utilities
+
+As soon as you start writing non-trivial package definitions
+(@pxref{Defining Packages}) or other build actions
+(@pxref{G-Expressions}), you will likely start looking for helpers for
+``shell-like'' actions---creating directories, copying and deleting
+files recursively, manipulating build phases, and so on. The
+@code{(guix build utils)} module provides such utility procedures.
+
+Most build systems load @code{(guix build utils)} (@pxref{Build
+Systems}). Thus, when writing custom build phases for your package
+definitions, you can usually assume those procedures are in scope.
+
+When writing G-expressions, you can import @code{(guix build utils)} on
+the ``build side'' using @code{with-imported-modules} and then put it in
+scope with the @code{use-modules} form (@pxref{Using Guile Modules,,,
+guile, GNU Guile Reference Manual}):
+
+@lisp
+(with-imported-modules '((guix build utils)) ;import it
+ (computed-file "empty-tree"
+ #~(begin
+ ;; Put it in scope.
+ (use-modules (guix build utils))
+
+ ;; Happily use its 'mkdir-p' procedure.
+ (mkdir-p (string-append #$output "/a/b/c")))))
+@end lisp
+
+The remainder of this section is the reference for most of the utility
+procedures provided by @code{(guix build utils)}.
+
+@c TODO Document what's missing.
+
+@subsection Dealing with Store File Names
+
+This section documents procedures that deal with store file names.
+
+@deffn {Scheme Procedure} %store-directory
+Return the directory name of the store.
+@end deffn
+
+@deffn {Scheme Procedure} store-file-name? @var{file}
+Return true if @var{file} is in the store.
+@end deffn
+
+@deffn {Scheme Procedure} strip-store-file-name @var{file}
+Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
+The result is typically a @code{"@var{package}-@var{version}"} string.
+@end deffn
+
+@deffn {Scheme Procedure} package-name->name+version @var{name}
+Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
+values: @code{"foo"} and @code{"0.9.1b"}. When the version part is
+unavailable, @var{name} and @code{#f} are returned. The first hyphen
+followed by a digit is considered to introduce the version part.
+@end deffn
+
+@subsection File Types
+
+The procedures below deal with files and file types.
+
+@deffn {Scheme Procedure} directory-exists? @var{dir}
+Return @code{#t} if @var{dir} exists and is a directory.
+@end deffn
+
+@deffn {Scheme Procedure} executable-file? @var{file}
+Return @code{#t} if @var{file} exists and is executable.
+@end deffn
+
+@deffn {Scheme Procedure} symbolic-link? @var{file}
+Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
+@end deffn
+
+@deffn {Scheme Procedure} elf-file? @var{file}
+@deffnx {Scheme Procedure} ar-file? @var{file}
+@deffnx {Scheme Procedure} gzip-file? @var{file}
+Return @code{#t} if @var{file} is, respectively, an ELF file, an
+@code{ar} archive (such as a @file{.a} static library), or a gzip file.
+@end deffn
+
+@deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t]
+If @var{file} is a gzip file, reset its embedded timestamp (as with
+@command{gzip --no-name}) and return true. Otherwise return @code{#f}.
+When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
+@end deffn
+
+@subsection File Manipulation
+
+The following procedures and macros help create, modify, and delete
+files. They provide functionality comparable to common shell utilities
+such as @command{mkdir -p}, @command{cp -r}, @command{rm -r}, and
+@command{sed}. They complement Guile's extensive, but low-level, file
+system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).
+
+@deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{}
+Run @var{body} with @var{directory} as the process's current directory.
+
+Essentially, this macro changes the current directory to @var{directory}
+before evaluating @var{body}, using @code{chdir} (@pxref{Processes,,,
+guile, GNU Guile Reference Manual}). It changes back to the initial
+directory when the dynamic extent of @var{body} is left, be it @i{via}
+normal procedure return or @i{via} a non-local exit such as an
+exception.
+@end deffn
+
+@deffn {Scheme Procedure} mkdir-p @var{dir}
+Create directory @var{dir} and all its ancestors.
+@end deffn
+
+@deffn {Scheme Procedure} install-file @var{file} @var{directory}
+Create @var{directory} if it does not exist and copy @var{file} in there
+under the same name.
+@end deffn
+
+@deffn {Scheme Procedure} make-file-writable @var{file}
+Make @var{file} writable for its owner.
+@end deffn
+
+@deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
+ [#:log (current-output-port)] [#:follow-symlinks? #f] [#:keep-mtime? #f]
+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.
+@end deffn
+
+@deffn {Scheme Procedure} delete-file-recursively @var{dir} @
+ [#:follow-mounts? #f]
+Delete @var{dir} recursively, like @command{rm -rf}, without following
+symlinks. Don't follow mount points either, unless @var{follow-mounts?}
+is true. Report but ignore errors.
+@end deffn
+
+@deffn {Scheme Syntax} substitute* @var{file} @
+ ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
+Substitute @var{regexp} in @var{file} by the string returned by
+@var{body}. @var{body} is evaluated with each @var{match-var} bound to
+the corresponding positional regexp sub-expression. For example:
+
+@lisp
+(substitute* file
+ (("hello")
+ "good morning\n")
+ (("foo([a-z]+)bar(.*)$" all letters end)
+ (string-append "baz" letter end)))
+@end lisp
+
+Here, anytime a line of @var{file} contains @code{hello}, it is replaced
+by @code{good morning}. Anytime a line of @var{file} matches the second
+regexp, @code{all} is bound to the complete match, @code{letters} is bound
+to the first sub-expression, and @code{end} is bound to the last one.
+
+When one of the @var{match-var} is @code{_}, no variable is bound to the
+corresponding match substring.
+
+Alternatively, @var{file} may be a list of file names, in which case
+they are all subject to the substitutions.
+
+Be careful about using @code{$} to match the end of a line; by itself it
+won't match the terminating newline of a line.
+@end deffn
+
+@subsection File Search
+
+@cindex file, searching
+This section documents procedures to search and filter files.
+
+@deffn {Scheme Procedure} file-name-predicate @var{regexp}
+Return a predicate that returns true when passed a file name whose base
+name matches @var{regexp}.
+@end deffn
+
+@deffn {Scheme Procedure} find-files @var{dir} [@var{pred}] @
+ [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f]
+Return the lexicographically sorted list of files under @var{dir} for
+which @var{pred} returns true. @var{pred} is passed two arguments: the
+absolute file name, and its stat buffer; the default predicate always
+returns true. @var{pred} can also be a regular expression, in which
+case it is equivalent to @code{(file-name-predicate @var{pred})}.
+@var{stat} is used to obtain file information; using @code{lstat} means
+that symlinks are not followed. If @var{directories?} is true, then
+directories will also be included. If @var{fail-on-error?} is true,
+raise an exception upon error.
+@end deffn
+
+Here are a few examples where we assume that the current directory is
+the root of the Guix source tree:
+
+@lisp
+;; List all the regular files in the current directory.
+(find-files ".")
+@result{} ("./.dir-locals.el" "./.gitignore" @dots{})
+
+;; List all the .scm files under gnu/services.
+(find-files "gnu/services" "\\.scm$")
+@result{} ("gnu/services/admin.scm" "gnu/services/audio.scm" @dots{})
+
+;; List ar files in the current directory.
+(find-files "." (lambda (file stat) (ar-file? file)))
+@result{} ("./libformat.a" "./libstore.a" @dots{})
+@end lisp
+
+@deffn {Scheme Procedure} which @var{program}
+Return the complete file name for @var{program} as found in
+@code{$PATH}, or @code{#f} if @var{program} could not be found.
+@end deffn
+
+@subsection Build Phases
+
+@cindex build phases
+The @code{(guix build utils)} also contains tools to manipulate build
+phases as used by build systems (@pxref{Build Systems}). Build phases
+are represented as association lists or ``alists'' (@pxref{Association
+Lists,,, guile, GNU Guile Reference Manual}) where each key is a symbol
+naming the phase and the associated value is a procedure (@pxref{Build
+Phases}).
+
+Guile core and the @code{(srfi srfi-1)} module both provide tools to
+manipulate alists. The @code{(guix build utils)} module complements
+those with tools written with build phases in mind.
+
+@cindex build phases, modifying
+@deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{}
+Modify @var{phases} sequentially as per each @var{clause}, which may
+have one of the following forms:
+
+@lisp
+(delete @var{old-phase-name})
+(replace @var{old-phase-name} @var{new-phase})
+(add-before @var{old-phase-name} @var{new-phase-name} @var{new-phase})
+(add-after @var{old-phase-name} @var{new-phase-name} @var{new-phase})
+@end lisp
+
+Where every @var{phase-name} above is an expression evaluating to a
+symbol, and @var{new-phase} an expression evaluating to a procedure.
+@end deffn
+
+The example below is taken from the definition of the @code{grep}
+package. It adds a phase to run after the @code{install} phase, called
+@code{fix-egrep-and-fgrep}. That phase is a procedure (@code{lambda*}
+is for anonymous procedures) that takes a @code{#:outputs} keyword
+argument and ignores extra keyword arguments (@pxref{Optional
+Arguments,,, guile, GNU Guile Reference Manual}, for more on
+@code{lambda*} and optional and keyword arguments.) The phase uses
+@code{substitute*} to modify the installed @file{egrep} and @file{fgrep}
+scripts so that they refer to @code{grep} by its absolute file name:
+
+@lisp
+(modify-phases %standard-phases
+ (add-after 'install 'fix-egrep-and-fgrep
+ ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
+ ;; absolute file name instead of searching for it in $PATH.
+ (lambda* (#:key outputs #:allow-other-keys)
+ (let* ((out (assoc-ref outputs "out"))
+ (bin (string-append out "/bin")))
+ (substitute* (list (string-append bin "/egrep")
+ (string-append bin "/fgrep"))
+ (("^exec grep")
+ (string-append "exec " bin "/grep")))
+ #t))))
+@end lisp
+
+In the example below, phases are modified in two ways: the standard
+@code{configure} phase is deleted, presumably because the package does
+not have a @file{configure} script or anything similar, and the default
+@code{install} phase is replaced by one that manually copies the
+executable files to be installed:
+
+@lisp
+(modify-phases %standard-phases
+ (delete 'configure) ;no 'configure' script
+ (replace 'install
+ (lambda* (#:key outputs #:allow-other-keys)
+ ;; The package's Makefile doesn't provide an "install"
+ ;; rule so do it by ourselves.
+ (let ((bin (string-append (assoc-ref outputs "out")
+ "/bin")))
+ (install-file "footswitch" bin)
+ (install-file "scythe" bin)
+ #t))))
+@end lisp
+
+@c TODO: Add more examples.
+
@node The Store
@section The Store
build the derivations; they are run by the daemon in a container
(@pxref{Invoking guix-daemon}).
+@cindex code staging
+@cindex staging, of code
@cindex strata of code
It should come as no surprise that we like to write these build actions
in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
@dfn{staging}.}: the ``host code''---code that defines packages, talks
to the daemon, etc.---and the ``build code''---code that actually
performs build actions, such as making directories, invoking
-@command{make}, etc.
+@command{make}, and so on (@pxref{Build Phases}).
To describe a derivation and its build actions, one typically needs to
embed build code inside host code. It boils down to manipulating build
@end deffn
@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
- [#:options '(#:local-build? #t)]
+ [#:local-build? #t]
+ [#:options '()]
Return an object representing the store item @var{name}, a file or
-directory computed by @var{gexp}. @var{options}
-is a list of additional arguments to pass to @code{gexp->derivation}.
+directory computed by @var{gexp}. When @var{local-build?} is true (the
+default), the derivation is built locally. @var{options} is a list of
+additional arguments to pass to @code{gexp->derivation}.
This is the declarative counterpart of @code{gexp->derivation}.
@end deffn
@code{let-system} is useful in the occasional case where the object
spliced into the gexp depends on the target system, as in this example:
-@example
+@lisp
#~(system*
#+(let-system system
(cond ((string-prefix? "armhf-" system)
(else
(error "dunno!"))))
"-net" "user" #$image)
-@end example
+@end lisp
@end deffn
@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
practically impossible for users to @emph{verify} whether third-party
binaries are genuine. @xref{Invoking guix challenge}, for more.
-Note that, currently, the differing build results are not kept around,
-so you will have to manually investigate in case of an error---e.g., by
-stashing one of the build results with @code{guix archive --export}
-(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
-the two results.
+When used in conjunction with @option{--keep-failed}, the differing
+output is kept in the store, under @file{/gnu/store/@dots{}-check}.
+This makes it easy to look for differences between the two results.
@item --no-offload
Do not use offload builds to other machines (@pxref{Daemon Offload
without having to type in the definitions of package variants
(@pxref{Defining Packages}).
+Package transformation options are preserved across upgrades:
+@command{guix upgrade} attempts to apply transformation options
+initially used when creating the profile to the upgraded packages.
+
+The available options are listed below. Most commands support them and
+also support a @option{--help-transform} option that lists all the
+available options and a synopsis (these options are not shown in the
+@option{--help} output for brevity).
+
@table @code
@item --with-source=@var{source}
@var{package}, then the resulting package may be unusable. Use with
care!
+@cindex debugging info, rebuilding
+@item --with-debug-info=@var{package}
+Build @var{package} in a way that preserves its debugging info and graft
+it onto packages that depend on it. This is useful if @var{package}
+does not already provide debugging info as a @code{debug} output
+(@pxref{Installing Debugging Files}).
+
+For example, suppose you're experiencing a crash in Inkscape and would
+like to see what's up in GLib, a library deep down in Inkscape's
+dependency graph. GLib lacks a @code{debug} output, so debugging is
+tough. Fortunately, you rebuild GLib with debugging info and tack it on
+Inkscape:
+
+@example
+guix install inkscape --with-debug-info=glib
+@end example
+
+Only GLib needs to be recompiled so this takes a reasonable amount of
+time. @xref{Installing Debugging Files}, for more info.
+
+@quotation Note
+Under the hood, this option works by passing the @samp{#:strip-binaries?
+#f} to the build system of the package of interest (@pxref{Build
+Systems}). Most build systems support that option but some do not. In
+that case, an error is raised.
+
+Likewise, if a C/C++ package is built without @code{-g} (which is rarely
+the case), debugging info will remain unavailable even when
+@code{#:strip-binaries?} is false.
+@end quotation
+
+@cindex tool chain, changing the build tool chain of a package
+@item --with-c-toolchain=@var{package}=@var{toolchain}
+This option changes the compilation of @var{package} and everything that
+depends on it so that they get built with @var{toolchain} instead of the
+default GNU tool chain for C/C++.
+
+Consider this example:
+
+@example
+guix build octave-cli \
+ --with-c-toolchain=fftw=gcc-toolchain@@10 \
+ --with-c-toolchain=fftwf=gcc-toolchain@@10
+@end example
+
+The command above builds a variant of the @code{fftw} and @code{fftwf}
+packages using version 10 of @code{gcc-toolchain} instead of the default
+tool chain, and then builds a variant of the GNU@tie{}Octave
+command-line interface using them. GNU@tie{}Octave itself is also built
+with @code{gcc-toolchain@@10}.
+
+This other example builds the Hardware Locality (@code{hwloc}) library
+and its dependents up to @code{intel-mpi-benchmarks} with the Clang C
+compiler:
+
+@example
+guix build --with-c-toolchain=hwloc=clang-toolchain \
+ intel-mpi-benchmarks
+@end example
+
+@quotation Note
+There can be application binary interface (ABI) incompatibilities among
+tool chains. This is particularly true of the C++ standard library and
+run-time support libraries such as that of OpenMP. By rebuilding all
+dependents with the same tool chain, @option{--with-c-toolchain} minimizes
+the risks of incompatibility but cannot entirely eliminate them. Choose
+@var{package} wisely.
+@end quotation
+
@item --with-git-url=@var{package}=@var{url}
@cindex Git, using the latest commit
@cindex latest commit, building
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.
+
+@cindex test suite, skipping
+@item --without-tests=@var{package}
+Build @var{package} without running its tests. This can be useful in
+situations where you want to skip the lengthy test suite of a
+intermediate package, or if a package's test suite fails in a
+non-deterministic fashion. It should be used with care because running
+the test suite is a good way to ensure a package is working as intended.
+
+Turning off tests leads to a different store item. Consequently, when
+using this option, anything that depends on @var{package} must be
+rebuilt, as in this example:
+
+@example
+guix install --without-tests=python python-notebook
+@end example
+
+The command above installs @code{python-notebook} on top of
+@code{python} built without running its test suite. To do so, it also
+rebuilds everything that depends on @code{python}, including
+@code{python-notebook} itself.
+
+Internally, @option{--without-tests} relies on changing the
+@code{#:tests?} option of a package's @code{check} phase (@pxref{Build
+Systems}). Note that some packages use a customized @code{check} phase
+that does not respect a @code{#:tests? #f} setting. Therefore,
+@option{--without-tests} has no effect on these packages.
+
@end table
@node Additional Build Options
When @option{--archive=bioconductor} is added, metadata is imported from
@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
-packages for for the analysis and comprehension of high-throughput
+packages for the analysis and comprehension of high-throughput
genomic data in bioinformatics.
Information is extracted from the @file{DESCRIPTION} file contained in the
(guix-service-type config =>
(guix-configuration
(inherit config)
- (use-substitutes? #f)
- (extra-options '("--gc-keep-derivations"))))
+ ;; Fetch substitutes from example.org.
+ (substitute-urls
+ (list "https://example.org/guix"
+ "https://ci.guix.gnu.org"))))
(mingetty-service-type config =>
(mingetty-configuration
- (inherit config)))))
+ (inherit config)
+ ;; Automatially log in as "guest".
+ (auto-login "guest")))))
(operating-system
;; @dots{}
``root'' account with UID@tie{}0 is automatically added.
@item @code{skeletons} (default: @code{(default-skeletons)})
-A list target file name/file-like object tuples (@pxref{G-Expressions,
+A list of target file name/file-like object tuples (@pxref{G-Expressions,
file-like objects}). These are the skeleton files that will be added to
the home directory of newly-created user accounts.
displayed when users log in on a text console.
@item @code{packages} (default: @code{%base-packages})
-The set of packages installed in the global profile, which is accessible
-at @file{/run/current-system/profile}.
+A list of packages to be installed in the global profile, which is accessible
+at @file{/run/current-system/profile}. Each element is either a package
+variable or a package/output tuple. Here's a simple example of both:
+
+@lisp
+(cons* git ; the default "out" output
+ (list git "send-email") ; another output of git
+ %base-packages) ; the default set
+@end lisp
The default set includes core utilities and it is good practice to
install non-core utilities in user profiles (@pxref{Invoking guix
@item @code{create-mount-point?} (default: @code{#f})
When true, the mount point is created if it does not exist yet.
+@item @code{mount-may-fail?} (default: @code{#f})
+When true, this indicates that mounting this file system can fail but
+that should not be considered an error. This is useful in unusual
+cases; an example of this is @code{efivarfs}, a file system that can
+only be mounted on EFI/UEFI systems.
+
@item @code{dependencies} (default: @code{'()})
This is a list of @code{<file-system>} or @code{<mapped-device>} objects
representing file systems that must be mounted or mapped devices that
@end table
@end deftp
+@deffn {Scheme Procedure} file-system-label @var{str}
+This procedure returns an opaque file system label from @var{str}, a
+string:
+
+@lisp
+(file-system-label "home")
+@result{} #<file-system-label "home">
+@end lisp
+
+File system labels are used to refer to file systems by label rather
+than by device name. See above for examples.
+@end deffn
+
The @code{(gnu system file-systems)} exports the following useful
variables.
@code{fuse.ko} kernel module to be loaded.
@end defvr
+The @code{(gnu system uuid)} module provides tools to deal with file
+system ``unique identifiers'' (UUIDs).
+
+@deffn {Scheme Procedure} uuid @var{str} [@var{type}]
+Return an opaque UUID (unique identifier) object of the given @var{type}
+(a symbol) by parsing @var{str} (a string):
+
+@lisp
+(uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")
+@result{} #<<uuid> type: dce bv: @dots{}>
+
+(uuid "1234-ABCD" 'fat)
+@result{} #<<uuid> type: fat bv: @dots{}>
+@end lisp
+
+@var{type} may be one of @code{dce}, @code{iso9660}, @code{fat},
+@code{ntfs}, or one of the commonly found synonyms for these.
+
+UUIDs are another way to unambiguously refer to file systems in
+operating system configuration. See the examples above.
+@end deffn
+
+
@node Btrfs file system
@subsection Btrfs file system
"audio" ;sound card
"video" ;video devices such as webcams
"cdrom")) ;the good ol' CD-ROM
- (comment "Bob's sister")
- (home-directory "/home/alice"))
+ (comment "Bob's sister"))
+@end lisp
+
+Here's a user account that uses a different shell and a custom home
+directory (the default would be @file{"/home/bob"}):
+
+@lisp
+(user-account
+ (name "bob")
+ (group "users")
+ (comment "Alice's bro")
+ (shell (file-append zsh "/bin/zsh"))
+ (home-directory "/home/robert"))
@end lisp
When booting or upon completion of @command{guix system reconfigure},
@item @code{shell} (default: Bash)
This is a G-expression denoting the file name of a program to be used as
-the shell (@pxref{G-Expressions}).
+the shell (@pxref{G-Expressions}). For example, you would refer to the
+Bash executable like this:
+
+@lisp
+(file-append bash "/bin/bash")
+@end lisp
+
+@noindent
+... and to the Zsh executable like that:
+
+@lisp
+(file-append zsh "/bin/zsh")
+@end lisp
@item @code{system?} (default: @code{#f})
This Boolean value indicates whether the account is a ``system''
@item @code{wpa-supplicant} (default: @code{wpa-supplicant})
The WPA Supplicant package to use.
-@item @code{requirement} (default: @code{'(user-processes dbus-system loopback syslogd)}
+@item @code{requirement} (default: @code{'(user-processes loopback syslogd)}
List of services that should be started before WPA Supplicant starts.
@item @code{dbus?} (default: @code{#t})
This is the configuration record for OpenSSH's @command{sshd}.
@table @asis
+@item @code{openssh} (default @var{openssh})
+The Openssh package to use.
+
@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
Name of the file where @command{sshd} writes its PID.
The maximum number of times SSH may be (re)started before AutoSSH exits.
When set to @code{#f}, no maximum is configured and AutoSSH may restart indefinitely.
-@item @code{message} (default @code{""})
-The message to append to the echo message sent when testing connections.
+@item @code{message} (default @code{""})
+The message to append to the echo message sent when testing connections.
+
+@item @code{port} (default @code{"0"})
+The ports used for monitoring the connection. When set to @code{"0"},
+monitoring is disabled. When set to @code{"@var{n}"} where @var{n} is
+a positive integer, ports @var{n} and @var{n}+1 are used for
+monitoring the connection, such that port @var{n} is the base
+monitoring port and @code{n+1} is the echo port. When set to
+@code{"@var{n}:@var{m}"} where @var{n} and @var{m} are positive
+integers, the ports @var{n} and @var{m} are used for monitoring the
+connection, such that port @var{n} is the base monitoring port and
+@var{m} is the echo port.
+
+@item @code{ssh-options} (default @code{'()})
+The list of command-line arguments to pass to @command{ssh} when it is
+run. Options @option{-f} and @option{-M} are reserved for AutoSSH and
+may cause undefined behaviour.
+
+@end table
+@end deftp
+
+@cindex WebSSH
+@deffn {Scheme Variable} webssh-service-type
+This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH}
+program that runs a web SSH client. WebSSH can be run manually from the
+command-line by passing arguments to the binary @command{wssh} from the
+package @code{webssh}, but it can also be run as a Guix service. This
+latter use case is documented here.
+
+For example, to specify a service running WebSSH on loopback interface
+on port @code{8888} with reject policy with a list of allowed to
+connection hosts, and NGINX as a reverse-proxy to this service listening
+for HTTPS connection, add this call to the operating system's
+@code{services} field:
+
+@lisp
+(service webssh-service-type
+ (webssh-configuration (address "127.0.0.1")
+ (port 8888)
+ (policy 'reject)
+ (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
+ "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))
+
+(service nginx-service-type
+ (nginx-configuration
+ (server-blocks
+ (list
+ (nginx-server-configuration
+ (inherit %webssh-configuration-nginx)
+ (server-name '("webssh.example.com"))
+ (listen '("443 ssl"))
+ (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
+ (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
+ (locations
+ (cons (nginx-location-configuration
+ (uri "/.well-known")
+ (body '("root /var/www;")))
+ (nginx-server-configuration-locations %webssh-configuration-nginx))))))))
+@end lisp
+@end deffn
+
+@deftp {Data Type} webssh-configuration
+Data type representing the configuration for @code{webssh-service}.
+
+@table @asis
+@item @code{package} (default: @var{webssh})
+@code{webssh} package to use.
+
+@item @code{user-name} (default: @var{"webssh"})
+User name or user ID that file transfers to and from that module should take
+place.
+
+@item @code{group-name} (default: @var{"webssh"})
+Group name or group ID that will be used when accessing the module.
+
+@item @code{address} (default: @var{#f})
+IP address on which @command{webssh} listens for incoming connections.
+
+@item @code{port} (default: @var{8888})
+TCP port on which @command{webssh} listens for incoming connections.
+
+@item @code{policy} (default: @var{#f})
+Connection policy. @var{reject} policy requires to specify @var{known-hosts}.
+
+@item @code{known-hosts} (default: @var{'()})
+List of hosts which allowed for SSH connection from @command{webssh}.
-@item @code{port} (default @code{"0"})
-The ports used for monitoring the connection. When set to @code{"0"},
-monitoring is disabled. When set to @code{"@var{n}"} where @var{n} is
-a positive integer, ports @var{n} and @var{n}+1 are used for
-monitoring the connection, such that port @var{n} is the base
-monitoring port and @code{n+1} is the echo port. When set to
-@code{"@var{n}:@var{m}"} where @var{n} and @var{m} are positive
-integers, the ports @var{n} and @var{n}+1 are used for monitoring the
-connection, such that port @var{n} is the base monitoring port and
-@var{m} is the echo port.
+@item @code{log-file} (default: @file{"/var/log/webssh.log"})
+Name of the file where @command{rsync} writes its log file.
-@item @code{ssh-options} (default @code{'()})
-The list of command-line arguments to pass to @command{ssh} when it is
-run. Options @option{-f} and @option{-M} are reserved for AutoSSH and
-may cause undefined behaviour.
+@item @code{log-level} (default: @var{#f})
+Logging level.
@end table
@end deftp
(@pxref{Channels}). By default, the tip of the official @code{guix}
channel is used.
+@item @code{operating-system-file} (default: @code{"/run/current-system/configuration.scm"})
+This field specifies the operating system configuration file to use.
+The default is to reuse the config file of the current configuration.
+
+There are cases, though, where referring to
+@file{/run/current-system/configuration.scm} is not enough, for instance
+because that file refers to extra files (SSH public keys, extra
+configuration files, etc.) @i{via} @code{local-file} and similar
+constructs. For those cases, we recommend something along these lines:
+
+@lisp
+(unattended-upgrade-configuration
+ (operating-system-file
+ (file-append (local-file "." "config-dir" #:recursive? #t)
+ "/config.scm")))
+@end lisp
+
+The effect here is to import all of the current directory into the
+store, and to refer to @file{config.scm} within that directory.
+Therefore, uses of @code{local-file} within @file{config.scm} will work
+as expected. @xref{G-Expressions}, for information about
+@code{local-file} and @code{file-append}.
+
@item @code{services-to-restart} (default: @code{'(mcron)})
This field specifies the Shepherd services to restart when the upgrade
completes.
Reference, @code{services}}).
Additionally, the @code{gnome-desktop-service-type},
-@code{xfce-desktop-service}, @code{mate-desktop-service-type} and
-@code{enlightenment-desktop-service-type} procedures can add GNOME, Xfce, MATE
-and/or Enlightenment to a system. To ``add GNOME'' means that system-level
-services like the backlight adjustment helpers and the power management
-utilities are added to the system, extending @code{polkit} and @code{dbus}
-appropriately, allowing GNOME to operate with elevated privileges on a
-limited number of special-purpose system interfaces. Additionally,
-adding a service made by @code{gnome-desktop-service-type} adds the GNOME
-metapackage to the system profile. Likewise, adding the Xfce service
-not only adds the @code{xfce} metapackage to the system profile, but it
-also gives the Thunar file manager the ability to open a ``root-mode''
-file management window, if the user authenticates using the
-administrator's password via the standard polkit graphical interface.
-To ``add MATE'' means that @code{polkit} and @code{dbus} are extended
-appropriately, allowing MATE to operate with elevated privileges on a
-limited number of special-purpose system interfaces. Additionally,
-adding a service of type @code{mate-desktop-service-type} adds the MATE
-metapackage to the system profile. ``Adding Enlightenment'' means that
-@code{dbus} is extended appropriately, and several of Enlightenment's binaries
-are set as setuid, allowing Enlightenment's screen locker and other
-functionality to work as expected.
+@code{xfce-desktop-service}, @code{mate-desktop-service-type},
+@code{lxqt-desktop-service-type} and @code{enlightenment-desktop-service-type}
+procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To
+``add GNOME'' means that system-level services like the backlight adjustment
+helpers and the power management utilities are added to the system, extending
+@code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with
+elevated privileges on a limited number of special-purpose system interfaces.
+Additionally, adding a service made by @code{gnome-desktop-service-type} adds
+the GNOME metapackage to the system profile. Likewise, adding the Xfce
+service not only adds the @code{xfce} metapackage to the system profile, but
+it also gives the Thunar file manager the ability to open a ``root-mode'' file
+management window, if the user authenticates using the administrator's
+password via the standard polkit graphical interface. To ``add MATE'' means
+that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE
+to operate with elevated privileges on a limited number of special-purpose
+system interfaces. Additionally, adding a service of type
+@code{mate-desktop-service-type} adds the MATE metapackage to the system
+profile. ``Adding Enlightenment'' means that @code{dbus} is extended
+appropriately, and several of Enlightenment's binaries are set as setuid,
+allowing Enlightenment's screen locker and other functionality to work as
+expected.
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
@end table
@end deftp
+@deffn {Scheme Variable} lxqt-desktop-service-type
+This is the type of the service that runs the @uref{https://lxqt.github.io,
+LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
+object (see below).
+
+This service adds the @code{lxqt} package to the system
+profile.
+@end deffn
+
+@deftp {Data Type} lxqt-desktop-configuration
+Configuration record for the LXQt desktop environment.
+
+@table @asis
+@item @code{lxqt} (default: @code{lxqt})
+The LXQT package to use.
+@end table
+@end deftp
+
@deffn {Scheme Variable} enlightenment-desktop-service-type
Return a service that adds the @code{enlightenment} package to the system
profile, and extends dbus with actions from @code{efl}.
@code{suspend}
@item handle-lid-switch-docked
@code{ignore}
+@item handle-lid-switch-external-power
+@code{ignore}
@item power-key-ignore-inhibited?
@code{#f}
@item suspend-key-ignore-inhibited?
@var{client-conf}.
@item @var{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
-Script file to use as as @file{default.pa}.
+Script file to use as @file{default.pa}.
@item @var{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
-Script file to use as as @file{system.pa}.
+Script file to use as @file{system.pa}.
@end table
@end deftp
@cindex SQL
The @code{(gnu services databases)} module provides the following services.
-@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
- [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @
- [#:port 5432] [#:locale ``en_US.utf8''] [#:extension-packages '()]
-Return a service that runs @var{postgresql}, the PostgreSQL database
-server.
+@subsubheading PostgreSQL
+
+The following example describes a PostgreSQL service with the default
+configuration.
+
+@lisp
+(service postgresql-service-type
+ (postgresql-configuration
+ (postgresql postgresql-10)))
+@end lisp
+
+If the services fails to start, it may be due to an incompatible
+cluster already present in @var{data-directory}. Adjust it (or, if you
+don't need the cluster anymore, delete @var{data-directory}), then
+restart the service.
+
+Peer authentication is used by default and the @code{postgres} user
+account has no shell, which prevents the direct execution of @code{psql}
+commands as this user. To use @code{psql}, you can temporarily log in
+as @code{postgres} using a shell, create a PostgreSQL superuser with the
+same name as one of the system users and then create the associated
+database.
+
+@example
+sudo -u postgres -s /bin/sh
+createuser --interactive
+createdb $MY_USER_LOGIN # Replace appropriately.
+@end example
+
+@deftp {Data Type} postgresql-configuration
+Data type representing the configuration for the
+@code{postgresql-service-type}.
+
+@table @asis
+@item @var{postgresql}
+PostgreSQL package to use for the service.
+
+@item @var{port} (default: @code{5432})
+Port on which PostgreSQL should listen.
+
+@item @var{locale} (default: @code{"en_US.utf8"})
+Locale to use as the default when creating the database cluster.
-The PostgreSQL daemon loads its runtime configuration from @var{config-file},
-creates a database cluster with @var{locale} as the default
-locale, stored in @var{data-directory}. It then listens on @var{port}.
+@item @var{config-file} (default: @code{(postgresql-config-file)})
+The configuration file to use when running PostgreSQL. The default
+behaviour uses the postgresql-config-file record with the default values
+for the fields.
+@item @var{data-directory} (default: @code{"/var/lib/postgresql/data"})
+Directory in which to store the data.
+
+@item @var{extension-packages} (default: @code{'()})
@cindex postgresql extension-packages
Additional extensions are loaded from packages listed in
@var{extension-packages}. Extensions are available at runtime. For instance,
There is no need to add this field for contrib extensions such as hstore or
dblink as they are already loadable by postgresql. This field is only
required to add extensions provided by other packages.
-@end deffn
+
+@end table
+@end deftp
+
+@subsubheading MariaDB/MySQL
@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)]
Return a service that runs @command{mysqld}, the MySQL or MariaDB
@end table
@end deftp
+@subsubheading Memcached
+
@defvr {Scheme Variable} memcached-service-type
This is the service type for the @uref{https://memcached.org/,
Memcached} service, which provides a distributed in memory cache. The
@end table
@end deftp
+@subsubheading MongoDB
+
@defvr {Scheme Variable} mongodb-service-type
This is the service type for @uref{https://www.mongodb.com/, MongoDB}.
The value for the service type is a @code{mongodb-configuration} object.
@end table
@end deftp
+@subsubheading Redis
+
@defvr {Scheme Variable} redis-service-type
This is the service type for the @uref{https://redis.io/, Redis}
key/value store, whose value is a @code{redis-configuration} object.
@cindex jabber
@cindex XMPP
The @code{(gnu services messaging)} module provides Guix service
-definitions for messaging services: currently only Prosody is supported.
+definitions for messaging services. Currently it provides the following
+services:
@subsubheading Prosody Service
@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string curve
-Curve for Elliptic curve Diffie-Hellman. Prosody's default is
+Curve for Elliptic curve Diffie-Hellman. Prosody's default is
@samp{"secp384r1"}.
@end deftypevr
(modules
(list
(file-append nginx-accept-language-module "\
-/etc/nginx/modules/ngx_http_accept_language_module.so")))
+/etc/nginx/modules/ngx_http_accept_language_module.so")
+ (file-append nginx-lua-module "\
+/etc/nginx/modules/ngx_http_lua_module.so")))
+@end lisp
+
+@item @code{lua-package-path} (default: @code{'()})
+List of nginx lua packages to load. This should be a list of package
+names of loadable lua modules, as in this example:
+
+@lisp
+(lua-package-path (list lua-resty-core
+ lua-resty-lrucache
+ lua-resty-signal
+ lua-tablepool
+ lua-resty-shell))
+@end lisp
+
+@item @code{lua-package-cpath} (default: @code{'()})
+List of nginx lua C packages to load. This should be a list of package
+names of loadable lua C modules, as in this example:
+
+@lisp
+(lua-package-cpath (list lua-resty-signal))
@end lisp
@item @code{global-directives} (default: @code{'((events . ()))})
@item @code{file} (default @code{#f})
An optional override of the whole configuration.
You can use the @code{mixed-text-file} function or an absolute filepath for it.
+@item @code{php-ini-file} (default @code{#f})
+An optional override of the default php settings.
+It may be any ``file-like'' object (@pxref{G-Expressions, file-like objects}).
+You can use the @code{mixed-text-file} function or an absolute filepath for it.
+
+For local development it is useful to set a higher timeout and memory
+limit for spawned php processes. This be accomplished with the
+following operating system configuration snippet:
+@lisp
+(define %local-php-ini
+ (plain-file "php.ini"
+ "memory_limit = 2G
+max_execution_time = 1800"))
+
+(operating-system
+ ;; @dots{}
+ (services (cons (service php-fpm-service-type
+ (php-fpm-configuration
+ (php-ini-file %local-php-ini)))
+ %base-services)))
+@end lisp
+
+Consult the @url{https://www.php.net/manual/en/ini.core.php,core php.ini
+directives} for comprehensive documentation on the acceptable
+@file{php.ini} directives.
@end table
@end deftp
certificates and request signatures. Each certificate has a @code{name}
and several @code{domains}.
-@item @code{email}
-Mandatory email used for registration, recovery contact, and important
-account notifications.
+@item @code{email} (default: @code{#f})
+Optional email address used for registration and recovery contact.
+Setting this is encouraged as it allows you to receive important
+notifications about the account and issued certificates.
@item @code{server} (default: @code{#f})
Optional URL of ACME server. Setting this overrides certbot's default,
@table @asis
@item @code{id} (default: @code{""})
-An identifier for ether configuration fields to refer to this key. IDs must be
+An identifier for other configuration fields to refer to this key. IDs must be
unique and must not be empty.
@item @code{address} (default: @code{'()})
@item @code{negative-cache?} (default: @code{#t})
When false, disable negative caching.
+@item @code{tftp-enable?} (default: @code{#f})
+Whether to enable the built-in TFTP server.
+
+@item @code{tftp-no-fail?} (default: @code{#f})
+If true, does not fail dnsmasq if the TFTP server could not start up.
+
+@item @code{tftp-single-port?} (default: @code{#f})
+Whether to use only one single port for TFTP.
+
+@item @code{tftp-secure?} (default: @code{#f})
+If true, only files owned by the user running the dnsmasq process are accessible.
+
+If dnsmasq is being run as root, different rules apply:
+@code{tftp-secure?} has no effect, but only files which have the
+world-readable bit set are accessible.
+
+@item @code{tftp-max} (default: @code{#f})
+If set, sets the maximal number of concurrent connections allowed.
+
+@item @code{tftp-mtu} (default: @code{#f})
+If set, sets the MTU for TFTP packets to that value.
+
+@item @code{tftp-no-blocksize?} (default: @code{#f})
+If true, stops the TFTP server from negotiating the blocksize with a client.
+
+@item @code{tftp-lowercase?} (default: @code{#f})
+Whether to convert all filenames in TFTP requests to lowercase.
+
+@item @code{tftp-port-range} (default: @code{#f})
+If set, fixes the dynamical ports (one per client) to the given range
+(@code{"<start>,<end>"}).
+
+@item @code{tftp-root} (default: @code{/var/empty,lo})
+Look for files to transfer using TFTP relative to the given directory.
+When this is set, TFTP paths which include ".." are rejected, to stop clients
+getting outside the specified root. Absolute paths (starting with /) are
+allowed, but they must be within the tftp-root. If the optional interface
+argument is given, the directory is only used for TFTP requests via that
+interface.
+
+@item @code{tftp-unique-root} (default: @code{#f})
+If set, add the IP or hardware address of the TFTP client as a path component
+on the end of the TFTP-root. Only valid if a TFTP root is set and the
+directory exists. Defaults to adding IP address (in standard dotted-quad
+format).
+
+For instance, if --tftp-root is "/tftp" and client 1.2.3.4 requests file
+"myfile" then the effective path will be "/tftp/1.2.3.4/myfile" if
+/tftp/1.2.3.4 exists or /tftp/myfile otherwise. When "=mac" is specified
+it will append the MAC address instead, using lowercase zero padded digits
+separated by dashes, e.g.: 01-02-03-04-aa-bb Note that resolving MAC
+addresses is only possible if the client is in the local network or obtained
+a DHCP lease from dnsmasq.
+
@end table
@end deftp
@item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
Location of the log file used by the web interface.
+@item @code{queries-log-file} (default: @code{#f})
+Location of the SQL queries log file. By default, SQL queries logging is
+disabled.
+
+@item @code{web-queries-log-file} (default: @code{#f})
+Location of the web SQL queries log file. By default, web SQL queries
+logging is disabled.
+
@item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
Location of the repository cache.
@uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
@deffn {Scheme Variable} tlp-service-type
-The service type for the TLP tool. Its value should be a valid
-TLP configuration (see below). To use the default settings, simply
-write:
+The service type for the TLP tool. The default settings are optimised
+for battery life on most systems, but you can tweak them to your heart's
+content by adding a valid @code{tlp-configuration}:
@lisp
-(service tlp-service-type)
+(service tlp-service-type
+ (tlp-configuration
+ (cpu-scaling-governor-on-ac (list "performance"))
+ (sched-powersave-on-bat? #t)))
@end lisp
@end deffn
-By default TLP does not need much configuration but most TLP parameters
-can be tweaked using @code{tlp-configuration}.
-
Each parameter definition is preceded by its type; for example,
@samp{boolean foo} indicates that the @code{foo} parameter
should be specified as a boolean. Types starting with
effect; this can be used as a trick to implement an external mixer
External Mixer) or no mixer (@code{none}).
-@item @code{extra-options} (default: @code{'()"})
+@item @code{extra-options} (default: @code{'()})
An association list of option symbols to string values to be appended to
the audio output configuration.
@node Virtualization Services
-@subsection Virtualization services
+@subsection Virtualization Services
The @code{(gnu services virtualization)} module provides services for
the libvirt and virtlog daemons, as well as other virtualization-related
services.
@subsubheading Libvirt daemon
+
@code{libvirtd} is the server side daemon component of the libvirt
virtualization management system. This daemon runs on host servers
and performs required management tasks for virtualized guests.
@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
Flag listening for secure TLS connections on the public TCP/IP port.
-must set @code{listen} for this to have any effect.
+You must set @code{listen} for this to have any effect.
It is necessary to setup a CA and issue server certificates before using
this capability.
@end deftypevr
@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
-Listen for unencrypted TCP connections on the public TCP/IP port. must
+Listen for unencrypted TCP connections on the public TCP/IP port. You must
set @code{listen} for this to have any effect.
Using the TCP socket requires SASL authentication by default. Only SASL
mechanisms which support data encryption are allowed. This is
-DIGEST_MD5 and GSSAPI (Kerberos5)
+DIGEST_MD5 and GSSAPI (Kerberos5).
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{libvirt-configuration} parameter} string tls-port
-Port for accepting secure TLS connections This can be a port number, or
-service name
+Port for accepting secure TLS connections. This can be a port number,
+or service name.
Defaults to @samp{"16514"}.
@end deftypevr
@deftypevr {@code{libvirt-configuration} parameter} string tcp-port
-Port for accepting insecure TCP connections This can be a port number,
-or service name
+Port for accepting insecure TCP connections. This can be a port number,
+or service name.
Defaults to @samp{"16509"}.
Logging filters.
A filter allows to select a different logging level for a given category
-of logs The format for a filter is one of:
+of logs. The format for a filter is one of:
@itemize @bullet
@item
@end deftypevr
+@anchor{transparent-emulation-qemu}
@subsubheading Transparent Emulation with QEMU
@cindex emulation
it allows you to transparently execute an ARMv7 program on an x86_64
machine. It achieves this by combining the @uref{https://www.qemu.org,
QEMU} emulator and the @code{binfmt_misc} feature of the kernel Linux.
+This feature only allows you to emulate GNU/Linux on a different
+architecture, but see below for GNU/Hurd support.
@defvr {Scheme Variable} qemu-binfmt-service-type
This is the type of the QEMU/binfmt service for transparent emulation.
@cindex @code{hurd}
@cindex the Hurd
+@cindex childhurd
Service @code{hurd-vm} provides support for running GNU/Hurd in a
-virtual machine (VM), a so-called ``Childhurd''. The virtual machine is
-a Shepherd service that can be referred to by the names @code{hurd-vm}
-and @code{childhurd} and be controlled with commands such as:
+virtual machine (VM), a so-called @dfn{childhurd}. This service is meant
+to be used on GNU/Linux and the given GNU/Hurd operating system
+configuration is cross-compiled. The virtual machine is a Shepherd
+service that can be referred to by the names @code{hurd-vm} and
+@code{childhurd} and be controlled with commands such as:
@example
herd start hurd-vm
herd stop childhurd
@end example
-The given GNU/Hurd operating system configuration is cross-compiled.
+When the service is running, you can view its console by connecting to
+it with a VNC client, for example with:
+
+@example
+guix environment --ad-hoc tigervnc-client -- \
+ vncviewer localhost:5900
+@end example
+
+The default configuration (see @code{hurd-vm-configuration} below)
+spawns a secure shell (SSH) server in your GNU/Hurd system, which QEMU
+(the virtual machine emulator) redirects to port 10222 on the host.
+Thus, you can connect over SSH to the childhurd with:
+
+@example
+ssh root@@localhost -p 10022
+@end example
+
+The childhurd is volatile and stateless: it starts with a fresh root
+file system every time you restart it. By default though, all the files
+under @file{/etc/childhurd} on the host are copied as is to the root
+file system of the childhurd when it boots. This allows you to
+initialize ``secrets'' inside the VM: SSH host keys, authorized
+substitute keys, and so on---see the explanation of @code{secret-root}
+below.
@defvr {Scheme Variable} hurd-vm-service-type
This is the type of the Hurd in a Virtual Machine service. Its value
@lisp
'("--device" "rtl8139,netdev=net0"
"--netdev" "user,id=net0\
- ,hostfwd=tcp:127.0.0.1:<ssh-port>-:2222\
- ,hostfwd=tcp:127.0.0.1:<vnc-port>-:5900")
+ ,hostfwd=tcp:127.0.0.1:@var{secrets-port}-:1004\
+ ,hostfwd=tcp:127.0.0.1:@var{ssh-port}-:2222\
+ ,hostfwd=tcp:127.0.0.1:@var{vnc-port}-:5900")
@end lisp
-with forwarded ports
+
+with forwarded ports:
+
+@example
+@var{secrets-port}: @code{(+ 11004 (* 1000 @var{ID}))}
+@var{ssh-port}: @code{(+ 10022 (* 1000 @var{ID}))}
+@var{vnc-port}: @code{(+ 15900 (* 1000 @var{ID}))}
+@end example
+
+@item @code{secret-root} (default: @file{/etc/childhurd})
+The root directory with out-of-band secrets to be installed into the
+childhurd once it runs. Childhurds are volatile which means that on
+every startup, secrets such as the SSH host keys and Guix signing key
+are recreated.
+
+If the @file{/etc/childhurd} directory does not exist, the
+@code{secret-service} running in the Childhurd will be sent an empty
+list of secrets.
+
+By default, the service automatically populates @file{/etc/childhurd}
+with the following non-volatile secrets, unless they already exist:
+
+@example
+/etc/childhurd/etc/guix/acl
+/etc/childhurd/etc/guix/signing-key.pub
+/etc/childhurd/etc/guix/signing-key.sec
+/etc/childhurd/etc/ssh/ssh_host_ed25519_key
+/etc/childhurd/etc/ssh/ssh_host_ecdsa_key
+/etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub
+/etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub
+@end example
+
+These files are automatically sent to the guest Hurd VM when it boots,
+including permissions.
+
+@cindex childhurd, offloading
+@cindex Hurd, offloading
+Having these files in place means that only a couple of things are
+missing to allow the host to offload @code{i586-gnu} builds to the
+childhurd:
+
+@enumerate
+@item
+Authorizing the childhurd's key on the host so that the host accepts
+build results coming from the childhurd, which can be done like so:
+
@example
-<ssh-port>: @code{(+ 10022 (* 1000 @var{ID}))}
-<vnc-port>: @code{(+ 15900 (* 1000 @var{ID}))}
+guix archive --authorize < \
+ /etc/childhurd/etc/guix/signing-key.pub
@end example
+@item
+Adding the childhurd to @file{/etc/guix/machines.scm} (@pxref{Daemon
+Offload Setup}).
+@end enumerate
+
+We're working towards making that happen automatically---get in touch
+with us at @email{guix-devel@@gnu.org} to discuss it!
@end table
@end deftp
(service hurd-vm-service-type
(hurd-vm-configuration
(image (const "/out/of/store/writable/hurd.img"))
- (options '("--hda"))))
+ (options '())))
@end lisp
@subsubheading Ganeti
@defvr {Scheme Variable} ganeti-luxid-service-type
@command{ganeti-luxid} is a daemon used to answer queries related to the
configuration and the current live state of a Ganeti cluster. Additionally,
-it is the authorative daemon for the Ganeti job queue. Jobs can be
+it is the authoritative daemon for the Ganeti job queue. Jobs can be
submitted via this daemon and it schedules and starts them.
It takes a @code{ganeti-luxid-configuration} object.
@defvr {Scheme Variable} ganeti-watcher-service-type
@command{ganeti-watcher} is a script designed to run periodically and ensure
the health of a cluster. It will automatically restart instances that have
-stopped without Ganetis consent, and repairs DRBD links in case a node has
+stopped without Ganeti's consent, and repairs DRBD links in case a node has
rebooted. It also archives old cluster jobs and restarts Ganeti daemons
that are not running. If the cluster parameter @code{ensure_node_health}
is set, the watcher will also shutdown instances and DRBD devices if the
@node Guix Services
@subsection Guix Services
+@subsubheading Guix Build Coordinator
+The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build
+Coordinator} aids in distributing derivation builds among machines
+running an @dfn{agent}. The build daemon is still used to build the
+derivations, but the Guix Build Coordinator manages allocating builds
+and working with the results.
+
+@quotation Note
+This service is considered experimental. Configuration options may be
+changed in a backwards-incompatible manner, and not all features have
+been thorougly tested.
+@end quotation
+
+The Guix Build Coordinator consists of one @dfn{coordinator}, and one or
+more connected @dfn{agent} processes. The coordinator process handles
+clients submitting builds, and allocating builds to agents. The agent
+processes talk to a build daemon to actually perform the builds, then
+send the results back to the coordinator.
+
+There is a script to run the coordinator component of the Guix Build
+Coordinator, but the Guix service uses a custom Guile script instead, to
+provide better integration with G-expressions used in the configuration.
+
+@defvar {Scheme Variable} guix-build-coordinator-service-type
+Service type for the Guix Build Coordinator. Its value must be a
+@code{guix-build-coordinator-configuration} object.
+@end defvar
+
+@deftp {Data Type} guix-build-coordinator-configuration
+Data type representing the configuration of the Guix Build Coordinator.
+
+@table @asis
+@item @code{package} (default: @code{guix-build-coordinator})
+The Guix Build Coordinator package to use.
+
+@item @code{user} (default: @code{"guix-build-coordinator"})
+The system user to run the service as.
+
+@item @code{group} (default: @code{"guix-build-coordinator"})
+The system group to run the service as.
+
+@item @code{database-uri-string} (default: @code{"sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"})
+The URI to use for the database.
+
+@item @code{agent-communication-uri} (default: @code{"http://0.0.0.0:8745"})
+The URI describing how to listen to requests from agent processes.
+
+@item @code{client-communication-uri} (default: @code{"http://127.0.0.1:8746"})
+The URI describing how to listen to requests from clients. The client
+API allows submitting builds and currently isn't authenticated, so take
+care when configuring this value.
+
+@item @code{allocation-strategy} (default: @code{#~basic-build-allocation-strategy})
+A G-expression for the allocation strategy to be used. This is a
+procedure that takes the datastore as an argument and populates the
+allocation plan in the database.
+
+@item @code{hooks} (default: @var{'()})
+An association list of hooks. These provide a way to execute arbitrary
+code upon certain events, like a build result being processed.
+
+@item @code{guile} (default: @code{guile-3.0-latest})
+The Guile package with which to run the Guix Build Coordinator.
+
+@end table
+@end deftp
+
+@defvar {Scheme Variable} guix-build-coordinator-agent-service-type
+Service type for a Guix Build Coordinator agent. Its value must be a
+@code{guix-build-coordinator-agent-configuration} object.
+@end defvar
+
+@deftp {Data Type} guix-build-coordinator-agent-configuration
+Data type representing the configuration a Guix Build Coordinator agent.
+
+@table @asis
+@item @code{package} (default: @code{guix-build-coordinator})
+The Guix Build Coordinator package to use.
+
+@item @code{user} (default: @code{"guix-build-coordinator-agent"})
+The system user to run the service as.
+
+@item @code{coordinator} (default: @code{"http://localhost:8745"})
+The URI to use when connecting to the coordinator.
+
+@item @code{uuid}
+The UUID of the agent. This should be generated by the coordinator
+process, stored in the coordinator database, and used by the intended
+agent.
+
+@item @code{password} (default: @code{#f})
+The password to use when connecting to the coordinator. A file to read
+the password from can also be specified, and this is more secure.
+
+@item @code{password-file} (default: @code{#f})
+A file containing the password to use when connecting to the
+coordinator.
+
+@item @code{systems} (default: @var{#f})
+The systems for which this agent should fetch builds. The agent process
+will use the current system it's running on as the default.
+
+@item @code{max-parallel-builds} (default: @code{1})
+The number of builds to perform in parallel.
+
+@item @code{derivation-substitute-urls} (default: @code{1})
+URLs from which to attempt to fetch substitutes for derivations, if the
+derivations aren't already available.
+
+@item @code{non-derivation-substitute-urls} (default: @code{1})
+URLs from which to attempt to fetch substitutes for build inputs, if the
+input store items aren't already available.
+
+@end table
+@end deftp
+
+The Guix Build Coordinator package contains a script to query an
+instance of the Guix Data Service for derivations to build, and then
+submit builds for those derivations to the coordinator. The service
+type below assists in running this script. This is an additional tool
+that may be useful when building derivations contained within an
+instance of the Guix Data Service.
+
+@defvar {Scheme Variable} guix-build-coordinator-queue-builds-service-type
+Service type for the
+guix-build-coordinator-queue-builds-from-guix-data-service script. Its
+value must be a @code{guix-build-coordinator-queue-builds-configuration}
+object.
+@end defvar
+
+@deftp {Data Type} guix-build-coordinator-queue-builds-configuration
+Data type representing the options to the queue builds from guix data
+service script.
+
+@table @asis
+@item @code{package} (default: @code{guix-build-coordinator})
+The Guix Build Coordinator package to use.
+
+@item @code{user} (default: @code{"guix-build-coordinator-queue-builds"})
+The system user to run the service as.
+
+@item @code{coordinator} (default: @code{"http://localhost:8745"})
+The URI to use when connecting to the coordinator.
+
+@item @code{systems} (default: @code{#f})
+The systems for which to fetch derivations to build.
+
+@item @code{systems-and-targets} (default: @code{#f})
+An association list of system and target pairs for which to fetch
+derivations to build.
+
+@item @code{guix-data-service} (default: @code{"https://data.guix.gnu.org"})
+The Guix Data Service instance from which to query to find out about
+derivations to build.
+
+@item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"})
+A file to record which commits have been processed, to avoid needlessly
+processing them again if the service is restarted.
+
+@end table
+@end deftp
+
@subsubheading Guix Data Service
The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores
and provides data about GNU Guix. This includes information about
@end lisp
@end deffn
+@cindex zram
+@cindex compressed swap
+@cindex Compressed RAM-based block devices
+@subsubheading Zram Device Service
+
+The Zram device service provides a compressed swap device in system
+memory. The Linux Kernel documentation has more information about
+@uref{https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html,zram}
+devices.
+
+@deffn {Scheme Variable} zram-device-service-type
+This service creates the zram block device, formats it as swap and
+enables it as a swap device. The service's value is a
+@code{zram-device-configuration} record.
+
+@deftp {Data Type} zram-device-configuration
+This is the data type representing the configuration for the zram-device
+service.
+
+@table @asis
+@item @code{size} (default @code{"1G"})
+This is the amount of space you wish to provide for the zram device. It
+accepts a string and can be a number of bytes or use a suffix, eg.:
+@code{"512M"} or @code{1024000}.
+@item @code{compression-algorithm} (default @code{'lzo})
+This is the compression algorithm you wish to use. It is difficult to
+list all the possible compression options, but common ones supported by
+Guix's Linux Libre Kernel include @code{'lzo}, @code{'lz4} and @code{'zstd}.
+@item @code{memory-limit} (default @code{0})
+This is the maximum amount of memory which the zram device can use.
+Setting it to '0' disables the limit. While it is generally expected
+that compression will be 2:1, it is possible that uncompressable data
+can be written to swap and this is a method to limit how much memory can
+be used. It accepts a string and can be a number of bytes or use a
+suffix, eg.: @code{"2G"}.
+@item @code{priority} (default @code{-1})
+This is the priority of the swap device created from the zram device.
+@code{swapon} accepts values between -1 and 32767, with higher values
+indicating higher priority. Higher priority swap will generally be used
+first.
+@end table
+
+@end deftp
+@end deffn
+
@node Hurd Services
@subsection Hurd Services
@table @asis
@item @code{package} (default: @code{docker})
-The Docker package to use.
+The Docker daemon package to use.
+
+@item @code{package} (default: @code{docker-cli})
+The Docker client package to use.
@item @code{containerd} (default: @var{containerd})
The Containerd package to use.
@item @code{proxy} (default @var{docker-libnetwork-cmd-proxy})
The Docker user-land networking proxy package to use.
-@item @code{enable-proxy?} (default @code{#f})
+@item @code{enable-proxy?} (default @code{#t})
Enable or disable the use of the Docker user-land networking proxy.
@item @code{debug?} (default @code{#f})
Enable or disable debug output.
+@item @code{enable-iptables?} (default @code{#t})
+Enable or disable the addition of iptables rules.
+
@end table
@end deftp
@defvr {Scheme Variable} rshiny-service-type
This is a type of service which is used to run a webapp created with
-@code{r-shiny}. This service sets the @code{R_LIBS_USER} environment
+@code{r-shiny}. This service sets the @env{R_LIBS_USER} environment
variable and runs the provided script to call @code{runApp}.
@deftp {Data Type} rshiny-configuration
(app (string-append out "/bin/" ,name))
(Rbin (string-append (assoc-ref %build-inputs "r-min")
"/bin/Rscript")))
-@dots{}
+ ;; @dots{}
(mkdir-p (string-append out "/bin"))
(call-with-output-file app
(lambda (port)
library(shiny)
setwd(\"~a\")
runApp(launch.browser=0, port=4202)~%\n"
- Rbin targetdir)))
-@dots{}
+ Rbin targetdir))))
@end lisp
@end table
@cindex BIOS, bootloader
The bootloader to use, as a @code{bootloader} object. For now
@code{grub-bootloader}, @code{grub-efi-bootloader},
-@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported.
+@code{grub-efi-netboot-bootloader}, @code{extlinux-bootloader} and
+@code{u-boot-bootloader} are supported.
+
+@cindex ARM, bootloaders
+@cindex AArch64, bootloaders
+Available bootloaders are described in @code{(gnu bootloader @dots{})}
+modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
+of bootloaders for a wide range of ARM and AArch64 systems, using the
+@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
@vindex grub-efi-bootloader
@code{grub-efi-bootloader} allows to boot on modern systems using the
@code{grub-bootloader} allows you to boot in particular Intel-based machines
in ``legacy'' BIOS mode.
-@cindex ARM, bootloaders
-@cindex AArch64, bootloaders
-Available bootloaders are described in @code{(gnu bootloader @dots{})}
-modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
-of bootloaders for a wide range of ARM and AArch64 systems, using the
-@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
+@vindex grub-efi-netboot-bootloader
+@code{grub-efi-netboot-bootloader} allows you to boot your system over network
+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.
+
+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
+@file{/boot/grub/grub.cfg} and other files from the store (like GRUBs background
+image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the
+initrd (@pxref{operating-system Reference, @code{initrd}})), too. All these
+files from the store will be accessed by GRUB through TFTP with their normal
+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}.
+
+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
+store link exposes the whole store through TFTP. Both points need to be
+considered carefully for security aspects.
+
+Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
+NFS servers, you also need a properly configured DHCP server to make the booting
+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
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}.
+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.
@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
@table @asis
@item @code{gfxmode} (default: @code{'("auto")})
-The GRUB @code{gfxmode} to set (a list of screen resolution strings, see
+The GRUB @code{gfxmode} to set (a list of screen resolution strings,
@pxref{gfxmode,,, grub, GNU GRUB manual}).
@end table
@end deftp
the @option{--image-size} option is ignored in the case of
@code{docker-image}.
-You can specify the root file system type by using the
-@option{--file-system-type} option. It defaults to @code{ext4}.
-
-When using @code{vm-image}, the returned image is in qcow2 format, which
-the QEMU emulator can efficiently use. @xref{Running Guix in a VM},
-for more information on how to run the image in a virtual machine.
+The @code{disk-image} command can produce various image types. The
+image type can be selected using the @command{--image-type} option. It
+defaults to @code{raw}. When its value is @code{iso9660}, the
+@option{--label} option can be used to specify a volume ID with
+@code{disk-image}.
-When using @code{disk-image}, a raw disk image is produced; it can be
-copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
-the device corresponding to a USB stick, one can copy the image to it
-using the following command:
+When using the @code{raw} image type, a raw disk image is produced; it
+can be copied as is to a USB stick, for instance. Assuming
+@code{/dev/sdc} is the device corresponding to a USB stick, one can copy
+the image to it using the following command:
@example
# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc status=progress
@end example
+The @code{--list-image-types} command lists all the available image
+types.
+
+When using @code{vm-image}, the returned image is in qcow2 format, which
+the QEMU emulator can efficiently use. @xref{Running Guix in a VM},
+for more information on how to run the image in a virtual machine.
+
When using @code{docker-image}, a Docker image is produced. Guix builds
the image from scratch, not from a pre-existing Docker base image. As a
result, it contains @emph{exactly} what you define in the operating
what it pretends to contain; or they could use that to derive a variant
of the image.
-@item --file-system-type=@var{type}
+@item --image-type=@var{type}
@itemx -t @var{type}
-For the @code{disk-image} action, create a file system of the given
-@var{type} on the image.
+For the @code{disk-image} action, create an image with given @var{type}.
-When this option is omitted, @command{guix system} uses @code{ext4}.
+When this option is omitted, @command{guix system} uses the @code{raw}
+image type.
@cindex ISO-9660 format
@cindex CD image format
@cindex DVD image format
-@option{--file-system-type=iso9660} produces an ISO-9660 image, suitable
+@option{--image-type=iso9660} produces an ISO-9660 image, suitable
for burning on CDs and DVDs.
@item --image-size=@var{size}
Do note that you first need to generate a key pair on the coordinator machine
to allow the daemon to export signed archives of files from the store
-(@pxref{Invoking guix archive}).
+(@pxref{Invoking guix archive}), though this step is automatic on Guix
+System:
@example
# guix archive --generate-key
(service guix-service-type
(guix-configuration
(build-accounts 5)
- (use-substitutes? #f)))
+ (extra-options '("--gc-keep-derivations"))))
@end lisp
The second argument to the @code{service} form is a value representing
argument and the result of applying @code{compose} to the extension
values as the second argument. It must return a value that is a valid
parameter value for the service instance.
+
+@item @code{description}
+This is a string, possibly using Texinfo markup, describing in a couple
+of sentences what the service is about. This string allows users to
+find about the service through @command{guix system search}
+(@pxref{Invoking guix system}).
+
+@item @code{default-value} (default: @code{&no-default-value})
+The default value associated for instances of this service type. This
+allows users to use the @code{service} form without its second argument:
+
+@lisp
+(service @var{type})
+@end lisp
+
+The returned service in this case has the default value specified by
+@var{type}.
@end table
@xref{Service Types and Services}, for examples.
debugger, GDB, to map binary code to source code; it is required to
debug a compiled program in good conditions.
+This chapter explains how to use separate debug info when packages
+provide it, and how to rebuild packages with debug info when it's
+missing.
+
+@menu
+* Separate Debug Info:: Installing 'debug' outputs.
+* Rebuilding Debug Info:: Building missing debug info.
+@end menu
+
+@node Separate Debug Info
+@section Separate Debug Info
+
The problem with debugging information is that is takes up a fair amount
of disk space. For example, debugging information for the GNU C Library
weighs in at more than 60 MiB. Thus, as a user, keeping all the
@c XXX: keep me up-to-date
The @code{debug} output mechanism in Guix is implemented by the
@code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
-opt-in---debugging information is available only for the packages
-with definitions explicitly declaring a @code{debug} output. This may be
-changed to opt-out in the future if our build farm servers can handle
-the load. To check whether a package has a @code{debug} output, use
-@command{guix package --list-available} (@pxref{Invoking guix package}).
+opt-in---debugging information is available only for the packages with
+definitions explicitly declaring a @code{debug} output. To check
+whether a package has a @code{debug} output, use @command{guix package
+--list-available} (@pxref{Invoking guix package}).
+
+Read on for how to deal with packages lacking a @code{debug} output.
+
+@node Rebuilding Debug Info
+@section Rebuilding Debug Info
+
+@cindex debugging info, rebuilding
+As we saw above, some packages, but not all, provide debugging info in a
+@code{debug} output. What can you do when debugging info is missing?
+The @option{--with-debug-info} option provides a solution to that: it
+allows you to rebuild the package(s) for which debugging info is
+missing---and only those---and to graft those onto the application
+you're debugging. Thus, while it's not as fast as installing a
+@code{debug} output, it is relatively inexpensive.
+
+Let's illustrate that. Suppose you're experiencing a bug in Inkscape
+and would like to see what's going on in GLib, a library that's deep
+down in its dependency graph. As it turns out, GLib does not have a
+@code{debug} output and the backtrace GDB shows is all sadness:
+
+@example
+(gdb) bt
+#0 0x00007ffff5f92190 in g_getenv ()
+ from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
+#1 0x00007ffff608a7d6 in gobject_init_ctor ()
+ from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
+#2 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
+ env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
+#3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
+ at dl-init.c:118
+@end example
+
+To address that, you install Inkscape linked against a variant GLib that
+contains debug info:
+
+@example
+guix install inkscape --with-debug-info=glib
+@end example
+
+This time, debugging will be a whole lot nicer:
+
+@example
+$ gdb --args sh -c 'exec inkscape'
+@dots{}
+(gdb) b g_getenv
+Function "g_getenv" not defined.
+Make breakpoint pending on future shared library load? (y or [n]) y
+Breakpoint 1 (g_getenv) pending.
+(gdb) r
+Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
+@dots{}
+(gdb) bt
+#0 g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
+#1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
+#2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
+#3 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
+ env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
+@dots{}
+@end example
+
+Much better!
+Note that there can be packages for which @option{--with-debug-info}
+will not have the desired effect. @xref{Package Transformation Options,
+@option{--with-debug-info}}, for more information.
@node Security Updates
@chapter Security Updates
HCoop / jackhill / guix / guix.git / blobdiff