Re: Feedback of the GNU Guix manual

[Matt <matt@excalamus.com>]

[-- Attachment #1: Type: text/plain, Size: 3623 bytes --]

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed an item and are ready to work on the next one:

#+begin_quote
,** Binary Installation L88 and L95

~root is weird. Should be root or simply ~ for the user profile which would be root as root user.
#+end_quote

I agree.  I found it weird at first, too.

Two thoughts:

1. The use of "~root" is intentional
2. Section 2.1 Binary Install can be refactored to remove the reported confusion as well as the tarpit of shell related details

*1. The use of "~root" is intentional*

According to the Bash info and man pages, "~root" is a TILDE-PREFIX with "root" as the LOGIN NAME.  The TILDE-PREFIX is replaced with the home directory associated with the specified LOGIN NAME.

Using "~root" solves the problem of operations happening in the wrong location.  It ensures that commands reference the 'root' user's home directory.

- (original issue) https://lists.gnu.org/archive/html/guix-devel/2015-06/msg00085.html
- (separate issue) https://bugs.gnu.org/30728

*2. Section 2.1 Binary Install needs refactoring*

The Binary Installation section tries to solve the problem of guiding readers to install Guix as quickly and painlessly as possible.  This began as a step-by-step process which was later automated by 'guix-install.sh'.  Over 6 years, 12 people have worked to make 'guix-install.sh' robust.  Because of these efforts, Section 2.1 Binary Installation has effectively become high level documentation for how 'guix-install.sh' works.

Like any code comment tends to drift out of sync with the source code, the current presentation of binary installations has become inconsistent and redundant.  Using 'guix-install.sh' is the recommended method for binary installation.  It's the first thing mentioned by Section 2 Installation and one of the first things mentioned by Section 2.1 Binary Installation.  It's inconsistent to say, "This is how to do it" and then proceed to explain how to *not* use the recommended method.

Key information, like the recommended installation method and the definition of "foreign distro", are improperly hidden inside notes.  Note blocks act as comments which, by definition, are secondary to the main point.  The main point is to use 'guix-install.sh' on foreign distros which don't provide their own packages for Guix.

The attached diff addresses these issues.  It fixes the root issue (pun intended) of whether or not to expect readers to understand '~root', as well as unmentioned issues also related to shell-specific knowledge like, "What does it mean to 'source'?"  Readers interested in those details may read the code for 'guix-install.sh'.

The diff does the following:

- Clarifies at the top level that installing on a foreign distro has two methods: using packaged binaries and building from source
- Places the overwrite warning at the top level node and binary installation level node
- Moves the definition of "foreign distro" out of quotation
- Moves the foreign distro installation instructions out of quotation
- Summarizes the steps 'guix-install.sh' follows rather than trying to detail them
- Splits the requirements between system requirements for binary installations, GNU/Linux or GNU/Hurd, and requirements for running 'guix-install.sh', tar, wget, Xz
- Removes redundant instructions to use 'guix-install.sh'
- Places directions for 'guix-install.sh' after directions to use distribution-specific package managers, giving preference to those simpler install processes over the more manual 'guix-install.sh' process

[-- Attachment #2: v01-refactor-binary-installation-section.diff --]
[-- Type: application/octet-stream, Size: 11940 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index f6476e0d81..6322cc6fe9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -690,20 +690,25 @@ to join!  @xref{Contributing}, for information about how you can help.
 @chapter Installation
 
 @cindex installing Guix
+@cindex foreign distro
+@cindex Guix System
+You can install the Guix package management tool on top of an existing
+GNU/Linux or GNU/Hurd system, referred to as a @dfn{foreign distro}, or
+as a standalone operating system distribution, the
+@dfn{Guix@tie{}System}.  This section is concerned with the installation
+of Guix on a foreign distro.  If, instead, you want to install the
+complete GNU operating system, @pxref{System Installation}.
 
-@quotation Note
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script} to install Guix on top of a running GNU/Linux system,
-thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
-with the installation of the package manager, which can be done on top of a
-running GNU/Linux system.  If, instead, you want to install the complete GNU
-operating system, @pxref{System Installation}.} The script automates the
-download, installation, and initial configuration of Guix.  It should be run
-as the root user.
+@quotation Important
+This section only applies to systems without Guix.  Following it for
+existing Guix installations will overwrite important system files.
 @end quotation
 
-@cindex foreign distro
+The following sections describe two methods of installation, binary
+installation and building from source.  They describe the software
+requirements of Guix, as well as how to install it manually and get
+ready to use it.
+
 @cindex directories related to foreign distro
 When installed on a foreign distro, GNU@tie{}Guix complements the available
 tools without interference.  Its data lives exclusively in two directories,
@@ -713,11 +718,6 @@ such as @file{/etc}, are left untouched.
 Once installed, Guix can be updated by running @command{guix pull}
 (@pxref{Invoking guix pull}).
 
-If you prefer to perform the installation steps manually or want to tweak
-them, you may find the following subsections useful.  They describe the
-software requirements of Guix, as well as how to install it manually and get
-ready to use it.
-
 @menu
 * Binary Installation::         Getting Guix running in no time!
 * Requirements::                Software needed to build and run Guix.
@@ -736,254 +736,57 @@ ready to use it.
 This section describes how to install Guix from a self-contained tarball
 providing binaries for Guix and for all its dependencies.  This is often
 quicker than installing from source, which is described in the next
-sections.  Binary installation requires a system using a Hurd or Linux
-kernel; the GNU@tie{}tar and Xz commands must also be available.
+sections.
 
 @quotation Important
 This section only applies to systems without Guix.  Following it for
 existing Guix installations will overwrite important system files.
+@end quotation
 
-@c Note duplicated from the ``Installation'' node.
-We recommend the use of this
-@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
-shell installer script}.  The script automates the download, installation, and
-initial configuration steps described below.  It should be run as the root
-user.  As root, you can thus run this:
-
-@example
-cd /tmp
-wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
-chmod +x guix-install.sh
-./guix-install.sh
-@end example
+Some distributions, such as Debian, Ubuntu, and openSUSE, provide Guix
+through their own package managers.  The version of Guix may be older
+than @value{VERSION} but you can update it afterwards by running
+@samp{guix pull}).
 
