From 10518b419c2f9322082c3f6d2a2c7535f7645f3d Mon Sep 17 00:00:00 2001 From: Chris Marusich Date: Mon, 7 Mar 2016 01:55:07 -0800 Subject: [PATCH] doc: Clarify and consolidate modify-services documentation. * doc/guix.texi ("Using the Configuration System": Move the example... * doc/guix.texi ("Service Reference"): ...to here, and clarify more. * gnu/services.scm (modify-services): Update docstring to match. --- doc/guix.texi | 93 +++++++++++++++++++++++++++++++++++--------------------- gnu/services.scm | 78 ++++++++++++++++++++++++++++++++--------------- 2 files changed, 112 insertions(+), 59 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 082fe5a..8d2b006 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -6044,28 +6044,14 @@ generated as needed (@pxref{Defining Services}). @cindex customization, of services @findex modify-services Occasionally, instead of using the base services as is, you will want to -customize them. For instance, to change the configuration of -@code{guix-daemon} and Mingetty (the console log-in), you may write the -following instead of @var{%base-services}: - -@lisp -(modify-services %base-services - (guix-service-type config => - (guix-configuration - (inherit config) - (use-substitutes? #f) - (extra-options '("--gc-keep-outputs")))) - (mingetty-service-type config => - (mingetty-configuration - (inherit config) - (motd (plain-file "motd" "Hi there!"))))) -@end lisp - -@noindent -The effect here is to change the options passed to @command{guix-daemon} -when it is started, as well as the ``message of the day'' that appears -when logging in at the console. @xref{Service Reference, -@code{modify-services}}, for more on that. +customize them. When working with a list of services such as +@var{%desktop-services}, you can use any of the standard list +combinators such as @code{map} and @code{fold} to manipulate the list +(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference +Manual}). However, there is an easier way: use @code{modify-services} to +modify the list. For detailed instructions on how to do that, including +a concrete example, see: @xref{Service Reference, +@code{modify-services}}. The configuration for a typical ``desktop'' usage, with the X11 display server, a desktop environment, network management, power management, and @@ -9916,11 +9902,12 @@ Here is an example of how a service is created and manipulated: The @code{modify-services} form provides a handy way to change the parameters of some of the services of a list such as -@var{%base-services} (@pxref{Base Services, @code{%base-services}}). Of -course, you could always use standard list combinators such as -@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, -guile, GNU Guile Reference Manual}); @code{modify-services} simply -provides a more concise form for this common pattern. +@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It +evalutes to a list of services. Of course, you could always use +standard list combinators such as @code{map} and @code{fold} to do that +(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual}); +@code{modify-services} simply provides a more concise form for this +common pattern. @deffn {Scheme Syntax} modify-services @var{services} @ (@var{type} @var{variable} => @var{body}) @dots{} @@ -9932,16 +9919,52 @@ clauses. Each clause has the form: (@var{type} @var{variable} => @var{body}) @end example -where @var{type} is a service type, such as @var{guix-service-type}, and -@var{variable} is an identifier that is bound within @var{body} to the -value of the service of that @var{type}. @xref{Using the Configuration -System}, for an example. +where @var{type} is a service type (e.g., @code{guix-service-type}), and +@var{variable} is an identifier that is bound within the @var{body} to +the service parameters (e.g., a @code{guix-configuration} instance) of +the original service of that @var{type}. -This is a shorthand for: +The @var{body} should evaluate to the new service parameters, which will +be used to configure the new service. This new service will replace the +original in the resulting list. Because a service's service parameters +are created using @code{define-record-type*}, you can write a succint +@var{body} that evaluates to the new service parameters by using the +@code{inherit} feature that @code{define-record-type*} provides. + +For the purpose of illustration, let us assume you want to modify the +default @var{%desktop-services} (@xref{Desktop Services}, for details) +in your operating system configuration file. To accomplish that, you +could write something like the following: + +@lisp +(operating-system + ;; Other configuration which precedes the "services" section + ;; has been omitted here for brevity. + (services (modify-services %desktop-services + (guix-service-type config => + (guix-configuration + (inherit config) + (use-substitutes? #f) + (extra-options '("--gc-keep-derivations")))) + (mingetty-service-type config => + (mingetty-configuration + (inherit config) + (motd (plain-file "motd" "Hi there!")))))) +@end lisp + +This changes the configuration (i.e., the service parameters) of the +@code{guix-service-type} instance, and that of all the +@code{mingetty-service-type} instances in the @var{%desktop-services} +list. Observe how this is accomplished: first, we arrange for the +original configuration to be bound to the identifier @code{config} in +the @var{body}, and then we write the @var{body} so that it evaluates to +the desired configuration. In particular, notice how we use +@code{inherit} to create a new configuration which has the same values +as the old configuration, but with a few modifications. + +@xref{Using the Configuration System}, for more information about +configuring the operating system. -@example -(map (lambda (service) @dots{}) @var{services}) -@end example @end deffn Next comes the programming interface for service types. This is diff --git a/gnu/services.scm b/gnu/services.scm index ffba418..f87819b 100644 --- a/gnu/services.scm +++ b/gnu/services.scm @@ -153,30 +153,60 @@ (define-syntax modify-services (syntax-rules () - "Modify the services listed in SERVICES according to CLAUSES. Each clause -must have the form: - - (TYPE VARIABLE => BODY) - -where TYPE is a service type, such as 'guix-service-type', and VARIABLE is an -identifier that is bound within BODY to the value of the service of that -TYPE. Consider this example: - - (modify-services %base-services - (guix-service-type config => - (guix-configuration - (inherit config) - (use-substitutes? #f) - (extra-options '(\"--gc-keep-derivations\")))) - (mingetty-service-type config => - (mingetty-configuration - (inherit config) - (motd (plain-file \"motd\" \"Hi there!\"))))) - -It changes the configuration of the GUIX-SERVICE-TYPE instance, and that of -all the MINGETTY-SERVICE-TYPE instances. - -This is a shorthand for (map (lambda (svc) ...) %base-services)." + "The 'modify-services' form provides a handy way to change the +parameters of some of the services of a list such as +%BASE-SERVICES. It evalutes to a list of services. Of course, you +could always use standard list combinators such as 'map' and 'fold' to +do that; 'modify-services' simply provides a more concise form for +this common pattern. + +modify-services SERVICES (TYPE VARIABLE => BODY) ... + +Modify the services listed in SERVICES according to the given clauses. +Each clause has the form: + +(TYPE VARIABLE => BODY) + +where TYPE is a service type (e.g., 'guix-service-type'), and VARIABLE +is an identifier that is bound within the BODY to the service +parameters (e.g., a 'guix-configuration' instance) of the original +service of that TYPE. + +The BODY should evaluate to the new service parameters, which will be +used to configure the new service. This new service will replace the +original in the resulting list. Because a service's service parameters +are created using 'define-record-type*', you can write a succint BODY +that evaluates to the new service parameters by using the 'inherit' +feature that 'define-record-type*' provides. + +For the purpose of illustration, let us assume you want to modify the +default %DESKTOP-SERVICES in your operating system configuration +file. To accomplish that, you could write something like the +following: + +(operating-system + ;; Other configuration which precedes the \"services\" section + ;; has been omitted here for brevity. + (services (modify-services %desktop-services + (guix-service-type config => + (guix-configuration + (inherit config) + (use-substitutes? #f) + (extra-options '(\"--gc-keep-derivations\")))) + (mingetty-service-type config => + (mingetty-configuration + (inherit config) + (motd (plain-file \"motd\" \"Hi there!\")))))) + +This changes the configuration (i.e., the service parameters) of the +'guix-service-type' instance, and that of all the +'mingetty-service-type' instances in the %DESKTOP-SERVICES list. +Observe how this is accomplished: first, we arrange for the original +configuration to be bound to the identifier 'config' in the BODY, and +then we write the BODY so that it evaluates to the desired +configuration. In particular, notice how we use 'inherit' to create a +new configuration which has the same values as the old configuration, +but with a few modifications." ((_ services clauses ...) (map (lambda (service) (%modify-service service clauses ...)) -- 2.6.3