Updating the Runtime

Updating the Runtime

Each CDX runtime release replaces the complete cdx-runtime folder in your project. Your application, DBCs, presets and root build files stay in place.

Identify The Installed Runtime

The installed release-manifest.json, not an old ZIP or README example, identifies your runtime. From the project root, use the project-local executable:

1.\cdx-runtime\bin\cdx.exe --version
2.\cdx-runtime\bin\cdx.exe verify-release --runtime cdx-runtime
  • --version identifies the executable and supported formats.
  • verify-release reports the installed runtime version and checks its inventory.

Do not copy a new executable into an older runtime or disable verification to hide a mismatch.

Replace The Runtime

  1. Close running builds and terminals that use the old runtime.
  2. Check the new release’s compiler and API requirements. The new release’s revision history lists changes since your version, including migration notes.
  3. Open a new PowerShell terminal at the application root.
  4. Replace the archive path below with your downloaded cdx-runtime-<version>.zip. Run each command separately and stop if it fails:
 1$ErrorActionPreference = 'Stop'
 2$archive = 'C:\Downloads\cdx-runtime-<version>.zip'
 3$backup = Join-Path '.cdx' ('runtime-upgrade-' + [Guid]::NewGuid().ToString('N'))
 4Expand-Archive -LiteralPath $archive -DestinationPath $backup
 5& "$backup\cdx-runtime\bin\cdx.exe" verify-release --runtime "$backup\cdx-runtime"
 6if ($LASTEXITCODE -ne 0) { throw 'New runtime verification failed; installed runtime unchanged.' }
 7
 8Move-Item 'cdx-runtime' "$backup\previous-runtime"
 9Move-Item "$backup\cdx-runtime" 'cdx-runtime'
10foreach ($directory in @('build', 'ginmake-generated')) {
11    if (Test-Path -LiteralPath $directory) {
12        Move-Item $directory (Join-Path $backup "previous-$directory")
13    }
14}

These commands replace the complete runtime without merging versions. They preserve the old runtime and generated outputs, and move all old preset caches out of their active paths.

  1. Keep the printed/assigned $backup path until you have validated the upgrade. If you use custom output locations, move those generated directories aside too. Never move application sources or staged model sources.
  2. Select the compiler required by the new manifest. Repeat terminal setup and build, adapting this compiler path to your installation:
1$env:PATH = "C:\Tools\arm-gcc-15.3.rel2\bin;$env:PATH"
2.\cdx-runtime\setup-cdx.ps1
3cdx verify-release --runtime cdx-runtime
4cdx doctor --operation build
5cdx compile
6cdx verify-image --image build\cm4-release\MDL_FIRM.bin
7cdx doctor --operation deploy

compile regenerates IPC from the project’s configuration and DBCs. It builds already staged model C sources. MATLAB regeneration and device programming are separate operations.

  1. Before uploading, run cdx embed, or reload the model in Dash Design, to replace the deployment copy with the newly built package. Do not upload an old prepared setup after upgrading.

Keep application files outside cdx-runtime. Do not copy the starter over an existing application. If you only need to reset the compiler/cache, see cache reset for cdx configure --fresh.

Script Migration

cdx build includes incremental MATLAB generation. Scripts that only rebuild staged C sources without MATLAB must use cdx compile. See Migration and compatibility aliases.