diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 380 |
1 files changed, 357 insertions, 23 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index bf9dbaa726..8b97920f21 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -20,17 +20,19 @@ Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* -Copyright @copyright{} 2015, 2016 Leo Famulari@* +Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@* Copyright @copyright{} 2015, 2016 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016 Chris Marusich@* -Copyright @copyright{} 2016 Efraim Flashner@* +Copyright @copyright{} 2016, 2017 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016 ng0@* Copyright @copyright{} 2016 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* -Copyright @copyright{} 2017 Clément Lassieur +Copyright @copyright{} 2017 Clément Lassieur@* +Copyright @copyright{} 2017 Mathieu Othacehe@* +Copyright @copyright{} 2017 Federico Beffa Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -451,6 +453,7 @@ If your host distro uses the Upstart init system: @example # ln -s ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/ +# initctl reload-configuration # start guix-daemon @end example @@ -1685,6 +1688,20 @@ of packages: (list guile-2.0 "debug"))) @end example +@findex specification->package+output +In this example we have to know which modules define the @code{emacs} +and @code{guile-2.0} variables to provide the right +@code{use-package-modules} line, which can be cumbersome. We can +instead provide regular package specifications and let +@code{specification->package-output} look up the corresponding package +objects, like this: + +@example +(packages->manifest + (map (compose list specification->package+output) + '("emacs" "guile@@2.0" "guile@@2.0:debug"))) +@end example + @item --roll-back @cindex rolling back @cindex undoing transactions @@ -2321,7 +2338,9 @@ instance, when user @code{root} runs @command{guix pull}, this has no effect on the version of Guix that user @code{alice} sees, and vice versa@footnote{Under the hood, @command{guix pull} updates the @file{~/.config/guix/latest} symbolic link to point to the latest Guix, -and the @command{guix} command loads code from there.}. +and the @command{guix} command loads code from there. Currently, the +only way to roll back an invocation of @command{guix pull} is to +manually update this symlink to point to the previous Guix.}. The @command{guix pull} command is usually invoked with no arguments, but it supports the following options: @@ -2336,6 +2355,20 @@ Download the source tarball of Guix from @var{url}. By default, the tarball is taken from its canonical address at @code{gnu.org}, for the stable branch of Guix. +With some Git servers, this can be used to deploy any version of Guix. +For example, to download and deploy version 0.12.0 of Guix from the +canonical Git repo: + +@example +guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz +@end example + +It can also be used to deploy arbitrary Git revisions: + +@example +guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz +@end example + @item --bootstrap Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers. @@ -3261,6 +3294,49 @@ specified with the @code{#:glib} parameter. Both phases are executed after the @code{install} phase. @end defvr +@defvr {Scheme Variable} ocaml-build-system +This variable is exported by @code{(guix build-sytem ocaml)}. It implements +a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists +of choosing the correct set of commands to run for each package. OCaml +packages can expect many different commands to be run. This build system will +try some of them. + +When the package has a @file{setup.ml} file present at the top-level, it will +run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and +@code{ocaml setup.ml -install}. The build system will assume that this file +was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take +care of setting the prefix and enabling tests if they are not disabled. You +can pass configure and build flags with the @code{#:configure-flags} and +@code{#:build-flags}. The @code{#:test-flags} key can be passed to change the +set of flags used to enable tests. The @code{#:use-make?} key can be used to +bypass this system in the build and install phases. + +When the package has a @file{configure} file, it is assumed that it is a +hand-made configure script that requires a different argument format than +in the @code{gnu-build-system}. You can add more flags with the +@code{#:configure-flags} key. + +When the package has a @file{Makefile} file (or @code{#:use-make?} is +@code{#t}), it will be used and more flags can be passed to the build and +install phases with the @code{#:make-flags} key. + +Finally, some packages do not have these files and use a somewhat standard +location for its build system. In that case, the build system will run +@code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of +providing the path to the required findlib module. Additional flags can +be passed via the @code{#:build-flags} key. Install is taken care of by +@command{opam-installer}. In this case, the @code{opam} package must +be added to the @code{native-inputs} field of the package definition. + +Note that most OCaml packages assume they will be installed in the same +directory as OCaml, which is not what we want in guix. In particular, they +will install @file{.so} files in their module's directory, which is usually +fine because it is in the OCaml compiler directory. In guix though, these +libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This +variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where +@file{.so} libraries should be installed. +@end defvr + @defvr {Scheme Variable} python-build-system This variable is exported by @code{(guix build-system python)}. It implements the more or less standard build procedure used by Python @@ -3362,6 +3438,16 @@ Which Haskell compiler is used can be specified with the @code{#:haskell} parameter which defaults to @code{ghc}. @end defvr +@defvr {Scheme Variable} dub-build-system +This variable is exported by @code{(guix build-system dub)}. It +implements the Dub build procedure used by D packages, which +involves running @code{dub build} and @code{dub run}. +Installation is done by copying the files manually. + +Which D compiler is used can be specified with the @code{#:ldc} +parameter which defaults to @code{ldc}. +@end defvr + @defvr {Scheme Variable} emacs-build-system This variable is exported by @code{(guix build-system emacs)}. It implements an installation procedure similar to the packaging system @@ -4481,7 +4567,7 @@ guix build --quiet --keep-going \ @var{package-or-derivation} may be either the name of a package found in the software distribution such as @code{coreutils} or -@code{coreutils-8.20}, or a derivation such as +@code{coreutils@@8.20}, or a derivation such as @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a package with the corresponding name (and optionally version) is searched for among the GNU distribution modules (@pxref{Package Modules}). @@ -5265,6 +5351,34 @@ package name by an at-sign and a version number as in the following example: guix import hackage mtl@@2.1.3.1 @end example +@item stackage +@cindex stackage +The @code{stackage} importer is a wrapper around the @code{hackage} one. +It takes a package name, looks up the package version included in a +long-term support (LTS) @uref{https://www.stackage.org, Stackage} +release and uses the @code{hackage} importer to retrieve its metadata. +Note that it is up to you to select an LTS release compatible with the +GHC compiler used by Guix. + +Specific command-line options are: + +@table @code +@item --no-test-dependencies +@itemx -t +Do not include dependencies required only by the test suites. +@item --lts-version=@var{version} +@itemx -r @var{version} +@var{version} is the desired LTS release version. If omitted the latest +release is used. +@end table + +The command below imports metadata for the @code{HTTP} Haskell package +included in the LTS Stackage release version 7.18: + +@example +guix import stackage --lts-version=7.18 HTTP +@end example + @item elpa @cindex elpa Import metadata from an Emacs Lisp Package Archive (ELPA) package @@ -5429,6 +5543,8 @@ the updater for @uref{https://rubygems.org, RubyGems} packages. the updater for @uref{https://github.com, GitHub} packages. @item hackage the updater for @uref{https://hackage.haskell.org, Hackage} packages. +@item stackage +the updater for @uref{https://www.stackage.org, Stackage} packages. @item crate the updater for @uref{https://crates.io, Crates} packages. @end table @@ -5641,7 +5757,7 @@ single output for a package that could easily be split (@pxref{Packages with Multiple Outputs}). Such are the typical issues that @command{guix size} can highlight. -The command can be passed a package specification such as @code{gcc-4.8} +The command can be passed a package specification such as @code{gcc@@4.8} or @code{guile:debug}, or a file name in the store. Consider this example: @@ -6060,7 +6176,7 @@ guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' starts a shell with all the GuixSD base packages available. -The above commands only the use default output of the given packages. +The above commands only use the default output of the given packages. To select other outputs, two element tuples can be specified: @example @@ -6594,6 +6710,11 @@ ARMv7-A architecture with hard float, Thumb-2 and NEON, using the EABI hard-float application binary interface (ABI), and Linux-Libre kernel. +@item aarch64-linux +little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is +currently in an experimental stage, with limited support. See +@xref{Contributing}, for how to help! + @item mips64el-linux little-endian 64-bit MIPS processors, specifically the Loongson series, n32 ABI, and Linux-Libre kernel. @@ -6934,6 +7055,11 @@ the partition layout you want: cfdisk @end example +If your disk uses the GUID Partition Table (GPT) format and you plan to +install BIOS-based GRUB (which is the default), make sure a BIOS Boot +Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB +manual}). + 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 @@ -6983,6 +7109,26 @@ mkswap /dev/sda2 swapon /dev/sda2 @end example +Alternatively, you may use a swap file. For example, assuming that in +the new system you want to use the file @file{/swapfile} as a swap file, +you would run@footnote{This example will work for many types of file +systems (e.g., ext4). However, for copy-on-write file systems (e.g., +btrfs), the required steps may be different. For details, see the +manual pages for @command{mkswap} and @command{swapon}.}: + +@example +# This is 10 GiB of swap space. Adjust "count" to change the size. +dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 +# For security, make the file readable and writable only by root. +chmod 600 /mnt/swapfile +mkswap /mnt/swapfile +swapon /mnt/swapfile +@end example + +Note that if you have encrypted the root partition and created a swap +file in its file system as described above, then the encryption also +protects the swap file, just like any other file in that file system. + @node Proceeding with the Installation @subsection Proceeding with the Installation @@ -7085,8 +7231,8 @@ disk image, follow these steps: @enumerate @item -First, retrieve the GuixSD installation image as described previously -(@pxref{USB Stick Installation}). +First, retrieve and decompress the GuixSD installation image as +described previously (@pxref{USB Stick Installation}). @item Create a disk image that will hold the installed system. To make a @@ -7103,7 +7249,7 @@ Boot the USB installation image in an VM: @example qemu-system-x86_64 -m 1024 -smp 1 \ - -net default -net nic,model=virtio -boot menu=on \ + -net user -net nic,model=virtio -boot menu=on \ -drive file=guixsd.img \ -drive file=guixsd-usb-install-@value{VERSION}.@var{system} @end example @@ -7436,9 +7582,12 @@ A list of file systems. @xref{File Systems}. @item @code{swap-devices} (default: @code{'()}) @cindex swap devices -A list of strings identifying devices to be used for ``swap space'' -(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}). -For example, @code{'("/dev/sda3")}. +A list of strings identifying devices or files to be used for ``swap +space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference +Manual}). For example, @code{'("/dev/sda3")} or @code{'("/swapfile")}. +It is possible to specify a swap file in a file system on a mapped +device, provided that the necessary device mapping and file system are +also specified. @xref{Mapped Devices} and @ref{File Systems}. @item @code{users} (default: @code{%base-user-accounts}) @itemx @code{groups} (default: @var{%base-groups}) @@ -7781,6 +7930,13 @@ and use it as follows: (type luks-device-mapping)) @end example +@cindex swap encryption +It is also desirable to encrypt swap space, since swap space may contain +sensitive data. One way to accomplish that is to use a swap file in a +file system on a device mapped via LUKS encryption. In this way, the +swap file is encrypted because the entire device is encrypted. +@xref{Preparing for Installation,,Disk Partitioning}, for an example. + A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1} may be declared as follows: @@ -8162,6 +8318,50 @@ this: @end example @end defvr +@defvr {Scheme Variable} special-files-service-type +This is the service that sets up ``special files'' such as +@file{/bin/sh}; an instance of it is part of @code{%base-services}. + +The value associated with @code{special-files-service-type} services +must be a list of tuples where the first element is the ``special file'' +and the second element is its target. By default it is: + +@cindex @file{/bin/sh} +@cindex @file{sh}, in @file{/bin} +@example +`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) +@end example + +@cindex @file{/usr/bin/env} +@cindex @file{env}, in @file{/usr/bin} +If you want to add, say, @code{/usr/bin/env} to your system, you can +change it to: + +@example +`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) + ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) +@end example + +Since this is part of @code{%base-services}, you can use +@code{modify-services} to customize the set of special files +(@pxref{Service Reference, @code{modify-services}}). But the simple way +to add a special file is @i{via} the @code{extra-special-file} procedure +(see below.) +@end defvr + +@deffn {Scheme Procedure} extra-special-file @var{file} @var{target} +Use @var{target} as the ``special file'' @var{file}. + +For example, adding the following lines to the @code{services} field of +your operating system declaration leads to a @file{/usr/bin/env} +symlink: + +@example +(extra-special-file "/usr/bin/env" + (file-append coreutils "/bin/env")) +@end example +@end deffn + @deffn {Scheme Procedure} host-name-service @var{name} Return a service that sets the host name to @var{name}. @end deffn @@ -8708,11 +8908,21 @@ Return a service that runs @var{dhcp}, a Dynamic Host Configuration Protocol (DHCP) client, on all the non-loopback network interfaces. @end deffn +@defvr {Scheme Variable} static-networking-service-type +This is the type for statically-configured network interfaces. +@c TODO Document <static-networking> data structures. +@end defvr + @deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @ [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] Return a service that starts @var{interface} with address @var{ip}. If @var{netmask} is true, use it as the network mask. If @var{gateway} is true, it must be a string specifying the default network gateway. + +This procedure can be called several times, one for each network +interface of interest. Behind the scenes what it does is extend +@code{static-networking-service-type} with additional network interfaces +to handle. @end deffn @cindex wicd @@ -8730,11 +8940,41 @@ and @command{wicd-curses} user interfaces. @end deffn @cindex NetworkManager -@deffn {Scheme Procedure} network-manager-service @ - [#:network-manager @var{network-manager}] -Return a service that runs NetworkManager, a network connection manager -attempting to keep network connectivity active when available. -@end deffn + +@defvr {Scheme Variable} network-manager-service-type +This is the service type for the +@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager} +service. The value for this service type is a +@code{network-manager-configuration} record. +@end defvr + +@deftp {Data Type} network-manager-configuration +Data type representing the configuration of NetworkManager. + +@table @asis +@item @code{network-manager} (default: @code{network-manager}) +The NetworkManager package to use. + +@item @code{dns} (default: @code{"default"}) +Processing mode for DNS, which affects how NetworkManager uses the +@code{resolv.conf} configuration file. + +@table @samp +@item default +NetworkManager will update @code{resolv.conf} to reflect the nameservers +provided by currently active connections. + +@item dnsmasq +NetworkManager will run @code{dnsmasq} as a local caching nameserver, +using a "split DNS" configuration if you are connected to a VPN, and +then update @code{resolv.conf} to point to the local nameserver. + +@item none +NetworkManager will not modify @code{resolv.conf}. +@end table + +@end table +@end deftp @cindex Connman @deffn {Scheme Procedure} connman-service @ @@ -9029,6 +9269,23 @@ Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6 sockets. @end deffn +@deffn {Scheme Variable} openvswitch-service-type +This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} +service, whose value should be an @code{openvswitch-configuration} +object. +@end deffn + +@deftp {Data Type} openvswitch-configuration +Data type representing the configuration of Open vSwitch, a multilayer +virtual switch which is designed to enable massive network automation +through programmatic extension. + +@table @asis +@item @code{package} (default: @var{openvswitch}) +Package object of the Open vSwitch. + +@end table +@end deftp @node X Window @subsubsection X Window @@ -9224,6 +9481,7 @@ makes the good ol' XlockMore usable. @node Printing Services @subsubsection Printing Services +@cindex printer support with CUPS The @code{(gnu services cups)} module provides a Guix service definition for the CUPS printing service. To add printer support to a GuixSD system, add a @code{cups-service} to the operating system definition: @@ -9244,13 +9502,17 @@ as GNOME's printer configuration services. By default, configuring a CUPS service will generate a self-signed certificate if needed, for secure connections to the print server. -One way you might want to customize CUPS is to enable or disable the web -interface. You can do that directly, like this: +Suppose you want to enable the Web interface of CUPS and also add +support for HP printers @i{via} the @code{hplip} package. You can do +that directly, like this (you need to use the @code{(gnu packages cups)} +module): @example (service cups-service-type (cups-configuration - (web-interface? #f))) + (web-interface? #t) + (extensions + (list cups-filters hplip)))) @end example The available configuration parameters follow. Each parameter @@ -12295,6 +12557,7 @@ The @code{(gnu services web)} module provides the following service: [#:log-directory ``/var/log/nginx''] @ [#:run-directory ``/var/run/nginx''] @ [#:server-list '()] @ + [#:upstream-list '()] @ [#:config-file @code{#f}] Return a service that runs @var{nginx}, the nginx web server. @@ -12306,8 +12569,10 @@ arguments should match what is in @var{config-file} to ensure that the directories are created when the service is activated. As an alternative to using a @var{config-file}, @var{server-list} can be -used to specify the list of @dfn{server blocks} required on the host. For -this to work, use the default value for @var{config-file}. +used to specify the list of @dfn{server blocks} required on the host and +@var{upstream-list} can be used to specify a list of @dfn{upstream +blocks} to configure. For this to work, use the default value for +@var{config-file}. @end deffn @@ -12349,6 +12614,11 @@ default server for connections matching no other server. @item @code{root} (default: @code{"/srv/http"}) Root of the website nginx will serve. +@item @code{locations} (default: @code{'()}) +A list of @dfn{nginx-location-configuration} or +@dfn{nginx-named-location-configuration} records to use within this +server block. + @item @code{index} (default: @code{(list "index.html")}) Index files to look for when clients ask for a directory. If it cannot be found, Nginx will send the list of files in the directory. @@ -12725,6 +12995,63 @@ Defaults to @samp{#f}. @c %end of automatic openvpn-server documentation +@deftp {Data Type} nginx-upstream-configuration +Data type representing the configuration of an nginx @code{upstream} +block. This type has the following parameters: + +@table @asis +@item @code{name} +Name for this group of servers. + +@item @code{servers} +Specify the addresses of the servers in the group. The address can be +specified as a IP address (e.g. @samp{127.0.0.1}), domain name +(e.g. @samp{backend1.example.com}) or a path to a UNIX socket using the +prefix @samp{unix:}. For addresses using an IP address or domain name, +the default port is 80, and a different port can be specified +explicitly. + +@end table +@end deftp + +@deftp {Data Type} nginx-location-configuration +Data type representing the configuration of an nginx @code{location} +block. This type has the following parameters: + +@table @asis +@item @code{uri} +URI which this location block matches. + +@anchor{nginx-location-configuration body} +@item @code{body} +Body of the location block, specified as a string. This can contain many +configuration directives. For example, to pass requests to a upstream +server group defined using an @code{nginx-upstream-configuration} block, +the following directive would be specified in the body @samp{proxy_pass +http://upstream-name;}. + +@end table +@end deftp + +@deftp {Data Type} nginx-named-location-configuration +Data type representing the configuration of an nginx named location +block. Named location blocks are used for request redirection, and not +used for regular request processing. This type has the following +parameters: + +@table @asis +@item @code{name} +Name to identify this location block. + +@item @code{body} +@xref{nginx-location-configuration body}, as the body for named location +blocks can be used in a similar way to the +@code{nginx-location-configuration body}. One restriction is that the +body of a named location block cannot contain location blocks. + +@end table +@end deftp + @node Network File System @subsubsection Network File System @cindex NFS @@ -12909,6 +13236,9 @@ Cuirass jobs. Location of sqlite database which contains the build results and previously added specifications. +@item @code{port} (default: @code{8080}) +Port number used by the HTTP server. + @item @code{specifications} (default: @code{#~'()}) A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications, where a specification is an association list @@ -12923,6 +13253,10 @@ from source. @item @code{one-shot?} (default: @code{#f}) Only evaluate specifications and build derivations once. +@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 |