@amritk/nish-x86_64-linux 0.18.0 → 0.21.0

package/INSTALL.md

@@ -109,7 +109,7 @@ Through npm, which is also how an Nish *program* resolves its dependencies
 the compiler pinned per project in a `package.json`:
 
 ```bash
-npm install -g @amritk/nish
+npm install -g nish
 nish --version
 ```
 
@@ -171,13 +171,12 @@ never fails over it.
 > underlying defect is [wp19 §5a](wp19-stage0-retirement.md#5a-what-r6-is-waiting-on)
 > item 4.
 
-**Do not install `nish`.** That name on the public registry has belonged to
-`stdarg`'s "A Node.js Interactive shell" since February 2014 — versions 0.0.0
-and 0.0.1, both deprecated by their author, nothing published since. **This
-compiler is `@amritk/nish`** (decided 2026-09-19,
-[docs/wp12-release.md](wp12-release.md#the-npm-name)), and the command it
-installs is still `nish` — the package name and the command are two different
-strings, and that is the one thing the scope costs.
+**The package is `nish` from 0.20.0.** Releases up to 0.18.0 were published
+as `@amritk/nish` (0.19.0's publish to npm failed), which is deprecated and
+points here; `npm install -g nish`
+replaces it ([docs/wp12-release.md](wp12-release.md#the-npm-name)). Versions
+0.0.0 and 0.0.1 of `nish` are an unrelated 2014 project that held the name
+before it, so pin `nish@^0.20.0` or later rather than an older range.
 
 **On a platform this project attaches no binary for, `npm install` gets you a
 command that refuses.** The table below is the whole list, so musl, FreeBSD and
@@ -224,7 +223,8 @@ routes are
   build/nish app.ts -o app.ll
   # on the musl host, with its own clang and the runtime from this repository
   clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
-    runtime/runtime-host.c runtime/runtime-net.c -lm -o app
+    runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
+    runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-term.c runtime/runtime-bytes.c -lm -o app
   ```
 
   `--link`ing inside the container is the mistake to avoid: it shells out to the
@@ -240,18 +240,20 @@ routes are
 If you need one of these to be a first-class install, that is the conversation
 to have on the issue tracker rather than a workaround to discover here.
 
-**On the registry from 0.10.0.** Every release publishes the main package and
-its platform packages to npm from `release.yml`, by trusted publishing
+**On the registry from 0.10.0** — as `@amritk/nish` through 0.18.0, and as
+`nish` from 0.20.0; 0.19.0 is on GitHub only, because its npm publish
+failed. Every release publishes the main package and its platform packages to
+npm from `release.yml`, by trusted publishing
 ([docs/wp12-release.md](wp12-release.md#release-procedure) step 4), so
-`npm install -g @amritk/nish` is the whole install. The rest of this section is
+`npm install -g nish` is the whole install. The rest of this section is
 for a machine that cannot reach the registry, or a release before 0.10.0.
 
 From a release tarball on GitHub — the same package `npm publish` uploads,
 carried by the release instead of the registry. The `Release` workflow attaches
 the npm tarball to the release it builds for a `v*` tag. `npm pack` names it
-after `package.json#name`, so it is `amritk-nish-<version>.tgz` from 0.4.0 on
-and `nish-<version>.tgz` for the releases cut before the scope was taken — the
-example below is one of those:
+after `package.json#name`, so it is `nish-<version>.tgz` before 0.4.0 and
+from 0.20.0 on, and `amritk-nish-<version>.tgz` from 0.4.0 to 0.19.0, while the
+package was scoped — the example below is one of the early ones:
 
 ```bash
 curl -LO https://github.com/amritk/nish/releases/download/v0.2.0/nish-0.2.0.tgz
@@ -358,21 +360,25 @@ it into `build/seed/`; `NISH_BOOTSTRAP=<path>` names one you already have and
 skips the download. §2a has what the build does with it.
 
 The published package ships `bin/` (the `nish` command, which is a launcher),
-`runtime/` (the C runtime — five translation units and their header),
-`scripts/build.sh` (the link pipeline) and `std/` (the standard library). The
+`runtime/` (the C runtime — ten translation units, the wasm subset and their
+header — and `runtime/sqlite/`, SQLite's vendored source),
+`scripts/build.sh` (the link pipeline), `std/` (the standard library) and
+`docs/AI.md` (the rules card). The
 compiler itself is not in it: it arrives as one prebuilt
 `@amritk/nish-<asset>` package per platform, and `bin/nish` hands over to
-whichever one npm installed. `nish` locates the runtime, the script and `std/`
+whichever one npm installed. That package carries its own copy of all of
+these, and its `docs/AI.md` is the one an agent's `nish --help` names. `nish` locates the runtime, the script and `std/`
 relative to its own install directory, so a global install works from any
 working directory — and the binary runs from inside its own platform package
 for exactly that reason.
 
 Building the IR yourself rather than through `--link` means naming the runtime
-on the `clang` line, and it is five files:
+on the `clang` line, and it is ten files:
 
 ```bash
 clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
-  runtime/runtime-host.c runtime/runtime-net.c -lm -o app
+  runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
+  runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-term.c runtime/runtime-bytes.c -lm -o app
 ```
 
 `runtime.c` is the part every program touches — the arena, strings, arrays,
@@ -380,16 +386,28 @@ number formatting, the panics — and `runtime-os.c` wraps the system calls:
 files, directories, subprocesses, `getenv`, the monotonic clock.
 `runtime-parallel.c` divides work across threads for `nish/threads` (a
 program built with `--threads`, as every importer of `nish/threads` is, also
-needs `-DNISH_THREADS=1 -pthread` on the line), `runtime-host.c` holds the
-wall clock, entropy, file times and signals, and `runtime-net.c` the sockets
-of `nish:net`. They are separate so that each
-carries its own measured size ceiling ([docs/wp7-runtime.md](wp7-runtime.md));
-nothing in the core calls into the others, so a line that names only
-`runtime.c` and `runtime-os.c` still links a program that uses none of the
-other three. `scripts/build.sh` compiles the other four beside any
+needs `-DNISH_THREADS=1 -pthread` on the line), `runtime-cross.c` copies
+the strings and arrays a task answers, a channel sends or a `Mutex` keeps out
+of the arena they were made in, `runtime-host.c` holds the wall clock,
+entropy, file times and signals, `runtime-net.c` the sockets of `nish:net`,
+`runtime-simd.c` and `runtime-aes.c` the vector text search and AES-GCM,
+`runtime-term.c` the stdin reads and terminal calls of `nish:term`, and
+`runtime-bytes.c` the byte-class runs of `nish/bytes`, which `nish/json` steps
+over.
+They are separate so that each carries its own measured size ceiling
+([docs/wp7-runtime.md](wp7-runtime.md)); nothing in the core calls into the
+others, so a line that names only `runtime.c` and `runtime-os.c` still links a
+program that uses none of the other eight. `scripts/build.sh` compiles the other
+eight beside any
 `runtime.c` it is handed, so a build that goes through it — every `--link`,
 and every `--profile` recipe in these documents — needs to name only the one.
 
+A program whose IR declares an `sqlite3_*` function also needs SQLite on a
+hand-written line. `scripts/build.sh` adds it by itself; by hand, append
+`runtime/sqlite/sqlite3.c` with the options `scripts/build.sh` lists under
+"SQLite's compile-time options" (at least `-DSQLITE_THREADSAFE=0`, or `=2`
+beside `-DNISH_THREADS=1`).
+
 ## 2a. What `npm run build` does
 
 `src/` is the compiler, written in Nish, and it compiles itself
@@ -479,6 +497,18 @@ refuses the run without one rather than keep a binary in a shared directory.
 The first run that builds into the cache makes its root `0700`, so no other
 user can plant a binary in it ([docs/security/cli.md](security/cli.md)).
 
+Every link with the debug, speed or size profile, `nish run`'s and `--link`'s
+alike, keeps the compiled C runtime in `$XDG_CACHE_HOME/nish/runtime` (or
+`~/.cache/nish/runtime`), one entry per profile, `-g`, `--threads`, `CC` and
+the version that compiler reports, made `0700` the same way. The first link
+compiles the runtime's six files at once into it, and every later link
+compiles only the program's modules, also at once, and links against the
+entry: a `hello.ts` debug link goes from about half a second to about a
+tenth. `--link` with no absolute `HOME` or `XDG_CACHE_HOME`, or with a root
+it cannot make private, compiles the runtime itself as it always did; the
+wasi profile and `scripts/build.sh` called directly never use the cache.
+Removing the directory is always safe.
+
 ## 4. Exit codes
 
 | Code | Meaning |
@@ -488,7 +518,7 @@ user can plant a binary in it ([docs/security/cli.md](security/cli.md)).
 | 2 | usage error: unknown flag, missing argument, no input files |
 | 3 | toolchain error: `--link` found no `clang` (`CC` overrides), or `scripts/build.sh` failed (its output is shown; the `.ll` files are still written) — or the `nish` command found no prebuilt compiler for this platform, or one that would not start. Under `--json` all of these are one `NL0002` object |
 | | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set to an absolute path it answers 3 |
-| 70 | internal compiler error: an unexpected exception. Please report it at <https://github.com/amritk/nish/issues> with the input and command line; `NISH_DEBUG=1` prints the stack trace |
+| 70 | internal compiler error: a broken invariant in the compiler. Please report it at <https://github.com/amritk/nish/issues> with the input and command line; the compiler is self-hosted and has no stack trace to print, so the message it prints is the whole report |
 
 ## Troubleshooting