vios-build-system · git:20260814.007874c · 2026-08-14 · sha256 dcf5f7265027a5ef
vios-build-system git:20260814.007874cA
Immutable. This exact content is served forever at /api/v1/blob/dcf5f7265027a5ef.
--- description: VIOS build system, container deployment, and common build pitfalls alwaysApply: true --- # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # Build System Use `./build.sh` -- **do not invoke `make` directly**. Run `./build.sh help` for all options. Valid modules: `sensor`, `rtspserver`, `recorder`, `livestream`, `replaystream`, `streambridge`, `storage`, `streamprocessing` **Toolchain & base are automatic:** `./build.sh container module=…` auto-builds the compile toolchain + base image on first run (cached afterward, never rebuilt unless deleted). Just run the build directly — do NOT ask the user to build a toolchain first or which toolchain tag to use. First build on a fresh clone is ~10-15 min longer because of this one-time step. For a pre-pulled toolchain, pass `toolchain-image=<ref>` (or set `X86_BUILD_IMAGE`/`AARCH64_CC_IMAGE`) with `no-auto-deps`. **Registry/tags:** default image tags are local-only (`vios/...`, `nvstreamer`). To publish, pass `image-registry=<ref>` / `nvstreamer-image=<ref>` / `toolchain-image=<ref>` (or the matching env vars) at build time, then `push=1`. # Build and Deploy Workflow VIOS runs inside Docker containers. The dev build-deploy cycle is: 1. **Build + containerize**: `./build.sh container module=<modules>` (compiles C++, packages, creates Docker image) 2. **Deploy via docker-compose**: `python3 deployment/stream-processing/oneclick_dc_deployment.py` (non-interactive one-click deployment by default; pass `--interactive` to opt in to prompts) ## IMPORTANT: Auto-run build and deploy commands When the user asks to build, deploy, stop, or redeploy -- run the commands immediately without asking for confirmation. Always use `--force` on the deployment script to skip the "existing deployment detected" prompt. Do NOT ask the user "shall I proceed?" or "want me to run this?" -- just execute. - Build: `./build.sh container module=<modules>` -- run directly, long-running (~20min for all modules) - Deploy: `python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --force` -- run directly - Stop: `python3 deployment/stream-processing/oneclick_dc_deployment.py stop` or `stop vst` -- run directly - Full cycle (build + deploy): run build first, then deploy sequentially -- no confirmation needed ## build.sh Options - `./build.sh all` -- one-shot: toolchain → base → all modules + NVStreamer - `./build.sh module=sensor` -- plain build (compile only, no packaging) - `./build.sh package module=sensor,rtspserver` -- build + package into deployable archives - `./build.sh container module=sensor,rtspserver,recorder,livestream,replaystream,storage,streambridge,streamprocessing` -- build + package + create Docker containers for all modules - `./build.sh container module=streamprocessing push=1` -- build + push to registry - `./build.sh container tag=mytag module=sensor` -- custom image tag - `./build.sh container nvstreamer` -- build NVStreamer container - `./build.sh container ingress` -- build ingress container - `./build.sh toolchain` -- build the compile toolchain only (auto-invoked otherwise); `arch=arm64` for aarch64 - `./build.sh toolchain push=1 toolchain-image=<registry>/vios-build:<tag>` -- build + push toolchain (ask the user for the registry if not given; default tag would push to Docker Hub) - `./build.sh base-container [push=1 image-registry=<registry>]` -- build (and optionally push) the runtime base image only - `./build.sh container module=… no-cache` -- force rebuild from scratch (the way to force a toolchain/base rebuild — otherwise cached & skipped) - `./build.sh container module=… no-auto-deps` -- fail fast if toolchain/base missing (CI / pre-pulled) - `./build.sh clean` -- clean the current arch's build objects (`arch=arm64` for aarch64). Run only when switching module set or arch; a same-modules rebuild does not need it. Do NOT clean the other arch (it would pull that arch's toolchain image just to delete files). - `./build.sh debug module=sensor` -- debug build ## One-Click Deployment Script **Script:** `deployment/stream-processing/oneclick_dc_deployment.py` Deploys VIOS microservices via docker-compose. Non-interactive by default; smart defaults are applied automatically. Uses `<action> [target]` positional form or `--target <target>` flag form. Targets: `vst` (default; alias `vios` accepted, stream-processor at `deployment/stream-processing/docker-compose/`), `nvstreamer`, `all`. ``` python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --force # deploy VIOS (default target) python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --target nvstreamer --force # deploy NVStreamer only python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --target all --force # deploy VIOS + NVStreamer python3 deployment/stream-processing/oneclick_dc_deployment.py stop # stop all services python3 deployment/stream-processing/oneclick_dc_deployment.py stop vst # stop only VIOS python3 deployment/stream-processing/oneclick_dc_deployment.py stop nvstreamer # stop only NVStreamer python3 deployment/stream-processing/oneclick_dc_deployment.py stop --clean # stop and remove persistent data python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --fresh-start --force # clean start python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --pull-always --force # pull latest images python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --interactive # opt in to prompts ``` **Key paths (stream-processor / default):** - Compose files: `deployment/stream-processing/docker-compose/docker-compose.yaml` - Config: `deployment/stream-processing/docker-compose/configs/` - Compose env: `deployment/stream-processing/docker-compose/compose.env` - SDRC overlay: `deployment/stream-processing/docker-compose/sdrc/` (only active when `VST_USE_SDRC=true` + `COMPOSE_PROFILES=sdrc` in `compose.env`) - NVStreamer compose: `deployment/stream-processing/docker-compose/nvstreamer/` **Deployment mode** (SDRC vs direct) is an **adaptor-independent** toggle selected by the block at the top of `compose.env` (`VST_USE_SDRC`, `COMPOSE_PROFILES`, `NGINX_MODE`). **SDRC mode is now the default** — it adds `sdr-controller` + the init chain for header-routed multi-pod operation (also works single-pod). Direct mode (no SDR/Envoy, single-pod only) is the alternative; deploy it with `oneclick_dc_deployment.py deploy --no-sdrc`, which rewrites `compose.env` to `VST_USE_SDRC=false` / `NGINX_MODE=vst` / cleared `COMPOSE_PROFILES` / stream-processor on `:30001`. SDRC-vs-direct is orthogonal to the `VST_ADAPTOR` (`vst`/`mms`) choice — `vst-sdrc` is **not** an adaptor. **Access URLs (after deploy):** - VIOS UI: `http://<HOST_IP>:30888/vst/#/dashboard` **VIOS containers (direct mode):** `centralizedb`, `vst-ingress`, `sensor-ms`, `streamprocessing-ms-1` **Extra containers in SDRC mode:** `redis`, `sdr-controller`, `sdrc-init-dirs`, `sdrc-render-config` ## Debugging: Source changes require container rebuild Since VIOS runs in Docker, editing source files alone does NOT affect the running service. The full cycle is: 1. Edit source files 2. `./build.sh container module=<affected_modules>` -- rebuilds container image 3. `python3 deployment/stream-processing/oneclick_dc_deployment.py deploy --force` -- redeploys with new image 4. Check logs: `sudo docker compose -f docker-compose.yaml --env-file ./compose.env logs -f` (from `deployment/stream-processing/docker-compose/`) # Common Build Pitfalls 1. **Use `./build.sh`, not `make`** -- arch detection, Docker, and module flags won't be set correctly otherwise. 2. **Wrong arch prebuilts** -- `PREBUILT_DIR` is `prebuilts/$(arch)/`; wrong arch links silently against the wrong libs. 3. **Missing module define** -- features gated by a `CPPFLAGS` define silently no-op if `module=` is omitted. 4. **Kafka consumer depends on `notification_proto`** -- enforced in the Makefile; do not remove it. 5. **OpenTelemetry on aarch64/SBSA** -- `USE_OTEL=0`; OTEL headers are not available there. 6. **Multi-module plain build** -- `module=a,b` without `package` or `container` will error out. 7. **Source edits not visible at runtime** -- VIOS runs in Docker; must rebuild container and redeploy.