diff options
author | Rebecca Turner <rbt@sent.as> | 2024-01-12 13:42:53 -0800 |
---|---|---|
committer | Rebecca Turner <rbt@sent.as> | 2024-02-01 16:02:33 -0800 |
commit | 63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed (patch) | |
tree | f85488e39aeaae2f968bc3254f3ece68cee69020 /pkgs/build-support | |
parent | 863786b98b36025ddca4c0678b39bbdf383468a0 (diff) | |
download | nixlib-63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed.tar nixlib-63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed.tar.gz nixlib-63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed.tar.bz2 nixlib-63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed.tar.lz nixlib-63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed.tar.xz nixlib-63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed.tar.zst nixlib-63f7c9b415fa09a4d7ae5b01f3ecdd420c30cbed.zip |
writeShellApplication: Document arguments
Diffstat (limited to 'pkgs/build-support')
-rw-r--r-- | pkgs/build-support/trivial-builders/default.nix | 104 |
1 files changed, 68 insertions, 36 deletions
diff --git a/pkgs/build-support/trivial-builders/default.nix b/pkgs/build-support/trivial-builders/default.nix index 3e63e12febd2..a38231bdcaa3 100644 --- a/pkgs/build-support/trivial-builders/default.nix +++ b/pkgs/build-support/trivial-builders/default.nix @@ -240,43 +240,75 @@ rec { meta.mainProgram = name; }; - /* - Similar to writeShellScriptBin and writeScriptBin. - Writes an executable Shell script to /nix/store/<store path>/bin/<name> and - checks its syntax with shellcheck and the shell's -n option. - Individual checks can be foregone by putting them in the excludeShellChecks - list, e.g. [ "SC2016" ]. - Automatically includes sane set of shellopts (errexit, nounset, pipefail) - and handles creation of PATH based on runtimeInputs - - Note that the checkPhase uses stdenv.shell for the test run of the script, - while the generated shebang uses runtimeShell. If, for whatever reason, - those were to mismatch you might lose fidelity in the default checks. - - Example: - - Writes my-file to /nix/store/<store path>/bin/my-file and makes executable. - - - writeShellApplication { - name = "my-file"; - runtimeInputs = [ curl w3m ]; - text = '' - curl -s 'https://nixos.org' | w3m -dump -T text/html - ''; - } - - */ + # See doc/build-helpers/trivial-build-helpers.chapter.md + # or https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-text-writing writeShellApplication = - { name - , text - , runtimeInputs ? [ ] - , runtimeEnv ? null - , meta ? { } - , checkPhase ? null - , excludeShellChecks ? [ ] - , bashOptions ? [ "errexit" "nounset" "pipefail" ] - , derivationArgs ? { } # Extra arguments to pass to `stdenv.mkDerivation` + { + /* + 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 ? { }, + /* + 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 <https://www.shellcheck.net/wiki/> for a list of checks. + + Type: [String] + */ + excludeShellChecks ? [ ], + /* + 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 ? { }, }: writeTextFile { inherit name meta derivationArgs; |