[bug#66577] [PATCH 0/4] Newcomer-oriented improvements to the manual and cookbook

[bug#66577] [PATCH 0/4] Newcomer-oriented improvements to the manual and cookbook

[Ludovic Courtès]

Hello!

These patches reorganize things a bit in the manual to make important
things more easily findable to newcomers, and adds a word of caution
regarding the section on multiple profiles in the cookbook (I’ve seen
newcomers attempt to adopt that software management style on their
systems, when it’s complex and in fact largely unnecessary since the
addition of a fast cache in ‘guix shell’).

Thoughts?

Ludo’.

Ludovic Courtès (4):
  doc: Move “System Troubleshooting Tips” below.
  doc: Mention Guix Home in “Getting Started”.
  doc: cookbook: Suggest ‘guix shell’ as an alternative to multiple
    profiles.
  doc: cookbook: Add cross references to the manual regarding manifests.

 doc/guix-cookbook.texi |  51 ++++----
 doc/guix.texi          | 257 ++++++++++++++++++++---------------------
 2 files changed, 152 insertions(+), 156 deletions(-)


base-commit: a0d2ecde943bd1854ddbb7c0cad35a1fc64dc5ab
-- 
2.41.0

[bug#66577] [PATCH 1/4] doc: Move “System Troubleshooting Tips” below.

[Ludovic Courtès]

So far this section would appear before “Getting Started”.  This moves
it right after “System Configuration”.

* doc/guix.texi (System Troubleshooting Tips): Move after “System
Configuration”.
---
 doc/guix.texi | 245 +++++++++++++++++++++++++-------------------------
 1 file changed, 123 insertions(+), 122 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 3517c95251..8ebf50469e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -185,7 +185,6 @@ Top
 * Introduction::                What is Guix about?
 * Installation::                Installing Guix.
 * System Installation::         Installing the whole operating system.
-* System Troubleshooting Tips::  When things don't go as planned.
 * Getting Started::             Your first steps.
 * Package Management::          Package installation, upgrade, etc.
 * Channels::                    Customizing the package collection.
@@ -194,6 +193,7 @@ Top
 * Utilities::                   Package management commands.
 * Foreign Architectures::       Build for foreign architectures.
 * System Configuration::        Configuring the operating system.
+* System Troubleshooting Tips::  When things don't go as planned.
 * Home Configuration::          Configuring the home environment.
 * Documentation::               Browsing software user manuals.
 * Platforms::                   Defining platforms.
@@ -251,10 +251,6 @@ Top
 * Keyboard Layout and Networking and Partitioning::  Initial setup.
 * Proceeding with the Installation::  Installing.
 
-System Troubleshooting Tips
-
-* Chrooting into an existing system::
-
 Package Management
 
 * Features::                    How Guix will make your life brighter.
@@ -427,6 +423,10 @@ Top
 * Shepherd Services::           A particular type of service.
 * Complex Configurations::      Defining bindings for complex configurations.
 
+System Troubleshooting Tips
+
+* Chrooting into an existing system::
+
 Home Configuration
 
 * Declaring the Home Environment::  Customizing your Home.
@@ -2978,123 +2978,6 @@ Building the Installation Image
 @code{A20-OLinuXino-Lime2} is the name of the board.  If you specify an invalid
 board, a list of possible boards will be printed.
 
-@c *********************************************************************
-@cindex troubleshooting, guix system
-@cindex guix system troubleshooting
-@node System Troubleshooting Tips
-@chapter System Troubleshooting Tips
-
-Guix System allows rebooting into a previous generation should the last
-one be malfunctioning, which makes it quite robust against being broken
-irreversibly.  This feature depends on GRUB being correctly functioning
-though, which means that if for whatever reasons your GRUB installation
-becomes corrupted during a system reconfiguration, you may not be able
-to easily boot into a previous generation.  A technique that can be used
-in this case is to @i{chroot} into your broken system and reconfigure it
-from there.  Such technique is explained below.
-
-@cindex chroot, guix system
-@cindex chrooting, guix system
-@cindex repairing GRUB, via chroot
-@menu
-* Chrooting into an existing system::
-@end menu
-
-@node Chrooting into an existing system
-@section Chrooting into an existing system
-
-This section details how to @i{chroot} to an already installed Guix
-System with the aim of reconfiguring it, for example to fix a broken
-GRUB installation.  The process is similar to how it would be done on
-other GNU/Linux systems, but there are some Guix System particularities
-such as the daemon and profiles that make it worthy of explaining here.
-
-@enumerate
-@item
-Obtain a bootable image of Guix System.  It is recommended the latest
-development snapshot so the kernel and the tools used are at least as as
-new as those of your installed system; it can be retrieved from the
-@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
-https://ci.guix.gnu.org} URL.  Follow the @pxref{USB Stick and DVD
-Installation} section for copying it to a bootable media.
-
-@item
-Boot the image, and proceed with the graphical text-based installer
-until your network is configured.  Alternatively, you could configure
-the network manually by following the
-@ref{manual-installation-networking} section.  If you get the error
-@samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
-@samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
-is your device identifier (ID).
-
-@item
-Switch to a virtual console (tty) if you haven't already by pressing
-simultaneously the @kbd{Control + Alt + F4} keys.  Mount your file
-system at @file{/mnt}.  Assuming your root partition is
-@file{/dev/sda2}, you would do:
-
-@example sh
-mount /dev/sda2 /mnt
-@end example
-
-@item
-Mount special block devices and Linux-specific directories:
-
-@example sh
-mount --rbind /proc /mnt/proc
-mount --rbind /sys /mnt/sys
-mount --rbind /dev /mnt/dev
-@end example
-
-If your system is EFI-based, you must also mount the ESP partition.
-Assuming it is @file{/dev/sda1}, you can do so with:
-
-@example sh
-mount /dev/sda1 /mnt/boot/efi
-@end example
-
-@item
-Enter your system via chroot:
-
-@example sh
-chroot /mnt /bin/sh
-@end example
-
-@item
-Source the system profile as well as your @var{user} profile to setup
-the environment, where @var{user} is the user name used for the Guix
-System you are attempting to repair:
-
-@example sh
-source /var/guix/profiles/system/profile/etc/profile
-source /home/@var{user}/.guix-profile/etc/profile
-@end example
-
-To ensure you are working with the Guix revision you normally would as
-your normal user, also source your current Guix profile:
-
-@example sh
-source /home/@var{user}/.config/guix/current/etc/profile
-@end example
-
-@item
-Start a minimal @command{guix-daemon} in the background:
-
-@example sh
-guix-daemon --build-users-group=guixbuild --disable-chroot &
-@end example
-
-@item
-Edit your Guix System configuration if needed, then reconfigure with:
-
-@example sh
-guix system reconfigure your-config.scm
-@end example
-
-@item
-Finally, you should be good to reboot the system to test your fix.
-
-@end enumerate
 
 @c *********************************************************************
 @node Getting Started
@@ -43020,6 +42903,124 @@ Complex Configurations
 @end example
 
 
+@c *********************************************************************
+@cindex troubleshooting, Guix System
+@cindex guix system troubleshooting
+@node System Troubleshooting Tips
+@chapter System Troubleshooting Tips
+
+Guix System allows rebooting into a previous generation should the last
+one be malfunctioning, which makes it quite robust against being broken
+irreversibly.  This feature depends on GRUB being correctly functioning
+though, which means that if for whatever reasons your GRUB installation
+becomes corrupted during a system reconfiguration, you may not be able
+to easily boot into a previous generation.  A technique that can be used
+in this case is to @i{chroot} into your broken system and reconfigure it
+from there.  Such technique is explained below.
+
+@cindex chroot, guix system
+@cindex chrooting, guix system
+@cindex repairing GRUB, via chroot
+@menu
+* Chrooting into an existing system::
+@end menu
+
+@node Chrooting into an existing system
+@section Chrooting into an existing system
+
+This section details how to @i{chroot} to an already installed Guix
+System with the aim of reconfiguring it, for example to fix a broken
+GRUB installation.  The process is similar to how it would be done on
+other GNU/Linux systems, but there are some Guix System particularities
+such as the daemon and profiles that make it worthy of explaining here.
+
+@enumerate
+@item
+Obtain a bootable image of Guix System.  It is recommended the latest
+development snapshot so the kernel and the tools used are at least as as
+new as those of your installed system; it can be retrieved from the
+@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
+https://ci.guix.gnu.org} URL.  Follow the @pxref{USB Stick and DVD
+Installation} section for copying it to a bootable media.
+
+@item
+Boot the image, and proceed with the graphical text-based installer
+until your network is configured.  Alternatively, you could configure
+the network manually by following the
+@ref{manual-installation-networking} section.  If you get the error
+@samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
+@samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
+is your device identifier (ID).
+
+@item
+Switch to a virtual console (tty) if you haven't already by pressing
+simultaneously the @kbd{Control + Alt + F4} keys.  Mount your file
+system at @file{/mnt}.  Assuming your root partition is
+@file{/dev/sda2}, you would do:
+
+@example sh
+mount /dev/sda2 /mnt
+@end example
+
+@item
+Mount special block devices and Linux-specific directories:
+
+@example sh
+mount --rbind /proc /mnt/proc
+mount --rbind /sys /mnt/sys
+mount --rbind /dev /mnt/dev
+@end example
+
+If your system is EFI-based, you must also mount the ESP partition.
+Assuming it is @file{/dev/sda1}, you can do so with:
+
+@example sh
+mount /dev/sda1 /mnt/boot/efi
+@end example
+
+@item
+Enter your system via chroot:
+
+@example sh
+chroot /mnt /bin/sh
+@end example
+
+@item
+Source the system profile as well as your @var{user} profile to setup
+the environment, where @var{user} is the user name used for the Guix
+System you are attempting to repair:
+
+@example sh
+source /var/guix/profiles/system/profile/etc/profile
+source /home/@var{user}/.guix-profile/etc/profile
+@end example
+
+To ensure you are working with the Guix revision you normally would as
+your normal user, also source your current Guix profile:
+
+@example sh
+source /home/@var{user}/.config/guix/current/etc/profile
+@end example
+
+@item
+Start a minimal @command{guix-daemon} in the background:
+
+@example sh
+guix-daemon --build-users-group=guixbuild --disable-chroot &
+@end example
+
+@item
+Edit your Guix System configuration if needed, then reconfigure with:
+
+@example sh
+guix system reconfigure your-config.scm
+@end example
+
+@item
+Finally, you should be good to reboot the system to test your fix.
+
+@end enumerate
+
 @node Home Configuration
 @chapter Home Configuration
 @cindex home configuration
-- 
2.41.0

[bug#66577] [PATCH 2/4] doc: Mention Guix Home in “Getting Started”.

[Ludovic Courtès]

* doc/guix.texi (Getting Started): Mention Guix Home.
(Home Configuration): Remove “still under development” note.
---
 doc/guix.texi | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 8ebf50469e..f5d20873be 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -3069,11 +3069,15 @@ Getting Started
 @quotation Going further
 @xref{Package Management}, for more about package management.  You may
 like @dfn{declarative} package management with @command{guix package
---manifest}, managing separate @dfn{profiles} with @option{--profile},
+--manifest},
 deleting old generations, collecting garbage, and other nifty features
 that will come in handy as you become more familiar with Guix.  If you
 are a developer, @pxref{Development} for additional tools.  And if
 you're curious, @pxref{Features}, to peek under the hood.
+
+You can also manage the configuration of your entire @dfn{home
+environment}---your user ``dot files'', services, and packages---using
+Guix Home.  @xref{Home Configuration}, to learn more about it!
 @end quotation
 
 Once you've installed a set of packages, you will want to periodically
@@ -43036,12 +43040,6 @@ Home Configuration
 @c Maybe later, it will be possible to make home configuration a part of
 @c system configuration to make everything managed by guix system.
 
-@quotation Note
-The functionality described in this section is still under development
-and is subject to change.  Get in touch with us on
-@email{guix-devel@@gnu.org}!
-@end quotation
-
 The user's home environment usually consists of three basic parts:
 software, configuration, and state.  Software in mainstream distros are
 usually installed system-wide, but with GNU Guix most software packages
-- 
2.41.0

[bug#66577] [PATCH 2/4] doc: Mention Guix Home in “Getting Started”.

[Simon Tournier]

Hi Ludo,


On Mon, 16 Oct 2023 at 14:43, Ludovic Courtès <ludo@gnu.org> wrote:

>  @quotation Going further
>  @xref{Package Management}, for more about package management.  You may
>  like @dfn{declarative} package management with @command{guix package
> ---manifest}, managing separate @dfn{profiles} with @option{--profile},
> +--manifest},
>  deleting old generations, collecting garbage, and other nifty features
>  that will come in handy as you become more familiar with Guix.  If you
>  are a developer, @pxref{Development} for additional tools.  And if
>  you're curious, @pxref{Features}, to peek under the hood.

It is part of “Going further”, so I would let « managing separate
@dfn{profiles} with @option{--profile} ».  For what it is worth, I
recommend for some newcomer to still use a separated profile inside the
project folder, just aside the files manifest.scm and channels.scm.

I agree that “guix shell” is really cool now, but all the balance is the
duration of the project with the cache cleanup.

Well, this mention does not bother, IMHO, and it invites to know more
for the interested reader since it is “Going further”…

> +You can also manage the configuration of your entire @dfn{home
> +environment}---your user ``dot files'', services, and packages---using
> +Guix Home.  @xref{Home Configuration}, to learn more about it!
>  @end quotation

…I mean, similarly, Guix Home is not something I recommend for
newcomers.  But it is good to mention it in “Going further”. :-)


