bug#53224: Profile definition, was Re: bug#53224: Cookbook recipe about profile collisions

[Matt]

 ---- On Mon, 17 Jan 2022 09:16:28 -0500 Ludovic Courtès <ludo@gnu.org> wrote 
----

 > > This person spent a lot of time trying to understand the situation and
 > > writing the blog post, but their understanding is still rather weak.
 > 
 > To be fair, the person didn’t look for “profile” in the manual.  I’m not
 > blaming—mentioning it to clarify what it is we’re trying to fix.

With all respect, I *did* look at "profile" in the manual. I spent a lot of 
time looking and trying to understand things.  I hear you say you're not trying 
to blame me and I trust that's not your intent.  However, what was said *does* 
blame me.  It says what I did and did not do, independent of reality: you are 
not me and you were not present.  Unfortunately, what was said carries all 
sorts of judgments and implications (ouch!) which, opposite to your intent, is 
not fair. 

I see you want clarification on what we're trying to fix. May I suggest instead 
asking, "What problem are we trying to solve?"

I see several problems beyond what I've already said.  However, I'll try to 
stick to just one that I encountered with the documentation.  Leo is certainly 
working toward something specific which I suspect is different from what I see. 
I'll let them speak for themselves.

I'm going to assume that you probably wanted to ask something like, "It looks 
to me like the manual adequately explains profiles.  But, since I'm the main 
architect of this system, maybe I have knowledge that someone new doesn't have. 
Person who is confused, are you able to say where you're confused?"

I would reply:

There are several places I've been confused. Let me give you a specific example.

The manual has at least four places that "profile" is defined:

1.  
[[https://guix.gnu.org/en/manual/en/html_node/Getting-Started.html#Getting-Started][(guix)
 Getting Started]] says,

#+begin_quote
"A profile is a directory containing installed packages"
#+end_quote

2.  
[[https://guix.gnu.org/en/manual/en/html_node/Invoking-guix-package.html#Invoking-guix-package][(guix)
 Invoking guix package]] says,

#+begin_quote
"a directory of installed packages"
#+end_quote

and 3, yet in the guix package options:

#+begin_quote
'-p PROFILE'
     Use PROFILE instead of the user's default profile.

     PROFILE must be the name of a file that will be created upon
     completion.  Concretely, PROFILE will be a mere symbolic link
     ("symlink") pointing to the actual profile where packages are
     installed:

          #+begin_example
          $ guix install hello -p ~/code/my-profile
          ...
          $ ~/code/my-profile/bin/hello
          Hello, world!
          #+end_example
#+end_quote

Elsewhere in (guix) Features is a 4th which says,

#+begin_quote
users have their own “profile”, which points to the packages that they actually 
want to use
#+end_quote

So, is the profile a directory or a pointer file (e.g. symlink)?  I tend to 
think of a directory as a container, like a manilla folder that contains 
papers.  To me, something that points is a file that contains a path to another 
location.  I see that I used the word "contains" to describe both file and 
directory, so maybe that's a sign to me I'm missing something there.

Regardless, I hope you can see that it's not always clear whether a profile is 
a directory or a file.  Yes, on Unix-like systems, directories are files. But 
Guix throws an error if you call =guix package -p= with a directory:

: guix package: error: rename-file: Is a directory

If you follow the symlinks, the profile is indeed a directory; it is a 
directory in the store.  But the way users interact with profiles is

          GUIX_PROFILE="$HOME/.guix-profile"
          . "$GUIX_PROFILE/etc/profile"

which is a file. And there are a bunch of symlinks in general. Those appear to 
be implementation details. But I think it's reasonable to say the abstraction 
isn't airtight and that, as a user, I have to interact with the implementation 
details at some level. Certainly at the documentation level. 

Leo is 100% correct that my understanding is still rather weak. I'll do my best 
despite that to help make the documentation better.