public/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #109594 from abathur/doc/resholve

Browse Source 
resholve: update README
This commit is contained in:
Sandro 2021-01-18 20:54:32 +01:00 committed by GitHub
commit 1a083843d9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 98 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
pkgs/development/misc/resholve/README.md
View File

@ -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 > 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 > 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 ```nix
{ stdenv, lib, resholvePackage, fetchFromGitHub, bashup-events44, bashInteractive_5, doCheck ? true, shellcheck }: { stdenv, lib, resholvePackage, fetchFromGitHub, bashup-events44, bashInteractive_5, doCheck ? true, shellcheck }:
@ -22,10 +41,20 @@ resholvePackage rec {
}; };
solutions = { 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 = { 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" ]; scripts = [ "bin/shellswain.bash" ];
# "none" for no shebang, "${bash}/bin/bash" for bash, etc.
interpreter = "none"; interpreter = "none";
# packages resholve should resolve executables from
inputs = [ bashup-events44 ]; inputs = [ bashup-events44 ];
}; };
}; };
@ -39,100 +68,91 @@ resholvePackage rec {
} }
``` ```
I'll focus on the `solutions` attribute, since this is the only part ## Options
that differs from other derivations.
Each "solution" (k=v pair) `resholvePackage` maps Nix types/idioms into the flags and environment variables
describes one resholve invocation. For most shell packages, one that the `resholve` CLI expects. Here's an overview:
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 | Option | Type | Containing |
directives, you can specify more than one solution to resolve the | ------------- | ------- | ----------------------------------------------------- |
scripts separately, but still produce a single package. | 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) |
Let's take a closer look: ## Controlling resolution with directives
```nix In order to resolve a script, resholve will make you disambiguate how it should
solutions = { handle any potential problems it encounters with directives. There are currently
# each solution has a short name; this is what you'd use to 3 types:
# override the settings of this solution, and it may also show up 1. `fake` directives tell resholve to pretend it knows about an identifier
# in (some) error messages. such as a function, builtin, external command, etc. if there's a good reason
profile = { it doesn't already know about it. Common examples:
# specify one or more $out-relative script paths (unlike many - builtins for a non-bash shell
# builders, resholve will modify the output files during fixup - loadable builtins
# to correctly resolve scripts that source within the package) - platform-specific external commands in cross-platform conditionals
scripts = [ "bin/shellswain.bash" ]; 2. `fix` directives give resholve permission to fix something that it can't
# "none" for no shebang, "${bash}/bin/bash" for bash, etc. safely fix automatically. Common examples:
interpreter = "none"; - resolving commands in aliases (this is appropriate for standalone scripts
# packages resholve should resolve executables from that use aliases non-interactively--but it would prevent profile/rc
inputs = [ bashup-events44 ]; 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
resholve has a (growing) number of options for handling more complex > NOTE: resholve has a (growing) number of directives detailed in `man resholve`
scripts. I won't cover these in excruciating detail here. You can find > via `nixpkgs.resholve`.
more information about these in `man resholve` via `nixpkgs.resholve`.
Instead, we'll look at the general form of the solutions attrset: 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.
```nix Full documentation may be greatly accellerated if someone can help me sort out
solutions = { single-sourcing. See: https://github.com/abathur/resholve/issues/19
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 This will hopefully make more sense when you see it. Here are CLI examples
fake = { fake directives }; from the manpage, and the Nix equivalents:
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.
```nix ```nix
# --fake 'f:setUp;tearDown builtin:setopt source:/etc/bashrc' # --fake 'f:setUp;tearDown builtin:setopt source:/etc/bashrc'
fake = { fake = {
function = [ "setUp" "tearDown" ]; # fake accepts the initial of valid identifier types as a CLI convienience.
builtin = [ "setopt" ]; # Use full names in the Nix API.
source = [ "/etc/bashrc" ]; function = [ "setUp" "tearDown" ];
builtin = [ "setopt" ];
source = [ "/etc/bashrc" ];
}; };
# --fix 'aliases xargs:ls $GIT:gix' # --fix 'aliases xargs:ls $GIT:gix'
fix = { fix = {
# all single-word directives use `true` as value # all single-word directives use `true` as value
aliases = true; aliases = true;
xargs = [ "ls" ]; xargs = [ "ls" ];
"$GIT" = [ "gix" ]; "$GIT" = [ "gix" ];
}; };
# --keep 'which:git;ls .:$HOME $LS:exa /etc/bashrc ~/.bashrc' # --keep 'which:git;ls .:$HOME $LS:exa /etc/bashrc ~/.bashrc'
keep = { keep = {
which = [ "git" "ls" ]; which = [ "git" "ls" ];
"." = [ "$HOME" ]; "." = [ "$HOME" ];
"$LS" = [ "exa" ]; "$LS" = [ "exa" ];
"/etc/bashrc" = true; "/etc/bashrc" = true;
"~/.bashrc" = true; "~/.bashrc" = true;
}; };
``` ```