Cheers,
simon

[bug#66577] [PATCH 2/4] doc: Mention Guix Home in “Getting Started”.

[Ludovic Courtès]

Hi,

Simon Tournier <zimon.toutoune@gmail.com> skribis:

> On Mon, 16 Oct 2023 at 14:43, Ludovic Courtès <ludo@gnu.org> wrote:
>
>>  @quotation Going further
>>  @xref{Package Management}, for more about package management.  You may
>>  like @dfn{declarative} package management with @command{guix package
>> ---manifest}, managing separate @dfn{profiles} with @option{--profile},
>> +--manifest},
>>  deleting old generations, collecting garbage, and other nifty features
>>  that will come in handy as you become more familiar with Guix.  If you
>>  are a developer, @pxref{Development} for additional tools.  And if
>>  you're curious, @pxref{Features}, to peek under the hood.
>
> It is part of “Going further”, so I would let « managing separate
> @dfn{profiles} with @option{--profile} ».  For what it is worth, I
> recommend for some newcomer to still use a separated profile inside the
> project folder, just aside the files manifest.scm and channels.scm.

Yeah, I thought about concision and ‘--profile’ seemed less important
than “deleting old generations” etc.

Also, caching in ‘guix shell’ was designed to automate what one would do
manually with ‘-p’: registering the GC root, cleaning things up that are
unused.  The goal was to provide a simpler interface, which ideally also
means simpler onboarding.

