@include version.texi
+@c Identifier of the OpenPGP key used to sign tarballs and such.
+@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
+
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2015, 2016 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016 Chris Marusich@*
-Copyright @copyright{} 2016 Efraim Flashner
+Copyright @copyright{} 2016 Efraim Flashner@*
+Copyright @copyright{} 2016 John Darrington@*
+Copyright @copyright{} 2016 ng0@*
+Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016 Julien Lepiller
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* USB Stick Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
+* Installing GuixSD in a VM:: GuixSD playground.
* Building the Installation Image:: How this comes to be.
System Configuration
* Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service.
+* Log Rotation:: The rottlog service.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Web Services:: Web servers.
-* Various Services:: Other services.
+* Network File System:: NFS related services.
+* Miscellaneous Services:: Other services.
Defining Services
where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
already running the kernel Linux, and so on.
+@c The following is somewhat duplicated in ``System Installation''.
Make sure to download the associated @file{.sig} file and to verify the
authenticity of the tarball against it, along these lines:
then run this command to import it:
@example
-$ gpg --keyserver pgp.mit.edu --recv-keys 090B11993D9AEBB5
+$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
@noindent
and rerun the @code{gpg --verify} command.
+@c end authentication part
@item
As @code{root}, run:
@end enumerate
This completes root-level install of Guix. Each user will need to
-perform additional steps to make their Guix envionment ready for use,
+perform additional steps to make their Guix environment ready for use,
@pxref{Application Setup}.
You can confirm that Guix is working by installing a sample package into
When using Guix on a foreign distro, you can install this package and
define the relevant environment variables so that packages know where to
-look for certificates. @pxref{X.509 Certificates}, for detailed
+look for certificates. @xref{X.509 Certificates}, for detailed
information.
@subsection Emacs Packages
You may also specify the full name of a package to only get details about a
specific version of it:
@example
-$ guix package --show=python-3.3.5 | recsel -p name,version
+$ guix package --show=python@@3.4 | recsel -p name,version
name: python
-version: 3.3.5
+version: 3.4.3
@end example
When provided, @var{options} must be a comma-separated list containing one
or more of @code{contents} and @code{repair}.
-When passing @option{--verify=contents}, the daemon computse the
+When passing @option{--verify=contents}, the daemon computes the
content hash of each store item and compares it against its hash in the
database. Hash mismatches are reported as data corruptions. Because it
traverses @emph{all the files in the store}, this command can take a
Configure and Build System}).
@end deffn
+@cindex package transformations
+@cindex input rewriting
+@cindex dependency tree rewriting
+Packages can be manipulated in arbitrary ways. An example of a useful
+transformation is @dfn{input rewriting}, whereby the dependency tree of
+a package is rewritten by replacing specific inputs by others:
+
+@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
+ [@var{rewrite-name}]
+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.
+
+Optionally, @var{rewrite-name} is a one-argument procedure that takes
+the name of a package and returns its new name after rewrite.
+@end deffn
+
+@noindent
+Consider this example:
+
+@example
+(define libressl-instead-of-openssl
+ ;; This is a procedure to replace OPENSSL by LIBRESSL,
+ ;; recursively.
+ (package-input-rewriting `((,openssl . ,libressl))))
+
+(define git-with-libressl
+ (libressl-instead-of-openssl git))
+@end example
+
+@noindent
+Here we first define a rewriting procedure that replaces @var{openssl}
+with @var{libressl}. Then we use it to define a @dfn{variant} of the
+@var{git} package that uses @var{libressl} instead of @var{openssl}.
+This is exactly what the @option{--with-input} command-line option does
+(@pxref{Package Transformation Options, @option{--with-input}}).
+
@menu
* package Reference :: The package data type.
* origin Reference:: The origin data type.
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, GHC, and
+@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}.
@end defvr
+@defvr {Scheme Variable} asdf-build-system/source
+@defvrx {Scheme Variable} asdf-build-system/sbcl
+@defvrx {Scheme Variable} asdf-build-system/ecl
+
+These variables, exported by @code{(guix build-system asdf)}, implement
+build procedures for Common Lisp packages using
+@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
+definition facility for Common Lisp programs and libraries.
+
+The @code{asdf-build-system/source} system installs the packages in
+source form, and can be loaded using any common lisp implementation, via
+ASDF. The others, such as @code{asdf-build-system/sbcl}, install binary
+systems in the format which a particular implementation understands.
+These build systems can also be used to produce executable programs, or
+lisp images which contain a set of packages pre-loaded.
+
+The build system uses naming conventions. For binary packages, the
+package itself as well as its run-time dependencies should begin their
+name with the lisp implementation, such as @code{sbcl-} for
+@code{asdf-build-system/sbcl}. Beginning the input name with this
+prefix will allow the build system to encode its location into the
+resulting library, so that the input can be found at run-time.
+
+If dependencies are used only for tests, it is convenient to use a
+different prefix in order to avoid having a run-time dependency on such
+systems. For example,
+
+@example
+(define-public sbcl-bordeaux-threads
+ (package
+ ...
+ (native-inputs `(("tests:cl-fiveam" ,sbcl-fiveam)))
+ ...))
+@end example
+
+Additionally, the corresponding source package should be labeled using
+the same convention as python packages (see @ref{Python Modules}), using
+the @code{cl-} prefix.
+
+For binary packages, each system should be defined as a Guix package.
+If one package @code{origin} contains several systems, package variants
+can be created in order to build all the systems. Source packages,
+which use @code{asdf-build-system/source}, may contain several systems.
+
+In order to create executable programs and images, the build-side
+procedures @code{build-program} and @code{build-image} can be used.
+They should be called in a build phase after the @code{create-symlinks}
+phase, so that the system which was just built can be used within the
+resulting image. @code{build-program} requires a list of Common Lisp
+expressions to be passed as the @code{#:entry-program} argument.
+
+If the system is not defined within its own @code{.asd} file of the same
+name, then the @code{#:asd-file} parameter should be used to specify
+which file the system is defined in.
+
+@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
"-s"
(string-append #$emacs "/bin/emacs")
(string-append #$output "/bin/vi")))
- #:target "mips64el-linux")
+ #:target "mips64el-linux-gnu")
@end example
@noindent
pulled into the isolated build environment of our gexp, such that
@code{(use-modules (guix build utils))} works as expected.
+@cindex module closure
+@findex source-module-closure
+Usually you want the @emph{closure} of the module to be imported---i.e.,
+the module itself and all the modules it depends on---rather than just
+the module; failing to do that, attempts to use the module will fail
+because of missing dependent modules. The @code{source-module-closure}
+procedure computes the closure of a module by looking at its source file
+headers, which comes in handy in this case:
+
+@example
+(use-modules (guix modules)) ;for 'source-module-closure'
+
+(with-imported-modules (source-module-closure
+ '((guix build utils)
+ (gnu build vm)))
+ (gexp->derivation "something-with-vms"
+ #~(begin
+ (use-modules (guix build utils)
+ (gnu build vm))
+ @dots{})))
+@end example
+
The syntactic form to construct gexps is summarized below.
@deffn {Scheme Syntax} #~@var{exp}
these objects lead to a file in the store. Consider this G-expression:
@example
-#~(system* (string-append #$glibc "/sbin/nscd") "-f"
+#~(system* #$(file-append glibc "/sbin/nscd") "-f"
#$(local-file "/tmp/my-nscd.conf"))
@end example
(use-modules (guix gexp) (gnu packages base))
(gexp->script "list-files"
- #~(execl (string-append #$coreutils "/bin/ls")
+ #~(execl #$(file-append coreutils "/bin/ls")
"ls"))
@end example
@example
#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
!#
-(execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
- "ls")
+(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
@end example
@end deffn
This is the declarative counterpart of @code{text-file*}.
@end deffn
+@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
+Return a file-like object that expands to the concatenation of @var{obj}
+and @var{suffix}, where @var{obj} is a lowerable object and each
+@var{suffix} is a string.
+
+As an example, consider this gexp:
+
+@example
+(gexp->script "run-uname"
+ #~(system* #$(file-append coreutils
+ "/bin/uname")))
+@end example
+
+The same effect could be achieved with:
+
+@example
+(gexp->script "run-uname"
+ #~(system* (string-append #$coreutils
+ "/bin/uname")))
+@end example
+
+There is one difference though: in the @code{file-append} case, the
+resulting script contains the absolute file name as a string, whereas in
+the second case, the resulting script contains a @code{(string-append
+@dots{})} expression to construct the file name @emph{at run time}.
+@end deffn
+
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
@code{guix} and its dependency @code{guile-json} (which also depends on
@code{guile}) get rebuilt against @code{guile-next}.
-However, implicit inputs are left unchanged.
+This is implemented using the @code{package-input-rewriting} Scheme
+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
+built and then @dfn{grafted} onto the binaries that were initially
+referring to @var{package}. @xref{Security Updates}, for more
+information on grafts.
+
+For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
+and all its dependencies, replacing references to the version of GnuTLS
+they currently refer to:
+
+@example
+guix build --with-graft=gnutls=gnutls@@3.5.4 wget
+@end example
+
+This has the advantage of being much faster than rebuilding everything.
+But there is a caveat: it works if and only if @var{package} and
+@var{replacement} are strictly compatible---for example, if they provide
+a library, the application binary interface (ABI) of those libraries
+must be compatible. If @var{replacement} is somehow incompatible with
+@var{package}, then the resulting package may be unusable. Use with
+care!
+
@end table
@node Additional Build Options
@cindex package definition, editing
So many packages, so many source files! The @command{guix edit} command
-facilitates the life of packagers by pointing their editor at the source
-file containing the definition of the specified packages. For instance:
+facilitates the life of users and packagers by pointing their editor at
+the source file containing the definition of the specified packages.
+For instance:
@example
guix edit gcc@@4.9 vim
@noindent
launches the program specified in the @code{VISUAL} or in the
-@code{EDITOR} environment variable to edit the recipe of GCC@tie{}4.9.3
+@code{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
and that of Vim.
+If you are using a Guix Git checkout (@pxref{Building from Git}), or
+have created your own packages on @code{GUIX_PACKAGE_PATH}
+(@pxref{Defining Packages}), you will be able to edit the package
+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 hash @var{option} @var{file}
@end example
-@command{guix hash} has the following option:
+@command{guix hash} has the following options:
@table @code
@c FIXME: Replace xref above with xref to an ``Archive'' section when
@c it exists.
+@item --exclude-vcs
+@itemx -x
+When combined with @option{--recursive}, exclude version control system
+directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)
+
@vindex git-fetch
As an example, here is how you would compute the hash of a Git checkout,
which is useful when using the @code{git-fetch} method (@pxref{origin
@example
$ git clone http://example.org/foo.git
$ cd foo
-$ rm -rf .git
-$ guix hash -r .
+$ guix hash -rx .
@end example
@end table
the updater for GNU packages;
@item gnome
the updater for GNOME packages;
+@item kde
+the updater for KDE packages;
@item xorg
the updater for X.org packages;
@item elpa
@example
guix graph -t references `readlink -f ~/.guix-profile`
@end example
+
+@item referrers
+This is the graph of the @dfn{referrers} of a store item, as returned by
+@command{guix gc --referrers} (@pxref{Invoking guix gc}).
+
+This relies exclusively on local information from your store. For
+instance, let us suppose that the current Inkscape is available in 10
+profiles on your machine; @command{guix graph -t referrers inkscape}
+will show a graph rooted at Inkscape and with those 10 profiles linked
+to it.
+
+It can help determine what is preventing a store item from being garbage
+collected.
+
@end table
The available options are the following:
@vindex GUIX_ENVIRONMENT
@command{guix environment} defines the @code{GUIX_ENVIRONMENT}
-variable in the shell it spawns. This allows users to, say, define a
+variable in the shell it spawns; its value is the file name of the
+profile of this environment. This allows users to, say, define a
specific prompt for development environments in their @file{.bashrc}
(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
fi
@end example
+@noindent
+... or to browse the profile:
+
+@example
+$ ls "$GUIX_ENVIRONMENT/bin"
+@end example
+
Additionally, more than one package may be specified, in which case the
union of the inputs for the given packages are used. For example, the
command below spawns a shell where all of the dependencies of both Guile
@section System Installation
@cindex Guix System Distribution
-This section explains how to install the Guix System Distribution
+This section explains how to install the Guix System Distribution (GuixSD)
on a machine. The Guix package manager can
also be installed on top of a running GNU/Linux system,
@pxref{Installation}.
* USB Stick Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
+* Installing GuixSD in a VM:: GuixSD playground.
* Building the Installation Image:: How this comes to be.
@end menu
(@pxref{Services}).
@item
-More than 3,200 packages are available, but you may
+More than 4,000 packages are available, but you may
occasionally find that a useful package is missing.
@item
for a 32-bit GNU/Linux system on Intel-compatible CPUs.
@end table
+@c start duplication of authentication part from ``Binary Installation''
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the image against it, along these lines:
+
+@example
+$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
+$ gpg --verify guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
+@end example
+
+If that command fails because you do not have the required public key,
+then run this command to import it:
+
+@example
+$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+@end example
+
+@noindent
+and rerun the @code{gpg --verify} command.
+@c end duplication
+
This image contains a single partition with the tools necessary for an
installation. It is meant to be copied @emph{as is} to a large-enough
USB stick.
the USB stick. The latter usually requires you to get in the BIOS' boot
menu, where you can choose to boot from the USB stick.
+@xref{Installing GuixSD in a VM}, if, instead, you would like to install
+GuixSD in a virtual machine (VM).
+
@node Preparing for Installation
@subsection Preparing for Installation
Next, you have to edit a file and
provide the declaration of the operating system to be installed. To
-that end, the installation system comes with two text editors: GNU nano
-(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
+that end, the installation system comes with three text editors: GNU nano
+(@pxref{Top,,, nano, GNU nano Manual}), GNU Zile (an Emacs clone), and
+nvi (a clone of the original BSD @command{vi} editor).
We strongly recommend storing that file on the target root file system, say,
as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
configuration file once you have rebooted into the newly-installed system.
@file{guix-devel@@gnu.org} to share your experience---good or not so
good.
+@node Installing GuixSD in a VM
+@subsection Installing GuixSD in a Virtual Machine
+
+@cindex virtual machine, GuixSD installation
+If you'd like to install GuixSD in a virtual machine (VM) rather than on
+your beloved machine, this section is for you.
+
+To boot a @uref{http://qemu.org/,QEMU} VM for installing GuixSD in a
+disk image, follow these steps:
+
+@enumerate
+@item
+First, retrieve the GuixSD installation image as described previously
+(@pxref{USB Stick Installation}).
+
+@item
+Create a disk image that will hold the installed system. To make a
+qcow2-formatted disk image, use the @command{qemu-img} command:
+
+@example
+qemu-img create -f qcow2 guixsd.img 5G
+@end example
+
+This will create a 5GB file.
+
+@item
+Boot the USB installation image in an VM:
+
+@example
+qemu-system-x86_64 -m 1024 -smp 1 \
+ -net default -net nic,model=virtio -boot menu=on \
+ -drive file=guixsd.img \
+ -drive file=guixsd-usb-install-@value{VERSION}.@var{system}
+@end example
+
+In the VM console, quickly press the @kbd{F12} key to enter the boot
+menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
+selection.
+
+@item
+You're now root in the VM, proceed with the installation process.
+@xref{Preparing for Installation}, and follow the instructions.
+@end enumerate
+
+Once installation is complete, you can boot the system that's on your
+@file{guixsd.img} image. @xref{Running GuixSD in a VM}, for how to do
+that.
+
@node Building the Installation Image
@subsection Building the Installation Image
(extra-options '("--gc-keep-derivations"))))
(mingetty-service-type config =>
(mingetty-configuration
- (inherit config)
- (motd (plain-file "motd" "Howdy!"))))))
+ (inherit config)))))
(operating-system
;; @dots{}
@cindex mapped devices
The Linux kernel has a notion of @dfn{device mapping}: a block device,
such as a hard disk partition, can be @dfn{mapped} into another device,
+usually in @code{/dev/mapper/},
with additional processing over the data that flows through
it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
concept of a ``mapped device'' and that of a file system: both boil down
(@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
typical example is encryption device mapping: all writes to the mapped
device are encrypted, and all reads are deciphered, transparently.
+Guix extends this notion by considering any device or set of devices that
+are @dfn{transformed} in some way to create a new device; for instance,
+RAID devices are obtained by @dfn{assembling} several other devices, such
+as hard disks or partitions, into a new one that behaves as one partition.
+Other examples, not yet implemented, are LVM logical volumes.
-Mapped devices are declared using the @code{mapped-device} form:
-
-@example
-(mapped-device
- (source "/dev/sda3")
- (target "home")
- (type luks-device-mapping))
-@end example
-
-Or, better yet, like this:
-
-@example
-(mapped-device
- (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
- (target "home")
- (type luks-device-mapping))
-@end example
-
-@cindex disk encryption
-@cindex LUKS
-This 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
-standard mechanism for disk encryption. In the second example, the UUID
-(unique identifier) is the LUKS UUID returned for the device by a
-command like:
-
-@example
-cryptsetup luksUUID /dev/sdx9
-@end example
-
-The @file{/dev/mapper/home}
-device can then be used as the @code{device} of a @code{file-system}
-declaration (@pxref{File Systems}). The @code{mapped-device} form is
-detailed below.
+Mapped devices are declared using the @code{mapped-device} form,
+defined as follows; for examples, see below.
@deftp {Data Type} mapped-device
Objects of this type represent device mappings that will be made when
@table @code
@item source
-This string specifies the name of the block device to be mapped, such as
-@code{"/dev/sda3"}.
+This is either a string specifying the name of the block device to be mapped,
+such as @code{"/dev/sda3"}, or a list of such strings when several devices
+need to be assembled for creating a new one.
@item target
-This string specifies the name of the mapping to be established. For
-example, specifying @code{"my-partition"} will lead to the creation of
+This string specifies the name of the resulting mapped device. For
+kernel mappers such as encrypted devices of type @code{luks-device-mapping},
+specifying @code{"my-partition"} leads to the creation of
the @code{"/dev/mapper/my-partition"} device.
+For RAID devices of type @code{raid-device-mapping}, the full device name
+such as @code{"/dev/md0"} needs to be given.
@item type
This must be a @code{mapped-device-kind} object, which specifies how
@code{dm-crypt} Linux kernel module.
@end defvr
+@defvr {Scheme Variable} raid-device-mapping
+This defines a RAID device, which is assembled using the @code{mdadm}
+command from the package with the same name. It requires a Linux kernel
+module for the appropriate RAID level to be loaded, such as @code{raid456}
+for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
+@end defvr
+
+@cindex disk encryption
+@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
+standard mechanism for disk encryption.
+The @file{/dev/mapper/home}
+device can then be used as the @code{device} of a @code{file-system}
+declaration (@pxref{File Systems}).
+
+@example
+(mapped-device
+ (source "/dev/sda3")
+ (target "home")
+ (type luks-device-mapping))
+@end example
+
+Alternatively, to become independent of device numbering, one may obtain
+the LUKS UUID (@dfn{unique identifier}) of the source device by a
+command like:
+
+@example
+cryptsetup luksUUID /dev/sda3
+@end example
+
+and use it as follows:
+
+@example
+(mapped-device
+ (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
+ (target "home")
+ (type luks-device-mapping))
+@end example
+
+A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
+may be declared as follows:
+
+@example
+(mapped-device
+ (source (list "/dev/sda1" "/dev/sdb1"))
+ (target "/dev/md0")
+ (type raid-device-mapping))
+@end example
+
+The @file{/dev/md0} device can then be used as the @code{device} of a
+@code{file-system} declaration (@pxref{File Systems}).
+Note that the RAID level need not be given; it is chosen during the
+initial creation and formatting of the RAID device and is determined
+automatically later.
+
+
@node User Accounts
@subsection User Accounts
@item @code{home-directory}
This is the name of the home directory for the account.
+@item @code{create-home-directory?} (default: @code{#t})
+Indicates whether the home directory of this account should be created
+if it does not exist yet.
+
@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}).
data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
the incompatible locale data, which is already an improvement.}.
Similarly, a program linked against libc 2.22 can read most, but not
-all, the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
+all, of the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
data is incompatible); thus calls to @code{setlocale} may fail, but
programs will not abort.
when the system boots, or other actions needed at that time---e.g.,
configuring network access.
-Services are managed by the GNU@tie{}Shepherd (@pxref{Introduction,,,
-shepherd, The GNU Shepherd Manual}). On a running system, the
-@command{herd} command allows you to list the available services, show
-their status, start and stop them, or do other specific operations
-(@pxref{Jump Start,,, shepherd, The GNU Shepherd Manual}). For example:
+GuixSD has a broad definition of ``service'' (@pxref{Service
+Composition}), but many services are managed by the GNU@tie{}Shepherd
+(@pxref{Shepherd Services}). On a running system, the @command{herd}
+command allows you to list the available services, show their status,
+start and stop them, or do other specific operations (@pxref{Jump
+Start,,, shepherd, The GNU Shepherd Manual}). For example:
@example
# herd status
@menu
* Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service.
+* 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.
* Web Services:: Web servers.
-* Various Services:: Other services.
+* Network File System:: NFS related services.
+* Miscellaneous Services:: Other services.
@end menu
@node Base Services
Return a service that sets the host name to @var{name}.
@end deffn
+@deffn {Scheme Procedure} login-service @var{config}
+Return a service to run login according to @var{config}, a
+@code{<login-configuration>} object, which specifies the message of the day,
+among other things.
+@end deffn
+
+@deftp {Data Type} login-configuration
+This is the data type representing the configuration of login.
+
+@table @asis
+
+@item @code{motd}
+A file-like object containing the ``message of the day''.
+
+@item @code{allow-empty-passwords?} (default: @code{#t})
+Allow empty passwords by default so that first-time users can log in when
+the 'root' account has just been created.
+
+@end table
+@end deftp
+
@deffn {Scheme Procedure} mingetty-service @var{config}
Return a service to run mingetty according to @var{config}, a
@code{<mingetty-configuration>} object, which specifies the tty to run, among
@item @code{tty}
The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
-@item @code{motd}
-A file-like object containing the ``message of the day''.
-
@item @code{auto-login} (default: @code{#f})
When true, this field must be a string denoting the user name under
which the system automatically logs in. When it is @code{#f}, a
@end table
@end deftp
+@deffn {Scheme Procedure} kmscon-service-type @var{config}
+Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
+according to @var{config}, a @code{<kmscon-configuration>} object, which
+specifies the tty to run, among other things.
+@end deffn
+
+@deftp {Data Type} kmscon-configuration
+This is the data type representing the configuration of Kmscon, which
+implements console log-in.
+
+@table @asis
+
+@item @code{virtual-terminal}
+The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
+
+@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
+A gexp denoting the name of the log-in program. The default log-in program is
+@command{login} from the Shadow tool suite.
+
+@item @code{login-arguments} (default: @code{'("-p")})
+A list of arguments to pass to @command{login}.
+
+@item @code{hardware-acceleration?} (default: #f)
+Whether to use hardware acceleration.
+
+@item @code{kmscon} (default: @var{kmscon})
+The Kmscon package to use.
+
+@end table
+@end deftp
+
@cindex name service cache daemon
@cindex nscd
@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
external name servers do not even need to be queried.
@end defvr
+@anchor{syslog-configuration-type}
+@deftp {Data Type} syslog-configuration
+This data type represents the configuration of the syslog daemon.
+
+@table @asis
+@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
+The syslog daemon to use.
+
+@item @code{config-file} (default: @code{%default-syslog.conf})
+The syslog configuration file to use.
-@deffn {Scheme Procedure} syslog-service @
- [#:config-file @var{%default-syslog.conf}]
-Return a service that runs @command{syslogd}. If the configuration file
-name @var{config-file} is not specified, use some reasonable default
-settings.
+@end table
+@end deftp
+
+@anchor{syslog-service}
+@deffn {Scheme Procedure} syslog-service @var{config}
+Return a service that runs a syslog daemon according to @var{config}.
@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
information on the configuration file syntax.
Number of build user accounts to create.
@item @code{authorize-key?} (default: @code{#t})
-Whether to authorize the substitute key for @code{hydra.gnu.org}
+Whether to authorize the substitute keys listed in
+@code{authorized-keys}---by default that of @code{hydra.gnu.org}
(@pxref{Substitutes}).
+@vindex %default-authorized-guix-keys
+@item @code{authorized-keys} (default: @var{%default-authorized-guix-keys})
+The list of authorized key files for archive imports, as a list of
+string-valued gexps (@pxref{Invoking guix archive}). By default, it
+contains that of @code{hydra.gnu.org} (@pxref{Substitutes}).
+
@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.
commonly used for real-time audio systems.
@end deffn
-
@node Scheduled Job Execution
@subsubsection Scheduled Job Execution
#~(job "5 0 * * *" ;Vixie cron syntax
"guix gc -F 1G"))
-(define idutils-jobs
+(define idutils-job
;; Update the index database as user "charlie" at 12:15PM
;; and 19:15PM. This runs from the user's home directory.
#~(job '(next-minute-from (next-hour '(12 19)) '(15))
This is a shorthand for:
@example
- (service mcron-service-type
- (mcron-configuration (mcron mcron) (jobs jobs)))
+(service mcron-service-type
+ (mcron-configuration (mcron mcron) (jobs jobs)))
@end example
@end deffn
This service type can be the target of a service extension that provides
it additional job specifications (@pxref{Service Composition}). In
-other words, it is possible to define services that provide addition
+other words, it is possible to define services that provide additional
mcron jobs to run.
@end defvr
@end deftp
+@node Log Rotation
+@subsubsection Log Rotation
+
+@cindex rottlog
+@cindex log rotation
+Log files such as those found in @file{/var/log} tend to grow endlessly,
+so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
+their contents in separate files, possibly compressed. The @code{(gnu
+services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
+log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
+
+The example below defines an operating system that provides log rotation
+with the default settings.
+
+@lisp
+(use-modules (guix) (gnu))
+(use-service-modules admin mcron)
+(use-package-modules base idutils)
+
+(operating-system
+ ;; @dots{}
+ (services (cons* (mcron-service)
+ (service rottlog-service-type (rottlog-configuration))
+ %base-services)))
+@end lisp
+
+@defvr {Scheme Variable} rottlog-service-type
+This is the type of the Rottlog service, whose value is a
+@code{rottlog-configuration} object.
+
+This service type can define mcron jobs (@pxref{Scheduled Job
+Execution}) to run the rottlog service.
+@end defvr
+
+@deftp {Data Type} rottlog-configuration
+Data type representing the configuration of rottlog.
+
+@table @asis
+@item @code{rottlog} (default: @code{rottlog})
+The Rottlog package to use.
+
+@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
+The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
+rottlog, GNU Rot[t]log Manual}).
+
+@item @code{periodic-rotations} (default: @code{`(("weekly" %default-rotatations))})
+A list of Rottlog period-name/period-config tuples.
+
+For example, taking an example from the Rottlog manual (@pxref{Period
+Related File Examples,,, rottlog, GNU Rot[t]log Manual}), a valid tuple
+might be:
+
+@example
+("daily" ,(plain-file "daily"
+ "\
+ /var/log/apache/* @{
+ storedir apache-archives
+ rotate 6
+ notifempty
+ nocompress
+ @}"))
+@end example
+
+@item @code{jobs}
+This is a list of gexps where each gexp corresponds to an mcron job
+specification (@pxref{Scheduled Job Execution}).
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %default-rotations
+Specifies weekly rotation of @var{%rotated-files} and
+@code{"/var/log/shepherd.log"}.
+@end defvr
+
+@defvr {Scheme Variable} %rotated-files
+The list of syslog-controlled files to be rotated. By default it is:
+@code{'("/var/log/messages" "/var/log/secure")}.
+@end defvr
+
@node Networking Services
@subsubsection Networking Services
@end deffn
@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
- [#:name-service @var{%ntp-servers}]
+ [#:servers @var{%ntp-servers}] @
+ [#:allow-large-adjustment? #f]
Return a service that runs the daemon from @var{ntp}, the
@uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
keep the system clock synchronized with that of @var{servers}.
+@var{allow-large-adjustment?} determines whether @command{ntpd} is allowed to
+make an initial adjustment of more than 1,000 seconds.
@end deffn
@defvr {Scheme Variable} %ntp-servers
The other options should be self-descriptive.
@end deffn
-@deffn {Scheme Procedure} dropbear-service [@var{config}]
-Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
-daemon} with the given @var{config}, a @code{<dropbear-configuration>}
-object.
-
-For example, to specify a Dropbear service listening on port 1234, add
-this call to the operating system's @code{services} field:
+@deffn {Scheme Variable} openssh-service-type
+This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
+shell daemon, @command{sshd}. Its value must be an
+@code{openssh-configuration} record as in this example:
@example
-(dropbear-service (dropbear-configuration
- (port-number 1234)))
+(service openssh-service-type
+ (openssh-configuration
+ (x11-forwarding? #t)
+ (permit-root-login 'without-password)))
@end example
+
+See below for details about @code{openssh-configuration}.
@end deffn
-@deftp {Data Type} dropbear-configuration
-This data type represents the configuration of a Dropbear SSH daemon.
+@deftp {Data Type} openssh-configuration
+This is the configuration record for OpenSSH's @command{sshd}.
@table @asis
-@item @code{dropbear} (default: @var{dropbear})
-The Dropbear package to use.
+@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
+Name of the file where @command{sshd} writes its PID.
-@item @code{port-number} (default: 22)
-The TCP port where the daemon waits for incoming connections.
+@item @code{port-number} (default: @code{22})
+TCP port on which @command{sshd} listens for incoming connections.
-@item @code{syslog-output?} (default: @code{#t})
-Whether to enable syslog output.
+@item @code{permit-root-login} (default: @code{#f})
+This field determines whether and when to allow logins as root. If
+@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
+If it's the symbol @code{'without-password}, then root logins are
+permitted but not with password-based authentication.
-@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
-File name of the daemon's PID file.
+@item @code{allow-empty-passwords?} (default: @code{#f})
+When true, users with empty passwords may log in. When false, they may
+not.
+
+@item @code{password-authentication?} (default: @code{#t})
+When true, users may log in with their password. When false, they have
+other authentication methods.
+
+@item @code{public-key-authentication?} (default: @code{#t})
+When true, users may log in using public key authentication. When
+false, users have to use other authentication method.
+
+Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
+This is used only by protocol version 2.
+
+@item @code{rsa-authentication?} (default: @code{#t})
+When true, users may log in using pure RSA authentication. When false,
+users have to use other means of authentication. This is used only by
+protocol 1.
+
+@item @code{x11-forwarding?} (default: @code{#f})
+When true, forwarding of X11 graphical client connections is
+enabled---in other words, @command{ssh} options @option{-X} and
+@option{-Y} will work.
+
+@item @code{protocol-number} (default: @code{2})
+The SSH protocol number to use.
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} dropbear-service [@var{config}]
+Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
+daemon} with the given @var{config}, a @code{<dropbear-configuration>}
+object.
+
+For example, to specify a Dropbear service listening on port 1234, add
+this call to the operating system's @code{services} field:
+
+@example
+(dropbear-service (dropbear-configuration
+ (port-number 1234)))
+@end example
+@end deffn
+
+@deftp {Data Type} dropbear-configuration
+This data type represents the configuration of a Dropbear SSH daemon.
+
+@table @asis
+@item @code{dropbear} (default: @var{dropbear})
+The Dropbear package to use.
+
+@item @code{port-number} (default: 22)
+The TCP port where the daemon waits for incoming connections.
+
+@item @code{syslog-output?} (default: @code{#t})
+Whether to enable syslog output.
+
+@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
+File name of the daemon's PID file.
@item @code{root-login?} (default: @code{#f})
Whether to allow @code{root} logins.
-@item @code{allow-empty-passwords?} (default: @code{#f})
-Whether to allow empty passwords.
+@item @code{allow-empty-passwords?} (default: @code{#f})
+Whether to allow empty passwords.
+
+@item @code{password-authentication?} (default: @code{#t})
+Whether to enable password-based authentication.
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %facebook-host-aliases
+This variable contains a string for use in @file{/etc/hosts}
+(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
+line contains a entry that maps a known server name of the Facebook
+on-line service---e.g., @code{www.facebook.com}---to the local
+host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
+
+This variable is typically used in the @code{hosts-file} field of an
+@code{operating-system} declaration (@pxref{operating-system Reference,
+@file{/etc/hosts}}):
+
+@example
+(use-modules (gnu) (guix))
+
+(operating-system
+ (host-name "mymachine")
+ ;; ...
+ (hosts-file
+ ;; Create a /etc/hosts file with aliases for "localhost"
+ ;; and "mymachine", as well as for Facebook servers.
+ (plain-file "hosts"
+ (string-append (local-host-aliases host-name)
+ %facebook-host-aliases))))
+@end example
+
+This mechanism can prevent programs running locally, such as Web
+browsers, from accessing Facebook.
+@end defvr
+
+The @code{(gnu services avahi)} provides the following definition.
+
+@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
+ [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
+ [#:ipv6? #t] [#:wide-area? #f] @
+ [#:domains-to-browse '()] [#:debug? #f]
+Return a service that runs @command{avahi-daemon}, a system-wide
+mDNS/DNS-SD responder that allows for service discovery and
+"zero-configuration" host name lookups (see @uref{http://avahi.org/}), and
+extends the name service cache daemon (nscd) so that it can resolve
+@code{.local} host names using
+@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. Additionally,
+add the @var{avahi} package to the system profile so that commands such as
+@command{avahi-browse} are directly usable.
+
+If @var{host-name} is different from @code{#f}, use that as the host name to
+publish for this machine; otherwise, use the machine's actual host name.
+
+When @var{publish?} is true, publishing of host names and services is allowed;
+in particular, avahi-daemon will publish the machine's host name and IP
+address via mDNS on the local network.
+
+When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
+
+Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
+sockets.
+@end deffn
+
+
+@node X Window
+@subsubsection X Window
+
+Support for the X Window graphical display system---specifically
+Xorg---is provided by the @code{(gnu services xorg)} module. Note that
+there is no @code{xorg-service} procedure. Instead, the X server is
+started by the @dfn{login manager}, currently SLiM.
+
+@deftp {Data Type} sddm-configuration
+This is the data type representing the sddm service configuration.
+
+@table @asis
+@item @code{display-server} (default: "x11")
+Select display server to use for the greeter. Valid values are "x11"
+or "wayland".
+
+@item @code{numlock} (default: "on")
+Valid values are "on", "off" or "none".
+
+@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
+Command to run when halting.
+
+@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
+Command to run when rebooting.
+
+@item @code{theme} (default "maldives")
+Theme to use. Default themes provided by SDDM are "elarun" or "maldives".
+
+@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
+Directory to look for themes.
+
+@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
+Directory to look for faces.
+
+@item @code{default-path} (default "/run/current-system/profile/bin")
+Default PATH to use.
+
+@item @code{minimum-uid} (default 1000)
+Minimum UID to display in SDDM.
+
+@item @code{maximum-uid} (default 2000)
+Maximum UID to display in SDDM
+
+@item @code{remember-last-user?} (default #t)
+Remember last user.
+
+@item @code{remember-last-session?} (default #t)
+Remember last session.
+
+@item @code{hide-users} (default "")
+Usernames to hide from SDDM greeter.
+
+@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
+Users with shells listed will be hidden from the SDDM greeter.
+
+@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
+Script to run before starting a wayland session.
+
+@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
+Directory to look for desktop files starting wayland sessions.
+
+@item @code{xorg-server-path} (default @code{xorg-start-command})
+Path to xorg-server.
+
+@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
+Path to xauth.
+
+@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
+Path to Xephyr.
+
+@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
+Script to run after starting xorg-server.
+
+@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
+Script to run before stopping xorg-server.
+
+@item @code{xsession-command} (default: @code{xinitr })
+Script to run before starting a X session.
+
+@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
+Directory to look for desktop files starting X sessions.
+
+@item @code{minimum-vt} (default: 7)
+Minimum VT to use.
+
+@item @code{xserver-arguments} (default "-nolisten tcp")
+Arguments to pass to xorg-server.
+
+@item @code{auto-login-user} (default "")
+User to use for auto-login.
+
+@item @code{auto-login-session} (default "")
+Desktop file to use for auto-login.
+
+@item @code{relogin?} (default #f)
+Relogin after logout.
+
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} sddm-service config
+Return a service that spawns the SDDM graphical login manager for config of
+type @code{<sddm-configuration>}.
+
+@example
+ (sddm-service (sddm-configuration
+ (auto-login-user "Alice")
+ (auto-login-session "xfce.desktop")))
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @
+ [#:auto-login? #f] [#:default-user ""] [#:startx] @
+ [#:theme @var{%default-slim-theme}] @
+ [#:theme-name @var{%default-slim-theme-name}]
+Return a service that spawns the SLiM graphical login manager, which in
+turn starts the X display server with @var{startx}, a command as returned by
+@code{xorg-start-command}.
+
+@cindex X session
+
+SLiM automatically looks for session types described by the @file{.desktop}
+files in @file{/run/current-system/profile/share/xsessions} and allows users
+to choose a session from the log-in screen using @kbd{F1}. Packages such as
+@var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
+adding them to the system-wide set of packages automatically makes them
+available at the log-in screen.
+
+In addition, @file{~/.xsession} files are honored. When available,
+@file{~/.xsession} must be an executable that starts a window manager
+and/or other X clients.
+
+When @var{allow-empty-passwords?} is true, allow logins with an empty
+password. When @var{auto-login?} is true, log in automatically as
+@var{default-user}.
+
+If @var{theme} is @code{#f}, use the default log-in theme; otherwise
+@var{theme} must be a gexp denoting the name of a directory containing the
+theme to use. In that case, @var{theme-name} specifies the name of the
+theme.
+@end deffn
+
+@defvr {Scheme Variable} %default-theme
+@defvrx {Scheme Variable} %default-theme-name
+The G-Expression denoting the default SLiM theme and its name.
+@end defvr
+
+@deffn {Scheme Procedure} xorg-start-command [#:guile] @
+ [#:configuration-file #f] [#:xorg-server @var{xorg-server}]
+Return a derivation that builds a @var{guile} script to start the X server
+from @var{xorg-server}. @var{configuration-file} is the server configuration
+file or a derivation that builds it; when omitted, the result of
+@code{xorg-configuration-file} is used.
+
+Usually the X server is started by a login manager.
+@end deffn
+
+@deffn {Scheme Procedure} xorg-configuration-file @
+ [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
+Return a configuration file for the Xorg server containing search paths for
+all the common drivers.
+
+@var{drivers} must be either the empty list, in which case Xorg chooses a
+graphics driver automatically, or a list of driver names that will be tried in
+this order---e.g., @code{(\"modesetting\" \"vesa\")}.
+
+Likewise, when @var{resolutions} is the empty list, Xorg chooses an
+appropriate screen resolution; otherwise, it must be a list of
+resolutions---e.g., @code{((1024 768) (640 480))}.
+
+Last, @var{extra-config} is a list of strings or objects appended to the
+@code{text-file*} argument list. It is used to pass extra text to be added
+verbatim to the configuration file.
+@end deffn
+
+@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{name}]
+Add @var{package}, a package for a screen-locker or screen-saver whose
+command is @var{program}, to the set of setuid programs and add a PAM entry
+for it. For example:
+
+@lisp
+(screen-locker-service xlockmore "xlock")
+@end lisp
+
+makes the good ol' XlockMore usable.
+@end deffn
+
+
+@node Printing Services
+@subsubsection Printing Services
+
+The @code{(gnu services cups)} module provides a Guix service definition
+for the CUPS printing service. To add printer support to a GuixSD
+system, add a @code{cups-service} to the operating system definition:
+
+@deffn {Scheme Variable} cups-service-type
+The service type for the CUPS print server. Its value should be a valid
+CUPS configuration (see below). For example:
+@example
+(service cups-service-type (cups-configuration))
+@end example
+@end deffn
+
+The CUPS configuration controls the basic things about your CUPS
+installation: what interfaces it listens on, what to do if a print job
+fails, how much logging to do, and so on. To actually add a printer,
+you have to visit the @url{http://localhost:631} URL, or use a tool such
+as GNOME's printer configuration services. By default, configuring a
+CUPS service will generate a self-signed certificate if needed, for
+secure connections to the print server.
+
+One way you might want to customize CUPS is to enable or disable the web
+interface. You can do that directly, like this:
+
+@example
+(service cups-service-type
+ (cups-configuration
+ (web-interface? #f)))
+@end example
+
+The available configuration parameters follow. Each parameter
+definition is preceded by its type; for example, @samp{string-list foo}
+indicates that the @code{foo} parameter should be specified as a list of
+strings. There is also a way to specify the configuration as a string,
+if you have an old @code{cupsd.conf} file that you want to port over
+from some other system; see the end for more details.
+
+@c The following documentation was initially generated by
+@c (generate-documentation) in (gnu services cups). Manually maintained
+@c documentation is better, so we shouldn't hesitate to edit below as
+@c needed. However if the change you want to make to this documentation
+@c can be done in an automated way, it's probably easier to change
+@c (generate-documentation) than to make it below and have to deal with
+@c the churn as CUPS updates.
+
+
+Available @code{cups-configuration} fields are:
+
+@deftypevr {@code{cups-configuration} parameter} package cups
+The CUPS package.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} package-list extensions
+Drivers and other extensions to the CUPS package.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
+Configuration of where to write logs, what directories to use for print
+spools, and related privileged configuration parameters.
+
+Available @code{files-configuration} fields are:
+
+@deftypevr {@code{files-configuration} parameter} log-location access-log
+Defines the access log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-access_log}.
+
+Defaults to @samp{"/var/log/cups/access_log"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name cache-dir
+Where CUPS should cache data.
+
+Defaults to @samp{"/var/cache/cups"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string config-file-perm
+Specifies the permissions for all configuration files that the scheduler
+writes.
+
+Note that the permissions for the printers.conf file are currently
+masked to only allow access from the scheduler user (typically root).
+This is done because printer device URIs sometimes contain sensitive
+authentication information that should not be generally known on the
+system. There is no way to disable this security feature.
+
+Defaults to @samp{"0640"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} log-location error-log
+Defines the error log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-error_log}.
+
+Defaults to @samp{"/var/log/cups/error_log"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string fatal-errors
+Specifies which errors are fatal, causing the scheduler to exit. The
+kind strings are:
+
+@table @code
+@item none
+No errors are fatal.
+
+@item all
+All of the errors below are fatal.
+
+@item browse
+Browsing initialization errors are fatal, for example failed connections
+to the DNS-SD daemon.
+
+@item config
+Configuration file syntax errors are fatal.
+
+@item listen
+Listen or Port errors are fatal, except for IPv6 failures on the
+loopback or @code{any} addresses.
+
+@item log
+Log file creation or write errors are fatal.
+
+@item permissions
+Bad startup file permissions are fatal, for example shared TLS
+certificate and key files with world-read permissions.
+@end table
+
+Defaults to @samp{"all -browse"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} boolean file-device?
+Specifies whether the file pseudo-device can be used for new printer
+queues. The URI @uref{file:///dev/null} is always allowed.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string group
+Specifies the group name or ID that will be used when executing external
+programs.
+
+Defaults to @samp{"lp"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string log-file-perm
+Specifies the permissions for all log files that the scheduler writes.
+
+Defaults to @samp{"0644"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} log-location page-log
+Defines the page log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-page_log}.
+
+Defaults to @samp{"/var/log/cups/page_log"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string remote-root
+Specifies the username that is associated with unauthenticated accesses
+by clients claiming to be the root user. The default is @code{remroot}.
+
+Defaults to @samp{"remroot"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name request-root
+Specifies the directory that contains print jobs and other HTTP request
+data.
+
+Defaults to @samp{"/var/spool/cups"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
+Specifies the level of security sandboxing that is applied to print
+filters, backends, and other child processes of the scheduler; either
+@code{relaxed} or @code{strict}. This directive is currently only
+used/supported on macOS.
+
+Defaults to @samp{strict}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name server-keychain
+Specifies the location of TLS certificates and private keys. CUPS will
+look for public and private keys in this directory: a @code{.crt} files
+for PEM-encoded certificates and corresponding @code{.key} files for
+PEM-encoded private keys.
+
+Defaults to @samp{"/etc/cups/ssl"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name server-root
+Specifies the directory containing the server configuration files.
+
+Defaults to @samp{"/etc/cups"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
+Specifies whether the scheduler calls fsync(2) after writing
+configuration or state files.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
+Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} file-name temp-dir
+Specifies the directory where temporary files are stored.
+
+Defaults to @samp{"/var/spool/cups/tmp"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} string user
+Specifies the user name or ID that is used when running external
+programs.
+
+Defaults to @samp{"lp"}.
+@end deftypevr
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
+Specifies the logging level for the AccessLog file. The @code{config}
+level logs when printers and classes are added, deleted, or modified and
+when configuration files are accessed or updated. The @code{actions}
+level logs when print jobs are submitted, held, released, modified, or
+canceled, and any of the conditions for @code{config}. The @code{all}
+level logs all requests.
+
+Defaults to @samp{actions}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
+Specifies whether to purge job history data automatically when it is no
+longer required for quotas.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
+Specifies which protocols to use for local printer sharing.
+
+Defaults to @samp{dnssd}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
+Specifies whether the CUPS web interface is advertised.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean browsing?
+Specifies whether shared printers are advertised.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string classification
+Specifies the security classification of the server. Any valid banner
+name can be used, including "classified", "confidential", "secret",
+"topsecret", and "unclassified", or the banner can be omitted to disable
+secure printing functions.
+
+Defaults to @samp{""}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean classify-override?
+Specifies whether users may override the classification (cover page) of
+individual print jobs using the @code{job-sheets} option.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
+Specifies the default type of authentication to use.
+
+Defaults to @samp{Basic}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
+Specifies whether encryption will be used for authenticated requests.
+
+Defaults to @samp{Required}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string default-language
+Specifies the default language to use for text and web content.
+
+Defaults to @samp{"en"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string default-paper-size
+Specifies the default paper size for new print queues. @samp{"Auto"}
+uses a locale-specific default, while @samp{"None"} specifies there is
+no default paper size. Specific size names are typically
+@samp{"Letter"} or @samp{"A4"}.
+
+Defaults to @samp{"Auto"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string default-policy
+Specifies the default access policy to use.
+
+Defaults to @samp{"default"}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean default-shared?
+Specifies whether local printers are shared by default.
+
+Defaults to @samp{#t}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
+Specifies the delay for updating of configuration and state files, in
+seconds. A value of 0 causes the update to happen as soon as possible,
+typically within a few milliseconds.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} error-policy error-policy
+Specifies what to do when an error occurs. Possible values are
+@code{abort-job}, which will discard the failed print job;
+@code{retry-job}, which will retry the job at a later time;
+@code{retry-this-job}, which retries the failed job immediately; and
+@code{stop-printer}, which stops the printer.
+
+Defaults to @samp{stop-printer}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
+Specifies the maximum cost of filters that are run concurrently, which
+can be used to minimize disk, memory, and CPU resource problems. A
+limit of 0 disables filter limiting. An average print to a
+non-PostScript printer needs a filter limit of about 200. A PostScript
+printer needs about half that (100). Setting the limit below these
+thresholds will effectively limit the scheduler to printing a single job
+at any time.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
+Specifies the scheduling priority of filters that are run to print a
+job. The nice value ranges from 0, the highest priority, to 19, the
+lowest priority.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
+Specifies whether to do reverse lookups on connecting clients. The
+@code{double} setting causes @code{cupsd} to verify that the hostname
+resolved from the address matches one of the addresses returned for that
+hostname. Double lookups also prevent clients with unregistered
+addresses from connecting to your server. Only set this option to
+@code{#t} or @code{double} if absolutely required.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
+Specifies the number of seconds to wait before killing the filters and
+backend associated with a canceled or held job.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
+Specifies the interval between retries of jobs in seconds. This is
+typically used for fax queues but can also be used with normal print
+queues whose error policy is @code{retry-job} or
+@code{retry-current-job}.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
+Specifies the number of retries that are done for jobs. This is
+typically used for fax queues but can also be used with normal print
+queues whose error policy is @code{retry-job} or
+@code{retry-current-job}.
+
+Defaults to @samp{5}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
+Specifies whether to support HTTP keep-alive connections.
+
+Defaults to @samp{#t}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
+Specifies how long an idle client connection remains open, in seconds.
+
+Defaults to @samp{30}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
+Specifies the maximum size of print files, IPP requests, and HTML form
+data. A limit of 0 disables the limit check.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
+Listens on the specified interfaces for connections. Valid values are
+of the form @var{address}:@var{port}, where @var{address} is either an
+IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
+indicate all addresses. Values can also be file names of local UNIX
+domain sockets. The Listen directive is similar to the Port directive
+but allows you to restrict access to specific interfaces or networks.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
+Specifies the number of pending connections that will be allowed. This
+normally only affects very busy servers that have reached the MaxClients
+limit, but can also be triggered by large numbers of simultaneous
+connections. When the limit is reached, the operating system will
+refuse additional connections until the scheduler can accept the pending
+ones.
+
+Defaults to @samp{128}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
+Specifies a set of additional access controls.
+
+Available @code{location-access-controls} fields are:
+
+@deftypevr {@code{location-access-controls} parameter} file-name path
+Specifies the URI path to which the access control applies.
+@end deftypevr
+
+@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
+Access controls for all access to this path, in the same format as the
+@code{access-controls} of @code{operation-access-control}.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
+Access controls for method-specific access to this path.
+
+Defaults to @samp{()}.
+
+Available @code{method-access-controls} fields are:
+
+@deftypevr {@code{method-access-controls} parameter} boolean reverse?
+If @code{#t}, apply access controls to all methods except the listed
+methods. Otherwise apply to only the listed methods.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+@deftypevr {@code{method-access-controls} parameter} method-list methods
+Methods to which this access control applies.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
+Access control directives, as a list of strings. Each string should be
+one directive, such as "Order allow,deny".
+
+Defaults to @samp{()}.
+@end deftypevr
+@end deftypevr
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
+Specifies the number of debugging messages that are retained for logging
+if an error occurs in a print job. Debug messages are logged regardless
+of the LogLevel setting.
+
+Defaults to @samp{100}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} log-level log-level
+Specifies the level of logging for the ErrorLog file. The value
+@code{none} stops all logging while @code{debug2} logs everything.
+
+Defaults to @samp{info}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
+Specifies the format of the date and time in the log files. The value
+@code{standard} logs whole seconds while @code{usecs} logs microseconds.
+
+Defaults to @samp{standard}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
+Specifies the maximum number of simultaneous clients that are allowed by
+the scheduler.
+
+Defaults to @samp{100}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
+Specifies the maximum number of simultaneous clients that are allowed
+from a single address.
+
+Defaults to @samp{100}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
+Specifies the maximum number of copies that a user can print of each
+job.
+
+Defaults to @samp{9999}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
+Specifies the maximum time a job may remain in the @code{indefinite}
+hold state before it is canceled. A value of 0 disables cancellation of
+held jobs.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
+Specifies the maximum number of simultaneous jobs that are allowed. Set
+to 0 to allow an unlimited number of jobs.
+
+Defaults to @samp{500}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
+Specifies the maximum number of simultaneous jobs that are allowed per
+printer. A value of 0 allows up to MaxJobs jobs per printer.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
+Specifies the maximum number of simultaneous jobs that are allowed per
+user. A value of 0 allows up to MaxJobs jobs per user.
+
+Defaults to @samp{0}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
+Specifies the maximum time a job may take to print before it is
+canceled, in seconds. Set to 0 to disable cancellation of "stuck" jobs.
+
+Defaults to @samp{10800}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
+Specifies the maximum size of the log files before they are rotated, in
+bytes. The value 0 disables log rotation.
+
+Defaults to @samp{1048576}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
+Specifies the maximum amount of time to allow between files in a
+multiple file print job, in seconds.
+
+Defaults to @samp{300}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} string page-log-format
+Specifies the format of PageLog lines. Sequences beginning with percent
+(@samp{%}) characters are replaced with the corresponding information,
+while all other characters are copied literally. The following percent
+sequences are recognized:
+
+@table @samp
+@item %%
+insert a single percent character
+
+@item %@{name@}
+insert the value of the specified IPP attribute
+
+@item %C
+insert the number of copies for the current page
+
+@item %P
+insert the current page number
+
+@item %T
+insert the current date and time in common log format
+
+@item %j
+insert the job ID
+
+@item %p
+insert the printer name
+
+@item %u
+insert the username
+@end table
+
+A value of the empty string disables page logging. The string @code{%p
+%u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
+%@{job-name@} %@{media@} %@{sides@}} creates a page log with the
+standard items.
+
+Defaults to @samp{""}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
+Passes the specified environment variable(s) to child processes; a list
+of strings.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
+Specifies named access control policies.
+
+Available @code{policy-configuration} fields are:
+
+@deftypevr {@code{policy-configuration} parameter} string name
+Name of the policy.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} string job-private-access
+Specifies an access list for a job's private values. @code{@@ACL} maps
+to the printer's requesting-user-name-allowed or
+requesting-user-name-denied values. @code{@@OWNER} maps to the job's
+owner. @code{@@SYSTEM} maps to the groups listed for the
+@code{system-group} field of the @code{files-config} configuration,
+which is reified into the @code{cups-files.conf(5)} file. Other
+possible elements of the access list include specific user names, and
+@code{@@@var{group}} to indicate members of a specific group. The
+access list may also be simply @code{all} or @code{default}.
+
+Defaults to @samp{"@@OWNER @@SYSTEM"}.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} string job-private-values
+Specifies the list of job values to make private, or @code{all},
+@code{default}, or @code{none}.
+
+Defaults to @samp{"job-name job-originating-host-name
+job-originating-user-name phone"}.
+@end deftypevr
+
+@deftypevr {@code{policy-configuration} parameter} string subscription-private-access
+Specifies an access list for a subscription's private values.
+@code{@@ACL} maps to the printer's requesting-user-name-allowed or
+requesting-user-name-denied values. @code{@@OWNER} maps to the job's
+owner. @code{@@SYSTEM} maps to the groups listed for the
+@code{system-group} field of the @code{files-config} configuration,
+which is reified into the @code{cups-files.conf(5)} file. Other
+possible elements of the access list include specific user names, and
+@code{@@@var{group}} to indicate members of a specific group. The
+access list may also be simply @code{all} or @code{default}.
-@item @code{password-authentication?} (default: @code{#t})
-Whether to enable password-based authentication.
-@end table
-@end deftp
+Defaults to @samp{"@@OWNER @@SYSTEM"}.
+@end deftypevr
-@defvr {Scheme Variable} %facebook-host-aliases
-This variable contains a string for use in @file{/etc/hosts}
-(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
-line contains a entry that maps a known server name of the Facebook
-on-line service---e.g., @code{www.facebook.com}---to the local
-host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
+@deftypevr {@code{policy-configuration} parameter} string subscription-private-values
+Specifies the list of job values to make private, or @code{all},
+@code{default}, or @code{none}.
-This variable is typically used in the @code{hosts-file} field of an
-@code{operating-system} declaration (@pxref{operating-system Reference,
-@file{/etc/hosts}}):
+Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
+notify-subscriber-user-name notify-user-data"}.
+@end deftypevr
-@example
-(use-modules (gnu) (guix))
+@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
+Access control by IPP operation.
-(operating-system
- (host-name "mymachine")
- ;; ...
- (hosts-file
- ;; Create a /etc/hosts file with aliases for "localhost"
- ;; and "mymachine", as well as for Facebook servers.
- (plain-file "hosts"
- (string-append (local-host-aliases host-name)
- %facebook-host-aliases))))
-@end example
+Defaults to @samp{()}.
+@end deftypevr
+@end deftypevr
-This mechanism can prevent programs running locally, such as Web
-browsers, from accessing Facebook.
-@end defvr
+@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
+Specifies whether job files (documents) are preserved after a job is
+printed. If a numeric value is specified, job files are preserved for
+the indicated number of seconds after printing. Otherwise a boolean
+value applies indefinitely.
-The @code{(gnu services avahi)} provides the following definition.
+Defaults to @samp{86400}.
+@end deftypevr
-@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
- [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
- [#:ipv6? #t] [#:wide-area? #f] @
- [#:domains-to-browse '()] [#:debug? #f]
-Return a service that runs @command{avahi-daemon}, a system-wide
-mDNS/DNS-SD responder that allows for service discovery and
-"zero-configuration" host name lookups (see @uref{http://avahi.org/}), and
-extends the name service cache daemon (nscd) so that it can resolve
-@code{.local} host names using
-@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. Additionally,
-add the @var{avahi} package to the system profile so that commands such as
-@command{avahi-browse} are directly usable.
+@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
+Specifies whether the job history is preserved after a job is printed.
+If a numeric value is specified, the job history is preserved for the
+indicated number of seconds after printing. If @code{#t}, the job
+history is preserved until the MaxJobs limit is reached.
-If @var{host-name} is different from @code{#f}, use that as the host name to
-publish for this machine; otherwise, use the machine's actual host name.
+Defaults to @samp{#t}.
+@end deftypevr
-When @var{publish?} is true, publishing of host names and services is allowed;
-in particular, avahi-daemon will publish the machine's host name and IP
-address via mDNS on the local network.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
+Specifies the amount of time to wait for job completion before
+restarting the scheduler.
-When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
+Defaults to @samp{30}.
+@end deftypevr
-Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
-sockets.
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} string rip-cache
+Specifies the maximum amount of memory to use when converting documents
+into bitmaps for a printer.
+Defaults to @samp{"128m"}.
+@end deftypevr
-@node X Window
-@subsubsection X Window
+@deftypevr {@code{cups-configuration} parameter} string server-admin
+Specifies the email address of the server administrator.
-Support for the X Window graphical display system---specifically
-Xorg---is provided by the @code{(gnu services xorg)} module. Note that
-there is no @code{xorg-service} procedure. Instead, the X server is
-started by the @dfn{login manager}, currently SLiM.
+Defaults to @samp{"root@@localhost.localdomain"}.
+@end deftypevr
-@deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @
- [#:auto-login? #f] [#:default-user ""] [#:startx] @
- [#:theme @var{%default-slim-theme}] @
- [#:theme-name @var{%default-slim-theme-name}]
-Return a service that spawns the SLiM graphical login manager, which in
-turn starts the X display server with @var{startx}, a command as returned by
-@code{xorg-start-command}.
+@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
+The ServerAlias directive is used for HTTP Host header validation when
+clients connect to the scheduler from external interfaces. Using the
+special name @code{*} can expose your system to known browser-based DNS
+rebinding attacks, even when accessing sites through a firewall. If the
+auto-discovery of alternate names does not work, we recommend listing
+each alternate name with a ServerAlias directive instead of using
+@code{*}.
-@cindex X session
+Defaults to @samp{*}.
+@end deftypevr
-SLiM automatically looks for session types described by the @file{.desktop}
-files in @file{/run/current-system/profile/share/xsessions} and allows users
-to choose a session from the log-in screen using @kbd{F1}. Packages such as
-@var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
-adding them to the system-wide set of packages automatically makes them
-available at the log-in screen.
+@deftypevr {@code{cups-configuration} parameter} string server-name
+Specifies the fully-qualified host name of the server.
-In addition, @file{~/.xsession} files are honored. When available,
-@file{~/.xsession} must be an executable that starts a window manager
-and/or other X clients.
+Defaults to @samp{"localhost"}.
+@end deftypevr
-When @var{allow-empty-passwords?} is true, allow logins with an empty
-password. When @var{auto-login?} is true, log in automatically as
-@var{default-user}.
+@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
+Specifies what information is included in the Server header of HTTP
+responses. @code{None} disables the Server header. @code{ProductOnly}
+reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
+reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
+@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
+the output of the @code{uname} command. @code{Full} reports @code{CUPS
+2.0.0 (@var{uname}) IPP/2.0}.
-If @var{theme} is @code{#f}, use the default log-in theme; otherwise
-@var{theme} must be a gexp denoting the name of a directory containing the
-theme to use. In that case, @var{theme-name} specifies the name of the
-theme.
-@end deffn
+Defaults to @samp{Minimal}.
+@end deftypevr
-@defvr {Scheme Variable} %default-theme
-@defvrx {Scheme Variable} %default-theme-name
-The G-Expression denoting the default SLiM theme and its name.
-@end defvr
+@deftypevr {@code{cups-configuration} parameter} string set-env
+Set the specified environment variable to be passed to child processes.
-@deffn {Scheme Procedure} xorg-start-command [#:guile] @
- [#:configuration-file #f] [#:xorg-server @var{xorg-server}]
-Return a derivation that builds a @var{guile} script to start the X server
-from @var{xorg-server}. @var{configuration-file} is the server configuration
-file or a derivation that builds it; when omitted, the result of
-@code{xorg-configuration-file} is used.
+Defaults to @samp{"variable value"}.
+@end deftypevr
-Usually the X server is started by a login manager.
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
+Listens on the specified interfaces for encrypted connections. Valid
+values are of the form @var{address}:@var{port}, where @var{address} is
+either an IPv6 address enclosed in brackets, an IPv4 address, or
+@code{*} to indicate all addresses.
-@deffn {Scheme Procedure} xorg-configuration-file @
- [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
-Return a configuration file for the Xorg server containing search paths for
-all the common drivers.
+Defaults to @samp{()}.
+@end deftypevr
-@var{drivers} must be either the empty list, in which case Xorg chooses a
-graphics driver automatically, or a list of driver names that will be tried in
-this order---e.g., @code{(\"modesetting\" \"vesa\")}.
+@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
+Sets encryption options. By default, CUPS only supports encryption
+using TLS v1.0 or higher using known secure cipher suites. The
+@code{AllowRC4} option enables the 128-bit RC4 cipher suites, which are
+required for some older clients that do not implement newer ones. The
+@code{AllowSSL3} option enables SSL v3.0, which is required for some
+older clients that do not support TLS v1.0.
-Likewise, when @var{resolutions} is the empty list, Xorg chooses an
-appropriate screen resolution; otherwise, it must be a list of
-resolutions---e.g., @code{((1024 768) (640 480))}.
+Defaults to @samp{()}.
+@end deftypevr
-Last, @var{extra-config} is a list of strings or objects appended to the
-@code{text-file*} argument list. It is used to pass extra text to be added
-verbatim to the configuration file.
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
+Specifies whether the scheduler requires clients to strictly adhere to
+the IPP specifications.
-@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{name}]
-Add @var{package}, a package for a screen-locker or screen-saver whose
-command is @var{program}, to the set of setuid programs and add a PAM entry
-for it. For example:
+Defaults to @samp{#f}.
+@end deftypevr
-@lisp
-(screen-locker-service xlockmore "xlock")
-@end lisp
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
+Specifies the HTTP request timeout, in seconds.
-makes the good ol' XlockMore usable.
-@end deffn
+Defaults to @samp{300}.
+
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} boolean web-interface?
+Specifies whether the web interface is enabled.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
+At this point you're probably thinking ``oh dear, Guix manual, I like
+you but you can stop already with the configuration options''. Indeed.
+However, one more point: it could be that you have an existing
+@code{cupsd.conf} that you want to use. In that case, you can pass an
+@code{opaque-cups-configuration} as the configuration of a
+@code{cups-service-type}.
+
+Available @code{opaque-cups-configuration} fields are:
+
+@deftypevr {@code{opaque-cups-configuration} parameter} package cups
+The CUPS package.
+@end deftypevr
+
+@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
+The contents of the @code{cupsd.conf}, as a string.
+@end deftypevr
+
+@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
+The contents of the @code{cups-files.conf} file, as a string.
+@end deftypevr
+
+For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
+strings of the same name, you could instantiate a CUPS service like
+this:
+
+@example
+(service cups-service-type
+ (opaque-cups-configuration
+ (cupsd.conf cupsd.conf)
+ (cups-files.conf cups-files.conf)))
+@end example
@node Desktop Services
@deffn {Scheme Procedure} xfce-desktop-service
Return a service that adds the @code{xfce} package to the system profile,
-and extends polkit with the abilit for @code{thunar} to manipulate the
+and extends polkit with the ability for @code{thunar} to manipulate the
file system as root from within a user session, after the user has
authenticated with the administrator's password.
@end deffn
Package object of the MySQL database server, can be either @var{mariadb}
or @var{mysql}.
-For MySQL, a temorary root password will be displayed at activation time.
+For MySQL, a temporary root password will be displayed at activation time.
For MariaDB, the root password is empty.
@end table
@end deftp
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
-Allow full filesystem access to clients. There's no access checks
+Allow full file system access to clients. There's no access checks
other than what the operating system does for the active UID/GID. It
works with both maildir and mboxes, allowing you to prefix mailboxes
names with e.g. /path/ or ~user/.
@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
Don't use mmap() at all. This is required if you store indexes to
-shared filesystems (NFS or clustered filesystem).
+shared file systems (NFS or clustered file system).
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
When creating new mdbox files, immediately preallocate their size to
@samp{mdbox-rotate-size}. This setting currently works only in Linux
-with some filesystems (ext4, xfs).
+with some file systems (ext4, xfs).
Defaults to @samp{#f}.
@end deftypevr
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
-Filesystem backend to use for saving attachments:
+File system backend to use for saving attachments:
@table @code
@item posix
No SiS done by Dovecot (but this might help FS's own deduplication)
@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
Address to use when sending rejection mails.
-Default is postmaster@@<your domain>. %d expands to recipient domain.
-Defaults to @samp{""}.
+%d expands to recipient domain.
+Defaults to @samp{"postmaster@@%d"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string hostname
However, it could be that you just want to get a @code{dovecot.conf} up
and running. In that case, you can pass an
-@code{opaque-dovecot-configuration} as the @code{#:config} paramter to
+@code{opaque-dovecot-configuration} as the @code{#:config} parameter to
@code{dovecot-service}. As its name indicates, an opaque configuration
does not have easy reflective capabilities.
@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]
Return a service that runs @var{nginx}, the nginx web server.
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
+this to work, use the default value for @var{config-file}.
+
@end deffn
-@node Various Services
-@subsubsection Various Services
+@deftp {Data Type} nginx-vhost-configuration
+Data type representing the configuration of an nginx virtual host.
+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}.
+
+@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}.
+
+Note that nginx can listen for HTTP and HTTPS connections in the same
+@dfn{virtual host}.
+
+@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.
+
+@item @code{root} (default: @code{"/srv/http"})
+Root of the website nginx will serve.
+
+@item @code{index} (default: @code{(list "index.html")})
+Index files to look for when clients ask for a directory. If it cannot be found,
+Nginx will send the list of files in the directory.
+
+@item @code{ssl-certificate} (default: @code{"/etc/nginx/cert.pem"})
+Where to find the certificate for secure connections. Set it to @code{#f} if
+you don't have a certificate or you don't want to use HTTPS.
+
+@item @code{ssl-certificate-key} (default: @code{"/etc/nginx/key.pem"})
+Where to find the private key for secure connections. Set it to @code{#f} if
+you don't have a key or you don't want to use HTTPS.
+
+@item @code{server-tokens?} (default: @code{#f})
+Whether the server should add its configuration to response.
+
+@end table
+@end deftp
+
+@node Network File System
+@subsubsection Network File System
+@cindex NFS
+
+The @code{(gnu services nfs)} module provides the following services,
+which are most commonly used in relation to mounting or exporting
+directory trees as @dfn{network file systems} (NFS).
+
+@subsubheading RPC Bind Service
+@cindex rpcbind
+
+The RPC Bind service provides a facility to map program numbers into
+universal addresses.
+Many NFS related services use this facility. Hence it is automatically
+started when a dependent service starts.
+
+@defvr {Scheme Variable} rpcbind-service-type
+A service type for the RPC portmapper daemon.
+@end defvr
+
+
+@deftp {Data Type} rpcbind-configuration
+Data type representing the configuration of the RPC Bind Service.
+This type has the following parameters:
+@table @asis
+@item @code{rpcbind} (default: @code{rpcbind})
+The rpcbind package to use.
+
+@item @code{warm-start?} (default: @code{#t})
+If this parameter is @code{#t}, then the daemon will read a
+state file on startup thus reloading state information saved by a previous
+instance.
+@end table
+@end deftp
+
+
+@subsubheading Pipefs Pseudo File System
+@cindex pipefs
+@cindex rpc_pipefs
+
+The pipefs file system is used to transfer NFS related data
+between the kernel and user space programs.
+
+@defvr {Scheme Variable} pipefs-service-type
+A service type for the pipefs pseudo file system.
+@end defvr
+
+@deftp {Data Type} pipefs-configuration
+Data type representing the configuration of the pipefs pseudo file system service.
+This type has the following parameters:
+@table @asis
+@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory to which the file system is to be attached.
+@end table
+@end deftp
+
+
+@subsubheading GSS Daemon Service
+@cindex GSSD
+@cindex GSS
+@cindex global security system
+
+The @dfn{global security system} (GSS) daemon provides strong security for RPC
+based protocols.
+Before exchanging RPC requests an RPC client must establish a security
+context. Typically this is done using the Kerberos command @command{kinit}
+or automatically at login time using PAM services.
+
+@defvr {Scheme Variable} gss-service-type
+A service type for the Global Security System (GSS) daemon.
+@end defvr
+
+@deftp {Data Type} gss-configuration
+Data type representing the configuration of the GSS daemon service.
+This type has the following parameters:
+@table @asis
+@item @code{nfs-utils} (default: @code{nfs-utils})
+The package in which the @command{rpc.gssd} command is to be found.
+
+@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory where the pipefs file system is mounted.
+
+@end table
+@end deftp
+
+
+@subsubheading IDMAP Daemon Service
+@cindex idmapd
+@cindex name mapper
+
+The idmap daemon service provides mapping between user IDs and user names.
+Typically it is required in order to access file systems mounted via NFSv4.
+
+@defvr {Scheme Variable} idmap-service-type
+A service type for the Identity Mapper (IDMAP) daemon.
+@end defvr
+
+@deftp {Data Type} idmap-configuration
+Data type representing the configuration of the IDMAP daemon service.
+This type has the following parameters:
+@table @asis
+@item @code{nfs-utils} (default: @code{nfs-utils})
+The package in which the @command{rpc.idmapd} command is to be found.
+
+@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory where the pipefs file system is mounted.
+
+@item @code{domain} (default: @code{#f})
+The local NFSv4 domain name.
+This must be a string or @code{#f}.
+If it is @code{#f} then the daemon will use the host's fully qualified domain name.
+
+@end table
+@end deftp
+
+
+@node Miscellaneous Services
+@subsubsection Miscellaneous Services
+
+
+@cindex lirc
+@subsubheading Lirc Service
The @code{(gnu services lirc)} module provides the following service.
passed to @command{lircd}.
@end deffn
+@cindex spice
+@subsubheading Spice Service
+
+The @code{(gnu services spice)} module provides the following service.
+
+@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
+Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon
+that enables sharing the clipboard with a vm and setting the guest display
+resolution when the graphical console window resizes.
+@end deffn
+
@subsubsection Dictionary Services
The @code{(gnu services dict)} module provides the following service:
@end deftp
+@cindex dual boot
+@cindex boot menu
Should you want to list additional boot menu entries @i{via} the
@code{menu-entries} field above, you will need to create them with the
-@code{menu-entry} form:
+@code{menu-entry} form. For example, imagine you want to be able to
+boot another distro (hard to imagine!), you can define a menu entry
+along these lines:
+
+@example
+(menu-entry
+ (label "The Other Distro")
+ (linux "/boot/old/vmlinux-2.6.32")
+ (linux-arguments '("root=/dev/sda2"))
+ (initrd "/boot/old/initrd"))
+@end example
+
+Details below.
@deftp {Data Type} menu-entry
The type of an entry in the GRUB boot menu.
The label to show in the menu---e.g., @code{"GNU"}.
@item @code{linux}
-The Linux kernel to boot.
+The Linux kernel image to boot, for example:
+
+@example
+(file-append linux-libre "/bzImage")
+@end example
@item @code{linux-arguments} (default: @code{()})
The list of extra Linux kernel command-line arguments---e.g.,
@item -m 256
RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
-which may be insufficent for some operations.
+which may be insufficient for some operations.
@item /tmp/qemu-image
The file name of the qcow2 image.
The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as
@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It
-evalutes to a list of services. Of course, you could always use
+evaluates to a list of services. Of course, you could always use
standard list combinators such as @code{map} and @code{fold} to do that
(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
@code{modify-services} simply provides a more concise form for this
The @var{body} should evaluate to the new service parameters, which will
be used to configure the new service. This new service will replace the
original in the resulting list. Because a service's service parameters
-are created using @code{define-record-type*}, you can write a succint
+are created using @code{define-record-type*}, you can write a succinct
@var{body} that evaluates to the new service parameters by using the
@code{inherit} feature that @code{define-record-type*} provides.
Return true if @var{obj} is a service extension.
@end deffn
+Occasionally, you might want to simply extend an existing service. This
+involves creating a new service type and specifying the extension of
+interest, which can be verbose; the @code{simple-service} procedure
+provides a shorthand for this.
+
+@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
+Return a service that extends @var{target} with @var{value}. This works
+by creating a singleton service type @var{name}, of which the returned
+service is an instance.
+
+For example, this extends mcron (@pxref{Scheduled Job Execution}) with
+an additional job:
+
+@example
+(simple-service 'my-mcron-job mcron-service-type
+ #~(job '(next-hour (3)) "guix gc -F 2G"))
+@end example
+@end deffn
+
At the core of the service abstraction lies the @code{fold-services}
procedure, which is responsible for ``compiling'' a list of services
down to a single directory that contains everything needed to boot and
recursive: when an indirect dependency requires grafting, then grafting
``propagates'' up to the package that the user is installing.
-Currently, the graft and the package it replaces (@var{bash-fixed} and
-@var{bash} in the example above) must have the exact same @code{name}
-and @code{version} fields. This restriction mostly comes from the fact
-that grafting works by patching files, including binary files, directly.
+Currently, the length of the name and version of the graft and that of
+the package it replaces (@var{bash-fixed} and @var{bash} in the example
+above) must be equal. This restriction mostly comes from the fact that
+grafting works by patching files, including binary files, directly.
Other restrictions may apply: for instance, when adding a graft to a
package providing a shared library, the original shared library and its
replacement must have the same @code{SONAME} and be binary-compatible.
@example
(define my-package
- (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7"))
+ (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
+ (revision "1")) ;Guix package revision
(package
- (version (string-append "0.9-1."
+ (version (string-append "0.9-" revision "."
(string-take commit 7)))
(source (origin
(method git-fetch)
described above.
+@subsubsection Specifying Dependencies
+@cindex inputs, for Python packages
+
+Dependency information for Python packages is usually available in the
+package source tree, with varying degrees of accuracy: in the
+@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
+
+Your mission, when writing a recipe for a Python package, is to map
+these dependencies to the appropriate type of ``input'' (@pxref{package
+Reference, inputs}). Although the @code{pypi} importer normally does a
+good job (@pxref{Invoking guix import}), you may want to check the
+following check list to determine which dependency goes where.
+
+@itemize
+
+@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
+@file{requirements.txt} file.
+
+@item
+Python packages required only at build time---e.g., those listed with
+the @code{setup_requires} keyword in @file{setup.py}---or only for
+testing---e.g., those in @code{tests_require}---go into
+@code{native-inputs}. The rationale is that (1) they do not need to be
+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
+frameworks. Of course if any of these packages is also required at
+run-time, it needs to go to @code{propagated-inputs}.
+
+@item
+Anything that does not fall in the previous categories goes to
+@code{inputs}, for example programs or C libraries required for building
+Python packages containing C extensions.
+
+@item
+If a Python package has optional dependencies (@code{extras_require}),
+it is up to you to decide whether to add them or not, based on their
+usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
+size}}).
+
+@end itemize
+
+
@node Perl Modules
@subsection Perl Modules
HCoop / jackhill / guix / guix.git / blobdiff