The template of an embedded C++ project, a library, an Arduino one or one of C++ and CMake alone, or a firmware: its style, its static analysis, its tests on the host and on its targets, its CI and its dev container. A project is made from it with copier and kept up to date with it: every improvement made here reaches each project as a merge, not as a copy by hand.
The library is C++11 without a standard library, so that avr-gcc compiles it as well as any
other compiler. Today the template checks it on the host, by GCC and by clang, and for each of
its targets, AVRs built by arduino-cli against an Arduino core or by CMake and avr-gcc alone, in
simavr where simavr runs the part. A firmware is built by CMake, an image for each target from
its portable src/ and its platform/<name>/, or by PlatformIO through a platformio.ini
there. A library for PlatformIO's registry and targets beyond the AVR are next, see
ROADMAP.md.
| Area | What | Where |
|---|---|---|
| One way in | A Makefile that names every build and check: make lists them, make check is what CI runs, make lint the checks of seconds |
Makefile, tools/project.mk |
| Style | The Google C++ style with const on the right, braced initialization, Doxygen blocks |
.clang-format, CPPLINT.cfg, docs/Documentation.md |
| Static analysis | clang-tidy with the C++ Core Guidelines, CERT, bugprone, the analyzer, Google's names and clang's warnings beyond -Wall -Wextra, every exception with its reason, and checks of our own (house-*) for the rules no check of clang-tidy's holds; cppcheck beside it; every header compiled on its own |
.clang-tidy, tools/, tools/lib/tidy_module/ |
| Warnings | -Wall -Wextra -Wconversion -Wsign-conversion -Wshadow, errors in CI and under make check |
cmake/checks.cmake, CMakePresets.json |
| Tests | GoogleTest on the host, by GCC and by clang, against a mock of the Arduino core for an Arduino library, also under ASan and UBSan, with coverage; tests of what must not compile; fuzzers on libFuzzer, going on from what the last run found; a self check on each target in simavr | CMakeLists.txt, test/, examples/SelfCheck |
| Targets | One or several, each built by arduino-cli, by CMake with a toolchain file (cmake/toolchains/avr-gcc.cmake) or by PlatformIO, mixed in one project as it needs; every example compiled for each, without a warning, its flash and RAM in a table, and read by clang-tidy as the target compiles it; on an AVR that CMake builds, the deepest stack of each against the RAM it leaves |
tools/project.sh, tools/lib/, tools/avr_stack.py |
| Documentation | Doxygen, failing on a gap, published on GitHub Pages | Doxyfile, tools/docs.sh |
| CI | Every target of make check, in ci.yml and static-analysis.yml, each with a badge; a release from a tag |
.github/ |
| Tools | The Python tools pinned in uv.lock, the same in the container and in CI |
pyproject.toml, uv.lock |
| Dev container | Every tool, pinned with its checksum; clangd with the databases of the host and the first target | .devcontainer/ |
In a dev container of any project made from the template, or wherever uv is installed:
uvx copier copy gh:theAndreas/embedded-cpp-template LedMatrix
cd LedMatrix && git init && git add -A && git commit -m "LedMatrix: from the template"
make setup && make checkcopier asks for the name, the namespace, whether it is a library or a firmware, whether a library
is an Arduino library, the board or the part and the rest. The folder has to be named as the project: cpplint takes the header guards from
it. A further target is a name in TARGETS of tools/project.sh and what differs for it in
target_settings(); the file says how.
uv run copier update # to the newest version of the template
uv run copier update --vcs-ref v0.2.0copier remembers in .copier-answers.yml which version a project was made from. An update
renders that version and the new one, and applies the difference to the project as a three-way
merge: what the project changed itself stays, and a conflict is marked in the file as git marks
one. Commit before an update, review the diff after it, and run make check.
- The template's: the configuration, the
Makefile,tools/exceptproject.shandproject.mk,cmake/checks.cmakeand the toolchain files ofcmake/toolchains/,pyproject.tomlanduv.lock, the workflows and actions in.github/, the dev container,AGENTS.mdanddocs/. An update brings every change to them. A project may still change one: add its own exceptions at the end of a list in.clang-tidy, with the reason, and the merge keeps them. A job of its own goes into a workflow of its own. - The project's, never touched by an update:
README.md,CMakeLists.txt,library.properties,Doxyfile.project,.devcontainer/apt-packages.txt,tools/project.shandtools/project.mk, written where they do not exist yet; and the starting point of a new project,src/andtest/, the examplesBasicsandSelfCheckof a library orplatform/avr/of a firmware, written only bycopier copywith the answerskeleton. An update neither brings back what a project deleted of it nor merges into what it changed.
tools/project.sh is how the template's tools learn about the project: the board, the core, the
build variants and their flags, and hooks such as prepare(), which builds what compiling needs
beyond the core. tools/project.mk holds the project's own targets of the Makefile; one added to
PROJECT_CHECKS there is part of make check.
The template's Dependabot keeps its actions and uv.lock current; a project gets those updates
with copier update, not with a Dependabot of its own, so that the two never conflict.
A project that was not made from the template has no .copier-answers.yml yet. On a branch of
its own:
uvx copier copy --overwrite --data project_name=LedMatrix --data skeleton=false \
gh:theAndreas/embedded-cpp-template .
git diff # what the template would change--overwrite replaces the template's files; the project's are left alone where they exist, and
skeleton=false leaves out the starting point of a new library. Take over what is better,
restore what the project needs to keep, move what is the project's into tools/project.sh and
tools/project.mk, and commit with .copier-answers.yml. From then on copier update works.
The repository has a dev container of its own, built from the template's Dockerfile, so that it carries exactly what a project's does: see .devcontainer/README.md.
- Change the files in
template/. A file ending in.jinjais rendered with the answers ofcopier.yml; any other is copied as it is. tests/check.shmakes a project from the working tree and runs all of its checks. A single one runs faster:tests/check.sh lint tests.- Add what changed to
CHANGELOG.md, with what a project has to do on the update. - Merge, and tag the version:
git tag -a v0.2.0 && git push origin v0.2.0.copier updatetakes the newest tag.