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

[Ludovic Courtès]

Hi,

"pelzflorian (Florian Pelz)"  skribis:

> Otherwise LGTM.  Could you send another diff?  Would a commit message
> like this be okay:
>
> doc: Simplify installation instructions.
>
> * doc/guix.texi (Installation): Direct readers towards the installation
> script.  Remove superfluous commentary.

I’d recommend sending it to guix-patches to make it more visible.

Ludo’.

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

[pelzflorian (Florian Pelz)]

Hello Matt and thank you for your precise wording.  You have made clear
the differences:

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

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.


> 3) compile a list of deferred
> actions, 4) compile a list of deferred topics, and 5) address points 3
> and 4 according to 2.
>
>  On Mon, 11 Mar 2024 16:54:01 +0100  pelzflorian (Florian Pelz)  wrote ---
>> Yes, however the removal means that we should move the sections
>>
>> * 2.2 Requirements
>> * 2.3 Running the Test Suite
>>
>> to the Contributing manual in doc/contributing.texi.  WDYT?  You said,
>> it could be a separate discussion, but in my opinion it would be part of
>> the same patch.
>
> I was thinking of the opposite, of moving "Building from Git" into
> Installation.  What you say makes more sense and I agree.  Since the
> suggested patch is already quite complex, I have not added moving
> Sections 2.2 and 2.3 to the changes.  I propose we make the move in a
> separate commit.

Yes, it should probably be a separate commit, to make it possible to
revert it separately.


>> > +@cindex foreign distro
>> > +@cindex Guix System
>>
>> “@cindex Guix System” is inappropriate, because instructions on Guix
>> System are not here.
>
> Removed.  Good catch!
>
>> > +You can install the Guix package management tool on top of an existing
>> > +GNU/Linux or GNU/Hurd system@footnote{Currently only the Linux-libre
>> > +kernel is fully supported. […]
>>
>> No.
>>
>> First of all, using guix-install.sh as per your instructions, one
>> installs the Guix distribution *and* package management tool.  Either
>> say “You can install the Guix package management tool and distribution”
>> or “You can install Guix”.
>
> I'm afraid I don't follow.  Where do you see the suggested changes
> confusing the installation process for Guix as a distribution and Guix
> as a package management tool?
>
> The sentence you quote is the suggested first sentence for the Chapter
> 2: Installation.  The complete sentence reads,
>
> "You can install the Guix package management tool on top of an
> existing GNU/Linux or GNU/Hurd system(1), referred to as a "foreign
> distro", or as a standalone operating system distribution, the "Guix
> System"."
>
> It literally says Guix is a package manager or a distribution.

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

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.



> No
> mention of 'guix-install.sh' is made on that page.

I wanted to give an example what I mean, not a suggestion.


>
> The current "introduction" to Chapter 2: Installation is this:
>
> "Note: We recommend the use of this  to
> install Guix on top of a running GNU/Linux system, thereafter called a
> foreign distro. The script automates the download, installation, and
> initial configuration of Guix. It should be run as the root user."
>
> https://guix.gnu.org/en/manual/devel/en/html_node/Installation.html
>
> Maybe the diff didn't apply correctly?  Maybe it's confusing how the
> Texinfo syntax puts the footnote markup in the middle of the source
> sentence, even though footnotes render at the bottom of the page?
>
>> Next, I believe Guix cannot currently be built on existing GNU/Hurd
>> systems, because guile-fibers does not work.  I do not really know
>> enough, but I would not mention Hurd support.
>
> The are two issues here, what is said and what should be said.
>
> Regarding what is said, the section we're talking about is for
> installing not building.  You *can* install the Guix package
> management tool on top of an existing GNU/Hurd system.

Probably a guix pack of the guix package would run, but Debian’s
guile-fibers is not accepted, if I don’t misunderstand.


> […]
>> >> Similarly, IMO the nuances are more appropriate in the old wording
>> 

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

[Matt]

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

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

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

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

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

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

Removed.  Good catch!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Excellent point: the package manager is indeed supported on non-free
distros.  I had carelessly copied the footnote, and the text containing this
issue, 

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

[Vagrant Cascadian]

On 2024-03-11, John Kehayias wrote:
> On Sunday, March 10th, 2024 at 9:58 PM, Vagrant Cascadian 
>  wrote:
>> On 2024-03-10, Suhail Singh wrote:
>> 
>> > Vagrant Cascadian vagr...@debian.org writes:
>> > 
>> > > but "guix pull" does not update the running guix-daemon;
>> > 
>> > Just to be clear, however, if one were to do =sudo -i guix pull=
>> > instead, followed by =systemctl restart guix-daemon.service= it /would/
>> > update the running guix-daemon on Debian, correct? Or is that not the
>> > case?
>> 
>> 
>> No, out of the box guix-daemon is provided by the Debian guix package.
>> 
>
> That means the instructions to update the guix daemon in the manual,
> 
> is incorrect or doesn't work? Or am I misunderstanding what you meant
> here?

I presume it works fine if you install from the GNU Guix binary tarball,
but not with the Debian guix packages without configuring systemd or
whatever init system to use the guix daemon provided by "guix pull".


> (I know in the past some discussions have come up about older
> guix-daemon on foreign distros, presumably because the packages there
> don't get updated and a user wouldn't think to upgrade guix
> separately? But it seems you are saying you can't upgrade without
> modifying the e.g. systemd service definition? This is also important
> for security updates to guix itself, of course.)

As with other packages in Debian, security updates would, at least in
theory, be uploaded via Debian's security update process, like any other
package in Debian... unless you actually configure it to work like the
instructions above (e.g. add a systemd override).

At least once, I pulled patches from guix upstream into the Debian
package to resolve security issues in the Debian packages.

Just to be absolutely clear here, "guix pull" and whatnot works fine;
that part of upgrading is no different than Guix System or Guix Binary
installation on a foreign distro.


live well,
  vagrant

>> > In other words, on Debian, does the systemd unit reference
>> > =/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?
>> 
>> 
>> But you could provide an override pointing at whatever guix-daemon you
>> want, of course! :)
>> 
>> Once you do that, you may as well remove the Debian packaged guix,
>> although users that have not yet run "guix pull" would need to guess
>> where to find guix, as there will be no guix on PATH.


