diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 338 |
1 files changed, 269 insertions, 69 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index cd4a871fc8..0bfad4d57d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -119,6 +119,9 @@ Copyright @copyright{} 2023 Tanguy Le Carrour@* Copyright @copyright{} 2023 Zheng Junjie@* Copyright @copyright{} 2023 Brian Cully@* Copyright @copyright{} 2023 Felix Lechner@* +Copyright @copyright{} 2023 Foundation Devices, Inc.@* +Copyright @copyright{} 2023 Thomas Ieong@* +Copyright @copyright{} 2023 Saku Laesvuori@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -1796,7 +1799,7 @@ Setup}), or simply fail. When the build or substitution process remains silent for more than @var{seconds}, terminate it and report a build failure. -The default value is @code{0}, which disables the timeout. +The default value is @code{3600} (one hour). The value specified here can be overridden by clients (@pxref{Common Build Options, @option{--max-silent-time}}). @@ -1805,7 +1808,7 @@ Build Options, @option{--max-silent-time}}). Likewise, when the build or substitution process lasts for more than @var{seconds}, terminate it and report a build failure. -The default value is @code{0}, which disables the timeout. +The default value is 24 hours. The value specified here can be overridden by clients (@pxref{Common Build Options, @option{--timeout}}). @@ -4058,6 +4061,7 @@ guix-daemon}). It can also be disabled temporarily by passing the @node Getting Substitutes from Other Servers @subsection Getting Substitutes from Other Servers +@c Note: This section name appears in a hint printed by 'guix weather'. @cindex substitute servers, adding more Guix can look up and fetch substitutes from several servers. This is @@ -4157,6 +4161,21 @@ can list as many substitute servers as you like, with the caveat that substitute lookup can be slowed down if too many servers need to be contacted. +@quotation Troubleshooting +To diagnose problems, you can run @command{guix weather}. For example, +running: + +@example +guix weather coreutils +@end example + +@noindent +not only tells you which of the currently-configured servers has +substitutes for the @code{coreutils} package, it also reports whether +one of these servers is unauthorized. @xref{Invoking guix weather}, for +more information. +@end quotation + Note that there are also situations where one may want to add the URL of a substitute server @emph{without} authorizing its key. @xref{Substitute Authentication}, to understand this fine point. @@ -9585,6 +9604,20 @@ debugging information''), which roughly means that code is compiled with @code{-O2 -g}, as is the case for Autoconf-based packages by default. @end defvar +@defvar composer-build-system +This variable is exported by @code{(guix build-system composer)}. It +implements the build procedure for packages using +@url{https://getcomposer.org/, Composer}, the PHP package manager. + +It automatically adds the @code{php} package to the set of inputs. Which +package is used can be specified with the @code{#:php} parameter. + +The @code{#:test-target} parameter is used to control which script is run +for the tests. By default, the @code{test} script is run if it exists. If +the script does not exist, the build system will run @code{phpunit} from the +source directory, assuming there is a @file{phpunit.xml} file. +@end defvar + @defvar dune-build-system This variable is exported by @code{(guix build-system dune)}. It supports builds of packages using @uref{https://dune.build/, Dune}, a build @@ -12177,6 +12210,11 @@ This is like the form above, but referring explicitly to the @var{output} of @var{obj}---this is useful when @var{obj} produces multiple outputs (@pxref{Packages with Multiple Outputs}). +Sometimes a gexp unconditionally refers to the @code{"out"} output, but +the user of that gexp would still like to insert a reference to another +output. The @code{gexp-input} procedure aims to address that. +@xref{gexp-input}. + @item #+@var{obj} @itemx #+@var{obj}:output @itemx (ungexp-native @var{obj}) @@ -12289,10 +12327,9 @@ When @var{references-graphs} is true, it must be a list of tuples of one of the following forms: @example -(@var{file-name} @var{package}) -(@var{file-name} @var{package} @var{output}) -(@var{file-name} @var{derivation}) -(@var{file-name} @var{derivation} @var{output}) +(@var{file-name} @var{obj}) +(@var{file-name} @var{obj} @var{output}) +(@var{file-name} @var{gexp-input}) (@var{file-name} @var{store-item}) @end example @@ -12570,6 +12607,39 @@ The example above returns an object that corresponds to the i686 build of Coreutils, regardless of the current value of @code{%current-system}. @end defmac +@anchor{gexp-input} +@deffn {Procedure} gexp-input @var{obj} [@var{output}] [#:native? #f] +Return a @dfn{gexp input} record for the given @var{output} of file-like +object @var{obj}, with @code{#:native?} determining whether this is a +native reference (as with @code{ungexp-native}) or not. + +This procedure is helpful when you want to pass a reference to a +specific output of an object to some procedure that may not know about +that output. For example, assume you have this procedure, which takes +one file-like object: + +@lisp +(define (make-symlink target) + (computed-file "the-symlink" + #~(symlink #$target #$output))) +@end lisp + +Here @code{make-symlink} can only ever refer to the default output of +@var{target}---the @code{"out"} output (@pxref{Packages with Multiple +Outputs}). To have it refer to, say, the @code{"lib"} output of the +@code{hwloc} package, you can call it like so: + +@lisp +(make-symlink (gexp-input hwloc "lib")) +@end lisp + +You can also compose it like any other file-like object: + +@lisp +(make-symlink + (file-append (gexp-input hwloc "lib") "/lib/libhwloc.so")) +@end lisp +@end deffn Of course, in addition to gexps embedded in ``host'' code, there are also modules containing build tools. To make it clear that they are @@ -14533,6 +14603,26 @@ 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. +@end table + +@item composer +@cindex Composer +@cindex PHP +Import metadata from the @uref{https://getcomposer.org/, Composer} package +archive used by the PHP community, as in this example: + +@example +guix import composer phpunit/phpunit +@end example + +Additional options include: + +@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. @item --repo By default, packages are searched in the official OPAM repository. This option, which can be used more than once, lets you add other repositories @@ -16511,7 +16601,10 @@ up building packages by yourself (@pxref{Substitutes}). The specified servers so you can have an idea of whether you'll be grumpy today. It can sometimes be useful info as a user, but it is primarily useful to people running @command{guix publish} (@pxref{Invoking guix -publish}). +publish}). Sometimes substitutes @emph{are} available but they are not +authorized on your system; @command{guix weather} reports it so you can +authorize them if you want (@pxref{Getting Substitutes from Other +Servers}). @cindex statistics, for substitutes @cindex availability of substitutes @@ -16578,8 +16671,9 @@ The available options are listed below. @table @code @item --substitute-urls=@var{urls} @var{urls} is the space-separated list of substitute server URLs to -query. When this option is omitted, the default set of substitute -servers is queried. +query. When this option is omitted, the URLs specified with the +@option{--substitute-urls} option of @command{guix-daemon} are used or, +as a last resort, the default set of substitute URLs. @item --system=@var{system} @itemx -s @var{system} @@ -16773,6 +16867,7 @@ The available targets are: - aarch64-linux-gnu - arm-linux-gnueabihf + - avr - i586-pc-gnu - i686-linux-gnu - i686-w64-mingw32 @@ -19373,8 +19468,8 @@ few seconds when enough entropy is available and is only done once; you might want to turn it off for instance in a virtual machine that does not need it and where the extra boot time is a problem. -@item @code{max-silent-time} (default: @code{0}) -@itemx @code{timeout} (default: @code{0}) +@item @code{max-silent-time} (default: @code{3600}) +@itemx @code{timeout} (default: @code{(* 3600 24)}) The number of seconds of silence and the number of seconds of activity, respectively, after which a build process times out. A value of zero disables the timeout. @@ -19390,7 +19485,8 @@ and DNS-SD. @anchor{guix-configuration-build-machines} @item @code{build-machines} (default: @code{#f}) This field must be either @code{#f} or a list of gexps evaluating to a -@code{build-machine} record (@pxref{Daemon Offload Setup}). +@code{build-machine} record or to a list of @code{build-machine} records +(@pxref{Daemon Offload Setup}). When it is @code{#f}, the @file{/etc/guix/machines.scm} file is left untouched. Otherwise, the list of of gexps is written to @@ -19459,7 +19555,8 @@ A list of file-like objects where each element contains a public key. A list of strings where each element is a substitute URL. @item @code{build-machines} (default: @code{'()}) -A list of gexps that evaluate to @code{build-machine} records +A list of gexps that evaluate to @code{build-machine} records or to a list of +@code{build-machine} records. (@pxref{Daemon Offload Setup}). Using this field, a service may add new build machines to receive builds @@ -27628,6 +27725,66 @@ on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at @end table @end deftp +@subsubheading Rspamd Service +@cindex email +@cindex spam + +@defvar rspamd-service-type +This is the type of the @uref{https://rspamd.com/, Rspamd} filtering +system whose value should be a @code{rspamd-configuration}. +@end defvar + +@c %start of fragment + +@deftp {Data Type} rspamd-configuration +Available @code{rspamd-configuration} fields are: + +@table @asis +@item @code{package} (default: @code{rspamd}) (type: file-like) +The package that provides rspamd. + +@item @code{config-file} (default: @code{%default-rspamd-config-file}) (type: file-like) +File-like object of the configuration file to use. By default all +workers are enabled except fuzzy and they are binded to their usual +ports, e.g localhost:11334, localhost:11333 and so on + +@item @code{local.d-files} (default: @code{()}) (type: directory-tree) +Configuration files in local.d, provided as a list of two element lists +where the first element is the filename and the second one is a +file-like object. Settings in these files will be merged with the +defaults. + +@item @code{override.d-files} (default: @code{()}) (type: directory-tree) +Configuration files in override.d, provided as a list of two element +lists where the first element is the filename and the second one is a +file-like object. Settings in these files will override the defaults. + +@item @code{user} (default: @code{%default-rspamd-account}) (type: user-account) +The user to run rspamd as. + +@item @code{group} (default: @code{%default-rspamd-group}) (type: user-group) +The group to run rspamd as. + +@item @code{debug?} (default: @code{#f}) (type: boolean) +Force debug output. + +@item @code{insecure?} (default: @code{#f}) (type: boolean) +Ignore running workers as privileged users. + +@item @code{skip-template?} (default: @code{#f}) (type: boolean) +Do not apply Jinja templates. + +@item @code{shepherd-requirements} (default: @code{(loopback)}) (type: list-of-symbols) +This is a list of symbols naming Shepherd services that this service +will depend on. + +@end table + +@end deftp + + +@c %end of fragment + @node Messaging Services @subsection Messaging Services @@ -34019,6 +34176,9 @@ The Laminar package to use. @item @code{home-directory} (default: @code{"/var/lib/laminar"}) The directory for job configurations and run directories. +@item @code{supplementary-groups} (default: @code{()}) +Supplementary groups for the Laminar user account. + @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. @@ -35027,17 +35187,24 @@ services. @subsubheading Libvirt daemon @code{libvirtd} is the server side daemon component of the libvirt -virtualization management system. This daemon runs on host servers -and performs required management tasks for virtualized guests. +virtualization management system. This daemon runs on host servers and +performs required management tasks for virtualized guests. To connect +to the libvirt daemon as an unprivileged user, it must be added to the +@samp{libvirt} group, as shown in the example below. @defvar libvirt-service-type This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its value must be a @code{libvirt-configuration}. @lisp +(users (cons (user-account + (name "user") + (group "users") + (supplementary-groups '("libvirt" + "audio" "video" "wheel"))) + %base-user-accounts)) (service libvirt-service-type (libvirt-configuration - (unix-sock-group "libvirt") (tls-port "16555"))) @end lisp @end defvar @@ -35119,7 +35286,7 @@ UNIX domain socket group ownership. This can be used to allow a 'trusted' set of users access to management capabilities without becoming root. -Defaults to @samp{"root"}. +Defaults to @samp{"libvirt"}. @end deftypevr @@ -38619,58 +38786,6 @@ the coordinator database, and is used by the agent to authenticate. @end table @end deftp -The Guix Build Coordinator package contains a script to query an -instance of the Guix Data Service for derivations to build, and then -submit builds for those derivations to the coordinator. The service -type below assists in running this script. This is an additional tool -that may be useful when building derivations contained within an -instance of the Guix Data Service. - -@defvar guix-build-coordinator-queue-builds-service-type -Service type for the -guix-build-coordinator-queue-builds-from-guix-data-service script. Its -value must be a @code{guix-build-coordinator-queue-builds-configuration} -object. -@end defvar - -@deftp {Data Type} guix-build-coordinator-queue-builds-configuration -Data type representing the options to the queue builds from guix data -service script. - -@table @asis -@item @code{package} (default: @code{guix-build-coordinator}) -The Guix Build Coordinator package to use. - -@item @code{user} (default: @code{"guix-build-coordinator-queue-builds"}) -The system user to run the service as. - -@item @code{coordinator} (default: @code{"http://localhost:8746"}) -The URI to use when connecting to the coordinator. - -@item @code{systems} (default: @code{#f}) -The systems for which to fetch derivations to build. - -@item @code{systems-and-targets} (default: @code{#f}) -An association list of system and target pairs for which to fetch -derivations to build. - -@item @code{guix-data-service} (default: @code{"https://data.guix.gnu.org"}) -The Guix Data Service instance from which to query to find out about -derivations to build. - -@item @code{guix-data-service-build-server-id} (default: @code{#f}) -The Guix Data Service build server ID corresponding to the builds being -submitted. Providing this speeds up the submitting of builds as -derivations that have already been submitted can be skipped before -asking the coordinator to build them. - -@item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"}) -A file to record which commits have been processed, to avoid needlessly -processing them again if the service is restarted. - -@end table -@end deftp - @subsubheading Guix Data Service The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores and provides data about GNU Guix. This includes information about @@ -39609,6 +39724,9 @@ This must be a list of strings where each string has the form "TMPDIR=/tmp/dockerd") @end lisp +@item @code{config-file} (type: maybe-file-like) +JSON configuration file pass to @command{dockerd}. + @end table @end deftp @@ -44977,6 +45095,7 @@ sound support. @cindex PulseAudio, home service @cindex RTP, for PulseAudio +@subsubheading PulseAudio RTP Streaming Services The following services dynamically reconfigure the @uref{https://pulseaudio.org,PulseAudio sound server}: they let you @@ -45064,6 +45183,77 @@ Stopping the Shepherd service turns off broadcasting. This is the multicast address used by default by the two services above. @end defvar +@cindex PipeWire, home service +@subsubheading PipeWire Home Service + +@uref{https://pipewire.org, PipeWire} provides a low-latency, +graph-based audio and video processing service. In addition to its +native protocol, it can also be used as a replacement for both JACK and +PulseAudio. + +While PipeWire provides the media processing and API, it does not, +directly, know about devices such as sound cards, nor how you might want +to connect applications, hardware, and media processing filters. +Instead, PipeWire relies on a @dfn{session manager} to specify all these +relationships. While you may use any session manager you wish, for most +people the @url{https://pipewire.pages.freedesktop.org/wireplumber/, +WirePlumber} session manager, a reference implementation provided by the +PipeWire project itself, suffices, and that is the one +@code{home-pipewire-service-type} uses. + +PipeWire can be used as a replacement for PulseAudio by setting +@code{enable-pulseaudio?} to @code{#t} in +@code{home-pipewire-configuration}, so that existing PulseAudio clients +may use it without any further configuration. + +In addition, JACK clients may connect to PipeWire by using the +@command{pw-jack} program, which comes with PipeWire. Simply prefix the +command with @command{pw-jack} when you run it, and audio data should go +through PipeWire: + +@example +pw-jack mpv -ao=jack sound-file.wav +@end example + +For more information on PulseAudio emulation, see +@uref{https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio}, +for JACK, see +@uref{https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-JACK}. + +As PipeWire does not use @code{dbus} to start its services on demand +(as PulseAudio does), @code{home-pipewire-service-type} uses Shepherd +to start services when logged in, provisioning the @code{pipewire}, +@code{wireplumber}, and, if configured, @code{pipewire-pulseaudio} +services. @xref{Shepherd Home Service}. + +@defvar home-pipewire-service-type +This provides the service definition for @command{pipewire}, which will +run on login. Its value is a @code{home-pipewire-configuration} object. + +To start the service, add it to the @code{service} field of your +@code{home-environment}, such as: + +@lisp +(service home-pipewire-service-type) +@end lisp +@end defvar + +@deftp {Data Type} home-pipewire-configuration +Available @code{home-pipewire-configuration} fields are: + +@table @asis +@item @code{pipewire} (default: @code{pipewire}) (type: file-like) +The PipeWire package to use. + +@item @code{wireplumber} (default: @code{wireplumber}) (type: file-like) +The WirePlumber package to use. + +@item @code{enable-pulseaudio?} (default: @code{#t}) (type: boolean) +When true, enable PipeWire's PulseAudio emulation support, allowing +PulseAudio clients to use PipeWire transparently. +@end table +@end deftp + @node Mail Home Services @subsection Mail Home Services @@ -45802,6 +45992,11 @@ This optional string field is only relevant if the kernel is Linux. In that case, it corresponds to the ARCH variable used when building Linux, @code{"mips"} for instance. +@item @code{rust-target} (default: @code{#false}) +This optional string field is used to determine which rust target is best +supported by this platform. For example, the base level system targeted by +@code{armhf-linux} system is closest to @code{armv7-unknown-linux-gnueabihf}. + @item @code{glibc-dynamic-linker} This field is the name of the GNU C Library dynamic linker for the corresponding system, as a string. It can be @@ -45863,6 +46058,11 @@ Platform targeting x86 CPU running GNU/Hurd (also referred to as ``GNU''). @end defvar +@defvar avr +Platform targeting AVR CPUs without an operating system, with run-time support +from AVR Libc. +@end defvar + @node System Images @chapter Creating System Images |