Contributing#
Development setup#
git clone git@github.com:tanh-lab/tanh-lib.git
cd tanh-lib
just build # cmake --preset desktop-debug && build
just test # + ctest
just (just --list) wraps the everyday recipes: format /
format-check, tidy / tidy-fix, test-filter PATTERN,
test-install, docs and the iOS configure/build recipes.
Naming conventions#
Enforced by .clang-tidy.
Classes/structs/enums/unions:
PascalCaseMethods/functions:
snake_caseMember variables:
m_prefix +snake_case, e.g.m_frequency_rangeLocal variables/parameters:
snake_caseConstants (
constexpr,static const, globalconst):k_prefix +snake_case, e.g.k_max_grainsEnum values:
PascalCase, e.g.ResonatorModal,LFOWaveform::SineMacros:
ALL_CAPS_WITH_UNDERSCORES, e.g.TANH_NONBLOCKING_FUNCTIONFolders:
kebab-case, e.g.audio-ioJSON keys exposed to JS/TS:
camelCase— C++ code emitting JSON for the JS bridge must use camelCase keys to match the TypeScript interfaces
Code style#
.clang-format (Google-based: 100-character lines, 4-space indent, K&R
braces) and .clang-tidy are enforced in the merge queue; clang-tidy
already checks the .cpp files a pull request changes (see CI).
Namespaces open with the ABI namespace (Symbol visibility), forward declarations included, and the file includes the header that defines it:
#include <tanh/core/AbiNamespace.h>
namespace thl::inline THL_ABI_NAMESPACE::dsp::utils {
...
} // namespace thl::inline THL_ABI_NAMESPACE::dsp::utils
scripts/abi-namespace.py rewrites plain namespace thl… openers and
their closing comments and adds the include; it is idempotent, so re-run it
after a rebase that brings in new files and clang-format the files it lists.
CTest runs its --check (abi_namespace_sources).
Tests#
test/ mirrors the components: test/core, test/state, test/dsp,
test/modulation and test/audio-io each build one test_* binary, and
test/exports, test/abi-namespace and test/install check the
packaging contracts. test/core builds a second binary,
test_core_allocation: it replaces the global operator new and
operator delete to count the allocations of a call and to make each one fail
in turn, and belongs to no ThreadSanitizer, LeakSanitizer or MemorySanitizer
build, whose runtimes define those operators themselves. Run one suite directly:
./build/desktop/Debug/test/dsp/test_dsp --gtest_filter="TestSuite.TestName"
The Rings resonator tests compare against reference fixtures that are not checked in; without them those tests are skipped (see Getting Started).
Every process() path is covered by the RealtimeSanitizer preset; see
Real-Time Safety.
CI#
Pull requests run a fast tier, the merge queue runs every leg, and a change
reaches main through the queue only:
Pull request: the
"pr": truelegs of the desktop build and test matrix (.github/build_test_matrix.json), iOS and Android, the WebAssembly build, and clang-tidy over the.cppfiles the pull request changes. The checks that only run in the queue (the install-tree consumer, the sanitizers, clang-format, the tanh-tooling drift check, the docs build) report an instant stub, so that every required status is there.Merge queue: every desktop leg, iOS and Android, the WebAssembly build, the install-tree consumer, the sanitizer presets, clang-format, the tanh-tooling drift check, the docs build, the full clang-tidy sweep, and the coverage run (uploaded to Codecov; not a required status).
Push to main: the docs are deployed and the compile caches warmed. Both have to follow the merge: the site shows what
mainis, and a cache can be restored from other branches only when it was written on the default branch.
All workflows call the shared actions in tanh-lab/ci-actions and must pin
the same version; build_test’s result job asserts that.
clang-tidy#
clang_tidy result is a required status. CI runs clang-tidy 20 with every
warning as an error over the translation units of the Linux desktop-debug
build under src/ and test/ (the entries of its
compile_commands.json; a source that only another platform compiles is not
checked there). A pull request checks the .cpp files it changes, and all of
them when it changes .clang-tidy or the workflow; the merge queue always
checks all of them. A header change does not widen a pull request’s set, so
what it breaks in a .cpp file the pull request did not touch fails in the
queue: after a header change, run clang-tidy on the files that include it, or
sweep the branch by starting the clang_tidy workflow by hand.
Documentation#
Document public API with Doxygen comments (
///or/** */); the API Reference is generated frominclude/tanh/on every push tomain.Design notes and guides live under
docs/sphinx/(reST or Markdown, both render); the README stays a short entry point that links here. The changelog page and the CMake options table are included fromCHANGELOG.mdandREADME.md, so keep those headings.Build locally with
just docsand openbuild/docs/docs/sphinx/html/index.html.
Changelog#
CHANGELOG.md follows Keep a Changelog. Add an entry under Unreleased
with every user-visible change, in the same style as the existing entries:
what changed, why, and what a consumer has to do about it.