bug#26170: documentation: Explanation of propagated-inputs unclear

bug#26170: documentation: Explanation of propagated-inputs unclear

[pelzflorian (Florian Pelz)]

Hello,

I presume the difference between a package’s `inputs` and
`propagated-inputs` in Guix packages is that propagated inputs get
installed to a Guix profile whenever the package is installed while
inputs are dependencies that remain in the Store. I presume libraries
the packaged program is linked to do not need to go to
`propagated-inputs` because the program is linked to the files in the Store.

For more context, I am attempting to package the GNOME Evolution mail
client which looks for evolution-data-server’s
share/dbus-1/services/org.gnome.evolution.dataserver.Sources.service
at run time and thus should use it as a propagated input (I believe).

I am however confused by `info guix` where I find explanations like
“Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
          specified packages will be automatically installed alongside
          the package they belong to (*note ‘guix package’:
          package-cmd-propagated-inputs, for information on how ‘guix
          package’ deals with propagated inputs.)”
and
“Sometimes packages have “propagated inputs”: these are dependencies
     that automatically get installed along with the required package
     (*note ‘propagated-inputs’ in ‘package’ objects:
     package-propagated-inputs, for information about propagated inputs
     in package definitions).“

I suggest mentioning more explicitly
 1) that `propagated-inputs` are automatically installed *to the Guix
profile* and not just the Store like regular inputs and
 2) that C/C++ libraries do not need to be propagated because they can
just as well be loaded from the Store *unless* their header files are
included by header files of another input package (?) and
 3) more examples like the above example for GNOME Evolution (which
however I have yet to finish packaging and submit as a patch; maybe
dconf is a better example – I presume it is also needed at run time and
not just).

This would have made the purpose of `propagated-inputs` easier to
understand.

Regards,
Florian

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[zimoun]

Dear Florian,

You report this bug [1] a couple of years ago about unclear
explanations of the term propagated-inputs.

[1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=26170

The explanations of propagated-inputs are here [2] and short words are
there [3]. Tey have not been changed since your report.

[2] https://guix.gnu.org/manual/en/html_node/package-Reference.html#package-Reference
[3] https://guix.gnu.org/manual/en/html_node/Invoking-guix-package.html#Invoking-guix-package


You proposed:

<<
 1) that `propagated-inputs` are automatically installed *to the Guix
profile* and not just the Store like regular inputs and
 2) that C/C++ libraries do not need to be propagated because they can
just as well be loaded from the Store *unless* their header files are
included by header files of another input package (?) and
 3) more examples like the above example for GNOME Evolution (which
however I have yet to finish packaging and submit as a patch; maybe
dconf is a better example – I presume it is also needed at run time and
not just).
>>

And I agree. I also had issue and I remember asking on IRC explanations.


Do you have already a patch? If no, do you plan to prepare one?


Thank you in advance for any comments.

All the best,
simon

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[pelzflorian (Florian Pelz)]

On Tue, Dec 03, 2019 at 01:14:05PM +0100, zimoun wrote:
> Dear Florian,
> 
> You report this bug [1] a couple of years ago about unclear
> explanations of the term propagated-inputs.
> […]
> Do you have already a patch? If no, do you plan to prepare one?
> 
> 
> Thank you in advance for any comments.
> 
> All the best,
> simon

Sorry I had totally forgotten about my bug report and do not have a
patch.  I do not have time at the moment or good knowledge of current
documentation and discussions, sorry.  I would be most happy if you
and/or others made patches for better explanations of profiles,
environments and propagated inputs.

Thank you for looking at / searching for old (but current) issues.

Regards,
Florian

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[zimoun]

Dear,

The bug 26170 [1] is about the description of “propagated inputs” in the
manual.

Currently, the term “propagated inputs” in the index [2] goes to the
section “Invoking guix package” [3] and explaining:

        Sometimes packages have propagated inputs: these are
        dependencies that automatically get installed along with the
        required package (see propagated-inputs in package objects, for
        information about propagated inputs in package definitions).

        An example is the GNU MPC library: its C header files refer to
        those of the GNU MPFR library, which in turn refer to those of
        the GMP library. Thus, when installing MPC, the MPFR and GMP
        libraries also get installed in the profile; removing MPC also
        removes MPFR and GMP—unless they had also been explicitly
        installed by the user.

