You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+51-52Lines changed: 51 additions & 52 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,78 +1,78 @@
1
1
# Tutorial <br>Building and testing with the IAR tools in CMake
2
2
3
-
[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].
3
+
[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 - using simple configuration files - to generate native build scripts for a selected build system, like ninja, make, etc.). For detailed documentation, visit the [CMake Documentation Page][url-cm-docs].
4
4
5
-
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.
6
-
The core ideas presented were inspired by the [Technical Note 190701][url-iar-docs-tn190701].
5
+
This tutorial serves as a very basic-level guide to using CMake together with the __IAR C/C++ compilers__ to cross-compile embedded software applications for the supported target architectures.
6
+
The core ideas presented were inspired by [Technical Note 190701][url-iar-docs-tn190701].
7
7
8
8
9
-
## Pre-requisites
9
+
## Prerequisites
10
10
This tutorial assumes that:
11
11
12
-
*__The reader is familiar with the usage of the IAR tools, as well as with the Kitware tools, from their respective command-line interfaces.__
12
+
*You are familiar with using the IAR and Kitware tools on the command line.
13
13
14
-
* This repository is cloned to the development computer (alternatively it can be downloaded as a zip archive via the __Code__ button).
14
+
* This repository is cloned to the development computer (it can also be downloaded as a zip archive by clicking the __Code__ button).
15
15
16
-
* The required tools are already installed in the system, according to the table below:
16
+
* The required tools are already installed on the system, according to the table below:
>: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_").
24
+
>: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. However, on Windows-based systems, this is not always the case. We recommend that their respective locations are on the search path, defined by the `PATH` environment variable. The same recommendation applies to using `cmake.exe` with other generators such as `"Unix Makefiles"` that rely on `make.exe` as the build system. In such a scenario, if the `make.exe` program cannot be found, CMake will fail immediately during the toolchain configuration step with a descriptive error message (for example, "`CMAKE_MAKE_PROGRAM not found`").
25
25
26
26
27
27
## Building Projects
28
-
To build a project developed with the IAR Compiler using CMake we need at least
28
+
To use CMake to build a project developed with an IAR compiler, you need at least:
29
29
* A toolchain file
30
-
* A CMakeLists.txt file
31
-
* The source code
30
+
* A `CMakeLists.txt` file
31
+
* The application source code
32
32
33
33
### Configuring the toolchain file
34
-
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__.
34
+
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 specify the intended toolchain's location to its compiler and assembler. This section provides a simple generic template for the __IAR C/C++ compilers__.
35
35
36
-
In the [examples/iar-toolchain.cmake](examples/iar-toolchain.cmake) file:
37
-
* Set `TOOLKIT` variable to the compiler's target architecture.
36
+
In the [`examples/iar-toolchain.cmake`](examples/iar-toolchain.cmake) file:
37
+
* Set the `TOOLKIT` variable to the compiler's target architecture.
# Alternative: override the default TOOLKIT_DIR (/path/to/installation/<arch>)
41
+
# Alternative: override the default TOOLKIT (/path/to/installation/<arch>)
42
42
set(TOOLKIT arm)
43
43
```
44
-
>:bulb: The default toolchain file will search for an available compiler in the default installation paths. Alternatively, the `TOOLKIT` variable can be used to set a specific installation directory (e.g., `C:/IAR_Systems/EWARM/N.nn`).
44
+
>:bulb: The default toolchain file will search for an available compiler on the default installation paths. You can also use the `TOOLKIT` variable to set a specific installation directory (for example, `C:/IAR/EWARM/N.nn`).
45
45
46
46
### A minimal project
47
-
A CMake project is defined by one or more CMakeLists.txt file(s). Let's understand how a simple `hello-world` project can be configured for the Arm target architecture.
47
+
A CMake project is defined by one or more `CMakeLists.txt` file(s). This is how a simple `hello-world` project can be configured for the Arm target architecture:
48
48
49
-
* Change to the `hello-world` project:
49
+
* Change the directory to the `hello-world` project:
50
50
```
51
51
cd /path/to/cmake-tutorial/examples/arm/hello-world
52
52
```
53
53
54
-
* Verify the contents of the __CMakeLists.txt__ file:
54
+
* Verify the contents of the `CMakeLists.txt` file:
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.
65
+
Once you have created the minimal project with a suitable toolchain file, invoke CMake to configure the build environment for cross-compiling, choosing the_build system generator_ and _toolchain file_to use for the project.
66
66
67
-
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.
67
+
In this example, 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.
68
68
69
69
* 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.
91
+
>:warning: If by mistake the configuration step fails (for example, because of using the wrong option, the wrong selection, etc.), you might have to remove the `_builds` subdirectory before you try again. This helps CMake to avoid potential cache misses interference during the new attempt.
92
92
93
93
### Building the project
94
94
* Once the `_builds` tree is configured, use CMake with the `--build` flag to build the project:
95
95
```
96
96
cmake --build _builds
97
97
```
98
-
>:bulb: Use `cmake --help` for more information.
98
+
>:bulb: The `cmake --help` command provides more information.
99
99
100
100
<details><summary><b>Expected output example</b> (click to unfold):</summary>
101
101
@@ -105,50 +105,49 @@ cmake --build _builds
105
105
106
106
</details>
107
107
108
-
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.
108
+
In the minimal example, we had an initial overview of what you need to bootstrap a CMake project for a simple executable file. Targets created from actual embedded software projects will typically require preprocessor symbols, compiler options, linker options and extended options. Additional project examples for the target architectures supported by CMake are provided as reference in the "[Examples](#examples)" section of this tutorial.
109
109
110
110
111
111
## Examples
112
-
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.
112
+
Now that you know how to use CMake to _configure_ and _build_ embedded projects developed with the IAR tools, you can start to explore how projects can be configured in greater detail.
113
113
114
-
In this section you will find descriptions for the provided [examples](examples). Each __architecture__ (__\<arch\>__) subdirectory contains multiple examples.
114
+
In this section you will find descriptions for the provided [examples](examples). Each __architecture__ (__<arch>__) subdirectory contains multiple examples.
115
115
116
-
Optionally, each example's CMakeLists.txtfor 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].
116
+
Optionally, each example's `CMakeLists.txt` file for target architectures contains the line `include(/path/to/iar-cspy-<arch>.cmake)` at 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].
117
117
118
-
### Example 1 - Mixing C and Assembly
119
-
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.
118
+
### Example 1 - Mixing C and assembler source code
119
+
The `examples/<arch>/mix-c-asm` example project demonstrates the basic concepts of building a single executable file (`mixLanguages`) using __C__ and __assembler__ source code.
120
120
121
-
It also shows:
122
-
* How to use `target_compile_definitions()` to set preprocessor symbols that can be used in the target's sources.
121
+
It also shows how to use `target_compile_definitions()` to set preprocessor symbols that can be used in the target source code.
123
122
124
123
125
124
### Example 2 - Creating and using libraries
126
-
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.
125
+
The `examples/<arch>/using-libs` example project demonstrates some advanced features and building one executable file (`myProgram`) linked with a static library file (`myMath`) using __C__ source code.
127
126
128
-
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__.
127
+
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`.
129
128
130
-
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.
129
+
The `myMath` library file is located in the `lib` subdirectory. The library contains functions that take two integer parameters to perform basic arithmetic on, returning another integer as the result.
131
130
132
-
The __myProgram__ executable target is located in the __app__ subdirectory. The program performs arithmetic operations using the __myMath__'s library functions.
131
+
The `myProgram` executable file is located in the `app` subdirectory. The application performs arithmetic operations using the functions in the `myMath` library.
133
132
134
133
It also shows:
135
134
* How to use `set_target_properties()` to propagate configuration details across the target options.
136
-
* How to set `target_link_options()` to create a map file of the executable.
137
-
* How to use `add_custom_command()` for generating .bin/.hex/.srec outputs using `ielftool`.
135
+
* How to set `target_link_options()` to create a map file of the executable file.
136
+
* How to use `add_custom_command()` for generating `.bin`/`.hex`/`.srec` output using the `ielftool` utility.
138
137
139
138
140
139
### Testing the examples
141
-
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.
140
+
CTest is an extension of CMake that can help you perform automated tests. With CTest, you can execute the target application directly on your host PC, evaluating its exit code.
142
141
143
-
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.
142
+
When cross-compiling, it is not possible to execute the target application directly on your host PC. However, you can execute the target application using the __IAR C-SPY Debugger__ and, for example, a custom function that wraps the required parameters (for example, `iar_cspy_add_test()`). A module named `iar-cspy-<arch>.cmake` is included in the `CMakeLists.txt` files for target architectures and illustrates the concept.
144
143
145
-
>:warning: This section requires the __IAR C-SPY Command Line Utility__ (`cspybat.exe`), which is available with the __IAR Embedded Workbench__ products.
144
+
>:warning: This section requires the __IAR C-SPY command line utility__ (`cspybat.exe`), which is installed with __IAR Embedded Workbench__.
146
145
147
-
* Test the desired project example (*built with debug information) by executing:
146
+
* Test the desired project example (*built with debug information*) by executing:
>:bulb: The `ctest --help` command provides more information.
152
151
153
152
<details><summary>Expected output - <b>Example 1</b> (click to unfold):</summary>
154
153
@@ -197,17 +196,17 @@ When cross-compiling, it is not possible to execute the target executable direct
197
196
198
197
199
198
## Debugging
200
-
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.
199
+
When target applications are built with _debug information_, they can be debugged with the __IAR C-SPY Debugger__, directly in the __IAR Embedded Workbench__ IDE.
201
200
202
-
The [Debugging an Externally Built Executable file][url-iar-docs-ext-elf] Technical Note has the instructions for setting up a __debug-only__ project.
201
+
The [Debugging an Externally Built Executable file][url-iar-docs-ext-elf] Technical Note has instructions for setting up a __debug-only__ project.
203
202
204
203
## Issues
205
-
Found an issue or have a suggestion related to the [__cmake-tutorial__][url-repo-home] tutorial? Feel free to use the public issue tracker.
204
+
Did you find an issue or do you have a suggestion related to the [__cmake-tutorial__][url-repo-home] tutorial? Please use the public issue tracker.
206
205
- Do not forget to take a look at [earlier issues][url-repo-issue-old].
207
-
- If creating a [new][url-repo-issue-new] issue, please describe it in detail.
206
+
- If you are reporting a [new][url-repo-issue-new] issue, please describe it in detail.
208
207
209
208
## Conclusion
210
-
This tutorial provided information on how to start building embedded software projects and, also, on how to perform automated tests when using the IAR 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.
209
+
This tutorial provides information on how to start building embedded software projects and, also, on how to perform automated tests when using the IAR tools with CMake. When you have understood the core ideas presented here, a world of possibilities opens up. Such a setup might be useful depending on your organization's needs, and can be used as a starting point for particular customizations.
0 commit comments