riir

doc/building.md

@@ -1,141 +1,77 @@
 # building and installing
 
-## dependencies
+inshellah is a rust crate. it builds with stock cargo on any platform
+rust supports.
 
-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:
+## with nix
 
 ```sh
 nix build
 ```
 
-the binary is at `./result/bin/inshellah`.
+binary is at `./result/bin/inshellah`.
 
-for development with a shell containing all dependencies:
+development shell:
 
 ```sh
 nix develop
-dune build
-dune test
+cargo build --release
+cargo test
 ```
 
-## building from source with opam
+## with cargo
 
-install dependencies via opam:
+requires rust >= 1.85 (edition 2024).
 
 ```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
+cargo build --release
+cargo test
+sudo install -Dm755 target/release/inshellah /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
+sudo pacman -S rust
+cargo build --release
+sudo install -Dm755 target/release/inshellah /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
+sudo apt install cargo rustc
+# or: rustup install stable
+cargo build --release
+sudo install -Dm755 target/release/inshellah /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
+sudo dnf install cargo rust
+cargo build --release
+sudo install -Dm755 target/release/inshellah /usr/local/bin/inshellah
 ```
 
 ## post-install setup
 
-after installing the binary, index completions from your system
-prefix(es):
+index completions from your system prefix(es):
 
 ```sh
 # typical linux system
 inshellah index /usr /usr/local
 
+# more workers / different timeout
+inshellah index /usr /usr/local --workers 16 --timeout-ms 500
+
 # check what was indexed
 inshellah dump
 ```
 
-then wire up the nushell completer:
+wire up the nushell completer in `~/.config/nushell/config.nu`:
 
 ```nu
-# ~/.config/nushell/config.nu
 $env.config.completions.external = {
     enable: true
     completer: {|spans|
@@ -145,19 +81,28 @@ $env.config.completions.external = {
 }
 ```
 
-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.
+see [nushell-integration.md](nushell-integration.md) for full
+completer details and [runtime-completions.md](runtime-completions.md)
+for on-the-fly resolution of commands not covered by the upfront
+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.
+on nixos, the system index regenerates on every `nixos-rebuild`. see
+[nixos.md](nixos.md).
+
+## development
+
+```sh
+cargo build           # debug build, faster compile
+cargo test            # full test suite
+cargo clippy --release
+```
+
+a `man` binary is useful at runtime as a fallback for locating
+manpages outside the indexed prefixes — not required for indexing
+itself.