diff mbox

gnu: Add rpc-daemon service

Message ID 1473180656-14742-1-git-send-email-jmd@gnu.org
State New
Headers show

Commit Message

John Darrington Sept. 6, 2016, 4:50 p.m. UTC
I think this patch does what you want.  Perhaps you can take another look before I push.

If I might be allowed to give my opinion though ...   I think this way of documenting 
things is of limited help to potential users.  It does nothing more than repeat what
is written in the code.  If that is what we want, then we could use some kind of
literate programming tool to do it.  That would be less maintenence and avoids
the possibility of code and documentation becoming out of sync.

However, what is really needed from documentation IMO, is not only a API reference,
but also a tutorial on how to use the thing.  I think this form of documentation will only
leave the newcommer scratching his head.



* gnu/services/nfs.scm: New file.
* gnu/local.mk (GNU_SYSTEM_MODULES): Add it.
---
 doc/guix.texi        | 26 +++++++++++++++++++++++++
 gnu/local.mk         |  1 +
 gnu/services/nfs.scm | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 81 insertions(+)
 create mode 100644 gnu/services/nfs.scm

Comments

Ludovic Courtès Sept. 7, 2016, 12:17 p.m. UTC | #1
Hi!

John Darrington <jmd@gnu.org> skribis:

> If I might be allowed to give my opinion though ...   I think this way of documenting 
> things is of limited help to potential users.  It does nothing more than repeat what
> is written in the code.  If that is what we want, then we could use some kind of
> literate programming tool to do it.  That would be less maintenence and avoids
> the possibility of code and documentation becoming out of sync.

I don’t see anything in nfs.scm explaining, for instance, the
‘warm-start?’ knob; nor is anything (and rightfully so) hinting at what
NFS is and how rpcbind relates to it.

> However, what is really needed from documentation IMO, is not only a API reference,
> but also a tutorial on how to use the thing.  I think this form of documentation will only
> leave the newcommer scratching his head.

I agree.  It’s often a good idea to (1) give context and relevant
cross-references in the doc, and (2) include an example for non-trivial
services.  For instance, I think the “Desktop Services” and “Scheduled
Job Execution” sections are doing pretty good in this regard.

> * gnu/services/nfs.scm: New file.
> * gnu/local.mk (GNU_SYSTEM_MODULES): Add it.

[...]

> +@subsubheading RPC Bind Service
> +@cindex rpcbind
> +
> +The @code{(gnu services nfs)} module provides the following:
> +
> +@defvr {Scheme Variable} rpcbind-service-type
> +A service type  for the RPC portmapper daemon.
> +@end defvr
> +
> +
> +@deftp {Data Type} rpcbind-configuration
> +Data type representing the configuration of the RPC Bind Service.
> +This type has the following parameters:
> +@table @asis
> +@item @code{rpcbind} (default: @code{rpcbind})
> +The rpcbind package to use.
> +
> +@item @code{warm-start?}
                           ^
Mention the default value here…

> +If this parameter is @code{#t} (the default), then the daemon will read a
                                  ^
… and not here.

Other than that, LGTM!

Regarding documentation, since you asked ;-), what could work well here
is to have a complete “Network File System” @subsection.  It would start
with a short intro of what NFS is, provide an example showing how to
export a directory over NFS, give an overview of the services involved
(rpcbind, mountd, statd), and then give the API reference.

Thoughts for future work.  :-)

Thank you!

Ludo’.
diff mbox

Patch

diff --git a/doc/guix.texi b/doc/guix.texi
index 59bc5d8..cff61d0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -25,6 +25,7 @@  Copyright @copyright{} 2015, 2016 Ricardo Wurmus@*
 Copyright @copyright{} 2016 Ben Woodcroft@*
 Copyright @copyright{} 2016 Chris Marusich@*
 Copyright @copyright{} 2016 Efraim Flashner@*
+Copyright @copyright{} 2016 John Darrington@*
 Copyright @copyright{} 2016 ng0
 
 Permission is granted to copy, distribute and/or modify this document
@@ -10089,6 +10090,31 @@  directories are created when the service is activated.
 @node Various Services
 @subsubsection Various Services
 
+
+@subsubheading RPC Bind Service
+@cindex rpcbind
+
+The @code{(gnu services nfs)} module provides the following:
+
+@defvr {Scheme Variable} rpcbind-service-type
+A service type  for the RPC portmapper daemon.
+@end defvr
+
+
+@deftp {Data Type} rpcbind-configuration
+Data type representing the configuration of the RPC Bind Service.
+This type has the following parameters:
+@table @asis
+@item @code{rpcbind} (default: @code{rpcbind})
+The rpcbind package to use.
+
+@item @code{warm-start?}
+If this parameter is @code{#t} (the default), then the daemon will read a
+state file on startup thus reloading state information saved by a previous
+instance.
+@end table
+@end deftp
+
 @cindex lirc
 @subsubheading Lirc Service
 
diff --git a/gnu/local.mk b/gnu/local.mk
index 0a9b831..f337a2a 100644
--- a/gnu/local.mk
+++ b/gnu/local.mk
@@ -389,6 +389,7 @@  GNU_SYSTEM_MODULES =				\
   %D%/services/mail.scm				\
   %D%/services/mcron.scm			\
   %D%/services/networking.scm			\
+  %D%/services/nfs.scm			\
   %D%/services/shepherd.scm			\
   %D%/services/herd.scm				\
   %D%/services/sddm.scm				\
diff --git a/gnu/services/nfs.scm b/gnu/services/nfs.scm
new file mode 100644
index 0000000..82713d8
--- /dev/null
+++ b/gnu/services/nfs.scm
@@ -0,0 +1,54 @@ 
+;;; GNU Guix --- Functional package management for GNU
+;;; Copyright © 2016 John Darrington <jmd@gnu.org>
+;;;
+;;; This file is part of GNU Guix.
+;;;
+;;; GNU Guix is free software; you can redistribute it and/or modify it
+;;; under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation; either version 3 of the License, or (at
+;;; your option) any later version.
+;;;
+;;; GNU Guix is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;; GNU General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+(define-module (gnu services nfs)
+  #:use-module (gnu)
+  #:use-module (gnu services shepherd)
+  #:use-module (gnu packages onc-rpc)
+  #:use-module (guix)
+  #:use-module (guix records)
+  #:export (rpcbind-service-type
+            rpcbind-configuration
+            rpcbind-configuration?))
+
+(define-record-type* <rpcbind-configuration>
+  rpcbind-configuration make-rpcbind-configuration
+  rpcbind-configuration?
+  (rpcbind             rpcbind-configuration-rpcbind
+                       (default rpcbind))
+  (warm-start?         rpcbind-configuration-warm-start?
+                       (default #t)))
+
+(define rpcbind-service-type
+  (shepherd-service-type
+   'rpcbind
+   (lambda (config)
+     (define pkg
+       (rpcbind-configuration-rpcbind config))
+
+     (define rpcbind-command
+       #~(list (string-append #$pkg "/bin/rpcbind") "-f"
+               #$@(if (rpcbind-configuration-warm-start? config) '("-w") '())))
+
+     (shepherd-service
+      (documentation "Start the RPC bind daemon.")
+      (requirement '(networking))
+      (provision '(rpcbind-daemon))
+
+      (start #~(make-forkexec-constructor #$rpcbind-command))
+      (stop #~(make-kill-destructor))))))