Anyway, no strong opinion, so I’ve re-added the “managing separate
profiles” bit.

Thanks,
Ludo’.

[bug#66577] [PATCH 3/4] doc: cookbook: Suggest ‘guix shell’ as an alternative to multiple profiles.

[Ludovic Courtès]

Multiple profiles are relatively hard to set up and maintain, especially
for newcomers.  Thus, suggest ‘guix shell’ as an alternative.

* doc/guix-cookbook.texi (Guix Profiles in Practice): Add note
linking to ‘guix shell’.
(The benefits of manifests): Remove outdated info about ‘guix
environment’ and profiles that may be GC’d.  Update.
---
 doc/guix-cookbook.texi | 39 ++++++++++++++++-----------------------
 1 file changed, 16 insertions(+), 23 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 712c131a51..1259f6aac7 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3714,7 +3714,7 @@ Guix Profiles in Practice
 @section Guix Profiles in Practice
 
 Guix provides a very useful feature that may be quite foreign to newcomers:
-@emph{profiles}.  They are a way to group package installations together and all users
+@dfn{profiles}.  They are a way to group package installations together and all users
 on the same system are free to use as many profiles as they want.
 
 Whether you're a developer or not, you may find that multiple profiles bring you
@@ -3722,6 +3722,16 @@ Guix Profiles in Practice
 @emph{traditional package managers}, they are very convenient to use once you've
 understood how to set them up.
 
+@quotation Note
+This section is an opinionated guide on the use of multiple profiles.
+It predates @command{guix shell} and its fast profile cache
+(@pxref{Invoking guix shell,,, guix, GNU Guix Reference Manual}).
+
+In many cases, you may find that using @command{guix shell} to set up
+the environment you need, when you need it, is less work that
+maintaining a dedicated profile.  Your call!
+@end quotation
+
 If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a
 kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not
 just Python software.  Furthermore, profiles are self-sufficient: they capture
@@ -4034,29 +4044,12 @@ The benefits of manifests
 they ``pin'' packages in the store, which prevents them from being
 garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual})
 and ensures that they will still be available at any point in
-the future.
+the future.  The @command{guix shell} command also protects
+recently-used profiles from garbage collection; profiles that have not
+been used for a while may be garbage-collected though, along with the
+packages they refer to.
 
-Let's take an example:
-
-@enumerate
-@item
-We have an environment for hacking on a project for which there isn't a Guix
-package yet.  We build the environment using a manifest, and then run @code{guix
-   environment -m manifest.scm}.  So far so good.
-
-@item
-Many weeks pass and we have run a couple of @code{guix pull} in the mean time.
-Maybe a dependency from our manifest has been updated; or we may have run
-@code{guix gc} and some packages needed by our manifest have been
-garbage-collected.
-
-@item
-Eventually, we set to work on that project again, so we run @code{guix shell
-   -m manifest.scm}.  But now we have to wait for Guix to build and install
-stuff!
-@end enumerate
-
-Ideally, we could spare the rebuild time.  And indeed we can, all we need is to
+To be 100% sure that a given profile will never be collected,
 install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile;
 . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our
 hacking environment will be available at all times.
-- 
2.41.0

[bug#66577] [PATCH 4/4] doc: cookbook: Add cross references to the manual regarding manifests.

[Ludovic Courtès]

* doc/guix-cookbook.texi (The benefits of manifests)
(Reproducible profiles): Add cross-references.
---
 doc/guix-cookbook.texi | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 1259f6aac7..b1fe1b932f 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -3987,7 +3987,9 @@ Default profile
 @node The benefits of manifests
 @subsection The benefits of manifests
 
-Manifests are a convenient way to keep your package lists around and, say,
+Manifests let you @dfn{declare} the set of packages you'd like to have
+in a profile (@pxref{Writing Manifests,,, guix, GNU Guix Reference Manual}).
+They are a convenient way to keep your package lists around and, say,
 to synchronize them across multiple machines using a version control system.
 
 A common complaint about manifests is that they can be slow to install when they
@@ -4064,16 +4066,18 @@ Reproducible profiles
 
 @itemize
 @item
-a manifest,
+a manifest (@pxref{Writing Manifests,,, guix, GNU Guix Reference Manual});
 @item
-a Guix channel specification.
+a Guix channel specification (@pxref{Replicating Guix,,, guix, GNU Guix
+Reference Manual}).
 @end itemize
 
 Indeed, manifests alone might not be enough: different Guix versions (or
 different channels) can produce different outputs for a given manifest.
 
 You can output the Guix channel specification with @samp{guix describe
---format=channels}.
+--format=channels} (@pxref{Invoking guix describe,,, guix, GNU Guix
+Reference Manual}).
 Save this to a file, say @samp{channel-specs.scm}.
 
 On another computer, you can use the channel specification file and the manifest
