cafkafk/nixpkgs
cafkafk/nixpkgs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

review pass

Browse source
This commit is contained in:
Valentin Gagarin 2024-01-15 22:31:47 +01:00 committed by fricklerhandwerk
parent 2e2aaa1c2e
commit b22ec91243
1 changed files with 115 additions and 94 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

209
doc/build-helpers/trivial-build-helpers.chapter.md
View file

@ -1,6 +1,7 @@
# Trivial build helpers {#chap-trivial-builders} # Trivial build helpers {#chap-trivial-builders}
Nixpkgs provides a variety of wrapper functions that help build commonly useful derivations. Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these builders creates a derivation, but the arguments passed are different (usually simpler) from those required by `stdenv.mkDerivation`. Nixpkgs provides a variety of wrapper functions that help build commonly useful derivations.
Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these build helpers creates a derivation, but the arguments passed are different (usually simpler) from those required by `stdenv.mkDerivation`.
## `runCommand` {#trivial-builder-runCommand} ## `runCommand` {#trivial-builder-runCommand}
@ -58,21 +59,21 @@ Variant of `runCommand` that forces the derivation to be built locally, it is no
This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr-allowSubstitutes), so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g., just copying some files to a different location or adding symlinks) because there the `system` is usually the same as `builtins.currentSystem`. This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr-allowSubstitutes), so only use `runCommandLocal` if you are certain the user will always have a builder for the `system` of the derivation. This should be true for most trivial use cases (e.g., just copying some files to a different location or adding symlinks) because there the `system` is usually the same as `builtins.currentSystem`.
::: :::
## `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, `writeShellScriptBin` {#trivial-builder-text-writing} ## Writing text files {#trivial-builder-text-writing}
Nixpkgs provides the following functions for producing derivations which write text into the Nix store: `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin`. Nixpkgs provides the following functions for producing derivations which write text files or executable scripts into the Nix store.
They are useful for creating files from Nix expression, and are all implemented as convenience wrappers around `writeTextFile`.
`writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin` are convenience functions over `writeTextFile`. Each of these functions will cause a derivation to be produced.
When you coerce the result of each of these functions to a string with [string interpolation](https://nixos.org/manual/nix/stable/language/string-interpolation) or [`builtins.toString`](https://nixos.org/manual/nix/stable/language/builtins#builtins-toString), it will evaluate to the [store path](https://nixos.org/manual/nix/stable/store/store-path) of this derivation.
These are useful for creating files from Nix expressions, which may be scripts or non-executable text files.
Each of these functions will cause a derivation to be produced. When you coerce the result of each of these functions to a string, it will evaluate to the *store path* of this derivation.
:::: {.note} :::: {.note}
Some of these functions will put the resulting files within a directory inside the derivation output. If you need to refer to the resulting files somewhere else in Nix code, remember to append the path to the file. For example, if the derivation destination is a directory: Some of these functions will put the resulting files within a directory inside the [derivation output](https://nixos.org/manual/nix/stable/language/derivations#attr-outputs).
If you need to refer to the resulting files somewhere else in a Nix expression, append their path to the derivation's store path.
For example, if the file destination is a directory:
```nix ```nix
my-file = writeTextFile { my-file = writeTextFile {
name = "my-file"; name = "my-file";
text = '' text = ''
@ -82,60 +83,83 @@ my-file = writeTextFile {
} }
``` ```
Remember to append "/share/my-file" to the derivation path when using it elsewhere: Remember to append "/share/my-file" to the resulting store path when using it elsewhere:
```nix ```nix
writeShellScript "evaluate-my-file.sh" '' writeShellScript "evaluate-my-file.sh" ''
cat ${my-file}/share/my-file cat ${my-file}/share/my-file
''; '';
``` ```
:::: ::::
### `writeTextFile` {#trivial-builder-writeTextFile} ### `writeTextFile` {#trivial-builder-writeTextFile}
Writes a text file to the store Write a text file to the Nix store.
`writeTextFile` takes an attribute set with the following possible attributes: `writeTextFile` takes an attribute set with the following possible attributes:
`name` `name` (String)
: Corresponds to the name used in the Nix store path identifier. : Corresponds to the name used in the Nix store path identifier.
`text` `text` (String)
: The contents of the file. : The contents of the file.
`executable` _optional_ `executable` (Bool, _optional_)
: Make this file have the executable bit set. Defaults to `false` : Make this file have the executable bit set.
`destination` _optional_ Default: `false`
: Supplies a subpath under the derivation's Nix store ouput path into which to create the file. It may contain directory path elements, these are created automatically when the derivation is realized. Defaults to `""`, which indicates that the store path itself will be a file containing the text contents. `destination` (String, _optional_)
`checkPhase` _optional_ : A subpath under the derivation's output path into which to put the file.
Subdirectories are created automatically when the derivation is realised.
: Commands to run after generating the file, e.g. lints. It defaults to `""` (no checking). By default, the store path itself will be a file containing the text contents.
`meta` _optional_ Default: `""`
: Additional metadata for the derivation. It defaults to `{}`. `checkPhase` (String, _optional_)
`allowSubstitutes` _optional_ : Commands to run after generating the file.
: Whether to allow substituting from a binary cache. It defaults to `false`, as the operation is assumed to be faster performed locally. You may want to set this to true if the `checkPhase` step is expensive. Default: `""`
`preferLocalBuild` _optional_ `meta` (Attribute set, _optional_)
: Whether to prefer building locally, even if faster remote builders are available. It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`. : Additional metadata for the derivation.
Default: `{}`
`allowSubstitutes` (Bool, _optional_)
: Whether to allow substituting from a binary cache.
Passed through to [`allowSubsitutes`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-allowSubstitutes) of the underlying call to `builtins.derivation`.
It defaults to `false`, as running the derivation's simple `builder` executable locally is assumed to be faster than network operations.
Set it to true if the `checkPhase` step is expensive.
Default: `false`
`preferLocalBuild` (Bool, _optional_)
: Whether to prefer building locally, even if faster [remote build machines](https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-substituters) are available.
Passed through to [`preferLocalBuild`](https://nixos.org/manual/nix/stable/language/advanced-attributes#adv-attr-preferLocalBuild) of the underlying call to `builtins.derivation`.
It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`.
Default: `true`
The resulting store path will include some variation of the name, and it will be a file unless `destination` is used, in which case it will be a directory. The resulting store path will include some variation of the name, and it will be a file unless `destination` is used, in which case it will be a directory.
::: {.example #ex-writeTextFile} ::: {.example #ex-writeTextFile}
# Usage 1 of `writeTextFile` # Usage 1 of `writeTextFile`
Writes my-file to `/nix/store/<store path>/some/subpath/my-cool-script`, making it executable. It also runs a check on the resulting file in a `checkPhase`, and supplies values for the less-used options. Write `my-file` to `/nix/store/<store path>/some/subpath/my-cool-script`, making it executable.
Also run a check on the resulting file in a `checkPhase`, and supply values for the less-used options.
```nix ```nix
writeTextFile { writeTextFile {
@ -161,7 +185,8 @@ writeTextFile {
::: {.example #ex2-writeTextFile} ::: {.example #ex2-writeTextFile}
# Usage 2 of `writeTextFile` # Usage 2 of `writeTextFile`
Writes `Contents of File` to `/nix/store/<store path>`. See also the `writeText` helper function below. Write the string `Contents of File` to `/nix/store/<store path>`.
See also the [](#trivial-builder-writeText) helper function.
```nix ```nix
writeTextFile { writeTextFile {
@ -176,43 +201,42 @@ writeTextFile {
::: {.example #ex3-writeTextFile} ::: {.example #ex3-writeTextFile}
# Usage 3 of `writeTextFile` # Usage 3 of `writeTextFile`
Writes an executable `my-file` to `/nix/store/<store path>/bin/my-file`. See also the `writeScriptBin` helper function below. Write an executable script `my-script` to `/nix/store/<store path>/bin/my-script`.
See also the [](#trivial-builder-writeScriptBin) helper function.
```nix ```nix
writeTextFile { writeTextFile {
name = "my-file"; name = "my-script";
text = '' text = ''
echo "hi" echo "hi"
''; '';
executable = true; executable = true;
destination = "/bin/my-file"; destination = "/bin/my-script";
} }
``` ```
::: :::
### `writeText` {#trivial-builder-writeText} ### `writeText` {#trivial-builder-writeText}
Writes a text file to the store Write a text file to the Nix store
`writeText` takes two arguments: `name` and `text`, each of which should be `writeText` takes the following arguments:
a string. a string.
`name` `name` (String)
: the name used in the Nix store path. : The name used in the Nix store path.
`text` `text` (String)
: will be the contents of the file. : The contents of the file.
The store path will include the the name, and it will be a file. The store path will include the name, and it will be a file.
Here is an example.
::: {.example #ex-writeText} ::: {.example #ex-writeText}
# Usage of `writeText` # Usage of `writeText`
Writes `Contents of File` to `/nix/store/<store path>` Write the string `Contents of File` to `/nix/store/<store path>`:
```nix ```nix
writeText "my-file" writeText "my-file"
@ -222,7 +246,7 @@ writeText "my-file"
``` ```
::: :::
This example is equivalent to: This is equivalent to:
```nix ```nix
writeTextFile { writeTextFile {
@ -235,24 +259,24 @@ writeTextFile {
### `writeTextDir` {#trivial-builder-writeTextDir} ### `writeTextDir` {#trivial-builder-writeTextDir}
Writes a text file within a subdirectory of the store. Write a text file within a subdirectory of the Nix store.
`writeTextDir` takes two arguments: `path` and `text`, each of which should be a string. `writeTextDir` takes the following arguments:
`path` `path` (String)
: the destination within the Nix store path under which to create the file. : The destination within the Nix store path under which to create the file.
`text` `text` (String)
: the contents of the file. : The contents of the file.
The store path will be a directory. The store path will be a directory.
::: {.example #ex-writeTextDir} ::: {.example #ex-writeTextDir}
# Usage of `writeTextDir` # Usage of `writeTextDir`
Writes `Contents of File` to `/nix/store/<store path>/share/my-file`. Write the string `Contents of File` to `/nix/store/<store path>/share/my-file`:
```nix ```nix
writeTextDir "share/my-file" writeTextDir "share/my-file"
@ -262,7 +286,7 @@ writeTextDir "share/my-file"
``` ```
::: :::
This example is equivalent to: This is equivalent to:
```nix ```nix
writeTextFile { writeTextFile {
@ -276,28 +300,25 @@ writeTextFile {
### `writeScript` {#trivial-builder-writeScript} ### `writeScript` {#trivial-builder-writeScript}
Writes a script within the store. Write an executable script file to the Nix store.
`writeScript` takes two arguments: `name` and `text`, each of which should be a string. `writeScript` takes the following arguments:
`name` `name` (String)
: the name used in the Nix store path. : The name used in the Nix store path.
`text` `text` (String)
: the contents of the file. : The contents of the file.
The created file is marked as executable. The created file is marked as executable.
The store path will include the name, and it will be a file.
The store path will include the the name, and it will be a file.
Here is an example.
::: {.example #ex-writeScript} ::: {.example #ex-writeScript}
# Usage of `writeScript` # Usage of `writeScript`
Writes `Contents of File` to `/nix/store/<store path>` and makes the store path executable. Write the string `Contents of File` to `/nix/store/<store path>` and make the file executable.
```nix ```nix
writeScript "my-file" writeScript "my-file"
@ -307,7 +328,7 @@ writeScript "my-file"
``` ```
::: :::
This example is equivalent to: This is equivalent to:
```nix ```nix
writeTextFile { writeTextFile {
@ -321,26 +342,26 @@ writeTextFile {
### `writeScriptBin` {#trivial-builder-writeScriptBin} ### `writeScriptBin` {#trivial-builder-writeScriptBin}
Writes a script within a "bin" subirectory of a subdirectory of the store. Write a script within a `bin` subirectory of a directory in the Nix store.
This is for consistency with the convention of software packages placing executables under `bin`.
`writeScriptBin` takes two arguments: `name` and `text`, each of which should be a string. `writeScriptBin` takes the following arguments:
`name` `name` (String)
: the name used in the Nix store path and within the file generated under the store path. : The name used in the Nix store path and within the file created under the store path.
`text` `text` (String)
: the contents of the file. : The contents of the file.
The created file is marked as executable. The created file is marked as executable.
The file's contents will be put into `/nix/store/<store path>/bin/<name>`. The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
The store path will include the the name, and it will be a directory. The store path will include the the name, and it will be a directory.
::: {.example #ex-writeScriptBin} ::: {.example #ex-writeScriptBin}
# Usage of `writeScriptBin` # Usage of `writeScriptBin`
```nix ```nix
writeScriptBin "my-script" writeScriptBin "my-script"
'' ''
@ -349,7 +370,7 @@ writeScriptBin "my-script"
``` ```
::: :::
This example is equivalent to: This is equivalent to:
```nix ```nix
writeTextFile { writeTextFile {
@ -364,28 +385,27 @@ writeTextFile {
### `writeShellScript` {#trivial-builder-writeShellScript} ### `writeShellScript` {#trivial-builder-writeShellScript}
Writes a shell script to the store. Write a Bash script to the store.
`writeShellScript` takes two arguments: `name` and `text`, each of which should be a string. `writeShellScript` takes the following arguments:
`name` `name` (String)
: the name used in the Nix store path. : The name used in the Nix store path.
`text` `text` (String)
: the contents of the file. : The contents of the file.
The created file is marked as executable. The created file is marked as executable.
The store path will include the name, and it will be a file.
This function is almost exactly like `writeScript`, but it prepends a shebang line that points to the runtime shell (usually bash) at the top of the file contents. This function is almost exactly like [](#trivial-builder-writeScript), except that it prepends to the file a [shebang](https://en.wikipedia.org/wiki/Shebang_%28Unix%29) line that points to the version of Bash used in Nixpkgs.
<!-- this cannot be changed in practice, so there is no point pretending it's somehow generic -->
The store path will include the the name, and it will be a file.
Here is an example.
::: {.example #ex-writeShellScript} ::: {.example #ex-writeShellScript}
# Usage of `writeShellScript` # Usage of `writeShellScript`
```nix ```nix
writeShellScript "my-script" writeShellScript "my-script"
'' ''
@ -394,7 +414,7 @@ writeShellScript "my-script"
``` ```
::: :::
This example is equivalent to: This is equivalent to:
```nix ```nix
writeTextFile { writeTextFile {
@ -406,28 +426,29 @@ writeTextFile {
executable = true; executable = true;
} }
``` ```
### `writeShellScriptBin` {#trivial-builder-writeShellScriptBin} ### `writeShellScriptBin` {#trivial-builder-writeShellScriptBin}
Writes a shell script to a "bin" subdirectory of subdirectory of the store. Write a Bash script to a "bin" subdirectory of a directory in the Nix store.
`writeShellScriptBin` takes two arguments: `name` and `text`, each of which should be a string. `writeShellScriptBin` takes the following arguments:
`name` `name` (String)
: the name used in the Nix store path and within the file generated under the store path. : The name used in the Nix store path and within the file generated under the store path.
`text` `text` (String)
: the contents of the file. : The contents of the file.
This function is almost exactly like `writeScriptBin`, but it prepends a shebang line that points to the runtime shell (usually bash) at the top of the file contents.
The file's contents will be put into `/nix/store/<store path>/bin/<name>`. The file's contents will be put into `/nix/store/<store path>/bin/<name>`.
The store path will include the the name, and it will be a directory. The store path will include the the name, and it will be a directory.
This function is a combination of [](#trivial-builder-writeShellScript) and [](#trivial-builder-writeScriptBin).
::: {.example #ex-writeShellScriptBin} ::: {.example #ex-writeShellScriptBin}
# Usage of `writeShellScriptBin` # Usage of `writeShellScriptBin`
```nix ```nix
writeShellScriptBin "my-script" writeShellScriptBin "my-script"
'' ''
@ -436,7 +457,7 @@ writeShellScriptBin "my-script"
``` ```
::: :::
This example is equivalent to: This is equivalent to:
```nix ```nix
writeTextFile { writeTextFile {