@amritk/nish-aarch64-linux 0.11.0 → 0.13.0

package/scripts/build.sh

@@ -4,9 +4,9 @@
 #   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm]
 #
 # The C runtime is three translation units and is named as one: an input
-# <dir>/runtime.c also compiles <dir>/runtime_os.c, the half that wraps the
+# <dir>/runtime.c also compiles <dir>/runtime-os.c, the half that wraps the
 # system calls (files, directories, subprocesses, the environment, the clock),
-# and <dir>/runtime_parallel.c, the half that divides a range of work across
+# and <dir>/runtime-parallel.c, the half that divides a range of work across
 # threads. Each of those files says why they are compiled and measured apart.
 #
 # Profiles:
@@ -15,7 +15,7 @@
 #   size   -Oz + LTO + section GC + strip + no unwind tables. Rust
 #          `opt-level="z"`, `panic="abort"`, `strip=true` equivalent.
 #   wasm   wasm32 freestanding module exporting every non-internal function;
-#          load it from Node. Add runtime/runtime_wasm.c to the inputs when a
+#          load it from Node. Add runtime/runtime-wasm.c to the inputs when a
 #          function uses arrays (the arena and the array cold paths, no libc);
 #          strings and I/O still need a WASI runtime and are not available.
 #   wasm   wasm32 freestanding module exporting every non-internal function
@@ -84,12 +84,12 @@ done
 [ -n "$out" ] || { echo "error: -o <out> is required" >&2; exit 2; }
 
 # The runtime is three translation units, and a caller names one: whoever passes
-# <dir>/runtime.c gets <dir>/runtime_os.c and <dir>/runtime_parallel.c compiled
+# <dir>/runtime.c gets <dir>/runtime-os.c and <dir>/runtime-parallel.c compiled
 # beside it. They were one file until the operating-system half was split out
 # for its own size budget, and the parallel half followed for the same reason
 # (each file's header comment says why), and a link line is where those splits
 # would otherwise leak: `nish --link` builds its command line in
-# self/compile.ts, the published package's recipe in every document and
+# src/compile.ts, the published package's recipe in every document and
 # README names runtime.c, and a user's own clang line does too. Pairing them
 # here keeps every one of those correct, and keeps "the runtime" one thing to
 # name from the outside. A caller that names one itself is left alone, because
@@ -97,7 +97,7 @@ done
 for i in ${inputs[@]+"${inputs[@]}"}; do
   case "$i" in
     */runtime.c|runtime.c)
-      for half in runtime_os.c runtime_parallel.c; do
+      for half in runtime-os.c runtime-parallel.c; do
         side="${i%runtime.c}$half"
         have=0
         for j in "${inputs[@]}"; do
@@ -133,8 +133,12 @@ case "$(uname -s)" in
     # of one input to one output path, and differing on a link to another. That
     # is what scripts/bootstrap.sh links every comparable stage at one path for,
     # and it is why `stage3 == stage2` holds on Mach-O with the load command in.
-    gc=(-Wl,-dead_strip); strip_flag=(-Wl,-x) ;;
+    # shellcheck disable=SC2054 # -Wl,<flag> is one argument: the comma is the linker's
+    gc=(-Wl,-dead_strip)
+    # shellcheck disable=SC2054
+    strip_flag=(-Wl,-x) ;;
   *)
+    # shellcheck disable=SC2054 # -Wl,<flag> is one argument: the comma is the linker's
     gc=(-Wl,--gc-sections -Wl,--as-needed -Wl,-O2 -Wl,--build-id=none); strip_flag=(-s)
     elf=(-fno-plt)
     # GNU ld needs the gold plugin for LTO; prefer lld when clang can find it.
@@ -158,7 +162,7 @@ if [ "$debug" = 1 ]; then common+=(-g); strip_flag=(); fi
 # own command line instead of using `common`; it is empty on every ordinary
 # build, hence the bash 3.2 expansion spelling explained below.
 #
-# -pthread is for runtime_parallel.c, the translation unit that divides a range
+# -pthread is for runtime-parallel.c, the translation unit that divides a range
 # of work across threads: it is compiled in either configuration and only spawns
 # under this macro, so this is the build where the flag has to be on the command
 # line. On a current glibc the library half is already inside libc and the link
@@ -167,7 +171,7 @@ if [ "$debug" = 1 ]; then common+=(-g); strip_flag=(); fi
 #
 # It is deliberately in `common` and not in `tls`: `tls` is the wasm and wasi
 # command lines, which have no threads to link against, and where
-# runtime_parallel.c compiles to its sequential fallback because it tests
+# runtime-parallel.c compiles to its sequential fallback because it tests
 # __wasi__ and __wasm__ as well as the macro.
 tls=()
 if [ "$threads" = 1 ]; then
@@ -265,6 +269,7 @@ case "$profile" in
     shared=(-shared -fPIC)
     # macOS: the napi_* symbols come from the node binary at load time, so the
     # linker must not insist on resolving them. ELF shared objects allow this.
+    # shellcheck disable=SC2054 # -Wl,<flag> is one argument: the comma is the linker's
     case "$(uname -s)" in Darwin) shared+=(-Wl,-undefined,dynamic_lookup) ;; esac
     # runtime/nish.h is the public ABI header the generated shim includes.
     runtime_inc="$(cd "$(dirname "$0")/../runtime" && pwd)"

package/std/README.md

@@ -1,10 +1,10 @@
 # `std/` — the standard library
 
 Nish modules written in Nish, for Nish programs to import. There is no magic
-here and — with two exceptions, `threads.ts` and `collections.ts` — nothing
-the compiler knows about: a module in this directory is an ordinary Nish source file, compiled as part of
+here and — with three exceptions, `threads.ts`, `collections.ts` and `map.ts` —
+nothing the compiler knows about: a module in this directory is an ordinary Nish source file, compiled as part of
 whatever program imports it, and subject to the same rules as `examples/` or
-`self/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
+`src/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
 
 | Module | What it is |
 | --- | --- |
@@ -12,7 +12,8 @@ whatever program imports it, and subject to the same rules as `examples/` or
 | [`text.ts`](./text.ts) | the string operations a program would otherwise write inline: `splitLines`, `splitWhitespace`, `trim` and its halves, `contains`, `replaceAll`, and `firstDifference` over two arrays of lines |
 | [`json.ts`](./json.ts) | `jsonField(object, name)`: the value of one field of one flat JSON object, which is the shape the compiler's own `--json` diagnostics have. A reader and not a parser — it answers text, answers `null` for a field that is not there, and does not validate |
 | [`pair.ts`](./pair.ts) | `Pair<A, B>`: an interface with `first` and `second`, for a function that answers two values from one call. A type and nothing else — the caller writes an object literal at the return — and for returning two values rather than storing them side by side |
-| [`collections.ts`](./collections.ts) | the global `Map<K, V>` and `Set<T>`: insertion-ordered tables whose buckets carry a hash fingerprint beside the entry index and whose entries keep their full hash, so every `get`, `set`, `add`, `has` and `delete` is one probe. `get` is not a method here: its `V | undefined` never crosses a call, so the compiler lowers it to `probe` and, where the key was found, `valueAt`. Nor are `keys()` and `values()`: an iterator is not a value, so a `for...of` over one is lowered to `walkOpen`, `walkNext`, `keyAt` or `valueAt`, and `walkClose`, and a count of live walks defers compaction until no loop is walking the table. A program never imports it: naming `Map` or `Set` loads it, and the compiler emits what a module uses of it into that module ([`docs/wp32-map.md`](../docs/wp32-map.md), [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)). Its `hashKey` and `sameKey` are lowered by the compiler per key type |
+| [`collections.ts`](./collections.ts) | the global `Map<K, V>` and `Set<T>`: insertion-ordered tables whose buckets carry a hash fingerprint beside the entry index and whose entries keep their full hash, so every `get`, `set`, `add`, `has` and `delete` is one probe. `get` is not a method here: its `V | undefined` never crosses a call, so the compiler lowers it to `probe` and, where the key was found, `valueAt`. Nor are `keys()` and `values()`: an iterator is not a value, so a `for...of` over one is lowered to `walkOpen`, `walkNext`, `keyAt` or `valueAt`, and `walkClose`, and a count of live walks defers compaction until no loop is walking the table. A program never imports it: naming `Map` or `Set` loads it, and the compiler emits what a module uses of it into that module ([`docs/wp32-map.md`](../docs/wp32-map.md), [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)). Its `hashKey`, `sameKey` and `storedKey` are lowered by the compiler per key type |
+| [`map.ts`](./map.ts) | `reserve(m, n)` and `getOrInsert(m, k, v)` for the global `Map`. Their bodies are the meaning, and what runs under Node: `reserve` does nothing, and `getOrInsert` is a `get`, and a `set` of `v` when the key was missing. Natively the compiler lowers every call in place — `reserve` to the table's `reserveSlots`, which grows the buckets once so that `n` entries fit without a rebuild, and `getOrInsert` to one `probe` and a `valueAt` or an `insertAt` through its answer — so, like `collections.ts`, it writes no `.ll` of its own ([`docs/wp32-map.md`](../docs/wp32-map.md) §9.2, [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)) |
 | [`threads.ts`](./threads.ts) | `parallelMapInto(src, dst, f)` and `parallelReduce(src, f, identity)`: a function over every element of an array, on as many threads as the length is worth. Its bodies are the sequential meaning, which is what runs under Node; the compiler recognises the two templates by module and name, lowers the one loop in each onto `nish_parallel_range`, holds the function to the rules that make that safe, and compiles an importing program with `--threads` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md#data-parallelism-nishthreads)). `tests/link/par_*` are its programs |
 
 ## How a program imports it
@@ -64,12 +65,16 @@ reasons that are only true of it:
   package and is versioned with it, so "the `std/` beside this binary" is not a
   guess a resolver makes — it is the only `std/` that can be correct for the
   compiler reading it. No version can be skewed against it.
-- It **is** what Node resolves. `package.json` declares
-  `"./*": "./std/*.ts"` in `exports`, so `nish/text` is a package
-  self-reference: `import.meta.resolve("nish/text")` answers `std/text.ts`, and
-  `tsc` under `moduleResolution: node16` resolves it to the same file, which is
-  what gives an editor go-to-definition into the real source. The compiler
-  short-circuits to that answer rather than walking `node_modules` to reach it.
+- It **is** what Node and `tsc` resolve. The package is published as
+  `@amritk/nish`, so a bare `nish/text` is not a package self-reference on its
+  own; `runtime/nish.mjs`, the prelude a program runs under Node with
+  (`node --experimental-strip-types --import ./runtime/nish.mjs`), resolves
+  `nish/<module>` to `std/<module>.ts` beside itself, and the repository's
+  `tsconfig.json` maps `nish/*` to `./std/*`, which is what gives `tsc` and an
+  editor go-to-definition into the real source. `package.json` still declares
+  `"./*": "./std/*.ts"` in `exports`, so `@amritk/nish/text` reaches the same
+  file. The compiler short-circuits to that answer rather than walking
+  `node_modules` to reach it.
 
 So this is WP21's first slice rather than a detour around it: the spelling is
 the one WP21 specifies, and what is still missing is resolution for specifiers
@@ -125,7 +130,7 @@ that are *not* this package.
   stdout. `tests/link/std_text_f64` is the same corpus under
   `--number-mode f64`, which is where a module that spelled its widths and forgot
   a `toI32` is caught.
-- **`std/` is not on the compiler's dependency list.** Nothing in `self/`
+- **`std/` is not on the compiler's dependency list.** Nothing in `src/`
   imports it, and nothing should: the compiler is the thing that has to
   build before the library means anything.