-If you're running Debian or a derivative such as Ubuntu, you can instead
-install the package (it might be a version older than @value{VERSION}
-but you can update it afterwards by running @samp{guix pull}):
+For Debian and Ubuntu-based systems call:
 
 @example
 sudo apt install guix
 @end example
 
-Likewise on openSUSE:
+Likewise on openSUSE run:
 
 @example
 sudo zypper install guix
 @end example
 
-When you're done, @pxref{Application Setup} for extra configuration you
-might need, and @ref{Getting Started} for your first steps!
-@end quotation
-
-Installing goes along these lines:
-
-@enumerate
-@item
-@cindex downloading Guix binary
-Download the binary tarball from
-@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
-where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
-@code{i686} (32-bits) machine already running the kernel Linux, and so on
-(@pxref{GNU Distribution}).
-
-@c The following is somewhat duplicated in ``System Installation''.
-Make sure to download the associated @file{.sig} file and to verify the
-authenticity of the tarball against it, along these lines:
-
-@example
-$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-$ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
-@end example
+The Guix project also provides a shell script, @file{guix-install.sh},
+which automates the binary installation process without use of a foreign
+distro package
+manager@footnote{@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh}}.
+Use of @file{guix-install.sh} requires Bash, GNU@tie{}tar, wget, and Xz.
 
-If that command fails because you do not have the required public key,
-then run this command to import it:
+The script does the following:
 
-@example
-$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-      -qO - | gpg --import -
-@end example
-
-@noindent
-and rerun the @code{gpg --verify} command.
-
-Take note that a warning like ``This key is not certified with a trusted
-signature!'' is normal.
-
-@c end authentication part
+@itemize
+@item Downloads and extracts the binary tarball
+@item Sets up the build daemon
+@item Makes the ‘guix’ command available to non-root users
+@item Configures substitute servers
+@end itemize
 
-@item
-Now, you need to become the @code{root} user.  Depending on your distribution,
-you may have to run @code{su -} or @code{sudo -i}.  As @code{root}, run:
+As root, run:
 
 @example
 # cd /tmp