signature.asc
Description: PGP signature

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

[pelzflorian (Florian Pelz)]

Hi Matt.  I would almost want to push your changes, but we still
disagree on some wordings.

Also,

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

Yes, however the removal means that we should move the sections

* 2.2 Requirements
* 2.3 Running the Test Suite

to the Contributing manual in doc/contributing.texi.  WDYT?  You said,
it could be a separate discussion, but in my opinion it would be part of
the same patch.


> +@cindex foreign distro
> +@cindex Guix System

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


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

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


>> You suggested in your mail:
>>
>> Matt m...@excalamus.com> writes:
>> > Readers interested in those details may read the code for 
>> > 'guix-install.sh'.
>>
>> Could you add this suggestion to your diff?
>
> I don't see that as relevant to the reader.  The ability to read the
> source is implicit in it being provided, which it is.

Yes, you are right.


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

“remove superfluous commentary” could be part of a commit message for
your changes, if you agree.


> What do you think is lost that isn't captured by the following bulleted list?
>
> +The script guides you through the following:
> +@itemize
> +@item Download and extract the binary tarball
> +@item Set up the build daemon
> +@item Make the ‘guix’ command available to non-root users
> +@item Configure substitute servers
> +@end itemize

The list is fine.


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

This could be:

described later (@pxref{Building from Git}).


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

:D  However, please also do not change:

> -Likewise on openSUSE:
> +Likewise, on openSUSE:



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

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

[John Kehayias]

Hi vagrant,


On Sunday, March 10th, 2024 at 9:58 PM, Vagrant Cascadian  
wrote:

> 
> 
> On 2024-03-10, Suhail Singh wrote:
> 
> > Vagrant Cascadian vagr...@debian.org writes:
> > 
> > > but "guix pull" does not update the running guix-daemon;
> > 
> > Just to be clear, however, if one were to do =sudo -i guix pull=
> > instead, followed by =systemctl restart guix-daemon.service= it /would/
> > update the running guix-daemon on Debian, correct? Or is that not the
> > case?
> 
> 
> No, out of the box guix-daemon is provided by the Debian guix package.
> 

