bug#34574: Confusing manual entry for gexp->file

bug#34574: Confusing manual entry for gexp->file

[pelzflorian (Florian Pelz)]

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

bug#34574: Confusing manual entry for gexp->file

[Ludovic Courtès]

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’.

bug#34574: Confusing manual entry for gexp->file

[pelzflorian (Florian Pelz)]

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.

Regards,
Florian

bug#34574: Confusing manual entry for gexp->file

[Ludovic Courtès]

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

Hi Florian,

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

> 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’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1538 bytes --]

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