diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.scm | 8 | ||||
| -rw-r--r-- | doc/contributing.texi | 867 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 214 | ||||
| -rw-r--r-- | doc/guix.texi | 2321 | ||||
| -rw-r--r-- | doc/htmlxref.cnf | 4 | ||||
| -rw-r--r-- | doc/local.mk | 35 |
6 files changed, 2977 insertions, 472 deletions
diff --git a/doc/build.scm b/doc/build.scm index 20d6624653..7a2b562028 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2019-2023 Ludovic Courtès <ludo@gnu.org> +;;; Copyright © 2019-2024 Ludovic Courtès <ludo@gnu.org> ;;; Copyright © 2020 Björn Höfling <bjoern.hoefling@bjoernhoefling.de> ;;; Copyright © 2022 Maxim Cournoyer <maxim.cournoyer@gmail.com> ;;; @@ -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. @@ -1061,8 +1061,7 @@ must be the Guix top-level source directory, from which PO files are taken." (bindtextdomain "guix-manual" #+(guix-manual-text-domain source)) (bindtextdomain "iso_639-3" ;language names - #+(file-append iso-codes - "/share/locale")) + #+(file-append iso-codes "/share/locale")) (setenv "LANGUAGE" ,language) (write (gettext ,str ,domain)))) @@ -1299,6 +1298,7 @@ commit date (an integer)." (setenv "PATH" (string-append #+tar "/bin:" #+xz "/bin:" + #+zstd "/bin:" #+texinfo "/bin")) (invoke "tar" "xf" #$(package-source guile)) (mkdir-p (string-append #$output "/en/html_node")) diff --git a/doc/contributing.texi b/doc/contributing.texi index 66f4e86d0a..d4784de452 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -31,11 +31,15 @@ choice. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. * Tracking Bugs and Changes:: Keeping it all organized. +* Teams:: Coordinating efforts. +* Making Decisions:: Collectively choosing the way forward. * Commit Access:: Pushing to the official repository. * Reviewing the Work of Others:: Some guidelines for sharing reviews. * Updating the Guix Package:: Updating the Guix package definition. +* Deprecation Policy:: Commitments and tools for deprecation. * Writing Documentation:: Improving documentation in GNU Guix. * Translating Guix:: Make Guix speak your native language. +* Contributing to Guix's Infrastructure:: Make Guix ecosystem work better. @end menu @node Requirements @@ -235,29 +239,17 @@ more information. Then, run: @example -./configure --localstatedir=/var --sysconfdir=/etc +./configure @end example @noindent -... where @file{/var} is the normal @code{localstatedir} value -(@pxref{The Store}, for information about this) and @file{/etc} is the -normal @code{sysconfdir} value. Note that you will probably not run -@command{make install} at the end (you don't have to) but it's still -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. +Optionally, @code{--localstatedir} and @code{--sysconfdir} can also be +provided as arguments. By default, @code{localstatedir} is @file{/var} +(@pxref{The Store}, for information about this) and @code{sysconfdir} is +@file{/etc}. Note that you will probably not run @command{make install} +at the end (you don't have to) but it's still important to pass the +right @code{localstatedir} and @code{sysconfdir} values, which get +recorded in the @code{(guix config)} Guile module. Finally, you can build Guix and, if you feel so inclined, run the tests (@pxref{Running the Test Suite}): @@ -276,25 +268,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.}: -Or, when your configuration for your local Git repository doesn't match +@example +guix git authenticate +@end example + +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 @@ -408,6 +416,20 @@ computationally intensive or rather cheap, depending on whether substitutes are available for their dependencies (@pxref{Substitutes}). Some of them require a lot of storage space to hold VM images. +If you encounter an error like: + +@example +Compiling Scheme modules... +ice-9/eval.scm:142:16: In procedure compile-top-call: +error: all-system-tests: unbound variable +hint: Did you forget `(use-modules (gnu tests))'? +@end example + +@noindent +there may be inconsistencies in the work tree from previous builds. To +resolve this, try running @command{make clean-go} followed by +@command{make}. + Again in case of test failures, please send @email{bug-guix@@gnu.org} all the details. @@ -847,7 +869,7 @@ example, the @code{(guix scripts shell)} module exports the 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. +is used by the @command{guix import pypi} command. @end table The directories we have seen so far all live under @file{guix/}. The @@ -1883,17 +1905,19 @@ Take some time to provide an adequate synopsis and description for the package. @xref{Synopses and Descriptions}, for some guidelines. @item -Run @code{guix lint @var{package}}, where @var{package} is the +Run @command{guix lint @var{package}}, where @var{package} is the name of the new or modified package, and fix any errors it reports (@pxref{Invoking guix lint}). @item -Run @code{guix style @var{package}} to format the new package definition +Run @command{guix style @var{package}} to format the new package definition according to the project's conventions (@pxref{Invoking guix style}). @item -Make sure the package builds on your platform, using @code{guix build -@var{package}}. +Make sure the package builds on your platform, using @command{guix build +@var{package}}. Also build at least its direct dependents with +@command{guix build --dependents=1 @var{package}} +(@pxref{build-dependents, @command{guix build}}). @item We recommend you also try building the package on other supported @@ -1945,7 +1969,7 @@ adding @code{texlive} as a dependency: because of its extreme size, use @item Check that dependent packages (if applicable) are not affected by the -change; @code{guix refresh --list-dependent @var{package}} will help you +change; @command{guix refresh --list-dependent @var{package}} will help you do that (@pxref{Invoking guix refresh}). @item @@ -1997,7 +2021,7 @@ Please follow our code formatting rules, possibly running When possible, use mirrors in the source URL (@pxref{Invoking guix download}). Use reliable URLs, not generated ones. For instance, GitHub archives are not necessarily identical from one generation to the next, so in this case it's -often better to clone the repository. Don't use the @command{name} field in +often better to clone the repository. Don't use the @code{name} field in the URL: it is not very useful and if the name changes, the URL will probably be wrong. @@ -2006,7 +2030,8 @@ Check if Guix builds (@pxref{Building from Git}) and address the warnings, especially those about use of undefined symbols. @item -Make sure your changes do not break Guix and simulate a @code{guix pull} with: +Make sure your changes do not break Guix and simulate a @command{guix pull} +with: @example guix pull --url=/path/to/your/checkout --profile=/tmp/guix.master @end example @@ -2018,11 +2043,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 @@ -2035,7 +2061,6 @@ When a bug is resolved, please close the thread by sending an email to @menu * Configuring Git:: * Sending a Patch Series:: -* Teams:: @end menu @node Configuring Git @@ -2166,9 +2191,21 @@ with @command{git format-patch}. @example $ git format-patch -@var{NUMBER_COMMITS} -o outgoing \ - --cover-letter --base=auto + --cover-letter @end example +@quotation Note +@code{git format-patch} accepts a wide range of +@uref{https://git-scm.com/docs/gitrevisions, revision range} specifiers. +For example, if you are working in a branch, you could select all commits +in your branch starting at @code{master}. + +@example +$ git format-patch master..@var{MY_BRANCH} -o outgoing \ + --cover-letter +@end example +@end quotation + We can now send @emph{just} the cover letter to the @email{guix-patches@@gnu.org} address, which will create an issue that we can send the rest of the patches to. @@ -2203,44 +2240,6 @@ If need be, you may use @option{--cover-letter --annotate} to send another cover letter, e.g. for explaining what's changed since the last revision, and these changes are necessary. -@node Teams -@subsection Teams -@cindex teams - -There are several teams mentoring different parts of the Guix source -code. To list all those teams, you can run from a Guix checkout: - -@example -$ ./etc/teams.scm list-teams -id: mentors -name: Mentors -description: A group of mentors who chaperone contributions by newcomers. -members: -+ Christopher Baines <mail@@cbaines.net> -+ Ricardo Wurmus <rekado@@elephly.net> -+ Mathieu Othacehe <othacehe@@gnu.org> -+ jgart <jgart@@dismail.de> -+ Ludovic Courtès <ludo@@gnu.org> -@dots{} -@end example - -You can run the following command to have the @code{Mentors} team put in -CC of a patch series: - -@example -$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \ - --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch -@end example - -The appropriate team or teams can also be inferred from the modified -files. For instance, if you want to send the two latest commits of the -current Git repository to review, you can run: - -@example -$ guix shell -D guix -[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2 -@end example - @node Tracking Bugs and Changes @section Tracking Bugs and Changes @@ -2298,9 +2297,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 +2307,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,22 +2359,37 @@ 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. + +@cindex work-in-progress branches, wip +@cindex wip branches +Sometimes, a branch may be a work in progress, for example for larger +efforts such as updating the GNOME desktop. In these cases, the branch +name should reflect this by having the @samp{wip-} prefix. The QA +infrastructure will avoid building work-in-progress branches, so that +the available resources can be better focused on building the branches +that are ready to be merged. When the branch is no longer a work in +progress, it should be renamed, with the @samp{wip-} prefix removed, and +only then should the merge requests be created, as documented earlier. + @node Debbugs User Interfaces @subsection Debbugs User Interfaces @subsubsection Web interface +@cindex mumi, web interface for issues A web interface (actually @emph{two} web interfaces!) are available to browse issues: @itemize @item -@url{https://issues.guix.gnu.org} provides a pleasant -interface@footnote{The web interface at -@url{https://issues.guix.gnu.org} is powered by Mumi, a nice piece of -software written in Guile, and you can help! See -@url{https://git.savannah.gnu.org/cgit/guix/mumi.git}.} to browse -bug reports and patches, and to participate in discussions; +@url{https://issues.guix.gnu.org} provides a pleasant interface powered +by mumi@footnote{Mumi is a nice piece of software written in Guile, and +you can help! See +@url{https://git.savannah.gnu.org/cgit/guix/mumi.git}.} to browse bug +reports and patches, and to participate in discussions; mumi also has a +command-line interface as we will see below; @item @url{https://bugs.gnu.org/guix} lists bug reports; @item @@ -2355,12 +2400,17 @@ To view discussions related to issue number @var{n}, go to @indicateurl{https://issues.guix.gnu.org/@var{n}} or @indicateurl{https://bugs.gnu.org/@var{n}}. -@subsubsection Command-line interface +@subsubsection Command-Line Interface +@cindex mumi command-line interface +@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 +2447,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 +2518,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. @@ -2435,7 +2535,7 @@ so by sending the first patch, polling the server for a response, and then sending the remaining patches. This polling can unfortunately take a few minutes. So, please be patient. -@subsubsection Emacs interface +@subsubsection Emacs Interface If you use Emacs, you may find it more convenient to interact with issues using @file{debbugs.el}, which you can install with: @@ -2556,6 +2656,102 @@ notifications that read like: where each RSS entry contains a link to the Cuirass build details page of the associated build. +@node Teams +@section Teams +@cindex teams + +To organize work on Guix, including but not just development efforts, +the project has a set of @dfn{teams}. Each team has its own focus and +interests and is the primary contact point for questions and +contributions in those areas. A team's primary mission is to coordinate +and review the work of individuals in its scope (@pxref{Reviewing the +Work of Others}); it can make decisions within its scope, in agreement +with other teams whenever there is overlap or a close connection, and in +accordance with other project rules such as seeking consensus +(@pxref{Making Decisions}). + +As an example, the Python team is responsible for core Python packaging +matters; it can decide to upgrade core Python packages in a dedicated +@code{python-team} branch, in collaboration with any team whose scope is +directly dependent on Python---e.g., the Science team---and following +branching rules (@pxref{Managing Patches and Branches}). The +Documentation team helps review changes to the documentation and can +initiate overarching documentation changes. The Translations team +organizes translation of Guix and its manual and coordinates efforts in +that area. The Core team is responsible for the development of core +functionality and interfaces of Guix; because of its central nature, +some of its work may require soliciting input from the community at +large and seeking consensus before enacting decisions that would affect +the entire community. + +Teams are defined in the @file{etc/teams.scm} file in the Guix +repository. The scope of each team is defined, when applicable, as a +set of files or as a regular expression matching file names. + +@cindex team membership +Anyone with interest in a team's domain and willing to contribute to its +work can apply to become a member by contacting current members by +email; commit access is not a precondition. Membership is formalized by +adding the person's name and email address to @file{etc/teams.scm}. +Members who have not been participating in the team's work for one year +or more may be removed; they are free to reapply for membership later. + +@cindex team creation +One or more people may propose the creation of a new team by reaching +out to the community by email at @email{guix-devel@@gnu.org}, clarifying +the intended scope and purpose. When consensus is reached on the +creation of this team, someone with commit access formalizes its +creation by adding it and its initial members to @file{etc/teams.scm}. + +To list existing teams, run the following command from a Guix checkout: + +@example +$ ./etc/teams.scm list-teams +id: mentors +name: Mentors +description: A group of mentors who chaperone contributions by newcomers. +members: ++ Charlie Smith <charlie@@example.org> +@dots{} +@end example + +@cindex mentoring +You can run the following command to have the Mentors team put in +CC of a patch series: + +@example +$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org \ + --header-cmd='etc/teams.scm cc-mentors-header-cmd' *.patch +@end example + +The appropriate team or teams can also be inferred from the modified +files. For instance, if you want to send the two latest commits of the +current Git repository to review, you can run: + +@example +$ guix shell -D guix +[env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2 +@end example + +@node Making Decisions +@section Making Decisions + +@cindex decision making +@cindex consensus seeking +It is expected from all contributors, and even more so from committers, +to help build consensus and make decisions based on consensus. By using +consensus, we are committed to finding solutions that everyone can live +with. It implies that no decision is made against significant concerns +and these concerns are actively resolved with proposals that work for +everyone. + +A contributor (who may or may not have commit access) wishing to block +a proposal bears a special responsibility for finding alternatives, +proposing ideas/code or explain the rationale for the status quo to +resolve the deadlock. To learn what consensus decision making means and +understand its finer details, you are encouraged to read +@url{https://www.seedsforchange.org.uk/consensus}. + @node Commit Access @section Commit Access @@ -2569,18 +2765,12 @@ project for at least 6 months. This ensures enough interactions with the contributor, which is essential for mentoring and assessing whether they are ready to become a committer. Commit access should not be thought of as a ``badge of honor'' but rather as a responsibility a -contributor is willing to take to help the project. It is expected from -all contributors, and even more so from committers, to help build -consensus and make decisions based on consensus. By using consensus, we -are committed to finding solutions that everyone can live with. It -implies that no decision is made against significant concerns and these -concerns are actively resolved with proposals that work for everyone. A -contributor (which may or may not have commit access) wishing to block a -proposal bears a special responsibility for finding alternatives, -proposing ideas/code or explain the rationale for the status quo to -resolve the deadlock. To learn what consensus decision making means and -understand its finer details, you are encouraged to read -@url{https://www.seedsforchange.org.uk/consensus}. +contributor is willing to take to help the project. + +Committers are in a position where they enact technical decisions. Such +decisions must be made by @emph{actively building consensus} among +interested parties and stakeholders. @xref{Making Decisions}, for more +on that. The following sections explain how to get commit access, how to be ready to push commits, and the policies and community expectations for commits @@ -2676,9 +2866,12 @@ git config user.signingkey CABBA6EA1DC0FF33 To check that commits are signed with correct key, use: @example -make authenticate +guix git authenticate @end example +@xref{Building from Git} for running the first authentication of a Guix +checkout. + To avoid accidentally pushing unsigned or signed with the wrong key commits to Savannah, make sure to configure Git according to @xref{Configuring Git}. @@ -2694,9 +2887,11 @@ Ensure you're aware of how the changes should be handled repository, especially for the @code{master} branch. If you're committing and pushing your own changes, try and wait at least -one week (two weeks for more significant changes) after you send them -for review. After this, if no one else is available to review them and -if you're confident about the changes, it's OK to commit. +one week (two weeks for more significant changes, up to one month for +changes such as removing a package---@pxref{package-removal-policy, +Package Removal}) after you send them for review. After this, if no one +else is available to review them and if you're confident about the +changes, it's OK to commit. When pushing a commit on behalf of somebody else, please add a @code{Signed-off-by} line at the end of the commit log message---e.g., @@ -2794,12 +2989,14 @@ Perhaps the biggest action you can do to help GNU Guix grow as a project is to review the work contributed by others. You do not need to be a committer to do so; applying, reading the source, building, linting and running other people's series and sharing your comments about your -experience will give some confidence to committers. Basically, you must +experience will give some confidence to committers. You must ensure the check list found in the @ref{Submitting Patches} section has been correctly followed. A reviewed patch series should give the best chances for the proposed change to be merged faster, so if a change you would like to see merged hasn't yet been reviewed, this is the most -appropriate thing to do! +appropriate thing to do! If you would like to review changes in a +specific area and to receive notifications for incoming patches relevant +to that domain, consider joining the relevant team(s) (@pxref{Teams}). @cindex reviewing, guidelines Review comments should be unambiguous; be as clear and explicit as you @@ -2846,6 +3043,8 @@ preference for the color of the shed at the expense of progress made on the project to keep bikes dry.}. As a reviewer, try hard to explain the rationale for suggestions you make, and to understand and take into account the submitter's motivation for doing things in a certain way. +In other words, build consensus with everyone involved (@pxref{Making +Decisions}). @end enumerate @cindex LGTM, Looks Good To Me @@ -2853,7 +3052,7 @@ account the submitter's motivation for doing things in a certain way. @cindex Reviewed-by, git trailer When you deem the proposed change adequate and ready for inclusion within Guix, the following well understood/codified -@samp{Reviewed-by:@tie{}Your@tie{}Name<your-email@@example.com>} +@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} @footnote{The @samp{Reviewed-by} Git trailer is used by other projects such as Linux, and is understood by third-party tools such as the @samp{b4 am} sub-command, which is able to retrieve the complete @@ -2865,7 +3064,8 @@ looks good to you: @itemize @item If the @emph{whole} series (containing multiple commits) looks good to -you, reply with @samp{Reviewed-by:@tie{}Your@tie{}Name<your-email@@example.com>} +you, reply with +@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} to the cover page if it has one, or to the last patch of the series otherwise, adding another @samp{(for the whole series)} comment on the line below to explicit this fact. @@ -2873,8 +3073,8 @@ line below to explicit this fact. @item If you instead want to mark a @emph{single commit} as reviewed (but not the whole series), simply reply with -@samp{Reviewed-by:@tie{}Your@tie{}Name<your-email@@example.com>} to that -commit message. +@samp{Reviewed-by:@tie{}Your@tie{}Name@tie{}<your-email@@example.com>} +to that commit message. @end itemize If you are not a committer, you can help others find a @emph{series} you @@ -2918,6 +3118,196 @@ This check can be disabled, @emph{at your own peril}, by setting the this variable is set, the updated package source is also added to the store. This is used as part of the release process of Guix. +@node Deprecation Policy +@section Deprecation Policy + +@cindex deprecation policy +As any lively project with a broad scope, Guix changes all the time and +at all levels. Because it's user-extensible and programmable, +incompatible changes can directly impact users and make their life +harder. It is thus important to reduce user-visible incompatible +changes to a minimum and, when such changes are deemed necessary, to +clearly communicate them through a @dfn{deprecation period} so everyone +can adapt with minimum hassle. This section defines the project's +commitments for smooth deprecation and describes procedures and +mechanisms to honor them. + +There are several ways to use Guix; how to handle deprecation will +depend on each use case. Those can be roughly categorized like this: + +@itemize +@item +package management exclusively through the command line; + +@item +advanced package management using the manifest and package interfaces; + +@item +Home and System management, using the @code{operating-system} and/or +@code{home-environment} interfaces together with the service interfaces; + +@item +development or use of external tools that use programming interfaces +such as the @code{(guix ...)} modules. +@end itemize + +These use cases form a spectrum with varying degrees of coupling---from +``distant'' to tightly coupled. Based on this insight, we define the +following @dfn{deprecation policies} that we consider suitable for each +of these levels. + +@table @asis +@item Command-line tools +Guix sub-commands should be thought of as remaining available +``forever''. Once a Guix sub-command is to be removed, it should be +deprecated first, and then remain available for @b{at least one year} +after the first release that deprecated it. + +Deprecation should first be announced in the manual and as an entry in +@file{etc/news.scm}; additional communication such as a blog post +explaining the rationale is welcome. Months before the scheduled +removal date, the command should print a warning explaining how to +migrate. An example of this is the replacement of @command{guix +environment} by @command{guix shell}, started in October +2021@footnote{For more details on the @command{guix shell} transition, +see +@uref{https://guix.gnu.org/en/blog/2021/from-guix-environment-to-guix-shell/}.}. + +Because of the broad impact of such a change, we recommend conducting a +user survey before enacting a plan. + +@cindex package deprecation +@item Package name changes +When a package name changes, it must remain available under its old name +for @b{at least one year}. For example, @code{go-ipfs} was renamed to +@code{kubo} following a decision made upstream; to communicate the name +change to users, the package module provided this definition: + +@findex deprecated-package +@lisp +(define-public go-ipfs + (deprecated-package "go-ipfs" kubo)) +@end lisp + +That way, someone running @command{guix install go-ipfs} or similar sees +a deprecation warning mentioning the new name. + +@cindex package removal policy +@anchor{package-removal-policy} +@item Package removal +Packages whose upstream developers have declared as having reached ``end +of life'' or being unmaintained may be removed; likewise, packages that +have been @b{failing to build for two months or more} may be removed. + +There is no formal deprecation mechanism for this case, unless a +replacement exists, in which case the @code{deprecated-package} +procedure mentioned above can be used. + +If the package being removed is a ``leaf'' (no other packages depend on +it), it may be removed after a @b{one-month review period} of the patch +removing it (this applies even when the removal has additional +motivations such as security problems affecting the package). + +If it has many dependent packages---as is the case for example with +Python version@tie{}2---the relevant team must propose a deprecation +removal agenda and seek consensus with other packagers for @b{at least +one month}. It may also invite feedback from the broader user +community, for example through a survey. Removal of all impacted +packages may be gradual, spanning multiple months, to accommodate all +use cases. + +When the package being removed is considered popular, whether or not it +is a leaf, its deprecation must be announced as an entry in +@code{etc/news.scm}. + +@item Package upgrade +In the case of packages with many dependents and/or many users, an +upgrade may be treated like the @emph{removal} of the previous version. + +Examples include major version upgrades of programming language +implementations, as we've seen above with Python, and major upgrades of +``big'' libraries such as Qt or GTK. + +@cindex service deprecation +@item Services +Changes to services for Guix Home and Guix System have a direct impact +on user configuration. For a user, adjusting to interface changes is +rarely rewarding, which is why any such change must be clearly +communicated in advance through deprecation warnings and documentation. + +Renaming of variables related to service, home, or system configuration +must be communicated for at least six months before removal using the +@code{(guix deprecation)} mechanisms. For example, renaming of +@code{murmur-configuration} to @code{mumble-server-configuration} was +communicated through a series of definitions like this one: + +@findex define-deprecated/public-alias +@lisp +(define-deprecated/public-alias + murmur-configuration + mumble-server-configuration) +@end lisp + +Procedures slated for removal may be defined like this: + +@findex define-deprecated +@lisp +(define-deprecated (elogind-service #:key (config (elogind-configuration))) + elogind-service-type + (service elogind-service-type config)) +@end lisp + +Record fields, notably fields of service configuration records, must +follow a similar deprecation period. This is usually achieved through +@i{ad hoc} means though. For example, the @code{hosts-file} field of +@code{operating-system} was deprecated by adding a @code{sanitized} +property that would emit a warning: + +@lisp +(define-record-type* <operating-system> + ;; @dots{} + (hosts-file %operating-system-hosts-file ;deprecated + (default #f) + (sanitize warn-hosts-file-field-deprecation))) + +(define-deprecated (operating-system-hosts-file os) + hosts-service-type + (%operating-system-hosts-file os)) +@end lisp + +When deprecating interfaces in @code{operating-system}, +@code{home-environment}, @code{(gnu services)}, or any popular service, +the deprecation must come with an entry in @code{etc/news.scm}. + +@cindex deprecation of programming interfaces +@item Core interfaces +Core programming interfaces, in particular the @code{(guix ...)} +modules, may be relied on by a variety of external tools and channels. +Any incompatible change must be formally deprecated with +@code{define-deprecated}, as shown above, for @b{at least one year} +before removal. The manual must clearly document the new interface and, +except in obvious cases, explain how to migrate from the old one. + +As an example, the @code{build-expression->derivation} procedure was +superseded by @code{gexp->derivation} and remained available as a +deprecated symbol: + +@lisp +(define-deprecated (build-expression->derivation store name exp + #:key @dots{}) + gexp->derivation + @dots{}) +@end lisp + +Sometimes bindings are moved from one module to another. In those +cases, bindings must be reexported from the original module for at least +one year. +@end table + +This section does not cover all possible situations but hopefully allows +users to know what to expect and developers to stick to its spirit. +Please email @email{guix-devel@@gnu.org} for any questions. + @cindex documentation @node Writing Documentation @section Writing Documentation @@ -2983,7 +3373,7 @@ Some of the software packaged in Guix also contain translations. We do not host a translation platform for them. If you want to translate a package provided by Guix, you should contact their developers or find the information on their website. As an example, you can find the homepage of the -@code{hello} package by typing @code{guix show hello}. On the ``homepage'' +@code{hello} package by typing @command{guix show hello}. On the ``homepage'' line, you will see @url{https://www.gnu.org/software/hello/} as the homepage. Many GNU and non-GNU packages can be translated on the @@ -3243,3 +3633,204 @@ differs for the various components. be updated accordingly (see @file{website/i18n-howto.txt} for more information on the process). @end itemize + + +@cindex infrastructure +@node Contributing to Guix's Infrastructure +@section Contributing to Guix's Infrastructure + +Since its inception, the Guix project has always valued its autonomy, and that +reflects in its infrastructure: our servers run Guix System and exclusively +free software, and are administered by volunteers. + +Of course this comes at a cost and this is why we need contributions. Our hope +is to make infrastructure-related activity more legible so that maybe you can +picture yourself helping in one of these areas. + + +@menu +* Coding:: +* System Administration:: +* Day-to-Day System Administration:: +* On-Site Intervention:: +* Hosting:: +* Administrative Tasks:: +@end menu + +@node Coding +@subsection Coding + +The project runs many Guix-specific services; this is all lovely Scheme code +but it tends to receive less attention than Guix itself: + +@itemize +@item +Build Farm Front-End: @url{https://git.cbaines.net/guix/bffe, bffe} +@item +Cuirass: @url{https://guix.gnu.org/cuirass/, Cuirass} +@item +Goggles (IRC logger): +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/goggles.scm, +Goggles} +@item +Guix Build Coordinator: +@url{https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/, +Build-Coordinator} +@item +Guix Data Service: +@url{https://git.savannah.gnu.org/git/guix/data-service.git/, Data-Service} +@item +Guix Packages Website: +@url{https://codeberg.org/luis-felipe/guix-packages-website.git, +Guix-Packages-Website} +@item +mumi: @url{https://git.savannah.gnu.org/cgit/guix/mumi.git/, Mumi} +@item +nar-herder: @url{https://git.savannah.gnu.org/cgit/guix/nar-herder.git/, +Nar-Herder} +@item +QA Frontpage: +@url{https://git.savannah.gnu.org/git/guix/qa-frontpage.git, QA-Frontpage} +@end itemize + +There is no time constraint on this coding activity: any improvement is +welcome, whenever it comes. Most of these code bases are relatively small, +which should make it easier to get started. + +Prerequisites: Familiarity with Guile, HTTP, and databases. + +If you wish to get started, check out the README of the project of your choice +and get in touch with guix-devel and the primary developer(s) of the tool as +per @code{git shortlog -s | sort -k1 -n}. + +@node System Administration +@subsection System Administration + +Guix System configuration for all our systems is held in this repository: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/} + +The two front-ends are @file{berlin.scm} (the machine behind ci.guix.gnu.org) +and @file{bayfront.scm} (the machine behind bordeaux.guix.gnu.org, +guix.gnu.org, hpc.guix.info, qa.guix.gnu.org, and more). Both connect to a +number of build machines and helpers. + +Without even having SSH access to the machine, you can help by posting patches +to improve the configuration (you can test it with @code{guix system vm}). +Here are ways you can help: + +@itemize +@item +Improve infra monitoring: set up a dashboard to monitor all the infrastructure, +and an out-of-band channel to communicate about downtime. + +@item +Implement web site redundancy: guix.gnu.org should be backed by several +machines on different sites. Get in touch with us and/or send a patch! + +@item +Implement substitute redundancy: likewise, bordeaux.guix.gnu.org and +ci.guix.gnu.org should be backed by several head nodes. + +@item +Improve backup: there's currently ad-hoc backup of selected pieces over rsync +between the two head nodes; we can improve on that, for example with a +dedicated backup site and proper testing of recoverability. + +@item +Support mirroring: We'd like to make it easy for others to mirror substitutes +from ci.guix and bordeaux.guix, perhaps by offering public rsync access. + +@item +Optimize our web services: Monitor the performance of our services and tweak +nginx config or whatever it takes to improve it. + +There is no time constraint on this activity: any improvement is welcome, +whenever you can work on it. + +Prerequisite: Familiarity with Guix System administration and ideally with the +infrastructure handbook: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org, +Infra-Handbook} + +@end itemize + +@node Day-to-Day System Administration +@subsection Day-to-Day System Administration + +We're also looking for people who'd be willing to have SSH access to some of +the infrastructure to help with day-to-day maintenance: restarting a build, +restarting the occasional service that has gone wild (that can happen), +reconfiguring/upgrading a machine, rebooting, etc. + +This day-to-day activity requires you to be available some of the time (during +office hours or not, during the week-end or not), whenever is convenient for +you, so you can react to issues reported on IRC, on the mailing list, or +elsewhere, and synchronize with other sysadmins. + +Prerequisite: Being a ``known'' member of the community, familiarity with Guix +System administration, with some of the services/web sites being run, and with +the infrastructure handbook: + +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org, +Infra-Handbook} + +@node On-Site Intervention +@subsection On-Site Intervention + +The first front-end is currently generously hosted by the Max Delbrück Center +(MDC), a research institute in Berlin, Germany. Only authorized personnel can +physically access it. + +The second one, bordeaux.guix.gnu.org, is hosted in Bordeaux, France, in a +professional data center shared with non-profit ISP Aquilenet. If you live in +the region of Bordeaux and would like to help out when we need to go on-site, +please make yourself known by emailing @email{guix-sysadmin@@gnu.org}. + +On-site interventions are rare, but they're usually in response to an +emergency. + +@node Hosting +@subsection Hosting + +We're looking for people who can host machines and help out whenever +physical access is needed. More specifically: + +@itemize +@item +We need hosting of ``small'' machines such as single-board computers (AArch64, +RISC-V) for use as build machines. + +@item +We need hosting for front-ends and x86_64 build machines in a data center where +they can be racked and where, ideally, several local Guix sysadmins can +physically access them. +@end itemize + +The machines should be accessible over Wireguard VPN most of the +time, so longer power or network interruptions should be the +exception. + +Prerequisites: Familiarity with installing and remotely administering Guix +System. + +@node Administrative Tasks +@subsection Administrative Tasks + +The infra remains up and running thanks to crucial administrative tasks, which +includes: + +@itemize +@item +Selecting and purchasing hardware, for example build machines. +@item +Renewing domain names. + +@item +Securing funding, in particular via the Guix Foundation: +@url{https://foundation.guix.info, Guix Foundation} +@end itemize + +Prerequisites: Familiarity with hardware, and/or DNS registrars, +and/or sponsorship, and/or crowdfunding. diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 3bc63cba7a..57e39f12d9 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 @@ -84,6 +86,7 @@ manual}). * Software Development:: Environments, continuous integration, etc. * Environment management:: Control environment * Installing Guix on a Cluster:: High-performance computing. +* Guix System Management:: System Management specifics. * Acknowledgments:: Thanks! * GNU Free Documentation License:: The license of this document. @@ -197,6 +200,10 @@ Installing Guix on a Cluster * Cluster Disk Usage:: Disk usage considerations. * Cluster Security Considerations:: Keeping the cluster secure. +Guix System Management + +* Upgrade Postgres for Cuirass:: How to handle deprecation of the default postgres package. + @end detailmenu @end menu @@ -747,7 +754,7 @@ my-hello 2.10 out We've gone as far as we could without any knowledge of Scheme. Before moving on to more complex packages, now is the right time to brush up on your Scheme -knowledge. @pxref{A Scheme Crash Course} to get up to speed. +knowledge. @xref{A Scheme Crash Course} to get up to speed. @node Setup @subsection Setup @@ -1606,8 +1613,8 @@ reference. @node Auto-Login to a Specific TTY @section Auto-Login to a Specific TTY -While the Guix manual explains auto-login one user to @emph{all} TTYs ( -@pxref{auto-login to TTY,,, guix, GNU Guix Reference Manual}), some +While the Guix manual explains auto-login one user to @emph{all} TTYs +(@pxref{auto-login to TTY,,, guix, GNU Guix Reference Manual}), some might prefer a situation, in which one user is logged into one TTY with the other TTYs either configured to login different users or no one at all. Note that one can auto-login one user to any TTY, but it is @@ -1681,7 +1688,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 +1700,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 +1756,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 +1806,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 +1820,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 +2414,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 @@ -2447,7 +2458,7 @@ be made setuid-root so it can authenticate users, and it needs a PAM service. Th can be achieved by adding the following service to your @file{config.scm}: @lisp -(service screen-locker-services-type +(service screen-locker-service-type (screen-locker-configuration (name "slock") (program (file-append slock "/bin/slock")))) @@ -2963,13 +2974,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 +2992,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 +3052,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 +3295,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. @@ -3778,13 +3796,15 @@ QEMU comes with a helper program to conveniently make use of a network bridge interface as an unprivileged user @pxref{Network options,,, QEMU, QEMU Documentation}. The binary must be made setuid root for proper operation; this can be achieved by adding it to the -@code{setuid-programs} field of your (host) @code{operating-system} +@code{privileged-programs} field of your (host) @code{operating-system} definition, as shown below: @example lisp -(setuid-programs - (cons (file-append qemu "/libexec/qemu-bridge-helper") - %setuid-programs)) +(privileged-programs + (cons (privileged-program + (program (file-append qemu "/libexec/qemu-bridge-helper")) + (setuid? #t)) + %default-privileged-programs)) @end example The file @file{/etc/qemu/bridge.conf} must also be made to allow the @@ -4076,7 +4096,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 @@ -4143,13 +4164,14 @@ It contains the same variables you would get if you ran: guix package --search-paths=prefix --profile=$my_profile" @end example -Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}) +Once again, see @ref{Invoking guix package,,, guix, GNU Guix Reference Manual} 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 +4181,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 +4360,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 +5096,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 +5204,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: @@ -5491,6 +5529,104 @@ guix gc --referrers /gnu/store/…-glibc-2.25 This will report whether profiles exist that refer to this specific glibc variant. +@c ********************************************************************* +@node Guix System Management +@chapter Guix System Management +@cindex system management +@cindex sysadmin + +Since Guix does not handle packaging, system configuration and services +the way other (more ``classical'') distributions do, some workflows tend +to unfold slightly different as we are used to and need slight +adjustment. This chapter intends to help with such manners. + +@menu +* Upgrade Postgres for Cuirass:: Upgrading from the default postgres. +@end menu + +@node Upgrade Postgres for Cuirass +@section Upgrade Postgres for Cuirass + +With the deprecation of the default value for the postgres package in +postgresql-configuration (see b93434e656eba4260df82158a96c295000d3ff44), +system upgrades need some manual action before they can take place. +Here's a handy guide on how to. + +Please note that this is a straight-forward way for smaller datasets. +For larger databases +@url{https://www.postgresql.org/docs/current/pgupgrade.html, +@code{pg_upgrade}} may be the better choice. Handling the service and +system upgrade as described in this guide still applies, though. + +@enumerate +@item +Stop and disable cuirass. + +Prevent the service from starting and failing after a reconfiguration: + + @code{sudo herd stop cuirass && sudo herd disable cuirass} + +@item +Dump the database contents. + + @code{sudo su - postgres -s /bin/sh -c pg_dumpall > /tmp/pg.dump} + +@item +Add or alter the postgres service. + +Depending on whether your postgres service is defined implicitly +(through the dependency from the cuirass service) or its own entry in +your operating system's @code{(services)} property, you need to either +add or alter the already existing configuration to reflect your intended +version upgrade. + +Be careful not to upgrade directly to postgres-16 -- cuirass service for +some reason doesn't like that. I had to find and purge the relevant +files and then re-initialize after a failed upgrade to postgres 16. + +@lisp +(service postgresql-service-type + (postgresql-configuration + (postgresql (@ (gnu packages databases) postgresql-15)))) +@end lisp + +Note: If you for some reason didn't read the text here but somewhat +blindly followed the examples and @emph{did upgrade to 16}, here's how +you reset the state: + +@enumerate +@item +Delete the database instance files. + +They default to live under @file{/var/lib/postgres/data}. + +@item +Re-initialize postgres. + +@code{sudo su - postgres -s /bin/sh -c 'pg_ctl init -D +/var/lib/postgres/data'} +@end enumerate + +@item +Reconfigure your system. + +@code{sudo guix system reconfigure path/to/your/altered/config.scm} + +@item +Restore database contents. + +@code{sudo su - postgres -s /bin/sh -c 'psql -d postgres -f /tmp/pg.dump'} + +@item +Enable and start the service. + +@example +sudo herd enable cuirass +sudo herd start cuirass +@end example + +@end enumerate + @c ********************************************************************* @node Acknowledgments diff --git a/doc/guix.texi b/doc/guix.texi index 1c1e0164e7..08ffbc36d7 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23,7 +23,7 @@ @copying Copyright @copyright{} 2012-2024 Ludovic Courtès@* -Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* +Copyright @copyright{} 2013, 2014, 2016, 2024 Andreas Enge@* Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* @@ -36,7 +36,7 @@ Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016, 2017 Nikita Gillmann@* -Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Jan Nieuwenhuizen@* +Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024 Janneke Nieuwenhuizen@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@* @@ -49,11 +49,11 @@ Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@* Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@* Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@* -Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023 Maxim Cournoyer@* +Copyright @copyright{} 2017, 2019, 2020, 2021, 2022, 2023, 2024 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@* @@ -116,17 +116,24 @@ Copyright @copyright{} 2022 Antero Mejr@* Copyright @copyright{} 2023 Karl Hallsby@* Copyright @copyright{} 2023 Nathaniel Nicandro@* Copyright @copyright{} 2023 Tanguy Le Carrour@* -Copyright @copyright{} 2023 Zheng Junjie@* +Copyright @copyright{} 2023, 2024 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@* 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@* +Copyright @copyright{} 2024 Fabio Natali@* +Copyright @copyright{} 2024 Arnaud Daby-Seesaram@* +Copyright @copyright{} 2024 Nigko Yerden@* +Copyright @copyright{} 2024 Troy Figiel@* +Copyright @copyright{} 2024 Sharlatan Hellseher@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -368,7 +375,7 @@ System Configuration * Keyboard Layout:: How the system interprets key strokes. * Locales:: Language and cultural convention settings. * Services:: Specifying system services. -* Setuid Programs:: Programs running with elevated privileges. +* Privileged Programs:: Programs running with elevated privileges. * X.509 Certificates:: Authenticating HTTPS servers. * Name Service Switch:: Configuring libc's name service switch. * Initial RAM Disk:: Linux-Libre bootstrapping. @@ -457,6 +464,7 @@ Home Services * Mail: Mail Home Services. Services for managing mail. * Messaging: Messaging Home Services. Services for managing messaging. * Media: Media Home Services. Services for managing media. +* Sway: Sway window manager. Setting up the Sway configuration. * Networking: Networking Home Services. Networking services. * Miscellaneous: Miscellaneous Home Services. More services. @@ -631,6 +639,13 @@ way for you to give it a try is by setting up an instance of (@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}). @xref{Contributing}, on how to help! +@item x86_64-gnu +@uref{https://hurd.gnu.org, GNU/Hurd} on the @code{x86_64} Intel/AMD +64-bit architecture. + +This configuration is even more experimental and under heavy upstream +development. + @item mips64el-linux (unsupported) little-endian 64-bit MIPS processors, specifically the Loongson series, n32 ABI, and Linux-Libre kernel. This configuration is no longer fully @@ -742,7 +757,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 +774,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 +805,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} @@ -840,8 +873,28 @@ files, configuration, and services. @section Setting Up the Daemon @cindex daemon +During installation, the @dfn{build daemon} that must be running +to use Guix has already been set up and you can run @command{guix} +commands in your terminal program, @pxref{Getting Started}: + +@example +guix build hello +@end example + +If this runs through without error, feel free to skip this section. +You should continue with the following section, @ref{Application +Setup}. + +However, now would be a good time to replace outdated daemon versions, +tweak it, perform builds on other machines (@pxref{Daemon Offload +Setup}), or start it manually in special environments like ``chroots'' +(@pxref{Chrooting into an existing system}) or WSL (not needed for WSL +images created with Guix, @pxref{System Images, +@code{wsl2-image-type}}). If you want to know more or optimize your +system, this section is worth reading. + Operations such as building a package or running the garbage collector -are all performed by a specialized process, the @dfn{build daemon}, on +are all performed by a specialized process, the build daemon, on behalf of clients. Only the daemon may access the store and its associated database. Thus, any operation that manipulates the store goes through the daemon. For instance, command-line tools such as @@ -1858,15 +1911,28 @@ running Emacs with the @option{--no-site-file} option (@pxref{Init File,,, emacs, The GNU Emacs Manual}). @quotation Note -Emacs can now compile packages natively. Under the default -configuration, this means that Emacs packages will now be -just-in-time (JIT) compiled as you use them, and the results -stored in a subdirectory of your @code{user-emacs-directory}. - -Furthermore, the build system for Emacs packages transparently -supports native compilation, but note, that -@code{emacs-minimal}---the default Emacs for building -packages---has been configured without native compilation. +Most Emacs variants are now capable of doing native compilation. +The approach taken by Guix Emacs however differs greatly +from the approach taken upstream. + +Upstream Emacs compiles packages just-in-time and typically places +shared object files in a special folder within your +@code{user-emacs-directory}. +These shared objects within said folder are organized in a +flat hierarchy, and their file names contain two hashes to +verify the original file name and contents of the source code. + +Guix Emacs on the other hand prefers to compile packages ahead-of-time. +Shared objects retain much of the original file name and no hashes +are added to verify the original file name or the contents of the file. +Crucially, this allows Guix Emacs and packages built against it +to be grafted (@pxref{Security Updates, grafts}), but at the same time, +Guix Emacs lacks the hash-based verification of source code baked +into upstream Emacs. As this naming schema is trivial to exploit, +we disable just-in-time compilation. + +Further note, that @code{emacs-minimal}---the default Emacs +for building packages---has been configured without native compilation. To natively compile your emacs packages ahead of time, use a transformation like @option{--with-input=emacs-minimal=emacs}. @end quotation @@ -1951,19 +2017,10 @@ We consider Guix System to be ready for a wide range of ``desktop'' and server use cases. The reliability guarantees it provides---transactional upgrades and rollbacks, reproducibility---make it a solid foundation. -Nevertheless, before you proceed with the installation, be aware of the -following noteworthy limitations applicable to version @value{VERSION}: +More and more system services are provided (@pxref{Services}). -@itemize -@item -More and more system services are provided (@pxref{Services}), but some -may be missing. - -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), -as well as a number of X11 window managers. However, KDE is currently -missing. -@end itemize +Nevertheless, before you proceed with the installation, be aware that some +services you rely on may still be missing from version @value{VERSION}. More than a disclaimer, this is an invitation to report issues (and success stories!), and to join us in improving it. @xref{Contributing}, for more @@ -2383,21 +2440,12 @@ the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html, @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, @code{man cryptsetup}} for more information). -@quotation Warning -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 LUKS1 partition would be along these +command sequence to format it as a LUKS partition would be along these lines: @example -cryptsetup luksFormat --type luks1 /dev/sda2 +cryptsetup luksFormat /dev/sda2 cryptsetup open /dev/sda2 my-partition mkfs.ext4 -L my-root /dev/mapper/my-partition @end example @@ -4342,11 +4390,11 @@ this option is primarily useful when the daemon was running with @item --vacuum-database @cindex vacuum the store database @comment Avoid words like 'repair,' 'compress,' and 'optimize.' -Guix uses an sqlite database to keep track of the items in (@pxref{The Store}). -Over time it is possible that the database may grow to a large size and become -fragmented. As a result, one may wish to clear the freed space and join the -partially used pages in the database left behind from removed packages or after -running the garbage collector. Running @command{sudo guix gc +Guix uses an sqlite database to keep track of the items in the store +(@pxref{The Store}). Over time it is possible that the database may grow to a +large size and become fragmented. As a result, one may wish to clear the freed +space and join the partially used pages in the database left behind from removed +packages or after running the garbage collector. Running @command{sudo guix gc --vacuum-database} will lock the database and @code{VACUUM} the store, defragmenting the database and purging freed pages, unlocking the database when it finishes. @@ -4404,15 +4452,7 @@ effect on the version of Guix that user @code{alice} sees, and vice versa. The result of running @command{guix pull} is a @dfn{profile} available -under @file{~/.config/guix/current} containing the latest Guix. Thus, -make sure to add it to the beginning of your search path so that you use -the latest version, and similarly for the Info manual -(@pxref{Documentation}): - -@example -export PATH="$HOME/.config/guix/current/bin:$PATH" -export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" -@end example +under @file{~/.config/guix/current} containing the latest Guix. The @option{--list-generations} or @option{-l} option lists past generations produced by @command{guix pull}, along with details about their provenance: @@ -4734,6 +4774,11 @@ Note that @command{guix time-machine} can trigger builds of channels and their dependencies, and these are controlled by the standard build options (@pxref{Common Build Options}). +If @command{guix time-machine} is executed without any command, it +prints the file name of the profile that would be used to execute the +command. This is sometimes useful if you need to get store file name of +the profile---e.g., when you want to @command{guix copy} it. + @node Inferiors @section Inferiors @@ -5344,7 +5389,8 @@ returns a package for the given channels, and using it as part of your operating system configuration, as in this example: @lisp -(use-modules (guix channels)) +(use-modules (gnu packages package-management) + (guix channels)) (define my-channels ;; Channels that should be available to @@ -5725,7 +5771,7 @@ named @code{keyring} (we recommend making it an @dfn{orphan branch}). @item Introduce an initial @file{.guix-authorizations} in the channel's repository. Do that in a signed commit (@pxref{Commit Access}, for -information on how to sign Git commits.) +information on how to sign Git commits). @item Advertise the channel introduction, for instance on your channel's web @@ -5894,6 +5940,10 @@ The general syntax is: guix shell [@var{options}] [@var{package}@dots{}] @end example +Sometimes an interactive shell session is not desired. An arbitrary +command may be invoked by placing the @code{--} token to separate the +command from the rest of the arguments. + The following example creates an environment containing Python and NumPy, building or downloading any missing package, and runs the @command{python3} command in that environment: @@ -6912,6 +6962,16 @@ directly be used as a file system container image with the environment}, using commands like @command{singularity shell} or @command{singularity exec}. +@cindex AppImage, create an AppImage file with @command{guix pack} +Another format internally based on SquashFS is +@uref{https://appimage.org/, AppImage}. An AppImage file can be created +and executed without any special privileges: + +@example +file=$(guix pack -f appimage --entry-point=bin/guile guile) +$file --help +@end example + Several command-line options allow you to customize your pack: @table @code @@ -7028,6 +7088,48 @@ to install Guix-produced @samp{.rpm} packages on a system where installation or other, non-rpm packs. @end quotation +@item appimage +@cindex AppImage, create an AppImage file with @command{guix pack} +This produces an @uref{https://appimage.org/, AppImage file} with the +@samp{.AppImage} extension. AppImage is a SquashFS volume prefixed with +a runtime that mounts the SquashFS file system and executes the binary +provided with @option{--entry-point}. This results in a self-contained +archive that bundles the software and all its requirements into a single +file. When the file is made executable it runs the packaged software. + +@example +guix pack -f appimage --entry-point=bin/vlc vlc +@end example + +The runtime used by AppImages invokes the @command{fusermount3} command +to mount the image quickly. If that command is unavailable, the +AppImage fails to run, but it can still be started by passing the +@option{--appimage-extract-and-run} flag. + +@quotation Warning +When building an AppImage, always @emph{pass} the @option{--relocatable} +option (or @option{-R}, or @option{-RR}) to make sure the image can be +used on systems where Guix is not installed. A warning is printed when +this option is not used. +@end quotation + +@example +guix pack -f appimage --entry-point=bin/hello --relocatable hello +@end example + +@quotation Note +The resulting AppImage does not conform to the complete standard as it +currently does not contain a @file{.DirIcon} file. This does not impact +functionality of the AppImage itself, but possibly that of software used +to manage AppImages. +@end quotation + +@quotation Note +As the generated AppImage packages the complete dependency graph, it +will be larger than comparable AppImage files found online, which depend +on host system libraries. +@end quotation + @end table @cindex relocatable binaries @@ -7117,10 +7219,10 @@ execution engines listed above by setting the @cindex entry point, for Docker and Singularity images @item --entry-point=@var{command} -Use @var{command} as the @dfn{entry point} of the resulting pack, if the pack -format supports it---currently @code{docker} and @code{squashfs} (Singularity) -support it. @var{command} must be relative to the profile contained in the -pack. +Use @var{command} as the @dfn{entry point} of the resulting pack, if the +pack format supports it---currently @code{docker}, @code{appimage}, and +@code{squashfs} (Singularity) support it. @var{command} must be +relative to the profile contained in the pack. The entry point specifies the command that tools like @code{docker run} or @code{singularity run} automatically start by default. For example, you can @@ -7181,6 +7283,15 @@ This has the same purpose as the same-named option in @command{guix build} (@pxref{Additional Build Options, @option{--expression} in @command{guix build}}). +@item --file=@var{file} +Build a pack containing the package or other object the code within +@var{file} evaluates to. + +This has the same purpose as the same-named option in @command{guix +build} (@pxref{Additional Build Options, @option{--file} in +@command{guix build}}), but it has no shorthand, because @option{-f} +already means @option{--format}. + @anchor{pack-manifest} @item --manifest=@var{file} @itemx -m @var{file} @@ -7264,7 +7375,7 @@ profile---by default @var{name} is @code{guix-profile}, which corresponds to @file{/var/guix} contains the store database (@pxref{The Store}) as well as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in the pack means that the store is ``complete'' and manageable by Guix; -not providing it pack means that the store is ``dead'': items cannot be +not providing it in the pack means that the store is ``dead'': items cannot be added to it or removed from it after extraction of the pack. One use case for this is the Guix self-contained binary tarball @@ -7950,8 +8061,8 @@ inputs. Look up @var{name} among @var{package}'s inputs (or native, propagated, or direct inputs). Return it if found, @code{#f} otherwise. -@var{name} is the name of a package depended on. Here's how you might -use it: +@var{name} is the name of a package or the file name of an origin +depended on. Here's how you might use it: @lisp (use-modules (guix packages) (gnu packages base)) @@ -7962,6 +8073,10 @@ use it: In this example we obtain the @code{gmp} package that is among the direct inputs of @code{coreutils}. + +When looking up an origin, use the name that appears in the origin's +@code{file-name} field or its default file name---e.g., +@code{"foo-1.2.tar.gz"}. @end deffn @cindex development inputs, of a package @@ -8029,7 +8144,7 @@ The build tool chain is part of the @dfn{implicit inputs} of packages---it's usually not listed as part of the various ``inputs'' fields and is instead pulled in by the build system. Consequently, this procedure works by changing the build system of @var{package} so that it -pulls in @var{toolchain} instead of the defaults. @ref{Build Systems}, +pulls in @var{toolchain} instead of the defaults. @xref{Build Systems}, for more on build systems. @end deffn @@ -8168,14 +8283,14 @@ Likewise, the @code{(guix git-download)} module defines the control repository, and the @code{git-reference} data type to describe the repository and revision to fetch. -@deffn {Procedure} git-fetch ref hash-algo hash +@deffn {Procedure} git-fetch ref hash-algo hash [name] Return a fixed-output derivation that fetches @var{ref}, a @code{<git-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 -@deffn {Procedure} git-fetch/lfs ref hash-algo hash +@deffn {Procedure} git-fetch/lfs ref hash-algo hash [name] This is a variant of the @code{git-fetch} procedure that supports the Git @acronym{LFS, Large File Storage} extension. This may be useful to pull some binary test data to run the test suite of a package, for @@ -8238,8 +8353,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 the changeset to fetch. @end table @end deftp @@ -8263,7 +8378,7 @@ retrieve. The URL of the Subversion repository to clone. @item @code{revision} -This string denotes revision to fetch specified as a number. +This string denotes the revision to fetch specified as a number. @item @code{recursive?} (default: @code{#f}) This Boolean indicates whether to recursively fetch Subversion @@ -8302,6 +8417,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 @@ -8539,7 +8691,8 @@ This is exactly what the @option{--with-input} command-line option does The following variant of @code{package-input-rewriting} can match packages to be replaced by name rather than by identity. -@deffn {Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t] +@deffn {Procedure} package-input-rewriting/spec @var{replacements} @ + [#:deep? #t] [#:replace-hidden? #t] Return a procedure that, given a package, applies the given @var{replacements} to all the package graph, including implicit inputs unless @var{deep?} is false. @@ -8548,7 +8701,7 @@ unless @var{deep?} is false. package specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching package and returns a replacement for that package. Matching packages that have the @code{hidden?} property -set are not replaced. +set are not replaced unless @var{replace-hidden?} is set to true. @end deffn The example above could be rewritten this way: @@ -8665,8 +8818,8 @@ Options}). @quotation Note Manifests are @emph{symbolic}: they refer to packages of the channels @emph{currently in use} (@pxref{Channels}). In the example above, -@code{gcc-toolchain} might refer to version 11 today, but it might refer -to version 13 two years from now. +@code{gcc-toolchain} might refer to version 14 today, but it might refer +to version 16 two years from now. If you want to ``pin'' your software environment to specific package versions and variants, you need an additional piece of information: the @@ -9246,6 +9399,9 @@ install all files but those matching the exclusion filters. If both inclusions and exclusions are specified, the exclusions are done on top of the inclusions. @end itemize +@item When a package has multiple outputs, the @code{#:output} argument +can be used to specify which output label the files should be installed +to. @end itemize In all cases, the paths relative to @var{source} are preserved within @var{target}. @@ -9262,6 +9418,9 @@ e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}. @file{share/my-app/sub/file}. @item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to @file{share/my-app/file}. +@item @code{("foo/doc" "share/my-app/doc" #:output "doc")}: Install +@file{"foo/doc"} to @file{"share/my-app/doc"} within the @code{"doc"} +output. @end itemize @end defvar @@ -9502,6 +9661,17 @@ in their documentation}. The key @code{#:go} can be used to specify the Go compiler package with which to build the package. +The phase @code{check} provides a wrapper for @code{go test} which +builds a test binary (or multiple binaries), vets the code and then runs +the test binary. Build, test and test binary flags can be provided as +@code{#:test-flags} parameter, default is @code{'()}. See @code{go help +test} and @code{go help testflag} for more details. + +The key @code{#:embed-files}, default is @code{'()}, provides a list of +future embedded files or regexps matching files. They will be copied to +build directory after @code{unpack} phase. See +@url{https://pkg.go.dev/embed} for more details. + @end defvar @defvar glib-or-gtk-build-system @@ -9757,6 +9927,18 @@ The API is slightly different from @var{python-build-system}: @item @code{#:use-setuptools?} and @code{#:test-target} is removed. @item +@code{#:configure-flags} is changed. Instead of a list +this option must be a JSON object, whose interpretation +depends on the build backend. For instance the example from +@url{https://peps.python.org/pep-0517/#config-settings,PEP 517} +should be written as @code{'(@@ ("CC" "gcc") ("--global-option" +("--some-global-option")) ("--build-option" ("--build-option1" +"--build-option2")))} +@item +@code{#:backend-path} is added. It defaults to @code{#false}, but when +set to a list it will be appended to Python’s search path and overrides +the definition in @file{pyproject.toml}. +@item @code{#:build-backend} is added. It defaults to @code{#false} and will try to guess the appropriate backend based on @file{pyproject.toml}. @item @@ -10429,7 +10611,7 @@ argument interactively, at the REPL (@pxref{Using Guix Interactively}). Keep in mind that build phases are code evaluated at the time the package is actually built. This explains why the whole @code{modify-phases} expression above is quoted (it comes after the -@code{'} or apostrophe): it is @dfn{staged} for later execution. +@code{#~} or hash-tilde): it is @dfn{staged} for later execution. @xref{G-Expressions}, for an explanation of code staging and the @dfn{code strata} involved. @@ -10555,13 +10737,19 @@ Make @var{file} writable for its owner. @deffn {Procedure} copy-recursively source destination @ [#:log (current-output-port)] [#:follow-symlinks? #f] @ - [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t] + [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t] @ + [#:select? (const #t)] Copy @var{source} directory to @var{destination}. Follow symlinks if @var{follow-symlinks?} is true; otherwise, just preserve them. Call -@var{copy-file} to copy regular files. When @var{keep-mtime?} is true, -keep the modification time of the files in @var{source} on those of -@var{destination}. When @var{keep-permissions?} is true, preserve file -permissions. Write verbose output to the @var{log} port. +@var{copy-file} to copy regular files. Call @var{select?}, taking two +arguments, @var{file} and @var{stat}, for each entry in @var{source}, +where @var{file} is the entry's absolute file name and @var{stat} is the +result of @code{lstat} (or @code{stat} if @var{follow-symlinks?} is +true); exclude entries for which @var{select?} does not return true. +When @var{keep-mtime?} is true, keep the modification time of the files +in @var{source} on those of @var{destination}. +When @var{keep-permissions?} is true, preserve file permissions. Write +verbose output to the @var{log} port. @end deffn @deffn {Procedure} delete-file-recursively dir [#:follow-mounts? #f] @@ -11008,17 +11196,14 @@ contain a list of @file{catalog.xml} files (not directories), which are to be found in @file{xml} sub-directories---nothing less. The search path specification looks like this: +@c This is defined at (guix search-paths) as $XML_CATALOG_FILES. @lisp -(package - (name "libxml2") - ;; some fields omitted - (native-search-paths - (list (search-path-specification - (variable "XML_CATALOG_FILES") - (separator " ") - (files '("xml")) - (file-pattern "^catalog\\.xml$") - (file-type 'regular))))) +(search-path-specification + (variable "XML_CATALOG_FILES") + (separator " ") + (files '("xml")) + (file-pattern "^catalog\\.xml$") + (file-type 'regular)) @end lisp Worry not, search path specifications are usually not this tricky. @@ -11054,15 +11239,16 @@ The type of file being matched---@code{'directory} or @code{'regular}, though it can be any symbol returned by @code{stat:type} (@pxref{File System, @code{stat},, guile, GNU Guile Reference Manual}). -In the libxml2 example above, we would match regular files; in the -Python example, we would match directories. +In the @env{XML_CATALOG_FILES} example above, we would match regular +files; in the Python example, we would match directories. @item @code{file-pattern} (default: @code{#f}) This must be either @code{#f} or a regular expression specifying files to be matched @emph{within} the sub-directories specified by the @code{files} field. -Again, the libxml2 example shows a situation where this is needed. +Again, the @env{XML_CATALOG_FILES} example shows a situation where this +is needed. @end table @end deftp @@ -11070,6 +11256,15 @@ Some search paths are not tied by a single package but to many packages. To reduce duplications, some of them are pre-defined in @code{(guix search-paths)}. +@defvar $SGML_CATALOG_FILES +@defvarx $XML_CATALOG_FILES +These two search paths indicate where the +@url{https://www.oasis-open.org/specs/a401.htm,TR9401 catalog}@footnote{ +Alternatively known as SGML catalog.} or +@url{https://www.oasis-open.org/committees/download.php/14809/xml-catalogs.html, +XML catalog} files can be found. +@end defvar + @defvar $SSL_CERT_DIR @defvarx $SSL_CERT_FILE These two search paths indicate where X.509 certificates can be found @@ -12154,6 +12349,26 @@ 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. +@findex assume-valid-file-name +@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 + +@cindex relative file name, in @code{local-file} +@findex assume-source-relative-file-name +@var{file} can be wrapped in the @code{assume-source-relative-file-name} +syntactic keyword. When this is done, the file name will be looked up +relative to the source file where it appears even when it is not a +string literal. + This is the declarative counterpart of the @code{interned-file} monadic procedure (@pxref{The Store Monad, @code{interned-file}}). @end deffn @@ -13432,6 +13647,56 @@ Lastly, @var{expr} may refer to a zero-argument monadic procedure (@pxref{The Store Monad}). The procedure must return a derivation as a monadic value, which is then passed through @code{run-with-store}. +@item --development +@itemx -D +Build the ``development environment'' (build dependencies) of the +following package. + +For example, the following command builds the inputs of @code{hello}, +but @emph{not} @code{hello} itself, and also builds @code{guile}: + +@example +guix build -D hello guile +@end example + +Notice that @option{-D} (or @option{--development}) only applies to the +immediately following package on the command line. Under the hood, it +uses @code{package->development-manifest} +(@pxref{package-development-manifest, +@code{package->development-manifest}}). + +@quotation Note +The effect of combining @option{--development} with @option{--target} +(for cross-compilation) may not be what you expect: it will +cross-compile all the dependencies of the given package when it is built +natively. +@end quotation + +@cindex dependents of a package, building them +@cindex building the dependents of a package +@anchor{build-dependents} +@item --dependents[=@var{depth}] +@itemx -P [@var{depth}] +Build the dependents of the following package. By default, build all +the direct and indirect dependents; when @var{depth} is provided, limit +to dependents at that distance: 1 for direct dependents, 2 for +dependents of dependents, and so on. + +For example, the command below builds @emph{all} the dependents of libgit2: + +@example +guix build --dependents libgit2 +@end example + +To build all the packages that directly depend on NumPy, run: + +@example +guix build -P1 python-numpy +@end example + +The list of dependents is computed in the same way as with @command{guix +refresh --list-dependent} (@pxref{Invoking guix refresh}). + @item --source @itemx -S Build the source derivations of the packages, rather than the packages @@ -13609,7 +13874,7 @@ guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' If a log is unavailable locally, and unless @option{--no-substitutes} is passed, the command looks for a corresponding log on one of the -substitute servers (as specified with @option{--substitute-urls}). +substitute servers. So for instance, imagine you want to see the build log of GDB on @code{aarch64}, but you are actually on an @code{x86_64} machine: @@ -14077,6 +14342,17 @@ The command below imports metadata for the Acme::Boolean Perl module: guix import cpan Acme::Boolean @end example +Like many other importers, the @code{cpan} importer supports recursive +imports: + +@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 cran @cindex CRAN @cindex Bioconductor @@ -14395,6 +14671,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 @@ -14891,6 +15200,8 @@ result of upgrading one or more packages. @command{guix graph}}, for information on how to visualize the list of dependents of a package. +@xref{build-dependents, @command{guix build --dependents}}, for a +convenient way to build all the dependents of a package. @end table Be aware that the @option{--list-dependent} option only @@ -15097,6 +15408,13 @@ configuration (you need write permissions for the file): guix style -f /etc/config.scm @end example +@item --alphabetical-sort +@itemx -A +Place the top-level package definitions in the given files in +alphabetical order. Package definitions with matching names are placed +with versions in descending order. This option only has an effect in +combination with @option{--whole-file}. + @item --styling=@var{rule} @itemx -S @var{rule} Apply @var{rule}, one of the following styling rules: @@ -16847,7 +17165,7 @@ instance to support new system services. * Keyboard Layout:: How the system interprets key strokes. * Locales:: Language and cultural convention settings. * Services:: Specifying system services. -* Setuid Programs:: Programs running with elevated privileges. +* Privileged Programs:: Programs running with elevated privileges. * X.509 Certificates:: Authenticating HTTPS servers. * Name Service Switch:: Configuring libc's name service switch. * Initial RAM Disk:: Linux-Libre bootstrapping. @@ -17175,10 +17493,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 @@ -17186,8 +17504,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 @@ -17571,9 +17889,9 @@ touch this field. Linux @dfn{pluggable authentication module} (PAM) services. @c FIXME: Add xref to PAM services section. -@item @code{setuid-programs} (default: @code{%setuid-programs}) -List of @code{<setuid-program>}. @xref{Setuid Programs}, for more -information. +@item @code{privileged-programs} (default: @code{%default-privileged-programs}) +List of @code{<privileged-program>}. @xref{Privileged Programs}, for +more information. @item @code{sudoers-file} (default: @code{%sudoers-specification}) @cindex sudoers file @@ -17779,6 +18097,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 @@ -18963,6 +19295,10 @@ symlink: (extra-special-file "/usr/bin/env" (file-append coreutils "/bin/env")) @end lisp + +This procedure is meant for @code{/bin/sh}, @code{/usr/bin/env} and +similar targets. In particular, use for targets under @code{/etc} might +not work as expected if the target is managed by Guix in other ways. @end deffn @defvar host-name-service-type @@ -19097,7 +19433,53 @@ When set to @code{#t} in conjunction with @var{auto-login}, the user will have to press a key before the log-in shell is launched. @item @code{clear-on-logout?} (default: @code{#t}) -When set to @code{#t}, the screen will be cleared after logout. +When set to @code{#t}, the screen will be cleared before showing the +login prompt. The field name is bit unfortunate, since it controls +clearing also before the initial login, not just after a logout. + +@item @code{delay} (default: @code{#f}) +When set to a number, sleep that many seconds after startup. + +@item @code{print-issue} (default: @code{#t}) +When set to @code{#t}, write out a new line and the content of +@file{/etc/issue}. Value of @code{'no-nl} can be used to suppress the +new line. + +@item @code{print-hostname} (default: @code{#t}) +When set to @code{#t}, print the host name before the login prompt. The +host name is printed up to the first dot. Can be set to @code{'long} to +print the full host name. + +@item @code{nice} (default: @code{#f}) +When set to a number, change the process priority using @code{nice}. + +@item @code{working-directory} (default: @code{#f}) +When set to a string, change into that directory before calling the +login program. + +@item @code{root-directory} (default: @code{#f}) +When set to a string, use this directory at the process's root +directory. + +@item @code{shepherd-requirement} +List of shepherd requirements. Unless you know what you are doing, it +is recommended to extend the default list instead of overriding it. + +As an example, when using auto-login on a system with elogind, it is +necessary to wait on the @code{'dbus-system} service: + +@lisp +(modify-services %base-services + (mingetty-service-type config => + (mingetty-configuration + (inherit config) + ;; Automatically log in as "guest". + (auto-login "guest") + (shepherd-requirement + (cons 'dbus-system + (mingetty-configuration-shepherd-requirement + config)))))) +@end lisp @item @code{mingetty} (default: @var{mingetty}) The Mingetty package to use. @@ -19375,9 +19757,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 @@ -19566,7 +19950,7 @@ might want to turn it off for instance in a virtual machine that does not need it and where the extra boot time is a problem. @anchor{guix-configuration-channels} -@item @code{channels} (default: @code{%default-channels}) +@item @code{channels} (default: @code{#f}) List of channels to be specified in @file{/etc/guix/channels.scm}, which is what @command{guix pull} uses by default (@pxref{Invoking guix pull}). @@ -19649,6 +20033,18 @@ A directory path where the @command{guix-daemon} will perform builds. Environment variables to be set before starting the daemon, as a list of @code{key=value} strings. +@item @code{socket-directory-permissions} (default: @code{#o755}) +Permissions to set for the directory @file{/var/guix/daemon-socket}. +This, together with @code{socket-directory-group} and +@code{socket-directory-user}, determines who can connect to the build +daemon via its Unix socket. TCP socket operation is unaffected by +these. + +@item @code{socket-directory-user} (default: @code{#f}) +@itemx @code{socket-directory-group} (default: @code{#f}) +User and group owning the @file{/var/guix/daemon-socket} directory or +@code{#f} to keep the user or group as root. + @end table @end deftp @@ -20615,30 +21011,33 @@ The file name of the processed log file. The following optional settings may be provided: -@table @asis -@item @code{skip-private?} +@table @code +@item debug? +Print debug messages when @code{#true}. + +@item skip-private? When @code{#true} do not mask addresses in private ranges. -@item @code{column} +@item column A 1-based indexed column number. Assume IP address is in the specified column (default is 1). -@item @code{replacement} +@item replacement Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}. -@item @code{ipv4mask} +@item ipv4mask Number of bits to mask in IPv4 addresses. -@item @code{ipv6mask} +@item ipv6mask Number of bits to mask in IPv6 addresses. -@item @code{increment} +@item increment Increment the IP address by the given number. By default this is zero. -@item @code{delimiter} +@item delimiter Log delimiter string. -@item @code{regex} +@item regex Regular expression for detecting IP addresses. Use this instead of @code{column}. @end table @end deftp @@ -20898,24 +21297,32 @@ the user mode network stack,,, qemu, QEMU Documentation}). @cindex DHCP, networking service @defvar dhcp-client-service-type -This is the type of services that run @var{dhcp}, a Dynamic Host Configuration -Protocol (DHCP) client. +This is the type of services that run @var{dhclient}, the ISC Dynamic +Host Configuration Protocol (DHCP) client. @end defvar @deftp {Data Type} dhcp-client-configuration -Data type representing the configuration of the DHCP client service. +Data type representing the configuration of the ISC DHCP client service. @table @asis @item @code{package} (default: @code{isc-dhcp}) -DHCP client package to use. +The ISC DHCP client package to use. @item @code{interfaces} (default: @code{'all}) -Either @code{'all} or the list of interface names that the DHCP client -should listen on---e.g., @code{'("eno1")}. +Either @code{'all} or the list of interface names that the ISC DHCP +client should listen on---e.g., @code{'("eno1")}. + +When set to @code{'all}, the ISC DHCP client listens on all the +available non-loopback interfaces that can be activated. Otherwise the +ISC DHCP client listens only on the specified interfaces. + +@item @code{config-file} (default: @code{#f}) +The configuration file for the ISC DHCP client. -When set to @code{'all}, the DHCP client listens on all the available -non-loopback interfaces that can be activated. Otherwise the DHCP -client listens only on the specified interfaces. +@item @code{version} (default: @code{"4"}) +The DHCP protocol version to use, as a string. Accepted values are +@code{"4"} or @code{"6"} for DHCPv4 or DHCPv6, respectively, as well as +@code{"4o6"}, for DHCPv4 over DHCPv6 (as specified by RFC 7341). @item @code{shepherd-requirement} (default: @code{'()}) @itemx @code{shepherd-provision} (default: @code{'(networking)}) @@ -20926,7 +21333,7 @@ networks. Likewise, @code{shepherd-provision} is a list of Shepherd service names (symbols) provided by this service. You might want to change the -default value if you intend to run several DHCP clients, only one of +default value if you intend to run several ISC DHCP clients, only one of which provides the @code{networking} Shepherd service. @end table @end deftp @@ -21877,6 +22284,12 @@ If @code{#t}, Tor will listen for control commands on the UNIX domain socket @file{/var/run/tor/control-sock}, which will be made writable by members of the @code{tor} group. +@item @code{transport-plugins} (default: @code{'()}) +The list of @code{<tor-transport-plugin>} records to use. +For any transport plugin you include in this list, appropriate +configuration line to enable transport plugin will be automatically +added to the default configuration file. + @end table @end deftp @@ -21905,6 +22318,68 @@ maps ports 22 and 80 of the Onion Service to the local ports 22 and 8080. @end table @end deftp +@cindex pluggable transports, tor +@deftp {Data Type} tor-transport-plugin +Data type representing a Tor pluggable transport plugin in +@code{tor-configuration}. Plugguble transports are programs +that disguise Tor traffic, which can be useful in case Tor is +censored. See the the Tor project's +@url{https://tb-manual.torproject.org/circumvention/, +documentation} and +@url{https://spec.torproject.org/pt-spec/index.html, +specification} for more information. + +Each transport plugin corresponds either to +@code{ClientTransportPlugin ...} or to +@code{ServerTransportPlugin ...} line in the default +configuration file, see @command{man tor}. +Available @code{tor-transport-plugin} fields are: + +@table @asis +@item @code{role} (default: @code{'client}) +This must be either @code{'client} or @code{'server}. Otherwise, +an error is raised. Set the @code{'server} value if you want to +run a bridge to help censored users connect to the Tor network, see +@url{https://community.torproject.org/relay/setup/bridge/, +the Tor project's brige guide}. Set the @code{'client} value +if you want to connect to somebody else's bridge, see +@url{https://bridges.torproject.org/, the Tor project's +``Get Bridges'' page}. In both cases the required +additional configuration should be provided via +@code{#:config-file} option of @code{tor-configuration}. +@item @code{protocol} (default: @code{"obfs4"}) +A string that specifies a pluggable transport protocol. +@item @code{program} +This must be a ``file-like'' object or a string +pointing to the pluggable transport plugin executable. +This option allows the Tor daemon run inside the container +to access the executable and all the references +(e.g. package dependencies) attached to it. +@end table + +Suppose you would like Tor daemon to use obfs4 type obfuscation and +to connect to Tor network via obfs4 bridge (a nonpublic Tor relay with +support for obfs4 type obfuscation). Then you may go to +@url{https://bridges.torproject.org/, https://bridges.torproject.org/} +and get there a couple of bridge lines (each starts with @code{obfs4 ...}) +and use these lines in tor-service-type configuration as follows: +@lisp +(service tor-service-type + (tor-configuration + (config-file (plain-file "torrc" + "\ +UseBridges 1 +Bridge obfs4 ... +Bridge obfs4 ...")) + (transport-plugins + (list (tor-transport-plugin + (program + (file-append + go-gitlab-torproject-org-tpo-anti-censorship-pluggable-transports-lyrebird + "/bin/lyrebird"))))))) +@end lisp +@end deftp + The @code{(gnu services rsync)} module provides the following services: You might want an rsync daemon if you have files that you want available @@ -22920,6 +23395,14 @@ system to use for the upgrade. If no value is provided the #~(@@ (guix system install) installation-os))) @end lisp +@item @code{reboot?} (default: @code{#f}) +This field specifies whether the system should reboot after completing +an unattended upgrade. + +When @code{reboot?} is @code{#t}, services are not restarted before +rebooting. This means that the value for @code{services-to-restart} is +ignored. The updated services will be started after the system reboots. + @item @code{services-to-restart} (default: @code{'(mcron)}) This field specifies the Shepherd services to restart when the upgrade completes. @@ -22987,9 +23470,9 @@ definition (@pxref{operating-system Reference, system-wide packages}). @anchor{wayland-gdm} GDM also supports Wayland: it can itself use Wayland instead of X11 for -its user interface, and it can also start Wayland sessions. The former is -required for the latter, to enable, set @code{wayland?} to @code{#t} in -@code{gdm-configuration}. +its user interface, and it can also start Wayland sessions. Wayland +support is enabled by default. To disable it, set @code{wayland?} to +@code{#f} in @code{gdm-configuration}. @defvar gdm-service-type This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME @@ -23050,7 +23533,7 @@ File name of the @code{dbus-daemon} executable. @item @code{gdm} (default: @code{gdm}) The GDM package to use. -@item @code{wayland?} (default: @code{#f}) +@item @code{wayland?} (default: @code{#t}) When true, enables Wayland in GDM, necessary to use Wayland sessions. @item @code{wayland-session} (default: @code{gdm-wayland-session-wrapper}) @@ -23187,6 +23670,11 @@ The available fields are: @item @code{sddm} (default: @code{sddm}) The SDDM package to use. +@quotation Note +sddm has Qt6 enabled by default. If you want to still use a Qt5 theme, +you need to set it to @code{sddm-qt5}. +@end quotation + @item @code{display-server} (default: "x11") Select display server to use for the greeter. Valid values are @samp{"x11"} or @samp{"wayland"}. @@ -23540,13 +24028,24 @@ 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 -saver to the set of setuid programs and/or add a PAM entry for it. The +saver to the set of privileged programs and/or add a PAM entry for it. The value for this service is a @code{<screen-locker-configuration>} object. -While the default behavior is to setup both a setuid program and PAM +While the default behavior is to setup both a privileged program and PAM entry, these two methods are redundant. Screen locker programs may not execute when PAM is configured and @code{setuid} is set on their executable. In this case, @code{using-setuid?} can be set to @code{#f}. @@ -23599,6 +24098,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 @@ -24453,28 +24960,26 @@ The @code{%desktop-services} variable can be used as the @code{services} field of an @code{operating-system} declaration (@pxref{operating-system Reference, @code{services}}). -Additionally, the @code{gnome-desktop-service-type}, -@code{xfce-desktop-service}, @code{mate-desktop-service-type}, -@code{lxqt-desktop-service-type} and @code{enlightenment-desktop-service-type} -procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To -``add GNOME'' means that system-level services like the backlight adjustment -helpers and the power management utilities are added to the system, extending -@code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with -elevated privileges on a limited number of special-purpose system interfaces. -Additionally, adding a service made by @code{gnome-desktop-service-type} adds -the GNOME metapackage to the system profile. Likewise, adding the Xfce -service not only adds the @code{xfce} metapackage to the system profile, but -it also gives the Thunar file manager the ability to open a ``root-mode'' file -management window, if the user authenticates using the administrator's -password via the standard polkit graphical interface. To ``add MATE'' means -that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE -to operate with elevated privileges on a limited number of special-purpose -system interfaces. Additionally, adding a service of type -@code{mate-desktop-service-type} adds the MATE metapackage to the system -profile. ``Adding Enlightenment'' means that @code{dbus} is extended -appropriately, and several of Enlightenment's binaries are set as setuid, -allowing Enlightenment's screen locker and other functionality to work as -expected. +Additionally, the following procedures add one (or more!) desktop +environments to a system. + +@itemize +@item @code{gnome-desktop-service-type} adds GNOME, +@item @code{plasma-desktop-service-type} adds KDE Plasma, +@item @code{enlightenment-desktop-service-type} adds Enlightenment, +@item @code{lxqt-desktop-service-type} adds LXQt, +@item @code{mate-desktop-service-type} adds MATE, and +@item @code{xfce-desktop-service} adds Xfce. +@end itemize + +These service types add ``metapackages'' such as @code{gnome} or +@code{plasma} to the system profile, but most of them also set up other useful +services that mere packages can't do. + +For example, they may elevate privileges on a limited number of +special-purpose system interfaces and programs. This allows backlight +adjustment helpers, power management utilities, screen lockers, and +other integrated functionality to work as expected. The desktop environments in Guix use the Xorg display server by default. If you'd like to use the newer display server protocol @@ -24833,6 +25338,12 @@ Data type representing the configuration of @command{elogind}. @item @code{hybrid-sleep-mode} (default: @code{'("suspend" "platform" "shutdown")}) (type: list) ... +@item @code{hibernate-delay-seconds} (default: @code{*unspecified*}) (type: integer) +... + +@item @code{suspend-estimation-seconds} (default: @code{*unspecified*}) (type: integer) +... + @end table @end deftp @@ -24972,7 +25483,7 @@ Package object for UDisks. @defvar gvfs-service-type Type for the service that provides virtual file systems for GIO -applicaitons, which enables support for @code{trash:///}, @code{ftp://}, +applications, which enables support for @code{trash://}, @code{ftp://}, @code{sftp://} and many other location schemas in file managers like Nautilus (GNOME Files) and Thunar. @@ -25703,7 +26214,7 @@ via @code{pulseaudio-configuration}, see below. @quotation Warning This service overrides per-user configuration files. If you want -PulseAudio to honor configuration files in @file{~/.config/pulse} you +PulseAudio to honor configuration files in @file{~/.config/pulse}, you have to unset the environment variables @env{PULSE_CONFIG} and @env{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}. @end quotation @@ -25774,7 +26285,7 @@ above example to modify the existing @code{pulseaudio-service-type} via @defvar ladspa-service-type This service sets the @var{LADSPA_PATH} variable, so that programs, which -respect it, e.g. PulseAudio, can load LADSPA plugins. +respect it, e.g.@: PulseAudio, can load LADSPA plugins. The following example will setup the service to enable modules from the @code{swh-plugins} package: @@ -25911,7 +26422,7 @@ configuration. @lisp (service postgresql-service-type (postgresql-configuration - (postgresql postgresql-10))) + (postgresql postgresql))) @end lisp If the services fails to start, it may be due to an incompatible @@ -25938,7 +26449,7 @@ Data type representing the configuration for the @code{postgresql-service-type}. @table @asis -@item @code{postgresql} (default: @code{postgresql-10}) +@item @code{postgresql} PostgreSQL package to use for the service. @item @code{port} (default: @code{5432}) @@ -25980,7 +26491,7 @@ configure the postgresql-service as in this example: (cons* (service postgresql-service-type (postgresql-configuration - (postgresql postgresql-10) + (postgresql postgresql) (extension-packages (list postgis)))) %base-services))) @end lisp @@ -27028,7 +27539,7 @@ user part in user@@domain, same as %u if there's no domain @item %d domain part in user@@domain, empty if there's no domain @item %h -home director +home directory @end table See doc/wiki/Variables.txt for full list. Some examples: @@ -27714,7 +28225,7 @@ remote servers. Run @command{man smtpd.conf} for more information. Make the following commands setgid to @code{smtpq} so they can be executed: @command{smtpctl}, @command{sendmail}, @command{send-mail}, @command{makemap}, @command{mailq}, and @command{newaliases}. -@xref{Setuid Programs}, for more information on setgid programs. +@xref{Privileged Programs}, for more information on setgid programs. @end table @end deftp @@ -28111,23 +28622,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 @@ -31770,8 +32453,17 @@ configuration. Values may themselves be association lists. @end lisp @item @code{extra-content} (default: @code{""}) -Extra content for the @code{http} block. Should be string or a string -valued G-expression. +Additional content to be appended to the @code{http} block. Can either +be a value that can be lowered into a string or a list of such values. +In the former case, it is inserted directly. In the latter, it is +prefixed with indentation and suffixed with a newline. Nested lists are +flattened into one line. + +@lisp +(extra-content "include /etc/nginx/custom-config.conf;") +(extra-content `("include /etc/nginx/custom-config.conf;" + ("include " ,%custom-config.conf ";"))) +@end lisp @end table @end deftp @@ -31824,7 +32516,9 @@ you don't have a key or you don't want to use HTTPS. Whether the server should add its configuration to response. @item @code{raw-content} (default: @code{'()}) -A list of raw lines added to the server block. +A list of strings or file-like objects to be appended to the server +block. Each item is prefixed with indentation and suffixed with a new +line. Nested lists are flattened. @end table @end deftp @@ -31846,7 +32540,16 @@ the default port is 80, and a different port can be specified explicitly. @item @code{extra-content} -A string or list of strings to add to the upstream block. +Additional content to be appended to the upstream block. Can be a +string or file-like object or list of thereof. In case of list, each +item is prefixed with indentation and suffixed with a new line. Nested +lists are flattened. + +@lisp +(extra-content "include /etc/nginx/custom-config.conf;") +(extra-content `("include /etc/nginx/custom-config.conf;" + ("include " ,%custom-config.conf ";"))) +@end lisp @end table @end deftp @@ -31861,11 +32564,13 @@ URI which this location block matches. @anchor{nginx-location-configuration body} @item @code{body} -Body of the location block, specified as a list of strings. This can contain -many -configuration directives. For example, to pass requests to a upstream -server group defined using an @code{nginx-upstream-configuration} block, -the following directive would be specified in the body @samp{(list "proxy_pass +Body of the location block, specified as a list of strings or file-like +objects. Each item is prefixed with indentation and suffixed with a new +line. Nested lists are flattened. + +For example, to pass requests to a upstream server group defined using +an @code{nginx-upstream-configuration} block, the following directive +would be specified in the body @samp{(list "proxy_pass http://upstream-name;")}. @end table @@ -32597,25 +33302,33 @@ This is the type of the agate service, whose value should be an (service agate-service-type (agate-configuration (content "/srv/gemini") - (cert "/srv/cert.pem") - (key "/srv/key.rsa"))) + (certificates "/srv/gemini-certs"))) @end lisp The example above represents the minimal tweaking necessary to get Agate -up and running. Specifying the path to the certificate and key is +up and running. Specifying the path to the certificate and key directory is always necessary, as the Gemini protocol requires TLS by default. -To obtain a certificate and a key, you could, for example, use OpenSSL, -running a command similar to the following example: +If the specified @code{certificates} path is writable by Agate, and contains +no valid pre-generated key and certificate, Agate will try to generate +them on the first start. In this case you should pass at least one +hostname using the @code{hostnames} option. +If the specified directory is read-only, key and certificate should be +pre-generated by the user. + +To obtain a certificate and a key in DER format, you could, for example, +use OpenSSL, running commands similar to the following example: @example -openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \ - -days 3650 -nodes -subj "/CN=example.com" +openssl genpkey -out key.der -outform DER -algorithm RSA \ + -pkeyopt rsa_keygen_bits:4096 +openssl req -x509 -key key.der -outform DER -days 3650 -out cert.der \ + -subj "/CN=example.com" @end example Of course, you'll have to replace @i{example.com} with your own domain name, and then point the Agate configuration towards the path of the -generated key and certificate. +directory with the generated key and certificate using the @code{certificates} option. @end defvar @@ -32629,30 +33342,38 @@ The package object of the Agate server. @item @code{content} (default: @file{"/srv/gemini"}) The directory from which Agate will serve files. -@item @code{cert} (default: @code{#f}) -The path to the TLS certificate PEM file to be used for encrypted -connections. Must be filled in with a value from the user. +@item @code{certificates} (default: @file{"/srv/gemini-certs"}) +Root of the certificate directory. Must be filled in with a value from the user. -@item @code{key} (default: @code{#f}) -The path to the PKCS8 private key file to be used for encrypted -connections. Must be filled in with a value from the user. - -@item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")}) +@item @code{addresses} (default: @code{'("[::]:1965" "0.0.0.0:1965")}) A list of the addresses to listen on. -@item @code{hostname} (default: @code{#f}) -The domain name of this Gemini server. Optional. +@item @code{hostnames} (default: @code{'()}) +Virtual hosts for the Gemini server. If multiple values are +specified, corresponding directory names should be present in the @code{content} +directory. Optional. -@item @code{lang} (default: @code{#f}) +@item @code{languages} (default: @code{#f}) RFC 4646 language code(s) for text/gemini documents. Optional. -@item @code{silent?} (default: @code{#f}) -Set to @code{#t} to disable logging output. +@item @code{only-tls13?} (default: @code{#f}) +Set to @code{#t} to disable support for TLSv1.2. @item @code{serve-secret?} (default: @code{#f}) Set to @code{#t} to serve secret files (files/directories starting with a dot). +@item @code{central-configuration?} (default: @code{#f}) +Set to @code{#t} to look for the .meta configuration file in the @code{content} +root directory and will ignore @code{.meta} files in other directories + +@item @code{ed25519?} (default: @code{#f}) +Set to @code{#t} to generate keys using the Ed25519 signature algorithm +instead of the default ECDSA. + +@item @code{skip-port-check?} (default: @code{#f}) +Set to @code{#t} to skip URL port check even when a @code{hostname} is specified. + @item @code{log-ip?} (default: @code{#t}) Whether or not to output IP addresses when logging. @@ -33498,6 +34219,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 @@ -33944,13 +34669,15 @@ The wireguard package to use for this service. The interface name for the VPN. @item @code{addresses} (default: @code{'("10.0.0.1/32")}) -The IP addresses to be assigned to the above interface. +List of strings or G-expressions which represent the IP addresses to be +assigned to the above interface. @item @code{port} (default: @code{51820}) The port on which to listen for incoming connections. @item @code{dns} (default: @code{'())}) -The DNS server(s) to announce to VPN clients via DHCP. +List of strings or G-expressions which represent the DNS server(s) to +announce to VPN clients via DHCP. @item @code{monitor-ips?} (default: @code{#f}) @cindex Dynamic IP, with Wireguard @@ -33967,23 +34694,48 @@ an mcron time specification (@pxref{Guile Syntax,,,mcron}). @item @code{private-key} (default: @code{"/etc/wireguard/private.key"}) The private key file for the interface. It is automatically generated -if the file does not exist. +if the file does not exist. If this field is @code{#f}, a private key +is not automatically created and the path is not serialized to the +configuration file. + +@item @code{bootstrap-private-key?} (default: @code{#t}) +Whether or not the private key should be generated automatically if it +does not exist. + +Setting this to @code{#f} allows one to set the private key using +command substitution. One example shown in the @code{wg-quick(8)} +manual is retrieving a private key using @code{password-store}. This +can be achieved with the following code: + +@lisp +(wireguard-configuration + (private-key + #~(string-append "<(" + #$(file-append password-store "/bin/pass") + ;; Wireguard replaces %i with the interface name. + " WireGuard/private-keys/%i)"))) +@end lisp + @item @code{peers} (default: @code{'()}) The authorized peers on this interface. This is a list of @var{wireguard-peer} records. @item @code{pre-up} (default: @code{'()}) -The script commands to be run before setting up the interface. +List of strings or G-expressions. These are script snippets which will +be executed before setting up the interface. @item @code{post-up} (default: @code{'()}) -The script commands to be run after setting up the interface. +List of strings or G-expressions. These are script snippets which will +be executed after setting up the interface. @item @code{pre-down} (default: @code{'()}) -The script commands to be run before tearing down the interface. +List of strings or G-expressions. These are script snippets which will +be executed before tearing down the interface. @item @code{post-down} (default: @code{'()}) -The script commands to be run after tearing down the interface. +List of strings or G-expressions. These are script snippets which will +be executed after tearing down the interface. @item @code{table} (default: @code{"auto"}) The routing table to which routes are added, as a string. There are two @@ -34009,8 +34761,8 @@ The optional endpoint for the peer, such as The peer public-key represented as a base64 string. @item @code{preshared-key} (default: @code{#f}) -An optional pre-shared key file for this peer. The given file will not -be autogenerated. +An optional pre-shared key file for this peer that can be either a +string or a G-expression. The given file will not be autogenerated. @item @code{allowed-ips} A list of IP addresses from which incoming traffic for this peer is @@ -34395,7 +35147,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 @@ -34414,7 +35166,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 @@ -34674,6 +35426,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 @@ -35234,6 +36025,32 @@ Ignore cpuid check for supported CPU models. @item @code{thermald} (default: @var{thermald}) Package object of thermald. +@cindex PowerTOP +@cindex power consumption tuning with PowerTOP +@subsubheading PowerTOP + +The @code{(gnu services pm)} module also provides a service definition +for @uref{https://01.org/powertop/, PowerTOP}, a power consumption +analysis and tuning tool. When started, it tunes Linux kernel settings +to reduce power consumption. + +@defvar powertop-service-type +The service type for PowerTOP. No configuration is necessary. When the +service starts, it executes @code{powertop --auto-tune}. + +@lisp +(service powertop-service-type) +@end lisp +@end defvar + +Available @code{powertop-configuration} fields are: + +@deftypevr {@code{powertop-configuration} parameter} package powertop +The PowerTOP package. Defaults to @code{powertop} in the @code{(gnu +packages linux)} module + +@end deftypevr + @end table @end deftp @@ -38798,7 +39615,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") @@ -38893,7 +39710,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. @@ -38909,6 +39726,7 @@ like to serve. @subsubheading Joycond service @cindex joycond +@cindex nintendo controllers The joycond service allows the pairing of Nintendo joycon game controllers over Bluetooth. (@pxref{Desktop Services} for setting up Bluetooth.) @@ -38923,7 +39741,10 @@ The joycond package to use. @end deftp @defvar joycond-service-type -Service type for the joycond service. +Service type for the joycond service. It also extends the +@code{udev-service-type} with the @code{joycond} package (provided via +the @code{joycond-configuration} configuration), so that joycond +controllers can be detected and used by an unprivileged user. @end defvar @subsubheading The Battle for Wesnoth Service @@ -39293,10 +40114,10 @@ coordinator. Possible record types are described below. The systems for which this agent should fetch builds. The agent process will use the current system it's running on as the default. -@item @code{max-parallel-builds} (default: @code{1}) +@item @code{max-parallel-builds} (default: @code{#f}) The number of builds to perform in parallel. -@item @code{max-parallel-uploads} (default: @code{1}) +@item @code{max-parallel-uploads} (default: @code{#f}) The number of uploads to perform in parallel. @item @code{max-allocated-builds} (default: @code{#f}) @@ -39319,6 +40140,8 @@ derivations aren't already available. URLs from which to attempt to fetch substitutes for build inputs, if the input store items aren't already available. +@item @code{extra-options} (default: @var{'()}) +Extra command line options for @code{guix-build-coordinator-agent}. @end table @end deftp @@ -39438,6 +40261,12 @@ Extra command line options for @code{guix-data-service}. @item @code{extra-process-jobs-options} (default: @var{'()}) Extra command line options for @code{guix-data-service-process-jobs}. +@item @code{git-repositories} (default: @var{#f}) +List of git-repository information to insert into the database. + +@item @code{build-servers} (default: @var{#f}) +List of build-server information to insert into the database. + @end table @end deftp @@ -39474,7 +40303,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 @@ -40343,12 +41172,54 @@ The following is an example @code{dicod-service-type} configuration. The @code{(gnu services docker)} module provides the following services. +@cindex containerd, container runtime +@defvar containerd-service-type + +This service type operates containerd +@url{https://containerd.io,containerd}, a daemon responsible for +overseeing the entire container lifecycle on its host system. This +includes image handling, storage management, container execution, +supervision, low-level storage operations, network connections, and +more. + +@end defvar + +@deftp {Data Type} containerd-configuration +This is the data type representing the configuration of containerd. + +@table @asis + +@item @code{containerd} (default: @code{containerd}) +The containerd daemon package to use. + +@item @code{debug?} (default @code{#f}) +Enable or disable debug output. + +@item @code{environment-variables} (default: @code{'()}) +List of environment variables to set for @command{containerd}. + +This must be a list of strings where each string has the form +@samp{@var{key}=@var{value}} as in this example: + +@lisp +(list "HTTP_PROXY=socks5://127.0.0.1:9150" + "HTTPS_PROXY=socks5://127.0.0.1:9150") +@end lisp + +@end table +@end deftp + @defvar docker-service-type This is the type of the service that runs @url{https://www.docker.com,Docker}, a daemon that can execute application bundles (sometimes referred to as ``containers'') in isolated environments. +The @code{containerd-service-type} service need to be added to a system +configuration, otherwise a message about not any service provides +@code{containerd} will be displayed during @code{guix system +reconfigure}. + @end defvar @deftp {Data Type} docker-configuration @@ -40363,7 +41234,7 @@ The Docker daemon package to use. The Docker client package to use. @item @code{containerd} (default: @var{containerd}) -The Containerd package to use. +This field is deprecated in favor of @code{containerd-service-type} service. @item @code{proxy} (default @var{docker-libnetwork-cmd-proxy}) The Docker user-land networking proxy package to use. @@ -40402,8 +41273,8 @@ create and run application bundles (aka. ``containers''). The value for this service is the Singularity package to use. The service does not install a daemon; instead, it installs helper programs as -setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke -@command{singularity run} and similar commands. +setuid-root (@pxref{Privileged Programs}) such that unprivileged users can +invoke @command{singularity run} and similar commands. @end defvar @cindex OCI-backed, Shepherd services @@ -40425,30 +41296,40 @@ processes as Shepherd Services. (service oci-container-service-type (list (oci-container-configuration - (image "prom/prometheus") (network "host") + (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") (ports '(("9000" . "9000") ("9090" . "9090")))) (oci-container-configuration (image "grafana/grafana:10.0.1") (network "host") - (ports - '(("3000" . "3000"))) (volumes '("/var/lib/grafana:/var/lib/grafana"))))) @end lisp -In this example two different Shepherd services are going be added to the +In this example three different Shepherd services are going to be added to the system. Each @code{oci-container-configuration} record translates to a @code{docker run} invocation and its fields directly map to options. You can refer to the -@url{https://docs.docker.com/engine/reference/commandline/run,upstream}, -documentation for the semantics of each value. If the images are not found they -will be +@url{https://docs.docker.com/engine/reference/commandline/run,upstream} +documentation for the semantics of each value. If the images are not found, +they will be @url{https://docs.docker.com/engine/reference/commandline/pull/,pulled}. The -spawned services are going to be attached to the host network and are supposed -to behave like other processes. +services with @code{(network "host")} are going to be attached to the +host network and are supposed to behave like native processes with regard to +networking. @end defvar @@ -40464,13 +41345,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 @@ -40478,22 +41376,45 @@ 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{log-file} (type: maybe-string) +When @code{log-file} is set, it names the file to which the service's +standard output and standard error are redirected. @code{log-file} is created +if it does not exist, otherwise it is appended to. + +@item @code{auto-start?} (default: @code{#t}) (type: boolean) +Whether this service should be started automatically by the Shepherd. If it +is @code{#f}, the service has to be started manually with @command{herd start}. + +@item @code{respawn?} (default: @code{#f}) (type: boolean) +Whether to have Shepherd restart the service when it stops, for instance when +the underlying process dies. + +@item @code{shepherd-actions} (default: @code{'()}) (type: list-of-symbols) +This is a list of @code{shepherd-action} records defining actions supported +by the 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: @@ -40502,11 +41423,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: @@ -40515,7 +41437,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. @@ -40525,11 +41448,67 @@ Set the current user inside the spawned container. You can refer to the documentation for semantics. @item @code{workdir} (default: @code{""}) (type: string) -Set the current working for the spawned Shepherd service. +Set the current working directory for the spawned Shepherd service. 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} invocation. + +@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 @@ -40669,7 +41648,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: @@ -40980,11 +41959,285 @@ Mode for filter. @c End of auto-generated fail2ban documentation. -@node Setuid Programs -@section Setuid Programs +@cindex resize-file-system +@subsubheading Resize File System Service + +This service type lets you resize a live file system during boot, which +can be convenient if a Guix image is flashed on an SD Card (e.g. for an +embedded device) or uploaded to a VPS. In both cases the medium the +image will reside upon may be larger than the image you want to produce. + +For an embedded device booting from an SD card you may use something like: +@lisp +(service resize-file-system-service-type + (resize-file-system-configuration + (file-system + (file-system (device (file-system-label "root")) + (type "ext4"))))) +@end lisp + +@quotation Warning +Be extra cautious to use the correct device and type. The service has +little error handling of its own and relies on the underlying tools. +Wrong use could end in loss of data or the corruption of the operating +system. +@end quotation + +Partitions and file systems are grown to the maximum size available. +File systems can only grow when they are on the last partition on a +device and have empty space available. + +This service supports the ext2, ext3, ext4, btrfs, and bcachefs file +systems. + +@table @asis + +@item @code{file-system} (default: @code{#f}) (type: file-system) +The file-system object to resize (@pxref{File Systems}). This object +must have the @code{device} and @code{type} fields set. Other fields +are ignored. + +@item @code{cloud-utils} (default: @code{cloud-utils}) (type: file-like) +The cloud-utils package to use. This package is used for the +@code{growpart} command. + +@item @code{e2fsprogs} (default: @code{e2fsprogs}) (type: file-like) +The e2fsprogs package to use, used for resizing ext2, ext3, and ext4 +file systems. + +@item @code{btrfs-progs} (default: @code{btrfs-progs}) (type: file-like) +The btrfs-progs package to use, used for resizing the btrfs file system. + +@item @code{bcachefs-tools} (default: @code{bcachefs-tools}) (type: file-like) +The bcachefs-tools package to use, used for resizing the bcachefs file system. + +@end table + +@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 + +@cindex DLNA/UPnP +@subsubheading DLNA/UPnP Services +The @code{(gnu services upnp)} module offers services related to +@acronym{UPnP, Universal Plug and Play} and @acronym{DLNA, Digital +Living Network Alliance}, networking protocols that can be used for +media streaming and device interoperability within a local network. For +now, this module provides the @code{readymedia-service-type}. + +@uref{https://sourceforge.net/projects/minidlna/, ReadyMedia} (formerly +known as MiniDLNA) is a DLNA/UPnP-AV media server. The project's +daemon, @code{minidlnad}, can serve media files (audio, pictures, and +video) to DLNA/UPnP-AV clients available on the network. +@code{readymedia-service-type} is a Guix service that wraps around +ReadyMedia's @code{minidlnad}. + +Consider the following configuration: +@lisp +(use-service-modules upnp @dots{}) + +(operating-system + @dots{} + (services + (list (service readymedia-service-type + (readymedia-configuration + (media-directories + (list (readymedia-media-directory + (path "/media/audio") + (types '(A))) + (readymedia-media-directory + (path "/media/video") + (types '(V))) + (readymedia-media-directory + (path "/media/misc")))) + (extra-config '(("notify_interval" . "60"))))) + @dots{}))) +@end lisp + +This sets up the ReadyMedia daemon to serve files from the media folders +specified in @code{media-directories}. The @code{media-directories} +field is mandatory. All other fields (such as network ports and the +server name) come with a predefined default and can be omitted. + +@c %start of fragment + +@deftp {Data Type} readymedia-configuration +Available @code{readymedia-configuration} fields are: + +@table @asis +@item @code{readymedia} (default: @code{readymedia}) (type: package) +The ReadyMedia package to be used for the service. + +@item @code{friendly-name} (default: @code{#f}) (type: maybe-string) +A custom name that will be displayed on connected clients. + +@item @code{media-directories} (type: list) +The list of media folders to serve content from. Each item is a +@code{readymedia-media-directory}. + +@item @code{cache-directory} (default: @code{"/var/cache/readymedia"}) (type: string) +A folder for ReadyMedia's cache files. If not existing already, the +folder will be created as part of the service activation and the +ReadyMedia user will be assigned ownership. + +@item @code{log-directory} (default: @code{"/var/log/readymedia"}) (type: string) +A folder for ReadyMedia's log files. If not existing already, the +folder will be created as part of the service activation and the +ReadyMedia user will be assigned ownership. + +@item @code{port} (default: @code{#f}) (type: maybe-integer) +A custom port that the service will be listening on. + +@item @code{extra-config} (default: @code{'()}) (type: alist) +An association list of further options, as accepted by ReadyMedia. +@end table + +@end deftp + +@c %end of fragment + +@c %start of fragment + +@deftp {Data Type} readymedia-media-directory +A @code{media-directories} entry includes a folder @code{path} and, +optionally, the @code{types} of media files included within the +folder. + +@table @asis +@item @code{path} (type: string) +The media folder location. + +@item @code{types} (default: @code{'()}) (type: list) +A list indicating the types of file included in the media folder. +Valid values are combinations of individual media types, i.e. symbol +@code{A} for audio, @code{P} for pictures, @code{V} for video. An +empty list means that no type is specified. +@end table + +@end deftp + +@c %end of fragment + +@node Privileged Programs +@section Privileged Programs + +@cindex privileged programs @cindex setuid programs @cindex setgid programs +@cindex capabilities, POSIX +@cindex setcap Some programs need to run with elevated privileges, even when they are launched by unprivileged users. A notorious example is the @command{passwd} program, which users can run to change their @@ -40995,46 +42248,48 @@ obvious security reasons. To address that, @command{passwd} should be (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual}, for more info about the setuid mechanism). -The store itself @emph{cannot} contain setuid programs: that would be a -security issue since any user on the system can write derivations that +The store itself @emph{cannot} contain privileged programs: that would be +a security issue since any user on the system can write derivations that populate the store (@pxref{The Store}). Thus, a different mechanism is -used: instead of changing the setuid or setgid bits directly on files that -are in the store, we let the system administrator @emph{declare} which +used: instead of directly granting permissions to files that are in +the store, we let the system administrator @emph{declare} which programs should be entrusted with these additional privileges. -The @code{setuid-programs} field of an @code{operating-system} -declaration contains a list of @code{<setuid-program>} denoting the +The @code{privileged-programs} field of an @code{operating-system} +declaration contains a list of @code{<privileged-program>} denoting the names of programs to have a setuid or setgid bit set (@pxref{Using the Configuration System}). For instance, the @command{mount.nfs} program, which is part of the nfs-utils package, with a setuid root can be designated like this: @lisp -(setuid-program - (program (file-append nfs-utils "/sbin/mount.nfs"))) +(privileged-program + (program (file-append nfs-utils "/sbin/mount.nfs")) + (setuid? #t)) @end lisp And then, to make @command{mount.nfs} setuid on your system, add the previous example to your operating system declaration by appending it to -@code{%setuid-programs} like this: +@code{%default-privileged-programs} like this: @lisp (operating-system ;; Some fields omitted... - (setuid-programs - (append (list (setuid-program - (program (file-append nfs-utils "/sbin/mount.nfs")))) - %setuid-programs))) + (privileged-programs + (append (list (privileged-program + (program (file-append nfs-utils "/sbin/mount.nfs")) + (setuid? #t)) + %default-privileged-programs))) @end lisp -@deftp {Data Type} setuid-program -This data type represents a program with a setuid or setgid bit set. +@deftp {Data Type} privileged-program +This data type represents a program with special privileges, such as setuid @table @asis @item @code{program} -A file-like object having its setuid and/or setgid bit set. +A file-like object to which all given privileges should apply. -@item @code{setuid?} (default: @code{#t}) +@item @code{setuid?} (default: @code{#f}) Whether to set user setuid bit. @item @code{setgid?} (default: @code{#f}) @@ -41048,22 +42303,27 @@ defaults to root. GID (integer) group name (string) for the group owner of the program, defaults to root. +@item @code{capabilities} (default: @code{#f}) +A string representing the program's POSIX capabilities, as described by +the @code{cap_to_text(3)} man page from the libcap package, or @code{#f} +to make no changes. + @end table @end deftp -A default set of setuid programs is defined by the -@code{%setuid-programs} variable of the @code{(gnu system)} module. +A default set of privileged programs is defined by the +@code{%default-privileged-programs} variable of the @code{(gnu system)} module. -@defvar %setuid-programs -A list of @code{<setuid-program>} denoting common programs that are -setuid-root. +@defvar {Scheme Variable} %default-privileged-programs +A list of @code{<privileged-program>} denoting common programs with +elevated privileges. The list includes commands such as @command{passwd}, @command{ping}, @command{su}, and @command{sudo}. @end defvar -Under the hood, the actual setuid programs are created in the -@file{/run/setuid-programs} directory at system activation time. The +Under the hood, the actual privileged programs are created in the +@file{/run/privileged/bin} directory at system activation time. The files in this directory refer to the ``real'' binaries, which are in the store. @@ -42005,7 +43265,7 @@ once @command{reconfigure} has completed. @end quotation This effects all the configuration specified in @var{file}: user -accounts, system services, global package list, setuid programs, etc. +accounts, system services, global package list, privileged programs, etc. The command starts system services specified in @var{file} that are not currently running; if a service is currently running this command will arrange for it to be upgraded the next time it is stopped (e.g.@: by @@ -42158,6 +43418,23 @@ This command also installs bootloader on the targets specified in @file{my-os-config}, unless the @option{--no-bootloader} option was passed. +@item installer +Run the installer. Usually the installer is built as an @file{iso} +image, copied to a USB Stick or DVD, and booted from (@ref{USB Stick and +DVD Installation}). If your machine already runs Guix and you still +want to run the installer, e.g., for testing purposes, you can skip the +step of creating an @file{iso} and run for instance: + +@example +guix system installer --dry-run +@end example + +@quotation Note +If you do not use @option{--dry-run} then you need to run as root. Be +@emph{very careful} when running the installer as root, it can cause +data loss or render your system unbootable! +@end quotation + @item vm @cindex virtual machine @cindex VM @@ -42224,7 +43501,7 @@ image. The @option{--no-graphic} option will instruct @command{guix system} to spawn a headless VM that will use the invoking tty for IO. Among other things, this enables copy-pasting, and scrollback. Use the @kbd{ctrl-a} -prefix to issue QEMU commands; e.g. @kbd{ctrl-a h} prints a help, +prefix to issue QEMU commands; e.g.@: @kbd{ctrl-a h} prints a help, @kbd{ctrl-a x} quits the VM, and @kbd{ctrl-a c} switches between the QEMU monitor and the VM. @@ -42250,7 +43527,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 @@ -43378,10 +44655,10 @@ In this example, the effect would be to add an @file{/etc/issue} file pointing to the given file. @end defvar -@defvar setuid-program-service-type -Type for the ``setuid-program service''. This service collects lists of +@defvar privileged-program-service-type +Type for the ``privileged-program service''. This service collects lists of executable file names, passed as gexps, and adds them to the set of -setuid and setgid programs on the system (@pxref{Setuid Programs}). +privileged programs on the system (@pxref{Privileged Programs}). @end defvar @defvar profile-service-type @@ -43521,7 +44798,7 @@ Services,,, shepherd, The GNU Shepherd Manual}, for details. When true, this is the delay in seconds before restarting a failed service. -@item @code{start} +@item @code{start} (default: @code{#~(const #t)}) @itemx @code{stop} (default: @code{#~(const #f)}) The @code{start} and @code{stop} fields refer to the Shepherd's facilities to start and stop processes (@pxref{Service De- and @@ -43540,6 +44817,30 @@ This is a list of @code{shepherd-action} objects (see below) defining herd @var{action} @var{service} [@var{arguments}@dots{}] @end example +@item @code{free-form} (default: @code{#f}) +When set, this field replaces the @code{start}, @code{stop}, and +@code{actions} fields. It is meant to be used when the service +definition comes from some other source, typically the service +collection provided by the Shepherd proper (@pxref{Service Collection,,, +shepherd, The GNU Shepherd Manual}). + +@cindex REPL service, for shepherd +For example, the snippet below defines a service for the Shepherd's +built-in @acronym{REPL, read-eval-print loop} service (@pxref{REPL +Service,,, shepherd, The GNU Shepherd Manual}): + +@lisp +(shepherd-service + (provision '(repl)) + (modules '((shepherd service repl))) + (free-form #~(repl-service))) +@end lisp + +In this case, the service object is returned by the @code{repl-service} +procedure of the Shepherd, so all the @code{free-form} G-expression does +is call that procedure. Note that the @code{provision} field must be +consistent with the actual service provision. + @item @code{auto-start?} (default: @code{#t}) Whether this service should be started automatically by the Shepherd. If it is @code{#f} the service has to be started manually with @code{herd start}. @@ -43940,7 +45241,9 @@ available for the configuration record. @var{sub-documentation} is a @code{(@var{field-name} @var{configuration-name})} tuple. @var{field-name} is the name of the field which takes another configuration record as its value, and -@var{configuration-name} is the name of that configuration record. +@var{configuration-name} is the name of that configuration record. The +same value may be used for multiple @var{field-name}s, in case a field +accepts different types of configurations. @var{sub-documentation} is only needed if there are nested configuration records. For example, the @code{getmail-configuration} record @@ -44050,7 +45353,7 @@ Below is an example of a record type created using "The owner's email address.") (contacts (list-of-contact-configurations '()) - "A list of @@code@{contact-configuation@} records which contain + "A list of @@code@{contact-configuration@} records which contain information about all your contacts.")) @end lisp @@ -44451,6 +45754,7 @@ services)}. * Mail: Mail Home Services. Services for managing mail. * Messaging: Messaging Home Services. Services for managing messaging. * Media: Media Home Services. Services for managing media. +* Sway: Sway window manager. Setting up the Sway configuration. * Networking: Networking Home Services. Networking services. * Miscellaneous: Miscellaneous Home Services. More services. @end menu @@ -45312,6 +46616,13 @@ The Shepherd package to use. @item auto-start? (default: @code{#t}) Whether or not to start Shepherd on first login. +@item daemonize? (default: @code{#t}) +Whether or not to run Shepherd in the background. + +@item silent? (default: @code{#t}) +When true, the @command{shepherd} process does not write +anything to standard output when started automatically. + @item services (default: @code{'()}) A list of @code{<shepherd-service>} to start. You should probably use the service extension @@ -45915,6 +47226,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 @@ -46356,6 +47676,409 @@ kodi} for more information. @end table @end deftp +@node Sway window manager +@subsection Sway window manager + +@cindex sway, Home Service +@cindex sway, configuration +The @code{(gnu home services sway)} module provides +@code{home-sway-service-type}, a home service to configure the +@uref{https://github.com/swaywm/sway,Sway window manager for Wayland} in +a declarative way. + +Here is an example of a service and its configuration that you could add +to the @code{services} field of your @code{home-environment}: + +@lisp +(service home-sway-service-type + (sway-configuration + (gestures + '((swipe:3:down . "move to scratchpad") + (swipe:3:up . "scratchpad show"))) + (outputs + (list (sway-output + (identifier '*) + (background (file-append sway + "\ +/share/backgrounds/sway/Sway_Wallpaper_Blue_1920x1080.png"))))))) +@end lisp + +The above example describes a Sway configuration in which +@itemize +@item +all monitors use a particular wallpaper whose @file{.png} is provided by +the @code{sway} package; +@item +swiping down (resp.@: up) with three fingers moves the active window to +the scratchpad (resp.@: shows/hides the scratchpad). +@end itemize + +@quotation Note +This home service only sets up the configuration file and profile +packages for Sway. It does @emph{not} start Sway in any way. If you +want to do so, you might be interested in using +@code{greetd-wlgreet-sway-session} instead. + +The procedure @code{sway-configuration->file} defined below can be used +to provide the value for the @emph{optional} @code{sway-configuration} +field of @code{greetd-wlgreet-sway-session}. +@end quotation + +@deffn {Procedure} sway-configuration->file config +This procedure takes one argument @code{config}, which must be a +@code{sway-configuration} record (defined below), and returns a +file-like object representing the serialized configuration. +@end deffn + +@defvar home-sway-service-type +This is a home service type to set up Sway. It takes care of: +@itemize +@item +providing a @file{~/.config/sway/config} file, +@item +adding Sway-related packages to your profile. +@end itemize +@end defvar + +@deftp {Data Type} sway-configuration +This configuration record describes the Sway configuration +(see@ @cite{sway(5)}). Available fields are: + +@table @asis +@item @code{variables} (default: @code{%sway-default-variables}) +The value of this field is an association list in which keys are symbols +and values are either strings, G-expressions or file-like objects +(@pxref{G-Expressions}). + +Example: +@lisp +(variables `((mod . "Mod4") ; string + (term ; file-append + . ,(file-append foot "/bin/foot")) + (Term ; G-expression + . ,#~(string-append #$foot "/bin/foot")))) +@end lisp + +@quotation Note +Default keybindings assume the existence of variables named @code{$mod}, +@code{$left}, @code{$right}, @code{$up} and @code{$down}. If you choose +not to define these variables, make sure to remove keybindings referring +to them. +@end quotation + +@item @code{keybindings} (default: @code{%sway-default-keybindings}) +This field describes keybindings for the @emph{default} mode. The value +is an association list: keys are symbols and values are either strings +or G-expressions. + +The following snippet launches the terminal when pressing @kbd{$mod+t} +and @kbd{$mod+Shift+t} (assuming that a variable @code{$term} is +defined): +@lisp +`(($mod+t . ,#~(string-append "exec " #$foot "/bin/foot")) + ($mod+Shift+t . "exec $term")) +@end lisp + +@item @code{gestures} (default: @code{%sway-default-gestures}) +Similar to the previous field, but for finger-gestures. + +The following snippet allows to navigate through workspaces by swiping +right and left with three fingers: +@lisp +'((swipe:3:right . "workspace next_on_output") + (swipe:3:left . "workspace prev_on_output")) +@end lisp + +@item @code{packages} (default: @code{%sway-default-packages}) +This field describes a list of packages to add to the user profile. At +the moment, the default value only adds @code{sway} to the profile. + +@item @code{inputs} (default: @code{'()}) +List of @code{sway-input} configuration records (described below). + +@item @code{outputs} (default: @code{'()}) +List of @code{sway-output} configuration records (described below). + +@item @code{bar} (optional @code{sway-bar} record) +Optional @code{sway-bar} record (described below) to configure a Sway +bar. + +@item @code{modes} (default: @code{%sway-default-modes}) +List of @code{sway-mode} records (described below) to add modes to the +Sway configuration. The default value @code{%sway-default-modes} adds +the ``resize'' mode of the default Sway configuration (as described +below). + +@item @code{startup+reload-programs} (default: @code{'()}) +Programs to execute at startup time @emph{and} after every configuration +reload. The value of this field is a list of strings, G-expressions or +file-like objects (@pxref{G-Expressions}). + +@item @code{startup-programs} (default: @code{%sway-default-startup-programs}) +Programs to execute at startup time. As above, values of this field are +a list of strings, G-expressions or file-like objects. + +The default value, @code{%sway-default-startup-programs}, executes @code{swayidle} +in order to lock the screen after 5@ minutes of inactivity (displaying a +background distributed with Sway) and turn the screen off after 10@ +minutes of inactivity. + +@item @code{extra-content} (default: @code{'()}) +Lines to add to the configuration file. The value of this field is a +list of strings or G-expressions. +@end table +@end deftp + +@deftp {Data Type} sway-input +@code{sway-input} records describe input blocks (see@ +@cite{sway-input(5)}). For example, the following snippet makes all +keyboards use a French layout, in which @kbd{capslock} has been remapped +to @kbd{ctrl}: +@lisp +(sway-input (identifier "type:keyboard") + (layout + (keyboard-layout "fr" #:options '("ctrl:nocaps")))) +@end lisp + +Available fields for @code{sway-input} configuration records are: + +@table @asis +@item @code{identifier} (default: @code{'*}) +Identifier of the input. The field accepts symbols and strings. If the +@code{identifier} is a symbol, it is inserted as is; if it is a string, +it will be quoted in the configuration file. + +@item @code{layout} (optional @code{<keyboard-layout>} record) +Keyboard specific option. Field specifying the layout to use for the +input. The value must be a @code{<keyboard-layout>} record +(@pxref{Keyboard Layout}). + +@quotation Note +@code{(gnu home services sway)} does not re-export the +@code{keyboard-layout} procedure. +@end quotation + +@item @code{disable-while-typing} (optional boolean) +If @code{#t} (resp.@: @code{#f}) enables (resp.@: disables) the +``disable while typing'' option for this input. + +@item @code{disable-while-trackpointing} (optional boolean) +If @code{#t} (resp.@: @code{#f}), enables (resp.@: disables) the +``disable while track-pointing'' option for this input. + +@item @code{tap} (optional boolean) +Enables or disables the ``tap'' option, which allows clicking by tapping +on a touchpad. + +@item @code{extra-content} (default: @code{'()}) +Lines to add to the input block. The value of this field must a list +whose elements are either strings or G-expressions. +@end table +@end deftp + +@deftp {Data Type} sway-output +@code{sway-output} records describe Sway outputs (see@ +@cite{sway-output(5)}). Available fields are: + +@table @asis +@item @code{identifier} (default: @code{'*}) +Identifier of the monitor. The field accepts symbols and strings. If +the @code{identifier} is a symbol, it is inserted as is; if it is a +string, it will be quoted in the configuration file. + +@item @code{resolution} (optional string) +This string defines the resolution of the monitor. + +@item @code{position} (optional) +The (optional) value of this field must be a @code{point}. +Example: +@lisp +(position + (point (x 1920) + (y 0))) +@end lisp + +@item @code{background} (optional) +The value of this field describes what wallpaper to use on this output. +The field accepts the following types of values: +@itemize +@item +a string, +@item +a G-expression, +@item +a file-like object, +@item +a pair. The first argument of this pair must be a string, a +G-expression or a file-like object. The second element describes how +the wallpaper will be displayed. It must be a symbol among +@code{stretch}, @code{fill}, @code{fit}, @code{center} and @code{tile}. + +If the second element is not specified (@i{i.e.}@: when the value is not +a pair), the @code{fill} mode will be used. +@end itemize + +@quotation Note +In order to use an SVG file, you must have @code{librsvg} in your +profile (@i{e.g.}@: by adding it in the @code{packages} field of +@code{sway-configuration}). +@end quotation + +@item @code{extra-content} (default: @code{'()}) +List defining additional lines to add to the output configuration block. +Elements of the list must be either strings or G-expressions. +@end table +@end deftp + +@deftp {Data Type} sway-border-color +@table @code +@item border +Color of the border. +@item background +Color of the background. +@item text +Color of the text. +@end table +@end deftp + +@deftp {Data Type} sway-color +@table @asis +@item @code{background} (optional string) +Background color of the bar. + +@item @code{statusline} (optional string) +Text color of the status line. + +@item @code{focused-background} (optional string) +Background color of the bar on the currently focused monitor. + +@item @code{focused-statusline} (optional string) +Text color of the statusline on the currently focused monitor. + +@item @code{focused-workspace} (optional @code{sway-border-color}) +Color scheme for focused workspaces. + +@item @code{active-workspace} (optional @code{sway-border-color}) +Color scheme for active workspaces. + +@item @code{inactive-workspace} (optional @code{sway-border-color}) +Color scheme for inactive workspaces. + +@item @code{urgent-workspace} (optional @code{sway-border-color}) +Color scheme for workspaces containing ``urgent windows''. + +@item @code{binding-mode} (optional @code{sway-border-color}) +Color scheme for the binding mode indicator. +@end table +@end deftp + +@deftp {Data Type} sway-bar +Describes the Sway bar (see@ @cite{sway-bar(5)}). + +@table @asis +@item @code{identifier} (default: @code{'bar0}) +Identifier of the bar. The value must be a symbol. + +@item @code{position} (optional) +Specify the position of the bar. Accepted values are @code{'top} or +@code{'bottom}. + +@item @code{hidden-state} (optional) +Specify the appearance of the bar when it is hidden. Accepted values are +@code{'hide} or @code{'show}. + +@item @code{binding-mode-indicator} (optional) +Boolean enabling or disabling the binding mode indicator. + +@item @code{colors} (optional) +An optional @code{sway-color} configuration record. + +@item @code{status-command} (optional) +This field accept strings, G-expressions and executable file-like +values. The default value is a command (string) that prints the date +and time every second. + +Each line printed on @code{stdout} by this command (or script) will be +displayed on the status area of the bar. + +Below are a few examples using: +@itemize +@item +a string: @code{"while date +'%Y-%m-%d %X'; do sleep 1; done"}, +@item +a G-exp: +@lisp +#~(string-append "while " + #$coreutils "/bin/date" + " +'%Y-%m-%d %X'; do sleep 1; done") +@end lisp +@item +an executable file: +@lisp +(program-file + "sway-bar-status" + #~(begin + (use-modules (ice-9 format) + (srfi srfi-19)) + (let loop () + (let* ((date (date->string + (current-date) + "~d/~m/~Y (~a) • ~H:~M:~S"))) + (format #t "~a~%~!" date) + (sleep 1) + (loop))))) +@end lisp +@end itemize + +@item @code{mouse-bindings} (default: @code{'()}) +This field accepts an associative list. Keys are integers describing +mouse events. Values can either be strings or G-expressions. + +The module @code{(gnu home services sway)} exports constants +@code{%ev-code-mouse-left}, @code{%ev-code-mouse-right} and +@code{%ev-code-mouse-scroll-click} whose values are integers +corresponding to left, right and scroll click respectively. For +example, with @code{(mouse-bindings `((,%ev-code-mouse-left . "exec +$term")))}, left clicks in the status bar open the terminal (assuming +that the variable @code{$term} is bound to a terminal). +@end table +@end deftp + +@deftp {Data Type} sway-mode +Describes a Sway mode (see@ @cite{sway(5)}). For example, the following +snippet defines the resize mode of the default Sway configuration: +@example +(sway-mode + (mode-name "resize") + (keybindings + '(($left . "resize shrink width 10px") + ($right . "resize grow width 10px") + ($down . "resize grow height 10px") + ($up . "resize shrink height 10px") + (Left . "resize shrink width 10px") + (Right . "resize grow width 10px") + (Down . "resize grow height 10px") + (Up . "resize shrink height 10px") + (Return . "mode \"default\"") + (Escape . "mode \"default\"")))) +@end example + +@table @asis +@item @code{mode-name} (default: @code{"default"}) +Name of the mode. This field accepts strings. + +@item @code{keybindings} (default: @code{'()}) +This field describes keybindings. The value is an association list: +keys are symbols and values are either strings or G-expressions, as +above. + +@item @code{mouse-bindings} (default: @code{'()}) +Ditto, but keys are mouse events (integers). Constants +@code{%ev-code-mouse-*} described above can be used as helpers to define +mouse bindings. +@end table +@end deftp + @node Networking Home Services @subsection Networking Home Services @@ -46400,6 +48123,38 @@ documentation of the system service (@pxref{Networking Services, This section lists Home services that lack a better place. +@subsubheading Beets Service + +@cindex Beets service, for Home +The @code{(gnu home services music)} module provides the following +service: + +@defvar home-beets-service-type +@uref{https://beets.io, Beets} is a music file and metadata manager +that can be used via its command-line interface, @command{beet}. Beets +requires a YAML configuration file and this Guix Home service is to +create such file. +@end defvar + +The service can be used as follows: + +@lisp +(service home-beets-service-type + (home-beets-configuration (directory "/home/alice/music"))) +@end lisp + +Additional options can be specified via the service wild-card field +@code{extra-options}: + +@lisp +(service home-beets-service-type + (home-beets-configuration + (directory "/home/alice/music") + (extra-options '(" +import: + move: yes")))) +@end lisp + @subsubheading Dictionary Service @cindex dictionary service, for Home @@ -47121,15 +48876,19 @@ the previous partition end. It defaults to @code{0} which means that there is no offset applied. @item @code{file-system} (default: @code{"ext4"}) -The partition file system as a string, defaulting to @code{"ext4"}. The -supported values are @code{"vfat"}, @code{"fat16"}, @code{"fat32"} and -@code{"ext4"}. @code{"vfat"}, @code{"fat16"} and @code{"fat32"} -partitions without the @code{'esp} flag are by default LBA compatible. +The partition file system as a string, defaulting to @code{"ext4"}. + +The supported values are @code{"vfat"}, @code{"fat16"}, @code{"fat32"}, +@code{"btrfs"}, and @code{"ext4"}. + +@code{"vfat"}, @code{"fat16"}, and @code{"fat32"} partitions without the +@code{'esp} flag are by default LBA compatible. @item @code{file-system-options} (default: @code{'()}) The partition file system creation options that should be passed to the partition creation tool, as a list of strings. This is only supported -when creating @code{"ext4"} partitions. +when creating @code{"vfat"}, @code{"fat16"}, @code{"fat32"} or +@code{"ext4"} partitions. See the @code{"extended-options"} man page section of the @code{"mke2fs"} tool for a more complete reference. 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" "$@" |