From f4cdad8aabe3ca7a73ed4929a529b7d2e6e63566 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 29 Dec 2023 07:52:10 -0500 Subject: [PATCH 01/14] doc: improve documentation for trivial text writing functions --- .../trivial-build-helpers.chapter.md | 290 ++++++++++++++++-- 1 file changed, 268 insertions(+), 22 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index a0cda86a6607..4f19f57626c2 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -1,6 +1,6 @@ # Trivial build helpers {#chap-trivial-builders} -Nixpkgs provides a couple of functions that help with building derivations. The most important one, `stdenv.mkDerivation`, has already been documented above. The following functions wrap `stdenv.mkDerivation`, making it easier to use in certain cases. +`nixpkgs` provides a variety of wrapper functions that help build very simple derivations. Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these builders creates and returns a derivation, but the composition of the arguments passed to each are different (usually simpler) than the arguments that must be passed to `stdenv.mkDerivation`. ## `runCommand` {#trivial-builder-runCommand} @@ -58,24 +58,101 @@ 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`. ::: -## `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin` {#trivial-builder-writeText} +## `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, `writeShellScriptBin` {#trivial-builder-textwriting} -These functions write `text` to the Nix store. This is useful for creating scripts from Nix expressions. `writeTextFile` takes an attribute set and expects two arguments, `name` and `text`. `name` corresponds to the name used in the Nix store path. `text` will be the contents of the file. You can also set `executable` to true to make this file have the executable bit set. +`nixpkgs` provides a number of functions that produce derivations which write text into the Nix store. These include `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin`, each of which is documented below. -Many more commands wrap `writeTextFile` including `writeText`, `writeTextDir`, `writeScript`, and `writeScriptBin`. These are convenience functions over `writeTextFile`. +These are useful for creating files from Nix expressions, which may be scripts or non-executable text files, depending on which of the functions is used and the arguments it takes. + +The result of each of these functions will be a derivation. When you coerce the resulting derivation to text, it will evaluate to the *store path*. Importantly, it will not include the destination subpath produced by the particular function. So, for example, given the following expression: -Here are a few examples: ```nix + +my-file = writeTextFile { + name = "my-file"; + text = '' + Contents of File + ''; + destination = "/share/my-file"; +} +``` + +If `my-file` is coerced to text, it will resolve to `/nix/store/`, like any other derivation. It will *not* evaluate to `/nix/store//share/my-file`. So to use it elsewhere, as an example (in this case, within a shell script you're writing in a Nix expression via `writeShellScript`), you might do: + +```nix +writeShellScript "evaluate-my-file.sh" '' + cat ${my-file}/share/my-file +''; +``` + +This will produce the desired result. However, the following will not, it will fail because the store path is a directory, and is not the `my-file` file. + +```nix +writeShellScript "evaluate-my-file.sh" '' + cat ${my-file} +''; +``` + +### `writeTextFile` {#trivial-builder-writeTextFile} + +`writeTextFile` takes an attribute set and expects it to contain at least two attributes: `name` and `text`. + +`name` corresponds to the name used in the Nix store path identifier. + +`text` will be the contents of the file. + +The resulting store path will include some variation of the name, and it will be a file unless `destination` (see below) is used, in which case it will be a directory. + +Common optional attributes in the attribute set are: + +`executable`: make this file have the executable bit set. Defaults to `false` + +`destination`: 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. + +Other less-frequently used optional attributes are: + +`checkPhase`: commands to run after generating the file, e.g. lints. It defaults to `""` (no checking). + +`meta`: Additional metadata for the derivation. It defaults to `{}`. + +`allowSubstitutes`: whether to allow substituting from a binary cache. It fefaults 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. + +`preferLocalBuild`: whether to prefer building locally, even if faster remote builders are available. It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`. + +::: {.example #ex-writeTextFile} +# Usages of `writeTextFile` +```nix +# Writes my-file to /nix/store//some/subpath/my-cool-script, +# making it executable and also supplies values for the less-used options +writeTextFile rec { + name = "my-cool-script"; + text = '' + #!/bin/sh + echo "This is my cool script!" + ''; + executable = true; + destination = "some/subpath/my-cool-script"; + checkPhase = '' + ${pkgs.shellcheck}/bin/shellcheck $out/${destination} + ''; + meta = { + license = pkgs.lib.licenses.cc0; + }; + allowSubstitutes = true; + preferLocalBuild = false; +} + # Writes my-file to /nix/store/ +# See also the `writeText` helper function below. writeTextFile { name = "my-file"; text = '' Contents of File ''; } -# See also the `writeText` helper function below. # Writes executable my-file to /nix/store//bin/my-file +# see also the `writeScriptBin` helper function below. writeTextFile { name = "my-file"; text = '' @@ -84,37 +161,206 @@ writeTextFile { executable = true; destination = "/bin/my-file"; } -# Writes contents of file to /nix/store/ +``` +::: + +::: {.note} +The commands `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin` documented below are convenience functions that wrap `writeTextFile`. +::: + +### `writeText` {#trivial-builder-writeText} + +`writeText` takes two arguments: `name` and `text`. + +`name` is the name used in the Nix store path. `text` will be the contents of the file. + +The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. + +Here is an example. + +::: {.example #ex-writeText} +# Usage of `writeText` +```nix +# Writes my-file to /nix/store/ writeText "my-file" '' Contents of File ''; +``` +::: + +This example is a simpler way to spell: + +```nix +writeTextFile { + name = "my-file"; + text = '' + Contents of File + ''; +} +``` + +### `writeTextDir` {#trivial-builder-writeTextDir} + +`writeTextDir` takes two arguments: `path` and `text`. + +`path` is the destination within the Nix store path under which to create the file. `text` will be the contents of the file. + +The store path will be a directory. The Nix store identifier will be generated based on various elements of the path. + +::: {.example #ex-writeTextDir} +# Usage of `writeTextDir` +```nix # Writes contents of file to /nix/store//share/my-file writeTextDir "share/my-file" '' Contents of File ''; +``` +::: + +The example is a simpler way to spell: + +```nix +writeTextFile { + name = "my-file"; + text = '' + Contents of File + ''; + destination = "share/my-file"; +} +``` + +### `writeScript` {#trivial-builder-writeScript} + +`writeScript` takes two arguments: `name` and `text`. + +`name` is the name used in the Nix store path. `text` will be the contents of the file. The created file is marked as executable. + +The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. + +Here is an example. + +::: {.example #ex-writeScript} +# Usage of `writeScript` +```nix # Writes my-file to /nix/store/ and makes executable writeScript "my-file" '' Contents of File ''; -# Writes my-file to /nix/store//bin/my-file and makes executable. -writeScriptBin "my-file" - '' - Contents of File - ''; -# Writes my-file to /nix/store/ and makes executable. -writeShellScript "my-file" - '' - Contents of File - ''; -# Writes my-file to /nix/store//bin/my-file and makes executable. -writeShellScriptBin "my-file" - '' - Contents of File - ''; +``` +::: +The example is a simpler way to spell: + +```nix +writeTextFile { + name = "my-file"; + text = '' + Contents of File + ''; + executable = true; +} +``` + +### `writeScriptBin` {#trivial-builder-writeScriptBin} + +`writeScriptBin` takes two arguments: `name` and `text`. + +`name` is the name used in the Nix store path and within the file generated under the store path. `text` will be the contents of the file. The created file is marked as executable. + +The file's contents will be put into `/nix/store//bin/`. + +The store path will include the the name, and it will be a directory. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. + +::: {.example #ex-writeScriptBin} +# Usage of `writeScriptBin` +```nix +writeScriptBin "my-script" + '' + echo "hi" + ''; +``` +::: + +The example is a simpler way to spell: + +```nix +writeTextFile { + name = "my-script"; + text = '' + echo "hi" + ''; + executable = true; + destination = "bin/my-script" +} +``` + +### `writeShellScript` {#trivial-builder-writeShellScript} + +`writeShellScript` takes two arguments: `name` and `text`. + +`name` is the name used in the Nix store path. `text` will be the contents of the file. The created file is marked as executable. 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. + +The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. + +Here is an example. + +::: {.example #ex-writeShellScript} +# Usage of `writeShellScript` +```nix +writeShellScript "my-script" + '' + echo "hi" + ''; +``` +::: + +The example is a simpler way to spell: + +```nix +writeTextFile { + name = "my-script"; + text = '' + #! ${pkgs.runtimeShell} + echo "hi" + ''; + executable = true; +} +``` +### `writeShellScriptBin` {#trivial-builder-writeShellScriptBin} + +`writeShellScriptBin` takes two arguments: `name` and `text`. + +`name` is the name used in the Nix store path and within the file generated under the store path. `text` will be 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//bin/`. + +The store path will include the the name, and it will be a directory. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. + +::: {.example #ex-writeShellScriptBin} +# Usage of `writeShellScriptBin` +```nix +writeShellScriptBin "my-script" + '' + echo "hi" + ''; +``` +::: + +The example is a simpler way to spell: + +```nix +writeTextFile { + name = "my-script"; + text = '' + #! ${pkgs.runtimeShell} + echo "hi" + ''; + executable = true; + destination = "bin/my-script" +} ``` ## `concatTextFile`, `concatText`, `concatScript` {#trivial-builder-concatText} From 41c3d2d96cebd7d623a2d2d6b951c2f26c34d0d1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 11:24:26 -0500 Subject: [PATCH 02/14] update arguments to definition lists as per docs team meeeting / @danielsidhion --- .../trivial-build-helpers.chapter.md | 135 ++++++++++++++---- 1 file changed, 104 insertions(+), 31 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 4f19f57626c2..650f8aa4067a 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -95,30 +95,44 @@ writeShellScript "evaluate-my-file.sh" '' ### `writeTextFile` {#trivial-builder-writeTextFile} -`writeTextFile` takes an attribute set and expects it to contain at least two attributes: `name` and `text`. +Writes a text file to the store -`name` corresponds to the name used in the Nix store path identifier. +`writeTextFile` takes an attribute set with the following possible attributes: -`text` will be the contents of the file. +`name` + +: Corresponds to the name used in the Nix store path identifier. + +`text` + +: The contents of the file. + +`executable` _optional_ + +: Make this file have the executable bit set. Defaults to `false` + +`destination` _optional_ + +: 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. + +`checkPhase` _optional_ + +: Commands to run after generating the file, e.g. lints. It defaults to `""` (no checking). + +`meta` _optional_ + +: Additional metadata for the derivation. It defaults to `{}`. + +`allowSubstitutes` _optional_ + +: 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. + +`preferLocalBuild` _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`. The resulting store path will include some variation of the name, and it will be a file unless `destination` (see below) is used, in which case it will be a directory. -Common optional attributes in the attribute set are: - -`executable`: make this file have the executable bit set. Defaults to `false` - -`destination`: 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. - -Other less-frequently used optional attributes are: - -`checkPhase`: commands to run after generating the file, e.g. lints. It defaults to `""` (no checking). - -`meta`: Additional metadata for the derivation. It defaults to `{}`. - -`allowSubstitutes`: whether to allow substituting from a binary cache. It fefaults 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. - -`preferLocalBuild`: whether to prefer building locally, even if faster remote builders are available. It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`. - ::: {.example #ex-writeTextFile} # Usages of `writeTextFile` ```nix @@ -170,9 +184,18 @@ The commands `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writ ### `writeText` {#trivial-builder-writeText} -`writeText` takes two arguments: `name` and `text`. +Writes a text file to the store -`name` is the name used in the Nix store path. `text` will be the contents of the file. +`writeText` takes two arguments: `name` and `text`, each of which should be +a string. + +`name` + +: the name used in the Nix store path. + +`text` + +: will be the contents of the file. The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. @@ -202,9 +225,17 @@ writeTextFile { ### `writeTextDir` {#trivial-builder-writeTextDir} -`writeTextDir` takes two arguments: `path` and `text`. +Writes a text file within a subdirectory of the store. -`path` is the destination within the Nix store path under which to create the file. `text` will be the contents of the file. +`writeTextDir` takes two arguments: `path` and `text`, each of which should be a string. + +`path` + +: the destination within the Nix store path under which to create the file. + +`text` + +: the contents of the file. The store path will be a directory. The Nix store identifier will be generated based on various elements of the path. @@ -233,9 +264,19 @@ writeTextFile { ### `writeScript` {#trivial-builder-writeScript} -`writeScript` takes two arguments: `name` and `text`. +Writes a script within the store. -`name` is the name used in the Nix store path. `text` will be the contents of the file. The created file is marked as executable. +`writeScript` takes two arguments: `name` and `text`, each of which should be a string. + +`name` + +: the name used in the Nix store path. + +`text` + +: the contents of the file. + +The created file is marked as executable. The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. @@ -266,9 +307,19 @@ writeTextFile { ### `writeScriptBin` {#trivial-builder-writeScriptBin} -`writeScriptBin` takes two arguments: `name` and `text`. +Writes a script within a "bin" subirectory of a subdirectory of the store. -`name` is the name used in the Nix store path and within the file generated under the store path. `text` will be the contents of the file. The created file is marked as executable. +`writeScriptBin` takes two arguments: `name` and `text`, each of which should be a string. + +`name` + +: the name used in the Nix store path and within the file generated under the store path. + +`text` + +: the contents of the file. + +The created file is marked as executable. The file's contents will be put into `/nix/store//bin/`. @@ -299,9 +350,21 @@ writeTextFile { ### `writeShellScript` {#trivial-builder-writeShellScript} -`writeShellScript` takes two arguments: `name` and `text`. +Writes a shell script to the store. -`name` is the name used in the Nix store path. `text` will be the contents of the file. The created file is marked as executable. 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. +`writeShellScript` takes two arguments: `name` and `text`, each of which should be a string. + +`name` + +: the name used in the Nix store path. + +`text` + +: the contents of the file. + +The created file is marked as executable. + +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. The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. @@ -331,9 +394,19 @@ writeTextFile { ``` ### `writeShellScriptBin` {#trivial-builder-writeShellScriptBin} -`writeShellScriptBin` takes two arguments: `name` and `text`. +Writes a shell script to a "bin" subdirectory of subdirectory of the store. -`name` is the name used in the Nix store path and within the file generated under the store path. `text` will be 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. +`writeShellScriptBin` takes two arguments: `name` and `text`, each of which should be a string. + +`name` + +: the name used in the Nix store path and within the file generated under the store path. + +`text` + +: 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//bin/`. From 1e9fc75c6ee179872a0a9e0560fa638425a06fc7 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 12:17:24 -0500 Subject: [PATCH 03/14] whitespace cleanup --- doc/build-helpers/trivial-build-helpers.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 650f8aa4067a..4e15be0ba539 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -191,7 +191,7 @@ a string. `name` -: the name used in the Nix store path. +: the name used in the Nix store path. `text` From 32638686d1913cc867cb8ab4ab0115e312c65113 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 21:58:13 -0500 Subject: [PATCH 04/14] Apply @bzm3r suggestions from code review Co-authored-by: Brian Merchant --- .../trivial-build-helpers.chapter.md | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 4e15be0ba539..5cf60b7a0783 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -1,6 +1,6 @@ # Trivial build helpers {#chap-trivial-builders} -`nixpkgs` provides a variety of wrapper functions that help build very simple derivations. Like [`stdenv.mkDerivation`](#sec-using-stdenv), each of these builders creates and returns a derivation, but the composition of the arguments passed to each are different (usually simpler) than the arguments that must be passed to `stdenv.mkDerivation`. +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`. ## `runCommand` {#trivial-builder-runCommand} @@ -60,9 +60,11 @@ This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr ## `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, `writeShellScriptBin` {#trivial-builder-textwriting} -`nixpkgs` provides a number of functions that produce derivations which write text into the Nix store. These include `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin`, each of which is documented below. +Nixpkgs provides the following functions for producing derivations which write text into the Nix store: `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin`. -These are useful for creating files from Nix expressions, which may be scripts or non-executable text files, depending on which of the functions is used and the arguments it takes. +`writeText`, `writeTextDir`, `writeScript`, and `writeScriptBin` are convenience functions over `writeTextFile`. + +These are useful for creating files from Nix expressions, which may be scripts or non-executable text files. The result of each of these functions will be a derivation. When you coerce the resulting derivation to text, it will evaluate to the *store path*. Importantly, it will not include the destination subpath produced by the particular function. So, for example, given the following expression: @@ -212,7 +214,7 @@ writeText "my-file" ``` ::: -This example is a simpler way to spell: +This example is equivalent to: ```nix writeTextFile { @@ -250,7 +252,7 @@ writeTextDir "share/my-file" ``` ::: -The example is a simpler way to spell: +This example is equivalent to: ```nix writeTextFile { @@ -293,7 +295,7 @@ writeScript "my-file" ``` ::: -The example is a simpler way to spell: +This example is equivalent to: ```nix writeTextFile { @@ -335,7 +337,7 @@ writeScriptBin "my-script" ``` ::: -The example is a simpler way to spell: +This example is equivalent to: ```nix writeTextFile { @@ -380,7 +382,7 @@ writeShellScript "my-script" ``` ::: -The example is a simpler way to spell: +This example is equivalent to: ```nix writeTextFile { @@ -422,7 +424,7 @@ writeShellScriptBin "my-script" ``` ::: -The example is a simpler way to spell: +This example is equivalent to: ```nix writeTextFile { From 25b2c3a0cc480ee4f01c82df717f26f984a490d4 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 22:15:43 -0500 Subject: [PATCH 05/14] incorporate the spirit of change proposed by @DanielSidhion at https://github.com/NixOS/nixpkgs/pull/277534#discussion_r1450778530 --- .../trivial-build-helpers.chapter.md | 25 +++++-------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 5cf60b7a0783..a33d499ceb15 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -62,14 +62,16 @@ This sets [`allowSubstitutes` to `false`](https://nixos.org/nix/manual/#adv-attr Nixpkgs provides the following functions for producing derivations which write text into the Nix store: `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin`. -`writeText`, `writeTextDir`, `writeScript`, and `writeScriptBin` are convenience functions over `writeTextFile`. +`writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin` are convenience functions over `writeTextFile`. These are useful for creating files from Nix expressions, which may be scripts or non-executable text files. -The result of each of these functions will be a derivation. When you coerce the resulting derivation to text, it will evaluate to the *store path*. Importantly, it will not include the destination subpath produced by the particular function. So, for example, given the following expression: +Each of these functions will cause a derivation to be realized. When you coerce the result of each of these functions to a string, it will evaluate to the *store path* of this derivation. + +:::: {.warning} +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: ```nix - my-file = writeTextFile { name = "my-file"; text = '' @@ -77,23 +79,12 @@ my-file = writeTextFile { ''; destination = "/share/my-file"; } -``` -If `my-file` is coerced to text, it will resolve to `/nix/store/`, like any other derivation. It will *not* evaluate to `/nix/store//share/my-file`. So to use it elsewhere, as an example (in this case, within a shell script you're writing in a Nix expression via `writeShellScript`), you might do: - -```nix writeShellScript "evaluate-my-file.sh" '' cat ${my-file}/share/my-file ''; ``` - -This will produce the desired result. However, the following will not, it will fail because the store path is a directory, and is not the `my-file` file. - -```nix -writeShellScript "evaluate-my-file.sh" '' - cat ${my-file} -''; -``` +:::: ### `writeTextFile` {#trivial-builder-writeTextFile} @@ -180,10 +171,6 @@ writeTextFile { ``` ::: -::: {.note} -The commands `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, and `writeShellScriptBin` documented below are convenience functions that wrap `writeTextFile`. -::: - ### `writeText` {#trivial-builder-writeText} Writes a text file to the store From 7aa84efba2600d1c2446c2dee95cf8d36ba437bc Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 22:17:39 -0500 Subject: [PATCH 06/14] incorporate the suggestion at https://github.com/NixOS/nixpkgs/pull/277534/files#r1450959283 --- doc/build-helpers/trivial-build-helpers.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index a33d499ceb15..315d0c68d257 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -226,7 +226,7 @@ Writes a text file within a subdirectory of the store. : the contents of the file. -The store path will be a directory. The Nix store identifier will be generated based on various elements of the path. +The store path will be a directory. ::: {.example #ex-writeTextDir} # Usage of `writeTextDir` From 56108dd5ab70b012c7ffd885b84bb44a7367e4f0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 22:49:04 -0500 Subject: [PATCH 07/14] not realized; produced --- doc/build-helpers/trivial-build-helpers.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 315d0c68d257..1da9e3b4c955 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -66,7 +66,7 @@ Nixpkgs provides the following functions for producing derivations which write t 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 realized. When you coerce the result of each of these functions to a string, it will evaluate to the *store path* of this derivation. +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. :::: {.warning} 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: From 39227d5ce39c9004972ca3b15e89268ceaeca7db Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 22:53:50 -0500 Subject: [PATCH 08/14] describing the composiion of the store path elements is not really that useful --- doc/build-helpers/trivial-build-helpers.chapter.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 1da9e3b4c955..c8c141cc83e5 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -186,7 +186,7 @@ a string. : will be the contents of the file. -The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. +The store path will include the the name, and it will be a file. Here is an example. @@ -267,7 +267,7 @@ Writes a script within the store. The created file is marked as executable. -The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. +The store path will include the the name, and it will be a file. Here is an example. @@ -312,7 +312,7 @@ The created file is marked as executable. The file's contents will be put into `/nix/store//bin/`. -The store path will include the the name, and it will be a directory. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. +The store path will include the the name, and it will be a directory. ::: {.example #ex-writeScriptBin} # Usage of `writeScriptBin` @@ -355,7 +355,7 @@ The created file is marked as executable. 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. -The store path will include the the name, and it will be a file. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. +The store path will include the the name, and it will be a file. Here is an example. @@ -399,7 +399,7 @@ This function is almost exactly like `writeScriptBin`, but it prepends a shebang The file's contents will be put into `/nix/store//bin/`. -The store path will include the the name, and it will be a directory. Any path separators and shell-reserved elements in the name are escaped to create the store path identifier. +The store path will include the the name, and it will be a directory. ::: {.example #ex-writeShellScriptBin} # Usage of `writeShellScriptBin` From b0f542304df44f97abe8c497dce917c53d7cd972 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 12 Jan 2024 22:59:49 -0500 Subject: [PATCH 09/14] add to example --- doc/build-helpers/trivial-build-helpers.chapter.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index c8c141cc83e5..d21b311516d9 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -72,6 +72,9 @@ Each of these functions will cause a derivation to be produced. When you coerce 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: ```nix + +# if the derivation destination is a directory.... + my-file = writeTextFile { name = "my-file"; text = '' @@ -80,6 +83,9 @@ my-file = writeTextFile { destination = "/share/my-file"; } +# remember to tack on "/share/my-file" to the derivation path when +# using it elsewhere. + writeShellScript "evaluate-my-file.sh" '' cat ${my-file}/share/my-file ''; From 559d06bbb2c1db2a322c1508dccc241e1f95a56f Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 15 Jan 2024 09:02:45 +0100 Subject: [PATCH 10/14] trivial-builders: Remove redundant docs - link instead --- .../trivial-build-helpers.chapter.md | 2 +- .../trivial-builders/default.nix | 107 ++---------------- 2 files changed, 13 insertions(+), 96 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index d21b311516d9..398fb60fc880 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -58,7 +58,7 @@ 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`. ::: -## `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, `writeShellScriptBin` {#trivial-builder-textwriting} +## `writeTextFile`, `writeText`, `writeTextDir`, `writeScript`, `writeScriptBin`, `writeShellScript`, `writeShellScriptBin` {#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`. diff --git a/pkgs/build-support/trivial-builders/default.nix b/pkgs/build-support/trivial-builders/default.nix index bdb79d9bf463..93ae83a8ebd1 100644 --- a/pkgs/build-support/trivial-builders/default.nix +++ b/pkgs/build-support/trivial-builders/default.nix @@ -182,101 +182,32 @@ rec { eval "$checkPhase" ''; - /* - Writes a text file to nix store with no optional parameters available. - - Example: - - - # Writes contents of file to /nix/store/ - writeText "my-file" - '' - Contents of File - ''; - - - */ + # See doc/build-helpers/trivial-build-helpers.chapter.md + # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing writeText = name: text: writeTextFile { inherit name text; }; - /* - Writes a text file to nix store in a specific directory with no - optional parameters available. - - Example: - - - # Writes contents of file to /nix/store//share/my-file - writeTextDir "share/my-file" - '' - Contents of File - ''; - - - */ + # See doc/build-helpers/trivial-build-helpers.chapter.md + # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing writeTextDir = path: text: writeTextFile { inherit text; name = builtins.baseNameOf path; destination = "/${path}"; }; - /* - Writes a text file to /nix/store/ and marks the file as - executable. - - If passed as a build input, will be used as a setup hook. This makes setup - hooks more efficient to create: you don't need a derivation that copies - them to $out/nix-support/setup-hook, instead you can use the file as is. - - Example: - - - # Writes my-file to /nix/store/ and makes executable - writeScript "my-file" - '' - Contents of File - ''; - - - */ + # See doc/build-helpers/trivial-build-helpers.chapter.md + # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing writeScript = name: text: writeTextFile { inherit name text; executable = true; }; - /* - Writes a text file to /nix/store//bin/ and - marks the file as executable. - - Example: - - - - # Writes my-file to /nix/store//bin/my-file and makes executable. - writeScriptBin "my-file" - '' - Contents of File - ''; - - - */ + # See doc/build-helpers/trivial-build-helpers.chapter.md + # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing writeScriptBin = name: text: writeTextFile { inherit name text; executable = true; destination = "/bin/${name}"; }; - /* - Similar to writeScript. Writes a Shell script and checks its syntax. - Automatically includes interpreter above the contents passed. - - Example: - - - # Writes my-file to /nix/store/ and makes executable. - writeShellScript "my-file" - '' - Contents of File - ''; - - - */ + # See doc/build-helpers/trivial-build-helpers.chapter.md + # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing writeShellScript = name: text: writeTextFile { inherit name; @@ -290,22 +221,8 @@ rec { ''; }; - /* - Similar to writeShellScript and writeScriptBin. - Writes an executable Shell script to /nix/store//bin/ and checks its syntax. - Automatically includes interpreter above the contents passed. - - Example: - - - # Writes my-file to /nix/store//bin/my-file and makes executable. - writeShellScriptBin "my-file" - '' - Contents of File - ''; - - - */ + # See doc/build-helpers/trivial-build-helpers.chapter.md + # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing writeShellScriptBin = name: text: writeTextFile { inherit name; From cec3e9441cb04878705536d2861d92060ec7f86e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 15 Jan 2024 10:49:36 -0500 Subject: [PATCH 11/14] Move prose Co-authored-by: Alexander Groleau --- doc/build-helpers/trivial-build-helpers.chapter.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 398fb60fc880..d90fee192b25 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -71,9 +71,9 @@ Each of these functions will cause a derivation to be produced. When you coerce :::: {.warning} 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: -```nix -# if the derivation destination is a directory.... +If the derivation destination is a directory... +```nix my-file = writeTextFile { name = "my-file"; @@ -83,13 +83,13 @@ my-file = writeTextFile { destination = "/share/my-file"; } -# remember to tack on "/share/my-file" to the derivation path when -# using it elsewhere. - writeShellScript "evaluate-my-file.sh" '' cat ${my-file}/share/my-file ''; ``` +::: {.note} +Remember to tack on "/share/my-file" to the derivation path when using it elsewhere. +::: :::: ### `writeTextFile` {#trivial-builder-writeTextFile} From 39a1686e562aa3d53a74615dbda50f01574724c0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 15 Jan 2024 10:49:51 -0500 Subject: [PATCH 12/14] Add a period Co-authored-by: Alexander Groleau --- doc/build-helpers/trivial-build-helpers.chapter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index d90fee192b25..8a1fd61c18c8 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -69,7 +69,7 @@ These are useful for creating files from Nix expressions, which may be scripts o 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. :::: {.warning} -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: +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... From 2e2aaa1c2e48ef25fba479bb3e2e000fa9c65569 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 15 Jan 2024 11:29:35 -0500 Subject: [PATCH 13/14] do not nest a note within a warning, break out writeTextFile examples into multiple example sections, test first writeTextFile example (it was broken, heh) and fix, move prose out of code blocks --- .../trivial-build-helpers.chapter.md | 65 ++++++++++++------- 1 file changed, 42 insertions(+), 23 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 8a1fd61c18c8..54118fa773ae 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -68,11 +68,9 @@ These are useful for creating files from Nix expressions, which may be scripts o 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. -:::: {.warning} -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: +:::: {.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: - -If the derivation destination is a directory... ```nix my-file = writeTextFile { @@ -82,14 +80,16 @@ my-file = writeTextFile { ''; destination = "/share/my-file"; } +``` +Remember to append "/share/my-file" to the derivation path when using it elsewhere: + +```nix writeShellScript "evaluate-my-file.sh" '' cat ${my-file}/share/my-file ''; ``` -::: {.note} -Remember to tack on "/share/my-file" to the derivation path when using it elsewhere. -::: + :::: ### `writeTextFile` {#trivial-builder-writeTextFile} @@ -130,46 +130,59 @@ Writes a text file to the store : Whether to prefer building locally, even if faster remote builders are available. It defaults to `true` for the same reason `allowSubstitutes` defaults to `false`. -The resulting store path will include some variation of the name, and it will be a file unless `destination` (see below) 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} -# Usages of `writeTextFile` +# Usage 1 of `writeTextFile` + +Writes my-file to `/nix/store//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. + ```nix -# Writes my-file to /nix/store//some/subpath/my-cool-script, -# making it executable and also supplies values for the less-used options -writeTextFile rec { +writeTextFile { name = "my-cool-script"; text = '' #!/bin/sh echo "This is my cool script!" ''; executable = true; - destination = "some/subpath/my-cool-script"; + destination = "/some/subpath/my-cool-script"; checkPhase = '' - ${pkgs.shellcheck}/bin/shellcheck $out/${destination} + ${pkgs.shellcheck}/bin/shellcheck $out/some/subpath/my-cool-script ''; meta = { license = pkgs.lib.licenses.cc0; }; allowSubstitutes = true; preferLocalBuild = false; -} +}; +``` +::: -# Writes my-file to /nix/store/ -# See also the `writeText` helper function below. +::: {.example #ex2-writeTextFile} +# Usage 2 of `writeTextFile` + +Writes `Contents of File` to `/nix/store/`. See also the `writeText` helper function below. + +```nix writeTextFile { name = "my-file"; text = '' Contents of File ''; } +``` +::: -# Writes executable my-file to /nix/store//bin/my-file -# see also the `writeScriptBin` helper function below. +::: {.example #ex3-writeTextFile} +# Usage 3 of `writeTextFile` + +Writes an executable `my-file` to `/nix/store//bin/my-file`. See also the `writeScriptBin` helper function below. + +```nix writeTextFile { name = "my-file"; text = '' - Contents of File + echo "hi" ''; executable = true; destination = "/bin/my-file"; @@ -198,8 +211,10 @@ Here is an example. ::: {.example #ex-writeText} # Usage of `writeText` + +Writes `Contents of File` to `/nix/store/` + ```nix -# Writes my-file to /nix/store/ writeText "my-file" '' Contents of File @@ -236,8 +251,10 @@ The store path will be a directory. ::: {.example #ex-writeTextDir} # Usage of `writeTextDir` + +Writes `Contents of File` to `/nix/store//share/my-file`. + ```nix -# Writes contents of file to /nix/store//share/my-file writeTextDir "share/my-file" '' Contents of File @@ -279,8 +296,10 @@ Here is an example. ::: {.example #ex-writeScript} # Usage of `writeScript` + +Writes `Contents of File` to `/nix/store/` and makes the store path executable. + ```nix -# Writes my-file to /nix/store/ and makes executable writeScript "my-file" '' Contents of File From b22ec91243c1d0bd645990d4f25869ecd1c0ca6c Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 15 Jan 2024 22:31:47 +0100 Subject: [PATCH 14/14] review pass --- .../trivial-build-helpers.chapter.md | 209 ++++++++++-------- 1 file changed, 115 insertions(+), 94 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index 54118fa773ae..4648c7985542 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -1,6 +1,7 @@ # 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} @@ -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`. ::: -## `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`. - -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. +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. :::: {.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 - my-file = writeTextFile { name = "my-file"; 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 writeShellScript "evaluate-my-file.sh" '' cat ${my-file}/share/my-file ''; ``` - :::: ### `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: -`name` +`name` (String) : Corresponds to the name used in the Nix store path identifier. -`text` +`text` (String) : 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. ::: {.example #ex-writeTextFile} # Usage 1 of `writeTextFile` -Writes my-file to `/nix/store//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//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 writeTextFile { @@ -161,7 +185,8 @@ writeTextFile { ::: {.example #ex2-writeTextFile} # Usage 2 of `writeTextFile` -Writes `Contents of File` to `/nix/store/`. See also the `writeText` helper function below. +Write the string `Contents of File` to `/nix/store/`. +See also the [](#trivial-builder-writeText) helper function. ```nix writeTextFile { @@ -176,43 +201,42 @@ writeTextFile { ::: {.example #ex3-writeTextFile} # Usage 3 of `writeTextFile` -Writes an executable `my-file` to `/nix/store//bin/my-file`. See also the `writeScriptBin` helper function below. +Write an executable script `my-script` to `/nix/store//bin/my-script`. +See also the [](#trivial-builder-writeScriptBin) helper function. ```nix writeTextFile { - name = "my-file"; + name = "my-script"; text = '' echo "hi" ''; executable = true; - destination = "/bin/my-file"; + destination = "/bin/my-script"; } ``` ::: ### `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. -`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. - -Here is an example. +The store path will include the name, and it will be a file. ::: {.example #ex-writeText} # Usage of `writeText` -Writes `Contents of File` to `/nix/store/` +Write the string `Contents of File` to `/nix/store/`: ```nix writeText "my-file" @@ -222,7 +246,7 @@ writeText "my-file" ``` ::: -This example is equivalent to: +This is equivalent to: ```nix writeTextFile { @@ -235,24 +259,24 @@ writeTextFile { ### `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. ::: {.example #ex-writeTextDir} # Usage of `writeTextDir` -Writes `Contents of File` to `/nix/store//share/my-file`. +Write the string `Contents of File` to `/nix/store//share/my-file`: ```nix writeTextDir "share/my-file" @@ -262,7 +286,7 @@ writeTextDir "share/my-file" ``` ::: -This example is equivalent to: +This is equivalent to: ```nix writeTextFile { @@ -276,28 +300,25 @@ writeTextFile { ### `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 store path will include the the name, and it will be a file. - -Here is an example. +The store path will include the name, and it will be a file. ::: {.example #ex-writeScript} # Usage of `writeScript` -Writes `Contents of File` to `/nix/store/` and makes the store path executable. +Write the string `Contents of File` to `/nix/store/` and make the file executable. ```nix writeScript "my-file" @@ -307,7 +328,7 @@ writeScript "my-file" ``` ::: -This example is equivalent to: +This is equivalent to: ```nix writeTextFile { @@ -321,26 +342,26 @@ writeTextFile { ### `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 file's contents will be put into `/nix/store//bin/`. - The store path will include the the name, and it will be a directory. ::: {.example #ex-writeScriptBin} # Usage of `writeScriptBin` + ```nix writeScriptBin "my-script" '' @@ -349,7 +370,7 @@ writeScriptBin "my-script" ``` ::: -This example is equivalent to: +This is equivalent to: ```nix writeTextFile { @@ -364,28 +385,27 @@ writeTextFile { ### `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 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. - -The store path will include the the name, and it will be a file. - -Here is an example. +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. + ::: {.example #ex-writeShellScript} # Usage of `writeShellScript` + ```nix writeShellScript "my-script" '' @@ -394,7 +414,7 @@ writeShellScript "my-script" ``` ::: -This example is equivalent to: +This is equivalent to: ```nix writeTextFile { @@ -406,28 +426,29 @@ writeTextFile { executable = true; } ``` + ### `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. - -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 contents of the file. The file's contents will be put into `/nix/store//bin/`. - 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} # Usage of `writeShellScriptBin` + ```nix writeShellScriptBin "my-script" '' @@ -436,7 +457,7 @@ writeShellScriptBin "my-script" ``` ::: -This example is equivalent to: +This is equivalent to: ```nix writeTextFile {