summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/build.scm2
-rw-r--r--doc/contributing.texi199
-rw-r--r--doc/guix-cookbook.texi91
-rw-r--r--doc/guix.texi691
-rw-r--r--doc/htmlxref.cnf4
-rw-r--r--doc/local.mk35
6 files changed, 884 insertions, 138 deletions
diff --git a/doc/build.scm b/doc/build.scm
index 20d6624653..880bb9e85c 100644
--- a/doc/build.scm
+++ b/doc/build.scm
@@ -70,7 +70,7 @@
(define %cookbook-languages
;; Available translations for the 'guix-cookbook' text domain.
- '("de" "en" "fr" "ko" "pt_BR" "sk"))
+ '("de" "en" "fr" "ko" "pt_BR" "sk" "sv"))
(define %languages
;; Available translations for the document being built.
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 66f4e86d0a..938c8bfdb1 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -235,7 +235,7 @@ more information.
Then, run:
@example
-./configure --localstatedir=/var --sysconfdir=/etc
+./configure
@end example
@noindent
@@ -246,19 +246,6 @@ normal @code{sysconfdir} value. Note that you will probably not run
important to pass the right @code{localstatedir} and @code{sysconfdir}
values, which get recorded in the @code{(guix config)} Guile module.
-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.
-
Finally, you can build Guix and, if you feel so inclined, run the tests
(@pxref{Running the Test Suite}):
@@ -276,25 +263,41 @@ From there on, you can authenticate all the commits included in your
checkout by running:
@example
-make authenticate
+guix git authenticate \
+ 9edb3f66fd807b096b48283debdcddccfea34bad \
+ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"
@end example
The first run takes a couple of minutes, but subsequent runs are faster.
+On subsequent runs, you can run the command without any arguments since
+the @dfn{introduction} (the commit ID and OpenPGP fingerprints above)
+will have been recorded@footnote{This requires a recent version of Guix,
+from May 2024 or more recent.}:
+
+@example
+guix git authenticate
+@end example
-Or, when your configuration for your local Git repository doesn't match
+When your configuration for your local Git repository doesn't match
the default one, you can provide the reference for the @code{keyring}
-branch through the variable @code{GUIX_GIT_KEYRING}. The following
+branch @i{via} the @option{-k} option. The following
example assumes that you have a Git remote called @samp{myremote}
pointing to the official repository:
@example
-make authenticate GUIX_GIT_KEYRING=myremote/keyring
+guix git authenticate \
+ -k myremote/keyring \
+ 9edb3f66fd807b096b48283debdcddccfea34bad \
+ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA"
@end example
+@xref{Invoking guix git authenticate}, for more information on this
+command.
+
@quotation Note
-You are advised to run @command{make authenticate} after every
-@command{git pull} invocation. This ensures you keep receiving valid
-changes to the repository.
+By default, hooks are installed such that @command{guix git
+authenticate} is invoked anytime you run @command{git pull} or
+@command{git push}.
@end quotation
After updating the repository, @command{make} might fail with an error
@@ -2018,11 +2021,12 @@ a subject, if your patch is to be applied on a branch other than
@code{master}, say @code{core-updates}, specify it in the subject like
@samp{[PATCH core-updates] @dots{}}.
-You may use your email client or the @command{git send-email} command
-(@pxref{Sending a Patch Series}). We prefer to get patches in plain
-text messages, either inline or as MIME attachments. You are advised to
-pay attention if your email client changes anything like line breaks or
-indentation which could potentially break the patches.
+You may use your email client, the @command{git send-email} command
+(@pxref{Sending a Patch Series}) or the @command{mumi send-email}
+command (@pxref{Debbugs User Interfaces}). We prefer to get patches in
+plain text messages, either inline or as MIME attachments. You are
+advised to pay attention if your email client changes anything like line
+breaks or indentation which could potentially break the patches.
Expect some delay when you submit your very first patch to
@email{guix-patches@@gnu.org}. You have to wait until you get an
@@ -2298,9 +2302,9 @@ indication of its build status on various platforms.
@cindex feature branches, coordination
To help coordinate the merging of branches, you must create a new
-guix-patches issue each time you wish to merge a branch (@pxref{The
-Issue Tracker}). The title of the issue requesting to merge a branch
-should have the following format:
+guix-patches issue each time you create a branch (@pxref{The Issue
+Tracker}). The title of the issue requesting to merge a branch should
+have the following format:
@cindex merge requests, template
@example
@@ -2308,20 +2312,51 @@ Request for merging "@var{name}" branch
@end example
The @url{https://qa.guix.gnu.org/, QA infrastructure} recognizes such
-issues and lists the merge requests on its main page. Normally branches
-will be merged in a ``first come, first merged'' manner, tracked through
-the guix-patches issues.
-
-If you agree on a different order with those involved, you can track
-this by updating which issues block@footnote{You can mark an issue as
-blocked by another by emailing @email{control@@debbugs.gnu.org} with the
-following line in the body of the email: @code{block XXXXX by YYYYY}.
-Where @code{XXXXX} is the number for the blocked issue, and @code{YYYYY}
-is the number for the issue blocking it.} which other issues.
-Therefore, to know which branch is at the front of the queue, look for
-the oldest issue, or the issue that isn't @dfn{blocked} by any other
-branch merges. An ordered list of branches with the open issues is
-available at @url{https://qa.guix.gnu.org}.
+issues and lists the merge requests on its main page. The following
+points apply to managing these branches:
+
+@enumerate
+@item
+The commits on the branch should be a combination of the patches
+relevant to the branch. Patches not related to the topic of the branch
+should go elsewhere.
+
+@item
+Any changes that can be made on the master branch, should be made on the
+master branch. If a commit can be split to apply part of the changes on
+master, this is good to do.
+
+@item
+It should be possible to re-create the branch by starting from master
+and applying the relevant patches.
+
+@item
+Avoid merging master in to the branch. Prefer rebasing or re-creating
+the branch on top of an updated master revision.
+
+@item
+Minimise the changes on master that are missing on the branch prior to
+merging the branch in to master. This means that the state of the
+branch better reflects the state of master should the branch be merged.
+
+@item
+If you don't have commit access, create the ``Request for merging''
+issue and request that someone creates the branch. Include a list of
+issues/patches to include on the branch.
+@end enumerate
+
+Normally branches will be merged in a ``first come, first merged''
+manner, tracked through the guix-patches issues. If you agree on a
+different order with those involved, you can track this by updating
+which issues block@footnote{You can mark an issue as blocked by another
+by emailing @email{control@@debbugs.gnu.org} with the following line in
+the body of the email: @code{block XXXXX by YYYYY}. Where @code{XXXXX}
+is the number for the blocked issue, and @code{YYYYY} is the number for
+the issue blocking it.} which other issues. Therefore, to know which
+branch is at the front of the queue, look for the oldest issue, or the
+issue that isn't @dfn{blocked} by any other branch merges. An ordered
+list of branches with the open issues is available at
+@url{https://qa.guix.gnu.org}.
Once a branch is at the front of the queue, wait until sufficient time
has passed for the build farms to have processed the changes, and for
@@ -2329,6 +2364,9 @@ the necessary testing to have happened. For example, you can check
@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}} to see
information on some builds and substitute availability.
+Once the branch has been merged, the issue should be closed and the
+branch deleted.
+
@node Debbugs User Interfaces
@subsection Debbugs User Interfaces
@@ -2357,10 +2395,15 @@ To view discussions related to issue number @var{n}, go to
@subsubsection Command-line interface
+@cindex mumi CLI
+@cindex mumi am
+@cindex mumi compose
+@cindex mumi send-email
+@cindex mumi www
Mumi also comes with a command-line interface that can be used to search
-existing issues, open new issues and send patches. You do not need to
-use Emacs to use the mumi command-line client. You interact with it
-only on the command-line.
+existing issues, open new issues, compose replies, apply and send
+patches. You do not need to use Emacs to use the mumi command-line
+client. You interact with it only on the command-line.
To use the mumi command-line interface, navigate to a local clone of the
Guix git repository, and drop into a shell with mumi, git and
@@ -2397,8 +2440,61 @@ Pick an issue and make it the "current" issue.
opened on 24 Jan 09:42 Z by Efraim Flashner
@end example
-Once an issue is the current issue, you can easily create and send
-patches to it using
+Once an issue is the current issue, you can open the issue in a web
+browser, compose replies, apply patches, send patches, etc. with short
+succinct commands.
+
+Open the issue in your web browser using
+
+@example
+~/guix [env]$ mumi www
+@end example
+
+Compose a reply using
+
+@example
+~/guix [env]$ mumi compose
+@end example
+
+Compose a reply and close the issue using
+
+@example
+~/guix [env]$ mumi compose --close
+@end example
+
+@command{mumi compose} opens your mail client by passing @samp{mailto:}
+URIs to @command{xdg-open}. So, you need to have @command{xdg-open} set
+up to open your mail client correctly.
+
+Apply the latest patchset from the issue using
+
+@example
+~/guix [env]$ mumi am
+@end example
+
+You may also apply a patchset of a specific version (say, v3) using
+
+@example
+~/guix [env]$ mumi am v3
+@end example
+
+Or, you may apply a patch from a specific e-mail message. For example,
+to apply the patch from the 4th message (message index starts from 0),
+run
+
+@example
+~/guix [env]$ mumi am @@4
+@end example
+
+@command{mumi am} is a wrapper around @command{git am}. You can pass
+@command{git am} arguments to it after a @samp{--}. For example, to add
+a Signed-off-by trailer, run
+
+@example
+~/guix [env]$ mumi am -- -s
+@end example
+
+Create and send patches to the issue using
@example
~/guix [env]$ git format-patch origin/master
@@ -2415,11 +2511,8 @@ To open a new issue, run
~/guix [env]$ mumi new
@end example
-and send patches
-
-@example
-~/guix [env]$ mumi send-email foo.patch bar.patch
-@end example
+and send an email (using @command{mumi compose}) or patches (using
+@command{mumi send-email}).
@command{mumi send-email} is really a wrapper around @command{git
send-email} that automates away all the nitty-gritty of sending patches.
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 3bc63cba7a..da67921ad0 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -23,7 +23,8 @@ Copyright @copyright{} 2020 Christine Lemmer-Webber@*
Copyright @copyright{} 2021 Joshua Branson@*
Copyright @copyright{} 2022, 2023 Maxim Cournoyer@*
Copyright @copyright{} 2023-2024 Ludovic Courtès@*
-Copyright @copyright{} 2023 Thomas Ieong
+Copyright @copyright{} 2023 Thomas Ieong@*
+Copyright @copyright{} 2024 Florian Pelz@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -67,8 +68,9 @@ This manual is also available in French (@pxref{Top,,, guix-cookbook.fr,
Livre de recettes de GNU Guix}), German (@pxref{Top,,, guix-cookbook.de,
GNU-Guix-Kochbuch}), Korean (@pxref{Top,,, guix-cookbook.ko, GNU Guix 쿡북}),
Brazilian Portuguese (@pxref{Top,,, guix-cookbook.pt_BR,
-Livro de Receitas do GNU Guix}) and Slovak (@pxref{Top,,, guix-cookbook.sk,
-Receptár GNU Guix}). If you would like to translate
+Livro de Receitas do GNU Guix}), Slovak (@pxref{Top,,, guix-cookbook.sk,
+Receptár GNU Guix}), and Swedish (@pxref{Top,,, guix-cookbook.sv,
+Kokbok för GNU Guix}). If you would like to translate
this document in your native language, consider joining
@uref{https://translate.fedoraproject.org/projects/guix/documentation-cookbook,
Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference
@@ -1681,7 +1683,7 @@ creates a package.
;; See kernel-config for an example.
(configuration-file #f)
(defconfig "defconfig")
- (extra-options %default-extra-linux-options))
+ (extra-options (default-extra-linux-options version)))
...)
@end lisp
@@ -1693,7 +1695,8 @@ declared like this:
(make-linux-libre* linux-libre-5.15-version
linux-libre-5.15-gnu-revision
linux-libre-5.15-source
- '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux" "riscv64-linux")
+ '("x86_64-linux" "i686-linux" "armhf-linux"
+ "aarch64-linux" "riscv64-linux")
#:configuration-file kernel-config))
@end lisp
@@ -1748,7 +1751,7 @@ The second way to create a custom kernel is to pass a new value to the
it:
@lisp
-(define %default-extra-linux-options
+(define (default-extra-linux-options version)
`(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html
("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #true)
;; Modules required for initrd:
@@ -1798,7 +1801,7 @@ custom kernel:
%file-systems
%efi-support
%emulation
- (@@@@ (gnu packages linux) %default-extra-linux-options)))
+ ((@@@@ (gnu packages linux) default-extra-linux-options) version)))
(define-public linux-libre-macbook41
;; XXX: Access the internal 'make-linux-libre*' procedure, which is
@@ -1812,11 +1815,12 @@ custom kernel:
#:extra-options %macbook41-config-options))
@end lisp
-In the above example @code{%file-systems} is a collection of flags enabling
-different file system support, @code{%efi-support} enables EFI support and
-@code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also.
-@code{%default-extra-linux-options} are the ones quoted above, which had to be
-added in since they were replaced in the @code{extra-options} keyword.
+In the above example @code{%file-systems} is a collection of flags
+enabling different file system support, @code{%efi-support} enables EFI
+support and @code{%emulation} enables a x86_64-linux machine to act in
+32-bit mode also. The @code{default-extra-linux-options} procedure is
+the one defined above, which had to be used to avoid loosing the default
+configuration options of the @code{extra-options} keyword.
This all sounds like it should be doable, but how does one even know which
modules are required for a particular system? Two places that can be helpful
@@ -2405,9 +2409,11 @@ Then you need to add the following code to a StumpWM configuration file
@lisp
(require :ttf-fonts)
(setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/"))
-(setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp"))
+(setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME")
+ "/.fonts/font-cache.sexp"))
(xft:cache-fonts)
-(set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11))
+(set-font (make-instance 'xft:font :family "DejaVu Sans Mono"
+ :subfamily "Book" :size 11))
@end lisp
@node Session lock
@@ -2963,13 +2969,14 @@ should be defined, so that the bind mount can depend on it.
(file-system
(device (uuid "UUID goes here"))
(mount-point "/path-to-spinning-disk-goes-here")
- (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive.
+ (type "ext4"))) ;Make sure to set this to the appropriate type for your drive.
@end lisp
The source folder must also be defined, so that guix will know it's not
a regular block device, but a folder.
@lisp
-(define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name.
+;; "source-directory" can be named any valid variable name.
+(define (%source-directory) "/path-to-spinning-disk-goes-here/tmp")
@end lisp
Finally, inside the @code{file-systems} definition, we must add the
@@ -2980,14 +2987,18 @@ mount itself.
...<other drives omitted for clarity>...
- source-drive ;; Must match the name you gave the source drive in the earlier definition.
+ ;; Must match the name you gave the source drive in the earlier definition.
+ source-drive
(file-system
- (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition.
+ ;; Make sure "source-directory" matches your earlier definition.
+ (device (%source-directory))
(mount-point "/tmp")
- (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none"
+ ;; We are mounting a folder, not a partition, so this type needs to be "none"
+ (type "none")
(flags '(bind-mount))
- (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive.
+ ;; Ensure "source-drive" matches what you've named the variable for the drive.
+ (dependencies (list source-drive))
)
...<other drives omitted for clarity>...
@@ -3036,8 +3047,8 @@ follow:
config => (guix-configuration
(inherit config)
;; ci.guix.gnu.org's Onion service
- (substitute-urls
- "@value{SUBSTITUTE-TOR-URL}")
+ (substitute-urls "\
+@value{SUBSTITUTE-TOR-URL}")
(http-proxy "http://localhost:9250")))))))
@end lisp
@@ -3279,12 +3290,14 @@ that should accomplish the above-mentioned tasks:
#~(string-append "\
# Declare Bluetooth audio device type \"bluealsa\" from bluealsa module
pcm_type.bluealsa @{
- lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_pcm_bluealsa.so") "\"
+ lib \""
+#$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_pcm_bluealsa.so") "\"
@}
# Declare control device type \"bluealsa\" from the same module
ctl_type.bluealsa @{
- lib \"" #$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_ctl_bluealsa.so") "\"
+ lib \""
+#$(file-append bluez-alsa "/lib/alsa-lib/libasound_module_ctl_bluealsa.so") "\"
@}
# Define the actual Bluetooth audio device.
@@ -4076,7 +4089,8 @@ We can create a manifest specification per profile and install them this way:
@example
GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles
mkdir -p "$GUIX_EXTRA_PROFILES"/my-project # if it does not exist yet
-guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
+guix package --manifest=/path/to/guix-my-project-manifest.scm \
+ --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
@end example
Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory
@@ -4149,7 +4163,8 @@ for the command line options.
To upgrade a profile, simply install the manifest again:
@example
-guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/my-project/my-project
+guix package -m /path/to/guix-my-project-manifest.scm \
+ -p "$GUIX_EXTRA_PROFILES"/my-project/my-project
@end example
To upgrade all profiles, it's easy enough to loop over them. For instance,
@@ -4159,7 +4174,8 @@ of the profile (e.g.@: "project1"), you could do the following in Bourne shell:
@example
for profile in "$GUIX_EXTRA_PROFILES"/*; do
- guix package --profile="$profile" --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm"
+ guix package --profile="$profile" \
+ --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm"
done
@end example
@@ -4337,7 +4353,9 @@ mkdir -p "$GUIX_EXTRA"/my-project
guix pull --channels=channel-specs.scm --profile="$GUIX_EXTRA/my-project/guix"
mkdir -p "$GUIX_EXTRA_PROFILES/my-project"
-"$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
+"$GUIX_EXTRA"/my-project/guix/bin/guix package \
+ --manifest=/path/to/guix-my-project-manifest.scm \
+ --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
@end example
It's safe to delete the Guix channel profile you've just installed with the
@@ -5071,12 +5089,13 @@ use_guix()
PACKAGES=(help2man guile-sqlite3 guile-gcrypt)
# Thanks <https://lists.gnu.org/archive/html/guix-devel/2016-09/msg00859.html>
- eval "$(guix environment --search-paths --root="$gcroot" --pure guix --ad-hoc $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} "$@@")"
+ eval "$(guix shell --search-paths --root="$gcroot" --pure \
+ --development guix $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} "$@@")"
# Predefine configure flags.
configure()
@{
- ./configure --localstatedir=/var --prefix=
+ ./configure
@}
export_function configure
@@ -5178,9 +5197,21 @@ startup file for @command{guix-daemon},
@code{--listen} argument to the @code{ExecStart} line so that it looks
something like this:
+@c Since Debian Buster, \ is documented to split lines.
+@c https://manpages.debian.org/buster/systemd/systemd.exec.5.en.html
+@c Use it in PDF and Info versions to avoid cut-off at the page border.
+@ifnothtml
+@example
+ExecStart=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon \
+ --build-users-group=guixbuild \
+ --listen=/var/guix/daemon-socket/socket --listen=0.0.0.0
+@end example
+@end ifnothtml
+@ifhtml
@example
ExecStart=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon --build-users-group=guixbuild --listen=/var/guix/daemon-socket/socket --listen=0.0.0.0
@end example
+@end ifhtml
For these changes to take effect, the service needs to be restarted:
diff --git a/doc/guix.texi b/doc/guix.texi
index 3f5d4e7f0d..9bbf85e32b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -53,7 +53,7 @@ Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@*
Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
-Copyright @copyright{} 2017, 2018, 2019, 2020, 2023 Arun Isaac@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2023, 2024 Arun Isaac@*
Copyright @copyright{} 2017 nee@*
Copyright @copyright{} 2018 Rutger Helling@*
Copyright @copyright{} 2018, 2021, 2023 Oleg Pykhalov@*
@@ -123,10 +123,12 @@ Copyright @copyright{} 2023 Foundation Devices, Inc.@*
Copyright @copyright{} 2023 Thomas Ieong@*
Copyright @copyright{} 2023 Saku Laesvuori@*
Copyright @copyright{} 2023 Graham James Addis@*
-Copyright @copyright{} 2023 Tomas Volf@*
+Copyright @copyright{} 2023, 2024 Tomas Volf@*
Copyright @copyright{} 2024 Herman Rimm@*
Copyright @copyright{} 2024 Matthew Trzcinski@*
Copyright @copyright{} 2024 Richard Sent@*
+Copyright @copyright{} 2024 Dariqq@*
+Copyright @copyright{} 2024 Denis 'GNUtoo' Carikli@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -742,7 +744,12 @@ 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}.
-For Debian or a derivative such as Ubuntu, call:
+We advise system administrators who install Guix, both from the
+installation script or @i{via} the native package manager of their
+foreign distribution, to also regularly read and follow security
+notices, as shown by @command{guix pull}.
+
+For Debian or derivatives such as Ubuntu or Trisquel, call:
@example
sudo apt install guix
@@ -754,6 +761,12 @@ Likewise, on openSUSE:
sudo zypper install guix
@end example
+If you are running Parabola, after enabling the pcr (Parabola
+Community Repo) repository, you can install Guix with:
+@example
+sudo pacman -S guix
+@end example
+
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
@@ -779,6 +792,13 @@ As root, run:
# ./guix-install.sh
@end example
+The script to install Guix is also packaged in Parabola (in the pcr
+repository). You can install and run it with:
+@example
+sudo pacman -S guix-installer
+sudo guix-install.sh
+@end example
+
@quotation Note
By default, @file{guix-install.sh} will configure Guix to download
pre-built package binaries, called @dfn{substitutes}
@@ -7314,6 +7334,8 @@ for Fortran development. For other languages, please use
@section Invoking @command{guix git authenticate}
@cindex @command{guix git authenticate}
+@cindex authentication, of Git checkouts
+@cindex Git checkout authentication
The @command{guix git authenticate} command authenticates a Git checkout
following the same rule as for channels (@pxref{channel-authentication,
@@ -7333,13 +7355,40 @@ The general syntax is:
guix git authenticate @var{commit} @var{signer} [@var{options}@dots{}]
@end example
+@cindex introduction, for Git authentication
By default, this command authenticates the Git checkout in the current
directory; it outputs nothing and exits with exit code zero on success
and non-zero on failure. @var{commit} above denotes the first commit
where authentication takes place, and @var{signer} is the OpenPGP
fingerprint of public key used to sign @var{commit}. Together, they
-form a ``channel introduction'' (@pxref{channel-authentication, channel
-introduction}). The options below allow you to fine-tune the process.
+form a @dfn{channel introduction} (@pxref{channel-authentication, channel
+introduction}). On your first successful run, the introduction is
+recorded in the @file{.git/config} file of your checkout, allowing you
+to omit them from subsequent invocations:
+
+@example
+guix git authenticate [@var{options}@dots{}]
+@end example
+
+Should you have branches that require different introductions, you can
+specify them directly in @file{.git/config}. For example, if the branch
+called @code{personal-fork} has a different introduction than other
+branches, you can extend @file{.git/config} along these lines:
+
+@smallexample
+[guix "authentication-personal-fork"]
+ introduction-commit = cabba936fd807b096b48283debdcddccfea3900d
+ introduction-signer = C0FF EECA BBA9 E6A8 0D1D E643 A2A0 6DF2 A33A 54FA
+ keyring = keyring
+@end smallexample
+
+The first run also attempts to install pre-push and post-merge hooks,
+such that @command{guix git authenticate} is invoked as soon as you run
+@command{git push}, @command{git pull}, and related commands; it does
+not overwrite preexisting hooks though.
+
+The command-line options described below allow you to fine-tune the
+process.
@table @code
@item --repository=@var{directory}
@@ -8209,8 +8258,8 @@ retrieve.
@item @code{url}
The URL of the Mercurial repository to clone.
-@item @code{revision}
-This string denotes revision to fetch specified as a number.
+@item @code{changeset}
+This string denotes changeset to fetch.
@end table
@end deftp
@@ -8273,6 +8322,43 @@ This string denotes revision to fetch specified as a number.
@end table
@end deftp
+For CVS repositories, the module @code{(guix cvs-download)} defines the
+@code{cvs-fetch} origin method and @code{cvs-reference} data type for
+support of the Concurrent Versions System (CVS).
+
+@deffn {Procedure} cvs-fetch ref hash-algo hash [name]
+Return a fixed-output derivation that fetches @var{ref}, a
+@code{<cvs-reference>} object. The output is expected to have recursive
+hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
+the file name, or a generic name if @code{#f}.
+@end deffn
+
+@deftp {Data Type} cvs-reference
+This data type represents a CVS reference for @code{cvs-fetch} to
+retrieve.
+
+@table @asis
+@item @code{root-directory}
+The CVS root directory.
+
+@item @code{module}
+Module to fetch.
+
+@item @code{revision}
+Revision to fetch.
+@end table
+
+The example below denotes a version of gnu-standards to fetch:
+
+@lisp
+(cvs-reference
+ (root-directory ":pserver:anonymous@@cvs.savannah.gnu.org:/sources/gnustandards")
+ (module "gnustandards")
+ (revision "2020-11-25"))
+@end lisp
+
+@end deftp
+
@node Defining Package Variants
@section Defining Package Variants
@@ -12125,6 +12211,18 @@ When @var{recursive?} is true, call @code{(@var{select?} @var{file}
absolute file name and @var{stat} is the result of @code{lstat}; exclude
entries for which @var{select?} does not return true.
+@var{file} can be wrapped in the @code{assume-valid-file-name} syntactic
+keyword. When this is done, there will not be a warning when
+@code{local-file} is used with a non-literal path. The path is still
+looked up relative to the current working directory at run time.
+Wrapping is done like this:
+
+@lisp
+(define alice-key-file-path "alice.pub")
+;; ...
+(local-file (assume-valid-file-name alice-key-file-path))
+@end lisp
+
This is the declarative counterpart of the @code{interned-file} monadic
procedure (@pxref{The Store Monad, @code{interned-file}}).
@end deffn
@@ -14366,6 +14464,39 @@ and generate package expressions for all those packages that are not yet
in Guix.
@end table
+@item npm-binary
+@cindex npm
+@cindex Node.js
+Import metadata from the @uref{https://registry.npmjs.org, npm
+Registry}, as in this example:
+
+@example
+guix import npm-binary buffer-crc32
+@end example
+
+The npm-binary importer also allows you to specify a version string:
+
+@example
+guix import npm-binary buffer-crc32@@1.0.0
+@end example
+
+@quotation Note
+Generated package expressions skip the build step of the
+@code{node-build-system}. As such, generated package expressions often
+refer to transpiled or generated files, instead of being built from
+source.
+@end quotation
+
+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.
+@end table
+
@item opam
@cindex OPAM
@cindex OCaml
@@ -17146,10 +17277,10 @@ version:
%base-packages)))
@end lisp
-@findex specification->package+output
+@findex specifications->packages
When a package has more than one output it can be a challenge to refer to a
specific output instead of just to the standard @code{out} output. For these
-situations one can use the @code{specification->package+output} procedure from
+situations one can use the @code{specifications->packages} procedure from
the @code{(gnu packages)} module. For example:
@lisp
@@ -17157,8 +17288,8 @@ the @code{(gnu packages)} module. For example:
(operating-system
;; ...
- (packages (append (map specification->package+output
- '("git" "git:send-email"))
+ (packages (append (specifications->packages
+ '("git" "git:send-email"))
%base-packages)))
@end lisp
@@ -17750,6 +17881,20 @@ a dependency of @file{/sys/fs/cgroup/cpu} and
Another example is a file system that depends on a mapped device, for
example for an encrypted partition (@pxref{Mapped Devices}).
+
+@item @code{shepherd-requirements} (default: @code{'()})
+This is a list of symbols denoting Shepherd requirements that must be
+met before mounting the file system.
+
+As an example, an NFS file system would typically have a requirement for
+@code{networking}.
+
+Typically, file systems are mounted before most other Shepherd services
+are started. However, file systems with a non-empty
+shepherd-requirements field are mounted after Shepherd services have
+begun. Any Shepherd service that depends on a file system with a
+non-empty shepherd-requirements field must depend on it directly and not
+on the generic symbol @code{file-systems}.
@end table
@end deftp
@@ -19346,9 +19491,11 @@ the nscd---e.g., @code{(list @var{nss-mdns})}.
Package object denoting the GNU C Library providing the @command{nscd}
command.
-@item @code{log-file} (default: @code{"/var/log/nscd.log"})
-Name of the nscd log file. This is where debugging output goes when
-@code{debug-level} is strictly positive.
+@item @code{log-file} (default: @code{#f})
+Name of the nscd log file. Debugging output goes to that file when
+@code{debug-level} is strictly positive, or to standard error if it is
+@code{#f}. Regular messages are written to syslog when
+@code{debug-level} is zero, regardless of the value of @code{log-file}.
@item @code{debug-level} (default: @code{0})
Integer denoting the debugging levels. Higher numbers mean that more
@@ -23511,6 +23658,17 @@ in @var{config}, are available. The result should be used in place of
Usually the X server is started by a login manager.
@end deffn
+@deffn {Procedure} xorg-start-command-xinit [config]
+Return a @code{startx} script in which the modules, fonts,
+etc. specified in @var{config} are available. The result should be used
+in place of @code{startx} and should be invoked by the user from a tty
+after login. Unlike @code{xorg-start-command}, this script calls xinit.
+Therefore it works well when executed from a tty. This script can be
+set up as @code{startx} using @code{startx-command-service-type} or
+@code{home-startx-command-service-type}. If you are using a desktop
+environment, you are unlikely to need this procedure.
+@end deffn
+
@defvar screen-locker-service-type
Type for a service that adds a package for a screen locker or screen
@@ -23570,6 +23728,14 @@ Whether to setup program as setuid binary.
@end deftp
+@defvar startx-command-service-type
+Add @command{startx} to the system profile putting it onto @env{PATH}.
+
+The value for this service is a @code{<xorg-configuration>} object which
+is passed to the @code{xorg-start-command-xinit} procedure producing the
+@command{startx} used. Default value is @code{(xorg-configuration)}.
+@end defvar
+
@node Printing Services
@subsection Printing Services
@@ -28082,23 +28248,195 @@ Mailutils Manual}, for details.
@cindex CardDAV
@defvar radicale-service-type
-This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
-server whose value should be a @code{radicale-configuration}.
+This is the type of the @uref{https://radicale.org, Radicale}
+CalDAV/CardDAV server whose value should be a
+@code{radicale-configuration}. The default configuration matches the
+@uref{https://radicale.org/v3.html#configuration, upstream
+documentation}.
@end defvar
@deftp {Data Type} radicale-configuration
Data type representing the configuration of @command{radicale}.
+Available @code{radicale-configuration} fields are:
@table @asis
-@item @code{package} (default: @code{radicale})
-The package that provides @command{radicale}.
+@item @code{package} (default: @code{radicale}) (type: package)
+Package that provides @command{radicale}.
-@item @code{config-file} (default: @code{%default-radicale-config-file})
-File-like object of the configuration file to use, by default it will listen
-on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at
-@file{/var/lib/radicale/users} with no (@code{plain}) encryption.
+@item @code{auth} (default: @code{'()}) (type: radicale-auth-configuration)
+Configuration for auth-related variables.
+
+@deftp {Data Type} radicale-auth-configuration
+Data type representing the @code{auth} section of a @command{radicale}
+configuration file. Available @code{radicale-auth-configuration} fields
+are:
+
+@table @asis
+@item @code{type} (default: @code{'none}) (type: symbol)
+The method to verify usernames and passwords. Options are @code{none},
+@code{htpasswd}, @code{remote-user}, and @code{http-x-remote-user}.
+This value is tied to @code{htpasswd-filename} and
+@code{htpasswd-encryption}.
+
+@item @code{htpasswd-filename} (default: @code{"/etc/radicale/users"}) (type: file-name)
+Path to the htpasswd file. Use htpasswd or similar to generate this
+file.
+
+@item @code{htpasswd-encryption} (default: @code{'md5}) (type: symbol)
+Encryption method used in the htpasswd file. Options are @code{plain},
+@code{bcrypt}, and @code{md5}.
+
+@item @code{delay} (default: @code{1}) (type: non-negative-integer)
+Average delay after failed login attempts in seconds.
+
+@item @code{realm} (default: @code{"Radicale - Password Required"}) (type: string)
+Message displayed in the client when a password is needed.
+
+@end table
+
+@end deftp
+
+@item @code{encoding} (default: @code{'()}) (type: radicale-encoding-configuration)
+Configuration for encoding-related variables.
+
+@deftp {Data Type} radicale-encoding-configuration
+Data type representing the @code{encoding} section of a
+@command{radicale} configuration file. Available
+@code{radicale-encoding-configuration} fields are:
+
+@table @asis
+@item @code{request} (default: @code{'utf-8}) (type: symbol)
+Encoding for responding requests.
+
+@item @code{stock} (default: @code{'utf-8}) (type: symbol)
+Encoding for storing local collections.
+
+@end table
+
+@end deftp
+
+@item @code{headers-file} (default: none) (type: file-like)
+Custom HTTP headers.
+
+@item @code{logging} (default: @code{'()}) (type: radicale-logging-configuration)
+Configuration for logging-related variables.
+
+@deftp {Data Type} radicale-logging-configuration
+Data type representing the @code{logging} section of a
+@command{radicale} configuration file. Available
+@code{radicale-logging-configuration} fields are:
+
+@table @asis
+@item @code{level} (default: @code{'warning}) (type: symbol)
+Set the logging level. One of @code{debug}, @code{info},
+@code{warning}, @code{error}, or @code{critical}.
+
+@item @code{mask-passwords?} (default: @code{#t}) (type: boolean)
+Whether to include passwords in logs.
+
+@end table
+
+@end deftp
+
+@item @code{rights} (default: @code{'()}) (type: radicale-rights-configuration)
+Configuration for rights-related variables. This should be a
+@code{radicale-rights-configuration}.
+
+@deftp {Data Type} radicale-rights-configuration
+Data type representing the @code{rights} section of a @command{radicale}
+configuration file. Available @code{radicale-rights-configuration}
+fields are:
+
+@table @asis
+@item @code{type} (default: @code{'owner-only}) (type: symbol)
+Backend used to check collection access rights. The recommended backend
+is @code{owner-only}. If access to calendars and address books outside
+the home directory of users is granted, clients won't detect these
+collections and will not show them to the user. Choosing any other
+method is only useful if you access calendars and address books directly
+via URL. Options are @code{authenticate}, @code{owner-only},
+@code{owner-write}, and @code{from-file}.
+
+@item @code{file} (default: @code{""}) (type: file-name)
+File for the rights backend @code{from-file}.
@end table
+
+@end deftp
+
+@item @code{server} (default: @code{'()}) (type: radicale-server-configuration)
+Configuration for server-related variables. Ignored if WSGI is used.
+
+@deftp {Data Type} radicale-server-configuration
+Data type representing the @code{server} section of a @command{radicale}
+configuration file. Available @code{radicale-server-configuration}
+fields are:
+
+@table @asis
+@item @code{hosts} (default: @code{(list "localhost:5232")}) (type: list-of-ip-addresses)
+List of IP addresses that the server will bind to.
+
+@item @code{max-connections} (default: @code{8}) (type: non-negative-integer)
+Maximum number of parallel connections. Set to 0 to disable the limit.
+
+@item @code{max-content-length} (default: @code{100000000}) (type: non-negative-integer)
+Maximum size of the request body in bytes.
+
+@item @code{timeout} (default: @code{30}) (type: non-negative-integer)
+Socket timeout in seconds.
+
+@item @code{ssl?} (default: @code{#f}) (type: boolean)
+Whether to enable transport layer encryption.
+
+@item @code{certificate} (default: @code{"/etc/ssl/radicale.cert.pem"}) (type: file-name)
+Path of the SSL certificate.
+
+@item @code{key} (default: @code{"/etc/ssl/radicale.key.pem"}) (type: file-name)
+Path to the private key for SSL. Only effective if @code{ssl?} is
+@code{#t}.
+
+@item @code{certificate-authority} (default: @code{""}) (type: file-name)
+Path to CA certificate for validating client certificates. This can be
+used to secure TCP traffic between Radicale and a reverse proxy. If you
+want to authenticate users with client-side certificates, you also have
+to write an authentication plugin that extracts the username from the
+certificate.
+
+@end table
+
+@end deftp
+
+@item @code{storage} (default: @code{'()}) (type: radicale-storage-configuration)
+Configuration for storage-related variables.
+
+@deftp {Data Type} radicale-storage-configuration
+Data type representing the @code{storage} section of a
+@command{radicale} configuration file. Available
+@code{radicale-storage-configuration} fields are:
+
+@table @asis
+@item @code{type} (default: @code{'multifilesystem}) (type: symbol)
+Backend used to store data. Options are @code{multifilesystem} and
+@code{multifilesystem-nolock}.
+
+@item @code{filesystem-folder} (default: @code{"/var/lib/radicale/collections"}) (type: file-name)
+Folder for storing local collections. Created if not present.
+
+@item @code{max-sync-token-age} (default: @code{2592000}) (type: non-negative-integer)
+Delete sync-tokens that are older than the specified time in seconds.
+
+@item @code{hook} (default: @code{""}) (type: string)
+Command run after changes to storage.
+
+@end table
+
+@end deftp
+
+@item @code{web-interface?} (default: @code{#t}) (type: boolean)
+Whether to use Radicale's built-in web interface.
+
+@end table
+
@end deftp
@subsubheading Rspamd Service
@@ -33469,6 +33807,10 @@ separated by dashes, e.g.: @samp{01-02-03-04-aa-bb}. Note that
resolving MAC addresses is only possible if the client is in the local
network or obtained a DHCP lease from dnsmasq.
+@item @code{extra-options} (default: @code{'()})
+This option provides an ``escape hatch'' for the user to provide arbitrary
+command-line arguments to @command{dnsmasq} as a list of strings.
+
@end table
@end deftp
@@ -34366,7 +34708,7 @@ the packages provided by the @code{my-channel} channel.
@lisp
(define %cuirass-specs
#~(list (specification
- (name "my-channel")
+ (name 'my-channel)
(build '(channels my-channel))
(channels
(cons (channel
@@ -34385,7 +34727,7 @@ channel, one can use the following configuration.
@lisp
(define %cuirass-specs
#~(list (specification
- (name "my-linux")
+ (name 'my-linux)
(build '(packages "linux-libre")))))
(service cuirass-service-type
@@ -34427,6 +34769,12 @@ Owner's group of the @code{cuirass} process.
Number of seconds between the poll of the repositories followed by the
Cuirass jobs.
+@item @code{ttl} (default: @code{2592000})
+Duration to keep build results' GC roots alive, in seconds.
+
+@item @code{threads} (default: @code{#f})
+Number of kernel threads to use for Cuirass. The default value should be appropriate for most cases.
+
@item @code{parameters} (default: @code{#f})
Read parameters from the given @var{parameters} file. The supported
parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
@@ -34453,10 +34801,6 @@ A gexp (@pxref{G-Expressions}) that evaluates to a list of
specifications records. The specification record is described in the
Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
-@item @code{use-substitutes?} (default: @code{#f})
-This allows using substitutes to avoid building every dependencies of a job
-from source.
-
@item @code{one-shot?} (default: @code{#f})
Only evaluate specifications and build derivations once.
@@ -34465,7 +34809,10 @@ When substituting a pre-built binary fails, fall back to building
packages locally.
@item @code{extra-options} (default: @code{'()})
-Extra options to pass when running the Cuirass processes.
+Extra options to pass when running the @code{cuirass register} process.
+
+@item @code{web-extra-options} (default: @code{'()})
+Extra options to pass when running the @code{cuirass web} process.
@end table
@end deftp
@@ -34640,6 +34987,45 @@ Base URL to use for links to laminar itself.
@node Power Management Services
@subsection Power Management Services
+@cindex power-profiles-daemon
+@subsubheading Power Profiles Daemon
+
+The @code{(gnu services pm)} module provides a Guix service definition for
+the Linux Power Profiles Daemon, which makes power profiles handling
+available over D-Bus.
+
+The available profiles consist of the default @samp{balanced} mode, a @samp{power-saver} mode
+and on supported systems a @samp{performance} mode.
+
+@quotation Important
+The @code{power-profiles-daemon} conflicts with other power management tools
+like @code{tlp}. Using both together is not recommended.
+@end quotation
+
+@defvar power-profiles-daemon-service-type
+This is the service type for the
+@uref{https://gitlab.freedesktop.org/upower/power-profiles-daemon/, Power Profiles Daemon}.
+The value for this service is a @code{power-profiles-daemon-configuration}.
+
+To enable the Power Profiles Daemon with default configuration
+add this line to your services:
+
+@lisp
+(service power-profiles-daemon-service-type)
+@end lisp
+@end defvar
+
+@deftp {Data Type} power-profiles-daemon-configuration
+Data type representing the configuration of @code{power-profiles-daemon-service-type}.
+
+@table @asis
+@item @code{power-profiles-daemon} (default: @code{power-profiles-daemon}) (type: file-like)
+Package object of power-profiles-daemon.
+
+@end table
+@end deftp
+
+
@cindex tlp
@cindex power management with TLP
@subsubheading TLP daemon
@@ -38764,7 +39150,7 @@ footers.
(index-title "My git repositories")
(intro '((p "This is all my public work!")))
(footer '((p "This is the end")))
- (nginx-server-block
+ (nginx
(nginx-server-configuration
(ssl-certificate
"/etc/certs/myweb.site/fullchain.pem")
@@ -38859,7 +39245,7 @@ of repositories, on the index page.
The footer content, as a list of sxml expressions. This is shown on every
page served by Gitile.
-@item @code{nginx-server-block}
+@item @code{nginx}
An nginx server block that will be extended and used as a reverse proxy by
Gitile to serve its pages, and as a normal web server to serve its assets.
@@ -39440,7 +39826,7 @@ 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
+(simple-service 'my-extra-home guix-home-service-type
`(("bob" ,my-extra-home))))
@end lisp
@end defvar
@@ -40391,6 +40777,17 @@ processes as Shepherd Services.
(service oci-container-service-type
(list
(oci-container-configuration
+ (image
+ (oci-image
+ (repository "guile")
+ (tag "3")
+ (value (specifications->manifest '("guile")))
+ (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
+ #:max-layers 2))))
+ (entrypoint "/bin/guile")
+ (command
+ '("-c" "(display \"hello!\n\")")))
+ (oci-container-configuration
(image "prom/prometheus")
(network "host")
(ports
@@ -40430,13 +40827,30 @@ The user under whose authority docker commands will be run.
@item @code{group} (default: @code{"docker"}) (type: string)
The group under whose authority docker commands will be run.
-@item @code{command} (default: @code{()}) (type: list-of-strings)
+@item @code{command} (default: @code{'()}) (type: list-of-strings)
Overwrite the default command (@code{CMD}) of the image.
@item @code{entrypoint} (default: @code{""}) (type: string)
Overwrite the default entrypoint (@code{ENTRYPOINT}) of the image.
-@item @code{environment} (default: @code{()}) (type: list)
+@item @code{host-environment} (default: @code{'()}) (type: list)
+Set environment variables in the host environment where @command{docker
+run} is invoked. This is especially useful to pass secrets from the
+host to the container without having them on the @command{docker run}'s
+command line: by setting the @code{MYSQL_PASSWORD} on the host and by passing
+@code{--env MYSQL_PASSWORD} through the @code{extra-arguments} field, it is
+possible to securely set values in the container environment. This field's
+value can be a list of pairs or strings, even mixed:
+
+@lisp
+(list '(\"LANGUAGE\" . \"eo:ca:eu\")
+ \"JAVA_HOME=/opt/java\")
+@end lisp
+
+Pair members can be strings, gexps or file-like objects. Strings are passed
+directly to @code{make-forkexec-constructor}.
+
+@item @code{environment} (default: @code{'()}) (type: list)
Set environment variables. This can be a list of pairs or strings, even mixed:
@lisp
@@ -40444,22 +40858,28 @@ Set environment variables. This can be a list of pairs or strings, even mixed:
"JAVA_HOME=/opt/java")
@end lisp
-String are passed directly to the Docker CLI. You can refer to the
+Pair members can be strings, gexps or file-like objects.
+Strings are passed directly to the Docker CLI. You can refer to the
@uref{https://docs.docker.com/engine/reference/commandline/run/#env,upstream}
documentation for semantics.
-@item @code{image} (type: string)
-The image used to build the container. Images are resolved by the
-Docker Engine, and follow the usual format
+@item @code{image} (type: string-or-oci-image)
+The image used to build the container. It can be a string or an
+@code{oci-image} record. Strings are resolved by the Docker Engine, and
+follow the usual format
@code{myregistry.local:5000/testing/test-image:tag}.
@item @code{provision} (default: @code{""}) (type: string)
Set the name of the provisioned Shepherd service.
+@item @code{requirement} (default: @code{'()}) (type: list-of-symbols)
+Set additional Shepherd services dependencies to the provisioned
+Shepherd service.
+
@item @code{network} (default: @code{""}) (type: string)
Set a Docker network for the spawned container.
-@item @code{ports} (default: @code{()}) (type: list)
+@item @code{ports} (default: @code{'()}) (type: list)
Set the port or port ranges to expose from the spawned container. This can be a
list of pairs or strings, even mixed:
@@ -40468,11 +40888,12 @@ list of pairs or strings, even mixed:
"10443:443")
@end lisp
-String are passed directly to the Docker CLI. You can refer to the
+Pair members can be strings, gexps or file-like objects.
+Strings are passed directly to the Docker CLI. You can refer to the
@uref{https://docs.docker.com/engine/reference/commandline/run/#publish,upstream}
documentation for semantics.
-@item @code{volumes} (default: @code{()}) (type: list)
+@item @code{volumes} (default: @code{'()}) (type: list)
Set volume mappings for the spawned container. This can be a
list of pairs or strings, even mixed:
@@ -40481,7 +40902,8 @@ list of pairs or strings, even mixed:
"/gnu/store:/gnu/store")
@end lisp
-String are passed directly to the Docker CLI. You can refer to the
+Pair members can be strings, gexps or file-like objects.
+Strings are passed directly to the Docker CLI. You can refer to the
@uref{https://docs.docker.com/engine/reference/commandline/run/#volume,upstream}
documentation for semantics.
@@ -40496,6 +40918,62 @@ You can refer to the
@url{https://docs.docker.com/engine/reference/run/#workdir,upstream}
documentation for semantics.
+@item @code{extra-arguments} (default: @code{'()}) (type: list)
+A list of strings, gexps or file-like objects that will be directly
+passed to the @command{docker run} invokation.
+
+@end table
+
+@end deftp
+
+
+@c %end of fragment
+
+@c %start of fragment
+
+@deftp {Data Type} oci-image
+Available @code{oci-image} fields are:
+
+@table @asis
+@item @code{repository} (type: string)
+A string like @code{myregistry.local:5000/testing/test-image} that names
+the OCI image.
+
+@item @code{tag} (default: @code{"latest"}) (type: string)
+A string representing the OCI image tag. Defaults to @code{latest}.
+
+@item @code{value} (type: oci-lowerable-image)
+A @code{manifest} or @code{operating-system} record that will be lowered
+into an OCI compatible tarball. Otherwise this field's value can be a
+gexp or a file-like object that evaluates to an OCI compatible tarball.
+
+@item @code{pack-options} (default: @code{'()}) (type: list)
+An optional set of keyword arguments that will be passed to the
+@code{docker-image} procedure from @code{guix scripts pack}. They can
+be used to replicate @command{guix pack} behavior:
+
+@lisp
+(oci-image
+ (repository "guile")
+ (tag "3")
+ (value
+ (specifications->manifest '("guile")))
+ (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
+ #:max-layers 2)))
+@end lisp
+
+If the @code{value} field is an @code{operating-system} record, this field's
+value will be ignored.
+
+@item @code{system} (default: @code{""}) (type: string)
+Attempt to build for a given system, e.g. "i686-linux"
+
+@item @code{target} (default: @code{""}) (type: string)
+Attempt to cross-build for a given triple, e.g. "aarch64-linux-gnu"
+
+@item @code{grafts?} (default: @code{#f}) (type: boolean)
+Whether to allow grafting or not in the pack build.
+
@end table
@end deftp
@@ -40635,7 +41113,7 @@ After @command{guix system reconfigure} configure Nix for your user:
@itemize
@item Add a Nix channel and update it. See
-@url{https://nixos.wiki/wiki/Nix_channels, Nix channels} for more
+@url{https://wiki.nixos.org/wiki/Nix_channels, Nix channels} for more
information about the available channels. If you would like to use the
unstable Nix channel you can do this by running:
@@ -40946,6 +41424,122 @@ Mode for filter.
@c End of auto-generated fail2ban documentation.
+@cindex Backup
+@subsubheading Backup Services
+
+The @code{(gnu services backup)} module offers services for backing up
+file system trees. For now, it provides the @code{restic-backup-service-type}.
+
+With @code{restic-backup-service-type}, you can periodically back up
+directories and files with @uref{https://restic.net/, Restic}, which
+supports end-to-end encryption and deduplication. Consider the
+following configuration:
+
+@lisp
+(use-service-modules backup @dots{}) ;for 'restic-backup-service-type'
+(use-package-modules sync @dots{}) ;for 'rclone'
+
+(operating-system
+ ;; @dots{}
+ (packages (append (list rclone) ;for use by restic
+ %base-packages))
+ (services
+ (list
+ (service restic-backup-service-type
+ (restic-backup-configuration
+ (jobs
+ (list (restic-backup-job
+ (name "remote-ftp")
+ (repository "rclone:remote-ftp:backup/restic")
+ (password-file "/root/.restic")
+ ;; Every day at 23.
+ (schedule "0 23 * * *")
+ (files '("/root/.restic"
+ "/root/.config/rclone"
+ "/etc/ssh/ssh_host_rsa_key"
+ "/etc/ssh/ssh_host_rsa_key.pub"
+ "/etc/guix/signing-key.pub"
+ "/etc/guix/signing-key.sec"))))))))))
+@end lisp
+
+Each @code{restic-backup-job} translates to an mcron job which sets the
+@env{RESTIC_PASSWORD} environment variable by reading the first line of
+@code{password-file} and runs @command{restic backup}, creating backups
+using rclone of all the files listed in the @code{files} field.
+
+The @code{restic-backup-service-type} installs as well @code{restic-guix}
+to the system profile, a @code{restic} utility wrapper that allows for easier
+interaction with the Guix configured backup jobs. For example the following
+could be used to instantaneusly trigger a backup for the above shown
+configuration, without waiting for the scheduled job:
+
+@example
+restic-guix backup remote-ftp
+@end example
+
+@c %start of fragment
+
+@deftp {Data Type} restic-backup-configuration
+Available @code{restic-backup-configuration} fields are:
+
+@table @asis
+@item @code{jobs} (default: @code{'()}) (type: list-of-restic-backup-jobs)
+The list of backup jobs for the current system.
+
+@end table
+
+@end deftp
+
+
+@c %end of fragment
+
+@c %start of fragment
+
+@deftp {Data Type} restic-backup-job
+Available @code{restic-backup-job} fields are:
+
+@table @asis
+@item @code{restic} (default: @code{restic}) (type: package)
+The restic package to be used for the current job.
+
+@item @code{user} (default: @code{"root"}) (type: string)
+The user used for running the current job.
+
+@item @code{repository} (type: string)
+The restic repository target of this job.
+
+@item @code{name} (type: string)
+A string denoting a name for this job.
+
+@item @code{password-file} (type: string)
+Name of the password file, readable by the configured @code{user},
+that will be used to set the @env{RESTIC_PASSWORD} environment variable
+for the current job.
+
+@item @code{schedule} (type: gexp-or-string)
+A string or a gexp that will be passed as time specification in the
+mcron job specification (@pxref{Syntax, mcron job specifications,,
+mcron,GNU@tie{}mcron}).
+
+@item @code{files} (default: @code{'()}) (type: list-of-lowerables)
+The list of files or directories to be backed up. It must be a list of
+values that can be lowered to strings.
+
+@item @code{verbose?} (default: @code{#f}) (type: boolean)
+Whether to enable verbose output for the current backup job.
+
+@item @code{extra-flags} (default: @code{'()}) (type: list-of-lowerables)
+A list of values that are lowered to strings. These will be passed as
+command-line arguments to the current job @command{restic backup}
+invokation.
+
+@end table
+
+@end deftp
+
+
+@c %end of fragment
+
@node Setuid Programs
@section Setuid Programs
@@ -42216,7 +42810,7 @@ image=$(guix system image --image-type=qcow2 \
cp $image /tmp/my-image.qcow2
chmod +w /tmp/my-image.qcow2
qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \
- -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin
+ -bios $(guix build ovmf-x86-64)/share/firmware/ovmf_x64.bin
@end example
When using the @code{mbr-hybrid-raw} image type, a raw disk image is
@@ -45881,6 +46475,15 @@ The list of expressions to be read by @code{xmodmap} on service startup.
@end table
@end deftp
+@defvar home-startx-command-service-type
+Add @command{startx} to the home profile putting it onto @env{PATH}.
+
+The value for this service is a @code{<xorg-configuration>} object which
+is passed to the @code{xorg-start-command-xinit} procedure producing the
+@command{startx} used. Default value is @code{(xorg-configuration)}.
+@end defvar
+
+
@node Guix Home Services
@subsection Guix Home Services
diff --git a/doc/htmlxref.cnf b/doc/htmlxref.cnf
index 73a53e9551..dc819a92ad 100644
--- a/doc/htmlxref.cnf
+++ b/doc/htmlxref.cnf
@@ -1,7 +1,7 @@
# htmlxref.cnf - reference file for free Texinfo manuals on the web.
# Modified by Ludovic Courtès <ludo@gnu.org> for the GNU Guix manual.
-htmlxrefversion=2024-03-31.22; # UTC
+htmlxrefversion=2024-06-02.15; # UTC
# Copyright 2010-2020, 2022 Free Software Foundation, Inc.
#
@@ -442,6 +442,8 @@ GUIX_COOKBOOK = ${GUIX_ROOT}/cookbook
guix-cookbook.pt_BR node ${GUIX_COOKBOOK}/pt-br/html_node/
guix-cookbook.sk mono ${GUIX_COOKBOOK}/sk/guix-cookbook.sk.html
guix-cookbook.sk node ${GUIX_COOKBOOK}/sk/html_node/
+ guix-cookbook.sv mono ${GUIX_COOKBOOK}/sv/guix-cookbook.sv.html
+ guix-cookbook.sv node ${GUIX_COOKBOOK}/sv/html_node/
guix-cookbook mono ${GUIX_COOKBOOK}/en/guix-cookbook.html
guix-cookbook node ${GUIX_COOKBOOK}/en/html_node/
diff --git a/doc/local.mk b/doc/local.mk
index 1d94e3c758..b81172939b 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -7,6 +7,7 @@
# Copyright © 2018, 2021 Julien Lepiller <julien@lepiller.eu>
# Copyright © 2019 Timothy Sample <samplet@ngyro.com>
# Copyright © 2024 Janneke Nieuwenhuizen <janneke@gnu.org>
+# Copyright © 2024 gemmaro <gemmaro.dev@gmail.com>
#
# This file is part of GNU Guix.
#
@@ -25,7 +26,7 @@
# If adding a language, update the following variables, and info_TEXINFOS.
MANUAL_LANGUAGES = de es fr pt_BR ru zh_CN
-COOKBOOK_LANGUAGES = de fr ko pt_BR sk
+COOKBOOK_LANGUAGES = de fr ko pt_BR sk sv
# Arg1: A list of languages codes.
# Arg2: The file name stem.
@@ -45,7 +46,8 @@ info_TEXINFOS = %D%/guix.texi \
%D%/guix-cookbook.fr.texi \
%D%/guix-cookbook.ko.texi \
%D%/guix-cookbook.pt_BR.texi \
- %D%/guix-cookbook.sk.texi
+ %D%/guix-cookbook.sk.texi \
+ %D%/guix-cookbook.sv.texi
%C%_guix_TEXINFOS = \
%D%/contributing.texi \
@@ -89,10 +91,6 @@ BUILT_SOURCES += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
EXTRA_DIST += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
MAINTAINERCLEANFILES = $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
-PO4A_PARAMS := -M UTF-8 -L UTF-8 #master and localized encoding
-PO4A_PARAMS += -k 0 # produce an output even if the translation is not complete
-PO4A_PARAMS += -f texinfo # texinfo format
-
# When a change to guix.texi occurs, it is not translated immediately.
# Because @pxref and @xref commands are references to sections by name, they
# should be translated. If a modification adds a reference to a section, this
@@ -104,20 +102,39 @@ $(top_srcdir)/pre-inst-env $(GUILE) --no-auto-compile \
$@.tmp $<
endef
+# If /dev/null is used for this POT file path, a warning will be issued
+# because the path extension is not 'pot'.
+dummy_pot = $(shell mktemp --suffix=.pot)
+
$(srcdir)/%D%/guix.%.texi: po/doc/guix-manual.%.po $(srcdir)/%D%/contributing.%.texi guix/build/po.go
- -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix.texi" -p "$<" -l "$@.tmp"
+ -$(AM_V_PO4A)$(PO4A) --no-update \
+ --variable localized="$@.tmp" \
+ --variable master="%D%/guix.texi" \
+ --variable po="$<" \
+ --variable pot=$(dummy_pot) \
+ po/doc/po4a.cfg
-sed -i "s|guix\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
-mv "$@.tmp" "$@"
$(srcdir)/%D%/guix-cookbook.%.texi: po/doc/guix-cookbook.%.po guix/build/po.go
- -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix-cookbook.texi" -p "$<" -l "$@.tmp"
+ -$(AM_V_PO4A)$(PO4A) --no-update \
+ --variable localized="$@.tmp" \
+ --variable master="%D%/guix-cookbook.texi" \
+ --variable po="$<" \
+ --variable pot=$(dummy_pot) \
+ po/doc/po4a.cfg
-sed -i "s|guix-cookbook\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
-mv "$@.tmp" "$@"
$(srcdir)/%D%/contributing.%.texi: po/doc/guix-manual.%.po guix/build/po.go
- -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/contributing.texi" -p "$<" -l "$@.tmp"
+ -$(AM_V_PO4A)$(PO4A) --no-update \
+ --variable localized="$@.tmp" \
+ --variable master="%D%/contributing.texi" \
+ --variable po="$<" \
+ --variable pot=$(dummy_pot) \
+ po/doc/po4a.cfg
-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
-mv "$@.tmp" "$@"
generated by cgit v1.2.3 (git 2.44.0) at 2024-06-26 08:07:24 +0000