From 498db4de1f09414adf68a3a383f0178434035179 Mon Sep 17 00:00:00 2001 From: Vivien Kraus Date: Mon, 2 Oct 2023 21:08:49 +0200 Subject: gnu: udev-service-type: accept hardware description file extensions. The udev-configuration record now has a hardware field. The contents of the /etc/udev directory now includes hwdb.bin, which is computed when the system is instanciated (prior to system activation). The hardware description files used to generate hwdb.bin are not installed in /etc, because they are not required at run-time. The documentation has been reworked so as to explain why creating udev rules or hardware needs helper functions for configuration or extension. * gnu/services/base.scm (udev-hardware): New function. (file->udev-hardware): New function. (udev-hardware-service): New function. (udev-etc): Add hwdb.d and hwdb.bin. (module): Export udev-hardware, file->udev-hardware, and udev-hardware-service. (): Add the native-udev field. (udev-service-type) [extend]: Populate the hardware field. * doc/guix.texi (Base Services)[udev-service-type]: Explain configuration and extension values. * doc/guix.texi (Base Services)[udev-hardware]: Document it. [udev-hardware-service]: Same. * doc/guix.texi (Base Services)[udev-configuration]: Document the native-udev field. --- doc/guix.texi | 57 ++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 11 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index ad26a29513..3530d317ec 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -19362,9 +19362,23 @@ 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. +Since the file names for udev rules and hardware description files +matter, the configuration items for rules and hardware cannot simply be +plain file-like objects with the rules content, because the name would +be ignored. Instead, they are directory file-like objects that contain +optional rules in @file{lib/udev/rules.d} and optional hardware files in +@file{lib/udev/hwdb.d}. This way, the service can be configured with +whole packages from which to take rules and hwdb files. + +The @code{udev-service-type} can be @emph{extended} with file-like +directories that respect this hierarchy. For convenience, the +@code{udev-rule} and @code{file->udev-rule} can be used to construct +udev rules, while @code{udev-hardware} and @code{file->udev-hardware} +can be used to construct hardware description files. + +In an @code{operating-system} declaration, this service type can be +@emph{extended} using procedures @code{udev-rules-service} and +@code{udev-hardware-service}. @end defvar @deftp {Data Type} udev-configuration @@ -19372,10 +19386,17 @@ Data type representing the configuration of udev. @table @asis @item @code{udev} (default: @code{eudev}) (type: file-like) -Package object of the udev service. +Package object of the udev service. This package is used at run-time, +when compiled for the target system. In order to generate the +@file{hwdb.bin} hardware index, it is also used when generating the +system definition, compiled for the current system. @item @code{rules} (default: @var{'()}) (type: list-of-file-like) -List of file-like objects denoting udev-rule files. +List of file-like objects denoting udev rule files under a sub-directory. + +@item @code{hardware} (default: @var{'()}) (type: list-of-file-like) +List of file-like objects denoting udev hardware description files under +a sub-directory. @end table @end deftp @@ -19398,6 +19419,11 @@ upon detecting a USB device with a given product identifier. @end lisp @end deffn +@deffn {Procedure} udev-hardware @var{file-name} @var{contents} +Return a udev hardware description file named @var{file-name} containing +the hardware information @var{contents}. +@end deffn + @deffn {Procedure} 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. @@ -19417,6 +19443,11 @@ with the previously defined rule @code{%example-udev-rule}. @end lisp @end deffn +@deffn {Procedure} udev-hardware-service @var{name} @var{hardware} +Return a service that extends @code{udev-service-type} with +@var{hardware}. The service name is @code{@var{name}-udev-hardware}. +@end deffn + @deffn {Procedure} 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. @@ -19441,12 +19472,16 @@ The following example showcases how we can use an existing rule file. @end lisp @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. +Since guix package definitions can be included in @var{rules} in order +to use all their rules under the @file{lib/udev/rules.d} sub-directory, +then 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. + +@deffn {Procedure} file->udev-hardware @var{file-name} @var{file} +Return a udev hardware description file named @var{file-name} containing +the rules defined within @var{file}, a file-like object. +@end deffn The following example shows how to use the @var{android-udev-rules} package so that the Android tool @command{adb} can detect devices -- cgit v1.2.3