Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
-Copyright @copyright{} 2017, 2018, 2019 Marius Bakke@*
-Copyright @copyright{} 2017, 2019 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
+Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
+Copyright @copyright{} 2017, 2019, 2020 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2020 Leo Prikler@*
Copyright @copyright{} 2019, 2020 Simon Tournier@*
Copyright @copyright{} 2020 Wiktor Żelazny@*
+Copyright @copyright{} 2020 Damien Cassou@*
+Copyright @copyright{} 2020 Jakub Kądziołka@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
* PAM Mount Service:: Service to mount volumes when logging in.
+* Linux Services:: Services tied to the Linux kernel.
* Miscellaneous Services:: Other services.
Defining Services
@itemize
@item
-@c Note: We need at least 0.10.2 for 'channel-send-eof'.
+@c Note: We need at least 0.12.0 for 'userauth-gssapi!'.
Support for build offloading (@pxref{Daemon Offload Setup}) and
@command{guix copy} (@pxref{Invoking guix copy}) depends on
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
-version 0.10.2 or later.
+version 0.12.0 or later.
@item
When @url{https://www.nongnu.org/lzip/lzlib.html, lzlib} is available, lzlib
Note that @command{sudo guix} runs your user's @command{guix} command and
@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To
explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
+
+The difference matters here, because @command{guix pull} updates
+the @command{guix} command and package definitions only for the user it is ran
+as. This means that if you choose to use @command{guix system reconfigure} in
+root's login shell, you'll need to @command{guix pull} separately.
@end quotation
Join us on @code{#guix} on the Freenode IRC network or on
@end example
@noindent
-This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are usable and
-will be downloaded, when possible, for future builds.
+The text changed from ``The following derivations would be built'' to
+``112.3 MB would be downloaded''. This indicates that substitutes from
+@code{@value{SUBSTITUTE-SERVER}} are usable and will be downloaded, when
+possible, for future builds.
@cindex substitutes, how to disable
The substitute mechanism can be disabled globally by running
(channel
(name 'my-personal-packages)
(url "https://example.org/personal-packages.git")
- (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
+ (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
The @command{guix describe --format=channels} command can even generate this
instead. See also @code{--user}.
@item --expose=@var{source}[=@var{target}]
-For containers, expose the file system @var{source} from the host system
-as the read-only file system @var{target} within the container. If
+@itemx --share=@var{source}[=@var{target}]
+For containers, @code{--expose} (resp. @code{--share}) exposes the file
+system @var{source} from the host system as the read-only
+(resp. writable) file system @var{target} within the container. If
@var{target} is not specified, @var{source} is used as the target mount
point in the container.
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example
-@item --share=@var{source}[=@var{target}]
-For containers, share the file system @var{source} from the host system
-as the writable file system @var{target} within the container. If
-@var{target} is not specified, @var{source} is used as the target mount
-point in the container.
-
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible for both reading and writing via the
-@file{/exchange} directory:
-
-@example
-guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
-@end example
@end table
@command{guix environment}
the following command:
@example
-guix pack -f docker guile emacs geiser
+guix pack -f docker -S /bin=bin guile guile-readline
@end example
@noindent
The result is a tarball that can be passed to the @command{docker load}
-command. See the
+command, followed by @code{docker run}:
+
+@example
+docker load < @var{file}
+docker run -ti guile-guile-readline /bin/guile
+@end example
+
+@noindent
+where @var{file} is the image returned by @var{guix pack}, and
+@code{guile-guile-readline} is its ``image tag''. See the
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
documentation} for more information.
if they are defined by the crate.
@end defvr
+
+@defvr {Scheme Variable} copy-build-system
+@cindex (copy build system)
+This variable is exported by @code{(guix build-system copy)}. It
+supports builds of simple packages that don't require much compiling,
+mostly just moving files around.
+
+It adds much of the @code{gnu-build-system} packages to the set of
+inputs. Because of this, the @code{copy-build-system} does not require
+all the boilerplate code often needed for the
+@code{trivial-build-system}.
+
+To further simplify the file installation process, an
+@code{#:install-plan} argument is exposed to let the packager specify
+which files go where. The install plan is a list of @code{(@var{source}
+@var{target} [@var{filters}])}. @var{filters} are optional.
+
+@itemize
+@item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
+@itemize
+@item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
+@item Otherwise install @var{source} as @var{target}.
+@end itemize
+
+@item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
+the trailing slash of @var{target} is implied with the same meaning
+as above.
+@itemize
+@item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
+@item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
+@code{#:exclude-regexp}, only select files are installed depending on
+the filters. Each filters is specified by a list of strings.
+@itemize
+@item With @code{#:include}, install all the files which the path suffix matches
+at least one of the elements in the given list.
+@item With @code{#:include-regexp}, install all the files which the
+subpaths match at least one of the regular expressions in the given
+list.
+@item The @code{#:exclude} and @code{#:exclude-regexp} filters
+are the complement of their inclusion counterpart. Without @code{#:include} flags,
+install all files but those matching the exclusion filters.
+If both inclusions and exclusions are specified, the exclusions are done
+on top of the inclusions.
+@end itemize
+@end itemize
+In all cases, the paths relative to @var{source} are preserved within
+@var{target}.
+@end itemize
+
+Examples:
+
+@itemize
+@item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
+@item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
+@item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
+e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
+@item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
+@file{share/my-app/sub/file}.
+@item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
+@file{share/my-app/file}.
+@end itemize
+@end defvr
+
+
@cindex Clojure (programming language)
@cindex simple Clojure build system
@defvr {Scheme Variable} clojure-build-system
This variable is exported by @code{(guix build-system qt)}. It
is intended for use with applications using Qt or KDE.
-This build system adds the phase @code{qt-wrap} to the ones defined by
-@code{cmake-build-system}, after the @code{install} phase.
+This build system adds the following two phases to the ones defined by
+@code{cmake-build-system}:
-This phase searches for Qt5 plugin paths, QML paths and some XDG in the inputs
+@table @code
+@item check-setup
+The phase @code{check-setup} prepares the environment for running
+the checks as commonly used by Qt test programs.
+For now this only sets some environment variables:
+@code{QT_QPA_PLATFORM=offscreen},
+@code{DBUS_FATAL_WARNINGS=0} and
+@code{CTEST_OUTPUT_ON_FAILURE=1}.
+
+This phase is added before the @code{check} phase.
+It's a separate phase to ease adjusting if necessary.
+
+@item qt-wrap
+The phase @code{qt-wrap}
+searches for Qt5 plugin paths, QML paths and some XDG in the inputs
and output. In case some path is found, all programs in the output's
@file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
are wrapped in scripts defining the necessary environment variables.
This is useful when an output is known not to contain any Qt binaries, and
where wrapping would gratuitously add a dependency of that output on Qt, KDE,
or such.
+
+This phase is added after the @code{install} phase.
+@end table
@end defvr
@defvr {Scheme Variable} r-build-system
@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:
+These URIs allow you to connect to a remote daemon over SSH. This
+feature requires Guile-SSH (@pxref{Requirements}) and a working
+@code{guile} binary in @code{PATH} on the destination machine. It
+supports public key and GSSAPI authentication. A typical URL might look
+like this:
@example
ssh://charlie@@guix.example.org:22
@include package-hello.scm
@end lisp
+@item --manifest=@var{manifest}
+@itemx -m @var{manifest}
+Build all packages listed in the given @var{manifest}
+(@pxref{profile-manifest, @option{--manifest}}).
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package or derivation @var{expr} evaluates to.
* Game Services:: Game servers.
* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
+* Linux Services:: Services tied to the Linux kernel.
* Miscellaneous Services:: Other services.
@end menu
Command to run when rebooting.
@item @code{theme} (default "maldives")
-Theme to use. Default themes provided by SDDM are "elarun" or "maldives".
+Theme to use. Default themes provided by SDDM are "elarun", "maldives" or "maya".
@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
Directory to look for themes.
@cindex X11 login
@defvr {Scheme Variable} sddm-service-type
This is the type of the service to run the
-@uref{https://github.com/sddm/sddm,SSDM display manager}. Its value
+@uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
must be a @code{sddm-configuration} record (see below).
Here's an example use:
means that all users are allowed.
@end deffn
+@cindex scanner access
+@deffn {Scheme Procedure} sane-service-type
+This service provides access to scanners @i{via}
+@uref{http://www.sane-project.org, SANE} by installing the necessary udev
+rules.
+@end deffn
+
@defvr {Scheme Variable} %standard-geoclue-applications
The standard list of well-known GeoClue application configurations,
granting authority to the GNOME date-and-time utility to ask for the
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string server
-Space separated list of arguments to the userdb driver.
+Username to login to the mail server with.
Defaults to @samp{unset}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string username
-Space separated list of arguments to the userdb driver.
+Username to login to the mail server with.
Defaults to @samp{unset}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
-Space separated list of arguments to the userdb driver.
+Port number to connect to.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
-PEM-formatted key file to use for the TLS negotiation
+PEM-formatted key file to use for the TLS negotiation.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
-PEM-formatted certificate file to use for the TLS negotiation
+PEM-formatted certificate file to use for the TLS negotiation.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
-CA certificates to use
+CA certificates to use.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
-Extra retriever parameters
+Extra retriever parameters.
Defaults to @samp{()}.
If true, getmail will record a log of its actions using the system
logger.
-Defaults to @samp{#t}.
+Defaults to @samp{#f}.
@end deftypevr
the reason for not retrieving them, as well as starting and ending
information lines.
-Defaults to @samp{#t}.
+Defaults to @samp{#f}.
@end deftypevr
@end deftypevr
+@deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
Verbosity level.
@end deftypevr
+@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
+Authenticate with server using username/password. The option is a file
+containing username/password on 2 lines. Do not use a file-like object as it
+would be added to the store and readable by any user.
+
+Defaults to @samp{'disabled}.
+@end deftypevr
+
@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
Whether to check the server certificate has server usage extension.
@end deftypevr
+@deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
Verbosity level.
@end table
@end deftp
+@node Linux Services
+@subsubheading Linux Services
+
+@cindex oom
+@cindex out of memory killer
+@cindex earlyoom
+@cindex early out of memory daemon
+@subsection Early OOM Service
+
+@uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
+Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user
+space and provides a more responsive and configurable alternative to the
+in-kernel OOM killer. It is useful to prevent the system from becoming
+unresponsive when it runs out of memory.
+
+@deffn {Scheme Variable} earlyoom-service-type
+The service type for running @command{earlyoom}, the Early OOM daemon.
+Its value must be a @code{earlyoom-configuration} object, described
+below. The service can be instantiated in its default configuration
+with:
+
+@lisp
+(service earlyoom-service-type)
+@end lisp
+@end deffn
+
+@deftp {Data Type} earlyoom-configuration
+This is the configuration record for the @code{earlyoom-service-type}.
+
+@table @asis
+@item @code{earlyoom} (default: @var{earlyoom})
+The Earlyoom package to use.
+
+@item @code{minimum-available-memory} (default: @code{10})
+The threshold for the minimum @emph{available} memory, in percentages.
+
+@item @code{minimum-free-swap} (default: @code{10})
+The threshold for the minimum free swap memory, in percentages.
+
+@item @code{prefer-regexp} (default: @code{#f})
+A regular expression (as a string) to match the names of the processes
+that should be preferably killed.
+
+@item @code{avoid-regexp} (default: @code{#f})
+A regular expression (as a string) to match the names of the processes
+that should @emph{not} be killed.
+
+@item @code{memory-report-interval} (default: @code{0})
+The interval in seconds at which a memory report is printed. It is
+disabled by default.
+
+@item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
+A boolean indicating whether the positive adjustments set in
+@file{/proc/*/oom_score_adj}.
+
+@item @code{show-debug-messages?} (default: @code{#f})
+A boolean indicating whether debug messages should be printed. The logs
+are saved at @file{/var/log/earlyoom.log}.
+
+@item @code{send-notification-command} (default: @code{#f})
+This can be used to provide a custom command used for sending
+notifications.
+@end table
+@end deftp
+
@node Miscellaneous Services
@subsection Miscellaneous Services
@end table
@end deftp
+@cindex HDPI
+@cindex HiDPI
+@cindex resolution
@c FIXME: Write documentation once it's stable.
-For now only GRUB has theme support. GRUB themes are created using
-the @code{grub-theme} form, which is not documented yet.
+For now only GRUB has theme support. GRUB themes are created using
+the @code{grub-theme} form, which is not fully documented yet.
+
+@deftp {Data Type} grub-theme
+Data type representing the configuration of the GRUB theme.
+
+@table @asis
+@item @code{gfxmode} (default: @code{'("auto")})
+The GRUB @code{gfxmode} to set (a list of screen resolution strings, see
+@pxref{gfxmode,,, grub, GNU GRUB manual}).
+@end table
+@end deftp
@defvr {Scheme Variable} %default-theme
This is the default GRUB theme used by the operating system if no
logos.
@end defvr
+For example, to override the default resolution, you may use something
+like
+
+@lisp
+(bootloader
+ (grub-configuration
+ ;; @dots{}
+ (theme (grub-theme
+ (inherit %default-theme)
+ (gfxmode '("1024x786x32" "auto"))))))
+@end lisp
@node Invoking guix system
@section Invoking @code{guix system}
HCoop / jackhill / guix / guix.git / blobdiff