Merge pull request #333262 from nbraud/doc/runCommandWith

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

```

:::

## `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.

  # `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