From 0d22fc8d36e4efba9748c94cab7cedbbe2bbb5bf Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Wed, 13 Jan 2021 22:14:00 +0100 Subject: services: shepherd: 'shepherd-service-type' requires documentation. * gnu/services/shepherd.scm (shepherd-service-type): Require a 'description' form. * gnu/services/base.scm (root-file-system-service-type) (rngd-service-type, host-name-service-type): (virtual-terminal-service-type, console-keymap-service-type) (syslog-service-type, swap-service-type) (kmscon-service-type): Add description. * gnu/services/networking.scm (dhcp-client-service-type): Likewise. * gnu/system/install.scm (cow-store-service-type): Likewise. * gnu/system/linux-container.scm (dummy-networking-service-type): Likewise. * gnu/system/mapped-devices.scm (device-mapping-service-type): Likewise. * tests/guix-system.sh: Likewise. --- gnu/services/base.scm | 32 +++++++++++++++++++++++--------- gnu/services/networking.scm | 6 ++++-- gnu/services/shepherd.scm | 14 ++++++++------ gnu/system/install.scm | 6 ++++-- gnu/system/linux-container.scm | 7 +++++-- gnu/system/mapped-devices.scm | 5 +++-- 6 files changed, 47 insertions(+), 23 deletions(-) (limited to 'gnu') diff --git a/gnu/services/base.scm b/gnu/services/base.scm index 945b546607..f6a490f712 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès +;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès ;;; Copyright © 2015, 2016 Alex Kost ;;; Copyright © 2015, 2016, 2020 Mark H Weaver ;;; Copyright © 2015 Sou Bunnbu @@ -279,7 +279,9 @@ (define %root-file-system-shepherd-service (define root-file-system-service-type (shepherd-service-type 'root-file-system - (const %root-file-system-shepherd-service))) + (const %root-file-system-shepherd-service) + (description "Take care of syncing the root file +system and of remounting it read-only when the system shuts down."))) (define (root-file-system-service) "Return a service whose sole purpose is to re-mount read-only the root file @@ -570,7 +572,9 @@ (define rngd-command (requirement '(udev)) (provision '(trng)) (start #~(make-forkexec-constructor '#$rngd-command)) - (stop #~(make-kill-destructor)))))) + (stop #~(make-kill-destructor)))) + (description "Run the @command{rngd} random number generation daemon to +supply entropy to the kernel's pool."))) (define* (rngd-service #:key (rng-tools rng-tools) @@ -597,7 +601,8 @@ (define host-name-service-type (provision '(host-name)) (start #~(lambda _ (sethostname #$name))) - (one-shot? #t))))) + (one-shot? #t))) + (description "Initialize the machine's host name."))) (define (host-name-service name) "Return a service that sets the host name to @var{name}." @@ -626,7 +631,8 @@ (define virtual-terminal-service-type (display 1 port)))) #t)) (stop #~(const #f))))) - #t)) ;default to UTF-8 + #t ;default to UTF-8 + (description "Ensure the Linux virtual terminals run in UTF-8 mode."))) (define console-keymap-service-type (shepherd-service-type @@ -638,7 +644,10 @@ (define console-keymap-service-type (start #~(lambda _ (zero? (system* #$(file-append kbd "/bin/loadkeys") #$@files)))) - (respawn? #f))))) + (respawn? #f))) + (description "@emph{This service is deprecated in favor of the +@code{keyboard-layout} field of @code{operating-system}.} Load the given list +of console keymaps with @command{loadkeys}."))) (define-deprecated (console-keymap-service #:rest files) #f @@ -1341,7 +1350,9 @@ (define syslog-service-type (pid (spawn))) (umask mask) pid)))) - (stop #~(make-kill-destructor)))))) + (stop #~(make-kill-destructor)))) + (description "Run the syslog daemon, @command{syslogd}, which is +responsible for logging system messages."))) ;; Snippet adapted from the GNU inetutils manual. (define %default-syslog.conf @@ -2207,7 +2218,8 @@ (define service-name (when device (restart-on-EINTR (swapoff device))) #f))) - (respawn? #f)))))) + (respawn? #f)))) + (description "Turn on the virtual memory swap area."))) (define (swap-service device) "Return a service that uses @var{device} as a swap device." @@ -2321,7 +2333,9 @@ (define kmscon-command (requirement '(user-processes udev dbus-system)) (provision (list (symbol-append 'term- (string->symbol virtual-terminal)))) (start #~(make-forkexec-constructor #$kmscon-command)) - (stop #~(make-kill-destructor))))))) + (stop #~(make-kill-destructor))))) + (description "Start the @command{kmscon} virtual terminal emulator for the +Linux @dfn{kernel mode setting} (KMS)."))) (define-record-type* static-networking make-static-networking diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm index 44754781c1..dd4061341e 100644 --- a/gnu/services/networking.scm +++ b/gnu/services/networking.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès +;;; Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès ;;; Copyright © 2015 Mark H Weaver ;;; Copyright © 2016, 2018, 2020 Efraim Flashner ;;; Copyright © 2016 John Darrington @@ -283,7 +283,9 @@ (define ifaces (and (zero? (cdr (waitpid pid))) (read-pid-file #$pid-file))))) (stop #~(make-kill-destructor)))) - isc-dhcp)) + isc-dhcp + (description "Run @command{dhcp}, a Dynamic Host Configuration +Protocol (DHCP) client, on all the non-loopback network interfaces."))) (define-deprecated (dhcp-client-service #:key (dhcp isc-dhcp)) dhcp-client-service-type diff --git a/gnu/services/shepherd.scm b/gnu/services/shepherd.scm index 1faeb350df..d2f9776288 100644 --- a/gnu/services/shepherd.scm +++ b/gnu/services/shepherd.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2013, 2014, 2015, 2016, 2018, 2019, 2020 Ludovic Courtès +;;; Copyright © 2013, 2014, 2015, 2016, 2018, 2019, 2020, 2021 Ludovic Courtès ;;; Copyright © 2017 Clément Lassieur ;;; Copyright © 2018 Carlo Zancanaro ;;; Copyright © 2020 Jan (janneke) Nieuwenhuizen @@ -119,23 +119,25 @@ (define %shepherd-root-service (service shepherd-root-service-type '())) (define-syntax shepherd-service-type - (syntax-rules () + (syntax-rules (description) "Return a denoting a simple shepherd service--i.e., the type for a service that extends SHEPHERD-ROOT-SERVICE-TYPE and nothing else. When DEFAULT is given, use it as the service's default value." - ((_ service-name proc default) + ((_ service-name proc default (description text)) (service-type (name service-name) (extensions (list (service-extension shepherd-root-service-type (compose list proc)))) - (default-value default))) - ((_ service-name proc) + (default-value default) + (description text))) + ((_ service-name proc (description text)) (service-type (name service-name) (extensions (list (service-extension shepherd-root-service-type - (compose list proc)))))))) + (compose list proc)))) + (description text))))) (define %default-imported-modules ;; Default set of modules imported for a service's consumption. diff --git a/gnu/system/install.scm b/gnu/system/install.scm index e753463473..7fa5c15324 100644 --- a/gnu/system/install.scm +++ b/gnu/system/install.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès +;;; Copyright © 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès ;;; Copyright © 2015 Mark H Weaver ;;; Copyright © 2016 Andreas Enge ;;; Copyright © 2017 Marius Bakke @@ -212,7 +212,9 @@ (define (import-module? module) ;; 'user-processes' doesn't depend on us. The 'user-file-systems' ;; service will unmount TARGET eventually. (delete-file-recursively - (string-append target #$%backing-directory)))))))) + (string-append target #$%backing-directory)))))) + (description "Make the store copy-on-write, with writes going to \ +the given target."))) (define (cow-store-service) "Return a service that makes the store copy-on-write, such that writes go to diff --git a/gnu/system/linux-container.scm b/gnu/system/linux-container.scm index 4a9cd0efe2..e6fd0f1315 100644 --- a/gnu/system/linux-container.scm +++ b/gnu/system/linux-container.scm @@ -1,6 +1,6 @@ ;;; GNU Guix --- Functional package management for GNU ;;; Copyright © 2015 David Thompson -;;; Copyright © 2016, 2017, 2019, 2020 Ludovic Courtès +;;; Copyright © 2016, 2017, 2019, 2020, 2021 Ludovic Courtès ;;; Copyright © 2019 Arun Isaac ;;; Copyright © 2020 Efraim Flashner ;;; Copyright © 2020 Google LLC @@ -76,7 +76,10 @@ (define dummy-networking-service-type doing anything.") (provision '(loopback networking)) (start #~(const #t)))) - #f)) + #f + (description "Provide loopback and networking without actually doing +anything. This service is used by guest systems running in containers, where +networking support is provided by the host."))) (define %nscd-container-caches ;; Similar to %nscd-default-caches but with smaller cache sizes. This allows diff --git a/gnu/system/mapped-devices.scm b/gnu/system/mapped-devices.scm index 559c27bb28..518dbc4fe8 100644 --- a/gnu/system/mapped-devices.scm +++ b/gnu/system/mapped-devices.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès +;;; Copyright © 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès ;;; Copyright © 2016 Andreas Enge ;;; Copyright © 2017, 2018 Mark H Weaver ;;; @@ -130,7 +130,8 @@ (define device-mapping-service-type (documentation "Map a device node using Linux's device mapper.") (start #~(lambda () #$(open source targets))) (stop #~(lambda _ (not #$(close source targets)))) - (respawn? #f)))))) + (respawn? #f)))) + (description "Map a device node using Linux's device mapper."))) (define (device-mapping-service mapped-device) "Return a service that sets up @var{mapped-device}." -- cgit v1.2.3