bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[Luis Felipe via Bug reports for GNU Guix]

The Guix reference manual does not seem to explain what profiles are.


## Steps to reproduce

Assuming you are browsing the Guix reference manual in Info:

1. Type i (to search for an index topic).
2. Type the word profile and hit Enter.
3. Type , repeatedly to explore all the parts of the manual related to profiles.


## Expected result

At some point, I get to a section defining what is a profile exactly, a profile of what, what can I get from using one or many of them, what is the GUIX_PROFILE variable, does it accept a single path to a profile or more, and some use cases and examples.


## Unexpected result

I see profiles are mentioned in places where they can be used, but the text assumes I know what a profile is.

Similarly, the GUIX_PROFILE variable doesn't seem to be defined. It seems missing from the concept and programming indices.


## Additional information

The "Guix Profiles in Practice" recipe in the cookbook defines profiles to some extent. Maybe some of this information can be used in the manual?


---
Luis Felipe López Acevedo
https://luis-felipe.gitlab.io/

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[Tobias Geerinckx-Rice via Bug reports for GNU Guix]

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

Luis Felipe,

I think that would be very helpful.  I'm trying to think of a 
concise, correct, but actually useful definition of profiles for 
someone not already familiar with them or Guix.

Out of curiosity: how do you intuitively understand profiles, as 
someone who's used Guix for a while?

Luis Felipe via Bug reports for GNU Guix 写道：
> [...] what is the GUIX_PROFILE variable, does it accept a single
> path to a profile or more, and some use cases and 
> examples. [...]

I don't think we should document GUIX_PROFILE.  It's not part of 
the definition of Guix profiles.  It should not matter to users 
nor should they rely on previously observed behaviour.  AIUI there 
are no supported ‘use cases’, beyond copy-pasting Guix error 
messages...

> Similarly, the GUIX_PROFILE variable doesn't seem to be 
> defined. It seems missing from the concept and programming 
> indices.

...so this part isn't unexpected.

Kind regards,

T G-R

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 247 bytes --]

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[Luis Felipe via Bug reports for GNU Guix]

On Friday, February 26, 2021 11:30 PM, Tobias Geerinckx-Rice <me@tobias.gr> wrote:

> Luis Felipe,
>
> I think that would be very helpful. I'm trying to think of a concise, correct, but actually useful definition of profiles for someone not already familiar with them or Guix.
>
> Out of curiosity: how do you intuitively understand profiles, as someone who's used Guix for a while?

I think I didn't intuitively understand profiles. I think I actually started using them last year (apart from the user profile) after reading the Guix Profiles in Practice recipe, which made things clearer to me (but I don't think I grok the concept).

So, right now, I see a profile like a collection of packages that you can activate/deactivate in your environment by setting the GUIX_PROFILE environment variable and sourcing its profile file.


> Luis Felipe via Bug reports for GNU Guix 写道：
>
> > [...] what is the GUIX_PROFILE variable, does it accept a single
> > path to a profile or more, and some use cases and > examples. [...]
>
> I don't think we should document GUIX_PROFILE. It's not part of the definition of Guix profiles. It should not matter to users nor should they rely on previously observed behaviour. AIUI there are no supported ‘use cases’, beyond copy-pasting Guix error messages...

In the Guix Profiles in Practice recipe, for example, you are instructed to set GUIX_PROFILE and then use it when sourcing the profile. So I thought it deserved an entry in the index, since it is mentioned so often when working with profiles.

I think I was expecting something like:

GUIX_PROFILE
  This is an environment variable that you can set to
  [...]. Its value is an absolute path to a Guix profile.
  See Profiles for more information.

Now I'm confused.. :)

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[Ludovic Courtès]

Hi,

Tobias Geerinckx-Rice via Bug reports for GNU Guix <bug-guix@gnu.org>
skribis:

> I think that would be very helpful.  I'm trying to think of a concise,
> correct, but actually useful definition of profiles for someone not
> already familiar with them or Guix.
>
> Out of curiosity: how do you intuitively understand profiles, as
> someone who's used Guix for a while?

I’m not Luis but I usually say that a profile is the location of a set
of installed packages.

> Luis Felipe via Bug reports for GNU Guix 写道：
>> [...] what is the GUIX_PROFILE variable, does it accept a single
>> path to a profile or more, and some use cases and examples. [...]
>
> I don't think we should document GUIX_PROFILE.  It's not part of the
> definition of Guix profiles.  It should not matter to users nor should
> they rely on previously observed behaviour.  AIUI there are no
> supported ‘use cases’, beyond copy-pasting Guix error messages...

Agreed.  ‘GUIX_PROFILE’ has no significance as an environment variable;
it’s referred to by the generated ‘etc/profile’, but it’s usually a
shell variable, not an environment variable.

Ludo’.

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[zimoun]

Hi Tobias,

On Sat, 27 Feb 2021 at 00:30, Tobias Geerinckx-Rice via Bug reports for GNU Guix <bug-guix@gnu.org> wrote:

> Out of curiosity: how do you intuitively understand profiles, as 
> someone who's used Guix for a while?

Effectively, profiles is not explicitly defined but implicitly, for
instance:

<https://guix.gnu.org/manual/devel/en/guix.html#Features>

Otherwise, the most explicit definition is in the Cookbook:

        Guix provides a very useful feature that may be quite foreign to
        newcomers: 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.

