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: PascalCase

  • Methods/functions: snake_case

  • Member variables: m_ prefix + snake_case, e.g. m_frequency_range

  • Local variables/parameters: snake_case

  • Constants (constexpr, static const, global const): k_ prefix + snake_case, e.g. k_max_grains

  • Enum values: PascalCase, e.g. ResonatorModal, LFOWaveform::Sine

  • Macros: ALL_CAPS_WITH_UNDERSCORES, e.g. TANH_NONBLOCKING_FUNCTION

  • Folders: kebab-case, e.g. audio-io

  • JSON 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).

Shared tooling#

just format / just format-check run clang-format, just tidy / just tidy-fix run clang-tidy. Their configs — .clang-format, .clang-tidy, .clangd in the repository root — and the CMake modules under cmake/tanh/ (platform detection, the symbol-export policy and its CTest check, git versioning, sanitizers, googletest/benchmark, Apple defaults, the iOS toolchain, CPack, install RPATHs, binary data, the compile-database link) are shared across the tanh-lab projects and are not maintained here: they are installed verbatim from a pinned release of tanh-tooling (canonical copies in its clang/ and cmake/ directories, documented in its cmake/README.md). Do not edit them by hand and do not add files to cmake/tanh/; the tooling-config CI job re-downloads the pinned release and fails if the committed files differ. Changes belong in tanh-tooling.

To move to a newer tanh-tooling release, run its installer with the new tag, commit the rewritten files, and bump the ref (and workflow version) in .github/workflows/lint.yml to the same tag in the same commit. anira pins the same modules and fetches tanh-lib, so both repositories must move to the same tag together:

curl -fsSL https://raw.githubusercontent.com/tanh-lab/tanh-tooling/vX.Y.Z/install.sh | sh -s -- clang cmake

clangd reads build/compile_commands.json (.clangd). The development presets (desktop-*, macos-x64-*, android-*, wasm-release) set TANH_LINK_COMPILE_COMMANDS=ON, so each configure of one of them links its tree’s database there, and clangd follows the tree configured last: configure wasm-release to see the Emscripten branches, desktop-debug to go back. The sanitizer, coverage, Windows and iOS presets leave the link alone (the Visual Studio and Xcode generators write no database). The wasm tree compiles with em++, which adds the wasm target and the emsdk sysroot itself; start clangd with --query-driver=**/em++ so it asks em++ for them (a command-line flag only, since it lets clangd run the compiler).

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": true legs of the desktop build and test matrix (.github/build_test_matrix.json), iOS and Android, the WebAssembly build, and clang-tidy over the .cpp files 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 main is, 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 from include/tanh/ on every push to main.

  • 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 from CHANGELOG.md and README.md, so keep those headings.

  • Build locally with just docs and open build/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.