Merge branch 'master' into gnome-team

3 files changed, 216 insertions, 8 deletions

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9e9b89782c..7337f4bd58 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -76,15 +76,17 @@ all the dependencies and appropriate environment variables are set up to
 hack on Guix:
 
 @example
-guix shell -D guix --pure
+guix shell -D guix -CPW
 @end example
 
 or even, from within a Git worktree for Guix:
 
 @example
-guix shell --pure
+guix shell -CPW
 @end example
 
+If @option{-C} (short for @option{--container}) is not supported on your
+system, try @command{--pure} instead of @option{-CPW}.
 @xref{Invoking guix shell}, for more information on that command.
 
 If you are unable to use Guix when building Guix from a checkout, the
@@ -1682,6 +1684,11 @@ command to submit patches.  To list the available actions of the script,
 you can invoke it via the @command{etc/teams.scm help} command.  For
 more information regarding teams, @pxref{Teams}.
 
+@quotation Note
+On foreign distros, you might have to use @command{./pre-inst-env git
+send-email} for @file{etc/teams.scm} to work.
+@end quotation
+
 @unnumberedsubsubsec Multiple Patches
 @anchor{Multiple Patches}
 @cindex cover letter
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 3d86fca396..cdca411706 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -78,7 +78,7 @@ manual}).
 * System Configuration::        Customizing the GNU System
 * Containers::                  Isolated environments and nested systems
 * Advanced package management::  Power to the users!
-* Software Development::         Environments, continuous integration, etc.
+* Software Development::        Environments, continuous integration, etc.
 * Environment management::      Control environment
 * Installing Guix on a Cluster::  High-performance computing.
 
@@ -167,6 +167,16 @@ Guix Profiles in Practice
 * The benefits of manifests::
 * Reproducible profiles::
 
+Software Development
+
+* Getting Started::             Step 0: using `guix shell'.
+* Building with Guix::          Step 1: building your code.
+* The Repository as a Channel::  Step 2: turning the repo in a channel.
+* Package Variants::            Bonus: Defining variants.
+* Setting Up Continuous Integration::  Step 3: continuous integration.
+* Build Manifest::              Bonus: Manifest.
+* Wrapping Up::                 Recap.
+
 Environment management
 
 * Guix environment via direnv::  Setup Guix environment with direnv
diff --git a/doc/guix.texi b/doc/guix.texi
index ec26a2295c..50d66e9557 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
@@ -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.
@@ -7975,6 +7994,10 @@ The exact set of supported keywords depends on the build system
 @code{#:phases}.  The @code{#:phases} keyword in particular lets you
 modify the set of build phases for your package (@pxref{Build Phases}).
 
+The REPL has dedicated commands to interactively inspect values of some
+of these arguments, as a convenient debugging aid (@pxref{Using Guix
+Interactively}).
+
 @quotation Compatibility Note
 Until version 1.3.0, the @code{arguments} field would typically use
 @code{quote} (@code{'}) or @code{quasiquote} (@code{`}) and no
@@ -8774,6 +8797,23 @@ when @var{cut?} returns true for a given package.  When @var{deep?} is true, @va
 applied to implicit inputs as well.
 @end deffn
 
+@quotation Tips
+Understanding what a variant really looks like can be difficult as one
+starts combining the tools shown above.  There are several ways to
+inspect a package before attempting to build it that can prove handy:
+
+@itemize
+@item
+You can inspect the package interactively at the REPL, for instance to
+view its inputs, the code of its build phases, or its configure flags
+(@pxref{Using Guix Interactively}).
+
+@item
+When rewriting dependencies, @command{guix graph} can often help
+visualize the changes that are made (@pxref{Invoking guix graph}).
+@end itemize
+@end quotation
+
 @node Writing Manifests
 @section Writing Manifests
 
@@ -9558,6 +9598,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
@@ -10585,6 +10639,11 @@ we have seen before.  @xref{Build Utilities}, for more about
 the helpers used by this phase, and for more examples of
 @code{modify-phases}.
 
+@quotation Tip
+You can inspect the code associated with a package's @code{#:phases}
+argument interactively, at the REPL (@pxref{Using Guix Interactively}).
+@end quotation
+
 @cindex code staging
 @cindex staging, of code
 Keep in mind that build phases are code evaluated at the time the
@@ -12763,6 +12822,30 @@ scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
 $5 = ("." ".." "egrep" "fgrep" "grep")
 @end example
 
+As a packager, you may be willing to inspect the build phases or flags
+of a given package; this is particularly useful when relying a lot on
+inheritance to define package variants (@pxref{Defining Package
+Variants}) or when package arguments are a result of some computation,
+both of which can make it harder to foresee what ends up in the package
+arguments.  Additional commands let you inspect those package arguments:
+
+@example
+scheme@@(guix-user)> ,phases grep
+$1 = (modify-phases %standard-phases
+       (add-after 'install 'fix-egrep-and-fgrep
+         (lambda* (#:key outputs #:allow-other-keys)
+           (let* ((out (assoc-ref outputs "out"))
+                  (bin (string-append out "/bin")))
+             (substitute* (list (string-append bin "/egrep")
+                                (string-append bin "/fgrep"))
+               (("^exec grep")
+                (string-append "exec " bin "/grep")))))))
+scheme@@(guix-user)> ,configure-flags findutils
+$2 = (list "--localstatedir=/var")
+scheme@@(guix-user)> ,make-flags binutils
+$3 = '("MAKEINFO=true")
+@end example
+
 At a lower-level, a useful command is @code{lower}: it takes a file-like
 object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
 store file:
@@ -12794,6 +12877,17 @@ This is similar to the @option{--verbosity} command-line option
 shows build events only, and higher levels print build logs.
 @end deffn
 
+@deffn {REPL command} phases @var{package}
+@deffnx {REPL command} configure-flags @var{package}
+@deffnx {REPL command} make-flags @var{package}
+These REPL commands return the value of one element of the
+@code{arguments} field of @var{package} (@pxref{package Reference}): the
+first one show the staged code associated with @code{#:phases}
+(@pxref{Build Phases}), the second shows the code for
+@code{#:configure-flags}, and @code{,make-flags} returns the code for
+@code{#:make-flags}.
+@end deffn
+
 @deffn {REPL command} run-in-store @var{exp}
 Run @var{exp}, a monadic expression, through the store monad.
 @xref{The Store Monad}, for more information.
@@ -14459,6 +14553,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
@@ -16437,7 +16551,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
@@ -16504,8 +16621,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}
@@ -16699,6 +16817,7 @@ The available targets are:
 
    - aarch64-linux-gnu
    - arm-linux-gnueabihf
+   - avr
    - i586-pc-gnu
    - i686-linux-gnu
    - i686-w64-mingw32
@@ -19316,7 +19435,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
@@ -19385,7 +19505,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
@@ -27589,6 +27710,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
 
@@ -45763,6 +45944,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
@@ -45824,6 +46010,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