MCUXpresso SDK Migration Guide#

Introduction#

Starting with version 25.12.00, the Arm GCC SDK package will have a new format. The new format will unify the CMake + Kconfig support between the SDK package and the GitHub repository. When users select Arm GCC in SDK Builder, the system will deliver a ZIP package that contains similar folders/files to that found in the GitHub SDK distribution. Additionally, VS Code integration provides access to Arm GCC Archive SDK packages. Starting with 25.12.00, VS Code will import the same Arm GCC Archive SDK package users download from the SDK Builder site.

Overview of Changes#

VS Code and GitHub workflows are based on CMake.
The CMakelists.txt and folder/file structure are now consistent for any Arm GCC SDK. (Archive packages and GitHub repositories)
Upcoming Change: Starting with version 25.12.00, Arm GCC SDK will be delivered through a ZIP package, ensuring unified CMake + Kconfig support across SDK builder distributions and GitHub workflows.

Folder Structure Changes#

Below are the differences in the SDK structure from older versions to the new SDK version 25.12.00 moving forward.

SDK Folder Structure Comparison#

Starting with SDK version 25.12.00, the overall organization of the SDK has been streamlined to improve modularity and maintainability for the Arm GCC SDK.
In previous releases, most source files and configuration files were grouped under the boards directory. In the new structure, the SDK introduces a centralized mcuxsdk folder that contains shared components, drivers, middleware, and examples. This change makes it easier to reuse code across multiple boards and projects. While some folders will translate directly to what was seen previously, there will also be new folders introduced to support the new CMake and Kconfig build system.

25.09.00 and Prior Releases	25.12.00 and Future Releases
📁 boards 📁 CMSIS 📂 components 📁 devices 📁 docs 📁 middleware 📁 rtos 📁tools	📁 .west 📁 manifests 📂 mcuxsdk ├── 📁 arch ├── 📁 cmake ├── 📁 components ├── 📁 devices ├── 📁 drivers ├── 📁 examples ├── 📁 middleware ├── 📁 rtos ├── 📁 scripts ├── 📁 share └── 📁 tool_data
For more details on how to use the new SDK structure, refer to Workspace Structure

Project Structure Changes#

The new SDK format introduces changes to how projects are organized and configured. In the new project structure:

Your application source files (e.g., hello_world.c) remain within the example folder, so you still have everything you need to build and modify your demo.
Board-specific files (like pin_mux.c, clock_config.c, and hardware initialization code) are no longer inside the same project folder. These are now located in shared directories under mcuxsdk further details in board specific files.
Build configuration files (CMakeLists.txt, Kconfig, example.yaml) are included in the example folder for easier project setup.

Looking at FRDM-MCXN947 as an example, we can see how a hello_world demo application is structured:

25.09.00 and Prior Releases	25.12.00 and Future Releases
📁 boards └─ 📁 frdmmcxn947 └─ 📁 demo_apps └─ 📁 hello_world └─ 📁 cm33_core0 ├─ 📁 armgcc │ └─ 📄 CMakeLists.txt ├─ 📄 app.c ├─ 📄 board.c ├─ 📄 board.h ├─ 📄 clock_config.c ├─ 📄 clock_config.h ├─ 📄 example_board_readme.md ├─ 📄 examples_shared_readme.md ├─ 📄 hardware_init.c ├─ 📄 hello_world.c ├─ 📄 mcux_config.c ├─ 📄 pin_mux.c ├─ 📄 pin_mux.h └─ 📄 readme.md	📁 mcuxsdk └─ 📁 examples └─ 📁 demo_apps └─ 📁 hello_world ├─ 📄 CMakeLists.txt ├─ 📄 example.yaml ├─ 📄 hello_world.c ├─ 📄 Kconfig └─ 📄 readme.md
For more details on how to build and run a project, refer to First Build

25.09.00 and Prior Releases

25.12.00 and Future Releases

📁 boards
└─ 📁 frdmmcxn947
└─ 📁 demo_apps
└─ 📁 hello_world
└─ 📁 cm33_core0
├─ 📁 armgcc
│ └─ 📄 CMakeLists.txt
├─ 📄 app.c
├─ 📄 board.c
├─ 📄 board.h
├─ 📄 clock_config.c
├─ 📄 clock_config.h
├─ 📄 example_board_readme.md
├─ 📄 examples_shared_readme.md
├─ 📄 hardware_init.c
├─ 📄 hello_world.c
├─ 📄 mcux_config.c
├─ 📄 pin_mux.c
├─ 📄 pin_mux.h
└─ 📄 readme.md

