# nsx module add

Add a module to an app's direct dependencies (modules:). The full closure is recomputed from the board profile + direct deps at lock time.

## Usage

```text
nsx module add [-h] [--app-dir APP_DIR] [--local] [--vendored]
                      [--path DIR] [--board BOARD] [--dry-run]
                      module
```

## Arguments

| Option | Value | Default | Description |
| --- | --- | --- | --- |
| module | value | required | Module name to add |

## Options

| Option | Value | Default | Description |
| --- | --- | --- | --- |
| --app-dir APP_DIR | value | . | App directory containing nsx.yml |
| --local | flag | optional | Mark the module as local (mirrored from external path; ignored by git) |
| --vendored | flag | optional | Scaffold a vendored module under modules/<name>/ (committed in this app's git; never touched by `nsx sync`) |
| --path DIR | value | optional | Use an external linked checkout at DIR (source: { path: DIR }) |
| --board BOARD | repeatable | optional | Scope the dependency to BOARD (repeatable; subset of supported targets) |
| --dry-run | flag | optional | Show changes without writing |

## Notes

This is the standard way to install a supported first-class module into an app. The module
is appended to the app's single `modules:` list of direct dependencies; the resolved
closure is recomputed into `nsx.lock`. For built-in modules NSX uses the registry's default
upstream repo and revision unless the app overrides that source.

```bash
cd <app-dir>
nsx module add nsx-uart
```

`--board` scopes the dependency to specific boards instead of all of `targets.supported`.
Repeat the flag for multiple boards; each must be a subset of the app's supported targets.
It writes a `boards:` filter on the entry:

```yaml
- name: nsx-pdm
  boards: [apollo510_evb]
```

`--path` adds the module as a linked dependency sourced from an external directory. The
on-disk copy under `modules/<name>/` is mirrored from that path on every `nsx sync`, and
the entry is written as `source: { path: ... }`.

`--vendored` scaffolds a custom module that lives inside this app's git repository and is
never touched by `nsx sync`, which suits AOT-generated modules, in-house drivers, or any
code that needs to be source-controlled with the app. It creates `modules/<name>/` with a
minimal `nsx-module.yaml` and `CMakeLists.txt`, appends `source: { vendored: true }` to
`nsx.yml`, regenerates `modules/.gitignore` so the directory is not ignored, and refreshes
`nsx.lock` so the module's content hash is recorded. Edit the scaffolded `CMakeLists.txt`
to add your sources, then re-run `nsx lock`.

`--local` marks the module as a local mirror, so the on-disk copy under `modules/<name>/`
is regenerated from an external source path on every sync. That path comes from either the
`source: { path: <p> }` shorthand on the module entry or from
`module_registry.modules.<name>.local_path`.

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