Building CMake projects with IAR

CMake is an open-source, cross-platform family of tools maintained and supported by Kitware. Among its many features, it essentially provides Makefile Generators and Ninja Generators which compose scripts for cross-compiling C/C++ embedded software projects based on one or more CMakeLists.txt configuration files.

This tutorial offers a short introduction for those seeking information on how to start using the IAR C/C++ Compiler together with CMake from the command line. While this guide is based on the IAR Build Tools for Arm version 9.50.1 on Linux, it should work with other supported IAR products with no or minimal changes.

Prerequisites

Before you begin, you will need to download and install the IAR product, CMake and then clone this repository.

1. Download, install and activate[^1] your IAR product

2. Download and install CMake.

3. Clone this repository to your computer. For more information, see "Cloning a repository".

Building a Basic CMake Project

The most basic CMake project is an executable built from a single source code file. For simple projects like this, a CMakeLists.txt file with about half dozen of commands is all that is required.

Any project's topmost CMakeLists.txt must start by specifying a minimum CMake version using the cmake_minimum_required() command. This establishes policy settings and ensures that CMake functions used in the project are run with a compatible version of CMake.

To start a project, use the project() command to set the project name. This call is required with every project and should be called soon after cmake_minimum_required(). This command can also be used to specify other project level information such as the language(s) used or its version number.

Use the add_executable() command to tell CMake to create an executable using the specified source code files.

Then use target_sources() to list the source files required to build the target.

Use target_compile_options() for setting up the compiler options to build the target.

And finally, set your target's linker options with target_link_options():

# set the minimum required version of CMake to be 3.20
cmake_minimum_required(VERSION 3.20)

# set the project name
project(Tutorial)

# add the executable target
add_executable(tutorial)

# target sources
target_sources(tutorial PRIVATE tutorial.c)

# compiler options
target_compile_options(tutorial PRIVATE --cpu=cortex-m4)

# linker options
target_link_options(tutorial PRIVATE --semihosting)

Enabling the IAR Compiler

CMake uses the host platform's default compiler. When cross-compiling embedded applications, the compiler must be set manually via CMAKE_<lang>_COMPILER variables for each supported language. Additionally, it is possible to specify a build tool via CMAKE_MAKE_PROGRAM:

During the configuration phase, CMake reads these variables from:

• a separate file called "toolchain file" that you invoke cmake with --toolchain /path/to/<filename>.cmake (see provided example files bxarm.cmake and ewarm.cmake) -or-
• the CMAKE_TOOLCHAIN_FILE variable, when you invoke cmake with -DCMAKE_TOOLCHAIN_FILE=/path/to/<filename>.cmake (useful for earlier CMake versions) -or-
• invoking cmake with -DCMAKE_<lang>_COMPILER=/path/to/icc<target> -or-
• the user/system environment variables CC, CXX and ASM which can be used to override the platform's default compiler -or-
• the IAR Embedded Workbench IDE 9.3 or later, shipped with IAR products starting from the IAR Embedded Workbench for Arm 9.50, where the available IAR toolchain environment is automatically set for CMake projects (See this article for details).

Configure and Build

We are ready to build our first project! Run CMake to configure the project and then build it with your chosen build tool.

• Before starting to use CMake, make sure your compiler is working and does not run into any license issues. Example (for Arm):

/path/to/iccarm --version

• From the terminal, navigate to the tutorial directory and create a build directory:

mkdir build

• Next, navigate to that build directory and run CMake to configure the project and generate a native build system using the compiler specified in the bxarm.cmake toolchain file (if needed, edit the supplied toolchain file to match your tool):

cd build
cmake .. -G Ninja --toolchain ../bxarm.cmake

• Then call CMake for building the executable using the build system:

cmake --build .

Run

Let's test the application. To run the executable you will need the non-interactive[^3] command line interface for the IAR C-SPY Debugger (cspybat) with the proper drivers for the desired target. Amongst the many ways of accomplishing this, let's take advantage of the add_test() for testing the application in a Arm Cortex-M4 simulated target.

In this example we will use Arm. To do so, you need to change the Tutorial's CMakeLists.txt:

• Firstly add enable_testing() to enable testing:

enable_testing()

• Then use add_test() to encapsulate the command line cspybat needs. In the example below, the parameters are adjusted for simulating a generic Arm Cortex-M4 target environment:

add_test(NAME tutorialTest
         COMMAND /opt/iarsystems/bxarm/common/bin/CSpyBat
         # C-SPY drivers for the Arm simulator via command line interface
         /opt/iarsystems/bxarm/arm/bin/libarmPROC.so
         /opt/iarsystems/bxarm/arm/bin/libarmSIM2.so
         --plugin=/opt/iarsystems/bxarm/arm/bin/libarmLibsupportUniversal.so
         # The target executable (built with debug information)
         --debug_file=$<TARGET_FILE:tutorial>
         # C-SPY driver options
         --backend
           --cpu=cortex-m4
           --semihosting)

• Now use the PASS_REGULAR_EXPRESSION test property to validate if the program emits the expected string to the standard output (stdout). In this case, verifying that printf() prints the expected message.

set_tests_properties(tutorialTest PROPERTIES PASS_REGULAR_EXPRESSION "Hello world!")

• Since CMakeLists.txt was modified, the build system needs to be reconfigured:

cmake --build .

• And finally we call CMake's ctest which subsequently will execute Tutorial.elf using the IAR C-SPY Debugger for Arm:

ctest

Summary

This tutorial covered the basics on using CMake with the IAR tools from the command line. Proceed to the wiki for additional tips & tricks!

Issues

Use the CMake Issue Tracker to report CMake-related software defects.

For questions/suggestions specifically related to this tutorial:

• Try the wiki.
• Check for earlier issues in the issue tracker.
• If nothing helps, create a new issue, describing in detail.

Do not use the issue tracker if you need technical support. The issue tracker is not a support forum:

• If you run into license issues, refer to IAR Customer Care.
• If you run into tools issues, contact IAR Tech Support.

[^1]: For more information, see the "Installation and Licensing" guide for your product. If you do not have a license, contact us. [^2]: CMake has built-in IAR C/C++ Compiler support for the following non-Arm architectures: 8051, AVR, MSP430, RH850, RISC-V, RL78, RX, STM8 and V850. [^3]: For interactively debugging of executable files (*.elf) using the C-SPY Debugger from the IAR Embedded Workbench IDE, read this wiki article.