[bug#53447] [PATCH] doc: Unset environment variables considered harmful

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

Hi Liliana and Ludo,

Liliana Marie Prikler <liliana.prikler@gmail.com> writes:

> Hi Ludo,
>
> Am Samstag, dem 22.01.2022 um 17:04 +0100 schrieb Ludovic Courtès:
>> Hi Liliana,
>> 
>> Liliana Marie Prikler <liliana.prikler@gmail.com> skribis:
>> 
>> > * doc/guix.texi (Application Setup): Add subsection for implicit
>> > environment variables.
>> > ---
>> >  doc/guix.texi | 27 +++++++++++++++++++++++++++
>> >  1 file changed, 27 insertions(+)
>> > 
>> > diff --git a/doc/guix.texi b/doc/guix.texi
>> > index 912a8e3c5a..805e3b611f 100644
>> > --- a/doc/guix.texi
>> > +++ b/doc/guix.texi
>> > @@ -2023,6 +2023,33 @@ want to avoid auto-loading the Emacs
>> > packages installed with Guix, you
>> >  can do so by running Emacs with the @option{--no-site-file} option
>> >  (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
>> >  
>> > +@subsection Implicit Environment Variables
>> > +
>> > +Many environment variables are defined in a way that assumes a
>> > certain
>> > +default value, even if unset.  For example, bash uses the current
>> > +working directory as @env{PATH} if unset, or @env{XDG_CONFIG_HOME}
>> > +expands to @file{$HOME/.config}.  Some of these defaults remain
>> > the same
>> > +whether a package is used through Guix or not---however,
>> > environment
>> > +variables referring to @file{/etc} or @file{/usr} typically have
>> > their
>> > +meaning subtly changed in Guix.  An application installed via Guix
>> > might
>> > +instead look up files in its own @file{etc} structure, or (if a
>> > +search-path was specified) even override the default for packages
>> > from
>> > +the foreign distro.
>> 
>> I think I miss some context: what concrete problem is this trying to
>> solve?  What is it telling me to do?
>> 
>> I wonder to what extent this is actionable for a user, due to wording
>> that leaves it up to the reader to figure out how this applies to
>> them:
>> 
>>   “Many environment variables”
>>   “a certain default value”
>>   “Some of these”
>>   “An application installed via Guix might”
>>   “problems coming from such implicitly defined”
>>   …
>> 
>> I think the “Application Setup” section should be as concrete as
>> possible, with clear instructions (“If X then type Y”), possibly
>> followed by explanations that curious readers can read and that
>> others can skip.
>> 
>> WDYT?

I initially thought it unnecessary and vague, but after reading the bug
reports listed below, it seems to make sense to document it.  And
reading it now, that's probably the issue I encountered myself in
https://issues.guix.gnu.org/53233.

> I think there are too many examples to exhaustively list them all, but
> to give an example, [1, 2, 3, 4] are all the same bug and in [2] Carlo
> said we should document this under "Application Setup".  My personal
> stance is that the Guix behaviour is not a bug and other distros are
> weird for not explicitly binding it.

I like to see this as a bug, so I've opened one as 53514; Guix should
strive to not mess with the host environment, and setting global
variables used by both Guix and a potentially foreign host goes against
this.  The proper fix would be to patch all applications in Guix to use
Guix-specific variables, such as GUIX_XDG_DATA_DIRS instead of
XDG_DATA_DIRS.

> I know my wording is not the best here, but "If X then Y" is a little
> too late when your session broke.  But if your session broke and you
> read the manual saying "blah blah unset environment variables evil",
> you are more likely to suspect "hmm, maybe evil environment variables
> were evil".  Fortunately, with distros trying out Flatpaks and Snaps,
> XDG_DATA_DIRS is less likely to break them, but still.  We never know
> which variable will be the next to blow things up.

Agreed that this is useful in the meantime.  Perhaps add a TODO comment
pointing to the bug I've opened.

Thank you,

Maxim