diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 647 |
1 files changed, 556 insertions, 91 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 5747484b20..e52382e976 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -10,10 +10,10 @@ @include version.texi @c Identifier of the OpenPGP key used to sign tarballs and such. -@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 +@set OPENPGP-SIGNING-KEY-ID BCA689B636553801C3C62150197A5888235FACAC @copying -Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@* +Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017 Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* @@ -28,7 +28,8 @@ Copyright @copyright{} 2016 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016 ng0@* Copyright @copyright{} 2016 Jan Nieuwenhuizen@* -Copyright @copyright{} 2016 Julien Lepiller +Copyright @copyright{} 2016 Julien Lepiller@* +Copyright @copyright{} 2016 Alex ter Weele Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -53,12 +54,6 @@ Documentation License''. * guix environment: (guix)Invoking guix environment. Building development environments with Guix. @end direntry -@dircategory Emacs -@direntry -* Guix user interface: (guix)Emacs Interface. Package management from the comfort of Emacs. -@end direntry - - @titlepage @title GNU Guix Reference Manual @subtitle Using the GNU Guix Functional Package Manager @@ -85,7 +80,6 @@ package management tool written for the GNU system. * Introduction:: What is Guix about? * Installation:: Installing Guix. * Package Management:: Package installation, upgrade, etc. -* Emacs Interface:: Using Guix from Emacs. * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. * GNU Distribution:: Software for your friendly GNU system. @@ -123,19 +117,6 @@ Package Management * Invoking guix pull:: Fetching the latest Guix and distribution. * Invoking guix archive:: Exporting and importing store files. -Emacs Interface - -* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. -* Package Management: Emacs Package Management. Managing packages and generations. -* Licenses: Emacs Licenses. Interface for licenses of Guix packages. -* Package Source Locations: Emacs Package Locations. Interface for package location files. -* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. -* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. -* Build Log Mode: Emacs Build Log. Highlighting Guix build logs. -* Completions: Emacs Completions. Completing @command{guix} shell command. -* Development: Emacs Development. Tools for Guix developers. -* Hydra: Emacs Hydra. Interface for Guix build farm. - Programming Interface * Defining Packages:: Defining new packages. @@ -164,12 +145,13 @@ Utilities * Invoking guix environment:: Setting up development environments. * Invoking guix publish:: Sharing substitutes. * Invoking guix challenge:: Challenging substitute servers. +* Invoking guix copy:: Copying to and from a remote store. * Invoking guix container:: Process isolation. Invoking @command{guix build} * Common Build Options:: Build options for most commands. -* Package Transformation Options:: Creating variants of packages. +* Package Transformation Options:: Creating variants of packages. * Additional Build Options:: Options specific to 'guix build'. GNU Distribution @@ -218,12 +200,14 @@ Services * Log Rotation:: The rottlog service. * Networking Services:: Network setup, SSH daemon, etc. * X Window:: Graphical display. +* Printing Services:: Local and remote printer support. * Desktop Services:: D-Bus and desktop services. * Database Services:: SQL databases. * Mail Services:: IMAP, POP3, SMTP, and all that. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. * Network File System:: NFS related services. +* Continuous Integration:: The Cuirass service. * Miscellaneous Services:: Other services. Defining Services @@ -277,8 +261,7 @@ assists with the creation and maintenance of software environments. @cindex user interfaces Guix provides a command-line package management interface (@pxref{Invoking guix package}), a set of command-line utilities -(@pxref{Utilities}), a visual user interface in Emacs (@pxref{Emacs -Interface}), as well as Scheme programming interfaces +(@pxref{Utilities}), as well as Scheme programming interfaces (@pxref{Programming Interface}). @cindex build daemon Its @dfn{build daemon} is responsible for building packages on behalf of @@ -358,6 +341,9 @@ without interference. Its data lives exclusively in two directories, usually @file{/gnu/store} and @file{/var/guix}; other files on your system, such as @file{/etc}, are left untouched. +Once installed, Guix can be updated by running @command{guix pull} +(@pxref{Invoking guix pull}). + @menu * Binary Installation:: Getting Guix running in no time! * Requirements:: Software needed to build and run Guix. @@ -568,7 +554,8 @@ interest primarily for developers and not for casual users. @item @c Note: We need at least 0.10.2 for 'channel-send-eof'. -Support for build offloading (@pxref{Daemon Offload Setup}) depends on +Support for build offloading (@pxref{Daemon Offload Setup}) and +@command{guix copy} (@pxref{Invoking guix copy}) depends on @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, version 0.10.2 or later. @@ -921,6 +908,13 @@ Port number of SSH server on the machine. The SSH private key file to use when connecting to the machine, in OpenSSH format. +@item @code{compression} (default: @code{"zlib@@openssh.com,zlib"}) +@itemx @code{compression-level} (default: @code{3}) +The SSH-level compression methods and compression level requested. + +Note that offloading relies on SSH compression to reduce bandwidth usage +when transferring files to and from build machines. + @item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"}) File name of the Unix-domain socket @command{guix-daemon} is listening to on that machine. @@ -941,9 +935,8 @@ name, and they will be scheduled on matching build machines. @end table @end deftp -The @code{guix} command must be in the search path on the build -machines, since offloading works by invoking the @code{guix archive} and -@code{guix build} commands. In addition, the Guix modules must be in +The @code{guile} command must be in the search path on the build +machines. In addition, the Guix modules must be in @code{$GUILE_LOAD_PATH} on the build machine---you can check whether this is the case by running: @@ -978,6 +971,32 @@ the master receives files from a build machine (and @i{vice versa}), its build daemon can make sure they are genuine, have not been tampered with, and that they are signed by an authorized key. +@cindex offload test +To test whether your setup is operational, run this command on the +master node: + +@example +# guix offload test +@end example + +This will attempt to connect to each of the build machines specified in +@file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are +available on each machine, attempt to export to the machine and import +from it, and report any error in the process. + +If you want to test a different machine file, just specify it on the +command line: + +@example +# guix offload test machines-qualif.scm +@end example + +Last, you can test the subset of the machines whose name matches a +regular expression like this: + +@example +# guix offload test machines.scm '\.gnu\.org$' +@end example @node Invoking guix-daemon @section Invoking @command{guix-daemon} @@ -1242,6 +1261,56 @@ data in the right format. This is important because the locale data format used by different libc versions may be incompatible. +@subsection Name Service Switch + +@cindex name service switch, glibc +@cindex NSS (name service switch), glibc +@cindex nscd (name service caching daemon) +@cindex name service caching daemon (nscd) +When using Guix on a foreign distro, we @emph{strongly recommend} that +the system run the GNU C library's @dfn{name service cache daemon}, +@command{nscd}, which should be listening on the +@file{/var/run/nscd/socket} socket. Failing to do that, applications +installed with Guix may fail to look up host names or user accounts, or +may even crash. The next paragraphs explain why. + +@cindex @file{nsswitch.conf} +The GNU C library implements a @dfn{name service switch} (NSS), which is +an extensible mechanism for ``name lookups'' in general: host name +resolution, user accounts, and more (@pxref{Name Service Switch,,, libc, +The GNU C Library Reference Manual}). + +@cindex Network information service (NIS) +@cindex NIS (Network information service) +Being extensible, the NSS supports @dfn{plugins}, which provide new name +lookup implementations: for example, the @code{nss-mdns} plugin allow +resolution of @code{.local} host names, the @code{nis} plugin allows +user account lookup using the Network information service (NIS), and so +on. These extra ``lookup services'' are configured system-wide in +@file{/etc/nsswitch.conf}, and all the programs running on the system +honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C +Reference Manual}). + +When they perform a name lookup---for instance by calling the +@code{getaddrinfo} function in C---applications first try to connect to +the nscd; on success, nscd performs name lookups on their behalf. If +the nscd is not running, then they perform the name lookup by +themselves, by loading the name lookup services into their own address +space and running it. These name lookup services---the +@file{libnss_*.so} files---are @code{dlopen}'d, but they may come from +the host system's C library, rather than from the C library the +application is linked against (the C library coming from Guix). + +And this is where the problem is: if your application is linked against +Guix's C library (say, glibc 2.24) and tries to load NSS plugins from +another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will +likely crash or have its name lookups fail unexpectedly. + +Running @command{nscd} on the system, among other advantages, eliminates +this binary incompatibility problem because those @code{libnss_*.so} +files are loaded in the @command{nscd} process, not in applications +themselves. + @subsection X11 Fonts @cindex fonts @@ -1328,10 +1397,14 @@ procedures or dependencies. Guix also goes beyond this obvious set of features. This chapter describes the main features of Guix, as well as the package -management tools it provides. Two user interfaces are provided for -routine package management tasks: A command-line interface described below -(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user -interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}). +management tools it provides. Along with the command-line interface +described below (@pxref{Invoking guix package, @code{guix package}}), +you may also use Emacs Interface, after installing @code{emacs-guix} +package (run @kbd{M-x guix-help} command to start with it): + +@example +guix package -i emacs-guix +@end example @menu * Features:: How Guix will make your life brighter. @@ -1348,9 +1421,7 @@ interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}). 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 -(note that Guix comes with an Emacs extension to shorten those file -names, @pxref{Emacs Prettify}.) +@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string. Instead of referring to these directories, users have their own @dfn{profile}, which points to the packages that they actually want to @@ -1896,9 +1967,7 @@ also result from derivation builds, can be available as substitutes. The @code{hydra.gnu.org} server is a front-end to a build farm that builds packages from the GNU distribution continuously for some -architectures, and makes them available as substitutes (@pxref{Emacs -Hydra}, for information on how to query the continuous integration -server). This is the +architectures, and makes them available as substitutes. This is the default source of substitutes; it can be overridden by passing the @option{--substitute-urls} option either to @command{guix-daemon} (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) @@ -2225,6 +2294,7 @@ this option is primarily useful when the daemon was running with @section Invoking @command{guix pull} @cindex upgrading Guix +@cindex updating Guix @cindex @command{guix pull} @cindex pull Packages are installed or upgraded to the latest version available in @@ -2318,12 +2388,16 @@ However, note that, in both examples, all of @code{emacs} and the profile as well as all of their dependencies are transferred (due to @code{-r}), regardless of what is already available in the store on the target machine. The @code{--missing} option can help figure out which -items are missing from the target store. - -Archives are stored in the ``Nix archive'' or ``Nar'' format, which is -comparable in spirit to `tar', but with a few noteworthy differences +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) +By default 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 +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 @@ -2336,6 +2410,9 @@ 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. +Optionally, archives can be exported as a Docker image in the tar +archive format using @code{--format=docker}. + The main options are: @table @code @@ -2364,6 +2441,19 @@ 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 -f +@item --format=@var{FMT} +@cindex docker, export +@cindex export format +Specify the export format. Acceptable arguments are @code{nar} and +@code{docker}. The default is the nar format. When the format is +@code{docker}, recursively export the specified store directory as a +Docker image in tar archive format, as specified in +@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, +version 1.2.0 of the Docker Image Specification}. Using +@code{--format=docker} implies @code{--recursive}. The generated +archive can be loaded by Docker using @command{docker load}. + @item --generate-key[=@var{parameters}] @cindex signing, archives Generate a new key pair for the daemon. This is a prerequisite before @@ -2421,9 +2511,6 @@ archive contents coming from possibly untrusted substitute servers. @end table @c ********************************************************************* -@include emacs.texi - -@c ********************************************************************* @node Programming Interface @chapter Programming Interface @@ -3102,6 +3189,19 @@ which file the system is defined in. @end defvr +@defvr {Scheme Variable} cargo-build-system +@cindex Rust programming language +@cindex Cargo (Rust build system) +This variable is exported by @code{(guix build-system cargo)}. It +supports builds of packages using Cargo, the build tool of the +@uref{https://www.rust-lang.org, Rust programming language}. + +In its @code{configure} phase, this build system replaces dependencies +specified in the @file{Carto.toml} file with inputs to the Guix package. +The @code{install} phase installs the binaries, and it also installs the +source code and @file{Cargo.toml} file. +@end defvr + @defvr {Scheme Variable} cmake-build-system This variable is exported by @code{(guix build-system cmake)}. It implements the build procedure for packages using the @@ -3170,6 +3270,11 @@ the @code{#:python} parameter. This is a useful way to force a package to be built for a specific version of the Python interpreter, which might be necessary if the package is only compatible with a single interpreter version. + +By default guix calls @code{setup.py} under control of +@code{setuptools}, much like @command{pip} does. Some packages are not +compatible with setuptools (and pip), thus you can disable this by +setting the @code{#:use-setuptools} parameter to @code{#f}. @end defvr @defvr {Scheme Variable} perl-build-system @@ -4332,6 +4437,7 @@ the Scheme programming interface of Guix in a convenient way. * Invoking guix environment:: Setting up development environments. * Invoking guix publish:: Sharing substitutes. * Invoking guix challenge:: Challenging substitute servers. +* Invoking guix copy:: Copying to and from a remote store. * Invoking guix container:: Process isolation. @end menu @@ -4384,7 +4490,7 @@ described in the subsections below. @menu * Common Build Options:: Build options for most commands. -* Package Transformation Options:: Creating variants of packages. +* Package Transformation Options:: Creating variants of packages. * Additional Build Options:: Options specific to 'guix build'. @end menu @@ -4595,7 +4701,7 @@ procedure (@pxref{Defining Packages, @code{package-input-rewriting}}). @item --with-graft=@var{package}=@var{replacement} This is similar to @code{--with-input} but with an important difference: -instead of rebuilding all the dependency chain, @var{replacement} is +instead of rebuilding the whole dependency chain, @var{replacement} is built and then @dfn{grafted} onto the binaries that were initially referring to @var{package}. @xref{Security Updates}, for more information on grafts. @@ -4816,11 +4922,6 @@ have created your own packages on @code{GUIX_PACKAGE_PATH} recipes. Otherwise, you will be able to examine the read-only recipes for packages currently in the store. -If you are using Emacs, note that the Emacs user interface provides the -@kbd{M-x guix-edit} command and a similar functionality in the ``package -info'' and ``package list'' buffers created by the @kbd{M-x -guix-search-by-name} and similar commands (@pxref{Emacs Commands}). - @node Invoking guix download @section Invoking @command{guix download} @@ -5058,6 +5159,10 @@ R package: guix import cran Cairo @end example +When @code{--recursive} is added, the importer will traverse the +dependency graph of the given upstream package recursively and generate +package expressions for all those packages that are not yet in Guix. + When @code{--archive=bioconductor} is added, metadata is imported from @uref{http://www.bioconductor.org/, Bioconductor}, a repository of R packages for for the analysis and comprehension of high-throughput @@ -5179,6 +5284,11 @@ signatures,, emacs, The GNU Emacs Manual}). identifier. @end itemize @end table + +@item crate +@cindex crate +Import metadata from the crates.io Rust package repository +@uref{https://crates.io, crates.io}. @end table The structure of the @command{guix import} code is modular. It would be @@ -5200,10 +5310,19 @@ gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18. gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0 @end example -It does so by browsing the FTP directory of each package and determining -the highest version number of the source tarballs therein. The command +Alternately, one can specify packages to consider, in which case a +warning is emitted for packages that lack an updater: + +@example +$ guix refresh coreutils guile guile-ssh +gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh +gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13 +@end example + +@command{guix refresh} browses the upstream repository of each package and determines +the highest version number of the releases therein. The command knows how to update specific types of packages: GNU packages, ELPA -packages, etc.---see the documentation for @option{--type} below. The +packages, etc.---see the documentation for @option{--type} below. There are many packages, though, for which it lacks a method to determine whether a new upstream release is available. However, the mechanism is extensible, so feel free to get in touch with us to add a new method! @@ -5243,7 +5362,7 @@ usually run from a checkout of the Guix source tree (@pxref{Running Guix Before It Is Installed}): @example -$ ./pre-inst-env guix refresh -s non-core +$ ./pre-inst-env guix refresh -s non-core -u @end example @xref{Defining Packages}, for more information on package definitions. @@ -5278,12 +5397,16 @@ the updater for GNOME packages; the updater for KDE packages; @item xorg the updater for X.org packages; +@item kernel.org +the updater for packages hosted on kernel.org; @item elpa the updater for @uref{http://elpa.gnu.org/, ELPA} packages; @item cran the updater for @uref{http://cran.r-project.org/, CRAN} packages; @item bioconductor the updater for @uref{http://www.bioconductor.org/, Bioconductor} R packages; +@item cpan +the updater for @uref{http://www.cpan.org/, CPAN} packages; @item pypi the updater for @uref{https://pypi.python.org, PyPI} packages. @item gem @@ -5292,6 +5415,8 @@ the updater for @uref{https://rubygems.org, RubyGems} packages. the updater for @uref{https://github.com, GitHub} packages. @item hackage the updater for @uref{https://hackage.haskell.org, Hackage} packages. +@item crate +the updater for @uref{https://crates.io, Crates} packages. @end table For instance, the following command only checks for updates of Emacs @@ -5309,7 +5434,7 @@ In addition, @command{guix refresh} can be passed one or more package names, as in this example: @example -$ ./pre-inst-env guix refresh -u emacs idutils gcc-4.8.4 +$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 @end example @noindent @@ -5328,11 +5453,18 @@ be used when passing @command{guix refresh} one or more package names: @itemx -L List available updaters and exit (see @option{--type} above.) +For each updater, display the fraction of packages it covers; at the +end, display the fraction of packages covered by all these updaters. + @item --list-dependent @itemx -l List top-level dependent packages that would need to be rebuilt as a result of upgrading one or more packages. +@xref{Invoking guix graph, the @code{reverse-package} type of +@command{guix graph}}, for information on how to visualize the list of +dependents of a package. + @end table Be aware that the @code{--list-dependent} option only @@ -5596,11 +5728,13 @@ Consider packages for @var{system}---e.g., @code{x86_64-linux}. Packages and their dependencies form a @dfn{graph}, specifically a directed acyclic graph (DAG). It can quickly become difficult to have a mental model of the package DAG, so the @command{guix graph} command -provides a visual representation of the DAG. @command{guix graph} -emits a DAG representation in the input format of +provides a visual representation of the DAG. By default, +@command{guix graph} emits a DAG representation in the input format of @uref{http://www.graphviz.org/, Graphviz}, so its output can be passed -directly to the @command{dot} command of Graphviz. The general -syntax is: +directly to the @command{dot} command of Graphviz. It can also emit an +HTML page with embedded JavaScript code to display a ``chord diagram'' +in a Web browser, using the @uref{https://d3js.org/, d3.js} library. +The general syntax is: @example guix graph @var{options} @var{package}@dots{} @@ -5632,6 +5766,20 @@ This is the default type used in the example above. It shows the DAG of package objects, excluding implicit dependencies. It is concise, but filters out many details. +@item reverse-package +This shows the @emph{reverse} DAG of packages. For example: + +@example +guix graph --type=reverse-package ocaml +@end example + +... yields the graph of packages that depend on OCaml. + +Note that for core packages this can yield huge graphs. If all you want +is to know the number of packages that depend on a given package, use +@command{guix refresh --list-dependent} (@pxref{Invoking guix refresh, +@option{--list-dependent}}). + @item bag-emerged This is the package DAG, @emph{including} implicit inputs. @@ -5718,6 +5866,15 @@ the values listed above. @item --list-types List the supported graph types. +@item --backend=@var{backend} +@itemx -b @var{backend} +Produce a graph using the selected @var{backend}. + +@item --list-backends +List the supported graph backends. + +Currently, the available backends are Graphviz and d3.js. + @item --expression=@var{expr} @itemx -e @var{expr} Consider the package @var{expr} evaluates to. @@ -5852,6 +6009,21 @@ The @code{--container} option requires Linux-libre 3.19 or newer. The available options are summarized below. @table @code +@item --root=@var{file} +@itemx -r @var{file} +@cindex persistent environment +@cindex garbage collector root, for environments +Make @var{file} a symlink to the profile for this environment, and +register it as a garbage collector root. + +This is useful if you want to protect your environment from garbage +collection, to make it ``persistent''. + +When this option is omitted, the environment is protected from garbage +collection only for the duration of the @command{guix environment} +session. This means that next time you recreate the same environment, +you could have to rebuild or re-download packages. + @item --expression=@var{expr} @itemx -e @var{expr} Create an environment for the package or list of packages that @@ -6240,6 +6412,68 @@ URLs to compare to. @end table +@node Invoking guix copy +@section Invoking @command{guix copy} + +@cindex copy, of store items, over SSH +@cindex SSH, copy of store items +@cindex sharing store items across machines +@cindex transferring store items across machines +The @command{guix copy} command copies items from the store of one +machine to that of another machine over a secure shell (SSH) +connection@footnote{This command is available only when Guile-SSH was +found. @xref{Requirements}, for details.}. For example, the following +command copies the @code{coreutils} package, the user's profile, and all +their dependencies over to @var{host}, logged in as @var{user}: + +@example +guix copy --to=@var{user}@@@var{host} \ + coreutils `readlink -f ~/.guix-profile` +@end example + +If some of the items to be copied are already present on @var{host}, +they are not actually sent. + +The command below retrieves @code{libreoffice} and @code{gimp} from +@var{host}, assuming they are available there: + +@example +guix copy --from=@var{host} libreoffice gimp +@end example + +The SSH connection is established using the Guile-SSH client, which is +compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and +@file{~/.ssh/config}, and uses the SSH agent for authentication. + +The key used to sign items that are sent must be accepted by the remote +machine. Likewise, the key used by the remote machine to sign items you +are retrieving must be in @file{/etc/guix/acl} so it is accepted by your +own daemon. @xref{Invoking guix archive}, for more information about +store item authentication. + +The general syntax is: + +@example +guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{} +@end example + +You must always specify one of the following options: + +@table @code +@item --to=@var{spec} +@itemx --from=@var{spec} +Specify the host to send to or receive from. @var{spec} must be an SSH +spec such as @code{example.org}, @code{charlie@@example.org}, or +@code{charlie@@example.org:2222}. +@end table + +The @var{items} can be either package names, such as @code{gimp}, or +store items, such as @file{/gnu/store/@dots{}-idutils-4.6}. + +When specifying the name of a package to send, it is first built if +needed, unless @option{--dry-run} was specified. Common build options +are supported (@pxref{Common Build Options}). + @node Invoking guix container @section Invoking @command{guix container} @@ -6727,6 +6961,7 @@ swap partition on @file{/dev/sda2}, you would run: @example mkswap /dev/sda2 +swapon /dev/sda2 @end example @node Proceeding with the Installation @@ -6807,6 +7042,14 @@ initialized by running the @command{passwd} command as @code{root}, unless your configuration specifies otherwise (@pxref{user-account-password, user account passwords}). +@cindex upgrading GuixSD +From then on, you can update GuixSD whenever you want by running +@command{guix pull} as @code{root} (@pxref{Invoking guix pull}), and +then running @command{guix system reconfigure} to build a new system +generation with the latest packages and services (@pxref{Invoking guix +system}). We recommend doing that regularly so that your system +includes the latest security updates (@pxref{Security Updates}). + Join us on @code{#guix} on the Freenode IRC network or on @file{guix-devel@@gnu.org} to share your experience---good or not so good. @@ -7073,7 +7316,7 @@ entry (@pxref{Invoking guix system}). The normal way to change the system configuration is by updating this file and re-running @command{guix system reconfigure}. One should never -have to touch files in @command{/etc} or to run commands that modify the +have to touch files in @file{/etc} or to run commands that modify the system state such as @command{useradd} or @command{grub-install}. In fact, you must avoid that since that would not only void your warranty but also prevent you from rolling back to previous versions of your @@ -7086,7 +7329,15 @@ modifying or deleting previous generations. Old system generations get an entry in the GRUB boot menu, allowing you to boot them in case something went wrong with the latest generation. Reassuring, no? The @command{guix system list-generations} command lists the system -generations available on disk. +generations available on disk. It is also possible to roll back the +system via the commands @command{guix system roll-back} and +@command{guix system switch-generation}. + +Although the command @command{guix system reconfigure} will not modify +previous generations, must take care when the current generation is not +the latest (e.g., after invoking @command{guix system roll-back}), since +the operation might overwrite a later generation (@pxref{Invoking guix +system}). @unnumberedsubsubsec The Programming Interface @@ -7481,7 +7732,7 @@ for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10. @cindex LUKS The following example specifies a mapping from @file{/dev/sda3} to @file{/dev/mapper/home} using LUKS---the -@url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a +@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a standard mechanism for disk encryption. The @file{/dev/mapper/home} device can then be used as the @code{device} of a @code{file-system} @@ -7862,6 +8113,7 @@ declaration. * Kerberos Services:: Kerberos services. * Web Services:: Web servers. * Network File System:: NFS related services. +* Continuous Integration:: The Cuirass service. * Miscellaneous Services:: Other services. @end menu @@ -8136,9 +8388,12 @@ The list of URLs where to look for substitutes by default. @item @code{extra-options} (default: @code{'()}) List of extra command-line options for @command{guix-daemon}. +@item @code{log-file} (default: @code{"/var/log/guix-daemon.log"}) +File where @command{guix-daemon}'s standard output and standard error +are written. + @item @code{lsof} (default: @var{lsof}) -@itemx @code{lsh} (default: @var{lsh}) -The lsof and lsh packages to use. +The lsof package to use. @end table @end deftp @@ -8485,7 +8740,7 @@ Thus, it can be instantiated like this: (use-modules (gnu services networking) (gnu packages admin)) -(service wpa-supplicant-type wpa-supplicant) +(service wpa-supplicant-service-type wpa-supplicant) @end lisp @end defvr @@ -10039,13 +10294,14 @@ Users need to be in the @code{lp} group to access the D-Bus service. 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''] + [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @ + [#:port 5432] [#:locale ``en_US.utf8''] Return a service that runs @var{postgresql}, the PostgreSQL database server. -The PostgreSQL daemon loads its runtime configuration from -@var{config-file} and stores the database cluster in -@var{data-directory}. +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}. @end deffn @deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)] @@ -10066,6 +10322,9 @@ or @var{mysql}. For MySQL, a temporary root password will be displayed at activation time. For MariaDB, the root password is empty. + +@item @code{port} (default: @code{3306}) +TCP port on which the database server listens for incoming connections. @end table @end deftp @@ -10584,7 +10843,7 @@ Defaults to @samp{""}. @deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab Kerberos keytab to use for the GSSAPI mechanism. Will use the -system default (usually /etc/krb5.keytab) if not specified. You may +system default (usually @file{/etc/krb5.keytab}) if not specified. You may need to change the auth service to run as root to be able to read this file. Defaults to @samp{""}. @@ -11472,6 +11731,99 @@ remote servers. Run @command{man smtpd.conf} for more information. The @code{(gnu services kerberos)} module provides services relating to the authentication protocol @dfn{Kerberos}. +@subsubheading Krb5 Service + +Programs using a Kerberos client library normally +expect a configuration file in @file{/etc/krb5.conf}. +This service generates such a file from a definition provided in the +operating system declaration. +It does not cause any daemon to be started. + +No ``keytab'' files are provided by this service---you must explicitly create them. +This service is known to work with the MIT client library, @code{mit-krb5}. +Other implementations have not been tested. + +@defvr {Scheme Variable} krb5-service-type +A service type for Kerberos 5 clients. +@end defvr + +@noindent +Here is an example of its use: +@lisp +(service krb5-service-type + (krb5-configuration + (default-realm "EXAMPLE.COM") + (allow-weak-crypto? #t) + (realms (list + (krb5-realm + (name "EXAMPLE.COM") + (admin-server "groucho.example.com") + (kdc "karl.example.com")) + (krb5-realm + (name "ARGRX.EDU") + (admin-server "kerb-admin.argrx.edu") + (kdc "keys.argrx.edu")))))) +@end lisp + +@noindent +This example provides a Kerberos@tie{}5 client configuration which: +@itemize +@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both +of which have distinct administration servers and key distribution centers; +@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly +specified by clients; +@item Accepts services which only support encryption types known to be weak. +@end itemize + +The @code{krb5-realm} and @code{krb5-configuration} types have many fields. +Only the most commonly used ones are described here. +For a full list, and more detailed explanation of each, see the MIT +@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} +documentation. + + +@deftp {Data Type} krb5-realm +@cindex realm, kerberos +@table @asis +@item @code{name} +This field is a string identifying the name of the realm. +A common convention is to use the fully qualified DNS name of your organization, +converted to upper case. + +@item @code{admin-server} +This field is a string identifying the host where the administration server is +running. + +@item @code{kdc} +This field is a string identifying the key distribution center +for the realm. +@end table +@end deftp + +@deftp {Data Type} krb5-configuration + +@table @asis +@item @code{allow-weak-crypto?} (default: @code{#f}) +If this flag is @code{#t} then services which only offer encryption algorithms +known to be weak will be accepted. + +@item @code{default-realm} (default: @code{#f}) +This field should be a string identifying the default Kerberos +realm for the client. +You should set this field to the name of your Kerberos realm. +If this value is @code{#f} +then a realm must be specified with every Kerberos principal when invoking programs +such as @command{kinit}. + +@item @code{realms} +This should be a non-empty list of @code{krb5-realm} objects, which clients may +access. +Normally, one of them will have a @code{name} field matching the @code{default-realm} +field. +@end table +@end deftp + + @subsubheading PAM krb5 Service @cindex pam-krb5 @@ -11509,8 +11861,8 @@ The @code{(gnu services web)} module provides the following service: @deffn {Scheme Procedure} nginx-service [#:nginx nginx] @ [#:log-directory ``/var/log/nginx''] @ [#:run-directory ``/var/run/nginx''] @ - [#:vhost-list (list (nginx-vhost-configuration))] @ - [#:config-file] + [#:server-list '()] @ + [#:config-file @code{#f}] Return a service that runs @var{nginx}, the nginx web server. @@ -11520,32 +11872,46 @@ files are written to @var{run-directory}. For proper operation, these arguments should match what is in @var{config-file} to ensure that the directories are created when the service is activated. -As an alternative to using a @var{config-file}, @var{vhost-list} can be -used to specify the list of @dfn{virtual hosts} required on the host. For +As an alternative to using a @var{config-file}, @var{server-list} can be +used to specify the list of @dfn{server blocks} required on the host. For this to work, use the default value for @var{config-file}. @end deffn -@deftp {Data Type} nginx-vhost-configuration -Data type representing the configuration of an nginx virtual host. +@deffn {Scheme Variable} nginx-service-type +This is type for the nginx web server. + +This service can be extended to add server blocks in addition to the +default one, as in this example: + +@example +(simple-service 'my-extra-server nginx-service-type + (list (nginx-server-configuration + (https-port #f) + (root "/srv/http/extra-website")))) +@end example +@end deffn + +@deftp {Data Type} nginx-server-configuration +Data type representing the configuration of an nginx server block. This type has the following parameters: @table @asis @item @code{http-port} (default: @code{80}) Nginx will listen for HTTP connection on this port. Set it at @code{#f} if nginx should not listen for HTTP (non secure) connection for this -@dfn{virtual host}. +@dfn{server block}. @item @code{https-port} (default: @code{443}) Nginx will listen for HTTPS connection on this port. Set it at @code{#f} if -nginx should not listen for HTTPS (secure) connection for this @dfn{virtual host}. +nginx should not listen for HTTPS (secure) connection for this @dfn{server block}. Note that nginx can listen for HTTP and HTTPS connections in the same -@dfn{virtual host}. +@dfn{server block}. @item @code{server-name} (default: @code{(list 'default)}) -A list of server names this vhost represents. @code{'default} represents the -default vhost for connections matching no other vhost. +A list of server names this server represents. @code{'default} represents the +default server for connections matching no other server. @item @code{root} (default: @code{"/srv/http"}) Root of the website nginx will serve. @@ -11683,6 +12049,93 @@ If it is @code{#f} then the daemon will use the host's fully qualified domain na @end table @end deftp +@node Continuous Integration +@subsubsection Continuous Integration + +@cindex continuous integration +@uref{https://notabug.org/mthl/cuirass, Cuirass} is a continuous +integration tool for Guix. It can be used both for development and for +providing substitutes to others (@pxref{Substitutes}). + +The @code{(gnu services cuirass)} module provides the following service. + +@defvr {Scheme Procedure} cuirass-service-type +The type of the Cuirass service. Its value must be a +@code{cuirass-configuration} object, as described below. +@end defvr + +To add build jobs, you have to set the @code{specifications} field of +the configuration. Here is an example of a service defining a build job +based on a specification that can be found in Cuirass source tree. This +service polls the Guix repository and builds a subset of the Guix +packages, as prescribed in the @file{gnu-system.scm} example spec: + +@example +(let ((spec #~((#:name . "guix") + (#:url . "git://git.savannah.gnu.org/guix.git") + (#:load-path . ".") + + ;; Here we must provide an absolute file name. + ;; We take jobs from one of the examples provided + ;; by Cuirass. + (#:file . #$(file-append + cuirass + "/tests/gnu-system.scm")) + + (#:proc . hydra-jobs) + (#:arguments (subset . "hello")) + (#:branch . "master")))) + (service cuirass-service-type + (cuirass-configuration + (specifications #~(list #$spec))))) +@end example + +While information related to build jobs is located directly in the +specifications, global settings for the @command{cuirass} process are +accessible in other @code{cuirass-configuration} fields. + +@deftp {Data Type} cuirass-configuration +Data type representing the configuration of Cuirass. + +@table @asis +@item @code{log-file} (default: @code{"/var/log/cuirass.log"}) +Location of the log file. + +@item @code{cache-directory} (default: @code{"/var/cache/cuirass"}) +Location of the repository cache. + +@item @code{user} (default: @code{"cuirass"}) +Owner of the @code{cuirass} process. + +@item @code{group} (default: @code{"cuirass"}) +Owner's group of the @code{cuirass} process. + +@item @code{interval} (default: @code{60}) +Number of seconds between the poll of the repositories followed by the +Cuirass jobs. + +@item @code{database} (default: @code{"/var/run/cuirass/cuirass.db"}) +Location of sqlite database which contains the build results and previously +added specifications. + +@item @code{specifications} (default: @code{#~'()}) +A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications, +where a specification is an association list +(@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) whose +keys are keywords (@code{#:keyword-example}) as shown in the example +above. + +@item @code{use-substitutes?} (default: @code{#f}) +This allows using substitutes to avoid building every dependencies of a job +from source. + +@item @code{one-shot?} (default: @code{#f}) +Only evaluate specifications and build derivations once. + +@item @code{cuirass} (default: @code{cuirass}) +The Cuirass package to use. +@end table +@end deftp @node Miscellaneous Services @subsubsection Miscellaneous Services @@ -12224,6 +12677,9 @@ The number of seconds to wait for keyboard input before booting. Set to @item @code{theme} (default: @var{%default-theme}) The @code{grub-theme} object describing the theme to use. + +@item @code{grub} (default: @code{grub}) +The GRUB package to use. @end table @end deftp @@ -12339,6 +12795,12 @@ currently running; if a service is currently running, it does not attempt to upgrade it since this would not be possible without stopping it first. +This command creates a new generation whose number is one greater than +the current generation (as reported by @command{guix system +list-generations}). If that generation already exists, it will be +overwritten. This behavior mirrors that of @command{guix package} +(@pxref{Invoking guix package}). + It also adds a GRUB menu entry for the new OS configuration, and moves entries for older configurations to a submenu---unless @option{--no-grub} is passed. @@ -12639,8 +13101,7 @@ host. @item -net user Enable the unprivileged user-mode network stack. The guest OS can access the host but not vice versa. This is the simplest way to get the -guest OS online. If you do not choose a network stack, the boot will -fail. +guest OS online. @item -net nic,model=virtio You must create a network interface of a given model. If you do not @@ -13747,7 +14208,6 @@ for instance, the module python-dateutil is packaged under the names starts with @code{py} (e.g. @code{pytz}), we keep it and prefix it as described above. - @subsubsection Specifying Dependencies @cindex inputs, for Python packages @@ -13764,6 +14224,12 @@ following check list to determine which dependency goes where. @itemize @item +We currently package Python 2 with @code{setuptools} and @code{pip} +installed like Python 3.4 has per default. Thus you don't need to +specify either of these as an input. @command{guix lint} will warn you +if you do. + +@item Python dependencies required at run time go into @code{propagated-inputs}. They are typically defined with the @code{install_requires} keyword in @file{setup.py}, or in the @@ -13777,8 +14243,7 @@ testing---e.g., those in @code{tests_require}---go into propagated because they are not needed at run time, and (2) in a cross-compilation context, it's the ``native'' input that we'd want. -Examples are @code{setuptools}, which is usually needed only at build -time, or the @code{pytest}, @code{mock}, and @code{nose} test +Examples are the @code{pytest}, @code{mock}, and @code{nose} test frameworks. Of course if any of these packages is also required at run-time, it needs to go to @code{propagated-inputs}. |