Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .copier-answers.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# The answers this project was made from, which `copier update` reads. Change one with
# `copier update --data name=value`, not here.
_commit: v0.11.1
_commit: v0.12.0
_src_path: gh:theAndreas/embedded-cpp-template
arduino: true
arduino_core: arduino:avr@1.8.8
Expand Down
7 changes: 4 additions & 3 deletions .devcontainer/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -86,9 +86,10 @@ RUN ARCH="$(dpkg --print-architecture)" && \
rm /tmp/gh.deb

# uv makes the environment of the Python tools from pyproject.toml and uv.lock, in the
# workspace's .venv, on the first `uv run` or with `uv sync --frozen` when the container is
# created: clang-format, clang-tidy, cpplint, gcovr, shellcheck, actionlint, ruff and copier,
# at the versions CI checks with. This ARG is the one place uv's version is written:
# workspace's .venv-devcontainer (UV_PROJECT_ENVIRONMENT in shared/devcontainer-feature.json),
# on the first `uv run` or with `uv sync --frozen` when the container is created: clang-format,
# clang-tidy, cpplint, gcovr, shellcheck, actionlint, ruff and copier, at the versions CI checks
# with. This ARG is the one place uv's version is written:
# .github/actions/uv-sync reads it for CI. Pinned with its published checksum, as the tools
# above.
ARG UV_VERSION=0.12.0
Expand Down
8 changes: 7 additions & 1 deletion .devcontainer/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ another container is lost with that container.
| `simavr` | `examples/SelfCheck` as the board runs it: `tools/self_check.sh` |
| `g++`, `gdb` (from the base image) | the tests on the host, and what `tools/project.sh` prepares |
| `cmake`, `ninja`, GoogleTest | the tests on the host: `cmake --workflow --preset default` |
| `uv` | the Python tools that `uv.lock` pins, in `.venv`: clang-format, clang-tidy, cpplint, gcovr, shellcheck, actionlint, ruff, copier |
| `uv` | the Python tools that `uv.lock` pins, in `.venv-devcontainer`: clang-format, clang-tidy, cpplint, gcovr, shellcheck, actionlint, ruff, copier |
| `clang` | the tests a second time, by another compiler: `make clang` |
| `clangd` | IntelliSense, see below |
| LLVM's headers, in `/opt/llvm-23/include` | the checks of our own, `house-*`, a module that `tools/lib/tidy_module.sh` builds and `tools/tidy.sh` loads |
Expand Down Expand Up @@ -61,6 +61,12 @@ clangd does not load the module of the checks of our own, `house-*`: those findi
`make tidy` alone. The module's own sources in `tools/lib/tidy_module/` are read against LLVM's
headers, without the checks of `.clang-tidy`, which are the library's rules and not LLVM's.

uv makes the Python tools' environment in `.venv-devcontainer`, which `UV_PROJECT_ENVIRONMENT` in
`shared/devcontainer-feature.json` names, not in `.venv`: the workspace is the host's folder, and a
`.venv` that uv made on the host names the host's paths in its scripts. uv takes such an
environment as current, and the tools fail to start (`Failed to spawn: clang-tidy`). A `.venv` in
the workspace is the host's, which the container leaves alone.

