Copyright @copyright{} 2015, 2016 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016 Chris Marusich@*
-Copyright @copyright{} 2016 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016 ng0@*
Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
Copyright @copyright{} 2017 Clément Lassieur@*
Copyright @copyright{} 2017 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
-Copyright @copyright{} 2017 Carlo Zancanaro
+Copyright @copyright{} 2017 Carlo Zancanaro@*
+Copyright @copyright{} 2017 Thomas Danckaert@*
+Copyright @copyright{} 2017 humanitiesNerd@*
+Copyright @copyright{} 2017 Christopher Allan Webber
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
+* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
* Synopses and Descriptions:: Helping users find the right package.
-* Python Modules:: Taming the snake.
+* Python Modules:: A touch of British comedy.
* Perl Modules:: Little pearls.
* Java Packages:: Coffee break.
* Fonts:: Fond of fonts.
~root/.guix-profile
@end example
+Source @file{etc/profile} to augment @code{PATH} and other relevant
+environment variables:
+
+@example
+# GUIX_PROFILE=$HOME/.guix-profile \
+ source $GUIX_PROFILE/etc/profile
+@end example
+
@item
Create the group and user accounts for build users as explained below
(@pxref{Build Environment Setup}).
procedures or dependencies. Guix also goes beyond this obvious set of
features.
-This chapter describes the main features of Guix, as well as the package
-management tools it provides. Along with the command-line interface
-described below (@pxref{Invoking guix package, @code{guix package}}),
-you may also use Emacs Interface, after installing @code{emacs-guix}
-package (run @kbd{M-x guix-help} command to start with it):
+This chapter describes the main features of Guix, as well as the
+package management tools it provides. Along with the command-line
+interface described below (@pxref{Invoking guix package, @code{guix
+package}}), you may also use Emacs Interface (@pxref{Top,,,
+emacs-guix, The Emacs-Guix Reference Manual}), after installing
+@code{emacs-guix} package (run @kbd{M-x guix-help} command to start
+with it):
@example
guix package -i emacs-guix
canonical Git repo:
@example
-guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz
+guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz
@end example
It can also be used to deploy arbitrary Git revisions:
@example
-guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz
+guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz
@end example
@item --bootstrap
useful to Guix developers.
@end table
+In addition, @command{guix pull} supports all the common build options
+(@pxref{Common Build Options}).
@node Invoking guix pack
@section Invoking @command{guix pack}
Docker Image Specification}.
@end table
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
+
+This has the same purpose as the same-named option in @command{guix
+build} (@pxref{Additional Build Options, @code{--expression} in
+@command{guix build}}).
+
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
-tool (@pxref{Invoking guix build}). You can easily jump back to the
+tool (@pxref{Invoking guix build}), troubleshooting any build failures
+you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
package definition using the @command{guix edit} command
(@pxref{Invoking guix edit}).
@xref{Packaging Guidelines}, for
This is exactly what the @option{--with-input} command-line option does
(@pxref{Package Transformation Options, @option{--with-input}}).
+A more generic procedure to rewrite a package dependency graph is
+@code{package-mapping}: it supports arbitrary changes to nodes in the
+graph.
+
+@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
+Return a procedure that, given a package, applies @var{proc} to all the packages
+depended on and returns the resulting package. The procedure stops recursion
+when @var{cut?} returns true for a given package.
+@end deffn
+
@menu
* package Reference :: The package data type.
* origin Reference:: The origin data type.
When the original package does not provide a suitable Ant build file,
the parameter @code{#:jar-name} can be used to generate a minimal Ant
build file @file{build.xml} with tasks to build the specified jar
-archive.
+archive. In this case the parameter @code{#:source-dir} can be used to
+specify the source sub-directory, defaulting to ``src''.
The parameter @code{#:build-target} can be used to specify the Ant task
that should be run during the @code{build} phase. By default the
@end defvr
@defvr {Scheme Variable} ocaml-build-system
-This variable is exported by @code{(guix build-sytem ocaml)}. It implements
+This variable is exported by @code{(guix build-system ocaml)}. It implements
a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
of choosing the correct set of commands to run for each package. OCaml
packages can expect many different commands to be run. This build system will
@end quotation
The @code{(guix store)} module provides procedures to connect to the
-daemon, and to perform RPCs. These are described below.
+daemon, and to perform RPCs. These are described below. By default,
+@code{open-connection}, and thus all the @command{guix} commands,
+connect to the local daemon or to the URI specified by the
+@code{GUIX_DAEMON_SOCKET} environment variable.
+
+@defvr {Environment Variable} GUIX_DAEMON_SOCKET
+When set, the value of this variable should be a file name or a URI
+designating the daemon endpoint. When it is a file name, it denotes a
+Unix-domain socket to connect to. In addition to file names, the
+supported URI schemes are:
-@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
-Connect to the daemon over the Unix-domain socket at @var{file}. When
+@table @code
+@item file
+@itemx unix
+These are for Unix-domain sockets.
+@code{file:///var/guix/daemon-socket/socket} is equivalent to
+@file{/var/guix/daemon-socket/socket}.
+
+@item guix
+These URIs denote connections over TCP/IP, without encryption nor
+authentication of the remote host. The URI must always specify both the
+host name and port number:
+
+@example
+guix://master.guix.example.org:1234
+@end example
+
+This setup is suitable on local networks, such as clusters, where only
+trusted nodes may connect to the build daemon at
+@code{master.guix.example.org}.
+
+@item ssh
+@cindex SSH access to build daemons
+These URIs allow you to connect to a remote daemon over
+SSH@footnote{This feature requires Guile-SSH (@pxref{Requirements}).}.
+A typical URL might look like this:
+
+@example
+ssh://charlie@@guix.example.org:22
+@end example
+
+As for @command{guix copy}, the usual OpenSSH client configuration files
+are honored (@pxref{Invoking guix copy}).
+@end table
+
+Additional URI schemes may be supported in the future.
+
+@c XXX: Remove this note when the protocol incurs fewer round trips
+@c and when (guix derivations) no longer relies on file system access.
+@quotation Note
+The ability to connect to remote build daemons is considered
+experimental as of @value{VERSION}. Please get in touch with us to
+share any problems or suggestions you may have (@pxref{Contributing}).
+@end quotation
+@end defvr
+
+@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
+Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
@var{reserve-space?} is true, instruct it to reserve a little bit of
extra space on the file system so that the garbage collector can still
operate should the disk become full. Return a server object.
@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
@var{body} ...
Bind the variables @var{var} to the monadic values @var{mval} in
-@var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
-``normal'' value @var{val}, as per @code{let}.
+@var{body}, which is a sequence of expressions. As with the bind
+operator, this can be thought of as ``unpacking'' the raw, non-monadic
+value ``contained'' in @var{mval} and making @var{var} refer to that
+raw, non-monadic value within the scope of the @var{body}. The form
+(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
+@var{val}, as per @code{let}. The binding operations occur in sequence
+from left to right. The last expression of @var{body} must be a monadic
+expression, and its result will become the result of the @code{mlet} or
+@code{mlet*} when run in the @var{monad}.
@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
Bind @var{mexp} and the following monadic expressions in sequence,
-returning the result of the last expression.
+returning the result of the last expression. Every expression in the
+sequence must be a monadic expression.
This is akin to @code{mlet}, except that the return values of the
monadic expressions are ignored. In that sense, it is analogous to
@code{begin}, but applied to monadic expressions.
@end deffn
+@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
+When @var{condition} is true, evaluate the sequence of monadic
+expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
+@var{condition} is false, return @code{*unspecified*} in the current
+monad. Every expression in the sequence must be a monadic expression.
+@end deffn
+
+@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
+When @var{condition} is false, evaluate the sequence of monadic
+expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
+@var{condition} is true, return @code{*unspecified*} in the current
+monad. Every expression in the sequence must be a monadic expression.
+@end deffn
+
@cindex state monad
The @code{(guix monads)} module provides the @dfn{state monad}, which
allows an additional value---the state---to be @emph{threaded} through
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
+* Debugging Build Failures:: Real life packaging experience
@end menu
@node Common Build Options
Keep the build tree of failed builds. Thus, if a build fails, its build
tree is kept under @file{/tmp}, in a directory whose name is shown at
the end of the build log. This is useful when debugging build issues.
+@xref{Debugging Build Failures}, for tips and tricks on how to debug
+build issues.
@item --keep-going
@itemx -k
You can freely access a huge library of build logs!
@end table
+@node Debugging Build Failures
+@subsection Debugging Build Failures
+
+@cindex build failures, debugging
+When defining a new package (@pxref{Defining Packages}), you will
+probably find yourself spending some time debugging and tweaking the
+build until it succeeds. To do that, you need to operate the build
+commands yourself in an environment as close as possible to the one the
+build daemon uses.
+
+To that end, the first thing to do is to use the @option{--keep-failed}
+or @option{-K} option of @command{guix build}, which will keep the
+failed build tree in @file{/tmp} or whatever directory you specified as
+@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}).
+
+From there on, you can @command{cd} to the failed build tree and source
+the @file{environment-variables} file, which contains all the
+environment variable definitions that were in place when the build
+failed. So let's say you're debugging a build failure in package
+@code{foo}; a typical session would look like this:
+
+@example
+$ guix build foo -K
+@dots{} @i{build fails}
+$ cd /tmp/guix-build-foo.drv-0
+$ source ./environment-variables
+$ cd foo-1.2
+@end example
+
+Now, you can invoke commands as if you were the daemon (almost) and
+troubleshoot your build process.
+
+Sometimes it happens that, for example, a package's tests pass when you
+run them manually but they fail when the daemon runs them. This can
+happen because the daemon runs builds in containers where, unlike in our
+environment above, network access is missing, @file{/bin/sh} does not
+exist, etc. (@pxref{Build Environment Setup}).
+
+In such cases, you may need to run inspect the build process from within
+a container similar to the one the build daemon creates:
+
+@example
+$ guix build -K foo
+@dots{}
+$ cd /tmp/guix-build-foo.drv-0
+$ guix environment -C foo --ad-hoc strace gdb
+[env]# source ./environment-variables
+[env]# cd foo-1.2
+@end example
+
+Here, @command{guix environment -C} creates a container and spawns a new
+shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
+strace gdb} part adds the @command{strace} and @command{gdb} commands to
+the container, which would may find handy while debugging.
+
+To get closer to a container like that used by the build daemon, we can
+remove @file{/bin/sh}:
+
+@example
+[env]# rm /bin/sh
+@end example
+
+(Don't worry, this is harmless: this is all happening in the throw-away
+container created by @command{guix environment}.)
+
+The @command{strace} command is probably not in the search path, but we
+can run:
+
+@example
+[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
+@end example
+
+In this way, not only you will have reproduced the environment variables
+the daemon uses, you will also be running the build process in a container
+similar to the one the daemon uses.
+
@node Invoking guix edit
@section Invoking @command{guix edit}
@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
-hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
+hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
@end example
The command above lists a set of packages that could be built to check
@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
directly to the @command{dot} command of Graphviz. It can also emit an
HTML page with embedded JavaScript code to display a ``chord diagram''
-in a Web browser, using the @uref{https://d3js.org/, d3.js} library.
+in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
+emit Cypher queries to construct a graph in a graph database supporting
+the @uref{http://www.opencypher.org/, openCypher} query language.
The general syntax is:
@example
guix-daemon --substitute-urls=http://example.org:8080
@end example
+By default, @command{guix publish} compresses archives on the fly as it
+serves them. This ``on-the-fly'' mode is convenient in that it requires
+no setup and is immediately available. However, when serving lots of
+clients, we recommend using the @option{--cache} option, which enables
+caching of the archives before they are sent to clients---see below for
+details.
+
As a bonus, @command{guix publish} also serves as a content-addressed
mirror for source files referenced in @code{origin} records
(@pxref{origin Reference}). For instance, assuming @command{guix
compression levels: 1 is the fastest, and 9 is the best (CPU-intensive).
The default is 3.
-Compression occurs on the fly and the compressed streams are not
+Unless @option{--cache} is used, compression occurs on the fly and
+the compressed streams are not
cached. Thus, to reduce load on the machine that runs @command{guix
-publish}, it may be a good idea to choose a low compression level, or to
-run @command{guix publish} behind a caching proxy.
+publish}, it may be a good idea to choose a low compression level, to
+run @command{guix publish} behind a caching proxy, or to use
+@option{--cache}. Using @option{--cache} has the advantage that it
+allows @command{guix publish} to add @code{Content-Length} HTTP header
+to its responses.
+
+@item --cache=@var{directory}
+@itemx -c @var{directory}
+Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
+and only serve archives that are in cache.
+
+When this option is omitted, archives and meta-data are created
+on-the-fly. This can reduce the available bandwidth, especially when
+compression is enabled, since this may become CPU-bound. Another
+drawback of the default mode is that the length of archives is not known
+in advance, so @command{guix publish} does not add a
+@code{Content-Length} HTTP header to its responses, which in turn
+prevents clients from knowing the amount of data being downloaded.
+
+Conversely, when @option{--cache} is used, the first request for a store
+item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a
+background process to @dfn{bake} the archive---computing its
+@code{.narinfo} and compressing the archive, if needed. Once the
+archive is cached in @var{directory}, subsequent requests succeed and
+are served directly from the cache, which guarantees that clients get
+the best possible bandwidth.
+
+The ``baking'' process is performed by worker threads. By default, one
+thread per CPU core is created, but this can be customized. See
+@option{--workers} below.
+
+When @option{--ttl} is used, cached entries are automatically deleted
+when they have expired.
+
+@item --workers=@var{N}
+When @option{--cache} is used, request the allocation of @var{N} worker
+threads to ``bake'' archives.
@item --ttl=@var{ttl}
Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
guarantee that the store items it provides will indeed remain available
for as long as @var{ttl}.
+Additionally, when @option{--cache} is used, cached entries that have
+not been accessed for @var{ttl} may be deleted.
+
@item --nar-path=@var{path}
Use @var{path} as the prefix for the URLs of ``nar'' files
(@pxref{Invoking guix archive, normalized archives}).
using the EABI hard-float application binary interface (ABI),
and Linux-Libre kernel.
+@item aarch64-linux
+little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
+currently in an experimental stage, with limited support.
+@xref{Contributing}, for how to help!
+
@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 ABI, and Linux-Libre kernel.
@menu
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
+* Documentation:: Browsing software user manuals.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
Support for the Logical Volume Manager (LVM) is missing.
@item
-Few system services are currently supported out-of-the-box
-(@pxref{Services}).
+More and more system services are provided (@pxref{Services}), but some
+may be missing.
@item
-More than 5,000 packages are available, but you may
+More than 5,300 packages are available, but you may
occasionally find that a useful package is missing.
@item
-GNOME, Xfce, and Enlightenment are available (@pxref{Desktop Services}),
+GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
as well as a number of X11 window managers. However, some graphical
applications may be missing, as well as KDE.
@end itemize
@noindent
This copies all the necessary files and installs GRUB on
-@file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
+@file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
more information, @pxref{Invoking guix system}. This command may trigger
downloads or builds of missing packages, which can take some time.
tasks---including the GNU Core Utilities, the GNU Networking Utilities,
the GNU Zile lightweight text editor, @command{find}, @command{grep},
etc. The example above adds tcpdump to those, taken from the @code{(gnu
-packages admin)} module (@pxref{Package Modules}).
+packages admin)} module (@pxref{Package Modules}). The
+@code{(list package output)} syntax can be used to add a specific output
+of a package:
+
+@lisp
+(use-modules (gnu packages))
+(use-modules (gnu packages dns))
+
+(operating-system
+ ;; ...
+ (packages (cons (list bind "utils")
+ %base-packages)))
+@end lisp
@findex specification->package
Referring to packages by variable name, like @var{tcpdump} above, has
@end deffn
@anchor{guix-publish-service-type}
-@deffn {Scheme Variable} guix-publish-service-type @var{config}
+@deffn {Scheme Variable} guix-publish-service-type
This is the service type for @command{guix publish} (@pxref{Invoking
-guix publish}). @var{config} must be a @code{guix-configuration}
+guix publish}). Its value must be a @code{guix-configuration}
object, as described below.
This assumes that @file{/etc/guix} already contains a signing key pair as
@item @code{nar-path} (default: @code{"nar"})
The URL path at which ``nars'' can be fetched. @xref{Invoking guix
publish, @code{--nar-path}}, for details.
+
+@item @code{cache} (default: @code{#f})
+When it is @code{#f}, disable caching and instead generate archives on
+demand. Otherwise, this should be the name of a directory---e.g.,
+@code{"/var/cache/guix/publish"}---where @command{guix publish} caches
+archives and meta-data ready to be sent. @xref{Invoking guix publish,
+@option{--cache}}, for more information on the tradeoffs involved.
+
+@item @code{workers} (default: @code{#f})
+When it is an integer, this is the number of worker threads used for
+caching; when @code{#f}, the number of processors is used.
+@xref{Invoking guix publish, @option{--workers}}, for more information.
+
+@item @code{ttl} (default: @code{#f})
+When it is an integer, this denotes the @dfn{time-to-live} of the
+published archives. @xref{Invoking guix publish, @option{--ttl}}, for
+more information.
@end table
@end deftp
(operating-system
;; @dots{}
(services (cons* (mcron-service)
- (service rottlog-service-type (rottlog-configuration))
+ (service rottlog-service-type)
%base-services)))
@end lisp
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))})
+@item @code{periodic-rotations} (default: @code{`(("weekly" %default-rotations))})
A list of Rottlog period-name/period-config tuples.
For example, taking an example from the Rottlog manual (@pxref{Period
Thus, it can be instantiated like this:
@lisp
-(use-modules (gnu services networking)
- (gnu packages admin))
+(use-modules (gnu services networking))
-(service wpa-supplicant-service-type wpa-supplicant)
+(service wpa-supplicant-service-type)
@end lisp
@end defvr
List of host names used as the default NTP servers.
@end defvr
+@cindex inetd
+@deffn {Scheme variable} inetd-service-type
+This service runs the @command{inetd} (@pxref{inetd invocation,,,
+inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
+connections on internet sockets, and lazily starts the specified server
+program when a connection is made on one of these sockets.
+
+The value of this service is an @code{inetd-configuration} object. The
+following example configures the @command{inetd} daemon to provide the
+built-in @command{echo} service, as well as an smtp service which
+forwards smtp traffic over ssh to a server @code{smtp-server} behind a
+gateway @code{hostname}:
+
+@example
+(service
+ inetd-service-type
+ (inetd-configuration
+ (entries (list
+ (inetd-entry
+ (name "echo")
+ (socket-type 'stream)
+ (protocol "tcp")
+ (wait? #f)
+ (user "root"))
+ (inetd-entry
+ (node "127.0.0.1")
+ (name "smtp")
+ (socket-type 'stream)
+ (protocol "tcp")
+ (wait? #f)
+ (user "root")
+ (program (file-append openssh "/bin/ssh"))
+ (arguments
+ '("ssh" "-qT" "-i" "/path/to/ssh_key"
+ "-W" "smtp-server:25" "user@@hostname")))))
+@end example
+
+See below for more details about @code{inetd-configuration}.
+@end deffn
+
+@deftp {Data Type} inetd-configuration
+Data type representing the configuration of @command{inetd}.
+
+@table @asis
+@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
+The @command{inetd} executable to use.
+
+@item @code{entries} (default: @code{'()})
+A list of @command{inetd} service entries. Each entry should be created
+by the @code{inetd-entry} constructor.
+@end table
+@end deftp
+
+@deftp {Data Type} inetd-entry
+Data type representing an entry in the @command{inetd} configuration.
+Each entry corresponds to a socket where @command{inetd} will listen for
+requests.
+
+@table @asis
+@item @code{node} (default: @code{#f})
+Optional string, a comma-separated list of local addresses
+@command{inetd} should use when listening for this service.
+@xref{Configuration file,,, inetutils, GNU Inetutils} for a complete
+description of all options.
+@item @code{name}
+A string, the name must correspond to an entry in @code{/etc/services}.
+@item @code{socket-type}
+One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
+@code{'seqpacket}.
+@item @code{protocol}
+A string, must correspond to an entry in @code{/etc/protocols}.
+@item @code{wait?} (default: @code{#t})
+Whether @command{inetd} should wait for the server to exit before
+listening to new service requests.
+@item @code{user}
+A string containing the user (and, optionally, group) name of the user
+as whom the server should run. The group name can be specified in a
+suffix, separated by a colon or period, i.e. @code{"user"},
+@code{"user:group"} or @code{"user.group"}.
+@item @code{program} (default: @code{"internal"})
+The server program which will serve the requests, or @code{"internal"}
+if @command{inetd} should use a built-in service.
+@item @code{arguments} (default: @code{'()})
+A list strings or file-like objects, which are the server program's
+arguments, starting with the zeroth argument, i.e. the name of the
+program itself. For @command{inetd}'s internal services, this entry
+must be @code{'()} or @code{'("internal")}.
+@end table
+
+@xref{Configuration file,,, inetutils, GNU Inetutils} for a more
+detailed discussion of each configuration field.
+@end deftp
+
@cindex Tor
@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
Return a service to run the @uref{https://torproject.org, Tor} anonymous
@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:
+CUPS configuration (see below). To use the default settings, simply
+write:
@example
-(service cups-service-type (cups-configuration))
+(service cups-service-type)
@end example
@end deffn
@item @code{port} (default: @code{6379})
Port on which to accept connections on, a value of 0 will disable
-listining on a TCP socket.
+listening on a TCP socket.
@item @code{working-directory} (default: @code{"/var/lib/redis"})
Directory in which to store the database and related files.
Defaults to @samp{"pam"}.
@end deftypevr
-@deftypevr {@code{passdb-configuration} parameter} free-form-args args
-A list of key-value args to the passdb driver.
-Defaults to @samp{()}.
+@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
+Space separated list of arguments to the passdb driver.
+Defaults to @samp{""}.
@end deftypevr
@end deftypevr
Defaults to @samp{"passwd"}.
@end deftypevr
-@deftypevr {@code{userdb-configuration} parameter} free-form-args args
-A list of key-value args to the userdb driver.
-Defaults to @samp{()}.
+@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
+Space separated list of arguments to the userdb driver.
+Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
@end deffn
@deftp {Data Type} opensmtpd-configuration
-Data type regresenting the configuration of opensmtpd.
+Data type representing the configuration of opensmtpd.
@table @asis
@item @code{package} (default: @var{opensmtpd})
@subsubheading Exim Service
+@cindex mail transfer agent (MTA)
+@cindex MTA (mail transfer agent)
+@cindex SMTP
+
@deffn {Scheme Variable} exim-service-type
-This is the type of the @uref{https://exim.org, Exim} service, whose value
-should be an @code{exim-configuration} object as in this example:
+This is the type of the @uref{https://exim.org, Exim} mail transfer
+agent (MTA), whose value should be an @code{exim-configuration} object
+as in this example:
@example
(service exim-service-type
(exim-configuration
- (config-file (local-file "./my-exim.conf"))
- (aliases '(("postmaster" "bob")
- ("bob" "bob@@example.com" "bob@@example2.com")))))
+ (config-file (local-file "./my-exim.conf"))))
@end example
@end deffn
+In order to use an @code{exim-service-type} service you must also have a
+@code{mail-aliases-service-type} service present in your
+@code{operating-system} (even if it has no aliases).
+
@deftp {Data Type} exim-configuration
Data type representing the configuration of exim.
after setting the @code{exim_user} and @code{exim_group} configuration
variables.
-@item @code{aliases} (default: @code{'()})
-List of aliases to use when delivering mail on this system. The
-@code{car} of each list is used to match incoming mail, with the
-@code{cdr} of each list designating how to deliver it. There may be many
-delivery methods provided, in which case the mail is delivered to them
-all.
-
@end table
@end deftp
+@subsubheading Mail Aliases Service
+
+@cindex email aliases
+@cindex aliases, for email addresses
+
+@deffn {Scheme Variable} mail-aliases-service-type
+This is the type of the service which provides @code{/etc/aliases},
+specifying how to deliver mail to users on this system.
+
+@example
+(service mail-aliases-service-type
+ '(("postmaster" "bob")
+ ("bob" "bob@@example.com" "bob@@example2.com")))
+@end example
+@end deffn
+
+The configuration for a @code{mail-aliases-service-type} service is an
+association list denoting how to deliver mail that comes to this
+system. Each entry is of the form @code{(alias addresses ...)}, with
+@code{alias} specifying the local alias and @code{addresses} specifying
+where to deliver this user's mail.
+
+The aliases aren't required to exist as users on the local system. In
+the above example, there doesn't need to be a @code{postmaster} entry in
+the @code{operating-system}'s @code{user-accounts} in order to deliver
+the @code{postmaster} mail to @code{bob} (which subsequently would
+deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
+
@node Messaging Services
@subsubsection Messaging Services
blocks} to configure. For this to work, use the default value for
@var{config-file}.
+At startup, @command{nginx} has not yet read its configuration file, so it
+uses a default file to log error messages. If it fails to load its
+configuration file, that is where error messages are logged. After the
+configuration file is loaded, the default error log file changes as per
+configuration. In our case, startup error messages can be found in
+@file{/var/run/nginx/logs/error.log}, and after configuration in
+@file{/var/log/nginx/error.log}. The second location can be changed with the
+@var{log-directory} configuration option.
+
@end deffn
@deffn {Scheme Variable} nginx-service-type
@end deftypevr
@deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client?
-When true, clients are alowed to talk to each other inside the VPN.
+When true, clients are allowed to talk to each other inside the VPN.
Defaults to @samp{#f}.
@deftypevr {@code{openvpn-server-configuration} parameter} string status
The status file. This file shows a small report on current connection.
-It is trunkated and rewritten every minute.
+It is truncated and rewritten every minute.
Defaults to @samp{"/var/run/openvpn/status"}.
@deffn {Scheme Variable} tlp-service-type
The service type for the TLP tool. Its value should be a valid
-TLP configuration (see below). For example:
+TLP configuration (see below). To use the default settings, simply
+write:
@example
-(service tlp-service-type (tlp-configuration))
+(service tlp-service-type)
@end example
@end deffn
@end deftypevr
@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist
-Exclude specified PCI(e) devices adresses from Runtime Power Management.
+Exclude specified PCI(e) device addresses from Runtime Power Management.
Defaults to @samp{disabled}.
@end deftypevr
+
+The @code{(gnu services pm)} module provides an interface to
+thermald, a CPU frequency scaling service which helps prevent overheating.
+
+@defvr {Scheme Variable} thermald-service-type
+This is the service type for
+@uref{https://01.org/linux-thermal-daemon/, thermald}, the Linux
+Thermal Daemon, which is responsible for controlling the thermal state
+of processors and preventing overheating.
+@end defvr
+
+@deftp {Data Type} thermald-configuration
+Data type representing the configuration of @code{thermald-service-type}.
+
+@table @asis
+@item @code{ignore-cpuid-check?} (default: @code{#f})
+Ignore cpuid check for supported CPU models.
+
+@item @code{thermald} (default: @var{thermald})
+Package object of thermald.
+
+@end table
+@end deftp
+
+
@node Miscellaneous Services
@subsubsection Miscellaneous Services
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-database
-Data type representing a dictionary database.
+@deftp {Data Type} dicod-handler
+Data type representing a dictionary handler (module instance).
@table @asis
@item @code{name}
-Name of the database, will be used in DICT commands.
+Name of the handler (module instance).
-@item @code{module}
-Name of the dicod module used by this database
+@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
-Dictonary of English using the @code{gcide} package.
+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
+
@subsubsection Version Control
The @code{(gnu services version-control)} module provides the following services:
@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]
Return a service that runs @command{git daemon}, a simple TCP server to
-expose repositiories over the Git protocol for annoymous access.
+expose repositories over the Git protocol for anonymous access.
The optional @var{config} argument should be a
@code{<git-daemon-configuration>} object, by default it allows read-only
$ export GIT_SSL_CAINFO="$SSL_CERT_FILE"
@end example
+As another example, R requires the @code{CURL_CA_BUNDLE} environment
+variable to point to a certificate bundle, so you would have to run
+something like this:
+
+@example
+$ guix package -i nss-certs
+$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
+@end example
+
+For other applications you may want to look up the required environment
+variable in the relevant documentation.
+
+
@node Name Service Switch
@subsection Name Service Switch
@item @code{grub} (default: @code{grub})
The GRUB package to use.
+
+@item @code{terminal-outputs} (default: @code{'gfxterm})
+The output terminals used for the GRUB boot menu, as a list of symbols.
+These values are accepted: @code{console}, @code{serial},
+@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text},
+@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB
+variable GRUB_TERMINAL_OUTPUT (@pxref{Simple configuration,,, grub,GNU
+GRUB manual}).
+
+@item @code{terminal-inputs} (default: @code{'()})
+The input terminals used for the GRUB boot menu, as a list of symbols.
+The default is the native platform terminal as determined by GRUB at
+run-time. These values are accepted: @code{console}, @code{serial},
+@code{serial_@{0-3@}}, @code{at_keyboard}, and @code{usb_keyboard}.
+This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT
+(@pxref{Simple configuration,,, grub,GNU GRUB manual}).
+
+@item @code{serial-unit} (default: @code{#f})
+The serial unit used by GRUB, as an integer from 0 to 3. The default
+value is chosen by GRUB at run-time; currently GRUB chooses 0, which
+corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
+
+@item @code{serial-speed} (default: @code{#f})
+The speed of the serial interface, as an integer. The default value is
+chosen by GRUB at run-time; currently GRUB chooses 9600@tie{}bps
+(@pxref{Serial terminal,,, grub,GNU GRUB manual}).
@end table
@end deftp
It also adds a GRUB menu entry for the new OS configuration, and moves
entries for older configurations to a submenu---unless
-@option{--no-grub} is passed.
+@option{--no-bootloader} is passed.
@quotation Note
@c The paragraph below refers to the problem discussed at
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
This command also installs GRUB on the device specified in
-@file{my-os-config}, unless the @option{--no-grub} option was passed.
+@file{my-os-config}, unless the @option{--no-bootloader} option was passed.
@item vm
@cindex virtual machine
include a unit as a suffix (@pxref{Block size, size specifications,,
coreutils, GNU Coreutils}).
+@item --root=@var{file}
+@itemx -r @var{file}
+Make @var{file} a symlink to the result, and register it as a garbage
+collector root.
+
@item --on-error=@var{strategy}
Apply @var{strategy} when an error occurs when reading @var{file}.
@var{strategy} may be one of the following:
The file name of the qcow2 image.
@end table
-The default @command{run-vm.sh} script that is returned by an invokation of
+The default @command{run-vm.sh} script that is returned by an invocation of
@command{guix system vm} does not add a @command{-net user} flag by default.
To get network access from within the vm add the @code{(dhcp-client-service)}
to your system definition and start the VM using
@command{`guix system vm config.scm` -net user}. An important caveat of using
@command{-net user} for networking is that @command{ping} will not work, because
it uses the ICMP protocol. You'll have to use a different command to check for
-network connectivity, like for example @command{curl}.
+network connectivity, for example @command{guix download}.
@subsubsection Connecting Through SSH
(extensions
(list (service-extension shepherd-root-service-type guix-shepherd-service)
(service-extension account-service-type guix-accounts)
- (service-extension activation-service-type guix-activation)))))
+ (service-extension activation-service-type guix-activation)))
+ (default-value (guix-configuration))))
@end example
@noindent
-It defines two things:
+It defines three things:
@enumerate
@item
Every service type has at least one service extension. The only
exception is the @dfn{boot service type}, which is the ultimate service.
+
+@item
+Optionally, a default value for instances of this type.
@end enumerate
In this example, @var{guix-service-type} extends three services:
The second argument to the @code{service} form is a value representing
the parameters of this specific service instance.
@xref{guix-configuration-type, @code{guix-configuration}}, for
-information about the @code{guix-configuration} data type.
+information about the @code{guix-configuration} data type. When the
+value is omitted, the default value specified by
+@code{guix-service-type} is used:
+
+@example
+(service guix-service-type)
+@end example
@var{guix-service-type} is quite simple because it extends other
services but is not extensible itself.
services and service types. This interface is provided by the
@code{(gnu services)} module.
-@deffn {Scheme Procedure} service @var{type} @var{value}
+@deffn {Scheme Procedure} service @var{type} [@var{value}]
Return a new service of @var{type}, a @code{<service-type>} object (see
below.) @var{value} can be any object; it represents the parameters of
this particular service instance.
+
+When @var{value} is omitted, the default value specified by @var{type}
+is used; if @var{type} does not specify a default value, an error is
+raised.
+
+For instance, this:
+
+@example
+(service openssh-service-type)
+@end example
+
+@noindent
+is equivalent to this:
+
+@example
+(service openssh-service-type
+ (openssh-configuration))
+@end example
+
+In both cases the result is an instance of @code{openssh-service-type}
+with the default configuration.
@end deffn
@deffn {Scheme Procedure} service? @var{obj}
Return the type of @var{service}---i.e., a @code{<service-type>} object.
@end deffn
-@deffn {Scheme Procedure} service-parameters @var{service}
+@deffn {Scheme Procedure} service-value @var{service}
Return the value associated with @var{service}. It represents its
parameters.
@end deffn
@end defvr
+@node Documentation
+@section Documentation
+
+@cindex documentation, searching for
+@cindex searching for documentation
+@cindex Info, documentation format
+@cindex man pages
+@cindex manual pages
+In most cases packages installed with Guix come with documentation.
+There are two main documentation formats: ``Info'', a browseable
+hypertext format used for GNU software, and ``manual pages'' (or ``man
+pages''), the linear documentation format traditionally found on Unix.
+Info manuals are accessed with the @command{info} command or with Emacs,
+and man pages are accessed using @command{man}.
+
+You can look for documentation of software installed on your system by
+keyword. For example, the following command searches for information
+about ``TLS'' in Info manuals:
+
+@example
+$ info -k TLS
+"(emacs)Network Security" -- STARTTLS
+"(emacs)Network Security" -- TLS
+"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
+"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
+@dots{}
+@end example
+
+@noindent
+The command below searches for the same keyword in man pages:
+
+@example
+$ man -k TLS
+SSL (7) - OpenSSL SSL/TLS library
+certtool (1) - GnuTLS certificate tool
+@dots {}
+@end example
+
+These searches are purely local to your computer so you have the
+guarantee that documentation you find corresponds to what you have
+actually installed, you can access it off-line, and your privacy is
+respected.
+
+Once you have these results, you can view the relevant documentation by
+running, say:
+
+@example
+$ info "(gnutls)Core TLS API"
+@end example
+
+@noindent
+or:
+
+@example
+$ man certtool
+@end example
+
+Info manuals contain sections and indices as well as hyperlinks like
+those found in Web pages. The @command{info} reader (@pxref{Top, Info
+reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
+(@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
+bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
+Introduction}, for an introduction to Info navigation.
+
@node Installing Debugging Files
@section Installing Debugging Files
@smallexample
$ guix lint -c cve
-gnu/packages/base.scm:652:2: glibc-2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
-gnu/packages/gcc.scm:334:2: gcc-4.9.3: probably vulnerable to CVE-2015-5276
-gnu/packages/image.scm:312:2: openjpeg-2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
+gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
+gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
+gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
@dots{}
@end smallexample
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
* Synopses and Descriptions:: Helping users find the right package.
-* Python Modules:: Taming the snake.
+* Python Modules:: A touch of British comedy.
* Perl Modules:: Little pearls.
* Java Packages:: Coffee break.
* Fonts:: Fond of fonts.
HCoop / jackhill / guix / guix.git / blobdiff