diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 508 |
1 files changed, 293 insertions, 215 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 7219ef4d0f..25c08b9f06 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23,7 +23,7 @@ Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* -Copyright @copyright{} 2016, 2017 Chris Marusich@* +Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016, 2017 Nils Gillmann@* @@ -471,7 +471,7 @@ archive content is independent of its creation time, thus making it reproducible. @item -Make @code{root}'s profile available under @file{~/.guix-profile}: +Make @code{root}'s profile available under @file{~root/.guix-profile}: @example # ln -sf /var/guix/profiles/per-user/root/guix-profile \ @@ -482,7 +482,7 @@ Source @file{etc/profile} to augment @code{PATH} and other relevant environment variables: @example -# GUIX_PROFILE=$HOME/.guix-profile ; \ +# GUIX_PROFILE="`echo ~root`/.guix-profile" ; \ source $GUIX_PROFILE/etc/profile @end example @@ -2642,6 +2642,24 @@ of these, recursively. In other words, the returned list is the of an element. @xref{Invoking guix graph}, for a tool to visualize the graph of references. +@item --derivers +@cindex derivation +Return the derivation(s) leading to the given store items +(@pxref{Derivations}). + +For example, this command: + +@example +guix gc --derivers `guix package -I ^emacs$ | cut -f4` +@end example + +@noindent +returns the @file{.drv} file(s) leading to the @code{emacs} package +installed in your profile. + +Note that there may be zero matching @file{.drv} files, for instance +because these files have been garbage-collected. There can also be more +than one matching @file{.drv} due to fixed-output derivations. @end table Lastly, the following options allow you to check the integrity of the @@ -2899,6 +2917,10 @@ added to it or removed from it after extraction of the pack. One use case for this is the Guix self-contained binary tarball (@pxref{Binary Installation}). + +@item --bootstrap +Use the bootstrap binaries to build the pack. This option is only +useful to Guix developers. @end table In addition, @command{guix pack} supports all the common build options @@ -5150,9 +5172,11 @@ is a list of additional arguments to pass to @code{gexp->derivation}. This is the declarative counterpart of @code{gexp->derivation}. @end deffn -@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} +@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @ + [#:guile (default-guile)] [#:module-path %load-path] Return an executable script @var{name} that runs @var{exp} using @var{guile}, with @var{exp}'s imported modules in its search path. +Look up @var{exp}'s modules in @var{module-path}. The example below builds a script that simply invokes the @command{ls} command: @@ -5177,20 +5201,22 @@ executable file @file{/gnu/store/@dots{}-list-files} along these lines: @end deffn @deffn {Scheme Procedure} program-file @var{name} @var{exp} @ - [#:guile #f] + [#:guile #f] [#:module-path %load-path] Return an object representing the executable store item @var{name} that runs @var{gexp}. @var{guile} is the Guile package used to execute that -script. +script. Imported modules of @var{gexp} are looked up in @var{module-path}. This is the declarative counterpart of @code{gexp->script}. @end deffn @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @ - [#:set-load-path? #t] + [#:set-load-path? #t] [#:module-path %load-path] @ + [#:guile (default-guile)] Return a derivation that builds a file @var{name} containing @var{exp}. When @var{set-load-path?} is true, emit code in the resulting file to set @code{%load-path} and @code{%load-compiled-path} to honor -@var{exp}'s imported modules. +@var{exp}'s imported modules. Look up @var{exp}'s modules in +@var{module-path}. The resulting file holds references to all the dependencies of @var{exp} or a subset thereof. @@ -6989,6 +7015,15 @@ name instead of a package name, as in: @example guix graph -t derivation `guix system build -d my-config.scm` @end example + +@item module +This is the graph of @dfn{package modules} (@pxref{Package Modules}). +For example, the following command shows the graph for the package +module that defines the @code{guile} package: + +@example +guix graph -t module guile | dot -Tpdf > module-graph.pdf +@end example @end table All the types above correspond to @emph{build-time dependencies}. The @@ -7877,15 +7912,27 @@ https://guix.example.org 19,824.2 MiB on disk (uncompressed) 0.030 seconds per request (182.9 seconds in total) 33.5 requests per second + + 9.8% (342 out of 3,470) of the missing items are queued + 867 queued builds + x86_64-linux: 518 (59.7%) + i686-linux: 221 (25.5%) + aarch64-linux: 128 (14.8%) + build rate: 23.41 builds per hour + x86_64-linux: 11.16 builds per hour + i686-linux: 6.03 builds per hour + aarch64-linux: 6.41 builds per hour @end example +@cindex continuous integration, statistics As you can see, it reports the fraction of all the packages for which substitutes are available on the server---regardless of whether substitutes are enabled, and regardless of whether this server's signing key is authorized. It also reports the size of the compressed archives (``nars'') provided by the server, the size the corresponding store items occupy in the store (assuming deduplication is turned off), and -the server's throughput. +the server's throughput. The second part gives continuous integration +(CI) statistics, if the server supports it. To achieve that, @command{guix weather} queries over HTTP(S) meta-data (@dfn{narinfos}) for all the relevant store items. Like @command{guix @@ -10396,6 +10443,8 @@ to add @var{device} to the kernel's entropy pool. The service will fail if @cindex session limits @cindex ulimit @cindex priority +@cindex realtime +@cindex jackd @deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}] Return a service that installs a configuration file for the @@ -15730,7 +15779,7 @@ Must be either: @item @code{<php-fpm-on-demand-process-manager-configuration>} @end table @item @code{display-errors} (default @code{#f}) -Determines wether php errors and warning should be sent to clients +Determines whether php errors and warning should be sent to clients and displayed in their browsers. This is useful for local php development, but a security risk for public sites, as error messages can reveal passwords and personal data. @@ -18325,11 +18374,12 @@ Return the name of @var{platform}---a string such as @code{"arm"}. @subsubsection Version Control Services The @code{(gnu services version-control)} module provides a service to -allow remote access to local Git repositories. There are two options: +allow remote access to local Git repositories. There are three options: the @code{git-daemon-service}, which provides access to repositories via -the @code{git://} unsecured TCP-based protocol, or extending the +the @code{git://} unsecured TCP-based protocol, extending the @code{nginx} web server to proxy some requests to -@code{git-http-backend}. +@code{git-http-backend}, or providing a web interface with +@code{cgit-service-type}. @deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)] @@ -18462,199 +18512,6 @@ HTTPS. You will also need to add an @code{fcgiwrap} proxy to your system services. @xref{Web Services}. @end deffn -@node Game Services -@subsubsection Game Services - -@subsubheading The Battle for Wesnoth Service -@cindex wesnothd -@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn -based tactical strategy game, with several single player campaigns, and -multiplayer games (both networked and local). - -@defvar {Scheme Variable} wesnothd-service-type -Service type for the wesnothd service. Its value must be a -@code{wesnothd-configuration} object. To run wesnothd in the default -configuration, instantiate it as: - -@example -(service wesnothd-service-type) -@end example -@end defvar - -@deftp {Data Type} wesnothd-configuration -Data type representing the configuration of @command{wesnothd}. - -@table @asis -@item @code{package} (default: @code{wesnoth-server}) -The wesnoth server package to use. - -@item @code{port} (default: @code{15000}) -The port to bind the server to. -@end table -@end deftp - -@node Miscellaneous Services -@subsubsection Miscellaneous Services - -@cindex sysctl -@subsubheading System Control Service - -The @code{(gnu services sysctl)} provides a service to configure kernel -parameters at boot. - -@defvr {Scheme Variable} sysctl-service-type -The service type for @command{sysctl}, which modifies kernel parameters -under @file{/proc/sys/}. To enable IPv4 forwarding, it can be -instantiated as: - -@example -(service sysctl-service-type - (sysctl-configuration - (settings '(("net.ipv4.ip_forward" . "1"))))) -@end example -@end defvr - -@deftp {Data Type} sysctl-configuration -The data type representing the configuration of @command{sysctl}. - -@table @asis -@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"}) -The @command{sysctl} executable to use. - -@item @code{settings} (default: @code{'()}) -An association list specifies kernel parameters and their values. -@end table -@end deftp - -@cindex lirc -@subsubheading Lirc Service - -The @code{(gnu services lirc)} module provides the following service. - -@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ - [#:device #f] [#:driver #f] [#:config-file #f] @ - [#:extra-options '()] -Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that -decodes infrared signals from remote controls. - -Optionally, @var{device}, @var{driver} and @var{config-file} -(configuration file name) may be specified. See @command{lircd} manual -for details. - -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{lircd}. -@end deffn - -@cindex spice -@subsubheading Spice Service - -The @code{(gnu services spice)} module provides the following service. - -@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] -Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon -that enables sharing the clipboard with a vm and setting the guest display -resolution when the graphical console window resizes. -@end deffn - -@subsubsection Dictionary Services -@cindex dictionary -The @code{(gnu services dict)} module provides the following service: - -@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)] -Return a service that runs the @command{dicod} daemon, an implementation -of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). - -The optional @var{config} argument specifies the configuration for -@command{dicod}, which should be a @code{<dicod-configuration>} object, by -default it serves the GNU Collaborative International Dictonary of English. - -You can add @command{open localhost} to your @file{~/.dico} file to make -@code{localhost} the default server for @command{dico} client -(@pxref{Initialization File,,, dico, GNU Dico Manual}). -@end deffn - -@deftp {Data Type} dicod-configuration -Data type representing the configuration of dicod. - -@table @asis -@item @code{dico} (default: @var{dico}) -Package object of the GNU Dico dictionary server. - -@item @code{interfaces} (default: @var{'("localhost")}) -This is the list of IP addresses and ports and possibly socket file -names to listen to (@pxref{Server Settings, @code{listen} directive,, -dico, GNU Dico Manual}). - -@item @code{handlers} (default: @var{'()}) -List of @code{<dicod-handler>} objects denoting handlers (module instances). - -@item @code{databases} (default: @var{(list %dicod-database:gcide)}) -List of @code{<dicod-database>} objects denoting dictionaries to be served. -@end table -@end deftp - -@deftp {Data Type} dicod-handler -Data type representing a dictionary handler (module instance). - -@table @asis -@item @code{name} -Name of the handler (module instance). - -@item @code{module} (default: @var{#f}) -Name of the dicod module of the handler (instance). If it is @code{#f}, -the module has the same name as the handler. -(@pxref{Modules,,, dico, GNU Dico Manual}). - -@item @code{options} -List of strings or gexps representing the arguments for the module handler -@end table -@end deftp - -@deftp {Data Type} dicod-database -Data type representing a dictionary database. - -@table @asis -@item @code{name} -Name of the database, will be used in DICT commands. - -@item @code{handler} -Name of the dicod handler (module instance) used by this database -(@pxref{Handlers,,, dico, GNU Dico Manual}). - -@item @code{complex?} (default: @var{#f}) -Whether the database configuration complex. The complex configuration -will need a corresponding @code{<dicod-handler>} object, otherwise not. - -@item @code{options} -List of strings or gexps representing the arguments for the database -(@pxref{Databases,,, dico, GNU Dico Manual}). -@end table -@end deftp - -@defvr {Scheme Variable} %dicod-database:gcide -A @code{<dicod-database>} object serving the GNU Collaborative International -Dictionary of English using the @code{gcide} package. -@end defvr - -The following is an example @code{dicod-service} configuration. - -@example -(dicod-service #:config - (dicod-configuration - (handlers (list (dicod-handler - (name "wordnet") - (module "dictorg") - (options - (list #~(string-append "dbdir=" #$wordnet)))))) - (databases (list (dicod-database - (name "wordnet") - (complex? #t) - (handler "wordnet") - (options '("database=wn"))) - %dicod-database:gcide)))) -@end example - - @subsubheading Cgit Service @cindex Cgit service @@ -19593,6 +19450,199 @@ could instantiate a cgit service like this: (cgitrc ""))) @end example + +@node Game Services +@subsubsection Game Services + +@subsubheading The Battle for Wesnoth Service +@cindex wesnothd +@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn +based tactical strategy game, with several single player campaigns, and +multiplayer games (both networked and local). + +@defvar {Scheme Variable} wesnothd-service-type +Service type for the wesnothd service. Its value must be a +@code{wesnothd-configuration} object. To run wesnothd in the default +configuration, instantiate it as: + +@example +(service wesnothd-service-type) +@end example +@end defvar + +@deftp {Data Type} wesnothd-configuration +Data type representing the configuration of @command{wesnothd}. + +@table @asis +@item @code{package} (default: @code{wesnoth-server}) +The wesnoth server package to use. + +@item @code{port} (default: @code{15000}) +The port to bind the server to. +@end table +@end deftp + +@node Miscellaneous Services +@subsubsection Miscellaneous Services + +@cindex sysctl +@subsubheading System Control Service + +The @code{(gnu services sysctl)} provides a service to configure kernel +parameters at boot. + +@defvr {Scheme Variable} sysctl-service-type +The service type for @command{sysctl}, which modifies kernel parameters +under @file{/proc/sys/}. To enable IPv4 forwarding, it can be +instantiated as: + +@example +(service sysctl-service-type + (sysctl-configuration + (settings '(("net.ipv4.ip_forward" . "1"))))) +@end example +@end defvr + +@deftp {Data Type} sysctl-configuration +The data type representing the configuration of @command{sysctl}. + +@table @asis +@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"}) +The @command{sysctl} executable to use. + +@item @code{settings} (default: @code{'()}) +An association list specifies kernel parameters and their values. +@end table +@end deftp + +@cindex lirc +@subsubheading Lirc Service + +The @code{(gnu services lirc)} module provides the following service. + +@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ + [#:device #f] [#:driver #f] [#:config-file #f] @ + [#:extra-options '()] +Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that +decodes infrared signals from remote controls. + +Optionally, @var{device}, @var{driver} and @var{config-file} +(configuration file name) may be specified. See @command{lircd} manual +for details. + +Finally, @var{extra-options} is a list of additional command-line options +passed to @command{lircd}. +@end deffn + +@cindex spice +@subsubheading Spice Service + +The @code{(gnu services spice)} module provides the following service. + +@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] +Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon +that enables sharing the clipboard with a vm and setting the guest display +resolution when the graphical console window resizes. +@end deffn + +@subsubsection Dictionary Services +@cindex dictionary +The @code{(gnu services dict)} module provides the following service: + +@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)] +Return a service that runs the @command{dicod} daemon, an implementation +of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). + +The optional @var{config} argument specifies the configuration for +@command{dicod}, which should be a @code{<dicod-configuration>} object, by +default it serves the GNU Collaborative International Dictonary of English. + +You can add @command{open localhost} to your @file{~/.dico} file to make +@code{localhost} the default server for @command{dico} client +(@pxref{Initialization File,,, dico, GNU Dico Manual}). +@end deffn + +@deftp {Data Type} dicod-configuration +Data type representing the configuration of dicod. + +@table @asis +@item @code{dico} (default: @var{dico}) +Package object of the GNU Dico dictionary server. + +@item @code{interfaces} (default: @var{'("localhost")}) +This is the list of IP addresses and ports and possibly socket file +names to listen to (@pxref{Server Settings, @code{listen} directive,, +dico, GNU Dico Manual}). + +@item @code{handlers} (default: @var{'()}) +List of @code{<dicod-handler>} objects denoting handlers (module instances). + +@item @code{databases} (default: @var{(list %dicod-database:gcide)}) +List of @code{<dicod-database>} objects denoting dictionaries to be served. +@end table +@end deftp + +@deftp {Data Type} dicod-handler +Data type representing a dictionary handler (module instance). + +@table @asis +@item @code{name} +Name of the handler (module instance). + +@item @code{module} (default: @var{#f}) +Name of the dicod module of the handler (instance). If it is @code{#f}, +the module has the same name as the handler. +(@pxref{Modules,,, dico, GNU Dico Manual}). + +@item @code{options} +List of strings or gexps representing the arguments for the module handler +@end table +@end deftp + +@deftp {Data Type} dicod-database +Data type representing a dictionary database. + +@table @asis +@item @code{name} +Name of the database, will be used in DICT commands. + +@item @code{handler} +Name of the dicod handler (module instance) used by this database +(@pxref{Handlers,,, dico, GNU Dico Manual}). + +@item @code{complex?} (default: @var{#f}) +Whether the database configuration complex. The complex configuration +will need a corresponding @code{<dicod-handler>} object, otherwise not. + +@item @code{options} +List of strings or gexps representing the arguments for the database +(@pxref{Databases,,, dico, GNU Dico Manual}). +@end table +@end deftp + +@defvr {Scheme Variable} %dicod-database:gcide +A @code{<dicod-database>} object serving the GNU Collaborative International +Dictionary of English using the @code{gcide} package. +@end defvr + +The following is an example @code{dicod-service} configuration. + +@example +(dicod-service #:config + (dicod-configuration + (handlers (list (dicod-handler + (name "wordnet") + (module "dictorg") + (options + (list #~(string-append "dbdir=" #$wordnet)))))) + (databases (list (dicod-database + (name "wordnet") + (complex? #t) + (handler "wordnet") + (options '("database=wn"))) + %dicod-database:gcide)))) +@end example + @node Setuid Programs @subsection Setuid Programs @@ -20374,12 +20424,18 @@ containing at least the kernel, initrd, and bootloader data files must be created. The @code{--image-size} option can be used to specify the size of the image. +@cindex System images, creation in various formats +@cindex Creating system images in various formats @item vm-image @itemx disk-image -Return a virtual machine or disk image of the operating system declared -in @var{file} that stands alone. By default, @command{guix system} -estimates the size of the image needed to store the system, but you can -use the @option{--image-size} option to specify a value. +@itemx docker-image +Return a virtual machine, disk image, or Docker image of the operating +system declared in @var{file} that stands alone. By default, +@command{guix system} estimates the size of the image needed to store +the system, but you can use the @option{--image-size} option to specify +a value. Docker images are built to contain exactly what they need, so +the @option{--image-size} option is ignored in the case of +@code{docker-image}. You can specify the root file system type by using the @option{--file-system-type} option. It defaults to @code{ext4}. @@ -20397,6 +20453,28 @@ using the following command: # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc @end example +When using @code{docker-image}, a Docker image is produced. Guix builds +the image from scratch, not from a pre-existing Docker base image. As a +result, it contains @emph{exactly} what you define in the operating +system configuration file. You can then load the image and launch a +Docker container using commands like the following: + +@example +image_id="$(docker load < guixsd-docker-image.tar.gz)" +docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\ + --entrypoint /var/guix/profiles/system/profile/bin/guile \\ + $image_id /var/guix/profiles/system/boot +@end example + +This command starts a new Docker container from the specified image. It +will boot the GuixSD system in the usual manner, which means it will +start any services you have defined in the operating system +configuration. Depending on what you run in the Docker container, it +may be necessary to give the container additional permissions. For +example, if you intend to build software using Guix inside of the Docker +container, you may need to pass the @option{--privileged} option to +@code{docker run}. + @item container Return a script to run the operating system declared in @var{file} within a container. Containers are a set of lightweight isolation @@ -21012,16 +21090,16 @@ services. Otherwise, it must be a one-argument procedure. The procedure is called by @code{fold-services} and is passed a list of values collected from -extensions. It must return a value that is a valid parameter value for -the service instance. +extensions. It may return any single value. @item @code{extend} (default: @code{#f}) If this is @code{#f}, services of this type cannot be extended. Otherwise, it must be a two-argument procedure: @code{fold-services} -calls it, passing it the initial value of the service as the first argument -and the result of applying @code{compose} to the extension values as the -second argument. +calls it, passing it the initial value of the service as the first +argument and the result of applying @code{compose} to the extension +values as the second argument. It must return a value that is a valid +parameter value for the service instance. @end table @xref{Service Types and Services}, for examples. |