# nsx build

Build a generated NSX app

## Usage

```text
nsx build [-h] [--app-dir APP_DIR] [--board BOARD]
                 [--build-dir BUILD_DIR] [--toolchain TOOLCHAIN]
                 [--sdk-root SDK_ROOT] [--target TARGET] [--jobs JOBS]
                 [--update] [--frozen] [--timeout SECONDS]
                 [app]
```

## Arguments

| Option | Value | Default | Description |
| --- | --- | --- | --- |
| app | value | optional | App name or directory (overrides --app-dir; resolved under ./ and ./examples) |

## Options

| Option | Value | Default | Description |
| --- | --- | --- | --- |
| --app-dir APP_DIR | value | . | App directory containing nsx.yml |
| --board BOARD | value | optional | Override board from nsx.yml |
| --build-dir BUILD_DIR | value | optional | Build directory override |
| --toolchain TOOLCHAIN | value | optional | Toolchain override (gcc, armclang, atfe) |
| --sdk-root SDK_ROOT | value | optional | Optional out-of-tree AmbiqSuite root passed as NSX_AMBIQSUITE_ROOT_OVERRIDE |
| --target TARGET | value | optional | Optional explicit build target |
| --jobs JOBS | value | 8 | Parallel build jobs |
| --update | flag | optional | Re-resolve module constraints to upstream tip and re-vendor before building |
| --frozen | flag | optional | When a (re)configure is needed (no build.ninja yet), error on any drift between nsx.yml, nsx.lock, and modules/ instead of correcting it; modules missing from modules/ are fetched at their locked revision and verified |
| --timeout SECONDS | value | optional | Wall-clock budget per subprocess (seconds). Kills the whole process group on timeout. |

## Notes

`nsx build` operates on the generated app's CMake build tree. When `--app-dir` is omitted
NSX searches upward from the current directory for `nsx.yml`; the positional `app` argument
overrides that and is resolved under the current directory and `examples/`.

`--sdk-root` is an escape hatch that builds against an out-of-tree AmbiqSuite root
(`NSX_AMBIQSUITE_ROOT_OVERRIDE`). It warns that `nsx.lock` and the SBOM no longer describe
the binary, cannot be combined with `--frozen`, and forces a reconfigure when it differs
from the cached override.

```bash
cd <app-dir>
nsx build --jobs 8
```

Run `nsx commands --json` for the authoritative machine-readable argument schema.

The out-of-tree SDK escape hatch is described under [SDK provider selection](/neuralspotx/guides/modules/sdk-providers/) in the guides.

`-v/--verbose`, `-q/--quiet` are parsed by `nsx` itself, so they go before the command name, as `nsx -v build`.