with the hyperlink [4] mentioning:

        Lastly, propagated-inputs is similar to inputs, but the
        specified packages will be automatically installed alongside the
        package they belong to (see guix package, for information on how
        guix package deals with propagated inputs).

        For example this is necessary when a C/C++ library needs headers
        of another library to compile, or when a pkg-config file refers
        to another one via its Requires field.

        Another example where propagated-inputs is useful is for
        languages that lack a facility to record the run-time search
        path akin to the RUNPATH of ELF files; this includes Guile,
        Python, Perl, and more. To ensure that libraries written in
        those languages can find library code they depend on at run
        time, run-time dependencies must be listed in propagated-inputs
        rather than inputs.

The initial suggestions of this bug report were:

--8<---------------cut here---------------start------------->8---
1) that `propagated-inputs` are automatically installed *to the Guix
profile* and not just the Store like regular inputs and

2) that C/C++ libraries do not need to be propagated because they can
just as well be loaded from the Store *unless* their header files are
included by header files of another input package (?) and

3) more examples like the above example for GNOME Evolution (which
however I have yet to finish packaging and submit as a patch; maybe
dconf is a better example – I presume it is also needed at run time and
not just).
--8<---------------cut here---------------end--------------->8---

which now appear to me clarified with the current manual.

Does it make sense to close?

All the best,
simon


[1] http://issues.guix.gnu.org/issue/26170 [2]
http://guix.gnu.org/manual/devel/en/guix.html#Concept-Index_cp_letter-P
[3]
http://guix.gnu.org/manual/devel/en/guix.html#index-propagated-inputs
[4] http://guix.gnu.org/manual/devel/en/guix.html#package_002dpropagated_002dinputs

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[pelzflorian (Florian Pelz)]

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

Thank you for bringing up this bug again with detailed
cross-referencing.  Sorry for not sending a patch earlier.

I do not think it makes sense to close yet.  I attach a proposed patch
now (its text is not properly wrapped yet).  It may contain
misunderstandings about propagated inputs as I have not packaged much.

On Wed, Sep 09, 2020 at 03:25:31PM +0200, zimoun wrote:
> Currently, the term “propagated inputs” in the index [2] goes to the
> section “Invoking guix package” [3] and explaining:
> 
>         Sometimes packages have propagated inputs: these are
>         dependencies that automatically get installed along with the
>         required package (see propagated-inputs in package objects, for
>         information about propagated inputs in package definitions).
> 
>         An example is the GNU MPC library: its C header files refer to
>         those of the GNU MPFR library, which in turn refer to those of
>         the GMP library. Thus, when installing MPC, the MPFR and GMP
>         libraries also get installed in the profile; removing MPC also
>         removes MPFR and GMP—unless they had also been explicitly
>         installed by the user.
> 
> with the hyperlink [4] mentioning:

Note the text currently in the manual is the same as back then when I
filed the bug.

When starting to read about propagated inputs in the documentation of
`guix package --install`, I agree, it is clear enough, the reader will
understand that propagated inputs get treated like with `guix package
--install` and the reader need not think about profiles and the store.

However, back then I may have gotten confused because I started off
reading the Defining Packages section without the context of `guix
package --install`.  In this context, I may have been thinking of
installation to a directory rather than a user running `guix install`.


> 3) more examples like the above example for GNOME Evolution (which
> however I have yet to finish packaging and submit as a patch; maybe
> dconf is a better example – I presume it is also needed at run time and
> not just).

I was mistaken about 3).  I am glad Ricardo Wurmus packaged Evolution.
Apparently I was wrong and evolution does not need
evolution-data-server as a propagated-input.

Regards,
Florian

[-- Attachment #2: 0001-doc-Clarify-what-propagated-inputs-are.patch --]
[-- Type: text/plain, Size: 2186 bytes --]

From fd4955cd0a61e92c37a371e4c5411a505ad5ac76 Mon Sep 17 00:00:00 2001
From: Florian Pelz <pelzflorian@pelzflorian.de>
Date: Wed, 9 Sep 2020 16:54:04 +0200
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Subject: [PATCH] doc: Clarify what propagated inputs are.

Fixes <https://issues.guix.info/issue/26170>.

* doc/guix.texi (package Reference)[package-propagated-inputs]: Clarify.
---
 doc/guix.texi | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 1d6782e6fa..0a5640b174 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -6360,21 +6360,21 @@ this area (@pxref{Invoking guix lint}).
 
 @anchor{package-propagated-inputs}
 Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
-specified packages will be automatically installed alongside the package
+specified packages will be automatically installed to profiles (@pxref{Features, the role of profiles in Guix}) alongside the package
 they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
 package}}, for information on how @command{guix package} deals with
 propagated inputs).
 
-For example this is necessary when a C/C++ library needs headers of
+For example this is necessary when packaging a C/C++ library that needs headers of
 another library to compile, or when a pkg-config file refers to another
 one @i{via} its @code{Requires} field.
 
 Another example where @code{propagated-inputs} is useful is for languages
 that lack a facility to record the run-time search path akin to the
 @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
-more.  To ensure that libraries written in those languages can find
-library code they depend on at run time, run-time dependencies must be
-listed in @code{propagated-inputs} rather than @code{inputs}.
+more.  When packaging libraries written in those languages, ensure they can find
+library code they depend on at run time by listing run-time dependencies
+in @code{propagated-inputs} rather than @code{inputs}.
 
 @item @code{outputs} (default: @code{'("out")})
 The list of output names of the package.  @xref{Packages with Multiple
-- 
2.28.0

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[zimoun]

On Wed, 09 Sep 2020 at 17:10, "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> wrote:
> Thank you for bringing up this bug again with detailed
> cross-referencing.  Sorry for not sending a patch earlier.

My pleasure. :-)


>>From fd4955cd0a61e92c37a371e4c5411a505ad5ac76 Mon Sep 17 00:00:00 2001
> From: Florian Pelz <pelzflorian@pelzflorian.de>
> Date: Wed, 9 Sep 2020 16:54:04 +0200
> Content-Type: text/plain; charset=UTF-8
> Content-Transfer-Encoding: 8bit
> Subject: [PATCH] doc: Clarify what propagated inputs are.
>
> Fixes <https://issues.guix.info/issue/26170>.
>
> * doc/guix.texi (package Reference)[package-propagated-inputs]: Clarify.
> ---
>  doc/guix.texi | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 1d6782e6fa..0a5640b174 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -6360,21 +6360,21 @@ this area (@pxref{Invoking guix lint}).
>  
>  @anchor{package-propagated-inputs}
>  Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
> -specified packages will be automatically installed alongside the package
> +specified packages will be automatically installed to profiles (@pxref{Features, the role of profiles in Guix}) alongside the package

Do not forget the correct filling length. :-)

>  they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
>  package}}, for information on how @command{guix package} deals with
>  propagated inputs).
>  
> -For example this is necessary when a C/C++ library needs headers of
> +For example this is necessary when packaging a C/C++ library that needs headers of

Idem.

>  another library to compile, or when a pkg-config file refers to another
>  one @i{via} its @code{Requires} field.
>  
>  Another example where @code{propagated-inputs} is useful is for languages
>  that lack a facility to record the run-time search path akin to the
>  @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
> -more.  To ensure that libraries written in those languages can find
> -library code they depend on at run time, run-time dependencies must be
> -listed in @code{propagated-inputs} rather than @code{inputs}.
> +more.  When packaging libraries written in those languages, ensure they can find
> +library code they depend on at run time by listing run-time dependencies
> +in @code{propagated-inputs} rather than @code{inputs}.

Idem.
And my English is not good enough to read the difference. :-)
  
