diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 440 |
1 files changed, 394 insertions, 46 deletions
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) |