Skip to content

SDK Upgrade

Upgrade Process

When a project created with one version of an SDK is to be used with a newer version of the SDK, it may need to be upgraded to be compatible, as the SDK may have renamed components, changed how components are configured, etc. The following four operations must be performed:

  • The project description file (.slcp) list of components must be updated.
  • The project must be re-generated to update the autogen directory and IDE project files.
  • The configuration files must be transformed and merged with the new configuration files from the SDK.
  • The configuration files owned by Advanced Configurators (AC) must be transformed in an AC-specific way. See the page on Component Configuration for details about Advanced Configurators.

The user shall not need to upgrade to every intermediate SDK to get to the newest SDK version. This means that newer SDKs must carry rules to upgrade from all older versions, and these must be applied in a way that is robust in scenarios where a component or configuration option may have been renamed multiple times.

The following process may be used to implement SDK upgrades:

  • Load configuration state from the project configuration directory, extract configuration names and values, and check whether they deviate from the default configuration values.
  • Inspect SDK metadata to find all registered upgrade rules and their corresponding versions. For every found version greater than the SDK version referenced in the project and lower than or equal to the version of the target SDK, do the following, in order from lowest to highest version number:
    • Run component upgrades, passing a read-only copy of the component and configuration state. Component state transformations are returned.
    • Run configuration upgrades, passing a read-only copy of the component and configuration state. Additional configuration is returned, where all configuration options written by the upgrade are also considered deviations from the default values.
    • Apply component state transformations and configuration state changes to the working state.
  • Generate the project using the updated component state. Merge the configuration state according to the rules for configuration merge. If the project fails to generate, prompt the user to resolve the issues.
  • Invoke the upgrade entry point of each Advanced Configurator, passing the updated project. If the upgrade fails, prompt the user to resolve the issues.

The destination for the upgrade should be a temporary directory until the entire process has completed successfully, to allow the user to abort the upgrade if it turns out it cannot be completed successfully.

Comparing SDK Versions

When comparing two SDK version numbers, the release ordering principles of the Semantic Versioning 2.0 specification (semver.org) are adopted.

For extended compatibility with other versioning schemes, the normal version number as defined by SemVer is also allowed to contain ASCII alphanumerics, rather than just numeric identifiers.

Upgrade Manifest

The SDK .slcs/.slce file may reference one or more upgrade manifests (.slcu). See the file format description for upgrade manifests for more information.

Back to top