|
| 1 | +# Configuring Holoscan CLI |
| 2 | + |
| 3 | +Run `holoscan` inside a source project. To select another project, put the |
| 4 | +global option before the command: |
| 5 | + |
| 6 | +```bash |
| 7 | +holoscan --project-root /path/to/module list |
| 8 | +``` |
| 9 | + |
| 10 | +The root is selected from `--project-root`, `HOLOSCAN_CLI_ROOT`, then the current |
| 11 | +directory and its ancestors. |
| 12 | + |
| 13 | +For standalone Modules, `metadata.json` supplies the identity, minimum SDK |
| 14 | +version, Dockerfile, and modes. The CLI otherwise uses these defaults: |
| 15 | + |
| 16 | +- Target architecture: `HOLOSCAN_CLI_TARGET_ARCH`, then the host architecture. |
| 17 | +- CUDA: `--cuda`, `HOLOSCAN_CLI_DEFAULT_CUDA_VERSION`, `tool.holoscan.cuda`, |
| 18 | + then host detection. |
| 19 | +- CTest script: `--ctest-script`, `HOLOSCAN_CLI_CTEST_SCRIPT`, |
| 20 | + `tool.holoscan.ctest-script`, then the bundled script. |
| 21 | +- Execution: `--local`, `HOLOSCAN_CLI_BUILD_LOCAL`, the selected mode, then a container. |
| 22 | +- Build type: `--build-type`, `CMAKE_BUILD_TYPE`, the selected mode, then release. |
| 23 | +- Local SDK: `--local-sdk-root`, `HOLOSCAN_SDK_ROOT`, `/workspace/holoscan-sdk` |
| 24 | + for local container builds, a nearby `holoscan-sdk` install or configured source |
| 25 | + build, then `/opt/nvidia/holoscan`. Both 4.x CUDA-qualified directories such as |
| 26 | + `install-cu13-x86_64` and 5.x architecture-only directories such as |
| 27 | + `install-x86_64` are supported; installs are preferred over builds. An invalid |
| 28 | + `HOLOSCAN_SDK_ROOT` warns and does not fall back. |
| 29 | + |
| 30 | +## `pyproject.toml` settings |
| 31 | + |
| 32 | +For a standalone Module, Holoscan CLI reads only the `[tool.holoscan]` table. |
| 33 | +Other `pyproject.toml` tables belong to Python packaging and development tools. |
| 34 | + |
| 35 | +These are all currently supported Holoscan CLI settings: |
| 36 | + |
| 37 | +| TOML path | Type and default | Behavior | |
| 38 | +| --- | --- | --- | |
| 39 | +| `tool.holoscan.cuda` | Integer; default detected from the host | Module-wide CUDA major version. | |
| 40 | +| `tool.holoscan.ctest-script` | Relative path; default is the bundled script | Module-specific CTest driver. | |
| 41 | +| `tool.holoscan.forward-env` | Array of strings; default `[]` | Names of host environment variables allowed into project containers. | |
| 42 | +| `tool.holoscan.docker-build-args` | Array of non-empty string tokens; default `[]` | Module-wide Docker build options. | |
| 43 | +| `tool.holoscan.docker-run-args` | Array of non-empty string tokens; default `[]` | Module-wide Docker run options. | |
| 44 | +| `tool.holoscan.base-images` | Table; default absent | Exact base images selected by target architecture. Only the two keys below are accepted. | |
| 45 | +| `tool.holoscan.base-images.x86_64` | String; no default | Base image used when the normalized target architecture is `x86_64`. | |
| 46 | +| `tool.holoscan.base-images.aarch64` | String; no default | Base image used when the normalized target architecture is `aarch64`. | |
| 47 | + |
| 48 | +For example: |
| 49 | + |
| 50 | +```toml |
| 51 | +[tool.holoscan] |
| 52 | +cuda = 13 |
| 53 | +ctest-script = "ci/container.ctest" |
| 54 | +forward-env = ["IS_CI_BUILD"] |
| 55 | +docker-build-args = ["--build-arg", "PROJECT_FEATURE=ON"] |
| 56 | +docker-run-args = ["--network=host"] |
| 57 | + |
| 58 | +[tool.holoscan.base-images] |
| 59 | +x86_64 = "registry.example.com/holoscan/sdk-build-x86_64:5.0.0-cuda13" |
| 60 | +aarch64 = "registry.example.com/holoscan/sdk-build-aarch64:5.0.0-cuda13" |
| 61 | +``` |
| 62 | + |
| 63 | +`cuda` selects the Module-wide CUDA major. |
| 64 | +`ctest-script` must stay within the Module and is resolved from its root. |
| 65 | +Environment variables and command options override both project defaults. |
| 66 | + |
| 67 | +`forward-env` entries must be valid environment variable names. Values are |
| 68 | +never stored in the file or placed on the Docker command line; Docker inherits |
| 69 | +the value only when that name exists on the host. Project entries are additive |
| 70 | +with `HOLOSCAN_CLI_FORWARD_ENV` and repeated `--forward-env NAME` options. |
| 71 | +`NVIDIA_DRIVER_CAPABILITIES`, `NVIDIA_VISIBLE_DEVICES`, `HOME`, |
| 72 | +`CUPY_CACHE_DIR`, and `HOLOSCAN_CLI_BUILD_LOCAL` are CLI-owned and cannot be |
| 73 | +listed. |
| 74 | + |
| 75 | +Each Docker argument array element is one command token. Arguments are composed |
| 76 | +in this order: project, selected `metadata.json` mode, environment |
| 77 | +(`HOLOSCAN_CLI_DEFAULT_DOCKER_BUILD_ARGS` or |
| 78 | +`HOLOSCAN_CLI_DEFAULT_DOCKER_RUN_ARGS`), then command line. Later options can |
| 79 | +therefore override earlier ones when Docker uses last-option-wins behavior. |
| 80 | + |
| 81 | +Each `base-images` value must be a non-empty image reference without whitespace |
| 82 | +and is used exactly as written. If the table exists, it must contain an entry |
| 83 | +for the selected target architecture. Provide both entries when the Module |
| 84 | +supports both architectures. `--base-img` and an explicit |
| 85 | +`HOLOSCAN_CLI_BASE_IMAGE` override the project value. |
| 86 | + |
| 87 | +Unknown keys in either `[tool.holoscan]` or `[tool.holoscan.base-images]` are |
| 88 | +rejected. No other Holoscan CLI `pyproject.toml` settings are currently |
| 89 | +supported. |
| 90 | + |
| 91 | +Do not put credentials or machine-specific paths in project configuration. |
| 92 | + |
| 93 | +## Command options |
| 94 | + |
| 95 | +```bash |
| 96 | +holoscan build my_app --local --build-type debug |
| 97 | +holoscan build my_app --cuda 13 --base-img registry.example.com/sdk:reviewed |
| 98 | +``` |
| 99 | + |
| 100 | +`--build-args` adds Docker build options. `--docker-opts`, `--configure-args`, |
| 101 | +and `--forward-env NAME` are repeatable and additive. |
| 102 | + |
| 103 | +`--build-with` replaces the selected mode's operator dependencies; use |
| 104 | +`--build-with=` to select none. |
| 105 | + |
| 106 | +Add `--dryrun` to a lifecycle command to see the resolved configuration and commands |
| 107 | +without executing them. Scalar values include their source. Docker and CMake options show |
| 108 | +which layers configured them without exposing their values; forwarded environment entries |
| 109 | +show names but not values. |
| 110 | + |
| 111 | +For example, a container build using the project settings above reports a summary like: |
| 112 | + |
| 113 | +```text |
| 114 | +Effective configuration (opaque option values hidden): |
| 115 | + project root: /workspace/my-module (directory discovery) |
| 116 | + mode: release (project default) |
| 117 | + execution: container (built-in default) |
| 118 | + build type: Release (built-in default) |
| 119 | + CUDA: 13 (project (tool.holoscan.cuda)) |
| 120 | + local SDK: none (container image) |
| 121 | + base image: registry.example.com/holoscan/sdk-build-x86_64:5.0.0-cuda13 (project (tool.holoscan.base-images)) |
| 122 | + Docker build options: configured by project (values hidden) |
| 123 | + run image: holoscan-my-module:review (derived default) |
| 124 | + Docker run options: configured by project (values hidden) |
| 125 | + forward-env: IS_CI_BUILD (project) |
| 126 | + CMake configure options: none |
| 127 | +``` |
0 commit comments