clangd comes from PyPI at 22.1.1, the newest there, one behind the clang-tidy 23 of CI, which stays
the measure. The package wraps the binary in a Python script whose interpreter would lie in root's
home; `/usr/local/bin/clangd` links to the binary itself.
Expand Down
9 changes: 7 additions & 2 deletions .devcontainer/shared/devcontainer-feature.json
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,16 @@
}
}
},
// uv's cache is a volume of its own, another file system than the workspace's .venv, so it
// copies rather than failing to link and saying so on every sync.
// uv's cache is a volume of its own, another file system than the project's environment, so
// it copies rather than failing to link and saying so on every sync.
"containerEnv": {
"GH_HOST": "github.com",
"UV_LINK_MODE": "copy",
// The environment of the Python tools in .venv-devcontainer, not in .venv: the workspace
// is the host's folder, and a .venv that uv made on the host names the host's paths in
// its scripts, which the container does not have; uv takes it as current and the tools
// fail to start. Relative, so that each worktree has its own.
"UV_PROJECT_ENVIRONMENT": ".venv-devcontainer",
// Claude Code keeps .claude.json beside ~/.claude rather than in it; this puts both
// into the volume below, so that a rebuild keeps the login and the settings.
"CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
Expand Down
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
build/
# The Python tools' environment, which uv makes from uv.lock.
# The Python tools' environment, which uv makes from uv.lock: on the host, and in the dev container,
# where UV_PROJECT_ENVIRONMENT names its own.
.venv/
.venv-devcontainer/
# What PlatformIO keeps beside a platformio.ini, its libraries among it; the builds go to build/.
.pio/
# A dev container variant of the site, such as one on an internal base image, see
Expand Down
4 changes: 2 additions & 2 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -120,8 +120,8 @@ docs: ## The reference from the Doxygen blocks, failing on a gap
tools/docs.sh

# What git has, tracked or new, copied into build/arduino-lint/<name>: the Library Manager sees
# the repository, not the working tree with its build/ and .venv, whose links arduino-lint would
# report.
# the repository, not the working tree with its build/ and uv's environments, whose links
# arduino-lint would report.
arduino-lint: ## The rules of the Arduino Library Manager
tools/arduino_lint.sh

Expand Down
2 changes: 1 addition & 1 deletion docs/CodingStyle.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ if (elapsed && running) {
| C-9 | Data members are `private` and end in `_`. | `readability-identifier-naming` |
| C-10 | A function that overrides says `override`, or `final`, and not `virtual` again. | `modernize-use-override` |
| C-11 | `mutable` only for what is not part of the state a user sees, as a cache (FN-11). | Review |
| C-12 | No `friend`: a class is reached through its public functions, by its own code as by a test (Testing.md TS-8). Neither a friend class nor a friend function, and no friend operator declared in the class and defined outside it. Two exceptions: an operator defined in the class, a hidden friend (C-15); and the derived class of a CRTP base, its type parameter, `friend Self;`, with the base's constructors private, so that only that class makes one, as `bugprone-crtp-constructor-accessibility` asks. | `house-no-friend` |
| C-12 | No `friend`: a class is reached through its public functions, by its own code as by a test (Testing.md TS-8). Neither a friend class nor a friend function, and no friend operator declared in the class and defined outside it. Three exceptions: an operator defined in the class, a hidden friend (C-15); the derived class of a CRTP base, its type parameter, `friend Self;`, with the base's constructors private, so that only that class makes one, as `bugprone-crtp-constructor-accessibility` asks; and, the other way round, the class's own CRTP base, a direct base with the class among its arguments, `friend Base;`, so that the hooks the base calls stay private to everyone else. | `house-no-friend` |
| C-13 | An operator is overloaded only where its meaning is obvious: `Point + Point`, not `Point * Point`. | `misc-unconventional-assign-operator`, Review |
| C-14 | A special member that does what the compiler's would is `= default`, not written out: `Sensor() = default;`, not `Sensor() {}`. | `modernize-use-equals-default` |
| C-15 | An operator takes one of two forms, by what it does. A **member**: one the language makes a member (`=`, `[]`, `()`, `->`, a conversion), one that changes its operand (`+=` and its like, `++`, `--`), and a unary one (`-x`, `!x`, `~x`, `*x`). A **hidden friend**, a `friend` defined in the class with both operands as its parameters: every other binary operator, `+`, `==`, `<`, `<<`. Both operands convert alike, which a member's left one does not, and the operator is found only through its class, so it neither turns up in the overloads the compiler weighs for every other `operator==` nor in their error messages. It is built on the others where it can: `+` on `+=`, `!=` on `==`, `>`, `<=` and `>=` on `<`. An operator of an `enum`, which can have no friend, is a free function beside it; so is one of a class of another file, which cannot be its friend, as a test's `operator<<` that prints a type of the library. | `house-operator-form` |
Expand Down
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ dependencies = []
[dependency-groups]
dev = [
# The C++ style and its analysis, at the versions CI checks with.
"clang-format==23.1.3",
"clang-format==23.1.5",
"clang-tidy==23.1.4",
"cpplint==2.0.2",
# What the tests reach of src/.
Expand All @@ -28,7 +28,7 @@ dev = [
"shellcheck-py==0.11.0.1",
"actionlint-py==1.7.12.25",
# The Python scripts, read with the checks [tool.ruff.lint] selects.
"ruff==0.17.3",
"ruff==0.17.4",
# The template itself, for `uv run copier update`.
"copier==9.19.1",
# A target with BUILD_SYSTEM=platformio. Pinned, as an unpinned one in Wordclock's CI became
Expand Down
8 changes: 4 additions & 4 deletions tools/arduino_lint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@
#
# Checks the library against the rules of the Arduino Library Manager, as arduino-lint does in
# CI. Not the working tree: the Library Manager sees the repository, and the working tree has
# build/ and .venv beside it, whose links arduino-lint reports as a library's. So what git has,
# tracked or new and not ignored, is copied into a folder of the library's name in build/, and
# that is checked. CI runs it as a developer does, through `make arduino-lint`, with arduino-lint
# installed by the action arduino-lint-setup at the dev container's version.
# build/ and uv's environments beside it, whose links arduino-lint reports as a library's. So
# what git has, tracked or new and not ignored, is copied into a folder of the library's name in
# build/, and that is checked. CI runs it as a developer does, through `make arduino-lint`, with
# arduino-lint installed by the action arduino-lint-setup at the dev container's version.

set -euo pipefail

Expand Down
34 changes: 33 additions & 1 deletion tools/common.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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=""
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:
Expand Down
31 changes: 23 additions & 8 deletions tools/lib/arduino_cli.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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}"
Expand Down Expand Up @@ -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}")"
Expand All @@ -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}"
Expand Down Expand Up @@ -144,17 +157,19 @@ 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
# dir: the folder to write into
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[@]}"
Expand Down
62 changes: 61 additions & 1 deletion tools/lib/tidy_module/no_friend_check.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,66 @@ bool IsOwnTypeParameter(clang::FriendDecl const& friend_decl) {
friend_decl.getDeclContext();
}

