08/23: services: base: Deprecate 'udev-service' procedure.

[guix-commits]

civodul pushed a commit to branch master
in repository guix.

commit 2e7516168e7b27d1ad3cee60d337d2ad98fb09ff
Author: Bruno Victal <mirai@makinata.eu>
AuthorDate: Sat Feb 25 18:57:54 2023 +0000

    services: base: Deprecate 'udev-service' procedure.
    
    * doc/guix.texi (Base Services): Replace udev-service with 
udev-service-type.
    Document <udev-configuration>. 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 <ludo@gnu.org>
---
 doc/guix.texi          | 52 ++++++++++++++++++++++++++++++++------------------
 gnu/services/base.scm  |  5 +++--
 gnu/system/install.scm |  4 +++-
 3 files changed, 39 insertions(+), 22 deletions(-)

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{<udev-configuration>} 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.