From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id UDOaFD9tL2GYcQAAgWs5BA (envelope-from ) for ; Wed, 01 Sep 2021 14:08:31 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id oN45ED9tL2G9LQAAB5/wlQ (envelope-from ) for ; Wed, 01 Sep 2021 12:08:31 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id C6E5ABA34 for ; Wed, 1 Sep 2021 14:08:30 +0200 (CEST) Received: from localhost ([::1]:45368 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mLP2b-0001QC-Pp for larch@yhetil.org; Wed, 01 Sep 2021 08:08:29 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57012) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mLOsU-0003E3-6h for guix-patches@gnu.org; Wed, 01 Sep 2021 07:58:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:53202) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mLOsT-0006o3-To for guix-patches@gnu.org; Wed, 01 Sep 2021 07:58:01 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mLOsT-0001yJ-Qc for guix-patches@gnu.org; Wed, 01 Sep 2021 07:58:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#50313] [PATCH] doc: Add Guix Home documentation. Resent-From: Xinglu Chen Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 01 Sep 2021 11:58:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 50313 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Andrew Tropin , 50313@debbugs.gnu.org Received: via spool by 50313-submit@debbugs.gnu.org id=B50313.16304974707554 (code B ref 50313); Wed, 01 Sep 2021 11:58:01 +0000 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= 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1630498111; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:resent-cc:resent-from:resent-sender: resent-message-id:in-reply-to:in-reply-to:references:references: list-id:list-help:list-unsubscribe:list-subscribe:list-post: dkim-signature; bh=rknsCRdwicf3JxuN59KfM3Uko7A1sOLLGzMeCyUCr6g=; b=t8v8fY9dDTKa7ksCU351bRF6k/zDMrw0+F9yNWrkOkWWFboWVFX9rRD26/lq8J7A2WaVM+ WMIG9koFX6TqSR2C1oKfh3nN6tOC+Uv4Tdk9QTEqrUZcrbHxbewzNk41/eDbPxcLmUuAzl orzhz9S2pENULPvUIpbWu0Rq9qaX5Mo1Uo8xIVeyRAeoMmlDsqH6iYx72S8Xl5KDaW2N6B 8V8UmGwIsaCgr/BfyDnocr7ofnEPhjRNewESpPq2b/86S4OkvnQhAu7WEkJo8ThwMTMp06 FotD/9gzv5cAgXcx7FBw6C06rVLUg0cKkGJ1HYniMWP/hqFFY7nQlj3iRWsJQA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1630498111; a=rsa-sha256; cv=none; b=P72j86UJ0afjPURGUu01gIseoyXc5SrtvsPdAwkyLKzaGxSf2K916Uuhwzf9tagY/oYXAe 4hWv+yBno4GmE+Jcldht7nTkajFaRVtoY4rywEgT2r16LOupV9Ix5ZpCdA4ZOhmD/iFVBi EqgbFpi3BgVZbbRiChOik1oL9axvuJjodE0z9qIS6E/yPP0o5VlsEFLm61h0eHIDqxSLff Z5BsUHJb1oRPcS4CAOloNqsbU+VWZ4O3Xin0hs6pHISJzHk5e/m/kST/2G0H6gtnPx+PZ9 t4Q7X11BJL9FD6FED2VVlr27/uCB1hhGcXREBE/jRtup8klLBIIVt5LTpGK02Q== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=yoctocell.xyz header.s=mail header.b=AubRFvxS; spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Spam-Score: -3.42 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=yoctocell.xyz header.s=mail header.b=AubRFvxS; dmarc=fail reason="SPF not aligned (relaxed)" header.from=yoctocell.xyz (policy=none); spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Queue-Id: C6E5ABA34 X-Spam-Score: -3.42 X-Migadu-Scanner: scn0.migadu.com X-TUID: D4QR+sQ/lWmu --=-=-= 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----- --=-=-=--