# Using resholve's Nix API
resholve replaces bare references (subject to a PATH search at runtime) to external commands and scripts with absolute paths.

This small super-power helps ensure script dependencies are declared, present, and don't unexpectedly shift when the PATH changes.

resholve is developed to enable the Nix package manager to package and integrate Shell projects, but its features are not Nix-specific and inevitably have other applications.

<!-- generated from resholve's repo; best to suggest edits there (or at least notify me) -->

This will hopefully make its way into the Nixpkgs manual soon, but
until then I'll outline how to use the functions:
- `resholve.mkDerivation` (formerly `resholvePackage`)
- `resholve.writeScript` (formerly `resholveScript`)
- `resholve.writeScriptBin` (formerly `resholveScriptBin`)
- `resholve.phraseSolution` (new in resholve 0.8.0)

> Fair warning: resholve does *not* aspire to resolving all valid Shell
> scripts. It depends on the OSH/Oil parser, which aims to support most (but
> not all) Bash. resholve aims to be a ~90% sort of solution.

## API Concepts

The main difference between `resholve.mkDerivation` and other builder functions
is the `solutions` attrset, which describes which scripts to resolve and how.
Each "solution" (k=v pair) in this attrset describes one resholve invocation.

> NOTE: For most shell packages, one invocation will probably be enough:
> - Packages with a single script will only need one solution.
> - Packages with multiple scripts can still use one solution if the scripts
>   don't require conflicting directives.
> - Packages with scripts that require conflicting directives can use multiple
>   solutions to resolve the scripts separately, but produce a single package.

`resholve.writeScript` and `resholve.writeScriptBin` support a _single_
`solution` attrset. This is basically the same as any single solution in `resholve.mkDerivation`, except that it doesn't need a `scripts` attr (it is automatically added). `resholve.phraseSolution` also only accepts a single solution--but it _does_ still require the `scripts` attr.

## Basic `resholve.mkDerivation` Example

Here's a simple example of how `resholve.mkDerivation` is already used in nixpkgs:

<!-- TODO: figure out how to pull this externally? -->

```nix
{
  bash,
  coreutils,
  gnused,
  goss,
  lib,
  resholve,
  which,
}:

resholve.mkDerivation rec {
  pname = "dgoss";
  version = goss.version;
  src = goss.src;

  dontConfigure = true;
  dontBuild = true;

  installPhase = ''
    sed -i '2i GOSS_PATH=${goss}/bin/goss' extras/dgoss/dgoss
    install -D extras/dgoss/dgoss $out/bin/dgoss
  '';

  solutions = {
    default = {
      scripts = [ "bin/dgoss" ];
      interpreter = "${bash}/bin/bash";
      inputs = [
        coreutils
        gnused
        which
      ];
      keep = {
        "$CONTAINER_RUNTIME" = true;
      };
    };
  };

  meta = {
    homepage = "https://github.com/goss-org/goss/blob/v${version}/extras/dgoss/README.md";
    changelog = "https://github.com/goss-org/goss/releases/tag/v${version}";
    description = "Convenience wrapper around goss that aims to bring the simplicity of goss to docker containers";
    license = lib.licenses.asl20;
    platforms = lib.platforms.linux;
    maintainers = with lib.maintainers; [
      hyzual
      anthonyroussel
    ];
    mainProgram = "dgoss";
  };
}
```


## Basic `resholve.writeScript` and `resholve.writeScriptBin` examples

Both of these functions have the same basic API. The examples are a little
trivial, so I'll also link to some real-world examples:
- [shell.nix from abathur/tdverpy](https://github.com/abathur/tdverpy/blob/e1f956df3ed1c7097a5164e0c85b178772e277f5/shell.nix#L6-L13)

```nix
{
  resholvedScript =
    resholve.writeScript "name"
      {
        inputs = [ file ];
        interpreter = "${bash}/bin/bash";
      }
      ''
        echo "Hello"
        file .
      '';
  resholvedScriptBin =
    resholve.writeScriptBin "name"