Confusing manual entry for gexp->file

  • Done
  • quality assurance status badge
Details
2 participants
  • Ludovic Courtès
  • pelzflorian (Florian Pelz)
Owner
unassigned
Submitted by
pelzflorian (Florian Pelz)
Severity
normal

Debbugs page

pelzflorian (Florian Pelz) wrote 6 years ago
(address . bug-guix@gnu.org)
20190219162120.7evs2ynhhdksyq2d@pelzflorian.localdomain
Hello,

The Guix manual contains the following description of gexp->file:

-- Monadic Procedure: gexp->file NAME EXP [#:set-load-path? #t]
[#:module-path %load-path] [#:splice? #f] [#:guile
(default-guile)] Return a derivation that builds a file NAME
containing EXP. When SPLICE? is true, EXP is considered to be a
list of expressions that will be spliced in the resulting file.

When SET-LOAD-PATH? is true, emit code in the resulting file to set
‘%load-path’ and ‘%load-compiled-path’ to honor EXP’s imported
modules. Look up EXP’s modules in MODULE-PATH.

The resulting file holds references to all the dependencies of EXP
or a subset thereof.

I do not understand this last sentence. How can it be a subset? A
subset of what? Can this be explained more clearly or removed?

Regards,
Florian
Ludovic Courtès wrote 6 years ago
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)(address . 34574@debbugs.gnu.org)
871s3kjg5e.fsf@gnu.org
Hi Florian,

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

Toggle quote (18 lines)
> The Guix manual contains the following description of gexp->file:
>
> -- Monadic Procedure: gexp->file NAME EXP [#:set-load-path? #t]
> [#:module-path %load-path] [#:splice? #f] [#:guile
> (default-guile)] Return a derivation that builds a file NAME
> containing EXP. When SPLICE? is true, EXP is considered to be a
> list of expressions that will be spliced in the resulting file.
>
> When SET-LOAD-PATH? is true, emit code in the resulting file to set
> ‘%load-path’ and ‘%load-compiled-path’ to honor EXP’s imported
> modules. Look up EXP’s modules in MODULE-PATH.
>
> The resulting file holds references to all the dependencies of EXP
> or a subset thereof.
>
> I do not understand this last sentence. How can it be a subset? A
> subset of what? Can this be explained more clearly or removed?

It can be a subset of the references of EXP because, when a build
completes, the daemon scan the output(s) to determine the set of
residual references. That’s the difference between build-time and
run-time dependencies.

For instance, ‘sed’ depends on ‘gcc’ and ‘gcc:lib’ at build time, but
its output depends only on ‘gcc:lib’.

Does that make sense?

Ludo’.
pelzflorian (Florian Pelz) wrote 6 years ago
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 34574@debbugs.gnu.org)
20190306183519.ws5hrx66ex4xa4d7@pelzflorian.localdomain
On Wed, Mar 06, 2019 at 02:17:49PM +0100, Ludovic Courtès wrote:
Toggle quote (34 lines)
> Hi Florian,
>
> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:
>
> > The Guix manual contains the following description of gexp->file:
> >
> > -- Monadic Procedure: gexp->file NAME EXP [#:set-load-path? #t]
> > [#:module-path %load-path] [#:splice? #f] [#:guile
> > (default-guile)] Return a derivation that builds a file NAME
> > containing EXP. When SPLICE? is true, EXP is considered to be a
> > list of expressions that will be spliced in the resulting file.
> >
> > When SET-LOAD-PATH? is true, emit code in the resulting file to set
> > ‘%load-path’ and ‘%load-compiled-path’ to honor EXP’s imported
> > modules. Look up EXP’s modules in MODULE-PATH.
> >
> > The resulting file holds references to all the dependencies of EXP
> > or a subset thereof.
> >
> > I do not understand this last sentence. How can it be a subset? A
> > subset of what? Can this be explained more clearly or removed?
>
> It can be a subset of the references of EXP because, when a build
> completes, the daemon scan the output(s) to determine the set of
> residual references. That’s the difference between build-time and
> run-time dependencies.
>
> For instance, ‘sed’ depends on ‘gcc’ and ‘gcc:lib’ at build time, but
> its output depends only on ‘gcc:lib’.
>
> Does that make sense?
>
> Ludo’.

Thank you. I did not know this is how the daemon determines outputs’
references. In this case I would understand the manual more easily if
it said:

The output(s) resulting from this derivation will be scanned for
references by the daemon. They can hold references to all the
dependencies of EXP or a subset thereof.

Please make this more clear in the manual.

Regards,
Florian
Ludovic Courtès wrote 6 years ago
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)(address . 34574-done@debbugs.gnu.org)
87r2bhhcal.fsf@gnu.org
Hi Florian,

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