>  @item @code{outputs} (default: @code{'("out")})
>  The list of output names of the package.  @xref{Packages with Multiple


All the best,
simon

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[Ludovic Courtès]

Hi,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

> From fd4955cd0a61e92c37a371e4c5411a505ad5ac76 Mon Sep 17 00:00:00 2001
> From: Florian Pelz <pelzflorian@pelzflorian.de>
> Date: Wed, 9 Sep 2020 16:54:04 +0200
> Content-Type: text/plain; charset=UTF-8
> Content-Transfer-Encoding: 8bit
> Subject: [PATCH] doc: Clarify what propagated inputs are.
>
> Fixes <https://issues.guix.info/issue/26170>.
>
> * doc/guix.texi (package Reference)[package-propagated-inputs]: Clarify.
> ---
>  doc/guix.texi | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 1d6782e6fa..0a5640b174 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -6360,21 +6360,21 @@ this area (@pxref{Invoking guix lint}).
>  
>  @anchor{package-propagated-inputs}
>  Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
> -specified packages will be automatically installed alongside the package
> +specified packages will be automatically installed to profiles (@pxref{Features, the role of profiles in Guix}) alongside the package

Like zimoun wrote, please introduce a newline.

>  Another example where @code{propagated-inputs} is useful is for languages
>  that lack a facility to record the run-time search path akin to the
>  @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
> -more.  To ensure that libraries written in those languages can find
> -library code they depend on at run time, run-time dependencies must be
> -listed in @code{propagated-inputs} rather than @code{inputs}.
> +more.  When packaging libraries written in those languages, ensure they can find
> +library code they depend on at run time by listing run-time dependencies
> +in @code{propagated-inputs} rather than @code{inputs}.

I’m not convinced about this hunk; it uses imperative tense towards the
reader to state the same thing no?

Otherwise LGTM, thanks!

Ludo’.

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[pelzflorian (Florian Pelz)]

On Wed, Sep 16, 2020 at 12:37:20PM +0200, Ludovic Courtès wrote:
> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:
> >  Another example where @code{propagated-inputs} is useful is for languages
> >  that lack a facility to record the run-time search path akin to the
> >  @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
> > -more.  To ensure that libraries written in those languages can find
> > -library code they depend on at run time, run-time dependencies must be
> > -listed in @code{propagated-inputs} rather than @code{inputs}.
> > +more.  When packaging libraries written in those languages, ensure they can find
> > +library code they depend on at run time by listing run-time dependencies
> > +in @code{propagated-inputs} rather than @code{inputs}.
> 
> I’m not convinced about this hunk; it uses imperative tense towards the
> reader to state the same thing no?

The difference is “When packaging libraries”.  I suppose the intention
is that propagated-inputs be declared as part of library packages and
not as part of the application using those libraries.  I am unsure if
I understand correctly if “When packaging libraries” is not explicitly
stated.

Regards,
Florian

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[Ludovic Courtès]

Hi,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

> On Wed, Sep 16, 2020 at 12:37:20PM +0200, Ludovic Courtès wrote:
>> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:
>> >  Another example where @code{propagated-inputs} is useful is for languages
>> >  that lack a facility to record the run-time search path akin to the
>> >  @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
>> > -more.  To ensure that libraries written in those languages can find
>> > -library code they depend on at run time, run-time dependencies must be
>> > -listed in @code{propagated-inputs} rather than @code{inputs}.
>> > +more.  When packaging libraries written in those languages, ensure they can find
>> > +library code they depend on at run time by listing run-time dependencies
>> > +in @code{propagated-inputs} rather than @code{inputs}.
>> 
>> I’m not convinced about this hunk; it uses imperative tense towards the
>> reader to state the same thing no?
>
> The difference is “When packaging libraries”.  I suppose the intention
> is that propagated-inputs be declared as part of library packages and
> not as part of the application using those libraries.  I am unsure if
> I understand correctly if “When packaging libraries” is not explicitly
> stated.

Oh I see, that makes sense to me.  Go ahead!  :-)

Thanks,
Ludo’.

bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear

[pelzflorian (Florian Pelz)]

Thank you both!  Pushed as 125fc37e5f32afdbd1e5fca119c9eb41e7ad8ec1.
Closing.

Regards,
Florian