diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contributing.texi | 63 | ||||
| -rw-r--r-- | doc/guix-cookbook.texi | 53 | ||||
| -rw-r--r-- | doc/guix.texi | 375 |
3 files changed, 433 insertions, 58 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index e1902f120f..02c7c5ae59 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -29,6 +29,7 @@ choice. * Tracking Bugs and Patches:: 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. * Translating Guix:: Make Guix speak your native language. @end menu @@ -224,8 +225,7 @@ $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' @noindent @cindex REPL @cindex read-eval-print loop -@dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile -Reference Manual}): +@dots{} and for a REPL (@pxref{Using Guix Interactively}): @example $ ./pre-inst-env guile @@ -278,8 +278,8 @@ prepared Guile object (@file{.go}) files. You can run @command{make} automatically as you work using @command{watchexec} from the @code{watchexec} package. For example, -to build again each time you update a package file, you can run -@samp{watchexec -w gnu/packages make -j4}. +to build again each time you update a package file, run +@samp{watchexec -w gnu/packages -- make -j4}. @node The Perfect Setup @section The Perfect Setup @@ -291,7 +291,7 @@ Manual}). First, you need more than an editor, you need wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run: @example -guix package -i emacs guile emacs-geiser emacs-geiser-guile +guix install emacs guile emacs-geiser emacs-geiser-guile @end example Geiser allows for interactive and incremental development from within @@ -664,7 +664,7 @@ hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful when using some characters for example @samp{@@} and curly braces which are the basic special characters in Texinfo (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces -such as @command{guix package --show} take care of rendering it +such as @command{guix show} take care of rendering it appropriately. Synopses and descriptions are translated by volunteers @@ -1118,11 +1118,11 @@ Development is done using the Git distributed version control system. Thus, access to the repository is not strictly necessary. We welcome contributions in the form of patches as produced by @code{git format-patch} sent to the @email{guix-patches@@gnu.org} mailing list -(@pxref{submitting patches,, Submitting patches to a project, git, Git -User Manual}). Contributors are encouraged to take a moment to set some -Git repository options (@pxref{Configuring Git}) first, which can -improve the readability of patches. Seasoned Guix developers may also -want to look at the section on commit access (@pxref{Commit Access}). +(@pxref{Submitting patches to a project,,, git, Git User Manual}). +Contributors are encouraged to take a moment to set some Git repository +options (@pxref{Configuring Git}) first, which can improve the +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 @@ -1779,6 +1779,47 @@ 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. +@cindex documentation +@node Writing Documentation +@section Writing Documentation + +Guix is documented using the Texinfo system. If you are not yet +familiar with it, we accept contributions for documentation in most +formats. That includes plain text, Markdown, Org, etc. + +Documentation contributions can be sent to +@email{guix-patches@@gnu.org}. Prepend @samp{[DOCUMENTATION]} to the +subject. + +When you need to make more than a simple addition to the documentation, +we prefer that you send a proper patch as opposed to sending an email +as described above. @xref{Submitting Patches} for more information on +how to send your patches. + +To modify the documentation, you need to edit @file{doc/guix.texi} and +@file{doc/contributing.texi} (which contains this documentation +section), or @file{doc/guix-cookbook.texi} for the cookbook. If +you compiled the Guix repository before, you will have +many more @file{.texi} files that are translations of these +documents. Do not modify them, the translation is managed through +@uref{https://translate.fedoraproject.org/projects/guix, Weblate}. +@xref{Translating Guix} for more information. + +To render documentation, you must first make sure that you ran +@command{./configure} in your source tree (@pxref{Running Guix Before +It Is Installed}). After that you can run one of the following +commands: + +@itemize +@item @samp{make doc/guix.info} to compile the Info manual. + You can check it with @command{info doc/guix.info}. +@item @samp{make doc/guix.html} to compile the HTML version. + You can point your browser to the relevant file in the + @file{doc/guix.html} directory. +@item @samp{make doc/guix-cookbook.info} for the cookbook Info manual. +@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version. +@end itemize + @cindex translation @cindex l10n @cindex i18n diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 06fb872177..b61adc06da 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -122,7 +122,7 @@ language, install it with @code{guix install guile} and start a @dfn{REPL}---short for @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop, @dfn{read-eval-print loop}}---by running @code{guile} from the command line. -Alternatively you can also run @code{guix environment --ad-hoc guile -- guile} +Alternatively you can also run @code{guix shell guile -- guile} if you'd rather not have Guile installed in your user profile. In the following examples, lines show what you would type at the REPL; @@ -284,24 +284,41 @@ depends on the @code{(guix store)} module and it exports two variables, @code{ruby-build} and @code{ruby-build-system}. @end itemize -For a more detailed introduction, check out -@uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, Scheme -at a Glance}, by Steve Litt. - -One of the reference Scheme books is the seminal ``Structure and -Interpretation of Computer Programs'', by Harold Abelson and Gerald Jay -Sussman, with Julie Sussman. You'll find a -@uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, free copy -online}, together with -@uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/, -videos of the lectures by the authors}. The book is available in Texinfo -format as the @code{sicp} Guix package. Go ahead, run @code{guix install -sicp} and start reading with @code{info sicp} (@pxref{Top,,, sicp, Structure and Interpretation of Computer Programs}). -An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also -available}. +@quotation Going further +Scheme is a language that has been widely used to teach programming and +you'll find plenty of material using it as a vehicle. Here's a +selection of documents to learn more about Scheme: + +@itemize +@item +@uref{https://spritely.institute/static/papers/scheme-primer.html, @i{A +Scheme Primer}}, by Christine Lemmer-Webber and the Spritely Institute. + +@item +@uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, +@i{Scheme at a Glance}}, by Steve Litt. + +@item +@uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, +@i{Structure and Interpretation of Computer Programs}}, by Harold +Abelson and Gerald Jay Sussman, with Julie Sussman. Colloquially known +as ``SICP'', this book is a reference. + +You can also install it and read it from your computer: + +@example +guix install sicp info-reader +info sicp +@end example + +An @uref{https://sarabander.github.io/sicp/, unofficial ebook} is also +available. + +@end itemize You'll find more books, tutorials and other resources at @url{https://schemers.org/}. +@end quotation @c ********************************************************************* @@ -1600,7 +1617,7 @@ letting you know what you're missing. If the file is blank then you're missing everything. The next step is to run: @example shell -guix environment linux-libre -- make localmodconfig +guix shell -D linux-libre -- make localmodconfig @end example and note the output. Do note that the @file{.config} file is still empty. @@ -2787,7 +2804,7 @@ Maybe a dependency from our manifest has been updated; or we may have run garbage-collected. @item -Eventually, we set to work on that project again, so we run @code{guix environment +Eventually, we set to work on that project again, so we run @code{guix shell -m manifest.scm}. But now we have to wait for Guix to build and install stuff! @end enumerate diff --git a/doc/guix.texi b/doc/guix.texi index 8affc235e1..6a4773189e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -30,7 +30,7 @@ Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@* -Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ricardo Wurmus@* +Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 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@* @@ -105,6 +105,7 @@ Copyright @copyright{} 2022 Aleksandr Vityazev@* Copyright @copyright{} 2022 Philip M@sup{c}Grath@* Copyright @copyright{} 2022 Karl Hallsby@* Copyright @copyright{} 2022 Justin Veilleux@* +Copyright @copyright{} 2022 Reily Siegel@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -298,6 +299,7 @@ Programming Interface * The Store Monad:: Purely functional interface to the store. * G-Expressions:: Manipulating build expressions. * Invoking guix repl:: Programming Guix in Guile. +* Using Guix Interactively:: Fine-grain interaction at the REPL. Defining Packages @@ -7099,6 +7101,7 @@ package definitions. * The Store Monad:: Purely functional interface to the store. * G-Expressions:: Manipulating build expressions. * Invoking guix repl:: Programming Guix in Guile +* Using Guix Interactively:: Fine-grain interaction at the REPL. @end menu @node Package Modules @@ -8524,14 +8527,8 @@ the number specified as the @option{--cores} option of This Boolean, @code{#t} by default, determines whether to ``validate'' the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well as executables) previously installed by the @code{install} phase. - -This validation step consists in making sure that all the shared -libraries needed by an ELF binary, which are listed as -@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the -@code{DT_RUNPATH} entry of that binary. In other words, it ensures that -running or using those binaries will not result in a ``file not found'' -error at run time. @xref{Options, @option{-rpath},, ld, The GNU -Linker}, for more information on @code{RUNPATH}. +@xref{phase-validate-runpath, the @code{validate-runpath} phase}, for +details. @item #:substitutable? This Boolean, @code{#t} by default, tells whether the package outputs @@ -9619,6 +9616,21 @@ Patch shebangs on the installed executable files. Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} is false), copying them to the @code{debug} output when available (@pxref{Installing Debugging Files}). + +@cindex RUNPATH, validation +@anchor{phase-validate-runpath} +@item validate-runpath +Validate the @code{RUNPATH} of ELF binaries, unless +@code{#:validate-runpath?} is false (@pxref{Build Systems}). + +This validation step consists in making sure that all the shared +libraries needed by an ELF binary, which are listed as @code{DT_NEEDED} +entries in its @code{PT_DYNAMIC} segment, appear in the +@code{DT_RUNPATH} entry of that binary. In other words, it ensures that +running or using those binaries will not result in a ``file not found'' +error at run time. @xref{Options, @option{-rpath},, ld, The GNU +Linker}, for more information on @code{RUNPATH}. + @end table Other build systems have similar phases, with some variations. For @@ -10859,8 +10871,9 @@ So, to exit the monad and get the desired effect, one must use @end lisp Note that the @code{(guix monad-repl)} module extends the Guile REPL with -new ``meta-commands'' to make it easier to deal with monadic procedures: -@code{run-in-store}, and @code{enter-store-monad}. The former is used +new ``commands'' to make it easier to deal with monadic procedures: +@code{run-in-store}, and @code{enter-store-monad} (@pxref{Using Guix +Interactively}). The former is used to ``run'' a single monadic value through the store: @example @@ -10885,6 +10898,9 @@ scheme@@(guile-user)> Note that non-monadic values cannot be returned in the @code{store-monad} REPL. +Other meta-commands are available at the REPL, such as @code{,build} to +build a file-like object (@pxref{Using Guix Interactively}). + The main syntactic forms to deal with monads in general are provided by the @code{(guix monads)} module and are described below. @@ -11777,7 +11793,8 @@ lines at the top of the script: @code{!#} @end example -Without a file name argument, a Guile REPL is started: +Without a file name argument, a Guile REPL is started, allowing for +interactive use (@pxref{Using Guix Interactively}): @example $ guix repl @@ -11833,6 +11850,132 @@ Inhibit loading of the @file{~/.guile} file. By default, that configuration file is loaded when spawning a @code{guile} REPL. @end table +@node Using Guix Interactively +@section Using Guix Interactively + +@cindex interactive use +@cindex REPL, read-eval-print loop +The @command{guix repl} command gives you access to a warm and friendly +@dfn{read-eval-print loop} (REPL) (@pxref{Invoking guix repl}). If +you're getting into Guix programming---defining your own packages, +writing manifests, defining services for Guix System or Guix Home, +etc.---you will surely find it convenient to toy with ideas at the REPL. + +If you use Emacs, the most convenient way to do that is with Geiser +(@pxref{The Perfect Setup}), but you do not have to use Emacs to enjoy +the REPL@. When using @command{guix repl} or @command{guile} in the +terminal, we recommend using Readline for completion and Colorized to +get colorful output. To do that, you can run: + +@example +guix install guile guile-readline guile-colorized +@end example + +@noindent +... and then create a @file{.guile} file in your home directory containing +this: + +@lisp +(use-modules (ice-9 readline) (ice-9 colorized)) + +(activate-readline) +(activate-colorized) +@end lisp + +The REPL lets you evaluate Scheme code; you type a Scheme expression at +the prompt, and the REPL prints what it evaluates to: + +@example +$ guix repl +scheme@@(guix-user)> (+ 2 3) +$1 = 5 +scheme@@(guix-user)> (string-append "a" "b") +$2 = "ab" +@end example + +It becomes interesting when you start fiddling with Guix at the REPL. +The first thing you'll want to do is to ``import'' the @code{(guix)} +module, which gives access to the main part of the programming +interface, and perhaps a bunch of useful Guix modules. You could type +@code{(use-modules (guix))}, which is valid Scheme code to import a +module (@pxref{Using Guile Modules,,, guile, GNU Guile Reference +Manual}), but the REPL provides the @code{use} @dfn{command} as a +shorthand notation (@pxref{REPL Commands,,, guile, GNU Guile Reference +Manual}): + +@example +scheme@@(guix-user)> ,use (guix) +scheme@@(guix-user)> ,use (gnu packages base) +@end example + +Notice that REPL commands are introduced by a leading comma. A REPL +command like @code{use} is not valid Scheme code; it's interpreted +specially by the REPL. + +Guix extends the Guile REPL with additional commands for convenience. +Among those, the @code{build} command comes in handy: it ensures that +the given file-like object is built, building it if needed, and returns +its output file name(s). In the example below, we build the +@code{coreutils} and @code{grep} packages, as well as a ``computed +file'' (@pxref{G-Expressions, @code{computed-file}}), and we use the +@code{scandir} procedure to list the files in Grep's @code{/bin} +directory: + +@example +scheme@@(guix-user)> ,build coreutils +$1 = "/gnu/store/@dots{}-coreutils-8.32-debug" +$2 = "/gnu/store/@dots{}-coreutils-8.32" +scheme@@(guix-user)> ,build grep +$3 = "/gnu/store/@dots{}-grep-3.6" +scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output)) +building /gnu/store/@dots{}-x.drv... +$4 = "/gnu/store/@dots{}-x" +scheme@@(guix-user)> ,use(ice-9 ftw) +scheme@@(guix-user)> (scandir (string-append $3 "/bin")) +$5 = ("." ".." "egrep" "fgrep" "grep") +@end example + +At a lower-level, a useful command is @code{lower}: it takes a file-like +object and ``lowers'' it into a derivation (@pxref{Derivations}) or a +store file: + +@example +scheme@@(guix-user)> ,lower grep +$6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0> +scheme@@(guix-user)> ,lower (plain-file "x" "Hello!") +$7 = "/gnu/store/@dots{}-x" +@end example + +The full list of REPL commands can be seen by typing @code{,help guix} +and is given below for reference. + +@deffn {REPL command} build @var{object} +Lower @var{object} and build it if it's not already built, returning its +output file name(s). +@end deffn + +@deffn {REPL command} lower @var{object} +Lower @var{object} into a derivation or store file name and return it. +@end deffn + +@deffn {REPL command} verbosity @var{level} +Change build verbosity to @var{level}. + +This is similar to the @option{--verbosity} command-line option +(@pxref{Common Build Options}): level 0 means total silence, level 1 +shows build events only, and higher levels print build logs. +@end deffn + +@deffn {REPL command} run-in-store @var{exp} +Run @var{exp}, a monadic expresssion, through the store monad. +@xref{The Store Monad}, for more information. +@end deffn + +@deffn {REPL command} enter-store-monad +Enter a new REPL to evaluate monadic expressions (@pxref{The Store +Monad}). You can quit this ``inner'' REPL by typing @code{,q}. +@end deffn + @c ********************************************************************* @node Utilities @chapter Utilities @@ -14002,6 +14145,10 @@ The @option{--input-simplification} option described below provides fine-grain control over when inputs should be simplified. @end table +@item --list-stylings +@itemx -l +List and describe the available styling rules and exit. + @item --load-path=@var{directory} @itemx -L @var{directory} Add @var{directory} to the front of the package module search path @@ -14950,7 +15097,9 @@ any given store item. The command output looks like this: @smallexample -$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org" +$ guix challenge \ + --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org" \ + openssl git pius coreutils grep updating substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0% updating substitutes from 'https://guix.example.org'... 100.0% /gnu/store/@dots{}-openssl-1.0.2d contents differ: @@ -14977,18 +15126,20 @@ updating substitutes from 'https://guix.example.org'... 100.0% @dots{} -6,406 store items were analyzed: - - 4,749 (74.1%) were identical - - 525 (8.2%) differed - - 1,132 (17.7%) were inconclusive +5 store items were analyzed: + - 2 (40.0%) were identical + - 3 (60.0%) differed + - 0 (0.0%) were inconclusive @end smallexample @noindent -In this example, @command{guix challenge} first scans the store to -determine the set of locally-built derivations---as opposed to store -items that were downloaded from a substitute server---and then queries -all the substitute servers. It then reports those store items for which -the servers obtained a result different from the local build. +In this example, @command{guix challenge} queries all the substitute +servers for each of the fives packages specified on the command line. +It then reports those store items for which the servers obtained a +result different from the local build (if it exists) and/or different +from one another; here, the @samp{local hash} lines indicate that a +local build result was available for each of these packages and shows +its hash. @cindex non-determinism, in package builds As an example, @code{guix.example.org} always gets a different answer. @@ -15044,19 +15195,21 @@ whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain t same build result as you did with: @example -$ guix challenge @var{package} +guix challenge @var{package} @end example -@noindent -where @var{package} is a package specification such as -@code{guile@@2.0} or @code{glibc:debug}. - The general syntax is: @example -guix challenge @var{options} [@var{packages}@dots{}] +guix challenge @var{options} @var{argument}@dots{} @end example +@noindent +where @var{argument} is a package specification such as +@code{guile@@2.0} or @code{glibc:debug} or, alternatively, a store file +name as returned, for example, by @command{guix build} or @command{guix +gc --list-live}. + When a difference is found between the hash of a locally-built item and that of a server-provided substitute, or among substitutes provided by different servers, the command displays it as in the example above and @@ -18709,6 +18862,75 @@ String or gexp denoting the corresponding mcron job schedule @end table @end deftp +@cindex logging, anonymization +@subheading Anonip Service + +Anonip is a privacy filter that removes IP address from web server logs. +This service creates a FIFO and filters any written lines with anonip +before writing the filtered log to a target file. + +The following example sets up the FIFO +@file{/var/run/anonip/https.access.log} and writes the filtered log file +@file{/var/log/anonip/https.access.log}. + +@lisp +(service anonip-service-type + (anonip-configuration + (input "/var/run/anonip/https.access.log") + (output "/var/log/anonip/https.access.log"))) +@end lisp + +Configure your web server to write its logs to the FIFO at +@file{/var/run/anonip/https.access.log} and collect the anonymized log +file at @file{/var/web-logs/https.access.log}. + +@deftp {Data Type} anonip-configuration +This data type represents the configuration of anonip. +It has the following parameters: + +@table @asis +@item @code{anonip} (default: @code{anonip}) +The anonip package to use. + +@item @code{input} +The file name of the input log file to process. The service creates a +FIFO of this name. The web server should write its logs to this FIFO. + +@item @code{output} +The file name of the processed log file. +@end table + +The following optional settings may be provided: + +@table @asis +@item @code{skip-private?} +When @code{#true} do not mask addresses in private ranges. + +@item @code{column} +A 1-based indexed column number. Assume IP address is in the specified +column (default is 1). + +@item @code{replacement} +Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}. + +@item @code{ipv4mask} +Number of bits to mask in IPv4 addresses. + +@item @code{ipv6mask} +Number of bits to mask in IPv6 addresses. + +@item @code{increment} +Increment the IP address by the given number. By default this is zero. + +@item @code{delimiter} +Log delimiter string. + +@item @code{regex} +Regular expression for detecting IP addresses. Use this instead of @code{column}. +@end table +@end deftp + + @node Networking Setup @subsection Networking Setup @@ -28507,6 +28729,9 @@ prefix @samp{unix:}. For addresses using an IP address or domain name, 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. + @end table @end deftp @@ -35082,6 +35307,11 @@ allocation plan in the database. An association list of hooks. These provide a way to execute arbitrary code upon certain events, like a build result being processed. +@item @code{parallel-hooks} (default: @var{'()}) +Hooks can be configured to run in parallel. This parameter is an +association list of hooks to do in parallel, where the key is the symbol +for the hook and the value is the number of threads to run. + @item @code{guile} (default: @code{guile-3.0-latest}) The Guile package with which to run the Guix Build Coordinator. @@ -37527,6 +37757,13 @@ bootloader boot menu: Describe the running system generation: its file name, the kernel and bootloader used, etc., as well as provenance information when available. +The @code{--list-installed} flag is available, with the same +syntax that is used in @command{guix package --list-installed} +(@pxref{Invoking guix package}). When the flag is used, +the description will include a list of packages that are currently +installed in the system profile, with optional filtering based on a +regular expression. + @quotation Note The @emph{running} system generation---referred to by @file{/run/current-system}---is not necessarily the @emph{current} @@ -37554,6 +37791,11 @@ generations that are up to 10 days old: $ guix system list-generations 10d @end example +The @code{--list-installed} flag may also be specified, with the same +syntax that is used in @command{guix package --list-installed}. This +may be helpful if trying to determine when a package was added to the +system. + @end table The @command{guix system} command has even more to offer! The following @@ -39313,6 +39555,7 @@ services)}. * Shepherd: Shepherd Home Service. Managing User's Daemons. * SSH: Secure Shell. Setting up the secure shell client. * Desktop: Desktop Home Services. Services for graphical environments. +* Guix: Guix Home Services. Services for Guix. @end menu @c In addition to that Home Services can provide @@ -39541,6 +39784,23 @@ contents of the extensions will be added to the end of the corresponding Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}. +For example, here is how you would define a service that extends the +Bash service such that @file{~/.bash_profile} defines an additional +environment variable, @env{PS1}: + +@lisp +(define bash-fancy-prompt-service + (simple-service 'bash-fancy-prompt + home-bash-service-type + (home-bash-extension + (environment-variables + '(("PS1" . "\\u \\wλ ")))))) +@end lisp + +You would then add @code{bash-fancy-prompt-service} to the list in the +@code{services} field of your @code{home-environment}. The reference of +@code{home-bash-extension} follows. + @deftp {Data Type} home-bash-extension Available @code{home-bash-extension} fields are: @@ -39953,6 +40213,37 @@ format. @end deftp +@node Guix Home Services +@subsection Guix Home Services + +The @code{(gnu home services guix)} module provides services for +user-specific Guix configuration. + +@defvr {Scheme Variable} home-channels-service-type +This is the service type for managing +@file{$XDG_CONFIG_HOME/guix/channels.scm}, the file that controls the +channels received on @command{guix pull} (@pxref{Channels}). Its +associated value is a list of @code{channel} records, defined in the +@code{(guix channels)} module. + +Generally, it is better to extend this service than to directly +configure it, as its default value is the default guix channel(s) +defined by @code{%default-channels}. If you configure this service +directly, be sure to include a guix channel. @xref{Specifying +Additional Channels} and @ref{Using a Custom Guix Channel} for more +details. + +A typical extension for adding a channel might look like this: + +@lisp +(simple-service 'variant-packages-service + home-channels-service-type + (list + (channel + (name 'variant-packages) + (url "https://example.org/variant-packages.git"))) +@end lisp +@end defvr @node Invoking guix home @section Invoking @code{guix home} @@ -40192,6 +40483,17 @@ install anything. Describe the current home generation: its file name, as well as provenance information when available. +To show installed packages in the current home generation's profile, the +@code{--list-installed} flag is provided, with the same syntax that is +used in @command{guix package --list-installed} (@pxref{Invoking guix +package}). For instance, the following command shows a table of all the +packages with ``emacs'' in their name that are installed in the current +home generation's profile: + +@example +guix home describe --list-installed=emacs +@end example + @item list-generations List a summary of each generation of the home environment available on disk, in a human-readable way. This is similar to the @@ -40204,9 +40506,14 @@ generations displayed. For instance, the following command displays generations that are up to 10 days old: @example -$ guix home list-generations 10d +guix home list-generations 10d @end example +The @code{--list-installed} flag may also be specified, with the same +syntax that is used in @command{guix home describe}. This may be +helpful if trying to determine when a package was added to the home +profile. + @item import Generate a @dfn{home environment} from the packages in the default profile and configuration files found in the user's home directory. The @@ -40634,6 +40941,16 @@ package, you can try and import it (@pxref{Invoking guix import}): guix import texlive @var{package} @end example +Additional options include: + +@table @code +@item --recursive +@itemx -r +Traverse the dependency graph of the given upstream package recursively +and generate package expressions for all those packages that are not yet +in Guix. +@end table + @quotation Note @TeX{} Live packaging is still very much work in progress, but you can help! @xref{Contributing}, for more information. |