Message ID | 878s0gzn54.fsf@trop.in |
---|---|
State | Accepted |
Headers | show |
Series | [bug#50313] doc: Add Guix Home documentation. | expand |
Context | Check | Description |
---|---|---|
cbaines/applying patch | fail | View Laminar job |
cbaines/issue | success | View issue |
Hi Andrew, doc/he-config-bare-bones.texi is missing.
On Wed, Sep 01 2021, Andrew Tropin wrote: > * doc/guix.texi: Add Guix Home documentation. > * doc/he-config-bare-bones.texi: Add home-environment example configuration. > --- > Reread and updated documentation for Guix Home to reflect latest changes, > still a subject for review and proofreading. Combined all changes into one > commit. Sections about Mcron and Shepherd (which are not in wip-guix-home > yet) contains only placeholders, will be updated with patches for related home > services. There is no section about Gradual Migration to Guix Home and > Invoking guix home's subsection about 'guix home import' subcommand yet, they > are planned, but probably will come later. Going to read this once again and leave some thoughts and comments while reading. (Edit: expect a long reply!) :-) > doc/guix.texi | 687 ++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 687 insertions(+) > > diff --git a/doc/guix.texi b/doc/guix.texi > index 2b8448c856..8a50678a80 100644 > --- a/doc/guix.texi > +++ b/doc/guix.texi > @@ -96,6 +96,7 @@ Copyright @copyright{} 2021 Domagoj Stolfa@* > Copyright @copyright{} 2021 Hui Lu@* > Copyright @copyright{} 2021 pukkamustard@* > Copyright @copyright{} 2021 Alice Brenon@* > +Copyright @copyright{} 2021 Andrew Tropin@* > > Permission is granted to copy, distribute and/or modify this document > under the terms of the GNU Free Documentation License, Version 1.3 or > @@ -167,6 +168,7 @@ Weblate} (@pxref{Translating Guix}). > * Programming Interface:: Using Guix in Scheme. > * Utilities:: Package management commands. > * System Configuration:: Configuring the operating system. > +* Home Configuration:: Configuring the home environment. > * Documentation:: Browsing software user manuals. > * Installing Debugging Files:: Feeding the debugger. > * Security Updates:: Deploying security fixes quickly. > @@ -328,6 +330,10 @@ System Configuration > * Running Guix in a VM:: How to run Guix System in a virtual machine. > * Defining Services:: Adding new service definitions. > > +Home Environment Configuration > + > +* Invoking guix home:: Instantiating a home environment configuration. > + > Services > > * Base Services:: Essential system services. > @@ -35090,6 +35096,687 @@ system: > This service represents PID@tie{}1. > @end defvr > > +@node Home Configuration > +@chapter Home Configuration > +@cindex home configuration > +Guix supports declarative configuration of @dfn{home environment} by @dfn{home environments} (plural form) > +utilizing the configuration mechanism described in the previous chapter > +(@pxref{Defining Services}), but for user's home. It works both on Guix ^ Double spacing. “users's home” sounds kind of vague; maybe “user's dotfiles and packages”. > +System and foreign distros and allows users to declare all the packages Maybe “packages and services” instead of just “packages”? > +that should be installed and configured for the user. After that, such It’s not super clear what “After that” is referring to. Maybe Once a user has written a file containing a home environment ? > +a @dfn{home configuration} can be @dfn{instantiated} by an unprivileged What is the difference between “home environment” and “home configuration”? > +user with the @command{guix home} command (@pxref{Invoking guix home}). > +@c Maybe later, it will be possible to make home configuration a part of > +@c system configuration to make everything managed by guix system. > + > +User's home environment usually consists of three basic parts: software, “The users's home environment” > +configuration and state. Software in mainstream distros are usually ^ Missing comma. > +installed system-wide, but with GNU Guix most software packages can be > +installed on a per-user basis without needing root privileges, and are > +thus considered part of the user’s @dfn{home environment}. Packages on > +their own not very useful in many cases, because often they require some > +additional configuration, usually config files that reside in > +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) or other Maybe just “(@file{~/.config} by default)” instead of “(default value is @file{~/.config})”? > +directories. Everything else can be considered state, like media files, > +application databases, and logs. > + > +Using Guix for managing home environments provides a number of > +advantages: > + > +@itemize > + > +@item All software can be configured in one language (Guile Scheme), > +this gives users to ability to share values between configurations of ^^ s/to/the > +different programs and other benifits. “and other benifits” doesn’t really fit here; I suggest we remove it. > +@item A well-defined home environment is self-contained and can be > +created in a declarative and reproducible way. There is no need to grab > +external binaries or manually edit some configuration file. I would personally use “---” instead of putting a period and starting a new sentence. @item A well-defined home environment is self-contained and can be created in a declarative and reproducible way---there is no need to grab external binaries or manually edit some configuration file. > +@item After every @command{guix home reconfigure} invocation, a new home > +environment generation will be created. This means that users can > +rollback to a previous home environment generation so they don’t have to > +worry about breaking their configuration. > + > +@item It is possible to manage stateful data with Guix Home, this > +includes the ability to automatically clone Git repositories on the > +initial setup of the machine, and periodically running commands like > +@command{rsync} to sync data with another host. This functionality is > +still in an experimental stage, though. > + > +@end itemize > + > +@menu > +* Declaring the Home Environment:: Customizing your Home. > +* Configuring the Shell:: Enabling home environment. > +* Home Services:: Specifying home services. > +* Invoking guix home:: Instantiating a home configuration. > +@end menu > + > +@node Declaring the Home Environment > +@section Declaring the Home Environment > +The home environment is configured by providing @code{home-environment} ^ Missing “a” > +declaration in a file that can be passed to the @command{guix home} > +command (@pxref{Invoking guix home}). A simple setup can include Bash > +and custom text configuration, like in the example below. Don't be ^ Missing “a” :-) > +afraid to declare home environment parts, which overlaps with your > +current dotfiles, before installing any configuration files Guix Home ^ Missing comma. > +will back up existing config files to a separate place in the home > +folder. > + > +@quotation Note > +It is highly recommended that you manage your shell or shells with Guix > +Home, because it will make sure that all the necessary scripts are > +sourced by shell configuration file. Otherwise you will need to do it ^ Missing “the” > +manually. (@pxref{Configuring the Shell}). > +@end quotation > + > +@findex home-environment > +@lisp > +@include he-config-bare-bones.texi > +@end lisp > + > +The @code{packages} field should be self-explanatory, it will install > +the list of packages into the user's profile. The most important field > +is @code{services}, it contains a list of @dfn{home services}, which are > +the basic building blocks of a home environment. > + > +There is no daemon (at least not necessary) related to home service, s/necessary/necessarily (adverb form) s/service/services (plural form) > +it's just an element that is used to declare part of home environment > +and extend other parts of it. I don’t quite understand this part. > The extension mechanism discussed in the > +previous chapter (@pxref{Defining Services}) should not be confused with > +@ref{Shepherd Services}. Using this extension mechanism and some Scheme > +code that glues things together gives a lot of freedom in declaring of > +very custom home environments. I would rephrase the last sentence Using this extension mechanism and some Scheme code that glues things together giver the user the freedom to declare their own, very custom, home environment. > +@node Configuring the Shell > +@section Configuring the Shell > +This section is safe to skip if your shell or shells are managed by > +Guix Home. Otherwise, read it carefully. > + > +There are a few scripts that must be evaluated by a login shell to > +activate the home environment. The shell startup files only read by > +login shells often have @code{profile} suffix. For more information > +about login shells see @ref{Invoking Bash,,, bash, The GNU Bash > +Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash > +Reference Manual}. > + > +The first script is @file{setup-environment}, which sets all the “The first script that needs to be sourced is @file{setup-environment}” > +necessary environment variables (including variables declared by user) ^ Missing “the” > +and the second one is @file{on-first-login}, which starts Shepherd for > +the current user and performs actions declared by other home services > +extending @code{home-run-on-first-login-service-type}. s/extending/that extends/ > +Guix Home will always create @file{~/.profile}, which contains the > +following lines: > + > +@example > +HOME_ENVIRONMENT=$HOME/.guix-home > +. $HOME_ENVIRONMENT/setup-environment > +$HOME_ENVIRONMENT/on-first-login > +@end example > + > +That makes POSIX compliant login shells activate the home environment. s/That/This/ > +However, in most cases this file won't be read by most modern shells, > +because they are run in non POSIX mode by default and have their own > +@file{*profile} startup files. For example Bash will prefer > +@file{~/.bash_profile} in case it exists and only if it doesn't will it > +fallback to @file{~/.profile}. Zsh (if no additional options specified) ^ Missing “are” > +will ignore @file{~/.profile}, even if @file{~/.zprofile} doesn't exist. > + > +To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or > +@code{source ~/profile} to the startup file for the login shell. In > +case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is > +@file{~/.zprofile}. > + > +@quotation Note > +This step is only required if your shell is NOT managed by Guix Home. > +Otherwise, everything will be done automatically. > +@end quotation > + > +@node Home Services > +@section Home Services > +@cindex home services > + > +A @dfn{home service} is not necessarily something that has a daemon and > +is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd > +Manual}), in most cases it doesn't. It's a simple building block of > +home environment, often declaring a set of packages to be installed in ^ Missing “the” > +the home environment profile, a set of config files to be symlinked into > +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and ^ “(@file{~/.config} by default)” Missing comma. > +environment variables to be set by a login shell. > + > +There is a service extension mechanism (@pxref{Service Composition}), > +which allows home services to extend other home services and utilize > +capabilities they provide, for example: declare mcron jobs > +(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home > +Service}, declare daemons by extending @ref{Shepherd Home Service}, add > +commands, which will be invoked on by the Bash by extending > +@ref{Shells Home Services, @code{home-bash-service-type}}. I would use semicolons instead of commas for separating the clauses. There is a service extension mechanism (@pxref{Service Composition}) which allows home services to extend other home services and utilize capabilities they provide; for example: declare mcron jobs (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home Service}; declare daemons by extending @ref{Shepherd Home Service}; add commands, which will be invoked on by the Bash by extending @ref{Shells Home Services, @code{home-bash-service-type}}. > +The good way to discover avaliable home services is using the I would “A” instead of “The”, which sounds a bit authoritative. > +@command{guix home search} command (@pxref{Invoking guix home}). After > +the required home services are found, include its module with the > +@code{use-modules} form (@pxref{use-modules,, Using Guile Modules, > +guile, The GNU Guile Reference Manual}), or the @code{#:use-modules} > +directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU > +Guile Reference Manual}) and declare a home service using the > +@code{service} function, or extend a service type by declaring a new > +service with the @code{simple-service} procedure from @code{(gnu > +services)}. > + > +@menu > +* Essential Home Services:: Environment variables, packages, on-* scripts. > +* Shells: Shells Home Services. POSIX shells, Bash, Zsh. > +* Mcron: Mcron Home Service. Scheduled User's Job Execution. > +* Shepherd: Shepherd Home Service. Managing User's Daemons. > +@end menu > +@c In addition to that Home Services can provide > + > +@node Essential Home Services > +@subsection Essential Home Services > +There are a few essential services defined in @code{(gnu > +home-services)}, they are mostly for internal use and are required to > +build a home environment, but some of them will be useful for the end > +user. > + > +@cindex environment variables > + > +@defvr {Scheme Variable} home-environment-variables-service-type > +The service of this type will be instantiated by every home environment > +automatically by default, there is no need to define it, but someone may > +want to extend it with a list of pairs to set some environment > +variables. > + > +@lisp > +(list ("ENV_VAR1" . "value1") > + ("ENV_VAR2" . "value2")) > +@end lisp > + > +The easiest way to extend service type, without defining new service ^ Missing “a” > +type is to use the @code{simple-service} helper from @code{(gnu > +services)}. > + > +@lisp > +(simple-service 'some-useful-env-vars-service > + home-environment-variables-service-type > + `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst") > + ("SHELL" . ,(file-append zsh "/bin/zsh")) > + ("USELESS_VAR" . #f) > + ("_JAVA_AWT_WM_NONREPARENTING" . #t))) > +@end lisp > + > +If you include such service to you home environment definition, it will s/to/in/ > +add the following content to the @file{setup-environment} script (which > +is expected to be sourced by the login shell): > + > +@example > +export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst > +export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh > +export _JAVA_AWT_WM_NONREPARENTING > +@end example > + > +@quotation Note > +Make sure that module @code{(gnu packages shells)} is imported with > +@code{use-modules} or any other way, this namespace contains definition > +of @code{zsh} packages, which is used in the example above. “this namespace contains the definition of the @code{zsh} package, …” > +The key of the association list (@pxref{Association Lists, alists, > +Association Lists, guile, The GNU Guile Reference manual}) is always a > +string, the value can be a string, string-valued gexp > +(@pxref{G-Expressions}) file-like object (@pxref{G-Expressions, > +file-like object}) or boolean. For gexps, the variable will be set to Maybe use ‘car’/‘cdr’ instead of ‘key’/‘value’? At first I though that “the value can be a string, …” was referring to the previous clause, which obviously doesn’t make sense. ;-) > +the value of the gexp; for file-like objects, it will be set to the path > +of the file in the store (@pxref{The Store}); for @code{#t}, it will > +export the variable without any value; and for @code{#f}, it will omit > +variable. > + > +@end defvr > + > +@defvr {Scheme Variable} home-profile-service-type > +The service of this type will be instantiated by every home environment > +automatically, there is no need to define it, but you may want to extend > +it with a list of packages if you want to install additional packages > +into your profile. Other services, which need to make some programs > +avaliable to the user will also extend this service type. > + > +The extension value is just a list of packages: > + > +@lisp > +(list htop vim emacs) > +@end lisp > + > +The same approach as @code{simple-service} (@pxref{Service Reference, > +simple-service}) for @code{home-environment-variables-service-type} can > +be used here, too. Make sure that modules containing the specified > +packages are imported with @code{use-modules}. To find a package or > +information about its module use @command{guix search} (@pxref{Invoking > +guix package}). Alternatively, @code{specification->package} can be > +used to get the package record from string without importing related > +module. > +@end defvr > + > +There are few more essential services, but users are not expected to > +extend them. > + > +@defvr {Scheme Variable} home-service-type > +The root of home services DAG, it generates a folder, which later will be > +symlinked to @file{~/.guix-home}, it contains configurations, > +profile with binaries and libraries, and some necessary scripts to glue > +things together. > +@end defvr > + > +@defvr {Scheme Variable} home-run-on-first-login-service-type > +The service of this type generates a Guile script, which is expected to > +be executed by the login shell. It is only executed if the special flag > +file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents > +redundant executions of the script if multiple login shells are spawned. > + > +It Can be extended with a gexp. However, to autostart an application, s/Can/can/ > +users SHOULD NOT use this service, in most cases it's better to extend Maybe @emph{should not} instead? > +@code{home-shpeherd-service-type} with a Shepherd service > +(@pxref{Shepherd Services}), or extend the shell's startup file with > +required command using the appropriate service type. > +@end defvr > + > +@defvr {Scheme Variable} home-activation-service-type > +The service of this type generates a guile script, which runs on every > +@command{guix home reconfigure} invocation or any other action, which > +leads to activation of home environment. “leads to the activation of the home environment.” > +@end defvr > + > +@node Shells Home Services > +@subsection Shells > + > +@cindex shell > +@cindex login shell > +@cindex interactive shell > +@cindex bash > +@cindex zsh > + > +Shells play a quite important role in the environment initialization > +process, you can configure them manually as described in section > +@ref{Configuring the Shell}, but the recommended way is to use home services > +listed below. It's both easier and more reliable. > + > +Each home environment instantiates > +@code{home-shell-profile-service-type}, which creates a > +@file{~/.profile} startup file for all POSIX-compatible shells. This > +file contains all the necessary steps to properly initialize the > +environment, but many modern shells like Bash or Zsh prefer their own > +startup files, that's why the respective home services > +(@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure > +that @file{~/.profile} is sourced by @file{~/.bash_profile} and > +@file{~/.zprofile}, respectively. > + > +@subsubheading Shell Profile Service > + > +Available @code{home-shell-profile-configuration} fields are: This section should be re-generated using the updated ‘generate-documenation’ procedure (see commit ad945029a2dbd1fb741be573f13e42c061e72d0f). > + > +@deftypevr {@code{home-shell-profile-configuration} parameter} text-config profile > +@code{home-shell-profile} is instantiated automatically by > +@code{home-environment}, DO NOT create this service manually, it can > +only be extended. > + > +@code{profile} is a list of strings or gexps, which will go to > +@file{~/.profile}. By default @file{~/.profile} contains the > +initialization code, which have to be evaluated by login shell to make > +home-environment's profile avaliable to the user, but other commands can > +be added to the file if it is really necessary. > + > +In most cases shell's configuration files are preferred places for > +user's customizations. Extend home-shell-profile service only if you > +really know what you do. > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@subsubheading Bash Home Service > + > +Available @code{home-bash-configuration} fields are: > + > +@deftypevr {@code{home-bash-configuration} parameter} package package > +The Bash package to use. > + > +@end deftypevr > + > +@deftypevr {@code{home-bash-configuration} parameter} boolean guix-defaults? > +Add sane defaults like reading @file{/etc/bashrc}, coloring output for > +@code{ls} provided by guix to @file{.bashrc}. > + > +Defaults to @samp{#t}. > + > +@end deftypevr > + > +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-profile > +List of strings or gexps, which will be added to @file{.bash_profile}. > +Used for executing user's commands at start of login shell (In most > +cases the shell started on tty just after login). @file{.bash_login} > +won't be ever read, because @file{.bash_profile} always present. > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@deftypevr {@code{home-bash-configuration} parameter} text-config bashrc > +List of strings or gexps, which will be added to @file{.bashrc}. Used > +for executing user's commands at start of interactive shell (The shell > +for interactive usage started by typing @code{bash} or by terminal app > +or any other program). > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-logout > +List of strings or gexps, which will be added to @file{.bash_logout}. > +Used for executing user's commands at the exit of login shell. It won't > +be read in some cases (if the shell terminates by exec'ing another > +process for example). > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@subsubheading Zsh Home Service > + > +Available @code{home-zsh-configuration} fields are: > + > +@deftypevr {@code{home-zsh-configuration} parameter} package package > +The Zsh package to use. > + > +@end deftypevr > + > +@deftypevr {@code{home-zsh-configuration} parameter} boolean xdg-flavor? > +Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes > +@file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}. > +Shell startup process will continue with > +@file{$XDG_CONFIG_HOME/zsh/.zshenv}. > + > +Defaults to @samp{#t}. > + > +@end deftypevr > + > +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshenv > +List of strings or gexps, which will be added to @file{.zshenv}. Used > +for setting user's shell environment variables. Must not contain > +commands assuming the presence of tty or producing output. Will be read > +always. Will be read before any other file in @env{ZDOTDIR}. > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@deftypevr {@code{home-zsh-configuration} parameter} text-config zprofile > +List of strings or gexps, which will be added to @file{.zprofile}. Used > +for executing user's commands at start of login shell (In most cases the > +shell started on tty just after login). Will be read before > +@file{.zlogin}. > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshrc > +List of strings or gexps, which will be added to @file{.zshrc}. Used > +for executing user's commands at start of interactive shell (The shell > +for interactive usage started by typing @code{zsh} or by terminal app or > +any other program). > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogin > +List of strings or gexps, which will be added to @file{.zlogin}. Used > +for executing user's commands at the end of starting process of login > +shell. > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogout > +List of strings or gexps, which will be added to @file{.zlogout}. Used > +for executing user's commands at the exit of login shell. It won't be > +read in some cases (if the shell terminates by exec'ing another process > +for example). > + > +Defaults to @samp{()}. > + > +@end deftypevr > + > +@node Mcron Home Service > +@subsection Scheduled User's Job Execution > + > +@cindex cron > +@cindex mcron > +@cindex scheduling jobs > + > +mcron info here > + > +@node Shepherd Home Service > +@subsection Managing User's Daemons > +shepherd info here > + > +@node Invoking guix home > +@section Invoking @code{guix home} > + > +Once you have written a home environment declaration (@pxref{Declaring > +the Home Environment,,,,}, it can be @dfn{instantiated} using the > +@command{guix home} command. The synopsis is: > + > +@example > +guix home @var{options}@dots{} @var{action} @var{file} > +@end example > + > +@var{file} must be the name of a file containing a > +@code{home-environment} declaration. @var{action} specifies how the > +home environment is instantiated, but there are few auxuliary actions, ^ This comma isn’t needed. > +which don't instantiate it. Currently the following values are > +supported: > + > +@table @code > +@item search > +Display available home service type definitions that match the given > +regular expressions, sorted by relevance: > + > +@cindex shell > +@cindex shell-profile > +@cindex bash > +@cindex zsh > +@example > +$ guix home search shell > +name: home-shell-profile > +location: gnu/home-services/shells.scm:73:2 > +extends: home-files > +description: Create `~/.profile', which is used for environment initialization > ++ of POSIX compatible login shells. Can be extended with a list of strings or > ++ gexps. > +relevance: 6 > + > +name: home-zsh-plugin-manager > +location: gnu/home-services/shellutils.scm:28:2 > +extends: home-zsh home-profile > +description: Install plugins in profile and configure Zsh to load them. > +relevance: 1 > + > +name: home-zsh-direnv > +location: gnu/home-services/shellutils.scm:69:2 > +extends: home-profile home-zsh > +description: Enables `direnv' for `zsh'. Adds hook to `.zshrc' and installs a > ++ package in the profile. > +relevance: 1 > + > +name: home-zsh-autosuggestions > +location: gnu/home-services/shellutils.scm:43:2 > +extends: home-zsh-plugin-manager home-zsh > +description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and > ++ sets reasonable default values for some plugin's variables to improve perfomance > ++ and adjust behavior: `(history completion)' is set for strategy, manual rebind > ++ and async are enabled. > +relevance: 1 > + > +name: home-zsh > +location: gnu/home-services/shells.scm:236:2 > +extends: home-files home-profile > +description: Install and configure Zsh. > +relevance: 1 > + > +name: home-bash > +location: gnu/home-services/shells.scm:388:2 > +extends: home-files home-profile > +description: Install and configure Bash. > +relevance: 1 > + > +@dots{} > +@end example > + > +As for @command{guix package --search}, the result is written in > +@code{recutils} format, which makes it easy to filter the output > +(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). > + > +@item reconfigure > +Build the home environment described in @var{file}, and switch to it. > +Switching means that activation script will be evaluated and (in basic ^ Missing “the” > +scenario) symlinks to configuration files generated from > +@code{home-environment} declaration will be created in @file{~}. If the > +file with the same path already exists in home folder it will be moved > +to @file{~/TIMESTAMP-guix-home-legacy-configs-backup}, where TIMESTAMP > +is a current UNIX epoch time. > + > +@c @footnote{This action (and the related actions > +@c @code{switch-generation} and @code{roll-back}) are usable after home > +@c environmet initialized.}. Why is this commented out? > +@quotation Note > +It is highly recommended to run @command{guix pull} once before you run > +@command{guix home reconfigure} for the first time (@pxref{Invoking guix > +pull}). > +@end quotation > + > +This effects all the configuration specified in @var{file}. > +The command starts shepherd services specified in @var{file} that are not s/shepherd/Shepherd > +currently running; if a service is currently running this command will ^ Missing comma > +arrange for it to be upgraded the next time it is stopped (e.g.@: by > +@code{herd stop X} or @code{herd restart X}). I would rephrase this part if a service is currently running, this command will make it so that the service gets updated the next time it is stopped (e.g., by @command{herd stop X} or @command{herd restart X}). > +This command creates a new generation whose number is one greater than > +the current generation (as reported by @command{guix home > +list-generations}). If that generation already exists, it will be > +overwritten. This behavior mirrors that of @command{guix package} > +(@pxref{Invoking guix package}). > + > +@cindex provenance tracking, of the home environment > +Upon completion, the new home is deployed under @file{~/.guix-home}. > +This directory contains @dfn{provenance meta-data}: the list of channels > +in use (@pxref{Channels}) and @var{file} itself, when available. You > +can view it by running: s/it/the provenance information/ Excited to see Guix Home get merged soon! :-)
On 2021-09-01 13:57, Xinglu Chen wrote: > On Wed, Sep 01 2021, Andrew Tropin wrote: > >> * doc/guix.texi: Add Guix Home documentation. >> * doc/he-config-bare-bones.texi: Add home-environment example configuration. >> --- >> Reread and updated documentation for Guix Home to reflect latest changes, >> still a subject for review and proofreading. Combined all changes into one >> commit. Sections about Mcron and Shepherd (which are not in wip-guix-home >> yet) contains only placeholders, will be updated with patches for related home >> services. There is no section about Gradual Migration to Guix Home and >> Invoking guix home's subsection about 'guix home import' subcommand yet, they >> are planned, but probably will come later. > > Going to read this once again and leave some thoughts and comments while > reading. (Edit: expect a long reply!) :-) > >> doc/guix.texi | 687 ++++++++++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 687 insertions(+) >> >> diff --git a/doc/guix.texi b/doc/guix.texi >> index 2b8448c856..8a50678a80 100644 >> --- a/doc/guix.texi >> +++ b/doc/guix.texi >> @@ -96,6 +96,7 @@ Copyright @copyright{} 2021 Domagoj Stolfa@* >> Copyright @copyright{} 2021 Hui Lu@* >> Copyright @copyright{} 2021 pukkamustard@* >> Copyright @copyright{} 2021 Alice Brenon@* >> +Copyright @copyright{} 2021 Andrew Tropin@* >> >> Permission is granted to copy, distribute and/or modify this document >> under the terms of the GNU Free Documentation License, Version 1.3 or >> @@ -167,6 +168,7 @@ Weblate} (@pxref{Translating Guix}). >> * Programming Interface:: Using Guix in Scheme. >> * Utilities:: Package management commands. >> * System Configuration:: Configuring the operating system. >> +* Home Configuration:: Configuring the home environment. >> * Documentation:: Browsing software user manuals. >> * Installing Debugging Files:: Feeding the debugger. >> * Security Updates:: Deploying security fixes quickly. >> @@ -328,6 +330,10 @@ System Configuration >> * Running Guix in a VM:: How to run Guix System in a virtual machine. >> * Defining Services:: Adding new service definitions. >> >> +Home Environment Configuration >> + >> +* Invoking guix home:: Instantiating a home environment configuration. >> + >> Services >> >> * Base Services:: Essential system services. >> @@ -35090,6 +35096,687 @@ system: >> This service represents PID@tie{}1. >> @end defvr >> >> +@node Home Configuration >> +@chapter Home Configuration >> +@cindex home configuration >> +Guix supports declarative configuration of @dfn{home environment} by > > @dfn{home environments} (plural form) > Done. > >> +utilizing the configuration mechanism described in the previous chapter >> +(@pxref{Defining Services}), but for user's home. It works both on Guix > ^ > Double spacing. > > “users's home” sounds kind of vague; maybe “user's dotfiles and > packages”. > Done. > >> +System and foreign distros and allows users to declare all the packages > > Maybe “packages and services” instead of just “packages”? > Done. > >> +that should be installed and configured for the user. After that, such > > It’s not super clear what “After that” is referring to. Maybe > > Once a user has written a file containing a home environment > > ? > >> +a @dfn{home configuration} can be @dfn{instantiated} by an unprivileged > > What is the difference between “home environment” and “home > configuration”? > Rephrased: Once a user has written a file containing @code{home-environment} record, such a configuration can be @dfn{instantiated} by an unprivileged user with the @command{guix home} command (@pxref{Invoking guix home}). > >> +user with the @command{guix home} command (@pxref{Invoking guix home}). >> +@c Maybe later, it will be possible to make home configuration a part of >> +@c system configuration to make everything managed by guix system. >> + >> +User's home environment usually consists of three basic parts: software, > > “The users's home environment” > Done. > >> +configuration and state. Software in mainstream distros are usually > ^ > Missing comma. > Done. > >> +installed system-wide, but with GNU Guix most software packages can be >> +installed on a per-user basis without needing root privileges, and are >> +thus considered part of the user’s @dfn{home environment}. Packages on >> +their own not very useful in many cases, because often they require some >> +additional configuration, usually config files that reside in >> +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) or other > > Maybe just “(@file{~/.config} by default)” instead of “(default value is > @file{~/.config})”? > Done. > >> +directories. Everything else can be considered state, like media files, >> +application databases, and logs. >> + >> +Using Guix for managing home environments provides a number of >> +advantages: >> + >> +@itemize >> + >> +@item All software can be configured in one language (Guile Scheme), >> +this gives users to ability to share values between configurations of > ^^ > s/to/the > >> +different programs and other benifits. > > “and other benifits” doesn’t really fit here; I suggest we remove it. > Done. > >> +@item A well-defined home environment is self-contained and can be >> +created in a declarative and reproducible way. There is no need to grab >> +external binaries or manually edit some configuration file. > > I would personally use “---” instead of putting a period and starting a > new sentence. > > @item A well-defined home environment is self-contained and can be > created in a declarative and reproducible way---there is no need to grab > external binaries or manually edit some configuration file. > Done. > >> +@item After every @command{guix home reconfigure} invocation, a new home >> +environment generation will be created. This means that users can >> +rollback to a previous home environment generation so they don’t have to >> +worry about breaking their configuration. >> + >> +@item It is possible to manage stateful data with Guix Home, this >> +includes the ability to automatically clone Git repositories on the >> +initial setup of the machine, and periodically running commands like >> +@command{rsync} to sync data with another host. This functionality is >> +still in an experimental stage, though. >> + >> +@end itemize >> + >> +@menu >> +* Declaring the Home Environment:: Customizing your Home. >> +* Configuring the Shell:: Enabling home environment. >> +* Home Services:: Specifying home services. >> +* Invoking guix home:: Instantiating a home configuration. >> +@end menu >> + >> +@node Declaring the Home Environment >> +@section Declaring the Home Environment >> +The home environment is configured by providing @code{home-environment} > ^ > Missing “a” > Done. > >> +declaration in a file that can be passed to the @command{guix home} >> +command (@pxref{Invoking guix home}). A simple setup can include Bash >> +and custom text configuration, like in the example below. Don't be > ^ > Missing “a” :-) > Changed to: and a custom text configuration > >> +afraid to declare home environment parts, which overlaps with your >> +current dotfiles, before installing any configuration files Guix Home > ^ > Missing comma. > Done. > >> +will back up existing config files to a separate place in the home >> +folder. >> + >> +@quotation Note >> +It is highly recommended that you manage your shell or shells with Guix >> +Home, because it will make sure that all the necessary scripts are >> +sourced by shell configuration file. Otherwise you will need to do it > ^ > Missing “the” > Done. > >> +manually. (@pxref{Configuring the Shell}). >> +@end quotation >> + >> +@findex home-environment >> +@lisp >> +@include he-config-bare-bones.texi >> +@end lisp >> + >> +The @code{packages} field should be self-explanatory, it will install >> +the list of packages into the user's profile. The most important field >> +is @code{services}, it contains a list of @dfn{home services}, which are >> +the basic building blocks of a home environment. >> + >> +There is no daemon (at least not necessary) related to home service, > > s/necessary/necessarily (adverb form) > Done. > > s/service/services (plural form) > >> +it's just an element that is used to declare part of home environment >> +and extend other parts of it. > > I don’t quite understand this part. > Rephrased: There is no daemon (at least not necessarily) related to a home service, a home service is just an element that is used to declare part of home environment and extend other parts of it. > >> The extension mechanism discussed in the >> +previous chapter (@pxref{Defining Services}) should not be confused with >> +@ref{Shepherd Services}. Using this extension mechanism and some Scheme >> +code that glues things together gives a lot of freedom in declaring of >> +very custom home environments. > > I would rephrase the last sentence > > Using this extension mechanism and some Scheme code that glues things > together giver the user the freedom to declare their own, very custom, > home environment. > Done. > >> +@node Configuring the Shell >> +@section Configuring the Shell >> +This section is safe to skip if your shell or shells are managed by >> +Guix Home. Otherwise, read it carefully. >> + >> +There are a few scripts that must be evaluated by a login shell to >> +activate the home environment. The shell startup files only read by >> +login shells often have @code{profile} suffix. For more information >> +about login shells see @ref{Invoking Bash,,, bash, The GNU Bash >> +Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash >> +Reference Manual}. >> + >> +The first script is @file{setup-environment}, which sets all the > > “The first script that needs to be sourced is @file{setup-environment}” > Done. > >> +necessary environment variables (including variables declared by user) > ^ > Missing “the” > Done. > >> +and the second one is @file{on-first-login}, which starts Shepherd for >> +the current user and performs actions declared by other home services >> +extending @code{home-run-on-first-login-service-type}. > > s/extending/that extends/ > Done. > >> +Guix Home will always create @file{~/.profile}, which contains the >> +following lines: >> + >> +@example >> +HOME_ENVIRONMENT=$HOME/.guix-home >> +. $HOME_ENVIRONMENT/setup-environment >> +$HOME_ENVIRONMENT/on-first-login >> +@end example >> + >> +That makes POSIX compliant login shells activate the home environment. > > s/That/This/ > Done. > >> +However, in most cases this file won't be read by most modern shells, >> +because they are run in non POSIX mode by default and have their own >> +@file{*profile} startup files. For example Bash will prefer >> +@file{~/.bash_profile} in case it exists and only if it doesn't will it >> +fallback to @file{~/.profile}. Zsh (if no additional options specified) > ^ > Missing “are” > Done. > >> +will ignore @file{~/.profile}, even if @file{~/.zprofile} doesn't exist. >> + >> +To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or >> +@code{source ~/profile} to the startup file for the login shell. In >> +case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is >> +@file{~/.zprofile}. >> + >> +@quotation Note >> +This step is only required if your shell is NOT managed by Guix Home. >> +Otherwise, everything will be done automatically. >> +@end quotation >> + >> +@node Home Services >> +@section Home Services >> +@cindex home services >> + >> +A @dfn{home service} is not necessarily something that has a daemon and >> +is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd >> +Manual}), in most cases it doesn't. It's a simple building block of >> +home environment, often declaring a set of packages to be installed in > ^ > Missing “the” > Done. > >> +the home environment profile, a set of config files to be symlinked into >> +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and > ^ > “(@file{~/.config} by default)” > > Missing comma. > Done. > >> +environment variables to be set by a login shell. >> + >> +There is a service extension mechanism (@pxref{Service Composition}), >> +which allows home services to extend other home services and utilize >> +capabilities they provide, for example: declare mcron jobs >> +(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home >> +Service}, declare daemons by extending @ref{Shepherd Home Service}, add >> +commands, which will be invoked on by the Bash by extending >> +@ref{Shells Home Services, @code{home-bash-service-type}}. > > I would use semicolons instead of commas for separating the clauses. > > There is a service extension mechanism (@pxref{Service Composition}) > which allows home services to extend other home services and utilize > capabilities they provide; for example: declare mcron jobs > (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home > Service}; declare daemons by extending @ref{Shepherd Home Service}; add > commands, which will be invoked on by the Bash by extending > @ref{Shells Home Services, @code{home-bash-service-type}}. > Picked your version > >> +The good way to discover avaliable home services is using the > > I would “A” instead of “The”, which sounds a bit authoritative. > Done. > >> +@command{guix home search} command (@pxref{Invoking guix home}). After >> +the required home services are found, include its module with the >> +@code{use-modules} form (@pxref{use-modules,, Using Guile Modules, >> +guile, The GNU Guile Reference Manual}), or the @code{#:use-modules} >> +directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU >> +Guile Reference Manual}) and declare a home service using the >> +@code{service} function, or extend a service type by declaring a new >> +service with the @code{simple-service} procedure from @code{(gnu >> +services)}. >> + >> +@menu >> +* Essential Home Services:: Environment variables, packages, on-* scripts. >> +* Shells: Shells Home Services. POSIX shells, Bash, Zsh. >> +* Mcron: Mcron Home Service. Scheduled User's Job Execution. >> +* Shepherd: Shepherd Home Service. Managing User's Daemons. >> +@end menu >> +@c In addition to that Home Services can provide >> + >> +@node Essential Home Services >> +@subsection Essential Home Services >> +There are a few essential services defined in @code{(gnu >> +home-services)}, they are mostly for internal use and are required to >> +build a home environment, but some of them will be useful for the end >> +user. >> + >> +@cindex environment variables >> + >> +@defvr {Scheme Variable} home-environment-variables-service-type >> +The service of this type will be instantiated by every home environment >> +automatically by default, there is no need to define it, but someone may >> +want to extend it with a list of pairs to set some environment >> +variables. >> + >> +@lisp >> +(list ("ENV_VAR1" . "value1") >> + ("ENV_VAR2" . "value2")) >> +@end lisp >> + >> +The easiest way to extend service type, without defining new service > ^ > Missing “a” > Done. > >> +type is to use the @code{simple-service} helper from @code{(gnu >> +services)}. >> + >> +@lisp >> +(simple-service 'some-useful-env-vars-service >> + home-environment-variables-service-type >> + `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst") >> + ("SHELL" . ,(file-append zsh "/bin/zsh")) >> + ("USELESS_VAR" . #f) >> + ("_JAVA_AWT_WM_NONREPARENTING" . #t))) >> +@end lisp >> + >> +If you include such service to you home environment definition, it will > > s/to/in/ > >> +add the following content to the @file{setup-environment} script (which >> +is expected to be sourced by the login shell): >> + >> +@example >> +export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst >> +export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh >> +export _JAVA_AWT_WM_NONREPARENTING >> +@end example >> + >> +@quotation Note >> +Make sure that module @code{(gnu packages shells)} is imported with >> +@code{use-modules} or any other way, this namespace contains definition >> +of @code{zsh} packages, which is used in the example above. > > “this namespace contains the definition of the @code{zsh} package, …” > Done. > >> +The key of the association list (@pxref{Association Lists, alists, >> +Association Lists, guile, The GNU Guile Reference manual}) is always a >> +string, the value can be a string, string-valued gexp >> +(@pxref{G-Expressions}) file-like object (@pxref{G-Expressions, >> +file-like object}) or boolean. For gexps, the variable will be set to > > Maybe use ‘car’/‘cdr’ instead of ‘key’/‘value’? At first I though that > “the value can be a string, …” was referring to the previous clause, > which obviously doesn’t make sense. ;-) > Rephrased: The association list (@pxref{Association Lists, alists, Association Lists, guile, The GNU Guile Reference manual}) is a data structure containing key-value pairs, for @code{home-environment-variables-service-type} the key is always a string, the value can be a string, string-valued gexp (@pxref{G-Expressions}), file-like object (@pxref{G-Expressions, file-like object}) or boolean. For gexps, the variable will be set to the value of the gexp; for file-like objects, it will be set to the path of the file in the store (@pxref{The Store}); for @code{#t}, it will export the variable without any value; and for @code{#f}, it will omit variable. > >> +the value of the gexp; for file-like objects, it will be set to the path >> +of the file in the store (@pxref{The Store}); for @code{#t}, it will >> +export the variable without any value; and for @code{#f}, it will omit >> +variable. >> + >> +@end defvr >> + >> +@defvr {Scheme Variable} home-profile-service-type >> +The service of this type will be instantiated by every home environment >> +automatically, there is no need to define it, but you may want to extend >> +it with a list of packages if you want to install additional packages >> +into your profile. Other services, which need to make some programs >> +avaliable to the user will also extend this service type. >> + >> +The extension value is just a list of packages: >> + >> +@lisp >> +(list htop vim emacs) >> +@end lisp >> + >> +The same approach as @code{simple-service} (@pxref{Service Reference, >> +simple-service}) for @code{home-environment-variables-service-type} can >> +be used here, too. Make sure that modules containing the specified >> +packages are imported with @code{use-modules}. To find a package or >> +information about its module use @command{guix search} (@pxref{Invoking >> +guix package}). Alternatively, @code{specification->package} can be >> +used to get the package record from string without importing related >> +module. >> +@end defvr >> + >> +There are few more essential services, but users are not expected to >> +extend them. >> + >> +@defvr {Scheme Variable} home-service-type >> +The root of home services DAG, it generates a folder, which later will be >> +symlinked to @file{~/.guix-home}, it contains configurations, >> +profile with binaries and libraries, and some necessary scripts to glue >> +things together. >> +@end defvr >> + >> +@defvr {Scheme Variable} home-run-on-first-login-service-type >> +The service of this type generates a Guile script, which is expected to >> +be executed by the login shell. It is only executed if the special flag >> +file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents >> +redundant executions of the script if multiple login shells are spawned. >> + >> +It Can be extended with a gexp. However, to autostart an application, > > s/Can/can/ > Done. > >> +users SHOULD NOT use this service, in most cases it's better to extend > > Maybe @emph{should not} instead? > Done. > >> +@code{home-shpeherd-service-type} with a Shepherd service >> +(@pxref{Shepherd Services}), or extend the shell's startup file with >> +required command using the appropriate service type. >> +@end defvr >> + >> +@defvr {Scheme Variable} home-activation-service-type >> +The service of this type generates a guile script, which runs on every >> +@command{guix home reconfigure} invocation or any other action, which >> +leads to activation of home environment. > > “leads to the activation of the home environment.” > Done. > >> +@end defvr >> + >> +@node Shells Home Services >> +@subsection Shells >> + >> +@cindex shell >> +@cindex login shell >> +@cindex interactive shell >> +@cindex bash >> +@cindex zsh >> + >> +Shells play a quite important role in the environment initialization >> +process, you can configure them manually as described in section >> +@ref{Configuring the Shell}, but the recommended way is to use home services >> +listed below. It's both easier and more reliable. >> + >> +Each home environment instantiates >> +@code{home-shell-profile-service-type}, which creates a >> +@file{~/.profile} startup file for all POSIX-compatible shells. This >> +file contains all the necessary steps to properly initialize the >> +environment, but many modern shells like Bash or Zsh prefer their own >> +startup files, that's why the respective home services >> +(@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure >> +that @file{~/.profile} is sourced by @file{~/.bash_profile} and >> +@file{~/.zprofile}, respectively. >> + >> +@subsubheading Shell Profile Service >> + >> +Available @code{home-shell-profile-configuration} fields are: > > This section should be re-generated using the updated > ‘generate-documenation’ procedure (see commit > ad945029a2dbd1fb741be573f13e42c061e72d0f). > Done. > >> + >> +@deftypevr {@code{home-shell-profile-configuration} parameter} text-config profile >> +@code{home-shell-profile} is instantiated automatically by >> +@code{home-environment}, DO NOT create this service manually, it can >> +only be extended. >> + >> +@code{profile} is a list of strings or gexps, which will go to >> +@file{~/.profile}. By default @file{~/.profile} contains the >> +initialization code, which have to be evaluated by login shell to make >> +home-environment's profile avaliable to the user, but other commands can >> +be added to the file if it is really necessary. >> + >> +In most cases shell's configuration files are preferred places for >> +user's customizations. Extend home-shell-profile service only if you >> +really know what you do. >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@subsubheading Bash Home Service >> + >> +Available @code{home-bash-configuration} fields are: >> + >> +@deftypevr {@code{home-bash-configuration} parameter} package package >> +The Bash package to use. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-bash-configuration} parameter} boolean guix-defaults? >> +Add sane defaults like reading @file{/etc/bashrc}, coloring output for >> +@code{ls} provided by guix to @file{.bashrc}. >> + >> +Defaults to @samp{#t}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-profile >> +List of strings or gexps, which will be added to @file{.bash_profile}. >> +Used for executing user's commands at start of login shell (In most >> +cases the shell started on tty just after login). @file{.bash_login} >> +won't be ever read, because @file{.bash_profile} always present. >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-bash-configuration} parameter} text-config bashrc >> +List of strings or gexps, which will be added to @file{.bashrc}. Used >> +for executing user's commands at start of interactive shell (The shell >> +for interactive usage started by typing @code{bash} or by terminal app >> +or any other program). >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-logout >> +List of strings or gexps, which will be added to @file{.bash_logout}. >> +Used for executing user's commands at the exit of login shell. It won't >> +be read in some cases (if the shell terminates by exec'ing another >> +process for example). >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@subsubheading Zsh Home Service >> + >> +Available @code{home-zsh-configuration} fields are: >> + >> +@deftypevr {@code{home-zsh-configuration} parameter} package package >> +The Zsh package to use. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-zsh-configuration} parameter} boolean xdg-flavor? >> +Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes >> +@file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}. >> +Shell startup process will continue with >> +@file{$XDG_CONFIG_HOME/zsh/.zshenv}. >> + >> +Defaults to @samp{#t}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshenv >> +List of strings or gexps, which will be added to @file{.zshenv}. Used >> +for setting user's shell environment variables. Must not contain >> +commands assuming the presence of tty or producing output. Will be read >> +always. Will be read before any other file in @env{ZDOTDIR}. >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zprofile >> +List of strings or gexps, which will be added to @file{.zprofile}. Used >> +for executing user's commands at start of login shell (In most cases the >> +shell started on tty just after login). Will be read before >> +@file{.zlogin}. >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshrc >> +List of strings or gexps, which will be added to @file{.zshrc}. Used >> +for executing user's commands at start of interactive shell (The shell >> +for interactive usage started by typing @code{zsh} or by terminal app or >> +any other program). >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogin >> +List of strings or gexps, which will be added to @file{.zlogin}. Used >> +for executing user's commands at the end of starting process of login >> +shell. >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogout >> +List of strings or gexps, which will be added to @file{.zlogout}. Used >> +for executing user's commands at the exit of login shell. It won't be >> +read in some cases (if the shell terminates by exec'ing another process >> +for example). >> + >> +Defaults to @samp{()}. >> + >> +@end deftypevr >> + >> +@node Mcron Home Service >> +@subsection Scheduled User's Job Execution >> + >> +@cindex cron >> +@cindex mcron >> +@cindex scheduling jobs >> + >> +mcron info here >> + >> +@node Shepherd Home Service >> +@subsection Managing User's Daemons >> +shepherd info here >> + >> +@node Invoking guix home >> +@section Invoking @code{guix home} >> + >> +Once you have written a home environment declaration (@pxref{Declaring >> +the Home Environment,,,,}, it can be @dfn{instantiated} using the >> +@command{guix home} command. The synopsis is: >> + >> +@example >> +guix home @var{options}@dots{} @var{action} @var{file} >> +@end example >> + >> +@var{file} must be the name of a file containing a >> +@code{home-environment} declaration. @var{action} specifies how the >> +home environment is instantiated, but there are few auxuliary actions, > ^ > This comma isn’t needed. > Done. > >> +which don't instantiate it. Currently the following values are >> +supported: >> + >> +@table @code >> +@item search >> +Display available home service type definitions that match the given >> +regular expressions, sorted by relevance: >> + >> +@cindex shell >> +@cindex shell-profile >> +@cindex bash >> +@cindex zsh >> +@example >> +$ guix home search shell >> +name: home-shell-profile >> +location: gnu/home-services/shells.scm:73:2 >> +extends: home-files >> +description: Create `~/.profile', which is used for environment initialization >> ++ of POSIX compatible login shells. Can be extended with a list of strings or >> ++ gexps. >> +relevance: 6 >> + >> +name: home-zsh-plugin-manager >> +location: gnu/home-services/shellutils.scm:28:2 >> +extends: home-zsh home-profile >> +description: Install plugins in profile and configure Zsh to load them. >> +relevance: 1 >> + >> +name: home-zsh-direnv >> +location: gnu/home-services/shellutils.scm:69:2 >> +extends: home-profile home-zsh >> +description: Enables `direnv' for `zsh'. Adds hook to `.zshrc' and installs a >> ++ package in the profile. >> +relevance: 1 >> + >> +name: home-zsh-autosuggestions >> +location: gnu/home-services/shellutils.scm:43:2 >> +extends: home-zsh-plugin-manager home-zsh >> +description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and >> ++ sets reasonable default values for some plugin's variables to improve perfomance >> ++ and adjust behavior: `(history completion)' is set for strategy, manual rebind >> ++ and async are enabled. >> +relevance: 1 >> + >> +name: home-zsh >> +location: gnu/home-services/shells.scm:236:2 >> +extends: home-files home-profile >> +description: Install and configure Zsh. >> +relevance: 1 >> + >> +name: home-bash >> +location: gnu/home-services/shells.scm:388:2 >> +extends: home-files home-profile >> +description: Install and configure Bash. >> +relevance: 1 >> + >> +@dots{} >> +@end example >> + >> +As for @command{guix package --search}, the result is written in >> +@code{recutils} format, which makes it easy to filter the output >> +(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). >> + >> +@item reconfigure >> +Build the home environment described in @var{file}, and switch to it. >> +Switching means that activation script will be evaluated and (in basic > ^ > Missing “the” > Done. > >> +scenario) symlinks to configuration files generated from >> +@code{home-environment} declaration will be created in @file{~}. If the >> +file with the same path already exists in home folder it will be moved >> +to @file{~/TIMESTAMP-guix-home-legacy-configs-backup}, where TIMESTAMP >> +is a current UNIX epoch time. >> + >> +@c @footnote{This action (and the related actions >> +@c @code{switch-generation} and @code{roll-back}) are usable after home >> +@c environmet initialized.}. > > Why is this commented out? > >> +@quotation Note >> +It is highly recommended to run @command{guix pull} once before you run >> +@command{guix home reconfigure} for the first time (@pxref{Invoking guix >> +pull}). >> +@end quotation >> + >> +This effects all the configuration specified in @var{file}. >> +The command starts shepherd services specified in @var{file} that are not > > s/shepherd/Shepherd > Done. > >> +currently running; if a service is currently running this command will > ^ > Missing comma > Done. > >> +arrange for it to be upgraded the next time it is stopped (e.g.@: by >> +@code{herd stop X} or @code{herd restart X}). > > I would rephrase this part > > if a service is currently running, this command will make it so that > the service gets updated the next time it is stopped (e.g., by > @command{herd stop X} or @command{herd restart X}). > Kept the original version. > >> +This command creates a new generation whose number is one greater than >> +the current generation (as reported by @command{guix home >> +list-generations}). If that generation already exists, it will be >> +overwritten. This behavior mirrors that of @command{guix package} >> +(@pxref{Invoking guix package}). >> + >> +@cindex provenance tracking, of the home environment >> +Upon completion, the new home is deployed under @file{~/.guix-home}. >> +This directory contains @dfn{provenance meta-data}: the list of channels >> +in use (@pxref{Channels}) and @var{file} itself, when available. You >> +can view it by running: > > s/it/the provenance information/ > Done. > > Excited to see Guix Home get merged soon! :-) (: Thank you for all the help)
diff --git a/doc/guix.texi b/doc/guix.texi index 2b8448c856..8a50678a80 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -96,6 +96,7 @@ Copyright @copyright{} 2021 Domagoj Stolfa@* Copyright @copyright{} 2021 Hui Lu@* Copyright @copyright{} 2021 pukkamustard@* Copyright @copyright{} 2021 Alice Brenon@* +Copyright @copyright{} 2021 Andrew Tropin@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -167,6 +168,7 @@ Weblate} (@pxref{Translating Guix}). * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. * System Configuration:: Configuring the operating system. +* Home Configuration:: Configuring the home environment. * Documentation:: Browsing software user manuals. * Installing Debugging Files:: Feeding the debugger. * Security Updates:: Deploying security fixes quickly. @@ -328,6 +330,10 @@ System Configuration * Running Guix in a VM:: How to run Guix System in a virtual machine. * Defining Services:: Adding new service definitions. +Home Environment Configuration + +* Invoking guix home:: Instantiating a home environment configuration. + Services * Base Services:: Essential system services. @@ -35090,6 +35096,687 @@ system: This service represents PID@tie{}1. @end defvr +@node Home Configuration +@chapter Home Configuration +@cindex home configuration +Guix supports declarative configuration of @dfn{home environment} by +utilizing the configuration mechanism described in the previous chapter +(@pxref{Defining Services}), but for user's home. It works both on Guix +System and foreign distros and allows users to declare all the packages +that should be installed and configured for the user. After that, such +a @dfn{home configuration} can be @dfn{instantiated} by an unprivileged +user with the @command{guix home} command (@pxref{Invoking guix home}). +@c Maybe later, it will be possible to make home configuration a part of +@c system configuration to make everything managed by guix system. + +User's home environment usually consists of three basic parts: software, +configuration and state. Software in mainstream distros are usually +installed system-wide, but with GNU Guix most software packages can be +installed on a per-user basis without needing root privileges, and are +thus considered part of the user’s @dfn{home environment}. Packages on +their own not very useful in many cases, because often they require some +additional configuration, usually config files that reside in +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) or other +directories. Everything else can be considered state, like media files, +application databases, and logs. + +Using Guix for managing home environments provides a number of +advantages: + +@itemize + +@item All software can be configured in one language (Guile Scheme), +this gives users to ability to share values between configurations of +different programs and other benifits. + +@item A well-defined home environment is self-contained and can be +created in a declarative and reproducible way. There is no need to grab +external binaries or manually edit some configuration file. + +@item After every @command{guix home reconfigure} invocation, a new home +environment generation will be created. This means that users can +rollback to a previous home environment generation so they don’t have to +worry about breaking their configuration. + +@item It is possible to manage stateful data with Guix Home, this +includes the ability to automatically clone Git repositories on the +initial setup of the machine, and periodically running commands like +@command{rsync} to sync data with another host. This functionality is +still in an experimental stage, though. + +@end itemize + +@menu +* Declaring the Home Environment:: Customizing your Home. +* Configuring the Shell:: Enabling home environment. +* Home Services:: Specifying home services. +* Invoking guix home:: Instantiating a home configuration. +@end menu + +@node Declaring the Home Environment +@section Declaring the Home Environment +The home environment is configured by providing @code{home-environment} +declaration in a file that can be passed to the @command{guix home} +command (@pxref{Invoking guix home}). A simple setup can include Bash +and custom text configuration, like in the example below. Don't be +afraid to declare home environment parts, which overlaps with your +current dotfiles, before installing any configuration files Guix Home +will back up existing config files to a separate place in the home +folder. + +@quotation Note +It is highly recommended that you manage your shell or shells with Guix +Home, because it will make sure that all the necessary scripts are +sourced by shell configuration file. Otherwise you will need to do it +manually. (@pxref{Configuring the Shell}). +@end quotation + +@findex home-environment +@lisp +@include he-config-bare-bones.texi +@end lisp + +The @code{packages} field should be self-explanatory, it will install +the list of packages into the user's profile. The most important field +is @code{services}, it contains a list of @dfn{home services}, which are +the basic building blocks of a home environment. + +There is no daemon (at least not necessary) related to home service, +it's just an element that is used to declare part of home environment +and extend other parts of it. The extension mechanism discussed in the +previous chapter (@pxref{Defining Services}) should not be confused with +@ref{Shepherd Services}. Using this extension mechanism and some Scheme +code that glues things together gives a lot of freedom in declaring of +very custom home environments. + +@node Configuring the Shell +@section Configuring the Shell +This section is safe to skip if your shell or shells are managed by +Guix Home. Otherwise, read it carefully. + +There are a few scripts that must be evaluated by a login shell to +activate the home environment. The shell startup files only read by +login shells often have @code{profile} suffix. For more information +about login shells see @ref{Invoking Bash,,, bash, The GNU Bash +Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash +Reference Manual}. + +The first script is @file{setup-environment}, which sets all the +necessary environment variables (including variables declared by user) +and the second one is @file{on-first-login}, which starts Shepherd for +the current user and performs actions declared by other home services +extending @code{home-run-on-first-login-service-type}. + +Guix Home will always create @file{~/.profile}, which contains the +following lines: + +@example +HOME_ENVIRONMENT=$HOME/.guix-home +. $HOME_ENVIRONMENT/setup-environment +$HOME_ENVIRONMENT/on-first-login +@end example + +That makes POSIX compliant login shells activate the home environment. +However, in most cases this file won't be read by most modern shells, +because they are run in non POSIX mode by default and have their own +@file{*profile} startup files. For example Bash will prefer +@file{~/.bash_profile} in case it exists and only if it doesn't will it +fallback to @file{~/.profile}. Zsh (if no additional options specified) +will ignore @file{~/.profile}, even if @file{~/.zprofile} doesn't exist. + +To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or +@code{source ~/profile} to the startup file for the login shell. In +case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is +@file{~/.zprofile}. + +@quotation Note +This step is only required if your shell is NOT managed by Guix Home. +Otherwise, everything will be done automatically. +@end quotation + +@node Home Services +@section Home Services +@cindex home services + +A @dfn{home service} is not necessarily something that has a daemon and +is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd +Manual}), in most cases it doesn't. It's a simple building block of +home environment, often declaring a set of packages to be installed in +the home environment profile, a set of config files to be symlinked into +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and +environment variables to be set by a login shell. + +There is a service extension mechanism (@pxref{Service Composition}), +which allows home services to extend other home services and utilize +capabilities they provide, for example: declare mcron jobs +(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home +Service}, declare daemons by extending @ref{Shepherd Home Service}, add +commands, which will be invoked on by the Bash by extending +@ref{Shells Home Services, @code{home-bash-service-type}}. + +The good way to discover avaliable home services is using the +@command{guix home search} command (@pxref{Invoking guix home}). After +the required home services are found, include its module with the +@code{use-modules} form (@pxref{use-modules,, Using Guile Modules, +guile, The GNU Guile Reference Manual}), or the @code{#:use-modules} +directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU +Guile Reference Manual}) and declare a home service using the +@code{service} function, or extend a service type by declaring a new +service with the @code{simple-service} procedure from @code{(gnu +services)}. + +@menu +* Essential Home Services:: Environment variables, packages, on-* scripts. +* Shells: Shells Home Services. POSIX shells, Bash, Zsh. +* Mcron: Mcron Home Service. Scheduled User's Job Execution. +* Shepherd: Shepherd Home Service. Managing User's Daemons. +@end menu +@c In addition to that Home Services can provide + +@node Essential Home Services +@subsection Essential Home Services +There are a few essential services defined in @code{(gnu +home-services)}, they are mostly for internal use and are required to +build a home environment, but some of them will be useful for the end +user. + +@cindex environment variables + +@defvr {Scheme Variable} home-environment-variables-service-type +The service of this type will be instantiated by every home environment +automatically by default, there is no need to define it, but someone may +want to extend it with a list of pairs to set some environment +variables. + +@lisp +(list ("ENV_VAR1" . "value1") + ("ENV_VAR2" . "value2")) +@end lisp + +The easiest way to extend service type, without defining new service +type is to use the @code{simple-service} helper from @code{(gnu +services)}. + +@lisp +(simple-service 'some-useful-env-vars-service + home-environment-variables-service-type + `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst") + ("SHELL" . ,(file-append zsh "/bin/zsh")) + ("USELESS_VAR" . #f) + ("_JAVA_AWT_WM_NONREPARENTING" . #t))) +@end lisp + +If you include such service to you home environment definition, it will +add the following content to the @file{setup-environment} script (which +is expected to be sourced by the login shell): + +@example +export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst +export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh +export _JAVA_AWT_WM_NONREPARENTING +@end example + +@quotation Note +Make sure that module @code{(gnu packages shells)} is imported with +@code{use-modules} or any other way, this namespace contains definition +of @code{zsh} packages, which is used in the example above. +@end quotation + + +The key of the association list (@pxref{Association Lists, alists, +Association Lists, guile, The GNU Guile Reference manual}) is always a +string, the value can be a string, string-valued gexp +(@pxref{G-Expressions}) file-like object (@pxref{G-Expressions, +file-like object}) or boolean. For gexps, the variable will be set to +the value of the gexp; for file-like objects, it will be set to the path +of the file in the store (@pxref{The Store}); for @code{#t}, it will +export the variable without any value; and for @code{#f}, it will omit +variable. + +@end defvr + +@defvr {Scheme Variable} home-profile-service-type +The service of this type will be instantiated by every home environment +automatically, there is no need to define it, but you may want to extend +it with a list of packages if you want to install additional packages +into your profile. Other services, which need to make some programs +avaliable to the user will also extend this service type. + +The extension value is just a list of packages: + +@lisp +(list htop vim emacs) +@end lisp + +The same approach as @code{simple-service} (@pxref{Service Reference, +simple-service}) for @code{home-environment-variables-service-type} can +be used here, too. Make sure that modules containing the specified +packages are imported with @code{use-modules}. To find a package or +information about its module use @command{guix search} (@pxref{Invoking +guix package}). Alternatively, @code{specification->package} can be +used to get the package record from string without importing related +module. +@end defvr + +There are few more essential services, but users are not expected to +extend them. + +@defvr {Scheme Variable} home-service-type +The root of home services DAG, it generates a folder, which later will be +symlinked to @file{~/.guix-home}, it contains configurations, +profile with binaries and libraries, and some necessary scripts to glue +things together. +@end defvr + +@defvr {Scheme Variable} home-run-on-first-login-service-type +The service of this type generates a Guile script, which is expected to +be executed by the login shell. It is only executed if the special flag +file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents +redundant executions of the script if multiple login shells are spawned. + +It Can be extended with a gexp. However, to autostart an application, +users SHOULD NOT use this service, in most cases it's better to extend +@code{home-shpeherd-service-type} with a Shepherd service +(@pxref{Shepherd Services}), or extend the shell's startup file with +required command using the appropriate service type. +@end defvr + +@defvr {Scheme Variable} home-activation-service-type +The service of this type generates a guile script, which runs on every +@command{guix home reconfigure} invocation or any other action, which +leads to activation of home environment. +@end defvr + +@node Shells Home Services +@subsection Shells + +@cindex shell +@cindex login shell +@cindex interactive shell +@cindex bash +@cindex zsh + +Shells play a quite important role in the environment initialization +process, you can configure them manually as described in section +@ref{Configuring the Shell}, but the recommended way is to use home services +listed below. It's both easier and more reliable. + +Each home environment instantiates +@code{home-shell-profile-service-type}, which creates a +@file{~/.profile} startup file for all POSIX-compatible shells. This +file contains all the necessary steps to properly initialize the +environment, but many modern shells like Bash or Zsh prefer their own +startup files, that's why the respective home services +(@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure +that @file{~/.profile} is sourced by @file{~/.bash_profile} and +@file{~/.zprofile}, respectively. + +@subsubheading Shell Profile Service + +Available @code{home-shell-profile-configuration} fields are: + +@deftypevr {@code{home-shell-profile-configuration} parameter} text-config profile +@code{home-shell-profile} is instantiated automatically by +@code{home-environment}, DO NOT create this service manually, it can +only be extended. + +@code{profile} is a list of strings or gexps, which will go to +@file{~/.profile}. By default @file{~/.profile} contains the +initialization code, which have to be evaluated by login shell to make +home-environment's profile avaliable to the user, but other commands can +be added to the file if it is really necessary. + +In most cases shell's configuration files are preferred places for +user's customizations. Extend home-shell-profile service only if you +really know what you do. + +Defaults to @samp{()}. + +@end deftypevr + +@subsubheading Bash Home Service + +Available @code{home-bash-configuration} fields are: + +@deftypevr {@code{home-bash-configuration} parameter} package package +The Bash package to use. + +@end deftypevr + +@deftypevr {@code{home-bash-configuration} parameter} boolean guix-defaults? +Add sane defaults like reading @file{/etc/bashrc}, coloring output for +@code{ls} provided by guix to @file{.bashrc}. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-profile +List of strings or gexps, which will be added to @file{.bash_profile}. +Used for executing user's commands at start of login shell (In most +cases the shell started on tty just after login). @file{.bash_login} +won't be ever read, because @file{.bash_profile} always present. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{home-bash-configuration} parameter} text-config bashrc +List of strings or gexps, which will be added to @file{.bashrc}. Used +for executing user's commands at start of interactive shell (The shell +for interactive usage started by typing @code{bash} or by terminal app +or any other program). + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{home-bash-configuration} parameter} text-config bash-logout +List of strings or gexps, which will be added to @file{.bash_logout}. +Used for executing user's commands at the exit of login shell. It won't +be read in some cases (if the shell terminates by exec'ing another +process for example). + +Defaults to @samp{()}. + +@end deftypevr + +@subsubheading Zsh Home Service + +Available @code{home-zsh-configuration} fields are: + +@deftypevr {@code{home-zsh-configuration} parameter} package package +The Zsh package to use. + +@end deftypevr + +@deftypevr {@code{home-zsh-configuration} parameter} boolean xdg-flavor? +Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes +@file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}. +Shell startup process will continue with +@file{$XDG_CONFIG_HOME/zsh/.zshenv}. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshenv +List of strings or gexps, which will be added to @file{.zshenv}. Used +for setting user's shell environment variables. Must not contain +commands assuming the presence of tty or producing output. Will be read +always. Will be read before any other file in @env{ZDOTDIR}. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{home-zsh-configuration} parameter} text-config zprofile +List of strings or gexps, which will be added to @file{.zprofile}. Used +for executing user's commands at start of login shell (In most cases the +shell started on tty just after login). Will be read before +@file{.zlogin}. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{home-zsh-configuration} parameter} text-config zshrc +List of strings or gexps, which will be added to @file{.zshrc}. Used +for executing user's commands at start of interactive shell (The shell +for interactive usage started by typing @code{zsh} or by terminal app or +any other program). + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogin +List of strings or gexps, which will be added to @file{.zlogin}. Used +for executing user's commands at the end of starting process of login +shell. + +Defaults to @samp{()}. + +@end deftypevr + +@deftypevr {@code{home-zsh-configuration} parameter} text-config zlogout +List of strings or gexps, which will be added to @file{.zlogout}. Used +for executing user's commands at the exit of login shell. It won't be +read in some cases (if the shell terminates by exec'ing another process +for example). + +Defaults to @samp{()}. + +@end deftypevr + +@node Mcron Home Service +@subsection Scheduled User's Job Execution + +@cindex cron +@cindex mcron +@cindex scheduling jobs + +mcron info here + +@node Shepherd Home Service +@subsection Managing User's Daemons +shepherd info here + +@node Invoking guix home +@section Invoking @code{guix home} + +Once you have written a home environment declaration (@pxref{Declaring +the Home Environment,,,,}, it can be @dfn{instantiated} using the +@command{guix home} command. The synopsis is: + +@example +guix home @var{options}@dots{} @var{action} @var{file} +@end example + +@var{file} must be the name of a file containing a +@code{home-environment} declaration. @var{action} specifies how the +home environment is instantiated, but there are few auxuliary actions, +which don't instantiate it. Currently the following values are +supported: + +@table @code +@item search +Display available home service type definitions that match the given +regular expressions, sorted by relevance: + +@cindex shell +@cindex shell-profile +@cindex bash +@cindex zsh +@example +$ guix home search shell +name: home-shell-profile +location: gnu/home-services/shells.scm:73:2 +extends: home-files +description: Create `~/.profile', which is used for environment initialization ++ of POSIX compatible login shells. Can be extended with a list of strings or ++ gexps. +relevance: 6 + +name: home-zsh-plugin-manager +location: gnu/home-services/shellutils.scm:28:2 +extends: home-zsh home-profile +description: Install plugins in profile and configure Zsh to load them. +relevance: 1 + +name: home-zsh-direnv +location: gnu/home-services/shellutils.scm:69:2 +extends: home-profile home-zsh +description: Enables `direnv' for `zsh'. Adds hook to `.zshrc' and installs a ++ package in the profile. +relevance: 1 + +name: home-zsh-autosuggestions +location: gnu/home-services/shellutils.scm:43:2 +extends: home-zsh-plugin-manager home-zsh +description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and ++ sets reasonable default values for some plugin's variables to improve perfomance ++ and adjust behavior: `(history completion)' is set for strategy, manual rebind ++ and async are enabled. +relevance: 1 + +name: home-zsh +location: gnu/home-services/shells.scm:236:2 +extends: home-files home-profile +description: Install and configure Zsh. +relevance: 1 + +name: home-bash +location: gnu/home-services/shells.scm:388:2 +extends: home-files home-profile +description: Install and configure Bash. +relevance: 1 + +@dots{} +@end example + +As for @command{guix package --search}, the result is written in +@code{recutils} format, which makes it easy to filter the output +(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). + +@item reconfigure +Build the home environment described in @var{file}, and switch to it. +Switching means that activation script will be evaluated and (in basic +scenario) symlinks to configuration files generated from +@code{home-environment} declaration will be created in @file{~}. If the +file with the same path already exists in home folder it will be moved +to @file{~/TIMESTAMP-guix-home-legacy-configs-backup}, where TIMESTAMP +is a current UNIX epoch time. + +@c @footnote{This action (and the related actions +@c @code{switch-generation} and @code{roll-back}) are usable after home +@c environmet initialized.}. + +@quotation Note +It is highly recommended to run @command{guix pull} once before you run +@command{guix home reconfigure} for the first time (@pxref{Invoking guix +pull}). +@end quotation + +This effects all the configuration specified in @var{file}. +The command starts shepherd 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 +@code{herd stop X} or @code{herd restart X}). + +This command creates a new generation whose number is one greater than +the current generation (as reported by @command{guix home +list-generations}). If that generation already exists, it will be +overwritten. This behavior mirrors that of @command{guix package} +(@pxref{Invoking guix package}). + +@cindex provenance tracking, of the home environment +Upon completion, the new home is deployed under @file{~/.guix-home}. +This directory contains @dfn{provenance meta-data}: the list of channels +in use (@pxref{Channels}) and @var{file} itself, when available. You +can view it by running: + +@example +guix home describe +@end example + +This information is useful should you later want to inspect how this +particular generation was built. In fact, assuming @var{file} is +self-contained, you can later rebuild generation @var{n} of your +home environment with: + +@example +guix time-machine \ + -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \ + home reconfigure \ + /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm + +@end example + +You can think of it as some sort of built-in version control! Your +home is not just a binary artifact: @emph{it carries its own source}. +@c @xref{Service Reference, @code{provenance-service-type}}, for more +@c information on provenance tracking. + +@item switch-generation +@cindex home generations +Switch to an existing home generation. This action atomically switches +the home profile to the specified home generation. + +The target generation can be specified explicitly by its generation +number. For example, the following invocation would switch to home +generation 7: + +@example +guix home switch-generation 7 +@end example + +The target generation can also be specified relative to the current +generation with the form @code{+N} or @code{-N}, where @code{+3} means +``3 generations ahead of the current generation,'' and @code{-1} means +``1 generation prior to the current generation.'' When specifying a +negative value such as @code{-1}, you must precede it with @code{--} to +prevent it from being parsed as an option. For example: + +@example +guix home switch-generation -- -1 +@end example + +This action will fail if the specified generation does not exist. + +@item roll-back +@cindex rolling back +Switch to the preceding home generation. This is the inverse +of @command{reconfigure}, and it is exactly the same as invoking +@command{switch-generation} with an argument of @code{-1}. + +@item delete-generations +@cindex deleting home generations +@cindex saving space +Delete home generations, making them candidates for garbage collection +(@pxref{Invoking guix gc}, for information on how to run the ``garbage +collector''). + +This works in the same way as @samp{guix package --delete-generations} +(@pxref{Invoking guix package, @option{--delete-generations}}). With no +arguments, all home generations but the current one are deleted: + +@example +guix home delete-generations +@end example + +You can also select the generations you want to delete. The example below +deletes all the home generations that are more than two month old: + +@example +guix home delete-generations 2m +@end example + +@item build +Build the derivation of the home environment, which includes all the +configuration files and programs needed. This action does not actually +install anything. + +@item describe +Describe the current home generation: its file name, as well as +provenance information when available. + +@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 +@option{--list-generations} option of @command{guix package} +(@pxref{Invoking guix package}). + +Optionally, one can specify a pattern, with the same syntax that is used +in @command{guix package --list-generations}, to restrict the list of +generations displayed. For instance, the following command displays +generations that are up to 10 days old: + +@example +$ guix home list-generations 10d +@end example + +@end table @node Documentation @chapter Documentation