[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#34574: Confusing manual entry for gexp->file
From: |
Ludovic Courtès |
Subject: |
bug#34574: Confusing manual entry for gexp->file |
Date: |
Fri, 08 Mar 2019 11:48:34 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) |
Hi Florian,
"pelzflorian (Florian Pelz)" <address@hidden> skribis:
> On Wed, Mar 06, 2019 at 02:17:49PM +0100, Ludovic Courtès wrote:
>> Hi Florian,
>>
>> "pelzflorian (Florian Pelz)" <address@hidden> 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.)
address@hidden build-time dependencies
address@hidden 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.
address@hidden references
address@hidden run-time dependencies
address@hidden dependencies, run-time
+The outputs of derivations---i.e., the build results---have a set of
address@hidden, as reported by the @code{references} RPC or the
address@hidden 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