# nucleos release test-suite

Per-target verification companion for the matching main tarball
`nucleos-<version>-<triple>.tar.gz`. Use this to confirm that a
released main tarball — signed, notarized, or neither — actually
runs the full Dezyne regression set on your platform. The main
tarball stays minimal (just `nucleos` + `mcrl2/bin/ltscompare` +
licences); `nuctest` and the test corpus live HERE.

## Contents

| Path | Purpose |
|---|---|
| `nuctest[.exe]` | The regression runner — same binary the upstream developer runs in CI, compiled for THIS target. |
| `nuctest.toml` | Config the runner picks up via `--root .`. |
| `test-models/` | The regression corpus baked at the tagged commit. Matches what `nuctest --category all` runs inside the repo. |
| `test-release-tarball.sh` (Linux/macOS targets) **or** `test-release-tarball-windows.sh` (Windows target) | The orchestrator. Extracts a main tarball into a temp dir, plugs the bundled `nuctest` (from here) + `nucleos` and `mcrl2/bin/ltscompare` (from the main tarball) together. The Windows variant runs the `.exe` binaries under `wine` so you can verify the Windows artefact from a Linux host without needing a Windows machine. |
| `README.md` | This file. |

## Use

Download the main per-target tarball matching your platform AND
the test-suite tarball for the same target+version (e.g. both
`*-aarch64-apple-darwin.tar.gz`). Then:

```bash
# Linux glibc:
tar xzf nucleos-test-suite-X.Y.Z-x86_64-unknown-linux-gnu.tar.gz
cd nucleos-test-suite-X.Y.Z-x86_64-unknown-linux-gnu
./test-release-tarball.sh ../nucleos-X.Y.Z-gHHHH-x86_64-unknown-linux-gnu.tar.gz

# macOS Apple Silicon:
tar xzf nucleos-test-suite-X.Y.Z-aarch64-apple-darwin.tar.gz
cd nucleos-test-suite-X.Y.Z-aarch64-apple-darwin
./test-release-tarball.sh ../nucleos-X.Y.Z-gHHHH-aarch64-apple-darwin.tar.gz

# Windows artefact, verified from Linux via Wine:
unzip nucleos-test-suite-X.Y.Z-x86_64-pc-windows-gnu.zip
cd nucleos-test-suite-X.Y.Z-x86_64-pc-windows-gnu
./test-release-tarball-windows.sh ../nucleos-X.Y.Z-gHHHH-x86_64-pc-windows-gnu.zip
# Requires `wine64` (or `wine-stable`) on PATH. The runner
# auto-detects native Windows vs Linux+Wine; pass --no-wine if
# you're running on actual Windows (MSYS2 / Git Bash).
```

Exit 0 → the main tarball passed every category `nuctest` covers
(parsing, wfc, symres, lts, verify, threads, phenom, lbs) at the
same PASS/FAIL/SKIP counts the developer's own pre-release run
reported. Exit non-zero → the per-target artefact regressed; do
NOT promote rc → final.

## What the runner does

1. Untars the main tarball into a fresh `mktemp -d` directory.
2. Verifies the main tarball layout (`nucleos`,
   `mcrl2/bin/ltscompare`, `LICENSE`, `mcrl2/LICENSE`).
3. On macOS only: `file` checks the binary is `Mach-O 64-bit
   executable arm64`; `codesign -dv` + `spctl --assess` probe
   signing/notarization (warnings, not hard failures).
4. Adds the extracted `mcrl2/bin/` to `$PATH` so nuctest's
   `find_ltscompare` resolves to it.
5. Runs `nuctest` from THIS test-suite dir against the
   EXTRACTED main-tarball nucleos:
   ```
   <test-suite>/nuctest --category all \
                        --nucleos <extract>/nucleos \
                        --root    <test-suite>
   ```
6. Propagates nuctest's exit code.
7. Cleans up the extract dir on exit (`--keep` to retain for
   post-mortem).

## Flags

```
test-release-tarball.sh <main-tarball> [--category CAT] [-j N] [--keep]
```

| Flag | Default | Meaning |
|---|---|---|
| `--category CAT` | `all` | Passed through to `nuctest --category` |
| `-j N` | `nuctest`'s default (`available_parallelism()`) | Passed through to `nuctest -j` |
| `--keep` | off | Don't delete the extracted temp dir on exit |

## Per-platform notes

- **macOS arm64**: The release is cross-compiled from Linux via
  `cargo-zigbuild` and signed/notarized via `rcodesign` (no Mac
  build runner in CI). The test-suite is the canonical end-to-end
  check that the cross-build actually runs natively on Apple
  Silicon. **Intel macOS is not supported** (no Intel target built).
- **Linux musl**: Static binary; should run on any glibc/musl box.
  Same regression set as glibc.
- **Windows**: Tested via WSL or a native nuctest.exe build; bash
  for the runner is provided by Git Bash / MSYS2.

## When to run

- Before promoting an `rc` to `final` (`scripts/release.sh promote`).
- After any change to `scripts/build-release.sh`, `scripts/build-mcrl2.sh`,
  or `.gitlab-ci.yml`'s build/sign/package stages.
- After any nucleos change suspected of platform-specific impact
  (threading, mcrl2 integration, signal handling, …).
