GNU bug report logs - #34574
Confusing manual entry for gexp->file

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 34574 in the body.
You can then email your comments to 34574 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: bug-guix <at> gnu.org
Subject: Confusing manual entry for gexp->file
Date: Tue, 19 Feb 2019 17:21:20 +0100

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

Message #8 received at 34574 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: "pelzflorian \(Florian Pelz\)" <pelzflorian <at> pelzflorian.de>
Cc: 34574 <at> debbugs.gnu.org
Subject: Re: bug#34574: Confusing manual entry for gexp->file
Date: Wed, 06 Mar 2019 14:17:49 +0100

Hi Florian,

"pelzflorian (Florian Pelz)" <pelzflorian <at> 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’.

Message #11 received at 34574 <at> debbugs.gnu.org (full text, mbox):

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: 34574 <at> debbugs.gnu.org
Subject: Re: bug#34574: Confusing manual entry for gexp->file
Date: Wed, 6 Mar 2019 19:35:19 +0100

On Wed, Mar 06, 2019 at 02:17:49PM +0100, Ludovic Courtès wrote:
> Hi Florian,
> 
> "pelzflorian (Florian Pelz)" <pelzflorian <at> 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

Message #16 received at 34574-done <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: "pelzflorian \(Florian Pelz\)" <pelzflorian <at> pelzflorian.de>
Cc: 34574-done <at> debbugs.gnu.org
Subject: Re: bug#34574: Confusing manual entry for gexp->file
Date: Fri, 08 Mar 2019 11:48:34 +0100

[Message part 1 (text/plain, inline)]

Hi Florian,

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

> On Wed, Mar 06, 2019 at 02:17:49PM +0100, Ludovic Courtès wrote:
>> Hi Florian,
>> 
>> "pelzflorian (Florian Pelz)" <pelzflorian <at> 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’.

[Message part 2 (text/x-patch, inline)]

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.