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.

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:

1.\cdx-runtime\setup-cdx.ps1
2Get-Command cdx
3cdx --version
4cdx compile

Or Command Prompt (cmd.exe):

1cdx-runtime\setup-cdx.cmd
2where.exe cdx
3cdx --version
4cdx compile

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.

  1. Search Start for Edit environment variables for your account.
  2. Under User variables, edit Path (create it if absent).
  3. Add the absolute bin directory, for example C:\work\my-model\cdx-runtime\bin, without quotation marks or the executable name.
  4. Confirm the dialogs and open a new terminal. Restart VS Code for its integrated terminal.
  5. Check Get-Command cdx (PowerShell) or where.exe cdx (Command Prompt), then cdx --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.

  1. Right-click the desktop and choose New > Shortcut.

  2. Use this target, replacing C:\work\my-model with 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""
  3. Name it CDX terminal - my-model.

  4. In Properties, set Start in to the application root, for example C:\work\my-model.

  5. Open it and run where.exe cdx, cdx --version and cdx 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 compile

Inside 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 --json

Help 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 12345

This 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:

1cdx matlab+compile+embed --preset cm4-release
2cdx deploy --preset cm4-release

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:

1cdx clean
2cdx compile

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:

1cdx configure --fresh
2cdx compile

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-debug

Explicit 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 build

Staged/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 12345

Repeat --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:

1winget install --id Kitware.CMake --exact
2winget install --id Ninja-build.Ninja --exact

If the ARM compiler is absent from PATH, configure its location per preset before cdx compile:

1cmake --preset cm4-release -DCDX_RT_TOOLCHAIN_BIN="C:/Tools/arm-gcc-15.3.rel2/bin"
2cdx 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:

1CDX_RT_generate_ipc(${PROJECT_NAME}
2  CAN PREFIX ipc_model_ INPUTS main/version.h)

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, _getpid and _kill return -1.
  • _isatty returns 0 (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 Debug

Use 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-cli

Only 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.