diff --git a/CHANGELOG.md b/CHANGELOG.md index 253b845..91e1a1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,21 @@ What changed in each version of the template, and what a project has to do when `copier update` brings it. +## Unreleased + +- **`EXAMPLES` in `tools/project.sh`: the examples a target compiles.** An example of one board + alone, as one of a timer only the Mega has, stops the compiler for any other board: `make + examples` compiled every example for every target, and `make tidy` read every one with each + target's flags, so a project of several targets could have none. `target_settings()` sets + `EXAMPLES` to the names of the folders of `examples/` a target compiles, all of them if it + does not. `make examples`, the table of sizes and clang-tidy take those alone; an example + that a target leaves out has empty cells in its columns. A name that is no folder of + `examples/` fails, and so does an example that no target compiles, as clang-tidy would never + read it. For AtmegaTimer's examples of Timer3 to Timer5 (its ROADMAP A-9). + +On the update: nothing to do. A project that sets no `EXAMPLES` compiles every example for +every target, as before. + ## v0.11.3 The dev container keeps the Python tools in an environment of its own, so that a `.venv` made on diff --git a/template/tools/common.sh b/template/tools/common.sh index d4abd09..56e2cfe 100755 --- a/template/tools/common.sh +++ b/template/tools/common.sh @@ -37,6 +37,7 @@ readonly BUILD_DIR="${ROOT_DIR}/build" SIMAVR_FREQUENCY=16000000 DATABASE_EXAMPLE="Basics" SELF_CHECK_EXAMPLE="SelfCheck" + EXAMPLES=() VARIANTS=(default) TIDY_VARIANTS=(default) DOCS_INTERNAL_API="" @@ -86,7 +87,8 @@ source "${ROOT_DIR}/tools/project.sh" # tools/project.sh sets for them is each target's starting point. Kept as declarations, with -g, # so that select_target() restores them as globals although it is a function. readonly TARGET_SETTINGS=(BUILD_SYSTEM CMAKE_TOOLCHAIN CMAKE_DEFINES PIO_DIR PIO_ENV FQBN - ARDUINO_CORE ARDUINO_BOARD_URLS SIMAVR_MCU SIMAVR_FREQUENCY DATABASE_EXAMPLE SELF_CHECK_EXAMPLE) + ARDUINO_CORE ARDUINO_BOARD_URLS SIMAVR_MCU SIMAVR_FREQUENCY DATABASE_EXAMPLE SELF_CHECK_EXAMPLE + EXAMPLES) PROJECT_SETTINGS="$(declare -p "${TARGET_SETTINGS[@]}" | sed 's/^declare /declare -g /')" readonly PROJECT_SETTINGS @@ -223,6 +225,36 @@ list_files() { mapfile -t list_files_into <<< "${listed}" } +# Fills the array named first with those of the files given that the selected target compiles: +# every file outside examples/, and in examples/ those of the folders list_examples() prints. +# Arguments: +# array: the name of the array to fill +# then the files, as paths from the root +target_files() { + local -n target_files_into="$1" + shift + target_files_into=() + local -A compiled_examples=() + local listed + local example + if [[ -d "${ROOT_DIR}/examples" ]]; then + listed="$(list_examples)" || return 1 + while IFS= read -r example; do + compiled_examples["${example}"]=1 + done <<< "${listed}" + fi + local file + for file in "$@"; do + if [[ "${file}" == examples/*/* ]]; then + example="${file#examples/}" + if [[ -z "${compiled_examples[${example%%/*}]:-}" ]]; then + continue + fi + fi + target_files_into+=("${file}") + done +} + # Fills the array named first with the folders of HOST_CODE, each without the / at its end. Fails # where one is no folder, as a misspelt one would be checked by nothing, without a word. # Arguments: diff --git a/template/tools/lib/arduino_cli.sh b/template/tools/lib/arduino_cli.sh index ce83f1f..ceb0e58 100644 --- a/template/tools/lib/arduino_cli.sh +++ b/template/tools/lib/arduino_cli.sh @@ -9,8 +9,21 @@ # every function works on the target select_target() selected, through its FQBN, ARDUINO_CORE, # ARDUINO_BOARD_URLS and DATABASE_EXAMPLE. This file comes from the template. -# Prints the name of every example, one per line. +# Prints the name of every example the selected target compiles, one per line: those EXAMPLES +# names, else every folder of examples/. Fails on a name that is no folder there, as a misspelt +# one would be compiled by no target, without a word. list_examples() { + local example + if ((${#EXAMPLES[@]} > 0)); then + for example in "${EXAMPLES[@]}"; do + if [[ ! -d "${ROOT_DIR}/examples/${example}" ]]; then + err "Target ${TARGET}: EXAMPLES names ${example}, which is no folder of examples/." + return 1 + fi + echo "${example}" + done + return 0 + fi local dir for dir in "${ROOT_DIR}"/examples/*/; do basename "${dir}" @@ -81,11 +94,11 @@ arduino_cli_log() { # example: optional, the name of a folder in examples/ arduino_cli_build() { local variant="$1" - local examples=("${2:-}") - if [[ -z "${examples[0]}" ]]; then + local to_build=("${2:-}") + if [[ -z "${to_build[0]}" ]]; then local listed listed="$(list_examples)" - mapfile -t examples <<< "${listed}" + mapfile -t to_build <<< "${listed}" fi local label label="$(target_label "${variant}")" @@ -94,7 +107,7 @@ arduino_cli_build() { local log local output local warnings - for example in "${examples[@]}"; do + for example in "${to_build[@]}"; do log="$(arduino_cli_log "${variant}" "${example}")" mkdir -p "${log%/*}" rm -f "${log}" @@ -144,8 +157,8 @@ arduino_cli_sizes() { echo "${flash} ${ram}" } -# Writes the database of a variant for the sources of src/ and examples/ with the flags of -# arduino_flags(), and prints its folder: the same database serves clang-tidy and the headers, +# Writes the database of a variant for the sources of src/ and of the examples the target compiles +# with the flags of arduino_flags(), and prints its folder: the same database serves clang-tidy and the headers, # as arduino_flags() already turned it into one that clang reads. # Arguments: # variant: one of TIDY_VARIANTS @@ -153,8 +166,10 @@ arduino_cli_sizes() { arduino_cli_database() { local variant="$1" local dir="$2" + local files + list_files files '\.(cpp|ino)$' 'src/*' 'examples/*' local sources - list_files sources '\.(cpp|ino)$' 'src/*' 'examples/*' + target_files sources "${files[@]}" local flags flags="$(arduino_flags "${variant}" "${BUILD_DIR}/tidy/arduino/${TARGET}/${variant}")" write_database "${dir}" "${flags}" "${sources[@]}" diff --git a/template/tools/project.sh.jinja b/template/tools/project.sh.jinja index 2cd45a6..931afba 100644 --- a/template/tools/project.sh.jinja +++ b/template/tools/project.sh.jinja @@ -12,8 +12,8 @@ # TARGETS the targets the project is built for, each a name of lower case, # digits and -, which names its folders of build/; one, board, if not # set. Each takes the settings below, from BUILD_SYSTEM to -# SELF_CHECK_EXAMPLE, as they are set here, and target_settings() -# changes them for a target +# EXAMPLES, as they are set here, and target_settings() changes them +# for a target # BUILD_SYSTEM what builds a target: arduino-cli, cmake with a toolchain file, or # platformio through a platformio.ini # CMAKE_TOOLCHAIN for cmake: the toolchain file, as cmake/toolchains/avr-gcc.cmake @@ -31,6 +31,10 @@ # SIMAVR_FREQUENCY its clock, in Hz # DATABASE_EXAMPLE for arduino-cli: the example whose flags tools/tidy.sh takes for all # SELF_CHECK_EXAMPLE the example tools/self_check.sh runs +# EXAMPLES for arduino-cli: the examples the target compiles and clang-tidy reads +# with its flags, names of folders of examples/; all of them if not set. +# An example of one board's alone, as of a timer only it has, is left +# out of the others'; one that no target compiles fails make tidy # VARIANTS the builds every example is compiled in, see variant_flags() # TIDY_VARIANTS the variants clang-tidy and cppcheck read: those whose defines change # the code. clangd reads the database of the first, on the first target diff --git a/template/tools/tidy.sh b/template/tools/tidy.sh index 5d45035..e09c8c7 100755 --- a/template/tools/tidy.sh +++ b/template/tools/tidy.sh @@ -197,6 +197,7 @@ main() { local found local own local source + local target_sources local databases=() for target in "${TARGETS[@]}"; do select_target "${target}" @@ -218,15 +219,18 @@ main() { mapfile -t own <<< "${found}" fi fi - for source in "${own[@]}"; do + # The examples of the target alone: one of another, which stops the compiler for any board + # but its own, is no entry of this database. + target_files target_sources "${sources[@]}" + for source in "${own[@]}" "${target_sources[@]}"; do compiled["${source}"]=1 done echo "clang-tidy, ${label}:" - run_tidy "${dir}" '' "${sources[@]}" "${own[@]}" "${headers[@]}" || failed=1 + run_tidy "${dir}" '' "${target_sources[@]}" "${own[@]}" "${headers[@]}" || failed=1 done done if ((!database_only)); then - for source in "${platform_sources[@]}"; do + for source in "${platform_sources[@]}" "${sources[@]}"; do if [[ -z "${compiled[${source}]:-}" ]]; then err "${source} is compiled by no target of tools/project.sh, so clang-tidy never reads it." failed=1 diff --git a/tests/check.sh b/tests/check.sh index 3c97636..5ffe601 100755 --- a/tests/check.sh +++ b/tests/check.sh @@ -14,7 +14,8 @@ # self-check; all of what `make check` runs if none is given. With --keep the project is left in # build/Demo for a look, else it is removed. With --targets the project is built for two targets # rather than one, an Uno and a Mega, as tools/project.sh describes a second target: the same -# core, so that it costs no download, and each run in simavr. With --no-arduino the project is +# core, so that it costs no download, and each run in simavr; and with an example for the Mega +# alone, which the Uno's EXAMPLES leave out. With --no-arduino the project is # a library of CMake alone (arduino=false): built by avr-gcc from apt with the template's # toolchain file, its examples programs of their own; with --targets as well, for an ATmega328P # and an ATmega2560, both run in simavr, and an AVR128DA48, which takes the other branch of @@ -48,18 +49,36 @@ run_check() { } # What tools/project.sh of the project gets with --targets, after what the template wrote: the -# text of a function, expanded by the project's shell, not this one. +# text of a function, expanded by the project's shell, not this one. The Uno leaves out the +# example of the Mega, MEGA_EXAMPLE, which does not compile for it. # shellcheck disable=SC2016 readonly TWO_TARGETS=' TARGETS=(uno mega) target_settings() { case "$1" in + uno) + EXAMPLES=(Basics SelfCheck) + ;; mega) FQBN="arduino:avr:mega" SIMAVR_MCU="atmega2560" ;; esac }' +# An example for the Mega alone, which the project gets with --targets: it stops the compiler +# for any other board, so that make examples and make tidy show that the Uno leaves it out. +readonly MEGA_EXAMPLE='// Copyright 2026 Andreas Burnickl +// SPDX-License-Identifier: GPL-3.0-or-later +// +// Does nothing, on the Mega alone. + +#ifndef __AVR_ATmega2560__ +#error "This example needs the ATmega2560 of the Mega" +#endif + +void setup() {} + +void loop() {}' # The same for a firmware. # shellcheck disable=SC2016 readonly TWO_FIRMWARE_TARGETS=' @@ -157,6 +176,8 @@ main() { echo "${TWO_FIRMWARE_TARGETS}" >> tools/project.sh elif [[ "${arduino}" == true ]]; then echo "${TWO_TARGETS}" >> tools/project.sh + mkdir -p examples/Mega + echo "${MEGA_EXAMPLE}" > examples/Mega/Mega.ino else echo "${TWO_CMAKE_TARGETS}" >> tools/project.sh fi