diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 661 |
1 files changed, 211 insertions, 450 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index acfe60b47a..3f5d4e7f0d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -125,6 +125,8 @@ Copyright @copyright{} 2023 Saku Laesvuori@* Copyright @copyright{} 2023 Graham James Addis@* Copyright @copyright{} 2023 Tomas Volf@* Copyright @copyright{} 2024 Herman Rimm@* +Copyright @copyright{} 2024 Matthew Trzcinski@* +Copyright @copyright{} 2024 Richard Sent@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -227,8 +229,6 @@ Introduction Installation * Binary Installation:: Getting Guix running in no time! -* Requirements:: Software needed to build and run Guix. -* Running the Test Suite:: Testing Guix. * Setting Up the Daemon:: Preparing the build daemon's environment. * Invoking guix-daemon:: Running the build daemon. * Application Setup:: Application-specific setup. @@ -358,7 +358,7 @@ Foreign Architectures System Configuration -* Getting Started with the System:: Your first steps. +* Getting Started with the System:: Your first steps. * Using the Configuration System:: Customizing your GNU system. * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. @@ -691,19 +691,20 @@ to join! @xref{Contributing}, for information about how you can help. @chapter Installation @cindex installing Guix +@cindex foreign distro +@cindex Guix System +You can install the package management tool Guix on top of an existing +GNU/Linux or GNU/Hurd system@footnote{Hurd support is currently +limited.}, referred to as a @dfn{foreign distro}. If, instead, you want +to install the complete, standalone GNU system distribution, +@dfn{Guix@tie{}System}, @pxref{System Installation}. This section is +concerned only with the installation of Guix on a foreign distro. -@quotation Note -We recommend the use of this -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script} to install Guix on top of a running GNU/Linux system, -thereafter called a @dfn{foreign distro}@footnote{This section is concerned -with the installation of the package manager, which can be done on top of a -running GNU/Linux system. If, instead, you want to install the complete GNU -operating system, @pxref{System Installation}.}. @xref{Binary -Installation}, for more information. +@quotation Important +This section only applies to systems without Guix. Following it for +existing Guix installations will overwrite important system files. @end quotation -@cindex foreign distro @cindex directories related to foreign distro When installed on a foreign distro, GNU@tie{}Guix complements the available tools without interference. Its data lives exclusively in two directories, @@ -713,15 +714,8 @@ such as @file{/etc}, are left untouched. Once installed, Guix can be updated by running @command{guix pull} (@pxref{Invoking guix pull}). -If you prefer to perform the installation steps manually or want to tweak -them, you may find the following subsections useful. They describe the -software requirements of Guix, as well as how to install it manually and get -ready to use it. - @menu * Binary Installation:: Getting Guix running in no time! -* Requirements:: Software needed to build and run Guix. -* Running the Test Suite:: Testing Guix. * Setting Up the Daemon:: Preparing the build daemon's environment. * Invoking guix-daemon:: Running the build daemon. * Application Setup:: Application-specific setup. @@ -735,226 +729,69 @@ ready to use it. @cindex installer script This section describes how to install Guix from a self-contained tarball providing binaries for Guix and for all its dependencies. This is often -quicker than installing from source, which is described in the next -sections. Binary installation requires a system using a Hurd or Linux -kernel; the GNU@tie{}tar and Xz commands must also be available. +quicker than installing from source, described later (@pxref{Building +from Git}). @quotation Important This section only applies to systems without Guix. Following it for existing Guix installations will overwrite important system files. +@end quotation -@c Note duplicated from the ``Installation'' node. -We recommend the use of this -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script}. The script automates the download, installation, and -initial configuration steps described below. It should be run as the root -user. As root, you can thus run this: - -@example -cd /tmp -wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh -chmod +x guix-install.sh -./guix-install.sh -@end example - -The script automates the download, installation, and initial -configuration of Guix, interactively offering various configuration -options. - -@cindex uninstalling Guix -@cindex uninstallation, of Guix -Should you eventually want to uninstall Guix, run the same script with -the @option{--uninstall} flag: - -@example -./guix-install.sh --uninstall -@end example - -With @option{--uninstall}, the script irreversibly deletes all the Guix -files, configuration, and services. +Some GNU/Linux distributions, such as Debian, Ubuntu, and openSUSE +provide Guix through their own package managers. The version of Guix +may be older than @value{VERSION} but you can update it afterwards by +running @samp{guix pull}. -If you're running Debian or a derivative such as Ubuntu, you can instead -install the package (it might be a version older than @value{VERSION} -but you can update it afterwards by running @samp{guix pull}): +For Debian or a derivative such as Ubuntu, call: @example sudo apt install guix @end example -Likewise on openSUSE: +Likewise, on openSUSE: @example sudo zypper install guix @end example -When you're done, @pxref{Application Setup} for extra configuration you -might need, and @ref{Getting Started} for your first steps! -@end quotation - -Installing goes along these lines: - -@enumerate -@item -@cindex downloading Guix binary -Download the binary tarball from -@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz}, -where @code{x86_64-linux} can be replaced with @code{i686-linux} for an -@code{i686} (32-bits) machine already running the kernel Linux, and so on -(@pxref{GNU Distribution}). - -@c The following is somewhat duplicated in ``System Installation''. -Make sure to download the associated @file{.sig} file and to verify the -authenticity of the tarball against it, along these lines: - -@example -$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig -$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig -@end example - -If that command fails because you do not have the required public key, -then run this command to import it: +The Guix project also provides a shell script, @file{guix-install.sh}, +which automates the binary installation process without use of a foreign +distro package +manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}. +Use of @file{guix-install.sh} requires Bash, GnuPG, GNU@tie{}tar, wget, +and Xz. -@example -$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \ - -qO - | gpg --import - -@end example +The script guides you through the following: -@noindent -and rerun the @code{gpg --verify} command. - -Take note that a warning like ``This key is not certified with a trusted -signature!'' is normal. +@itemize +@item Downloading and extracting the binary tarball +@item Setting up the build daemon +@item Making the ‘guix’ command available to non-root users +@item Configuring substitute servers +@end itemize -@c end authentication part - -@item -Now, you need to become the @code{root} user. Depending on your distribution, -you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run: +As root, run: @example # cd /tmp -# tar --warning=no-timestamp -xf \ - /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz -# mv var/guix /var/ && mv gnu / -@end example - -This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}. -The latter contains a ready-to-use profile for @code{root} (see next -step). - -Do @emph{not} unpack the tarball on a working Guix system since that -would overwrite its own essential files. - -The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does -not emit warnings about ``implausibly old time stamps'' (such -warnings were triggered by GNU@tie{}tar 1.26 and older; recent -versions are fine). -They stem from the fact that all the -files in the archive have their modification time set to 1 (which -means January 1st, 1970). This is done on purpose to make sure the -archive content is independent of its creation time, thus making it -reproducible. - -@item -Make the profile available under @file{~root/.config/guix/current}, which is -where @command{guix pull} will install updates (@pxref{Invoking guix pull}): - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -Source @file{etc/profile} to augment @env{PATH} and other relevant -environment variables: - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Create the group and user accounts for build users as explained below -(@pxref{Build Environment Setup}). - -@item -Run the daemon, and set it to automatically start on boot. - -If your host distro uses the systemd init system, this can be achieved -with these commands: - -@c Versions of systemd that supported symlinked service files are not -@c yet widely deployed, so we should suggest that users copy the service -@c files into place. -@c -@c See this thread for more information: -@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html - -@example -# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \ - ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ - /etc/systemd/system/ -# systemctl enable --now gnu-store.mount guix-daemon -@end example - -You may also want to arrange for @command{guix gc} to run periodically: - -@example -# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \ - ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \ - /etc/systemd/system/ -# systemctl enable --now guix-gc.timer -@end example - -You may want to edit @file{guix-gc.service} to adjust the command line -options to fit your needs (@pxref{Invoking guix gc}). - -If your host distro uses the Upstart init system: - -@example -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -Otherwise, you can still start the daemon manually with: - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Make the @command{guix} command available to other users on the machine, -for instance with: - -@example -# mkdir -p /usr/local/bin -# cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix +# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh +# chmod +x guix-install.sh +# ./guix-install.sh @end example -It is also a good idea to make the Info version of this manual available -there: - -@example -# mkdir -p /usr/local/share/info -# cd /usr/local/share/info -# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ; - do ln -s $i ; done -@end example - -That way, assuming @file{/usr/local/share/info} is in the search path, -running @command{info guix} will open this manual (@pxref{Other Info -Directories,,, texinfo, GNU Texinfo}, for more details on changing the -Info search path). +@quotation Note +By default, @file{guix-install.sh} will configure Guix to download +pre-built package binaries, called @dfn{substitutes} +(@pxref{Substitutes}), from the project's build farms. If you choose +not to permit this, Guix will build @emph{everything} from source, +making each installation and upgrade very expensive. @xref{On Trusting +Binaries} for a discussion of why you may want to build packages from +source. -@item @cindex substitutes, authorization thereof To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, -@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}), -authorize them: +@code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you must authorize them. +For example, @example # guix archive --authorize < \ @@ -962,28 +799,13 @@ authorize them: # guix archive --authorize < \ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub @end example - -@quotation Note -If you do not enable substitutes, Guix will end up building -@emph{everything} from source on your machine, making each installation -and upgrade very expensive. @xref{On Trusting Binaries}, for a -discussion of reasons why one might want do disable substitutes. @end quotation -@item -Each user may need to perform a few additional steps to make their Guix -environment ready for use, @pxref{Application Setup}. -@end enumerate - -Voilà, the installation is complete! - -You can confirm that Guix is working by installing a sample package into -the root profile: - -@example -# guix install hello -@end example +When you're done installing Guix, @pxref{Application Setup} for extra +configuration you might need, and @ref{Getting Started} for your first +steps! +@quotation Note The binary installation tarball can be (re)produced and verified simply by running the following command in the Guix source tree: @@ -1000,200 +822,19 @@ guix pack -s @var{system} --localstatedir \ @end example @xref{Invoking guix pack}, for more info on this handy tool. +@end quotation -@node Requirements -@section Requirements - -This section lists requirements when building Guix from source. The -build procedure for Guix is the same as for other GNU software, and is -not covered here. Please see the files @file{README} and @file{INSTALL} -in the Guix source tree for additional details. - -@cindex official website -GNU Guix is available for download from its website at -@url{https://www.gnu.org/software/guix/}. - -GNU Guix depends on the following packages: - -@itemize -@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x, -version 3.0.3 or later; -@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version -0.1.0 or later; -@item -@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile -Preparations, how to install the GnuTLS bindings for Guile,, -gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to -@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS -until version 3.7.8 included.}; -@item -@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0 -or later; -@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib}, -version 0.1.0 or later; -@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib}; -@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi}; -@item -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0 -or later; -@item @uref{https://git-scm.com, Git} (yes, both!); -@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} -4.3.0 or later; -@item @url{https://www.gnu.org/software/make/, GNU Make}. -@end itemize - -The following dependencies are optional: - -@itemize -@item -@c Note: We need at least 0.13.0 for #:nodelay. -Support for build offloading (@pxref{Daemon Offload Setup}) and -@command{guix copy} (@pxref{Invoking guix copy}) depends on -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, -version 0.13.0 or later. - -@item -@uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd -compression and decompression in @command{guix publish} and for -substitutes (@pxref{Invoking guix publish}). - -@item -@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for -the @code{crate} importer (@pxref{Invoking guix import}). - -@item -@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for -the @code{go} importer (@pxref{Invoking guix import}) and for some of -the ``updaters'' (@pxref{Invoking guix refresh}). - -@item -When @url{http://www.bzip.org, libbz2} is available, -@command{guix-daemon} can use it to compress build logs. -@end itemize - -Unless @option{--disable-daemon} was passed to @command{configure}, the -following packages are also needed: - -@itemize -@item @url{https://gnupg.org/, GNU libgcrypt}; -@item @url{https://sqlite.org, SQLite 3}; -@item @url{https://gcc.gnu.org, GCC's g++}, with support for the -C++11 standard. -@end itemize - -@cindex state directory -@cindex localstatedir -@cindex system configuration directory -@cindex sysconfdir -When configuring Guix on a system that already has a Guix installation, -be sure to specify the same state directory as the existing installation -using the @option{--localstatedir} option of the @command{configure} -script (@pxref{Directory Variables, @code{localstatedir},, standards, -GNU Coding Standards}). Usually, this @var{localstatedir} option is set -to the value @file{/var}. The @command{configure} script protects -against unintended misconfiguration of @var{localstatedir} so you do not -inadvertently corrupt your store (@pxref{The Store}). The configuration -directory should also be configured by setting the @option{--sysconfdir} -option to the @file{/etc} value, which is the location used by Guix to -store for example the access control list of authorized machines and the -definition of offload machines. - -@node Running the Test Suite -@section Running the Test Suite - -@cindex test suite -After a successful @command{configure} and @code{make} run, it is a good -idea to run the test suite. It can help catch issues with the setup or -environment, or bugs in Guix itself---and really, reporting test -failures is a good way to help improve the software. To run the test -suite, type: - -@example -make check -@end example - -Test cases can run in parallel: you can use the @code{-j} option of -GNU@tie{}make to speed things up. The first run may take a few minutes -on a recent machine; subsequent runs will be faster because the store -that is created for test purposes will already have various things in -cache. - -It is also possible to run a subset of the tests by defining the -@code{TESTS} makefile variable as in this example: - -@example -make check TESTS="tests/store.scm tests/cpio.scm" -@end example - -By default, tests results are displayed at a file level. In order to -see the details of every individual test cases, it is possible to define -the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example: - -@example -make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" -@end example - -The underlying SRFI 64 custom Automake test driver used for the 'check' -test suite (located at @file{build-aux/test-driver.scm}) also allows -selecting which test cases to run at a finer level, via its -@option{--select} and @option{--exclude} options. Here's an example, to -run all the test cases from the @file{tests/packages.scm} test file -whose names start with ``transaction-upgrade-entry'': - -@example -export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry" -make check TESTS="tests/packages.scm" -@end example - -Those wishing to inspect the results of failed tests directly from the -command line can add the @option{--errors-only=yes} option to the -@code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE} -Automake makefile variable, as in: - -@example -make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1 -@end example - -The @option{--show-duration=yes} option can be used to print the -duration of the individual test cases, when used in combination with -@option{--brief=no}: - -@example -make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes" -@end example - -@xref{Parallel Test Harness,,,automake,GNU Automake} for more -information about the Automake Parallel Test Harness. - -Upon failure, please email @email{bug-guix@@gnu.org} and attach the -@file{test-suite.log} file. Please specify the Guix version being used -as well as version numbers of the dependencies (@pxref{Requirements}) in -your message. - -Guix also comes with a whole-system test suite that tests complete -Guix System instances. It can only run on systems where -Guix is already installed, using: - -@example -make check-system -@end example - -@noindent -or, again, by defining @code{TESTS} to select a subset of tests to run: +@cindex uninstalling Guix +@cindex uninstallation, of Guix +Should you eventually want to uninstall Guix, run the same script with +the @option{--uninstall} flag: @example -make check-system TESTS="basic mcron" +./guix-install.sh --uninstall @end example -These system tests are defined in the @code{(gnu tests @dots{})} -modules. They work by running the operating systems under test with -lightweight instrumentation in a virtual machine (VM). They can be -computationally intensive or rather cheap, depending on whether -substitutes are available for their dependencies (@pxref{Substitutes}). -Some of them require a lot of storage space to hold VM images. - -Again in case of test failures, please send @email{bug-guix@@gnu.org} -all the details. +With @option{--uninstall}, the script irreversibly deletes all the Guix +files, configuration, and services. @node Setting Up the Daemon @section Setting Up the Daemon @@ -1208,8 +849,8 @@ goes through the daemon. For instance, command-line tools such as daemon (@i{via} remote procedure calls) to instruct it what to do. The following sections explain how to prepare the build daemon's -environment. See also @ref{Substitutes}, for information on how to allow -the daemon to download pre-built binaries. +environment. @xref{Substitutes} for how to allow the daemon to download +pre-built binaries. @menu * Build Environment Setup:: Preparing the isolated build environment. @@ -2908,7 +2549,7 @@ This builds a new system @dfn{generation} with the latest packages and services. Now, @pxref{Getting Started with the System}, and -join us on @code{#guix} on the Libera Chat IRC network or on +join us on @code{#guix} on the Libera.Chat IRC network or on @email{guix-devel@@gnu.org} to share your experience! @@ -2942,7 +2583,7 @@ The resulting file will be much smaller than 50 GB (typically less than 1 MB), but it will grow as the virtualized storage device is filled up. @item -Boot the USB installation image in an VM: +Boot the USB installation image in a VM: @example qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \ @@ -6342,12 +5983,18 @@ such as @file{/usr/bin} on foreign distros. This @option{--container} option can also prove useful if you wish to run a security-sensitive application, such as a web browser, in an isolated environment. For example, the command below launches -Ungoogled-Chromium in an isolated environment, this time sharing network -access with the host and preserving its @code{DISPLAY} environment -variable, but without even sharing the current directory: +Ungoogled-Chromium in an isolated environment, which: +@itemize +@item shares network access with the host +@item inherits host's environment variables @code{DISPLAY} and @code{XAUTHORITY} +@item has access to host's authentication records from the @code{XAUTHORITY} +file +@item has no information about host's current directory +@end itemize @example guix shell --container --network --no-cwd ungoogled-chromium \ + --preserve='^XAUTHORITY$' --expose="$@{XAUTHORITY@}" \ --preserve='^DISPLAY$' -- chromium @end example @@ -9446,7 +9093,7 @@ package name should be prefixed with the lisp implementation, such as @code{sbcl-} for @code{asdf-build-system/sbcl}. Additionally, the corresponding source package should be labeled using -the same convention as python packages (see @ref{Python Modules}), using +the same convention as Python packages (@pxref{Python Modules}), using the @code{cl-} prefix. In order to create executable programs and images, the build-side @@ -12552,9 +12199,10 @@ The resulting file holds references to all the dependencies of @var{exp} or a subset thereof. @end deffn -@deffn {Procedure} scheme-file name exp [#:splice? #f] [#:set-load-path? #t] +@deffn {Procedure} scheme-file name exp [#:splice? #f] @ + [#:guile #f] [#:set-load-path? #t] Return an object representing the Scheme file @var{name} that contains -@var{exp}. +@var{exp}. @var{guile} is the Guile package used to produce that file. This is the declarative counterpart of @code{gexp->file}. @end deffn @@ -17020,7 +16668,9 @@ The available targets are: - powerpc64le-linux-gnu - riscv64-linux-gnu - x86_64-linux-gnu + - x86_64-linux-gnux32 - x86_64-w64-mingw32 + - xtensa-ath9k-elf @end example Targets are specified as GNU triplets (@pxref{Specifying Target @@ -17158,7 +16808,7 @@ instantiated. Then we show how this mechanism can be extended, for instance to support new system services. @menu -* Getting Started with the System:: Your first steps. +* Getting Started with the System:: Your first steps. * Using the Configuration System:: Customizing your GNU system. * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. @@ -17508,7 +17158,7 @@ the @code{(gnu packages)} module. For example: (operating-system ;; ... (packages (append (map specification->package+output - '("nss-certs" "git" "git:send-email")) + '("git" "git:send-email")) %base-packages))) @end lisp @@ -17596,8 +17246,7 @@ This example refers to the @file{/boot/efi} file system by its UUID, as returned by the @command{blkid} command. @xref{Desktop Services}, for the exact list of services provided by -@code{%desktop-services}. @xref{X.509 Certificates}, for background -information about the @code{nss-certs} package that is used here. +@code{%desktop-services}. Again, @code{%desktop-services} is just a list of service objects. If you want to remove services from there, you can do so using the @@ -17726,6 +17375,7 @@ configuration (@pxref{Using the Configuration System}). @table @asis @item @code{kernel} (default: @code{linux-libre}) +@c footnote duplicated in @pxref{Installation} The package object of the operating system kernel to use@footnote{Currently only the Linux-libre kernel is fully supported. Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only @@ -24818,10 +24468,42 @@ polkit with the actions from @code{gnome-settings-daemon}. @deftp {Data Type} gnome-desktop-configuration Configuration record for the GNOME desktop environment. +Available @code{gnome-desktop-configuration} fields are: @table @asis -@item @code{gnome} (default: @code{gnome}) -The GNOME package to use. +@item @code{core-services} (type: list-of-packages) +A list of packages that the GNOME Shell and applications may rely on. + +@item @code{shell} (type: list-of-packages) +A list of packages that constitute the GNOME Shell, without +applications. + +@item @code{utilities} (type: list-of-packages) +A list of packages that serve as applications to use on top of the GNOME Shell. + +@item @code{gnome} (type: maybe-package) +This field used to be the only configuration point and specified +a GNOME meta-package to install system-wide. Since the meta-package +itself provides neither sources nor the actual packages and is only +used to propagate them, this field is deprecated. + +@item @code{extra-packages} (type: list-of-packages) +A list of GNOME-adjacent packages to also include. This field is +intended for users to add their own packages to their GNOME experience. +Note, that it already includes some packages that are considered +essential by some (most?) GNOME users. + +@item @code{udev-ignorelist} (default: @code{()}) (type: list-of-strings) +A list of regular expressions denoting udev rules or hardware file names +provided by any package that should not be installed. By default, every +udev rule and hardware file specified by any package referenced in the +other fields are installed. + +@item @code{polkit-ignorelist} (default: @code{()}) (type: list-of-strings) +A list of regular expressions denoting polkit rules provided by any +package that should not be installed. By default, every polkit rule +added by any package referenced in the other fields are installed. + @end table @end deftp @@ -25259,6 +24941,25 @@ Package object for UDisks. @end table @end deftp +@defvar gvfs-service-type +Type for the service that provides virtual file systems for GIO +applicaitons, which enables support for @code{trash:///}, @code{ftp://}, +@code{sftp://} and many other location schemas in file managers like +Nautilus (GNOME Files) and Thunar. + +The value for this service is a @code{<gvfs-configuration>} object. +@end defvar + +@deftp {Data Type} gvfs-configuration +Data type representing the configuration for @code{gvfs-service-type}. + +@table @asis +@item @code{gvfs} (default: @code{gvfs}) (type: file-like) +Package object for GVfs. + +@end table +@end deftp + @defvar colord-service-type This is the type of the service that runs @command{colord}, a system service with a D-Bus @@ -26999,7 +26700,7 @@ Disable LOGIN command and all other plaintext authentications unless SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP matches the local IP (i.e.@: you're connecting from the same computer), the connection is considered secure and plaintext authentication is -allowed. See also ssl=required setting. +allowed. See also the @samp{ssl=required} setting. Defaults to @samp{#t}. @end deftypevr @@ -27139,7 +26840,7 @@ Defaults to @samp{#f}. List of wanted authentication mechanisms. Supported mechanisms are: @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, @samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, -@samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also +@samp{otp}, @samp{skey}, and @samp{gss-spnego}. See also the @samp{disable-plaintext-auth} setting. @end deftypevr @@ -32812,9 +32513,9 @@ pulling channels from Git. To that end, it needs to access X.509 certificates so that it can authenticate Git servers when communicating over HTTPS, and it assumes that @file{/etc/ssl/certs} contains those certificates. -Thus, make sure to add @code{nss-certs} or another certificate package to the -@code{packages} field of your configuration. @ref{X.509 Certificates}, for -more information on X.509 certificates. +A certificate package, @code{nss-certs}, is provided by default as +part of @code{%base-packages}. @ref{X.509 Certificates}, for more +information on X.509 certificates. @end quotation @subsubheading gmnisrv @@ -39706,6 +39407,44 @@ Extra command line options for @code{guix-data-service-process-jobs}. @end table @end deftp +@anchor{guix-home-service-type} +@subsubheading Guix Home Service + +The Guix Home service is a way to let Guix System deploy the home +environment of one or more users (@pxref{Home Configuration}, for more +on Guix Home). That way, the system configuration embeds declarations +of the home environment of those users and can be used to deploy +everything consistently at once, saving users the need to run +@command{guix home reconfigure} independently. + +@defvar guix-home-service-type +Service type for the Guix Home service. Its value must be a list of +lists containing user and home environment pairs. The key of each pair +is a string representing the user to deploy the configuration under and +the value is a home-environment configuration. + +@lisp +(use-modules (gnu home)) + +(define my-home + (home-environment + @dots{})) + +(operating-system + (services (append (list (service guix-home-service-type + `(("alice" ,my-home)))) + %base-services))) +@end lisp + +This service can be extended by other services to add additional home +environments, as in this example: + +@lisp +(simple-service 'my-extra-home home-service-type + `(("bob" ,my-extra-home)))) +@end lisp +@end defvar + @subsubheading Nar Herder The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is a utility for managing a collection of nars. @@ -41323,7 +41062,7 @@ Reference}). Guix includes one such package, @code{nss-certs}, which is a set of CA certificates provided as part of Mozilla's Network Security Services. -Note that it is @emph{not} part of @code{%base-packages}, so you need to +This package is part of @code{%base-packages}, so there is no need to explicitly add it. The @file{/etc/ssl/certs} directory, which is where most applications and libraries look for certificates by default, points to the certificates installed globally. @@ -41696,7 +41435,7 @@ program. That gives a lot of flexibility. The program to run in that initrd. @deffn {Procedure} expression->initrd exp @ - [#:guile %guile-static-stripped] [#:name "guile-initrd"] + [#:guile %guile-static-initrd] [#:name "guile-initrd"] Return as a file-like object a Linux initrd (a gzipped cpio archive) containing @var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All the derivations referenced by @var{exp} are @@ -44579,6 +44318,12 @@ mechanism to create the XDG run-time directory and has the like user Shepherd and its descendants will not start. @end quotation +If you're using Guix System, you can embed your home configuration in +your system configuration such that @command{guix system reconfigure} +will deploy both the system @emph{and} your home at once! +@xref{guix-home-service-type, @code{guix-home-service-type}}, for how to +do that. + @node Configuring the Shell @section Configuring the Shell This section is safe to skip if your shell or shells are managed by @@ -46823,12 +46568,13 @@ guix time-machine \ You can think of it as some sort of built-in version control! Your home is not just a binary artifact: @emph{it carries its own source}. -@c @xref{Service Reference, @code{provenance-service-type}}, for more -@c information on provenance tracking. -@c @footnote{This action (and the related actions -@c @code{switch-generation} and @code{roll-back}) are usable after the -@c home environment is initialized.}. +@quotation Note +If you're using Guix System, @ref{guix-home-service-type, +@code{guix-home-service-type}}, on how to embed your home configuration +in your system configuration such that @command{guix system reconfigure} +deploys both your system and your home. +@end quotation @item switch-generation @cindex home generations @@ -47159,6 +46905,11 @@ Platform targeting x86 CPU running GNU/Linux. Platform targeting x86 64-bit CPU running GNU/Linux. @end defvar +@defvar x86_64-linux-x32 +Platform targeting x86 64-bit CPU running GNU/Linux with the run-time using +the X32 ABI. +@end defvar + @defvar i686-mingw Platform targeting x86 CPU running Windows, with run-time support from MinGW. @@ -47184,6 +46935,11 @@ Platform targeting OpenRISC 1000 CPU without an operating system and without a C standard library. @end defvar +@defvar xtensa-ath9k-elf +Platform targeting Xtensa CPU used in the Qualcomm Atheros AR7010 and AR9271 +USB 802.11n @acronym{NICs, Network Interface Controllers}. +@end defvar + @node System Images @chapter Creating System Images @@ -48223,7 +47979,12 @@ The graph below shows the resulting dependency graph for @code{gcc-core-mesboot0}, the bootstrap compiler used for the traditional bootstrap of the rest of the Guix System. -@c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-seeds|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot +@c ./pre-inst-env guix graph \ +@c -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' \ +@c | sed -r \ +@c -e 's,((bootstrap-seeds|guile-bootstrap).*shape =) box,\1 ellipse,' \ +@c -e 's,fontname = sans,fontname = "dejavu sans",' \ +@c > doc/images/gcc-core-mesboot0-graph.dot @image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0} Work is ongoing to bring these bootstraps to the @code{arm-linux} and |