[bug#69977] [PATCH] doc: doc-Simplify installation instructions (was Re: doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation))

[Matt <matt@excalamus.com>]

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

On Ludo's recommendation, I'm submitting this patch set.  It fixes issues of confusion raised in feedback on the manual.  See this discussion: https://lists.gnu.org/archive/html/guix-devel/2024-03/msg00023.html

I will reply to points raised in that thread here and have CC'd people who have previously shown interest.

 ---- On Sat, 16 Mar 2024 15:05:13 +0100  pelzflorian (Florian Pelz)  wrote ---
 > I think the diff was quite appropriate.  You could make a patch via “git
 > format-patch” or “git send-email”, which would include a commit message
 > and which could include a move of sections 2.2 and 2.3 to the
 > contributing.texi.  But it is not necessary for documentation changes.

See attached.

 > >> > Matt matt@excalamus.com> writes:
 > >> > +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.
 >
 > Precisely this terminology is the issue.  Nix is a package manager;
 > Nixpkgs is a distribution.  For Guix, Guix is both a package manager and
 > distribution.  Guix System is not a distribution in this sense; Guix is
 > the distribution.  I am aware that some people expect distribution to
 > mean a self-sufficient operating system, but we should not subscribe to
 > one side of terminology.  (Actually, the term operating system is
 > complex as well, for example GNU is an operating system and the people
 > from Robot Operating System call ROS an operating system.)

Thank you for your feedback.  Reading the suggested changes again with fresh eyes, I think I now see your concerns.  I see you raise two concerns:

1. A clear distinction between Guix and the Guix System was not made

I have split the suggested sentence, whose current version (v04) is given above, into two. One sentence has the subject of "the package management tool Guix" and the other "the Guix System".  You were correct in observing that the suggestion confused the meaning of "Guix".  Good catch!

2. The use of "operating system" is inappropriate

The v04 suggestion used "operating system" only because the current manual (bf53001) says in Section 1: Introduction, "If, instead, you want to install the complete GNU operating system..." before linking to "...how to install Guix System on a machine."

I have changed the patch set to say,

"If, instead, you want to install the complete, standalone GNU system distribution..."

This is based off the Section 1: Introduction which calls Guix System a distribution, "...or you can use [Guix] as a standalone operating system distribution, 'Guix System'" and Section 1.2: GNU Distribution which says, "we refer to the standalone distribution as Guix System."

I'm not sure if I've responded to all of your concerns here.  Have I missed any?

 > I would not address Hurd here at all.  Hurd support would be important
 > and is promising, but documentation for it should come after it works on
 > more than a Childhurd.

You say, "I would not address Hurd *here*" which implies it's valid to address Hurd elsewhere.  What's the criteria for deciding whether to address Hurd and how are the reasons I inadequate?

Here are the reasons I gave previously for why we should continue documenting Hurd support:

- The manual already documents Hurd support
- Core developers have published the statement, "running on the Hurd was always a goal for Guix"
- Guix can run on Hurd
- Code exists in the main branch for Hurd support

 > > No mention of 'guix-install.sh' is made on that page.
 >
 > I wanted to give an example what I mean, not a suggestion.

I don't understand what you mean then.  The exchange quoted here was part of the "Guix" versus "Guix System" discussion above.  Have the updates I've made there addressed this point?

 > >> 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.
 >
 > Probably a guix pack of the guix package would run, but Debian’s
 > guile-fibers is not accepted, if I don’t misunderstand.

What I ask myself is, "Is this a problem or a detail?"  I know that probably sounds stupid.  However, the question is whether Guix can be installed on Hurd.  The answer is, Guix can be installed on Hurd.  Everything else, therefore, including guile-fibers or which Hurd, while important in other contexts, is not important to this issue.

 > > […]
 > >> >> 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.
 >
 > Ubuntu should not get the credits for what Debian is doing.  The current
 > wording “Debian or a derivative such as Ubuntu” is fairer and equally
 > clear.

Ensuring fairness is everyone's responsiblity.  I respect you for accepting this and speaking up.  I understand that you're concerned about proper attribution.

AFAIK, Ubuntu gives clear credit to Debian.  For example, the Ubuntu website says, "Debian is the rock on which Ubuntu is built."  https://ubuntu.com/community/governance/debian They give similarly clear statements elsewhere, too.

My understanding is that many distros call themselves "based on Ubuntu", "built upon Ubuntu", or list Ubuntu as "upstream" because they use packages that are, at minimum, distributed by Ubuntu.  That adds value also deserving of credit and which is separate from the value added by Debian.  Also, we must not overlook that Debian is itself built upon the work of others, many of whom are not associated with Debian and may not even be aware Debian packages or distributes their work.  This is all possible and just because of Free Software.  One of the four freedoms is the right to distribute unmodified copies.  It depends on the license terms, or lack thereof, whether explicit credit needs to be given.  I've not heard of Ubuntu violating any license terms or other legal restrictions requiring attribution.

Am I missing something?

 > >> Better not change the wording?  I believe enabling substitutes is not
 > >> the default.

You are correct!  I misunderstood the current manual and wrote that misunderstanding into my suggested changes.  I have updated the suggested changes.  Thank you for catching this!

 > I agree with you now that the wording can be simplified, except it must be rewritten to that disabling substitutes is an option that is not the default.

The term "substitute" is given in the Section 1 Introduction.  However, since it's jargon and this is a different chapter, I think it prudent to repeat the definition again as a reminder.

The 'guix-install.sh' script uses the term "pre-built package binaries" instead of "substitute":

"Permit downloading pre-built package binaries from the project's build farms? [Y/n]"

I propose the following.  The intent is to match the script's language so that readers may understand the consequences of a 'Y' or 'n' choice.  The best place to do this would be in the prompt.  However, documenting consequences in the manual seems a reasonable compromise which makes the prompt concise and allows us to link to the "On Trusting Binaries" section.

+By default, 'guix-install.sh' will configure Guix to download pre-built
+package binaries, called @dfn{substitutes} (@pxref{Substitutes}), from
+the project's build farms.  If you choose not to permit this, Guix will
+build @emph{everything} from source, making each installation and
+upgrade very expensive.  @xref{On Trusting Binaries} for a discussion of
+why you may want to build packages from source.

 > Otherwise LGTM.  Could you send another diff?

Gladly.  I reviewed our past messages and tried to document all the relevant changes in the commit messages.

[-- Attachment #2: 0001-doc-Simplify-installation-instructions.patch --]
[-- Type: application/octet-stream, Size: 14587 bytes --]

From 3bd6b96f2829130d677702fba69bff37ae5ae483 Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Sun, 24 Mar 2024 10:02:40 +0100
Subject: [PATCH 1/3] doc: Simplify installation instructions

* doc/guix.texi (Installation):
- Move the definition of "foreign distro" out of quotation
- Repeat overwrite warning
- Remove superfluous commentary

* doc/guix.texi (Binary Installation):
- Clarify that installing on a foreign distro has two methods: using
  packaged binaries and building from source
- Add cross reference to "Building from Git"
- Move the foreign distro installation instructions out of quotation
- Move directions for 'guix-install.sh' after instructions to use
  distribution-specific package managers
- Specify "distributions" as "GNU/Linux distributions"
- Add GnuPG as a requirement for 'guix-install.sh'
- Add comma after "Likewise"
- Remove redundant instructions to use 'guix-install.sh'
- Split the requirements between system requirements for binary
  installations, GNU/Linux or GNU/Hurd, and requirements for running
  'guix-install.sh'
- Clarify that 'guix-install.sh' guides users through the steps
- Summarize the steps 'guix-install.sh' follows rather than try to
  detail them
- Make explicit that the 'guix-install.sh' default is to download
  substitutes
- Emphasize that the substitute authorization code is an example and
  may need modification

Link: <https://lists.gnu.org/archive/html/guix-devel/2024-03/msg00023.html>
---
 doc/guix.texi | 280 +++++++++-----------------------------------------
 1 file changed, 50 insertions(+), 230 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index eda4084e7f..2b4d3585ba 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
+@cindex Guix System
+You can install the package management tool Guix on top of an existing
+GNU/Linux or GNU/Hurd system@footnote{Hurd support is currently
+limited.}, referred to as a @dfn{foreign distro}.  If, instead, you want
+to install the complete, standalone GNU system distribution,
+@dfn{Guix@tie{}System}, @pxref{System Installation}.  This section is
+concerned only with the installation of Guix on a foreign distro.
 
-@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,210 +731,68 @@ 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
 @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 Downloading and extracting the binary tarball
+@item Setting up the build daemon
+@item Making the ‘guix’ command available to non-root users
+@item Configuring 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
+# wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+# chmod +x guix-install.sh
+# ./guix-install.sh
 @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, 'guix-install.sh' will configure Guix to download pre-built
+package binaries, called @dfn{substitutes} (@pxref{Substitutes}), from
+the project's build farms.  If you choose not to permit this, Guix will
+build @emph{everything} from source, making each installation and
+upgrade very expensive.  @xref{On Trusting Binaries} for a discussion of
+why you may want to build packages from source.
 
-@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, you must authorize them.
+For example,
 
 @example
 # guix archive --authorize < \
@@ -947,45 +800,8 @@ 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.
-
 @node Requirements
 @section Requirements
 
@@ -1179,6 +995,9 @@ Some of them require a lot of storage space to hold VM images.
 
 Again in case of test failures, please send @email{bug-guix@@gnu.org}
 all the details.
+When you're done installing Guix, @pxref{Application Setup} for extra
+configuration you might need, and @ref{Getting Started} for your first
+steps!
 
 @node Setting Up the Daemon
 @section Setting Up the Daemon
@@ -17649,6 +17468,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
-- 
2.41.0