init

doc/building.md

@@ -0,0 +1,163 @@
+# 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:
+
+```sh
+nix build
+```
+
+the binary is at `./result/bin/inshellah`.
+
+for development with a shell containing all dependencies:
+
+```sh
+nix develop
+dune build
+dune test
+```
+
+## building from source with opam
+
+install dependencies via opam:
+
+```sh
+opam install dune angstrom angstrom-unix camlzip
+```
+
+build and test:
+
+```sh
+dune build
+dune test
+```
+
+install into the opam switch:
+
+```sh
+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:
+
+```sh
+dune build
+```
+
+the binary is at `_build/default/bin/main.exe`. copy it to your
+`$PATH`:
+
+```sh
+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:
+
+```sh
+# 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
+
+```sh
+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
+
+```sh
+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):
+
+```sh
+# typical linux system
+inshellah index /usr /usr/local
+
+# check what was indexed
+inshellah dump
+```
+
+then wire up the nushell completer:
+
+```nu
+# ~/.config/nushell/config.nu
+$env.config.completions.external = {
+    enable: true
+    completer: {|spans|
+        inshellah complete ...$spans
+        | from json
+    }
+}
+```
+
+see [nushell-integration.md](nushell-integration.md) for full details
+on the completer, and [runtime-completions.md](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:
+
+```sh
+inshellah index /usr /usr/local
+```
+
+on nixos, the system index regenerates on every `nixos-rebuild`
+automatically. see [nixos.md](nixos.md) for details.