<https://guix.gnu.org/cookbook/en/html_node/Guix-Profiles-in-Practice.html>


BTW, I remember that coming from Conda (and Python), I was confused by
what was Profile and Environment in Guix, since ’environment’ (in Conda)
corresponds to Profile (in Guix).  Anyway, for words inspiration,
Conda’s doc:

        A conda environment is a directory that contains a specific collection
        of conda packages that you have installed. For example, you may have one
        environment with NumPy 1.7 and its dependencies, and another environment
        with NumPy 1.6 for legacy testing. If you change one environment, your
        other environments are not affected. You can easily activate or
        deactivate environments, which is how you switch between them. You can
        also share your environment with someone by giving them a copy of your
        environment.yaml file. For more information, see Managing environments.

<https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html>

And from this old time, I remember that examples really helps, for
instance.

<https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments>.

Therefore, the section «Getting Started» could be a bit extended with a
paragraph about Profiles and one or two examples.  WDYT?

<https://guix.gnu.org/manual/devel/en/guix.html#Getting-Started>


Cheers,
simon

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[Ludovic Courtès]

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

Hello,

zimoun <zimon.toutoune@gmail.com> skribis:

> Effectively, profiles is not explicitly defined but implicitly, for
> instance:
>
> <https://guix.gnu.org/manual/devel/en/guix.html#Features>
>
> Otherwise, the most explicit definition is in the Cookbook:
>
>         Guix provides a very useful feature that may be quite foreign to
>         newcomers: 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.
>
> <https://guix.gnu.org/cookbook/en/html_node/Guix-Profiles-in-Practice.html>

[...]

> <https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html>
>
> And from this old time, I remember that examples really helps, for
> instance.
>
> <https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-environments>.
>
> Therefore, the section «Getting Started» could be a bit extended with a
> paragraph about Profiles and one or two examples.  WDYT?
>
> <https://guix.gnu.org/manual/devel/en/guix.html#Getting-Started>

Thanks for the pointers!  How about these changes to “Getting Started”
and “Invoking guix package”?

Ludo’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1372 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 4cf241c56a..00bd087628 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2751,7 +2751,10 @@ you can go ahead and install it (run this command as a regular user,
 guix install emacs
 @end example
 
-You've installed your first package, congrats!  In the process, you've
+You've installed your first package, congrats!  The package is now
+visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
+profile is a directory containing installed packages.
+In the process, you've
 probably noticed that Guix downloaded pre-built binaries; or, if you
 explicitly chose to @emph{not} use pre-built binaries, then probably
 Guix is still building software (@pxref{Substitutes}, for more info).
@@ -3061,7 +3064,10 @@ retaining precise @dfn{provenance tracking} of the software.
 @cindex package removal
 The @command{guix package} command is the tool that allows users to
 install, upgrade, and remove packages, as well as rolling back to
-previous configurations.  It operates only on the user's own profile,
+previous configurations.  These operations work on a user
+@dfn{profile}---a directory of installed packages.  Each user has a
+default profile in @file{$HOME/.guix-profile}.
+The command operates only on the user's own profile,
 and works with normal user privileges (@pxref{Features}).  Its syntax
 is:
 

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[zimoun]

Hi Ludo,

On Sun, 14 Mar 2021 at 11:56, Ludovic Courtès <ludo@gnu.org> wrote:

> diff --git a/doc/guix.texi b/doc/guix.texi
> index 4cf241c56a..00bd087628 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -2751,7 +2751,10 @@ you can go ahead and install it (run this command as a regular user,
>  guix install emacs
>  @end example
>  
> -You've installed your first package, congrats!  In the process, you've
> +You've installed your first package, congrats!  The package is now
> +visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
> +profile is a directory containing installed packages.
> +In the process, you've

I would add a link to the index term ’profile’ in “Invoking guix package”:

--8<---------------cut here---------------start------------->8---
@cindex profile
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}.  This symlink always points to the
…
--8<---------------cut here---------------end--------------->8---


>  probably noticed that Guix downloaded pre-built binaries; or, if you
>  explicitly chose to @emph{not} use pre-built binaries, then probably
>  Guix is still building software (@pxref{Substitutes}, for more info).
> @@ -3061,7 +3064,10 @@ retaining precise @dfn{provenance tracking} of the software.
>  @cindex package removal
>  The @command{guix package} command is the tool that allows users to
>  install, upgrade, and remove packages, as well as rolling back to
> -previous configurations.  It operates only on the user's own profile,
> +previous configurations.  These operations work on a user
> +@dfn{profile}---a directory of installed packages.  Each user has a
> +default profile in @file{$HOME/.guix-profile}.
> +The command operates only on the user's own profile,
>  and works with normal user privileges (@pxref{Features}).  Its syntax
>  is:

I would add an index term and/or anchor and points to the option:

--8<---------------cut here---------------start------------->8---
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.

@var{profile} must be the name of a file that will be created upon
completion.  Concretely, @var{profile} will be a mere symbolic link
(``symlink'') pointing to the actual profile where packages are
installed:
…
--8<---------------cut here---------------end--------------->8---


Well, LGTM. :-)

Cheers,
simon

bug#46803: User manual does not explain Profiles (nor GUIX_PROFILE)

[Ludovic Courtès]

Hi zimoun,

Pushed something like the initial patch + index entries as
0571aa7abf262f617add727ac03e3bf63d41ae6d.  Thank you!

Ludo’.