mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-17 23:36:17 +01:00
resholve: update README
This commit is contained in:
Travis A. Everett
parent
a588b71b37
commit
a14aa84dd7
1 changed files with 98 additions and 78 deletions
|
|
@ -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.
|
||||
## Options
|
||||
|
||||
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.
|
||||
`resholvePackage` maps Nix types/idioms into the flags and environment variables
|
||||
that the `resholve` CLI expects. Here's an overview:
|
||||
|
||||
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.
|
||||
| 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) |
|
||||
|
||||
Let's take a closer look:
|
||||
## Controlling resolution with directives
|
||||
|
||||
```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 ];
|
||||
};
|
||||
};
|
||||
```
|
||||
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
|
||||
|
||||
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`.
|
||||
> NOTE: resholve has a (growing) number of directives detailed 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
|
||||
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";
|
||||
Full documentation may be greatly accellerated if someone can help me sort out
|
||||
single-sourcing. See: https://github.com/abathur/resholve/issues/19
|
||||
-->
|
||||
|
||||
# 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.
|
||||
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;
|
||||
};
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue