aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/emacs.texi10
-rw-r--r--doc/guix.texi657
-rw-r--r--doc/images/service-graph.dot35
3 files changed, 579 insertions, 123 deletions
diff --git a/doc/emacs.texi b/doc/emacs.texi
index b6f2701bc4..ab69515972 100644
--- a/doc/emacs.texi
+++ b/doc/emacs.texi
@@ -667,6 +667,16 @@ this command---for example, with @kbd{C-M-x} (@pxref{To eval or not to
eval,,, geiser, Geiser User Manual})
(@code{guix-devel-build-package-definition}).
+@item C-c . s
+Build a source derivation of the package defined by the current variable
+definition. This command has the same meaning as @code{guix build -S}
+shell command (@pxref{Invoking guix build})
+(@code{guix-devel-build-package-source}).
+
+@item C-c . l
+Lint (check) a package defined by the current variable definition
+(@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}).
+
@end table
Unluckily, there is a limitation related to long-running REPL commands.
diff --git a/doc/guix.texi b/doc/guix.texi
index 79877f156b..709ec0ff70 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -182,6 +182,13 @@ Services
* Web Services:: Web servers.
* Various Services:: Other services.
+Defining Services
+
+* Service Composition:: The model for composing services.
+* Service Types and Services:: Types and services.
+* Service Reference:: API reference.
+* dmd Services:: A particular type of service.
+
Packaging Guidelines
* Software Freedom:: What may go into the distribution.
@@ -3367,7 +3374,8 @@ The other arguments are as for @code{derivation} (@pxref{Derivations}).
@end deffn
@cindex file-like objects
-The @code{local-file} and @code{plain-file} procedures below return
+The @code{local-file}, @code{plain-file}, @code{computed-file},
+@code{program-file}, and @code{scheme-file} procedures below return
@dfn{file-like objects}. That is, when unquoted in a G-expression,
these objects lead to a file in the store. Consider this G-expression:
@@ -3405,6 +3413,16 @@ Return an object representing a text file called @var{name} with the given
This is the declarative counterpart of @code{text-file}.
@end deffn
+@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
+ [#:modules '()] [#:options '(#:local-build? #t)]
+Return an object representing the store item @var{name}, a file or
+directory computed by @var{gexp}. @var{modules} specifies the set of
+modules visible in the execution context of @var{gexp}. @var{options}
+is a list of additional arguments to pass to @code{gexp->derivation}.
+
+This is the declarative counterpart of @code{gexp->derivation}.
+@end deffn
+
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
Return an executable script @var{name} that runs @var{exp} using
@var{guile} with @var{modules} in its search path.
@@ -3432,6 +3450,15 @@ executable file @file{/gnu/store/@dots{}-list-files} along these lines:
@end example
@end deffn
+@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
+ [#:modules '()] [#:guile #f]
+Return an object representing the executable store item @var{name} that
+runs @var{gexp}. @var{guile} is the Guile package used to execute that
+script, and @var{modules} is the list of modules visible to that script.
+
+This is the declarative counterpart of @code{gexp->script}.
+@end deffn
+
@deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
Return a derivation that builds a file @var{name} containing @var{exp}.
@@ -3439,6 +3466,13 @@ The resulting file holds references to all the dependencies of @var{exp}
or a subset thereof.
@end deffn
+@deffn {Scheme Procedure} scheme-file @var{name} @var{exp}
+Return an object representing the Scheme file @var{name} that contains
+@var{exp}.
+
+This is the declarative counterpart of @code{gexp->file}.
+@end deffn
+
@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
Return as a monadic value a derivation that builds a text file
containing all of @var{text}. @var{text} may list, in addition to
@@ -3465,6 +3499,19 @@ will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
preventing them from being garbage-collected during its lifetime.
@end deffn
+@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
+Return an object representing store file @var{name} containing
+@var{text}. @var{text} is a sequence of strings and file-like objects,
+as in:
+
+@example
+(mixed-text-file "profile"
+ "export PATH=" coreutils "/bin:" grep "/bin")
+@end example
+
+This is the declarative counterpart of @code{text-file*}.
+@end deffn
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
@@ -4560,11 +4607,12 @@ and Emacs are available:
guix environment guile emacs
@end example
-Sometimes an interactive shell session is not desired. The
-@code{--exec} option can be used to specify the command to run instead.
+Sometimes an interactive shell session is not desired. An arbitrary
+command may be invoked by placing the @code{--} token to separate the
+command from the rest of the arguments:
@example
-guix environment guile --exec=make
+guix environment guile -- make -j4
@end example
In other situations, it is more convenient to specify the list of
@@ -4573,7 +4621,7 @@ runs @command{python} from an environment containing Python@tie{}2.7 and
NumPy:
@example
-guix environment --ad-hoc python2-numpy python-2.7 -E python
+guix environment --ad-hoc python2-numpy python-2.7 -- python
@end example
The available options are summarized below.
@@ -4604,11 +4652,6 @@ As an example, @var{file} might contain a definition like this
@verbatiminclude environment-gdb.scm
@end example
-
-@item --exec=@var{command}
-@item -E @var{command}
-Execute @var{command} in the new environment.
-
@item --ad-hoc
Include all specified packages in the resulting environment, as if an
@i{ad hoc} package were defined with them as inputs. This option is
@@ -4618,7 +4661,7 @@ package expression to contain the desired inputs.
For instance, the command:
@example
-guix environment --ad-hoc guile guile-sdl -E guile
+guix environment --ad-hoc guile guile-sdl -- guile
@end example
runs @command{guile} in an environment where Guile and Guile-SDL are
@@ -5743,38 +5786,55 @@ this:
@end example
@end defvr
-@deffn {Monadic Procedure} host-name-service @var{name}
+@deffn {Scheme Procedure} host-name-service @var{name}
Return a service that sets the host name to @var{name}.
@end deffn
-@deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
- [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
- [#:allow-empty-passwords? #f]
-Return a service to run mingetty on @var{tty}.
+@deffn {Scheme Procedure} mingetty-service @var{config}
+Return a service to run mingetty according to @var{config}, a
+@code{<mingetty-configuration>} object, which specifies the tty to run, among
+other things.
+@end deffn
-When @var{allow-empty-passwords?} is true, allow empty log-in password. When
-@var{auto-login} is true, it must be a user name under which to log-in
-automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
-@var{auto-login}, in which case the user will have to press a key before the
-login shell is launched.
+@deftp {Data Type} mingetty-configuration
+This is the data type representing the configuration of Mingetty, which
+implements console log-in.
-When true, @var{login-program} is a gexp or a monadic gexp denoting the name
-of the log-in program (the default is the @code{login} program from the Shadow
-tool suite.)
+@table @asis
-@var{motd} is a monadic value containing a text file to use as
-the ``message of the day''.
-@end deffn
+@item @code{tty}
+The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
+
+@item @code{motd}
+A file-like object containing the ``message of the day''.
+
+@item @code{auto-login} (default: @code{#f})
+When true, this field must be a string denoting the user name under
+which the the system automatically logs in. When it is @code{#f}, a
+user name and password must be entered to log in.
+
+@item @code{login-program} (default: @code{#f})
+This must be either @code{#f}, in which case the default log-in program
+is used (@command{login} from the Shadow tool suite), or a gexp denoting
+the name of the log-in program.
+
+@item @code{login-pause?} (default: @code{#f})
+When set to @code{#t} in conjunction with @var{auto-login}, the user
+will have to press a key before the log-in shell is launched.
+
+@item @code{mingetty} (default: @var{mingetty})
+The Mingetty package to use.
+
+@end table
+@end deftp
@cindex name service cache daemon
@cindex nscd
-@deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc] @
+@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
[#:name-services '()]
-Return a service that runs libc's name service cache daemon (nscd) with
-the given @var{config}---an @code{<nscd-configuration>} object.
-Optionally, @code{#:name-services} is a list of packages that provide
-name service switch (NSS) modules needed by nscd. @xref{Name Service
-Switch}, for an example.
+Return a service that runs libc's name service cache daemon (nscd) with the
+given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
+Service Switch}, for an example.
@end deffn
@defvr {Scheme Variable} %nscd-default-configuration
@@ -5789,6 +5849,14 @@ configuration.
@table @asis
+@item @code{name-services} (default: @code{'()})
+List of packages denoting @dfn{name services} that must be visible to
+the nscd---e.g., @code{(list @var{nss-mdns})}.
+
+@item @code{glibc} (default: @var{glibc})
+Package object denoting the GNU C Library providing the @command{nscd}
+command.
+
@item @code{log-file} (default: @code{"/var/log/nscd.log"})
Name of nscd's log file. This is where debugging output goes when
@code{debug-level} is strictly positive.
@@ -5855,36 +5923,54 @@ external name servers do not even need to be queried.
@end defvr
-@deffn {Monadic Procedure} syslog-service [#:config-file #f]
+@deffn {Scheme Procedure} syslog-service [#:config-file #f]
Return a service that runs @code{syslogd}. If configuration file name
@var{config-file} is not specified, use some reasonable default
settings.
@end deffn
-@deffn {Monadic Procedure} guix-service [#:guix guix] @
- [#:builder-group "guixbuild"] [#:build-accounts 10] @
- [#:authorize-hydra-key? #t] [#:use-substitutes? #t] @
- [#:extra-options '()]
-Return a service that runs the build daemon from @var{guix}, and has
-@var{build-accounts} user accounts available under @var{builder-group}.
+@anchor{guix-configuration-type}
+@deftp {Data Type} guix-configuration
+This data type represents the configuration of the Guix build daemon.
+@xref{Invoking guix-daemon}, for more information.
-When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
-provided by @var{guix} is authorized upon activation, meaning that substitutes
-from @code{hydra.gnu.org} are used by default.
+@table @asis
+@item @code{guix} (default: @var{guix})
+The Guix package to use.
-If @var{use-substitutes?} is false, the daemon is run with
-@option{--no-substitutes} (@pxref{Invoking guix-daemon,
-@option{--no-substitutes}}).
+@item @code{build-group} (default: @code{"guixbuild"})
+Name of the group for build user accounts.
-Finally, @var{extra-options} is a list of additional command-line options
-passed to @command{guix-daemon}.
+@item @code{build-accounts} (default: @code{10})
+Number of build user accounts to create.
+
+@item @code{authorize-key?} (default: @code{#t})
+Whether to authorize the substitute key for @code{hydra.gnu.org}
+(@pxref{Substitutes}).
+
+@item @code{use-substitutes?} (default: @code{#t})
+Whether to use substitutes.
+
+@item @code{extra-options} (default: @code{'()})
+List of extra command-line options for @command{guix-daemon}.
+
+@item @code{lsof} (default: @var{lsof})
+@itemx @code{lsh} (default: @var{lsh})
+The lsof and lsh packages to use.
+
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} guix-service @var{config}
+Return a service that runs the Guix build daemon according to
+@var{config}.
@end deffn
-@deffn {Monadic Procedure} udev-service [#:udev udev]
+@deffn {Scheme Procedure} udev-service [#:udev udev]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
@end deffn
-@deffn {Monadic Procedure} console-keymap-service @var{file}
+@deffn {Scheme Procedure} console-keymap-service @var{file}
Return a service to load console keymap from @var{file} using
@command{loadkeys} command.
@end deffn
@@ -5897,12 +5983,12 @@ The @code{(gnu services networking)} module provides services to configure
the network interface.
@cindex DHCP, networking service
-@deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
+@deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
Return a service that runs @var{dhcp}, a Dynamic Host Configuration
Protocol (DHCP) client, on all the non-loopback network interfaces.
@end deffn
-@deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
+@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
[#:gateway #f] [#:name-services @code{'()}]
Return a service that starts @var{interface} with address @var{ip}. If
@var{gateway} is true, it must be a string specifying the default network
@@ -5910,12 +5996,12 @@ gateway.
@end deffn
@cindex wicd
-@deffn {Monadic Procedure} wicd-service [#:wicd @var{wicd}]
+@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a
network manager that aims to simplify wired and wireless networking.
@end deffn
-@deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
+@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
[#:name-service @var{%ntp-servers}]
Return a service that runs the daemon from @var{ntp}, the
@uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
@@ -5926,14 +6012,14 @@ keep the system clock synchronized with that of @var{servers}.
List of host names used as the default NTP servers.
@end defvr
-@deffn {Monadic Procedure} tor-service [#:tor tor]
+@deffn {Scheme Procedure} tor-service [#:tor tor]
Return a service to run the @uref{https://torproject.org,Tor} daemon.
The daemon runs with the default settings (in particular the default exit
policy) as the @code{tor} unprivileged user.
@end deffn
-@deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
+@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @
[#:interface "127.0.0.1"] [#:port 6667] @
[#:extra-settings ""]
Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
@@ -5950,7 +6036,7 @@ configuration file.
Furthermore, @code{(gnu services ssh)} provides the following service.
-@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
+@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
[#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
[#:allow-empty-passwords? #f] [#:root-login? #f] @
[#:syslog-output? #t] [#:x11-forwarding? #t] @
@@ -6017,7 +6103,7 @@ browsers, from accessing Facebook.
The @code{(gnu services avahi)} provides the following definition.
-@deffn {Monadic Procedure} avahi-service [#:avahi @var{avahi}] @
+@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
[#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
[#:ipv6? #t] [#:wide-area? #f] @
[#:domains-to-browse '()]
@@ -6047,7 +6133,7 @@ Xorg---is provided by the @code{(gnu services xorg)} module. Note that
there is no @code{xorg-service} procedure. Instead, the X server is
started by the @dfn{login manager}, currently SLiM.
-@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
+@deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @
[#:auto-login? #f] [#:default-user ""] [#:startx] @
[#:theme @var{%default-slim-theme}] @
[#:theme-name @var{%default-slim-theme-name}]
@@ -6083,7 +6169,7 @@ theme.
The G-Expression denoting the default SLiM theme and its name.
@end defvr
-@deffn {Monadic Procedure} xorg-start-command [#:guile] @
+@deffn {Scheme Procedure} xorg-start-command [#:guile] @
[#:configuration-file #f] [#:xorg-server @var{xorg-server}]
Return a derivation that builds a @var{guile} script to start the X server
from @var{xorg-server}. @var{configuration-file} is the server configuration
@@ -6093,7 +6179,7 @@ file or a derivation that builds it; when omitted, the result of
Usually the X server is started by a login manager.
@end deffn
-@deffn {Monadic Procedure} xorg-configuration-file @
+@deffn {Scheme Procedure} xorg-configuration-file @
[#:drivers '()] [#:resolutions '()] [#:extra-config '()]
Return a configuration file for the Xorg server containing search paths for
all the common drivers.
@@ -6141,11 +6227,10 @@ The @var{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).
-The actual service definitions provided by @code{(gnu services desktop)}
-are described below.
+The actual service definitions provided by @code{(gnu services dbus)}
+and @code{(gnu services desktop)} are described below.
-@deffn {Monadic Procedure} dbus-service @var{services} @
- [#:dbus @var{dbus}]
+@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
Return a service that runs the ``system bus'', using @var{dbus}, with
support for @var{services}.
@@ -6159,8 +6244,7 @@ and policy files. For example, to allow avahi-daemon to use the system bus,
@var{services} must be equal to @code{(list avahi)}.
@end deffn
-@deffn {Monadic Procedure} elogind-service @
- [#:elogind @var{elogind}] [#:config @var{config}]
+@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
Return a service that runs the @code{elogind} login and
seat management daemon. @uref{https://github.com/andywingo/elogind,
Elogind} exposes a D-Bus interface that can be used to know which users
@@ -6230,7 +6314,7 @@ their default values are:
@end table
@end deffn
-@deffn {Monadic Procedure} polkit-service @
+@deffn {Scheme Procedure} polkit-service @
[#:polkit @var{polkit}]
Return a service that runs the Polkit privilege manager.
@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit} allows
@@ -6240,7 +6324,7 @@ whose session is active to shut down the machine, if there are no other
users active.
@end deffn
-@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
+@deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @
[#:watts-up-pro? #f] @
[#:poll-batteries? #t] @
[#:ignore-lid? #f] @
@@ -6259,7 +6343,7 @@ levels, with the given configuration settings. It implements the
GNOME.
@end deffn
-@deffn {Monadic Procedure} colord-service [#:colord @var{colord}]
+@deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
Return a service that runs @command{colord}, a system service with a D-Bus
interface to manage the color profiles of input and output devices such as
screens and scanners. It is notably used by the GNOME Color Manager graphical
@@ -6287,7 +6371,7 @@ Firefox and Epiphany both query the user before allowing a web page to
know the user's location.
@end defvr
-@deffn {Monadic Procedure} geoclue-service [#:colord @var{colord}] @
+@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
[#:whitelist '()] @
[#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
[#:submit-data? #f]
@@ -6307,7 +6391,7 @@ web site} for more information.
The @code{(gnu services databases)} module provides the following service.
-@deffn {Monadic Procedure} postgresql-service [#:postgresql postgresql] @
+@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
[#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
Return a service that runs @var{postgresql}, the PostgreSQL database
server.
@@ -6322,7 +6406,7 @@ The PostgreSQL daemon loads its runtime configuration from
The @code{(gnu services web)} module provides the following service:
-@deffn {Monadic Procedure} nginx-service [#:nginx nginx] @
+@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
[#:log-directory ``/var/log/nginx''] @
[#:run-directory ``/var/run/nginx''] @
[#:config-file]
@@ -6342,7 +6426,7 @@ directories are created when the service is activated.
The @code{(gnu services lirc)} module provides the following service.
-@deffn {Monadic Procedure} lirc-service [#:lirc lirc] @
+@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
[#:device #f] [#:driver #f] [#:config-file #f] @
[#:extra-options '()]
Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
@@ -6515,13 +6599,11 @@ configuration file:
(define %my-base-services
;; Replace the default nscd service with one that knows
;; about nss-mdns.
- (map (lambda (mservice)
- ;; "Bind" the MSERVICE monadic value to inspect it.
- (mlet %store-monad ((service mservice))
- (if (member 'nscd (service-provision service))
- (nscd-service (nscd-configuration)
- #:name-services (list nss-mdns))
- mservice)))
+ (map (lambda (service)
+ (if (member 'nscd (service-provision service))
+ (nscd-service (nscd-configuration
+ (name-services (list nss-mdns))))
+ service))
%base-services))
@end example
@@ -6880,6 +6962,11 @@ using the following command:
Attempt to build for @var{system} instead of the host's system type.
This works as per @command{guix build} (@pxref{Invoking guix build}).
+@item --derivation
+@itemx -d
+Return the derivation file name of the given operating system without
+building anything.
+
@item --image-size=@var{size}
For the @code{vm-image} and @code{disk-image} actions, create an image
of the given @var{size}. @var{size} may be a number of bytes, or it may
@@ -6916,54 +7003,378 @@ build users.
@node Defining Services
@subsection Defining Services
-The @code{(gnu services @dots{})} modules define several procedures that allow
-users to declare the operating system's services (@pxref{Using the
-Configuration System}). These procedures are @emph{monadic
-procedures}---i.e., procedures that return a monadic value in the store
-monad (@pxref{The Store Monad}). For examples of such procedures,
-@xref{Services}.
-
-@cindex service definition
-The monadic value returned by those procedures is a @dfn{service
-definition}---a structure as returned by the @code{service} form.
-Service definitions specifies the inputs the service depends on, and an
-expression to start and stop the service. Behind the scenes, service
-definitions are ``translated'' into the form suitable for the
-configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
-dmd Manual}).
-
-As an example, here is what the @code{nscd-service} procedure looks
-like:
+The previous sections show the available services and how one can combine
+them in an @code{operating-system} declaration. But how do we define
+them in the first place? And what is a service anyway?
-@lisp
-(define (nscd-service)
- (with-monad %store-monad
- (return (service
- (documentation "Run libc's name service cache daemon.")
- (provision '(nscd))
- (activate #~(begin
- (use-modules (guix build utils))
- (mkdir-p "/var/run/nscd")))
- (start #~(make-forkexec-constructor
- (string-append #$glibc "/sbin/nscd")
- "-f" "/dev/null" "--foreground"))
- (stop #~(make-kill-destructor))
- (respawn? #f)))))
-@end lisp
+@menu
+* Service Composition:: The model for composing services.
+* Service Types and Services:: Types and services.
+* Service Reference:: API reference.
+* dmd Services:: A particular type of service.
+@end menu
+
+@node Service Composition
+@subsubsection Service Composition
+
+@cindex services
+@cindex daemons
+Here we define a @dfn{service} as, broadly, something that extends the
+operating system's functionality. Often a service is a process---a
+@dfn{daemon}---started when the system boots: a secure shell server, a
+Web server, the Guix build daemon, etc. Sometimes a service is a daemon
+whose execution can be triggered by another daemon---e.g., an FTP server
+started by @command{inetd} or a D-Bus service activated by
+@command{dbus-daemon}. Occasionally, a service does not map to a
+daemon. For instance, the ``account'' service collects user accounts
+and makes sure they exist when the system runs; the ``udev'' service
+collects device management rules and makes them available to the eudev
+daemon; the @file{/etc} service populates the system's @file{/etc}
+directory.
+
+GuixSD services are connected by @dfn{extensions}. For instance, the
+secure shell service @emph{extends} dmd---GuixSD's initialization system,
+running as PID@tie{}1---by giving it the command lines to start and stop
+the secure shell daemon (@pxref{Networking Services,
+@code{lsh-service}}); the UPower service extends the D-Bus service by
+passing it its @file{.service} specification, and extends the udev
+service by passing it device management rules (@pxref{Desktop Services,
+@code{upower-service}}); the Guix daemon service extends dmd by passing
+it the command lines to start and stop the daemon, and extends the
+account service by passing it a list of required build user accounts
+(@pxref{Base Services}).
+
+All in all, services and their ``extends'' relations form a directed
+acyclic graph (DAG). If we represent services as boxes and extensions
+as arrows, a typical system might provide something like this:
+
+@image{images/service-graph,,5in,Typical service extension graph.}
+
+At the bottom, we see the @dfn{boot service}, which produces the boot
+script that is executed at boot time from the initial RAM disk.
+
+@cindex service types
+Technically, developers can define @dfn{service types} to express these
+relations. There can be any number of services of a given type on the
+system---for instance, a system running two instances of the GNU secure
+shell server (lsh) has two instances of @var{lsh-service-type}, with
+different parameters.
+
+The following section describes the programming interface for service
+types and services.
+
+@node Service Types and Services
+@subsubsection Service Types and Services
+
+A @dfn{service type} is a node in the DAG described above. Let us start
+with a simple example, the service type for the Guix build daemon
+(@pxref{Invoking guix-daemon}):
+
+@example
+(define guix-service-type
+ (service-type
+ (name 'guix)
+ (extensions
+ (list (service-extension dmd-root-service-type guix-dmd-service)
+ (service-extension account-service-type guix-accounts)
+ (service-extension activation-service-type guix-activation)))))
+@end example
@noindent
-The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
-(@pxref{G-Expressions}). The @code{activate} field contains a script to
-run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
-directory exists before @command{nscd} is started.
+It defines a two things:
+
+@enumerate
+@item
+A name, whose sole purpose is to make inspection and debugging easier.
+
+@item
+A list of @dfn{service extensions}, where each extension designates the
+target service type and a procedure that, given the service's
+parameters, returns a list of object to extend the service of that type.
+
+Every service type has at least one service extension. The only
+exception is the @dfn{boot service type}, which is the ultimate service.
+@end enumerate
+
+In this example, @var{guix-service-type} extends three services:
+
+@table @var
+@item dmd-root-service-type
+The @var{guix-dmd-service} procedure defines how the dmd service is
+extended. Namely, it returns a @code{<dmd-service>} object that defines
+how @command{guix-daemon} is started and stopped (@pxref{dmd Services}).
+
+@item account-service-type
+This extension for this service is computed by @var{guix-accounts},
+which returns a list of @code{user-group} and @code{user-account}
+objects representing the build user accounts (@pxref{Invoking
+guix-daemon}).
+
+@item activation-service-type
+Here @var{guix-activation} is a procedure that returns a gexp, which is
+a code snippet to run at ``activation time''---e.g., when the service is
+booted.
+@end table
+
+A service of this type is instantiated like this:
+
+@example
+(service guix-service-type
+ (guix-configuration
+ (build-accounts 5)
+ (use-substitutes? #f)))
+@end example
+
+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.
+
+@var{guix-service-type} is quite simple because it extends other
+services but is not extensible itself.
+
+@c @subsubsubsection Extensible Service Types
+
+The service type for an @emph{extensible} service looks like this:
+
+@example
+(define udev-service-type
+ (service-type (name 'udev)
+ (extensions
+ (list (service-extension dmd-root-service-type
+ udev-dmd-service)))
+
+ (compose concatenate) ;concatenate the list of rules
+ (extend (lambda (config rules)
+ (match config
+ (($ <udev-configuration> udev initial-rules)
+ (udev-configuration
+ (udev udev) ;the udev package to use
+ (rules (append initial-rules rules)))))))))
+@end example
+This is the service type for the
+@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
+management daemon}. Compared to the previous example, in addition to an
+extension of @var{dmd-root-service-type}, we see two new fields:
+
+@table @code
+@item compose
+This is the procedure to @dfn{compose} the list of extensions to
+services of this type.
+
+Services can extend the udev service by passing it lists of rules; we
+compose those extensions simply by concatenating them.
+
+@item extend
+This procedure defines how the service's value is @dfn{extended} with
+the composition of the extensions.
+
+Udev extensions are composed into a list of rules, but the udev service
+value is itself a @code{<udev-configuration>} record. So here, we
+extend that record by appending the list of rules is contains to the
+list of contributed rules.
+@end table
+
+There can be only one instance of an extensible service type such as
+@var{udev-service-type}. If there were more, the
+@code{service-extension} specifications would be ambiguous.
+
+Still here? The next section provides a reference of the programming
+interface for services.
+
+@node Service Reference
+@subsubsection Service Reference
+
+We have seen an overview of service types (@pxref{Service Types and
+Services}). This section provides a reference on how to manipulate
+services and service types. This interface is provided by the
+@code{(gnu services)} module.
+
+@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.
+@end deffn
+
+@deffn {Scheme Procedure} service? @var{obj}
+Return true if @var{obj} is a service.
+@end deffn
+
+@deffn {Scheme Procedure} service-kind @var{service}
+Return the type of @var{service}---i.e., a @code{<service-type>} object.
+@end deffn
+
+@deffn {Scheme Procedure} service-parameters @var{service}
+Return the value associated with @var{service}. It represents its
+parameters.
+@end deffn
+
+Here is an example of how a service is created and manipulated:
+
+@example
+(define s
+ (service nginx-service-type
+ (nginx-configuration
+ (nginx nginx)
+ (log-directory log-directory)
+ (run-directory run-directory)
+ (file config-file))))
+
+(service? s)
+@result{} #t
+
+(eq? (service-kind s) nginx-service-type)
+@result{} #t
+@end example
+
+@deftp {Data Type} service-type
+@cindex service type
+This is the representation of a @dfn{service type} (@pxref{Service Types
+and Services}).
+
+@table @asis
+@item @code{name}
+This is a symbol, used only to simplify inspection and debugging.
+
+@item @code{extensions}
+A non-empty list of @code{<service-extension>} objects (see below.)
+
+@item @code{compose} (default: @code{#f})
+If this is @code{#f}, then the service type denotes services that cannot
+be extended---i.e., services that do not receive ``values'' from other
+services.
+
+Otherwise, it must be a one-argument procedure. The procedure is called
+by @code{fold-services} and is passed a list of values collected from
+extensions. It must return a value that is a valid parameter value for
+the service instance.
+
+@item @code{extend} (default: @code{#f})
+If this is @code{#f}, services of this type cannot be extended.
+
+Otherwise, it must be a two-argument procedure: @code{fold-services}
+calls it, passing it the service's initial value as the first argument
+and the result of applying @code{compose} to the extension values as the
+second argument.
+@end table
+
+@xref{Service Types and Services}, for examples.
+@end deftp
+
+@deffn {Scheme Procedure} service-extension @var{target-type} @
+ @var{compute}
+Return a new extension for services of type @var{target-type}.
+@var{compute} must be a one-argument procedure: @code{fold-services}
+calls it, passing it the value associated with the service that provides
+the extension; it must return a valid value for the target service.
+@end deffn
+
+@deffn {Scheme Procedure} service-extension? @var{obj}
+Return true if @var{obj} is a service extension.
+@end deffn
+
+At the core of the service abstraction lies the @code{fold-services}
+procedure, which is responsible for ``compiling'' a list of services
+down to a single boot script. In essence, it propagates service
+extensions down the service graph, updating each node parameters on the
+way, until it reaches the root node.
+
+@deffn {Scheme Procedure} fold-services @var{services} @
+ [#:target-type @var{boot-service-type}]
+Fold @var{services} by propagating their extensions down to the root of
+type @var{target-type}; return the root service adjusted accordingly.
+@end deffn
+
+Lastly, the @code{(gnu services)} module also defines several essential
+service types, some of which are listed below.
+
+@defvr {Scheme Variable} boot-service-type
+The type of the ``boot service'', which is the root of the service
+graph.
+@end defvr
+
+@defvr {Scheme Variable} etc-service-type
+The type of the @file{/etc} service. This service can be extended by
+passing it name/file tuples such as:
+
+@example
+(list `("issue" ,(plain-file "issue" "Welcome!\n")))
+@end example
+
+In this example, the effect would be to add an @file{/etc/issue} file
+pointing to the given file.
+@end defvr
+
+@defvr {Scheme Variable} setuid-program-service-type
+Type for the ``setuid-program service''. This service collects lists of
+executable file names, passed as gexps, and adds them to the set of
+setuid-root programs on the system (@pxref{Setuid Programs}).
+@end defvr
+
+
+@node dmd Services
+@subsubsection dmd Services
+
+@cindex PID 1
+@cindex init system
+The @code{(gnu services dmd)} provides a way to define services managed
+by GNU@tie{}dmd, which is GuixSD initialization system---the first
+process that is started when the system boots, aka. PID@tie{}1
+(@pxref{Introduction,,, dmd, GNU dmd Manual}). The
+@var{%dmd-root-service} represents PID@tie{}1, of type
+@var{dmd-root-service-type}; it can be extended by passing it lists of
+@code{<dmd-service>} objects.
+
+@deftp {Data Type} dmd-service
+The data type representing a service managed by dmd.
+
+@table @asis
+@item @code{provision}
+This is a list of symbols denoting what the service provides.
+
+These are the names that may be passed to @command{deco start},
+@command{deco status}, and similar commands (@pxref{Invoking deco,,,
+dmd, GNU dmd Manual}). @xref{Slots of services, the @code{provides}
+slot,, dmd, GNU dmd Manual}, for details.
+
+@item @code{requirements} (default: @code{'()})
+List of symbols denoting the dmd services this one depends on.
+
+@item @code{respawn?} (default: @code{#t})
+Whether to restart the service when it stops, for instance when the
+underlying process dies.
+
+@item @code{start}
+@itemx @code{stop} (default: @code{#~(const #f)})
The @code{start} and @code{stop} fields refer to dmd's facilities to
start and stop processes (@pxref{Service De- and Constructors,,, dmd,
-GNU dmd Manual}). The @code{provision} field specifies the name under
-which this service is known to dmd, and @code{documentation} specifies
-on-line documentation. Thus, the commands @command{deco start ncsd},
-@command{deco stop nscd}, and @command{deco doc nscd} will do what you
-would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
+GNU dmd Manual}). They are given as G-expressions that get expanded in
+the dmd configuration file (@pxref{G-Expressions}).
+
+@item @code{documentation}
+A documentation string, as shown when running:
+
+@example
+deco doc @var{service-name}
+@end example
+
+where @var{service-name} is one of the symbols in @var{provision}
+(@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
+@end table
+@end deftp
+
+@defvr {Scheme Variable} dmd-root-service-type
+The service type for the dmd ``root service''---i.e., PID@tie{}1.
+
+This is the service type that extensions target when they want to create
+dmd services (@pxref{Service Types and Services}, for an example). Each
+extension must pass a list of @code{<dmd-service>}.
+@end defvr
+
+@defvr {Scheme Variable} %dmd-root-service
+This service represents PID@tie{}1.
+@end defvr
@node Installing Debugging Files
diff --git a/doc/images/service-graph.dot b/doc/images/service-graph.dot
new file mode 100644
index 0000000000..3397b878e9
--- /dev/null
+++ b/doc/images/service-graph.dot
@@ -0,0 +1,35 @@
+digraph "Service Type Dependencies" {
+ dmd [shape = box, fontname = Helvetica];
+ pam [shape = box, fontname = Helvetica];
+ etc [shape = box, fontname = Helvetica];
+ accounts [shape = box, fontname = Helvetica];
+ activation [shape = box, fontname = Helvetica];
+ boot [shape = house, fontname = Helvetica];
+ lshd -> dmd;
+ lshd -> pam;
+ udev -> dmd;
+ nscd -> dmd [label = "extends"];
+ "nss-mdns" -> nscd;
+ "kvm-rules" -> udev;
+ colord -> udev;
+ dbus -> dmd;
+ colord -> dbus;
+ upower -> udev;
+ upower -> dbus;
+ polkit -> dbus;
+ polkit -> pam;
+ elogind -> dbus;
+ elogind -> udev;
+ elogind -> polkit [label = "extends"];
+ dmd -> boot;
+ colord -> accounts;
+ accounts -> activation;
+ accounts -> etc;
+ etc -> activation;
+ activation -> boot;
+ pam -> etc;
+ elogind -> pam;
+ guix -> dmd;
+ guix -> activation;
+ guix -> accounts;
+}