// The class a type names: a class, the injected name of a class template, or a
// specialization of a class template, by that template's pattern where it
// depends on a parameter, as `Length<Unit>` in the template `Length`.
clang::CXXRecordDecl const* ClassOf(clang::QualType type) {
clang::CXXRecordDecl const* record{type->getAsCXXRecordDecl()};
if (record == nullptr) {
if (auto const* specialization =
type->getAs<clang::TemplateSpecializationType>()) {
auto const* const pattern{
llvm::dyn_cast_or_null<clang::ClassTemplateDecl>(
specialization->getTemplateName().getAsTemplateDecl())};
record = pattern == nullptr ? nullptr : pattern->getTemplatedDecl();
}
}
return record == nullptr ? nullptr : record->getCanonicalDecl();
}

// The class template a type is a specialization of, as written, by its
// canonical declaration; null for any other type.
clang::Decl const* TemplateOf(clang::QualType type) {
auto const* const specialization{
type->getAs<clang::TemplateSpecializationType>()};
clang::TemplateDecl const* const pattern{
specialization == nullptr
? nullptr
: specialization->getTemplateName().getAsTemplateDecl()};
return pattern == nullptr ? nullptr : pattern->getCanonicalDecl();
}

// Whether `friend_decl` names the class's own CRTP base: a specialization of
// the class template of one of its direct bases, with the class itself among
// its arguments. The derived side of the pattern IsOwnTypeParameter() lets
// pass: the base calls the hooks the class keeps private to everyone else.
bool IsOwnCrtpBase(clang::FriendDecl const& friend_decl) {
clang::TypeSourceInfo const* const written{friend_decl.getFriendType()};
auto const* const self{
llvm::dyn_cast<clang::CXXRecordDecl>(friend_decl.getDeclContext())};
if (written == nullptr || self == nullptr || !self->hasDefinition()) {
return false;
}
clang::QualType const friend_type{written->getType()};
clang::Decl const* const base_template{TemplateOf(friend_type)};
if (base_template == nullptr) {
return false;
}
bool is_a_base{false};
for (clang::CXXBaseSpecifier const& base : self->bases()) {
is_a_base = is_a_base || TemplateOf(base.getType()) == base_template;
}
bool names_self{false};
for (clang::TemplateArgument const& argument :
friend_type->getAs<clang::TemplateSpecializationType>()
->template_arguments()) {
bool const is_type{argument.getKind() == clang::TemplateArgument::Type};
names_self = names_self || (is_type && ClassOf(argument.getAsType()) ==
self->getCanonicalDecl());
}
return is_a_base && names_self;
}

} // namespace

void NoFriendCheck::registerMatchers(clang::ast_matchers::MatchFinder* finder) {
Expand Down Expand Up @@ -57,7 +117,7 @@ void NoFriendCheck::check(
return;
}
}
if (IsOwnTypeParameter(*friend_decl)) {
if (IsOwnTypeParameter(*friend_decl) || IsOwnCrtpBase(*friend_decl)) {
return;
}
diag(friend_decl->getFriendLoc(),
Expand Down
10 changes: 7 additions & 3 deletions tools/tidy.sh
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,7 @@ main() {
local found
local own
local source
local target_sources
local databases=()
for target in "${TARGETS[@]}"; do
select_target "${target}"
Expand All @@ -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
Expand Down
Loading
Loading