GNU bug report logs - #50313
[PATCH] doc: Add Guix Home documentation.

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 50313 in the body.
You can then email your comments to 50313 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Andrew Tropin <andrew <at> trop.in>
To: guix-patches <at> gnu.org
Subject: [PATCH] doc: Add Guix Home documentation.
Date: Wed, 1 Sep 2021 11:47:04 +0300

[Message part 1 (text/plain, inline)]

* 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.

 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 <at> 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 <at> 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
-- 
2.33.0

[signature.asc (application/pgp-signature, inline)]

Message #8 received at 50313 <at> debbugs.gnu.org (full text, mbox):

From: Oleg Pykhalov <go.wigust <at> gmail.com>
To: Andrew Tropin <andrew <at> trop.in>
Cc: 50313 <at> debbugs.gnu.org
Subject: Re: [bug#50313] [PATCH] doc: Add Guix Home documentation.
Date: Wed, 01 Sep 2021 13:12:15 +0300

[Message part 1 (text/plain, inline)]

Hi Andrew,

doc/he-config-bare-bones.texi is missing.

[signature.asc (application/pgp-signature, inline)]

Message #11 received at 50313 <at> debbugs.gnu.org (full text, mbox):

From: Xinglu Chen <public <at> yoctocell.xyz>
To: Andrew Tropin <andrew <at> trop.in>, 50313 <at> debbugs.gnu.org
Subject: Re: [bug#50313] [PATCH] doc: Add Guix Home documentation.
Date: Wed, 01 Sep 2021 13:57:32 +0200

[Message part 1 (text/plain, inline)]

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 <at> 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 <at> 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 <at> 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!  :-)

[signature.asc (application/pgp-signature, inline)]

Message #14 received at 50313 <at> debbugs.gnu.org (full text, mbox):

From: Andrew Tropin <andrew <at> trop.in>
To: Xinglu Chen <public <at> yoctocell.xyz>, 50313 <at> debbugs.gnu.org
Subject: Re: [bug#50313] [PATCH] doc: Add Guix Home documentation.
Date: Wed, 01 Sep 2021 16:28:40 +0300

[Message part 1 (text/plain, inline)]

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 <at> 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 <at> 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 <at> 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)

[signature.asc (application/pgp-signature, inline)]

Message #17 received at 50313 <at> debbugs.gnu.org (full text, mbox):

From: Andrew Tropin <andrew <at> trop.in>
To: Oleg Pykhalov <go.wigust <at> gmail.com>
Cc: 50313 <at> debbugs.gnu.org
Subject: [PATCH v2] doc: Add Guix Home documentation.
Date: Wed, 01 Sep 2021 16:32:23 +0300

[Message part 1 (text/plain, inline)]

On 2021-09-01 13:12, Oleg Pykhalov wrote:

> Hi Andrew,
>
> doc/he-config-bare-bones.texi is missing.

Added, also applied the changes suggested by Xinglu.

[v2-0001-doc-Add-Guix-Home-documentation.patch (text/x-patch, inline)]

From 296145ea58bc9c10aa80bc80a24e4f55a87fbef6 Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew <at> trop.in>
Date: Wed, 1 Sep 2021 11:47:04 +0300
Subject: [PATCH v2] doc: Add Guix Home documentation.

* doc/guix.texi: Add Guix Home documentation.
---
 doc/guix.texi                 | 665 ++++++++++++++++++++++++++++++++++
 doc/he-config-bare-bones.texi |  24 ++
 2 files changed, 689 insertions(+)
 create mode 100644 doc/he-config-bare-bones.texi

diff --git a/doc/guix.texi b/doc/guix.texi
index 2b8448c856..d98db87a1d 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,665 @@ system:
 This service represents PID <at> tie{}1.
 @end defvr
 
+@node Home Configuration
+@chapter Home Configuration
+@cindex home configuration
+Guix supports declarative configuration of @dfn{home environments} by
+utilizing the configuration mechanism described in the previous chapter
+(@pxref{Defining Services}), but for user's dotfiles and packages.  It
+works both on Guix System and foreign distros and allows users to
+declare all the packages and services that should be installed and
+configured for the user.  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}).
+@c Maybe later, it will be possible to make home configuration a part of
+@c system configuration to make everything managed by guix system.
+
+The 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} (@file{~/.config} by default) 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 the ability to share values between configurations of
+different programs.
+
+@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 a
+@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 a 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 the 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 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 the user
+the freedom to declare their own, 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 that needs to be sourced is @file{setup-environment},
+which sets all the necessary environment variables (including variables
+declared by the 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 that extends
+@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
+
+This 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 are
+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 the
+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} (@file{~/.config} by default), 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 <at> 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}}.
+
+A 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 a 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 a service in 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 the
+definition of the @code{zsh} packages, which is used in the example
+above.
+@end quotation
+
+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.
+
+@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 @emph{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 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
+
+@deftp {Data Type} home-shell-profile-configuration
+Available @code{home-shell-profile-configuration} fields are:
+
+@table @asis
+@item @code{profile} (default: @code{()}) (type: text-config)
+@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.
+
+@end table
+
+@end deftp
+
+@subsubheading Bash Home Service
+
+@deftp {Data Type} home-bash-configuration
+Available @code{home-bash-configuration} fields are:
+
+@table @asis
+@item @code{package} (default: @code{bash}) (type: package)
+The Bash package to use.
+
+@item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
+Add sane defaults like reading @file{/etc/bashrc}, coloring output for
+@code{ls} provided by guix to @file{.bashrc}.
+
+@item @code{environment-variables} (default: @code{()}) (type: alist)
+Association list of environment variables to set for the Bash session.
+
+@item @code{bash-profile} (default: @code{()}) (type: text-config)
+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.
+
+@item @code{bashrc} (default: @code{()}) (type: text-config)
+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).
+
+@item @code{bash-logout} (default: @code{()}) (type: text-config)
+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).
+
+@end table
+
+@end deftp
+
+@subsubheading Zsh Home Service
+
+@deftp {Data Type} home-zsh-configuration
+Available @code{home-zsh-configuration} fields are:
+
+@table @asis
+@item @code{package} (default: @code{zsh}) (type: package)
+The Zsh package to use.
+
+@item @code{xdg-flavor?} (default: @code{#t}) (type: boolean)
+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}.
+
+@item @code{environment-variables} (default: @code{()}) (type: alist)
+Association list of environment variables to set for the Zsh session.
+
+@item @code{zshenv} (default: @code{()}) (type: text-config)
+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}.
+
+@item @code{zprofile} (default: @code{()}) (type: text-config)
+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}.
+
+@item @code{zshrc} (default: @code{()}) (type: text-config)
+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).
+
+@item @code{zlogin} (default: @code{()}) (type: text-config)
+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.
+
+@item @code{zlogout} (default: @code{()}) (type: text-config)
+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).
+
+@end table
+
+@end deftp
+
+@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 the 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.
+
+@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 the provenance information 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.
+
+@c @footnote{This action (and the related actions
+@c @code{switch-generation} and @code{roll-back}) are usable after the
+@c home environment is initialized.}.
+
+@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
diff --git a/doc/he-config-bare-bones.texi b/doc/he-config-bare-bones.texi
new file mode 100644
index 0000000000..01be46a7b0
--- /dev/null
+++ b/doc/he-config-bare-bones.texi
@@ -0,0 +1,24 @@
+(use-modules (gnu home)
+             (gnu home-services)
+             (gnu home-services shells)
+             (gnu services)
+             (gnu packages admin)
+             (guix gexp))
+
+
+(home-environment
+ (packages (list htop))
+ (services
+  (list
+   (service home-bash-service-type
+            (home-bash-configuration
+             (guix-defaults? #t)
+             (bash-profile '("\
+export HISTFILE=$XDG_CACHE_HOME/.bash_history"))))
+
+   (simple-service 'test-config
+                   home-files-service-type
+                   (list `("config/test.conf"
+                           ,(plain-file "tmp-file.txt"
+                                        "the content of ~/.config/test.conf")))))))
+
-- 
2.33.0

[signature.asc (application/pgp-signature, inline)]

Message #22 received at 50313-done <at> debbugs.gnu.org (full text, mbox):

From: Oleg Pykhalov <go.wigust <at> gmail.com>
To: Andrew Tropin <andrew <at> trop.in>
Cc: 50313-done <at> debbugs.gnu.org
Subject: Re: [PATCH v2] doc: Add Guix Home documentation.
Date: Wed, 01 Sep 2021 18:10:11 +0300

[Message part 1 (text/plain, inline)]

Andrew Tropin <andrew <at> trop.in> writes:

> From 296145ea58bc9c10aa80bc80a24e4f55a87fbef6 Mon Sep 17 00:00:00 2001
> From: Andrew Tropin <andrew <at> trop.in>
> Date: Wed, 1 Sep 2021 11:47:04 +0300
> Subject: [PATCH v2] doc: Add Guix Home documentation.
>
> * doc/guix.texi: Add Guix Home documentation.
> ---
>  doc/guix.texi                 | 665 ++++++++++++++++++++++++++++++++++
>  doc/he-config-bare-bones.texi |  24 ++
>  2 files changed, 689 insertions(+)
>  create mode 100644 doc/he-config-bare-bones.texi

[…]

Moved doc/he-config-bare-bones.texi to doc/he-config-bare-bones.scm
similar to package-hello.scm mentioned in guix.texi, and added changelog
for doc/he-config-bare-bones.scm in Git message.

Pushed to wip-guix-home.

Oleg.

[signature.asc (application/pgp-signature, inline)]

Message #25 received at 50313-done <at> debbugs.gnu.org (full text, mbox):

From: Andrew Tropin <andrew <at> trop.in>
To: Oleg Pykhalov <go.wigust <at> gmail.com>
Cc: 50313-done <at> debbugs.gnu.org
Subject: Re: [PATCH v2] doc: Add Guix Home documentation.
Date: Fri, 03 Sep 2021 10:21:05 +0300

[Message part 1 (text/plain, inline)]

On 2021-09-01 18:10, Oleg Pykhalov wrote:

> Andrew Tropin <andrew <at> trop.in> writes:
>
>> From 296145ea58bc9c10aa80bc80a24e4f55a87fbef6 Mon Sep 17 00:00:00 2001
>> From: Andrew Tropin <andrew <at> trop.in>
>> Date: Wed, 1 Sep 2021 11:47:04 +0300
>> Subject: [PATCH v2] doc: Add Guix Home documentation.
>>
>> * doc/guix.texi: Add Guix Home documentation.
>> ---
>>  doc/guix.texi                 | 665 ++++++++++++++++++++++++++++++++++
>>  doc/he-config-bare-bones.texi |  24 ++
>>  2 files changed, 689 insertions(+)
>>  create mode 100644 doc/he-config-bare-bones.texi
>
> […]
>
> Moved doc/he-config-bare-bones.texi to doc/he-config-bare-bones.scm
> similar to package-hello.scm mentioned in guix.texi, and added changelog
> for doc/he-config-bare-bones.scm in Git message.
>
> Pushed to wip-guix-home.
>
> Oleg.

Thank you!)

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.