From ef606760abd87c98371fbc08c1f25ad897823a2a Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Wed, 22 Jul 2020 23:17:48 +0200 Subject: Pandoc conversion --- doc/manual/src/expressions/generic-builder.md | 61 +++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 doc/manual/src/expressions/generic-builder.md (limited to 'doc/manual/src/expressions/generic-builder.md') diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md new file mode 100644 index 000000000..cbc484199 --- /dev/null +++ b/doc/manual/src/expressions/generic-builder.md @@ -0,0 +1,61 @@ +# Generic Builder Syntax + +Recall from [???](#ex-hello-builder) that the builder looked something +like this: + + PATH=$perl/bin:$PATH + tar xvfz $src + cd hello-* + ./configure --prefix=$out + make + make install + +The builders for almost all Unix packages look like this — set up some +environment variables, unpack the sources, configure, build, and +install. For this reason the standard environment provides some Bash +functions that automate the build process. A builder using the generic +build facilities in shown in [example\_title](#ex-hello-builder2). + + buildInputs="$perl" + + source $stdenv/setup + + genericBuild + + - The buildInputs variable tells `setup` to use the indicated packages + as “inputs”. This means that if a package provides a `bin` + subdirectory, it's added to PATH; if it has a `include` + subdirectory, it's added to GCC's header search path; and so + on.\[1\] + + - The function `genericBuild` is defined in the file `$stdenv/setup`. + + - The final step calls the shell function `genericBuild`, which + performs the steps that were done explicitly in + [???](#ex-hello-builder). The generic builder is smart enough to + figure out whether to unpack the sources using `gzip`, `bzip2`, etc. + It can be customised in many ways; see the Nixpkgs manual for + details. + +Discerning readers will note that the buildInputs could just as well +have been set in the Nix expression, like this: + +``` + buildInputs = [ perl ]; +``` + +The `perl` attribute can then be removed, and the builder becomes even +shorter: + + source $stdenv/setup + genericBuild + +In fact, `mkDerivation` provides a default builder that looks exactly +like that, so it is actually possible to omit the builder for Hello +entirely. + +1. How does it work? `setup` tries to source the file + `pkg/nix-support/setup-hook` of all dependencies. These “setup + hooks” can then set up whatever environment variables they want; + for instance, the setup hook for Perl sets the PERL5LIB environment + variable to contain the `lib/site_perl` directories of all inputs. -- cgit v1.2.3 From f3903035667e158112dfd414091d8d50ef90c5f4 Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 23 Jul 2020 10:44:54 +0200 Subject: Reconvert --- doc/manual/src/expressions/generic-builder.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'doc/manual/src/expressions/generic-builder.md') diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index cbc484199..a00b08b55 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -22,9 +22,9 @@ build facilities in shown in [example\_title](#ex-hello-builder2). genericBuild - - The buildInputs variable tells `setup` to use the indicated packages - as “inputs”. This means that if a package provides a `bin` - subdirectory, it's added to PATH; if it has a `include` + - The `buildInputs` variable tells `setup` to use the indicated + packages as “inputs”. This means that if a package provides a `bin` + subdirectory, it's added to `PATH`; if it has a `include` subdirectory, it's added to GCC's header search path; and so on.\[1\] @@ -37,7 +37,7 @@ build facilities in shown in [example\_title](#ex-hello-builder2). It can be customised in many ways; see the Nixpkgs manual for details. -Discerning readers will note that the buildInputs could just as well +Discerning readers will note that the `buildInputs` could just as well have been set in the Nix expression, like this: ``` @@ -57,5 +57,6 @@ entirely. 1. How does it work? `setup` tries to source the file `pkg/nix-support/setup-hook` of all dependencies. These “setup hooks” can then set up whatever environment variables they want; - for instance, the setup hook for Perl sets the PERL5LIB environment - variable to contain the `lib/site_perl` directories of all inputs. + for instance, the setup hook for Perl sets the `PERL5LIB` + environment variable to contain the `lib/site_perl` directories of + all inputs. -- cgit v1.2.3 From 13df1faf25769924dae07e65f3ef3ffdd66f10ee Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 23 Jul 2020 13:58:49 +0200 Subject: Get rid of callouts since Markdown doesn't support them --- doc/manual/src/expressions/generic-builder.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) (limited to 'doc/manual/src/expressions/generic-builder.md') diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index a00b08b55..90bdc556b 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -13,24 +13,26 @@ like this: The builders for almost all Unix packages look like this — set up some environment variables, unpack the sources, configure, build, and install. For this reason the standard environment provides some Bash -functions that automate the build process. A builder using the generic -build facilities in shown in [example\_title](#ex-hello-builder2). +functions that automate the build process. Here is what a builder using +the generic build facilities looks like: - buildInputs="$perl" + buildInputs="$perl" ① - source $stdenv/setup + source $stdenv/setup ② - genericBuild + genericBuild ③ - - The `buildInputs` variable tells `setup` to use the indicated +Here is what each line means: + +1. The `buildInputs` variable tells `setup` to use the indicated packages as “inputs”. This means that if a package provides a `bin` subdirectory, it's added to `PATH`; if it has a `include` subdirectory, it's added to GCC's header search path; and so on.\[1\] - - The function `genericBuild` is defined in the file `$stdenv/setup`. +2. The function `genericBuild` is defined in the file `$stdenv/setup`. - - The final step calls the shell function `genericBuild`, which +3. The final step calls the shell function `genericBuild`, which performs the steps that were done explicitly in [???](#ex-hello-builder). The generic builder is smart enough to figure out whether to unpack the sources using `gzip`, `bzip2`, etc. -- cgit v1.2.3 From 8d0b311a1ccd0aef49c6f272aad4ecb5105b285a Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Fri, 24 Jul 2020 11:43:44 +0200 Subject: Get rid of footnotes Markdown doesn't support them. --- doc/manual/src/expressions/generic-builder.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) (limited to 'doc/manual/src/expressions/generic-builder.md') diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index 90bdc556b..6942abe70 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -27,8 +27,12 @@ Here is what each line means: 1. The `buildInputs` variable tells `setup` to use the indicated packages as “inputs”. This means that if a package provides a `bin` subdirectory, it's added to `PATH`; if it has a `include` - subdirectory, it's added to GCC's header search path; and so - on.\[1\] + subdirectory, it's added to GCC's header search path; and so on. + (This is implemented in a modular way: `setup` tries to source the + file `pkg/nix-support/setup-hook` of all dependencies. These “setup + hooks” can then set up whatever environment variables they want; for + instance, the setup hook for Perl sets the `PERL5LIB` environment + variable to contain the `lib/site_perl` directories of all inputs.) 2. The function `genericBuild` is defined in the file `$stdenv/setup`. @@ -55,10 +59,3 @@ shorter: In fact, `mkDerivation` provides a default builder that looks exactly like that, so it is actually possible to omit the builder for Hello entirely. - -1. How does it work? `setup` tries to source the file - `pkg/nix-support/setup-hook` of all dependencies. These “setup - hooks” can then set up whatever environment variables they want; - for instance, the setup hook for Perl sets the `PERL5LIB` - environment variable to contain the `lib/site_perl` directories of - all inputs. -- cgit v1.2.3 From da3d776cb91123a4d0528251b7ce909419ca0c7a Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Fri, 24 Jul 2020 14:31:33 +0200 Subject: Fix some dangling references --- doc/manual/src/expressions/generic-builder.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) (limited to 'doc/manual/src/expressions/generic-builder.md') diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index 6942abe70..43275dbf7 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -1,7 +1,7 @@ # Generic Builder Syntax -Recall from [???](#ex-hello-builder) that the builder looked something -like this: +Recall that the [build script for GNU Hello](build-script.md) looked +something like this: PATH=$perl/bin:$PATH tar xvfz $src @@ -37,11 +37,10 @@ Here is what each line means: 2. The function `genericBuild` is defined in the file `$stdenv/setup`. 3. The final step calls the shell function `genericBuild`, which - performs the steps that were done explicitly in - [???](#ex-hello-builder). The generic builder is smart enough to - figure out whether to unpack the sources using `gzip`, `bzip2`, etc. - It can be customised in many ways; see the Nixpkgs manual for - details. + performs the steps that were done explicitly in the previous build + script. The generic builder is smart enough to figure out whether + to unpack the sources using `gzip`, `bzip2`, etc. It can be + customised in many ways; see the Nixpkgs manual for details. Discerning readers will note that the `buildInputs` could just as well have been set in the Nix expression, like this: -- cgit v1.2.3 From 1d0a7b54fa330b041a720932ee4e05dcad1d2d5c Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Fri, 31 Jul 2020 15:43:25 +0200 Subject: Enable syntax highlighting --- doc/manual/src/expressions/generic-builder.md | 34 ++++++++++++++++----------- 1 file changed, 20 insertions(+), 14 deletions(-) (limited to 'doc/manual/src/expressions/generic-builder.md') diff --git a/doc/manual/src/expressions/generic-builder.md b/doc/manual/src/expressions/generic-builder.md index 43275dbf7..cf26b5f82 100644 --- a/doc/manual/src/expressions/generic-builder.md +++ b/doc/manual/src/expressions/generic-builder.md @@ -3,12 +3,14 @@ Recall that the [build script for GNU Hello](build-script.md) looked something like this: - PATH=$perl/bin:$PATH - tar xvfz $src - cd hello-* - ./configure --prefix=$out - make - make install +```bash +PATH=$perl/bin:$PATH +tar xvfz $src +cd hello-* +./configure --prefix=$out +make +make install +``` The builders for almost all Unix packages look like this — set up some environment variables, unpack the sources, configure, build, and @@ -16,11 +18,13 @@ install. For this reason the standard environment provides some Bash functions that automate the build process. Here is what a builder using the generic build facilities looks like: - buildInputs="$perl" ① - - source $stdenv/setup ② - - genericBuild ③ +```bash +buildInputs="$perl" ① + +source $stdenv/setup ② + +genericBuild ③ +``` Here is what each line means: @@ -45,15 +49,17 @@ Here is what each line means: Discerning readers will note that the `buildInputs` could just as well have been set in the Nix expression, like this: -``` +```nix buildInputs = [ perl ]; ``` The `perl` attribute can then be removed, and the builder becomes even shorter: - source $stdenv/setup - genericBuild +```bash +source $stdenv/setup +genericBuild +``` In fact, `mkDerivation` provides a default builder that looks exactly like that, so it is actually possible to omit the builder for Hello -- cgit v1.2.3