From b93d7daeaffd59436b3cf52a777d2cbe052c14d9 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Fri, 19 Mar 2021 18:26:59 +0100 Subject: doc: Add 'shepherd-service' example. * doc/guix.texi (Shepherd Services): Add example. --- doc/guix.texi | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 73757be887..386169b2a5 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -34060,6 +34060,38 @@ This is the list of modules that must be in scope when @code{start} and @end table @end deftp +The example below defines a Shepherd service that spawns +@command{syslogd}, the system logger from the GNU Networking Utilities +(@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU +Inetutils}): + +@example +(let ((config (plain-file "syslogd.conf" "@dots{}"))) + (shepherd-service + (documentation "Run the syslog daemon (syslogd).") + (provision '(syslogd)) + (requirement '(user-processes)) + (start #~(make-forkexec-constructor + (list #$(file-append inetutils "/libexec/syslogd") + "--rcfile" #$config) + #:pid-file "/var/run/syslog.pid")) + (stop #~(make-kill-destructor)))) +@end example + +Key elements in this example are the @code{start} and @code{stop} +fields: they are @dfn{staged} code snippets that use the +@code{make-forkexec-constructor} procedure provided by the Shepherd and +its dual, @code{make-kill-destructor} (@pxref{Service De- and +Constructors,,, shepherd, The GNU Shepherd Manual}). The @code{start} +field will have @command{shepherd} spawn @command{syslogd} with the +given option; note that we pass @code{config} after @option{--rcfile}, +which is a configuration file declared above (contents of this file are +omitted). Likewise, the @code{stop} field tells how this service is to +be stopped; in this case, it is stopped by making the @code{kill} system +call on its PID@. Code staging is achieved using G-expressions: +@code{#~} stages code, while @code{#$} ``escapes'' back to host code +(@pxref{G-Expressions}). + @deftp {Data Type} shepherd-action This is the data type that defines additional actions implemented by a Shepherd service (see above). -- cgit v1.2.3