02/02: doc: Add example showing how to customize 'nscd-service'.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 4c9050c63d707222730fc6112415f4324e0c7c37
Author: Ludovic Courtès <address@hidden>
Date:   Sun Apr 12 22:34:47 2015 +0200

    doc: Add example showing how to customize 'nscd-service'.
    
    * doc/guix.texi (Name Service Switch): Add link to nss-mdns.  Add
      example show how to pass #:name-services to 'nscd-service'.
      (Base Services): Add link from 'nscd-service' to the above.
    * gnu/services/base.scm (nscd-service): Update docstring accordingly.
---
 doc/guix.texi         |   38 +++++++++++++++++++++++++++++++++++---
 gnu/services/base.scm |    2 +-
 2 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index c0af4cb..872caa8 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4531,7 +4531,8 @@ the ``message of the day''.
 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.
+name service switch (NSS) modules needed by nscd.  @xref{Name Service
+Switch}, for an example.
 @end deffn
 
 @defvr {Scheme Variable} %nscd-default-configuration
@@ -4898,9 +4899,12 @@ next method in the list.  The NSS configuration is given 
in the
 @code{name-service-switch} field of @code{operating-system} declarations
 (@pxref{operating-system Reference, @code{name-service-switch}}).
 
address@hidden See <http://0pointer.de/lennart/projects/nss-mdns/>.
address@hidden nss-mdns
address@hidden .local, host name lookup
 As an example, the declaration below configures the NSS to use the
address@hidden back-end for host name lookups:
address@hidden://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
+back-end}, which supports host name lookups over multicast DNS (mDNS)
+for host names ending in @code{.local}:
 
 @example
 (name-service-switch
@@ -4926,6 +4930,34 @@ As an example, the declaration below configures the NSS 
to use the
                   (name "mdns")))))
 @end example
 
+Note that, in this case, in addition to setting the
address@hidden of the @code{operating-system} declaration,
address@hidden must be told where to find the @code{nss-mdns}
+shared library (@pxref{Base Services, @code{nscd-service}}).  Since the
address@hidden service is part of @var{%base-services}, you may want to
+customize it by adding this snippet in the operating system
+configuration file:
+
address@hidden
+(use-modules (guix) (gnu))
+
+(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)))
+       %base-services))
address@hidden example
+
address@hidden
address@hidden and then refer to @var{%my-base-services} instead of
address@hidden in the @code{operating-system} declaration.
+
 The reference for name service switch configuration is given below.  It
 is a direct mapping of the C library's configuration file format, so
 please refer to the C library manual for more information (@pxref{NSS
diff --git a/gnu/services/base.scm b/gnu/services/base.scm
index cd1ba0b..956fa7e 100644
--- a/gnu/services/base.scm
+++ b/gnu/services/base.scm
@@ -499,7 +499,7 @@ the ``message of the day''."
   "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."
+ (NSS) modules needed by nscd.  @xref{Name Service Switch}, for an example."
   (mlet %store-monad ((nscd.conf (nscd.conf-file config)))
     (return (service
              (documentation "Run libc's name service cache daemon (nscd).")