Skip to content

Commit 0f6594c

Browse files
KSDaemonKSDaemon
committed
README REformatting
1 parent 04d45f8 commit 0f6594c

File tree

2 files changed

+88
-29
lines changed

2 files changed

+88
-29
lines changed

‎Arduino-toolchain.cmake

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,7 @@ if (NOT _BOARD_INDEXING_COMPLETED)
6767
get_property(_in_try_compile GLOBAL PROPERTY IN_TRY_COMPILE)
6868
# IN_TRY_COMPILE check seems to be not enough. Check for parent
6969
# script works, but may be undocumented!
70-
get_filename_component(parent_script "${_ARDUINO_TOOLCHAIN_PARENT}"
71-
NAME_WE)
70+
get_filename_component(parent_script "${_ARDUINO_TOOLCHAIN_PARENT}" NAME_WE)
7271
if (parent_script STREQUAL "CMakeSystem")
7372
check_board_options_changed(_b_changed)
7473
if (NOT _b_changed)

‎README.md

Lines changed: 87 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
# Arduino CMake Toolchain
22

3-
**Arduino CMake toolchain** is a CMake toolchain for cross-compiling CMake based projects for all Arduino compatible boards (AVR, ESP32 etc.). Of course, this means all the benefits of CMake for Arduino compilation, like using your favourite IDE, configuration checks (e.g. `try_compile`, `CheckTypeSize`), etc. This also brings the Arduino compilation to professional users, who are limited by the Arduino IDE compilation.
3+
**Arduino CMake toolchain** is a CMake toolchain for cross-compiling CMake based projects for all Arduino compatible
4+
boards (AVR, ESP32 etc.). Of course, this means all the benefits of CMake for Arduino compilation, like using your
5+
favourite IDE, configuration checks (e.g. `try_compile`, `CheckTypeSize`), etc. This also brings the Arduino compilation
6+
to professional users, who are limited by the Arduino IDE compilation.
47

58
## Note by technyon
69

7-
This is a fork of
10+
This is a fork of
811

912
https://github.com/a9183756-gh/Arduino-CMake-Toolchain
1013

@@ -16,21 +19,31 @@ The included fixes are:
1619

1720
- https://github.com/a9183756-gh/Arduino-CMake-Toolchain/pull/53
1821
- https://github.com/a9183756-gh/Arduino-CMake-Toolchain/pull/57
19-
- Generate build_opts.h file in cmake binary dear to pass cpp compiler check
22+
- Generate build_opts.h file in cmake binary dear to pass cpp compiler check
2023

2124
## Project Roots
2225

