From 76ea89aa78c9099a2e5c5121942cdaa8b2d52c89 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Sun, 22 Jan 2017 14:36:46 -0500 Subject: nixpkgs doc: Talk about nativeBuildInputs and propgatedNativeBuildInputs Do so in the stdenv section where the other two are discussed. This can be done without brining up cross-compilation by talking about build-time vs run-time. --- doc/stdenv.xml | 92 +++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 55 insertions(+), 37 deletions(-) (limited to 'doc/stdenv.xml') diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 44a0e4601fc12..6ec5c9f2814ff 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -194,33 +194,52 @@ genericBuild tools. + + + + Variables specifying dependencies + + + nativeBuildInputs + + A list of dependencies used by the new derivation at build-time. + I.e. these dependencies should not make it into the package's runtime-closure, though this is currently not checked. + For each dependency dir, the directory dir/bin, if it exists, is added to the PATH environment variable. + Other environment variables are also set up via a pluggable mechanism. + For instance, if buildInputs contains Perl, then the lib/site_perl subdirectory of each input is added to the PERL5LIB environment variable. + See for details. + + + buildInputs - A list of dependencies used by - stdenv to set up the environment for the build. - For each dependency dir, the directory - dir/bin, if it - exists, is added to the PATH environment variable. - Other environment variables are also set up via a pluggable - mechanism. For instance, if buildInputs - contains Perl, then the lib/site_perl - subdirectory of each input is added to the PERL5LIB - environment variable. See for - details. - - + + A list of dependencies used by the new derivation at run-time. + Currently, the build-time environment is modified in the exact same way as with nativeBuildInputs. + This is problematic in that when cross-compiling, foreign executables can clobber native ones on the PATH. + Even more confusing is static-linking. + A statically-linked library should be listed here because ultimately that generated machine code will be used at run-time, even though a derivation containing the object files or static archives will only be used at build-time. + A less confusing solution to this would be nice. + + + + + + propagatedNativeBuildInputs + + Like nativeBuildInputs, but these dependencies are propagated: + that is, the dependencies listed here are added to the nativeBuildInputs of any package that uses this package as a dependency. + So if package Y has propagatedBuildInputs = [X], and package Z has buildInputs = [Y], then package X will appear in Z’s build environment automatically. + + + propagatedBuildInputs - Like buildInputs, but these - dependencies are propagated: that is, the - dependencies listed here are added to the - buildInputs of any package that uses - this package as a dependency. So if package - Y has propagatedBuildInputs = [X], and package - Z has buildInputs = [Y], then package X will - appear in Z’s build environment automatically. + + Like buildInputs, but propagated just like propagatedNativeBuildInputs. + This inherits buildInputs's flaws of clobbering native executables when cross-compiling and being confusing for static linking. + - @@ -322,7 +341,7 @@ executed and in what order: $preInstallPhases installPhase fixupPhase $preDistPhases distPhase $postPhases. - + Usually, if you just want to add a few phases, it’s more convenient to set one of the variables below (such as preInstallPhases), as you then don’t specify @@ -706,7 +725,7 @@ makeFlagsArray=(CFLAGS="-O0 -g" LDFLAGS="-lfoo -lbar") - + You can set flags for make through the makeFlags variable. @@ -773,7 +792,7 @@ doCheck = true; - + @@ -840,12 +859,12 @@ install phase. The default fixupPhase does the following: - + It moves the man/, doc/ and info/ subdirectories of $out to share/. - + It strips libraries and executables of debug information. @@ -1091,13 +1110,13 @@ functions. - + substitute infile outfile subs - + Performs string substitution on the contents of infile, writing the result to @@ -1125,7 +1144,7 @@ functions. @...@ in the template as placeholders. - + varName @@ -1134,7 +1153,7 @@ functions. @varName@ by the string s. - + @@ -1162,7 +1181,7 @@ substitute ./foo.in ./foo.out \ - + substituteInPlace @@ -1173,7 +1192,7 @@ substitute ./foo.in ./foo.out \ file. - + substituteAll infile @@ -1233,7 +1252,7 @@ echo @foo@ Strips the directory and hash part of a store path, outputting the name part to stdout. For example: - + # prints coreutils-8.24 stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" @@ -1241,7 +1260,7 @@ stripHash "/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" If you wish to store the result in another variable, then the following idiom may be useful: - + name="/nix/store/9s9r019176g7cvn2nvcw41gsp862y6b4-coreutils-8.24" someVar=$(stripHash $name) @@ -1250,7 +1269,7 @@ someVar=$(stripHash $name) - + @@ -1607,4 +1626,3 @@ Arch Wiki. - -- cgit 1.4.1