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 will need to be upgraded to be compatible, as the SDK may have renamed components, changed how components are configured, etc. This will also apply if a newer SDK Extension is installed replacing an older one even if the SDK version does not change. 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/Extension.
  • 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 or SDK Extension to get to the newest versions. This means that newer SDKs and newer SDK Extensions 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 outlines a general process tools should use to implement SDK and SDK Extension 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 along with installed SDK Extensions to find all registered upgrade rules and their corresponding versions (Individual SDK Extension upgrades will of course only check their subset of this metadata) For every found SDK Upgrade Rule version greater than the SDK version referenced in the project and lower than or equal to the version of the target SDK, and for every found SDK Extension Upgrade Rule version greater than the extension version referenced in the project and lower than or equal to the version of the chosen/latest (tool discretion) SDK Extension(s), 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 Versions

When comparing two SDK or SDK Extension 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 / SDK Extension .slce file may reference one or more upgrade manifests (.slcu). See the file format description for upgrade manifests for more information.

Individual SDK Extension Upgrades

An SDK Extension .slce may be updated independently of the SDK it is connected to. In other words, a user chooses to install a newer extension, either ignoring the version requirement (which is not a hard rule) or a newer extension still defines itself as compatible with the same SDK id/version. It is expected that a tool provide a means to run the upgrade flow on an extension-by-extension basis. The ability to run through the above flows for an extension only should not be gated on whether the parent SDK has had a version upgrade.

Back to top