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

[Matt <matt@excalamus.com>]

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

I realigned the subject.  It was previously changed to "doc: Removing much of Binary Installation" which is misleading.  The topic is how to clarify installation based on reported confusion, not about removing text.  The reported confusion was on the use of '~root'.  Explicit mention of '~root' is only necessary when the manual details how 'guix-install.sh' works.  Since 'guix-install.sh' is the recommended method of installation, such level of detail is unnecessary, inappropriate, and impractical.  The suggested changes address the issue, only incidentally, by removing text.

I respond to Suhail Singh, Vagrant Cascadian, and pelzflorian in order.

---- On Wed, 06 Mar 2024 22:18:33 +0100  Suhail Singh  wrote ---
> Suhail Singh suhailsingh247@gmail.com> writes:
>
> > FWIW, as an openSUSE Tumbleweed user, I believe Tumbleweed users who don't care if there is an easy way to uninstall Guix would be better served by using =guix-install.sh= as opposed to =zypper=.
> Btw, for completeness, on Tumbleweed, the user needs to take some additional steps to ensure that restoring a previous Tumbleweed snapshot doesn't revert Guix state.  Unless I'm misremembering, these steps are needed regardless of whether =zypper= or =guix-install.sh= was used to install Guix.

Thank you for this.  I want to follow up with Vagrant and Florian first before responding more fully.

---- On Wed, 06 Mar 2024 22:29:23 +0100  Vagrant Cascadian  wrote ---
> As the one who packaged and maintains guix in Debian...

Thank you for doing this work!

> The guix-daemon should continue to work from the packaged version, although as guix develops more and more features; how long an old version can be expected to continue to work remains an open question.

I was under the impression that Guix installed through a foreign package manager is able to update with 'guix pull'.  This is what the current documentation says,

"If you’re running Debian or a derivative such as Ubuntu, you can instead install the package (it might be a version older than 0.0-git but you can update it afterwards by running ‘guix pull’):"

Is this correct?  Does 'guix pull' update Guix when installed through a foreign package manager?

---- On Thu, 07 Mar 2024 18:03:50 +0100  pelzflorian (Florian Pelz)  wrote ---

> I first tried guix-install.sh on a Debian GNU/Hurd VM.  It fails, telling me:
>
> [1709825168.049]: [ INFO ] init system is: sysv-init
> [1709825168.059]: [ FAIL ] Unsupported CPU type: i686-AT386
>
> The script guix-install.sh cannot be used on any GNU/Hurd system.

Thanks for taking the time to test 'guix-install.sh' on Hurd.  This looks like a bug.

> Vagrant’s guix package is missing on Debian GNU/Hurd as well, which is fine of course, but we should not claim otherwise.

Updated to specify "distributions" as "GNU/Linux distributions".

> Therefore, could you change it like the old instructions and only talk about GNU/Linux?

I don't think that's appropriate.  Guix supports GNU/Linux and GNU/Hurd and the installation section needs to cover both.

There are two issues here:

1) Up to this point, the manual doesn't make clear that current GNU/Hurd support is limited

I've duplicated the footnote from the 'operating-system Reference' section which explains the current status of GNU/Hurd support: https://guix.gnu.org/en/manual/devel/en/html_node/operating_002dsystem-Reference.html

2) 'guix-install.sh' has a bug preventing installation on GNU/Hurd

Any takers?

> > If, instead, you want to install the complete GNU operating system, @pxref{System Installation}.
>
> Maybe better say “complete Guix operating system”?  *complete* GNU operating system maybe should only be used for GNU/Hurd.

That line is directly copied from the current manual: https://guix.gnu.org/en/manual/en/html_node/Installation.html#FOOT4

I saw this and I agree with you.  It would be better stated as something like you suggest.  My intent was to do this in a separate patch.

> You suggested in your mail:
>
> Matt matt@excalamus.com> writes:
> > Readers interested in those details may read the code for 'guix-install.sh'.
>
> Could you add this suggestion to your diff?

I don't see that as relevant to the reader.  The ability to read the source is implicit in it being provided, which it is.

> IIRC, you are removing the manual installation.

Yes? No? I'm not sure how to respond.

The suggested changes remove superfluous commentary on the recommended binary installation process which create confusion.

The challenge in directly responding to your statement is there's not a clear cut-off between "install" and "configure."  To install, generally, means something like "situate artifacts so the user can make use of them".  Often, this is simply adding a directory to PATH.  Guix isn't that simple.  It requires setting up the store, var/guix, configuring the demon, setting up profiles, and other things.  That's all part of "so the user can make use of them" which is more "configuration" than "installation".  Which specific configuration is necessary, however, depends on the system and the user.  Detailing that at the level of "type this, type that" requires many caveats, explanations, and updates that don't really address the core topic: get Guix on a reader's system so that they can use it.  That, as far as I can tell, is the fundamental reason why 'guix-install.sh' exists.

What do you think is lost that isn't captured by the following bulleted list?

+The script guides you through the following:
+@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

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

> Also,
>
> 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 :)

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

> At the beginning, “You can install the Guix package management tool on top of an existing” makes it appear as if Guix were not a distribution.  It is both a tool and a distro.  A distro does not need to be an OS.  For example, MSYS2 is a distribution.  I therefore nitpickingly prefer “You can install Guix”.  Admittedly, the wording was vague before, perhaps deliberately.

I don't follow you.  The complete sentence is:

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

What about that is unclear?

> “Use of @file{guix-install.sh} requires Bash, GNU@tie{}tar, wget, and Xz.” is incomplete when applied to guix-install.sh, which also requires GnuPG.

Added! Thank you.

An updated diff is included.  I tried to split it into separate commits but couldn't.  That's very, very hard and probably impossible to do in an independent way.  My hope is that we can settle on language for this topic and try for a more step-wise approach on the next feedback item.

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

diff --git a/doc/guix.texi b/doc/guix.texi
index 858d5751bf..9113cd0152 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -691,20 +691,23 @@ 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@footnote{Currently only the Linux-libre
+kernel is fully supported.  Using GNU@tie{}mach with the GNU@tie{}Hurd
+is experimental and only available when building a virtual machine disk
+image.}, 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 +717,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,210 +734,64 @@ 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.
 
 @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
 @end example
 
-Likewise on openSUSE:
+Likewise, on openSUSE:
 
 @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:
+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.
 
-@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 script guides you through the following:
 
-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.
-
-Take note that a warning like ``This key is not certified with a trusted
-signature!'' is normal.
-
-@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 /
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @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).
+@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 +799,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 +17462,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