inshellah/doc/building.md

building and installing

dependencies

inshellah is written in OCaml and uses dune as its build system.

build dependencies:

• OCaml >= 5.0
• dune >= 3.20
• angstrom — parser combinator library
• angstrom-unix — unix extensions for angstrom
• camlzip — gzip decompression for reading compressed manpages
• str — regular expressions (ships with OCaml)
• unix — process/file operations (ships with OCaml)

runtime dependencies:

• man (optional) — used as a fallback to locate manpages during on-the-fly completion resolution. not needed if system directories are provided via --dir (manpages are found via sibling share/man).

building with nix (recommended)

if you have nix installed:

nix build

the binary is at ./result/bin/inshellah.

for development with a shell containing all dependencies:

nix develop
dune build
dune test

building from source with opam

install dependencies via opam:

opam install dune angstrom angstrom-unix camlzip

build and test:

dune build
dune test

install into the opam switch:

dune install

building from source without opam

if your distribution packages the OCaml libraries directly, install them through your package manager, then build with dune:

dune build

the binary is at _build/default/bin/main.exe. copy it to your $PATH:

install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah

arch linux

install OCaml and dune from the official repos, and the remaining libraries from the AUR or via opam:

# system packages
sudo pacman -S ocaml dune

# ocaml libraries (via opam)
opam init    # if not already initialized
eval $(opam env)
opam install angstrom angstrom-unix camlzip

# build
dune build
dune test

# install
sudo install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah

debian / ubuntu

sudo apt install ocaml opam
opam init
eval $(opam env)
opam install dune angstrom angstrom-unix camlzip

dune build
sudo install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah

fedora

sudo dnf install ocaml opam
opam init
eval $(opam env)
opam install dune angstrom angstrom-unix camlzip

dune build
sudo install -Dm755 _build/default/bin/main.exe /usr/local/bin/inshellah

post-install setup

after installing the binary, index completions from your system prefix(es):

# typical linux system
inshellah index /usr /usr/local

# check what was indexed
inshellah dump

then wire up the nushell completer:

# ~/.config/nushell/config.nu
$env.config.completions.external = {
    enable: true
    completer: {|spans|
        inshellah complete ...$spans
        | from json
    }
}

see nushell-integration.md for full details on the completer, and runtime-completions.md for on-the-fly resolution of commands not covered by the index.

re-indexing after package changes

the index is a static cache — it doesn't update automatically when you install or remove packages. re-run inshellah index after significant package changes:

inshellah index /usr /usr/local

on nixos, the system index regenerates on every nixos-rebuild automatically. see nixos.md for details.