This guide contains instructions for configuring the build system, building targets, and executing the demonstration applications included in this repository, specifically designed for TQ-developed boards using the i.MX MCU family from NXP.
[[TOC]]
NOTE: The versions provided are the ones with which the build system and its artifacts were tested.
ms-vscode.cmake-tools
marus25.cortex-debug
CMake
is added to the system path.<Path to MinGW>/MinGW/bin
.7.92
).This repository uses NXP's MCUX SDK
repository.
NXP's MCUX SDK uses the Zephyr West Tool
to manage multiple Git repositories.
To clone the NXP's mcu-sdk repository using West, open a terminal and execute the following commands:
pip install west
cd <project path>\dependencies
west init -m https://github.com/NXPmicro/mcux-sdk --mr MCUX_2.16.000 mcuxsdk
cd mcuxsdk
west update
NOTE: You can also install mcuxsdk
in another path. If you did so, set the MCUXSDK_ROOT
environment variable to
the mcuxsdk
path before building. Use the same procedure as for the variable ARMGCC_DIR.
Afterwards, copy replace_include_guards.py
into the same directory as the mcuxsdk
.
ATTENTION: This step is absolutely necessary!
After downloading the SDK from NXP using West, the Python script replace_include_guards.py
must be run once. This is required because targets set to global
cannot be built
in the same build folder due to the existing include guards in the CMake files
in the NXP SDK.
cd <project path>
python3 <project path>/dependencies/replace_include_guards.py
This step will be executed automatically every time CMake generates the build system. CMake will check for the patched.txt
file in your mcuxsdk
dir after every execution. If this file exists, the patch script won't be executed again through
a build command.
When using from the command line, CMake has to know where to find the toolchain:
ARMGCC_DIR
pointing to the toolchain installation dir.cmake
in parallel, you can define a variable
CMAKE
pointing to the executable to use.cmake
command line.Flag | Meaning |
---|---|
CMAKE_TOOLCHAIN_FILE |
must point to <project path>/dependencies/mcuxsdk/core/tools/cmake_toolchain_files/armgcc.cmake |
CMAKE_BUILD_TYPE |
following different types are tested in SDK: Debug , Release |
bootDisk |
Linker file selection, e.g., Ram , Flash |
NOTE: Available bootDisk
settings are listed under the specific board README.
build
using -B <project path>/build
.-G <your generator>
.cd <project path>
cmake -DCMAKE_TOOLCHAIN_FILE="dependencies\mcuxsdk\core\tools\cmake_toolchain_files\armgcc.cmake" -DCMAKE_BUILD_TYPE=
"Debug" -DbootDisk="Ram" -B ".\build" -G "MinGW Makefiles" --fresh
cd <project path>
cmake --build ".\build" --config Debug --target < name of .elf-file or "all" > -j 14 --
When using the VS-Code support, the following additional steps are needed:
Flags like CMAKE_TOOLCHAIN_FILE
, CMAKE_BUILD_TYPE
, bootDisk
should be set
in the .vscode folder. Use the examples for guidance.
.json-files
and .yaml-files
in your .vscode folder by the end of this section.ext install ms-vscode.cmake-tools
or search for the extension under the menu extensions on the left bar.Ctrl+P
and ext install marus25.cortex-debug
examples/README.md
.After fulfilling the preparations, VS-Code should be displaying the CMake-Tools option on the lower bar. In order to build a target, select the build variant by clicking on the corresponding option. You can also select your target by clicking on "set default build target".
Click after selection of the desired options on "Build" to build your target(s).
Optionally you can choose the target within the CMake-menu-bar.
Before running a target, make sure you've minded the boot instructions of your board.
If you prefer to boot without VS-Code, follow the instructions for debugging within the board's README.
You can follow the instructions for debugging with VS-Code.
The repository utilizes JLinkGDBServerCL
alongside the appropriate hardware for debugging in VS-Code. To initiate
debugging, you need to configure the debug tool. Once configured, select the debug tool from the
left menu bar and choose the desired debug configuration specified within the launch.json.
To begin debugging, either click on start debugging
or press F5
.
examples/README.md
.The list of all applications can be found in the board README file.
The general structure is constituted in such a way that it was tried to create as little maintenance effort for the demo repo as possible. Thus, everything that can be summarized in higher-level folders is also deposited there.
Folder/File | Description |
---|---|
templates |
Examples for the VS-Code setting files. |
templates/cmake-variants.yaml |
The Build-Type configurations. |
templates/settings.json |
Configurations for CMake and the cortex-debug tool. |
templates/launch.json |
All debug configurations. |
examples |
Path for the demo applications. |
examples/board |
Generic files used for every app and board-specific information/configuration. |
examples/board/cmake |
CMake related files used for integrating the board into the build system. |
examples/board/<file>.mex |
Configuration file used in MCUX-Config Tools. |
build |
All build-related files. |
build/boards/<boardtype>/dist |
Location for images. |
cmake |
Location for CMake scripts. |
dependencies |
Dependencies and dependencies related files. |
dependencies/TQDevices |
Custom programmed APIs used for the applications. |
dependencies/mcuxsdk |
The downloaded repository from NXP. |
dependencies/replace_include_guards.py |
A patch script for the mcusdk. |
doxy |
Doxy-file generator configurations. |
scripts |
Scripts for automated build tests and version generation. |
The build system was created based on the specifications of NXP. Accordingly, for each app in NXP's repo,
all sources from the Driver-APIs and other libs are added to the target named MCUX_SDK_PROJECT_NAME
using the target_sources()
command. This target is created in the CMakeLists.txt
from the application.
This scheme is basically also used in this repo. However, all Include-Guards were changed from Global to
Directory using the patch script replace_include_guards.py
. This has the consequence that
one build directory can now be used for all apps here. Using the add_subdirectory()
command, a directory is added per level, so that there are no conflicts per target.
However, this has the disadvantage that the order of all includes must be correct.
This guide provides instructions and hints on structuring the build system within the context of MCUXpresso SDKs and the build system structure within this repository when creating new apps or boards.
To create a new application, you must create a new folder for it and update the CMakeLists.txt
file located in ../examples
.
Place a new CMakeLists.txt
file within the new application directory. You can use any of the CMakeLists.txt
files
from the demo applications as a template. Once a new directory with an application is created, it must be added to
examples/CMakeLists.txt
, and the variables in the examples/CMakeList.txt
folder must be adjusted accordingly.
The CMakeLists.txt
file in the examples/<app_name>
directory ensures the correct inclusion of files. To use
flags_macros
for linking/compiling and configure NXP modules, create a config.cmake
file. Templates for this can
also be found in the demo applications.
You can add special files globally to all targets by adding them to the BOARD_SRCS
variable, or specifically to one
target by adding them to the list under add_executable
. Note that you should also point to the directory where these
files are located by adding it to target_include_directories
, especially if the directory is newly created.
If you need your own board files instead of the default ones in this repository, reset the BOARD_SRCS
variable with
your own file list and the BoardDirPath
variable with your desired directory.
Compiler and linker flags are set in the flags.cmake
file in the examples/board/cmake
directory. However, to
configure specific flags, use the config.cmake
file in the application folder. There is also a flags_macros.cmake
file under cmake in the top-level directory.
When programming, use the linker scripts provided by TQ. You can include your own linker files using the set commands with the variables:
set(LINKER_FILE_RAM "<your_path>")
set(LINKER_FILE_FLASH "<your_path>")
...
Place the command in the CMakeLists.txt
of the application directory before including flags.cmake
.
For learning about NXP's API, the examples under mcuxsdk/examples
can be helpful.
Except where otherwise noted, all files within this repository are licensed under the following terms, excluding build system files (such as .cmake) and configuration files for development environments (such as Visual Studio Code setup files):
SPDX-License-Identifier: BSD-3-Clause
All documentation is licensed under CC-BY-4.0 (Creative Commons Attribution 4.0International Public License).
Copyright (c) 2021 - 2023 TQ-Systems GmbH license@tq-group.com,
D-82229 Seefeld, Germany.
Author: Isaac L. L. Yuki
For more information, please refer to our support wiki.