Merge branch 'master' into core-updates

1 files changed, 123 insertions, 18 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index 7d7d556697..d7fabe9599 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4990,6 +4990,34 @@ as in:
 This is the declarative counterpart of @code{text-file*}.
 @end deffn
 
+@deffn {Scheme Procedure} file-union @var{name} @var{files}
+Return a @code{<computed-file>} 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
+denoting the target file.  Here's an example:
+
+@example
+(file-union "etc"
+            `(("hosts" ,(plain-file "hosts"
+                                    "127.0.0.1 localhost"))
+              ("bashrc" ,(plain-file "bashrc"
+                                     "alias ls='ls --color'"))))
+@end example
+
+This yields an @code{etc} directory containing these two files.
+@end deffn
+
+@deffn {Scheme Procedure} directory-union @var{name} @var{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:
+
+@example
+(directory-union "guile+emacs" (list guile emacs))
+@end example
+
+yields a directory that is the union of the @code{guile} and @code{emacs} packages.
+@end deffn
+
 @deffn {Scheme Procedure} file-append @var{obj} @var{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
@@ -9790,35 +9818,112 @@ Return a service that runs the Guix build daemon according to
 @var{config}.
 @end deffn
 
-@cindex udev-service
-@cindex udev-rule
-@deffn {Scheme Procedure} udev-service [#:udev @var{udev}] [#:rules @var{'()}]
+@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
 Run @var{udev}, which populates the @file{/dev} directory dynamically.
-Additional udev rules can be provided as a list of files through the
-@var{rules} variable.  The procedure @var{udev-rule} simplifies the
-creation of these rule files.
+udev rules can be provided as a list of files through the @var{rules}
+variable.  The procedures @var{udev-rule} and @var{file->udev-rule} from
+@code{(gnu services base)} simplify the creation of such rule files.
+
+@deffn {Scheme Procedure} 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.
 
 In the following example, a rule for a USB device is defined to be
-stored in the file @file{90-usb-thing.rules}, and the default
-@var{udev-service} is extended with it.  The rule runs a script upon
-detecting a USB device with a given product identifier.
+stored in the file @file{90-usb-thing.rules}.  The rule runs a script
+upon detecting a USB device with a given product identifier.
 
 @example
 (define %example-udev-rule
-  (udev-rule "90-usb-thing.rules"
-             "ACTION==\"add\", SUBSYSTEM==\"usb\", ATTR@{product@}==\"Example\", RUN+=\"/path/to/script\""))
+  (udev-rule
+    "90-usb-thing.rules"
+    (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
+                   "ATTR@{product@}==\"Example\", "
+                   "RUN+=\"/path/to/script\"")))
+@end example
+@end deffn
+
+Here we show how the default @var{udev-service} can be extended with it.
+
+@example
+(operating-system
+ ;; @dots{}
+ (services
+ (modify-services %desktop-services
+   (udev-service-type config =>
+     (udev-configuration (inherit config)
+      (rules (append (udev-configuration-rules config)
+                     (list %example-udev-rule))))))))
+@end example
+
+@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.
+
+The following example showcases how we can use an existing rule file.
+
+@example
+(use-modules (guix download)     ;for url-fetch
+             (guix packages)     ;for origin
+             ;; @dots{})
+
+(define %android-udev-rules
+  (file->udev-rule
+    "51-android-udev.rules"
+    (let ((version "20170910"))
+      (origin
+       (method url-fetch)
+       (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
+                           "android-udev-rules/" version "/51-android.rules"))
+       (sha256
+        (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
+@end example
+@end deffn
+
+Additionally, Guix package definitions can be included in @var{rules} in
+order to extend the udev rules with the definitions found under their
+@file{lib/udev/rules.d} sub-directory.  In lieu of the previous
+@var{file->udev-rule} example, we could have used the
+@var{android-udev-rules} package which exists in Guix in the @code{(gnu
+packages android)} module.
+
+The following example shows how to use the @var{android-udev-rules}
+package so that the Android tool @command{adb} can detect devices
+without root privileges.  It also details how to create the
+@code{adbusers} group, which is required for the proper functioning of
+the rules defined within the @var{android-udev-rules} package.  To
+create such a group, we must define it both as part of the
+@var{supplementary-groups} of our @var{user-account} declaration, as
+well as in the @var{groups} field of the @var{operating-system} record.
+
+@example
+(use-modules (gnu packages android)  ;for android-udev-rules
+             (gnu system shadow)     ;for user-group
+             ;; @dots{})
 
 (operating-system
   ;; @dots{}
-  (services (modify-services %desktop-services
-              (udev-service-type config =>
-                (udev-configuration (inherit config)
-                  (rules (append (udev-configuration-rules config)
-                                 (list %example-udev-rule))))))))
+  (users (cons (user-acount
+                ;; @dots{}
+                (supplementary-groups
+                 '("adbusers"   ;for adb
+                   "wheel" "netdev" "audio" "video"))
+                ;; @dots{})))
+
+  (groups (cons (user-group (system? #t) (name "adbusers"))
+                %base-groups))
+
+  ;; @dots{}
+
+  (services
+    (modify-services %desktop-services
+      (udev-service-type config =>
+       (udev-configuration (inherit config)
+       (rules (cons* android-udev-rules
+              (udev-configuration-rules config))))))))
 @end example
 @end deffn
 
-@deffn {Scheme Procedure} urandom-seed-service @var{#f}
+@deffn {Scheme Procedure} urandom-seed-service
 Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
 when rebooting.
 @end deffn
@@ -9930,7 +10035,7 @@ to add @var{device} to the kernel's entropy pool.  The service will fail if
 @cindex session limits
 @cindex ulimit
 @cindex priority
-@deffn {Scheme Procedure} pam-limits-service [#:limits @var{limits}]
+@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
 
 Return a service that installs a configuration file for the
 @uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,