==== Preface ====

The aim is to create a reproducible build chain for a “Hello World” demo on the Cortex-M7 core of the TQMa117xL using VS code under Ubuntu 24.04. \\ The following regarding the **OS** is necessary:
  * Ubuntu 24.04 (64-bit), kept up-to-date.
  * Super user rights for tool installations and system changes.
<callout type="info" icon="true">
The instructions on this page refer to the TQMa117xL repository and ancillary tools listed in the following table.
</callout>

==== Prerequisites  ====

<grid>
<col sm="6">
<panel type="default" title="Software Versions" height="400px">
Building under Windows has been tested with the following software and versions.
^  Tool  ^  Version  ^
^ GitHub Repository |  [[https://github.com/tq-systems/MBa117xL.SW.MCU.BSP | MBa117xL.SW.MCU.BSP]]  |
^ [[https://code.visualstudio.com/Download|VS-Code]] |  Version 1.88.1  |
^ [[https://github.com/nxp-mcuxpresso/mcux-sdk|NXP's MCUXpresso SDK]]  |  MCUX_2.14.0_UPDATE_ENHC1  |
^ [[https://cmake.org/download/|CMAKE]]  |  Version 3.27.4  |
^ [[https://pypi.org/project/west/|West]]  |  Version 1.0.0  |
^ [[https://www.python.org/downloads/|Python]]  |  Version 3.10.4  |
^ [[https://www.segger.com/downloads/jlink/|Segger J-Link for debugging]]  |  Version v7.92l  |
^ Download MinGW for Windows  |  v13.1.0  |
</panel>
</col>
<col sm="6">
<panel type="default" title="VS-Code-Extentions" height="400px">
In order to build and debug the examples via VS-Code you need to add the following VS-Code extentions.
^  Extention  ^  Version  ^
^ <code>ms-vscode.cmake-tools</code> |  CMake tools (from Microsoft): v1.16.3  |
^ <code>marus25.cortex-debug</code> |  Cortex-Debug (from marus25): v1.12.0  |
<callout type="danger">
Advice: Check if the 'Status-Bar-Visibility' option by the CMAKE extention is set to 'visible'.
</callout>
</panel>
</col>
</grid>

==== Setup Host System and VS-Code ====

<panel type="primary" title="Setup Host">
1. Install Python3 (needed for west and helper scripts)
<code>
sudo apt install python3 python3-pip python3-venv -y
</code>

3. Setup Virtual Enviroment
<code>
python3 -m venv ~/mba117xl-env
source ~/mba117xl-env/bin/activate
</code>
2. Install Arm GNU Toolchain
Download from: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads

<code>
sudo apt install gcc-arm-none-eabi
</code>

3. Install CMake
<code>
sudo apt install cmake -y
</code>

4. (Optional) Install SEGGER J-Link for Debugging

</panel>


==== Setup Project ====
<panel type="primary" title="Setup Project">
<callout type="primary">Take a look at [[https://support.tq-net.de/en/arm/tqma117xl/overview#structure-of-repository|Structure of Repository]]</callout>
**Clone the TQMa117xL demo repository:**
<code bash>
mkdir -p ~/workspace/NXP
cd ~/workspace
git clone https://https://github.com/tq-systems/MBa117xL.SW.MCU.BSP.git
cd MBa117xL.SW.MCU.BSP
git checkout MBa117xL.SW.MCU.BSP.0003 -b tqma117xl-bsp
</code>
\\
**Clone NXP MCUXpresso SDK via West:**
<code bash>
pip3 install west
cd dependencies
west init -m https://github.com/NXPmicro/mcux-sdk --mr MCUX_2.16.000 mcuxsdk
cd mcuxsdk
west update
</code>
<callout type="warning" icon="fa fa-warning">
Afterwards, copy replace_include_guards.py into the same directory as the mcuxsdk.\\ **ATTENTION: This step is absolutely necessary!**
<code>
cp ../replace_include_guards.py ./
</code>
</callout>
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.
<code bash>
cd ..
python3 replace_include_guards.py
</code>
\\
**VS-Code additional step:** \\
When using Visual Studio Code as your development environment, the `.vscode` folder plays a critical role in configuring how your project is built and debugged.
These files inside the `.vscode` folder are **specific to your local development environment**.
<code>
.vscode/
├── settings.json           → Environment vars and toolchain path
├── launch.json             → Debug configuration (e.g. for J-Link)
├── cmake-variants.yaml     → Build variants (Debug/Release + bootDisk)
</code>
Place the `.vscode` folder under: 
<code>
mv ~/workspace/MBa117xL.SW.MCU.BSP/templates .vscode
</code>
You can use the templates provided in the `templates/` folder of the repository as a starting point.
**Open VS-Code**
<code>
code .
</code>
</panel> 

==== Building examples ====

<panel type="primary" title="Building">
<grid>
<col sm="6">
{{ :en:arm:step_1.webp |}}
</col>
<col sm="6">
[github_markdown url="https://raw.githubusercontent.com/tq-systems/MBa117xL.SW.MCU.BSP/main/README.md" section="Building Target"]
</col>
</grid>
</panel>