>From 891e944dc522cdc250058e92d9150d6a6a39242f 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 | 79 ++++++++++++++++++++++++++++++++++---------------------- gnu/services.scm | 39 +++++++++++----------------- 2 files changed, 63 insertions(+), 55 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 082fe5a..701a946 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18,6 +18,7 @@ Copyright @copyright{} 2014 Pierre-Antoine address@hidden Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/address@hidden Copyright @copyright{} 2015, 2016 Leo Famulari Copyright @copyright{} 2016 Ben Woodcroft +Copyright @copyright{} 2016 Chris Marusich Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -6044,28 +6045,38 @@ 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 address@hidden and Mingetty (the console log-in), you may write the -following instead of @var{%base-services}: +customize them. To do this, use @code{modify-services} (@pxref{Service +Reference, @code{modify-services}}) to modify the list. + +For example, suppose you want to modify @code{guix-daemon} and Mingetty +(the console log-in) in the @var{%base-services} list (@pxref{Base +Services, @code{%base-services}). To do that, you could write the +following in your operating system declaration: @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!"))))) +(operating-system + ;; @dots{} + (services (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!")))))) @end lisp address@hidden -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, address@hidden, for more on that. +This changes the configuration---i.e., the service parameters---of the address@hidden instance, and that of all the address@hidden instances in the @var{%base-services} list. +Observe how this is accomplished: first, we arrange for the original +configuration to be bound to the identifier @code{config} in the address@hidden, 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. The configuration for a typical ``desktop'' usage, with the X11 display server, a desktop environment, network management, power management, and @@ -9916,11 +9927,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 address@hidden (@pxref{Base Services, @code{%base-services}}). Of -course, you could always use standard list combinators such as address@hidden 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. address@hidden (@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}); address@hidden 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 +9944,21 @@ 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 address@hidden 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., address@hidden @var{variable} is an identifier that is +bound within the @var{body} to the service parameters---e.g., a address@hidden instance---of the original service of that address@hidden -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 address@hidden that evaluates to the new service parameters by using the address@hidden feature that @code{define-record-type*} provides. + address@hidden the Configuration System} for example usage. address@hidden -(map (lambda (service) @dots{}) @var{services}) address@hidden 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..59ce763 100644 --- a/gnu/services.scm +++ b/gnu/services.scm @@ -1,5 +1,6 @@ ;;; GNU Guix --- Functional package management for GNU ;;; Copyright © 2015, 2016 Ludovic Courtès +;;; Copyright © 2016 Chris Marusich ;;; ;;; This file is part of GNU Guix. ;;; @@ -153,30 +154,20 @@ (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)." + "Modify the services in the SERVICES list according to the given +clauses. This form evaluates to a list of services. 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." ((_ services clauses ...) (map (lambda (service) (%modify-service service clauses ...)) -- 2.6.3