Merge pull request #333262 from nbraud/doc/runCommandWith
nixpkgs-manual: Document `runCommandWith`, refactor `runCommand{,CC,Local}`
This commit is contained in:
Philip Taron
@@ -3,32 +3,122 @@
|
||||
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 :: String -> AttrSet -> String -> Derivation`
|
||||
## `runCommandWith` {#trivial-builder-runCommandWith}
|
||||
|
||||
The result of `runCommand name drvAttrs buildCommand` is a derivation that is built by running the specified shell commands.
|
||||
The function `runCommandWith` returns a derivation built using the specified command(s), in a specified environment.
|
||||
|
||||
By default `runCommand` runs in a stdenv with no compiler environment, whereas [`runCommandCC`](#trivial-builder-runCommandCC) uses the default stdenv, `pkgs.stdenv`.
|
||||
It is the underlying base function of all [`runCommand*` variants].
|
||||
The general behavior is controlled via a single attribute set passed
|
||||
as the first argument, and allows specifying `stdenv` freely.
|
||||
|
||||
`name :: String`
|
||||
: The name that Nix will append to the store path in the same way that `stdenv.mkDerivation` uses its `name` attribute.
|
||||
The following [`runCommand*` variants] exist: `runCommand`, `runCommandCC`, and `runCommandLocal`.
|
||||
|
||||
`drvAttr :: AttrSet`
|
||||
: Attributes to pass to the underlying call to [`stdenv.mkDerivation`](#chap-stdenv).
|
||||
[`runCommand*` variants]: #trivial-builder-runCommand
|
||||
|
||||
`buildCommand :: String`
|
||||
### Type {#trivial-builder-runCommandWith-Type}
|
||||
|
||||
```
|
||||
runCommandWith :: {
|
||||
name :: name;
|
||||
stdenv? :: Derivation;
|
||||
runLocal? :: Bool;
|
||||
derivationArgs? :: { ... };
|
||||
} -> String -> Derivation
|
||||
```
|
||||
|
||||
### Inputs {#trivial-builder-runCommandWith-Inputs}
|
||||
|
||||
`name` (String)
|
||||
: The derivation's name, which Nix will append to the store path; see [`mkDerivation`](#sec-using-stdenv).
|
||||
|
||||
`runLocal` (Boolean)
|
||||
: If set to `true` this forces the derivation to be built locally, not using [substitutes] nor remote builds.
|
||||
This is intended for very cheap commands (<1s execution time) which can be sped up by avoiding the network round-trip(s).
|
||||
Its effect is to set [`preferLocalBuild = true`][preferLocalBuild] and [`allowSubstitutes = false`][allowSubstitutes].
|
||||
|
||||
::: {.note}
|
||||
This prevents the use of [substituters][substituter], so only set `runLocal` (or use `runCommandLocal`) when 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`.
|
||||
:::
|
||||
|
||||
`stdenv` (Derivation)
|
||||
: The [standard environment](#chap-stdenv) to use, defaulting to `pkgs.stdenv`
|
||||
|
||||
`derivationArgs` (Attribute set)
|
||||
: Additional arguments for [`mkDerivation`](#sec-using-stdenv).
|
||||
|
||||
`buildCommand` (String)
|
||||
: Shell commands to run in the derivation builder.
|
||||
|
||||
::: {.note}
|
||||
You have to create a file or directory `$out` for Nix to be able to run the builder successfully.
|
||||
:::
|
||||
|
||||
[allowSubstitutes]: https://nixos.org/nix/manual/#adv-attr-allowSubstitutes
|
||||
[preferLocalBuild]: https://nixos.org/nix/manual/#adv-attr-preferLocalBuild
|
||||
[substituter]: https://nix.dev/manual/nix/latest/glossary#gloss-substituter
|
||||
[substitutes]: https://nix.dev/manual/nix/2.23/glossary#gloss-substitute
|
||||
|
||||
::: {.example #ex-runcommandwith}
|
||||
# Invocation of `runCommandWith`
|
||||
|
||||
```nix
|
||||
runCommandWith {
|
||||
name = "example";
|
||||
derivationArgs.nativeBuildInputs = [ cowsay ];
|
||||
} ''
|
||||
cowsay > $out <<EOMOO
|
||||
'runCommandWith' is a bit cumbersome,
|
||||
so we have more ergonomic wrappers.
|
||||
EOMOO
|
||||
''
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
|
||||
## `runCommand` and `runCommandCC` {#trivial-builder-runCommand}
|
||||
|
||||
The function `runCommand` returns a derivation built using the specified command(s), in the `stdenvNoCC` environment.
|
||||
|
||||
`runCommandCC` is similar but uses the default compiler environment. To minimize dependencies, `runCommandCC`
|
||||
should only be used when the build command needs a C compiler.
|
||||
|
||||
`runCommandLocal` is also similar to `runCommand`, but forces the derivation to be built locally.
|
||||
See the note on [`runCommandWith`] about `runLocal`.
|
||||
|
||||
[`runCommandWith`]: #trivial-builder-runCommandWith
|
||||
|
||||
### Type {#trivial-builder-runCommand-Type}
|
||||
|
||||
```
|
||||
runCommand :: String -> AttrSet -> String -> Derivation
|
||||
runCommandCC :: String -> AttrSet -> String -> Derivation
|
||||
runCommandLocal :: String -> AttrSet -> String -> Derivation
|
||||
```
|
||||
|
||||
### Input {#trivial-builder-runCommand-Input}
|
||||
|
||||
While the type signature(s) differ from [`runCommandWith`], individual arguments with the same name will have the same type and meaning:
|
||||
|
||||
`name` (String)
|
||||
: The derivation's name
|
||||
|
||||
`derivationArgs` (Attribute set)
|
||||
: Additional parameters passed to [`mkDerivation`]
|
||||
|
||||
`buildCommand` (String)
|
||||
: The command(s) run to build the derivation.
|
||||
|
||||
|
||||
::: {.example #ex-runcommand-simple}
|
||||
# Invocation of `runCommand`
|
||||
|
||||
```nix
|
||||
(import <nixpkgs> {}).runCommand "my-example" {} ''
|
||||
runCommand "my-example" {} ''
|
||||
echo My example command is running
|
||||
|
||||
mkdir $out
|
||||
@@ -49,18 +139,24 @@ By default `runCommand` runs in a stdenv with no compiler environment, whereas [
|
||||
```
|
||||
:::
|
||||
|
||||
## `runCommandCC` {#trivial-builder-runCommandCC}
|
||||
|
||||
This works just like `runCommand`. The only difference is that it also provides a C compiler in `buildCommand`'s environment. To minimize your dependencies, you should only use this if you are sure you will need a C compiler as part of running your command.
|
||||
|
||||
## `runCommandLocal` {#trivial-builder-runCommandLocal}
|
||||
|
||||
Variant of `runCommand` that forces the derivation to be built locally, it is not substituted. This is intended for very cheap commands (<1s execution time). It saves on the network round-trip and can speed up a build.
|
||||
|
||||
::: {.note}
|
||||
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`.
|
||||
`runCommand name derivationArgs buildCommand` is equivalent to
|
||||
```nix
|
||||
runCommandWith {
|
||||
inherit name derivationArgs;
|
||||
stdenv = stdenvNoCC;
|
||||
} buildCommand
|
||||
```
|
||||
|
||||
Likewise, `runCommandCC name derivationArgs buildCommand` is equivalent to
|
||||
```nix
|
||||
runCommandWith {
|
||||
inherit name derivationArgs;
|
||||
} buildCommand
|
||||
```
|
||||
:::
|
||||
|
||||
|
||||
## Writing text files {#trivial-builder-text-writing}
|
||||
|
||||
Nixpkgs provides the following functions for producing derivations which write text files or executable scripts into the Nix store.
|
||||
|
||||
@@ -36,17 +36,8 @@ rec {
|
||||
# `runCommandCCLocal` left out on purpose.
|
||||
# We shouldn’t force the user to have a cc in scope.
|
||||
|
||||
# TODO: Move documentation for runCommandWith to the Nixpkgs manual
|
||||
/*
|
||||
Generalized version of the `runCommand`-variants
|
||||
which does customized behavior via a single
|
||||
attribute set passed as the first argument
|
||||
instead of having a lot of variants like
|
||||
`runCommand*`. Additionally it allows changing
|
||||
the used `stdenv` freely and has a more explicit
|
||||
approach to changing the arguments passed to
|
||||
`stdenv.mkDerivation`.
|
||||
*/
|
||||
# Docs in doc/build-helpers/trivial-build-helpers.chapter.md
|
||||
# See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-runCommandWith
|
||||
runCommandWith =
|
||||
let
|
||||
# prevent infinite recursion for the default stdenv value
|
||||
|
||||
Reference in New Issue
Block a user