Unverified Commit 7fbfc53b authored by Philip Taron's avatar Philip Taron Committed by GitHub
Browse files

Merge pull request #334176 from philiptaron/pr-333270/follow-up

pkgs.writers: improve documentation on {makeScriptWriter,makeScriptWriterBin}
parents e66d58c7 989f10d4
Loading
Loading
Loading
Loading
+15 −14
Original line number Diff line number Diff line
@@ -22,17 +22,17 @@ let
in
rec {
  /**
    A generic function that returns a derivation which, when beeing built outputs the script in an executable format.
    `makeScriptWriter` returns a derivation which creates an executable script.

    # Inputs

    config (AttrSet)
    : `interpreter` (String)
      : the interpreter to use for the script
      : the [interpreter](https://en.wikipedia.org/wiki/Shebang_(Unix)) to use for the script.
    : `check` (String)
      : A command to check the script. I.e. some linting check.
      : A command to check the script. For example, this could be a linting check.
    : `makeWrapperArgs` (Optional, [ String ], Default: [])
      : Arguments forwarded to (`makeWrapper`)[#fun-makeWrapper]
      : Arguments forwarded to (`makeWrapper`)[#fun-makeWrapper].

    `nameOrPath` (String)
    : The name of the script or the path to the script.
@@ -40,8 +40,8 @@ rec {
      When a `string` starting with "/" is passed, the script will be created at the specified path in $out.
      I.e. `"/bin/hello"` will create a script at `$out/bin/hello`.

      Any other `string` is interpreted as filename.
      It must be a simple unix filename starting with a letter, digit, dot, or underscore.
      Any other `string` is interpreted as a filename.
      It must be a [POSIX filename](https://en.wikipedia.org/wiki/Filename) starting with a letter, digit, dot, or underscore.
      Spaces or special characters are not allowed.

    `content` (String)
@@ -51,6 +51,7 @@ rec {
    This function is used as base implementation for other high-level writer functions.

    For example, `writeBash` can (roughly) be implemented as:

    ```nix
    writeBash = makeScriptWriter { interpreter = "${pkgs.bash}/bin/bash"; }
    ```
@@ -103,7 +104,8 @@ rec {
      name = last (builtins.split "/" nameOrPath);
      path = if nameIsPath then nameOrPath else "/bin/${name}";
      # The inner derivation which creates the executable under $out/bin (never at $out directly)
      # This is required in order to support wrapping, as wrapped programs consist of at least two files: the executable and the wrapper.
      # This is required in order to support wrapping, as wrapped programs consist of
      # at least two files: the executable and the wrapper.
      inner =
        pkgs.runCommandLocal name
          (
@@ -178,11 +180,10 @@ rec {
      '';

  /**
    This is a generic function that returns a derivation which, when built, compiles the given script into an executable format.
    `makeBinWriter` returns a derivation which compiles the given script into an executable format.

    :::{.note}
    This function is the base implementation for other compile language `writers`.
    i.e. `writeHaskell`, `writeRust`.
    This function is the base implementation for other compile language `writers`, such as `writeHaskell` and `writeRust`.
    :::

    # Inputs
@@ -192,7 +193,7 @@ rec {
      : The script that compiles the given content into an executable.

    : `strip` (Boolean, Default: true)
      : Whether to strip the executable or not.
      : Whether to [strip](https://nixos.org/manual/nixpkgs/stable/#ssec-fixup-phase) the executable or not.

    : `makeWrapperArgs` (Optional, [ String ], Default: [])
      : Arguments forwarded to (`makeWrapper`)[#fun-makeWrapper]
@@ -201,10 +202,10 @@ rec {
    : The name of the script or the path to the script.

      When a `string` starting with "/" is passed, the script will be created at the specified path in $out.
      I.e. `"/bin/hello"` will create a script at `$out/bin/hello`.
      For example, `"/bin/hello"` will create a script at `$out/bin/hello`.

      Any other `string` is interpreted as filename.
      It must be a simple unix filename starting with a letter, digit, dot, or underscore.
      Any other `string` is interpreted as a filename.
      It must be a [POSIX filename](https://en.wikipedia.org/wiki/Filename) starting with a letter, digit, dot, or underscore.
      Spaces or special characters are not allowed.

    # Examples