diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 247 |
1 files changed, 225 insertions, 22 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index a458c7c8dd..19c9813f6a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -27,7 +27,7 @@ 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@* -Copyright @copyright{} 2016, 2017 Jan Nieuwenhuizen@* +Copyright @copyright{} 2016, 2017, 2018 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2017, 2018 Clément Lassieur@* @@ -48,7 +48,8 @@ Copyright @copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike Gerwitz@* -Copyright @copyright{} 2018 Pierre-Antoine Rouby +Copyright @copyright{} 2018 Pierre-Antoine Rouby@* +Copyright @copyright{} 2018 Gábor Boskovits@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -165,6 +166,7 @@ Programming Interface * Derivations:: Low-level interface to package derivations. * The Store Monad:: Purely functional interface to the store. * G-Expressions:: Manipulating build expressions. +* Invoking guix repl:: Fiddling with Guix interactively. Defining Packages @@ -429,7 +431,7 @@ Installing goes along these lines: @item @cindex downloading Guix binary Download the binary tarball from -@indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}, +@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}, where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine already running the kernel Linux, and so on. @@ -438,7 +440,7 @@ Make sure to download the associated @file{.sig} file and to verify the authenticity of the tarball against it, along these lines: @example -$ wget ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig +$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig $ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig @end example @@ -1373,8 +1375,8 @@ derivations. @cindex garbage collector roots When set to ``yes'', the GC will keep the outputs of any live derivation available in the store---the @code{.drv} files. The default is ``no'', -meaning that derivation outputs are kept only if they are GC roots. -@xref{Invoking guix gc}, for more on GC roots. +meaning that derivation outputs are kept only if they are reachable from a GC +root. @xref{Invoking guix gc}, for more on GC roots. @item --gc-keep-derivations[=yes|no] Tell whether the garbage collector (GC) must keep derivations @@ -1385,12 +1387,13 @@ derivations---i.e., @code{.drv} files---as long as at least one of their outputs is live. This allows users to keep track of the origins of items in their store. Setting it to ``no'' saves a bit of disk space. -Note that when both @code{--gc-keep-derivations} and -@code{--gc-keep-outputs} are used, the effect is to keep all the build -prerequisites (the sources, compiler, libraries, and other build-time -tools) of live objects in the store, regardless of whether these -prerequisites are live. This is convenient for developers since it -saves rebuilds or downloads. +In this way, setting @code{--gc-keep-derivations} to ``yes'' causes liveness +to flow from outputs to derivations, and setting @code{--gc-keep-outputs} to +``yes'' causes liveness to flow from derivations to outputs. When both are +set to ``yes'', the effect is to keep all the build prerequisites (the +sources, compiler, libraries, and other build-time tools) of live objects in +the store, regardless of whether these prerequisites are reachable from a GC +root. This is convenient for developers since it saves rebuilds or downloads. @item --impersonate-linux-2.6 On Linux-based systems, impersonate Linux 2.6. This means that the @@ -2784,12 +2787,18 @@ Generation 2 Jun 11 2018 11:02:49 repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d + 2 new packages: keepalived, libnfnetlink + 6 packages upgraded: emacs-nix-mode@@2.0.4, + guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac, + heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4 Generation 3 Jun 13 2018 23:31:07 (current) guix 844cc1c repository URL: https://git.savannah.gnu.org/git/guix.git branch: origin/master commit: 844cc1c8f394f03b404c5bb3aee086922373490c + 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{} + 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{} @end example This @code{~/.config/guix/current} profile works like any other profile @@ -3266,6 +3275,7 @@ package definitions. * Derivations:: Low-level interface to package derivations. * The Store Monad:: Purely functional interface to the store. * G-Expressions:: Manipulating build expressions. +* Invoking guix repl:: Fiddling with Guix interactively. @end menu @node Defining Packages @@ -4036,6 +4046,21 @@ specified with the @code{#:glib} parameter. Both phases are executed after the @code{install} phase. @end defvr +@defvr {Scheme Variable} guile-build-system +This build system is for Guile packages that consist exclusively of Scheme +code and that are so lean that they don't even have a makefile, let alone a +@file{configure} script. It compiles Scheme code using @command{guild +compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and +installs the @file{.scm} and @file{.go} files in the right place. It also +installs documentation. + +This build system supports cross-compilation by using the @code{--target} +option of @command{guild compile}. + +Packages built with @code{guile-build-system} must provide a Guile package in +their @code{native-inputs} field. +@end defvr + @defvr {Scheme Variable} minify-build-system This variable is exported by @code{(guix build-system minify)}. It implements a minification procedure for simple JavaScript packages. @@ -4915,6 +4940,12 @@ containing @var{text}, a string. @var{references} is a list of store items that resulting text file refers to; it defaults to the empty list. @end deffn +@deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}] +Return as a monadic value the absolute file name in the store of the file +containing @var{data}, a bytevector. @var{references} is a list of store +items that the resulting binary file refers to; it defaults to the empty list. +@end deffn + @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @ [#:recursive? #t] [#:select? (const #t)] Return the name of @var{file} once interned in the store. Use @@ -5348,7 +5379,7 @@ procedure (@pxref{The Store Monad, @code{interned-file}}). @deffn {Scheme Procedure} plain-file @var{name} @var{content} Return an object representing a text file called @var{name} with the given -@var{content} (a string) to be added to the store. +@var{content} (a string or a bytevector) to be added to the store. This is the declarative counterpart of @code{text-file}. @end deffn @@ -5537,6 +5568,57 @@ corresponding to @var{obj} for @var{system}, cross-compiling for has an associated gexp compiler, such as a @code{<package>}. @end deffn +@node Invoking guix repl +@section Invoking @command{guix repl} + +@cindex REPL, read-eval-print loop +The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop} +(REPL) for interactive programming (@pxref{Using Guile Interactively,,, guile, +GNU Guile Reference Manual}). Compared to just launching the @command{guile} +command, @command{guix repl} guarantees that all the Guix modules and all its +dependencies are available in the search path. You can use it this way: + +@example +$ guix repl +scheme@@(guile-user)> ,use (gnu packages base) +scheme@@(guile-user)> coreutils +$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300> +@end example + +@cindex inferiors +In addition, @command{guix repl} implements a simple machine-readable REPL +protocol for use by @code{(guix inferior)}, a facility to interact with +@dfn{inferiors}, separate processes running a potentially different revision +of Guix. + +The available options are as follows: + +@table @code +@item --type=@var{type} +@itemx -t @var{type} +Start a REPL of the given @var{TYPE}, which can be one of the following: + +@table @code +@item guile +This is default, and it spawns a standard full-featured Guile REPL. +@item machine +Spawn a REPL that uses the machine-readable protocol. This is the protocol +that the @code{(guix inferior)} module speaks. +@end table + +@item --listen=@var{endpoint} +By default, @command{guix repl} reads from standard input and writes to +standard output. When this option is passed, it will instead listen for +connections on @var{endpoint}. Here are examples of valid options: + +@table @code +@item --listen=tcp:37146 +Accept connections on localhost on port 37146. + +@item --listen=unix:/tmp/socket +Accept connections on the Unix-domain socket @file{/tmp/socket}. +@end table +@end table @c ********************************************************************* @node Utilities @@ -6379,6 +6461,14 @@ The command below imports metadata for the @code{rails} Ruby package: guix import gem rails @end example +@table @code +@item --recursive +@itemx -r +Traverse the dependency graph of the given upstream package recursively +and generate package expressions for all those packages that are not yet +in Guix. +@end table + @item cpan @cindex CPAN Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}@footnote{This @@ -6660,6 +6750,12 @@ in Guix. @cindex crate Import metadata from the crates.io Rust package repository @uref{https://crates.io, crates.io}. + +@item opam +@cindex OPAM +@cindex OCaml +Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package +repository used by the OCaml community. @end table The structure of the @command{guix import} code is modular. It would be @@ -8392,7 +8488,7 @@ about their support in GNU/Linux. An ISO-9660 installation image that can be written to a USB stick or burnt to a DVD can be downloaded from -@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz}, +@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz}, where @var{system} is one of: @table @code @@ -8408,7 +8504,7 @@ Make sure to download the associated @file{.sig} file and to verify the authenticity of the image against it, along these lines: @example -$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig +$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig $ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig @end example @@ -10829,6 +10925,21 @@ gexps to introduce job definitions that are passed to mcron for more information on mcron job specifications. Below is the reference of the mcron service. +On a running system, you can use the @code{schedule} action of the service to +visualize the mcron jobs that will be executed next: + +@example +# herd schedule mcron +@end example + +@noindent +The example above lists the next five tasks that will be executed, but you can +also specify the number of tasks to display: + +@example +# herd schedule mcron 10 +@end example + @deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron}] Return an mcron service running @var{mcron} that schedules @var{jobs}, a list of gexps denoting mcron job specifications. @@ -12046,7 +12157,7 @@ secure connections to the print server. Suppose you want to enable the Web interface of CUPS and also add support for Epson printers @i{via} the @code{escpr} package and for HP -printers @i{via} the @code{hplip} package. You can do that directly, +printers @i{via} the @code{hplip-minimal} package. You can do that directly, like this (you need to use the @code{(gnu packages cups)} module): @example @@ -12054,9 +12165,13 @@ like this (you need to use the @code{(gnu packages cups)} module): (cups-configuration (web-interface? #t) (extensions - (list cups-filters escpr hplip)))) + (list cups-filters escpr hplip-minimal)))) @end example +Note: If you wish to use the Qt5 based GUI which comes with the hplip +package then it is suggested that you install the @code{hplip} package, +either in your OS configuration file or as your user. + The available configuration parameters follow. Each parameter definition is preceded by its type; for example, @samp{string-list foo} indicates that the @code{foo} parameter should be specified as a list of @@ -15649,6 +15764,39 @@ Specify the path of the base URL. This can be useful if @end table @end deftp +@subsubheading Prometheus Node Exporter Service + +@cindex prometheus-node-exporter +The Prometheus ``node exporter'' makes hardware and operating system statistics +provided by the Linux kernel available for the Prometheus monitoring system. +This service should be deployed on all physical nodes and virtual machines, +where monitoring these statistics is desirable. + +@defvar {Scheme variable} prometheus-node-exporter-service-type +This is the service type for the +@uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter} +service, its value must be a @code{prometheus-node-exporter-configuration} +record as in this example: + +@example +(service prometheus-node-exporter-service-type + (prometheus-node-exporter-configuration + (web-listen-address ":9100"))) +@end example +@end defvar + +@deftp {Data Type} prometheus-node-exporter-configuration +Data type representing the configuration of @command{node_exporter}. + +@table @asis +@item @code{package} (default: @code{go-github-com-prometheus-node-exporter}) +The prometheus-node-exporter package to use. + +@item @code{web-listen-address} (default: @code{":9100"}) +Bind the web interface to the specified address. + +@end table +@end deftp @node Kerberos Services @subsubsection Kerberos Services @@ -17614,10 +17762,6 @@ Only evaluate specifications and build derivations once. When substituting a pre-built binary fails, fall back to building packages locally. -@item @code{load-path} (default: @code{'()}) -This allows users to define their own packages and make them visible to -cuirass as in @command{guix build} command. - @item @code{cuirass} (default: @code{cuirass}) The Cuirass package to use. @end table @@ -21323,7 +21467,7 @@ example graph. @cindex virtual machine To run GuixSD in a virtual machine (VM), one can either use the pre-built GuixSD VM image distributed at -@indicateurl{ftp://alpha.gnu.org/guix/guixsd-vm-image-@value{VERSION}.@var{system}.tar.xz} +@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz} , or build their own virtual machine image using @command{guix system vm-image} (@pxref{Invoking guix system}). The returned image is in qcow2 format, which the @uref{http://qemu.org/, QEMU emulator} can @@ -21915,6 +22059,17 @@ Constructors,,, shepherd, The GNU Shepherd Manual}). They are given as G-expressions that get expanded in the Shepherd configuration file (@pxref{G-Expressions}). +@item @code{actions} (default: @code{'()}) +@cindex actions, of Shepherd services +This is a list of @code{shepherd-action} objects (see below) defining +@dfn{actions} supported by the service, in addition to the standard +@code{start} and @code{stop} actions. Actions listed here become available as +@command{herd} sub-commands: + +@example +herd @var{action} @var{service} [@var{arguments}@dots{}] +@end example + @item @code{documentation} A documentation string, as shown when running: @@ -21932,6 +22087,54 @@ This is the list of modules that must be in scope when @code{start} and @end table @end deftp +@deftp {Data Type} shepherd-action +This is the data type that defines additional actions implemented by a +Shepherd service (see above). + +@table @code +@item name +Symbol naming the action. + +@item documentation +This is a documentation string for the action. It can be viewed by running: + +@example +herd doc @var{service} action @var{action} +@end example + +@item procedure +This should be a gexp that evaluates to a procedure of at least one argument, +which is the ``running value'' of the service (@pxref{Slots of services,,, +shepherd, The GNU Shepherd Manual}). +@end table + +The following example defines an action called @code{say-hello} that kindly +greets the user: + +@example +(shepherd-action + (name 'say-hello) + (documentation "Say hi!") + (procedure #~(lambda (running . args) + (format #t "Hello, friend! arguments: ~s\n" + args) + #t))) +@end example + +Assuming this action is added to the @code{example} service, then you can do: + +@example +# herd say-hello example +Hello, friend! arguments: () +# herd say-hello example a b c +Hello, friend! arguments: ("a" "b" "c") +@end example + +This, as you can see, is a fairly sophisticated way to say hello. +@xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more +info on actions. +@end deftp + @defvr {Scheme Variable} shepherd-root-service-type The service type for the Shepherd ``root service''---i.e., PID@tie{}1. |