[CMake][url-cm-home] is an open-source, cross-platform family of tools maintained and supported by [Kitware][url-cm-kitware]. CMake is used to control the software compilation process through simple configuration files to generate native build scripts for a chosen build system (e.g. ninja, make, etc.). For full documentation visit the [CMake Documentation Page][url-cm-docs].
This tutorial serves as a mini-guide on the ways CMake can be used alongside the __IAR C/C++ Compilers__ to cross-compile embedded software applications for the supported target architectures.
The core ideas presented were inspired by the [Technical Note 190701][url-iar-docs-tn190701].
* __The reader is familiar with the usage of the IAR Systems tools, as well as with the Kitware tools, from their respective command-line interfaces.__
>:bulb: On Linux-based systems, [`cmake`](https://cmake.org/install/) and [`ninja`](https://ninja-build.org/#:~:text=Getting%20Ninja,system%27s%20package%20manager) are normally found on the default search path so that both can be executed directly from anywhere in the system. Although, on Windows-based systems, this is not always the case. It is recommended that their respective locations are on the search path, defined by the __PATH__ environment variable. The same recommendation applies for when using `cmake.exe` with other generators such as `"Unix Makefiles"` that relies on `make.exe` as build system. Under such a scenario, if the `make.exe` program cannot be found, CMake will fail immediately during the toolchain configuration step with a corresponding error message (e.g. "_CMAKE_MAKE_PROGRAM not found_").
By default, CMake uses what it assumes to be the host platform's default compiler. When the application targets an embedded platform (known as cross-compiling), a toolchain file `<toolchain-file>.cmake` can be used to indicate the desired toolchain's location for its compiler and assembler. This section provides a simple generic template for the __IAR C/C++ Compilers__.
On the [examples/iar-toolchain.cmake](examples/iar-toolchain.cmake) file from the repository you have cloned, perform the following changes to match your system:
* Update [__IAR_INSTALL_DIR__](examples/iar-toolchain.cmake#L8) to match the corresponding location where the active product was __installed__ on __your__ system, adjusting as needed.
> * The __IAR_INSTALL_DIR__ is used to set the [__TOOLKIT_DIR__](https://github.com/IARSystems/cmake-tutorial/blob/v2022.06/examples/iar-toolchain.cmake#L17) variable.
> * The __TOOLKIT_DIR__ variable is used to set the [PATH](https://github.com/IARSystems/cmake-tutorial/blob/v2022.06/examples/iar-toolchain.cmake#L20-L24) environment variable with the `bin` directory so that the compiler can be found on the search path. Setting the PATH with this method lasts for the time CMake is running.
A project is defined by one or more CMakeLists.txt file(s). Let's understand how a project can be configured with a simple example for the Arm target architecture.
Once we have our minimal project with a suitable toolchain file, we invoke CMake to configure our build environment for when cross-compiling, choosing which _build system generator_ and which _toolchain file_ should be used for the project.
In this example we will take advantage of the `"Ninja Multi-Config"` generator option. This option can be used to generate build configurations for "Debug" and "Release" purposes. The general recommendation when using CMake is to perform an "out-of-source" build, which means creating a subdirectory for the output files.
* Use the following command to generate the scripts for the build system inside the `_builds` subdirectory:
>:warning: If for some mistake the configuration step fails (e.g. wrong option, wrong selection, etc.), it might be necessary to remove the `_builds` subdirectory before trying again. This helps CMake to avoid potential cache misses interfering during a new attempt.
<details><summary><b>Expected output example</b> (click to unfold):</summary>
>```
>[2/2] Linking C executable Debug\hello-world.elf
>```
</details>
In the minimal example we had an initial overview of what is needed to bootstrap a CMake project for a simple executable. Targets created from actual embedded software projects will typically require preprocessor symbols, compiler flags, linker flags and extended options. Additional project examples for the target architectures supported in CMake are provided as reference in the "[Examples](#examples)" section of this tutorial.
Now that you know how to _configure_ and _build_ embedded projects developed with the IAR tools using CMake, you can start to explore how projects can be configured in greater detail using the previously acquired knowledge.
In this section you will find descriptions for the provided [examples](examples). Each __architecture__ (__\<arch\>__) subdirectory contains multiple examples.
Optionally, each example's CMakeLists.txt for executable targets comes with a line `include(/path/to/iar-cspy-<arch>.cmake)` in the end as an example that illustrates how to use CTest to invoke the __IAR C-SPY Command-line Utility__ ([`cspybat.exe`][url-iar-docs-cspybat]) to perform automated tests using [macros][url-iar-docs-macros].
The __examples/\<arch\>/mix-c-asm__ example project demonstrates the basic concepts on how to build a single executable target (__mixLanguages__) using __C__ and __Assembly__ sources.
The __examples/\<arch\>/using-libs__ example project demonstrates some advanced features and how to build one executable target (__myProgram__) linked against a static library target (__myMath__) using __C__ sources.
The top-level directory contains a __CMakeLists.txt__ file that will add the __lib__ and the __app__ subdirectories, each one containing its own __CMakeLists.txt__.
The __myMath__ library target is located in the __lib__ subdirectory. The library contains functions which take two integer parameters to perform basic arithmetic over them, returning another integer as result.
The __myProgram__ executable target is located in the __app__ subdirectory. The program performs arithmetic operations using the __myMath__'s library functions.
CTest is an extension of CMake that can help when performing automated tests. In its conception, a test in CTest allows desktop software developers to execute the target directly on the host computer, evaluating its exit code.
When cross-compiling, it is not possible to execute the target executable directly from the host computer. However it is possible to execute the target with the __IAR C-SPY Debugger__ using, for example, a custom function that wraps the needed parameters (e.g. `iar_cspy_add_test()`). A module named `iar-cspy-<arch>.cmake` was included in the CMakeLists.txt files for executable targets and illustrates such a concept.
>:warning: This section requires the __IAR C-SPY Command Line Utility__ (`cspybat.exe`), which is available with the __IAR Embedded Workbench__ products.
When executable targets are built with _debug information_, they can be debugged with the __IAR C-SPY Debugger__, directly from the __IAR Embedded Workbench__ IDE.
This tutorial provided information on how to start building embedded software projects and, also, on how to perform automated tests when using the IAR Systems' tools with CMake. Once the core ideas presented here are mastered, the possibilities are only limited by the developer's mind. Such a setup might be useful depending on each organization's needs and can be used as a starting point for particular customizations.
