4. CardInfo

The sketch in this example is one of the examples of Arduino's SD library. This library is one of the standard libraries that come built in Arduino IDE, but from the point of view of Arduino_Core_STM32, it is third-party, as opposed to the libraries residing in the "libraries/" folder of the core. Hence, using SD requires a bit more work in the CMakeLists.txt.

# STEP 3: configure your sketch
# -----------------------------------------------------------------------------
include(external_library)
# I cannot tell the dependencies of the library ahead-of-time
# Please write them in using the DEPENDS ... clause
external_library(PATH "${USER_LIBS}/SD" DEPENDS SPI)

include(build_sketch)
build_sketch(TARGET "4_DumpFile"
  SOURCES
  4_DumpFile.ino

  DEPENDS
  SD SPI
)

This project introduces a new function: external_library(). Its goal is to make CMake aware of third-party libraries:

• parse the target library;
• if necessary, generate a CMakeLists.txt for the library;
• add the library.

After this function returns, a new target is available with the same name as the library folder, in this case "SD". This target can then be used as a dependency of other libraries, or of the sketch itself.

In addition to a mandatory PATH, external_library() recognizes two keywords:

• "DEPENDS ...", with the same use as in build_sketch();
• "FORCE", to overwrite any preexisting CMakeLists.txt (this is not made by default, to prevent any data loss).

In our case, SD depends on SPI, a library built into Arduino_Core_STM32, and the sketch depends on both these libraries, hence the two DEPENDS clauses in external_library() and build_sketch().

---

Additional note: this CMakeLists.txt was autogenerated by the CMake bootstrap script in Arduino_Core_STM32/cmake/scripts/cmake_easy_setup.py. This script handles the source file listing, board selection, discovery of third-party libraries... However, it does not handle the dependencies of the sketch or libraries. These have been added manually here, and it is always up to the user to do this.

Note that the script relies on arduino-cli to find the third-party libraries; it should be made available in the $PATH, or passed in through the --cli option.

For completeness, here is the option summary of this script:

usage: cmake_easy_setup.py [-h] [--cli CLI] [--board BOARD] [--fire] (--output OUTPUT | --sketch SKETCH)

optional arguments:
  -h, --help            show this help message and exit
  --cli CLI, -x CLI     path to arduino-cli
  --board BOARD, -b BOARD
                        board name
  --fire                launch the build immediately (use with caution!)
  --output OUTPUT, -o OUTPUT
                        output file (CMake) with placeholders
  --sketch SKETCH, -s SKETCH
                        output file (CMake) filled given a sketch folder

Note about --output / --sketch:

The script can be used in two ways: generic, to be reused on several projects, or specific, tuned for a particular sketch. The comments at the top of the generated file show this double usage: the file can be used standalone, or included in a project (with the include() function).

In the latter case, processing will stop early, at the end of step 1, so that only the useful variables and CMake boilerplate are executed. These variables (CORE_PATH, USER_LIBS, BOARDNAME) can be used in the main CMakeLists.txt as demonstrated in this example.

# This file was autogenerated by ~/Arduino_Core_STM32/cmake/scripts/cmake_easy_setup.py.
# Use it in your CMake configuration by `include()`'ing it.
# You can also copy it in your sketch's folder and edit it to fit your project.

cmake_minimum_required(VERSION 3.21)

# STEP 1: set up bases of environment
# -----------------------------------------------------------------------------

file(REAL_PATH "~/Arduino_Core_STM32" CORE_PATH EXPAND_TILDE)
file(TO_CMAKE_PATH "${CORE_PATH}" CORE_PATH)

file(REAL_PATH "~/Arduino/libraries" USER_LIBS EXPAND_TILDE)
file(TO_CMAKE_PATH "${USER_LIBS}" USER_LIBS)

set(BOARDNAME "NUCLEO_L433RC_P")

list(APPEND CMAKE_MODULE_PATH ${CORE_PATH}/cmake)
set(CMAKE_TOOLCHAIN_FILE toolchain)


# You may remove this block when using this file as the sketch's CMakeLists.txt
if (NOT ${CMAKE_PARENT_LIST_FILE} STREQUAL ${CMAKE_CURRENT_LIST_FILE})
    # When we are imported from the main CMakeLists.txt, we should stop here
    # not to interfere with the true build config.
    return()
endif()