CDX CLI Guide
CDX command-line workflows
Use bin/cdx.exe to generate, build, package and deploy models. This bundled,
self-contained Windows x64 C#/.NET 10 executable needs no PowerShell, .NET SDK or
separately installed .NET runtime. Only maintainers need the SDK to build it.
Keep the executable, libraries, MATLAB helpers and release manifest together.
This guide is a reference. To build and run a first application, start with the Quickstart.
Run as cdx
Add cdx-runtime\bin to PATH to run cdx without its directory or .exe.
Do not move cdx-runtime\bin\cdx.exe out of the runtime or add . to PATH.
These optional alternatives need no administrator rights. Explicit paths work without setup.
Current terminal only (recommended)
Use a setup helper for the current terminal and its child programs only. Other terminals, future sessions and your saved environment are unchanged.
From the application root in PowerShell:
Or Command Prompt (cmd.exe):
Both helpers locate the runtime relative to themselves, check bin\cdx.exe and
prepend its absolute directory to PATH, supporting project paths with spaces.
Incomplete runtimes fail without changing PATH. The current directory stays
unchanged: run project commands from the application root or use --project.
Run the PowerShell helper directly in your cdx terminal. Dot-sourcing is not
required.
A separate powershell -File or pwsh -File process cannot change its parent.
From another batch file, use call cdx-runtime\setup-cdx.cmd to return after setup.
The PowerShell helper supports Windows PowerShell 5.1 and PowerShell 7+. Approved releases carry a verified Authenticode signature. Your organisation’s execution policy may require GEMS publisher approval. Neither helper changes policy. If scripts are prohibited, use CMD or consult your administrator, not a policy bypass.
Close the terminal to discard changes. Use separate terminals for projects with different runtime versions.
Persistent user PATH
Add a runtime at a stable location to your user PATH for future sessions.
- Search Start for Edit environment variables for your account.
- Under User variables, edit Path (create it if absent).
- Add the absolute
bindirectory, for exampleC:\work\my-model\cdx-runtime\bin, without quotation marks or the executable name. - Confirm the dialogs and open a new terminal. Restart VS Code for its integrated terminal.
- Check
Get-Command cdx(PowerShell) orwhere.exe cdx(Command Prompt), thencdx --version.
The system PATH is unchanged. Update/remove entries when runtimes move or are
deleted. Earlier entries can select the wrong version. For project-specific
runtimes, prefer the current-terminal helper or a shortcut.
Project-specific CDX terminal shortcuts
A desktop shortcut opens a shell in your project with its runtime on PATH,
without changing your saved environment.
-
Right-click the desktop and choose New > Shortcut.
-
Use this target, replacing
C:\work\my-modelwith your application’s absolute path and keeping the quotation marks:1%SystemRoot%\System32\cmd.exe /d /s /k ""C:\work\my-model\cdx-runtime\setup-cdx.cmd"" -
Name it CDX terminal - my-model.
-
In Properties, set Start in to the application root, for example
C:\work\my-model. -
Open it and run
where.exe cdx,cdx --versionandcdx compile.
For Windows PowerShell, use the same steps with:
1%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoLogo -NoProfile -NoExit -File "C:\work\my-model\cdx-runtime\setup-cdx.ps1"For PowerShell 7, substitute the quoted absolute path to pwsh.exe. -NoExit
keeps the prepared shell open. Do not add an execution-policy bypass.
Current-terminal scope and policy rules also apply here. CMD needs no PowerShell. Update Target and Start in after moving the project. Double-clicking a setup script alone does not keep its terminal open.
No PATH setup
Run the executable by path instead. From the application root, either shell accepts:
1cdx-runtime\bin\cdx compileInside cdx-runtime\bin, Command Prompt accepts cdx. PowerShell requires .\cdx
because it does not search the current directory. Both shells allow omitting .exe.
For an unexpected runtime, check Get-Command cdx -All or where.exe cdx.
Use the project-local path or a fresh project-specific terminal. CLI/runtime
matching applies regardless of PATH setup.
Discover commands
Use help for commands/options and doctor for prerequisites. From your project:
1cdx-runtime\bin\cdx.exe --help
2cdx-runtime\bin\cdx.exe help build
3cdx-runtime\bin\cdx.exe --version
4cdx-runtime\bin\cdx.exe doctor --operation build
5cdx-runtime\bin\cdx.exe doctor --operation package --jsonHelp and version need neither a project nor build/deployment tools. doctor
checks executables and deployment capabilities,
including the unattended-upload member when selecting a device. It never installs
or repairs software. Licence usability, the specific package/setup and physical
upload remain unverified.
| Operation | Required tools |
|---|---|
| Package finalized image | None external. |
| Package ELF | ARM objcopy. |
| Compile | CMake, Ninja, ARM GNU compiler targeting the required CM4 ABI, licensed Ginmake. |
| Generate model | Compilation tools plus MATLAB, Simulink Coder and Embedded Coder. |
Project configuration
Copy the example’s cdx-project.json into your application root to select runtime,
preset and paths. Paths are relative to that file, not the terminal.
The CLI searches the current directory and parents. --project selects a
configuration file or project directory.
1{
2 "format": 1,
3 "runtime": "cdx-runtime",
4 "preset": "cm4-release",
5 "generated_sources": "model-generated",
6 "model": "model/hello.slx",
7 "initialization": "model/initialize.m",
8 "setup": "templates/model.cd6.gdd",
9 "deployment_setup": "output/model.cd6.gdd"
10}Add model/initialization and setup/output paths only for operations you use. Create the deployment output directory explicitly.
The project-owned initialization script runs in MATLAB’s base workspace before
loading the model. It must establish paths, custom signal classes, dictionaries
and workspace values without silently saving/discarding user changes. Generation
uses the project root as MATLAB’s current folder, so build paths from the script’s
location. Simulink Projects provides a complete
script, including cdx.inputs for CDX fast-I/O signals.
Shared tool paths go in the project file:
1{
2 "tools": {
3 "cmake": "%CDX_TOOLS%\\cmake\\bin\\cmake.exe",
4 "ginmake": "%CDX_TOOLS%\\ginmake\\ginmake.exe",
5 "matlab": "%MATLAB_ROOT%\\bin\\matlab.exe"
6 }
7}All project paths accept Windows %VAR% references, expanded when used.
Undefined variables cause configuration errors. Define variables per machine
to share paths.
Machine-local executable paths belong in ignored cdx-project.local.json:
1{
2 "tools": {
3 "matlab": "C:/Program Files/MATLAB/R2023b/bin/matlab.exe",
4 "ginmake": "C:/Program Files/GEMS/Ginmake/ginmake.exe"
5 }
6}CLI tool keys are cmake, ginmake, matlab and objcopy. Both files treat null,
empty and whitespace-only values as omitted, including Dash Design fields.
| Setting | Behaviour |
|---|---|
| Omitted shared value | CLI default. |
| Empty local value | Shared setting unchanged. |
| Non-empty local value | Override that shared tools key only. |
CMake controls compiler, target, DBCs, package metadata and outputs. Configure exports
.cdx/<preset>.json workflow metadata: do not edit it. The CLI accepts Dash Design’s
cli, compiler and ninja tool fields, but CMake presets/cache still select
compiler and Ninja.
Project operations require a CLI matching the selected runtime’s version and
bundled executable bytes. Another executable on PATH cannot bypass this check.
Individual and complete workflows
Run individual stages or join them with + in execution order. build combines
incremental MATLAB generation with compilation and packaging.
flowchart LR
subgraph build["build = incremental matlab + compile"]
direction LR
matlab["matlab<br/>(build skips when up to date)"] -->|"staged C sources"| compile["compile"]
end
compile -->|".cdxmodel package + MDL_FIRM.bin"| embed["embed"]
embed -->|"prepared deployment .cd6.gdd"| deploy["deploy"]
deploy --> programmed["programmed CD6"]
implicit["compile+deploy implicitly embeds"] -.-> embed
1cdx-runtime\bin\cdx.exe configure
2cdx-runtime\bin\cdx.exe ipc
3cdx-runtime\bin\cdx.exe codegen
4cdx-runtime\bin\cdx.exe stage
5cdx-runtime\bin\cdx.exe matlab
6cdx-runtime\bin\cdx.exe compile
7cdx-runtime\bin\cdx.exe matlab+compile
8cdx-runtime\bin\cdx.exe build
9cdx-runtime\bin\cdx.exe embed
10cdx-runtime\bin\cdx.exe compile+embed
11cdx-runtime\bin\cdx.exe embed+deploy --serial 12345
12cdx-runtime\bin\cdx.exe compile+deploy --serial 12345
13cdx-runtime\bin\cdx.exe matlab+compile+deploy --serial 12345
14cdx-runtime\bin\cdx.exe build+deploy --serial 12345
15cdx-runtime\bin\cdx.exe devices --json
16cdx-runtime\bin\cdx.exe deploy
17cdx-runtime\bin\cdx.exe deploy --serial 12345| Stage | Work performed |
|---|---|
matlab |
Configure CMake, generate IPC and MATLAB/Simulink code, stage sources. No compilation or upload. |
build |
Refresh IPC/workspaces, generate/stage MATLAB code if stale, compile/package incrementally. |
compile |
CMake configure/build/package of staged sources, regenerating IPC as needed. No MATLAB or upload. |
embed |
Embed package in source setup, save separate deployment copy. No hardware access. |
deploy |
Upload prepared setup only. No generation, compilation or implicit embedding. |
The CLI validates the entire sequence and options before work, stops on first failure and passes only successful outputs onward.
| Pipeline | Behaviour |
|---|---|
compile+deploy |
Compile, implicitly embed, upload. |
matlab+compile+deploy, build+deploy |
Full generation-to-upload sequence. |
matlab+compile+embed+deploy |
Explicit full sequence. |
compile+embed |
Compile and prepare without uploading. |
embed+deploy |
Prepare with existing package, then upload. |
Migration and compatibility aliases
Breaking change: cdx build includes incremental MATLAB generation. Change
staged-C-only rebuild scripts to cdx compile. Explicit matlab always attempts
generation, unlike build, so matlab+compile is not an exact alias.
| Alias | Equivalent pipeline |
|---|---|
full-build |
build |
full-build-embed |
build+embed |
full-build-deploy, build-deploy |
build+deploy |
embed-setup |
embed |
Prefer stage names/pipelines in new scripts. Hyphenated aliases still work but are
hidden from top-level help. Use cdx help <alias>.
Incremental MATLAB generation
build and aliases skip MATLAB and staging only when saved input/output content
hashes match, not timestamps. Compilation uses CMake/Ninja’s incremental build.
First, CMake configures and updates IPC/workspaces. CMake/Ginmake regenerates
missing/stale outputs from configuration, DBC and declared INPUTS dependencies.
The MATLAB check includes refreshed contents at default/custom workspace locations
exported by the CMake helper.
Successful CLI matlab or stale build generation/staging records hashes in
.cdx/matlab-build.json. The conservative check covers:
- Project files: model, initialization scripts, dictionaries, parameter data, project/local configuration and generated workspaces.
- Runtime distribution, preset and all exported IPC outputs.
- MATLAB dependency-analysis results, active referenced models and open dictionaries recorded before generation.
- Staging manifest, generated files and complete staged source tree.
The project scan excludes .git, .vs, .cdx, build, the selected CMake binary
directory, staged sources and configured deployment output (its directory for
filename templates). Runtime checks are separate. Unrelated project changes can
trigger generation: keep other build artifacts outside the source tree.
Declare external/dynamically loaded data, undiscoverable dependencies and inputs
under excluded paths with codegen_inputs:
1"codegen_inputs": ["../shared-models", "../calibration/parameters.mat"]Paths can be absolute or project-configuration-relative. Directory scans are recursive and detect additions/removals. Missing declared inputs fail. Do not list generation outputs or changing build/log directories.
The first post-migration build regenerates: staged C alone cannot prove model freshness. Missing/modified/extra staged files, changed presets or unavailable dependency metadata also prevent skipping. Failed generation invalidates the old fingerprint. Inputs changing during generation cause an error, not a fresh fingerprint.
Use cdx matlab or cdx matlab+compile after MATLAB/toolbox or non-file dependency
changes, such as environment variables, network data or callbacks. File checks
cannot reliably infer these. MATLAB’s slbuild may reuse its cache.
Current-session cdx.workflow requests generation without establishing a CLI
fingerprint.
--skip-matlab removes generation/staging only, leaving compilation and later
stages. It accepts build/full-build and combinations containing both matlab
and compile, including aliases, but not plain matlab, compile or deploy.
For example, build-deploy --skip-matlab equals compile+deploy. Reusing staged
sources does not verify model freshness.
codegen generates IPC before matlab -batch, without staging failed/partial
generation. stage replaces the complete owned source tree, removing obsolete
sources from compilation. Project operations take an exclusive project lock.
CMake’s Ginmake rule locks the generated directory exclusively.
Select presets with --preset. Direct CMake and VS Code builds remain supported.
Packaging is a tracked link byproduct, regenerated if missing. DBC, version,
configuration and tool changes invalidate corresponding outputs.
Deploying to a display
Use deploy or pipelines ending in it to upload to a selected display.
Deployment compatibility and safety rules
apply throughout.
| Selection | Behaviour |
|---|---|
No --serial |
First USB display in Dash Design’s device-list order, even with several attached. Fail if none. No network fallback. |
Explicit --serial |
Must match exactly one device. Required for network displays. No USB fallback. |
Diagnostics and results report the selected serial. Automatic USB selection
requires IsUsbAt. devices --json reports is_usb as true/false when supported,
or null on older COM servers. VID/PID identifies the display model, not transport.
For unknown transport, update Dash Design or supply --serial, which older servers
still support. Immediately before upload, connection type is rechecked. Disappearing
or ambiguous devices fail rather than switch transport.
Negative native progress means preparation/waiting, not a negative percentage. Stderr progress prints only when its displayed value changes.
Uploads default to a 300-second timeout. --timeout SECONDS accepts positive values up to
86400. Timeout/cancellation requests job cancellation and briefly waits for
confirmation. An unconfirmed stop reports unknown device state: stopping the client
may not stop programming. Synchronous COM calls are not forcibly interrupted.
Success does not verify compatibility or physical model startup/IPC. With the
mismatch override, results include display_mismatch_allowed and
model_startup_verified: false.
Dash Design deployment compatibility
Run cdx doctor --operation deploy before preparing or uploading setups.
The CLI also enforces preflight before embedding, uploading and starting builds
in combined build/embed/deploy workflows.
The registered server must expose the read-only
SupportsCdxModelImageDescriptor(version) query and support every image descriptor
listed by cdx --version. Servers lacking the query fail explicitly, without
guessing capabilities from application version strings. Device enumeration remains
available.
Preflight confirms server format support only, not package integrity, setup/device
compatibility, display firmware or upload success. The query neither opens/modifies
setups nor imports packages or enumerates hardware. embed validates the actual
package when preparing a separate deployment copy.
To embed into Dash Design’s open editable setup, use --current-setup instead of
--setup:
1cdx build+embed+deploy --current-setup --dash-process 9876 --serial 12345This includes unsaved edits and writes a separate copy to deployment_setup.
The open setup remains modified, without saving or renaming. --dash-process
selects the running Dash Design instance with that PID through its
process-specific COM Running Object Table endpoint. CDX Project Tools supplies
its own PID automatically for embedding, deployment and device enumeration.
CDX reports the selected PID and executable on stderr and never falls back to
another instance if that endpoint is unavailable. Keep that instance open and
run both processes at the same elevation level.
Without --dash-process, standalone commands retain registered COM activation;
with multiple open instances this does not guarantee which setup is selected.
Registration alone does not select an instance. Project Tools neither activates
the registered executable nor changes registration to select its instance.
Both CDX and Dash Design must support process selection; older runtimes reject
the new option.
Deployment requires IDashDevice.UploadSetupUnattended. Servers lacking it fail
before upload, even with an explicit serial. There is no interactive fallback.
Interactive automation clients can still use UploadSetup, but cdx does not.
Unattended upload rejects display-type mismatches, nonempty logs and excessive RAM requirements with job errors, without dialogs or programming. Preserve/download logs and resolve compatibility issues in Dash Design before retrying. Firmware updates, raw setups, log erasure and implicit setup downloads are disabled. Unsaved interactive setup edits cause failure rather than discard.
For a deliberate bench transfer test:
1cdx deploy --serial 12345 --allow-display-mismatch--allow-display-mismatch works on deploy and pipelines ending in deploy,
including aliases. It requires an explicit, unambiguous --serial and disables
automatic USB selection. The initial UploadSetupUnattended contract includes
allowDisplayMismatch, without a separate capability property.
The override accepts only mismatches the interactive uploader would let you confirm. Hard device restrictions and log, RAM, firmware and cancellation rules remain unchanged. CLI diagnostics and the native job warn that the setup may not function. See upload results and cancellation.
Automatic output filenames
All --output options and deployment_setup accept date/build-number filename
templates. Create the output directory before these examples:
1cdx matlab+compile+deploy --output "output\model-{utc:yyyy-MM-dd_HHmmss}-{build}.cd6.gdd"
2cdx matlab+compile+embed --output "output\model-{utc:yyyyMMdd}-{build}.gdd" --build-number 42
3cdx package --image firmware.bin --name "My model" --output "output\model-{y2k}.cdxmodel"
4cdx finalize-image --image raw.bin --output "output\firmware-{utc:yyyyMMdd_HHmmss}.bin"For device selection, see Deploying to a display.
build+deploy and aliases full-build-deploy/build-deploy run the same sequence.
| Token | Meaning |
|---|---|
{utc:yyyy-MM-dd} |
UTC date, for example 2026-03-15. |
{utc:yyyyMMdd_HHmmss} |
UTC date and 24-hour time without Windows-invalid separators. |
{utc:FORMAT} |
Filename-safe .NET date/time format, invariant culture. |
{y2k} |
Whole UTC seconds since 2000-01-01T00:00:00Z. |
{unix} |
Whole UTC seconds since 1970-01-01T00:00:00Z. |
{build} |
Explicit --build-number VALUE, otherwise next project counter value. |
{{ and }} |
Literal braces. |
- Tokens are case-sensitive and allowed only in filenames, not directories.
- Date formats cannot contain braces. Avoid
/,\,:and ordinary ISO times with colons: these are unsuitable for Windows filenames. - Quote templates in PowerShell or Command Prompt. Escape literal directory braces.
- Parent directories must exist.
Unknown tokens, unbalanced braces and invalid Windows filenames fail without silent sanitization.
Each command captures UTC once for all tokens. This dates naming, not necessarily
an existing image/package’s compilation. Current-session MATLAB’s separate embed
command captures its own start time. Second-resolution timestamps are not guaranteed
unique.
Explicit and automatic build numbers
--build-number accepts filename-safe strings, including leading zeroes or CI
identifiers such as pipeline-0042, without a project or counter advancement.
Otherwise, the first {build} reserves a number from .cdx/naming/build-number.json,
starting at 1. Repeated tokens reuse it. All project presets/output commands share
the counter. Date-only/literal names consume none.
Leaf commands discover projects in the current directory/parents or use
--project FILE|DIR. Without a project, {build} requires --build-number.
Reservation needs no runtime/build tools, uses an exclusive lock and persists
atomically. Lock contention, invalid state and exhaustion fail without resetting
or reusing numbers.
Failed naming/build/preparation can leave gaps: this is not a successful-build
count. Deleting state resets it. Project copies do not share a global sequence.
For CI/cross-machine uniqueness, pass the build system ID with --build-number.
Collisions and later deployment
Expanded-token names refuse existing destinations unless the output-producing
command uses --overwrite. The final atomic write also protects against files
appearing after the initial check.
Literal filenames retain existing replacement behaviour. Escaped braces alone
do not make names automatic. --overwrite cannot replace protected inputs,
including setup templates and packages.
For generated deployment names by default, set:
1"deployment_setup": "output\\model-{utc:yyyy-MM-dd_HHmmss}-{build}.cd6.gdd"Project embed and setup-preparing pipelines record successful paths per preset
under .cdx/naming. With templated or unset deployment_setup, later deploy
reuses that path, not a fresh timestamp:
No prior preparation, changed templates or missing prepared files cause errors.
Failed preparation retains the previous record. Literal deployment_setup selects
that file. deploy --setup ACTUAL_FILE explicitly selects another prepared file.
Input options such as --setup are not templates. Combined build/deploy passes
the newly prepared path directly.
Templates change names only, not package metadata, firmware identity or CMake
ELF/package basenames. package --elf retains its CMake/options-defined basename
and rejects --output.
Similar tools and alternatives
Generate names upstream and pass filename-safe --build-number values to avoid
duplicate counters.
Azure Pipelines run numbers
combine dates and build IDs/revisions.
CMake timestamps
and MSBuild property functions
also generate names. CDX uses braces, not $()/%, to avoid Windows shell expansion.
Prefer CI’s existing build ID. A Git description
can trace sources better than timestamps alone.
MATLAB, without starting another MATLAB
Use cdx.workflow for current-session generation/builds or cdx.cli for CLI
commands/flags. Add the runtime’s matlab directory to MATLAB’s path:
1addpath(fullfile(projectRoot, 'cdx-runtime', 'matlab'));
2config = fullfile(projectRoot, 'cdx-project.json');
3cdx.cli('help', config, 'build');
4cdx.cli('doctor', config, '--operation', 'codegen');
5cdx.codegen(config);
6cdx.cli('stage', config);
7cdx.cli('compile', config);
8cdx.workflow('full-build', config);
9cdx.workflow('full-build-embed', config);
10cdx.workflow('full-build-deploy', config); % First USB display.
11cdx.workflow('full-build-deploy', config, 'Serial', '12345');
12cdx.workflow('full-build-embed', config, ...
13 'Output', 'output\model-{utc:yyyyMMdd}-{build}.gdd', 'BuildNumber', '0042');cdx.workflow accepts full-build, full-build-embed and full-build-deploy with
MATLAB name/value options. It compiles after current-session generation, without
recursive code generation, CLI pipeline parsing or --skip-matlab.
cdx.cli forwards command names and flags unchanged:
1cdx.cli('compile+embed', config);
2cdx.cli('build+deploy', config, '--skip-matlab', '--serial', '12345');
3cdx.cli('matlab+compile', config); % Launches a separate matlab -batch process.Pipelines containing matlab launch batch MATLAB unless --skip-matlab removes
generation. See incremental generation.
Current-session generation uses the explicit model and active referenced-model
build information, including shared utilities, sources, headers and include layout.
It excludes ert_main.c: the runtime supplies the entry point.
Generation restores paths, directory and temporary code-generation settings. It rejects unsaved models/dictionaries without saving/discarding them. Newly loaded models stay open and workspace initialization remains. R2023b compatibility and real generation require release validation in an installed licensed environment.
Setup-producing workflows pass these options only to embed and deploy its
returned path:
| Option | Value |
|---|---|
Output |
Output path. |
BuildNumber |
String. |
Overwrite |
Logical, default false. |
full-build rejects these options, retaining CMake’s package naming.
For the bench-only mismatch override,
full-build-deploy accepts 'AllowDisplayMismatch', true with 'Serial', '12345'.
Other workflows reject it before building. Individual uploads can use
cdx.cli('deploy', config, '--serial', '12345', '--allow-display-mismatch').
Consume the staged inventory, not an assumed flat directory:
1include("${CMAKE_CURRENT_SOURCE_DIR}/model-generated/cdx-generated.cmake")
2target_sources(your_target PRIVATE ${CDX_MODEL_SOURCES})
3target_include_directories(your_target PRIVATE ${CDX_MODEL_INCLUDE_DIRS})The project-template example handles this automatically, with legacy flat-source fallback until its first staged build.
Clean build outputs or reset the CMake cache
Use clean for build outputs or configure --fresh for the selected preset’s
CMake cache. Neither replaces the runtime.
For replacement, follow the verified upgrade and backup sequence
using cdx-runtime-<version>.zip for the downloaded version. The installed manifest
and verify-release result identify the active runtime, not an old archive filename.
From the application root, with the runtime on PATH:
clean defaults to --category build, running the selected preset’s CMake clean
target. It removes tracked outputs but keeps CMakeCache.txt and the generated
build system, without MATLAB or hardware access. Select another preset with
--preset cm4-debug.
To discard cached compiler/toolchain settings:
configure --fresh requires CMake 3.24 or newer. CMake’s --fresh removes the
selected preset’s CMakeCache.txt and CMakeFiles, then reconfigures and regenerates
CDX metadata. It leaves other presets, staged sources and application/runtime files
untouched, without cleaning outputs or removing the whole build directory.
Cache-only settings are lost. Put compiler/toolchain settings in
CMakeUserPresets.json or project presets first. Normal configure retains cached
settings.
Reset only Debug’s cache:
1cdx configure --fresh --preset cm4-debugExplicit categories need no terminal setup:
1cdx-runtime\bin\cdx.exe clean --category staged
2cdx-runtime\bin\cdx.exe clean --category matlab
3cdx-runtime\bin\cdx.exe clean --category buildStaged/MATLAB outputs require matching .cdx-owned.json markers. Unmarked
directories are never automatically adopted/deleted. Review and move legacy
outputs aside before first managed staging. No category recursively deletes the
project, runtime, model, dictionary or user data.
Leaf operations
Leaf operations need no project or enclosing CMake/MATLAB workflow. Explicit paths are relative to the current working directory.
1cdx finalize-image --image raw.bin --build-hash MODEL_IPC_HASH.bin --output MDL_FIRM.bin
2cdx verify-image --image MDL_FIRM.bin
3cdx package --elf model.elf --objcopy arm-none-eabi-objcopy --options model-package.json
4cdx package --image MDL_FIRM.bin --output model.cdxmodel --name "My Model" --rx model-output.dbc --tx model-input.dbc
5cdx verify-release --runtime cdx-runtime
6cdx embed --setup source.cd6.gdd --package model.cdxmodel --output output.cd6.gdd
7cdx deploy --setup output.cd6.gdd --serial 12345Repeat --rx/--tx to preserve DBC repeats/directions. --protected produces a
protected package. Producer validation preserves exact-byte hashes and binary
contracts. It does not replace Dash Design’s DBC parsing/channel-binding validation.
| Operation | Write behaviour |
|---|---|
finalize-image |
Default: replace input after validation. |
verify-image |
Never writes. |
| ELF conversion | Stages all outputs before publication. |
Failed validation never replaces a valid image/package.
CMake’s leaf generate-ipc arguments --ginmake, --config,
--generated-directory and --working-directory describe its existing rule,
not another project configuration.
For verify-release --skip-manifest-hashes and missing/malformed manifests, see
Modified runtime verification. Inventory hashes
detect modification, not publisher authenticity.
Results and exit codes
--json emits one JSON result on stdout. Progress, child-process output, warnings and
errors go to stderr. Failures return no success-shaped JSON.
Device results contain devices entries with serial, name, description,
usb_vid and usb_pid.
| Exit | Meaning |
|---|---|
| 0 | Completed. Inspect doctor/unverified validation fields where applicable. |
| 2 | Invalid command, arguments or JSON configuration |
| 3 | Validation, configuration, I/O, missing tool or COM failure |
| 4 | Child process returned a nonzero exit code |
| 5 | Upload timeout |
| 6 | Cancellation |
Project and build reference
Use this reference for custom builds and optional features. The quickstart covers example-to-hardware workflows.
Keep the runtime intact, including licence notices.
Release versions
CLI, runtime, public API and package/templates share one release version, identified
by the ZIP filename, cdx --version and release-manifest.json’s version.
| Component | Meaning |
|---|---|
| Major | Incompatible API changes. |
| Minor | Backward-compatible functionality. |
| Patch | Fixes. |
Manifest schema and IPC ABI numbers describe formats/compatibility, not releases.
The model’s application-owned REV_VERSION is independent.
Tool installation alternatives
cdx-runtime\install-tools.ps1 (or install-tools.cmd) checks tools and offers to
install the supported ARM compiler beside older versions. See
Install Tools Script.
Install CMake and Ninja with Windows Package Manager:
If the ARM compiler is absent from PATH, configure its location per preset before
cdx compile:
Substitute your compiler’s bin directory. CMake caches it per preset: repeat for
cm4-debug or after deleting the build directory.
Check & "C:\Tools\arm-gcc-15.3.rel2\bin\arm-none-eabi-gcc.exe" --version.
doctor --operation build checks objcopy on PATH or in local tool overrides,
not this CMake setting.
In VS Code, install Microsoft’s C/C++ and CMake Tools extensions, open the application
folder, select cm4-release or cm4-debug and build. Set CDX_RT_TOOLCHAIN_BIN
locally if needed. Application developers need no documentation tools.
Application build helpers
add_subdirectory(cdx-runtime) supplies the prebuilt library and two build helpers.
Your application owns its executable/sources. CMAKE_BUILD_TYPE selects the
included Release or Debug archive.
After declaring the executable and include directories:
1CDX_RT_configure_model(${PROJECT_NAME}
2 PACKAGE_NAME my-model
3 RX_DBC ipc/dash-receives.dbc
4 TX_DBC ipc/dash-transmits.dbc)This supplies image descriptor, linker script, libraries and packaging. DBC paths are project-relative and use dash directions.
| Option | Meaning |
|---|---|
RX_DBC |
Model outputs, multiple files allowed. |
TX_DBC |
Model inputs, multiple files allowed. |
PACKAGE_NAME |
Defaults to executable target name. |
NAME |
Optional displayed model name. |
EPK_HEADER |
Overrides default ipc_model_epk.h. |
Omit both DBC keywords for no-DBC models. For automatic model-ipc.json5.in
generation, also call:
Keep Ginmake configuration consistent with those DBCs. CONFIG accepts another
.in template or plain JSON5. Plain configurations run from the project root,
so relative paths also work in manual Ginmake calls. INPUTS adds dependencies.
Set REV_NAME and REV_VERSION in application-owned main/version.h, independent
of dash firmware. The echo demonstrates optional calibration/A2L generation.
If running Ginmake separately, omit the helper and add generated sources/include
directory to the executable yourself.
The packaging helper runs bin/cdx.exe package --elf: objcopy, image
validation/finalization and packaging, with ELF-derived output paths. CMake supplies
JSON options, so clients need not repeat three commands/intermediate filenames.
Manual calls require --elf, plus --objcopy if the tool is not on PATH, and
generated --options <target>-package.json for DBC-based models. No-DBC models with objcopy
on PATH need only --elf.
Optional <target>-ipc generates IPC/workspaces separately. For plain Ginmake
configurations, WORKSPACE_DIR declares a nondefault workspace directory. Keep it
consistent with out_dir_workspace.
Runtime I/O constraints
The runtime does not supply POSIX file/console I/O. Its image includes explicit newlib hooks for file, console and process operations:
_close,_lseek,_read,_write,_fstat,_getpidand_killreturn-1._isattyreturns0(not a terminal).- All report
ENOSYS, even for zero-length I/O, without accessing caller buffers.
The linker script separates immutable image segments from writable data/shared memory without moving firmware addresses. This avoids syscall/RWX linker warnings without suppression flags or hardware MPU changes.
Client header
CDX_USER_HEADER injects your types into every public cdx_*.h, before normal
includes and outside extern "C". Disabled by default, it is unnecessary when
building the runtime archive.
Keep main/cdx_user.h outside the replaceable runtime and enable it for application
targets only:
1target_include_directories(${PROJECT_NAME} PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/main")
2target_compile_definitions(${PROJECT_NAME} PRIVATE CDX_USER_HEADER="cdx_user.h")Use guard CDX_USER_H_INCLUDED, checked even through nested CDX headers:
1#ifndef CDX_USER_H_INCLUDED
2#define CDX_USER_H_INCLUDED
3
4#include <stdint.h>
5
6typedef struct APP_SAMPLE_STRUCT
7{
8 uint32_t value;
9} APP_SAMPLE;
10
11#endif- Include the header’s own dependencies, not CDX headers whose declarations are unavailable at this point.
- Support every application language. Guard C++-only declarations with
#ifdef __cplusplus. - Apply the setting to every target needing the types, never the runtime library.
- Do not redefine CDX typedefs, change packing or alter public declarations: the prebuilt ABI is fixed.
An enabled but missing header fails compilation.
MSVC simulator DLL
Both examples build native Windows simulator DLLs from the same model sources and Ginmake-generated identity. Use a separate project build directory without the ARM toolchain:
1cmake -S . -B build\simulator -G "Visual Studio 17 2022" -A Win32 -DCDX_RT_BUILD_SIMULATOR=ON
2cmake --build build\simulator --config DebugUse the installed Visual Studio generator matching simulator architecture (Win32
or x64). In custom CMake projects, use add_library(target SHARED
...) instead of add_executable when CDX_RT_BUILD_SIMULATOR is enabled. Retain
normal configure/generation helpers.
Delivered simulator/ runtime sources produce DLL/PDB, not firmware or .cdxmodel.
MSVC, Windows SDK and Ginmake are required, not an ARM compiler for the DLL.
Rebuild the CD6 simulator display plugin with simulator-model support. Before
launching it or Dash Design, set CDX_MODEL_DLL to the absolute DLL path.
Use the matching CM4 image embedded in the setup. Only if absent, set
CDX_MODEL_IMAGE to finalized matching MDL_FIRM.bin. Build the image separately
and sequentially with the native build, using identical sources, version/EPK header
and DBCs. DLL EPK and DBC hash must match. Embedded image errors never fall back
to a sidecar. Independent dash setup identity is validated as on hardware.
Attach a native debugger and load the model PDB. Close simulation before DLL rebuilds.
Production controller, CAN3 transport, runtime and shared-memory/MU ownership protocol remain, servicing both endpoints on one foreground thread with the real steady clock. ARM/cache/interrupt/parallel-core faults and physical CAN timing cannot be reproduced. Calibration defaults/shared memory work, not durable persistence. Use only trusted DLLs: they execute inside the simulator process.
Modified runtime verification
Use unmodified GEMS runtimes normally. For intentional local changes, disable hash checks from the application root:
1cdx-runtime\bin\cdx.exe verify-release --runtime cdx-runtime --skip-manifest-hashes
2cmake --preset cm4-release -DCDX_RT_VERIFY_MANIFEST_HASHES=OFF| Setting | Hash checks controlled |
|---|---|
CMake cache option (default ON) |
Release/Debug archives for prebuilt CM4. Full inventory for native simulator and CM4 runtime source builds. |
| CLI switch | Full inventory during manual verification. |
Both warn when disabled. Compatibility, inventory syntax, applicable manifest/ABI,
library profile/inventory consistency and file-presence checks remain. Packaging’s
firmware CRC, descriptor and firmware-versus-DBC IPC hash checks are unaffected.
Restore ON or omit the CLI switch to re-enable hashes.
Without release-manifest.json, direct CMake and verify-release warn and skip
manifest checks regardless of these settings. Release version/ABI metadata and
compiler provenance become unavailable. Manual verification checks only both
archive paths. CM4 still requires both archives, GNU C/C++, CM4 target flags and
Release/Debug builds. Native MSVC source builds need no ARM archives without a
manifest, leaving file integrity unverified.
Malformed/incompatible manifests fail. Project workflows such as cdx compile
still require the manifest and matching bundled CLI.
Maintainer validation and release gates
Build/test the CLI independently of the embedded toolchain, then validate the signed release on real tools/hardware:
1dotnet build model-runtime\tools\cdx-cli\cdx.csproj -c Release
2dotnet test model-runtime\tools\cdx-cli\tests\cdx.tests.csproj -c Release --filter TestCategory!=Parity
3dotnet test model-runtime\tools\cdx-cli\tests\cdx.tests.csproj -c Release --filter TestCategory=Parity
4dotnet publish model-runtime\tools\cdx-cli\cdx.csproj -c Release -r win-x64 --self-contained true -o model-runtime\build\cdx-cliOnly parity tests need PowerShell, using signed legacy scripts as a temporary
oracle, never customer execution paths. Source-tree CMake sets CDX_RT_CLI to
the published executable. Tests compare managed binary constants with authoritative
C headers.
The exporter tests, publishes/signs the executable, verifies signed optional PowerShell setup/tool-installer helpers, copies .NET licence notices/MATLAB helpers, hashes signed bytes for inventory and verifies the staging tree and extracted ZIP. It requires the approved signing client and pinned SDK/CMSIS inputs, with no unsigned-release fallback. Development publishes are unsigned, not approved releases. Service bundled .NET with runtime updates.
Before certification, verify:
- Signed artifacts on restricted endpoints without PowerShell/separate .NET.
- Real batch/current-session MATLAB generation.
- Compatible Dash Design embedding/save behaviour.
- Physical deployment/model startup.
Development consumer migrations may exercise native builds earlier, but must record gates and keep unverified MATLAB/deployment operations gated. Replace the whole runtime, never overlay older versions. Mock tests do not certify hardware.