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

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

[Matt]

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

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

[Matt]

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

Ugh.  All the patches were not attached to my previous message.  Here are all the patches.

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


[-- Attachment #3: 0002-doc-Move-Requirements-before-Building-from-Git.patch --]
[-- Type: application/octet-stream, Size: 10072 bytes --]

From 280209be877d7f9b29c3540d0ebe4b9f064f70a2 Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Sun, 24 Mar 2024 10:07:37 +0100
Subject: [PATCH 2/3] doc: Move "Requirements" before "Building from Git"

* doc/contributing.texi (doc/guix.texi): Move "Requirements" before "Building
from Git".

Link: <https://lists.gnu.org/archive/html/guix-devel/2024-03/msg00023.html>
---
 doc/contributing.texi | 98 ++++++++++++++++++++++++++++++++++++++++++
 doc/guix.texi         | 99 -------------------------------------------
 2 files changed, 98 insertions(+), 99 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index f5b01f42fd..565be5c6b9 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -20,6 +20,7 @@ on-line communication; they can use any name or pseudonym of their
 choice.
 
 @menu
+* Requirements::                Software needed to build and run Guix.
 * Building from Git::           The latest and greatest.
 * Running Guix Before It Is Installed::  Hacker tricks.
 * The Perfect Setup::           The right tools.
@@ -36,6 +37,103 @@ choice.
 * Translating Guix::            Make Guix speak your native language.
 @end menu
 
+@node Requirements
+@section Requirements
+
+This section lists requirements when building Guix from source.  The
+build procedure for Guix is the same as for other GNU software, and is
+not covered here.  Please see the files @file{README} and @file{INSTALL}
+in the Guix source tree for additional details.
+
+@cindex official website
+GNU Guix is available for download from its website at
+@url{https://www.gnu.org/software/guix/}.
+
+GNU Guix depends on the following packages:
+
+@itemize
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x,
+version 3.0.3 or later;
+@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
+0.1.0 or later;
+@item
+@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
+Preparations, how to install the GnuTLS bindings for Guile,,
+gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
+@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
+until version 3.7.8 included.};
+@item
+@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
+or later;
+@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
+version 0.1.0 or later;
+@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
+@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
+@item
+@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
+or later;
+@item @uref{https://git-scm.com, Git} (yes, both!);
+@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
+4.3.0 or later;
+@item @url{https://www.gnu.org/software/make/, GNU Make}.
+@end itemize
+
+The following dependencies are optional:
+
+@itemize
+@item
+@c Note: We need at least 0.13.0 for #:nodelay.
+Support for build offloading (@pxref{Daemon Offload Setup}) and
+@command{guix copy} (@pxref{Invoking guix copy}) depends on
+@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
+version 0.13.0 or later.
+
+@item
+@uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
+compression and decompression in @command{guix publish} and for
+substitutes (@pxref{Invoking guix publish}).
+
+@item
+@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
+the @code{crate} importer (@pxref{Invoking guix import}).
+
+@item
+@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
+the @code{go} importer (@pxref{Invoking guix import}) and for some of
+the ``updaters'' (@pxref{Invoking guix refresh}).
+
+@item
+When @url{http://www.bzip.org, libbz2} is available,
+@command{guix-daemon} can use it to compress build logs.
+@end itemize
+
+Unless @option{--disable-daemon} was passed to @command{configure}, the
+following packages are also needed:
+
+@itemize
+@item @url{https://gnupg.org/, GNU libgcrypt};
+@item @url{https://sqlite.org, SQLite 3};
+@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
+C++11 standard.
+@end itemize
+
+@cindex state directory
+@cindex localstatedir
+@cindex system configuration directory
+@cindex sysconfdir
+When configuring Guix on a system that already has a Guix installation,
+be sure to specify the same state directory as the existing installation
+using the @option{--localstatedir} option of the @command{configure}
+script (@pxref{Directory Variables, @code{localstatedir},, standards,
+GNU Coding Standards}).  Usually, this @var{localstatedir} option is set
+to the value @file{/var}.  The @command{configure} script protects
+against unintended misconfiguration of @var{localstatedir} so you do not
+inadvertently corrupt your store (@pxref{The Store}).  The configuration
+directory should also be configured by setting the @option{--sysconfdir}
+option to the @file{/etc} value, which is the location used by Guix to
+store for example the access control list of authorized machines and the
+definition of offload machines.
+
 @node Building from Git
 @section Building from Git
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 2b4d3585ba..7a3507388d 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -227,7 +227,6 @@ Introduction
 Installation
 
 * Binary Installation::         Getting Guix running in no time!
-* Requirements::                Software needed to build and run Guix.
 * Running the Test Suite::      Testing Guix.
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
@@ -716,7 +715,6 @@ Once installed, Guix can be updated by running @command{guix pull}
 
 @menu
 * Binary Installation::         Getting Guix running in no time!
-* Requirements::                Software needed to build and run Guix.
 * Running the Test Suite::      Testing Guix.
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
@@ -802,103 +800,6 @@ For example,
 @end example
 @end quotation
 
-@node Requirements
-@section Requirements
-
-This section lists requirements when building Guix from source.  The
-build procedure for Guix is the same as for other GNU software, and is
-not covered here.  Please see the files @file{README} and @file{INSTALL}
-in the Guix source tree for additional details.
-
-@cindex official website
-GNU Guix is available for download from its website at
-@url{https://www.gnu.org/software/guix/}.
-
-GNU Guix depends on the following packages:
-
-@itemize
-@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x,
-version 3.0.3 or later;
-@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
-0.1.0 or later;
-@item
-@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
-Preparations, how to install the GnuTLS bindings for Guile,,
-gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
-@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
-until version 3.7.8 included.};
-@item
-@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
-or later;
-@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
-version 0.1.0 or later;
-@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
-@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
-@item
-@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
-or later;
-@item @uref{https://git-scm.com, Git} (yes, both!);
-@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
-4.3.0 or later;
-@item @url{https://www.gnu.org/software/make/, GNU Make}.
-@end itemize
-
-The following dependencies are optional:
-
-@itemize
-@item
-@c Note: We need at least 0.13.0 for #:nodelay.
-Support for build offloading (@pxref{Daemon Offload Setup}) and
-@command{guix copy} (@pxref{Invoking guix copy}) depends on
-@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
-version 0.13.0 or later.
-
-@item
-@uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
-compression and decompression in @command{guix publish} and for
-substitutes (@pxref{Invoking guix publish}).
-
-@item
-@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
-the @code{crate} importer (@pxref{Invoking guix import}).
-
-@item
-@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
-the @code{go} importer (@pxref{Invoking guix import}) and for some of
-the ``updaters'' (@pxref{Invoking guix refresh}).
-
-@item
-When @url{http://www.bzip.org, libbz2} is available,
-@command{guix-daemon} can use it to compress build logs.
-@end itemize
-
-Unless @option{--disable-daemon} was passed to @command{configure}, the
-following packages are also needed:
-
-@itemize
-@item @url{https://gnupg.org/, GNU libgcrypt};
-@item @url{https://sqlite.org, SQLite 3};
-@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
-C++11 standard.
-@end itemize
-
-@cindex state directory
-@cindex localstatedir
-@cindex system configuration directory
-@cindex sysconfdir
-When configuring Guix on a system that already has a Guix installation,
-be sure to specify the same state directory as the existing installation
-using the @option{--localstatedir} option of the @command{configure}
-script (@pxref{Directory Variables, @code{localstatedir},, standards,
-GNU Coding Standards}).  Usually, this @var{localstatedir} option is set
-to the value @file{/var}.  The @command{configure} script protects
-against unintended misconfiguration of @var{localstatedir} so you do not
-inadvertently corrupt your store (@pxref{The Store}).  The configuration
-directory should also be configured by setting the @option{--sysconfdir}
-option to the @file{/etc} value, which is the location used by Guix to
-store for example the access control list of authorized machines and the
-definition of offload machines.
-
 @node Running the Test Suite
 @section Running the Test Suite
 
-- 
2.41.0


[-- Attachment #4: 0003-doc-Move-Running-the-Test-Suite-after-Building-from-.patch --]
[-- Type: application/octet-stream, Size: 9725 bytes --]

From c88873224a6c5bd4c5e7d29aea234b480a14f250 Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Sun, 24 Mar 2024 10:08:49 +0100
Subject: [PATCH 3/3] doc: Move "Running the Test Suite" after "Building from
 Git"

* doc/contributing.texi (doc/guix.texi): Move "Running the Test
Suite" after "Building from Git"

Link: <https://lists.gnu.org/archive/html/guix-devel/2024-03/msg00023.html>
---
 doc/contributing.texi | 98 +++++++++++++++++++++++++++++++++++++++++++
 doc/guix.texi         | 98 -------------------------------------------
 2 files changed, 98 insertions(+), 98 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 565be5c6b9..ee19418cdb 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -22,6 +22,7 @@ choice.
 @menu
 * Requirements::                Software needed to build and run Guix.
 * Building from Git::           The latest and greatest.
+* Running the Test Suite::      Testing Guix.
 * Running Guix Before It Is Installed::  Hacker tricks.
 * The Perfect Setup::           The right tools.
 * Alternative Setups::          Other possible tools that do the job.
@@ -301,6 +302,103 @@ example, the @code{origin} record) has changed, and all of guix needs
 to be recompiled to take that change into account.  To do so, run
 @command{make clean-go} followed by @command{make}.
 
+@node Running the Test Suite
+@section Running the Test Suite
+
+@cindex test suite
+After a successful @command{configure} and @code{make} run, it is a good
+idea to run the test suite.  It can help catch issues with the setup or
+environment, or bugs in Guix itself---and really, reporting test
+failures is a good way to help improve the software.  To run the test
+suite, type:
+
+@example
+make check
+@end example
+
+Test cases can run in parallel: you can use the @code{-j} option of
+GNU@tie{}make to speed things up.  The first run may take a few minutes
+on a recent machine; subsequent runs will be faster because the store
+that is created for test purposes will already have various things in
+cache.
+
+It is also possible to run a subset of the tests by defining the
+@code{TESTS} makefile variable as in this example:
+
+@example
+make check TESTS="tests/store.scm tests/cpio.scm"
+@end example
+
+By default, tests results are displayed at a file level.  In order to
+see the details of every individual test cases, it is possible to define
+the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
+
+@example
+make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
+@end example
+
+The underlying SRFI 64 custom Automake test driver used for the 'check'
+test suite (located at @file{build-aux/test-driver.scm}) also allows
+selecting which test cases to run at a finer level, via its
+@option{--select} and @option{--exclude} options.  Here's an example, to
+run all the test cases from the @file{tests/packages.scm} test file
+whose names start with ``transaction-upgrade-entry'':
+
+@example
+export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
+make check TESTS="tests/packages.scm"
+@end example
+
+Those wishing to inspect the results of failed tests directly from the
+command line can add the @option{--errors-only=yes} option to the
+@code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
+Automake makefile variable, as in:
+
+@example
+make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
+@end example
+
+The @option{--show-duration=yes} option can be used to print the
+duration of the individual test cases, when used in combination with
+@option{--brief=no}:
+
+@example
+make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
+@end example
+
+@xref{Parallel Test Harness,,,automake,GNU Automake} for more
+information about the Automake Parallel Test Harness.
+
+Upon failure, please email @email{bug-guix@@gnu.org} and attach the
+@file{test-suite.log} file.  Please specify the Guix version being used
+as well as version numbers of the dependencies (@pxref{Requirements}) in
+your message.
+
+Guix also comes with a whole-system test suite that tests complete
+Guix System instances.  It can only run on systems where
+Guix is already installed, using:
+
+@example
+make check-system
+@end example
+
+@noindent
+or, again, by defining @code{TESTS} to select a subset of tests to run:
+
+@example
+make check-system TESTS="basic mcron"
+@end example
+
+These system tests are defined in the @code{(gnu tests @dots{})}
+modules.  They work by running the operating systems under test with
+lightweight instrumentation in a virtual machine (VM).  They can be
+computationally intensive or rather cheap, depending on whether
+substitutes are available for their dependencies (@pxref{Substitutes}).
+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.
+
 @node Running Guix Before It Is Installed
 @section Running Guix Before It Is Installed
 
diff --git a/doc/guix.texi b/doc/guix.texi
index 7a3507388d..7b2cf0f193 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -227,7 +227,6 @@ Introduction
 Installation
 
 * Binary Installation::         Getting Guix running in no time!
-* Running the Test Suite::      Testing Guix.
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
 * Application Setup::           Application-specific setup.
@@ -715,7 +714,6 @@ Once installed, Guix can be updated by running @command{guix pull}
 
 @menu
 * Binary Installation::         Getting Guix running in no time!
-* Running the Test Suite::      Testing Guix.
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
 * Application Setup::           Application-specific setup.
@@ -800,102 +798,6 @@ For example,
 @end example
 @end quotation
 
-@node Running the Test Suite
-@section Running the Test Suite
-
-@cindex test suite
-After a successful @command{configure} and @code{make} run, it is a good
-idea to run the test suite.  It can help catch issues with the setup or
-environment, or bugs in Guix itself---and really, reporting test
-failures is a good way to help improve the software.  To run the test
-suite, type:
-
-@example
-make check
-@end example
-
-Test cases can run in parallel: you can use the @code{-j} option of
-GNU@tie{}make to speed things up.  The first run may take a few minutes
-on a recent machine; subsequent runs will be faster because the store
-that is created for test purposes will already have various things in
-cache.
-
-It is also possible to run a subset of the tests by defining the
-@code{TESTS} makefile variable as in this example:
-
-@example
-make check TESTS="tests/store.scm tests/cpio.scm"
-@end example
-
-By default, tests results are displayed at a file level.  In order to
-see the details of every individual test cases, it is possible to define
-the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
-
-@example
-make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
-@end example
-
-The underlying SRFI 64 custom Automake test driver used for the 'check'
-test suite (located at @file{build-aux/test-driver.scm}) also allows
-selecting which test cases to run at a finer level, via its
-@option{--select} and @option{--exclude} options.  Here's an example, to
-run all the test cases from the @file{tests/packages.scm} test file
-whose names start with ``transaction-upgrade-entry'':
-
-@example
-export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
-make check TESTS="tests/packages.scm"
-@end example
-
-Those wishing to inspect the results of failed tests directly from the
-command line can add the @option{--errors-only=yes} option to the
-@code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
-Automake makefile variable, as in:
-
-@example
-make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
-@end example
-
-The @option{--show-duration=yes} option can be used to print the
-duration of the individual test cases, when used in combination with
-@option{--brief=no}:
-
-@example
-make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
-@end example
-
-@xref{Parallel Test Harness,,,automake,GNU Automake} for more
-information about the Automake Parallel Test Harness.
-
-Upon failure, please email @email{bug-guix@@gnu.org} and attach the
-@file{test-suite.log} file.  Please specify the Guix version being used
-as well as version numbers of the dependencies (@pxref{Requirements}) in
-your message.
-
-Guix also comes with a whole-system test suite that tests complete
-Guix System instances.  It can only run on systems where
-Guix is already installed, using:
-
-@example
-make check-system
-@end example
-
-@noindent
-or, again, by defining @code{TESTS} to select a subset of tests to run:
-
-@example
-make check-system TESTS="basic mcron"
-@end example
-
-These system tests are defined in the @code{(gnu tests @dots{})}
-modules.  They work by running the operating systems under test with
-lightweight instrumentation in a virtual machine (VM).  They can be
-computationally intensive or rather cheap, depending on whether
-substitutes are available for their dependencies (@pxref{Substitutes}).
-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!
-- 
2.41.0

[bug#69977] [PATCH] doc: doc-Simplify installation instructions

[pelzflorian (Florian Pelz)]

Hi Matt, mostly looks good to me.

Matt <matt@excalamus.com> writes:
>---- On Sat, 16 Mar 2024 15:05:13 +0100  pelzflorian (Florian Pelz)  wrote ---
>>>> Either
>>>> say “You can install the Guix package management tool and distribution”
>>>> or “You can install Guix”.
>>> You can install the Guix package management tool on top of an
>> 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.[…]
> You can install the package management tool Guix on top of an

Looking at it with fresh eyes myself, your wording is OK.  Even though I
still think you have a misunderstanding of the term distribution, there
is no reason for me to insist the term distribution must be explained
here.


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

I like that you added the word “standalone”.  But I prefer the old
ordering where this sentence comes after “This section +is concerned
with the installation of Guix on a foreign distro.”


Looking at how to make an install tarball for Hurd, I noticed that you
removed these important instructions for building the tarball:

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

The tarball is needed by guix-install.sh, so the instructions for
building it should stay, because it is what your recommended
guix-install.sh uses.  Please keep the instructions for this reason.

No such tarball is released for GNU Hurd yet, and when I tried to build
it for GNU Hurd, it fails, because guile-git cannot be built.  Note that
it is possible to instead cross-compile a pack for Hurd, using
“--target=i586-pc-gnu” instead of “-s i586-gnu”, even though I have not
tested if it can be used.  Also note that Hurd is quite crashy.  Better
just not mention it here.



>> 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.
> […]
> 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.

I believe “Debian or a derivative such as Ubuntu” is a better wording
than “Debian and Ubuntu-based systems”, despite some Ubuntu derivatives
not mentioning Debian or users being aware only of Ubuntu.


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

Good!


> * 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"

I think this comma (“Likewise, on openSUSE:”) should not be added, since
it does not improve understanding, but it is not really important.


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

Well these details are good for reviewers, but the commit message is
intended for readers of “git log”.  Better keep it short like the other
commits you can view with “cd ~/src/guix; git log doc”.

Could you send another patch without mentioning the Hurd, or do you see
a way to actually run Guix on a foreign GNU/Hurd distribution that you
can document?

Regards,
Florian

[bug#69977] [PATCH] doc: doc-Simplify installation instructions

[Matt]

 ---- On Mon, 25 Mar 2024 20:26:17 +0100  pelzflorian (Florian Pelz)  wrote --- 
 > Hi Matt, mostly looks good to me.

That's good to hear!  I would like to address your comments in an updated patch set.  Unfortunately, I'm struggling to do that.  Between my last message and this one, life happened and changes have been made to guix.texi that prevent the application of patch set you've commented on.  I've already spent several hours already trying to figure out a better way to revise my suggestions than retyping everything by hand from HEAD.  How can git help me in this situation?  Or, am I better off scrapping my old patches and just retyping the changes?

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

[pelzflorian (Florian Pelz)]

Thank you Maxim for the updating and pushing, so that future changes to
the install instructions will be based on Matt’s version.

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
> Hi Matt et al.,
>
> Matt <matt@excalamus.com> writes:
>
>> Ugh.  All the patches were not attached to my previous message.  Here are all the patches.
>
> Excellent work.  Thanks for Florian and others for the comments.  I've
> now merged the 3 patches as-is, except for a trivial change to use @file
> to decorate 'guix-install.sh' in the first one.

I have followed up by:

commit 80d364b92b73e6757f2c9a703582519655bb4f5c (HEAD -> master)
Author: Florian Pelz <pelzflorian@pelzflorian.de>
Date:   Sun Apr 7 09:39:45 2024 +0200

    doc: Restore some of the old installation instructions.
    
    Follow-up to 227e0469dbfec7e47b57d824dcf45a04ac4026c9.
    
    * doc/guix.texi (Binary Installation):
    Revert wording for installing the Debian package.
    Restore how to reproduce the binary tarball.
    Restore how to uninstall.
    (copying): Add copyright notice for Matthew Trzcinski.
    
    Change-Id: Ib74199e39bd7a50ac58045f2bc47f61fc04eacb9

Regards,
Florian

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

[Maxim Cournoyer]

Hi,

Le 7 avril 2024 04:30:57 GMT-04:00, "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> a écrit :
>Thank you Maxim for the updating and pushing, so that future changes to
>the install instructions will be based on Matt’s version.
>
>Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:
>> Hi Matt et al.,
>>
>> Matt <matt@excalamus.com> writes:
>>
>>> Ugh.  All the patches were not attached to my previous message.  Here are all the patches.
>>
>> Excellent work.  Thanks for Florian and others for the comments.  I've
>> now merged the 3 patches as-is, except for a trivial change to use @file
>> to decorate 'guix-install.sh' in the first one.
>
>I have followed up by:
>
>commit 80d364b92b73e6757f2c9a703582519655bb4f5c (HEAD -> master)
>Author: Florian Pelz <pelzflorian@pelzflorian.de>
>Date:   Sun Apr 7 09:39:45 2024 +0200
>
>    doc: Restore some of the old installation instructions.
>    
>    Follow-up to 227e0469dbfec7e47b57d824dcf45a04ac4026c9.
>    
>    * doc/guix.texi (Binary Installation):
>    Revert wording for installing the Debian package.
>    Restore how to reproduce the binary tarball.
>    Restore how to uninstall.
>    (copying): Add copyright notice for Matthew Trzcinski.

 Sounds good; thank you for the follow-up!

Maxim

[bug#70823] [PATCH] Re: Creating a documentation team?

[Matt]

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


 ---- On Wed, 01 May 2024 22:34:05 +0200  Ludovic Courtès  wrote --- 

 > I’ve added the documentation team locally.  I’ll push shortly and let
 > you add yourselves.

 See attached patch.  Happy to continue helping and learning more about Guix :)

[-- Attachment #2: 0001-teams-Add-to-the-documentation-team.patch --]
[-- Type: application/octet-stream, Size: 769 bytes --]

From fe1ccf9bce9e29e3f623c5f99258281ae1e3e29d Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Tue, 7 May 2024 19:40:33 +0200
Subject: [PATCH] teams: Add to the documentation team.

* etc/teams.scm (Matthew Trzcinski): Add to documentation team.
---
 etc/teams.scm | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/etc/teams.scm b/etc/teams.scm
index 0dc2325c3e..6cf29b74cc 100755
--- a/etc/teams.scm
+++ b/etc/teams.scm
@@ -734,6 +734,10 @@ (define-member (person "Adam Faiz"
                        "adam.faiz@disroot.org")
   games)
 
+(define-member (person "Matthew Trzcinski"
+                       "matt@excalamus.com")
+  documentation)
+
 \f
 (define (find-team name)
   (or (hash-ref %teams (string->symbol name))
-- 
2.41.0

bug#70823: [PATCH] Re: Creating a documentation team?

[pelzflorian (Florian Pelz)]

Matt <matt@excalamus.com> writes:
>  See attached patch.  Happy to continue helping and learning more about Guix :)

Pushed as 9288654773a110156e0bb6fc703a9c24f5bfc527.

I have slightly adjusted the commit message to have the same style as
prior changes to etc/teams.scm.

This means you will get Cc’d on changes to the listed .texi files and
related files, if the sender of the change used git send-email.  Feel
free to comment on such mails.

Thank you for joining,
Florian