Toggle quote (45 lines)
> On Wed, Mar 06, 2019 at 02:17:49PM +0100, Ludovic Courtès wrote:
>> Hi Florian,
>>
>> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:
>>
>> > The Guix manual contains the following description of gexp->file:
>> >
>> > -- Monadic Procedure: gexp->file NAME EXP [#:set-load-path? #t]
>> > [#:module-path %load-path] [#:splice? #f] [#:guile
>> > (default-guile)] Return a derivation that builds a file NAME
>> > containing EXP. When SPLICE? is true, EXP is considered to be a
>> > list of expressions that will be spliced in the resulting file.
>> >
>> > When SET-LOAD-PATH? is true, emit code in the resulting file to set
>> > ‘%load-path’ and ‘%load-compiled-path’ to honor EXP’s imported
>> > modules. Look up EXP’s modules in MODULE-PATH.
>> >
>> > The resulting file holds references to all the dependencies of EXP
>> > or a subset thereof.
>> >
>> > I do not understand this last sentence. How can it be a subset? A
>> > subset of what? Can this be explained more clearly or removed?
>>
>> It can be a subset of the references of EXP because, when a build
>> completes, the daemon scan the output(s) to determine the set of
>> residual references. That’s the difference between build-time and
>> run-time dependencies.
>>
>> For instance, ‘sed’ depends on ‘gcc’ and ‘gcc:lib’ at build time, but
>> its output depends only on ‘gcc:lib’.
>>
>> Does that make sense?
>>
>> Ludo’.
>
> Thank you. I did not know this is how the daemon determines outputs’
> references. In this case I would understand the manual more easily if
> it said:
>
> The output(s) resulting from this derivation will be scanned for
> references by the daemon. They can hold references to all the
> dependencies of EXP or a subset thereof.
>
> Please make this more clear in the manual.

The explanation isn’t specific to ‘gexp->file’ so I’ve added the
following text under “Derivations”.

Thanks,
Ludo’.
modified doc/guix.texi
@@ -6238,8 +6238,11 @@ The outputs of the derivation---derivations produce at least one file or
directory in the store, but may produce more.
@item
-The inputs of the derivations, which may be other derivations or plain
-files in the store (patches, build scripts, etc.)
+@cindex build-time dependencies
+@cindex dependencies, build-time
+The inputs of the derivations---i.e., its build-time dependencies---which may
+be other derivations or plain files in the store (patches, build scripts,
+etc.)
@item
The system type targeted by the derivation---e.g., @code{x86_64-linux}.
@@ -6270,6 +6273,16 @@ of a fixed-output derivation are independent of its inputs---e.g., a
source code download produces the same result regardless of the download
method and tools being used.
+@cindex references
+@cindex run-time dependencies
+@cindex dependencies, run-time
+The outputs of derivations---i.e., the build results---have a set of
+@dfn{references}, as reported by the @code{references} RPC or the
+@command{guix gc --references} command (@pxref{Invoking guix gc}). References
+are the set of run-time dependencies of the build results. References are a
+subset of the inputs of the derivation; this subset is automatically computed
+by the build daemon by scanning all the files in the outputs.
+
The @code{(guix derivations)} module provides a representation of
derivations as Scheme objects, along with procedures to create and
otherwise manipulate derivations. The lowest-level primitive to create
Closed
?
Your comment

This issue is archived.

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

To respond to this issue using the mumi CLI, first switch to it
mumi current 34574
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
You may also tag this issue. See list of standard tags. For example, to set the confirmed and easy tags
mumi command -t +confirmed -t +easy
Or, remove the moreinfo tag and set the help tag
mumi command -t -moreinfo -t +help