---- On Sat, 11 May 2024 10:14:15 +0200 pelzflorian (Florian Pelz) wrote ---
> Instead, there already is advice for .config/guix/current documented in
> the Guix manual’s Getting Started section. The advice should be a
> cross-reference that users should follow the steps from Getting Started,
> so search paths are set up properly instead of advising to set PATH and
> INFOPATH.
>
> The advice of setting PATH really should go away.
Sorry for the late and lengthy reply. Life is life and when I returned to the
issue I noticed that the problem is really that the concept of profiles could
use some revision within the manual. That will make for a rather complex
change set. I hoped to have one ready yet, again, life is life. So, here are
my thoughts and, after hearing yours, I can put together the necessary changes
if my points hold.
I see two fundamental issues:
1. should there be a single point of reference for the concept of "profile" and
where should it be?
2. what information about profiles is relevant to addressing the reported issue
and where is it?
We'll need to discuss possible solutions because, unfortunately, the concept of
"profiles" isn't conveniently documented.
ISSUE 1 - should there be a single point of reference for the concept of
"profile" and where should it be?
tl;dr create a new subsection for the profile concept
I find your suggestion reasonable; document concepts in a single place and then
favor references to that place. Unfortunately, there is currently no single
place of reference for the concept of "profile".
Important facts about profiles are spread across the following sections (a list
is given at the end of this section):
- Section 4: Getting Started (1)
- Section 5.1: Features (and isn't indexed there) (1)
- Section 5.2: Invoking 'guix package' (13)
- Section 5.7: Invoking 'guix pull' (3)
- Section 8.8: Search Paths (1)
- Section 9.1: Invoking 'guix build' (1)
- Section 11.3: operating-system Reference (2), and
- Section 11.19.3: Service Reference (1)
Should we make Section 4: Getting Started the common reference point?
I say no. The Getting Started section is intended to help readers get started
with Guix and get a feel of what it's like. Therefore, it should contain a
simple how-to with minimal explanation. As the GNU Press Styleguide[1] advises,
"Move slowly. Do not impose too much of a cognitive load at once on the reader."
I think the Getting Started section has too much profile information in it as
is. For example, GUIX_PYTHONPATH is a convention, hard-coded into package
definitions whereas GUIX_PROFILE is a literary shorthand for the concept that
multiple profiles may exist and that the profile is the $HOME/.guix-profile in
this case.
Of all the sections that discuss profiles, Invoking 'guix package' contains the
most information (13 facts). It's also given as the point of reference by 5
other sections:
1. Invoking 'guix pull' (twice)
2. Invoking 'guix shell'
3. Invoking 'guix environment'
4. Invoking 'guix build'
5. operating-system Reference
Should we make Invoking 'guix package' be the common reference point for
profiles?
Again, I say no. AFAIU, profiles have two forms: a system profile, sometimes
called the global profile, which manages Guix itself and user profiles,
including "default" or "current", which dictate package accessibility. While
system and user profiles "work exactly" like each other (see Invoking guix
pull), there are separate commands for each: 'guix package' is for user
profiles and 'guix pull' is for the system profile. It's easy to confuse all
this. Therefore, it would be better to have a separate section that explains
profiles and let Invoking 'guix package' and Invoking 'guix pull' focus on the
command options.
The best common reference point for profiles is in a new section just below
Section 5.1: Features. As the Styleguide[1] says,
"Put important notes to the reader in subsections of their own. This tells the
reader the notes really are important."
Profiles are first introduced in Section 4: Getting Started. It does a good
job introducing the idea and could actually provide less information. The
concept, however, is first explained in Section 5.1: Features. The majority of
Features is about how profiles are useful and a core concept of Guix. I think
we could switch the focus of Features to be about the benefits of the store,
the symlink forest, transactions, control of the build environment, and
provenance tracking and move the explanation and details of profiles to a new
subsection.
Information about profiles grouped by section:
- Getting Started
+ A profile is a directory containing installed packages
- Features (not indexed)
+ A profile is a reference to the store kept in each user's home
directory managed by 'guix package'
- Invoking 'guix package'
+ a profile is a directory of installed packages
+ profiles exist per user
+ there exists a "default" profile
+ guix package operations create and modify profiles
+ profiles are created in $HOME/.guix-profile
+ $HOME/.guix-profile is a symlink
+ In a multi-user setup, user profiles are stored in a place
registered as a "garbage-collector root"
+ there is a notion of "current profile"
+ profiles have generations
+ generations within a profile are linear, starting with a "zeroth
generation", which contains no files apart from its own metadata.
+ multiple profiles may be referenced at a time
+ removing a profile means removing the symlink previously specified
by "guix project --profile" as well as any corresponding '-*-link'
suffixed symlinks
+ profiles are handles on state (that is, the state of which
software is installed and available)
- Invoking guix pull
+ the latest Guix is determined by a profile
+ 'guix pull' and 'guix package' both create profiles and how these
profiles work is similar
+ there are two types of profiles; those managed by 'guix pull' and
those managed by 'guix package'
- Search Paths
+ installing packages in the default profile creates the file
'~/.guix-profile/etc/profile' which defines search path
environment variables
- Invoking 'guix build'
+ modifying the user's profile is the job of 'guix package'
- operating-system Reference
+ the global profile is accessible at '/run/current-system/profile'
+ it is good practice to install non-core utilities in user profiles
- Service Reference
+ the "system profile" is the programs under
'/run/current-system/profile'
ISSUE 2- what information about profiles is relevant to addressing the reported
issue and where is it?
tldr; we should create a new subsection rather than expand Getting Started
I'm able to reduce the information necessary to address the reported issue to:
1. the user environment must be configured so that the shell and other
applications can find software installed with Guix
2. Guix provides a file, $GUIX_PROFILE/etc/profile, to configure the user
environment
3. $GUIX_PROFILE/etc/profile is created for *each* profile
4. $GUIX_PROFILE/etc/profile must be sourced
Section 4: Getting Started explicitly states the first and forth points and
implies the second. AFAICT, the third isn't actually in the manual (although
it is in the Cookbook)!
I think explaining $GUIX_PROFILE/etc/profile in more detail within Getting
Started wouldn't make sense. Therefore, because of this, and the points I made
above, we should consider breaking out profiles into their own section.
[1] https://www.fsf.org/licensing/gnu-press/GNU-Press-styleguide.pdf
