Re: doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation)

[Matt <matt@excalamus.com>]

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

There are several actions which we have deferred and other topics
which still need to be addressed, such as those raised by Vagrant and
Suhail.  My hope is to 1) resolve and merge this immediate patch, as
we appear to be converging on a consensus, 2) discuss how we could
better handle documentation changes than how I've handled them here
(that is, in one ever evolving diff), 3) compile a list of deferred
actions, 4) compile a list of deferred topics, and 5) address points 3
and 4 according to 2.

---- On Mon, 11 Mar 2024 16:54:01 +0100  pelzflorian (Florian Pelz)  wrote ---
> Hi Matt.  I would almost want to push your changes, but we still
> disagree on some wordings.

I'm glad to hear the suggested changes are more acceptable than not.
Let's do what we need to get things right.

> Yes, however the removal means that we should move the sections
>
> * 2.2 Requirements
> * 2.3 Running the Test Suite
>
> to the Contributing manual in doc/contributing.texi.  WDYT?  You said,
> it could be a separate discussion, but in my opinion it would be part of
> the same patch.

I was thinking of the opposite, of moving "Building from Git" into
Installation.  What you say makes more sense and I agree.  Since the
suggested patch is already quite complex, I have not added moving
Sections 2.2 and 2.3 to the changes.  I propose we make the move in a
separate commit.

> > +@cindex foreign distro
> > +@cindex Guix System
>
> “@cindex Guix System” is inappropriate, because instructions on Guix
> System are not here.

Removed.  Good catch!

> > +You can install the Guix package management tool on top of an existing
> > +GNU/Linux or GNU/Hurd system@footnote{Currently only the Linux-libre
> > +kernel is fully supported. […]
>
> No.
>
> First of all, using guix-install.sh as per your instructions, one
> installs the Guix distribution *and* package management tool.  Either
> say “You can install the Guix package management tool and distribution”
> or “You can install Guix”.

I'm afraid I don't follow.  Where do you see the suggested changes
confusing the installation process for Guix as a distribution and Guix
as a package management tool?

The sentence you quote is the suggested first sentence for the Chapter
2: Installation.  The complete sentence reads,

"You can install the Guix package management tool on top of an
existing GNU/Linux or GNU/Hurd system(1), referred to as a "foreign
distro", or as a standalone operating system distribution, the "Guix
System"."

It literally says Guix is a package manager or a distribution.  No
mention of 'guix-install.sh' is made on that page.

The current "introduction" to Chapter 2: Installation is this:

"Note: We recommend the use of this <shell installer script> to
install Guix on top of a running GNU/Linux system, thereafter called a
foreign distro. The script automates the download, installation, and
initial configuration of Guix. It should be run as the root user."

https://guix.gnu.org/en/manual/devel/en/html_node/Installation.html

Maybe the diff didn't apply correctly?  Maybe it's confusing how the
Texinfo syntax puts the footnote markup in the middle of the source
sentence, even though footnotes render at the bottom of the page?

> Next, I believe Guix cannot currently be built on existing GNU/Hurd
> systems, because guile-fibers does not work.  I do not really know
> enough, but I would not mention Hurd support.

The are two issues here, what is said and what should be said.

Regarding what is said, the section we're talking about is for
installing not building.  You *can* install the Guix package
management tool on top of an existing GNU/Hurd system.  This is
exactly what the suggested changes say, minus the emphasis.  As far as
I know, it's true:

1. https://guix.gnu.org/en/blog/2020/a-hello-world-virtual-machine-running-the-hurd/
2. https://guix.gnu.org/en/blog/2020/childhurds-and-substitutes/

Further, the manual already mentions Hurd support:
https://guix.gnu.org/en/manual/devel/en/html_node/operating_002dsystem-Reference.html

Beyond the manual, there are two blog posts (linked above) which have explicit
sections about why it makes sense to develop for Hurd.  Code for Hurd
is mainlined with 80 files in the master branch providing Hurd
support.

I get it, it's the Hurd.  Running Guix on Hurd was part of a joke.
Correct me if I'm wrong, though: Hurd support wasn't the punchline,
ending support for Linux was.  The part that said, "running on the
Hurd was always a goal for Guix" is sincere.

So, what should be said is that Hurd support is limited.  Any errors
are bugs, either for Guix or for upstream.

I've updated the footnote to warn that Hurd support is currently
limited.

> Additionally “only the Linux-libre kernel” is incorrect, because
> running Guix on non-libre Linux is fully supported.  Running Guix
> System there is not supported (by us).

Excellent point: the package manager is indeed supported on non-free
distros.  I had carelessly copied the footnote, and the text containing this
issue, from another section.  The update on the previous point,
regarding Hurd support, removes this issue by removing mention of
Linux.

> >> Therefore, the sentence would have to be removed: “The following
> >> sections describe two methods of installation, binary installation
> >> and building from source.”
> >
> > I've removed that sentence for a different reason.  I also revised the
> > sentence, "This is often quicker than installing from source, which is
> > described in the next sections", to simply, "described later".
> >
> > The reason is that Chapter 2 doesn't currently explain building or
> > installing from source.  Building and installing from source is
> > currently covered much later in Section 22.1.  Whether or not the
> > Installation section should cover building from source is a separate
> > issue and shouldn't be part of this discussion.
>
> This could be:
>
> described later (@pxref{Building from Git}).

Updated.

> >> Matt matt@excalamus.com> writes:
> >> > - Add commas in appropriate places; after "For...Ubuntu-based
> >> > systems", "Likewise", and the 'or' within the list of substitutes
> >>
> >> I’m not a native speaker, but I believe the commas are not
> >> necessary.  There particularly does not need to be an Oxford comma
> >> before ‘or’.  There could be, but there is no reason to change it.
> >
> > Ah, the One True Brace Style of natural language :)
> >
> > I think there's already enough controversy in this thread.  I've changed it back :)
>
> :D  However, please also do not change:
>
> > -Likewise on openSUSE:
> > +Likewise, on openSUSE:

