diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 305 |
1 files changed, 278 insertions, 27 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 841bc2a34f..f9b3ef0e55 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 @@ -96,6 +97,15 @@ Edition @value{EDITION} @* This document describes GNU Guix version @value{VERSION}, a functional package management tool written for the GNU system. +@c TRANSLATORS: You can replace the following paragraph with information on +@c how to join your own translation team and how to report issues with the +@c translation. +This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de +référence de GNU Guix}). If you would like to translate it in your native +language, consider joining the +@uref{https://translationproject.org/domain/guix-manual.html, Translation +Project}. + @menu * Introduction:: What is Guix about? * Installation:: Installing Guix. @@ -156,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 @@ -420,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. @@ -429,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 @@ -2775,12 +2786,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 @@ -3257,6 +3274,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 @@ -4027,6 +4045,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. @@ -4906,6 +4939,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 @@ -5339,7 +5378,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 @@ -5464,7 +5503,7 @@ denoting the target file. Here's an example: `(("hosts" ,(plain-file "hosts" "127.0.0.1 localhost")) ("bashrc" ,(plain-file "bashrc" - "alias ls='ls --color'")))) + "alias ls='ls --color=auto'")))) @end example This yields an @code{etc} directory containing these two files. @@ -5528,6 +5567,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 @@ -6370,6 +6460,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 @@ -6651,6 +6749,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 @@ -8329,7 +8433,7 @@ More and more system services are provided (@pxref{Services}), but some may be missing. @item -More than 6,500 packages are available, but you might +More than 7,500 packages are available, but you might occasionally find that a useful package is missing. @item @@ -8383,7 +8487,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 @@ -8399,7 +8503,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 @@ -8636,6 +8740,17 @@ must have the @code{esp} flag set. E.g., for @command{parted}: parted /dev/sda set 1 esp on @end example +@quotation Note +@vindex grub-bootloader +@vindex grub-efi-bootloader +Unsure whether to use EFI- or BIOS-based GRUB? If the directory +@file{/sys/firmware/efi} exists in the installation image, then you should +probably perform an EFI installation, using @code{grub-efi-bootloader}. +Otherwise you should use the BIOS-based GRUB, known as +@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on +bootloaders. +@end quotation + Once you are done partitioning the target hard disk drive, you have to create a file system on the relevant partition(s)@footnote{Currently GuixSD only supports ext4 and btrfs file systems. In particular, code @@ -8964,6 +9079,27 @@ Below we discuss the effect of some of the most important fields fields), and how to @dfn{instantiate} the operating system using @command{guix system}. +@unnumberedsubsubsec Bootloader + +@cindex legacy boot, on Intel machines +@cindex BIOS boot, on Intel machines +@cindex UEFI boot +@cindex EFI boot +The @code{bootloader} field describes the method that will be used to boot +your system. Machines based on Intel processors can boot in ``legacy'' BIOS +mode, as in the example above. However, more recent machines rely instead on +the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case, +the @code{bootloader} field should contain something along these lines: + +@example +(bootloader-configuration + (bootloader grub-efi-bootloader) + (target "/boot/efi")) +@end example + +@xref{Bootloader Configuration}, for more information on the available +configuration options. + @unnumberedsubsubsec Globally-Visible Packages @vindex %base-packages @@ -9074,8 +9210,7 @@ management, power management, and more, would look like this: @include os-config-desktop.texi @end lisp -@cindex UEFI -A graphical UEFI system with a choice of lightweight window managers +A graphical system with a choice of lightweight window managers instead of full-blown desktop environments would look like this: @lisp @@ -10789,6 +10924,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. @@ -15609,6 +15759,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 @@ -17574,10 +17757,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 @@ -20697,21 +20876,34 @@ The type of a bootloader configuration declaration. The bootloader to use, as a @code{bootloader} object. For now @code{grub-bootloader}, @code{grub-efi-bootloader}, @code{extlinux-bootloader} and @code{u-boot-bootloader} are supported. + +@vindex grub-efi-bootloader @code{grub-efi-bootloader} allows to boot on modern systems using the -@dfn{Unified Extensible Firmware Interface} (UEFI). +@dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should +use if the installation image contains a @file{/sys/firmware/efi} directory +when you boot it on your system. + +@vindex grub-bootloader +@code{grub-bootloader} allows you to boot in particular Intel-based machines +in ``legacy'' BIOS mode. +@cindex ARM, bootloaders +@cindex AArch64, bootloaders Available bootloaders are described in @code{(gnu bootloader @dots{})} -modules. +modules. In particular, @code{(gnu bootloader u-boot)} contains definitions +of bootloaders for a wide range of ARM and AArch64 systems, using the +@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. @item @code{target} This is a string denoting the target onto which to install the -bootloader. The exact interpretation depends on the bootloader in -question; for @code{grub-bootloader}, for example, it should be a device -name understood by the bootloader @command{installer} command, such as -@code{/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking -grub-install,,, grub, GNU GRUB Manual}). For -@code{grub-efi-bootloader}, it should be the path to a mounted EFI file -system. +bootloader. + +The interpretation depends on the bootloader in question. For +@code{grub-bootloader}, for example, it should be a device name understood by +the bootloader @command{installer} command, such as @code{/dev/sda} or +@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}). For +@code{grub-efi-bootloader}, it should be the mount point of the EFI file +system, usually @file{/boot/efi}. @item @code{menu-entries} (default: @code{()}) A possibly empty list of @code{menu-entry} objects (see below), denoting @@ -20736,7 +20928,7 @@ The output terminals used for the bootloader boot menu, as a list of symbols. GRUB accepts the values: @code{console}, @code{serial}, @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, @code{morse}, and @code{pkmodem}. This field -corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (@pxref{Simple +corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,, grub,GNU GRUB manual}). @item @code{terminal-inputs} (default: @code{'()}) @@ -20745,7 +20937,7 @@ symbols. For GRUB, the default is the native platform terminal as determined at run-time. GRUB accepts the values: @code{console}, @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and @code{usb_keyboard}. This field corresponds to the GRUB variable -GRUB_TERMINAL_INPUT (@pxref{Simple configuration,,, grub,GNU GRUB +@code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB manual}). @item @code{serial-unit} (default: @code{#f}) @@ -21270,7 +21462,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 @@ -21862,6 +22054,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: @@ -21879,6 +22082,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. |