That means the instructions to update the guix daemon in the manual, 
 is 
incorrect or doesn't work? Or am I misunderstanding what you meant here?

(I know in the past some discussions have come up about older guix-daemon on 
foreign distros, presumably because the packages there don't get updated and a 
user wouldn't think to upgrade guix separately? But it seems you are saying you 
can't upgrade without modifying the e.g. systemd service definition? This is 
also important for security updates to guix itself, of course.)

> > In other words, on Debian, does the systemd unit reference
> > =/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?
> 
> 
> But you could provide an override pointing at whatever guix-daemon you
> want, of course! :)
> 
> Once you do that, you may as well remove the Debian packaged guix,
> although users that have not yet run "guix pull" would need to guess
> where to find guix, as there will be no guix on PATH.
> 
> 
> live well,
> vagrant

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

[Vagrant Cascadian]

On 2024-03-10, Suhail Singh wrote:
> Vagrant Cascadian  writes:
>> but "guix pull" does not update the running guix-daemon;
>
> Just to be clear, however, if one were to do =sudo -i guix pull=
> instead, followed by =systemctl restart guix-daemon.service= it /would/
> update the running guix-daemon on Debian, correct?  Or is that not the
> case?

No, out of the box guix-daemon is provided by the Debian guix package.


> In other words, on Debian, does the systemd unit reference
> =/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?

But you could provide an override pointing at whatever guix-daemon you
want, of course! :)

Once you do that, you may as well remove the Debian packaged guix,
although users that have not yet run "guix pull" would need to guess
where to find guix, as there will be no guix on PATH.


live well,
  vagrant


signature.asc
Description: PGP signature

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

[Suhail Singh]

Vagrant Cascadian  writes:

> but "guix pull" does not update the running guix-daemon;

Just to be clear, however, if one were to do =sudo -i guix pull=
instead, followed by =systemctl restart guix-daemon.service= it /would/
update the running guix-daemon on Debian, correct?  Or is that not the
case?  In other words, on Debian, does the systemd unit reference
=/var/guix/profiles/per-user/root/current-guix/bin/guix-daemon= ?

-- 
Suhail

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

[Vagrant Cascadian]

On 2024-03-10, m...@excalamus.com wrote:
>  On Wed, 06 Mar 2024 22:29:23 +0100  Vagrant Cascadian  wrote ---
>> As the one who packaged and maintains guix in Debian...
>
> Thank you for doing this work!
>
>> The guix-daemon should continue to work from the packaged version, although 
>> as guix develops more and more features; how long an old version can be 
>> expected to continue to work remains an open question.
>
> I was under the impression that Guix installed through a foreign package 
> manager is able to update with 'guix pull'.  This is what the current 
> documentation says,
>
> "If you’re running Debian or a derivative such as Ubuntu, you can instead 
> install the package (it might be a version older than 0.0-git but you can 
> update it afterwards by running ‘guix pull’):"
>
> Is this correct?  Does 'guix pull' update Guix when installed through a 
> foreign package manager?

Yes, with the guix packages provided by Debian, generally I would
recommend doing "guix pull" to get current packages (a lot has changed
since guix 1.4!) ... but "guix pull" does not update the running
guix-daemon; that is not the responsibility of "guix pull".

There is also the classic issue of updating PATH and other environment
variables after the first "guix pull" but that is not unique to the
packages from Debian.

A newly pulled guix should continue to remain compatible with older
guix-daemon to some extent, but it may be missing new guix-daemon
features (and possibly security updates, though those are grounds for
getting it fixed in the package), and possibly someday may no longer be
compatible.

live well,
  vagrant


signature.asc
Description: PGP signature

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

[Matt]

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

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

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

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

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

Thank you for doing this work!

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

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

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

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

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

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

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

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

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

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

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

There are two issues here:

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

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

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

Any takers?

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

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

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

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

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

> IIRC, you are removing the manual installation.

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

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

