From 397efdd9201aa3052babe4b520458ebd2c0c4371 Mon Sep 17 00:00:00 2001 From: blokyk Date: Sat, 3 Jan 2026 03:15:09 +0000 Subject: [PATCH] doc: move writeShellApplication param docs to manual --- .../trivial-build-helpers.chapter.md | 76 ++++++++++++++++++- doc/redirects.json | 3 + .../trivial-builders/default.nix | 73 ------------------ 3 files changed, 78 insertions(+), 74 deletions(-) diff --git a/doc/build-helpers/trivial-build-helpers.chapter.md b/doc/build-helpers/trivial-build-helpers.chapter.md index c7dbded893a8..aa57779cb1b2 100644 --- a/doc/build-helpers/trivial-build-helpers.chapter.md +++ b/doc/build-helpers/trivial-build-helpers.chapter.md @@ -734,7 +734,80 @@ Some basic Bash options are set by default (`errexit`, `nounset`, and `pipefail` Extra arguments may be passed to `stdenv.mkDerivation` by setting `derivationArgs`; note that variables set in this manner will be set when the shell script is _built,_ not when it's run. Runtime environment variables can be set with the `runtimeEnv` argument. -For example, the following shell application can refer to `curl` directly, rather than needing to write `${curl}/bin/curl`: +`writeShellApplication` has the following arguments: + +`name` (String) + +: The name of the script to write. + +`text` (String) + +: The shell script's text, not including a shebang. + +`runtimeInputs` (List of derivations or strings, _optional_) + +: Inputs to add to the shell script's `$PATH` at runtime. + + Each elements can either be a normal derivation, or a string containing a path, in which case it will be suffixed with `/bin` to create a `PATH` expression (see [`lib.strings.makeBinPath`](#function-library-lib.strings.makeBinPath) for more information). + +`runtimeEnv` (Attribute set, _optional_) + +: Extra environment variables to set at runtime. + +`checkPhase` (String, _optional_) + +: The `checkPhase` to run. + + The script path will be given as `$target` in the `checkPhase` + + _Default behavior:_ run [`shellcheck`](https://github.com/koalaman/shellcheck) (on supported platforms) and `bash -n` (check syntax but don't execute commands). + +`excludeShellChecks` (List of strings, _optional_) + +: Checks to exclude when running `shellcheck`. + + For example, `excludeShellChecks = [ "SC2016" ]` would prevent `shellcheck` from reporting `SC2016`, but would still detect any other problems. + + See [the `shellcheck` wiki](https://www.shellcheck.net/wiki/) for a list of checks. + +`extraShellCheckFlags` (List of strings, _optional_) + +: Extra command-line flags to pass to `shellcheck`. + +`bashOptions` (List of strings, _optional_) + +: Bash options to activate with `set -o` at the start of the script + + _Default:_ `[ "errexit" "nounset" "pipefail" ]`, which means: + 1. A failing command inside of a command list or pipeline will make the script exit, except if used as a conditional (inside a `while`, `if`, `&&`, `||`, etc.); + 2. Any attempt to expand an undefined variable will make the script exit. + +`inheritPath` (Bool, _optional_) + +: Whether the script will inherit the PATH from its parent environment. + + _Default:_ `true` + +`meta` (Attribute set, _optional_) + +: `stdenv.mkDerivation`'s [`meta`](#chap-meta) argument + +`passthru` (Attribute set, _optional_) + +: `stdenv.mkDerivation`'s [`passthru`](#chap-passthru) argument + +`derivationArgs` (Attribute set, _optional_) + +: Extra arguments to pass to [`stdenv.mkDerivation`](#chap-stdenv) + + ::: {.caution} + Certain derivation attributes are also set internally, so overriding those could cause problems. + ::: + +::: {.example #ex-writeShellApplication} +# Usage of `writeShellApplication` + +The following shell application can refer to `curl` directly, rather than needing to write `${curl}/bin/curl` ```nix writeShellApplication { @@ -750,6 +823,7 @@ writeShellApplication { ''; } ``` +::: ## `symlinkJoin` {#trivial-builder-symlinkJoin} diff --git a/doc/redirects.json b/doc/redirects.json index ad19777f2dd2..ea68ceb965c7 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -119,6 +119,9 @@ "ex-testEqualArrayOrMap-test-function-add-cowbell": [ "index.html#ex-testEqualArrayOrMap-test-function-add-cowbell" ], + "ex-writeShellApplication": [ + "index.html#ex-writeShellApplication" + ], "friction-graphics": [ "index.html#friction-graphics" ], diff --git a/pkgs/build-support/trivial-builders/default.nix b/pkgs/build-support/trivial-builders/default.nix index 3f3c1bc3a0bc..63bf8a7082b4 100644 --- a/pkgs/build-support/trivial-builders/default.nix +++ b/pkgs/build-support/trivial-builders/default.nix @@ -241,98 +241,25 @@ rec { meta.mainProgram = name; }; - # TODO: move parameter documentation to the Nixpkgs manual # See doc/build-helpers/trivial-build-helpers.chapter.md # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-writeShellApplication writeShellApplication = { - /* - The name of the script to write. - - Type: String - */ name, - /* - The shell script's text, not including a shebang. - - Type: String - */ text, - /* - Inputs to add to the shell script's `$PATH` at runtime. - - Type: [String|Derivation] - */ runtimeInputs ? [ ], - /* - Extra environment variables to set at runtime. - - Type: AttrSet - */ runtimeEnv ? null, - /* - `stdenv.mkDerivation`'s `meta` argument. - - Type: AttrSet - */ meta ? { }, - /* - `stdenv.mkDerivation`'s `passthru` argument. - - Type: AttrSet - */ passthru ? { }, - /* - The `checkPhase` to run. Defaults to `shellcheck` on supported - platforms and `bash -n`. - - The script path will be given as `$target` in the `checkPhase`. - - Type: String - */ checkPhase ? null, - /* - Checks to exclude when running `shellcheck`, e.g. `[ "SC2016" ]`. - - See for a list of checks. - - Type: [String] - */ excludeShellChecks ? [ ], - /* - Extra command-line flags to pass to ShellCheck. - - Type: [String] - */ extraShellCheckFlags ? [ ], - /* - Bash options to activate with `set -o` at the start of the script. - - Defaults to `[ "errexit" "nounset" "pipefail" ]`. - - Type: [String] - */ bashOptions ? [ "errexit" "nounset" "pipefail" ], - /* - Extra arguments to pass to `stdenv.mkDerivation`. - - :::{.caution} - Certain derivation attributes are used internally, - overriding those could cause problems. - ::: - - Type: AttrSet - */ derivationArgs ? { }, - /* - Whether to inherit the current `$PATH` in the script. - - Type: Bool - */ inheritPath ? true, }@args: writeTextFile {