Re: doc: Removing much of Binary Installation (was: Feedback of the GNU Guix manual)

[Matt <matt@excalamus.com>]

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

 ---- On Wed, 06 Mar 2024 18:15:05 +0100  pelzflorian (Florian Pelz)  wrote ---
 > Thank you Matt for the suggested diff.

Thank you for taking the time to review it!

 > > - 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
 >
 > I don’t feel qualified to judge, but is this the preference?  Arch wiki advises against the Arch AUR package: “Therefore, after updating Guix once, the AUR advantage really turns into a disadvantage, as there will be many unnecessary files in the /usr file tree that are part of the Guix AUR package but that are never used by Guix anymore.  Therefore, consider using the manual installation.” [0]
 >
 > [0] https://wiki.archlinux.org/title/Guix

Good question, I wondered about this after I submitted.

The current manual has instructions for using the Debian, Ubuntu, and openSUSE package managers.  These instructions are given after the recommendation for =guix-install.sh= along with the transition:

"If you’re running Debian or a derivative such as Ubuntu, you can instead install the package..."

"Instead" means "in place of something previously mentioned."  So, as written, installing with =guix-install.sh= and installing with those specific package managers have equal levels of recommendation.

Since users of foreign systems are likely familiar with the corresponding foreign package managers, in addition to their use being one step versus four, I vote that they appear first.

This is good information about the situation with Arch.  Maybe this is why Arch isn't mentioned?

I wonder if we should have similar concerns about the Debian and openSUSE packages?

 > The reason of existence for these distribution packages is probably similar to the reason why the Binary Installation section exists.
 >
 > As for the suggested diff where much of Binary Installation gets removed,
 >
 > > -@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
 >
 > I disagree with this chunk.  This must stay.  Not enabling substitutes is an option in guix-install.sh and the Guix System installer.  Users might want to enable substitutes later on.

Excellent point.

I have updated the patch with the following:

- Add commas in appropriate places; after "For...Ubuntu-based systems", "Likewise", and the 'or' within the list of substitutes
- Remove ')' from after 'guix pull'
- Clarify that 'guix-install.sh' guides users through the steps.  Previously, it was unclear if the script ran without user input.
- Add the substitute server setup with the following changes:
  + Make explicit that the default for binary installations is to build everything
  + Change "for a discussion of reasons why one might want do disable substitutes" (note the 'do' typo) to "for a discussion why this is the default".  This aims to state it positively and encourage people to consider the reasons.
- Emphasize that the substitute authorization code is an example and may need modification

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

diff --git a/doc/guix.texi b/doc/guix.texi
index 87fe9f803c..cc9b07c152 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -691,20 +691,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,
@@ -714,11 +719,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.
@@ -737,209 +737,63 @@ 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:
 
 @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
-
-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, 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:
+@code{@value{SUBSTITUTE-SERVER-2}}, or a mirror (@pxref{Substitutes}),
+you must authorize them.  For example,
 
 @example
 # guix archive --authorize < \
@@ -947,44 +801,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