diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.scm | 2 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 51 | ||||
| -rw-r--r-- | doc/guix.texi | 121 |
3 files changed, 146 insertions, 28 deletions
diff --git a/doc/build.scm b/doc/build.scm index 994b94eae2..3907b49caf 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -142,7 +142,7 @@ as well as images, OS examples, and translations." (for-each (lambda (texi) (install-file texi #$output)) - (append (find-files #$documentation "\\.(texi|scm)$") + (append (find-files #$documentation "\\.(texi|scm|json)$") (find-files #$(translated-texi-manuals source) "\\.texi$"))) diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 58a5ba1c80..5d126acd3d 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -12,6 +12,7 @@ Copyright @copyright{} 2019 Ricardo Wurmus@* Copyright @copyright{} 2019 Efraim Flashner@* Copyright @copyright{} 2019 Pierre Neidhardt@* Copyright @copyright{} 2020 Oleg Pykhalov@* +Copyright @copyright{} 2020 Matthew Brooks@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1322,6 +1323,7 @@ reference. @menu * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. +* Setting up a bind mount:: Setting up a bind mount in the file-systems definition. @end menu @node Customizing the Kernel @@ -1614,6 +1616,55 @@ Then you need to add the following code to a StumpWM configuration file (set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11)) @end lisp +@node Setting up a bind mount +@section Setting up a bind mount + +To bind mount a file system, one must first set up some definitions +before the @code{operating-system} section of the system definition. In +this example we will bind mount a folder from a spinning disk drive to +@code{/tmp}, to save wear and tear on the primary SSD, without +dedicating an entire partition to be mounted as @code{/tmp}. + +First, the source drive that hosts the folder we wish to bind mount +should be defined, so that the bind mount can depend on it. + +@lisp +(define source-drive ;; "source-drive" can be named anything you want. + (file-system + (device (uuid "UUID goes here")) + (mount-point "/path-to-spinning-disk-goes-here") + (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive. +@end lisp + +The source folder must also be defined, so that guix will know it's not +a regular block device, but a folder. +@lisp +(define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name. +@end lisp + +Finally, inside the @code{file-systems} definition, we must add the +mount itself. + +@lisp +(file-systems (cons* + + ...<other drives omitted for clarity>... + + source-drive ;; Must match the name you gave the source drive in the earlier definition. + + (file-system + (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition. + (mount-point "/tmp") + (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none" + (flags '(bind-mount)) + (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive. + ) + + ...<other drives omitted for clarity>... + + )) +@end lisp + @c ********************************************************************* @node Advanced package management @chapter Advanced package management diff --git a/doc/guix.texi b/doc/guix.texi index 0b8460a6fe..19094c4b70 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1691,7 +1691,7 @@ package in Guix looks for fonts in @file{$HOME/.guix-profile} by default. Thus, to allow graphical applications installed with Guix to display fonts, you have to install fonts with Guix as well. Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and -@code{font-gnu-freefont-ttf}. +@code{font-gnu-freefont}. @cindex @code{fc-cache} @cindex font cache @@ -7483,6 +7483,10 @@ value in the absolute file name of @var{file} within the @var{output} directory of @var{package}. When @var{file} is omitted, return the name of the @var{output} directory of @var{package}. When @var{target} is true, use it as a cross-compilation target triplet. + +Note that this procedure does @emph{not} build @var{package}. Thus, the +result might or might not designate an existing file. We recommend not +using this procedure unless you know what you are doing. @end deffn @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}] @@ -7951,7 +7955,8 @@ 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] +@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @ + [#:splice? #f] [#:set-load-path? #t] Return an object representing the Scheme file @var{name} that contains @var{exp}. @@ -12845,8 +12850,12 @@ A directory path where the @command{guix-daemon} will perform builds. @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} and @code{file->udev-rule} from -@code{(gnu services base)} simplify the creation of such rule files. +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. + +The @command{herd rules udev} command, as root, returns the name of the +directory containing all the active udev rules. @end deffn @deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}] @@ -12865,23 +12874,27 @@ upon detecting a USB device with a given product identifier. "ATTR@{product@}==\"Example\", " "RUN+=\"/path/to/script\""))) @end lisp - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. @end deffn -Here we show how the default @var{udev-service} can be extended with it. +@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} +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}. @lisp (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)))))))) + (cons (udev-rules-service 'usb-thing %example-udev-rule) + %desktop-services))) @end lisp +@end deffn @deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}] Return a udev file named @var{file-name} containing the rules defined @@ -12918,10 +12931,10 @@ 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 +the rules defined within the @code{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. +@code{supplementary-groups} of our @code{user-account} declaration, as +well as in the @var{groups} of the @code{udev-rules-service} procedure. @lisp (use-modules (gnu packages android) ;for android-udev-rules @@ -12935,19 +12948,11 @@ well as in the @var{groups} field of the @var{operating-system} record. (supplementary-groups '("adbusers" ;for adb "wheel" "netdev" "audio" "video"))))) - - (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)))))))) + (cons (udev-rules-service 'android android-udev-rules + #:groups '("adbusers")) + %desktop-services))) @end lisp @defvr {Scheme Variable} urandom-seed-service-type @@ -13633,6 +13638,68 @@ List of additional command-line arguments to pass to the daemon. @end table @end deftp +@cindex hostapd service, for Wi-Fi access points +@cindex Wi-Fi access points, hostapd service +@defvr {Scheme Variable} hostapd-service-type +This is the service type to run the @uref{https://w1.fi/hostapd/, +hostapd} daemon to set up WiFi (IEEE 802.11) access points and +authentication servers. Its associated value must be a +@code{hostapd-configuration} as shown below: + +@lisp +;; Use wlan1 to run the access point for "My Network". +(service hostapd-service-type + (hostapd-configuration + (interface "wlan1") + (ssid "My Network") + (channel 12))) +@end lisp +@end defvr + +@deftp {Data Type} hostapd-configuration +This data type represents the configuration of the hostapd service, with +the following fields: + +@table @asis +@item @code{package} (default: @code{hostapd}) +The hostapd package to use. + +@item @code{interface} (default: @code{"wlan0"}) +The network interface to run the WiFi access point. + +@item @code{ssid} +The SSID (@dfn{service set identifier}), a string that identifies this +network. + +@item @code{broadcast-ssid?} (default: @code{#t}) +Whether to broadcast this SSID. + +@item @code{channel} (default: @code{1}) +The WiFi channel to use. + +@item @code{driver} (default: @code{"nl80211"}) +The driver interface type. @code{"nl80211"} is used with all Linux +mac80211 drivers. Use @code{"none"} if building hostapd as a standalone +RADIUS server that does # not control any wireless/wired driver. + +@item @code{extra-settings} (default: @code{""}) +Extra settings to append as-is to the hostapd configuration file. See +@uref{https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf} for the +configuration file reference. +@end table +@end deftp + +@defvr {Scheme Variable} simulated-wifi-service-type +This is the type of a service to simulate WiFi networking, which can be +useful in virtual machines for testing purposes. The service loads the +Linux kernel +@uref{https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html, +@code{mac80211_hwsim} module} and starts hostapd to create a pseudo WiFi +network that can be seen on @code{wlan0}, by default. + +The service's value is a @code{hostapd-configuration} record. +@end defvr + @cindex iptables @defvr {Scheme Variable} iptables-service-type This is the service type to set up an iptables configuration. iptables is a |