Building and Debugging from Visual Studio Code (Linux)

Introduction

This article will demonstrate the steps required for setting up a CMake project for an Arm Cortex-M4 device, built with the IAR Build Tools on Linux, from Visual Studio Code on Linux.

Required software

Below you will find the software and their versions used in this article. Newer versions might work with little or no modification(s).

Software	Version	Link
Ubuntu Desktop	22.04.3	link
IAR Build Tools for Arm	9.50.1	link
Microsoft Visual Studio Code	1.86.0	link
Microsoft CMake Tools Extension	1.17.15	link
Microsoft C/C++ Extension Pack	1.3.0	link
IAR Debug Extension	1.30.4	link
CMake	3.22.1	link

Installing the software

Install the required software:

• Install the IAR Build Tools: sudo apt install /path/to/bxarm-*.deb (setup the license)
• Install CMake: sudo apt install cmake
• Install VSCode: sudo apt install /path/to/vscode-*.deb and launch it code
• Install the VSCode extensions (Ctrl+Shift+X):
  • CMake Tools extension
  • IAR C-SPY Debug

Procedure

This demonstration assumes all the required software installed with their defaults and ready to use.

• In Visual Studio Code, select: File → Open Folder... (Ctrl+K, Ctrl+O).

Note VSCode will ask you if you trust the authors of the files in the opened folder.

• Create a new empty folder. (e.g., "hello"). This folder will be referred to as <proj-dir> from now on.

• Create a <proj-dir>/main.c source file with the following content:

#include <intrinsics.h>
#include <stdio.h>
#include <stdint.h>

__root uint_fast8_t counter = 0;

void main() {
   while (counter < 10) {
     printf("Hello world! %u\n", counter);
     ++counter;
   }
   for(;;) {
      ++counter;
   }
}

Creating the CMakeLists

• Create a <proj-dir>/CMakeLists.txt file with the following content:

cmake_minimum_required(VERSION 3.22)

# Set the project name and its required languages (ASM, C and/or CXX)
project(example LANGUAGES C)

# Add an executable named "hello"
add_executable(hello)

# Add "hello" source file(s)
target_sources(hello PRIVATE main.c)

# Set the compiler options for "hello"
target_compile_options(hello PRIVATE
  --cpu Cortex-M4
  -e
)

# Set the linker options for "hello"
target_link_options(hello PRIVATE
  --semihosting
  --map .
  --config "${TOOLKIT_DIR}/config/linker/ST/stm32f407xG.icf"
)

Configuring the CMake Tools extension

• Create a <proj-dir>/.vscode/cmake-kits.json file with the following content (adjusting the paths as needed):

[
  {
    "name": "IAR",
    "compilers": {
      "C": "/opt/iarsystems/bxarm/arm/bin/iccarm"
    },
    "cmakeSettings": {
      "TOOLKIT_DIR": "/opt/iarsystems/bxarm/arm",
      "CMAKE_MAKE_PROGRAM": "/opt/iarsystems/bxarm/common/bin/ninja"
    }
  }
]

Note

• CMake Tools will prefer Ninja it is present, unless configured otherwise.
• If you change the active kit while a project is configured, the project configuration will be re-generated with the chosen kit.

Building the project

• Invoke the palette (CTRL+SHIFT+P).
  • Perform CMake: Configure.
  • Select IAR from the drop-down list.
• Invoke the palette
  • Perform CMake: Build.

Output:

[main] Building folder: hello
[build] Starting build
[proc] Executing command: /usr/bin/cmake --build /home/user/hello/build --config Debug --target all --
[build] [1/2  50% :: 0.070] Building C object CMakeFiles/hello.dir/main.c.o
[build] [2/2 100% :: 0.144] Linking C executable hello.elf
[driver] Build completed: 00:00:00.206
[build] Build finished with exit code 0

Enabling Intellisense for the IAR C/C++ Compiler for Arm in Visual Studio Code

In order to get accurate results, Intellisense needs:

• the compiler's internal macros
• the compiler's keywords

For consistency, we will create two header files containing such information.

~/.config/Code/IAR/iccarm_predef.h

This header file can be generated with the following command:

mkdir -p ~/.config/Code/IAR
/opt/iarsystems/bxarm/arm/bin/iccarm . --c++ --predef_macros=n ~/.config/Code/IAR/iccarm_predef.h

~/.config/Code/IAR/iccarm_keywords.h

Create this header file with the following contents:

#define __absolute
#define __arm
#define __big_endian 
#define __cmse_nonsecure_call
#define __cmse_nonsecure_entry
#define __exception
#define __fiq
#define __interwork
#define __intrinsic
#define __irq
#define __little_endian
#define __naked
#define __no_alloc
#define __no_alloc16
#define __no_alloc_str
#define __no_alloc_str16
#define __nested
#define __no_init
#define __noreturn
#define __nounwind
#define __packed
#define __pcrel
#define __ramfunc
#define __root
#define __ro_placement
#define __sbrel
#define __stackless
#define __svc
#define __swi
#define __task
#define __thumb
#define __weak

Note Extended keywords available as per IAR C/C++ Compiler for Arm 9.50.1

~/.config/Code/User/settings.json

The following JSON file configures Microsoft Intellisense to work with the IAR C/C++ Compiler for Arm:

{
    // Intellisense settings
    "C_Cpp.default.compilerPath": "/opt/iarsystems/bxarm/arm/bin/iccarm",
    "C_Cpp.default.cStandard": "c17",
    "C_Cpp.default.cppStandard": "c++17",
    "C_Cpp.default.intelliSenseMode": "clang-arm",
    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
    "C_Cpp.default.mergeConfigurations": true,
    "C_Cpp.default.includePath": [
        "/opt/iarsystems/bxarm/arm/inc/c",
        "/opt/iarsystems/bxarm/arm/inc/c/aarch32"
    ],
    "C_Cpp.default.forcedInclude": [
        "~/.config/Code/IAR/iccarm_predef.h",
        "~/.config/Code/IAR/iccarm_keywords.h"
    ],
    // CMake settings
    "cmake.enabledOutputParsers": ["cmake", "iar"]
}

Debugging the project

In this final section, it is time to setup the project's launch configuration for the IAR C-SPY Simulator for Arm in Visual Studio Code. For this article, we will use a Cortex-M4 simulated target.

• Go to Run → Add Configuration...
• From the drop-down list, select IAR C-SPY Debug
• From the next drop-down list, select Template: Debug with C-SPY Simulator (Arm template)

A general template will be created inside the project folder (<proj-dir>/.vscode/launch.json). Update the fields in the template configuration to match the following:

{
   // Use IntelliSense to learn about possible attributes.
   // Nover to view description of existing attributes.
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
      {
         "type": "cspy",
         "request": "launch",
         "name": "Debug with C-SPY Simulator",
         "target": "arm",
         "program": "${command:cmake.launchTargetPath}",
         "stopOnSymbol": "main",
         "workbenchPath": "/opt/iarsystems/bxarm",
         "projectPath": "${workspaceRoot}",
         "driver": "Simulator",
         "driverOptions": [
            "--cpu=cortex-m4",
            "--semihosting"
         ]
      }
   ]
}

Once the <proj-dir>/build/hello.elf executable was built:

• In main.c, click on the left curb of the line which increments the counter (++counter;) to set a breakpoint.
• Go to Run → Start Debugging (F5) to start the debugging session.

Summary

This article described the steps to prepare a CMake project in Visual Studio Code on Linux, build it with the IAR Build Tools and debug it with the IAR C-SPY Debugger.