-# tar --warning=no-timestamp -xf \
-     /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
-# mv var/guix /var/ && mv gnu /
-@end example
-
-This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
-The latter contains a ready-to-use profile for @code{root} (see next
-step).
-
-Do @emph{not} unpack the tarball on a working Guix system since that
-would overwrite its own essential files.
-
-The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
-not emit warnings about ``implausibly old time stamps'' (such
-warnings were triggered by GNU@tie{}tar 1.26 and older; recent
-versions are fine).
-They stem from the fact that all the
-files in the archive have their modification time set to 1 (which
-means January 1st, 1970).  This is done on purpose to make sure the
-archive content is independent of its creation time, thus making it
-reproducible.
-
-@item
-Make the profile available under @file{~root/.config/guix/current}, which is
-where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
-
-@example
-# mkdir -p ~root/.config/guix
-# ln -sf /var/guix/profiles/per-user/root/current-guix \
-         ~root/.config/guix/current
-@end example
-
-Source @file{etc/profile} to augment @env{PATH} and other relevant
-environment variables:
-
-@example
-# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
-  source $GUIX_PROFILE/etc/profile
-@end example
-
-@item
-Create the group and user accounts for build users as explained below
-(@pxref{Build Environment Setup}).
-
-@item
-Run the daemon, and set it to automatically start on boot.
-
-If your host distro uses the systemd init system, this can be achieved
-with these commands:
-
-@c Versions of systemd that supported symlinked service files are not
-@c yet widely deployed, so we should suggest that users copy the service
-@c files into place.
-@c
-@c See this thread for more information:
-@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
-     ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
-     /etc/systemd/system/
-# systemctl enable --now gnu-store.mount guix-daemon
-@end example
-
-You may also want to arrange for @command{guix gc} to run periodically:
-
-@example
-# cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
-     ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
-     /etc/systemd/system/
-# systemctl enable --now guix-gc.timer
-@end example
-
-You may want to edit @file{guix-gc.service} to adjust the command line
-options to fit your needs (@pxref{Invoking guix gc}).
-
-If your host distro uses the Upstart init system:
-
-@example
-# initctl reload-configuration
-# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
-     /etc/init/
-# start guix-daemon
-@end example
-
-Otherwise, you can still start the daemon manually with:
-
-@example
-# ~root/.config/guix/current/bin/guix-daemon \
-       --build-users-group=guixbuild
-@end example
-
-@item
-Make the @command{guix} command available to other users on the machine,
-for instance with:
-
-@example
-# mkdir -p /usr/local/bin
-# cd /usr/local/bin
-# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
-@end example
-
-It is also a good idea to make the Info version of this manual available
-there:
-
-@example
-# mkdir -p /usr/local/share/info
-# cd /usr/local/share/info
-# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
-  do ln -s $i ; done
-@end example
-
-That way, assuming @file{/usr/local/share/info} is in the search path,
-running @command{info guix} will open this manual (@pxref{Other Info
-Directories,,, texinfo, GNU Texinfo}, for more details on changing the
-Info search path).
-
-@item
-@cindex substitutes, authorization thereof
-To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
-@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
-authorize them:
-
-@example
-# guix archive --authorize < \
-     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
-# guix archive --authorize < \
-     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
-@end example
-
-@quotation Note
-If you do not enable substitutes, Guix will end up building
-@emph{everything} from source on your machine, making each installation
-and upgrade very expensive.  @xref{On Trusting Binaries}, for a
-discussion of reasons why one might want do disable substitutes.
-@end quotation
-
-@item
-Each user may need to perform a few additional steps to make their Guix
-environment ready for use, @pxref{Application Setup}.
-@end enumerate
-
-Voilà, the installation is complete!
-
-You can confirm that Guix is working by installing a sample package into
-the root profile:
-
-@example
-# guix install hello
-@end example
-
-The binary installation tarball can be (re)produced and verified simply
-by running the following command in the Guix source tree:
-
-@example
-make guix-binary.@var{system}.tar.xz
-@end example
-
-@noindent
-...@: which, in turn, runs:
-
-@example
-guix pack -s @var{system} --localstatedir \
-  --profile-name=current-guix guix
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @end example
 
-@xref{Invoking guix pack}, for more info on this handy tool.
+When you're done installing Guix, @pxref{Application Setup} for extra
+configuration you might need, and @ref{Getting Started} for your first
+steps!
 
 @node Requirements
 @section Requirements