documentation: Explanation of propagated-inputs unclear

  • Done
  • quality assurance status badge
Details
3 participants
  • Ludovic Courtès
  • pelzflorian (Florian Pelz)
  • zimoun
Owner
unassigned
Submitted by
pelzflorian (Florian Pelz)
Severity
normal
P
P
pelzflorian (Florian Pelz) wrote on 19 Mar 2017 08:03
(address . bug-guix@gnu.org)
03214f18-23c3-3879-0be3-f1abb95abcea@pelzflorian.de
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
Z
Z
zimoun wrote on 3 Dec 2019 13:14
Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear
CAJ3okZ3=1GeVM6_hOWkUfc_rLODR=Lr7SF_6q=90NCO7vQvL2g@mail.gmail.com
Dear Florian,

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


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



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).
Toggle quote (2 lines)
>>

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
P
P
pelzflorian (Florian Pelz) wrote on 3 Dec 2019 13:49
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 26170@debbugs.gnu.org)
20191203124904.lotocvk7htki2ill@pelzflorian.localdomain
On Tue, Dec 03, 2019 at 01:14:05PM +0100, zimoun wrote:
Toggle quote (13 lines)
> 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
Z
Z
zimoun wrote on 9 Sep 2020 15:25
Re: bug#26170: Bug #26170 Hunting: doc: Explanation of propagated-inputs unclear
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)(address . 26170@debbugs.gnu.org)
87h7s7ulo4.fsf@gmail.com
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:

Toggle snippet (13 lines)
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).

which now appear to me clarified with the current manual.

Does it make sense to close?

All the best,
simon


[3]
P
P
pelzflorian (Florian Pelz) wrote on 9 Sep 2020 17:10
(name . zimoun)(address . zimon.toutoune@gmail.com)(address . 26170@debbugs.gnu.org)
20200909151021.dnte7uodi3gj5t6r@pelzflorian.localdomain
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:
Toggle quote (17 lines)
> 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`.


Toggle quote (5 lines)
> 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
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.


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

Toggle diff (33 lines)
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
Z
Z
zimoun wrote on 9 Sep 2020 17:45
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)(address . 26170@debbugs.gnu.org)
874ko7uf6c.fsf@gmail.com
On Wed, 09 Sep 2020 at 17:10, "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> wrote:
Toggle quote (3 lines)
> Thank you for bringing up this bug again with detailed
> cross-referencing. Sorry for not sending a patch earlier.

My pleasure. :-)


Toggle quote (25 lines)
>>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. :-)

Toggle quote (7 lines)
> 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.

Toggle quote (13 lines)
> 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. :-)
Toggle quote (4 lines)
> @item @code{outputs} (default: @code{'("out")})
> The list of output names of the package. @xref{Packages with Multiple


All the best,
simon
L
L
Ludovic Courtès wrote on 16 Sep 2020 12:37
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)
87een2nh27.fsf@gnu.org
Hi,

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

Toggle quote (25 lines)
> 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.

Toggle quote (10 lines)
> 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’.
P
P
pelzflorian (Florian Pelz) wrote on 16 Sep 2020 15:27
(name . Ludovic Courtès)(address . ludo@gnu.org)
20200916132752.cfkabi2bdmgpdnm3@pelzflorian.localdomain
On Wed, Sep 16, 2020 at 12:37:20PM +0200, Ludovic Courtès wrote:
Toggle quote (14 lines)
> "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
L
L
Ludovic Courtès wrote on 17 Sep 2020 21:45
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)
87tuvw6vcq.fsf@gnu.org
Hi,

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

Toggle quote (21 lines)
> 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’.
P
P
pelzflorian (Florian Pelz) wrote on 18 Sep 2020 11:08
(name . Ludovic Courtès)(address . ludo@gnu.org)
20200918090842.dqv3w6h5dq4otqzx@pelzflorian.localdomain
Thank you both! Pushed as 125fc37e5f32afdbd1e5fca119c9eb41e7ad8ec1.
Closing.

Regards,
Florian
Closed
?
Your comment

This issue is archived.

To comment on this conversation send an email to 26170@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 26170
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch