Copyright @copyright{} 2022 Justin Veilleux@*
Copyright @copyright{} 2022 Reily Siegel@*
Copyright @copyright{} 2022 Simon Streit@*
+Copyright @copyright{} 2022 (@*
+Copyright @copyright{} 2022 John Kehayias@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
-@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
-(@pxref{Guile Preparations, how to install the GnuTLS bindings for
-Guile,, gnutls-guile, GnuTLS-Guile});
+@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
+Preparations, how to install the GnuTLS bindings for Guile,,
+gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
+@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
+until version 3.7.8 included.};
@item
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
@node Invoking guix-daemon
@section Invoking @command{guix-daemon}
-
+@cindex @command{guix-daemon}
The @command{guix-daemon} program implements all the functionality to
access the store. This includes launching build processes, running the
garbage collector, querying the availability of a build result, etc. It
can do so by running Emacs with the @option{--no-site-file} option
(@pxref{Init File,,, emacs, The GNU Emacs Manual}).
+@quotation Note
+Emacs can now compile packages natively. Under the default
+configuration, this means that Emacs packages will now be
+just-in-time (JIT) compiled as you use them, and the results
+stored in a subdirectory of your @code{user-emacs-directory}.
+
+Furthermore, the build system for Emacs packages transparently
+supports native compilation, but note, that
+@code{emacs-minimal}---the default Emacs for building
+packages---has been configured without native compilation.
+To natively compile your emacs packages ahead of time, use a
+transformation like @option{--with-input=emacs-minimal=emacs}.
+@end quotation
@node Upgrading Guix
@section Upgrading Guix
@cindex package installation
@cindex package removal
@cindex profile
+@cindex @command{guix package}
The @command{guix package} command is the tool that allows users to
install, upgrade, and remove packages, as well as rolling back to
previous configurations. These operations work on a user
@cindex garbage collector
@cindex disk space
+@cindex @command{guix gc}
Packages that are installed, but not used, may be @dfn{garbage-collected}.
The @command{guix gc} command allows users to explicitly run the garbage
collector to reclaim space from the @file{/gnu/store} directory. It is
@itemx --branch=@var{branch}
Download code for the @code{guix} channel from the specified @var{url}, at the
given @var{commit} (a valid Git commit ID represented as a hexadecimal
-string), or @var{branch}.
+string or the name of a tag), or @var{branch}.
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
description file created by @command{guix describe}
(@pxref{Invoking guix describe}).
+Let's assume that you want to travel to those days of November 2020 when
+version 1.2.0 of Guix was released and, once you're there, run the
+@command{guile} of that time:
+
+@example
+guix time-machine --commit=v1.2.0 -- \
+ environment -C --ad-hoc guile -- guile
+@end example
+
+The command above fetches Guix@tie{}1.2.0 and runs its @command{guix
+environment} command to spawn an environment in a container running
+@command{guile} (@command{guix environment} has since been subsumed by
+@command{guix shell}; @pxref{Invoking guix shell}). It's like driving a
+DeLorean@footnote{If you don't know what a DeLorean is, consider
+traveling back to the 1980's.}! The first @command{guix time-machine}
+invocation can be expensive: it may have to download or even build a
+large number of packages; the result is cached though and subsequent
+commands targeting the same commit are almost instantaneous.
+
The general syntax is:
@example
@itemx --branch=@var{branch}
Use the @code{guix} channel from the specified @var{url}, at the
given @var{commit} (a valid Git commit ID represented as a hexadecimal
-string), or @var{branch}.
+string or the name of a tag), or @var{branch}.
@item --channels=@var{file}
@itemx -C @var{file}
@cindex reproducibility
@cindex replicating Guix
+@cindex @command{guix describe}
Often you may want to answer questions like: ``Which revision of Guix am I
using?'' or ``Which channels am I using?'' This is useful information in many
situations: if you want to @emph{replicate} an environment on a different
@cindex @command{guix archive}
@cindex archive
+@cindex exporting files from the store
+@cindex importing files to the store
The @command{guix archive} command allows users to @dfn{export} files
from the store into a single archive, and to later @dfn{import} them on
a machine that runs Guix.
@cindex reproducible build environments
@cindex development environments
@cindex @command{guix environment}
+@cindex @command{guix shell}
@cindex environment, package build environment
The purpose of @command{guix shell} is to make it easy to create one-off
software environments, without changing one's profile. It is typically
guix shell --container --expose=$HOME=/exchange guile -- guile
@end example
+@cindex file system hierarchy standard (FHS)
+@cindex FHS (file system hierarchy standard)
+@item --emulate-fhs
+@itemx -F
+When used with @option{--container}, emulate a
+@uref{https://refspecs.linuxfoundation.org/fhs.shtml, Filesystem
+Hierarchy Standard (FHS)} configuration within the container, providing
+@file{/bin}, @file{/lib}, and other directories and files specified by
+the FHS.
+
+As Guix deviates from the FHS specification, this
+option sets up the container to more closely mimic that of other
+GNU/Linux distributions. This is useful for reproducing other
+development environments, testing, and using programs which expect the
+FHS specification to be followed. With this option, the container will
+include a version of glibc that will read
+@file{/etc/ld.so.cache} within the container for the shared library
+cache (contrary to glibc in regular Guix usage) and set up the
+expected FHS directories: @file{/bin}, @file{/etc}, @file{/lib}, and
+@file{/usr} from the container's profile.
+
@item --rebuild-cache
@cindex caching, of profiles
@cindex caching, in @command{guix shell}
@node Invoking guix environment
@section Invoking @command{guix environment}
+@cindex @command{guix environment}
+
The purpose of @command{guix environment} is to assist in creating
development environments.
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example
+@item --emulate-fhs
+@item -F
+For containers, emulate a Filesystem Hierarchy Standard (FHS)
+configuration within the container, see
+@uref{https://refspecs.linuxfoundation.org/fhs.shtml, the official
+specification}. As Guix deviates from the FHS specification, this
+option sets up the container to more closely mimic that of other
+GNU/Linux distributions. This is useful for reproducing other
+development environments, testing, and using programs which expect the
+FHS specification to be followed. With this option, the container will
+include a version of @code{glibc} which will read
+@code{/etc/ld.so.cache} within the container for the shared library
+cache (contrary to @code{glibc} in regular Guix usage) and set up the
+expected FHS directories: @code{/bin}, @code{/etc}, @code{/lib}, and
+@code{/usr} from the container's profile.
+
@end table
@command{guix environment}
@node Invoking guix pack
@section Invoking @command{guix pack}
+@cindex @command{guix pack}
+
Occasionally you want to pass software to people who are not (yet!)
lucky enough to be using Guix. You'd tell them to run @command{guix
package -i @var{something}}, but that's not possible in this case. This
@node Invoking guix git authenticate
@section Invoking @command{guix git authenticate}
+@cindex @command{guix git authenticate}
+
The @command{guix git authenticate} command authenticates a Git checkout
following the same rule as for channels (@pxref{channel-authentication,
channel authentication}). That is, starting from a given commit, it
include a Python package as only a part of the software, and thus want to
combine the phases of @code{python-build-system} with another build system.
Python bindings are a common usecase.
+@end defvr
+@defvr {Scheme Variable} pyproject-build-system
+This is a variable exported by @code{guix build-system pyproject}. It
+is based on @var{python-build-system}, and adds support for
+@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517}.
+It also supports a variety of build backends and test frameworks.
+
+The API is slightly different from @var{python-build-system}:
+@itemize
+@item
+@code{#:use-setuptools?} and @code{#:test-target} is removed.
+@item
+@code{#:build-backend} is added. It defaults to @code{#false} and will try
+to guess the appropriate backend based on @file{pyproject.toml}.
+@item
+@code{#:test-backend} is added. It defaults to @code{#false} and will guess
+an appropriate test backend based on what is available in package inputs.
+@item
+@code{#:test-flags} is added. The default is @code{#false}, and varies based
+on the detected @code{#:test-backend}.
+@end itemize
+
+It is considered ``experimental'' in that the implementation details are
+not set in stone yet, however users are encouraged to try it for new
+Python projects (even those using @file{setup.py}). The API is subject to
+change, but any breaking changes in the Guix channel will be dealt with.
+
+Eventually this build system will be deprecated and merged back into
+@var{python-build-system}, probably some time in 2024.
@end defvr
@defvr {Scheme Variable} perl-build-system
@node Invoking guix repl
@section Invoking @command{guix repl}
+@cindex @command{guix repl}
@cindex REPL, read-eval-print loop, script
The @command{guix repl} command makes it easier to program Guix in Guile
by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
You can also ask for a specific version:
@example
-guix import gem @@7.0.4
+guix import gem rails@@7.0.4
@end example
@table @code
@node Invoking guix style
@section Invoking @command{guix style}
+@cindex @command{guix style}
+@cindex styling rules
+@cindex lint, code style
+@cindex format, code style
+@cindex format conventions
The @command{guix style} command helps users and packagers alike style
their package definitions and configuration files according to the
latest fashionable trends. It can either reformat whole files, with the
@node Invoking guix copy
@section Invoking @command{guix copy}
+@cindex @command{guix copy}
@cindex copy, of store items, over SSH
@cindex SSH, copy of store items
@cindex sharing store items across machines
@node Invoking guix weather
@section Invoking @command{guix weather}
+@cindex @command{guix weather}
Occasionally you're grumpy because substitutes are lacking and you end
up building packages by yourself (@pxref{Substitutes}). The
@command{guix weather} command reports on substitute availability on the
@node Invoking guix processes
@section Invoking @command{guix processes}
+@cindex @command{guix processes}
The @command{guix processes} command can be useful to developers and system
administrators, especially on multi-user machines and on build farms: it lists
the current sessions (connections to the daemon), as well as information about
install non-core utilities in user profiles (@pxref{Invoking guix
package}).
-@item @code{timezone}
+@item @code{timezone} (default: @code{"Etc/UTC"})
A timezone identifying string---e.g., @code{"Europe/Paris"}.
You can run the @command{tzselect} command to find out which timezone
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
access to special files), @code{no-suid} (ignore setuid and setgid
bits), @code{no-atime} (do not update file access times),
+@code{no-diratime} (likewise for directories only),
@code{strict-atime} (update file access time), @code{lazy-time} (only
update time on the in-memory version of the file inode),
@code{no-exec} (disallow program execution), and @code{shared} (make the
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
+* VNC Services:: VNC daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
* Samba Services:: Samba services.
@end table
@end deftp
+@deftp {Data Type} greetd-wlgreet-session
+Generic configuration record for the wlgreet greetd greeter.
+
+@table @asis
+@item @code{wlgreet} (default: @code{wlgreet})
+The package with the @command{/bin/wlgreet} command.
+
+@item @code{command} (default: @code{(file-append sway "/bin/sway")})
+Command to be started by @command{/bin/wlgreet} on successful login.
+
+@item @code{command-args} (default: @code{'()})
+Command arguments to pass to command.
+
+@item @code{output-mode} (default: @code{"all"})
+Option to use for @code{outputMode} in the TOML configuration file.
+
+@item @code{scale} (default: @code{1})
+Option to use for @code{scale} in the TOML configuration file.
+
+@item @code{background} (default: @code{'(0 0 0 0.9)})
+RGBA list to use as the background colour of the login prompt.
+
+@item @code{headline} (default: @code{'(1 1 1 1)})
+RGBA list to use as the headline colour of the UI popup.
+
+@item @code{prompt} (default: @code{'(1 1 1 1)})
+RGBA list to use as the prompt colour of the UI popup.
+
+@item @code{prompt-error} (default: @code{'(1 1 1 1)})
+RGBA list to use as the error colour of the UI popup.
+
+@item @code{border} (default: @code{'(1 1 1 1)})
+RGBA list to use as the border colour of the UI popup.
+
+@item @code{extra-env} (default: @code{'()})
+Extra environment variables to set on login.
+
+@end table
+@end deftp
+
+@deftp {Data Type} greetd-wlgreet-sway-session
+Sway-specific configuration record for the wlgreet greetd greeter.
+
+@table @asis
+@item @code{wlgreet-session} (default: @code{(greetd-wlgreet-session)})
+A @code{greetd-wlgreet-session} record for generic wlgreet configuration,
+on top of the Sway-specific @code{greetd-wlgreet-sway-session}.
+
+@item @code{sway} (default: @code{sway})
+The package providing the @command{/bin/sway} command.
+
+@item @code{sway-configuration} (default: #f)
+File-like object providing an additional Sway configuration file to be
+prepended to the mandatory part of the configuration.
+
+@end table
+
+Here is an example of a greetd configuration that uses wlgreet and Sway:
+
+@lisp
+ (greetd-configuration
+ ;; We need to give the greeter user these permissions, otherwise
+ ;; Sway will crash on launch.
+ (greeter-supplementary-groups (list "video" "input" "seat"))
+ (terminals
+ (list (greetd-terminal-configuration
+ (terminal-vt "1")
+ (terminal-switch #t)
+ (default-session-command
+ (greetd-wlgreet-sway-session
+ (sway-configuration
+ (local-file "sway-greetd.conf"))))))))
+@end lisp
+@end deftp
+
@node Scheduled Job Execution
@subsection Scheduled Job Execution
@cindex DHCP, networking service
@defvr {Scheme Variable} dhcp-client-service-type
This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
-Protocol (DHCP) client, on all the non-loopback network interfaces. Its value
-is the DHCP client package to use, @code{isc-dhcp} by default.
+Protocol (DHCP) client.
@end defvr
+@deftp {Data Type} dhcp-client-configuration
+Data type representing the configuration of the DHCP client service.
+
+@table @asis
+@item @code{package} (default: @code{isc-dhcp})
+DHCP client package to use.
+
+@item @code{interfaces} (default: @code{'all})
+Either @code{'all} or the list of interface names that the DHCP client
+should listen on---e.g., @code{'("eno1")}.
+
+When set to @code{'all}, the DHCP client listens on all the available
+non-loopback interfaces that can be activated. Otherwise the DHCP
+client listens only on the specified interfaces.
+@end table
+@end deftp
+
@cindex NetworkManager
@defvr {Scheme Variable} network-manager-service-type
@cindex GDM
@cindex GNOME, login manager
+@anchor{gdm}
GDM of course allows users to log in into window managers and desktop
environments other than GNOME; for those using GNOME, GDM is required for
features such as automatic screen locking.
When @code{auto-login?} is true, GDM logs in directly as
@code{default-user}.
+@item @code{auto-suspend?} (default @code{#t})
+When true, GDM will automatically suspend to RAM when nobody is
+physically connected. When a machine is used via remote desktop or SSH,
+this should be set to false to avoid GDM interrupting remote sessions or
+rendering the machine unavailable.
+
@item @code{debug?} (default: @code{#f})
When true, GDM writes debug messages to its log.
@item @code{x-session} (default: @code{(xinitrc)})
Script to run before starting a X session.
+@item @code{xdmcp?} (default: @code{#f})
+When true, enable the X Display Manager Control Protocol (XDMCP). This
+should only be enabled in trusted environments, as the protocol is not
+secure. When enabled, GDM listens for XDMCP queries on the UDP port
+177.
+
@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
File name of the @code{dbus-daemon} executable.
@cindex lightdm, graphical login manager
@cindex display manager, lightdm
+@anchor{lightdm}
@defvr {Scheme Variable} lightdm-service-type
This is the type of the service to run the
@url{https://github.com/canonical/lightdm,LightDM display manager}. Its
The name of the cursor theme to use.
@item @code{cursor-theme-size} (default: @code{16}) (type: number)
-The size to use for the the cursor theme.
+The size to use for the cursor theme.
@item @code{allow-debugging?} (type: maybe-boolean)
Set to #t to enable debug log level.
@cindex Xorg, configuration
@deftp {Data Type} xorg-configuration
-This data type represents the configuration of the Xorg graphical display
-server. Note that there is no Xorg service; instead, the X server is started
-by a ``display manager'' such as GDM, SDDM, and SLiM@. Thus, the configuration
-of these display managers aggregates an @code{xorg-configuration} record.
+This data type represents the configuration of the Xorg graphical
+display server. Note that there is no Xorg service; instead, the X
+server is started by a ``display manager'' such as GDM, SDDM, LightDM or
+SLiM@. Thus, the configuration of these display managers aggregates an
+@code{xorg-configuration} record.
@table @asis
@item @code{modules} (default: @code{%default-xorg-modules})
Ignore the lid state, this can be useful if it's incorrect on a device.
@item @code{use-percentage-for-policy?} (default: @code{#t})
-Whether a to use a policy based on battery percentage rather than on
+Whether to use a policy based on battery percentage rather than on
estimated time left. A policy based on battery percentage is usually
more reliable.
Whether peer discovery should be enabled. Peer discovery is used to
discover other OpenDHT nodes on the local network, which can be useful
to maintain communication between devices on such network even when the
-connection to the the Internet has been lost. When left unspecified,
+connection to the Internet has been lost. When left unspecified,
the value from the account archive prevails.
@item @code{bootstrap-hostnames} (type: maybe-string-list)
@c %end of fragment
+@node VNC Services
+@subsection VNC Services
+@cindex VNC (virtual network computing)
+@cindex XDMCP (x display manager control protocol)
+
+The @code{(gnu services vnc)} module provides services related to
+@dfn{Virtual Network Computing} (VNC), which makes it possible to
+locally use graphical Xorg applications running on a remote machine.
+Combined with a graphical manager that supports the @dfn{X Display
+Manager Control Protocol}, such as GDM (@pxref{gdm}) or LightDM
+(@pxref{lightdm}), it is possible to remote an entire desktop for a
+multi-user environment.
+
+@subsubheading Xvnc
+
+Xvnc is a VNC server that spawns its own X window server; which means it
+can run on headless servers. The Xvnc implementations provided by the
+@code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient.
+
+@defvar {Scheme Variable} xvnc-service-type
+
+The @code{xvnc-server-type} service can be configured via the
+@code{xvnc-configuration} record, documented below. A second virtual
+display could be made available on a remote machine via the
+following configuration:
+@end defvar
+
+@lisp
+(service xvnc-service-type (xvnc-configuration (display-number 10)
+@end lisp
+
+As a demonstration, the @command{xclock} command could then be started
+on the remote machine on display number 10, and it could be displayed
+locally via the @command{vncviewer} command:
+@example
+# Start xclock on the remote machine.
+ssh -L5910:localhost:5910 -- guix shell xclock -- env DISPLAY=:10 xclock
+# Access it via VNC.
+guix shell tigervnc-client -- vncviewer localhost:5910
+@end example
+
+The following configuration combines XDMCP and Inetd to allow multiple
+users to concurrently use the remote system, login in graphically via
+the GDM display manager:
+
+@lisp
+(operating-system
+ [...]
+ (services (cons*
+ [...]
+ (service xvnc-service-type (xvnc-configuration
+ (display-number 5)
+ (localhost? #f)
+ (xdmcp? #t)
+ (inetd? #t)))
+ (modify-services %desktop-services
+ (gdm-service-type config => (gdm-configuration
+ (inherit config)
+ (auto-suspend? #f)
+ (xdmcp? #t)))))))
+@end lisp
+
+A remote user could then connect to it by using the @command{vncviewer}
+command or a compatible VNC client and start a desktop session of their
+choosing:
+@example
+vncviewer remote-host:5905
+@end example
+
+@quotation Warning
+Unless your machine is in a controlled environment, for security
+reasons, the @code{localhost?} configuration of the
+@code{xvnc-configuration} record should be left to its default @code{#t}
+value and exposed via a secure means such as an SSH port forward. The
+XDMCP port, UDP 177 should also be blocked from the outside by a
+firewall, as it is not a secure protocol and can expose login
+credentials in clear.
+@end quotation
+
+@c Use (configuration->documentation 'xvnc-configuration) to regenerate
+@c the documentation.
+@c %start of fragment
+@deftp {Data Type} xvnc-configuration
+Available @code{xvnc-configuration} fields are:
+
+@table @asis
+@item @code{xvnc} (default: @code{tigervnc-server}) (type: file-like)
+The package that provides the Xvnc binary.
+
+@item @code{display-number} (default: @code{0}) (type: number)
+The display number used by Xvnc. You should set this to a number not
+already used a Xorg server.
+
+@item @code{geometry} (default: @code{"1024x768"}) (type: string)
+The size of the desktop to be created.
+
+@item @code{depth} (default: @code{24}) (type: color-depth)
+The pixel depth in bits of the desktop to be created. Accepted values
+are 16, 24 or 32.
+
+@item @code{port} (type: maybe-port)
+The port on which to listen for connections from viewers. When left
+unspecified, it defaults to 5900 plus the display number.
+
+@item @code{ipv4?} (default: @code{#t}) (type: boolean)
+Use IPv4 for incoming and outgoing connections.
+
+@item @code{ipv6?} (default: @code{#t}) (type: boolean)
+Use IPv6 for incoming and outgoing connections.
+
+@item @code{password-file} (type: maybe-string)
+The password file to use, if any. Refer to vncpasswd(1) to learn how to
+generate such a file.
+
+@item @code{xdmcp?} (default: @code{#f}) (type: boolean)
+Query the XDMCP server for a session. This enables users to log in a
+desktop session from the login manager screen. For a multiple users
+scenario, you'll want to enable the @code{inetd?} option as well, so
+that each connection to the VNC server is handled separately rather than
+shared.
+
+@item @code{inetd?} (default: @code{#f}) (type: boolean)
+Use an Inetd-style service, which runs the Xvnc server on demand.
+
+@item @code{frame-rate} (default: @code{60}) (type: number)
+The maximum number of updates per second sent to each client.
+
+@item @code{security-types} (default: @code{("None")}) (type: security-types)
+The allowed security schemes to use for incoming connections. The
+default is "None", which is safe given that Xvnc is configured to
+authenticate the user via the display manager, and only for local
+connections. Accepted values are any of the following: ("None"
+"VncAuth" "Plain" "TLSNone" "TLSVnc" "TLSPlain" "X509None" "X509Vnc")
+
+@item @code{localhost?} (default: @code{#t}) (type: boolean)
+Only allow connections from the same machine. It is set to #true by
+default for security, which means SSH or another secure means should be
+used to expose the remote port.
+
+@item @code{log-level} (default: @code{30}) (type: log-level)
+The log level, a number between 0 and 100, 100 meaning most verbose
+output. The log messages are output to syslog.
+
+@item @code{extra-options} (default: @code{()}) (type: strings)
+This can be used to provide extra Xvnc options not exposed via this
+<xvnc-configuration> record.
+
+@end table
+
+@end deftp
+@c %end of fragment
@node VPN Services
@subsection VPN Services
The authorized peers on this interface. This is a list of
@var{wireguard-peer} records.
+@item @code{pre-up} (default: @code{'()})
+The script commands to be run before setting up the interface.
+
+@item @code{post-up} (default: @code{'()})
+The script commands to be run after setting up the interface.
+
+@item @code{pre-down} (default: @code{'()})
+The script commands to be run before tearing down the interface.
+
+@item @code{post-down} (default: @code{'()})
+The script commands to be run after tearing down the interface.
+
+@item @code{table} (default: @code{"auto"})
+The routing table to which routes are added, as a string. There are two
+special values: @code{"off"} that disables the creation of routes
+altogether, and @code{"auto"} (the default) that adds routes to the
+default table and enables special handling of default routes.
+
@end table
@end deftp
@table @asis
@item @code{package} (default: @var{gitolite})
-Gitolite package to use.
+Gitolite package to use. There are optional Gitolite dependencies that
+are not included in the default package, such as Redis and git-annex.
+These features can be made available by using the @code{make-gitolite}
+procedure in the @code{(gnu packages version-control}) module to produce
+a variant of Gitolite with the desired additional dependencies.
+
+The following code returns a package in which the Redis and git-annex
+programs can be invoked by Gitolite's scripts:
+
+@example
+(use-modules (gnu packages databases)
+ (gnu packages haskell-apps)
+ (gnu packages version-control))
+(make-gitolite (list redis git-annex))
+@end example
@item @code{user} (default: @var{git})
User to use for Gitolite. This will be user that you use when accessing
@item @code{max-parallel-builds} (default: @code{1})
The number of builds to perform in parallel.
+@item @code{max-allocated-builds} (default: @code{#f})
+The maximum number of builds this agent can be allocated.
+
@item @code{max-1min-load-average} (default: @code{#f})
Load average value to look at when considering starting new builds, if
the 1 minute load average exceeds this value, the agent will wait before
@end lisp
@node Invoking guix system
-@section Invoking @code{guix system}
+@section Invoking @command{guix system}
+@cindex @command{guix system}
Once you have written an operating system declaration as seen in the
previous section, it can be @dfn{instantiated} using the @command{guix
system} command. The synopsis is:
@end table
@node Invoking guix deploy
-@section Invoking @code{guix deploy}
+@section Invoking @command{guix deploy}
+@cindex @command{guix deploy}
We've already seen @code{operating-system} declarations used to manage a
machine's configuration locally. Suppose you need to configure multiple
machines, though---perhaps you're managing a service on the web that's
@menu
* Essential Home Services:: Environment variables, packages, on-* scripts.
-* Shells: Shells Home Services. POSIX shells, Bash, Zsh.
-* Mcron: Mcron Home Service. Scheduled User's Job Execution.
-* Shepherd: Shepherd Home Service. Managing User's Daemons.
-* SSH: Secure Shell. Setting up the secure shell client.
-* Desktop: Desktop Home Services. Services for graphical environments.
-* Guix: Guix Home Services. Services for Guix.
+* Shells: Shells Home Services. POSIX shells, Bash, Zsh.
+* Mcron: Mcron Home Service. Scheduled User's Job Execution.
+* Power Management: Power Management Home Services. Services for battery power.
+* Shepherd: Shepherd Home Service. Managing User's Daemons.
+* SSH: Secure Shell. Setting up the secure shell client.
+* Desktop: Desktop Home Services. Services for graphical environments.
+* Guix: Guix Home Services. Services for Guix.
@end menu
@c In addition to that Home Services can provide
@end table
@end deftp
+@node Power Management Home Services
+@subsection Power Management Home Services
+
+@cindex power management
+The @code{(gnu home services pm)} module provides home services
+pertaining to battery power.
+
+@defvr {Scheme Variable} home-batsignal-service-type
+Service for @code{batsignal}, a program that monitors battery levels
+and warns the user through desktop notifications when their battery
+is getting low. You can also configure a command to be run when the
+battery level passes a point deemed ``dangerous''. This service is
+configured with the @code{home-batsignal-configuration} record.
+@end defvr
+
+@deftp {Data Type} home-batsignal-configuration
+Data type representing the configuration for batsignal.
+
+@table @asis
+@item @code{warning-level} (default: @code{15})
+The battery level to send a warning message at.
+
+@item @code{warning-message} (default: @code{#f})
+The message to send as a notification when the battery level reaches
+the @code{warning-level}. Setting to @code{#f} uses the default
+message.
+
+@item @code{critical-level} (default: @code{5})
+The battery level to send a critical message at.
+
+@item @code{critical-message} (default: @code{#f})
+The message to send as a notification when the battery level reaches
+the @code{critical-level}. Setting to @code{#f} uses the default
+message.
+
+@item @code{danger-level} (default: @code{2})
+The battery level to run the @code{danger-command} at.
+
+@item @code{danger-command} (default: @code{#f})
+The command to run when the battery level reaches the @code{danger-level}.
+Setting to @code{#f} disables running the command entirely.
+
+@item @code{full-level} (default: @code{#f})
+The battery level to send a full message at. Setting to @code{#f}
+disables sending the full message entirely.
+
+@item @code{full-message} (default: @code{#f})
+The message to send as a notification when the battery level reaches
+the @code{full-level}. Setting to @code{#f} uses the default message.
+
+@item @code{batteries} (default: @code{'()})
+The batteries to monitor. Setting to @code{'()} tries to find batteries
+automatically.
+
+@item @code{poll-delay} (default: @code{60})
+The time in seconds to wait before checking the batteries again.
+
+@item @code{icon} (default: @code{#f})
+A file-like object to use as the icon for battery notifications. Setting
+to @code{#f} disables notification icons entirely.
+
+@item @code{notifications?} (default: @code{#t})
+Whether to send any notifications.
+
+@item @code{notifications-expire?} (default: @code{#f})
+Whether notifications sent expire after a time.
+
+@item @code{notification-command} (default: @code{#f})
+Command to use to send messages. Setting to @code{#f} sends a notification
+through @code{libnotify}.
+
+@item @code{ignore-missing?} (default: @code{#f})
+Whether to ignore missing battery errors.
+@end table
+@end deftp
+
@node Shepherd Home Service
@subsection Managing User Daemons
@end deftp
+@defvr {Scheme Variable} home-dbus-service-type
+This is the service type for running a session-specific D-Bus, for
+unprivileged applications that require D-Bus to be running.
+@end defvr
+
+@deftp {Data Type} home-dbus-configuration
+The configuration record for @code{home-dbus-service-type}.
+
+@table @asis
+@item @code{dbus} (default: @code{dbus})
+The package providing the @code{/bin/dbus-daemon} command.
+@end table
+@end deftp
+
@node Guix Home Services
@subsection Guix Home Services
@end defvr
@node Invoking guix home
-@section Invoking @code{guix home}
+@section Invoking @command{guix home}
+
+@cindex @command{guix home}
Once you have written a home environment declaration (@pxref{Declaring
the Home Environment,,,,}, it can be @dfn{instantiated} using the
HCoop / jackhill / guix / guix.git / blobdiff