add darwin support
This commit is contained in:
atagen
parent
73904c036f
commit
4a7febee6c
10 changed files with 774 additions and 47 deletions
73
doc/nixos.md
73
doc/nixos.md
|
|
@ -1,10 +1,12 @@
|
|||
# nixos integration
|
||||
# nixos / nix-darwin integration
|
||||
|
||||
inshellah provides a nixos module that indexes nushell completions for
|
||||
every installed package at system build time, and a wrapped binary
|
||||
that knows where to find the result.
|
||||
inshellah provides a module that indexes nushell completions for every
|
||||
installed package at system build time, and a wrapped binary that knows
|
||||
where to find the result. the same module body backs both NixOS and
|
||||
nix-darwin — on Linux it scrapes ELF binaries, on macOS Mach-O ones,
|
||||
selected automatically by the inshellah build's target platform.
|
||||
|
||||
## enabling
|
||||
## enabling (NixOS)
|
||||
|
||||
```nix
|
||||
# flake.nix outputs:
|
||||
|
|
@ -28,6 +30,34 @@ or importing directly:
|
|||
}
|
||||
```
|
||||
|
||||
## enabling (nix-darwin)
|
||||
|
||||
```nix
|
||||
# flake.nix outputs:
|
||||
{
|
||||
darwinConfigurations.mymac = nix-darwin.lib.darwinSystem {
|
||||
modules = [
|
||||
inshellah.darwinModules.default
|
||||
{ programs.inshellah.enable = true; }
|
||||
];
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
the options and behaviour are identical to the NixOS module — it reads
|
||||
the same `programs.inshellah.*` settings and writes the same completion
|
||||
index and nushell shim under the system profile (`/run/current-system/sw`,
|
||||
which nix-darwin also uses).
|
||||
|
||||
on macOS, the tools you reach through `/usr/bin` (`git`, `clang`, …) are
|
||||
`xcrun` shims whose real binaries and manpages live under the active
|
||||
developer dir, outside the nix system profile — so they aren't indexed by
|
||||
default. rather than probe the host toolchain impurely, list the nix
|
||||
equivalents you want completed in `extraScrapePackages`; the module rolls
|
||||
their store paths into the build-time scrape (`inshellah index … --prefix
|
||||
…`). this applies on NixOS too, for any package whose completions you want
|
||||
indexed without putting it on the system path.
|
||||
|
||||
after rebuilding, completions are immediately available through the
|
||||
autoloaded nushell shim.
|
||||
|
||||
|
|
@ -69,6 +99,11 @@ programs.inshellah = {
|
|||
# commands to skip manpage parsing for (uses --help instead)
|
||||
helpOnlyCommands = [ "nix" ];
|
||||
|
||||
# extra packages to scrape alongside the system profile; each store path
|
||||
# is passed to `inshellah index --prefix`. handy on macOS for the nix
|
||||
# equivalents of /usr/bin shim tools (git, clang, …)
|
||||
extraScrapePackages = [ pkgs.git pkgs.clang ];
|
||||
|
||||
# per-subprocess timeout in ms during indexing (null = built-in
|
||||
# default of 200ms)
|
||||
timeoutMs = null;
|
||||
|
|
@ -81,11 +116,39 @@ programs.inshellah = {
|
|||
# set to 0 to omit native result-limit flags
|
||||
dynamicLimit = 200;
|
||||
|
||||
# characters that trigger flag completions when a partial token begins
|
||||
# with one of them. default "-"; e.g. "-+" also triggers on "+"
|
||||
flagTriggers = "-";
|
||||
|
||||
# also surface flags on an empty token (right after a space), mixed in
|
||||
# with subcommands. default false
|
||||
flagOnEmpty = false;
|
||||
|
||||
# cap on candidates returned and nushell's max_results. 0 = no cap
|
||||
# (nushell's built-in default of 200 still applies)
|
||||
maxCompletions = 0;
|
||||
|
||||
# per-subprocess timeout (ms) for the completer's on-the-fly --help
|
||||
# resolution of uncached commands. null = built-in default of 200ms.
|
||||
# distinct from timeoutMs (indexing) and dynamicTimeoutMs (live shim)
|
||||
completeTimeoutMs = null;
|
||||
|
||||
# worker-thread count for the parallel scrape
|
||||
workers = null;
|
||||
};
|
||||
```
|
||||
|
||||
### flag-triggering behaviour
|
||||
|
||||
`flagTriggers` and `flagOnEmpty` control when option/flag completions are
|
||||
offered. By default flags appear only after a leading `-`. Add characters
|
||||
to `flagTriggers` (e.g. `"-+"`) to trigger on them as well — for a
|
||||
non-dash trigger the text after it is matched against the bare flag name,
|
||||
so `+ver` completes to `--verbose`. Set `flagOnEmpty = true` to list flags
|
||||
immediately after a space, alongside subcommands. These map to the
|
||||
`INSHELLAH_FLAG_TRIGGERS` / `INSHELLAH_FLAG_ON_EMPTY` environment variables
|
||||
(see [runtime-completions.md](runtime-completions.md)).
|
||||
|
||||
## using the completer
|
||||
|
||||
the module installs the completer under nushell's vendor autoload path,
|
||||
|
|
|
|||
|
|
@ -54,6 +54,35 @@ $env.config.completions.external = {
|
|||
|
||||
paths after the first in `--dir` are read-only system dirs.
|
||||
|
||||
## configuration
|
||||
|
||||
the `complete` path reads a few behavioural knobs from the environment.
|
||||
each has a compiled-in default that reproduces the original behaviour, so
|
||||
an unconfigured install is unchanged. on nixos these are set for you by
|
||||
the module options (see [nixos.md](nixos.md)); elsewhere, export them in
|
||||
your shell before nushell starts.
|
||||
|
||||
| variable | default | effect |
|
||||
|---|---|---|
|
||||
| `INSHELLAH_FLAG_TRIGGERS` | `-` | characters that surface flag completions when a partial token begins with one of them. set to `-+` to also trigger on `+`; whitespace is ignored. an empty value disables prefix-triggered flags (leaving only `INSHELLAH_FLAG_ON_EMPTY`). |
|
||||
| `INSHELLAH_FLAG_ON_EMPTY` | `0` | when truthy (`1`/`true`/`yes`/`on`), also surface flags on an empty token — i.e. right after a space — alongside subcommands. otherwise an empty token hands off to file/dynamic completion. |
|
||||
| `INSHELLAH_MAX_COMPLETIONS` | `0` | cap on the number of candidates returned (and nushell's `max_results` when sourcing the bundled snippet). `0` imposes no inshellah cap; nushell's own default of 200 still applies. |
|
||||
| `INSHELLAH_TIMEOUT_MS` | `200` | per-subprocess timeout for the on-the-fly `--help` resolution. an explicit `--timeout-ms` flag overrides it. |
|
||||
|
||||
### flag triggering
|
||||
|
||||
by default flags are offered only once a token begins with `-`
|
||||
(`git commit --<TAB>`). two overrides are available:
|
||||
|
||||
- **other trigger characters** — `INSHELLAH_FLAG_TRIGGERS="-+"` makes a
|
||||
leading `+` surface flags too. for non-dash triggers the typed text
|
||||
after the trigger is matched against the bare flag name, so `+ver`
|
||||
completes to `--verbose`. the emitted value keeps the tool's real
|
||||
dashed flag.
|
||||
- **flags after a space** — `INSHELLAH_FLAG_ON_EMPTY=1` lists flags
|
||||
immediately after a space, mixed in with subcommands, before any
|
||||
character is typed.
|
||||
|
||||
## cache management
|
||||
|
||||
```sh
|
||||
|
|
@ -84,3 +113,23 @@ for upfront indexing on non-nixos systems:
|
|||
```sh
|
||||
inshellah index /usr /usr/local
|
||||
```
|
||||
|
||||
## macOS developer toolchain
|
||||
|
||||
`/usr/bin/git`, `/usr/bin/clang`, and friends are `xcrun` shims whose real
|
||||
binaries and manpages live under the active developer dir (`xcode-select
|
||||
-p` — Command Line Tools or full Xcode), outside the usual prefixes. to
|
||||
index those, point `index` at the real prefix explicitly — either the
|
||||
developer dir or, preferably, the nix equivalents:
|
||||
|
||||
```sh
|
||||
# the active developer toolchain
|
||||
inshellah index --prefix "$(xcode-select -p)/usr"
|
||||
|
||||
# or nix-provided tools, kept reproducible
|
||||
inshellah index /run/current-system/sw --prefix /nix/store/…-git:/nix/store/…-clang
|
||||
```
|
||||
|
||||
`--prefix` takes a colon-separated list of extra prefixes, scraped
|
||||
alongside the positional ones. the nix module exposes this as
|
||||
`programs.inshellah.extraScrapePackages` (see [nixos.md](nixos.md)).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue