build-and-run.md (8449B)
1 # Build and run 2 3 Run these commands from the extracted tricu directory. You need [Nix](https://nixos.org/download/) 4 with flakes enabled. Native development uses the Haskell host; builds and tests 5 run through Nix. The [Zig runtime and owned-handle C ABI](../ext/zig/README.md) 6 have their own Nix validation targets. The 7 [cross-runtime reproduction workflow](compiler-rebuilding.md.html#isolated-cross-runtime-fixed-point-reproduction) 8 verifies identical compiler generations on Haskell and Zig. 9 10 ## Build the host 11 12 ```sh 13 nix build .# 14 result/bin/tricu --help 15 ``` 16 17 The host evaluates trees and provides IO. The source compiler is a separate, 18 compiled tricu program, included at `bootstrap/build-stable.arboricx`. 19 20 The executable automatically selects that packaged stable compiler. It locates 21 its installed data independently of the caller's working directory, authenticates 22 the bundle, and imports it indexed into the selected store. Missing or corrupt 23 package data is an error, never a switch to the Haskell recovery syntax. 24 25 The compiler's bytes and source provenance are recorded in 26 `bootstrap/stable-compiler.json`. `python3 test/shipped_compiler.py` verifies the 27 bundle against its recorded snapshots and published executable tree. 28 29 ## Run a program 30 31 Create a UTF-8 source file. Strings and comments support Unicode; identifiers 32 remain ASCII. Malformed UTF-8 and an initial BOM are rejected. See 33 [source characters](language.md.html#source-characters-and-tokens). 34 35 ```sh 36 WORK=$(mktemp -d) 37 cat > "$WORK/hello.tri" <<'EOF' 38 !export main 39 40 first [value | _] = value 41 first _ = 0 42 43 main = first [42 7] 44 EOF 45 46 result/bin/tricu eval "$WORK/hello.tri" \ 47 --store "$WORK/application" --format number 48 # 42 49 ``` 50 51 `--store` holds application objects, build records, and the automatically imported 52 compiler. The selected stable compiler supports the 53 [current language features](language-features.md.html). 54 55 The module exports `main`, which `eval` selects. `first` matches equations in 56 order: a nonempty list returns its first value; the fallback returns zero. 57 `--format number` tells the host how to display the resulting tree. 58 59 ## Package a program 60 61 Compile the same module into a self-contained bundle: 62 63 ```sh 64 result/bin/tricu arboricx compile --file "$WORK/hello.tri" \ 65 --store "$WORK/application" --output "$WORK/hello.arboricx" 66 67 result/bin/tricu arboricx import \ 68 --file "$WORK/hello.arboricx" --store "$WORK/runtime" 69 ``` 70 71 Set `APP_MANIFEST` to the full manifest hash printed by this import, then run: 72 73 ```sh 74 APP_MANIFEST=PASTE_THE_MANIFEST_HASH_HERE 75 result/bin/tricu arboricx run --module "$APP_MANIFEST" --name main \ 76 --store "$WORK/runtime" --format number 77 # 42 78 ``` 79 80 This last command executes the stored program. Bundle import defaults 81 to indexed storage, preserving shared branches. Importing native library 82 dependencies is a different operation; see [modules](modules.md.html) 83 and the [artifact checks](tri-tools.md.html#host-artifact-checks) before choosing flat storage. 84 85 For programs with effects, select `--io` and grant the application its own file 86 permissions. Use trusted store directories. See [execution options](tri-tools.md.html#io-and-permissions). 87 88 `WORK` is temporary and contains all objects created by this example. Keep it if 89 you want to reuse them, or remove it when finished. 90 91 For exact-version registry publication and dependency fetching, see 92 [Packages](modules.md.html#exact-version-packages-from-trusted-registries). 93 For a whole application dependency set, use a 94 [project declaration and consolidated lock](modules.md.html#project-dependencies); 95 resolve/update, fetch, bind and check remain separate from compilation. Offline 96 [explain and diff reports](modules.md.html#explain-selections-and-compare-locks) 97 show selected dependencies, local evidence and structural changes without running 98 exported programs. 99 100 ## Deploy the Arboricx registry (Linux) 101 102 The `arboricxServer` flake output builds the image `arboricx-server:latest`. 103 It compiles `tricu-apps/arboricxServer.tri` directly using the repository 104 `tricu.workspace` source locations and packaged stable compiler at build time. Startup runs the compiled 105 manifest from a read-only Nix store; it does not compile source, search 106 `tricu.workspace`, or write a compiler cache into registry storage. 107 108 ```sh 109 nix build .#arboricxServerTest --no-link 110 nix build .#arboricxServer -o result-server 111 112 docker load < result-server 113 mkdir -p registry-store 114 docker run -d --name arboricx-registry --restart unless-stopped \ 115 --user "$(id -u):$(id -g)" --read-only \ 116 --cap-drop ALL --security-opt no-new-privileges \ 117 -p 127.0.0.1:8080:8080 \ 118 --mount "type=bind,src=$PWD/registry-store,dst=/app/store" \ 119 arboricx-server:latest 120 curl --fail http://127.0.0.1:8080/_arboricx/health 121 ``` 122 123 The process listens on `0.0.0.0:8080` inside the container. The example publishes 124 only host loopback; put a protected reverse proxy in front of it for remote 125 access. The bind mount must be writable by the selected UID/GID. Preserve and 126 back up `registry-store` across replacements; do not mount over `/nix/store`. 127 Storage initialization and socket bind/listen failures exit nonzero. Monitor the 128 HTTP health endpoint externally; the minimal image has no curl-based healthcheck. 129 130 Endpoints include the landing page, `GET /_arboricx/health`, 131 `POST /_arboricx/bundle` (201 with a SHA-256 hash), 132 `GET /_arboricx/bundle/hash/HASH`, and 133 `GET /_arboricx/package/NAME/VERSION`. Package indexes are read-only over HTTP; 134 use [administrative publication](modules.md.html#exact-version-packages-from-trusted-registries) 135 to populate them in the mounted root. Uploads store opaque bytes: hashing is not 136 bundle validation or authorization. 137 138 **Deployment limits:** this is a research registry, not a hardened public upload 139 service. It has no built-in authentication, TLS, quotas, or request deadlines. 140 Protect uploads at the proxy and apply connection/time/rate and storage limits. 141 The current HTTP parser caps headers at 64 KiB and bodies at 1 MiB. The runner 142 uses one Haskell capability and a 2 GiB managed-heap limit, not a total-process 143 memory guarantee; set container resource limits appropriate to the workload. 144 Retain the previous image and a storage backup for rollback. 145 146 For native operation, build `.#arboricxServerRunner` and run 147 `result/bin/arboricx-server` from a writable directory; it uses `./store` and the 148 same fixed port. `.#arboricxServerBundle` exposes `server.arboricx`, `manifest`, 149 and the indexed `runtime` store. The opt-in `arboricxServerTest` exercises the 150 actual runner: startup failures, health, binary uploads/downloads, invalid paths, 151 package lookup, and persistence across restart. It is not a container-engine test. 152 153 ## Explicit compiler selection 154 155 For development or a pinned alternate compiler, import a caller-selected bundle: 156 157 ```sh 158 result/bin/tricu arboricx import --file bootstrap/build-stable.arboricx \ 159 --store "$WORK/tools" --indexed 160 COMPILER_MANIFEST=PASTE_THE_FULL_MANIFEST_HASH_HERE 161 result/bin/tricu eval "$WORK/hello.tri" --store "$WORK/application" \ 162 --toolchain "$COMPILER_MANIFEST" --tool-store "$WORK/tools" --format number 163 ``` 164 165 Use the manifest hash printed on the last import line, not a mutable alias or 166 individual export hash. `--tool-store` requires `--toolchain` and otherwise defaults 167 to the application store. An explicit selection never falls back to package data. 168 169 For retained source/compiler/dependency inputs and an independent offline replay, 170 see [provenance capture, verify and rebuild](modules.md.html#retained-build-inputs-and-reproduction). 171 172 ## Interactive use 173 174 Run `result/bin/tricu` (or `result/bin/tricu repl`) for a portable session. 175 Definitions and expressions use the same compiler as files. Use `!help` for 176 multiline blocks, imports, loading files, and session operations; see 177 [interactive semantics](tri-tools.md.html#interactive-sessions). 178 179 ## Where next 180 181 - [Language features](language-features.md.html) and [contracts](contracts.md.html). 182 - [Modules](modules.md.html) for imports and exports, including the 183 [offline package inspector](modules.md.html#first-published-libraries-an-offline-bundle-inspector). 184 - [Tools](tri-tools.md.html) for formatting, IO, and compiler options. 185 - [Testing](validation.md.html): start with `nix flake check`; understand the difference 186 between reference tests, candidate checks, and compiler acceptance. 187 - [Compiler rebuilding](compiler-rebuilding.md.html): for changing or recovering the 188 compiler.