CMAW - CMake Arduino[CLI] Wrapper - Version 0.1.3

If you want to manage an arduino-cli installation from CMake scripts, or build simple sketches on a headless environment (such as a CI pipeline), CMAW is for you.

Usage

CMAW is a CMake module. It can be included in both build and script files.

Download CMAW.cmake from this repository, and put it somewhere in a folder you added to your CMAKE_MODULE_PATH. To do this at configure time, you can simply write:

set (CMAW_URL "https://github.com/AeroStun/CMAW/raw/v0.1.3/CMAW.cmake")
set (CMAW_RUNDIR "${CMAKE_BINARY_DIR}/runmodules")
set (CMAW_RUNLOC "${CMAW_RUNDIR}/CMAW.cmake")
if (NOT EXISTS "${CMAW_RUNLOC}")
  file (MAKE_DIRECTORY "${CMAW_RUNDIR}")
  file (DOWNLOAD "${CMAW_URL}" "${CMAW_RUNLOC}")
  list (APPEND CMAKE_MODULE_PATH "${CMAW_RUNDIR}")
endif ()

include (CMAW)

All function and macro names starting by cmaw_ should be considered reserved for CMAW.
All variable names starting by CMAW_ should be considered reserved for CMAW.
All functions, macros, and variables starting by cmaw_internal or CMAW_INTERNAL should be considered implementation details and never used directly.

Testsuite

To run the testsuite, set the environment variable ARDUINOCLI_VER to the version of the ArduinoCLI installation, and run:

cmake -P testsuite/Main.cmake

Configuration variables

• CMAW_ARDUINOCLI_DL_VERSION ["latest"]: arduino-cli version to use if there is need to download it.
• CMAW_ARDUINOCLI_BINARY_LOCATION [""]: Path to an existing arduino-cli binary on disk; empty to autodetect.
• CMAW_ARDUINOCLI_BINARY_NOSYSTEM [OFF]: When enabled, CMAW will skip searching for arduino-cli on the system.
• CMAW_ARDUINOCLI_CONFIG_FILEPATH [""]: The custom config file (if not specified the default will be used).
• CMAW_ARDUINOCLI_EXTRA_BOARD_URL [""]: Additional URLs for the board manager.
• CMAW_AUTO_PATH [""]: Directory where CMAW can self-manage an ArduinoCLI installation

Informational variables

• CMAW_VERSION: CMAW's version string (format: "major.minor.patch")

Functions

• cmaw_arduinocli_version (<out-var>): sets variable <out-var> to the ArduinoCLI version-string.
• cmaw_init_config (<destination-dir>): creates a default config file in <destination-dir>.
• cmaw_dump_config (<out-var> [JSON]): dumps the ArduinoCLI config (YAML) into the variable <out-var>. Specify the JSON flag to get the output in JSON format (CMake has some support for reading JSON).
• cmaw_update_core_index (): updates the ArduinoCLI index file for cores.
• cmaw_list_installed_cores (<ids-out-list> <versions-out-list> <latests-out-list> <names-out-list>): lists the installed cores and stores the content of each column in its respective list.
• cmaw_install_cores (<packager>:<arch>[@<version>]...): installs the specified cores.
• cmaw_uninstall_cores (<packager>:<arch>...): uninstalls the specified cores.
• cmaw_upgrade_cores (<packager>:<arch>...): upgrades the specified cores.
• cmaw_upgrade_cores (ALL): upgrades all the cores.
• cmaw_list_known_boards (<names-out-list> <fqbns-out-list>)
• cmaw_list_connected_boards (<ports-out-list> <types-out-list> <events-out-list> <names-out-list> <fqbns-out-list> <cores-out-list>): lists the connected boards and stores the content of each column in its respective list.
• cmaw_list_installed_libraries (<names-out-list> <versions-out-list> <availabilities-out-list> <locations-out-list>): list the installed libraries and stores the content of each column in its respective list.
• cmaw_update_library_index (): updates the ArduinoCLI index files for libraries.
• cmaw_install_libraries (<name>[@<version>]... [NO_DEPS]): installs the specified libraries. Specify NO_DEPS to prevent the dependencies of these libraries from being installed as well.
• cmaw_uninstall_libraries (<lib-name>...): uninstalls the specified libraries.
• cmaw_upgrade_libraries (<lib-name>...): upgrades the specified libraries.
• cmaw_upgrade_libraries (ALL): upgrades all the libraries.
• cmaw_clean_arduino_cache (): cleans the Arduino cache.
• cmaw_create_sketch (<name>): creates a named sketch (in the default sketch location).
• cmaw_preprocess (<out-var> <fqbn> "path/to/sketch"): preprocesses sketch with the provided board and stores the ouput in <out-var>

Extra Features

• ArduinoCLI autodownload: if no path for arduino-cli is provided, and that there is no system installed version (or the check was disabled via CMAW_ARDUINOCLI_NOSYSTEM), CMAW will setup its own local installation in CMAW_AUTO_PATH when set, or CMAKE_BINARY_DIR if not in script mode

Experimental (Untested) Features

• Function add_arduino_sketch: Analogous to add_executable. Supports custom compiler options (assume GNU), compile definitions, and include directories.

TODO

Highest priority first, lowest last.

• CI config with matrix of all supported CMake and ArduinoCLI versions
• Intentional support for sketch directories
• User-defined configuration file location
• Support for compilation and preprocessing with custom (local) libraries
• Function cmaw_compile_sketch
• Uploading support
• Better error handling