-- 
2.41.0

[bug#66577] [PATCH 0/4] Newcomer-oriented improvements to the manual and cookbook

[Mathieu Othacehe]

Hello,

> regarding the section on multiple profiles in the cookbook (I’ve seen
> newcomers attempt to adopt that software management style on their
> systems, when it’s complex and in fact largely unnecessary since the
> addition of a fast cache in ‘guix shell’).

It is clear that "guix shell" is now an easier alternative to manual
profile management. So that commit:

>
>   doc: cookbook: Suggest ‘guix shell’ as an alternative to multiple
>     profiles.

and the rest of the series looks good to me.

Thanks,

Mathieu

[bug#66577] [PATCH 0/4] Newcomer-oriented improvements to the manual and cookbook

[Simon Tournier]

Hi,

Cool!  That’s better.

On Mon, 16 Oct 2023 at 14:36, Ludovic Courtès <ludo@gnu.org> wrote:

> Ludovic Courtès (4):
>   doc: Move “System Troubleshooting Tips” below.
>   doc: Mention Guix Home in “Getting Started”.
>   doc: cookbook: Suggest ‘guix shell’ as an alternative to multiple
>     profiles.
>   doc: cookbook: Add cross references to the manual regarding manifests.

LGTM, except keep the mention about profile in “Going further” of
“Getting Started”.

Cheers,
simon

bug#66577: [PATCH 0/4] Newcomer-oriented improvements to the manual and cookbook

[Ludovic Courtès]

Hey,

Pushed as 216f8ffff49c54ad56209c4fd6528f2d80ee8fed with the change Simon
suggested.  Thank you Mathieu and Simon for your feedback!

Ludo’.