23-
[Arduino-CMake-NG](https://github.com/arduino-cmake/Arduino-CMake-NG) is a great project, which could have prevented me from writing yet another Arduino CMake toolchain. However, as claimed by the project, Arduino-CMake-NG could not be easily utilized/modified for other Arduino compatible boards other than AVR, like ESP32, due to the fact that it does not fully work the way Arduino IDE works and has lot of AVR specific stuff. An other important limitation is related to portability. Arduino-CMake-NG provides Arduino specific CMake interface, requiring CMake scripts to be written/modified specifically for Arduino, rather than just passing `-D CMAKE_TOOLCHAIN_FILE=/path/to/Arduino-toolchain.cmake` to a generic CMake project.
26+
[Arduino-CMake-NG](https://github.com/arduino-cmake/Arduino-CMake-NG) is a great project, which could have prevented me
27+
from writing yet another Arduino CMake toolchain. However, as claimed by the project, Arduino-CMake-NG could not be
28+
easily utilized/modified for other Arduino compatible boards other than AVR, like ESP32, due to the fact that it does
29+
not fully work the way Arduino IDE works and has lot of AVR specific stuff. An other important limitation is related to
30+
portability. Arduino-CMake-NG provides Arduino specific CMake interface, requiring CMake scripts to be written/modified
31+
specifically for Arduino, rather than just passing `-D CMAKE_TOOLCHAIN_FILE=/path/to/Arduino-toolchain.cmake` to a
32+
generic CMake project.
2433

25-
My initial expectation was to contribute to Arduino-CMake-NG to fix the above limitations, but had to redo a lot of core logic making it very incompatible (including the usage). Also, the project Arduino-CMake-NG seems to be no longer maintained. I would like to acknowledge the authors who contributed directly/indirectly to Arduino-CMake-NG, and thus indirectly contributed to this project.
34+
My initial expectation was to contribute to Arduino-CMake-NG to fix the above limitations, but had to redo a lot of core
35+
logic making it very incompatible (including the usage). Also, the project Arduino-CMake-NG seems to be no longer
36+
maintained. I would like to acknowledge the authors who contributed directly/indirectly to Arduino-CMake-NG, and thus
37+
indirectly contributed to this project.
2638

2739
## Features
2840

2941
- [x] CMake Arduino toolchain (passed to CMake using `-D CMAKE_TOOLCHAIN_FILE=/path/to/Arduino-toolchain.cmake)`
3042
- [x] Support for all Arduino compatible platforms (such as **AVR**, **ESP32** etc.)
3143
- [x] Generic CMake scripting interface without requiring Arduino specific functions
3244
- [x] Arduino IDE compatible build (e.g. use of build rules and flags in board.local.txt, pre/postbuild hooks etc.)
33-
- [x] Selection of board and board-specific menu options as in Arduino IDE tools menu (See `ARDUINO_BOARD_OPTIONS_FILE`)
45+
- [x] Selection of board and board-specific menu options as in Arduino IDE tools menu (
46+
See `ARDUINO_BOARD_OPTIONS_FILE`)
3447
- [x] Generate Arduino HEX binaries and upload to Arduino boards (See `target_enable_arduino_upload`)
3548
- [x] Upload using serial port
3649
- [x] Remote provisioning through network
@@ -52,27 +65,46 @@ The provided toolchain file (Arduino-toolchain.cmake) is passed to cmake as folo
5265
```sh
5366
cmake -D CMAKE_TOOLCHAIN_FILE=/path/to/Arduino-toolchain.cmake <CMAKE_SOURCE_DIR>
5467
```
55-
Note: As this is cross compilation, use any cross compilation compatible generator, like makefile generators (e.g. `-G "NMake Makefiles"` or `-G "MinGW Makefiles"` on Windows command prompt or `-G "Unix Makefiles"` on UNIX compatible prompts etc.).
5668

57-
The above command generates a file **BoardOptions.cmake** in the build directory, that enumerates all the installed Arduino boards (installed through Arduino IDE or any other board manager) and their menu options. Select the Arduino board and any non-default options for the board from the BoardOptions.cmake (Or from cmake-gui), and then reinvoke the same command above.
69+
Note: As this is cross compilation, use any cross compilation compatible generator, like makefile generators (
70+
e.g. `-G "NMake Makefiles"` or `-G "MinGW Makefiles"` on Windows command prompt or `-G "Unix Makefiles"` on UNIX
71+
compatible prompts etc.).
5872

59-
If you already have a customized BoardOptions.cmake file for the Arduino Board, you can use that instead, without waiting for the generation of BoardOptions.cmake, as given below.
73+
The above command generates a file **BoardOptions.cmake** in the build directory, that enumerates all the installed
74+
Arduino boards (installed through Arduino IDE or any other board manager) and their menu options. Select the Arduino
75+
board and any non-default options for the board from the BoardOptions.cmake (Or from cmake-gui), and then reinvoke the
76+
same command above.
77+
78+
If you already have a customized BoardOptions.cmake file for the Arduino Board, you can use that instead, without
79+
waiting for the generation of BoardOptions.cmake, as given below.
6080

6181
```sh
6282
cmake -D CMAKE_TOOLCHAIN_FILE=/path/to/Arduino-toolchain.cmake -D ARDUINO_BOARD_OPTIONS_FILE=/path/to/any/BoardOptions.cmake <CMAKE_SOURCE_DIR>
6383
```
6484

6585
Note:
66-
1. After the cmake generation is successful, changing the menu options in BoardOptions.cmake may work, but changing the board itself may not be allowed by CMake because the compiler, ABI, features determination and any cache dependencies may not be retriggered again.
67-
1. CMake does not support build for multiple architectures in the same build tree. If a project requires to build applications for more than one type of Arduino boards, refer to CMake documentation for multiple architecture build.
68-
1. When this toolchain is used, executables (added with `add_executable`) have the entry points setup()/loop() and not main(). Need to include "Arduino.h" for these entry points.
69-
1. If your source files are compiled for both Arduino and other platforms like linux, then the CMake flag `ARDUINO` and the compiler flag `ARDUINO` can be used for script/code portability. Other Arduino board/architecture specific standard flags can also be used.
86+
87+
1. After the cmake generation is successful, changing the menu options in BoardOptions.cmake may work, but changing the
88+
board itself may not be allowed by CMake because the compiler, ABI, features determination and any cache dependencies
89+
may not be retriggered again.
90+
1. CMake does not support build for multiple architectures in the same build tree. If a project requires to build
91+
applications for more than one type of Arduino boards, refer to CMake documentation for multiple architecture build.
92+
1. When this toolchain is used, executables (added with `add_executable`) have the entry points setup()/loop() and not
93+
main(). Need to include "Arduino.h" for these entry points.
94+
1. If your source files are compiled for both Arduino and other platforms like linux, then the CMake flag `ARDUINO` and
95+
the compiler flag `ARDUINO` can be used for script/code portability. Other Arduino board/architecture specific
96+
standard flags can also be used.
7097

7198
### Linking with Arduino code/libraries (`target_link_arduino_libraries`)
7299

73-
`<CMAKE_SOURCE_DIR>/CMakeLists.txt` and any other dependent CMake scripts of the project contain the standard CMake scripting using `add_library`, `add_executable` etc. without Arduino specific changes. Refer to CMake documentation for the same. However when the project source code depends on the Arduino code or libraries (i.e. if the corresponding header files are included), then appropriate linking is required, as expected. This is done using `target_link_arduino_libraries` as explained below.
100+
`<CMAKE_SOURCE_DIR>/CMakeLists.txt` and any other dependent CMake scripts of the project contain the standard CMake
101+
scripting using `add_library`, `add_executable` etc. without Arduino specific changes. Refer to CMake documentation for
102+
the same. However, when the project source code depends on the Arduino code or libraries (i.e. if the corresponding
103+
header files are included), then appropriate linking is required, as expected. This is done
104+
using `target_link_arduino_libraries` as explained below.
74105

75-
If Arduino.h is included in your source files, then the target must be linked against the 'core' Arduino library as follows.
106+
If Arduino.h is included in your source files, then the target must be linked against the 'core' Arduino library as
107+
follows.
76108

77109
```cmake
78110
add_library(my_library my_library.c) # my_library.c includes Arduino.h
@@ -86,7 +118,8 @@ add_executable(my_app my_app.c) # my_app.c includes Wire.h, Arduino.h
86118
target_link_arduino_libraries(my_app PRIVATE Wire core)
87119
```
88120

89-
Like Arduino IDE, if the required Arduino libraries are to be automatically identified and linked, then it can be done as follows.
121+
Like Arduino IDE, if the required Arduino libraries are to be automatically identified and linked, then it can be done
122+
as follows.
90123

91124
```cmake
92125
add_executable(my_app my_app.c) # my_app.c includes Wire.h, Arduino.h
@@ -95,14 +128,22 @@ target_link_arduino_libraries(my_app AUTO_PUBLIC)
95128
```
96129

97130
Note:
131+
98132
1. *Wire* and *core* in the above examples are not CMake targets. They are just Arduino library names (case-sensitive).
99-
1. It is required only to specify the direct dependencies. Any deeper dependencies are automatically identified and linked. For example, if *SD.h* is included, it is sufficient to link with *SD*, even if *SD* depends on other Arduino libraries, like *SPI*.
133+
1. It is required only to specify the direct dependencies. Any deeper dependencies are automatically identified and
134+
linked. For example, if *SD.h* is included, it is sufficient to link with *SD*, even if *SD* depends on other Arduino
135+
libraries, like *SPI*.
100136

101-
These examples illustrates simple usage, but powerful enough for most use cases. However more advanced control and customization of Arduino libraries should be possible. Please refer to the [Examples](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/master/Examples) folder, as well as the API documentation of `target_link_arduino_libraries` (Currently documented as comments in [BoardBuildTargets.cmake](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/blob/master/Arduino/System/BoardBuildTargets.cmake)).
137+
These examples illustrate simple usage, but powerful enough for most use cases. However, more advanced control and
138+
customization of Arduino libraries should be possible. Please refer to
139+
the [Examples](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/master/Examples) folder, as well as the API
140+
documentation of `target_link_arduino_libraries` (Currently documented as comments
141+
in [BoardBuildTargets.cmake](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/blob/master/Arduino/System/BoardBuildTargets.cmake)).
102142

103143
### Uploading to the target board (`target_enable_arduino_upload`)
104144

105-
If support for generating HEX binary and uploading it to the board is required, then a call to `target_enable_arduino_upload` is required for each executable target, as shown below.
145+
If support for generating HEX binary and uploading it to the board is required, then a call
146+
to `target_enable_arduino_upload` is required for each executable target, as shown below.
106147

107148
```cmake
108149
add_executable(my_executable my_executable.c)
@@ -136,39 +177,58 @@ Using the programmer, bootloader can be flashed as below
136177

137178
## Serial port monitoring
138179

139-
Currently there is no support available for this within this toolchain. However any external serial port monitor can be used (e.g. Putty). External serial monitor may need to be closed before upload and reopened after upload, because both use the same serial port.
180+
Currently there is no support available for this within this toolchain. However any external serial port monitor can be
181+
used (e.g. Putty). External serial monitor may need to be closed before upload and reopened after upload, because both
182+
use the same serial port.
140183

141184
## Known issues
142185

143-
Many of the issues in the master branch have been fixed in release-1.1-dev branch. Although not tested to be fully stable, release-1.1-dev is stable enough to try out and report any futher issues before it gets merged into master.
186+
Many of the issues in the master branch have been fixed in release-1.1-dev branch. Although not tested to be fully
187+
stable, release-1.1-dev is stable enough to try out and report any further issues before it gets merged into master.
144188

145189
Below are the list of known issues in the master branch.
146190

147191
**1. Uploaded application does not work on some boards**
148192

149-
Caused by build linking issue that does not link some object files related to platform variant sources contained in the core library. Affects any Arduino platform that has variant source files in addition to the variant header files.
193+
Caused by build linking issue that does not link some object files related to platform variant sources contained in the
194+
core library. Affects any Arduino platform that has variant source files in addition to the variant header files.
150195

151-
Resolution: Please try with release-1.1-dev branch or otherwise, temporary fixes are available in the branches [fix/variant_link_alt1](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/fix/variant_link_alt1) and [fix/variant_link_alt2](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/fix/variant_link_alt2).
196+
Resolution: Please try with release-1.1-dev branch or otherwise, temporary fixes are available in the
197+
branches [fix/variant_link_alt1](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/fix/variant_link_alt1)
198+
and [fix/variant_link_alt2](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/fix/variant_link_alt2).
152199

153-
**Compromises when using the fix/variant_link_alt1 fix**: (1) CMake version must be above 3.13, (2) Application needs to link with core directly, like in [Examples/01_hello_world](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/master/Examples/01_hello_world), and not like in [Examples/03_portable_app](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/master/Examples/03_portable_app) which links transitively.
200+
**Compromises when using the fix/variant_link_alt1 fix**: (1) CMake version must be above 3.13, (2) Application needs to
201+
link with core directly, like
202+
in [Examples/01_hello_world](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/master/Examples/01_hello_world),
203+
and not like
204+
in [Examples/03_portable_app](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/tree/master/Examples/03_portable_app)
205+
which links transitively.
154206

155-
**Compromises when using the fix/variant_link_alt2 fix**: Need to retrigger cmake and do rebuild, after the first successful build, if transitive linking of core is used in the project. May get "source some_file.o not found error" in CMake during the first invocation of CMake that can be ignored.
207+
**Compromises when using the fix/variant_link_alt2 fix**: Need to retrigger cmake and do rebuild, after the first
208+
successful build, if transitive linking of core is used in the project. May get "source some_file.o not found error" in
209+
CMake during the first invocation of CMake that can be ignored.
156210

157211
**2. Build/link issue on some 3rd party platforms**
158212

159213
Resolution: Please try with release-1.1-dev branch.
160214

161215
**3. Some libraries are not detected by *target_link_arduino_libraries***
162216

163-
Currently, *target_link_arduino_libraries* takes only include names (i.e. the name of the header file without extension). If the include name does not match with the library name (as mentioned in *library.properties* of the library), the detection of the library fails \(Refer issue [#19](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/issues/19)\).
217+
Currently, *target_link_arduino_libraries* takes only include names (i.e. the name of the header file without
218+
extension). If the include name does not match with the library name (as mentioned in *library.properties* of the
219+
library), the detection of the library fails \(Refer
220+
issue [#19](https://github.com/a9183756-gh/Arduino-CMake-Toolchain/issues/19)\).
164221

165222
Workaround: Rename the library folder to the include name and use include name in *target_link_arduino_libraries*.
166223

167224
Resolution: Please try with release-1.1-dev branch.
168225

169226
## How it works
170227

171-
This toolchain follows the build process described in [Arduino Build Process](https://arduino.github.io/arduino-cli/sketch-build-process/), and processes the JSON, platform.txt and boards.txt files correponding to the Arduino platform as specified in the documentation [Arduino IDE 1.5 3rd party Hardware specification](https://arduino.github.io/arduino-cli/platform-specification/).
228+
This toolchain follows the build process described
229+
in [Arduino Build Process](https://arduino.github.io/arduino-cli/sketch-build-process/), and processes the JSON,
230+
platform.txt and boards.txt files corresponding to the Arduino platform as specified in the
231+
documentation [Arduino IDE 1.5 3rd party Hardware specification](https://arduino.github.io/arduino-cli/platform-specification/).
172232

173233
## License
174234

0 commit comments

Comments
 (0)