diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 110 |
1 files changed, 82 insertions, 28 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index b353d91bd5..27dc9143fa 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -9494,6 +9494,9 @@ install all files but those matching the exclusion filters. If both inclusions and exclusions are specified, the exclusions are done on top of the inclusions. @end itemize +@item When a package has multiple outputs, the @code{#:output} argument +can be used to specify which output label the files should be installed +to. @end itemize In all cases, the paths relative to @var{source} are preserved within @var{target}. @@ -9510,6 +9513,9 @@ e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}. @file{share/my-app/sub/file}. @item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to @file{share/my-app/file}. +@item @code{("foo/doc" "share/my-app/doc" #:output "doc")}: Install +@file{"foo/doc"} to @file{"share/my-app/doc"} within the @code{"doc"} +output. @end itemize @end defvar @@ -10801,12 +10807,18 @@ Make @var{file} writable for its owner. @deffn {Procedure} copy-recursively source destination @ [#:log (current-output-port)] [#:follow-symlinks? #f] @ [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t] + [#:select? (const #t)] Copy @var{source} directory to @var{destination}. Follow symlinks if @var{follow-symlinks?} is true; otherwise, just preserve them. Call -@var{copy-file} to copy regular files. When @var{keep-mtime?} is true, -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. +@var{copy-file} to copy regular files. Call @var{select?}, taking two +arguments, @var{file} and @var{stat}, for each entry in @var{source}, +where @var{file} is the entry's absolute file name and @var{stat} is the +result of @code{lstat} (or @code{stat} if @var{follow-symlinks?} is +true); exclude entries for which @var{select?} does not return true. +When @var{keep-mtime?} is true, 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 @deffn {Procedure} delete-file-recursively dir [#:follow-mounts? #f] @@ -11253,17 +11265,14 @@ contain a list of @file{catalog.xml} files (not directories), which are to be found in @file{xml} sub-directories---nothing less. The search path specification looks like this: +@c This is defined at (guix search-paths) as $XML_CATALOG_FILES. @lisp -(package - (name "libxml2") - ;; some fields omitted - (native-search-paths - (list (search-path-specification - (variable "XML_CATALOG_FILES") - (separator " ") - (files '("xml")) - (file-pattern "^catalog\\.xml$") - (file-type 'regular))))) +(search-path-specification + (variable "XML_CATALOG_FILES") + (separator " ") + (files '("xml")) + (file-pattern "^catalog\\.xml$") + (file-type 'regular)) @end lisp Worry not, search path specifications are usually not this tricky. @@ -11299,15 +11308,16 @@ The type of file being matched---@code{'directory} or @code{'regular}, though it can be any symbol returned by @code{stat:type} (@pxref{File System, @code{stat},, guile, GNU Guile Reference Manual}). -In the libxml2 example above, we would match regular files; in the -Python example, we would match directories. +In the @env{XML_CATALOG_FILES} example above, we would match regular +files; in the Python example, we would match directories. @item @code{file-pattern} (default: @code{#f}) This must be either @code{#f} or a regular expression specifying files to be matched @emph{within} the sub-directories specified by the @code{files} field. -Again, the libxml2 example shows a situation where this is needed. +Again, the @env{XML_CATALOG_FILES} example shows a situation where this +is needed. @end table @end deftp @@ -11315,6 +11325,15 @@ Some search paths are not tied by a single package but to many packages. To reduce duplications, some of them are pre-defined in @code{(guix search-paths)}. +@defvar $SGML_CATALOG_FILES +@defvarx $XML_CATALOG_FILES +These two search paths indicate where the +@url{https://www.oasis-open.org/specs/a401.htm,TR9401 catalog}@footnote{ +Alternatively known as SGML catalog.} or +@url{https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html, +XML catalog} files can be found. +@end defvar + @defvar $SSL_CERT_DIR @defvarx $SSL_CERT_FILE These two search paths indicate where X.509 certificates can be found @@ -19913,9 +19932,23 @@ 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. +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 @@ -19923,10 +19956,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 @@ -19949,6 +19989,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. @@ -19968,6 +20013,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. @@ -19992,12 +20042,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 |