doc: merge the cmake wiki

Signed-off-by: Frederic Pillon <[email protected]>

Author: fpistm

Home.md

@@ -1,4 +1,4 @@
-![stm32duino](https://avatars2.githubusercontent.com/u/12180191?v=3&s=200) 
+![stm32duino](https://avatars2.githubusercontent.com/u/12180191?v=3&s=200)
 # Welcome to the **stm32duino** wiki!
 
 # [[Getting Started|Getting-Started]]
@@ -49,4 +49,4 @@ Or submit a topic on the [stm32duino forum](http://stm32duino.com):
 # Links
 [Arduino.cc official website](https://www.arduino.cc/)
 
-[STM32 MCU](http://www.st.com/en/microcontrollers/stm32-32-bit-arm-cortex-mcus.html)
+[STM32 MCU](http://www.st.com/en/microcontrollers/stm32-32-bit-arm-cortex-mcus.html)

_Sidebar.md

@@ -49,7 +49,7 @@
     * [Board support based on a core](https://github.com/stm32duino/wiki/wiki/Custom-board-based-on-a-core)
   * [How to debug](https://github.com/stm32duino/wiki/wiki/How-to-debug)
   * [PlatformIO](https://github.com/stm32duino/wiki/wiki/PlatformIO)
-  * [CMake support](https://github.com/massonal/Arduino_Core_STM32/wiki)
+  * [CMake support](./Cmake_home)
 </details>
 
 * <details>

_cmake/Advanced usage.md

@@ -0,0 +1,68 @@
+
+This page will discuss how to customize your project beyond the functions provided with Arduino_Core_STM32, using some standard CMake features.
+Hence, knowledge of both CMake and the STM32 CMake framework is assumed.
+Regarding the latter, an [`insight()`](./Functions-reference#insights) can be useful, namely LOGIC_STRUCTURE.
+
+Below is the logic structure of the simplest example, the Blink sketch.
+The following sections may refer to it to illustrate their points.
+
+![Blink logic structure](../img/logicstructure.gv.svg)
+
+
+# Adding new settings to the build
+
+Depending on the particular setting, CMake provides several functions:
+- [`target_compile_definitions()`](https://cmake.org/cmake/help/latest/command/target_compile_definitions.html)
+- [`target_compile_options()`](https://cmake.org/cmake/help/latest/command/target_compile_options.html)
+- [`target_include_directories()`](https://cmake.org/cmake/help/latest/command/target_include_directories.html)
+- [`target_link_directories()`](https://cmake.org/cmake/help/latest/command/target_link_directories.html)
+- [`target_link_libraries()`](https://cmake.org/cmake/help/latest/command/target_link_libraries.html)
+- [`target_link_options()`](https://cmake.org/cmake/help/latest/command/target_link_options.html)
+- [`target_sources()`](https://cmake.org/cmake/help/latest/command/target_sources.html)
+
+Most of these commands make use of the `PUBLIC`, `INTERFACE` or `PRIVATE` keywords.
+- `PUBLIC` and `INTERFACE` will apply the setting to all the dependers of the target in question;
+- `INTERFACE` and `PRIVATE` apply the setting to the target itself.
+
+[Here](https://cmake.org/cmake/help/latest/manual/cmake-commands.7.html) is a comprehensive list of commands that can be used in a project.
+
+# Where to add the settings
+
+Several interface targets are of interest when the settings are to affect more than just the user sketch:
+- `base_config` is depended upon by all the project (core, libraries, sketch);
+- The targets ending in  `_usage` contain settings that are propagated upwards through the tree;
+  these are useful when the scope of the setting is more specific.
+
+It is also possible to add `PRIVATE` build settings directly on the code targets; e.g., to the sketch target.
+However, a good practice is to instead create additional INTERFACE targets to put these flags in,
+and make it a dependency of other parts of the project, using [`target_link_libraries()`](https://cmake.org/cmake/help/latest/command/target_link_libraries.html).
+
+Some code part come in three targets, e.g., `core`, `core_bin`, `core_usage`.
+The actual source files always are in the `_bin` target; that is to say, when there are source files (think of precompiled Arduino libraries).
+`*_usage` gathers "public" settings to be used in that that target, and also by the dependers.
+Lastly, the bare name target is just a wrapper are the previous two.
+
+# Change the way CMake builds the project
+
+Some variables affect the way CMake builds the project.
+They can be specified either in a CMakeLists.txt, or (preferably) on the command-line, with the following syntax:
+```sh
+cmake -S ... -B ... -DVARIABLE=VALUE
+```
+_(The value is mandatory; use `1`, `ON` or `YES` as boolean true value.)_
+
+A comprehensive list of such variables is defined in the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html); some of the most relevant ones are listed below.
+
+- [`CMAKE_DISABLE_PRECOMPILE_HEADERS`](https://cmake.org/cmake/help/latest/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.html)
+- [`CMAKE_INCLUDE_CURRENT_DIR`](https://cmake.org/cmake/help/latest/variable/CMAKE_INCLUDE_CURRENT_DIR.html)
+- [`CMAKE_INTERPROCEDURAL_OPTIMIZATION`](https://cmake.org/cmake/help/latest/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.html) (equivalent to the `LTO` switch in [`overall_settings()`](./Functions-reference#overall_settings))
+- [`CMAKE_UNITY_BUILD`](https://cmake.org/cmake/help/latest/variable/CMAKE_UNITY_BUILD.html)
+- [`EXECUTABLE_OUTPUT_PATH`](https://cmake.org/cmake/help/latest/variable/EXECUTABLE_OUTPUT_PATH.html)
+
+CMake is also affected by some environment variables (doc [here](https://cmake.org/cmake/help/latest/manual/cmake-env-variables.7.html)), e.g.:
+- [`CMAKE_BUILD_PARALLEL_LEVEL`](https://cmake.org/cmake/help/latest/envvar/CMAKE_BUILD_PARALLEL_LEVEL.html)
+- [`CMAKE_GENERATOR`](https://cmake.org/cmake/help/latest/envvar/CMAKE_GENERATOR.html) (_usful to omit the `-G` on each CMake call_)
+- `CC`, `CXX`, `CFLAGS`, `CXXFLAGS`, `LDFLAGS` with the same meaning as with `make`
+
+Please note that not all features work, or even make sense, for embedded projects.
+Caution and testing are advised when dealing with the variables listed here.

_cmake/Arduino (in)compatibility.md

@@ -0,0 +1,48 @@
+# Deviations to the behavior of Arduino IDE
+
+While the CMake toolsuite aims at replicating the behavior of Arduino IDE, there may be some deviations, by design or accident.
+This page lists all such known deviations.
+
+# Source files
+
+Arduino IDE dynamically discovers all the source files of the sketch when rebuilding.
+On the other hand, with the CMake tools, there is a hard-coded list of files to update manually (cf. [`build_sketch()`](./Functions-reference#build_sketch).).
+
+This comes from the different levels at which the tools operate: Arduino IDE behaves as a build system, while CMake is a _meta_ build system.
+This means that, while CMake can discover all the source files when it is manually invoked,
+it may not be reinvoked (as should be) after a source file is added, since it was not "monitoring" that file in the first place.
+Please reat the [warning note](https://cmake.org/cmake/help/latest/command/file.html#glob) in the CMake documentation for details.
+
+Also, as mentioned in [the Arduino documentation](https://arduino.github.io/arduino-cli/0.21/sketch-build-process/#pre-processing), all the
+`.ino` files of the sketch are concatenated during the pre-processing step.
+This is not implemented with CMake, as most sketches have a single `.ino` file, but if you fill the need for this feature, please submit a PR!
+
+On the other hand, Arduino _requires_ each sketch to have a `.ino` file with the same name as the sketch folder.
+In CMake, there is no such restriction; you may name your `.ino` files differently, or even not have any `.ino` file at all.
+
+Final tweak: as part of the conversion `.ino` -> `.cpp`, Arduino IDE generates the prototypes of all the functions defined in .ino files.
+This is meant mostly for beginners, so that they may write their functions in any order without the added complexity of prototypes.
+This process is replicated with CMake, with the slight nuance that Arduino runs the GCC preprocessor _before_ doing this,
+in order to resolve all the macros and get "sane" C++ code. As opposed to this, CMake does not model the preprocessing stage, so it has to work
+on the "raw" `.ino` file. Usually this has no consequence whatsoever, but it may cause trouble if you use complex macros that alter the structure
+of the code.
+
+# Library management
+
+Arduino IDE comes with a full library management suite, to download and update third-pary libraries as needed.
+This is out of the scope of the CMake tool; users have to download and manage their libraries externally.
+It is, however, possible to reuse the libraries installed by `arduino-cli`, e.g., by using the [quickstart script](./Quickstart-guide#Quickstart%20script).
+
+Second item, Arduino IDE discovers at compile-time what libraries the sketch needs.
+This is done by catching GCC errors during the preprocessing stage, and fuzzy matching the missing `#include` with all the available libraries,
+as described in [their documentation](https://arduino.github.io/arduino-cli/0.21/sketch-build-process/#dependency-resolution).
+
+CMake does not have access to all these data _at configure-time_; also, it does not model the preprocessing at all.
+This means the dependency resolution process, if implemented, would have been awkward and fragile.
+This is why another solution has been preferred: to have the user fill in all the dependencies manually (cf. the `DEPENDS` keyword in several functions in [Functions reference](./Functions-reference).)
+
+
+# Upload, serial monitor, debugger
+
+These items are out of the scope of a CMake-based tool. Your IDE may handle (part of) those features; please refer to its documentation.
+As a fallback, [`arduino-cli`](https://arduino.github.io/arduino-cli/0.25/) may also be used to these ends.

_cmake/Cmake_home.md

@@ -0,0 +1,15 @@
+Welcome to the CMake port of Arduino_Core_STM32!
+
+The goal of this repository is to let users build Arduino sketches for STM32 boards, without using neither Arduino IDE nor `arduino-cli`.
+Advantages of this approach include:
+- faster build time (about -50%, tested on Windows 10 and Ubuntu20.04);
+- flexibility: CMake has a full language centered around build description;
+- integration with IDEs: CMake integrates with most recent IDEs, easing the work of those who code outside of Arduino IDE;
+- better support of incremental compilation;
+- overstepping limits set by Arduino: sketch filename, library selection...
+
+Of course, this all has a cost: building is no longer as simple as hitting "build" in Arduino IDE; there is a CMake file to write and maintain.
+However, much has been done to make the file as high-level as possible: it is written in CMake's own syntax, but makes heavy use of the custom functions defined here in the [`cmake/` folder](../blob/cmake_dev/cmake).
+Didactic examples can be found on a separate repository: [https://github.com/stm32duino/CMake_workspace](https://github.com/stm32duino/CMake_workspace).
+
+Before delving into this wiki, be sure to read [the dedicated README](https://github.com/massonal/Arduino_Core_STM32/blob/cmake_dev/README_CMAKE.md) first!

_cmake/Functions reference.md

@@ -0,0 +1,186 @@
+# Functions reference
+
+This document lists all the functions defined in the [`/cmake`](../blob/cmake_dev/cmake) folder in this project.
+It would be a good idea to add this folder to the "CMake search path" in your project :
+
+```cmake
+list(APPEND CMAKE_MODULE_PATH ${CORE_PATH}/cmake)
+```
+(done by default in the [quickstart template](./Quickstart-guide#Quickstart-script).)
+
+All the functions are defined in a CMake module of the same name. Therefore, you have to include said module before calling the function:
+
+```cmake
+include(foo)
+foo()
+```
+
+(Of course, this does _not_ apply to the CMake built-in functions as described in [Introduction to CMake](./Introduction-to-CMake#CMake-language). These can be called directly.)
+
+# Functions emulating the Arduino behavior
+
+## build_sketch
+
+__Syntax:__
+
+```cmake
+build_sketch(TARGET <targetName>
+  SOURCES <sourcefile...>
+  [DEPENDS <dependency...>]
+)
+```
+
+This is the main function that encapsulates most of the automation of Arduino. It should only be called _after_ `overall_settings` and `set_board`.
+
+- `targetName` is the name of the [binary target](https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#binary-executables) that will be created as a result of this function; this is a handle that may be reused in later calls, to e.g., `insights()`.
+- `sourcefile...` is a list of sources files to be compiled. This does not comprise header files (`.h`).
+  You are strongly advised to hard-code the list of files directly in the CMakeLists.txt. Using [wildcards](https://cmake.org/cmake/help/latest/command/file.html#glob) is possible, but not guaranteed to work in all cases.
+- the optional `dependencies` are targets, usually Arduino libraries such as created by `external_library()`, that the sketch depdends on.
+  The CMake build model makes it awkward at best to automatically handle dependencies the way Arduino does, so they have to be specified explicitely.
+
+What this function does is the following:
+
+- Include the parts of Arduino_Core_STM32 needed for the project (core + right variant);
+- Preprocess the sources: turn the `.ino` files to `.cpp`;
+- Create the binary executable target;
+- Bind the target to its dependencies (core + "DEPENDS");
+- Add post-build hooks to:
+  - Display the size report message ("Sketch uses xxx bytes of program storage space. Maximum is yyy bytes...";
+  - Convert the binary to `.bin` and `.hex`.
+
+## external_library
+
+__Syntax:__
+
+```cmake
+external_library(PATH <path_to_lib>
+  [DEPENDS <dependency...>]
+  [FORCE]
+)
+```
+
+This function is used to add a third-party library in the build description. It takes as arguments:
+- the path to the library to parse;
+- as with `build_sketch()`, an optional list of dependencies of the library;
+- optionally, the `FORCE` keyword; read below about it.
+
+Most third-party libraries do not ship with a CMakeLists.txt.
+Therefore, one needs to be generated before that library can be used in a CMake build.
+This function wraps the generation of the CMakeLists.txt and the subsequent `add_subdirectory()` to actually add the library to the build.
+
+If no CMakeLists.txt is found, it is autogenerated by a Python script after reading `library.properties`.
+The `FORCE` keyword lets you override this behavior and overwrite the CMakeLists.txt unconditionally.
+
+In the default case, the autogenerated CMakeLists.txt will create for the library __a target with the same name as the folder name__.
+You can then use this target as a dependency of another library or of your sketch.
+
+Note: libraries built into Arduino_Core_STM32 are handled automatically; they do not need this function and can be used out-of-the-box.
+Such libraries include EEPROM, Servo, SPI, Mouse, or Wire.
+Libraries that are shipped with Arduino IDE (SD, Ethernet, ...) are not covered by this convenience.
+
+## insights
+
+__Syntax:__
+
+```cmake
+insights(TARGET <targetName>
+  [DIRECT_INCLUDES]
+  [TRANSITIVE_INCLUDES]
+  [SYMBOLS]
+  [ARCHIVES]
+  [LOGIC_STRUCTURE]
+)
+```
+
+This function lets you produce insights about the build process.
+It uses Graphviz to generate SVG files in order to better understand what happens throughout the build: configuration, compilation, linking.
+The mandatory TARGET argument is the name of the element to analyze, usually your sketch target (crated with `build_sketch()`).
+Each insight keyword is optional; even when provided, they are not built by default, you have to explicitely generate them with the build tool (e.g., `ninja symbols.svg`).
+
+| Keyword | Generated file | Description |
+| :------ | :------------- | :---------- |
+| DIRECT_INCLUDES | direct_includes.svg | Shows which source files include which |
+| TRANSITIVE_INCLUDES | transitive_includes.svg | Shows which source files include which, both directly and indirectly (chained `#include`) |
+| SYMBOLS | symbols.svg | Shows which symbol pull which other(s), at link-time |
+| ARCHIVES | archives.svg | Shows which archive pull which other(s), at link-time |
+| LOGIC_STRUCTURE | logicstructure.svg | Shows the targets involved in the project, and the dependencies they share. This is a wrapper around a built-in feature of CMake, read about details [here](https://cmake.org/cmake/help/latest/module/CMakeGraphVizOptions.html). |
+
+Note: Enabling some of these graphs can hinder performances much (in the order of +50% build time).
+
+## overall_settings
+__Syntax:__
+
+```cmake
+overall_settings(
+  [STANDARD_LIBC]
+  [PRINTF_FLOAT]
+  [SCANF_FLOAT]
+  [DEBUG_SYMBOLS]
+  [LTO]
+  [NO_RELATIVE_MACRO]
+  [UNDEF_NDEBUG]
+  [CORE_CALLBACK]
+  [OPTIMIZATION <optLevel>]
+  [BUILD_OPT <path_to_build.opt>]
+  [DISABLE_HAL_MODULES <modules...>]
+)
+```
+
+This function replaces, with additions, some of the options of the menu bar of Arduino IDE.
+All the keywords are optional; the default behavior is selected on fallback. The order of the keywords does not matter.
+
+Keywords that take no argument:
+- STANDARD_LIBC: switch to Newlib Standard as the runtime library, instead of Newlib Nano;
+- PRINTF_FLOAT: enable `%f` in `printf` (Newlib Nano only);
+- SCANF_FLOAT: enable `%f` in `scanf` (Newlib Nano only);
+- DEBUG_SYMBOLS: add `-g` to GCC (for debug);
+- LTO: enable Link-Time Optimizations (`-flto`);
+- NO_RELATIVE_MACRO: make `__FILE__` yield absolute paths; the default is the oppisite, for size and security reasons;
+- UNDEF_NDEBUG: do not define the `NDEBUG` macro; use this keyword for debug builds;
+- CORE_CALLBACK: define the `CORE_CALLBACK` macro; read about use cases [here](https://github.com/stm32duino/wiki/wiki/API#core-callback).
+
+Keywords that take a single argument:
+- OPTIMIZATION: takes an optimization level (one of `0123gs`); this will then be passed to GCC's as a `-O` flag;
+- BUILD_OPT: add the specified file to GCC's command line, as a `@file`. The file is usually named "build.opt", hence the keyword name. Note: with Arduino IDE, the file is taken by default into account; with CMake, it is not, only this keyword triggers this.
+
+Keyword that takes several arguments:
+- DISABLE_HAL_MODULES: lets you disable any unused HAL modules as an optimization.
+  Read about it [on the wiki](https://github.com/stm32duino/wiki/wiki/HAL-configuration).
+  The supported HAL modules are:
+  - ADC
+  - I2C
+  - RTC
+  - SPI
+  - TIM
+  - DAC
+  - EXTI
+  - ETH
+  - SD
+  - QSPI
+  Disabling them all (when possible) yields a significant additional size gain.
+
+## set_board
+
+__Syntax:__
+
+```cmake
+set_board(<boardName>
+  [SERIAL <serialSetting>]
+  [USB <usbSetting>]
+  [XUSB <usbSpeed>]
+  [VIRTIO <virtioSetting>]
+)
+```
+
+This function replaces the options of the menu bar of Arduino IDE that are related to board-specific features.
+It manages to stay up-to-date with what Arduino IDE would offer by parsing `board.txt`/`platform.txt` as needed,
+and caches the result in a CMake-readable database.
+
+The first argument to this function must be the board codename, as used in boards.txt.
+E.g., "GENERIC_L010RBTX", not "Generic L010RBTx" (the latter being what the IDE displays).
+Then come any number of the four keywords, in any order. As with `overall_settings`, default values are used on fallback.
+Depending on your board, not all features may be meaningful. Note: the values for each keyword are case-sensitive!
+- SERIAL: Serial support. Usually one of `generic`, `disabled`, `none` (standing for "Enabled (no generic 'Serial')");
+- USB: USB support. Usually one of `none`, `CDCgen`, `CDC`, `HID`;
+- XUSB: USB speed. Usually one of `FS`, `HS`, `HSFS`;
+- VIRTIO: virtIO support. Usually one of `disable`, `generic`, `enabled`.