From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 01 05:00:28 2021 Received: (at submit) by debbugs.gnu.org; 1 Sep 2021 09:00:28 +0000 Received: from localhost ([127.0.0.1]:36255 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLM6d-0007hu-Cl for submit@debbugs.gnu.org; Wed, 01 Sep 2021 05:00:28 -0400 Received: from lists.gnu.org ([209.51.188.17]:39828) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLM6Y-0007hi-2K for submit@debbugs.gnu.org; Wed, 01 Sep 2021 05:00:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:51344) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mLM6W-0001gI-AW for guix-patches@gnu.org; Wed, 01 Sep 2021 05:00:21 -0400 Received: from mail-lj1-x230.google.com ([2a00:1450:4864:20::230]:42630) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mLM6S-0006lK-EB for guix-patches@gnu.org; Wed, 01 Sep 2021 05:00:20 -0400 Received: by mail-lj1-x230.google.com with SMTP id h1so3613952ljl.9 for ; Wed, 01 Sep 2021 02:00:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=trop-in.20150623.gappssmtp.com; s=20150623; h=from:to:subject:date:message-id:mime-version; bh=HrU6EIoCc6tnpiTXqiiaswt8RiGROyEBN3GXYAiJDEE=; b=SSrzYUuQ6E/Ll5OKbOFORv6ic7c2/l1P+24UEhUPOcRfRk/8+0eRWYCnxfZ8biVBlw sh8GMgr3HPl/Ya6xjLQSW69Gnx+W0lmPujls7P6UNRDNud7eCA3sS2JnMiPI+HHry39D 3r4woEhyW9jr+86nqwTTCmJNGEw8iL0/KA37bpqLCPszNvkEbRjxXzvit9UQnKwxjPow 5XU0R/+dYozEFtU4WO7E8VMUwdKhbLSiL4AfVSZdakUwZgomMEKWYwNZtOzdhWre6JBB nMcOgFGHUpS2Hp68b7DfGN21Rqo8ktKC7fSBrlO1XXQdwfAmrZo9/h3LcVquJsu0H3xP eKjg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:mime-version; bh=HrU6EIoCc6tnpiTXqiiaswt8RiGROyEBN3GXYAiJDEE=; b=H9Fr0C5BrlJ0wXEgTAaSQxcfFPCQ0oTS7RwgQTM9I+1uFXzvfCqESa4705s68sUJIm FZvjOuuh6jvrbreJ6hp7Z9GV1IJRXF+LydN/j6BOI8+U3i4kg0xkuUJKTuXkOg8PO8JE agA56xR9nnxDqK77E8wRxf60Iah1i5Fy8miM04jwKoiNwz30yLsMnj6xS5kw5Jz+Dtdd /sUWOJ5vwDvFw6qm9FoUma0r+OIIYb/hryB4gd8Nk9FiAs0XCiYP3bI0UjAuISpNIPrD gOtndjKBbE2hPyqaxqv5pOFvKux5xz2VBro9s6xS2CgHcfTSMdTNxkCmrV9zbG2g3LgQ vtDg== X-Gm-Message-State: AOAM531zIHaLIQvkYcYnzQtfXwhcy4nn9puMA00s5C3iqWpzVn1lAyFL P9JMr/h6fS3qYK00ozaLpdfrVF1hI2fpSg== X-Google-Smtp-Source: ABdhPJwN90V++ZTGihF1Bk3nbXp7YCFNPLTNaA320uP4l7e7h8kDXUCD/jDYGO/qX+iOzyYJHl4ZtQ== X-Received: by 2002:a05:651c:1796:: with SMTP id bn22mr29272899ljb.362.1630486811622; Wed, 01 Sep 2021 02:00:11 -0700 (PDT) Received: from localhost ([109.252.93.92]) by smtp.gmail.com with ESMTPSA id i3sm1966490lfj.28.2021.09.01.02.00.10 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Sep 2021 02:00:10 -0700 (PDT) From: Andrew Tropin To: guix-patches@gnu.org Subject: [PATCH] doc: Add Guix Home documentation. Date: Wed, 1 Sep 2021 11:47:04 +0300 Message-ID: <878s0gzn54.fsf@trop.in> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" Received-SPF: none client-ip=2a00:1450:4864:20::230; envelope-from=andrew@trop.in; helo=mail-lj1-x230.google.com X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_NONE=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable * doc/guix.texi: Add Guix Home documentation. * doc/he-config-bare-bones.texi: Add home-environment example configuration. =2D-- 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 h= ome services. There is no section about Gradual Migration to Guix Home and Invoking guix home's subsection about 'guix home import' subcommand yet, th= ey 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 =2D-- 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@* =20 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 machin= e. * Defining Services:: Adding new service definitions. =20 +Home Environment Configuration + +* Invoking guix home:: Instantiating a home environment configura= tion. + Services =20 * Base Services:: Essential system services. @@ -35090,6 +35096,687 @@ system: This service represents PID@tie{}1. @end defvr =20 +@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=E2=80=99s @dfn{home environment}. Packag= es 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=E2=80=99t h= ave 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=3D$HOME/.guix-home +. $HOME_ENVIRONMENT/setup-environment +$HOME_ENVIRONMENT/on-first-login +@end example + +That makes POSIX compliant login shells activate the home environment. +However, in most cases this file won't be read by most modern shells, +because they are run in non POSIX mode by default and have their own +@file{*profile} startup files. For example Bash will prefer +@file{~/.bash_profile} in case it exists and only if it doesn't will it +fallback to @file{~/.profile}. Zsh (if no additional options specified) +will ignore @file{~/.profile}, even if @file{~/.zprofile} doesn't exist. + +To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or +@code{source ~/profile} to the startup file for the login shell. In +case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is +@file{~/.zprofile}. + +@quotation Note +This step is only required if your shell is NOT managed by Guix Home. +Otherwise, everything will be done automatically. +@end quotation + +@node Home Services +@section Home Services +@cindex home services + +A @dfn{home service} is not necessarily something that has a daemon and +is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd +Manual}), in most cases it doesn't. It's a simple building block of +home environment, often declaring a set of packages to be installed in +the home environment profile, a set of config files to be symlinked into +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and +environment variables to be set by a login shell. + +There is a service extension mechanism (@pxref{Service Composition}), +which allows home services to extend other home services and utilize +capabilities they provide, for example: declare mcron jobs +(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home +Service}, declare daemons by extending @ref{Shepherd Home Service}, add +commands, which will be invoked on by the Bash by extending +@ref{Shells Home Services, @code{home-bash-service-type}}. + +The good way to discover avaliable home services is using the +@command{guix home search} command (@pxref{Invoking guix home}). After +the required home services are found, include its module with the +@code{use-modules} form (@pxref{use-modules,, Using Guile Modules, +guile, The GNU Guile Reference Manual}), or the @code{#:use-modules} +directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU +Guile Reference Manual}) and declare a home service using the +@code{service} function, or extend a service type by declaring a new +service with the @code{simple-service} procedure from @code{(gnu +services)}. + +@menu +* Essential Home Services:: Environment variables, packages, on-* scripts. +* Shells: Shells Home Services. POSIX shells, Bash, Zsh. +* Mcron: Mcron Home Service. Scheduled User's Job Execution. +* Shepherd: Shepherd Home Service. Managing User's Daemons. +@end menu +@c In addition to that Home Services can provide + +@node Essential Home Services +@subsection Essential Home Services +There are a few essential services defined in @code{(gnu +home-services)}, they are mostly for internal use and are required to +build a home environment, but some of them will be useful for the end +user. + +@cindex environment variables + +@defvr {Scheme Variable} home-environment-variables-service-type +The service of this type will be instantiated by every home environment +automatically by default, there is no need to define it, but someone may +want to extend it with a list of pairs to set some environment +variables. + +@lisp +(list ("ENV_VAR1" . "value1") + ("ENV_VAR2" . "value2")) +@end lisp + +The easiest way to extend service type, without defining new service +type is to use the @code{simple-service} helper from @code{(gnu +services)}. + +@lisp +(simple-service 'some-useful-env-vars-service + home-environment-variables-service-type + `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst") + ("SHELL" . ,(file-append zsh "/bin/zsh")) + ("USELESS_VAR" . #f) + ("_JAVA_AWT_WM_NONREPARENTING" . #t))) +@end lisp + +If you include such service to you home environment definition, it will +add the following content to the @file{setup-environment} script (which +is expected to be sourced by the login shell): + +@example +export LESSHISTFILE=3D$XDG_CACHE_HOME/.lesshst +export SHELL=3D/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 servic= es +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-default= s? +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-pro= file +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-log= out +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 initializa= tion ++ of POSIX compatible login shells. Can be extended with a list of string= s 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 instal= ls 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 pe= rfomance ++ 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/channel= s.scm -- \ + home reconfigure \ + /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configurat= ion.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 =20 @node Documentation @chapter Documentation =2D-=20 2.33.0 --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmEvQRcACgkQIgjSCVjB 3rDczw/9HhIWDQw4UgXabY02LFLzvpEc/hBaQ7yCfXytleLalfaRpuh0bNOH5o6K +oRDwKPoZkajBIqRMlbRYI3p0zO1vaEUJYLpPLgZcYSPkdBqEa5GJxZIadkTfak9 yXGPoOqcv2MJr31GFJRDOkP3E+PCC2ZyD9v+ouSUUr8B13TVLxcOmYDSC9cxIl9q jdXzJahrhqWNhuzeCWbw3z7lMUfbiHsWpK0GIE+AKTamkqXK+HifDMKZ8tXH8mRe PmuTNSe2Y/X8HXwvnrkWIXTRW0ON3LASiGSYqRQFvrt5gu1yIBr/01kGu/CdvDmN mtrVShUvyRRnYlhBmko++fkN1ZxcU+tb/CzDi1RMS782S9i7L+zBDsaj/WrX9oOz RDa+uTPrfwcoQbnAwyfnuuBpVXqPEHaR02ok6vA8ww4ohS5AIDXVg2K/g8b8jb/l aFi5kORXhXxYng71pzagfdkz+eNHmpnK5BZv3QWCh4K778tzTNFkoWSeZqROR50C oHvpuXJdhi6vYk8uMHvG5279yfNyCSdOQ5xxClZlaHVaMUc2asnMu9+lFVSMbwSy yCQqq1XkEXcFVhyspmEopkEGdnCQnJYBVzZOdNVxgOP1AsZEZ5IR+AgBNUP6l4++ A5K1YGnuhwD41KnoNFVwIElIX9XjknFJSav2xVqqDNtFjJKBCnY= =5Az7 -----END PGP SIGNATURE----- --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 01 06:12:28 2021 Received: (at 50313) by debbugs.gnu.org; 1 Sep 2021 10:12:28 +0000 Received: from localhost ([127.0.0.1]:36427 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLNEK-0001GT-0X for submit@debbugs.gnu.org; Wed, 01 Sep 2021 06:12:28 -0400 Received: from mail-lj1-f181.google.com ([209.85.208.181]:38907) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLNEH-0001G7-Ew for 50313@debbugs.gnu.org; Wed, 01 Sep 2021 06:12:26 -0400 Received: by mail-lj1-f181.google.com with SMTP id g14so3958082ljk.5 for <50313@debbugs.gnu.org>; Wed, 01 Sep 2021 03:12:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=3VexNR/KLK/EJRZG0B3P5sJFoV1jREyTXsEhoMDjvcs=; b=sn8w5Yc3H9yUvieJD9slpIymt2AvXZQD7VnoPRKFXJA6SisjFt904sz4rYesyTLWsM Cuu/36B6TUMufk+pJMSxGvtiQNfyS6Kc4F2dcDVk5tLMnqhbWhoquVUSBzChJdu1tZip B0G9X+R7S14nzm0UBNSbf2TRCAvl1xFXGZpQrL4sYHwcCA1aGo2MmGXPrOGm9np8L4Ck 9k/WVCwgYhK8EGs8Y5s3F6xBznwHAngwwW/Wtl4RJNrFoOpweyZHzjxQIMJB+nKoMVvS 7PbuWOdq9l64YSxOZ7kTJm8RCpJbEjpSxtEF80P9GGktseQ/fRsR0BO1oIzvcf2IB8HH ToNQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=3VexNR/KLK/EJRZG0B3P5sJFoV1jREyTXsEhoMDjvcs=; b=cTyXWZFGgKh8z0wxRCi81CrD3Y2ILHYuwWtB3r6fq/F8IPpfUnEzdR3hg0KNjy10O2 f5hUdpxdtKtAXbKF/KAqW1WeqjIjE9xre4IrXOTBbZimLw4pIlsYIO8UQb31NRksYfSo JUx8Vx57+3+RLRMWb/JS7p+LvAM16GGrnE6UrYcWJTsxqgn+4enqQzFGmCYUr2bvYUUg I0fFNgM6vtcN8nusDooVgOWSQTcaUQ51xxa8J6COPid2Wk9mjYGFoXfPHqfM6ul93327 RmlQdWlKS/dLV9oy47WEN6lVmwky+SSNNUUOtRjplnSLneATArYRagHcG6mwXV5fmqtD pQOw== X-Gm-Message-State: AOAM532h3oXrJZ572rJ8CclKa46cSKNCFNwJHz0OOm9yWDyeGgc4b7dk YCdl3vjRamWCBv832aKTWupbm5oMXS4= X-Google-Smtp-Source: ABdhPJwpgjKNBL0XiANPWUrigL+lEcEMKfqyakVuGcLmGdkedG5lX3mdHHFzquB6cANh3UZD/SH6aw== X-Received: by 2002:a2e:1556:: with SMTP id 22mr28507352ljv.253.1630491138988; Wed, 01 Sep 2021 03:12:18 -0700 (PDT) Received: from guixsd ([88.201.161.72]) by smtp.gmail.com with ESMTPSA id m19sm1987674lfl.294.2021.09.01.03.12.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Sep 2021 03:12:18 -0700 (PDT) From: Oleg Pykhalov To: Andrew Tropin Subject: Re: [bug#50313] [PATCH] doc: Add Guix Home documentation. References: <878s0gzn54.fsf@trop.in> Date: Wed, 01 Sep 2021 13:12:15 +0300 In-Reply-To: <878s0gzn54.fsf@trop.in> (Andrew Tropin's message of "Wed, 1 Sep 2021 11:47:04 +0300") Message-ID: <874kb4siyo.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 50313 Cc: 50313@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain Hi Andrew, doc/he-config-bare-bones.texi is missing. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJIBAEBCgAyFiEEcjhxI46s62NFSFhXFn+OpQAa+pwFAmEvUf8UHGdvLndpZ3Vz dEBnbWFpbC5jb20ACgkQFn+OpQAa+pwwjA/+J3xu0eg1LdHgCtN0veLKFwuG9rmk shEAwOJFs4w9o+P4ZE553s/olUsqFWzF0zITOwXTqIsj8Jzq9VVLfhFveP+fgNf2 1yffdZFeYMLybodrKqv+IFF1YCGf2gZGeljkokvy2ILjdZBvLMi/ov7Vh4O2fzcL Y6kQoWx/xiSAe8TFttFTQDtW+MGVhfFiYFQBVJ1aupe3+f6LspqP+6N7y3VGnhVb QO3h/z9QHS4vSq8fN6etP/uQl8oW1ZGRIXkp5+OqVddc9AvpligmlAbLeAXzqZwD sYZBjr+NNwVPcK+vRmNUXQHFdRtDloOELg8alLWWrKBDWzjOdGItK/ZNkZMhKrHC 1U0epvLYR4qP0SwzoCdJqCd8DMiGM+BIUGlLwVGSRmKBdL09V19HUEY6fZg6VDdq xuj7yFCk8M5x8B0IUjvhbWY8FLwQf9wfyQ40bQVPHFzf/ftZ4H+Ssuf/OTE8nuWn 9Oqs5XJ8AkWrnrhaRZGeUMeLRK9uUazoSS9ZyE9AHCd7WAQe++LSPMF8mtxK081L 6xdGHj1IjI+lrG1QKt9t1gnnbBampQRehXClHWR/KbQyBxGet80jj0uNQCDGwITr Obra3e0K8En3rS+l5NkGk7Ri/wlJk5lCg5Mh30MEJcKwf5ZXukdzpIfl72NNzR1I NwY3exukzD4v+eI= =7va3 -----END PGP SIGNATURE----- --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 01 07:57:50 2021 Received: (at 50313) by debbugs.gnu.org; 1 Sep 2021 11:57:50 +0000 Received: from localhost ([127.0.0.1]:36515 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLOsH-0001xi-35 for submit@debbugs.gnu.org; Wed, 01 Sep 2021 07:57:50 -0400 Received: from h87-96-130-155.cust.a3fiber.se ([87.96.130.155]:58988 helo=mail.yoctocell.xyz) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLOsD-0001xO-Sz for 50313@debbugs.gnu.org; Wed, 01 Sep 2021 07:57:47 -0400 From: Xinglu Chen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=yoctocell.xyz; s=mail; t=1630497455; bh=qGDUorSzvuKO2XFnnLYcEItMX04zzKlP0QYFdZEKwLM=; h=From:To:Subject:In-Reply-To:References:Date; b=AubRFvxS5d3wWBsyqV8tg8v1PmI1G9X4VD1fqZkXu5477RDtHZHjO04qpkl5QrSti +A2AUGA4o8kC9MEXRmNIlMK4GzQuR7VmBBtGZ5H1YqyLjpC0coHnDcbVePAnnO8ORE kGajhOcoZxAwBezmvkgsTU76ho0kxmbeV3kut+HE= To: Andrew Tropin , 50313@debbugs.gnu.org Subject: Re: [bug#50313] [PATCH] doc: Add Guix Home documentation. In-Reply-To: <878s0gzn54.fsf@trop.in> References: <878s0gzn54.fsf@trop.in> Date: Wed, 01 Sep 2021 13:57:32 +0200 Message-ID: <878s0gld8z.fsf@yoctocell.xyz> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" X-Spam-Score: 2.9 (++) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: 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 [...] Content analysis details: (2.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_PASS SPF: sender matches SPF record 2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs [URI: yoctocell.xyz (xyz)] 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.5 FROM_SUSPICIOUS_NTLD From abused NTLD 0.4 RDNS_DYNAMIC Delivered to internal network by host with dynamic-looking rDNS 0.0 PDS_RDNS_DYNAMIC_FP RDNS_DYNAMIC with FP steps X-Debbugs-Envelope-To: 50313 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 2.9 (++) X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: 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 [...] Content analysis details: (2.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_PASS SPF: sender matches SPF record 2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs [URI: yoctocell.xyz (xyz)] 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.5 FROM_SUSPICIOUS_NTLD From abused NTLD 0.4 RDNS_DYNAMIC Delivered to internal network by host with dynamic-looking rDNS 1.0 BULK_RE_SUSP_NTLD Precedence bulk and RE: from a suspicious TLD -1.0 MAILING_LIST_MULTI Multiple indicators imply a widely-seen list manager 0.0 PDS_RDNS_DYNAMIC_FP RDNS_DYNAMIC with FP steps --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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 configurati= on. > --- > Reread and updated documentation for Guix Home to reflect latest changes, > still a subject for review and proofreading. Combined all changes into o= ne > 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@* >=20=20 > 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 mach= ine. > * Defining Services:: Adding new service definitions. >=20=20 > +Home Environment Configuration > + > +* Invoking guix home:: Instantiating a home environment configu= ration. > + > Services >=20=20 > * Base Services:: Essential system services. > @@ -35090,6 +35096,687 @@ system: > This service represents PID@tie{}1. > @end defvr >=20=20 > +@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. =E2=80=9Cusers's home=E2=80=9D sounds kind of vague; maybe =E2=80=9Cuser's = dotfiles and packages=E2=80=9D. > +System and foreign distros and allows users to declare all the packages Maybe =E2=80=9Cpackages and services=E2=80=9D instead of just =E2=80=9Cpack= ages=E2=80=9D? > +that should be installed and configured for the user. After that, such It=E2=80=99s not super clear what =E2=80=9CAfter that=E2=80=9D 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 =E2=80=9Chome environment=E2=80=9D and =E2= =80=9Chome configuration=E2=80=9D? > +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, =E2=80=9CThe users's home environment=E2=80=9D > +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=E2=80=99s @dfn{home environment}. Pack= ages 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 =E2=80=9C(@file{~/.config} by default)=E2=80=9D instead of =E2= =80=9C(default value is @file{~/.config})=E2=80=9D? > +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. =E2=80=9Cand other benifits=E2=80=9D doesn=E2=80=99t really fit here; I sug= gest 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 =E2=80=9C---=E2=80=9D instead of putting a period an= d 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=E2=80=99t= 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 =E2=80=9Ca=E2=80=9D > +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 =E2=80=9Ca=E2=80=9D :-) > +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 =E2=80=9Cthe=E2=80=9D > +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=E2=80=99t 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. =20=20 > +@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 =E2=80=9CThe first script that needs to be sourced is @file{setup-environme= nt}=E2=80=9D > +necessary environment variables (including variables declared by user) ^ Missing =E2=80=9Cthe=E2=80=9D > +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=3D$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 =E2=80=9Care=E2=80=9D > +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 =E2=80=9Cthe=E2=80=9D > +the home environment profile, a set of config files to be symlinked into > +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and ^ =E2=80=9C(@file{~/.config} by default)=E2=80=9D Missing comma. > +environment variables to be set by a login shell. > + > +There is a service extension mechanism (@pxref{Service Composition}), > +which allows home services to extend other home services and utilize > +capabilities they provide, for example: declare mcron jobs > +(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home > +Service}, declare daemons by extending @ref{Shepherd Home Service}, add > +commands, which will be invoked on by the Bash by extending > +@ref{Shells Home Services, @code{home-bash-service-type}}. I would use semicolons instead of commas for separating the clauses. There is a service extension mechanism (@pxref{Service Composition}) which allows home services to extend other home services and utilize capabilities they provide; for example: declare mcron jobs (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home Service}; declare daemons by extending @ref{Shepherd Home Service}; add commands, which will be invoked on by the Bash by extending @ref{Shells Home Services, @code{home-bash-service-type}}. > +The good way to discover avaliable home services is using the I would =E2=80=9CA=E2=80=9D instead of =E2=80=9CThe=E2=80=9D, 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-* scrip= ts. > +* 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 =E2=80=9Ca=E2=80=9D > +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=3D$XDG_CACHE_HOME/.lesshst > +export SHELL=3D/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/z= sh > +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. =E2=80=9Cthis namespace contains the definition of the @code{zsh} package, = =E2=80=A6=E2=80=9D > +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 =E2=80=98car=E2=80=99/=E2=80=98cdr=E2=80=99 instead of =E2=80=98k= ey=E2=80=99/=E2=80=98value=E2=80=99? At first I though that =E2=80=9Cthe value can be a string, =E2=80=A6=E2=80=9D was referring to the= previous clause, which obviously doesn=E2=80=99t 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. =E2=80=9Cleads to the activation of the home environment.=E2=80=9D > +@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 serv= ices > +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 =E2=80=98generate-documenation=E2=80=99 procedure (see commit ad945029a2dbd1fb741be573f13e42c061e72d0f). > + > +@deftypevr {@code{home-shell-profile-configuration} parameter} text-conf= ig 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-defau= lts? > +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-p= rofile > +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-l= ogout > +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=E2=80=99t 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 initiali= zation > ++ of POSIX compatible login shells. Can be extended with a list of stri= ngs 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 inst= alls 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, manua= l 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 =E2=80=9Cthe=E2=80=9D > +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! :-) --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmEvaqwVHHB1YmxpY0B5 b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5QIQQAJYPL4FOaapKuBBIjW4q26iX9Pyt 1Rpq8UkrTiE/NWxKRom1TF8DOMiw3K/o+RZF1IJ8E3nMZwyeCls9SkLy8T55yNZD Ay0G/DR3Bj34PPjQKAHTjDOEProaxUzYJ3VfVpaVACuEU4DkjOAy6KrM4ablLO/J MegUXLWAXH+Kxw0omvayZ0tWmbMysle1NPnbJgFFGR36o9vn3DtMIqZp5RUBxjVo 8Y48N1ytOPA1HTDKNUMzT6wKHYcig+18grYyhBrdkTvEqFNBPx3NjT2Q6/FLjZW5 4CL6+Lylht2U6FvMBus9hRVs3rPiwmMq1G408KJXI0OTl47mcZkqz10XUcrXxPCw G8KLKCAUQYU2cAjyUTRrDNaAMpJb7l9PueZT+vzAOiX0OPm+bGAr1RNge7hViHEc yRZW3qQS0PxETn1p4gaa2SJAGljWodf+6FXjMXQ5Jl+OVYmzpzvMe2DMYf1EztD6 kjPWJA+DlZLVAmPxzyZGxsdL2wuOofB0FBVAD2XhnuH0jLrITvXA8JtHg2FscCcR hOsGb2Qs3v1ZDjIqr4YoK3oiQi13cDSXbu73m+iB963JScq/UEzpruVUaMwmyifG msZHEsju15PGrwBa1zDes6lUvLis+pGjFG+CvuDBIqHc/69FnJSMH+F3ehUbMgzj qbjMjDpMyqHpkJrg =bLa0 -----END PGP SIGNATURE----- --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 01 09:28:57 2021 Received: (at 50313) by debbugs.gnu.org; 1 Sep 2021 13:28:57 +0000 Received: from localhost ([127.0.0.1]:36677 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLQIR-0006gW-RJ for submit@debbugs.gnu.org; Wed, 01 Sep 2021 09:28:57 -0400 Received: from mail-lf1-f51.google.com ([209.85.167.51]:36624) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLQIO-0006gH-9T for 50313@debbugs.gnu.org; Wed, 01 Sep 2021 09:28:54 -0400 Received: by mail-lf1-f51.google.com with SMTP id c8so6437226lfi.3 for <50313@debbugs.gnu.org>; Wed, 01 Sep 2021 06:28:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=trop-in.20150623.gappssmtp.com; s=20150623; h=from:to:subject:in-reply-to:references:date:message-id:mime-version; bh=uIjfT8+IqkmkIYXIkwrTcq5SiDTVqiB36/RL6ulnT3o=; b=VMKr7f7661tgH4V02w1898lCYxGWa49CDK7olqlUc1bE71iOdhAPYEhEwURk5pH60B zxIlkP3FMbjHzOYuQomgCW2UZ0Wty6OaLWma8BOUqtPfjS94oVK70rvHiuC6il0U07Cz mNHuNEnmZjva7nhoVVbNKfDPWkYLYcqKYOJ2nrgCIGAfDib2ssq/1RSanrkXRXkSIAbS FZkkO0fXN0FpHczNRsZVkJvuVeFjyPy4xpKSvMG+Ic1I55YzC9r1+FiPRNReyIK/ZD8l SYGiir9cE9ePDzoewDe2C6pzt1t32pgI+daxF5997NKI3G0gG+EIPxX/1KXfEdj1yxy4 fhPg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:in-reply-to:references:date :message-id:mime-version; bh=uIjfT8+IqkmkIYXIkwrTcq5SiDTVqiB36/RL6ulnT3o=; b=UrMaV+XOCtJkarul4fFvochbQKuOs1fdWLSGRZTXMTNWIYVDKecnWrZ9oaEXej3EAN d3kfMrQnnlGsF6DbOt0ME2njpaTzN9cazv3PnWIobDmbkYA2U9kj+YF4zTUo7iPi12bh jEOXlxfAIsZ7p49JFr4R4KlmfTADapF3IQVLuBVtBvX1tPLZX0dznu26zzhsy3WtR12y 7rHrBQBVxrXyE+RxTjsVgG+V3Jg9qZqBOdqE765Z/dY0e1X3mOaxSxsR9S2+zOYD6FwA sHzfaY6TpGg9iWcGJ+Td6vOPah4c3Pv/eWb82ulCezx9+dOHdUWOObNnT01L4BI/baIq e6iA== X-Gm-Message-State: AOAM531bHv6Ag7cqU3N9qVQvQ0sgj2QaLWSeEL1lwPURusT8DO1H/n8Q T1inheLp7G9QP+spYUZzl1Ihi4vi/wzRuA== X-Google-Smtp-Source: ABdhPJw3pBobO+JrVDEY2JCRshiqG9iezdEbaByIOcijNN3H4iQ3gISvyeAxp0hKgyQUUHmzU3xgwQ== X-Received: by 2002:a05:6512:1112:: with SMTP id l18mr19407334lfg.402.1630502925189; Wed, 01 Sep 2021 06:28:45 -0700 (PDT) Received: from localhost ([109.252.93.92]) by smtp.gmail.com with ESMTPSA id v14sm1309699lfd.225.2021.09.01.06.28.43 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Sep 2021 06:28:44 -0700 (PDT) From: Andrew Tropin To: Xinglu Chen , 50313@debbugs.gnu.org Subject: Re: [bug#50313] [PATCH] doc: Add Guix Home documentation. In-Reply-To: <878s0gld8z.fsf@yoctocell.xyz> References: <878s0gzn54.fsf@trop.in> <878s0gld8z.fsf@yoctocell.xyz> Date: Wed, 01 Sep 2021 16:28:40 +0300 Message-ID: <87bl5cqvav.fsf@trop.in> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 50313 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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 configurat= ion. >> --- >> 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-ho= me >> yet) contains only placeholders, will be updated with patches for relate= d 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@* >>=20=20 >> 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 mac= hine. >> * Defining Services:: Adding new service definitions. >>=20=20 >> +Home Environment Configuration >> + >> +* Invoking guix home:: Instantiating a home environment config= uration. >> + >> Services >>=20=20 >> * Base Services:: Essential system services. >> @@ -35090,6 +35096,687 @@ system: >> This service represents PID@tie{}1. >> @end defvr >>=20=20 >> +@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. > > =E2=80=9Cusers's home=E2=80=9D sounds kind of vague; maybe =E2=80=9Cuser'= s dotfiles and > packages=E2=80=9D. > Done. > >> +System and foreign distros and allows users to declare all the packages > > Maybe =E2=80=9Cpackages and services=E2=80=9D instead of just =E2=80=9Cpa= ckages=E2=80=9D? > Done. > >> +that should be installed and configured for the user. After that, such > > It=E2=80=99s not super clear what =E2=80=9CAfter that=E2=80=9D is referri= ng 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 =E2=80=9Chome environment=E2=80=9D and =E2= =80=9Chome > configuration=E2=80=9D? > 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, > > =E2=80=9CThe users's home environment=E2=80=9D > 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=E2=80=99s @dfn{home environment}. Pac= kages 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 =E2=80=9C(@file{~/.config} by default)=E2=80=9D instead of =E2= =80=9C(default value is > @file{~/.config})=E2=80=9D? > 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. > > =E2=80=9Cand other benifits=E2=80=9D doesn=E2=80=99t really fit here; I s= uggest 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 =E2=80=9C---=E2=80=9D 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=E2=80=99= 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 =E2=80=9Ca=E2=80=9D > 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 =E2=80=9Ca=E2=80=9D :-) > 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 =E2=80=9Cthe=E2=80=9D > 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. >=20 > 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=E2=80=99t 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. >=20=20=20 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 > > =E2=80=9CThe first script that needs to be sourced is @file{setup-environ= ment}=E2=80=9D > Done. > >> +necessary environment variables (including variables declared by user) > ^ > Missing =E2=80=9Cthe=E2=80=9D > 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=3D$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 =E2=80=9Care=E2=80=9D > 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 =E2=80=9Cthe=E2=80=9D > Done. > >> +the home environment profile, a set of config files to be symlinked into >> +@env{XDG_CONFIG_HOME} (default value is @file{~/.config}) and > ^ > =E2=80=9C(@file{~/.config} by default)=E2=80=9D > > Missing comma. > Done. > >> +environment variables to be set by a login shell. >> + >> +There is a service extension mechanism (@pxref{Service Composition}), >> +which allows home services to extend other home services and utilize >> +capabilities they provide, for example: declare mcron jobs >> +(@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home >> +Service}, declare daemons by extending @ref{Shepherd Home Service}, add >> +commands, which will be invoked on by the Bash by extending >> +@ref{Shells Home Services, @code{home-bash-service-type}}. > > I would use semicolons instead of commas for separating the clauses. > > There is a service extension mechanism (@pxref{Service Composition}) > which allows home services to extend other home services and utilize > capabilities they provide; for example: declare mcron jobs > (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home > Service}; declare daemons by extending @ref{Shepherd Home Service}; add > commands, which will be invoked on by the Bash by extending > @ref{Shells Home Services, @code{home-bash-service-type}}. > Picked your version > >> +The good way to discover avaliable home services is using the > > I would =E2=80=9CA=E2=80=9D instead of =E2=80=9CThe=E2=80=9D, which sound= s 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-* scri= pts. >> +* 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 =E2=80=9Ca=E2=80=9D > 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=3D$XDG_CACHE_HOME/.lesshst >> +export SHELL=3D/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. > > =E2=80=9Cthis namespace contains the definition of the @code{zsh} package= , =E2=80=A6=E2=80=9D > 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 =E2=80=98car=E2=80=99/=E2=80=98cdr=E2=80=99 instead of =E2=80= =98key=E2=80=99/=E2=80=98value=E2=80=99? At first I though that > =E2=80=9Cthe value can be a string, =E2=80=A6=E2=80=9D was referring to t= he previous clause, > which obviously doesn=E2=80=99t 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. > > =E2=80=9Cleads to the activation of the home environment.=E2=80=9D > 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 ser= vices >> +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 > =E2=80=98generate-documenation=E2=80=99 procedure (see commit > ad945029a2dbd1fb741be573f13e42c061e72d0f). > Done. > >> + >> +@deftypevr {@code{home-shell-profile-configuration} parameter} text-con= fig 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-defa= ults? >> +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 zprofi= le >> +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=E2=80=99t 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 initial= ization >> ++ of POSIX compatible login shells. Can be extended with a list of str= ings 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 ins= talls 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 `zs= h' and >> ++ sets reasonable default values for some plugin's variables to improve= perfomance >> ++ and adjust behavior: `(history completion)' is set for strategy, manu= al 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 =E2=80=9Cthe=E2=80=9D > 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 n= ot > > 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. >=20 > Excited to see Guix Home get merged soon! :-) (: Thank you for all the help) --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmEvgAgACgkQIgjSCVjB 3rDjORAAhVrG8Pqt7EeiNzYIc8GCV699Ez2B0sjG6KqlfK91SV+dk5PxRnjzRzbQ LdCKCg3Rujw3mFec7hGxEYn/2pHbaDMU2wetLvA3XDQfkxp+WhkADP5m2QSL1HY/ Y1VLATKzB06AGzql/M5ZTBex5fE1ocDldaCIlDv6oscMDt284W+DubMrtkK2XdIW kz2HL4jM+fk+4dwQFFbys0KxPw4+qHgHIxYdZBwM9ZKukZKGRI2Uj1i4HPTa7yK8 UA5mg87B+B2PtH/YyxGWmkI4QDzwzCi6j3g3pt6DlLJnHP2O+l+HGC5x+vi8Aerf od233lzsbYSWX1MUQLQ3aK48DCaBoQphEkB0tVn8P1b+LXHHD0ho5Enivq6ft1mP hbvTz4qHEHqU+3n0LWhnWDiSrrvz+0Qi6kCELXbF20puKzZ1BAPsQp2R+a2otYbz yOSrzlxPRn55B5pkGsElteyx3AHf4Fs87h4IEwVxjYXShZZA1HcQhh5T5qAhEwYo 6IqiNqMlW5laIHRiD0mhx5qwsoRzOICCPISF6T8eIQwCTrZCBq4JDVP5u1VoH6uC h8HhZqh7X4xSJxzuebBiTRjzsDUW6b7Z1uFU7Nqn8SdorTF5XRTJCgKJcBWYDxw6 eK8hQy9pEMoltPVHu/9/aC0a0UU4rESfFjWgXFffdtB9Cimh/2k= =6SJj -----END PGP SIGNATURE----- --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 01 09:32:46 2021 Received: (at 50313) by debbugs.gnu.org; 1 Sep 2021 13:32:46 +0000 Received: from localhost ([127.0.0.1]:36686 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLQM4-0006ny-BM for submit@debbugs.gnu.org; Wed, 01 Sep 2021 09:32:45 -0400 Received: from mail-lj1-f176.google.com ([209.85.208.176]:41898) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLQLx-0006nf-Ku for 50313@debbugs.gnu.org; Wed, 01 Sep 2021 09:32:35 -0400 Received: by mail-lj1-f176.google.com with SMTP id m4so4932528ljq.8 for <50313@debbugs.gnu.org>; Wed, 01 Sep 2021 06:32:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=trop-in.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:in-reply-to:references:date:message-id :mime-version; bh=PSvrGo7xc02EfNoGcjBHaL6i9TmTxLO71n6nNuyEbCM=; b=lQ/70V7LCbpo90Z3VqivHEleA69ib85ZUQfLbxznLxZNegZIRcapRU3Aa83TV4f8vz tWnRou9JQnYw/V/zJMqP8afJX/n1g9rQ5bmFzIHkLOVlXyvXjlqXi0tpHHrasGXCp1Np e7d9PqS/ziUeCFiZjXWHClebzeTbzCoS7WxlmIdpSAs60BpnrVQpgeFHQwbI08Ix7Mgq kuI8+uwCnABXCAqxCP9+JvH+y0S1D1Ma0o5wKEjYE2L1u9PbKbYA88B8umZgNrf2xXsb qD8MYrDAA+T3Cu442YQIxo2yU2nTzPiYhrnuqJ7fDPGrjYznU9vfa/0C1/cSb0T/niTX vwMg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references:date :message-id:mime-version; bh=PSvrGo7xc02EfNoGcjBHaL6i9TmTxLO71n6nNuyEbCM=; b=e3A2u/UBQ93/V4+6ob1RilbZ3MgUcikydf6HLwK0GsQFti7W4HSQo3bi39DkgGJDBn kY1lX75AGEyRkGq9mJJcWNgBOv/Hu1PH1YPYLk79ya5JPXJ8xkeFQ0fePpm2AL3z8FU5 N4I6FUuvVQ0ajQfUMF7NXGlm1nKzUhtr6UETGPUM/jqIoSmafm+jcJ3XTfPFVphsK1aP zIaytNTFiRaIbhzm4fEnl/7KoRlQqzEQ12ODPZwmiNIf6FfmFcbn4/nOgBw5roH/goOk 4aobNO+FyWweQbDg6PcP8fIqUAxtnYxLyz+XaFIfjwO1lKhJ6qkRfA6/Ol75Vi0/wK0D ofNA== X-Gm-Message-State: AOAM530RZCyTJFEW6EPMro6NxreCbnbEscmCfwPYkWZ7qnxfihVsHjRB lOkKRoHOMCmRQZaolQtp2T3Haw== X-Google-Smtp-Source: ABdhPJxKx38gr8F6Fwn0FqMNuiAr5k8nA9w1Z0ZYFhbqLuRd+UDeQplE7iQjRqEHQAPXABl+4IUFdQ== X-Received: by 2002:a05:651c:339:: with SMTP id b25mr29692189ljp.312.1630503147224; Wed, 01 Sep 2021 06:32:27 -0700 (PDT) Received: from localhost ([109.252.93.92]) by smtp.gmail.com with ESMTPSA id h15sm2554814ljc.96.2021.09.01.06.32.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Sep 2021 06:32:26 -0700 (PDT) From: Andrew Tropin To: Oleg Pykhalov Subject: [PATCH v2] doc: Add Guix Home documentation. In-Reply-To: <874kb4siyo.fsf@gmail.com> References: <878s0gzn54.fsf@trop.in> <874kb4siyo.fsf@gmail.com> Date: Wed, 01 Sep 2021 16:32:23 +0300 Message-ID: <878s0gqv4o.fsf@trop.in> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="==-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 50313 Cc: 50313@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --==-=-= Content-Type: multipart/mixed; boundary="=-=-=" --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: inline; filename=v2-0001-doc-Add-Guix-Home-documentation.patch Content-Transfer-Encoding: quoted-printable From=20296145ea58bc9c10aa80bc80a24e4f55a87fbef6 Mon Sep 17 00:00:00 2001 From: Andrew Tropin Date: Wed, 1 Sep 2021 11:47:04 +0300 Subject: [PATCH v2] doc: Add Guix Home documentation. * doc/guix.texi: Add Guix Home documentation. =2D-- 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 =2D-- 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@* =20 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 machin= e. * Defining Services:: Adding new service definitions. =20 +Home Environment Configuration + +* Invoking guix home:: Instantiating a home environment configura= tion. + Services =20 * Base Services:: Essential system services. @@ -35090,6 +35096,665 @@ system: This service represents PID@tie{}1. @end defvr =20 +@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=E2=80=99s @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=E2=80=99t h= ave 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=3D$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@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=3D$XDG_CACHE_HOME/.lesshst +export SHELL=3D/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 ext= end +@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 servic= es +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 initializa= tion ++ of POSIX compatible login shells. Can be extended with a list of string= s 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 instal= ls 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 pe= rfomance ++ 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/channel= s.scm -- \ + home reconfigure \ + /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configurat= ion.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 =20 @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 =2D-- /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=3D$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.con= f"))))))) + =2D-=20 2.33.0 --=-=-=-- --==-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmEvgOcACgkQIgjSCVjB 3rAPFA//a7bRhsAXzZJNEcouEoXE2WBJcV4258JUTgy6maxzsnKo/jUN4Q+L7391 ELZhkZ6r6uL1IYFNFlfVPtNRjXdXteVPmc/x3IaZKalFODtJX7zE0tQCjuTAKvsz SEeWr6v2WkaW9fNGg0s0NKSMwgg2QcZwdB1r2ha9g4NeYYiFgHOELylpTMMoq5+N oLxbuBZZaEwJfTn7EgcQRlUBxxUi7CrwMWkiivRfvpPp9v2KgK5LkxTcw79Ksvg1 8qR9azjAezwdpPPlnSfwvSX27xsYVbaiDt/wa/p5HQ3sLX/jy78SXInCnp5FK4tb l1i7qMuOzKmntJnIgouYBIyVqddBkfd7QJsQo0hWytcotu++KxLgsMnQOuce1EpF v075czIs2NVDqn+ZbRLqJln4aaxxMvQA7McDWCVR+VW21Bm/01FGDTyptw4uQbAv TiFLX6zAaVzLEVAZPtrHlbHyXV5b26twnizMrXaCV3X9M4Irt8+fW88Gu2AvJCtl THm/LRn6IzBZgHLKGqlDCbVkgNbEnD+vJ6uv7rs2TzoIBcocYCp5Vel4B+CVjEMh VjluvC3CMwjAn6aUe69nyH3gbUy5G6Zi4g/3+DSTB/HafV/HoY5gUAgJCpt/6A1P M9Kk4sRNragODPH404ag6kH1x3r8xm2G411IIop4usgMnUPCct4= =DK3h -----END PGP SIGNATURE----- --==-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Wed Sep 01 11:10:23 2021 Received: (at 50313-done) by debbugs.gnu.org; 1 Sep 2021 15:10:23 +0000 Received: from localhost ([127.0.0.1]:38824 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLRsc-0005lc-O2 for submit@debbugs.gnu.org; Wed, 01 Sep 2021 11:10:22 -0400 Received: from mail-lj1-f174.google.com ([209.85.208.174]:38873) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mLRsb-0005lL-PB for 50313-done@debbugs.gnu.org; Wed, 01 Sep 2021 11:10:22 -0400 Received: by mail-lj1-f174.google.com with SMTP id g14so5532270ljk.5 for <50313-done@debbugs.gnu.org>; Wed, 01 Sep 2021 08:10:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=GhbHszm6wXr1+1oygkqDlrzmL8NCHNJUIRggSc8oFVg=; b=SmG2u9JexXOrgWDYDMvXgy27zhr3hg3xXjPCB1HnH1Bc4LYdJ3lZ5HQ1TgoAIjdur7 9SmrnrKFbJBiaUqfrQ+OBjyUI2Vy4haFsibbtX+QmsJrZ7yuxXC+JPdM671riXDifupg YtoDeFe8M6HF6IsdhF20Dn3NCTTMJYYm4Ugz+TQIABCYVVmidgaLQGgjBuQNWEo3nuom Lwan7dmwracp7UoRijx0Ut66PPuRHBH5rYw2fQ1m+3qwFpqCEVxS9yZbXyRtxJ415iED v3ymz8eCKwCOHKCZxQcHTioJi4Hp2VSvh20+OScgOI07rlPv0DDhQrHJdajfPN3hUfJ2 IOOw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=GhbHszm6wXr1+1oygkqDlrzmL8NCHNJUIRggSc8oFVg=; b=YnOb2b4VBKa4xMmEgH1NUh11lzbguBTQV7KkCC5P83qw9xz7EPeGa5MiM9KUDqufSU wU9Hnh7pRv/jMNexHfykkD1wheLr92++gRnzrGfxui7mwwCkOwb0gFPIjQXZK7uMtkLB x3+3aqVbggx+SrACl/sQml2gE1Bi+vWwSXkstb56qA3jQCqVMkS0a1T3XFS/I2RbcIUb jvkmkpJtjRA/5v2ZiqHnoeJsi9/kn44x7FupRs8e/vNG2yDWwM7ywCaDtg7//Vwlhvtl +AzFOz2UZyXbJ4w8477snFoJwfDHC5maL+FwyFDG49q1bRDDnKKs/B+/38pHZLAXOc4z HQZg== X-Gm-Message-State: AOAM532IpfDGwQhTByVp8jMnVidqbbx+Ef3votcTbmqL9Q+PmmD+zlVy oxb5lvZ4J+nqJ7O/XVdtJ7L0oiniAwY= X-Google-Smtp-Source: ABdhPJx/XMb7MAG7XzWY9/QgjoMdRPD7V21XT05DyOUNzfMoZzrZaqBNjjHbrM/AQWf7LPa2hrlUPg== X-Received: by 2002:a2e:350e:: with SMTP id z14mr79309ljz.183.1630509015412; Wed, 01 Sep 2021 08:10:15 -0700 (PDT) Received: from guixsd ([88.201.161.72]) by smtp.gmail.com with ESMTPSA id q7sm13120ljg.137.2021.09.01.08.10.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Sep 2021 08:10:14 -0700 (PDT) From: Oleg Pykhalov To: Andrew Tropin Subject: Re: [PATCH v2] doc: Add Guix Home documentation. References: <878s0gzn54.fsf@trop.in> <874kb4siyo.fsf@gmail.com> <878s0gqv4o.fsf@trop.in> Date: Wed, 01 Sep 2021 18:10:11 +0300 In-Reply-To: <878s0gqv4o.fsf@trop.in> (Andrew Tropin's message of "Wed, 01 Sep 2021 16:32:23 +0300") Message-ID: <87zgswqqlo.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 50313-done Cc: 50313-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Andrew Tropin writes: > From 296145ea58bc9c10aa80bc80a24e4f55a87fbef6 Mon Sep 17 00:00:00 2001 > From: Andrew Tropin > 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 [=E2=80=A6] 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. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJIBAEBCgAyFiEEcjhxI46s62NFSFhXFn+OpQAa+pwFAmEvl9MUHGdvLndpZ3Vz dEBnbWFpbC5jb20ACgkQFn+OpQAa+pwVeg/+ODveGAxS0lrgcUQv/hvfJO2JKmkU 12QAWJgf0Ao7VVsrOEFynoy3ybkSHxXz5aU7cspIJ3mJE+6GaJ3P7B+yA/U3vZOR Z25vxNDYGwk3AdEwK7mhx5pP6M9UJPG6Uco/GpjWZiPnfIwQ1zlXSHTjlDZsI1ys NVauo9qjk/xmKDOSGIomNTEtEW/h/Xmi51MsKV4+uA7mt0okgezRSBESV12V14tm z/UtQbNcRRiGKPB0qhvLnBQi7UPNSZaxxWS5ar3as6BE68nswww+FvvJSk0vz4pq +PvZFDSbE4khrLWoT8/IYHUD/Ze//mHT1dQQqVsebQdjfm0uaE1OSRO4aDHEE3AG jISStq16dm8U68B2fPDAngYDqsN0XvMII3y/f/VbolZABvkKi8k/mYCIP/8Ik0uL jz/po/9dIm6iB2dvBJiIP9w0+ib5jc8xm44TPruP523293P8h32CgsXXOWlA9ieS 5pOsrJJ6CFyA1Kc1EP2V4/a88pclMLr+cUDodhQx/FLZ/P6mUz66KSpMoCraWwM/ MksnBt+j8ZxcIMP1NonyG4OS/sEQNEaybHJbgxPEuMMznjuukAdhPjkxymO/ICOM K1fxVfhXXP4m35H74M9JoCxejZdl2vfDeYpCo0Hs9T+9uin8KMsjBjThKxbfAaD9 7Q1LiMnH96M5Mxc= =n0pi -----END PGP SIGNATURE----- --=-=-=-- From debbugs-submit-bounces@debbugs.gnu.org Fri Sep 03 03:21:17 2021 Received: (at 50313-done) by debbugs.gnu.org; 3 Sep 2021 07:21:17 +0000 Received: from localhost ([127.0.0.1]:42703 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mM3Vl-0008Jq-BX for submit@debbugs.gnu.org; Fri, 03 Sep 2021 03:21:17 -0400 Received: from mail-lj1-f172.google.com ([209.85.208.172]:41481) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mM3Vj-0008Jc-Iw for 50313-done@debbugs.gnu.org; Fri, 03 Sep 2021 03:21:16 -0400 Received: by mail-lj1-f172.google.com with SMTP id m4so8173079ljq.8 for <50313-done@debbugs.gnu.org>; Fri, 03 Sep 2021 00:21:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=trop-in.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:in-reply-to:references:date:message-id :mime-version; bh=M2AO1IH8xRWBbjdyT694NRqCpci5t6QLjygDa/cz+Fg=; b=xnEPAR+zCUT+SpLe+SXaajtQ0n0K/lat/JvDzK5+4jmCH3k+R1t0j+4Y/l0Gn5G6oG 1E4WwW+y0LY0jMkjraZxrUlyshePcYJcWaOhNXzGeCSUstT1ooF03pE6rmTD+hvGtco7 RbVNluCLU+yWtCblDWc8ntBnlKJRFIgj+rQooV9FHUidgDkogh1YnppieDWyp79rwtGB zrbVVZs4wCM28ATgsotojKK42OoOUu1AS1wVhPtygcE3XYtdT/OlFnDz1hyyWRYPdvUS BhekFuXJG/7ZqyZvwiMJSqHED6F1cWtJQRDaM1w5YYIfy57Sf7MzF3W+1oppqIsdN9e7 rApw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references:date :message-id:mime-version; bh=M2AO1IH8xRWBbjdyT694NRqCpci5t6QLjygDa/cz+Fg=; b=ATWgi41s1qyBsTLnDaza6zJNAGIhOezQyUOFXdZiWSWkyaooI0cH7+ZTkCG1Rq7q20 kdy1ZlVZbjt8n/sLz6kJHUAi0ERQ+KE5FDD9ybm9x7vYWpf8HSJYGRM1eiovMD8mgxkg 20cR+MmsZqNzqOVFwNlhhiR4uUKb+du5JMM3FZGeNM9h0+4VDDn6vDzJY5uBY5gmX4+t kiDh61ViHksSqVgaZqFvKa4uJ/Ahf8rTctCCKGJj+Cr2CZxncQFQ1hPIBSzlhsrSbIYd LfZlsatAubCSHHmZJ0Tp+NiyvAraXH9cm98fs0Flq40u2UXCvjSBG9GP0ijUQSAFPLIx b/7g== X-Gm-Message-State: AOAM531P0vVqZ60aKTF4IeKVOiXveo21xRGCJouN+sbntZjI5gMubFmh i7TJiEezS2aaBKn7DnOMMPEuqQ== X-Google-Smtp-Source: ABdhPJztdkEN8k6WzeFzH+kPvGbFoHx9EQG+XMYFSd9E9RqK1O/wd8kbeRETEQVlPUOwNeCMnhvZLQ== X-Received: by 2002:a05:651c:382:: with SMTP id e2mr1778515ljp.401.1630653669513; Fri, 03 Sep 2021 00:21:09 -0700 (PDT) Received: from localhost ([109.252.93.92]) by smtp.gmail.com with ESMTPSA id u14sm417984lfm.241.2021.09.03.00.21.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 03 Sep 2021 00:21:08 -0700 (PDT) From: Andrew Tropin To: Oleg Pykhalov Subject: Re: [PATCH v2] doc: Add Guix Home documentation. In-Reply-To: <87zgswqqlo.fsf@gmail.com> References: <878s0gzn54.fsf@trop.in> <874kb4siyo.fsf@gmail.com> <878s0gqv4o.fsf@trop.in> <87zgswqqlo.fsf@gmail.com> Date: Fri, 03 Sep 2021 10:21:05 +0300 Message-ID: <875yviuntq.fsf@trop.in> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: 50313-done Cc: 50313-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 2021-09-01 18:10, Oleg Pykhalov wrote: > Andrew Tropin writes: > >> From 296145ea58bc9c10aa80bc80a24e4f55a87fbef6 Mon Sep 17 00:00:00 2001 >> From: Andrew Tropin >> 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 > > [=E2=80=A6] > > 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!) --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmExzOEACgkQIgjSCVjB 3rC7Fw/+Jfo5oAVQg80oEtgRrdQXBFIll4IIZk6ogQiI09Haeip7Yz68P6FU8HCy bZXnwcnybQ2NJeY31iBwach2+NAoMSePjMoLQ7EvH5/5pXgnL8XuZoDV/rikP6/8 0yKgFReSOzS7emw43R9jtJX1kSm/1syfCoKEqz0NhNVcH3wL1/mZmCU/gwSvjFuY twtVhGlD6VAmaZMBlCYrAc4zLIEj+CTZzwZbjxQ5XF9xR5QOE7kvLGHbkTBqPnO3 GI4ipWBqVCKe/ZnjBSM0ZsoQ3sJ9svi0J6vUW53UY05FnCuITE7Hz5jzByRW64lz qkKmdUbBf6hlkOHYOSQLfKKlBpy4pQn2BqOJUJJZMrd7Kx420/3iLEY/PNxZn8bl 68BXwtKlHgo8oj2sKv7kNyGrXalezrXS3tUB9Jno0NhmARNX4rHub2vRDCi40RgS GRWsr5EGAhs2pHp5rJPhs0plIUFueDJH+W0xVIb0CQygiVypYHCK/pHydgxn4jnY fkPs90bld27M6TVSWmJW9c46p/T/SmhJGdXzFWhxuG0LLfiVNJYlQZtn0n3V7YFb UoAnamg+No3eoFohb/olgTdHQqeJcuOJ+hrn6VT27oQwdeXbdSwpDkGMygx/BpbA 9wmPkUkFh+HCLTiO9cFMtMVCqaCgBN6gn3ufLKrx7SiP1KbCz9g= =t7A6 -----END PGP SIGNATURE----- --=-=-=-- From unknown Tue Sep 09 21:32:51 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Fri, 01 Oct 2021 11:24:04 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator