diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 144 | ||||
| -rw-r--r-- | doc/guix.texi | 440 |
2 files changed, 467 insertions, 117 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index 958fc44cbd..3a402c13a9 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -26,7 +26,7 @@ choice. * Packaging Guidelines:: Growing the distribution. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. -* Tracking Bugs and Patches:: Keeping it all organized. +* Tracking Bugs and Changes:: Keeping it all organized. * Commit Access:: Pushing to the official repository. * Updating the Guix Package:: Updating the Guix package definition. * Writing Documentation:: Improving documentation in GNU Guix. @@ -1161,11 +1161,11 @@ readability of patches. Seasoned Guix developers may also want to look at the section on commit access (@pxref{Commit Access}). This mailing list is backed by a Debbugs instance, which allows us to -keep track of submissions (@pxref{Tracking Bugs and Patches}). Each -message sent to that mailing list gets a new tracking number assigned; -people can then follow up on the submission by sending email to -@code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} is -the tracking number (@pxref{Sending a Patch Series}). +keep track of submissions (@pxref{Tracking Bugs and Changes}). +Each message sent to that mailing list gets a new tracking number +assigned; people can then follow up on the submission by sending email +to @code{@var{ISSUE_NUMBER}@@debbugs.gnu.org}, where @var{ISSUE_NUMBER} +is the tracking number (@pxref{Sending a Patch Series}). Please write commit logs in the ChangeLog format (@pxref{Change Logs,,, standards, GNU Coding Standards}); you can check the commit history for @@ -1257,48 +1257,9 @@ and which optional dependencies should be used. In particular, avoid adding the @code{texlive-tiny} package or @code{texlive-union} procedure instead. @item -For important changes, check that dependent packages (if applicable) are -not affected by the change; @code{guix refresh --list-dependent -@var{package}} will help you do that (@pxref{Invoking guix refresh}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2016-10/msg00933.html>. -@cindex branching strategy -@cindex rebuild scheduling strategy -Depending on the number of dependent packages and thus the amount of -rebuilding induced, commits go to different branches, along these lines: - -@table @asis -@item 300 dependent packages or less -@code{master} branch (non-disruptive changes). - -@item between 300 and 1,800 dependent packages -@code{staging} branch (non-disruptive changes). This branch is intended -to be merged in @code{master} every 6 weeks or so. Topical changes -(e.g., an update of the GNOME stack) can instead go to a specific branch -(say, @code{gnome-updates}). This branch is not expected to be -buildable or usable until late in its development process. - -@item more than 1,800 dependent packages -@code{core-updates} branch (may include major and potentially disruptive -changes). This branch is intended to be merged in @code{master} every -6 months or so. This branch is not expected to be buildable or usable -until late in its development process. -@end table - -All these branches are @uref{https://@value{SUBSTITUTE-SERVER-1}, -tracked by our build farm} and merged into @code{master} once -everything has been successfully built. This allows us to fix issues -before they hit users, and to reduce the window during which pre-built -binaries are not available. - -When we decide to start building the @code{staging} or -@code{core-updates} branches, they will be forked and renamed with the -suffix @code{-frozen}, at which time only bug fixes may be pushed to the -frozen branches. The @code{core-updates} and @code{staging} branches -will remain open to accept patches for the next cycle. Please ask on -the mailing list or IRC if unsure where to place a patch. -@c TODO: It would be good with badges on the website that tracks these -@c branches. Or maybe even a status page. +Check that dependent packages (if applicable) are not affected by the +change; @code{guix refresh --list-dependent @var{package}} will help you +do that (@pxref{Invoking guix refresh}). @item @cindex determinism, of build processes @@ -1574,16 +1535,17 @@ $ guix shell -D guix [env]$ git send-email --to=@var{ISSUE_NUMBER}@@debbugs.gnu.org -2 @end example -@node Tracking Bugs and Patches -@section Tracking Bugs and Patches +@node Tracking Bugs and Changes +@section Tracking Bugs and Changes -This section describes how the Guix project tracks its bug reports and -patch submissions. +This section describes how the Guix project tracks its bug reports, +patch submissions and topic branches. @menu -* The Issue Tracker:: The official bug and patch tracker. -* Debbugs User Interfaces:: Ways to interact with Debbugs. -* Debbugs Usertags:: Tag reports with custom labels. +* The Issue Tracker:: The official bug and patch tracker. +* Managing Patches and Branches:: How changes to Guix are managed. +* Debbugs User Interfaces:: Ways to interact with Debbugs. +* Debbugs Usertags:: Tag reports with custom labels. @end menu @node The Issue Tracker @@ -1600,6 +1562,55 @@ email to @email{bug-guix@@gnu.org}, while patch submissions are filed against the @code{guix-patches} package by sending email to @email{guix-patches@@gnu.org} (@pxref{Submitting Patches}). +@node Managing Patches and Branches +@subsection Managing Patches and Branches +@cindex branching strategy +@cindex rebuild scheduling strategy + +Changes should be posted to @email{guix-patches@@gnu.org}. This mailing +list fills the patch-tracking database (@pxref{The Issue Tracker}). It +also allows patches to be picked up and tested by the quality assurance +tooling; the result of that testing eventually shows up on the dashboard +at @indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where +@var{ISSUE_NUMBER} is the number assigned by the issue tracker. Leave +time for a review, without committing anything. + +As an exception, some changes considered ``trivial'' or ``obvious'' may +be pushed directly to the @code{master} branch. This includes changes +to fix typos and reverting commits that caused immediate problems. This +is subject to being adjusted, allowing individuals to commit directly on +non-controversial changes on parts they’re familiar with. + +Changes which affect more than 300 dependent packages (@pxref{Invoking +guix refresh}) should first be pushed to a topic branch other than +@code{master}; the set of changes should be consistent---e.g., ``GNOME +update'', ``NumPy update'', etc. This allows for testing: the branch +will automatically show up at +@indicateurl{https://qa.guix.gnu.org/branch/@var{branch}}, with an +indication of its build status on various platforms. + +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}). 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 +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. + @node Debbugs User Interfaces @subsection Debbugs User Interfaces @@ -1816,23 +1827,14 @@ If you get commit access, please make sure to follow the policy below (discussions of the policy can take place on @email{guix-devel@@gnu.org}). -Changes should be posted to @email{guix-patches@@gnu.org}. This mailing -list fills the patch-tracking database (@pxref{Tracking Bugs and -Patches}). It also allows patches to be picked up and tested by the -quality assurance tooling; the result of that testing eventually shows -up on the dashboard at -@indicateurl{https://qa.guix.gnu.org/issue/@var{ISSUE_NUMBER}}, where -@var{ISSUE_NUMBER} is the number assigned by the issue tracker. Leave -time for a review, without committing anything (@pxref{Submitting -Patches}). If you didn’t receive any reply after one week (two weeks -for more significant changes), and if you're confident, it's OK to -commit. +Ensure you're aware of how the changes should be handled +(@pxref{Managing Patches and Branches}) prior to being pushed to the +repository, especially for the @code{master} branch. -As an exception, some changes considered ``trivial'' or ``obvious'' may -be pushed directly. This includes changes to fix typos and reverting -commits that caused immediate problems. This is subject to being -adjusted, allowing individuals to commit directly on non-controversial -changes on parts they’re familiar with. +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. 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., diff --git a/doc/guix.texi b/doc/guix.texi index e6bff33a37..0cdc528c1c 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -33,7 +33,7 @@ Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021, 2023 Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@* -Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@* +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@* @@ -258,6 +258,7 @@ Package Management * Invoking guix package:: Package installation, removal, etc. * Substitutes:: Downloading pre-built binaries. * Packages with Multiple Outputs:: Single source package, multiple outputs. +* Invoking guix locate:: Locating packages that provide a file. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. * Invoking guix time-machine:: Running an older revision of Guix. @@ -637,18 +638,18 @@ includes POWER9 systems such as the RYF Talos II mainboard}. This platform is available as a "technology preview": although it is supported, substitutes are not yet available from the build farm (@pxref{Substitutes}), and some packages may fail to -build (@pxref{Tracking Bugs and Patches}). That said, the Guix +build (@pxref{Tracking Bugs and Changes}). That said, the Guix community is actively working on improving this support, and now is a great time to try it and get involved! @item riscv64-linux little-endian 64-bit RISC-V processors, specifically RV64GC, and -Linux-Libre kernel. This platform is available as a "technology preview": -although it is supported, substitutes are not yet available from the -build farm (@pxref{Substitutes}), and some packages may fail to build -(@pxref{Tracking Bugs and Patches}). That said, the Guix community is -actively working on improving this support, and now is a great time to -try it and get involved! +Linux-Libre kernel. This platform is available as a "technology +preview": although it is supported, substitutes are not yet available +from the build farm (@pxref{Substitutes}), and some packages may fail to +build (@pxref{Tracking Bugs and Changes}). That said, the Guix +community is actively working on improving this support, and now is a +great time to try it and get involved! @end table @@ -3297,6 +3298,7 @@ guix install emacs-guix * Invoking guix package:: Package installation, removal, etc. * Substitutes:: Downloading pre-built binaries. * Packages with Multiple Outputs:: Single source package, multiple outputs. +* Invoking guix locate:: Locating packages that provide a file. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. * Invoking guix time-machine:: Running an older revision of Guix. @@ -4417,6 +4419,134 @@ the output of @command{guix package --list-available} (@pxref{Invoking guix package}). +@node Invoking guix locate +@section Invoking @command{guix locate} + +@cindex file, searching in packages +@cindex file search +@cindex searching for packages +There's so much free software out there that sooner or later, you will +need to search for packages. The @command{guix search} command that +we've seen before (@pxref{Invoking guix package}) lets you search by +keywords: + +@example +guix search video editor +@end example + +@cindex searching for packages, by file name +Sometimes, you instead want to find which package provides a given file, +and this is where @command{guix locate} comes in. Here is how you can +find which package provides the @command{ls} command: + +@example +$ guix locate ls +coreutils@@9.1 /gnu/store/@dots{}-coreutils-9.1/bin/ls +@end example + +Of course the command works for any file, not just commands: + +@example +$ guix locate unistr.h +icu4c@@71.1 /gnu/store/@dots{}/include/unicode/unistr.h +libunistring@@1.0 /gnu/store/@dots{}/include/unistr.h +@end example + +You may also specify @dfn{glob patterns} with wildcards. For example, +here is how you would search for packages providing @file{.service} +files: + +@example +$ guix locate -g '*.service' +man-db@@2.11.1 @dots{}/lib/systemd/system/man-db.service +wpa-supplicant@@2.10 @dots{}/system-services/fi.w1.wpa_supplicant1.service +@end example + +The @command{guix locate} command relies on a database that maps file +names to package names. By default, it automatically creates that +database if it does not exist yet by traversing packages available +@emph{locally}, which can take a few minutes (depending on the size of +your store and the speed of your storage device). + +@quotation Note +For now, @command{guix locate} builds its database based on purely local +knowledge---meaning that you will not find packages that never reached +your store. Eventually it will support downloading a pre-built database +so you can potentially find more packages. +@end quotation + +By default, @command{guix locate} first tries to look for a system-wide +database, usually under @file{/var/cache/guix/locate}; if it does not +exist or is too old, it falls back to the per-user database, by default +under @file{~/.cache/guix/locate}. On a multi-user system, +administrators may want to periodically update the system-wide database +so that all users can benefit from it. + +The general syntax is: + +@example +guix locate [@var{options}@dots{}] @var{file}@dots{} +@end example + +@noindent +... where @var{file} is the name of a file to search for (specifically, +the ``base name'' of the file: files whose parent directories are called +@var{file} are not matched). + +The available options are as follows: + +@table @code +@item --glob +@item -g +Interpret @var{file}@dots{} as @dfn{glob patterns}---patterns that may +include wildcards, such as @samp{*.scm} to denote all files ending in +@samp{.scm}. + +@item --stats +Display database statistics. + +@item --update +@itemx -u +Update the file database. + +By default, the database is automatically updated when it is too old. + +@item --clear +Clear the database and re-populate it. + +This option lets you start anew, ensuring old data is removed from the +database, which also avoids having an endlessly growing database. By +default @command{guix locate} automatically does that periodically, +though infrequently. + +@item --database=@var{file} +Use @var{file} as the database, creating it if necessary. + +By default, @command{guix locate} picks the database under +@file{~/.cache/guix} or @file{/var/cache/guix}, whichever is the most +recent one. + +@item --method=@var{method} +@itemx -m @var{method} +Use @var{method} to select the set of packages to index. Possible +values are: + +@table @code +@item manifests +This is the default method: it works by traversing profiles on the +machine and recording packages it encounters---packages you or other +users of the machine installed, directly or indirectly. It is fast but +it can miss other packages available in the store but not referred to by +any profile. + +@item store +This is a slower but more exhaustive method: it checks among all the +existing packages those that are available in the store and records +them. +@end table +@end table + + @node Invoking guix gc @section Invoking @command{guix gc} @@ -5641,18 +5771,99 @@ machines with limited resources. Let's say you have a bunch of custom package variants or personal packages that you think would make little sense to contribute to the Guix project, but would like to have these packages transparently available to you at the -command line. You would first write modules containing those package -definitions (@pxref{Package Modules}), maintain them in a Git repository, and -then you and anyone else can use it as an additional channel to get packages -from. Neat, no? +command line. By creating a @dfn{channel}, you can use and publish such +a package collection. This involves the following steps: + +@enumerate +@item +Channels live in a Git repository so the first step, when creating a +channel, is to create its repository: + +@example +mkdir my-channel +cd my-channel +git init +@end example + +@item +The next step is to create files containing package modules +(@pxref{Package Modules}), each of which will contain one or more +package definitions (@pxref{Defining Packages}). A channel can provide +things other than packages, such as build systems or services; we're +using packages as most common use case. + +For example, Alice might want to provide a module called @code{(alice +packages greetings)} that will provide her favorite ``hello world'' +implementations. To do that Alice will create a directory corresponding +to that module name. + +@example +mkdir -p alice/packages +$EDITOR alice/packages/greetings.scm +git add alice/packages/greetings.scm +@end example + +You can name your package modules however you like; the main constraint +to keep in mind is to avoid name clashes with other package collections, +which is why our hypothetical Alice wisely chose the @code{(alice +packages @dots{})} name space. + +Note that you can also place modules in a sub-directory of the +repository; @pxref{Package Modules in a Sub-directory}, for more info on +that. + +@item +With this first module in place, the next step is to test the packages +it provides. This can be done with @command{guix build}, which needs to +be fold to look for modules in the Git checkout. For example, assuming +@code{(alice packages greetings)} provides a package called +@code{hi-from-alice}, Alice will run this command from the Git checkout: + +@example +guix build -L. hi-from-alice +@end example + +@noindent +... where @code{-L.} adds the current directory to Guile's load path +(@pxref{Load Paths,,, guile, GNU Guile Reference Manual}). + +@item +It might take Alice a few iterations to obtain satisfying package +definitions. Eventually Alice will commit this file: + +@example +git commit +@end example + +As a channel author, consider bundling authentication material with your +channel so that users can authenticate it. @xref{Channel +Authentication}, and @ref{Specifying Channel Authorizations}, for info +on how to do it. + +@item +To use Alice's channel, anyone can now add it to their channel file +(@pxref{Specifying Additional Channels}) and run @command{guix pull} +(@pxref{Invoking guix pull}): + +@example +$EDITOR ~/.config/guix/channels.scm +guix pull +@end example + +Guix will now behave as if the root directory of that channel's Git +repository had been permanently added to the Guile load path. In this +example, @code{(alice packages greetings)} will automatically be found +by the @command{guix} command. +@end enumerate + +Voilà! @c What follows stems from discussions at @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as @c earlier discussions on guix-devel@gnu.org. @quotation Warning -Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and -publish your personal channel to the world, we would like to share a few words -of caution: +Before you publish your channel, we would like to share a few words of +caution: @itemize @item @@ -5663,13 +5874,11 @@ available to all Guix users and benefit from the project's quality assurance process. @item -When you maintain package definitions outside Guix, we, Guix developers, -consider that @emph{the compatibility burden is on you}. Remember that -package modules and package definitions are just Scheme code that uses various -programming interfaces (APIs). We want to remain free to change these APIs to -keep improving Guix, possibly in ways that break your channel. We never -change APIs gratuitously, but we will @emph{not} commit to freezing APIs -either. +Package modules and package definitions are Scheme code that uses +various programming interfaces (APIs). We, Guix developers, never +change APIs gratuitously, but we do @emph{not} commit to freezing APIs +either. When you maintain package definitions outside Guix, we consider +that @emph{the compatibility burden is on you}. @item Corollary: if you're using an external channel and that channel breaks, please @@ -5683,21 +5892,6 @@ share your improvements, which are basic tenets of email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. @end quotation -To create a channel, create a Git repository containing your own package -modules and make it available. The repository can contain anything, but a -useful channel will contain Guile modules that export packages. Once you -start using a channel, Guix will behave as if the root directory of that -channel's Git repository has been added to the Guile load path (@pxref{Load -Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel -contains a file at @file{my-packages/my-tools.scm} that defines a Guile -module, then the module will be available under the name @code{(my-packages -my-tools)}, and you will be able to use it like any other module -(@pxref{Modules,,, guile, GNU Guile Reference Manual}). - -As a channel author, consider bundling authentication material with your -channel so that users can authenticate it. @xref{Channel -Authentication}, and @ref{Specifying Channel Authorizations}, for info -on how to do it. @node Package Modules in a Sub-directory @@ -6995,7 +7189,7 @@ docker run -ti guile-guile-readline /bin/guile @end example @noindent -where @var{file} is the image returned by @var{guix pack}, and +where @var{file} is the image returned by @command{guix pack}, and @code{guile-guile-readline} is its ``image tag''. See the @uref{https://docs.docker.com/engine/reference/commandline/load/, Docker documentation} for more information. @@ -22578,7 +22772,7 @@ and setuid enabled. One can thus disable setuid: (service screen-locker-service-type (screen-locker-configuration (name "swaylock") - (program (file-append xlockmore "/bin/xlock")) + (program (file-append swaylock "/bin/swaylock")) (using-pam? #t) (using-setuid? #f))) @end lisp @@ -36710,7 +36904,8 @@ Defaults to @samp{'()}. @end deftypevr @deftypevr {@code{cgit-configuration} parameter} file-object readme -Text which will be used as default value for @code{cgit-repo-readme}. +Text which will be used as default @code{repository-cgit-configuration} +@code{readme}. Defaults to @samp{""}. @@ -36875,7 +37070,7 @@ Defaults to @samp{"/"}. @end deftypevr @deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories -A list of @dfn{cgit-repo} records to use with config. +A list of @code{repository-cgit-configuration} records. Defaults to @samp{'()}. @@ -42797,6 +42992,135 @@ for example). @end deftp +@subsubheading Inputrc Profile Service +@cindex inputrc +@cindex readline + +The @uref{https://tiswww.cwru.edu/php/chet/readline/rltop.html, GNU +Readline package} includes Emacs and vi editing modes, with the ability +to customize the configuration with settings in the @file{~/.inputrc} +file. With the @code{gnu home services shells} module, you can setup +your readline configuration in a predictable manner, as shown below. +For more information about configuring an @file{~/.inputrc} file, +@pxref{Readline Init File,,, readline, GNU Readline}. + +@defvar home-inputrc-service-type + +This is the service to setup various @file{.inputrc} configurations. The +settings in @file{.inputrc} are read by all programs which are linked +with GNU Readline. + +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-inputrc-service-type + (home-inputrc-configuration + (key-bindings + `(("Control-l" . "clear-screen"))) + (variables + `(("bell-style" . "visible") + ("colored-completion-prefix" . #t) + ("editing-mode" . "vi") + ("show-mode-in-prompt" . #t))) + (conditional-constructs + `(("$if mode=vi" . + ,(home-inputrc-configuration + (variables + `(("colored-stats" . #t) + ("enable-bracketed-paste" . #t))))) + ("$else" . + ,(home-inputrc-configuration + (variables + `(("show-all-if-ambiguous" . #t))))) + ("endif" . #t) + ("$include" . "/etc/inputrc") + ("$include" . ,(file-append + (specification->package "readline") + "/etc/inputrc")))))) +@end lisp + +The example above starts with a combination of @code{key-bindings} and +@code{variables}. The @code{conditional-constructs} show how it is +possible to add conditionals and includes. In the example above +@code{colored-stats} is only enabled if the editing mode is @code{vi} +style, and it also reads any additional configuration located in +@file{/etc/inputrc} or in @file{/gnu/store/@dots{}-readline/etc/inputrc}. + +The value associated with a @code{home-inputrc-service-type} instance +must be a @code{home-inputrc-configuration} record, as described below. + +@end defvar + +@anchor{home-inputrc-configuration} +@deftp {Data Type} home-inputrc-configuration +Available @code{home-inputrc-configuration} fields are: + +@table @asis +@item @code{key-bindings} (default: @code{'()}) (type: alist) +Association list of readline key bindings to be added to the +@file{~/.inputrc} file. + +@lisp +'((\"Control-l\" . \"clear-screen\")) +@end lisp + +turns into + +@example +Control-l: clear-screen +@end example + +@item @code{variables} (default: @code{'()}) (type: alist) +Association list of readline variables to set. + +@lisp +'((\"bell-style\" . \"visible\") + (\"colored-completion-prefix\" . #t)) +@end lisp + +turns into + +@example +set bell-style visible +set colored-completion-prefix on +@end example + +@item @code{conditional-constructs} (default: @code{'()}) (type: alist) +Association list of conditionals to add to the initialization file. This +includes @command{$if}, @command{else}, @command{endif} and @command{include} +and they receive a value of another @command{home-inputrc-configuration}. + +@lisp +(conditional-constructs + `((\"$if mode=vi\" . + ,(home-inputrc-configuration + (variables + `((\"show-mode-in-prompt\" . #t))))) + (\"$else\" . + ,(home-inputrc-configuration + (key-bindings + `((\"Control-l\" . \"clear-screen\"))))) + (\"$endif\" . #t))) +@end lisp + +turns into + +@example +$if mode=vi +set show-mode-in-prompt on +$else +Control-l: clear-screen +$endif +@end example + +@item @code{extra-content} (default: @code{""}) (type: text-config) +Extra content appended as-is to the configuration file. Run @command{man +readline} for more information about all the configuration options. + +@end table +@end deftp + @node Mcron Home Service @subsection Scheduled User's Job Execution @@ -43076,6 +43400,20 @@ Concretely, these files are concatenated and made available as running on this machine, then it @emph{may} take this file into account: this is what @command{sshd} does by default, but be aware that it can also be configured to ignore it. + +@item @code{add-keys-to-agent} (default: @code{``no''}) +This string specifies whether keys should be automatically added to a +running ssh-agent. If this option is set to @code{``yes''} and a key is +loaded from a file, the key and its passphrase are added to the agent +with the default lifetime, as if by @code{ssh-add}. If this option is +set to @code{``ask''}, @code{ssh} will require confirmation. If this +option is set to @code{``confirm''}, each use of the key must be +confirmed. If this option is set to @code{``no''}, no keys are added to +the agent. Alternately, this option may be specified as a time interval +to specify the key's lifetime in @code{ssh-agent}, after which it will +automatically be removed. The argument must be @code{``no''}, +@code{``yes''}, @code{``confirm''} (optionally followed by a time +interval), @code{``ask''} or a time interval. @end table @end deftp @@ -43086,11 +43424,21 @@ Available @code{openssh-host} fields are: @table @asis @item @code{name} (type: string) -Name of this host declaration. +Name of this host declaration. A @code{openssh-host} must define only +@code{name} or @code{match-criteria}. Use host-name @code{\"*\"} for +top-level options. @item @code{host-name} (type: maybe-string) Host name---e.g., @code{"foo.example.org"} or @code{"192.168.1.2"}. +@item @code{match-criteria} (type: maybe-match-criteria) +When specified, this string denotes the set of hosts to which the entry +applies, superseding the @code{host-name} field. Its first element must be +all or one of @code{ssh-match-keywords}. The rest of the elements are +arguments for the keyword, or other criteria. A @code{openssh-host} must +define only @code{name} or @code{match-criteria}. Other host configuration +options will apply to all hosts matching @code{match-criteria}. + @item @code{address-family} (type: maybe-address-family) Address family to use when connecting to this host: one of @code{AF_INET} (for IPv4 only), @code{AF_INET6} (for IPv6 only). @@ -43105,19 +43453,19 @@ TCP port number to connect to. @item @code{user} (type: maybe-string) User name on the remote host. -@item @code{forward-x11?} (default: @code{#f}) (type: boolean) +@item @code{forward-x11?} (type: maybe-boolean) Whether to forward remote client connections to the local X11 graphical display. -@item @code{forward-x11-trusted?} (default: @code{#f}) (type: boolean) +@item @code{forward-x11-trusted?} (type: maybe-boolean) Whether remote X11 clients have full access to the original X11 graphical display. -@item @code{forward-agent?} (default: @code{#f}) (type: boolean) +@item @code{forward-agent?} (type: maybe-boolean) Whether the authentication agent (if any) is forwarded to the remote machine. -@item @code{compression?} (default: @code{#f}) (type: boolean) +@item @code{compression?} (type: maybe-boolean) Whether to compress data in transit. @item @code{proxy} (type: maybe-proxy-command-or-jump-list) |