The challenge in directly responding to your statement is there's not a clear 
cut-off between "install" and "configure."  To install, generally, means 
something like "situate artifacts so the user can make use of them".  Often, 
this is simply addi

Re: doc: Removing much of Binary Installation

[pelzflorian (Florian Pelz)]

Hello Matt and all.  As a more proper review, I first tried
guix-install.sh on a Debian GNU/Hurd VM.  It fails, telling me:

[1709825168.049]: [ INFO ] init system is: sysv-init
[1709825168.059]: [ FAIL ] Unsupported CPU type: i686-AT386

The script guix-install.sh cannot be used on any GNU/Hurd system.
Vagrant’s guix package is missing on Debian GNU/Hurd as well, which is
fine of course, but we should not claim otherwise.  Therefore, could you
change it like the old instructions and only talk about GNU/Linux?

> If, instead, you want to install the complete GNU operating system,
> @pxref{System Installation}.

Maybe better say “complete Guix operating system”?  *complete* GNU
operating system maybe should only be used for GNU/Hurd.

You suggested in your mail:

Matt  writes:
> Readers interested
> in those details may read the code for 'guix-install.sh'.

Could you add this suggestion to your diff?

Further:

IIRC, you are removing the manual installation.  Therefore, the sentence
would have to be removed: “The following sections describe two methods
of installation, binary installation and building from source.”

Also,

Matt  writes:
> - Add commas in appropriate places; after "For...Ubuntu-based
> systems", "Likewise", and the 'or' within the list of substitutes

I’m not a native speaker, but I believe the commas are not necessary.
There particularly does not need to be an Oxford comma before ‘or’.
There could be, but there is no reason to change it.

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

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

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

Regards,
Florian

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

[Vagrant Cascadian]

On 2024-03-06, pelzflorian (Florian Pelz) wrote:
> I don’t feel qualified to judge, but is this the preference?  Arch wiki
> advises against the Arch AUR package: “Therefore, after updating Guix
> once, the AUR advantage really turns into a disadvantage, as there will
> be many unnecessary files in the /usr file tree that are part of the
> Guix AUR package but that are never used by Guix anymore.  Therefore,
> consider using the manual installation.” [0]
>
> The reason of existence for these distribution packages is probably
> similar to the reason why the Binary Installation section exists.

Indeed, after the first guix pull, most of the packaged files are no
longer used.

As the one who packaged and maintains guix in Debian, my main motivation
was and is to have a trust path from debian; mainly not having to
manually verify the signatures of the manual installation method (I
would hazard to guess that the percentage of people who actually do
manually verify signatures is disturbingly small).

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

I cannot say I have done a *great* job at maintaining guix in Debian,
but hopefully at least a passable job. Although there are some annoying
things that probably need to be fixed:

  https://bugs.debian.org/1064748
  a.k.a.
  https://issues.guix.gnu.org/69518

... or backported to Debian stable:

  https://bugs.debian.org/1036304
  https://bugs.debian.org/1038916


I have found a fair number of issues (especially typos!) to fix in
upstream guix as a result of packaging it for Debian, so if nothing
else, it is some quality assurance! :)


live well,
  vagrant


signature.asc
Description: PGP signature

Re: doc: Removing much of Binary Installation

[Suhail Singh]

Suhail Singh  writes:

> FWIW, as an openSUSE Tumbleweed user, I believe Tumbleweed users who
> don't care if there is an easy way to uninstall Guix would be better
> served by using =guix-install.sh= as opposed to =zypper=.

Btw, for completeness, on Tumbleweed, the user needs to take some
additional steps to ensure that restoring a previous Tumbleweed snapshot
doesn't revert Guix state.  Unless I'm misremembering, these steps are
needed regardless of whether =zypper= or =guix-install.sh= was used to
install Guix.

-- 
Suhail

Re: doc: Removing much of Binary Installation

[Suhail Singh]

Matt  writes:

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

FWIW, as an openSUSE Tumbleweed user, I believe Tumbleweed users who
don't care if there is an easy way to uninstall Guix would be better
served by using =guix-install.sh= as opposed to =zypper=.  The issues of
"unnecessary files" applies to Tumbleweed as well (and I believe the
same would be true for Debian as well).