Corrected.

> >> Similarly, IMO the nuances are more appropriate in the old wording
> >> “For Debian or a derivative such as Ubuntu,” rather than your change
> >> “For Debian and Ubuntu-based systems”.
> >
> > The current wording is, "If you're running Debian or a derivative such
> > as Ubuntu..."  None of the suggested changes include the wording you
> > give.
> >
> > What are the nuances?  If they matter, we should probably make them explicit.
>
> The nuance is that Ubuntu is a derivative of Debian.  It can be
> bootstrapped with Debian’s dpkg, although I did not follow a recent
> e-mail thread on how to do this from a Guix-provided dpkg.

Unless there's something about this nuance which directly affects the
installation process, I don't think the distinction warrants mention.

I opted to ignore the distinction and use "Debian and Ubuntu-based
systems" because many popular distros, such as Ubuntu, Linux Mint,
Zorin OS, Elementary OS, Linux Lite, and Pop!_OS, are known for being
"based on Ubuntu."  The relevant information for users of these
systems is not that they're derivatives of Debian, it's that this is
the installation process for such systems.

> > +@quotation Note
> > +By default, binary installations of Guix build @emph{everything} from
> > +source.  This makes each installation and upgrade very expensive.
> > +@xref{On Trusting Binaries} for a discussion of why this is the default.
> > […]
> > -
> > -@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
>
> Better not change the wording?  I believe enabling substitutes is not
> the default.

My assumption is that the vast majority of readers are not installing
Guix on distros whose default is to compile from source.  The concept
and jargon of substitutes, let alone the idea of compiling from
source, is likely completely unknown to most readers.  Readers likely
expect, what we would call, substitutes to be enabled.

As far as I understand, the default behavior is opposite what most
readers would expect: substitutes are *not* enabled by default for
binary installations of Guix.

The suggested wording avoids the jargon of "substitutes" in favor of
simpler language which directly addresses what the reader likely cares
about: the default Guix behavior is to compile from source which takes
a long time.  It also frames the discussion of "On Trusting Binaries"
from the perspective of "the expensive default was decided by careful
consideration."  The current wording, "why one might want to disable
substitutes," involves jargon (substitutes) and a negative (disable)
which requires understanding what a substitute is, what the default
is, and whether "disabling" is contrary to the default.  That
complexity is unnecessary, as I believe the suggested changes
demonstrate.

I think a valid critique of the suggested changes is "why say 'very
expensive' instead of 'takes a long time'?"  The suggestion uses the
phrase "very expensive" instead of "takes a long time" because 1)
"very expensive" is the current language and 2) wall time is only one
of several expenses; others are energy and CPU cycles.  This is a
situation where I think it's okay to be non-specific.  The point is
"the default behavior may seem undesirable" and the word "expensive"
is typically considered undesirable.

> IMHO The discussion about whether Upgrading Guix should recommend to
> edit the systemd service of the Debian guix package is for a
> separate second patch.

Agreed.

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

diff --git a/doc/guix.texi b/doc/guix.texi
index 796ac0028f..844e8df135 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -691,20 +691,20 @@ to join!  @xref{Contributing}, for information about how you can help.
 @chapter Installation
 
 @cindex installing Guix
+@cindex foreign distro
+You can install the Guix package management tool on top of an existing
+GNU/Linux or GNU/Hurd system@footnote{Hurd support is currently
+limited.}, 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
 @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,
@@ -714,11 +714,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,31 +731,20 @@ ready to use it.
 @cindex installer script
 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.
+quicker than installing from source, described later (@pxref{Building
+from Git}).
 
 @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 GNU/Linux 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
@@ -772,174 +756,40 @@ Likewise on openSUSE:
 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
-
-If that command fails because you do not have the required public key,
-then run this command to import it:
-
-@example
-$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-      -qO - | gpg --import -
-@end example
-
-@noindent
-and rerun the @code{gpg --verify} command.
+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, GnuPG, GNU@tie{}tar, wget,
+and Xz.
 
-Take note that a warning like ``This key is not certified with a trusted
-signature!'' is normal.
+The script guides you through the following:
 
-@c end authentication part
+@itemize
+@item Download and extract the binary tarball
+@item Set up the build daemon
+@item Make the ‘guix’ command available to non-root users
+@item Configure 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
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @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).
+@quotation Note
+By default, binary installations of Guix build @emph{everything} from
+source.  This makes each installation and upgrade very expensive.
+@xref{On Trusting Binaries} for a discussion of why this is the default.
 
-@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:
+you must authorize them.  For example,
 
 @example
 # guix archive --authorize < \
@@ -947,44 +797,11 @@ authorize them:
 # 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
-@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
@@ -17643,6 +17460,7 @@ configuration (@pxref{Using the Configuration System}).
 
 @table @asis
 @item @code{kernel} (default: @code{linux-libre})
+@c footnote duplicated in @pxref{Installation}
 The package object of the operating system kernel to
 use@footnote{Currently only the Linux-libre kernel is fully supported.
 Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only