diff options
Diffstat (limited to 'pkgs/development/misc/resholve/README.md')
| -rw-r--r-- | pkgs/development/misc/resholve/README.md | 192 |
1 files changed, 106 insertions, 86 deletions
diff --git a/pkgs/development/misc/resholve/README.md b/pkgs/development/misc/resholve/README.md index ddba7fc14934..6b99aebb5979 100644 --- a/pkgs/development/misc/resholve/README.md +++ b/pkgs/development/misc/resholve/README.md @@ -6,9 +6,28 @@ until then I'll outline how to use the `resholvePackage` function. > 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, and aims to be a ~90% sort of solution. +> not all) Bash. resholve aims to be a ~90% sort of solution. -Let's start with a simple example from one of my own projects: +## API Concepts + +The main difference between `resholvePackage` 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. + +## Basic Example + +Here's a simple example from one of my own projects, with annotations: +<!-- +TODO: ideally this will use a nixpkgs example; but we don't have any IN yet +and the first package PR (bashup-events) is too complex for this context. +--> ```nix { stdenv, lib, resholvePackage, fetchFromGitHub, bashup-events44, bashInteractive_5, doCheck ? true, shellcheck }: @@ -22,10 +41,20 @@ resholvePackage rec { }; solutions = { + # Give each solution a short name. This is what you'd use to + # override its settings, and it shows in (some) error messages. profile = { - # the only *required* arguments + # the only *required* arguments are the 3 below + + # Specify 1 or more $out-relative script paths. Unlike many + # builders, resholvePackage modifies the output files during + # fixup (to correctly resolve in-package sourcing). scripts = [ "bin/shellswain.bash" ]; + + # "none" for no shebang, "${bash}/bin/bash" for bash, etc. interpreter = "none"; + + # packages resholve should resolve executables from inputs = [ bashup-events44 ]; }; }; @@ -39,100 +68,91 @@ resholvePackage rec { } ``` -I'll focus on the `solutions` attribute, since this is the only part -that differs from other derivations. - -Each "solution" (k=v pair) -describes one resholve invocation. For most shell packages, one -invocation will probably be enough. resholve will make you be very -explicit about your script's dependencies, and it may also need your -help sorting out some references or problems that it can't safely -handle on its own. - -If you have more than one script, and your scripts need conflicting -directives, you can specify more than one solution to resolve the -scripts separately, but still produce a single package. - -Let's take a closer look: - -```nix - solutions = { - # each solution has a short name; this is what you'd use to - # override the settings of this solution, and it may also show up - # in (some) error messages. - profile = { - # specify one or more $out-relative script paths (unlike many - # builders, resholve will modify the output files during fixup - # to correctly resolve scripts that source within the package) - scripts = [ "bin/shellswain.bash" ]; - # "none" for no shebang, "${bash}/bin/bash" for bash, etc. - interpreter = "none"; - # packages resholve should resolve executables from - inputs = [ bashup-events44 ]; - }; - }; -``` - -resholve has a (growing) number of options for handling more complex -scripts. I won't cover these in excruciating detail here. You can find -more information about these in `man resholve` via `nixpkgs.resholve`. - -Instead, we'll look at the general form of the solutions attrset: - -```nix -solutions = { - shortname = { - # required - # $out-relative paths to try resolving - scripts = [ "bin/shunit2" ]; - # packages to resolve executables from - inputs = [ coreutils gnused gnugrep findutils ]; - # path for shebang, or 'none' to omit shebang - interpreter = "${bash}/bin/bash"; - - # optional - fake = { fake directives }; - fix = { fix directives }; - keep = { keep directives }; - # file to inject before first code-line of script - prologue = file; - # file to inject after last code-line of script - epilogue = file; - # extra command-line flags passed to resholve; generally this API - # should align with what resholve supports, but flags may help if - # you need to override the version of resholve. - flags = [ ]; - }; -}; -``` - -The main way you'll adjust how resholve handles your scripts are the -fake, fix, and keep directives. The manpage covers their purpose and -how to format them on the command-line, so I'll focus on how you'll -need to translate them into Nix types. +## Options + +`resholvePackage` maps Nix types/idioms into the flags and environment variables +that the `resholve` CLI expects. Here's an overview: + +| Option | Type | Containing | +| ------------- | ------- | ----------------------------------------------------- | +| scripts | list | $out-relative string paths to resolve | +| inputs | list | packages to resolve executables from | +| interpreter | string | 'none' or abspath for shebang | +| prologue | file | text to insert before the first code-line | +| epilogue | file | text to isnert after the last code-line | +| flags | list | strings to pass as flags | +| fake | attrset | [directives](#controlling-resolution-with-directives) | +| fix | attrset | [directives](#controlling-resolution-with-directives) | +| keep | attrset | [directives](#controlling-resolution-with-directives) | + +## Controlling resolution with directives + +In order to resolve a script, resholve will make you disambiguate how it should +handle any potential problems it encounters with directives. There are currently +3 types: +1. `fake` directives tell resholve to pretend it knows about an identifier + such as a function, builtin, external command, etc. if there's a good reason + it doesn't already know about it. Common examples: + - builtins for a non-bash shell + - loadable builtins + - platform-specific external commands in cross-platform conditionals +2. `fix` directives give resholve permission to fix something that it can't + safely fix automatically. Common examples: + - resolving commands in aliases (this is appropriate for standalone scripts + that use aliases non-interactively--but it would prevent profile/rc + scripts from using the latest current-system symlinks.) + - resolve commands in a variable definition + - resolve an absolute command path from inputs as if it were a bare reference +3. `keep` directives tell resholve not to raise an error (i.e., ignore) + something it would usually object to. Common examples: + - variables used as/within the first word of a command + - pre-existing absolute or user-relative (~) command paths + - dynamic (variable) arguments to commands known to accept/run other commands + +> NOTE: resholve has a (growing) number of directives detailed in `man resholve` +> via `nixpkgs.resholve`. + +Each of these 3 types is represented by its own attrset, where you can think +of the key as a scope. The value should be: +- `true` for any directives that the resholve CLI accepts as a single word +- a list of strings for all other options +<!-- +TODO: these should be fully-documented here, but I'm already maintaining +more copies of their specification/behavior than I like, and continuing to +add more at this early date will only ensure that I spend more time updating +docs and less time filling in feature gaps. + +Full documentation may be greatly accellerated if someone can help me sort out +single-sourcing. See: https://github.com/abathur/resholve/issues/19 +--> + +This will hopefully make more sense when you see it. Here are CLI examples +from the manpage, and the Nix equivalents: ```nix # --fake 'f:setUp;tearDown builtin:setopt source:/etc/bashrc' fake = { - function = [ "setUp" "tearDown" ]; - builtin = [ "setopt" ]; - source = [ "/etc/bashrc" ]; + # fake accepts the initial of valid identifier types as a CLI convienience. + # Use full names in the Nix API. + function = [ "setUp" "tearDown" ]; + builtin = [ "setopt" ]; + source = [ "/etc/bashrc" ]; }; # --fix 'aliases xargs:ls $GIT:gix' fix = { - # all single-word directives use `true` as value - aliases = true; - xargs = [ "ls" ]; - "$GIT" = [ "gix" ]; + # all single-word directives use `true` as value + aliases = true; + xargs = [ "ls" ]; + "$GIT" = [ "gix" ]; }; # --keep 'which:git;ls .:$HOME $LS:exa /etc/bashrc ~/.bashrc' keep = { - which = [ "git" "ls" ]; - "." = [ "$HOME" ]; - "$LS" = [ "exa" ]; - "/etc/bashrc" = true; - "~/.bashrc" = true; + which = [ "git" "ls" ]; + "." = [ "$HOME" ]; + "$LS" = [ "exa" ]; + "/etc/bashrc" = true; + "~/.bashrc" = true; }; ``` |