orisys-sdk/build/README.md

# Build tooling

Use one launcher from the repo root:

```bash
python build/run.py <command>
```

```text
build/
  run.py                  << single entrypoint
  README.md
  common/                 shared helpers (paths, pyproject, verify)
  wheel/                  SDK .whl (Nuitka + manylinux Docker)
  release/                local release gate (preflight / audit)
  gui/
    common/               shared PyInstaller driver
    ory_finger/           ORY-FINGER dashboard
    ory_mini/             ORY-MINI internal GUI (scaffold)
    ory_box/              ORY-BOX internal GUI (scaffold)
```

## Commands

### SDK wheel

```bash
python build/run.py wheel-win
python build/run.py wheel-manylinux
python build/run.py wheel-manylinux -Architecture aarch64 -PythonVersions 3.10

# Single Version
python build/run.py wheel
# Inside Docker
python build/run.py wheel --target pypi-linux --verify
```

Direct module paths (same behavior):

```bash
python build/wheel/build.py
build\wheel\win.bat
.\build\wheel\docker\run.ps1 -SkipImageBuild   # reuse the image when only sources changed
```

`wheel-manylinux` defaults to `x86_64`; `-Architecture aarch64` builds ARM64 Linux
wheels in `quay.io/pypa/manylinux_2_28_aarch64`. Docker Desktop must use Linux
containers and support ARM64 emulation on an Intel/AMD host. This runs the ARM64
compiler under QEMU, so compilation can be much slower than on native ARM64.
The default Python versions remain 3.10, 3.11 and 3.12; `-PythonVersions` selects
which ABIs to compile. The image still prepares tooling for all three ABIs.

The default image names are `orisys-manylinux` and `orisys-manylinux-aarch64`.
`-ImageName` overrides the name; a reused image must match the requested
architecture. For example, reuse the ARM64 image after source-only changes:

```powershell
.\build\wheel\docker\run.ps1 -Architecture aarch64 -PythonVersions 3.10 -SkipImageBuild
```

ARM64 wheels target glibc Linux, including Q6A and Jetson systems with compatible
Python ABIs and glibc versions (2.28 or newer for this build image). They do not
target Android. The build requires binary ARM64 wheels for the runtime
dependencies and performs the existing isolated import check. Validate on each
board before delivery; CUDA, JetPack and Qualcomm GPU/NPU runtimes need separate
compatibility checks. Builds share staging directories, so run architectures
and Python ABIs sequentially.

The image bakes in per-ABI build tooling and a per-ABI wheelhouse of the runtime
deps, so the entrypoint no longer re-resolves them over the network. See
`docs/publishing.md` §6 for build-time details, why `-SkipImageBuild` matters,
and what to change before attempting to parallelize the per-ABI builds.

### Release gate

Local only: never publishes. `--check-pypi` probes the index; native Windows
venvs may download dependencies. Linux verification uses local Docker images
and their offline wheelhouses. See `docs/publishing.en.md` for the full flow.

```bash
python build/run.py release preflight --version <version>
python build/run.py release preflight --all-wheel-pythons --check-pypi
python build/run.py release audit SDK\<version>\orisys-<version>-cp312-cp312-win_amd64.whl
```

`preflight` runs: repo state → version consistency → version-string scan →
duplicate guard (fails only when the version is already released: a local git
tag, or PyPI with `--check-pypi`) → pytest → bundle precheck → per-wheel static
content/metadata assertions → isolated runtime verification in one venv per wheel
(imports + bundled assets + real frames, no camera). A populated `SDK/<version>/`
is the expected input, so build first:

```bash
python build/run.py wheel-win
python build/run.py wheel-manylinux
python build/run.py wheel-manylinux -Architecture aarch64
python build/run.py release preflight --all-wheel-pythons --check-pypi
```

Reports land in `build/release/reports/<version>/`.

### Publish

Both default to a dry run; `--apply` is required for anything irreversible.

```bash
python build/run.py release auth                                   # credential status
python build/run.py release auth --set-token pypi                 # hidden prompt, writes ~/.pypirc
python build/run.py release github --version <version>            # preview
python build/run.py release github --version <version> --apply    # sync + tag + push + Release
python build/run.py release pypi   --version <version> --apply                  # TestPyPI only
python build/run.py release pypi   --version <version> --confirm-pypi --apply   # + PyPI
python build/run.py release pypi   --version <version> --pypi-only --apply      # skip TestPyPI
```

Both refuse to act unless `release preflight` passed on a clean commit with no
waived options, and every wheel still hashes to what that report recorded.
Runtime evidence must cover every wheel hash. `--all-wheel-pythons` verifies all
staged platforms and ABIs, using conda for Windows and matching Docker images for
Linux. GitHub attaches all certified wheels; PyPI verifies every uploaded
Python/platform wheel by downloading it and comparing its hash.
Tokens are only ever read from a hidden prompt or stdin, never from argv.
See `docs/publishing.md` §3.

### GUI

```bash
python build/run.py gui finger
python build/run.py gui mini    # scaffold / NotImplemented
python build/run.py gui box     # scaffold / NotImplemented
```

### Verify

```bash
python build/run.py verify path\to\orisys.whl
python build/run.py verify path\to\orisys.whl --contents --assets --runtime
python build/run.py verify --gui-dist --product ory_finger
```

## Outputs

- Wheels: `SDK/<version>/`, `dist/repaired/`
- Preflight reports: `build/release/reports/<version>/`
- Finger GUI: `dist/OrisysDashboard/`
- Future mini/box: `dist/OryMini/`, `dist/OryBox/`

Generated work files under `build/nuitka/`, `build/release/reports/` and
`build/pyinstaller_work/` are gitignored.