In addition, the manpages can get out of sync.  The reason for the
latter is that doing =sudo -i guix pull --fallback= doesn't generate
manpages.  However, the version of Guix installed via =zypper= does
install manpages (presumably generated via =help2man=).  As such, after
updating Guix, running something like =man guix= results in outdated
manpage being shown.  If Guix installation is done via
=guix-install.sh=, no manpage is shown which, in my opinion, is the
lesser evil.

On a related note, it would help if Guix would install manpages in
addition to infopages.  Not sure if this omission constitutes a bug or a
missing feature.

-- 
Suhail

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

[Matt]

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

Thank you for taking the time to review it!

 > > - Places directions for 'guix-install.sh' after directions to use 
 > > distribution-specific package managers, giving preference to those simpler 
 > > install processes over the more manual 'guix-install.sh' process
 >
 > I don’t feel qualified to judge, but is this the preference?  Arch wiki 
 > advises against the Arch AUR package: “Therefore, after updating Guix once, 
 > the AUR advantage really turns into a disadvantage, as there will be many 
 > unnecessary files in the /usr file tree that are part of the Guix AUR 
 > package but that are never used by Guix anymore.  Therefore, consider using 
 > the manual installation.” [0]
 >
 > [0] https://wiki.archlinux.org/title/Guix

Good question, I wondered about this after I submitted.

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

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

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

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

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

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

 > The reason of existence for these distribution packages is probably similar 
 > to the reason why the Binary Installation section exists.
 >
 > As for the suggested diff where much of Binary Installation gets removed,
 >
 > > -@item
 > > -@cindex substitutes, authorization thereof
 > > -To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
 > > -@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
 > > -authorize them:
 > > -
 > > -@example
 > > -# guix archive --authorize < \
 > > - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
 > > -# guix archive --authorize < \
 > > - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
 > > -@end example
 > > -
 > > -@quotation Note
 > > -If you do not enable substitutes, Guix will end up building
 > > -@emph{everything} from source on your machine, making each installation
 > > -and upgrade very expensive.  @xref{On Trusting Binaries}, for a
 > > -discussion of reasons why one might want do disable substitutes.
 > > -@end quotation
 >
 > I disagree with this chunk.  This must stay.  Not enabling substitutes is an 
 > option in guix-install.sh and the Guix System installer.  Users might want 
 > to enable substitutes later on.

Excellent point.

I have updated the patch with the following:

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


v02-refactor-binary-installation-section.diff
Description: Binary data

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

[pelzflorian (Florian Pelz)]

Thank you Matt for the suggested diff.

Yes, I agree some simplification as you suggested would be beneficial,
so that the description of Binary Installation looks as simple as it
really is.  (In particular, I have witnessed people, to whom I had
suggested Guix, fail at trying Guix because they tried Guix System on a
not libre-friendly laptop, when they could/should have tried Binary
Installation.)

> - Places
> directions for 'guix-install.sh' after directions to use
> distribution-specific package managers, giving preference to those
> simpler install processes over the more manual 'guix-install.sh'
> process

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

The reason of existence for these distribution packages is probably
similar to the reason why the Binary Installation section exists.

As for the suggested diff where much of Binary Installation gets
removed,

> -@item
> -@cindex substitutes, authorization thereof
> -To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
> -@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
> -authorize them:
> -
> -@example
> -# guix archive --authorize < \
> - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
> -# guix archive --authorize < \
> - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
> -@end example
> -
> -@quotation Note
> -If you do not enable substitutes, Guix will end up building
> -@emph{everything} from source on your machine, making each installation
> -and upgrade very expensive.  @xref{On Trusting Binaries}, for a
> -discussion of reasons why one might want do disable substitutes.
> -@end quotation

I disagree with this chunk.  This must stay.  Not enabling substitutes
is an option in guix-install.sh and the Guix System installer.  Users
might want to enable substitutes later on.

Regards,
Florian

[0] https://wiki.archlinux.org/title/Guix