Merge remote-tracking branch 'origin/master' into core-updates

Change-Id: Id398a49a83cfe6f3a5ba0aee811d09ca12f897de

4 files changed, 303 insertions, 38 deletions

diff --git a/doc/build.scm b/doc/build.scm
index 2cd57b4a92..9ab2ca32d2 100644
--- a/doc/build.scm
+++ b/doc/build.scm
@@ -365,7 +365,7 @@ actual file name."
                                                             #:languages
                                                             languages))
                                   (syntax-css-url
-                                   "/static/base/css/code.css"))
+                                   "/themes/initial/css/code.css"))
   "Return a derivation called NAME that processes all the HTML files in INPUT
 to (1) add them a link to SYNTAX-CSS-URL, and (2) highlight the syntax of all
 its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
@@ -624,7 +624,7 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')."
                         #:key
                         (languages %languages)
                         (manual %manual)
-                        (manual-css-url "/static/base/css/manual.css"))
+                        (manual-css-url "/themes/initial/css/manual.css"))
   "Process all the HTML files in INPUT; add them MANUAL-CSS-URL as a <style>
 link, and add a menu to choose among LANGUAGES.  Use the Guix PO files found
 in SOURCE."
@@ -741,7 +741,7 @@ in SOURCE."
                             (list (menu-dropdown
                                    #:label
                                    `(img (@ (alt "Language")
-                                            (src "/static/base/img/language-picker.svg")))
+                                            (src "/themes/initial/img/language-picker.svg")))
                                    #:items
                                    (language-menu-items file)))
                             #:split-node? split-node?)
@@ -1141,16 +1141,16 @@ must be the Guix top-level source directory, from which PO files are taken."
                     ;; Menu prefetch.
                     (link (@ (rel "prefetch") (href ,(guix-url "menu/index.html"))))
                     ;; Base CSS.
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/elements.css"))))
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/common.css"))))
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/messages.css"))))
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/navbar.css"))))
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/breadcrumbs.css"))))
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/buttons.css"))))
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/footer.css"))))
-
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/page.css"))))
-                    (link (@ (rel "stylesheet") (href ,(guix-url "static/base/css/post.css")))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/elements.css"))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/common.css"))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/messages.css"))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/navbar.css"))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/breadcrumbs.css"))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/buttons.css"))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/footer.css"))))
+
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/page.css"))))
+                    (link (@ (rel "stylesheet") (href ,(guix-url "themes/initial/css/post.css")))))
                    (body
                     (header (@ (class "navbar"))
                             (h1 (a (@ (class "branding")
diff --git a/doc/contributing.texi b/doc/contributing.texi
index a7d91724fb..f5b01f42fd 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -23,7 +23,8 @@ choice.
 * Building from Git::           The latest and greatest.
 * Running Guix Before It Is Installed::  Hacker tricks.
 * The Perfect Setup::           The right tools.
-* Alternative Setups::          Other posible tools that do the job.
+* Alternative Setups::          Other possible tools that do the job.
+* Source Tree Structure::       Source code guided tour.
 * Packaging Guidelines::        Growing the distribution.
 * Coding Style::                Hygiene of the contributor.
 * Submitting Patches::          Share your work.
@@ -546,6 +547,257 @@ In NeoVim you can even make a similar setup to Geiser using
 process and inject your code there live (sadly it's not packaged in Guix yet).
 
 
+@node Source Tree Structure
+@section Source Tree Structure
+
+@cindex structure, of the source tree
+If you're willing to contribute to Guix beyond packages, or if you'd
+like to learn how it all fits together, this section provides a guided
+tour in the code base that you may find useful.
+
+Overall, the Guix source tree contains almost exclusively Guile
+@dfn{modules}, each of which can be seen as an independent library
+(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
+
+The following table gives an overview of the main directories and what
+they contain.  Remember that in Guile, each module name is derived from
+its file name---e.g., the module in file @file{guix/packages.scm} is
+called @code{(guix packages)}.
+
+@table @file
+@item guix
+This is the location of core Guix mechanisms.  To illustrate what is
+meant by ``core'', here are a few examples, starting from low-level
+tools and going towards higher-level tools:
+
+@table @code
+@item (guix store)
+Connecting to and interacting with the build daemon (@pxref{The Store}).
+@item (guix derivations)
+Creating derivations (@pxref{Derivations}).
+@item (guix gexps)
+Writing G-expressions (@pxref{G-Expressions}).
+@item (guix packages)
+Defining packages and origins (@pxref{package Reference}).
+@item (guix download)
+@itemx (guix git-download)
+The @code{url-fetch} and @code{git-fetch} origin download methods
+(@pxref{origin Reference}).
+@item (guix swh)
+Fetching source code from the
+@uref{https://archive.softwareheritage.org,Software Heritage archive}.
+@item (guix search-paths)
+Implementing search paths (@pxref{Search Paths}).
+@item (guix build-system)
+The build system interface (@pxref{Build Systems}).
+@item (guix profiles)
+Implementing profiles.
+@end table
+
+@cindex build system, directory structure
+@item guix/build-system
+This directory contains specific build system implementations
+(@pxref{Build Systems}), such as:
+
+@table @code
+@item (guix build-system gnu)
+the GNU build system;
+@item (guix build-system cmake)
+the CMake build system;
+@item (guix build-system pyproject)
+The Python ``pyproject'' build system.
+@end table
+
+@item guix/build
+This contains code generally used on the ``build side''
+(@pxref{G-Expressions, strata of code}).  This includes code used to
+build packages or other operating system components, as well as
+utilities:
+
+@table @code
+@item (guix build utils)
+Utilities for package definitions and more (@pxref{Build Utilities}).
+@item (guix build gnu-build-system)
+@itemx (guix build cmake-build-system)
+@itemx (guix build pyproject-build-system)
+Implementation of build systems, and in particular definition of their
+build phases (@pxref{Build Phases}).
+@item (guix build syscalls)
+Interface to the C library and to Linux system calls.
+@end table
+
+@cindex command-line tools, as Guile modules
+@cindex command modules
+@item guix/scripts
+This contains modules corresponding to @command{guix} sub-commands.  For
+example, the @code{(guix scripts shell)} module exports the
+@code{guix-shell} procedure, which directly corresponds to the
+@command{guix shell} command (@pxref{Invoking guix shell}).
+
+@cindex importer modules
+@item guix/import
+This contains supporting code for the importers and updaters
+(@pxref{Invoking guix import}, and @pxref{Invoking guix refresh}).  For
+example, @code{(guix import pypi)} defines the interface to PyPI, which
+is used by the @code{guix import pypi} command.
+@end table
+
+The directories we have seen so far all live under @file{guix/}.  The
+other important place is the @file{gnu/} directory, which contains
+primarily package definitions as well as libraries and tools for Guix
+System (@pxref{System Configuration}) and Guix Home (@pxref{Home
+Configuration}), all of which build upon functionality provided by
+@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix
+@dots{})} modules must generally not depend on @code{(gnu @dots{})}
+modules, with notable exceptions: @code{(guix build-system @dots{})}
+modules may look up packages at run time---e.g., @code{(guix
+build-system cmake)} needs to access the @code{cmake} variable at run
+time---, @code{(guix scripts @dots{})} often rely on @code{(gnu @dots{})}
+modules, and the same goes for some of the @code{(guix import @dots{})}
+modules.}.
+
+@table @file
+@cindex package modules
+@item gnu/packages
+This is by far the most crowded directory of the source tree: it
+contains @dfn{package modules} that export package definitions
+(@pxref{Package Modules}).  A few examples:
+
+@table @code
+@item (gnu packages base)
+Module providing ``base'' packages: @code{glibc}, @code{coreutils},
+@code{grep}, etc.
+@item (gnu packages guile)
+Guile and core Guile packages.
+@item (gnu packages linux)
+The Linux-libre kernel and related packages.
+@item (gnu packages python)
+Python and core Python packages.
+@item (gnu packages python-xyz)
+Miscellaneous Python packages (we were not very creative).
+@end table
+
+In any case, you can jump to a package definition using @command{guix
+edit} (@pxref{Invoking guix edit}) and view its location with
+@command{guix show} (@pxref{Invoking guix package}).
+
+@findex search-patches
+@item gnu/packages/patches
+This directory contains patches applied against packages and obtained
+using the @code{search-patches} procedure.
+
+@item gnu/services
+This contains service definitions, primarily for Guix System
+(@pxref{Services}) but some of them are adapted and reused for Guix Home
+as we will see below.  Examples:
+
+@table @code
+@item (gnu services)
+The service framework itself, which defines the service and service type
+data types (@pxref{Service Composition}).
+@item (gnu services base)
+``Base'' services (@pxref{Base Services}).
+@item (gnu services desktop)
+``Desktop'' services (@pxref{Desktop Services}).
+@item (gnu services shepherd)
+Support for Shepherd services (@pxref{Shepherd Services}).
+@end table
+
+You can jump to a service definition using @command{guix system edit}
+and view its location with @command{guix system search} (@pxref{Invoking
+guix system}).
+
+@item gnu/system
+These are core Guix System modules, such as:
+
+@table @code
+@item (gnu system)
+Defines @code{operating-system} (@pxref{operating-system Reference}).
+@item (gnu system file-systems)
+Defines @code{file-system} (@pxref{File Systems}).
+@item (gnu system mapped-devices)
+Defines @code{mapped-device} (@pxref{Mapped Devices}).
+@end table
+
+@item gnu/build
+These are modules that are either used on the ``build side'' when
+building operating systems or packages, or at run time by operating
+systems.
+
+@table @code
+@item (gnu build accounts)
+Creating @file{/etc/passwd}, @file{/etc/shadow}, etc. (@pxref{User
+Accounts}).
+@item (gnu build activation)
+Activating an operating system at boot time or reconfiguration time.
+@item (gnu build file-systems)
+Searching, checking, and mounting file systems.
+@item (gnu build linux-boot)
+@itemx (gnu build hurd-boot)
+Booting GNU/Linux and GNU/Hurd operating systems.
+@item (gnu build linux-initrd)
+Creating a Linux initial RAM disk (@pxref{Initial RAM Disk}).
+@end table
+
+@item gnu/home
+This contains all things Guix Home (@pxref{Home Configuration});
+examples:
+
+@table @code
+@item (gnu home services)
+Core services such as @code{home-files-service-type}.
+@item (gnu home services ssh)
+SSH-related services (@pxref{Secure Shell}).
+@end table
+
+@item gnu/installer
+This contains the text-mode graphical system installer (@pxref{Guided
+Graphical Installation}).
+
+@item gnu/machine
+These are the @dfn{machine abstractions} used by @command{guix deploy}
+(@pxref{Invoking guix deploy}).
+
+@item gnu/tests
+This contains system tests---tests that spawn virtual machines to check
+that system services work as expected (@pxref{Running the Test Suite}).
+@end table
+
+Last, there's also a few directories that contain files that are
+@emph{not} Guile modules:
+
+@table @file
+@item nix
+This is the C++ implementation of @command{guix-daemon}, inherited from
+Nix (@pxref{Invoking guix-daemon}).
+
+@item tests
+These are unit tests, each file corresponding more or less to one
+module, in particular @code{(guix @dots{})} modules (@pxref{Running the
+Test Suite}).
+
+@item doc
+This is the documentation in the form of Texinfo files: this manual and
+the Cookbook.  @xref{Writing a Texinfo File,,, texinfo, GNU Texinfo},
+for information on Texinfo markup language.
+
+@item po
+This is the location of translations of Guix itself, of package synopses
+and descriptions, of the manual, and of the cookbook.  Note that
+@file{.po} files that live here are pulled directly from Weblate
+(@pxref{Translating Guix}).
+
+@item etc
+Miscellaneous files: shell completions, support for systemd and other
+init systems, Git hooks, etc.
+@end table
+
+With all this, a fair chunk of your operating system is at your
+fingertips!  Beyond @command{grep} and @command{git grep}, @pxref{The
+Perfect Setup} on how to navigate code from your editor, and
+@pxref{Using Guix Interactively} for information on how to use Scheme
+modules interactively.  Enjoy!
+
 @node Packaging Guidelines
 @section Packaging Guidelines
 
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 2366c13caf..e7ef5fa784 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -22,7 +22,7 @@ Copyright @copyright{} 2020 André Batista@*
 Copyright @copyright{} 2020 Christine Lemmer-Webber@*
 Copyright @copyright{} 2021 Joshua Branson@*
 Copyright @copyright{} 2022, 2023 Maxim Cournoyer@*
-Copyright @copyright{} 2023 Ludovic Courtès@*
+Copyright @copyright{} 2023-2024 Ludovic Courtès@*
 Copyright @copyright{} 2023 Thomas Ieong
 
 Permission is granted to copy, distribute and/or modify this document
@@ -5299,14 +5299,17 @@ export LC_ALL
 For convenience, @code{guix package} automatically generates
 @file{~/.guix-profile/etc/profile}, which defines all the environment
 variables necessary to use the packages---@code{PATH},
-@code{C_INCLUDE_PATH}, @code{PYTHONPATH}, etc.  Thus it's a good idea to
-source it from @code{/etc/profile}:
+@code{C_INCLUDE_PATH}, @code{PYTHONPATH}, etc.  Likewise, @command{guix
+pull} does that under @file{~/.config/guix/current}.  Thus it's a good
+idea to source both from @code{/etc/profile}:
 
 @example
-GUIX_PROFILE="$HOME/.guix-profile"
-if [ -f "$GUIX_PROFILE/etc/profile" ]; then
-  . "$GUIX_PROFILE/etc/profile"
-fi
+for GUIX_PROFILE in "$HOME/.config/guix/current" "$HOME/.guix-profile"
+do
+  if [ -f "$GUIX_PROFILE/etc/profile" ]; then
+    . "$GUIX_PROFILE/etc/profile"
+  fi
+done
 @end example
 
 Last but not least, Guix provides command-line completion notably for
diff --git a/doc/guix.texi b/doc/guix.texi
index 536e7c5ea8..27dc9143fa 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2728,20 +2728,20 @@ the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
 @code{man cryptsetup}} for more information).
 
 @quotation Warning
-Note that GRUB can unlock LUKS2 devices since version 2.06, but only
-supports the PBKDF2 key derivation function, which is not the default
-for @command{cryptsetup luksFormat}.  You can check which key derivation
-function is being used by a device by running @command{cryptsetup
-luksDump @var{device}}, and looking for the PBKDF field of your
-keyslots.
+While efforts are in progress to extend support to LUKS2, please note
+that Guix only supports devices of type LUKS1 at the moment. You can
+verify that your existing LUKS device is of the right type by running
+@command{cryptsetup luksDump @var{device}}. Alternatively, you can
+create a new LUKS1 device with @command{cryptsetup luksFormat --type
+luks1 @var{device}}.
 @end quotation
 
 Assuming you want to store the root partition on @file{/dev/sda2}, the
-command sequence to format it as a LUKS2 partition would be along these
+command sequence to format it as a LUKS1 partition would be along these
 lines:
 
 @example
-cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 /dev/sda2
+cryptsetup luksFormat --type luks1 /dev/sda2
 cryptsetup open /dev/sda2 my-partition
 mkfs.ext4 -L my-root /dev/mapper/my-partition
 @end example
@@ -3445,7 +3445,7 @@ Install the package @var{exp} evaluates to.
 @var{exp} must be a Scheme expression that evaluates to a
 @code{<package>} object.  This option is notably useful to disambiguate
 between same-named variants of a package, with expressions such as
-@code{(@@ (gnu packages base) guile-final)}.
+@code{(@@ (gnu packages commencement) guile-final)}.
 
 Note that this option installs the first output of the specified
 package, which may be insufficient when needing a specific output of a
@@ -7632,6 +7632,9 @@ contain OpenPGP public keys in @file{.key} files, either in binary form
 or ``ASCII-armored''.  By default the keyring is loaded from the branch
 named @code{keyring}.
 
+@item --end=@var{commit}
+Authenticate revisions up to @var{commit}.
+
 @item --stats
 Display commit signing statistics upon completion.
 
@@ -7677,7 +7680,8 @@ assembly is to C programs.  The term ``derivation'' comes from the fact
 that build results @emph{derive} from them.
 
 This chapter describes all these APIs in turn, starting from high-level
-package definitions.
+package definitions.  @xref{Source Tree Structure}, for a more general
+overview of the source code.
 
 @menu
 * Package Modules::             Packages from the programmer's viewpoint.
@@ -21135,7 +21139,7 @@ the @code{loopback} Shepherd service.
 @defvar %qemu-static-networking
 This is the @code{static-networking} record representing network setup
 when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using
-the user mode network stack,,, QEMU, QEMU Documentation}).
+the user mode network stack,,, qemu, QEMU Documentation}).
 @end defvar
 
 @cindex DHCP, networking service
@@ -22770,9 +22774,9 @@ Logging level.
 This service type adds a list of known Facebook hosts to the
 @file{/etc/hosts} file.
 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual})
-Each line contains a entry that maps a known server name of the Facebook
-on-line service---e.g., @code{www.facebook.com}---to the local
-host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
+Each line contains an entry that maps a known server name of the Facebook
+on-line service---e.g., @code{www.facebook.com}---to unroutable IPv4 and
+IPv6 addresses.
 
 This mechanism can prevent programs running locally, such as Web
 browsers, from accessing Facebook.
@@ -28605,6 +28609,12 @@ Set of mechanisms that will never be offered.  See
 Defaults to @samp{'("DIGEST-MD5")}.
 @end deftypevr
 
+@deftypevr {@code{prosody-configuration} parameter} string-list insecure-sasl-mechanisms
+Set of mechanisms that will not be offered on unencrypted connections.
+See @url{https://prosody.im/doc/modules/mod_saslauth}.
+Defaults to @samp{'("PLAIN" "LOGIN")}.
+@end deftypevr
+
 @deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
 Whether to force all server-to-server connections to be encrypted or not.
 See @url{https://prosody.im/doc/modules/mod_tls}.
@@ -28684,7 +28694,7 @@ See @url{https://prosody.im/doc/configure#virtual_host_settings}.
 
 Available @code{virtualhost-configuration} fields are:
 
-all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
+all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{insecure-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
 @deftypevr {@code{virtualhost-configuration} parameter} string domain
 Domain you wish Prosody to serve.
 @end deftypevr
@@ -28706,7 +28716,7 @@ Defaults to @samp{'()}.
 
 Available @code{int-component-configuration} fields are:
 
-all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
+all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{insecure-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
 @deftypevr {@code{int-component-configuration} parameter} string hostname
 Hostname of the component.
 @end deftypevr
@@ -28759,7 +28769,7 @@ Defaults to @samp{'()}.
 
 Available @code{ext-component-configuration} fields are:
 
-all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
+all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{insecure-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
 @deftypevr {@code{ext-component-configuration} parameter} string component-secret
 Password which the component will use to log in.
 @end deftypevr