From cb00e600ffe7ec493464788dd16308b7b8e87d20 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:47 +0000 Subject: services: base: Deprecate 'host-name-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (operating-system Reference): Reorder cross-reference. Add an anchor to be used ... (Base services): ... here by host-name-service-type. Document host-name-service-type. * gnu/services/base.scm: Export host-name-service-type. (host-name-service): Deprecate procedure. * gnu/system.scm (operating-system-default-essential-services): Use host-name-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 6ff525d0ff..537b8e19f5 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -16640,12 +16640,14 @@ details. @item @code{services} (default: @code{%base-services}) A list of service objects denoting system services. @xref{Services}. +@anchor{operating-system-essential-services} @cindex essential services @item @code{essential-services} (default: ...) The list of ``essential services''---i.e., things like instances of -@code{system-service-type} and @code{host-name-service-type} (@pxref{Service -Reference}), which are derived from the operating system definition itself. -As a user you should @emph{never} need to touch this field. +@code{system-service-type} (@pxref{Service Reference}) and +@code{host-name-service-type}, which are derived from the operating +system definition itself. As a user you should @emph{never} need to +touch this field. @item @code{pam-services} (default: @code{(base-pam-services)}) @cindex PAM @@ -18018,9 +18020,11 @@ symlink: @end lisp @end deffn -@deffn {Scheme Procedure} host-name-service @var{name} -Return a service that sets the host name to @var{name}. -@end deffn +@defvar host-name-service-type +Type of the service that sets the system host name, whose value +is a string. This service is included in @code{operating-system} by +default (@pxref{operating-system-essential-services,@code{essential-services}}). +@end defvar @defvar console-font-service-type Install the given fonts on the specified ttys (fonts are per -- cgit 1.4.1 From 6dd635b4cf7a65560056c1089982fe00f73e6468 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:48 +0000 Subject: services: base: Deprecate 'login-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Base Services): Replace with login-service-type. * gnu/services/base.scm (login-service): Deprecate procedure. * gnu/system/install.scm (%installation-services): Use login-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 12 ++++++------ gnu/services/base.scm | 5 +++-- gnu/system/install.scm | 5 +++-- 3 files changed, 12 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 537b8e19f5..0d205555c1 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18101,14 +18101,14 @@ Return a new record for the host at @var{address} with the given host names. @end defun -@deffn {Scheme Procedure} login-service @var{config} -Return a service to run login according to @var{config}, a -@code{} object, which specifies the message of the day, -among other things. -@end deffn +@defvar login-service-type +Type of the service that provides a console login service, whose value +is a @code{} object. +@end defvar @deftp {Data Type} login-configuration -This is the data type representing the configuration of login. +Data type representing the configuration of login, which specifies the +@acronym{MOTD, message of the day}, among other things. @table @asis diff --git a/gnu/services/base.scm b/gnu/services/base.scm index c471107883..8dfd92aacf 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -158,7 +158,7 @@ login-configuration login-configuration? login-service-type - login-service + login-service ; deprecated agetty-configuration agetty-configuration? @@ -937,7 +937,8 @@ Return a service that sets up Unicode support in @var{tty} and loads "Provide a console log-in service as specified by its configuration value, a @code{login-configuration} object."))) -(define* (login-service #:optional (config (login-configuration))) +(define-deprecated (login-service #:optional (config (login-configuration))) + login-service-type "Return a service configure login according to @var{config}, which specifies the message of the day, among other things." (service login-service-type config)) diff --git a/gnu/system/install.scm b/gnu/system/install.scm index b3cf7a1bd8..8c7585f188 100644 --- a/gnu/system/install.scm +++ b/gnu/system/install.scm @@ -347,8 +347,9 @@ Access documentation at any time by pressing Alt-F2.\x1b[0m (virtual-terminal "tty1") (login-program (installer-program)))) - (login-service (login-configuration - (motd motd))) + (service login-service-type + (login-configuration + (motd motd))) ;; Documentation. The manual is in UTF-8, but ;; 'console-font-service' sets up Unicode support and loads a font -- cgit 1.4.1 From ad665a38fc18ed7a6b8efb09086713b0e73e3781 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:49 +0000 Subject: services: base: Deprecate 'mingetty-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Base Services): Replace mingetty-service with mingetty-service-type. * gnu/services/base.scm (mingetty-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 15 +++++++-------- gnu/services/base.scm | 5 +++-- gnu/system/install.scm | 7 ++++--- 3 files changed, 14 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 0d205555c1..06f77639ce 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18123,18 +18123,17 @@ the 'root' account has just been created. @end table @end deftp -@deffn {Scheme Procedure} mingetty-service @var{config} -Return a service to run mingetty according to @var{config}, a -@code{} object, which specifies the tty to run, among -other things. -@end deffn +@defvar mingetty-service-type +Type of the service that runs Mingetty, an implementation of the +virtual console log-in. The value for this service is a +@code{} object. +@end defvar @deftp {Data Type} mingetty-configuration -This is the data type representing the configuration of Mingetty, which -provides the default implementation of virtual console log-in. +Data type representing the configuration of Mingetty, which specifies +the tty to run, among other things. @table @asis - @item @code{tty} The name of the console this Mingetty runs on---e.g., @code{"tty1"}. diff --git a/gnu/services/base.scm b/gnu/services/base.scm index 8dfd92aacf..c762485054 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -173,7 +173,7 @@ mingetty-configuration-clear-on-logout? mingetty-configuration-mingetty mingetty-configuration? - mingetty-service + mingetty-service ; deprecated mingetty-service-type %nscd-default-caches @@ -1275,7 +1275,8 @@ the tty to run, among other things." "Provide console login using the @command{mingetty} program."))) -(define* (mingetty-service config) +(define-deprecated (mingetty-service config) + mingetty-service-type "Return a service to run mingetty according to @var{config}, which specifies the tty to run, among other things." (service mingetty-service-type config)) diff --git a/gnu/system/install.scm b/gnu/system/install.scm index 8c7585f188..1b05a862c6 100644 --- a/gnu/system/install.scm +++ b/gnu/system/install.scm @@ -331,9 +331,10 @@ Using this shell, you can carry out the installation process \"manually.\" Access documentation at any time by pressing Alt-F2.\x1b[0m "))) (define (normal-tty tty) - (mingetty-service (mingetty-configuration (tty tty) - (auto-login "root") - (login-pause? #t)))) + (service mingetty-service-type + (mingetty-configuration (tty tty) + (auto-login "root") + (login-pause? #t)))) (define bare-bones-os (load "examples/bare-bones.tmpl")) -- cgit 1.4.1 From 4892c0186eec75253701c5097803b6168a2956ce Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:50 +0000 Subject: services: base: Deprecate 'agetty-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Base Services): Replace agetty-service with agetty-service-type. * gnu/services/base.scm (agetty-service): Deprecate procedure. * gnu/system/examples/beaglebone-black.tmpl (operating-system)[services]: Use agetty-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 17 ++++++++--------- gnu/services/base.scm | 5 +++-- gnu/system/examples/beaglebone-black.tmpl | 14 +++++++------- 3 files changed, 18 insertions(+), 18 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 06f77639ce..de7b61432e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18160,19 +18160,18 @@ The Mingetty package to use. @end table @end deftp -@deffn {Scheme Procedure} agetty-service @var{config} -Return a service to run agetty according to @var{config}, an -@code{} object, which specifies the tty to run, -among other things. -@end deffn +@defvar agetty-service-type +Type of the service that runs agetty, which implements virtual and +serial console log-in. The value for this service is a +@code{} object. +@end defvar @deftp {Data Type} agetty-configuration -This is the data type representing the configuration of agetty, which -implements virtual and serial console log-in. See the @code{agetty(8)} -man page for more information. +Data type representing the configuration of agetty, which specifies the +tty to run, among other things@footnote{See the @code{agetty(8)} +man page for more information.}. @table @asis - @item @code{tty} The name of the console this agetty runs on, as a string---e.g., @code{"ttyS0"}. This argument is optional, it will default to diff --git a/gnu/services/base.scm b/gnu/services/base.scm index c762485054..c5fd0cf5b4 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -162,7 +162,7 @@ agetty-configuration agetty-configuration? - agetty-service + agetty-service ; deprecated agetty-service-type mingetty-configuration @@ -1210,7 +1210,8 @@ to use as the tty. This is primarily useful for headless systems." "Provide console login using the @command{agetty} program."))) -(define* (agetty-service config) +(define-deprecated (agetty-service config) + agetty-service-type "Return a service to run agetty according to @var{config}, which specifies the tty to run, among other things." (service agetty-service-type config)) diff --git a/gnu/system/examples/beaglebone-black.tmpl b/gnu/system/examples/beaglebone-black.tmpl index 40d0a76a37..18bbb2723c 100644 --- a/gnu/system/examples/beaglebone-black.tmpl +++ b/gnu/system/examples/beaglebone-black.tmpl @@ -48,10 +48,10 @@ (services (append (list (service dhcp-client-service-type) ;; mingetty does not work on serial lines. ;; Use agetty with board-specific serial parameters. - (agetty-service - (agetty-configuration - (extra-options '("-L")) - (baud-rate "115200") - (term "vt100") - (tty "ttyO0")))) - %base-services))) + (service agetty-service-type + (agetty-configuration + (extra-options '("-L")) + (baud-rate "115200") + (term "vt100") + (tty "ttyO0")))) + %base-services))) -- cgit 1.4.1 From 5bd5e772812e735edc54ef2b321a75cebb7ebd0b Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:51 +0000 Subject: doc: kmscon-service-type: Use @defvar @-command. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Base Services): Use @defvar @-command for kmscon-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index de7b61432e..c0932804dd 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18342,18 +18342,17 @@ The option can be used to provides extra shepherd requirements (for example @end table @end deftp -@deffn {Scheme Procedure} kmscon-service-type @var{config} -Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} -according to @var{config}, a @code{} object, which -specifies the tty to run, among other things. -@end deffn +@defvar kmscon-service-type +Type of the service that runs @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}, +which implements virtual console log-in. The value for this service is a +@code{} object. +@end defvar @deftp {Data Type} kmscon-configuration -This is the data type representing the configuration of Kmscon, which -implements virtual console log-in. +Data type representing the configuration of Kmscon, which specifies the +tty to run, among other things. @table @asis - @item @code{virtual-terminal} The name of the console this Kmscon runs on---e.g., @code{"tty1"}. -- cgit 1.4.1 From 98e9dc6ab7f66203fa9a921605ef7de0ff038e11 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:52 +0000 Subject: services: base: Deprecate 'nscd-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Application Setup): Compress @cindex entries. (Base Services): Compress @cindex entries. Delete %nscd-default-configuration. Replace 'nscd-service' with 'nscd-service-type'. * gnu/services/base.scm (%nscd-default-configuration): Deprecate variable. (nscd-service): Deprecate procedure. * gnu/system/install.scm (%installation-services): Use nscd-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 25 +++++++------------------ gnu/services/base.scm | 12 +++++++----- gnu/system/install.scm | 5 +++-- 3 files changed, 17 insertions(+), 25 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index c0932804dd..e849728b4e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1976,8 +1976,7 @@ versions may be incompatible. @cindex name service switch, glibc @cindex NSS (name service switch), glibc -@cindex nscd (name service caching daemon) -@cindex name service caching daemon (nscd) +@cindex @abbr{nscd, name service cache daemon} When using Guix on a foreign distro, we @emph{strongly recommend} that the system run the GNU C library's @dfn{name service cache daemon}, @command{nscd}, which should be listening on the @@ -18390,20 +18389,17 @@ The Kmscon package to use. @end table @end deftp -@cindex name service cache daemon -@cindex nscd -@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @ - [#:name-services '()] -Return a service that runs the libc name service cache daemon (nscd) with the -given @var{config}---an @code{} object. @xref{Name -Service Switch}, for an example. +@cindex @abbr{nscd, name service cache daemon} +@defvar nscd-service-type +Type of the service that runs the libc @abbr{nscd, name service cache +daemon}, whose value is a @code{} object. For convenience, the Shepherd service for nscd provides the following actions: @table @code @item invalidate -@cindex cache invalidation, nscd @cindex nscd, cache invalidation +@cindex cache invalidation, nscd This invalidate the given cache. For instance, running: @example @@ -18417,17 +18413,10 @@ invalidates the host name lookup cache of nscd. Running @command{herd statistics nscd} displays information about nscd usage and caches. @end table - -@end deffn - -@defvar %nscd-default-configuration -This is the default @code{} value (see below) used -by @code{nscd-service}. It uses the caches defined by -@code{%nscd-default-caches}; see below. @end defvar @deftp {Data Type} nscd-configuration -This is the data type representing the name service cache daemon (nscd) +Data type representing the @abbr{nscd, name service cache daemon} configuration. @table @asis diff --git a/gnu/services/base.scm b/gnu/services/base.scm index c5fd0cf5b4..423a38e39d 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -177,7 +177,7 @@ mingetty-service-type %nscd-default-caches - %nscd-default-configuration + %nscd-default-configuration ; deprecated nscd-configuration nscd-configuration? @@ -186,7 +186,7 @@ nscd-cache? nscd-service-type - nscd-service + nscd-service ; deprecated syslog-configuration syslog-configuration? @@ -1343,7 +1343,8 @@ the tty to run, among other things." (check-files? #t) ;check /etc/services changes (persistent? #t)))) -(define %nscd-default-configuration +(define-deprecated %nscd-default-configuration + #f ;; Default nscd configuration. (nscd-configuration)) @@ -1497,13 +1498,14 @@ the tty to run, among other things." (name-services (append (nscd-configuration-name-services config) name-services))))) - (default-value %nscd-default-configuration) + (default-value (nscd-configuration)) (description "Runs libc's @dfn{name service cache daemon} (nscd) with the given configuration---an @code{} object. @xref{Name Service Switch}, for an example."))) -(define* (nscd-service #:optional (config %nscd-default-configuration)) +(define-deprecated (nscd-service #:optional (config (nscd-configuration))) + nscd-service-type "Return a service that runs libc's name service cache daemon (nscd) with the given @var{config}---an @code{} object. @xref{Name Service Switch}, for an example." diff --git a/gnu/system/install.scm b/gnu/system/install.scm index 1b05a862c6..f7de0d6a09 100644 --- a/gnu/system/install.scm +++ b/gnu/system/install.scm @@ -426,8 +426,9 @@ Access documentation at any time by pressing Alt-F2.\x1b[0m ;; Since this is running on a USB stick with a overlayfs as the root ;; file system, use an appropriate cache configuration. - (nscd-service (nscd-configuration - (caches %nscd-minimal-caches))) + (service nscd-service-type + (nscd-configuration + (caches %nscd-minimal-caches))) ;; Having /bin/sh is a good idea. In particular it allows Tramp ;; connections to this system to work. -- cgit 1.4.1 From 6edacf249110ce9e59dc44f330d7f03ecd7c60d8 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:53 +0000 Subject: services: base: Deprecate 'syslog-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Base Services): Replace syslog-service with syslog-service-type. * gnu/services/base.scm (%default-syslog.conf): Place before . (syslog-service-type): Set default value. (syslog-service): Deprecate procedure. (%base-services): Use syslog-service-type. * gnu/system/hurd.scm (%base-services/hurd): Ditto. * gnu/system/install.scm (%installation-services): Ditto. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 19 +++++++--------- gnu/services/base.scm | 61 +++++++++++++++++++++++++------------------------- gnu/system/hurd.scm | 2 +- gnu/system/install.scm | 2 +- 4 files changed, 41 insertions(+), 43 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index e849728b4e..7b4ecf9e81 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18494,11 +18494,15 @@ privacy---often the result of host name lookups is in local cache, so external name servers do not even need to be queried. @end defvar -@anchor{syslog-configuration-type} @cindex syslog @cindex logging +@defvar syslog-service-type +Type of the service that runs the syslog daemon, whose value is a +@code{} object. +@end defvar + @deftp {Data Type} syslog-configuration -This data type represents the configuration of the syslog daemon. +Data type representing the configuration of the syslog daemon. @table @asis @item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")}) @@ -18506,19 +18510,12 @@ The syslog daemon to use. @item @code{config-file} (default: @code{%default-syslog.conf}) The syslog configuration file to use. +@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more +information on the configuration file syntax. @end table @end deftp -@anchor{syslog-service} -@cindex syslog -@deffn {Scheme Procedure} syslog-service @var{config} -Return a service that runs a syslog daemon according to @var{config}. - -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more -information on the configuration file syntax. -@end deffn - @defvar guix-service-type This is the type of the service that runs the build daemon, @command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a diff --git a/gnu/services/base.scm b/gnu/services/base.scm index 423a38e39d..45e6c5f448 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -190,7 +190,7 @@ syslog-configuration syslog-configuration? - syslog-service + syslog-service ; deprecated syslog-service-type %default-syslog.conf @@ -1511,6 +1511,32 @@ given @var{config}---an @code{} object. @xref{Name Service Switch}, for an example." (service nscd-service-type config)) +;; Snippet adapted from the GNU inetutils manual. +(define %default-syslog.conf + (plain-file "syslog.conf" " + # Log all error messages, authentication messages of + # level notice or higher and anything of level err or + # higher to the console. + # Don't log private authentication messages! + *.alert;auth.notice;authpriv.none -/dev/console + + # Log anything (except mail) of level info or higher. + # Don't log private authentication messages! + *.info;mail.none;authpriv.none -/var/log/messages + + # Log \"debug\"-level entries and nothing else. + *.=debug -/var/log/debug + + # Same, in a different place. + *.info;mail.none;authpriv.none -/dev/tty12 + + # The authpriv file has restricted access. + # 'fsync' the file after each line (hence the lack of a leading dash). + authpriv.* /var/log/secure + + # Log all the mail messages in one place. + mail.* -/var/log/maillog +")) (define-record-type* syslog-configuration make-syslog-configuration @@ -1540,37 +1566,12 @@ Service Switch}, for an example." (umask mask) pid)))) (stop #~(make-kill-destructor)))) + (syslog-configuration) (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 - (plain-file "syslog.conf" " - # Log all error messages, authentication messages of - # level notice or higher and anything of level err or - # higher to the console. - # Don't log private authentication messages! - *.alert;auth.notice;authpriv.none -/dev/console - - # Log anything (except mail) of level info or higher. - # Don't log private authentication messages! - *.info;mail.none;authpriv.none -/var/log/messages - - # Log \"debug\"-level entries and nothing else. - *.=debug -/var/log/debug - - # Same, in a different place. - *.info;mail.none;authpriv.none -/dev/tty12 - - # The authpriv file has restricted access. - # 'fsync' the file after each line (hence the lack of a leading dash). - authpriv.* /var/log/secure - - # Log all the mail messages in one place. - mail.* -/var/log/maillog -")) - -(define* (syslog-service #:optional (config (syslog-configuration))) +(define-deprecated (syslog-service #:optional (config (syslog-configuration))) + syslog-service-type "Return a service that runs @command{syslogd} and takes @var{} as a parameter. @@ -3294,7 +3295,7 @@ login manager daemon.") (cons tty %default-console-font)) '("tty1" "tty2" "tty3" "tty4" "tty5" "tty6"))) - (syslog-service) + (service syslog-service-type) (service agetty-service-type (agetty-configuration (extra-options '("-L")) ; no carrier detect (term "vt100") diff --git a/gnu/system/hurd.scm b/gnu/system/hurd.scm index 24fc6dbcae..20dc4ae735 100644 --- a/gnu/system/hurd.scm +++ b/gnu/system/hurd.scm @@ -93,7 +93,7 @@ `(("/bin/sh" ,(file-append bash "/bin/sh")) ("/usr/bin/env" ,(file-append coreutils "/bin/env")))) - (syslog-service)) + (service syslog-service-type)) (map (lambda (n) (service hurd-getty-service-type (hurd-getty-configuration diff --git a/gnu/system/install.scm b/gnu/system/install.scm index f7de0d6a09..8c7752df0e 100644 --- a/gnu/system/install.scm +++ b/gnu/system/install.scm @@ -367,7 +367,7 @@ Access documentation at any time by pressing Alt-F2.\x1b[0m (normal-tty "tty6") ;; The usual services. - (syslog-service) + (service syslog-service-type) ;; Use the Avahi daemon to discover substitute servers on the local ;; network. It can be faster than fetching from remote servers. -- cgit 1.4.1 From 2e7516168e7b27d1ad3cee60d337d2ad98fb09ff Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:54 +0000 Subject: services: base: Deprecate 'udev-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Base Services): Replace udev-service with udev-service-type. Document . Use @defun @-commands for udev-rules-service, udev-rule and file->udev-rule. * gnu/services/base.scm (udev-service): Deprecate procedure. * gnu/system/install.scm (%installation-services): Use udev-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 52 ++++++++++++++++++++++++++++++++------------------ gnu/services/base.scm | 5 +++-- gnu/system/install.scm | 4 +++- 3 files changed, 39 insertions(+), 22 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 7b4ecf9e81..f4bfb8a24f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18675,15 +18675,30 @@ A list of file-like objects or strings pointing to additional directories the bu @end table @end deftp -@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}] -Run @var{udev}, which populates the @file{/dev} directory dynamically. -udev rules can be provided as a list of files through the @var{rules} -variable. The procedures @code{udev-rule}, @code{udev-rules-service} -and @code{file->udev-rule} from @code{(gnu services base)} simplify the -creation of such rule files. -@end deffn +@defvar udev-service-type +Type of the service that runs udev, a service which populates the +@file{/dev} directory dynamically, whose value is a +@code{} object. + +This service type can be @emph{extended} using procedures +@code{udev-rules-service} along with @code{file->udev-rule} or +@code{udev-rule} which simplify the process of writing udev rules. +@end defvar -@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}] +@deftp {Data Type} udev-configuration +Data type representing the configuration of udev. + +@table @asis +@item @code{udev} (default: @code{eudev}) (type: file-like) +Package object of the udev service. + +@item @code{rules} (default: @var{'()}) (type: list-of-file-like) +List of file-like objects denoting udev-rule files. + +@end table +@end deftp + +@defun udev-rule @var{file-name} @var{contents} Return a udev-rule file named @var{file-name} containing the rules defined by the @var{contents} literal. @@ -18699,18 +18714,17 @@ upon detecting a USB device with a given product identifier. "ATTR@{product@}==\"Example\", " "RUN+=\"/path/to/script\""))) @end lisp -@end deffn +@end defun -@deffn {Scheme Procedure} udev-rules-service [@var{name} @var{rules}] @ - [#:groups @var{groups}] -Return a service that extends @code{udev-service-type } with @var{rules} +@defun udev-rules-service @var{name} @var{rules} [#:groups '()] +Return a service that extends @code{udev-service-type} with @var{rules} and @code{account-service-type} with @var{groups} as system groups. This works by creating a singleton service type @code{@var{name}-udev-rules}, of which the returned service is an instance. -Here we show how it can be used to extend @code{udev-service-type} with the -previously defined rule @code{%example-udev-rule}. +Here we show how it can be used to extend @code{udev-service-type} +with the previously defined rule @code{%example-udev-rule}. @lisp (operating-system @@ -18719,11 +18733,11 @@ previously defined rule @code{%example-udev-rule}. (cons (udev-rules-service 'usb-thing %example-udev-rule) %desktop-services))) @end lisp -@end deffn +@end defun -@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}] -Return a udev file named @var{file-name} containing the rules defined -within @var{file}, a file-like object. +@defun file->udev-rule @var{file-name} @var{file} +Return a udev-rule file named @var{file-name} containing the rules +defined within @var{file}, a file-like object. The following example showcases how we can use an existing rule file. @@ -18743,7 +18757,7 @@ The following example showcases how we can use an existing rule file. (sha256 (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003")))))) @end lisp -@end deffn +@end defun Additionally, Guix package definitions can be included in @var{rules} in order to extend the udev rules with the definitions found under their diff --git a/gnu/services/base.scm b/gnu/services/base.scm index 45e6c5f448..b183cf58c1 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -150,7 +150,7 @@ udev-configuration? udev-configuration-rules udev-service-type - udev-service + udev-service ; deprecated udev-rule file->udev-rule udev-rules-service @@ -2351,7 +2351,8 @@ item of @var{packages}." directory dynamically. Get extra rules from the packages listed in the @code{rules} field of its value, @code{udev-configuration} object."))) -(define* (udev-service #:key (udev eudev) (rules '())) +(define-deprecated (udev-service #:key (udev eudev) (rules '())) + udev-service-type "Run @var{udev}, which populates the @file{/dev} directory dynamically. Get extra rules from the packages listed in @var{rules}." (service udev-service-type diff --git a/gnu/system/install.scm b/gnu/system/install.scm index 8c7752df0e..dd965f312b 100644 --- a/gnu/system/install.scm +++ b/gnu/system/install.scm @@ -388,7 +388,9 @@ Access documentation at any time by pressing Alt-F2.\x1b[0m ;; Start udev so that useful device nodes are available. ;; Use device-mapper rules for cryptsetup & co; enable the CRDA for ;; regulations-compliant WiFi access. - (udev-service #:rules (list lvm2 crda)) + (service udev-service-type + (udev-configuration + (rules (list lvm2 crda)))) ;; Add the 'cow-store' service, which users have to start manually ;; since it takes the installation directory as an argument. -- cgit 1.4.1 From 31b1e229268683826524cb93dd2da8d46dd77343 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:55 +0000 Subject: services: base: Deprecate 'rngd-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Base Services): Replace rngd-service with rngd-service-type. Document . * gnu/services/base.scm (): Set default values from the values in the now deprecated 'rngd-service' procedure. (rngd-service): Deprecate procedure. (rngd-service-type): Set default value. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 25 ++++++++++++++++++------- gnu/services/base.scm | 15 +++++++++------ 2 files changed, 27 insertions(+), 13 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index f4bfb8a24f..1edbad33c6 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -18919,13 +18919,24 @@ seconds for the negative lookups. @xref{Invoking guix publish, @end table @end deftp -@anchor{rngd-service} -@deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @ - [#:device "/dev/hwrng"] -Return a service that runs the @command{rngd} program from @var{rng-tools} -to add @var{device} to the kernel's entropy pool. The service will fail if -@var{device} does not exist. -@end deffn +@defvar rngd-service-type +Type of the service that runs rng-tools rngd, whose value is a +@code{} object. +@end defvar + +@deftp {Data Type} rngd-configuration +Data type representing the configuration of rngd. + +@table @asis +@item @code{rng-tools} (default: @code{rng-tools}) (type: file-like) +Package object of the rng-tools rngd. + +@item @code{device} (default: @var{"/dev/hwrng"}) (type: string) +Path of the device to add to the kernel's entropy pool. The service +will fail if @var{device} does not exist. + +@end table +@end deftp @anchor{pam-limits-service} @cindex session limits diff --git a/gnu/services/base.scm b/gnu/services/base.scm index b183cf58c1..1423ab6767 100644 --- a/gnu/services/base.scm +++ b/gnu/services/base.scm @@ -239,7 +239,7 @@ rngd-configuration rngd-configuration? rngd-service-type - rngd-service + rngd-service ; deprecated kmscon-configuration kmscon-configuration? @@ -662,8 +662,10 @@ down."))) (define-record-type* rngd-configuration make-rngd-configuration rngd-configuration? - (rng-tools rngd-configuration-rng-tools) ;file-like - (device rngd-configuration-device)) ;string + (rng-tools rngd-configuration-rng-tools ;file-like + (default rng-tools)) + (device rngd-configuration-device ;string + (default "/dev/hwrng"))) (define rngd-service-type (shepherd-service-type @@ -682,12 +684,13 @@ down."))) (provision '(trng)) (start #~(make-forkexec-constructor '#$rngd-command)) (stop #~(make-kill-destructor)))) + (rngd-configuration) (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) - (device "/dev/hwrng")) +(define-deprecated (rngd-service #:key (rng-tools rng-tools) + (device "/dev/hwrng")) + rngd-service-type "Return a service that runs the @command{rngd} program from @var{rng-tools} to add @var{device} to the kernel's entropy pool. The service will fail if @var{device} does not exist." -- cgit 1.4.1 From 0e21015fd2214aade16de35ce5a79bcc192530c7 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:58 +0000 Subject: services: ssh: Deprecate 'lsh-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Networking Services): Remove mention of lsh-service. Document lsh-service-type and lsh-service-configuration. * gnu/services/ssh.scm (): Set default values based on the now deprecated 'lsh-service' procedure. (lsh-service-type): Set default value. (lsh-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 98 ++++++++++++++++++++++++++++++++++------------------ gnu/services/ssh.scm | 68 ++++++++++++++++++++++-------------- 2 files changed, 106 insertions(+), 60 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 1edbad33c6..9c30e97466 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -20725,41 +20725,71 @@ Furthermore, @code{(gnu services ssh)} provides the following services. @cindex SSH @cindex SSH server -@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ - [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @ - [#:allow-empty-passwords? #f] [#:root-login? #f] @ - [#:syslog-output? #t] [#:x11-forwarding? #t] @ - [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @ - [#:public-key-authentication? #t] [#:initialize? #t] -Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}. -@var{host-key} must designate a file containing the host key, and readable -only by root. - -When @var{daemonic?} is true, @command{lshd} will detach from the -controlling terminal and log its output to syslogd, unless one sets -@var{syslog-output?} to false. Obviously, it also makes lsh-service -depend on existence of syslogd service. When @var{pid-file?} is true, -@command{lshd} writes its PID to the file called @var{pid-file}. - -When @var{initialize?} is true, automatically create the seed and host key -upon service activation if they do not exist yet. This may take long and -require interaction. - -When @var{initialize?} is false, it is up to the user to initialize the -randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create -a key pair with the private key stored in file @var{host-key} (@pxref{lshd -basics,,, lsh, LSH Manual}). - -When @var{interfaces} is empty, lshd listens for connections on all the -network interfaces; otherwise, @var{interfaces} must be a list of host names -or addresses. - -@var{allow-empty-passwords?} specifies whether to accept log-ins with empty -passwords, and @var{root-login?} specifies whether to accept log-ins as -root. +@defvar lsh-service-type +Type of the service that runs the GNU@tie{}lsh secure shell (SSH) +daemon, @command{lshd}. The value for this service is a +@code{} object. +@end defvar -The other options should be self-descriptive. -@end deffn +@deftp {Data Type} lsh-configuration +Data type representing the configuration of @command{lshd}. + +@table @asis +@item @code{lsh} (default: @code{lsh}) (type: file-like) +The package object of the GNU@tie{}lsh secure shell (SSH) daemon. + +@item @code{daemonic?} (default: @code{#t}) (type: boolean) +Whether to detach from the controlling terminal. + +@item @code{host-key} (default: @code{"/etc/lsh/host-key"}) (type: string) +File containing the @dfn{host key}. This file must be readable by +root only. + +@item @code{interfaces} (default: @code{()}) (type: list) +List of host names or addresses that @command{lshd} will listen on. +If empty, @command{lshd} listens for connections on all the network +interfaces. + +@item @code{port-number} (default: @code{22}) (type: integer) +Port to listen on. + +@item @code{allow-empty-passwords?} (default: @code{#f}) (type: boolean) +Whether to accept log-ins with empty passwords. + +@item @code{root-login?} (default: @code{#f}) (type: boolean) +Whether to accept log-ins as root. + +@item @code{syslog-output?} (default: @code{#t}) (type: boolean) +Whether to log @command{lshd} standard output to syslogd. +This will make the service depend on the existence of a syslogd service. + +@item @code{pid-file?} (default: @code{#f}) (type: boolean) +When @code{#t}, @command{lshd} writes its PID to the file specified in +@var{pid-file}. + +@item @code{pid-file} (default: @code{"/var/run/lshd.pid"}) (type: string) +File that @command{lshd} will write its PID to. + +@item @code{x11-forwarding?} (default: @code{#t}) (type: boolean) +Whether to enable X11 forwarding. + +@item @code{tcp/ip-forwarding?} (default: @code{#t}) (type: boolean) +Whether to enable TCP/IP forwarding. + +@item @code{password-authentication?} (default: @code{#t}) (type: boolean) +Whether to accept log-ins using password authentication. + +@item @code{public-key-authentication?} (default: @code{#t}) (type: boolean) +Whether to accept log-ins using public key authentication. + +@item @code{initialize?} (default: @code{#t}) (type: boolean) +When @code{#f}, it is up to the user to initialize the randomness +generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create +a key pair with the private key stored in file @var{host-key} +(@pxref{lshd basics,,, lsh, LSH Manual}). + +@end table +@end deftp @cindex SSH @cindex SSH server diff --git a/gnu/services/ssh.scm b/gnu/services/ssh.scm index 7b038e6ac6..3baa55731d 100644 --- a/gnu/services/ssh.scm +++ b/gnu/services/ssh.scm @@ -42,7 +42,7 @@ #:use-module (ice-9 vlist) #:export (lsh-configuration lsh-configuration? - lsh-service + lsh-service ; deprecated lsh-service-type openssh-configuration @@ -74,20 +74,34 @@ lsh-configuration? (lsh lsh-configuration-lsh (default lsh)) - (daemonic? lsh-configuration-daemonic?) - (host-key lsh-configuration-host-key) - (interfaces lsh-configuration-interfaces) - (port-number lsh-configuration-port-number) - (allow-empty-passwords? lsh-configuration-allow-empty-passwords?) - (root-login? lsh-configuration-root-login?) - (syslog-output? lsh-configuration-syslog-output?) - (pid-file? lsh-configuration-pid-file?) - (pid-file lsh-configuration-pid-file) - (x11-forwarding? lsh-configuration-x11-forwarding?) - (tcp/ip-forwarding? lsh-configuration-tcp/ip-forwarding?) - (password-authentication? lsh-configuration-password-authentication?) - (public-key-authentication? lsh-configuration-public-key-authentication?) - (initialize? lsh-configuration-initialize?)) + (daemonic? lsh-configuration-daemonic? + (default #t)) + (host-key lsh-configuration-host-key + (default "/etc/lsh/host-key")) + (interfaces lsh-configuration-interfaces + (default '())) + (port-number lsh-configuration-port-number + (default 22)) + (allow-empty-passwords? lsh-configuration-allow-empty-passwords? + (default #f)) + (root-login? lsh-configuration-root-login? + (default #f)) + (syslog-output? lsh-configuration-syslog-output? + (default #t)) + (pid-file? lsh-configuration-pid-file? + (default #f)) + (pid-file lsh-configuration-pid-file + (default "/var/run/lshd.pid")) + (x11-forwarding? lsh-configuration-x11-forwarding? + (default #t)) + (tcp/ip-forwarding? lsh-configuration-tcp/ip-forwarding? + (default #t)) + (password-authentication? lsh-configuration-password-authentication? + (default #t)) + (public-key-authentication? lsh-configuration-public-key-authentication? + (default #t)) + (initialize? lsh-configuration-initialize? + (default #t))) (define %yarrow-seed "/var/spool/lsh/yarrow-seed-file") @@ -203,19 +217,20 @@ (lsh-configuration-allow-empty-passwords? config)))) (define lsh-service-type - (service-type (name 'lsh) - (description - "Run the GNU@tie{}lsh secure shell (SSH) daemon, + (service-type + (name 'lsh) + (extensions + (list (service-extension shepherd-root-service-type + lsh-shepherd-service) + (service-extension pam-root-service-type + lsh-pam-services) + (service-extension activation-service-type + lsh-activation))) + (description "Run the GNU@tie{}lsh secure shell (SSH) daemon, @command{lshd}.") - (extensions - (list (service-extension shepherd-root-service-type - lsh-shepherd-service) - (service-extension pam-root-service-type - lsh-pam-services) - (service-extension activation-service-type - lsh-activation))))) + (default-value (lsh-configuration)))) -(define* (lsh-service #:key +(define-deprecated (lsh-service #:key (lsh lsh) (daemonic? #t) (host-key "/etc/lsh/host-key") @@ -231,6 +246,7 @@ (password-authentication? #t) (public-key-authentication? #t) (initialize? #t)) + lsh-service-type "Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}. @var{host-key} must designate a file containing the host key, and readable only by root. -- cgit 1.4.1 From 3b2e88011a485293bd11b25466ffbaa8791ec64a Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:57:59 +0000 Subject: services: ssh: Deprecate 'dropbear-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Networking Services): Replace 'dropbear-service' with 'dropbear-service-type'. * gnu/services/ssh.scm (dropbear-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 17 ++++++++--------- gnu/services/ssh.scm | 6 ++++-- 2 files changed, 12 insertions(+), 11 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 9c30e97466..61359183f1 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -20983,19 +20983,18 @@ Match Address 192.168.0.1 @end table @end deftp -@deffn {Scheme Procedure} dropbear-service [@var{config}] -Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH -daemon} with the given @var{config}, a @code{} -object. +@defvar dropbear-service-type +Type of the service that runs the +@url{https://matt.ucc.asn.au/dropbear/dropbear.html, Dropbear SSH daemon}, +whose value is a @code{} object. -For example, to specify a Dropbear service listening on port 1234, add -this call to the operating system's @code{services} field: +For example, to specify a Dropbear service listening on port 1234: @lisp -(dropbear-service (dropbear-configuration - (port-number 1234))) +(service dropbear-service-type (dropbear-configuration + (port-number 1234))) @end lisp -@end deffn +@end defvar @deftp {Data Type} dropbear-configuration This data type represents the configuration of a Dropbear SSH daemon. diff --git a/gnu/services/ssh.scm b/gnu/services/ssh.scm index 3baa55731d..b76544c1a8 100644 --- a/gnu/services/ssh.scm +++ b/gnu/services/ssh.scm @@ -52,7 +52,7 @@ dropbear-configuration dropbear-configuration? dropbear-service-type - dropbear-service + dropbear-service ; deprecated autossh-configuration autossh-configuration? @@ -717,7 +717,9 @@ of user-name/file-like tuples." dropbear-activation))) (default-value (dropbear-configuration)))) -(define* (dropbear-service #:optional (config (dropbear-configuration))) +(define-deprecated (dropbear-service #:optional + (config (dropbear-configuration))) + dropbear-service-type "Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH daemon} with the given @var{config}, a @code{} object." -- cgit 1.4.1 From 00767d967d2f70d53bb7494ac09e0e7c44323697 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:01 +0000 Subject: services: desktop: Deprecate 'elogind-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Desktop Services): Replace 'elogind-service' with 'elogind-service-type'. * gnu/services/desktop.scm (elogind-service): Deprecate procedure. (desktop-services-for-system): Use elogind-service-type. * gnu/tests/lightdm.scm (minimal-desktop-services): Ditto. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 166 ++++++++++++++++++++++++++++------------------- gnu/services/desktop.scm | 7 +- gnu/tests/lightdm.scm | 2 +- 3 files changed, 106 insertions(+), 69 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 61359183f1..e0563f493f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23320,77 +23320,113 @@ and policy files. For example, to allow avahi-daemon to use the system bus, @var{services} must be equal to @code{(list avahi)}. @end deffn -@deffn {Scheme Procedure} elogind-service [#:config @var{config}] -Return a service that runs the @code{elogind} login and -seat management daemon. @uref{https://github.com/elogind/elogind, -Elogind} exposes a D-Bus interface that can be used to know which users +@subsubheading Elogind + +@uref{https://github.com/elogind/elogind, Elogind} is a login and seat +management daemon that also handles most system-level power events for a +computer, for example suspending the system when a lid is closed, or +shutting it down when the power button is pressed. + +It also provides a D-Bus interface that can be used to know which users are logged in, know what kind of sessions they have open, suspend the system, inhibit system suspend, reboot the system, and other tasks. -Elogind handles most system-level power events for a computer, for -example suspending the system when a lid is closed, or shutting it down -when the power button is pressed. +@defvar elogind-service-type +Type of the service that runs @command{elogind}, a login and +seat management daemon. The value for this service is a +@code{} object. +@end defvar -The @var{config} keyword argument specifies the configuration for -elogind, and should be the result of an @code{(elogind-configuration -(@var{parameter} @var{value})...)} invocation. Available parameters and -their default values are: +@c TODO: field descriptions. This is best done by refactoring +@c elogind-configuration to use define-configuration which embeds the +@c descriptions in the code and then use configuration->documentation. +@deftp {Data Type} elogind-configuration +Data type representing the configuration of @command{elogind}. + +@table @asis +@item @code{elogind} (default: @code{elogind}) (type: file-like) +... + +@item @code{kill-user-processes?} (default: @code{#f}) (type: boolean) +... + +@item @code{kill-only-users} (default: @code{'()}) (type: list) +... + +@item @code{kill-exclude-users} (default: @code{'("root")}) (type: list-of-string) +... + +@item @code{inhibit-delay-max-seconds} (default: @code{5}) (type: integer) +... + +@item @code{handle-power-key} (default: @code{'poweroff}) (type: symbol) +... + +@item @code{handle-suspend-key} (default: @code{'suspend}) (type: symbol) +... + +@item @code{handle-hibernate-key} (default: @code{'hibernate}) (type: symbol) +... + +@item @code{handle-lid-switch} (default: @code{'suspend}) (type: symbol) +... + +@item @code{handle-lid-switch-docked} (default: @code{'ignore}) (type: symbol) +... + +@item @code{handle-lid-switch-external-power} (default: @code{*unspecified*}) (type: symbol) +... + +@item @code{power-key-ignore-inhibited?} (default: @code{#f}) (type: boolean) +... + +@item @code{suspend-key-ignore-inhibited?} (default: @code{#f}) (type: boolean) +... + +@item @code{hibernate-key-ignore-inhibited?} (default: @code{#f}) (type: boolean) +... + +@item @code{lid-switch-ignore-inhibited?} (default: @code{#t}) (type: boolean) +... + +@item @code{holdoff-timeout-seconds} (default: @code{30}) (type: integer) +... + +@item @code{idle-action} (default: @code{'ignore}) (type: symbol) +... + +@item @code{idle-action-seconds} (default: @code{(* 30 60)}) (type: integer) +... + +@item @code{runtime-directory-size-percent} (default: @code{10}) (type: integer) +... + +@item @code{runtime-directory-size} (default: @code{#f}) (type: integer) +... + +@item @code{remove-ipc?} (default: @code{#t}) (type: boolean) +... + +@item @code{suspend-state} (default: @code{'("mem" "standby" "freeze")}) (type: list) +... + +@item @code{suspend-mode} (default: @code{'()}) (type: list) +... + +@item @code{hibernate-state} (default: @code{'("disk")}) (type: list) +... + +@item @code{hibernate-mode} (default: @code{'("platform" "shutdown")}) (type: list) +... + +@item @code{hybrid-sleep-state} (default: @code{'("disk")}) (type: list) +... + +@item @code{hybrid-sleep-mode} (default: @code{'("suspend" "platform" "shutdown")}) (type: list) +... -@table @code -@item kill-user-processes? -@code{#f} -@item kill-only-users -@code{()} -@item kill-exclude-users -@code{("root")} -@item inhibit-delay-max-seconds -@code{5} -@item handle-power-key -@code{poweroff} -@item handle-suspend-key -@code{suspend} -@item handle-hibernate-key -@code{hibernate} -@item handle-lid-switch -@code{suspend} -@item handle-lid-switch-docked -@code{ignore} -@item handle-lid-switch-external-power -@code{*unspecified*} -@item power-key-ignore-inhibited? -@code{#f} -@item suspend-key-ignore-inhibited? -@code{#f} -@item hibernate-key-ignore-inhibited? -@code{#f} -@item lid-switch-ignore-inhibited? -@code{#t} -@item holdoff-timeout-seconds -@code{30} -@item idle-action -@code{ignore} -@item idle-action-seconds -@code{(* 30 60)} -@item runtime-directory-size-percent -@code{10} -@item runtime-directory-size -@code{#f} -@item remove-ipc? -@code{#t} -@item suspend-state -@code{("mem" "standby" "freeze")} -@item suspend-mode -@code{()} -@item hibernate-state -@code{("disk")} -@item hibernate-mode -@code{("platform" "shutdown")} -@item hybrid-sleep-state -@code{("disk")} -@item hybrid-sleep-mode -@code{("suspend" "platform" "shutdown")} @end table -@end deffn +@end deftp @deffn {Scheme Procedure} accountsservice-service @ [#:accountsservice @var{accountsservice}] diff --git a/gnu/services/desktop.scm b/gnu/services/desktop.scm index 4724294433..374d47869b 100644 --- a/gnu/services/desktop.scm +++ b/gnu/services/desktop.scm @@ -116,7 +116,7 @@ elogind-configuration elogind-configuration? - elogind-service + elogind-service ; deprecated elogind-service-type %gdm-file-system @@ -1230,7 +1230,8 @@ allow other system components to know the set of logged-in users as well as their session types (graphical, console, remote, etc.). It can also clean up after users when they log out."))) -(define* (elogind-service #:key (config (elogind-configuration))) +(define-deprecated (elogind-service #:key (config (elogind-configuration))) + elogind-service-type "Return a service that runs the @command{elogind} login and seat management service. The @command{elogind} service integrates with PAM to allow other system components to know the set of logged-in users as well as their session @@ -1866,7 +1867,7 @@ applications needing access to be root.") (service colord-service-type) (geoclue-service) (service polkit-service-type) - (elogind-service) + (service elogind-service-type) (dbus-service) (service ntp-service-type) diff --git a/gnu/tests/lightdm.scm b/gnu/tests/lightdm.scm index 57d029a75a..25fa06a9f1 100644 --- a/gnu/tests/lightdm.scm +++ b/gnu/tests/lightdm.scm @@ -48,7 +48,7 @@ (service upower-service-type) (accountsservice-service) (service polkit-service-type) - (elogind-service) + (service elogind-service-type) (dbus-service) x11-socket-directory-service)) -- cgit 1.4.1 From c3dc13e29c624609b851ef50db343074fad2d7cb Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:03 +0000 Subject: services: desktop: Deprecate 'accountsservice-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Desktop Services): Replace 'accountsservice-service' with 'accountsservice-service-type'. * gnu/services/desktop.scm (accountsservice-service): Deprecate procedure. (desktop-services-for-system): Use accountsservice-service-type. * gnu/tests/lightdm.scm (minimal-desktop-services): Ditto. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 15 +++++++-------- gnu/services/desktop.scm | 8 +++++--- gnu/tests/lightdm.scm | 2 +- 3 files changed, 13 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index e0563f493f..0530b9a45b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23428,18 +23428,17 @@ Data type representing the configuration of @command{elogind}. @end table @end deftp -@deffn {Scheme Procedure} accountsservice-service @ - [#:accountsservice @var{accountsservice}] -Return a service that runs AccountsService, a system service that can +@defvar accountsservice-service-type +Type for the service that runs AccountsService, a system service that can list available accounts, change their passwords, and so on. AccountsService integrates with PolicyKit to enable unprivileged users to acquire the capability to modify their system configuration. -@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the -accountsservice web site} for more information. +See @url{https://www.freedesktop.org/wiki/Software/AccountsService/, +AccountsService} for more information. -The @var{accountsservice} keyword argument is the @code{accountsservice} -package to expose as a service. -@end deffn +The value for this service is a file-like object, by default it is +set to @code{accountsservice} (the package object for AccountsService). +@end defvar @deffn {Scheme Procedure} polkit-service @ [#:polkit @var{polkit}] diff --git a/gnu/services/desktop.scm b/gnu/services/desktop.scm index 634b240af2..4a790fbdc4 100644 --- a/gnu/services/desktop.scm +++ b/gnu/services/desktop.scm @@ -126,7 +126,7 @@ fontconfig-file-system-service accountsservice-service-type - accountsservice-service + accountsservice-service ; deprecated cups-pk-helper-service-type sane-service-type @@ -1295,7 +1295,9 @@ over D-Bus that can list available accounts, change their passwords, and so on. AccountsService integrates with PolicyKit to enable unprivileged users to acquire the capability to modify their system configuration."))) -(define* (accountsservice-service #:key (accountsservice accountsservice)) +(define-deprecated + (accountsservice-service #:key (accountsservice accountsservice)) + accountsservice-service-type "Return a service that runs AccountsService, a system service that can list available accounts, change their passwords, and so on. AccountsService integrates with PolicyKit to enable unprivileged users to @@ -1858,7 +1860,7 @@ applications needing access to be root.") (service avahi-service-type) (udisks-service) (service upower-service-type) - (accountsservice-service) + (service accountsservice-service-type) (service cups-pk-helper-service-type) (service colord-service-type) (geoclue-service) diff --git a/gnu/tests/lightdm.scm b/gnu/tests/lightdm.scm index 25fa06a9f1..aa97a96939 100644 --- a/gnu/tests/lightdm.scm +++ b/gnu/tests/lightdm.scm @@ -46,7 +46,7 @@ (define minimal-desktop-services (list polkit-wheel-service (service upower-service-type) - (accountsservice-service) + (service accountsservice-service-type) (service polkit-service-type) (service elogind-service-type) (dbus-service) -- cgit 1.4.1 From ffc5d42fc2589c349579c00e9dd11fabdff2663b Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:04 +0000 Subject: services: dbus: Deprecate 'polkit-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Desktop Services): Replace 'polkit-service' with 'polkit-service-type'. * gnu/services/dbus.scm (polkit-service): Deprecate procedure. * gnu/tests/docker.scm (%docker-os): Use polkit-service-type. * gnu/tests/virtualization.scm (%libvirt-os): Ditto. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 14 +++++++++----- gnu/services/dbus.scm | 6 ++++-- gnu/tests/docker.scm | 2 +- gnu/tests/virtualization.scm | 2 +- 4 files changed, 15 insertions(+), 9 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 0530b9a45b..4ff5622ad3 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23440,16 +23440,20 @@ The value for this service is a file-like object, by default it is set to @code{accountsservice} (the package object for AccountsService). @end defvar -@deffn {Scheme Procedure} polkit-service @ - [#:polkit @var{polkit}] -Return a service that runs the -@uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege +@defvar polkit-service-type +Type for the service that runs the +@url{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege management service}, which allows system administrators to grant access to privileged operations in a structured way. By querying the Polkit service, a privileged system component can know when it should grant additional capabilities to ordinary users. For example, an ordinary user can be granted the capability to suspend the system if the user is logged in locally. -@end deffn + +The value for this service is a @code{} object. +@end defvar + +@c TODO: Document , preferably by refactoring this to use +@c define-configuration and generating documentation from it. @defvar polkit-wheel-service Service that adds the @code{wheel} group as admins to the Polkit diff --git a/gnu/services/dbus.scm b/gnu/services/dbus.scm index 5efd6bdadf..ea2593501f 100644 --- a/gnu/services/dbus.scm +++ b/gnu/services/dbus.scm @@ -28,6 +28,7 @@ #:use-module ((gnu packages glib) #:select (dbus)) #:use-module (gnu packages polkit) #:use-module (gnu packages admin) + #:use-module (guix deprecation) #:use-module (guix gexp) #:use-module ((guix packages) #:select (package-name)) #:use-module (guix records) @@ -43,7 +44,7 @@ polkit-configuration polkit-configuration? polkit-service-type - polkit-service)) + polkit-service)) ; deprecated ;;; ;;; D-Bus. @@ -404,7 +405,8 @@ management service}, which allows system administrators to grant access to privileged operations in a structured way. Polkit is a requirement for most desktop environments, such as GNOME."))) -(define* (polkit-service #:key (polkit polkit)) +(define-deprecated (polkit-service #:key (polkit polkit)) + polkit-service-type "Return a service that runs the @uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege management service}, which allows system administrators to grant access to diff --git a/gnu/tests/docker.scm b/gnu/tests/docker.scm index 4267ff89a8..e464ec587e 100644 --- a/gnu/tests/docker.scm +++ b/gnu/tests/docker.scm @@ -49,7 +49,7 @@ (simple-operating-system (service dhcp-client-service-type) (dbus-service) - (polkit-service) + (service polkit-service-type) (service elogind-service-type) (service docker-service-type))) diff --git a/gnu/tests/virtualization.scm b/gnu/tests/virtualization.scm index 60789fbb5b..6749ade4bd 100644 --- a/gnu/tests/virtualization.scm +++ b/gnu/tests/virtualization.scm @@ -50,7 +50,7 @@ (simple-operating-system (service dhcp-client-service-type) (dbus-service) - (polkit-service) + (service polkit-service-type) (service libvirt-service-type))) (define (run-libvirt-test) -- cgit 1.4.1 From e8f161ea11c24b9812d74e6793f5d7f8e789e170 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:05 +0000 Subject: services: desktop: Deprecate 'udisks-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Desktop Services): Replace 'udisks-service' with 'udisks-service-type'. Document . * gnu/packages/kde-multimedia.scm (k3b)[description]: Replace 'udisks-service' with 'udisks-service-type'. * gnu/services/desktop.scm (udisks-service-type): Set default value. (udisks-service): Deprecate procedure. (desktop-services-for-system): Use udisks-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 21 +++++++++++++++++---- gnu/packages/kde-multimedia.scm | 4 ++-- gnu/services/desktop.scm | 10 ++++++---- 3 files changed, 25 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 4ff5622ad3..659f451933 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23537,9 +23537,10 @@ Possible values are: @end table @end deftp -@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] -Return a service for @uref{https://udisks.freedesktop.org/docs/latest/, -UDisks}, a @dfn{disk management} daemon that provides user interfaces +@defvar udisks-service-type +Type for the service that runs +@uref{https://udisks.freedesktop.org/docs/latest/, UDisks}, +a @dfn{disk management} daemon that provides user interfaces with notifications and ways to mount/unmount disks. Programs that talk to UDisks include the @command{udisksctl} command, part of UDisks, and GNOME Disks. Note that Udisks relies on the @command{mount} command, so @@ -23547,7 +23548,19 @@ it will only be able to use the file-system utilities installed in the system profile. For example if you want to be able to mount NTFS file-systems in read and write fashion, you'll need to have @code{ntfs-3g} installed system-wide. -@end deffn + +The value for this service is a @code{} object. +@end defvar + +@deftp {Data Type} udisks-configuration +Data type representing the configuration for @code{udisks-service-type}. + +@table @asis +@item @code{udisks} (default: @code{udisks}) (type: file-like) +Package object for UDisks. + +@end table +@end deftp @defvar colord-service-type This is the type of the service that runs @command{colord}, a system diff --git a/gnu/packages/kde-multimedia.scm b/gnu/packages/kde-multimedia.scm index d635eca26d..e3de6db432 100644 --- a/gnu/packages/kde-multimedia.scm +++ b/gnu/packages/kde-multimedia.scm @@ -460,8 +460,8 @@ and provide an easily usable interface. Features include burning audio CDs from .WAV and .MP3 audio files, configuring external programs and configuring devices. -The @code{udisks-service} should be enabled for @command{k3b} to discover the -available CD drives.") +The @code{udisks-service-type} should be enabled for @command{k3b} to discover +the available CD drives.") (license ;; GPL for programs, FDL for documentation (list license:gpl2+ license:fdl1.2+)))) diff --git a/gnu/services/desktop.scm b/gnu/services/desktop.scm index 4a790fbdc4..99a3628606 100644 --- a/gnu/services/desktop.scm +++ b/gnu/services/desktop.scm @@ -97,7 +97,7 @@ udisks-configuration udisks-configuration? - udisks-service + udisks-service ; deprecated udisks-service-type colord-service-type @@ -945,9 +945,11 @@ screens and scanners."))) (description "Run UDisks, a @dfn{disk management} daemon that provides user interfaces with notifications and ways to mount/unmount disks. Programs that talk to UDisks include the @command{udisksctl} command, -part of UDisks, and GNOME Disks.")))) +part of UDisks, and GNOME Disks.") + (default-value (udisks-configuration))))) -(define* (udisks-service #:key (udisks udisks)) +(define-deprecated (udisks-service #:key (udisks udisks)) + udisks-service-type "Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, UDisks}, a @dfn{disk management} daemon that provides user interfaces with notifications and ways to mount/unmount disks. Programs that talk to UDisks @@ -1858,7 +1860,7 @@ applications needing access to be root.") ;; The D-Bus clique. (service avahi-service-type) - (udisks-service) + (service udisks-service-type) (service upower-service-type) (service accountsservice-service-type) (service cups-pk-helper-service-type) -- cgit 1.4.1 From ae0975332c60818793c6c63a3646c982d686bf49 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:06 +0000 Subject: services: desktop: Deprecate 'geoclue-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Desktop Services): Replace 'geoclue-service' with 'geoclue-service-type'. * gnu/services/desktop.scm (): Set default values based on the values from the now deprecated geoclue-service procedure. (geoclue-service): Deprecate procedure. (desktop-services-for-system): Use geoclue-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 26 ++++++++++----------- gnu/services/desktop.scm | 61 ++++++++++++++++++++++++++++-------------------- 2 files changed, 48 insertions(+), 39 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 659f451933..74238cc150 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23633,20 +23633,18 @@ IceCat and Epiphany both query the user before allowing a web page to know the user's location. @end defvar -@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @ - [#:whitelist '()] @ - [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @ - [#:submit-data? #f] - [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @ - [#:submission-nick "geoclue"] @ - [#:applications %standard-geoclue-applications] -Return a service that runs the GeoClue location service. This service -provides a D-Bus interface to allow applications to request access to a -user's physical location, and optionally to add information to online -location databases. See -@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue -web site} for more information. -@end deffn +@defvar geoclue-service-type +Type for the service that runs the +@url{https://wiki.freedesktop.org/www/Software/GeoClue/, GeoClue} +location service. This service provides a D-Bus interface to allow +applications to request access to a user's physical location, and +optionally to add information to online location databases. + +The value for this service is a @code{} object. +@end defvar + +@c TODO: Document , preferably by refactoring this to use +@c define-configuration and generating documentation from it. @deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @ [@w{#:auto-enable? #f}] diff --git a/gnu/services/desktop.scm b/gnu/services/desktop.scm index 99a3628606..073e0132e1 100644 --- a/gnu/services/desktop.scm +++ b/gnu/services/desktop.scm @@ -106,7 +106,7 @@ geoclue-configuration geoclue-configuration? %standard-geoclue-applications - geoclue-service + geoclue-service ; deprecated geoclue-service-type bluetooth-service-type @@ -318,19 +318,6 @@ used by GNOME.") ;;; GeoClue D-Bus service. ;;; -;; TODO: Export. -(define-record-type* - geoclue-configuration make-geoclue-configuration - geoclue-configuration? - (geoclue geoclue-configuration-geoclue - (default geoclue)) - (whitelist geoclue-configuration-whitelist) - (wifi-geolocation-url geoclue-configuration-wifi-geolocation-url) - (submit-data? geoclue-configuration-submit-data?) - (wifi-submission-url geoclue-configuration-wifi-submission-url) - (submission-nick geoclue-configuration-submission-nick) - (applications geoclue-configuration-applications)) - (define* (geoclue-application name #:key (allowed? #t) system? (users '())) "Configure default GeoClue access permissions for an application. NAME is the Desktop ID of the application, without the .desktop part. If ALLOWED? is @@ -350,6 +337,28 @@ users are allowed." (geoclue-application "epiphany" #:system? #f) (geoclue-application "firefox" #:system? #f))) +;; TODO: Use define-configuration and export accessors. +(define-record-type* + geoclue-configuration make-geoclue-configuration + geoclue-configuration? + (geoclue geoclue-configuration-geoclue + (default geoclue)) + (whitelist geoclue-configuration-whitelist + (default '())) + (wifi-geolocation-url + geoclue-configuration-wifi-geolocation-url + ;; Mozilla geolocation service: + (default "https://location.services.mozilla.com/v1/geolocate?key=geoclue")) + (submit-data? geoclue-configuration-submit-data? + (default #f)) + (wifi-submission-url + geoclue-configuration-wifi-submission-url + (default "https://location.services.mozilla.com/v1/submit?key=geoclue")) + (submission-nick geoclue-configuration-submission-nick + (default "geoclue")) + (applications geoclue-configuration-applications + (default %standard-geoclue-applications))) + (define* (geoclue-configuration-file config) "Return a geoclue configuration file." (plain-file "geoclue.conf" @@ -397,16 +406,18 @@ This service provides a D-Bus interface to allow applications to request access to a user's physical location, and optionally to add information to online location databases."))) -(define* (geoclue-service #:key (geoclue geoclue) - (whitelist '()) - (wifi-geolocation-url - ;; Mozilla geolocation service: - "https://location.services.mozilla.com/v1/geolocate?key=geoclue") - (submit-data? #f) - (wifi-submission-url - "https://location.services.mozilla.com/v1/submit?key=geoclue") - (submission-nick "geoclue") - (applications %standard-geoclue-applications)) +(define-deprecated + (geoclue-service #:key (geoclue geoclue) + (whitelist '()) + (wifi-geolocation-url + ;; Mozilla geolocation service: + "https://location.services.mozilla.com/v1/geolocate?key=geoclue") + (submit-data? #f) + (wifi-submission-url + "https://location.services.mozilla.com/v1/submit?key=geoclue") + (submission-nick "geoclue") + (applications %standard-geoclue-applications)) + geoclue-service-type "Return a service that runs the @command{geoclue} location service. This service provides a D-Bus interface to allow applications to request access to a user's physical location, and optionally to add information to online @@ -1865,7 +1876,7 @@ applications needing access to be root.") (service accountsservice-service-type) (service cups-pk-helper-service-type) (service colord-service-type) - (geoclue-service) + (service geoclue-service-type) (service polkit-service-type) (service elogind-service-type) (dbus-service) -- cgit 1.4.1 From be1435d6687d6597e09676c2d6edd286cc4d5ad8 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:07 +0000 Subject: services: desktop: Deprecate 'bluetooth-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Desktop Services): Remove mention of 'bluetooth-service'. * gnu/services/desktop.scm (bluetooth-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 9 --------- gnu/services/desktop.scm | 5 +++-- 2 files changed, 3 insertions(+), 11 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 74238cc150..dabd71f18c 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23646,15 +23646,6 @@ The value for this service is a @code{} object. @c TODO: Document , preferably by refactoring this to use @c define-configuration and generating documentation from it. -@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @ - [@w{#:auto-enable? #f}] -Return a service that runs the @command{bluetoothd} daemon, which -manages all the Bluetooth devices and provides a number of D-Bus -interfaces. When AUTO-ENABLE? is true, the bluetooth controller is -powered automatically at boot, which can be useful when using a -bluetooth keyboard or mouse. -@end deffn - @defvar bluetooth-service-type This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf} diff --git a/gnu/services/desktop.scm b/gnu/services/desktop.scm index 073e0132e1..3ec746cdbd 100644 --- a/gnu/services/desktop.scm +++ b/gnu/services/desktop.scm @@ -112,7 +112,7 @@ bluetooth-service-type bluetooth-configuration bluetooth-configuration? - bluetooth-service + bluetooth-service ; deprecated elogind-configuration elogind-configuration? @@ -859,7 +859,8 @@ site} for more information." (description "Run the @command{bluetoothd} daemon, which manages all the Bluetooth devices and provides a number of D-Bus interfaces."))) -(define* (bluetooth-service #:key (bluez bluez) (auto-enable? #f)) +(define-deprecated (bluetooth-service #:key (bluez bluez) (auto-enable? #f)) + bluetooth-service-type "Return a service that runs the @command{bluetoothd} daemon, which manages all the Bluetooth devices and provides a number of D-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller is powered automatically at -- cgit 1.4.1 From c6cbce9ad8ee5fa7b51d8abea83ddc3dd07fa3c6 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:08 +0000 Subject: services: mail: Deprecate 'dovecot-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Mail Services): Replace 'dovecot-service' with 'dovecot-service-type'. * gnu/services/mail.scm (dovecot-service-type): Set default value. (dovecot-service): Deprecate procedure. * gnu/tests/mail.scm (%dovecot-os): Use dovecot-service-type. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 13 +++++++------ gnu/services/mail.scm | 9 ++++++--- gnu/tests/mail.scm | 20 ++++++++++---------- 3 files changed, 23 insertions(+), 19 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index dabd71f18c..af15894d49 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -24709,9 +24709,10 @@ in the subsections below. @subsubheading Dovecot Service -@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)] -Return a service that runs the Dovecot IMAP/POP3/LMTP mail server. -@end deffn +@defvar dovecot-service-type +Type for the service that runs the Dovecot IMAP/POP3/LMTP mail server, +whose value is a @code{} object. +@end defvar By default, Dovecot does not need much configuration; the default configuration object created by @code{(dovecot-configuration)} will @@ -24726,9 +24727,9 @@ For example, to specify that mail is located at @code{maildir~/.mail}, one would instantiate the Dovecot service like this: @lisp -(dovecot-service #:config - (dovecot-configuration - (mail-location "maildir:~/.mail"))) +(service dovecot-service-type + (dovecot-configuration + (mail-location "maildir:~/.mail"))) @end lisp The available configuration parameters follow. Each parameter diff --git a/gnu/services/mail.scm b/gnu/services/mail.scm index 6f588679b1..bf4948dcfb 100644 --- a/gnu/services/mail.scm +++ b/gnu/services/mail.scm @@ -35,6 +35,7 @@ #:use-module (gnu packages admin) #:use-module (gnu packages dav) #:use-module (gnu packages tls) + #:use-module (guix deprecation) #:use-module (guix modules) #:use-module (guix records) #:use-module (guix packages) @@ -42,7 +43,7 @@ #:use-module (ice-9 match) #:use-module (ice-9 format) #:use-module (srfi srfi-1) - #:export (dovecot-service + #:export (dovecot-service ; deprecated dovecot-service-type dovecot-configuration opaque-dovecot-configuration @@ -1601,9 +1602,11 @@ greyed out, instead of only later giving \"not selectable\" popup error. (service-extension activation-service-type %dovecot-activation))) (description "Run Dovecot, a mail server that can run POP3, -IMAP, and LMTP."))) +IMAP, and LMTP.") + (default-value (dovecot-configuration)))) -(define* (dovecot-service #:key (config (dovecot-configuration))) +(define-deprecated (dovecot-service #:key (config (dovecot-configuration))) + dovecot-service-type "Return a service that runs @command{dovecot}, a mail server that can run POP3, IMAP, and LMTP. @var{config} should be a configuration object created by @code{dovecot-configuration}. @var{config} may also be created by diff --git a/gnu/tests/mail.scm b/gnu/tests/mail.scm index f13751b72f..dc1f18b3f1 100644 --- a/gnu/tests/mail.scm +++ b/gnu/tests/mail.scm @@ -293,16 +293,16 @@ acl_check_data: (define %dovecot-os (simple-operating-system (service dhcp-client-service-type) - (dovecot-service #:config - (dovecot-configuration - (disable-plaintext-auth? #f) - (ssl? "no") - (auth-mechanisms '("anonymous")) - (auth-anonymous-username "alice") - (mail-location - (string-append "maildir:~/Maildir" - ":INBOX=~/Maildir/INBOX" - ":LAYOUT=fs")))))) + (service dovecot-service-type + (dovecot-configuration + (disable-plaintext-auth? #f) + (ssl? "no") + (auth-mechanisms '("anonymous")) + (auth-anonymous-username "alice") + (mail-location + (string-append "maildir:~/Maildir" + ":INBOX=~/Maildir/INBOX" + ":LAYOUT=fs")))))) (define (run-dovecot-test) "Return a test of an OS running Dovecot service." -- cgit 1.4.1 From eddd9b1240897caabf64c90549ffa940eef45ce7 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:09 +0000 Subject: services: vpn: Deprecate 'openvpn-client-service' & 'openvpn-server-service' procedures. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (VPN Services): Replace 'openvpn-client-service' & 'openvpn-server-service' procedures with their service-type counterparts. * gnu/services/vpn.scm (openvpn-client-service, openvpn-server-service): Deprecate procedure. (openvpn-server-service-type, openvpn-client-service-type): Set default value. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 22 ++++++++++++---------- gnu/services/vpn.scm | 19 +++++++++++++------ 2 files changed, 25 insertions(+), 16 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index af15894d49..937b85e16c 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -31859,20 +31859,22 @@ desktop-environment or should be run manually. It provides a @emph{client} service for your machine to connect to a VPN, and a @emph{server} service for your machine to host a VPN@. +Both @code{openvpn-client-service-type} and +@code{openvpn-server-service-type} can be run simultaneously. -@deffn {Scheme Procedure} openvpn-client-service @ - [#:config (openvpn-client-configuration)] +@defvar openvpn-client-service-type +Type of the service that runs @command{openvpn}, a VPN daemon, as a client. -Return a service that runs @command{openvpn}, a VPN daemon, as a client. -@end deffn - -@deffn {Scheme Procedure} openvpn-server-service @ - [#:config (openvpn-server-configuration)] +The value for this service is a @code{} +object. +@end defvar -Return a service that runs @command{openvpn}, a VPN daemon, as a server. +@defvar openvpn-server-service-type +Type of the service that runs @command{openvpn}, a VPN daemon, as a server. -Both can be run simultaneously. -@end deffn +The value for this service is a @code{} +object. +@end defvar @c %automatically generated documentation diff --git a/gnu/services/vpn.scm b/gnu/services/vpn.scm index 4103f89ecf..a884d71eb2 100644 --- a/gnu/services/vpn.scm +++ b/gnu/services/vpn.scm @@ -39,11 +39,12 @@ #:use-module (guix records) #:use-module (guix gexp) #:use-module (guix i18n) + #:use-module (guix deprecation) #:use-module (srfi srfi-1) #:use-module (ice-9 match) #:use-module (ice-9 regex) - #:export (openvpn-client-service - openvpn-server-service + #:export (openvpn-client-service ; deprecated + openvpn-server-service ; deprecated openvpn-client-service-type openvpn-server-service-type openvpn-client-configuration @@ -531,7 +532,8 @@ is truncated and rewritten every minute.") (service-extension activation-service-type (const %openvpn-activation)))) (description "Run the OpenVPN server, which allows you to -@emph{host} a @acronym{VPN, virtual private network}."))) +@emph{host} a @acronym{VPN, virtual private network}.") + (default-value (openvpn-server-configuration)))) (define openvpn-client-service-type (service-type (name 'openvpn-client) @@ -544,12 +546,17 @@ is truncated and rewritten every minute.") (const %openvpn-activation)))) (description "Run the OpenVPN client service, which allows you to connect -to an existing @acronym{VPN, virtual private network}."))) +to an existing @acronym{VPN, virtual private network}.") + (default-value (openvpn-client-configuration)))) -(define* (openvpn-client-service #:key (config (openvpn-client-configuration))) +(define-deprecated + (openvpn-client-service #:key (config (openvpn-client-configuration))) + openvpn-client-service-type (service openvpn-client-service-type config)) -(define* (openvpn-server-service #:key (config (openvpn-server-configuration))) +(define-deprecated + (openvpn-server-service #:key (config (openvpn-server-configuration))) + openvpn-server-service-type (service openvpn-server-service-type config)) (define (generate-openvpn-server-documentation) -- cgit 1.4.1 From e24555234a2914ccd2f6291f9ca95f60f137d74f Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:10 +0000 Subject: services: lirc: Deprecate 'lirc-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Miscellaneous Services): Replace 'lirc-service' with 'lirc-service-type'. Document . * gnu/services/lirc.scm (): Set default values based on the arguments from the now deprecated 'lirc-service' procedure. (lirc-service-type): Set default value. (lirc-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 40 +++++++++++++++++++++++++++------------- gnu/services/lirc.scm | 18 ++++++++++++------ 2 files changed, 39 insertions(+), 19 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 937b85e16c..54b75dd1f8 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -37726,24 +37726,38 @@ under @file{pcsc/drivers} in the store directory of the package. @end table @end deftp -@cindex lirc -@subsubheading Lirc Service +@cindex LIRC +@subsubheading LIRC Service The @code{(gnu services lirc)} module provides the following service. -@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ - [#:device #f] [#:driver #f] [#:config-file #f] @ - [#:extra-options '()] -Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that -decodes infrared signals from remote controls. +@defvar lirc-service-type +Type for a service that runs @url{http://www.lirc.org, LIRC}, a daemon +that decodes infrared signals from remote controls. -Optionally, @var{device}, @var{driver} and @var{config-file} -(configuration file name) may be specified. See @command{lircd} manual -for details. +The value for this service is a @code{} object. +@end defvar -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{lircd}. -@end deffn +@deftp {Data Type} lirc-configuration +Data type representing the configuration of @command{lircd}. + +@table @asis +@item @code{lirc} (default: @code{lirc}) (type: file-like) +Package object for @command{lirc}. + +@item @code{device} (default: @code{#f}) (type: string) +@itemx @code{driver} (default: @code{#f}) (type: string) +@itemx @code{config-file} (default: @code{#f}) (type: string-or-file-like) +TODO. See @command{lircd} manual for details. + +@item @code{extra-options} (default: @code{'()}) (type: list-of-string) +Additional command-line options to pass to @command{lircd}. + +@end table +@end deftp + +@c TODO: Document , preferably by refactoring this to use +@c define-configuration and generating documentation from it. @cindex spice @subsubheading Spice Service diff --git a/gnu/services/lirc.scm b/gnu/services/lirc.scm index 492d77defa..92784b65ca 100644 --- a/gnu/services/lirc.scm +++ b/gnu/services/lirc.scm @@ -21,12 +21,13 @@ #:use-module (gnu services) #:use-module (gnu services shepherd) #:use-module (gnu packages lirc) + #:use-module (guix deprecation) #:use-module (guix gexp) #:use-module (guix records) #:use-module (ice-9 match) #:export (lirc-configuration lirc-configuation? - lirc-service + lirc-service ; deprecated lirc-service-type)) ;;; Commentary: @@ -40,9 +41,12 @@ lirc-configuation? (lirc lirc-configuration-lirc ;file-like (default lirc)) - (device lirc-configuration-device) ;string - (driver lirc-configuration-driver) ;string - (config-file lirc-configuration-file) ;string | file-like object + (device lirc-configuration-device ;string + (default #f)) + (driver lirc-configuration-driver ;string + (default #f)) + (config-file lirc-configuration-file ;string | file-like object + (default #f)) (extra-options lirc-configuration-options ;list of strings (default '()))) @@ -81,11 +85,13 @@ (service-extension activation-service-type (const %lirc-activation)))) (description "Run LIRC, a daemon that decodes infrared signals -from remote controls."))) +from remote controls.") + (default-value (lirc-configuration)))) -(define* (lirc-service #:key (lirc lirc) +(define-deprecated (lirc-service #:key (lirc lirc) device driver config-file (extra-options '())) + lirc-service-type "Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that decodes infrared signals from remote controls. -- cgit 1.4.1 From 7c23dab85ca9d507ceeb078150c56d9fd0e4fd4d Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:11 +0000 Subject: services: spice: Deprecate 'spice-vdagent-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Miscellaneous Services): Replace 'spice-vdagent-service' with 'spice-vdagent-service-type'. Document . * gnu/services/spice.scm (spice-vdagent-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 25 ++++++++++++++++++------- gnu/services/spice.scm | 7 ++++--- 2 files changed, 22 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 54b75dd1f8..704c125b10 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -37759,16 +37759,27 @@ Additional command-line options to pass to @command{lircd}. @c TODO: Document , preferably by refactoring this to use @c define-configuration and generating documentation from it. -@cindex spice -@subsubheading Spice Service +@cindex SPICE +@subsubheading SPICE Service The @code{(gnu services spice)} module provides the following service. -@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] -Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon -that enables sharing the clipboard with a vm and setting the guest display -resolution when the graphical console window resizes. -@end deffn +@defvar spice-vdagent-service-type +Type of the service that runs @url{https://www.spice-space.org, VDAGENT}, +a daemon that enables sharing the clipboard with a vm and setting the +guest display resolution when the graphical console window resizes. +@end defvar + +@deftp {Data Type} spice-vdagent-configuration +Data type representing the configuration of +@code{spice-vdagent-service-type}. + +@table @asis +@item @code{spice-vdagent} (default: @code{spice-vdagent}) (type: file-like) +Package object for VDAGENT. + +@end table +@end deftp @cindex inputattach @subsubheading inputattach Service diff --git a/gnu/services/spice.scm b/gnu/services/spice.scm index e5ec46b9b5..b8d2f8486e 100644 --- a/gnu/services/spice.scm +++ b/gnu/services/spice.scm @@ -21,12 +21,13 @@ #:use-module (gnu packages spice) #:use-module (gnu services) #:use-module (gnu services shepherd) + #:use-module (guix deprecation) #:use-module (guix gexp) #:use-module (guix records) #:export (spice-vdagent-configuration spice-vdagent-configuration? spice-vdagent-service-type - spice-vdagent-service)) + spice-vdagent-service)) ; deprecated (define-record-type* spice-vdagent-configuration make-spice-vdagent-configuration @@ -74,8 +75,8 @@ from the @code{spice-vdagent} package to enable window resizing and clipboard sharing for @acronym{VM, virtual machine} guests."))) -(define* (spice-vdagent-service - #:optional (config (spice-vdagent-configuration))) +(define-deprecated (spice-vdagent-service + #:optional (config (spice-vdagent-configuration))) "Start the @command{vdagentd} and @command{vdagent} daemons from @var{spice-vdagent} to enable guest window resizing and clipboard sharing." -- cgit 1.4.1 From 2799ad44234be675f018115f99be98d2c9fd565d Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sat, 25 Feb 2023 18:58:13 +0000 Subject: services: dbus: Deprecate 'dbus-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Desktop Services): Replace with 'dbus-root-service-type'. Document dbus-configuration. * gnu/services/dbus.scm (dbus-service): Define with 'define-deprecated'. * gnu/services/desktop.scm (desktop-services-for-system): Replace with dbus-root-service-type. * gnu/system/install.scm (%installation-services): Ditto. * gnu/tests/base.scm (%avahi-os): Ditto. * gnu/tests/docker.scm (%docker-os): Ditto. * gnu/tests/lightdm.scm (minimal-desktop-services): Ditto. * gnu/tests/virtualization.scm (%libvirt-os): Ditto. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 49 ++++++++++++++++++++++++++++---------------- gnu/services/dbus.scm | 5 +++-- gnu/services/desktop.scm | 2 +- gnu/system/install.scm | 2 +- gnu/tests/base.scm | 2 +- gnu/tests/docker.scm | 2 +- gnu/tests/lightdm.scm | 2 +- gnu/tests/virtualization.scm | 2 +- 8 files changed, 40 insertions(+), 26 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 704c125b10..74658dbc86 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23301,24 +23301,37 @@ The actual service definitions included in @code{%desktop-services} and provided by @code{(gnu services dbus)} and @code{(gnu services desktop)} are described below. -@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] @ - [#:verbose?] -Return a service that runs the ``system bus'', using @var{dbus}, with -support for @var{services}. When @var{verbose?} is true, it causes the -@samp{DBUS_VERBOSE} environment variable to be set to @samp{1}; a -verbose-enabled D-Bus package such as @code{dbus-verbose} should be -provided as @var{dbus} in this scenario. The verbose output is logged -to @file{/var/log/dbus-daemon.log}. - -@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication -facility. Its system bus is used to allow system services to communicate -and to be notified of system-wide events. - -@var{services} must be a list of packages that provide an -@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration -and policy files. For example, to allow avahi-daemon to use the system bus, -@var{services} must be equal to @code{(list avahi)}. -@end deffn +@defvar dbus-root-service-type +Type for a service that runs the D-Bus ``system bus''. +@footnote{@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process +communication facility. Its system bus is used to allow system services +to communicate and to be notified of system-wide events.} + +The value for this service type is a @code{} record. +@end defvar + +@deftp {Data Type} dbus-configuration +Data type representing the configuration for @code{dbus-root-service-type}. + +@table @asis +@item @code{dbus} (default: @code{dbus}) (type: file-like) +Package object for dbus. + +@item @code{services} (default: @code{()}) (type: list) +List of packages that provide an @file{etc/dbus-1/system.d} directory +containing additional D-Bus configuration and policy files. +For example, to allow avahi-daemon to use the system bus, @var{services} +must be equal to @code{(list avahi)}. + +@item @code{verbose?} (default: @code{#f}) (type: boolean) +When @code{#t}, D-Bus is launched with environment variable +@samp{DBUS_VERBOSE} set to @samp{1}. A verbose-enabled D-Bus package +such as @code{dbus-verbose} should be provided to @var{dbus} in this +scenario. The verbose output is logged to +@file{/var/log/dbus-daemon.log}. + +@end table +@end deftp @subsubheading Elogind diff --git a/gnu/services/dbus.scm b/gnu/services/dbus.scm index ea2593501f..e9c9346f56 100644 --- a/gnu/services/dbus.scm +++ b/gnu/services/dbus.scm @@ -38,7 +38,7 @@ #:export (dbus-configuration dbus-configuration? dbus-root-service-type - dbus-service + dbus-service ; deprecated wrapped-dbus-service polkit-configuration @@ -245,7 +245,8 @@ includes the @code{etc/dbus-1/system.d} directories of each package listed in bus. It allows programs and daemons to communicate and is also responsible for spawning (@dfn{activating}) D-Bus services on demand."))) -(define* (dbus-service #:key (dbus dbus) (services '()) verbose?) +(define-deprecated (dbus-service #:key (dbus dbus) (services '()) verbose?) + dbus-root-service-type "Return a service that runs the \"system bus\", using @var{dbus}, with support for @var{services}. When @var{verbose?} is true, it causes the @samp{DBUS_VERBOSE} environment variable to be set to @samp{1}; a diff --git a/gnu/services/desktop.scm b/gnu/services/desktop.scm index 3ec746cdbd..8026778ea5 100644 --- a/gnu/services/desktop.scm +++ b/gnu/services/desktop.scm @@ -1880,7 +1880,7 @@ applications needing access to be root.") (service geoclue-service-type) (service polkit-service-type) (service elogind-service-type) - (dbus-service) + (service dbus-root-service-type) (service ntp-service-type) diff --git a/gnu/system/install.scm b/gnu/system/install.scm index dd965f312b..7a68c19606 100644 --- a/gnu/system/install.scm +++ b/gnu/system/install.scm @@ -442,7 +442,7 @@ Access documentation at any time by pressing Alt-F2.\x1b[0m (list %loopback-static-networking)) (service wpa-supplicant-service-type) - (dbus-service) + (service dbus-root-service-type) (service connman-service-type (connman-configuration (disable-vpn? #t))) diff --git a/gnu/tests/base.scm b/gnu/tests/base.scm index 3e72e193d7..97edbbc6ad 100644 --- a/gnu/tests/base.scm +++ b/gnu/tests/base.scm @@ -962,7 +962,7 @@ non-ASCII names from /tmp.") (name-service-switch %mdns-host-lookup-nss) (services (cons* (service avahi-service-type (avahi-configuration (debug? #t))) - (dbus-service) + (service dbus-root-service-type) (service dhcp-client-service-type) ;needed for multicast ;; Enable heavyweight debugging output. diff --git a/gnu/tests/docker.scm b/gnu/tests/docker.scm index e464ec587e..0276e398a7 100644 --- a/gnu/tests/docker.scm +++ b/gnu/tests/docker.scm @@ -48,7 +48,7 @@ (define %docker-os (simple-operating-system (service dhcp-client-service-type) - (dbus-service) + (service dbus-root-service-type) (service polkit-service-type) (service elogind-service-type) (service docker-service-type))) diff --git a/gnu/tests/lightdm.scm b/gnu/tests/lightdm.scm index aa97a96939..dda472bd74 100644 --- a/gnu/tests/lightdm.scm +++ b/gnu/tests/lightdm.scm @@ -49,7 +49,7 @@ (service accountsservice-service-type) (service polkit-service-type) (service elogind-service-type) - (dbus-service) + (service dbus-root-service-type) x11-socket-directory-service)) (define %lightdm-os diff --git a/gnu/tests/virtualization.scm b/gnu/tests/virtualization.scm index 6749ade4bd..effdeb4cfa 100644 --- a/gnu/tests/virtualization.scm +++ b/gnu/tests/virtualization.scm @@ -49,7 +49,7 @@ (define %libvirt-os (simple-operating-system (service dhcp-client-service-type) - (dbus-service) + (service dbus-root-service-type) (service polkit-service-type) (service libvirt-service-type))) -- cgit 1.4.1 From a66438e497303ce08d05cf8d76b2d5827e3e3578 Mon Sep 17 00:00:00 2001 From: Leo Famulari Date: Sun, 5 Mar 2023 14:54:06 -0500 Subject: doc: Give advice to contributors about communicating with reviewers. * doc/contributing.texi (Submitting Patches): Give advice. --- doc/contributing.texi | 10 ++++++++++ doc/guix.texi | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/contributing.texi b/doc/contributing.texi index c436bc4a31..61c05c2489 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1170,6 +1170,16 @@ Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, standards, GNU Coding Standards}); you can check the commit history for examples. +You can help make the review process more efficient, and increase the +chance that your patch will be reviewed quickly, by describing the +context of your patch and the impact you expect it to have. For +example, if your patch is fixing something that is broken, describe the +problem and how your patch fixes it. Tell us how you have tested your +patch. Will users of the code changed by your patch have to adjust +their workflow at all? If so, tell us how. In general, try to imagine +what questions a reviewer will ask, and answer those questions in +advance. + Before submitting a patch that adds or modifies a package definition, please run through this check list: diff --git a/doc/guix.texi b/doc/guix.texi index 74658dbc86..7c6ff3d0c9 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -29,7 +29,7 @@ Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* -Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021, 2023 Leo Famulari@* +Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021, 2023, 2024 Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@* -- cgit 1.4.1 From da5ba283596e7ad68c6c5a910460f929a179ee21 Mon Sep 17 00:00:00 2001 From: Leo Famulari Date: Sun, 5 Mar 2023 15:06:35 -0500 Subject: Fix bogus copyright year update. This is a followup to commit a66438e497303ce08d05cf8d76b2d5827e3e3578. * doc/guix.texi: Ahem. --- doc/guix.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 7c6ff3d0c9..74658dbc86 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -29,7 +29,7 @@ Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* -Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021, 2023, 2024 Leo Famulari@* +Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021, 2023 Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@* -- cgit 1.4.1 From 674d8933169e018efa3471e4eac52e5ea1e6afee Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Wed, 1 Mar 2023 23:08:28 +0100 Subject: home: services: Add 'pulseaudio-rtp-sink' and 'pulseaudio-rtp-source'. * gnu/home/services/sound.scm: New file. * gnu/local.mk (GNU_SYSTEM_MODULES): Add it. * doc/guix.texi (Sound Home Services): New section. --- doc/guix.texi | 114 ++++++++++++++++++++++++++++++--- gnu/home/services/sound.scm | 151 ++++++++++++++++++++++++++++++++++++++++++++ gnu/local.mk | 3 +- 3 files changed, 258 insertions(+), 10 deletions(-) create mode 100644 gnu/home/services/sound.scm (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 74658dbc86..6671ba9305 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -41679,15 +41679,16 @@ service with the @code{simple-service} procedure from @code{(gnu services)}. @menu -* Essential Home Services:: Environment variables, packages, on-* scripts. -* Shells: Shells Home Services. POSIX shells, Bash, Zsh. -* Mcron: Mcron Home Service. Scheduled User's Job Execution. -* Power Management: Power Management Home Services. Services for battery power. -* Shepherd: Shepherd Home Service. Managing User's Daemons. -* SSH: Secure Shell. Setting up the secure shell client. -* Desktop: Desktop Home Services. Services for graphical environments. -* Guix: Guix Home Services. Services for Guix. -* Fonts: Fonts Home Services. Services for managing User's fonts. +* Essential Home Services:: Environment variables, packages, on-* scripts. +* Shells: Shells Home Services. POSIX shells, Bash, Zsh. +* Mcron: Mcron Home Service. Scheduled User's Job Execution. +* Power Management: Power Management Home Services. Services for battery power. +* Shepherd: Shepherd Home Service. Managing User's Daemons. +* SSH: Secure Shell. Setting up the secure shell client. +* Desktop: Desktop Home Services. Services for graphical environments. +* Guix: Guix Home Services. Services for Guix. +* Fonts: Fonts Home Services. Services for managing User's fonts. +* Sound: Sound Home Services. Dealing with audio. @end menu @c In addition to that Home Services can provide @@ -42601,6 +42602,101 @@ like this: @end lisp @end defvar +@node Sound Home Services +@subsection Sound Home Services + +The @code{(gnu home services sound)} module provides services related to +sound support. + +@cindex PulseAudio, home service +@cindex RTP, for PulseAudio + +The following services dynamically reconfigure the +@uref{https://pulseaudio.org,PulseAudio sound server}: they let you +toggle broadcast of audio output over the network using the +@acronym{RTP, real-time transport protocol} and, correspondingly, +playback of sound received over RTP. Once +@code{home-pulseaudio-rtp-sink-service-type} is among your home +services, you can start broadcasting audio output by running this +command: + +@example +herd start pulseaudio-rtp-sink +@end example + +You can then run a PulseAudio-capable mixer, such as @code{pavucontrol} +or @code{pulsemixer} (both from the same-named package) to control which +audio stream(s) should be sent to the RTP ``sink''. + +By default, audio is broadcasted to a multicast address: any device on +the @acronym{LAN, local area network} receives it and may play it. +Using multicast in this way puts a lot of pressure on the network and +degrades its performance, so you may instead prefer sending to +specifically one device. The first way to do that is by specifying the +IP address of the target device when starting the service: + +@example +herd start pulseaudio-rtp-sink 192.168.1.42 +@end example + +The other option is to specify this IP address as the one to use by +default in your home environment configuration: + +@lisp +(service home-pulseaudio-rtp-sink-service-type + "192.168.1.42") +@end lisp + +On the device where you intend to receive and play the RTP stream, you +can use @code{home-pulseaudio-rtp-source-service-type}, like so: + +@lisp +(service home-pulseaudio-rtp-source-service-type) +@end lisp + +This will then let you start the receiving module for PulseAudio: + +@example +herd start pulseaudio-rtp-source +@end example + +Again, by default it will listen on the multicast address. If, instead, +you'd like it to listen for direct incoming connections, you can do that +by running: + +@lisp +(service home-pulseaudio-rtp-source-service-type + "0.0.0.0") +@end lisp + +The reference of these services is given below. + +@defvar home-pulseaudio-rtp-sink-service-type +@defvarx home-pulseaudio-rtp-source-service-type +This is the type of the service to send, respectively receive, audio +streams over @acronym{RTP, real-time transport protocol}. + +The value associated with this service is the IP address (a string) +where to send, respectively receive, the audio stream. By default, +audio is sent/received on multicast address +@code{%pulseaudio-rtp-multicast-address}. + +This service defines one Shepherd service: @code{pulseaudio-rtp-sink}, +respectively @code{pulseaudio-rtp-source}. The service is not started +by default, so you have to explicitly start it when you want to turn it +on, as in this example: + +@example +herd start pulseaudio-rtp-sink +@end example + +Stopping the Shepherd service turns off broadcasting. +@end defvar + +@defvar %pulseaudio-rtp-multicast-address +This is the multicast address used by default by the two services above. +@end defvar + @node Invoking guix home @section Invoking @command{guix home} diff --git a/gnu/home/services/sound.scm b/gnu/home/services/sound.scm new file mode 100644 index 0000000000..22c1a99250 --- /dev/null +++ b/gnu/home/services/sound.scm @@ -0,0 +1,151 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2023 Ludovic Courtès +;;; +;;; 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 . + +(define-module (gnu home services sound) + #:use-module (gnu home services) + #:use-module (gnu home services shepherd) + #:use-module (guix records) + #:use-module (guix gexp) + #:use-module (srfi srfi-1) + #:use-module (ice-9 match) + #:export (home-pulseaudio-rtp-sink-service-type + home-pulseaudio-rtp-source-service-type + %pulseaudio-rtp-multicast-address)) + + +;;; +;;; PulseAudio support. +;;; + +(define (with-pulseaudio-connection sock exp) + ;; Wrap EXP in an expression where SOCK is bound to a socket connected to + ;; the user's PulseAudio command-line interface socket. + #~(let* ((#$sock (socket AF_UNIX SOCK_STREAM 0)) + (pulse-user-file + (lambda (name) + (string-append "/run/user/" (number->string (getuid)) + "/pulse/" name))) + (file (pulse-user-file "cli"))) + (let loop ((tries 0)) + (catch #t + (lambda () + (connect #$sock AF_UNIX file) + (let ((result #$exp)) + (close-port #$sock) + result)) + (lambda (key . args) + (if (and (eq? key 'system-error) + (= ENOENT (system-error-errno (cons key args))) + (< tries 3)) + ;; The CLI socket doesn't exist yet, so send pulseaudio + ;; SIGUSR2 so that it creates it and listens to it. + (let ((pid (call-with-input-file (pulse-user-file "pid") + read))) + (when (and (integer? pid) (> pid 1)) + (kill pid SIGUSR2)) + ((@ (fibers) sleep) 1) + (loop (+ tries 1))) + (begin + (close-port #$sock) + (apply throw key args)))))))) + +(define %pulseaudio-rtp-multicast-address + ;; Default address used by 'module-rtp-sink' and 'module-rtp-recv'. This is + ;; a multicast address, for the Session Announcement Protocol (SAP) and the + ;; Session Description Protocol (SDP). + "224.0.0.56") + +(define (pulseaudio-rtp-sink-shepherd-services destination-ip) + (list (shepherd-service + (provision '(pulseaudio-rtp-sink)) + (start + #~(lambda* (#:optional (destination-ip #$destination-ip)) + #$(with-pulseaudio-connection + #~sock + #~(begin + (display "\ +load-module module-null-sink \ +sink_name=rtp sink_properties=\"device.description='RTP network output'\"\n" + sock) + (display (string-append "\ +load-module module-rtp-send source=rtp.monitor" + (if destination-ip + (string-append + " destination_ip=" + destination-ip) + "") + "\n") + sock) + #t)))) + (stop + #~(lambda (_) + #$(with-pulseaudio-connection + #~sock + #~(begin + (display "unload-module module-rtp-send\n" + sock) + (display "unload-module module-null-sink\n" + sock) + #f)))) + (auto-start? #f)))) + +(define home-pulseaudio-rtp-sink-service-type + (service-type + (name 'pulseaudio-rtp-sink) + (extensions + (list (service-extension home-shepherd-service-type + pulseaudio-rtp-sink-shepherd-services))) + (description + "Define a PulseAudio sink to broadcast audio output over RTP, which can +then by played by another PulseAudio instance.") + + ;; By default, send to the SAP multicast address, 224.0.0.56, which can be + ;; network-intensive. + (default-value %pulseaudio-rtp-multicast-address))) + +(define (pulseaudio-rtp-source-shepherd-services source-ip) + (list (shepherd-service + (provision '(pulseaudio-rtp-source)) + (start + #~(lambda* (#:optional (source-ip #$source-ip)) + #$(with-pulseaudio-connection + #~sock + #~(begin + (format sock "\ +load-module module-rtp-recv sap_address=~a\n" source-ip) + #t)))) + (stop + #~(lambda (_) + #$(with-pulseaudio-connection + #~sock + #~(begin + (display "unload-module module-rtp-recv\n" + sock) + #f)))) + (auto-start? #f)))) + +(define home-pulseaudio-rtp-source-service-type + (service-type + (name 'pulseaudio-rtp-source) + (extensions + (list (service-extension home-shepherd-service-type + pulseaudio-rtp-source-shepherd-services))) + (description + "Define a PulseAudio source to receive audio broadcasted over RTP by +another PulseAudio instance.") + (default-value %pulseaudio-rtp-multicast-address))) diff --git a/gnu/local.mk b/gnu/local.mk index e286e0b076..70dab40087 100644 --- a/gnu/local.mk +++ b/gnu/local.mk @@ -1,5 +1,5 @@ # GNU Guix --- Functional package management for GNU -# Copyright © 2012-2021, 2021-2022 Ludovic Courtès +# Copyright © 2012-2023 Ludovic Courtès # Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2022 Andreas Enge # Copyright © 2016 Mathieu Lirzin # Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Mark H Weaver @@ -94,6 +94,7 @@ GNU_SYSTEM_MODULES = \ %D%/home/services/pm.scm \ %D%/home/services/shells.scm \ %D%/home/services/shepherd.scm \ + %D%/home/services/sound.scm \ %D%/home/services/ssh.scm \ %D%/home/services/mcron.scm \ %D%/home/services/utils.scm \ -- cgit 1.4.1 From 7777d767a43ec73539cf386311feee2f683ead92 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Tue, 7 Mar 2023 12:43:58 +0000 Subject: services: network-manager: Add 'shepherd-requirement' field. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Note: This also makes wpa-supplicant an optional requirement. * gnu/services/networking.scm () [shepherd-requirement]: New field. (network-manager-shepherd-service): Honor it. (network-manager-configuration-shepherd-requirement): Export accessor. * doc/guix.texi (Networking Setup): Document it. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 6 ++++++ gnu/services/networking.scm | 10 +++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 6671ba9305..ed518cbcb8 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -19836,6 +19836,12 @@ Data type representing the configuration of NetworkManager. @item @code{network-manager} (default: @code{network-manager}) The NetworkManager package to use. +@item @code{shepherd-requirement} (default: @code{'(wpa-supplicant)}) +This option can be used to provide a list of symbols naming Shepherd services +that this service will depend on, such as @code{'wpa-supplicant} or +@code{'iwd} if you require authenticated access for encrypted WiFi or Ethernet +networks. + @item @code{dns} (default: @code{"default"}) Processing mode for DNS, which affects how NetworkManager uses the @code{resolv.conf} configuration file. diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm index dacf64c2d1..4a3d5b887f 100644 --- a/gnu/services/networking.scm +++ b/gnu/services/networking.scm @@ -143,6 +143,7 @@ network-manager-configuration network-manager-configuration? + network-manager-configuration-shepherd-requirement network-manager-configuration-dns network-manager-configuration-vpn-plugins network-manager-service-type @@ -1140,6 +1141,8 @@ project's documentation} for more information." network-manager-configuration? (network-manager network-manager-configuration-network-manager (default network-manager)) + (shepherd-requirement network-manager-configuration-shepherd-requirement + (default '(wpa-supplicant))) (dns network-manager-configuration-dns (default "default")) (vpn-plugins network-manager-configuration-vpn-plugins ;list of file-like @@ -1200,7 +1203,7 @@ project's documentation} for more information." (define (network-manager-shepherd-service config) (match-record config - (network-manager dns vpn-plugins iwd?) + (network-manager shepherd-requirement dns vpn-plugins iwd?) (let ((conf (plain-file "NetworkManager.conf" (string-append "[main]\ndns=" dns "\n" @@ -1209,8 +1212,9 @@ project's documentation} for more information." (list (shepherd-service (documentation "Run the NetworkManager.") (provision '(networking)) - (requirement (append '(user-processes dbus-system loopback) - (if iwd? '(iwd) '(wpa-supplicant)))) + (requirement `(user-processes dbus-system loopback + ,@shepherd-requirement + ,@(if iwd? '(iwd) '()))) (start #~(make-forkexec-constructor (list (string-append #$network-manager "/sbin/NetworkManager") -- cgit 1.4.1 From 1e1b3ec0126ec3b23338c7991c747ab432c97a3c Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Tue, 7 Mar 2023 12:43:59 +0000 Subject: services: network-manager: Deprecate 'iwd?' field. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gnu/services/networking.scm (warn-iwd?-field-deprecation): New procedure, helper for deprecated field. ()[iwd?]: Use helper to warn deprecated field. (network-manager-shepherd-service): Make iwd? a local variable independent from the deprecated field. * doc/guix.texi (Networking Setup): Remove mention of iwd? field. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 4 ---- gnu/services/networking.scm | 20 ++++++++++++++++++-- 2 files changed, 18 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index ed518cbcb8..ccaca0a71b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -19890,10 +19890,6 @@ This is the list of available plugins for virtual private networks (VPNs). An example of this is the @code{network-manager-openvpn} package, which allows NetworkManager to manage VPNs @i{via} OpenVPN. -@item @code{iwd?} (default: @code{#f}) -NetworkManager will use iwd as a backend for wireless networking if this -option is set to @code{#t}, otherwise it will use wpa-supplicant. - @end table @end deftp diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm index 4a3d5b887f..f572de1279 100644 --- a/gnu/services/networking.scm +++ b/gnu/services/networking.scm @@ -1136,6 +1136,15 @@ project's documentation} for more information." ;;; NetworkManager ;;; +;; TODO: deprecated field, remove later. +(define-with-syntax-properties (warn-iwd?-field-deprecation + (value properties)) + (when value + (warning (source-properties->location properties) + (G_ "the 'iwd?' field is deprecated, please use \ +'shepherd-requirement' field instead~%"))) + value) + (define-record-type* network-manager-configuration make-network-manager-configuration network-manager-configuration? @@ -1147,7 +1156,9 @@ project's documentation} for more information." (default "default")) (vpn-plugins network-manager-configuration-vpn-plugins ;list of file-like (default '())) - (iwd? network-manager-configuration-iwd? (default #f))) + (iwd? network-manager-configuration-iwd? ; TODO: deprecated field, remove. + (default #f) + (sanitize warn-iwd?-field-deprecation))) (define (network-manager-activation config) ;; Activation gexp for NetworkManager @@ -1204,7 +1215,10 @@ project's documentation} for more information." (define (network-manager-shepherd-service config) (match-record config (network-manager shepherd-requirement dns vpn-plugins iwd?) - (let ((conf (plain-file "NetworkManager.conf" + (let ((iwd? (or iwd? ; TODO: deprecated field, remove later. + (and shepherd-requirement + (memq 'iwd shepherd-requirement)))) + (conf (plain-file "NetworkManager.conf" (string-append "[main]\ndns=" dns "\n" (if iwd? "[device]\nwifi.backend=iwd\n" "")))) @@ -1214,6 +1228,8 @@ project's documentation} for more information." (provision '(networking)) (requirement `(user-processes dbus-system loopback ,@shepherd-requirement + ;; TODO: iwd? is deprecated and should be passed + ;; with shepherd-requirement, remove later. ,@(if iwd? '(iwd) '()))) (start #~(make-forkexec-constructor (list (string-append #$network-manager -- cgit 1.4.1 From 269871d18e7d1a95fbe5dfa7360208110dde9163 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Tue, 7 Mar 2023 12:44:01 +0000 Subject: services: connman: Add 'shepherd-requirement' field. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gnu/services/networking.scm () [shepherd-requirement]: New field. (connman-shepherd-service): Honor it. (connman-configuration-shepherd-requirement): Export accessor. * doc/guix.texi (Networking Setup): Document it. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 6 ++++++ gnu/services/networking.scm | 12 ++++++++---- 2 files changed, 14 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index ccaca0a71b..ece0c0354d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -19917,6 +19917,12 @@ Data Type representing the configuration of connman. @item @code{connman} (default: @var{connman}) The connman package to use. +@item @code{shepherd-requirement} (default: @code{()}) +This option can be used to provide a list of symbols naming Shepherd services +that this service will depend on, such as @code{'wpa-supplicant} or +@code{'iwd} if you require authenticated access for encrypted WiFi or Ethernet +networks. + @item @code{disable-vpn?} (default: @code{#f}) When true, disable connman's vpn plugin. diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm index abfaba8004..6a09f6e728 100644 --- a/gnu/services/networking.scm +++ b/gnu/services/networking.scm @@ -151,6 +151,7 @@ connman-configuration connman-configuration? connman-configuration-connman + connman-configuration-shepherd-requirement connman-configuration-disable-vpn? connman-configuration-iwd? connman-service-type @@ -1288,6 +1289,8 @@ wireless networking.")))) connman-configuration? (connman connman-configuration-connman (default connman)) + (shepherd-requirement connman-configuration-shepherd-requirement + (default '())) (disable-vpn? connman-configuration-disable-vpn? (default #f)) (iwd? connman-configuration-iwd? @@ -1303,13 +1306,14 @@ wireless networking.")))) (mkdir-p "/var/lib/connman-vpn/")))))) (define (connman-shepherd-service config) - (match-record config (connman disable-vpn? iwd?) + (match-record config (connman shepherd-requirement + disable-vpn? iwd?) (list (shepherd-service (documentation "Run Connman") (provision '(networking)) - (requirement - (append '(user-processes dbus-system loopback) - (if iwd? '(iwd) '()))) + (requirement `(user-processes dbus-system loopback + ,@shepherd-requirement + ,@(if iwd? '(iwd) '()))) (start #~(make-forkexec-constructor (list (string-append #$connman "/sbin/connmand") -- cgit 1.4.1 From 17c80118fa2a78a249f7fb992ffa3e31407a24a7 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Tue, 7 Mar 2023 12:44:02 +0000 Subject: services: connman: Deprecate 'iwd?' field. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gnu/services/networking.scm () [iwd?]: Use helper to warn deprecated field. (connman-shepherd-service): Make iwd? a local variable independent from the deprecated field. * doc/guix.texi (Networking Setup): Remove mention of iwd? field. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 2 -- gnu/services/networking.scm | 50 +++++++++++++++++++++++++-------------------- 2 files changed, 28 insertions(+), 24 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index ece0c0354d..b098e45a50 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -19926,8 +19926,6 @@ networks. @item @code{disable-vpn?} (default: @code{#f}) When true, disable connman's vpn plugin. -@item @code{iwd?} (default: @code{#f}) -When true, ConnMan uses iwd to connect to wireless networks. @end table @end deftp diff --git a/gnu/services/networking.scm b/gnu/services/networking.scm index 6a09f6e728..0ed467f9d8 100644 --- a/gnu/services/networking.scm +++ b/gnu/services/networking.scm @@ -1294,7 +1294,8 @@ wireless networking.")))) (disable-vpn? connman-configuration-disable-vpn? (default #f)) (iwd? connman-configuration-iwd? - (default #f))) + (default #f) + (sanitize warn-iwd?-field-deprecation))) (define (connman-activation config) (let ((disable-vpn? (connman-configuration-disable-vpn? config))) @@ -1308,27 +1309,32 @@ wireless networking.")))) (define (connman-shepherd-service config) (match-record config (connman shepherd-requirement disable-vpn? iwd?) - (list (shepherd-service - (documentation "Run Connman") - (provision '(networking)) - (requirement `(user-processes dbus-system loopback - ,@shepherd-requirement - ,@(if iwd? '(iwd) '()))) - (start #~(make-forkexec-constructor - (list (string-append #$connman - "/sbin/connmand") - "--nodaemon" - "--nodnsproxy" - #$@(if disable-vpn? '("--noplugin=vpn") '()) - #$@(if iwd? '("--wifi=iwd_agent") '())) - - ;; As connman(8) notes, when passing '-n', connman - ;; "directs log output to the controlling terminal in - ;; addition to syslog." Redirect stdout and stderr - ;; to avoid spamming the console (XXX: for some reason - ;; redirecting to /dev/null doesn't work.) - #:log-file "/var/log/connman.log")) - (stop #~(make-kill-destructor)))))) + (let ((iwd? (or iwd? ; TODO: deprecated field, remove later. + (and shepherd-requirement + (memq 'iwd shepherd-requirement))))) + (list (shepherd-service + (documentation "Run Connman") + (provision '(networking)) + (requirement `(user-processes dbus-system loopback + ,@shepherd-requirement + ;; TODO: iwd? is deprecated and should be passed + ;; with shepherd-requirement, remove later. + ,@(if iwd? '(iwd) '()))) + (start #~(make-forkexec-constructor + (list (string-append #$connman + "/sbin/connmand") + "--nodaemon" + "--nodnsproxy" + #$@(if disable-vpn? '("--noplugin=vpn") '()) + #$@(if iwd? '("--wifi=iwd_agent") '())) + + ;; As connman(8) notes, when passing '-n', connman + ;; "directs log output to the controlling terminal in + ;; addition to syslog." Redirect stdout and stderr + ;; to avoid spamming the console (XXX: for some reason + ;; redirecting to /dev/null doesn't work.) + #:log-file "/var/log/connman.log")) + (stop #~(make-kill-destructor))))))) (define %connman-log-rotation (list (log-rotation -- cgit 1.4.1 From 5627c73a9e410c7e28d67df517bd275d8c5f5d8d Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Mon, 6 Mar 2023 17:26:44 +0000 Subject: services: xorg: Deprecate 'screen-locker-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (X Window): Replace 'screen-locker-service' with 'screen-locker-service-type'. Document . * gnu/services/desktop.scm (desktop-services-for-system): Use screen-locker-service-type. * gnu/services/xorg.scm: Export accessors for . (): Rename to ... (): ... this. ()[empty?]: Rename to ... ()[allow-empty-password?]: ... this. (screen-locker-pam-services): Update record name. (screen-locker-setuid-programs): Update accessor name. (screen-locker-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 32 ++++++++++++++++++++++++++------ gnu/services/desktop.scm | 8 ++++++-- gnu/services/xorg.scm | 47 ++++++++++++++++++++++++++++++----------------- 3 files changed, 62 insertions(+), 25 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index b098e45a50..ce65a3bf99 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -22212,18 +22212,38 @@ Usually the X server is started by a login manager. @end deffn -@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}] -Add @var{package}, a package for a screen locker or screen saver whose -command is @var{program}, to the set of setuid programs and add a PAM entry -for it. For example: +@defvar screen-locker-service-type +Type for a service that adds a package for a screen locker or screen +saver to the set of setuid programs and add a PAM entry for it. The +value for this service is a @code{} object. + +For example, to make XlockMore usable: @lisp -(screen-locker-service xlockmore "xlock") +(service screen-locker-service-type + (screen-locker-configuration + "xlock" (file-append xlockmore "/bin/xlock") #f)) @end lisp makes the good ol' XlockMore usable. -@end deffn +@end defvar +@deftp {Data Type} screen-locker-configuration +Data type representing the configuration of +@code{screen-locker-service-type}. + +@table @asis +@item @code{name} (type: string) +Name of the screen locker. + +@item @code{program} (type: gexp) +Path to the executable for the screen locker as a G-Expression. + +@item @code{allow-empty-password?} (type: boolean) +Whether to allow empty passwords. + +@end table +@end deftp @node Printing Services @subsection Printing Services diff --git a/gnu/services/desktop.scm b/gnu/services/desktop.scm index aa9f93997d..c0178135b0 100644 --- a/gnu/services/desktop.scm +++ b/gnu/services/desktop.scm @@ -1832,8 +1832,12 @@ applications needing access to be root.") (service sddm-service-type)) ;; Screen lockers are a pretty useful thing and these are small. - (screen-locker-service slock) - (screen-locker-service xlockmore "xlock") + (service screen-locker-service-type + (screen-locker-configuration + "slock" (file-append slock "/bin/slock") #f)) + (service screen-locker-service-type + (screen-locker-configuration + "xlock" (file-append xlockmore "/bin/xlock") #f)) ;; Add udev rules for MTP devices so that non-root users can access ;; them. diff --git a/gnu/services/xorg.scm b/gnu/services/xorg.scm index 5f073d05d3..c4745cecf5 100644 --- a/gnu/services/xorg.scm +++ b/gnu/services/xorg.scm @@ -107,10 +107,13 @@ slim-service-type - screen-locker - screen-locker? + screen-locker-configuration + screen-locker-configuration? + screen-locker-configuration-name + screen-locker-configuration-program + screen-locker-configuration-allow-empty-password? screen-locker-service-type - screen-locker-service + screen-locker-service ; deprecated localed-configuration localed-configuration? @@ -683,21 +686,30 @@ reboot_cmd " shepherd "/sbin/reboot\n" ;;; Screen lockers & co. ;;; -(define-record-type - (screen-locker name program empty?) +(define-record-type + (screen-locker-configuration name program allow-empty-password?) + screen-locker-configuration? + (name screen-locker-configuration-name) ;string + (program screen-locker-configuration-program) ;gexp + (allow-empty-password? + screen-locker-configuration-allow-empty-password?)) ;Boolean + +(define-deprecated/public-alias + screen-locker + screen-locker-configuration) + +(define-deprecated/public-alias screen-locker? - (name screen-locker-name) ;string - (program screen-locker-program) ;gexp - (empty? screen-locker-allows-empty-passwords?)) ;Boolean + screen-locker-configuration?) (define screen-locker-pam-services (match-lambda - (($ name _ empty?) + (($ name _ empty?) (list (unix-pam-service name #:allow-empty-passwords? empty?))))) (define screen-locker-setuid-programs - (compose list file-like->setuid-program screen-locker-program)) + (compose list file-like->setuid-program screen-locker-configuration-program)) (define screen-locker-service-type (service-type (name 'screen-locker) @@ -711,10 +723,11 @@ reboot_cmd " shepherd "/sbin/reboot\n" the graphical server by making it setuid-root, so it can authenticate users, and by creating a PAM service for it."))) -(define* (screen-locker-service package - #:optional - (program (package-name package)) - #:key allow-empty-passwords?) +(define-deprecated (screen-locker-service package + #:optional + (program (package-name package)) + #:key allow-empty-passwords?) + screen-locker-service-type "Add @var{package}, a package for a screen locker or screen saver whose command is @var{program}, to the set of setuid programs and add a PAM entry for it. For example: @@ -725,9 +738,9 @@ for it. For example: makes the good ol' XlockMore usable." (service screen-locker-service-type - (screen-locker program - (file-append package "/bin/" program) - allow-empty-passwords?))) + (screen-locker-configuration program + (file-append package "/bin/" program) + allow-empty-passwords?))) ;;; -- cgit 1.4.1 From bc876cf08e8e93d6f46794aaf170003036d15066 Mon Sep 17 00:00:00 2001 From: Hugo Buddelmeijer Date: Mon, 6 Mar 2023 21:39:05 +0100 Subject: doc: Sending-a-Patch-Series: Fix URL. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/contributing.texi (Sending a Patch Series): Fix URL for issue tracker. Signed-off-by: Ludovic Courtès --- doc/contributing.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/contributing.texi b/doc/contributing.texi index 61c05c2489..911c3a7bbf 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -1488,7 +1488,7 @@ Due to an apparent bug in @command{git send-email}, @end quotation You can find out @var{ISSUE_NUMBER} either by searching on the mumi -interface at @url{issues.guix.gnu.org} for the name of your patch or +interface at @url{https://issues.guix.gnu.org} for the name of your patch or reading the acknowledgement email sent automatically by Debbugs in reply to incoming bugs and patches, which contains the bug number. -- cgit 1.4.1 From f437b1118014b813b7c6cf8b9b0deb87108b807e Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Fri, 10 Mar 2023 17:40:50 +0100 Subject: doc: Add missing space after @deftp. * doc/guix.texi (Samba Services): Add missing space before brace. --- doc/guix.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index ce65a3bf99..b545751e1b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -32487,7 +32487,7 @@ guest only = yes\n")))) @end defvar -@deftp{Data Type} samba-service-configuration +@deftp {Data Type} samba-service-configuration Configuration record for the Samba suite. @table @asis -- cgit 1.4.1 From d1edb26388ca4dab4b435a686cd059d97c113c3e Mon Sep 17 00:00:00 2001 From: Sergey Trofimov Date: Fri, 10 Mar 2023 16:00:56 +0100 Subject: services: dns: Extend dnsmasq-configuration. * gnu/service/dns.scm: ()[servers-file]: Add. ()[tftp-secure?]: Fix typo in parameter name. * doc/guix.texi: Document ()[servers-file]. Signed-off-by: Andrew Tropin --- doc/guix.texi | 4 ++ gnu/services/dns.scm | 124 +++++++++++++++++++++++++++------------------------ 2 files changed, 69 insertions(+), 59 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index b545751e1b..e448bee284 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -31528,6 +31528,10 @@ in @var{servers}. @item @code{servers} (default: @code{'()}) Specify IP address of upstream servers directly. +@item @code{servers-file} (default: @code{#f}) +Specify file containing upstream servers. This file is re-read when dnsmasq receives SIGHUP. +Could be either a string or a file-like object. + @item @code{addresses} (default: @code{'()}) For each entry, specify an IP address to return for any host in the given domains. Queries in the domains are never forwarded and always diff --git a/gnu/services/dns.scm b/gnu/services/dns.scm index 32fb8c0664..837e3fe6f7 100644 --- a/gnu/services/dns.scm +++ b/gnu/services/dns.scm @@ -754,6 +754,8 @@ cache.size = 100 * MB (default #f)) ;boolean (servers dnsmasq-configuration-servers (default '())) ;list of string + (servers-file dnsmasq-configuration-servers-file + (default #f)) ;string|file-like (addresses dnsmasq-configuration-addresses (default '())) ;list of string (cache-size dnsmasq-configuration-cache-size @@ -792,7 +794,7 @@ cache.size = 100 * MB port local-service? listen-addresses resolv-file no-resolv? forward-private-reverse-lookup? query-servers-in-order? - servers addresses + servers addresses servers-file cache-size negative-cache? cpe-id tftp-enable? tftp-no-fail? @@ -805,76 +807,80 @@ cache.size = 100 * MB (requirement '(networking)) (documentation "Run the dnsmasq DNS server.") (start #~(make-forkexec-constructor - '(#$(file-append package "/sbin/dnsmasq") - "--keep-in-foreground" - "--pid-file=/run/dnsmasq.pid" - #$@(if no-hosts? - '("--no-hosts") + (list + #$(file-append package "/sbin/dnsmasq") + "--keep-in-foreground" + "--pid-file=/run/dnsmasq.pid" + #$@(if no-hosts? + '("--no-hosts") '()) - #$(format #f "--port=~a" port) - #$@(if local-service? - '("--local-service") + #$(format #f "--port=~a" port) + #$@(if local-service? + '("--local-service") '()) - #$@(map (cut format #f "--listen-address=~a" <>) - listen-addresses) - #$(format #f "--resolv-file=~a" resolv-file) - #$@(if no-resolv? - '("--no-resolv") + #$@(map (cut format #f "--listen-address=~a" <>) + listen-addresses) + #$(format #f "--resolv-file=~a" resolv-file) + #$@(if no-resolv? + '("--no-resolv") '()) - #$@(if forward-private-reverse-lookup? - '() + #$@(if forward-private-reverse-lookup? + '() '("--bogus-priv")) - #$@(if query-servers-in-order? - '("--strict-order") + #$@(if query-servers-in-order? + '("--strict-order") '()) - #$@(map (cut format #f "--server=~a" <>) - servers) - #$@(map (cut format #f "--address=~a" <>) - addresses) - #$(format #f "--cache-size=~a" cache-size) - #$@(if negative-cache? - '() + #$@(if servers-file + (list #~(string-append "--servers-file=" #$servers-file)) + '()) + #$@(map (cut format #f "--server=~a" <>) + servers) + #$@(map (cut format #f "--address=~a" <>) + addresses) + #$(format #f "--cache-size=~a" cache-size) + #$@(if negative-cache? + '() '("--no-negcache")) - #$@(if cpe-id - (list (format #f "--add-cpe-id=~a" cpe-id)) + #$@(if cpe-id + (list (format #f "--add-cpe-id=~a" cpe-id)) + '()) + #$@(if tftp-enable? + '("--enable-tftp") '()) - #$@(if tftp-enable? - '("--enable-tftp") + #$@(if tftp-no-fail? + '("--tftp-no-fail") '()) - #$@(if tftp-no-fail? - '("--tftp-no-fail") + #$@(if tftp-single-port? + '("--tftp-single-port") '()) - #$@(if tftp-single-port? - '("--tftp-single-port") + #$@(if tftp-secure? + '("--tftp-secure") '()) - #$@(if tftp-secure? - '("--tftp-secure?") + #$@(if tftp-max + (list (format #f "--tftp-max=~a" tftp-max)) + '()) + #$@(if tftp-mtu + (list (format #f "--tftp-mtu=~a" tftp-mtu)) + '()) + #$@(if tftp-no-blocksize? + '("--tftp-no-blocksize") '()) - #$@(if tftp-max - (list (format #f "--tftp-max=~a" tftp-max)) + #$@(if tftp-lowercase? + '("--tftp-lowercase") '()) - #$@(if tftp-mtu - (list (format #f "--tftp-mtu=~a" tftp-mtu)) - '()) - #$@(if tftp-no-blocksize? - '("--tftp-no-blocksize") - '()) - #$@(if tftp-lowercase? - '("--tftp-lowercase") - '()) - #$@(if tftp-port-range - (list (format #f "--tftp-port-range=~a" - tftp-port-range)) - '()) - #$@(if tftp-root - (list (format #f "--tftp-root=~a" tftp-root)) - '()) - #$@(if tftp-unique-root - (list - (if (> (length tftp-unique-root) 0) - (format #f "--tftp-unique-root=~a" tftp-unique-root) - (format #f "--tftp-unique-root"))) - '())) + #$@(if tftp-port-range + (list (format #f "--tftp-port-range=~a" + tftp-port-range)) + '()) + #$@(if tftp-root + (list (format #f "--tftp-root=~a" tftp-root)) + '()) + #$@(if tftp-unique-root + (list + (if (> (length tftp-unique-root) 0) + (format #f "--tftp-unique-root=~a" tftp-unique-root) + (format #f "--tftp-unique-root"))) + '())) #:pid-file "/run/dnsmasq.pid")) (stop #~(make-kill-destructor))))) -- cgit 1.4.1 From 266a9f9d973a3bc11cc86f03576da09aefab08f3 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Tue, 21 Feb 2023 22:16:14 +0000 Subject: doc: %desktop-services: Fix incorrect description. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Name Service Switch service is configured in operating-system. * doc/guix.texi (Desktop Services): Fix incorrect description for %desktop-services. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index e448bee284..3814e60467 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23124,9 +23124,7 @@ support (@pxref{Networking Services, @code{modem-manager-service-type}}), energy and color management services, the @code{elogind} login and seat manager, the Polkit privilege service, the GeoClue location service, the AccountsService daemon that allows authorized users change system passwords, -an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the -name service switch service configured to be able to use @code{nss-mdns} -(@pxref{Name Service Switch, mDNS}). +a NTP client (@pxref{Networking Services}) and the Avahi daemon. @end defvar The @code{%desktop-services} variable can be used as the @code{services} -- cgit 1.4.1 From eee95b5a879b7096dffd533f24107cf8926b621e Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Wed, 8 Mar 2023 12:53:20 +0100 Subject: packages: 'package-input-rewriting/spec' ignores hidden packages. The primary motivation is to support things like: guix build guix --with-input=guile=guile-next without triggering a rebuild of (@@ (gnu packages commencement) guile-final) and similar things. It is also consistent with package name resolution on the command line: a package that cannot be named cannot be replaced. * guix/packages.scm (package-input-rewriting/spec)[rewrite]: When P is hidden, return it as-is. * tests/packages.scm ("package-input-rewriting/spec, hidden package"): New test. * doc/guix.texi (Defining Package Variants): Update. (Package Transformation Options): Update '--with-input' example. --- doc/guix.texi | 21 ++++++++++++--------- guix/packages.scm | 7 +++++-- tests/packages.scm | 20 +++++++++++++++++++- 3 files changed, 36 insertions(+), 12 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 3814e60467..95c954bfcf 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -8331,10 +8331,13 @@ be replaced by name rather than by identity. @deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t] Return a procedure that, given a package, applies the given @var{replacements} to all the package graph, including implicit inputs -unless @var{deep?} is false. @var{replacements} is a list of -spec/procedures pair; each spec is a package specification such as -@code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching -package and returns a replacement for that package. +unless @var{deep?} is false. + +@var{replacements} is a list of spec/procedures pair; each spec is a +package specification such as @code{"gcc"} or @code{"guile@@2"}, and +each procedure takes a matching package and returns a replacement for +that package. Matching packages that have the @code{hidden?} property +set are not replaced. @end deffn The example above could be rewritten this way: @@ -12664,18 +12667,18 @@ or @code{guile@@1.8}. For instance, the following command builds Guix, but replaces its dependency on the current stable version of Guile with a dependency on -the legacy version of Guile, @code{guile@@2.0}: +the legacy version of Guile, @code{guile@@2.2}: @example -guix build --with-input=guile=guile@@2.0 guix +guix build --with-input=guile=guile@@2.2 guix @end example This is a recursive, deep replacement. So in this example, both @code{guix} and its dependency @code{guile-json} (which also depends on -@code{guile}) get rebuilt against @code{guile@@2.0}. +@code{guile}) get rebuilt against @code{guile@@2.2}. -This is implemented using the @code{package-input-rewriting} Scheme -procedure (@pxref{Defining Packages, @code{package-input-rewriting}}). +This is implemented using the @code{package-input-rewriting/spec} Scheme +procedure (@pxref{Defining Packages, @code{package-input-rewriting/spec}}). @item --with-graft=@var{package}=@var{replacement} This is similar to @option{--with-input} but with an important difference: diff --git a/guix/packages.scm b/guix/packages.scm index ca958c6eae..4c0c194652 100644 --- a/guix/packages.scm +++ b/guix/packages.scm @@ -1533,9 +1533,11 @@ package and returns its new name after rewrite." (define* (package-input-rewriting/spec replacements #:key (deep? #t)) "Return a procedure that, given a package, applies the given REPLACEMENTS to all the package graph, including implicit inputs unless DEEP? is false. + REPLACEMENTS is a list of spec/procedures pair; each spec is a package specification such as \"gcc\" or \"guile@2\", and each procedure takes a -matching package and returns a replacement for that package." +matching package and returns a replacement for that package. Matching +packages that have the 'hidden?' property set are not replaced." (define table (fold (lambda (replacement table) (match replacement @@ -1563,7 +1565,8 @@ matching package and returns a replacement for that package." (gensym " package-replacement")) (define (rewrite p) - (if (assq-ref (package-properties p) replacement-property) + (if (or (assq-ref (package-properties p) replacement-property) + (hidden-package? p)) p (match (find-replacement p) (#f p) diff --git a/tests/packages.scm b/tests/packages.scm index 27fb918f90..ef97fca86d 100644 --- a/tests/packages.scm +++ b/tests/packages.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2012-2022 Ludovic Courtès +;;; Copyright © 2012-2023 Ludovic Courtès ;;; Copyright © 2018 Jan (janneke) Nieuwenhuizen ;;; Copyright © 2021 Maxim Cournoyer ;;; Copyright © 2021 Maxime Devos @@ -1592,6 +1592,24 @@ (match (delete-duplicates pythons eq?) ((p) (eq? p (rewrite python)))))) +(test-assert "package-input-rewriting/spec, hidden package" + ;; Hidden packages are not subject to rewriting. + (let* ((python (hidden-package python)) + (p0 (dummy-package "chbouib" + (build-system trivial-build-system) + (inputs (list python)))) + (rewrite (package-input-rewriting/spec + `(("python" . ,(const sed))) + #:deep? #t)) + (p1 (rewrite p0)) + (bag1 (package->bag p1)) + (pythons (filter-map (match-lambda + (("python" python) python) + (_ #f)) + (bag-transitive-inputs bag1)))) + (match (delete-duplicates pythons eq?) + ((p) (eq? p python))))) + (test-equal "package-input-rewriting/spec, graft" (derivation-file-name (package-derivation %store sed)) -- cgit 1.4.1 From eec5b16d7068610554195f7fcfdfa7d974869a9a Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Wed, 8 Mar 2023 01:22:06 +0000 Subject: doc: Fix incorrect @deffn usage for service-types. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Networking Services): Fix incorrect @deffn usage for service-types. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 95c954bfcf..b8da614680 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -20043,7 +20043,7 @@ running a WiFi access point with @command{hostapd}, running the @command{inetd} ``superdaemon'', and more. This section describes those. -@deffn {Scheme Procedure} dhcpd-service-type +@defvar dhcpd-service-type This type defines a service that runs a DHCP daemon. To create a service of this type, you must supply a @code{}. For example: @@ -20054,7 +20054,7 @@ For example: (config-file (local-file "my-dhcpd.conf")) (interfaces '("enp0s25")))) @end lisp -@end deffn +@end defvar @deftp {Data Type} dhcpd-configuration @table @asis @@ -20290,7 +20290,7 @@ to use with the options @option{iburst} and @option{prefer}, as well as @end deftp @cindex OpenNTPD -@deffn {Scheme Procedure} openntpd-service-type +@defvar openntpd-service-type Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system clock synchronized with that of the given servers. @@ -20305,7 +20305,7 @@ clock synchronized with that of the given servers. (constraints-from '("https://www.google.com/")))) @end lisp -@end deffn +@end defvar @defvar %openntpd-servers This variable is a list of the server addresses defined in -- cgit 1.4.1 From dbfaca42a0377c65b96e11ef292275cb0113108f Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Wed, 8 Mar 2023 01:22:07 +0000 Subject: doc: Fix incorrect @deffn usage for data types. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Web Services): Fix incorrect @deffn usage for data types. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index b8da614680..a2beaa832c 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -29610,7 +29610,7 @@ The details for the @code{httpd-configuration}, @code{httpd-module}, @code{httpd-config-file} and @code{httpd-virtualhost} record types are given below. -@deffn {Data Type} httpd-configuration +@deftp {Data Type} httpd-configuration This data type represents the configuration for the httpd service. @table @asis @@ -29627,9 +29627,9 @@ G-expression that generates a file, for example a @code{plain-file}. A file outside of the store can also be specified through a string. @end table -@end deffn +@end deftp -@deffn {Data Type} httpd-module +@deftp {Data Type} httpd-module This data type represents a module for the httpd service. @table @asis @@ -29643,13 +29643,13 @@ within the store, for example @code{(file-append mod-wsgi "/modules/mod_wsgi.so")}. @end table -@end deffn +@end deftp @defvar %default-httpd-modules A default list of @code{httpd-module} objects. @end defvar -@deffn {Data Type} httpd-config-file +@deftp {Data Type} httpd-config-file This data type represents a configuration file for the httpd service. @table @asis @@ -29728,9 +29728,9 @@ Any values which the service is extended with will be appended to this list. @end table -@end deffn +@end deftp -@deffn {Data Type} httpd-virtualhost +@deftp {Data Type} httpd-virtualhost This data type represents a virtualhost configuration block for the httpd service. These should be added to the extra-config for the httpd-service. @@ -29754,7 +29754,7 @@ The contents of the @code{VirtualHost} directive, this should be a list of strings and G-expressions. @end table -@end deffn +@end deftp @anchor{NGINX} @subsubheading NGINX @@ -29795,7 +29795,7 @@ configuration. In our case, startup error messages can be found in @file{/var/log/nginx/error.log}. The second location can be changed with the @var{log-directory} configuration option. -@deffn {Data Type} nginx-configuration +@deftp {Data Type} nginx-configuration This data type represents the configuration for NGinx. Some configuration can be done through this and the other provided record types, or alternatively, a config file can be provided. @@ -29935,7 +29935,7 @@ Extra content for the @code{http} block. Should be string or a string valued G-expression. @end table -@end deffn +@end deftp @anchor{nginx-server-configuration} @deftp {Data Type} nginx-server-configuration -- cgit 1.4.1 From 3c40dfe2851dd4ef48d2711f9f3531c06afbe1f2 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Wed, 8 Mar 2023 01:22:08 +0000 Subject: doc: Use @defun for procedures. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Inferiors, Defining Packages, package Reference) (origin Reference, Defining Package Variants, Writing Manifests) (Build Utilities, Search Paths, The Store, Derivations, The Store Monad) (G-Expressions, File Systems, Keyboard Layout, Base Services, X Window) (Desktop Services, File-Sharing Services, Web Services, Virtualization Services) (Version Control Services, Miscellaneous Services, Initial RAM Disk) (Bootloader Configuration, Service Reference, Shepherd Services) (Complex Configurations): Use @defun for procedures. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 504 +++++++++++++++++++++++++++------------------------------- 1 file changed, 238 insertions(+), 266 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index a2beaa832c..539490d69b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -4958,60 +4958,57 @@ be much faster because the Guix revision will be cached. The @code{(guix inferior)} module provides the following procedures to open an inferior: -@deffn {Scheme Procedure} inferior-for-channels @var{channels} @ - [#:cache-directory] [#:ttl] +@defun inferior-for-channels channels [#:cache-directory] [#:ttl] Return an inferior for @var{channels}, a list of channels. Use the cache at @var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds. This procedure opens a new connection to the build daemon. As a side effect, this procedure may build or substitute binaries for @var{channels}, which can take time. -@end deffn +@end defun -@deffn {Scheme Procedure} open-inferior @var{directory} @ - [#:command "bin/guix"] +@defun open-inferior directory [#:command "bin/guix"] Open the inferior Guix in @var{directory}, running @code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if the inferior could not be launched. -@end deffn +@end defun @cindex inferior packages The procedures listed below allow you to obtain and manipulate inferior packages. -@deffn {Scheme Procedure} inferior-packages @var{inferior} +@defun inferior-packages inferior Return the list of packages known to @var{inferior}. -@end deffn +@end defun -@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @ - [@var{version}] +@defun lookup-inferior-packages inferior name [version] Return the sorted list of inferior packages matching @var{name} in @var{inferior}, with highest version numbers first. If @var{version} is true, return only packages with a version number prefixed by @var{version}. -@end deffn +@end defun -@deffn {Scheme Procedure} inferior-package? @var{obj} +@defun inferior-package? obj Return true if @var{obj} is an inferior package. -@end deffn +@end defun -@deffn {Scheme Procedure} inferior-package-name @var{package} -@deffnx {Scheme Procedure} inferior-package-version @var{package} -@deffnx {Scheme Procedure} inferior-package-synopsis @var{package} -@deffnx {Scheme Procedure} inferior-package-description @var{package} -@deffnx {Scheme Procedure} inferior-package-home-page @var{package} -@deffnx {Scheme Procedure} inferior-package-location @var{package} -@deffnx {Scheme Procedure} inferior-package-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-search-paths @var{package} +@defun inferior-package-name package +@defunx inferior-package-version package +@defunx inferior-package-synopsis package +@defunx inferior-package-description package +@defunx inferior-package-home-page package +@defunx inferior-package-location package +@defunx inferior-package-inputs package +@defunx inferior-package-native-inputs package +@defunx inferior-package-propagated-inputs package +@defunx inferior-package-transitive-propagated-inputs package +@defunx inferior-package-native-search-paths package +@defunx inferior-package-transitive-native-search-paths package +@defunx inferior-package-search-paths package These procedures are the counterpart of package record accessors (@pxref{package Reference}). Most of them work by querying the inferior @var{package} comes from, so the inferior must still be live when you call these procedures. -@end deffn +@end defun Inferior packages can be used transparently like any other package or file-like object in G-expressions (@pxref{G-Expressions}). They are also @@ -7575,7 +7572,7 @@ That derivation is stored in a @file{.drv} file under @file{/gnu/store}. The build actions it prescribes may then be realized by using the @code{build-derivations} procedure (@pxref{The Store}). -@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}] +@defun package-derivation store package [system] Return the @code{} object of @var{package} for @var{system} (@pxref{Derivations}). @@ -7584,22 +7581,21 @@ must be a string denoting the target system type---e.g., @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store} must be a connection to the daemon, which operates on the store (@pxref{The Store}). -@end deffn +@end defun @noindent @cindex cross-compilation Similarly, it is possible to compute a derivation that cross-builds a package for some other system: -@deffn {Scheme Procedure} package-cross-derivation @var{store} @ - @var{package} @var{target} [@var{system}] +@defun package-cross-derivation store package target [system] Return the @code{} object of @var{package} cross-built from @var{system} to @var{target}. @var{target} must be a valid GNU triplet denoting the target hardware and operating system, such as @code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets,,, autoconf, Autoconf}). -@end deffn +@end defun Once you have package definitions, you can easily define @emph{variants} of those packages. @xref{Defining Package Variants}, for more on that. @@ -7810,10 +7806,10 @@ It is an error to refer to @code{this-package} outside a package definition. The following helper procedures are provided to help deal with package inputs. -@deffn {Scheme Procedure} lookup-package-input @var{package} @var{name} -@deffnx {Scheme Procedure} lookup-package-native-input @var{package} @var{name} -@deffnx {Scheme Procedure} lookup-package-propagated-input @var{package} @var{name} -@deffnx {Scheme Procedure} lookup-package-direct-input @var{package} @var{name} +@defun lookup-package-input package name +@defunx lookup-package-native-input package name +@defunx lookup-package-propagated-input package name +@defunx lookup-package-direct-input package name Look up @var{name} among @var{package}'s inputs (or native, propagated, or direct inputs). Return it if found, @code{#f} otherwise. @@ -7829,7 +7825,7 @@ use it: In this example we obtain the @code{gmp} package that is among the direct inputs of @code{coreutils}. -@end deffn +@end defun @cindex development inputs, of a package @cindex implicit inputs, of a package @@ -7838,8 +7834,7 @@ Sometimes you will want to obtain the list of inputs needed to package is compiled. This is what the @code{package-development-inputs} procedure returns. -@deffn {Scheme Procedure} package-development-inputs @var{package} @ - [@var{system}] [#:target #f] +@defun package-development-inputs package [system] [#:target #f] Return the list of inputs required by @var{package} for development purposes on @var{system}. When @var{target} is true, return the inputs needed to cross-compile @var{package} from @var{system} to @@ -7870,7 +7865,7 @@ because @code{hello} has zero explicit dependencies. Conversely, gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph hello} would show you explicit inputs, whereas @command{guix graph -t bag hello} would include implicit inputs (@pxref{Invoking guix graph}). -@end deffn +@end defun Because packages are regular Scheme objects that capture a complete dependency graph and associated build procedures, it is often useful to @@ -7878,7 +7873,7 @@ write procedures that take a package and return a modified version thereof according to some parameters. Below are a few examples. @cindex tool chain, choosing a package's tool chain -@deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain} +@defun package-with-c-toolchain package toolchain Return a variant of @var{package} that uses @var{toolchain} instead of the default GNU C/C++ toolchain. @var{toolchain} must be a list of inputs (label/package tuples) providing equivalent functionality, such @@ -7899,7 +7894,7 @@ fields and is instead pulled in by the build system. Consequently, this procedure works by changing the build system of @var{package} so that it pulls in @var{toolchain} instead of the defaults. @ref{Build Systems}, for more on build systems. -@end deffn +@end defun @node origin Reference @subsection @code{origin} Reference @@ -8016,8 +8011,7 @@ retrieved is determined by its @code{method} field. The @code{(guix download)} module provides the most common method, @code{url-fetch}, described below. -@deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @ - [name] [#:executable? #f] +@defun url-fetch url hash-algo hash [name] [#:executable? #f] Return a fixed-output derivation that fetches data from @var{url} (a string, or a list of strings denoting alternate URLs), which is expected to have hash @var{hash} of type @var{hash-algo} (a symbol). By default, @@ -8030,19 +8024,19 @@ interpreted as the name of a mirror scheme, taken from @file{%mirror-file}. Alternatively, when URL starts with @code{file://}, return the corresponding file name in the store. -@end deffn +@end defun Likewise, the @code{(guix git-download)} module defines the @code{git-fetch} origin method, which fetches data from a Git version control repository, and the @code{git-reference} data type to describe the repository and revision to fetch. -@deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash} +@defun git-fetch ref hash-algo hash Return a fixed-output derivation that fetches @var{ref}, a @code{} object. The output is expected to have recursive hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as the file name, or a generic name if @code{#f}. -@end deffn +@end defun @deftp {Data Type} git-reference This data type represents a Git reference for @code{git-fetch} to @@ -8085,13 +8079,12 @@ For Mercurial repositories, the module @code{(guix hg-download)} defines the @code{hg-fetch} origin method and @code{hg-reference} data type for support of the Mercurial version control system. -@deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @ - [name] +@defun hg-fetch ref hash-algo hash [name] Return a fixed-output derivation that fetches @var{ref}, a @code{} object. The output is expected to have recursive hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as the file name, or a generic name if @code{#false}. -@end deffn +@end defun @node Defining Package Variants @section Defining Package Variants @@ -8242,7 +8235,7 @@ These are pretty simple package variants. As a convenience, the that directly maps to the more sophisticated package transformation options (@pxref{Package Transformation Options}): -@deffn {Scheme Procedure} options->transformation @var{opts} +@defun options->transformation opts Return a procedure that, when passed an object to build (package, derivation, etc.), applies the transformations specified by @var{opts} and returns the resulting objects. @var{opts} must be a list of symbol/string pairs such as: @@ -8254,7 +8247,7 @@ the resulting objects. @var{opts} must be a list of symbol/string pairs such as Each symbol names a transformation and the corresponding string is an argument to that transformation. -@end deffn +@end defun For instance, a manifest equivalent to this command: @@ -8293,8 +8286,7 @@ Dependency graph rewriting, for the purposes of swapping packages in the graph, is what the @code{package-input-rewriting} procedure in @code{(guix packages)} implements. -@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @ - [@var{rewrite-name}] [#:deep? #t] +@defun package-input-rewriting replacements [rewrite-name] [#:deep? #t] Return a procedure that, when passed a package, replaces its direct and indirect dependencies, including implicit inputs when @var{deep?} is true, according to @var{replacements}. @var{replacements} is a list of @@ -8303,7 +8295,7 @@ and the second one is the replacement. Optionally, @var{rewrite-name} is a one-argument procedure that takes the name of a package and returns its new name after rewrite. -@end deffn +@end defun @noindent Consider this example: @@ -8356,12 +8348,12 @@ A more generic procedure to rewrite a package dependency graph is @code{package-mapping}: it supports arbitrary changes to nodes in the graph. -@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] [#:deep? #f] +@defun package-mapping proc [cut?] [#:deep? #f] Return a procedure that, given a package, applies @var{proc} to all the packages depended on and returns the resulting package. The procedure stops recursion when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is applied to implicit inputs as well. -@end deffn +@end defun @node Writing Manifests @section Writing Manifests @@ -8566,15 +8558,14 @@ related to a manifest entry coming from a @code{dependencies} field. @end table @end deftp -@deffn {Scheme Procedure} concatenate-manifests @var{lst} +@defun concatenate-manifests lst Concatenate the manifests listed in @var{lst} and return the resulting manifest. -@end deffn +@end defun @c TODO: , manifest-lookup, manifest-remove, etc. -@deffn {Scheme Procedure} package->manifest-entry @var{package} @ - [@var{output}] [#:properties] +@defun package->manifest-entry package [output] [#:properties] Return a manifest entry for the @var{output} of package @var{package}, where @var{output} defaults to @code{"out"}, and with the given @var{properties}. By default @var{properties} is the empty list or, if @@ -8592,9 +8583,9 @@ output and the @code{send-email} output of the @code{git} package: (manifest (list (package->manifest-entry git) (package->manifest-entry git "send-email"))) @end lisp -@end deffn +@end defun -@deffn {Scheme Procedure} packages->manifest @var{packages} +@defun packages->manifest packages Return a list of manifest entries, one for each item listed in @var{packages}. Elements of @var{packages} can be either package objects or package/string tuples denoting a specific output of a @@ -8608,11 +8599,10 @@ concisely: (packages->manifest (list git `(,git "send-email"))) @end lisp -@end deffn +@end defun @anchor{package-development-manifest} -@deffn {Scheme Procedure} package->development-manifest @var{package} @ - [@var{system}] [#:target] +@defun package->development-manifest package [system] [#:target] Return a manifest for the @dfn{development inputs} of @var{package} for @var{system}, optionally when cross-compiling to @var{target}. Development inputs include both explicit and implicit inputs of @@ -8640,7 +8630,7 @@ In this example, the development manifest that (GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and a couple of additional development tools---these are the dependencies @command{guix show inkscape} lists. -@end deffn +@end defun @c TODO: Move (gnu packages) interface to a section of its own. @@ -8648,7 +8638,7 @@ Last, the @code{(gnu packages)} module provides higher-level facilities to build manifests. In particular, it lets you look up packages by name---see below. -@deffn {Scheme Procedure} specifications->manifest @var{specs} +@defun specifications->manifest specs Given @var{specs}, a list of specifications such as @code{"emacs@@25.2"} or @code{"guile:debug"}, return a manifest. Specs have the format that command-line tools such as @command{guix install} and @command{guix @@ -8665,7 +8655,7 @@ Notice that we do not need to worry about @code{use-modules}, importing the right set of modules, and referring to the right variables. Instead, we directly refer to packages in the same way as on the command line, which can often be more convenient. -@end deffn +@end defun @c TODO: specifications->package, etc. @@ -10117,54 +10107,54 @@ procedures provided by @code{(guix build utils)}. This section documents procedures that deal with store file names. -@deffn {Scheme Procedure} %store-directory +@defun %store-directory Return the directory name of the store. -@end deffn +@end defun -@deffn {Scheme Procedure} store-file-name? @var{file} +@defun store-file-name? file Return true if @var{file} is in the store. -@end deffn +@end defun -@deffn {Scheme Procedure} strip-store-file-name @var{file} +@defun strip-store-file-name file Strip the @file{/gnu/store} and hash from @var{file}, a store file name. The result is typically a @code{"@var{package}-@var{version}"} string. -@end deffn +@end defun -@deffn {Scheme Procedure} package-name->name+version @var{name} +@defun package-name->name+version name Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two values: @code{"foo"} and @code{"0.9.1b"}. When the version part is unavailable, @var{name} and @code{#f} are returned. The first hyphen followed by a digit is considered to introduce the version part. -@end deffn +@end defun @subsection File Types The procedures below deal with files and file types. -@deffn {Scheme Procedure} directory-exists? @var{dir} +@defun directory-exists? dir Return @code{#t} if @var{dir} exists and is a directory. -@end deffn +@end defun -@deffn {Scheme Procedure} executable-file? @var{file} +@defun executable-file? file Return @code{#t} if @var{file} exists and is executable. -@end deffn +@end defun -@deffn {Scheme Procedure} symbolic-link? @var{file} +@defun symbolic-link? file Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink''). -@end deffn +@end defun -@deffn {Scheme Procedure} elf-file? @var{file} -@deffnx {Scheme Procedure} ar-file? @var{file} -@deffnx {Scheme Procedure} gzip-file? @var{file} +@defun elf-file? file +@defunx ar-file? file +@defunx gzip-file? file Return @code{#t} if @var{file} is, respectively, an ELF file, an @code{ar} archive (such as a @file{.a} static library), or a gzip file. -@end deffn +@end defun -@deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t] +@defun reset-gzip-timestamp file [#:keep-mtime? #t] If @var{file} is a gzip file, reset its embedded timestamp (as with @command{gzip --no-name}) and return true. Otherwise return @code{#f}. When @var{keep-mtime?} is true, preserve @var{file}'s modification time. -@end deffn +@end defun @subsection File Manipulation @@ -10185,20 +10175,20 @@ normal procedure return or @i{via} a non-local exit such as an exception. @end deffn -@deffn {Scheme Procedure} mkdir-p @var{dir} +@defun mkdir-p dir Create directory @var{dir} and all its ancestors. -@end deffn +@end defun -@deffn {Scheme Procedure} install-file @var{file} @var{directory} +@defun install-file file directory Create @var{directory} if it does not exist and copy @var{file} in there under the same name. -@end deffn +@end defun -@deffn {Scheme Procedure} make-file-writable @var{file} +@defun make-file-writable file Make @var{file} writable for its owner. -@end deffn +@end defun -@deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @ +@defun copy-recursively source destination @ [#:log (current-output-port)] [#:follow-symlinks? #f] @ [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t] Copy @var{source} directory to @var{destination}. Follow symlinks if @@ -10207,14 +10197,13 @@ Copy @var{source} directory to @var{destination}. Follow symlinks if keep the modification time of the files in @var{source} on those of @var{destination}. When @var{keep-permissions?} is true, preserve file permissions. Write verbose output to the @var{log} port. -@end deffn +@end defun -@deffn {Scheme Procedure} delete-file-recursively @var{dir} @ - [#:follow-mounts? #f] +@defun delete-file-recursively dir [#:follow-mounts? #f] Delete @var{dir} recursively, like @command{rm -rf}, without following symlinks. Don't follow mount points either, unless @var{follow-mounts?} is true. Report but ignore errors. -@end deffn +@end defun @deffn {Scheme Syntax} substitute* @var{file} @ ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{} @@ -10250,12 +10239,12 @@ won't match the terminating newline of a line. @cindex file, searching This section documents procedures to search and filter files. -@deffn {Scheme Procedure} file-name-predicate @var{regexp} +@defun file-name-predicate regexp Return a predicate that returns true when passed a file name whose base name matches @var{regexp}. -@end deffn +@end defun -@deffn {Scheme Procedure} find-files @var{dir} [@var{pred}] @ +@defun find-files dir [pred] @ [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f] Return the lexicographically sorted list of files under @var{dir} for which @var{pred} returns true. @var{pred} is passed two arguments: the @@ -10266,7 +10255,7 @@ case it is equivalent to @code{(file-name-predicate @var{pred})}. that symlinks are not followed. If @var{directories?} is true, then directories will also be included. If @var{fail-on-error?} is true, raise an exception upon error. -@end deffn +@end defun Here are a few examples where we assume that the current directory is the root of the Guix source tree: @@ -10285,13 +10274,13 @@ the root of the Guix source tree: @result{} ("./libformat.a" "./libstore.a" @dots{}) @end lisp -@deffn {Scheme Procedure} which @var{program} +@defun which program Return the complete file name for @var{program} as found in @code{$PATH}, or @code{#f} if @var{program} could not be found. -@end deffn +@end defun -@deffn {Scheme Procedure} search-input-file @var{inputs} @var{name} -@deffnx {Scheme Procedure} search-input-directory @var{inputs} @var{name} +@defun search-input-file inputs name +@defunx search-input-directory inputs name Return the complete file name for @var{name} as found in @var{inputs}; @code{search-input-file} searches for a regular file and @code{search-input-directory} searches for a directory. If @var{name} @@ -10300,7 +10289,7 @@ could not be found, an exception is raised. Here, @var{inputs} must be an association list like @code{inputs} and @code{native-inputs} as available to build phases (@pxref{Build Phases}). -@end deffn +@end defun Here is a (simplified) example of how @code{search-input-file} is used in a build phase of the @code{wireguard-tools} package: @@ -10323,7 +10312,7 @@ You'll find handy procedures to spawn processes in this module, essentially convenient wrappers around Guile's @code{system*} (@pxref{Processes, @code{system*},, guile, GNU Guile Reference Manual}). -@deffn {Scheme Procedure} invoke @var{program} @var{args}@dots{} +@defun invoke program args@dots{} Invoke @var{program} with the given @var{args}. Raise an @code{&invoke-error} exception if the exit code is non-zero; otherwise return @code{#t}. @@ -10331,21 +10320,21 @@ return @code{#t}. The advantage compared to @code{system*} is that you do not need to check the return value. This reduces boilerplate in shell-script-like snippets for instance in package build phases. -@end deffn +@end defun -@deffn {Scheme Procedure} invoke-error? @var{c} +@defun invoke-error? c Return true if @var{c} is an @code{&invoke-error} condition. -@end deffn +@end defun -@deffn {Scheme Procedure} invoke-error-program @var{c} -@deffnx {Scheme Procedure} invoke-error-arguments @var{c} -@deffnx {Scheme Procedure} invoke-error-exit-status @var{c} -@deffnx {Scheme Procedure} invoke-error-term-signal @var{c} -@deffnx {Scheme Procedure} invoke-error-stop-signal @var{c} +@defun invoke-error-program c +@defunx invoke-error-arguments c +@defunx invoke-error-exit-status c +@defunx invoke-error-term-signal c +@defunx invoke-error-stop-signal c Access specific fields of @var{c}, an @code{&invoke-error} condition. -@end deffn +@end defun -@deffn {Scheme Procedure} report-invoke-error @var{c} [@var{port}] +@defun report-invoke-error c [port] Report to @var{port} (by default the current error port) about @var{c}, an @code{&invoke-error} condition, in a human-friendly way. @@ -10361,9 +10350,9 @@ Typical usage would look like this: @print{} command "date" "--imaginary-option" failed with status 1 @end lisp -@end deffn +@end defun -@deffn {Scheme Procedure} invoke/quiet @var{program} @var{args}@dots{} +@defun invoke/quiet program args@dots{} Invoke @var{program} with @var{args} and capture @var{program}'s standard output and standard error. If @var{program} succeeds, print nothing and return the unspecified value; otherwise, raise a @@ -10387,7 +10376,7 @@ Here's an example: date: unrecognized option '--imaginary-option' Try 'date --help' for more information. @end lisp -@end deffn +@end defun @subsection Build Phases @@ -10497,8 +10486,7 @@ are always found. The wrapper would be used to set @env{PATH}, To ease that task, the @code{(guix build utils)} module provides a couple of helpers to wrap commands. -@deffn {Scheme Procedure} wrap-program @var{program} @ - [#:sh @var{sh}] [#:rest @var{variables}] +@defun wrap-program program [#:sh sh] [#:rest variables] Make a wrapper for @var{program}. @var{variables} should look like this: @lisp @@ -10530,10 +10518,9 @@ exec -a $0 location/of/.foo-real "$@@" If @var{program} has previously been wrapped by @code{wrap-program}, the wrapper is extended with definitions for @var{variables}. If it is not, @var{sh} will be used as the interpreter. -@end deffn +@end defun -@deffn {Scheme Procedure} wrap-script @var{program} @ - [#:guile @var{guile}] [#:rest @var{variables}] +@defun wrap-script program [#:guile guile] [#:rest variables] Wrap the script @var{program} such that @var{variables} are set first. The format of @var{variables} is the same as in the @code{wrap-program} procedure. This procedure differs from @code{wrap-program} in that it @@ -10546,7 +10533,7 @@ second line. Note that this procedure can only be used once per file as Guile scripts are not supported. -@end deffn +@end defun @node Search Paths @section Search Paths @@ -10735,13 +10722,12 @@ How do you turn search path specifications on one hand and a bunch of directories on the other hand in a set of environment variable definitions? That's the job of @code{evaluate-search-paths}. -@deffn {Scheme Procedure} evaluate-search-paths @var{search-paths} @ - @var{directories} [@var{getenv}] +@defun evaluate-search-paths search-paths directories [getenv] Evaluate @var{search-paths}, a list of search-path specifications, for @var{directories}, a list of directory names, and return a list of specification/value pairs. Use @var{getenv} to determine the current settings and report only settings not already effective. -@end deffn +@end defun The @code{(guix profiles)} provides a higher-level helper procedure, @code{load-profile}, that sets the environment variables of a profile. @@ -10845,7 +10831,7 @@ share any problems or suggestions you may have (@pxref{Contributing}). @end quotation @end defvr -@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t] +@defun open-connection [uri] [#:reserve-space? #t] Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When @var{reserve-space?} is true, instruct it to reserve a little bit of extra space on the file system so that the garbage collector can still @@ -10853,11 +10839,11 @@ operate should the disk become full. Return a server object. @var{file} defaults to @code{%default-socket-path}, which is the normal location given the options that were passed to @command{configure}. -@end deffn +@end defun -@deffn {Scheme Procedure} close-connection @var{server} +@defun close-connection server Close the connection to @var{server}. -@end deffn +@end defun @defvar current-build-output-port This variable is bound to a SRFI-39 parameter, which refers to the port @@ -10867,8 +10853,8 @@ where build and error logs sent by the daemon should be written. Procedures that make RPCs all take a server object as their first argument. -@deffn {Scheme Procedure} valid-path? @var{server} @var{path} @cindex invalid store items +@defun valid-path? server path Return @code{#t} when @var{path} designates a valid store item and @code{#f} otherwise (an invalid item may exist on disk but still be invalid, for instance because it is the result of an aborted or failed @@ -10876,20 +10862,19 @@ build). A @code{&store-protocol-error} condition is raised if @var{path} is not prefixed by the store directory (@file{/gnu/store}). -@end deffn +@end defun -@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}] +@defun add-text-to-store server name text [references] Add @var{text} under file @var{name} in the store, and return its store path. @var{references} is the list of store paths referred to by the resulting store path. -@end deffn +@end defun -@deffn {Scheme Procedure} build-derivations @var{store} @var{derivations} @ - [@var{mode}] +@defun build-derivations store derivations [mode] Build @var{derivations}, a list of @code{} objects, @file{.drv} file names, or derivation/output pairs, using the specified @var{mode}---@code{(build-mode normal)} by default. -@end deffn +@end defun Note that the @code{(guix monads)} module provides a monad as well as monadic versions of the above procedures, with the goal of making it @@ -10963,8 +10948,8 @@ derivations as Scheme objects, along with procedures to create and otherwise manipulate derivations. The lowest-level primitive to create a derivation is the @code{derivation} procedure: -@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @ - @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ +@defun derivation store name builder args @ + [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @ [#:system (%current-system)] [#:references-graphs #f] @ [#:allowed-references #f] [#:disallowed-references #f] @ @@ -11009,7 +10994,7 @@ host CPU instruction set. @var{properties} must be an association list describing ``properties'' of the derivation. It is kept as-is, uninterpreted, in the derivation. -@end deffn +@end defun @noindent Here's an example with a shell script as its builder, assuming @@ -11042,8 +11027,7 @@ derivations with build code written in Scheme was achieved with @code{build-expression->derivation}, documented below. This procedure is now deprecated in favor of the much nicer @code{gexp->derivation}. -@deffn {Scheme Procedure} build-expression->derivation @var{store} @ - @var{name} @var{exp} @ +@defun build-expression->derivation store name exp @ [#:system (%current-system)] [#:inputs '()] @ [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ @@ -11075,7 +11059,7 @@ See the @code{derivation} procedure for the meaning of @var{references-graphs}, @var{allowed-references}, @var{disallowed-references}, @var{local-build?}, and @var{substitutable?}. -@end deffn +@end defun @noindent Here's an example of a single-output derivation that creates a directory @@ -11330,10 +11314,10 @@ Pop a value from the current state and return it as a monadic value. The state is assumed to be a list. @end deffn -@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}] +@defun run-with-state mval [state] Run monadic value @var{mval} starting with @var{state} as the initial state. Return two values: the resulting value, and the resulting state. -@end deffn +@end defun The main interface to the store monad, provided by the @code{(guix store)} module, is as follows. @@ -11346,10 +11330,11 @@ effect is needed, a value of the store monad must be ``evaluated'' by passing it to the @code{run-with-store} procedure (see below). @end defvar -@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)] +@defun run-with-store store mval @ + [#:guile-for-build] [#:system (%current-system)] Run @var{mval}, a monadic value in the store monad, in @var{store}, an open store connection. -@end deffn +@end defun @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}] Return as a monadic value the absolute file name in the store of the file @@ -11693,9 +11678,9 @@ are also added to the load path of the gexp returned by @var{body}@dots{}. @end deffn -@deffn {Scheme Procedure} gexp? @var{obj} +@defun gexp? obj Return @code{#t} if @var{obj} is a G-expression. -@end deffn +@end defun G-expressions are meant to be written to disk, either as code building some derivation, or as plain files in the store. The monadic procedures @@ -11782,8 +11767,7 @@ does not have any effect on what the G-expression does. @code{plain-file} can be used similarly; it differs in that the file content is directly passed as a string. -@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @ - [#:recursive? #f] [#:select? (const #t)] +@defun local-file file [name] [#:recursive? #f] [#:select? (const #t)] Return an object representing local file @var{file} to add to the store; this object can be used in a gexp. If @var{file} is a literal string denoting a relative file name, it is looked up relative to the source @@ -11803,24 +11787,23 @@ entries for which @var{select?} does not return true. This is the declarative counterpart of the @code{interned-file} monadic procedure (@pxref{The Store Monad, @code{interned-file}}). -@end deffn +@end defun -@deffn {Scheme Procedure} plain-file @var{name} @var{content} +@defun plain-file name content Return an object representing a text file called @var{name} with the given @var{content} (a string or a bytevector) to be added to the store. This is the declarative counterpart of @code{text-file}. -@end deffn +@end defun -@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @ - [#:local-build? #t] [#:options '()] +@defun computed-file name gexp [#:local-build? #t] [#:options '()] Return an object representing the store item @var{name}, a file or directory computed by @var{gexp}. When @var{local-build?} is true (the default), the derivation is built locally. @var{options} is a list of additional arguments to pass to @code{gexp->derivation}. This is the declarative counterpart of @code{gexp->derivation}. -@end deffn +@end defun @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @ [#:guile (default-guile)] [#:module-path %load-path] @ @@ -11851,14 +11834,13 @@ executable file @file{/gnu/store/@dots{}-list-files} along these lines: @end example @end deffn -@deffn {Scheme Procedure} program-file @var{name} @var{exp} @ - [#:guile #f] [#:module-path %load-path] +@defun program-file name exp [#:guile #f] [#:module-path %load-path] Return an object representing the executable store item @var{name} that runs @var{gexp}. @var{guile} is the Guile package used to execute that script. Imported modules of @var{gexp} are looked up in @var{module-path}. This is the declarative counterpart of @code{gexp->script}. -@end deffn +@end defun @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @ [#:set-load-path? #t] [#:module-path %load-path] @ @@ -11877,13 +11859,12 @@ The resulting file holds references to all the dependencies of @var{exp} or a subset thereof. @end deffn -@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @ - [#:splice? #f] [#:set-load-path? #t] +@defun scheme-file name exp [#:splice? #f] [#:set-load-path? #t] Return an object representing the Scheme file @var{name} that contains @var{exp}. This is the declarative counterpart of @code{gexp->file}. -@end deffn +@end defun @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{} Return as a monadic value a derivation that builds a text file @@ -11911,7 +11892,7 @@ will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby preventing them from being garbage-collected during its lifetime. @end deffn -@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{} +@defun mixed-text-file name text @dots{} Return an object representing store file @var{name} containing @var{text}. @var{text} is a sequence of strings and file-like objects, as in: @@ -11922,9 +11903,9 @@ as in: @end lisp This is the declarative counterpart of @code{text-file*}. -@end deffn +@end defun -@deffn {Scheme Procedure} file-union @var{name} @var{files} +@defun file-union name files Return a @code{} that builds a directory containing all of @var{files}. Each item in @var{files} must be a two-element list where the first element is the file name to use in the new directory, and the second element is a gexp @@ -11939,9 +11920,9 @@ denoting the target file. Here's an example: @end lisp This yields an @code{etc} directory containing these two files. -@end deffn +@end defun -@deffn {Scheme Procedure} directory-union @var{name} @var{things} +@defun directory-union name things Return a directory that is the union of @var{things}, where @var{things} is a list of file-like objects denoting directories. For example: @@ -11950,9 +11931,9 @@ file-like objects denoting directories. For example: @end lisp yields a directory that is the union of the @code{guile} and @code{emacs} packages. -@end deffn +@end defun -@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{} +@defun file-append obj suffix @dots{} Return a file-like object that expands to the concatenation of @var{obj} and @var{suffix}, where @var{obj} is a lowerable object and each @var{suffix} is a string. @@ -11977,7 +11958,7 @@ There is one difference though: in the @code{file-append} case, the resulting script contains the absolute file name as a string, whereas in the second case, the resulting script contains a @code{(string-append @dots{})} expression to construct the file name @emph{at run time}. -@end deffn +@end defun @deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{} @deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{} @@ -12044,7 +12025,7 @@ corresponding to @var{obj} for @var{system}, cross-compiling for has an associated gexp compiler, such as a @code{}. @end deffn -@deffn {Procedure} gexp->approximate-sexp @var{gexp} +@defun gexp->approximate-sexp gexp Sometimes, it may be useful to convert a G-exp into a S-exp. For example, some linters (@pxref{Invoking guix lint}) peek into the build phases of a package to detect potential problems. This conversion can @@ -12052,7 +12033,7 @@ be achieved with this procedure. However, some information can be lost in the process. More specifically, lowerable objects will be silently replaced with some arbitrary object -- currently the list @code{(*approximate*)}, but this may change. -@end deffn +@end defun @node Invoking guix repl @section Invoking @command{guix repl} @@ -16868,7 +16849,7 @@ example for an encrypted partition (@pxref{Mapped Devices}). @end table @end deftp -@deffn {Scheme Procedure} file-system-label @var{str} +@defun file-system-label str This procedure returns an opaque file system label from @var{str}, a string: @@ -16879,7 +16860,7 @@ string: File system labels are used to refer to file systems by label rather than by device name. See above for examples. -@end deffn +@end defun The @code{(gnu system file-systems)} exports the following useful variables. @@ -16930,7 +16911,7 @@ and unmount user-space FUSE file systems. This requires the The @code{(gnu system uuid)} module provides tools to deal with file system ``unique identifiers'' (UUIDs). -@deffn {Scheme Procedure} uuid @var{str} [@var{type}] +@defun uuid str [type] Return an opaque UUID (unique identifier) object of the given @var{type} (a symbol) by parsing @var{str} (a string): @@ -16947,7 +16928,7 @@ Return an opaque UUID (unique identifier) object of the given @var{type} UUIDs are another way to unambiguously refer to file systems in operating system configuration. See the examples above. -@end deffn +@end defun @node Btrfs file system @@ -17610,14 +17591,13 @@ optional variant name, an optional keyboard model name, and a possibly empty list of additional options. In most cases the layout name is all you care about. -@deffn {Scheme Procedure} keyboard-layout @var{name} [@var{variant}] @ - [#:model] [#:options '()] +@defun keyboard-layout name [variant] [#:model] [#:options '()] Return a new keyboard layout with the given @var{name} and @var{variant}. @var{name} must be a string such as @code{"fr"}; @var{variant} must be a string such as @code{"bepo"} or @code{"nodeadkeys"}. See the @code{xkeyboard-config} package for valid options. -@end deffn +@end defun Here are a few examples: @@ -18009,7 +17989,7 @@ to add a special file is @i{via} the @code{extra-special-file} procedure (see below). @end defvar -@deffn {Scheme Procedure} extra-special-file @var{file} @var{target} +@defun extra-special-file file target Use @var{target} as the ``special file'' @var{file}. For example, adding the following lines to the @code{services} field of @@ -18020,7 +18000,7 @@ symlink: (extra-special-file "/usr/bin/env" (file-append coreutils "/bin/env")) @end lisp -@end deffn +@end defun @defvar host-name-service-type Type of the service that sets the system host name, whose value @@ -22196,23 +22176,22 @@ default is @code{-nolisten tcp}. @end table @end deftp -@deffn {Scheme Procedure} set-xorg-configuration @var{config} @ - [@var{login-manager-service-type}] +@defun set-xorg-configuration config [login-manager-service-type] Tell the log-in manager (of type @var{login-manager-service-type}) to use @var{config}, an @code{} record. Since the Xorg configuration is embedded in the log-in manager's configuration---e.g., @code{gdm-configuration}---this procedure provides a shorthand to set the Xorg configuration. -@end deffn +@end defun -@deffn {Scheme Procedure} xorg-start-command [@var{config}] +@defun xorg-start-command [config] Return a @code{startx} script in which the modules, fonts, etc. specified in @var{config}, are available. The result should be used in place of @code{startx}. Usually the X server is started by a login manager. -@end deffn +@end defun @defvar screen-locker-service-type @@ -23653,7 +23632,7 @@ a system which relies on @code{%desktop-services}, you may use @end lisp @end defvar -@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] +@defun geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] Return a configuration allowing an application to access GeoClue location data. @var{name} is the Desktop ID of the application, without the @code{.desktop} part. If @var{allowed?} is true, the application @@ -23662,7 +23641,7 @@ will have access to location information by default. The boolean or not. Finally @var{users} is a list of UIDs of all users for which this application is allowed location info access. An empty users list means that all users are allowed. -@end deffn +@end defun @defvar %standard-geoclue-applications The standard list of well-known GeoClue application configurations, @@ -27624,7 +27603,7 @@ client is already being used. Otherwise, the procedures provided by this module can be used to obtain a suitable hash value. -@deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt} +@defun transmission-password-hash password salt Returns a string containing the result of hashing @var{password} together with @var{salt}, in the format recognized by Transmission clients for their @code{rpc-password} configuration setting. @@ -27632,13 +27611,13 @@ clients for their @code{rpc-password} configuration setting. @var{salt} must be an eight-character string. The @code{transmission-random-salt} procedure can be used to generate a suitable salt value at random. -@end deffn +@end defun -@deffn {Scheme Procedure} transmission-random-salt +@defun transmission-random-salt Returns a string containing a random, eight-character salt value of the type generated and used by Transmission clients, suitable for passing to the @code{transmission-password-hash} procedure. -@end deffn +@end defun These procedures are accessible from within a Guile REPL started with the @command{guix repl} command (@pxref{Invoking guix repl}). This is @@ -30535,13 +30514,11 @@ The time in seconds after which a process with no requests is killed. @end deftp -@deffn {Scheme Procedure} nginx-php-location @ - [#:nginx-package nginx] @ - [socket (string-append "/var/run/php" @ - (version-major (package-version php)) @ - "-fpm.sock")] +@defun nginx-php-location [#:nginx-package nginx] @ + [socket (string-append "/var/run/php" @ + (version-major (package-version php)) "-fpm.sock")] A helper function to quickly add php to an @code{nginx-server-configuration}. -@end deffn +@end defun A simple services setup for nginx with php can look like this: @lisp @@ -30564,7 +30541,7 @@ The cat avatar generator is a simple service to demonstrate the use of php-fpm in @code{Nginx}. It is used to generate cat avatar from a seed, for instance the hash of a user's email address. -@deffn {Scheme Procedure} cat-avatar-generator-service @ +@defun cat-avatar-generator-service @ [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package cat-avatar-generator] @ [#:configuration (nginx-server-configuration)] @@ -30572,7 +30549,7 @@ Returns an nginx-server-configuration that inherits @code{configuration}. It extends the nginx configuration to add a server block that serves @code{package}, a version of cat-avatar-generator. During execution, cat-avatar-generator will be able to use @code{cache-dir} as its cache directory. -@end deffn +@end defun A simple setup for cat-avatar-generator can look like this: @lisp @@ -34579,20 +34556,20 @@ The QEMU package to use. @end table @end deftp -@deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{} +@defun lookup-qemu-platforms platforms@dots{} Return the list of QEMU platform objects corresponding to @var{platforms}@dots{}. @var{platforms} must be a list of strings corresponding to platform names, such as @code{"arm"}, @code{"sparc"}, @code{"mips64el"}, and so on. -@end deffn +@end defun -@deffn {Scheme Procedure} qemu-platform? @var{obj} +@defun qemu-platform? obj Return true if @var{obj} is a platform object. -@end deffn +@end defun -@deffn {Scheme Procedure} qemu-platform-name @var{platform} +@defun qemu-platform-name platform Return the name of @var{platform}---a string such as @code{"arm"}. -@end deffn +@end defun @subsubheading QEMU Guest Agent @@ -35088,27 +35065,27 @@ Alignment of the partition in sectors. @end table @end deftp -@deffn {Scheme Procedure} debootstrap-variant @var{name} @var{configuration} +@defun debootstrap-variant name configuration This is a helper procedure that creates a @code{ganeti-os-variant} record. It takes two parameters: a name and a @code{debootstrap-configuration} object. -@end deffn +@end defun -@deffn {Scheme Procedure} debootstrap-os @var{variants}@dots{} +@defun debootstrap-os variants@dots{} This is a helper procedure that creates a @code{ganeti-os} record. It takes a list of variants created with @code{debootstrap-variant}. -@end deffn +@end defun -@deffn {Scheme Procedure} guix-variant @var{name} @var{configuration} +@defun guix-variant name configuration This is a helper procedure that creates a @code{ganeti-os-variant} record for use with the Guix OS provider. It takes a name and a G-expression that returns a ``file-like'' (@pxref{G-Expressions, file-like objects}) object containing a Guix System configuration. -@end deffn +@end defun -@deffn {Scheme Procedure} guix-os @var{variants}@dots{} +@defun guix-os variants@dots{} This is a helper procedure that creates a @code{ganeti-os} record. It takes a list of variants produced by @code{guix-variant}. -@end deffn +@end defun @defvar %default-debootstrap-variants This is a convenience variable to make the debootstrap provider work @@ -35606,7 +35583,7 @@ create an @code{nginx-location-configuration} from a @code{git-http-configuration} and then add that location to a web server. -@deffn {Scheme Procedure} git-http-nginx-location-configuration @ +@defun git-http-nginx-location-configuration @ [config=(git-http-configuration)] Compute an @code{nginx-location-configuration} that corresponds to the given Git http configuration. An example nginx service definition to @@ -35635,7 +35612,7 @@ certificate. @xref{Certificate Services}. The default @code{certbot} service will redirect all HTTP traffic on @code{git.my-host.org} to HTTPS@. You will also need to add an @code{fcgiwrap} proxy to your system services. @xref{Web Services}. -@end deffn +@end defun @subsubheading Cgit Service @@ -38252,7 +38229,7 @@ is an example of a basic, explicit configuration: @end lisp @end defvar -@deffn {Scheme Procedure} fail2ban-jail-service @var{svc-type} @var{jail} +@defun fail2ban-jail-service svc-type jail Extend @var{svc-type}, a @code{} object with @var{jail}, a @code{fail2ban-jail-configuration} object. @@ -38272,7 +38249,7 @@ For example: (enabled? #t))) (openssh-configuration ...)))) @end lisp -@end deffn +@end defun Below is the reference for the different @code{jail-service-type} configuration records. @@ -38879,7 +38856,7 @@ here is how to use it and customize it further. @cindex initrd @cindex initial RAM disk -@deffn {Scheme Procedure} raw-initrd @var{file-systems} @ +@defun raw-initrd file-systems @ [#:linux-modules '()] [#:pre-mount #t] [#:mapped-devices '()] @ [#:keyboard-layout #f] [#:helper-packages '()] @ [#:qemu-networking? #f] [#:volatile-root? #f] @@ -38908,9 +38885,9 @@ initrd can be used as a QEMU guest with para-virtualized I/O drivers. When @var{volatile-root?} is true, the root file system is writable but any changes to it are lost. -@end deffn +@end defun -@deffn {Scheme Procedure} base-initrd @var{file-systems} @ +@defun base-initrd file-systems @ [#:mapped-devices '()] [#:keyboard-layout #f] @ [#:qemu-networking? #f] [#:volatile-root? #f] @ [#:linux-modules '()] @@ -38932,7 +38909,7 @@ The initrd is automatically populated with all the kernel modules necessary for @var{file-systems} and for the given options. Additional kernel modules can be listed in @var{linux-modules}. They will be added to the initrd, and loaded at boot time in the order in which they appear. -@end deffn +@end defun Needless to say, the initrds we produce and use embed a statically-linked Guile, and the initialization program is a Guile @@ -38940,13 +38917,13 @@ program. That gives a lot of flexibility. The @code{expression->initrd} procedure builds such an initrd, given the program to run in that initrd. -@deffn {Scheme Procedure} expression->initrd @var{exp} @ +@defun expression->initrd exp @ [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a file-like object a Linux initrd (a gzipped cpio archive) containing @var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All the derivations referenced by @var{exp} are automatically copied to the initrd. -@end deffn +@end defun @node Bootloader Configuration @section Bootloader Configuration @@ -39292,14 +39269,14 @@ The GRUB @code{gfxmode} to set (a list of screen resolution strings, @end table @end deftp -@deffn {Scheme Procedure} grub-theme +@defun grub-theme Return the default GRUB theme used by the operating system if no @code{theme} field is specified in @code{bootloader-configuration} record. It comes with a fancy background image displaying the GNU and Guix logos. -@end deffn +@end defun For example, to override the default resolution, you may use something like @@ -40551,7 +40528,7 @@ Services}). This section provides a reference on how to manipulate services and service types. This interface is provided by the @code{(gnu services)} module. -@deffn {Scheme Procedure} service @var{type} [@var{value}] +@defun service type [value] Return a new service of @var{type}, a @code{} object (see below). @var{value} can be any object; it represents the parameters of this particular service instance. @@ -40576,20 +40553,20 @@ is equivalent to this: In both cases the result is an instance of @code{openssh-service-type} with the default configuration. -@end deffn +@end defun -@deffn {Scheme Procedure} service? @var{obj} +@defun service? obj Return true if @var{obj} is a service. -@end deffn +@end defun -@deffn {Scheme Procedure} service-kind @var{service} +@defun service-kind service Return the type of @var{service}---i.e., a @code{} object. -@end deffn +@end defun -@deffn {Scheme Procedure} service-value @var{service} +@defun service-value service Return the value associated with @var{service}. It represents its parameters. -@end deffn +@end defun Here is an example of how a service is created and manipulated: @@ -40710,24 +40687,23 @@ The returned service in this case has the default value specified by @xref{Service Types and Services}, for examples. @end deftp -@deffn {Scheme Procedure} service-extension @var{target-type} @ - @var{compute} +@defun service-extension target-type compute Return a new extension for services of type @var{target-type}. @var{compute} must be a one-argument procedure: @code{fold-services} calls it, passing it the value associated with the service that provides the extension; it must return a valid value for the target service. -@end deffn +@end defun -@deffn {Scheme Procedure} service-extension? @var{obj} +@defun service-extension? obj Return true if @var{obj} is a service extension. -@end deffn +@end defun Occasionally, you might want to simply extend an existing service. This involves creating a new service type and specifying the extension of interest, which can be verbose; the @code{simple-service} procedure provides a shorthand for this. -@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value} +@defun simple-service name target value Return a service that extends @var{target} with @var{value}. This works by creating a singleton service type @var{name}, of which the returned service is an instance. @@ -40739,7 +40715,7 @@ an additional job: (simple-service 'my-mcron-job mcron-service-type #~(job '(next-hour (3)) "guix gc -F 2G")) @end lisp -@end deffn +@end defun At the core of the service abstraction lies the @code{fold-services} procedure, which is responsible for ``compiling'' a list of services @@ -40749,11 +40725,10 @@ command (@pxref{Invoking guix system}). In essence, it propagates service extensions down the service graph, updating each node parameters on the way, until it reaches the root node. -@deffn {Scheme Procedure} fold-services @var{services} @ - [#:target-type @var{system-service-type}] +@defun fold-services services [#:target-type system-service-type] Fold @var{services} by propagating their extensions down to the root of type @var{target-type}; return the root service adjusted accordingly. -@end deffn +@end defun Lastly, the @code{(gnu services)} module also defines several essential service types, some of which are listed below. @@ -41036,7 +41011,7 @@ info on actions. @end deftp @cindex configuration file, of Shepherd services -@deffn {Scheme Procedure} shepherd-configuration-action +@defun shepherd-configuration-action Return a @code{configuration} action to display @var{file}, which should be the name of the service's configuration file. @@ -41066,7 +41041,7 @@ cat $(herd configuration tor) @end example This can come in as a handy debugging tool! -@end deffn +@end defun @defvar shepherd-root-service-type The service type for the Shepherd ``root service''---i.e., PID@tie{}1. @@ -41297,30 +41272,28 @@ whether its value is set or not. @end lisp @end deffn -@deffn (Scheme Procedure) maybe-value-set? @var{value} +@defun maybe-value-set? value Predicate to check whether a user explicitly specified the value of a maybe field. -@end deffn +@end defun -@deffn {Scheme Procedure} serialize-configuration @var{configuration} @ -@var{fields} +@defun serialize-configuration configuration fields Return a G-expression that contains the values corresponding to the @var{fields} of @var{configuration}, a record that has been generated by @code{define-configuration}. The G-expression can then be serialized to disk by using something like @code{mixed-text-file}. -@end deffn +@end defun -@deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value} +@defun empty-serializer field-name value A serializer that just returns an empty string. The @code{serialize-package} procedure is an alias for this. -@end deffn +@end defun Once you have defined a configuration record, you will most likely also want to document it so that other people know to use it. To help with that, there are two procedures, both of which are documented below. -@deffn {Scheme Procedure} generate-documentation @var{documentation} @ -@var{documentation-name} +@defun generate-documentation documentation documentation-name Generate a Texinfo fragment from the docstrings in @var{documentation}, a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}. @var{label} should be a symbol and should be the name of the @@ -41350,16 +41323,15 @@ record in one of its @code{rcfile} field, therefore documentation for @var{documentation-name} should be a symbol and should be the name of the configuration record. -@end deffn +@end defun -@deffn {Scheme Procedure} configuration->documentation -@var{configuration-symbol} +@defun configuration->documentation configuration-symbol Take @var{configuration-symbol}, the symbol corresponding to the name used when defining a configuration record with @code{define-configuration}, and print the Texinfo documentation of its fields. This is useful if there aren’t any nested configuration records since it only prints the documentation for the top-level fields. -@end deffn +@end defun As of right now, there is no automated way to generate documentation for configuration records and put them in the manual. Instead, every -- cgit 1.4.1 From 830497941526ac7320dcd4c5bb545ce9a040d1b1 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Wed, 8 Mar 2023 01:22:09 +0000 Subject: doc: Use @defmac and @defspec for macros. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (package Reference, Defining Package Variants) (Build Utilities, The Store Monad, G-Expressions, operating-system Reference) (Service Reference, Complex Configurations): Use @defmac and @defspec for macros. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 97 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 47 insertions(+), 50 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 539490d69b..39932d5aad 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -7781,7 +7781,7 @@ automatically corrected. @end table @end deftp -@deffn {Scheme Syntax} this-package +@defmac this-package When used in the @emph{lexical scope} of a package field definition, this identifier resolves to the package being defined. @@ -7801,7 +7801,7 @@ cross-compiling: @end lisp It is an error to refer to @code{this-package} outside a package definition. -@end deffn +@end defmac The following helper procedures are provided to help deal with package inputs. @@ -8160,7 +8160,7 @@ from the @code{inputs} field of @code{gdb}. The @code{modify-inputs} macro is a helper that can prove useful anytime you want to remove, add, or replace package inputs. -@deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses} +@defmac modify-inputs inputs clauses Modify the given package inputs, as returned by @code{package-inputs} & co., according to the given clauses. Each clause must have one of the following forms: @@ -8195,7 +8195,7 @@ The example below replaces the @code{guile} package from the inputs of The last type of clause is @code{append}, to add inputs at the back of the list. -@end deffn +@end defmac In some cases, you may find it useful to write functions (``procedures'', in Scheme parlance) that return a package based on some @@ -10164,7 +10164,7 @@ such as @command{mkdir -p}, @command{cp -r}, @command{rm -r}, and @command{sed}. They complement Guile's extensive, but low-level, file system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}). -@deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{} +@defmac with-directory-excursion directory body @dots{} Run @var{body} with @var{directory} as the process's current directory. Essentially, this macro changes the current directory to @var{directory} @@ -10173,7 +10173,7 @@ guile, GNU Guile Reference Manual}). It changes back to the initial directory when the dynamic extent of @var{body} is left, be it @i{via} normal procedure return or @i{via} a non-local exit such as an exception. -@end deffn +@end defmac @defun mkdir-p dir Create directory @var{dir} and all its ancestors. @@ -10205,8 +10205,8 @@ symlinks. Don't follow mount points either, unless @var{follow-mounts?} is true. Report but ignore errors. @end defun -@deffn {Scheme Syntax} substitute* @var{file} @ - ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{} +@defmac substitute* file @ + ((regexp match-var@dots{}) body@dots{}) @dots{} Substitute @var{regexp} in @var{file} by the string returned by @var{body}. @var{body} is evaluated with each @var{match-var} bound to the corresponding positional regexp sub-expression. For example: @@ -10232,7 +10232,7 @@ they are all subject to the substitutions. Be careful about using @code{$} to match the end of a line; by itself it won't match the terminating newline of a line. -@end deffn +@end defmac @subsection File Search @@ -10393,7 +10393,7 @@ manipulate alists. The @code{(guix build utils)} module complements those with tools written with build phases in mind. @cindex build phases, modifying -@deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{} +@defmac modify-phases phases clause@dots{} Modify @var{phases} sequentially as per each @var{clause}, which may have one of the following forms: @@ -10406,7 +10406,7 @@ have one of the following forms: Where every @var{phase-name} above is an expression evaluating to a symbol, and @var{new-phase} an expression evaluating to a procedure. -@end deffn +@end defmac The example below is taken from the definition of the @code{grep} package. It adds a phase to run after the @code{install} phase, called @@ -11193,16 +11193,16 @@ build a file-like object (@pxref{Using Guix Interactively}). The main syntactic forms to deal with monads in general are provided by the @code{(guix monads)} module and are described below. -@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ... +@defmac with-monad monad body @dots{} Evaluate any @code{>>=} or @code{return} forms in @var{body} as being in @var{monad}. -@end deffn +@end defmac -@deffn {Scheme Syntax} return @var{val} +@defmac return val Return a monadic value that encapsulates @var{val}. -@end deffn +@end defmac -@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ... +@defmac >>= mval mproc @dots{} @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic procedures @var{mproc}@dots{}@footnote{This operation is commonly referred to as ``bind'', but that name denotes an unrelated procedure in @@ -11221,12 +11221,10 @@ in this example: @result{} 4 @result{} some-state @end lisp -@end deffn +@end defmac -@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... -@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... +@defmac mlet monad ((var mval) @dots{}) body @dots{} +@defmacx mlet* monad ((var mval) @dots{}) body @dots{} Bind the variables @var{var} to the monadic values @var{mval} in @var{body}, which is a sequence of expressions. As with the bind operator, this can be thought of as ``unpacking'' the raw, non-monadic @@ -11240,9 +11238,9 @@ expression, and its result will become the result of the @code{mlet} or @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let} (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). -@end deffn +@end defmac -@deffn {Scheme System} mbegin @var{monad} @var{mexp} ... +@defmac mbegin monad mexp @dots{} Bind @var{mexp} and the following monadic expressions in sequence, returning the result of the last expression. Every expression in the sequence must be a monadic expression. @@ -11250,21 +11248,21 @@ sequence must be a monadic expression. This is akin to @code{mlet}, except that the return values of the monadic expressions are ignored. In that sense, it is analogous to @code{begin}, but applied to monadic expressions. -@end deffn +@end defmac -@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ... +@defmac mwhen condition mexp0 mexp* @dots{} When @var{condition} is true, evaluate the sequence of monadic expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is false, return @code{*unspecified*} in the current monad. Every expression in the sequence must be a monadic expression. -@end deffn +@end defmac -@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ... +@defmac munless condition mexp0 mexp* @dots{} When @var{condition} is false, evaluate the sequence of monadic expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is true, return @code{*unspecified*} in the current monad. Every expression in the sequence must be a monadic expression. -@end deffn +@end defmac @cindex state monad The @code{(guix monads)} module provides the @dfn{state monad}, which @@ -11585,8 +11583,8 @@ package available on the build side, here's how you would do it: The syntactic form to construct gexps is summarized below. -@deffn {Scheme Syntax} #~@var{exp} -@deffnx {Scheme Syntax} (gexp @var{exp}) +@defmac #~@var{exp} +@defmacx (gexp @var{exp}) Return a G-expression containing @var{exp}. @var{exp} may contain one or more of the following forms: @@ -11640,9 +11638,9 @@ Like the above, but refers to native builds of the objects listed in G-expressions created by @code{gexp} or @code{#~} are run-time objects of the @code{gexp?} type (see below). -@end deffn +@end defmac -@deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{} +@defmac with-imported-modules modules body@dots{} Mark the gexps defined in @var{body}@dots{} as requiring @var{modules} in their execution environment. @@ -11664,9 +11662,9 @@ path, and the last one is created from the given file-like object. This form has @emph{lexical} scope: it has an effect on the gexps directly defined in @var{body}@dots{}, but not on those defined, say, in procedures called from @var{body}@dots{}. -@end deffn +@end defmac -@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{} +@defmac with-extensions extensions body@dots{} Mark the gexps defined in @var{body}@dots{} as requiring @var{extensions} in their build and execution environment. @var{extensions} is typically a list of package objects such as those @@ -11676,7 +11674,7 @@ Concretely, the packages listed in @var{extensions} are added to the load path while compiling imported modules in @var{body}@dots{}; they are also added to the load path of the gexp returned by @var{body}@dots{}. -@end deffn +@end defmac @defun gexp? obj Return @code{#t} if @var{obj} is a G-expression. @@ -11960,8 +11958,8 @@ the second case, the resulting script contains a @code{(string-append @dots{})} expression to construct the file name @emph{at run time}. @end defun -@deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{} -@deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{} +@defmac let-system system body@dots{} +@defmacx let-system (system target) body@dots{} Bind @var{system} to the currently targeted system---e.g., @code{"x86_64-linux"}---within @var{body}. @@ -11984,9 +11982,9 @@ spliced into the gexp depends on the target system, as in this example: (error "dunno!")))) "-net" "user" #$image) @end lisp -@end deffn +@end defmac -@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp} +@defmac with-parameters ((parameter value) @dots{}) exp This macro is similar to the @code{parameterize} form for dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU Guile Reference Manual}). The key difference is that it takes effect @@ -12003,7 +12001,7 @@ for a given object: The example above returns an object that corresponds to the i686 build of Coreutils, regardless of the current value of @code{%current-system}. -@end deffn +@end defmac Of course, in addition to gexps embedded in ``host'' code, there are @@ -16654,7 +16652,7 @@ is that only @code{root} and members of the @code{wheel} group may use @end table -@deffn {Scheme Syntax} this-operating-system +@defmac this-operating-system When used in the @emph{lexical scope} of an operating system field definition, this identifier resolves to the operating system being defined. @@ -16672,7 +16670,7 @@ the definition of the @code{label} field: It is an error to refer to @code{this-operating-system} outside an operating system definition. -@end deffn +@end defmac @end deftp @@ -40595,8 +40593,8 @@ standard list combinators such as @code{map} and @code{fold} to do that @code{modify-services} simply provides a more concise form for this common pattern. -@deffn {Scheme Syntax} modify-services @var{services} @ - (@var{type} @var{variable} => @var{body}) @dots{} +@defspec modify-services services @ + (type variable => body) @dots{} Modify the services listed in @var{services} according to the given clauses. Each clause has the form: @@ -40629,7 +40627,7 @@ Such a clause removes all services of the given @var{type} from @xref{Using the Configuration System}, for example usage. -@end deffn +@end defspec Next comes the programming interface for service types. This is something you want to know when writing new service definitions, but not @@ -41105,8 +41103,7 @@ procedures that take some kind of Scheme value and returns a G-expression (@pxref{G-Expressions}), which should, once serialized to the disk, return a string. More details are listed below. -@deffn {Scheme Syntax} define-configuration @var{name} @var{clause1} @ -@var{clause2} ... +@defmac define-configuration name clause1 clause2 @dots{} Create a record type named @code{@var{name}} that contains the fields found in the clauses. @@ -41216,9 +41213,9 @@ macro which is a shorthand of this. (string "test") "Some documentation.")) @end lisp -@end deffn +@end defmac -@deffn {Scheme Syntax} define-maybe @var{type} +@defmac define-maybe type Sometimes a field should not be serialized if the user doesn’t specify a value. To achieve this, you can use the @code{define-maybe} macro to define a ``maybe type''; if the value of a maybe type is left unset, or @@ -41270,7 +41267,7 @@ whether its value is set or not. maybe-symbol "Docstring.")) @end lisp -@end deffn +@end defmac @defun maybe-value-set? value Predicate to check whether a user explicitly specified the value of a -- cgit 1.4.1 From 837e179e009cd55acc03193e5600fb0a8eb60e6b Mon Sep 17 00:00:00 2001 From: conses Date: Tue, 14 Mar 2023 13:36:36 +0100 Subject: home: services: Add home-unclutter-service-type. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gnu/home/services/desktop.scm (home-unclutter-configuration) (home-unclutter-service-type): New variables; (home-unclutter-shepherd-service): New procedure; * doc/guix.texi (Desktop Services): Document it. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 30 ++++++++++++++++++++++++ gnu/home/services/desktop.scm | 53 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 81 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 39932d5aad..56a24a1011 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -42541,6 +42541,36 @@ The package providing the @code{/bin/dbus-daemon} command. @end table @end deftp +@defvar home-unclutter-service-type +This is the service type for Unclutter, a program that runs on the +background of an X11 session and detects when the X pointer hasn't moved +for a specified idle timeout, after which it hides the cursor so that +you can focus on the text underneath. Its associated value must be a +@code{home-unclutter-configuration} record, as shown below. + +A typical configuration, where we manually specify the idle timeout (in +seconds), might look like this: + +@lisp +(service home-unclutter-service-type + (home-unclutter-configuration + (idle-timeout 2))) +@end lisp +@end defvar + +@deftp {Data Type} home-unclutter-configuration +The configuration record for @code{home-unclutter-service-type}. + +@table @asis +@item @code{unclutter} (default: @code{unclutter}) (type: file-like) +Unclutter package to use. + +@item @code{idle-timeout} (default: @code{5}) (type: integer) +A timeout in seconds after which to hide cursor. +@end table + +@end deftp + @node Guix Home Services @subsection Guix Home Services diff --git a/gnu/home/services/desktop.scm b/gnu/home/services/desktop.scm index cb25b03b64..ab2b871539 100644 --- a/gnu/home/services/desktop.scm +++ b/gnu/home/services/desktop.scm @@ -1,6 +1,7 @@ ;;; GNU Guix --- Functional package management for GNU ;;; Copyright © 2022 Ludovic Courtès ;;; Copyright © 2022 ( +;;; Copyright © 2023 conses ;;; ;;; This file is part of GNU Guix. ;;; @@ -22,7 +23,7 @@ #:use-module (gnu home services shepherd) #:use-module (gnu services configuration) #:autoload (gnu packages glib) (dbus) - #:autoload (gnu packages xdisorg) (redshift) + #:autoload (gnu packages xdisorg) (redshift unclutter) #:use-module (guix records) #:use-module (guix gexp) #:use-module (srfi srfi-1) @@ -32,7 +33,10 @@ home-redshift-service-type home-dbus-configuration - home-dbus-service-type)) + home-dbus-service-type + + home-unclutter-configuration + home-unclutter-service-type)) ;;; @@ -226,3 +230,48 @@ according to time of day."))) (default-value (home-dbus-configuration)) (description "Run the session-specific D-Bus inter-process message bus."))) + + +;;; +;;; Unclutter. +;;; + +(define-configuration/no-serialization home-unclutter-configuration + (unclutter + (file-like unclutter) + "The @code{unclutter} package to use.") + (idle-timeout + (integer 5) + "Timeout in seconds after which to hide the cursor.")) + +(define (home-unclutter-shepherd-service config) + (list + (shepherd-service + (provision '(unclutter)) + (requirement '()) + (one-shot? #t) + (start #~(make-forkexec-constructor + (list + #$(file-append + (home-unclutter-configuration-unclutter config) + "/bin/unclutter") + "-idle" + (number->string + #$(home-unclutter-configuration-idle-timeout config))) + #:log-file (string-append + (or (getenv "XDG_LOG_HOME") + (format #f "~a/.local/var/log" + (getenv "HOME"))) + "/unclutter.log")))))) + +(define home-unclutter-service-type + (service-type + (name 'home-unclutter) + (extensions + (list + (service-extension home-shepherd-service-type + home-unclutter-shepherd-service))) + (default-value (home-unclutter-configuration)) + (description "Run the @code{unclutter} daemon, which, on systems using the +Xorg graphical display server, automatically hides the cursor after a +user-defined timeout has expired."))) -- cgit 1.4.1 From 5864fc33803762388264e461e002ff09e3b5e4e8 Mon Sep 17 00:00:00 2001 From: Simon Tournier Date: Fri, 27 Jan 2023 12:12:37 +0100 Subject: doc: Document 'shebang' for 'guix shell'. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Invoking guix shell): Add a note mentioning how to use 'shebang'. Co-authored-by: Ludovic Courtès --- doc/guix.texi | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 56a24a1011..aa98d7df4b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -71,7 +71,7 @@ Copyright @copyright{} 2019 Kyle Andrews@* Copyright @copyright{} 2019 Alex Griffin@* Copyright @copyright{} 2019, 2020, 2021, 2022 Guillaume Le Vaillant@* Copyright @copyright{} 2020 Liliana Marie Prikler@* -Copyright @copyright{} 2019, 2020, 2021, 2022 Simon Tournier@* +Copyright @copyright{} 2019, 2020, 2021, 2022, 2023 Simon Tournier@* Copyright @copyright{} 2020 Wiktor Żelazny@* Copyright @copyright{} 2020 Damien Cassou@* Copyright @copyright{} 2020 Jakub Kądziołka@* @@ -5939,6 +5939,22 @@ building or downloading any missing package, and runs the guix shell python python-numpy -- python3 @end example +@quotation Note +@cindex shebang, for @command{guix shell} +@command{guix shell} can be also be used as a script interpreter, also +known as @dfn{shebang}. Here is an example self-contained Python script +making use of this feature: + +@example +#!/usr/bin/env -S guix shell python python-numpy -- python3 +import numpy +print("This is numpy", numpy.version.version) +@end example + +You may pass any @command{guix shell} option, but there's one caveat: +the Linux kernel has a limit of 127 bytes on shebang length. +@end quotation + Development environments can be created as in the example below, which spawns an interactive shell containing all the dependencies and environment variables needed to work on Inkscape: -- cgit 1.4.1 From 2c2f382e757d5eef39e8460a20ac75a1b1f8b22e Mon Sep 17 00:00:00 2001 From: "Jan (janneke) Nieuwenhuizen" Date: Sun, 5 Mar 2023 17:17:04 +0100 Subject: gnu: home: services: Add home-ssh-agent-service-type. * gnu/home/services/ssh.scm: (): New type. (home-ssh-agent-services): New procedure. (home-ssh-agent-service-type): New variable. * doc/guix.texi (Secure Shell): Document it. --- doc/guix.texi | 56 ++++++++++++++++++++++++++++++++++++++++++++++- gnu/home/services/ssh.scm | 54 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 108 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index aa98d7df4b..8baa2f3224 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -36,7 +36,7 @@ Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016, 2017 Nikita Gillmann@* -Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@* +Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2023 Jan Nieuwenhuizen@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@* @@ -42464,6 +42464,60 @@ Extra content appended as-is to this @code{Host} block in @c %end of fragment +@cindex ssh-agent +The @uref{https://www.openssh.com, OpenSSH package} includes a daemon, +the @command{ssh-agent} command, that manages keys to connect to remote +machines using the @acronym{SSH, secure shell} protocol. With the +@code{(gnu home services ssh-agent)} service, you can configure the +OpenSSH ssh-agent to run upon login. + +When using the @code{home-ssh-agent-service-type}, you need to add your +@file{~/.bash_profile}: + +@example +SSH_AUTH_SOCK=$@{XDG_RUNTIME_DIR-$HOME/.cache@}/ssh-agent/socket +export SSH_AUTH_SOCK +@end example + +Of course, you can do that using the @code{home-bash-service-type}, by +adding something like: + +@lisp +(environment-variables + '(("SSH_AUTH_SOCK" + . "$@{SSH_AUTH_SOCK-$@{XDG_RUNTIME_DIR-$HOME/.cache@}/ssh-agent/socket@}"))) +@end lisp + +Here is an example of a service and its configuration that you could add +to the @code{services} field of your @code{home-environment}: + +@lisp +(service home-ssh-agent-service-type + (home-ssh-agent-configuration + (extra-options '("-t" "1h30m")))) +@end lisp + +@defvr {Scheme Variable} home-ssh-agent-service-type +This is the type of the @code{git daemon} home service, whose value is an +@code{home-ssh-agent-configuration} object. +@end defvr + +@deftp {Data Type} home-ssh-agent-configuration +Available @code{home-ssh-agent-configuration} fields are: + +@table @asis +@item @code{git} (default: @code{git}) (type: file-like) +The git package to use. + +@item @code{socket-directory} (default: @code{@env{XDG_RUNTIME_DIR}/ssh-agent"}) (type: string) +The directory to write the ssh-agent's @file{socket} file. + +@item @code{extra-options} (default: @code{'()}) +Extra options will be passed to @command{ssh-agent}, please run +@command{man ssh-agent} for more information. + +@end table +@end deftp @node Desktop Home Services @subsection Desktop Home Services diff --git a/gnu/home/services/ssh.scm b/gnu/home/services/ssh.scm index d15f5ee912..205650d489 100644 --- a/gnu/home/services/ssh.scm +++ b/gnu/home/services/ssh.scm @@ -1,5 +1,6 @@ ;;; GNU Guix --- Functional package management for GNU ;;; Copyright © 2022 Ludovic Courtès +;;; Copyright © 2023 Janneke Nieuwenhuizen ;;; ;;; This file is part of GNU Guix. ;;; @@ -25,9 +26,12 @@ #:use-module (gnu services configuration) #:use-module (guix modules) #:use-module (gnu home services) + #:use-module (gnu home services shepherd) #:use-module ((gnu home services utils) #:select (object->camel-case-string)) #:autoload (gnu packages base) (glibc-utf8-locales) + #:use-module (gnu packages ssh) + #:use-module (shepherd support) #:use-module (srfi srfi-1) #:use-module (srfi srfi-34) #:use-module (srfi srfi-35) @@ -36,6 +40,7 @@ home-openssh-configuration-authorized-keys home-openssh-configuration-known-hosts home-openssh-configuration-hosts + home-ssh-agent-configuration openssh-host openssh-host-host-name @@ -52,7 +57,8 @@ openssh-host-accepted-key-types openssh-host-extra-content - home-openssh-service-type)) + home-openssh-service-type + home-ssh-agent-service-type)) (define (serialize-field-name name) (match name @@ -254,3 +260,49 @@ inserted after each of them." by providing a @file{~/.ssh/config} file, which is honored by the OpenSSH client,@command{ssh}, and by other tools such as @command{guix deploy}.") (default-value (home-openssh-configuration)))) + + +;;; +;;; Ssh-agent. +;;; +(define-record-type* + home-ssh-agent-configuration make-home-ssh-agent-configuration + home-ssh-agent-configuration? + (openssh home-ssh-agent-openssh ;file-like + (default openssh)) + (socket-directory home-ssh-agent-socket-directory ;string + (default (string-append %user-runtime-dir "/ssh-agent"))) + (extra-options home-ssh-agent-extra-options ;list of string + (default '()))) + +(define (home-ssh-agent-services config) + "Return a for an ssh-agent with CONFIG." + (match config + (($ + openssh socket-directory extra-options) + (let* ((ssh-agent (file-append openssh "/bin/ssh-agent")) + (socket-file (string-append socket-directory "/socket")) + (command `(,ssh-agent + "-D" + "-a" ,socket-file + ,@extra-options)) + (log-file (string-append %user-log-dir "/ssh-agent.log"))) + (list (shepherd-service + (documentation "Run the ssh-agent.") + (provision '(ssh-agent)) + (start #~(lambda _ + (unless (file-exists? #$socket-directory) + (mkdir-p #$socket-directory) + (chmod #$socket-directory #o700)) + (fork+exec-command '#$command #:log-file #$log-file))) + (stop #~(make-kill-destructor)))))))) + +(define home-ssh-agent-service-type + (service-type + (name 'home-ssh-agent) + (default-value (home-ssh-agent-configuration)) + (extensions + (list (service-extension home-shepherd-service-type + home-ssh-agent-services))) + (description + "Install and configure @command{ssh-agent} as a Shepherd service."))) -- cgit 1.4.1 From 193f547ca35eb49ef57bd9a25b67cb3965f10b03 Mon Sep 17 00:00:00 2001 From: "Jan (janneke) Nieuwenhuizen" Date: Sun, 5 Mar 2023 17:38:50 +0100 Subject: gnu: home: services: Add home-znc-service-type. * gnu/home/services/messaging.scm: New file. * gnu/local.mk (GNU_SYSTEM_MODULES): Add it. * po/guix/POTFILES.in: Likewise. * doc/guix.texi (Messaging Home Services): Document it in new subsection. --- doc/guix.texi | 37 +++++++++++++++++++++ gnu/home/services/messaging.scm | 73 +++++++++++++++++++++++++++++++++++++++++ gnu/local.mk | 3 +- po/guix/POTFILES.in | 1 + 4 files changed, 113 insertions(+), 1 deletion(-) create mode 100644 gnu/home/services/messaging.scm (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 8baa2f3224..a823d5f27d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -41705,6 +41705,7 @@ services)}. * Guix: Guix Home Services. Services for Guix. * Fonts: Fonts Home Services. Services for managing User's fonts. * Sound: Sound Home Services. Dealing with audio. +* Messaging: Messaging Home Services. Services for managing messaging. @end menu @c In addition to that Home Services can provide @@ -42797,6 +42798,42 @@ Stopping the Shepherd service turns off broadcasting. This is the multicast address used by default by the two services above. @end defvar +@node Messaging Home Services +@subsection Messaging Home Services + +@cindex znc +The @uref{https://znc.in, ZNC bouncer} can be run as a daemon to manage +your IRC presence. With the @code{(gnu home services znc)} service, you +can configure ZNC to run upon login. + +You will have to provide a @file{~/.znc/configs/znc.conf} seperately. + +Here is an example of a service and its configuration that you could add +to the @code{services} field of your @code{home-environment}: + +@lisp +(service home-znc-service-type) +@end lisp + +@defvr {Scheme Variable} home-znc-service-type +This is the type of the @code{git daemon} home service, whose value is an +@code{home-znc-configuration} object. +@end defvr + +@deftp {Data Type} home-znc-configuration +Available @code{home-znc-configuration} fields are: + +@table @asis +@item @code{git} (default: @code{git}) (type: file-like) +The git package to use. + +@item @code{extra-options} (default: @code{'()}) +Extra options will be passed to @command{znc}, please run @command{man +znc} for more information. + +@end table +@end deftp + @node Invoking guix home @section Invoking @command{guix home} diff --git a/gnu/home/services/messaging.scm b/gnu/home/services/messaging.scm new file mode 100644 index 0000000000..d403b84ac9 --- /dev/null +++ b/gnu/home/services/messaging.scm @@ -0,0 +1,73 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2023 Janneke Nieuwenhuizen +;;; +;;; 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 . + +(define-module (gnu home services messaging) + #:use-module (srfi srfi-26) + + #:use-module (ice-9 match) + + #:use-module (shepherd support) + + #:use-module (gnu home services) + #:use-module (gnu home services shepherd) + #:use-module (gnu packages messaging) + #:use-module (gnu services configuration) + #:use-module (gnu services shepherd) + #:use-module (guix records) + #:use-module (guix gexp) + + #:export (home-znc-configuration + home-znc-service-type)) + +;;; +;;; Znc. +;;; +(define-record-type* + home-znc-configuration make-home-znc-configuration + home-znc-configuration? + (znc home-znc-znc ;string + (default znc)) + (extra-options home-znc-extra-options ;list of string + (default '()))) + +(define (home-znc-services config) + "Return a for znc with CONFIG." + (match config + (($ znc extra-options) + (let* ((znc (file-append znc "/bin/znc")) + (command `(,znc + "--foreground" + ,@extra-options)) + (log-file (string-append %user-log-dir "/znc.log"))) + (list (shepherd-service + (documentation "Run the znc IRC bouncer.") + (provision '(znc)) + (start #~(make-forkexec-constructor '#$command + #:log-file #$log-file)) + (stop #~(make-kill-destructor)))))))) + +(define home-znc-service-type + (service-type + (name 'home-znc) + (default-value (home-znc-configuration)) + (extensions + (list (service-extension home-shepherd-service-type + home-znc-services))) + (description + "Install and configure @command{znc}, an @acronym{IRC, Internet Relay +Chat} bouncer, as a Shepherd service."))) diff --git a/gnu/local.mk b/gnu/local.mk index eafd7c40ea..c87ce6fa8c 100644 --- a/gnu/local.mk +++ b/gnu/local.mk @@ -11,7 +11,7 @@ # Copyright © 2016 Ben Woodcroft # Copyright © 2016, 2017, 2018, 2019 Alex Vong # Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Efraim Flashner -# Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022 Jan (janneke) Nieuwenhuizen +# Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Jan (janneke) Nieuwenhuizen # Copyright © 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice # Copyright © 2017, 2018 Clément Lassieur # Copyright © 2017, 2020 Mathieu Othacehe @@ -91,6 +91,7 @@ GNU_SYSTEM_MODULES = \ %D%/home/services/symlink-manager.scm \ %D%/home/services/fontutils.scm \ %D%/home/services/guix.scm \ + %D%/home/services/messaging.scm \ %D%/home/services/pm.scm \ %D%/home/services/shells.scm \ %D%/home/services/shepherd.scm \ diff --git a/po/guix/POTFILES.in b/po/guix/POTFILES.in index 7009fc756c..c71a6ca857 100644 --- a/po/guix/POTFILES.in +++ b/po/guix/POTFILES.in @@ -13,6 +13,7 @@ gnu/services/shepherd.scm gnu/services/samba.scm gnu/services/version-control.scm gnu/home/services.scm +gnu/home/services/messaging.scm gnu/home/services/ssh.scm gnu/home/services/symlink-manager.scm gnu/system/file-systems.scm -- cgit 1.4.1 From 70056b1b2beebbc9f8ea2c34eacc57f379368ab3 Mon Sep 17 00:00:00 2001 From: "Jan (janneke) Nieuwenhuizen" Date: Sun, 5 Mar 2023 18:31:58 +0100 Subject: gnu: home: services: Add home-kodi-service-type. * gnu/home/services/media.scm: New file. * gnu/local.mk (GNU_SYSTEM_MODULES): Add it. * po/guix/POTFILES.in: Likewise. * doc/guix.texi (Media Home Services): Document it in new subsection. --- doc/guix.texi | 37 +++++++++++++++++++++++ gnu/home/services/media.scm | 73 +++++++++++++++++++++++++++++++++++++++++++++ gnu/local.mk | 1 + po/guix/POTFILES.in | 1 + 4 files changed, 112 insertions(+) create mode 100644 gnu/home/services/media.scm (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index a823d5f27d..79f098c114 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -41706,6 +41706,7 @@ services)}. * Fonts: Fonts Home Services. Services for managing User's fonts. * Sound: Sound Home Services. Dealing with audio. * Messaging: Messaging Home Services. Services for managing messaging. +* Media: Media Home Services. Services for managing media. @end menu @c In addition to that Home Services can provide @@ -42834,6 +42835,42 @@ znc} for more information. @end table @end deftp +@node Media Home Services +@subsection Media Home Services + +@cindex kodi +The @uref{https://kodi.tv, KODI media center} can be run as a daemon on +a media server. With the @code{(gnu home services kodi)} service, you +can configure KODI to run upon login. + +Here is an example of a service and its configuration that you could add +to the @code{services} field of your @code{home-environment}: + +@lisp +(service home-kodi-service-type + (home-kodi-configuration + (extra-options '("--settings="")))) +@end lisp + +@defvr {Scheme Variable} home-kodi-service-type +This is the type of the @code{git daemon} home service, whose value is an +@code{home-kodi-configuration} object. +@end defvr + +@deftp {Data Type} home-kodi-configuration +Available @code{home-kodi-configuration} fields are: + +@table @asis +@item @code{git} (default: @code{git}) (type: file-like) +The git package to use. + +@item @code{extra-options} (default: @code{'()}) +Extra options will be passed to @command{kodi}, please run @command{man +kodi} for more information. + +@end table +@end deftp + @node Invoking guix home @section Invoking @command{guix home} diff --git a/gnu/home/services/media.scm b/gnu/home/services/media.scm new file mode 100644 index 0000000000..48d7ccf67a --- /dev/null +++ b/gnu/home/services/media.scm @@ -0,0 +1,73 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2023 Janneke Nieuwenhuizen +;;; +;;; 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 . + +(define-module (gnu home services media) + #:use-module (srfi srfi-26) + + #:use-module (ice-9 match) + + #:use-module (shepherd support) + + #:use-module (gnu home services) + #:use-module (gnu home services shepherd) + #:use-module (gnu packages kodi) + #:use-module (gnu services configuration) + #:use-module (gnu services shepherd) + #:use-module (guix records) + #:use-module (guix gexp) + + #:export (home-kodi-configuration + home-kodi-service-type)) + +;;; +;;; Kodi. +;;; +(define-record-type* + home-kodi-configuration make-home-kodi-configuration + home-kodi-configuration? + (kodi home-kodi-kodi ;file-like + (default kodi)) + (extra-options home-kodi-extra-options ;list of string + (default '()))) + +(define (home-kodi-services config) + "Return a for kodi with CONFIG." + (match config + (($ kodi extra-options) + (let* ((kodi (file-append kodi "/bin/kodi")) + (command `(kodi + "-fs" + ,@extra-options)) + (log-file (string-append %user-log-dir "/kodi.log"))) + (list (shepherd-service + (documentation "Run the kodi media center.") + (provision '(kodi)) + (start #~(make-forkexec-constructor '#$command + #:log-file #$log-file)) + (stop #~(make-kill-destructor)))))))) + +(define home-kodi-service-type + (service-type + (name 'home-kodi) + (default-value (home-kodi-configuration)) + (extensions + (list (service-extension home-shepherd-service-type + home-kodi-services))) + (description + "Install and configure the Kodi media center so that it runs as a Shepherd +service."))) diff --git a/gnu/local.mk b/gnu/local.mk index c87ce6fa8c..f8061e4a34 100644 --- a/gnu/local.mk +++ b/gnu/local.mk @@ -91,6 +91,7 @@ GNU_SYSTEM_MODULES = \ %D%/home/services/symlink-manager.scm \ %D%/home/services/fontutils.scm \ %D%/home/services/guix.scm \ + %D%/home/services/media.scm \ %D%/home/services/messaging.scm \ %D%/home/services/pm.scm \ %D%/home/services/shells.scm \ diff --git a/po/guix/POTFILES.in b/po/guix/POTFILES.in index c71a6ca857..88cc507ea7 100644 --- a/po/guix/POTFILES.in +++ b/po/guix/POTFILES.in @@ -13,6 +13,7 @@ gnu/services/shepherd.scm gnu/services/samba.scm gnu/services/version-control.scm gnu/home/services.scm +gnu/home/services/media.scm gnu/home/services/messaging.scm gnu/home/services/ssh.scm gnu/home/services/symlink-manager.scm -- cgit 1.4.1 From be7e2bf7ebc10bb4e5808ddeabc4b914f575865f Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Thu, 16 Mar 2023 17:09:46 +0100 Subject: home: services: ssh-agent: Remove host-side use of (shepherd support). This is a followup to 2c2f382e757d5eef39e8460a20ac75a1b1f8b22e, which inadvertently pulled in (shepherd support) on the host side. * gnu/home/services/ssh.scm ()[socket-directory]: Change value to a gexp. (home-ssh-agent-services): Change 'socket-file' and 'command' to a gexp. Add 'modules' field to 'shepherd-service'. * doc/guix.texi (Secure Shell): Adjust accordingly. --- doc/guix.texi | 2 +- gnu/home/services/ssh.scm | 17 ++++++++--------- 2 files changed, 9 insertions(+), 10 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 79f098c114..c73a05a0c4 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -42511,7 +42511,7 @@ Available @code{home-ssh-agent-configuration} fields are: @item @code{git} (default: @code{git}) (type: file-like) The git package to use. -@item @code{socket-directory} (default: @code{@env{XDG_RUNTIME_DIR}/ssh-agent"}) (type: string) +@item @code{socket-directory} (default: @code{@env{XDG_RUNTIME_DIR}/ssh-agent"}) (type: gexp) The directory to write the ssh-agent's @file{socket} file. @item @code{extra-options} (default: @code{'()}) diff --git a/gnu/home/services/ssh.scm b/gnu/home/services/ssh.scm index 205650d489..2eae08bd86 100644 --- a/gnu/home/services/ssh.scm +++ b/gnu/home/services/ssh.scm @@ -31,7 +31,6 @@ #:select (object->camel-case-string)) #:autoload (gnu packages base) (glibc-utf8-locales) #:use-module (gnu packages ssh) - #:use-module (shepherd support) #:use-module (srfi srfi-1) #:use-module (srfi srfi-34) #:use-module (srfi srfi-35) @@ -271,7 +270,7 @@ client,@command{ssh}, and by other tools such as @command{guix deploy}.") (openssh home-ssh-agent-openssh ;file-like (default openssh)) (socket-directory home-ssh-agent-socket-directory ;string - (default (string-append %user-runtime-dir "/ssh-agent"))) + (default #~(string-append %user-runtime-dir "/ssh-agent"))) (extra-options home-ssh-agent-extra-options ;list of string (default '()))) @@ -281,20 +280,20 @@ client,@command{ssh}, and by other tools such as @command{guix deploy}.") (($ openssh socket-directory extra-options) (let* ((ssh-agent (file-append openssh "/bin/ssh-agent")) - (socket-file (string-append socket-directory "/socket")) - (command `(,ssh-agent - "-D" - "-a" ,socket-file - ,@extra-options)) - (log-file (string-append %user-log-dir "/ssh-agent.log"))) + (socket-file #~(string-append #$socket-directory "/socket")) + (command #~`(#$ssh-agent + "-D" "-a" ,#$socket-file + #$@extra-options)) + (log-file #~(string-append %user-log-dir "/ssh-agent.log"))) (list (shepherd-service (documentation "Run the ssh-agent.") (provision '(ssh-agent)) + (modules '((shepherd support))) ;for '%user-runtime-dir', etc. (start #~(lambda _ (unless (file-exists? #$socket-directory) (mkdir-p #$socket-directory) (chmod #$socket-directory #o700)) - (fork+exec-command '#$command #:log-file #$log-file))) + (fork+exec-command #$command #:log-file #$log-file))) (stop #~(make-kill-destructor)))))))) (define home-ssh-agent-service-type -- cgit 1.4.1 From b68d4118e7233586ad1e5746b2ebc594977db1e3 Mon Sep 17 00:00:00 2001 From: "Jan (janneke) Nieuwenhuizen" Date: Thu, 16 Mar 2023 18:41:30 +0100 Subject: doc: Use @defvar instead of @defvr for Scheme variables. Suggested by mirai via IRC, see also https://issues.guix.gnu.org/60634 * doc/guix.texi (Build Systems) (Secure Shell) (Messaging Home Services) (Media Home Services): Use @defvar instead of @defvr for Scheme variables. --- doc/guix.texi | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index c73a05a0c4..4807f16c0a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -9826,7 +9826,7 @@ be specified with the @code{#:node} parameter which defaults to @code{node}. @end defvar -@defvr {Scheme Variable} tree-sitter-build-system +@defvar tree-sitter-build-system This variable is exported by @code{(guix build-system tree-sitter)}. It implements procedures to compile grammars for the @@ -9843,7 +9843,7 @@ Grammars sometimes depend on each other, such as C++ depending on C and TypeScript depending on JavaScript. You may use inputs to declare such dependencies. -@end defvr +@end defvar Lastly, for packages that do not need anything as sophisticated, a ``trivial'' build system is provided. It is trivial in the sense that @@ -42499,10 +42499,10 @@ to the @code{services} field of your @code{home-environment}: (extra-options '("-t" "1h30m")))) @end lisp -@defvr {Scheme Variable} home-ssh-agent-service-type +@defvar home-ssh-agent-service-type This is the type of the @code{git daemon} home service, whose value is an @code{home-ssh-agent-configuration} object. -@end defvr +@end defvar @deftp {Data Type} home-ssh-agent-configuration Available @code{home-ssh-agent-configuration} fields are: @@ -42816,10 +42816,10 @@ to the @code{services} field of your @code{home-environment}: (service home-znc-service-type) @end lisp -@defvr {Scheme Variable} home-znc-service-type +@defvar home-znc-service-type This is the type of the @code{git daemon} home service, whose value is an @code{home-znc-configuration} object. -@end defvr +@end defvar @deftp {Data Type} home-znc-configuration Available @code{home-znc-configuration} fields are: @@ -42852,10 +42852,10 @@ to the @code{services} field of your @code{home-environment}: (extra-options '("--settings="")))) @end lisp -@defvr {Scheme Variable} home-kodi-service-type +@defvar home-kodi-service-type This is the type of the @code{git daemon} home service, whose value is an @code{home-kodi-configuration} object. -@end defvr +@end defvar @deftp {Data Type} home-kodi-configuration Available @code{home-kodi-configuration} fields are: -- cgit 1.4.1 From 2714c9ef2d6cb42f15c2f284449f602467f0d1c0 Mon Sep 17 00:00:00 2001 From: "Jan (janneke) Nieuwenhuizen" Date: Fri, 17 Mar 2023 12:40:16 +0100 Subject: home: services: ssh-agent: Handle setting of SSH_AUTH_SOCK. * gnu/home/services/ssh.scm (home-ssh-agent-environment-variables): New procedure. (home-ssh-agent-service-type): Use it as ahome-environment-service type extension. * doc/guix.texi (Secure Shell): Remove advice about, and examples of setting SSH_AUTH_SOCK. --- doc/guix.texi | 17 ----------------- gnu/home/services/ssh.scm | 8 +++++++- 2 files changed, 7 insertions(+), 18 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 4807f16c0a..2d42ca8de2 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -42473,23 +42473,6 @@ machines using the @acronym{SSH, secure shell} protocol. With the @code{(gnu home services ssh-agent)} service, you can configure the OpenSSH ssh-agent to run upon login. -When using the @code{home-ssh-agent-service-type}, you need to add your -@file{~/.bash_profile}: - -@example -SSH_AUTH_SOCK=$@{XDG_RUNTIME_DIR-$HOME/.cache@}/ssh-agent/socket -export SSH_AUTH_SOCK -@end example - -Of course, you can do that using the @code{home-bash-service-type}, by -adding something like: - -@lisp -(environment-variables - '(("SSH_AUTH_SOCK" - . "$@{SSH_AUTH_SOCK-$@{XDG_RUNTIME_DIR-$HOME/.cache@}/ssh-agent/socket@}"))) -@end lisp - Here is an example of a service and its configuration that you could add to the @code{services} field of your @code{home-environment}: diff --git a/gnu/home/services/ssh.scm b/gnu/home/services/ssh.scm index dc37ecf329..01917a29cd 100644 --- a/gnu/home/services/ssh.scm +++ b/gnu/home/services/ssh.scm @@ -295,12 +295,18 @@ client,@command{ssh}, and by other tools such as @command{guix deploy}.") (fork+exec-command #$command #:log-file #$log-file))) (stop #~(make-kill-destructor))))))) +(define (home-ssh-agent-environment-variables config) + '(("SSH_AUTH_SOCK" + . "${SSH_AUTH_SOCK-${XDG_RUNTIME_DIR-$HOME/.cache}/ssh-agent/socket}"))) + (define home-ssh-agent-service-type (service-type (name 'home-ssh-agent) (default-value (home-ssh-agent-configuration)) (extensions (list (service-extension home-shepherd-service-type - home-ssh-agent-services))) + home-ssh-agent-services) + (service-extension home-environment-variables-service-type + home-ssh-agent-environment-variables))) (description "Install and configure @command{ssh-agent} as a Shepherd service."))) -- cgit 1.4.1 From fd4f91dea6d82219c196549d29feb0090fd32a36 Mon Sep 17 00:00:00 2001 From: Maxim Cournoyer Date: Fri, 17 Mar 2023 10:57:08 -0400 Subject: doc: Use 'mount --rbind' for chroot instructions. This was reported by a user in #guix. It's at least necessary for /sys, to have the /sys/firmware/efivars location available insinde the chroot when using an UEFI system. * doc/guix.texi (Chrooting into an existing system): Replace --bind argument with --rbind Suggested-by: Josselin Poiret --- doc/guix.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 2d42ca8de2..0a965f53c0 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2945,9 +2945,9 @@ mount /dev/sda2 /mnt Mount special block devices and Linux-specific directories: @example sh -mount --bind /proc /mnt/proc -mount --bind /sys /mnt/sys -mount --bind /dev /mnt/dev +mount --rbind /proc /mnt/proc +mount --rbind /sys /mnt/sys +mount --rbind /dev /mnt/dev @end example If your system is EFI-based, you must also mount the ESP partition. -- cgit 1.4.1 From 511ae8325db0dfc7803d7b98d7e4d8f76774e8c5 Mon Sep 17 00:00:00 2001 From: conses Date: Fri, 17 Mar 2023 13:06:35 +0100 Subject: home: services: Add home-xmodmap-service-type. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gnu/home/services/desktop.scm (home-xmodmap-service-type) (home-xmodmap-configuration): New variables; (serialize-xmodmap-configuration) (xmodmap-shepherd-service): New procedures; * doc/guix.texi (Desktop Services): Document it. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 41 +++++++++++++++++++++++++++++++ gnu/home/services/desktop.scm | 57 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 0a965f53c0..edf410d024 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -42626,6 +42626,47 @@ A timeout in seconds after which to hide cursor. @end deftp +@defvar home-xmodmap-service-type +This is the service type for the +@uref{https://gitlab.freedesktop.org/xorg/app/xmodmap,xmodmap} utility +to modify keymaps and pointer button mappings under the Xorg display +server. Its associated value must be a +@code{home-xmodmap-configuration} record, as shown below. + +The @code{key-map} field takes a list of objects, each of which is +either a @dfn{statement} (a string) or an @dfn{assignment} (a pair of +strings). As an example, the snippet below swaps around the +@kbd{Caps_Lock} and the @kbd{Control_L} keys, by first removing the +keysyms (on the right-hand side) from the corresponding modifier maps +(on the left-hand side), re-assigning them by swapping each other out, +and finally adding back the keysyms to the modifier maps. + +@lisp +(service home-xmodmap-service-type + (home-xmodmap-configuration + (key-map '(("remove Lock" . "Caps_Lock") + ("remove Control" . "Control_L") + ("keysym Control_L" . "Caps_Lock") + ("keysym Caps_Lock" . "Control_L") + ("add Lock" . "Caps_Lock") + ("add Control" . "Control_L"))))) +@end lisp +@end defvar + +@deftp {Data Type} home-xmodmap-configuration +The configuration record for @code{home-xmodmap-service-type}. Its +available fields are: + +@table @asis +@item @code{xmodmap} (default: @code{xmodmap}) (type: file-like) +The @code{xmodmap} package to use. + +@item @code{key-map} (default: @code{'()}) (type: list) +The list of expressions to be read by @code{xmodmap} on service startup. + +@end table +@end deftp + @node Guix Home Services @subsection Guix Home Services diff --git a/gnu/home/services/desktop.scm b/gnu/home/services/desktop.scm index ab2b871539..fb1cd44060 100644 --- a/gnu/home/services/desktop.scm +++ b/gnu/home/services/desktop.scm @@ -24,6 +24,7 @@ #:use-module (gnu services configuration) #:autoload (gnu packages glib) (dbus) #:autoload (gnu packages xdisorg) (redshift unclutter) + #:autoload (gnu packages xorg) (setxkbmap xmodmap) #:use-module (guix records) #:use-module (guix gexp) #:use-module (srfi srfi-1) @@ -275,3 +276,59 @@ according to time of day."))) (description "Run the @code{unclutter} daemon, which, on systems using the Xorg graphical display server, automatically hides the cursor after a user-defined timeout has expired."))) + + +;;; +;;; Xmodmap. +;;; + +(define-configuration/no-serialization home-xmodmap-configuration + (xmodmap + (file-like xmodmap) + "The @code{xmodmap} package to use.") + (key-map + (list '()) + "List of expressions to be read by @code{xmodmap} on service startup.")) + +(define (serialize-xmodmap-configuration field-name val) + (define serialize-field + (match-lambda + ((key . value) + (format #f "~a = ~a" key value)) + (e e))) + + #~(string-append + #$@(interpose (map serialize-field val) "\n" 'suffix))) + +(define (xmodmap-shepherd-service config) + (define config-file + (mixed-text-file + "config" + (serialize-xmodmap-configuration + #f (home-xmodmap-configuration-key-map config)))) + + (list + (shepherd-service + (provision '(xmodmap)) + (start #~(make-system-constructor + (string-join + (list #$(file-append + (home-xmodmap-configuration-xmodmap config) + "/bin/xmodmap") + #$config-file)))) + (stop #~(make-system-constructor + #$(file-append setxkbmap "/bin/setxkbmap"))) + (documentation "On startup, run @code{xmodmap} and read the expressions in +the configuration file. On stop, reset all the mappings back to the +defaults.")))) + +(define home-xmodmap-service-type + (service-type + (name 'home-xmodmap) + (extensions + (list + (service-extension home-shepherd-service-type + xmodmap-shepherd-service))) + (default-value (home-xmodmap-configuration)) + (description "Run the @code{xmodmap} utility to modify keymaps and pointer +buttons under the Xorg display server via user-defined expressions."))) -- cgit 1.4.1 From 20aa4c30fbfdb72c25d267fe36299f02e3e202e2 Mon Sep 17 00:00:00 2001 From: Bruno Victal Date: Sun, 5 Mar 2023 00:48:23 +0000 Subject: services: dict: Deprecate 'dicod-service' procedure. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * doc/guix.texi (Miscellaneous Services): Remove 'dicod-service' mention. * gnu/services/dict.scm (dicod-service): Deprecate procedure. Signed-off-by: Ludovic Courtès --- doc/guix.texi | 46 ++++++++++++++++++++-------------------------- gnu/services/dict.scm | 6 ++++-- 2 files changed, 24 insertions(+), 28 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index edf410d024..fa9ea5a6ec 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -37850,25 +37850,17 @@ If true, this must be the name of a file to log messages to. @subsubheading Dictionary Service @cindex dictionary + The @code{(gnu services dict)} module provides the following service: @defvar dicod-service-type This is the type of the service that runs the @command{dicod} daemon, an implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). -@end defvar - -@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)] -Return a service that runs the @command{dicod} daemon, an implementation -of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). - -The optional @var{config} argument specifies the configuration for -@command{dicod}, which should be a @code{} object, by -default it serves the GNU Collaborative International Dictionary of English. You can add @command{open localhost} to your @file{~/.dico} file to make @code{localhost} the default server for @command{dico} client (@pxref{Initialization File,,, dico, GNU Dico Manual}). -@end deffn +@end defvar @deftp {Data Type} dicod-configuration Data type representing the configuration of dicod. @@ -37933,22 +37925,24 @@ A @code{} object serving the GNU Collaborative International Dictionary of English using the @code{gcide} package. @end defvar -The following is an example @code{dicod-service} configuration. - -@lisp -(dicod-service #:config - (dicod-configuration - (handlers (list (dicod-handler - (name "wordnet") - (module "dictorg") - (options - (list #~(string-append "dbdir=" #$wordnet)))))) - (databases (list (dicod-database - (name "wordnet") - (complex? #t) - (handler "wordnet") - (options '("database=wn"))) - %dicod-database:gcide)))) +The following is an example @code{dicod-service-type} configuration. + +@lisp +(service dicod-service-type + (dicod-configuration + (handlers (list + (dicod-handler + (name "wordnet") + (module "dictorg") + (options + (list #~(string-append "dbdir=" #$wordnet)))))) + (databases (list + (dicod-database + (name "wordnet") + (complex? #t) + (handler "wordnet") + (options '("database=wn"))) + %dicod-database:gcide)))) @end lisp @cindex Docker diff --git a/gnu/services/dict.scm b/gnu/services/dict.scm index 35253a0077..5a61085316 100644 --- a/gnu/services/dict.scm +++ b/gnu/services/dict.scm @@ -19,6 +19,7 @@ ;;; along with GNU Guix. If not, see . (define-module (gnu services dict) + #:use-module (guix deprecation) #:use-module (guix gexp) #:use-module (guix records) #:use-module (guix modules) @@ -34,7 +35,7 @@ #:use-module (srfi srfi-1) #:use-module (srfi srfi-26) #:use-module (ice-9 match) - #:export (dicod-service + #:export (dicod-service ; deprecated dicod-service-type dicod-configuration dicod-handler @@ -202,7 +203,8 @@ database { implements the standard DICT protocol supported by clients such as @command{dico} and GNOME Dictionary."))) -(define* (dicod-service #:key (config (dicod-configuration))) +(define-deprecated (dicod-service #:key (config (dicod-configuration))) + dicod-service-type "Return a service that runs the @command{dicod} daemon, an implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). -- cgit 1.4.1