==== 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.
  * Administrator rights (sudo access) 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. \\
Keep in mind that the paths specified in these instructions refer to the test system. Your paths may differ.
</callout>

==== Prerequisites  ====

<grid>
<col sm="6">
<panel type="default" title="Software Versions" height="400px">
Building under Ubuntu 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 v8.83  |
</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">
<alert type="warning" icon="fa fa-warning">
Install the following tools and ensure they are added to the system PATH where indicated:
</alert>
**Install Tools & Dependencies**
  - Git (latest version):
    - Download: https://git-scm.com/download/win
    - Installation: ''sudo apt update'' and ''sudo apt install git''
    - After installation, open Git Bash or PowerShell and run: ''git config --global core.longpaths true'' (to minimize issues with long paths during Git operations). \\ 
  - Python (Version ≥ 3.10):
    - Installation: ''sudo apt install python3 python3-pip python3-venv''
  - CMake (Version ≥ 3.20):
    - Installation: ''sudo apt install cmake''
  - ARM GNU Toolchain (Version 14.2.rel1):
    - Download:[[https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-mingw-w64-i686-arm-none-eabi.zip|ARM Developer Website]] (Version 14.2.rel1 for AArch32(arm-none-eabi), x86_64-hosted Linux tar.xz).
    - Create a directory and extract the archive: ''sudo mkdir -p /opt/arm-gnu-toolchain'' and ''sudo tar -xf arm-gnu-toolchain-14.2.rel1-x86_64-arm-none-eabi.tar.xz -C /opt/arm-gnu-toolchain --      strip-components=1''
    - The path should be: /opt/arm-gnu-toolchain/bin.
  - Segger J-Link Software (Version ≥ v8.83):
    - Download: [[https://www.segger.com/downloads/jlink/|"J-Link Software and Documentation Pack" for Linux]] (e.g., DEB Installer).
    - Installation (for DEB): ''sudo dpkg -i JLink_Linux_V*.deb'' The default path is typically /opt/SEGGER/JLink.
  - Visual Studio Code:
    - Download: [[https://code.visualstudio.com/|VS Code website]] (Debian package).
    - Installation: ''sudo dpkg -i code_*.deb'' and ''sudo apt install -f''
    - Install the necessary extentions listed here [[https://support.tq-group.com/en/arm/tqma117xl/build#vs-code-extentions-1|VS-CODE-Extentions]]

----

**Set Environment Variables**
  - Add the following to your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc). Then, run source ~/.bashrc (or ~/.zshrc) or open a new terminal.
<code>
    export ARMGCC_DIR="/opt/arm-gnu-toolchain"
    export PATH="$ARMGCC_DIR/bin:$PATH"
    export PATH="/opt/SEGGER/JLink:$PATH" # Adjust if your J-Link path is different
</code> Close and reopen all terminals and VS Code.


<callout type="warning">
Close all dialogs with "OK". Restart PC or at least close and reopen all terminals and VS Code.
</callout>
<accordion collapsed="true">
<div>
<panel type="default" title="Check">
To make sure everything is set correctly use the following commands in a new terminal:
<code bash>
which arm-none-eabi-gcc
which make # or which mingw32-make if you somehow installed MinGW, but 'make' is standard
which cmake
which python3
which JLinkGDBServerCL
echo $ARMGCC_DIR
echo $env:ARMGCC_DIR
</code>
If everything is correct, the output should be looking something like this:
<code bash>
$ which arm-none-eabi-gcc
/opt/arm-gnu-toolchain/bin/arm-none-eabi-gcc
$ which make
/usr/bin/make
$ which cmake
/usr/bin/cmake
$ which python3
/usr/bin/python3
$ which JLinkGDBServerCL
/opt/SEGGER/JLink/JLinkGDBServerCL
$ echo $ARMGCC_DIR
/opt/arm-gnu-toolchain
</code>
</panel>
</div>
</accordion>
</panel>

==== Setup Project ====
<panel type="primary" title="Setup Project">
**Create Workspace**
<code bash>
mkdir ~/workspace
cd ~/workspace
</code>
**Clone the TQMa117xL demo repository:**
<code bash>
git clone 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>
\\
**Set up Python Virtual Environment** \\
This isolates the Python tools for this project.
<code bash>
python3 -m venv .tqma117xl
source ./.tqma117xl/bin/activate
</code>
**Clone NXP MCUXpresso SDK via West:**
<code bash>
pip 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 bash>
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 bash>
cd ..
mv 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>
Below you can find a example 'settings.json' and a 'launch.json'
<grid>
<col sm="6">
<accordion collapsed="true">
<panel type="default" title="settings.json">
<code json>
{
    /* CMake configurations */
    "cmake.configureOnOpen": false,
    "cmake.preferredGenerators": [
        "Ninja",
        "Unix Makefiles"
    ],
    "cmake.generator": "Unix Makefiles",
    "cmake.environment": {
        "ARMGCC_DIR": "/opt/arm-gnu-toolchain"
        //"MCUXSDK_ROOT": "/path/to/mcuxsdk" //can be used as alternative path for the sdk
    },
    "cmake.buildDirectory": "${sourceDirectory}/build",
    "cmake.configureSettings": {
        "CMAKE_TOOLCHAIN_FILE": "dependencies/mcuxsdk/core/tools/cmake_toolchain_files/armgcc.cmake"
    },
    /* Debugger configurations */
    "cortex-debug.gdbPath": "/opt/arm-gnu-toolchain/bin/arm-none-eabi-gdb",
    "cortex-debug.armToolchainPath": "/opt/arm-gnu-toolchain/bin/",
    "cortex-debug.JLinkGDBServerPath": "/opt/SEGGER/JLink/JLinkGDBServerCL",
    "cortex-debug.variableUseNaturalFormat": true,
    /*Styling configurations*/
    "files.insertFinalNewline": true,
    "files.trimFinalNewlines": true
}
</code>
</panel>
</accordion>
</col>
<col sm="6">
<accordion collapsed="true">
<panel type="default" title="launch.json">
<code json>
{
    "inputs": [
        {
            "type": "pickString",
            "id": "app",
            "description": "choose your app",
            "options": [
                "demo_hello_world",
                "demo_gpio_led",
                "demo_flexcan",
                "demo_digital_io",
                "demo_afe",
                "demo_rs485",
                "demo_sdcard",
                "demo_RTC",
                "demo_eeprom",
                "demo_iot",
                "demo_usb",
                "demo_PMIC",
                "demo_spi_flash",
                "demo_SE97BTP",
                "demo_display_dsi",
                "demo_ethernet_qos",
                "demo_ethernet_1g"
            ]
        }
    ],
    "configurations": [
        {
            "showDevDebugOutput": "both",
            "type": "cortex-debug",
            "request": "launch",
            "name": "Debug J-Link Ram",
            "cwd": "${workspaceFolder}",
            "servertype": "jlink",
            "device": "MIMXRT1176xxxA_M7",
            "interface": "jtag",
            "executable": "${workspaceFolder}/build/dist/Debug/TQMa1176xL_${input:app}.elf",
            "serverArgs": [
                "-endian",
                "little",
                "-LocalhostOnly",
                "-speed",
                "4000"
            ],
            "postLaunchCommands": [
                "target remote localhost:50000",
                "monitor reset",
                "monitor halt",
                "load"
            ]
        },
        {
            "showDevDebugOutput": "both",
            "type": "cortex-debug",
            "request": "launch",
            "name": "Debug J-Link Nor-Flash",
            "cwd": "${workspaceFolder}",
            "servertype": "jlink",
            "device": "MIMXRT1176xxxA_M7",
            "interface": "jtag",
            "executable": "${workspaceFolder}/build/dist/Debug/Flash/TQMa1176xL_${input:app}.elf",
            "serverArgs": [
                "-endian",
                "little",
                "-LocalhostOnly",
                "-speed",
                "4000",
                "-device",
                "MIMXRT1176xxxA_M7?BankAddr=0x30000000&Loader=nCS@AD18_CLK@AD19_D0@AD20_D1@AD21_D2@AD22_D3@AD23&BankAddr=0x60000000&Loader=nCS@SDB100_CLK@SDB101_D0@SDB102_D1@SDB103_D2@SDB104_D3@SDB105"
            ],
            "postLaunchCommands": [
                "monitor reset"
            ]
        },
        {
            "showDevDebugOutput": "both",
            "type": "cortex-debug",
            "request": "launch",
            "name": "Debug J-Link SD-Ram-Flash",
            "cwd": "${workspaceFolder}",
            "servertype": "jlink",
            "device": "MIMXRT1176xxxA_M7",
            "interface": "jtag",
            "executable": "${workspaceFolder}/build/dist/Debug/SD-Ram-Flash/TQMa1176xL_${input:app}.elf",
            "serverArgs": [
                "-endian",
                "little",
                "-LocalhostOnly",
                "-speed",
                "4000",
                "-device",
                "MIMXRT1176xxxA_M7?BankAddr=0x30000000&Loader=nCS@AD18_CLK@AD19_D0@AD20_D1@AD21_D2@AD22_D3@AD23&BankAddr=0x60000000&Loader=nCS@SDB100_CLK@SDB101_D0@SDB102_D1@SDB103_D2@SDB104_D3@SDB105"
            ],
            "postLaunchCommands": [
                "monitor reset"
            ]
        }
    ]
}
</code>
</panel>
</accordion>
</col>
</grid>
</panel> 

==== Building examples ====

<panel type="primary" title="Building">
After fulfilling the preparations, VS-Code should be displaying the CMake-Tools
option on the lower bar. 
<callout type="primary">Take a look at [[https://support.tq-net.de/en/arm/tqma117xl/overview#structure-of-repository|Structure of Repository]]</callout>
  - In order to build a target, select the build variant by clicking on the corresponding option in the lower bar or by selecting the CMake-Tool icon on the left hand side.
  - Choose the correct compiler (GCC 14.2.1 arm-none-eabi) and the desired build variant under "Configure"
  - Select the example application you wish to build in the "Build" option tab.
  - Finaly click "Build" in the lower bar.
  - The generated build files will be placed under ~/workspace/MBa117xL.SW.MCU.BSP/build/dist/Debug or ~/workspace/MBa117xL.SW.MCU.BSP/build/dist/Release.

<callout type="info">For Debuging via SEGGER J-Link or flashing examples via MCUXpresso-Secure-Provisioning Tool visit the [[https://support.tq-group.com/en/arm/tqma117xl/deployment|Deployment]] section.</callout>
\\
<html>
<video width="100%" height="auto" controls>
  <source src="https://support.tq-group.com/_media/en/templates/build_tqma117xl_examples.webm" type="video/webm">
</video>
</html>

</panel>