diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 334 |
1 files changed, 255 insertions, 79 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index d1a15cb28b..1069a5d296 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -38,7 +38,7 @@ Copyright @copyright{} 2016, 2017 Nikita Gillmann@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* -Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@* +Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@* Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@* Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@* Copyright @copyright{} 2017 Federico Beffa@* @@ -87,6 +87,7 @@ Copyright @copyright{} 2020 Daniel Brooks@* Copyright @copyright{} 2020 John Soo@* Copyright @copyright{} 2020 Jonathan Brielmaier@* Copyright @copyright{} 2020 Edgar Vincent@* +Copyright @copyright{} 2021 Maxime Devos@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -342,7 +343,7 @@ Services * DNS Services:: DNS daemons. * VPN Services:: VPN daemons. * Network File System:: NFS related services. -* Continuous Integration:: The Cuirass service. +* Continuous Integration:: Cuirass and Laminar services. * Power Management Services:: Extending battery life. * Audio Services:: The MPD. * Virtualization Services:: Virtualization services. @@ -652,7 +653,7 @@ If that command fails because you do not have the required public key, then run this command to import it: @example -$ wget @value{OPENPGP-SIGNING-KEY-URL} \ +$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \ -qO - | gpg --import - @end example @@ -1428,7 +1429,7 @@ the Guix daemon. @code{guix_daemon_socket_t} isn’t actually used. None of the socket operations involve contexts that have anything to do with @code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label, -but it would be preferrable to define socket rules for only this label. +but it would be preferable to define socket rules for only this label. @item @code{guix gc} cannot access arbitrary links to profiles. By design, @@ -7297,64 +7298,94 @@ standards, GNU Coding Standards}). In a nutshell, packages using it are configured, built, and installed with the usual @code{./configure && make && make check && make install} command sequence. In practice, a few additional steps are often needed. -All these steps are split up in separate @dfn{phases}, -notably@footnote{Please see the @code{(guix build gnu-build-system)} -modules for more details about the build phases.}: +All these steps are split up in separate @dfn{phases}. +@xref{Build Phases}, for more info on build phases and ways to customize +them. + +In addition, this build system ensures that the ``standard'' environment +for GNU packages is available. This includes tools such as GCC, libc, +Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix +build-system gnu)} module for a complete list). We call these the +@dfn{implicit inputs} of a package, because package definitions do not +have to mention them. + +This build system supports a number of keyword arguments, which can be +passed @i{via} the @code{arguments} field of a package. Here are some +of the main parameters: @table @code -@item unpack -Unpack the source tarball, and change the current directory to the -extracted source tree. If the source is actually a directory, copy it -to the build tree, and enter that directory. +@item #:phases +This argument specifies build-side code that evaluates to an alist of +build phases. @xref{Build Phases}, for more information. -@item patch-source-shebangs -Patch shebangs encountered in source files so they refer to the right -store file names. For instance, this changes @code{#!/bin/sh} to -@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. +@item #:configure-flags +This is a list of flags (strings) passed to the @command{configure} +script. @xref{Defining Packages}, for an example. -@item configure -Run the @file{configure} script with a number of default options, such -as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified -by the @code{#:configure-flags} argument. +@item #:make-flags +This list of strings contains flags passed as arguments to +@command{make} invocations in the @code{build}, @code{check}, and +@code{install} phases. -@item build -Run @code{make} with the list of flags specified with -@code{#:make-flags}. If the @code{#:parallel-build?} argument is true -(the default), build with @code{make -j}. +@item #:out-of-source? +This Boolean, @code{#f} by default, indicates whether to run builds in a +build directory separate from the source tree. -@item check -Run @code{make check}, or some other target specified with -@code{#:test-target}, unless @code{#:tests? #f} is passed. If the -@code{#:parallel-tests?} argument is true (the default), run @code{make -check -j}. +When it is true, the @code{configure} phase creates a separate build +directory, changes to that directory, and runs the @code{configure} +script from there. This is useful for packages that require it, such as +@code{glibc}. -@item install -Run @code{make install} with the flags listed in @code{#:make-flags}. +@item #:tests? +This Boolean, @code{#t} by default, indicates whether the @code{check} +phase should run the package's test suite. -@item patch-shebangs -Patch shebangs on the installed executable files. +@item #:test-target +This string, @code{"check"} by default, gives the name of the makefile +target used by the @code{check} phase. -@item strip -Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} -is false), copying them to the @code{debug} output when available -(@pxref{Installing Debugging Files}). -@end table +@item #:parallel-build? +@itemx #:parallel-tests? +These Boolean values specify whether to build, respectively run the test +suite, in parallel, with the @code{-j} flag of @command{make}. When +they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is +the number specified as the @option{--cores} option of +@command{guix-daemon} or that of the @command{guix} client command +(@pxref{Common Build Options, @option{--cores}}). -@vindex %standard-phases -The build-side module @code{(guix build gnu-build-system)} defines -@code{%standard-phases} as the default list of build phases. -@code{%standard-phases} is a list of symbol/procedure pairs, where the -procedure implements the actual phase. +@cindex RUNPATH, validation +@item #:validate-runpath? +This Boolean, @code{#t} by default, determines whether to ``validate'' +the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well +as executables) previously installed by the @code{install} phase. -@xref{Build Phases}, for more info on build phases and ways to customize -them. +This validation step consists in making sure that all the shared +libraries needed by an ELF binaries, which are listed as +@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the +@code{DT_RUNPATH} entry of that binary. In other words, it ensures that +running or using those binaries will not result in a ``file not found'' +error at run time. @xref{Options, @option{-rpath},, ld, The GNU +Linker}, for more information on @code{RUNPATH}. -In addition, this build system ensures that the ``standard'' environment -for GNU packages is available. This includes tools such as GCC, libc, -Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix -build-system gnu)} module for a complete list). We call these the -@dfn{implicit inputs} of a package, because package definitions do not -have to mention them. +@item #:substitutable? +This Boolean, @code{#t} by default, tells whether the package outputs +should be substitutable---i.e., whether users should be able to obtain +substitutes for them instead of building locally (@pxref{Substitutes}). + +@item #:allowed-references +@itemx #:disallowed-references +When true, these arguments must be a list of dependencies that must not +appear among the references of the build results. If, upon build +completion, some of these references are retained, the build process +fails. + +This is useful to ensure that a package does not erroneously keep a +reference to some of it build-time inputs, in cases where doing so +would, for example, unnecessarily increase its size (@pxref{Invoking +guix size}). +@end table + +Most other build systems support these keyword arguments. @end defvr Other @code{<build-system>} objects are defined to support other @@ -7769,7 +7800,7 @@ after the wrapped library followed by @code{_jll.jl}. To add the binary path @code{_jll.jl} packages, you need to patch the files under @file{src/wrappers/}, replacing the call to the macro -@code{JLLWrappers.@@generate_wrapper_header}, adding as a secound +@code{JLLWrappers.@@generate_wrapper_header}, adding as a second argument containing the store path the binary. As an example, in the MbedTLS Julia package, we add a build phase @@ -8249,16 +8280,53 @@ exception is the ``bare-bones'' @code{trivial-build-system} (@pxref{Build Systems}). As discussed in the previous section, those build systems provide a -standard list of phases. For @code{gnu-build-system}, the standard -phases include an @code{unpack} phase to unpack the source code tarball, -a @command{configure} phase to run @code{./configure}, a @code{build} -phase to run @command{make}, and (among others) an @code{install} phase -to run @command{make install}; @pxref{Build Systems}, for a more -detailed view of these phases. Likewise, @code{cmake-build-system} -inherits these phases, but its @code{configure} phase runs -@command{cmake} instead of @command{./configure}. Other build systems, -such as @code{python-build-system}, have a wholly different list of -standard phases. All this code runs on the @dfn{build side}: it is +standard list of phases. For @code{gnu-build-system}, the main build +phases are the following: + +@table @code +@item unpack +Unpack the source tarball, and change the current directory to the +extracted source tree. If the source is actually a directory, copy it +to the build tree, and enter that directory. + +@item patch-source-shebangs +Patch shebangs encountered in source files so they refer to the right +store file names. For instance, this changes @code{#!/bin/sh} to +@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. + +@item configure +Run the @file{configure} script with a number of default options, such +as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified +by the @code{#:configure-flags} argument. + +@item build +Run @code{make} with the list of flags specified with +@code{#:make-flags}. If the @code{#:parallel-build?} argument is true +(the default), build with @code{make -j}. + +@item check +Run @code{make check}, or some other target specified with +@code{#:test-target}, unless @code{#:tests? #f} is passed. If the +@code{#:parallel-tests?} argument is true (the default), run @code{make +check -j}. + +@item install +Run @code{make install} with the flags listed in @code{#:make-flags}. + +@item patch-shebangs +Patch shebangs on the installed executable files. + +@item strip +Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} +is false), copying them to the @code{debug} output when available +(@pxref{Installing Debugging Files}). +@end table + +Other build systems have similar phases, with some variations. For +example, @code{cmake-build-system} has same-named phases but its +@code{configure} phases runs @code{cmake} instead of @code{./configure}. +Others, such as @code{python-build-system}, have a wholly different list +of standard phases. All this code runs on the @dfn{build side}: it is evaluated when you actually build the package, in a dedicated build process spawned by the build daemon (@pxref{Invoking guix-daemon}). @@ -8269,6 +8337,7 @@ is a procedure that accepts an arbitrary number of arguments. By convention, those procedures receive information about the build in the form of @dfn{keyword parameters}, which they can use or ignore. +@vindex %standard-phases For example, here is how @code{(guix build gnu-build-system)} defines @code{%standard-phases}, the variable holding its alist of build phases@footnote{We present a simplified view of those build phases, but @@ -11553,13 +11622,13 @@ Select the given repository (a repository name). Possible values include: Import metadata for a Go module using @uref{https://proxy.golang.org, proxy.golang.org}. -This importer is highly experimental. See the source code for more info -about the current state. - @example guix import go gopkg.in/yaml.v2 @end example +It is possible to use a package specification with a @code{@@VERSION} +suffix to import a specific version. + Additional options include: @table @code @@ -11568,6 +11637,14 @@ Additional options include: Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix. +@item --pin-versions +When using this option, the importer preserves the exact versions of the +Go modules dependencies instead of using their latest available +versions. This can be useful when attempting to import packages that +recursively depend on former versions of themselves to build. When +using this mode, the symbol of the package is made by appending the +version to its name, so that multiple versions of the same package can +coexist. @end table @end table @@ -13510,6 +13587,14 @@ following expression returns a list that contains all the services in %desktop-services) @end lisp +Alternatively, the @code{modify-services} macro can be used: + +@lisp +(modify-services %desktop-services + (delete avahi-service-type)) +@end lisp + + @unnumberedsubsec Instantiating the System Assuming the @code{operating-system} declaration @@ -14820,7 +14905,7 @@ declaration. * DNS Services:: DNS daemons. * VPN Services:: VPN daemons. * Network File System:: NFS related services. -* Continuous Integration:: The Cuirass service. +* Continuous Integration:: Cuirass and Laminar services. * Power Management Services:: Extending battery life. * Audio Services:: The MPD. * Virtualization Services:: Virtualization services. @@ -16417,7 +16502,7 @@ netfilter project that aims to replace the existing iptables, ip6tables, arptables and ebtables framework. It provides a new packet filtering framework, a new user-space utility @command{nft}, and a compatibility layer for iptables. This service comes with a default ruleset -@code{%default-nftables-ruleset} that rejecting all incomming connections +@code{%default-nftables-ruleset} that rejecting all incoming connections except those to the ssh port 22. To use it, simply write: @lisp @@ -16820,7 +16905,7 @@ Data type representing the configuration for @code{syncthing-service-type}. List of command-line arguments passing to @code{syncthing} binary. @item @code{logflags} (default: @var{0}) -Sum of loging flags, see +Sum of logging flags, see @uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}. @item @code{user} (default: @var{#f}) @@ -17490,6 +17575,37 @@ address, delete everything except these options: @end table @end deftp +@cindex IPFS +@defvr {Scheme Variable} ipfs-service-type +The service type for connecting to the @uref{https://ipfs.io,IPFS network}, +a global, versioned, peer-to-peer file system. Pass it a +@code{ipfs-configuration} to change the ports used for the gateway and API. + +Here's an example configuration, using some non-standard ports: + +@lisp +(service ipfs-service-type + (ipfs-configuration + (gateway "/ip4/127.0.0.1/tcp/8880") + (api "/ip4/127.0.0.1/tcp/8881"))) +@end lisp +@end defvr + +@deftp {Data Type} ipfs-configuration +Data type representing the configuration of IPFS. + +@table @asis +@item @code{package} (default: @code{go-ipfs}) +Package object of IPFS. + +@item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"}) +Address of the gateway, in ‘multiaddress’ format. + +@item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"}) +Address of the API endpoint, in ‘multiaddress’ format. +@end table +@end deftp + @cindex keepalived @deffn {Scheme Variable} keepalived-service-type This is the type for the @uref{https://www.keepalived.org/, Keepalived} @@ -17779,9 +17895,8 @@ and tty8. (service slim-service-type (slim-configuration (display ":1") (vt "vt8"))) - (remove (lambda (service) - (eq? (service-kind service) gdm-service-type)) - %desktop-services)))) + (modify-services %desktop-services + (delete gdm-service-type))))) @end lisp @end defvr @@ -19715,12 +19830,15 @@ configuration. @item @code{ident-file} (default: @code{%default-postgres-ident}) Filename or G-expression for the user name mapping configuration. -@item @code{socket-directory} (default: @code{"/var/run/postgresql"}) +@item @code{socket-directory} (default: @code{#false}) Specifies the directory of the Unix-domain socket(s) on which PostgreSQL -is to listen for connections from client applications. If set to -@code{#false} PostgreSQL does not listen on any Unix-domain sockets, in +is to listen for connections from client applications. If set to +@code{""} PostgreSQL does not listen on any Unix-domain sockets, in which case only TCP/IP sockets can be used to connect to the server. +By default, the @code{#false} value means the PostgreSQL default value +will be used, which is currently @samp{/tmp}. + @item @code{extra-config} (default: @code{'()}) List of additional keys and values to include in the PostgreSQL config file. Each entry in the list should be a list where the first element @@ -25905,7 +26023,7 @@ this amount of time. After this period, resolvers will invalidate their cache and check again that it still exists. @item @code{nx} (default: @code{3600}) -Default TTL of inexistant records. This delay is usually short because you want +Default TTL of inexistent records. This delay is usually short because you want your new domains to reach everyone quickly. @end table @@ -27329,6 +27447,64 @@ the store items being published. @end table @end deftp +@subsubheading Laminar + +@uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular +Continuous Integration service. It doesn't have a configuration web UI +instead uses version-controllable configuration files and scripts. + +Laminar encourages the use of existing tools such as bash and cron +instead of reinventing them. + +@defvr {Scheme Procedure} laminar-service-type +The type of the Laminar service. Its value must be a +@code{laminar-configuration} object, as described below. + +All configuration values have defaults, a minimal configuration to get +Laminar running is shown below. By default, the web interface is +available on port 8080. + +@lisp +(service laminar-service-type) +@end lisp +@end defvr + +@deftp {Data Type} laminar-configuration +Data type representing the configuration of Laminar. + +@table @asis +@item @code{laminar} (default: @code{laminar}) +The Laminar package to use. + +@item @code{home-directory} (default: @code{"/var/lib/laminar"}) +The directory for job configurations and run directories. + +@item @code{bind-http} (default: @code{"*:8080"}) +The interface/port or unix socket on which laminard should listen for +incoming connections to the web frontend. + +@item @code{bind-rpc} (default: @code{"unix-abstract:laminar"}) +The interface/port or unix socket on which laminard should listen for +incoming commands such as build triggers. + +@item @code{title} (default: @code{"Laminar"}) +The page title to show in the web frontend. + +@item @code{keep-rundirs} (default: @code{0}) +Set to an integer defining how many rundirs to keep per job. The +lowest-numbered ones will be deleted. The default is 0, meaning all run +dirs will be immediately deleted. + +@item @code{archive-url} (default: @code{#f}) +The web frontend served by laminard will use this URL to form links to +artefacts archived jobs. + +@item @code{base-url} (default: @code{#f}) +Base URL to use for links to laminar itself. + +@end table +@end deftp + @node Power Management Services @subsection Power Management Services @@ -31048,7 +31224,7 @@ coordinator. @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth Data type representing an agent authenticating with a coordinator via a -dyanmic auth token and agent name. +dynamic auth token and agent name. @table @asis @item @code{agent-name} @@ -31065,7 +31241,7 @@ database, and is used by the agent to authenticate. @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file Data type representing an agent authenticating with a coordinator via a -dyanmic auth token read from a file and agent name. +dynamic auth token read from a file and agent name. @table @asis @item @code{agent-name} @@ -33463,7 +33639,7 @@ $(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-: To connect to the VM you can run @example -ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 +ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost @end example The @command{-p} tells @command{ssh} the port you want to connect to. @@ -34219,7 +34395,7 @@ This service represents PID@tie{}1. @cindex man pages @cindex manual pages In most cases packages installed with Guix come with documentation. -There are two main documentation formats: ``Info'', a browseable +There are two main documentation formats: ``Info'', a browsable hypertext format used for GNU software, and ``manual pages'' (or ``man pages''), the linear documentation format traditionally found on Unix. Info manuals are accessed with the @command{info} command or with Emacs, @@ -34629,7 +34805,7 @@ traditional bootstrap of the rest of the Guix System. The only significant binary bootstrap seeds that remain@footnote{ Ignoring the 68KB @code{mescc-tools}; that will be removed later, -together with @code{mes}.} are a Scheme intepreter and a Scheme +together with @code{mes}.} are a Scheme interpreter and a Scheme compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the static binaries for @file{bash}, @code{tar}, and @code{xz} that are used to get Guile running.}. |