path: root/pkgs/build-support/trivial-builders.nix

{ lib, stdenv, stdenvNoCC, lndir, runtimeShell, shellcheck }:

let
  inherit (lib)
    optionalAttrs
    warn
    ;
in

rec {

  /* Run the shell command `buildCommand' to produce a store path named
   `name'.  The attributes in `env' are added to the environment
   prior to running the command. By default `runCommand` runs in a
   stdenv with no compiler environment. `runCommandCC` uses the default
   stdenv, `pkgs.stdenv`.

   Example:


   runCommand "name" {envVariable = true;} ''echo hello > $out''
   runCommandCC "name" {} ''gcc -o myfile myfile.c; cp myfile $out'';


   The `*Local` variants force a derivation to be built locally,
   it is not substituted.

   This is intended for very cheap commands (<1s execution time).
   It saves on the network roundrip and can speed up a build.

   It is the same as adding the special fields

   `preferLocalBuild = true;`
   `allowSubstitutes = false;`

   to a derivation’s attributes.
  */
  runCommand = name: env: runCommandWith {
    stdenv = stdenvNoCC;
    runLocal = false;
    inherit name;
    derivationArgs = env;
  };
  runCommandLocal = name: env: runCommandWith {
    stdenv = stdenvNoCC;
    runLocal = true;
    inherit name;
    derivationArgs = env;
  };

  runCommandCC = name: env: runCommandWith {
    stdenv = stdenv;
    runLocal = false;
    inherit name;
    derivationArgs = env;
  };
  # `runCommandCCLocal` left out on purpose.
  # We shouldn’t force the user to have a cc in scope.

  /* 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`.
   */
  runCommandWith =
    let
      # prevent infinite recursion for the default stdenv value
      defaultStdenv = stdenv;
    in
    {
    # which stdenv to use, defaults to a stdenv with a C compiler, pkgs.stdenv
      stdenv ? defaultStdenv
    # whether to build this derivation locally instead of substituting
    , runLocal ? false
    # extra arguments to pass to stdenv.mkDerivation
    , derivationArgs ? {}
    # name of the resulting derivation
    , name
    # TODO(@Artturin): enable strictDeps always
    }: buildCommand:
    stdenv.mkDerivation ({
      enableParallelBuilding = true;
      inherit buildCommand name;
      passAsFile = [ "buildCommand" ]
        ++ (derivationArgs.passAsFile or []);
    }
    // (lib.optionalAttrs runLocal {
          preferLocalBuild = true;
          allowSubstitutes = false;
       })
    // builtins.removeAttrs derivationArgs [ "passAsFile" ]);


  /* Writes a text file to the nix store.
    The contents of text is added to the file in the store.

    Example:


    # Writes my-file to /nix/store/<store path>
    writeTextFile {
      name = "my-file";
      text = ''
        Contents of File
      '';
    }


    See also the `writeText` helper function below.


    # Writes executable my-file to /nix/store/<store path>/bin/my-file
    writeTextFile {
      name = "my-file";
      text = ''
        Contents of File
      '';
      executable = true;
      destination = "/bin/my-file";
    }


   */
  writeTextFile =
    { name # the name of the derivation
    , text
    , executable ? false # run chmod +x ?
    , destination ? ""   # relative path appended to $out eg "/bin/foo"
    , checkPhase ? ""    # syntax checks, e.g. for scripts
    , meta ? { }
    }:
    runCommand name
      { inherit text executable checkPhase meta;
        passAsFile = [ "text" ];
        # Pointless to do this on a remote machine.
        preferLocalBuild = true;
        allowSubstitutes = false;
      }
      ''
        target=$out${lib.escapeShellArg destination}
        mkdir -p "$(dirname "$target")"

        if [ -e "$textPath" ]; then
          mv "$textPath" "$target"
        else
          echo -n "$text" > "$target"
        fi

        eval "$checkPhase"

        (test -n "$executable" && chmod +x "$target") || true
      '';

  /*
   Writes a text file to nix store with no optional parameters available.

   Example:


   # Writes contents of file to /nix/store/<store path>
   writeText "my-file"
     ''
     Contents of File
     '';


  */
  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/<store path>/share/my-file
    writeTextDir "share/my-file"
     ''
     Contents of File
     '';


  */
  writeTextDir = path: text: writeTextFile {
    inherit text;
    name = builtins.baseNameOf path;
    destination = "/${path}";
  };

  /*
    Writes a text file to /nix/store/<store path> 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/<store path> and makes executable
    writeScript "my-file"
      ''
      Contents of File
      '';


  */
  writeScript = name: text: writeTextFile {inherit name text; executable = true;};

  /*
    Writes a text file to /nix/store/<store path>/bin/<name> and
    marks the file as executable.

    Example:



    # Writes my-file to /nix/store/<store path>/bin/my-file and makes executable.
    writeScriptBin "my-file"
      ''
      Contents of File
      '';


  */
  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/<store path> and makes executable.
    writeShellScript "my-file"
      ''
      Contents of File
      '';


  */
  writeShellScript = name: text:
    writeTextFile {
      inherit name;
      executable = true;
      text = ''
        #!${runtimeShell}
        ${text}
        '';
      checkPhase = ''
        ${stdenv.shellDryRun} "$target"
      '';
    };

  /*
    Similar to writeShellScript and writeScriptBin.
    Writes an executable Shell script to /nix/store/<store path>/bin/<name> and checks its syntax.
    Automatically includes interpreter above the contents passed.

    Example:


    # Writes my-file to /nix/store/<store path>/bin/my-file and makes executable.
    writeShellScriptBin "my-file"
      ''
      Contents of File
      '';


  */
  writeShellScriptBin = name : text :
    writeTextFile {
      inherit name;
      executable = true;
      destination = "/bin/${name}";
      text = ''
        #!${runtimeShell}
        ${text}
        '';
      checkPhase = ''
        ${stdenv.shellDryRun} "$target"
      '';
    };

  /*
    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.
    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
       '';
    }

  */
  writeShellApplication =
    { name
    , text
    , runtimeInputs ? [ ]
    , checkPhase ? null
    }:
    writeTextFile {
      inherit name;
      executable = true;
      destination = "/bin/${name}";
      text = ''
        #!${runtimeShell}
        set -o errexit
        set -o nounset
        set -o pipefail
      '' + lib.optionalString (runtimeInputs != [ ]) ''

        export PATH="${lib.makeBinPath runtimeInputs}:$PATH"
      '' + ''

        ${text}
      '';

      checkPhase =
        if checkPhase == null then ''
          runHook preCheck
          ${stdenv.shellDryRun} "$target"
          ${shellcheck.unwrapped}/bin/shellcheck "$target"
          runHook postCheck
        ''
        else checkPhase;

      meta.mainProgram = name;
    };

  # Create a C binary
  writeCBin = name: code:
    runCommandCC name
    {
      inherit name code;
      executable = true;
      passAsFile = ["code"];
      # Pointless to do this on a remote machine.