Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
-Copyright @copyright{} 2016, 2017 Chris Marusich@*
+Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 Nils Gillmann@*
Copyright @copyright{} 2017 nee@*
Copyright @copyright{} 2018 Rutger Helling@*
Copyright @copyright{} 2018 Oleg Pykhalov@*
-Copyright @copyright{} 2018 Mike Gerwitz
+Copyright @copyright{} 2018 Mike Gerwitz@*
+Copyright @copyright{} 2018 Pierre-Antoine Rouby
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
+* Sound Services:: ALSA and Pulseaudio services.
* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
reproducible.
@item
-Make @code{root}'s profile available under @file{~/.guix-profile}:
+Make @code{root}'s profile available under @file{~root/.guix-profile}:
@example
# ln -sf /var/guix/profiles/per-user/root/guix-profile \
environment variables:
@example
-# GUIX_PROFILE=$HOME/.guix-profile ; \
+# GUIX_PROFILE="`echo ~root`/.guix-profile" ; \
source $GUIX_PROFILE/etc/profile
@end example
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
+@cindex collisions, in a profile
+@cindex colliding packages in profiles
+@cindex profile collisions
+@item --allow-collisions
+Allow colliding packages in the new profile. Use at your own risk!
+
+By default, @command{guix package} reports as an error @dfn{collisions}
+in the profile. Collisions happen when two or more different versions
+or variants of a given package end up in the profile.
+
@item --verbose
Produce verbose output. In particular, emit the build log of the
environment on the standard error port.
of an element. @xref{Invoking guix graph}, for a tool to visualize
the graph of references.
+@item --derivers
+@cindex derivation
+Return the derivation(s) leading to the given store items
+(@pxref{Derivations}).
+
+For example, this command:
+
+@example
+guix gc --derivers `guix package -I ^emacs$ | cut -f4`
+@end example
+
+@noindent
+returns the @file{.drv} file(s) leading to the @code{emacs} package
+installed in your profile.
+
+Note that there may be zero matching @file{.drv} files, for instance
+because these files have been garbage-collected. There can also be more
+than one matching @file{.drv} due to fixed-output derivations.
@end table
Lastly, the following options allow you to check the integrity of the
effect is limited to the user who run @command{guix pull}. For
instance, when user @code{root} runs @command{guix pull}, this has no
effect on the version of Guix that user @code{alice} sees, and vice
-versa@footnote{Under the hood, @command{guix pull} updates the
-@file{~/.config/guix/latest} symbolic link to point to the latest Guix,
-and the @command{guix} command loads code from there. Currently, the
-only way to roll back an invocation of @command{guix pull} is to
-manually update this symlink to point to the previous Guix.}.
+versa.
+
+The result of running @command{guix pull} is a @dfn{profile} available
+under @file{~/.config/guix/current} containing the latest Guix. Thus,
+make sure to add it to the beginning of your search path so that you use
+the latest version, and similarly for the Info manual
+(@pxref{Documentation}):
+
+@example
+export PATH="$HOME/.config/guix/current/bin:$PATH"
+export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
+@end example
+
+This @code{~/.config/guix/current} profile works like any other profile
+created by @command{guix package} (@pxref{Invoking guix package}). That
+is, you can list generations, roll back to the previous
+generation---i.e., the previous Guix---and so on:
+
+@example
+$ guix package -p ~/.config/guix/current -l
+Generation 1 May 25 2018 10:06:41
+ guix 221951a out /gnu/store/i4dfk7vw5k112s49jrhl6hwsfnh6wr7l-guix-221951af4
+
+Generation 2 May 27 2018 19:07:47
+ + guix 2fbae00 out /gnu/store/44cv9hyvxg34xf5kblf5dz57hc52y4bm-guix-2fbae006f
+ - guix 221951a out /gnu/store/i4dfk7vw5k112s49jrhl6hwsfnh6wr7l-guix-221951af4
+
+Generation 3 May 30 2018 16:11:39 (current)
+ + guix a076f19 out /gnu/store/332czkicwwg6lc3x4aqbw5q2mq12s7fj-guix-a076f1990
+ - guix 2fbae00 out /gnu/store/44cv9hyvxg34xf5kblf5dz57hc52y4bm-guix-2fbae006f
+$ guix package -p ~/.config/guix/current --roll-back
+switched from generation 3 to 2
+@end example
The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:
@noindent
That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
+@cindex relocatable binaries, with @command{guix pack}
+What if the recipient of your pack does not have root privileges on
+their machine, and thus cannot unpack it in the root file system? In
+that case, you will want to use the @code{--relocatable} option (see
+below). This option produces @dfn{relocatable binaries}, meaning they
+they can be placed anywhere in the file system hierarchy: in the example
+above, users can unpack your tarball in their home directory and
+directly run @file{./opt/gnu/bin/guile}.
+
+@cindex Docker, build an image with guix pack
Alternatively, you can produce a pack in the Docker image format using
the following command:
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
documentation} for more information.
+@cindex Singularity, build an image with guix pack
+@cindex SquashFS, build an image with guix pack
+Yet another option is to produce a SquashFS image with the following
+command:
+
+@example
+guix pack -f squashfs guile emacs geiser
+@end example
+
+@noindent
+The result is a SquashFS file system image that can either be mounted or
+directly be used as a file system container image with the
+@uref{http://singularity.lbl.gov, Singularity container execution
+environment}, using commands like @command{singularity shell} or
+@command{singularity exec}.
+
Several command-line options allow you to customize your pack:
@table @code
This produces a tarball that follows the
@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
Docker Image Specification}.
+
+@item squashfs
+This produces a SquashFS image containing all the specified binaries and
+symlinks, as well as empty mount points for virtual file systems like
+procfs.
@end table
+@item --relocatable
+@itemx -R
+Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
+anywhere in the file system hierarchy and run from there. For example,
+if you create a pack containing Bash with:
+
+@example
+guix pack -R -S /mybin=bin bash
+@end example
+
+@noindent
+... you can copy that pack to a machine that lacks Guix, and from your
+home directory as a normal user, run:
+
+@example
+tar xf pack.tar.gz
+./mybin/sh
+@end example
+
+@noindent
+In that shell, if you type @code{ls /gnu/store}, you'll notice that
+@file{/gnu/store} shows up and contains all the dependencies of
+@code{bash}, even though the machine actually lacks @file{/gnu/store}
+altogether! That is probably the simplest way to deploy Guix-built
+software on a non-Guix machine.
+
+There's a gotcha though: this technique relies on the @dfn{user
+namespace} feature of the kernel Linux, which allows unprivileged users
+to mount or change root. Old versions of Linux did not support it, and
+some GNU/Linux distributions turn it off; on these systems, programs
+from the pack @emph{will fail to run}, unless they are unpacked in the
+root file system.
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.
One use case for this is the Guix self-contained binary tarball
(@pxref{Binary Installation}).
+
+@item --bootstrap
+Use the bootstrap binaries to build the pack. This option is only
+useful to Guix developers.
@end table
In addition, @command{guix pack} supports all the common build options
@end defvr
+@defvr {Scheme Variable} android-ndk-build-system
+@cindex Android distribution
+@cindex Android NDK build system
+This variable is exported by @code{(guix build-system android-ndk)}. It
+implements a build procedure for Android NDK (native development kit)
+packages using a Guix-specific build process.
+
+The build system assumes that packages install their public interface
+(header) files to the subdirectory "include" of the "out" output and
+their libraries to the subdirectory "lib" of the "out" output.
+
+It's also assumed that the union of all the dependencies of a package
+has no conflicting files.
+
+For the time being, cross-compilation is not supported - so right now
+the libraries and header files are assumed to be host tools.
+
+@end defvr
+
@defvr {Scheme Variable} asdf-build-system/source
@defvrx {Scheme Variable} asdf-build-system/sbcl
@defvrx {Scheme Variable} asdf-build-system/ecl
@dots{})))
@end example
+@cindex extensions, for gexps
+@findex with-extensions
+In the same vein, sometimes you want to import not just pure-Scheme
+modules, but also ``extensions'' such as Guile bindings to C libraries
+or other ``full-blown'' packages. Say you need the @code{guile-json}
+package available on the build side, here's how you would do it:
+
+@example
+(use-modules (gnu packages guile)) ;for 'guile-json'
+
+(with-extensions (list guile-json)
+ (gexp->derivation "something-with-json"
+ #~(begin
+ (use-modules (json))
+ @dots{})))
+@end example
+
The syntactic form to construct gexps is summarized below.
@deffn {Scheme Syntax} #~@var{exp}
procedures called from @var{body}@dots{}.
@end deffn
+@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
+Mark the gexps defined in @var{body}@dots{} as requiring
+@var{extensions} in their build and execution environment.
+@var{extensions} is typically a list of package objects such as those
+defined in the @code{(gnu packages guile)} module.
+
+Concretely, the packages listed in @var{extensions} are added to the
+load path while compiling imported modules in @var{body}@dots{}; they
+are also added to the load path of the gexp returned by
+@var{body}@dots{}.
+@end deffn
+
@deffn {Scheme Procedure} gexp? @var{obj}
Return @code{#t} if @var{obj} is a G-expression.
@end deffn
[#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
[#:module-path @var{%load-path}] @
+ [#:effective-version "2.2"] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:disallowed-references #f] @
[#:leaked-env-vars #f] @
the load path during the execution of @var{exp}---e.g., @code{((guix
build utils) (guix build gnu-build-system))}.
+@var{effective-version} determines the string to use when adding extensions of
+@var{exp} (see @code{with-extensions}) to the search path---e.g., @code{"2.2"}.
+
@var{graft?} determines whether packages referred to by @var{exp} should be grafted when
applicable.
This is the declarative counterpart of @code{gexp->derivation}.
@end deffn
-@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
+@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
+ [#:guile (default-guile)] [#:module-path %load-path]
Return an executable script @var{name} that runs @var{exp} using
@var{guile}, with @var{exp}'s imported modules in its search path.
+Look up @var{exp}'s modules in @var{module-path}.
The example below builds a script that simply invokes the @command{ls}
command:
@end deffn
@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
- [#:guile #f]
+ [#:guile #f] [#:module-path %load-path]
Return an object representing the executable store item @var{name} that
runs @var{gexp}. @var{guile} is the Guile package used to execute that
-script.
+script. Imported modules of @var{gexp} are looked up in @var{module-path}.
This is the declarative counterpart of @code{gexp->script}.
@end deffn
@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
- [#:set-load-path? #t]
+ [#:set-load-path? #t] [#:module-path %load-path] @
+ [#:splice? #f] @
+ [#:guile (default-guile)]
Return a derivation that builds a file @var{name} containing @var{exp}.
+When @var{splice?} is true, @var{exp} is considered to be a list of
+expressions that will be spliced in the resulting file.
+
When @var{set-load-path?} is true, emit code in the resulting file to
set @code{%load-path} and @code{%load-compiled-path} to honor
-@var{exp}'s imported modules.
+@var{exp}'s imported modules. Look up @var{exp}'s modules in
+@var{module-path}.
The resulting file holds references to all the dependencies of @var{exp}
or a subset thereof.
@end deffn
-@deffn {Scheme Procedure} scheme-file @var{name} @var{exp}
+@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f]
Return an object representing the Scheme file @var{name} that contains
@var{exp}.
An example use of this is on Linux-based systems, which can emulate
different personalities. For instance, passing
-@code{--system=i686-linux} on an @code{x86_64-linux} system allows you
+@code{--system=i686-linux} on an @code{x86_64-linux} system or
+@code{--system=armhf-linux} on an @code{aarch64-linux} system allows you
to build packages in a complete 32-bit environment.
+@quotation Note
+Building for an @code{armhf-linux} system is unconditionally enabled on
+@code{aarch64-linux} machines, although certain aarch64 chipsets do not
+allow for this functionality, notably the ThunderX.
+@end quotation
+
Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
is enabled (@pxref{Virtualization Services,
@code{qemu-binfmt-service-type}}), you can build for any system for
@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
identifier.
@end itemize
+
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
@end table
@item crate
Package developers can specify in package recipes the
@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
-name and version of the package when they differ from the name that Guix
-uses, as in this example:
+name and version of the package when they differ from the name or version
+that Guix uses, as in this example:
@example
(package
(name "grub")
;; @dots{}
;; CPE calls this package "grub2".
- (properties '((cpe-name . "grub2"))))
+ (properties '((cpe-name . "grub2")
+ (cpe-version . "2.3")))
+@end example
+
+@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
+Some entries in the CVE database do not specify which version of a
+package they apply to, and would thus ``stick around'' forever. Package
+developers who found CVE alerts and verified they can be ignored can
+declare them as in this example:
+
+@example
+(package
+ (name "t1lib")
+ ;; @dots{}
+ ;; These CVEs no longer apply and can be safely ignored.
+ (properties `((lint-hidden-cve . ("CVE-2011-0433"
+ "CVE-2011-1553"
+ "CVE-2011-1554"
+ "CVE-2011-5244")))))
@end example
@item formatting
with Multiple Outputs}). Such are the typical issues that
@command{guix size} can highlight.
-The command can be passed a package specification such as @code{gcc@@4.8}
+The command can be passed one or more package specifications
+such as @code{gcc@@4.8}
or @code{guile:debug}, or a file name in the store. Consider this
example:
@example
$ guix size coreutils
store item total self
-/gnu/store/@dots{}-coreutils-8.23 70.0 13.9 19.8%
-/gnu/store/@dots{}-gmp-6.0.0a 55.3 2.5 3.6%
-/gnu/store/@dots{}-acl-2.2.52 53.7 0.5 0.7%
-/gnu/store/@dots{}-attr-2.4.46 53.2 0.3 0.5%
-/gnu/store/@dots{}-gcc-4.8.4-lib 52.9 15.7 22.4%
-/gnu/store/@dots{}-glibc-2.21 37.2 37.2 53.1%
+/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
+/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
+/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
+/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
+/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
+/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
+/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
+/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
+total: 78.9 MiB
@end example
@cindex closure
itself to the space occupied by all the items listed here.
In this example, we see that the closure of Coreutils weighs in at
-70@tie{}MiB, half of which is taken by libc. (That libc represents a
-large fraction of the closure is not a problem @i{per se} because it is
-always available on the system anyway.)
-
-When the package passed to @command{guix size} is available in the
-store, @command{guix size} queries the daemon to determine its
+79@tie{}MiB, most of which is taken by libc and GCC's run-time support
+libraries. (That libc and GCC's libraries represent a large fraction of
+the closure is not a problem @i{per se} because they are always available
+on the system anyway.)
+
+When the package(s) passed to @command{guix size} are available in the
+store@footnote{More precisely, @command{guix size} looks for the
+@emph{ungrafted} variant of the given package(s), as returned by
+@code{guix build @var{package} --no-grafts}. @xref{Security Updates},
+for information on grafts.}, @command{guix size} queries the daemon to determine its
dependencies, and measures its size in the store, similar to @command{du
-ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
Coreutils}).
-When the given package is @emph{not} in the store, @command{guix size}
+When the given packages are @emph{not} in the store, @command{guix size}
reports information based on the available substitutes
(@pxref{Substitutes}). This makes it possible it to profile disk usage of
store items that are not even on disk, only available remotely.
@example
guix graph -t derivation `guix system build -d my-config.scm`
@end example
+
+@item module
+This is the graph of @dfn{package modules} (@pxref{Package Modules}).
+For example, the following command shows the graph for the package
+module that defines the @code{guile} package:
+
+@example
+guix graph -t module guile | dot -Tpdf > module-graph.pdf
+@end example
@end table
All the types above correspond to @emph{build-time dependencies}. The
19,824.2 MiB on disk (uncompressed)
0.030 seconds per request (182.9 seconds in total)
33.5 requests per second
+
+ 9.8% (342 out of 3,470) of the missing items are queued
+ 867 queued builds
+ x86_64-linux: 518 (59.7%)
+ i686-linux: 221 (25.5%)
+ aarch64-linux: 128 (14.8%)
+ build rate: 23.41 builds per hour
+ x86_64-linux: 11.16 builds per hour
+ i686-linux: 6.03 builds per hour
+ aarch64-linux: 6.41 builds per hour
@end example
+@cindex continuous integration, statistics
As you can see, it reports the fraction of all the packages for which
substitutes are available on the server---regardless of whether
substitutes are enabled, and regardless of whether this server's signing
key is authorized. It also reports the size of the compressed archives
(``nars'') provided by the server, the size the corresponding store
items occupy in the store (assuming deduplication is turned off), and
-the server's throughput.
+the server's throughput. The second part gives continuous integration
+(CI) statistics, if the server supports it.
To achieve that, @command{guix weather} queries over HTTP(S) meta-data
(@dfn{narinfos}) for all the relevant store items. Like @command{guix
To configure wireless networking, you can create a configuration file
for the @command{wpa_supplicant} configuration tool (its location is not
important) using one of the available text editors such as
-@command{zile}:
+@command{nano}:
@example
-zile wpa_supplicant.conf
+nano wpa_supplicant.conf
@end example
As an example, the following stanza can go to this file and will work
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 three text editors: GNU nano
-(@pxref{Top,,, nano, GNU nano Manual}), GNU Zile (an Emacs clone), and
+that end, the installation system comes with three text editors. We
+recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
+supports syntax highlighting and parentheses matching; other editors
+include GNU Zile (an Emacs clone), and
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
@example
# mkdir /mnt/etc
# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
-# zile /mnt/etc/config.scm
+# nano /mnt/etc/config.scm
@end example
You should pay attention to what your configuration file contains, and
This designates the place where the file system is to be mounted.
@item @code{device}
-This names the ``source'' of the file system. By default it is the name
-of a node under @file{/dev}, but its meaning depends on the @code{title}
-field described below.
+This names the ``source'' of the file system. It can be one of three
+things: a file system label, a file system UUID, or the name of a
+@file{/dev} node. Labels and UUIDs offer a way to refer to file
+systems without having to hard-code their actual device
+name@footnote{Note that, while it is tempting to use
+@file{/dev/disk/by-uuid} and similar device names to achieve the same
+result, this is not recommended: These special device nodes are created
+by the udev daemon and may be unavailable at the time the device is
+mounted.}.
-@item @code{title} (default: @code{'device})
-This is a symbol that specifies how the @code{device} field is to be
-interpreted.
+@findex file-system-label
+File system labels are created using the @code{file-system-label}
+procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
+plain strings. Here's an example of a file system referred to by its
+label, as shown by the @command{e2label} command:
-When it is the symbol @code{device}, then the @code{device} field is
-interpreted as a file name; when it is @code{label}, then @code{device}
-is interpreted as a file system label name; when it is @code{uuid},
-@code{device} is interpreted as a file system unique identifier (UUID).
+@example
+(file-system
+ (mount-point "/home")
+ (type "ext4")
+ (device (file-system-label "my-home")))
+@end example
-UUIDs may be converted from their string representation (as shown by the
+@findex uuid
+UUIDs are converted from their string representation (as shown by the
@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
@code{uuid} form expects 16-byte UUIDs as defined in
@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
(file-system
(mount-point "/home")
(type "ext4")
- (title 'uuid)
(device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
@end example
-The @code{label} and @code{uuid} options offer a way to refer to file
-systems without having to hard-code their actual device
-name@footnote{Note that, while it is tempting to use
-@file{/dev/disk/by-uuid} and similar device names to achieve the same
-result, this is not recommended: These special device nodes are created
-by the udev daemon and may be unavailable at the time the device is
-mounted.}.
-
-However, when the source of a file system is a mapped device (@pxref{Mapped
+When the source of a file system is a mapped device (@pxref{Mapped
Devices}), its @code{device} field @emph{must} refer to the mapped
-device name---e.g., @file{/dev/mapper/root-partition}---and consequently
-@code{title} must be set to @code{'device}. This is required so that
+device name---e.g., @file{"/dev/mapper/root-partition"}.
+This is required so that
the system knows that mounting the file system depends on having the
corresponding device mapping established.
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
+* Sound Services:: ALSA and Pulseaudio services.
* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
@cindex mouse
@cindex gpm
-@deffn {Scheme Procedure} gpm-service [#:gpm @var{gpm}] @
- [#:options]
-Run @var{gpm}, the general-purpose mouse daemon, with the given
-command-line @var{options}. GPM allows users to use the mouse in the console,
-notably to select, copy, and paste text. The default value of @var{options}
-uses the @code{ps2} protocol, which works for both USB and PS/2 mice.
-
-This service is not part of @var{%base-services}.
-@end deffn
+@defvr {Scheme Variable} gpm-service-type
+This is the type of the service that runs GPM, the @dfn{general-purpose
+mouse daemon}, which provides mouse support to the Linux console. GPM
+allows users to use the mouse in the console, notably to select, copy,
+and paste text.
+
+The value for services of this type must be a @code{gpm-configuration}
+(see below). This service is not part of @var{%base-services}.
+@end defvr
+
+@deftp {Data Type} gpm-configuration
+Data type representing the configuration of GPM.
+
+@table @asis
+@item @code{options} (default: @code{%default-gpm-options})
+Command-line options passed to @command{gpm}. The default set of
+options instruct @command{gpm} to listen to mouse events on
+@file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, for
+more information.
+
+@item @code{gpm} (default: @code{gpm})
+The GPM package to use.
+
+@end table
+@end deftp
@anchor{guix-publish-service-type}
@deffn {Scheme Variable} guix-publish-service-type
@cindex session limits
@cindex ulimit
@cindex priority
+@cindex realtime
+@cindex jackd
@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
Return a service that installs a configuration file for the
Protocol (DHCP) client, on all the non-loopback network interfaces.
@end deffn
+@deffn {Scheme Procedure} dhcpd-service-type
+This type defines a service that runs a DHCP daemon. To create a
+service of this type, you must supply a @code{<dhcpd-configuration>}.
+For example:
+
+@example
+(service dhcpd-service-type
+ (dhcpd-configuration
+ (config-file (local-file "my-dhcpd.conf"))
+ (interfaces '("enp0s25"))))
+@end example
+@end deffn
+
+@deftp {Data Type} dhcpd-configuration
+@table @asis
+@item @code{package} (default: @code{isc-dhcp})
+The package that provides the DHCP daemon. This package is expected to
+provide the daemon at @file{sbin/dhcpd} relative to its output
+directory. The default package is the
+@uref{http://www.isc.org/products/DHCP, ISC's DHCP server}.
+@item @code{config-file} (default: @code{#f})
+The configuration file to use. This is required. It will be passed to
+@code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
+object (@pxref{G-Expressions, file-like objects}). See @code{man
+dhcpd.conf} for details on the configuration file syntax.
+@item @code{version} (default: @code{"4"})
+The DHCP version to use. The ISC DHCP server supports the values ``4'',
+``6'', and ``4o6''. These correspond to the @code{dhcpd} program
+options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
+details.
+@item @code{run-directory} (default: @code{"/run/dhcpd"})
+The run directory to use. At service activation time, this directory
+will be created if it does not exist.
+@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
+The PID file to use. This corresponds to the @code{-pf} option of
+@code{dhcpd}. See @code{man dhcpd} for details.
+@item @code{interfaces} (default: @code{'()})
+The names of the network interfaces on which dhcpd should listen for
+broadcasts. If this list is not empty, then its elements (which must be
+strings) will be appended to the @code{dhcpd} invocation when starting
+the daemon. It may not be necessary to explicitly specify any
+interfaces here; see @code{man dhcpd} for details.
+@end table
+@end deftp
+
@defvr {Scheme Variable} static-networking-service-type
This is the type for statically-configured network interfaces.
@c TODO Document <static-networking> data structures.
and @command{wicd-curses} user interfaces.
@end deffn
+@cindex ModemManager
+
+@defvr {Scheme Variable} modem-manager-service-type
+This is the service type for the
+@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
+service. The value for this service type is a
+@code{modem-manager-configuration} record.
+
+This service is part of @code{%desktop-services} (@pxref{Desktop
+Services}).
+@end defvr
+
+@deftp {Data Type} modem-manager-configuration
+Data type representing the configuration of ModemManager.
+
+@table @asis
+@item @code{modem-manager} (default: @code{modem-manager})
+The ModemManager package to use.
+
+@end table
+@end deftp
+
@cindex NetworkManager
@defvr {Scheme Variable} network-manager-service-type
@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 })
+@item @code{xsession-command} (default: @code{xinitrc})
Script to run before starting a X session.
@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
Last, @var{extra-config} is a list of strings or objects appended to the
configuration file. It is used to pass extra text to be
added verbatim to the configuration file.
+
+@cindex keymap
+@cindex keyboard layout
+This procedure is especially useful to configure a different keyboard layout
+than the default US keymap. For instance, to use the ``bépo'' keymap by
+default on the display manager:
+
+@example
+(define bepo-evdev
+ "Section \"InputClass\"
+ Identifier \"evdev keyboard catchall\"
+ Driver \"evdev\"
+ MatchIsKeyboard \"on\"
+ Option \"xkb_layout\" \"fr\"
+ Option \"xkb_variant\" \"bepo\"
+EndSection")
+
+(operating-system
+ ...
+ (services
+ (modify-services %desktop-services
+ (slim-service-type config =>
+ (slim-configuration
+ (inherit config)
+ (startx (xorg-start-command
+ #:configuration-file
+ (xorg-configuration-file
+ #:extra-config
+ (list bepo-evdev)))))))))
+@end example
+
+The @code{MatchIsKeyboard} line specifies that we only apply the configuration
+to keyboards. Without this line, other devices such as touchpad may not work
+correctly because they will be attached to the wrong driver. In this example,
+the user typically used @code{setxkbmap fr bepo} to set their favorite keymap
+once logged in. The first argument corresponds to the layout, while the second
+argument corresponds to the variant. The @code{xkb_variant} line can be omitted
+to select the default variant.
@end deffn
@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
Reference, @code{services}}).
Additionally, the @code{gnome-desktop-service},
-@code{xfce-desktop-service} and @code{mate-desktop-service}
-procedures can add GNOME, XFCE and/or MATE to a system.
-To ``add GNOME'' means that system-level services like the
-backlight adjustment helpers and the power management utilities are
-added to the system, extending @code{polkit} and @code{dbus}
+@code{xfce-desktop-service}, @code{mate-desktop-service} and
+@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, MATE
+and/or Enlightenment to a system. To ``add GNOME'' means that system-level
+services like the backlight adjustment helpers and the power management
+utilities are added to the system, extending @code{polkit} and @code{dbus}
appropriately, allowing GNOME to operate with elevated privileges on a
limited number of special-purpose system interfaces. Additionally,
adding a service made by @code{gnome-desktop-service} adds the GNOME
appropriately, allowing MATE to operate with elevated privileges on a
limited number of special-purpose system interfaces. Additionally,
adding a service made by @code{mate-desktop-service} adds the MATE
-metapackage to the system profile.
+metapackage to the system profile. ``Adding ENLIGHTENMENT'' means that
+@code{dbus} is extended appropriately, and several of Enlightenment's binaries
+are set as setuid, allowing Enlightenment's screen locker and other
+functionality to work as expetected.
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
@code{mate-settings-daemon}.
@end deffn
+@deffn {Scheme Procedure} enlightenment-desktop-service-type
+Return a service that adds the @code{enlightenment} package to the system
+profile, and extends dbus with actions from @code{efl}.
+@end deffn
+
+@deftp {Data Type} enlightenment-desktop-service-configuration
+@table @asis
+@item @code{enlightenment} (default @code{enlightenment})
+The enlightenment package to use.
+@end table
+@end deftp
+
Because the GNOME, XFCE and MATE desktop services pull in so many packages,
-the default @code{%desktop-services} variable doesn't include either of
+the default @code{%desktop-services} variable doesn't include any of
them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:
Users need to be in the @code{lp} group to access the D-Bus service.
@end deffn
+@node Sound Services
+@subsubsection Sound Services
+
+@cindex sound support
+@cindex ALSA
+@cindex PulseAudio, sound support
+
+The @code{(gnu services sound)} module provides an
+@code{alsa-service-type} service to generate an ALSA
+@file{/etc/asound.conf} configuration file. This configuration file is
+what allows applications that produce sound using ALSA to be correctly
+handled.
+
+@deffn {Scheme Variable} alsa-service-type
+This is the type for the @uref{https://alsa-project.org/, ALSA},
+@command{alsa-configuration} record as in this example:
+
+@example
+(service alsa-service-type)
+@end example
+
+See below for details about @code{alsa-configuration}.
+@end deffn
+
+@deftp {Data Type} alsa-configuration
+Data type representing the configuration for @code{alsa-service}.
+
+@table @asis
+@item @code{pulseaudio?} (default: @var{#t})
+Whether ALSA applications should transparently be made to use the
+@uref{http://www.pulseaudio.org/, PulseAudio} sound server.
+
+Using PulseAudio allows you to run several sound-producing applications
+at the same time and to individual control them @i{via}
+@command{pavucontrol}, among other things.
+
+@item @code{extra-options} (default: @var{""})
+String to append to the @file{asound.conf} file.
+
+@end table
+@end deftp
+
@node Database Services
@subsubsection Database Services
@item @code{package} (default: @code{bitlbee})
The BitlBee package to use.
+@item @code{plugins} (default: @code{'()})
+List of plugin packages to use---e.g., @code{bitlbee-discord}.
+
@item @code{extra-settings} (default: @code{""})
Configuration snippet added as-is to the BitlBee configuration file.
@end table
@item @code{<php-fpm-on-demand-process-manager-configuration>}
@end table
@item @code{display-errors} (default @code{#f})
-Determines wether php errors and warning should be sent to clients
+Determines whether php errors and warning should be sent to clients
and displayed in their browsers.
This is useful for local php development, but a security risk for public sites,
as error messages can reveal passwords and personal data.
%base-services))
@end example
+@subsubheading Hpcguix-web
+
+@cindex hpcguix-web
+The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/}
+program is a customizable web interface to browse Guix packages,
+initially designed for users of high-performance computing (HPC)
+clusters.
+
+@defvr {Scheme Variable} hpcguix-web-service-type
+The service type for @code{hpcguix-web}.
+@end defvr
+
+@deftp {Data Type} hpcguix-web-configuration
+Data type for the hpcguix-web service configuration.
+
+@table @asis
+@item @code{specs}
+A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service
+configuration. The main items available in this spec are:
+
+@table @asis
+@item @code{title-prefix} (default: @code{"hpcguix | "})
+The page title prefix.
+
+@item @code{guix-command} (default: @code{"guix"})
+The @command{guix} command.
+
+@item @code{package-filter-proc} (default: @code{(const #t)})
+A procedure specifying how to filter packages that are displayed.
+
+@item @code{package-page-extension-proc} (default: @code{(const '())})
+Extension package for @code{hpcguix-web}.
+
+@item @code{menu} (default: @code{'()})
+Additional entry in page @code{menu}.
+@end table
+
+See the hpcguix-web repository for a
+@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
+complete example}.
+
+@item @code{package} (default: @code{hpcguix-web})
+The hpcguix-web package to use.
+@end table
+@end deftp
+
+A typical hpcguix-web service declaration looks like this:
+
+@example
+(service hpcguix-web-service-type
+ (hpcguix-web-configuration
+ (specs
+ #~(define site-config
+ (hpcweb-configuration
+ (title-prefix "Guix-HPC - ")
+ (menu '(("/about" "ABOUT"))))))))
+@end example
+
@node Certificate Services
@subsubsection Certificate Services
The @code{(gnu services dns)} module provides services related to the
@dfn{domain name system} (DNS). It provides a server service for hosting
an @emph{authoritative} DNS server for multiple zones, slave or master.
-This service uses @uref{https://www.knot-dns.cz/, Knot DNS}.
+This service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a
+caching and forwarding DNS server for the LAN, which uses
+@uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}.
+
+@subsubheading Knot Service
An example configuration of an authoritative server for two zones, one master
and one slave, is:
@end table
@end deftp
+@subsubheading Dnsmasq Service
+
+@deffn {Scheme Variable} dnsmasq-service-type
+This is the type of the dnsmasq service, whose value should be an
+@code{dnsmasq-configuration} object as in this example:
+
+@example
+(service dnsmasq-service-type
+ (dnsmasq-configuration
+ (no-resolv? #t)
+ (servers '("192.168.1.1"))))
+@end example
+@end deffn
+
+@deftp {Data Type} dnsmasq-configuration
+Data type representing the configuration of dnsmasq.
+
+@table @asis
+@item @code{package} (default: @var{dnsmasq})
+Package object of the dnsmasq server.
+
+@item @code{no-hosts?} (default: @code{#f})
+When true, don't read the hostnames in /etc/hosts.
+
+@item @code{port} (default: @code{53})
+The port to listen on. Setting this to zero completely disables DNS
+funtion, leaving only DHCP and/or TFTP.
+
+@item @code{local-service?} (default: @code{#t})
+Accept DNS queries only from hosts whose address is on a local subnet,
+ie a subnet for which an interface exists on the server.
+
+@item @code{listen-addresses} (default: @code{'()})
+Listen on the given IP addresses.
+
+@item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
+The file to read the IP address of the upstream nameservers from.
+
+@item @code{no-resolv?} (default: @code{#f})
+When true, don't read @var{resolv-file}.
+
+@item @code{servers} (default: @code{'()})
+Specify IP address of upstream servers directly.
+
+@item @code{cache-size} (default: @code{150})
+Set the size of dnsmasq's cache. Setting the cache size to zero
+disables caching.
+
+@item @code{negative-cache?} (default: @code{#t})
+When false, disable negative caching.
+
+@end table
+@end deftp
@node VPN Services
@subsubsection VPN Services
@subsubsection Version Control Services
The @code{(gnu services version-control)} module provides a service to
-allow remote access to local Git repositories. There are two options:
+allow remote access to local Git repositories. There are three options:
the @code{git-daemon-service}, which provides access to repositories via
-the @code{git://} unsecured TCP-based protocol, or extending the
+the @code{git://} unsecured TCP-based protocol, extending the
@code{nginx} web server to proxy some requests to
-@code{git-http-backend}.
+@code{git-http-backend}, or providing a web interface with
+@code{cgit-service-type}.
@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]
system services. @xref{Web Services}.
@end deffn
-@node Game Services
-@subsubsection Game Services
+@subsubheading Cgit Service
-@subsubheading The Battle for Wesnoth Service
-@cindex wesnothd
-@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
-based tactical strategy game, with several single player campaigns, and
-multiplayer games (both networked and local).
+@cindex Cgit service
+@cindex Git, web interface
+@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
+repositories written in C.
-@defvar {Scheme Variable} wesnothd-service-type
-Service type for the wesnothd service. Its value must be a
-@code{wesnothd-configuration} object. To run wesnothd in the default
-configuration, instantiate it as:
+The following example will configure the service with default values.
+By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
@example
-(service wesnothd-service-type)
+(service cgit-service-type)
@end example
-@end defvar
-
-@deftp {Data Type} wesnothd-configuration
-Data type representing the configuration of @command{wesnothd}.
-@table @asis
-@item @code{package} (default: @code{wesnoth-server})
-The wesnoth server package to use.
+The @code{file-object} type designates either a file-like object
+(@pxref{G-Expressions, file-like objects}) or a string.
-@item @code{port} (default: @code{15000})
-The port to bind the server to.
-@end table
-@end deftp
+@c %start of fragment
-@node Miscellaneous Services
-@subsubsection Miscellaneous Services
+Available @code{cgit-configuration} fields are:
-@cindex sysctl
-@subsubheading System Control Service
+@deftypevr {@code{cgit-configuration} parameter} package package
+The CGIT package.
-The @code{(gnu services sysctl)} provides a service to configure kernel
-parameters at boot.
-
-@defvr {Scheme Variable} sysctl-service-type
-The service type for @command{sysctl}, which modifies kernel parameters
-under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
-instantiated as:
-
-@example
-(service sysctl-service-type
- (sysctl-configuration
- (settings '(("net.ipv4.ip_forward" . "1")))))
-@end example
-@end defvr
-
-@deftp {Data Type} sysctl-configuration
-The data type representing the configuration of @command{sysctl}.
-
-@table @asis
-@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
-The @command{sysctl} executable to use.
-
-@item @code{settings} (default: @code{'()})
-An association list specifies kernel parameters and their values.
-@end table
-@end deftp
-
-@cindex lirc
-@subsubheading Lirc Service
-
-The @code{(gnu services lirc)} module provides the following service.
-
-@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
- [#:device #f] [#:driver #f] [#:config-file #f] @
- [#:extra-options '()]
-Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
-decodes infrared signals from remote controls.
-
-Optionally, @var{device}, @var{driver} and @var{config-file}
-(configuration file name) may be specified. See @command{lircd} manual
-for details.
-
-Finally, @var{extra-options} is a list of additional command-line options
-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
-@cindex dictionary
-The @code{(gnu services dict)} module provides the following service:
-
-@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
-Return a service that runs the @command{dicod} daemon, an implementation
-of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
-
-The optional @var{config} argument specifies the configuration for
-@command{dicod}, which should be a @code{<dicod-configuration>} object, by
-default it serves the GNU Collaborative International Dictonary of English.
-
-You can add @command{open localhost} to your @file{~/.dico} file to make
-@code{localhost} the default server for @command{dico} client
-(@pxref{Initialization File,,, dico, GNU Dico Manual}).
-@end deffn
-
-@deftp {Data Type} dicod-configuration
-Data type representing the configuration of dicod.
-
-@table @asis
-@item @code{dico} (default: @var{dico})
-Package object of the GNU Dico dictionary server.
-
-@item @code{interfaces} (default: @var{'("localhost")})
-This is the list of IP addresses and ports and possibly socket file
-names to listen to (@pxref{Server Settings, @code{listen} directive,,
-dico, GNU Dico Manual}).
-
-@item @code{handlers} (default: @var{'()})
-List of @code{<dicod-handler>} objects denoting handlers (module instances).
-
-@item @code{databases} (default: @var{(list %dicod-database:gcide)})
-List of @code{<dicod-database>} objects denoting dictionaries to be served.
-@end table
-@end deftp
-
-@deftp {Data Type} dicod-handler
-Data type representing a dictionary handler (module instance).
-
-@table @asis
-@item @code{name}
-Name of the handler (module instance).
-
-@item @code{module} (default: @var{#f})
-Name of the dicod module of the handler (instance). If it is @code{#f},
-the module has the same name as the handler.
-(@pxref{Modules,,, dico, GNU Dico Manual}).
-
-@item @code{options}
-List of strings or gexps representing the arguments for the module handler
-@end table
-@end deftp
-
-@deftp {Data Type} dicod-database
-Data type representing a dictionary database.
-
-@table @asis
-@item @code{name}
-Name of the database, will be used in DICT commands.
-
-@item @code{handler}
-Name of the dicod handler (module instance) used by this database
-(@pxref{Handlers,,, dico, GNU Dico Manual}).
-
-@item @code{complex?} (default: @var{#f})
-Whether the database configuration complex. The complex configuration
-will need a corresponding @code{<dicod-handler>} object, otherwise not.
-
-@item @code{options}
-List of strings or gexps representing the arguments for the database
-(@pxref{Databases,,, dico, GNU Dico Manual}).
-@end table
-@end deftp
-
-@defvr {Scheme Variable} %dicod-database:gcide
-A @code{<dicod-database>} object serving the GNU Collaborative International
-Dictionary of English using the @code{gcide} package.
-@end defvr
-
-The following is an example @code{dicod-service} configuration.
-
-@example
-(dicod-service #:config
- (dicod-configuration
- (handlers (list (dicod-handler
- (name "wordnet")
- (module "dictorg")
- (options
- (list #~(string-append "dbdir=" #$wordnet))))))
- (databases (list (dicod-database
- (name "wordnet")
- (complex? #t)
- (handler "wordnet")
- (options '("database=wn")))
- %dicod-database:gcide))))
-@end example
-
-
-@subsubheading Cgit Service
-
-@cindex Cgit service
-@cindex Git, web interface
-@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
-repositories written in C.
-
-The following example will configure the service with default values.
-By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
-
-@example
-(service cgit-service-type)
-@end example
-
-@c %start of fragment
-
-Available @code{cgit-configuration} fields are:
-
-@deftypevr {@code{cgit-configuration} parameter} package package
-The CGIT package.
-
-@end deftypevr
+@end deftypevr
@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx
NGINX configuration.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string about-filter
+@deftypevr {@code{cgit-configuration} parameter} file-object about-filter
Specifies a command which will be invoked to format the content of about
pages (both top-level and for each repository).
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string auth-filter
+@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter
Specifies a command that will be invoked for authenticating repository
access.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string commit-filter
+@deftypevr {@code{cgit-configuration} parameter} file-object commit-filter
Command which will be invoked to format commit messages.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string css
+@deftypevr {@code{cgit-configuration} parameter} file-object css
URL which specifies the css document to include in all cgit pages.
Defaults to @samp{"/share/cgit/cgit.css"}.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string email-filter
+@deftypevr {@code{cgit-configuration} parameter} file-object email-filter
Specifies a command which will be invoked to format names and email
address of committers, authors, and taggers, as represented in various
places throughout the cgit interface.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string favicon
+@deftypevr {@code{cgit-configuration} parameter} file-object favicon
URL used as link to a shortcut icon for cgit.
Defaults to @samp{"/favicon.ico"}.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string include
+@deftypevr {@code{cgit-configuration} parameter} file-object include
Name of a configfile to include before the rest of the current config-
file is parsed.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string logo
+@deftypevr {@code{cgit-configuration} parameter} file-object logo
URL which specifies the source of an image which will be used as a logo
on all cgit pages.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string owner-filter
+@deftypevr {@code{cgit-configuration} parameter} file-object owner-filter
Command which will be invoked to format the Owner column of the main
page.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string mimetype-file
+@deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file
Specifies the file to use for automatic mimetype lookup.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string readme
+@deftypevr {@code{cgit-configuration} parameter} project-list project-list
+A list of subdirectories inside of @code{repository-directory}, relative
+to it, that should loaded as Git repositories. An empty list means that
+all subdirectories will be loaded.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object readme
Text which will be used as default value for @code{cgit-repo-readme}.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{cgit-configuration} parameter} string source-filter
+@deftypevr {@code{cgit-configuration} parameter} file-object source-filter
Specifies a command which will be invoked to format plaintext blobs in
the tree view.
@end deftypevr
-@deftypevr {@code{repository-cgit-configuration} parameter} repo-string source-filter
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter
Override the default @code{source-filter}.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{repository-cgit-configuration} parameter} repo-string about-filter
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter
Override the default @code{about-filter}.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-filter
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter
Override the default @code{commit-filter}.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{repository-cgit-configuration} parameter} repo-string email-filter
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter
Override the default @code{email-filter}.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo
URL which specifies the source of an image which will be used as a logo
on this repo’s pages.
@end deftypevr
-@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner-filter
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter
Override the default @code{owner-filter}.
Defaults to @samp{""}.
@end deftypevr
+
@c %end of fragment
However, it could be that you just want to get a @code{cgitrc} up and
(cgitrc "")))
@end example
+
+@node Game Services
+@subsubsection Game Services
+
+@subsubheading The Battle for Wesnoth Service
+@cindex wesnothd
+@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
+based tactical strategy game, with several single player campaigns, and
+multiplayer games (both networked and local).
+
+@defvar {Scheme Variable} wesnothd-service-type
+Service type for the wesnothd service. Its value must be a
+@code{wesnothd-configuration} object. To run wesnothd in the default
+configuration, instantiate it as:
+
+@example
+(service wesnothd-service-type)
+@end example
+@end defvar
+
+@deftp {Data Type} wesnothd-configuration
+Data type representing the configuration of @command{wesnothd}.
+
+@table @asis
+@item @code{package} (default: @code{wesnoth-server})
+The wesnoth server package to use.
+
+@item @code{port} (default: @code{15000})
+The port to bind the server to.
+@end table
+@end deftp
+
+@node Miscellaneous Services
+@subsubsection Miscellaneous Services
+
+@cindex sysctl
+@subsubheading System Control Service
+
+The @code{(gnu services sysctl)} provides a service to configure kernel
+parameters at boot.
+
+@defvr {Scheme Variable} sysctl-service-type
+The service type for @command{sysctl}, which modifies kernel parameters
+under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
+instantiated as:
+
+@example
+(service sysctl-service-type
+ (sysctl-configuration
+ (settings '(("net.ipv4.ip_forward" . "1")))))
+@end example
+@end defvr
+
+@deftp {Data Type} sysctl-configuration
+The data type representing the configuration of @command{sysctl}.
+
+@table @asis
+@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
+The @command{sysctl} executable to use.
+
+@item @code{settings} (default: @code{'()})
+An association list specifies kernel parameters and their values.
+@end table
+@end deftp
+
+@cindex lirc
+@subsubheading Lirc Service
+
+The @code{(gnu services lirc)} module provides the following service.
+
+@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
+ [#:device #f] [#:driver #f] [#:config-file #f] @
+ [#:extra-options '()]
+Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
+decodes infrared signals from remote controls.
+
+Optionally, @var{device}, @var{driver} and @var{config-file}
+(configuration file name) may be specified. See @command{lircd} manual
+for details.
+
+Finally, @var{extra-options} is a list of additional command-line options
+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
+@cindex dictionary
+The @code{(gnu services dict)} module provides the following service:
+
+@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
+Return a service that runs the @command{dicod} daemon, an implementation
+of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
+
+The optional @var{config} argument specifies the configuration for
+@command{dicod}, which should be a @code{<dicod-configuration>} object, by
+default it serves the GNU Collaborative International Dictonary of English.
+
+You can add @command{open localhost} to your @file{~/.dico} file to make
+@code{localhost} the default server for @command{dico} client
+(@pxref{Initialization File,,, dico, GNU Dico Manual}).
+@end deffn
+
+@deftp {Data Type} dicod-configuration
+Data type representing the configuration of dicod.
+
+@table @asis
+@item @code{dico} (default: @var{dico})
+Package object of the GNU Dico dictionary server.
+
+@item @code{interfaces} (default: @var{'("localhost")})
+This is the list of IP addresses and ports and possibly socket file
+names to listen to (@pxref{Server Settings, @code{listen} directive,,
+dico, GNU Dico Manual}).
+
+@item @code{handlers} (default: @var{'()})
+List of @code{<dicod-handler>} objects denoting handlers (module instances).
+
+@item @code{databases} (default: @var{(list %dicod-database:gcide)})
+List of @code{<dicod-database>} objects denoting dictionaries to be served.
+@end table
+@end deftp
+
+@deftp {Data Type} dicod-handler
+Data type representing a dictionary handler (module instance).
+
+@table @asis
+@item @code{name}
+Name of the handler (module instance).
+
+@item @code{module} (default: @var{#f})
+Name of the dicod module of the handler (instance). If it is @code{#f},
+the module has the same name as the handler.
+(@pxref{Modules,,, dico, GNU Dico Manual}).
+
+@item @code{options}
+List of strings or gexps representing the arguments for the module handler
+@end table
+@end deftp
+
+@deftp {Data Type} dicod-database
+Data type representing a dictionary database.
+
+@table @asis
+@item @code{name}
+Name of the database, will be used in DICT commands.
+
+@item @code{handler}
+Name of the dicod handler (module instance) used by this database
+(@pxref{Handlers,,, dico, GNU Dico Manual}).
+
+@item @code{complex?} (default: @var{#f})
+Whether the database configuration complex. The complex configuration
+will need a corresponding @code{<dicod-handler>} object, otherwise not.
+
+@item @code{options}
+List of strings or gexps representing the arguments for the database
+(@pxref{Databases,,, dico, GNU Dico Manual}).
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %dicod-database:gcide
+A @code{<dicod-database>} object serving the GNU Collaborative International
+Dictionary of English using the @code{gcide} package.
+@end defvr
+
+The following is an example @code{dicod-service} configuration.
+
+@example
+(dicod-service #:config
+ (dicod-configuration
+ (handlers (list (dicod-handler
+ (name "wordnet")
+ (module "dictorg")
+ (options
+ (list #~(string-append "dbdir=" #$wordnet))))))
+ (databases (list (dicod-database
+ (name "wordnet")
+ (complex? #t)
+ (handler "wordnet")
+ (options '("database=wn")))
+ %dicod-database:gcide))))
+@end example
+
@node Setuid Programs
@subsection Setuid Programs
be created. The @code{--image-size} option can be used to specify the
size of the image.
+@cindex System images, creation in various formats
+@cindex Creating system images in various formats
@item vm-image
@itemx disk-image
-Return a virtual machine or disk image of the operating system declared
-in @var{file} that stands alone. By default, @command{guix system}
-estimates the size of the image needed to store the system, but you can
-use the @option{--image-size} option to specify a value.
+@itemx docker-image
+Return a virtual machine, disk image, or Docker image of the operating
+system declared in @var{file} that stands alone. By default,
+@command{guix system} estimates the size of the image needed to store
+the system, but you can use the @option{--image-size} option to specify
+a value. Docker images are built to contain exactly what they need, so
+the @option{--image-size} option is ignored in the case of
+@code{docker-image}.
You can specify the root file system type by using the
@option{--file-system-type} option. It defaults to @code{ext4}.
# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
@end example
+When using @code{docker-image}, a Docker image is produced. Guix builds
+the image from scratch, not from a pre-existing Docker base image. As a
+result, it contains @emph{exactly} what you define in the operating
+system configuration file. You can then load the image and launch a
+Docker container using commands like the following:
+
+@example
+image_id="$(docker load < guixsd-docker-image.tar.gz)"
+docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\
+ --entrypoint /var/guix/profiles/system/profile/bin/guile \\
+ $image_id /var/guix/profiles/system/boot
+@end example
+
+This command starts a new Docker container from the specified image. It
+will boot the GuixSD system in the usual manner, which means it will
+start any services you have defined in the operating system
+configuration. Depending on what you run in the Docker container, it
+may be necessary to give the container additional permissions. For
+example, if you intend to build software using Guix inside of the Docker
+container, you may need to pass the @option{--privileged} option to
+@code{docker run}.
+
@item container
Return a script to run the operating system declared in @var{file}
within a container. Containers are a set of lightweight isolation
Otherwise, it must be a one-argument procedure. The procedure is called
by @code{fold-services} and is passed a list of values collected from
-extensions. It must return a value that is a valid parameter value for
-the service instance.
+extensions. It may return any single value.
@item @code{extend} (default: @code{#f})
If this is @code{#f}, services of this type cannot be extended.
Otherwise, it must be a two-argument procedure: @code{fold-services}
-calls it, passing it the initial value of the service as the first argument
-and the result of applying @code{compose} to the extension values as the
-second argument.
+calls it, passing it the initial value of the service as the first
+argument and the result of applying @code{compose} to the extension
+values as the second argument. It must return a value that is a valid
+parameter value for the service instance.
@end table
@xref{Service Types and Services}, for examples.
HCoop / jackhill / guix / guix.git / blobdiff