📁 mcuxsdk
└─ 📁 examples
└─ 📁 demo_apps
└─ 📁 hello_world
├─ 📄 CMakeLists.txt
├─ 📄 example.yaml
├─ 📄 hello_world.c
├─ 📄 Kconfig
└─ 📄 readme.md

For more details on how to build and run a project, refer to First Build

What’s New in Projects#

MCUXpresso SDK CMake extensions and configuration#

The CMake extensions can be reviewed in the mcuxsdk/cmake folder. These extensions introduce an abstraction layer that significantly reduces the complexity of individual CMakeLists.txt files, making them more minimal and easier to maintain.

Instead of requiring developers to manually declare toolchains, link flags, source lists, and post-build steps, the SDK provides macros and functions (such as mcux_add_source, mcux_convert_binary, etc.) that encapsulate these repetitive tasks. This approach improves portability and enforces consistency across projects.

However, the abstraction does not hide the underlying logic entirely. The extension scripts expose the atomic CMake commands they rely on—such as add_executable, target_link_libraries, and add_custom_command—within modular files. This transparency allows developers to:

Understand how the build system is structured.
Inspect or override specific behaviors when needed.
Learn the mapping between high-level SDK macros and standard CMake primitives.

In short, the extensions strike a balance between simplicity for day-to-day use and visibility for advanced customization, making the build system both developer-friendly and flexible.

Category	25.09.00 and Prior Releases	25.12.00 and Future Releases	Why the Change
CMake version & system	`cmake_minimum_required(3.10)`, sets `CMAKE_SYSTEM_NAME Generic`; custom build types	`cmake_minimum_required(3.22)`; relies on MCUXpresso SDK CMake extensions	Align with modern CMake features and SDK automation
SDK integration	Manual includes: `devices/MCXN947/all_lib_device.cmake`; local `flags.cmake`, `config.cmake`	Centralized SDK extension: `include(${SdkRootDirPath}/cmake/extension/mcux.cmake)` and root `CMakeLists.txt`	Reduce duplication and enforce consistent SDK structure
Project declaration	`project(hello_world_cm33_core0)` + `enable_language(ASM)`	`project(hello_world LANGUAGES C CXX ASM PROJECT_BOARD_PORT_PATH …)`	Support multi-language builds and board-specific paths
Source definition	`add_executable(...)` with explicit file list	`mcux_add_source(BASE_PATH … SOURCES …)` (SDK macro)	Simplify source management and improve portability
Board/config overrides	Includes local `flags.cmake`, `config.cmake`	Optional board-level `reconfig.cmake`	Enable flexible board-level customization without manual edits
Linking	Manual system libs `-lm -lc -lgcc -lnosys`; start/end group wrapping	Linking abstracted by SDK; no explicit system lib flags	Avoid manual link order issues and leverage SDK defaults
Post-build	`objcopy -Obinary` to produce `hello_world.bin`	`mcux_convert_binary(BINARY …)` (SDK macro)	Standardize binary conversion and reduce custom commands
Build outputs	`EXECUTABLE_OUTPUT_PATH` and `LIBRARY_OUTPUT_PATH` set manually	Uses `${APPLICATION_BINARY_DIR}` (SDK-managed)	Centralize output handling for multi-config

Kconfig Support#

The new project format introduces Kconfig, which enables advanced configuration management.

Kconfig provides GUIConfig, a visual interface for setting key software configuration symbols and values.
This makes it easier to customize features without manually editing configuration files.

For more details:#

Getting Started with 25.12.00 SDK#

While the content noted above has changed, the process for importing the SDK and projects remains the same:

Use SDK Builder to download your Arm GCC SDK as a ZIP/archive file
Import SDK to download your Arm GCC SDK from GitHub directly to your VS Code workspace
Import projects and checkout the new project structure
Build and run a project using the updated CMake configuration

MCUXpresso SDK Migration Guide

Contents