Symbol visibility#
Every component is compiled with hidden symbol visibility; TANH_API (include/tanh/core/Exports.h, self-contained: it holds the dllexport/dllimport/visibility switch itself; tanh/core/ExportMacros.h is only a deprecated forwarding shim kept for one release) is the allowlist of what a shared component exports, and a shared component additionally pins its export table to namespace thl at link time (tanh_set_export_allowlist in cmake/tanh/symbol-policy.cmake). So libtanh_audio_io.so exports thl:: and nothing else — not miniaudio’s ma_*, not nlohmann::json, not moodycamel, not libstdc++ instantiations — and cannot be interposed against a host application that ships its own copy of any of those. A static component is compiled without export decoration (TANH_STATIC, defined for consumers through the CMake package), so a plugin that embeds it exports nothing of tanh-lib either. test/exports verifies both shapes in CTest on Linux, macOS and Windows.
Plugins should embed the static components. Sharing one libtanh_*.so between independently shipped plugins is only sound while every version carrying the same SONAME is ABI-compatible — the loader binds the first copy it sees to every later plugin — and every 0.x release has SOVERSION 0 without such a promise.
The ABI namespace#
Hidden visibility keeps a shared component’s internals out of the host’s export table, but it does not keep two copies of tanh-lib apart that end up in one link: a plugin’s static tanh-lib and the host’s own, or an embedder’s private core (anira compiles one into libanira) next to the application’s tanh-lib. Static archives are resolved by name, so without more the linker would pick one copy of thl::Logger::set_level for both sides; with different versions that is an ABI mismatch, with the same version the two sides share the logger’s state.
So every declaration lives in an inline namespace: each opener reads namespace thl::inline THL_ABI_NAMESPACE::core {, and thl::core::Logger is thl::v0_5::core::Logger to the compiler and the linker (_ZN3thl4v0_5… on ELF and Mach-O, …@v0_5@thl@@ on PE). Code keeps spelling thl::…; only the mangled names, debugger output and log symbolication show the namespace. Templates and inline functions in the headers are mangled with it too, so header-only code of two copies never merges either.
The value is
TANH_ABI_NAMESPACE:AUTO(the default) isv<major>_<minor>of the version from git, so every minor release changes every mangled name (normal for 0.x: consumers rebuild against a new release anyway, and two releases can now share a process). Any C++ identifier can be set instead.One source for it: the core’s
tanh_add_core_library()writes#define THL_ABI_NAMESPACE <value>into a generatedtanh/core/AbiNamespace.hin the library’s build tree, which is in the core’s public include directories and is installed with it. Every component compiles against the core’s header, and so does every consumer, in-tree or from the installed package; a header that does not match the library fails to link instead of binding silently.Objective-C class names are global to the process, so the namespace is pasted into them: the Net component’s download delegate is
TanhDownloadDelegate_<ns>.The remaining limit: miniaudio. AudioIO compiles miniaudio’s C sources as C++ (
src/audio-io/miniaudio_impl.cpp), so miniaudio’s functions are C++ symbols at global scope (ma_device_init(...)), outside any namespace. In a shared AudioIO they are hidden and stay inside it. Two copies of AudioIO in one static link (a host’s and a plugin’s tanh-lib, both with AudioIO) still define the samema_*symbols, and the linker resolves both copies’ miniaudio calls to one of them or reports duplicate symbols, as it did for all of tanh-lib before the namespace. The core and the other components are not affected; anira’s private core contains no miniaudio. The symbol check oftest/abi-namespaceallows thema_prefix for this reason.The same limit: pffft. With
TANH_FFT_BACKEND=pffft, DSP compiles pffft’s C sources in as C (cmake/fft-backend.cmake), sopffft_*andpffftd_*are unmangled C symbols at global scope. In a shared DSP they are hidden, and the linker drops them from its symbol table;test/exportsforbids thepffftprefix in the export table. Two copies of DSP in one static link (or DSP and another library that bundles pffft) define the same symbols, as with miniaudio.TANH_FFT_BACKEND=acceleratehas no such symbols.Consequences for consumers: code that forward-declares a tanh-lib type itself (
namespace thl { class State; }) declares a second, differentthl::State: where the tanh-lib header is seen too, the name is ambiguous (a compile error), and where it is not, a function taking it no longer links. Include the tanh-lib header instead.
A private core beside tanh_core#
cmake/core-library.cmake defines the core component, and tanh-lib’s own tanh_core is defined through it:
include(<tanh-lib>/cmake/core-library.cmake)
tanh_add_core_library(<target> SOURCE_DIR <tanh-lib> ABI_NAMESPACE <ns>
[STATIC | SHARED] [LOG_COMPILED_MAX_LEVEL <AUTO | 1..4>]
[WITH_JOURNALD] [ALIAS <name>])
It adds the core sources, include directories, public definitions, platform libraries, the symbol policy and the version properties, and generates the target’s own tanh/core/AbiNamespace.h. An embedder that needs a core no host can interfere with fetches tanh-lib under its own FetchContent name, without running tanh-lib’s top-level CMakeLists.txt, and builds its own copy in its own namespace:
FetchContent_Declare(anira_tanh_lib
GIT_REPOSITORY https://github.com/tanh-lab/tanh-lib.git
GIT_TAG <commit>
SOURCE_SUBDIR anira-uses-the-core-only) # populate only
FetchContent_MakeAvailable(anira_tanh_lib)
include(${anira_tanh_lib_SOURCE_DIR}/cmake/core-library.cmake)
tanh_add_core_library(anira_tanh_core
SOURCE_DIR ${anira_tanh_lib_SOURCE_DIR}
ABI_NAMESPACE anira
STATIC
LOG_COMPILED_MAX_LEVEL 4)
A parent that fetches tanh-lib itself (FetchContent_Declare(tanh-lib …), namespace v0_5) and the embedder’s anira_tanh_core (namespace anira) then coexist in one build and one process, in any link mode: they share no symbol and no state. The file has no include guard on purpose: each caller includes the copy of the tree it builds right before the call, so two tanh-lib trees in one build each use their own function. The function leaves sanitizers and install rules to the caller.
What this means when adding API#
Every class or free function a consumer uses needs
TANH_API. A missing decoration is a link error on every platform, not only on Windows.A type that is thrown or
dynamic_castacross the library boundary needsTANH_APIfor its typeinfo.A
staticorthread_localinside an inline function of an undecorated header template is duplicated per shared object. The RCU registry lives insrc/core/RCU.cppfor that reason.test/exportschecks the export table of every component, and of a plugin-shaped module that embeds the static components, in CTest.Open every namespace as
namespace thl::inline THL_ABI_NAMESPACE[::…] {, forward declarations included, and include<tanh/core/AbiNamespace.h>directly.scripts/abi-namespace.pyrewrites plain openers (re-run it after a rebase that brings in new files, then clang-format what it lists).test/abi-namespacechecks it in CTest on Linux, macOS and Windows:abi_namespace_symbols_<library>reads every symbol a library defines (nm, dumpbin) and fails on one ofthloutside the namespace, on a function of tanh-lib at global scope, or on one in a namespace that is neither tanh-lib’s nor a bundled library’s (what the toolchain defines is exempt: reserved names and the entities of reserved namespaces such as__gnu_cxxor RTSan’s__rtsan, libc++’s ABI-tagged functions such as Apple’s::absoverloads, the C++ overloads of the C library that MSVC’s<cmath>defines globally),abi_namespace_sourcesruns the script’s--check, andtest_abi_namespacelinks a second core library (tanh_core_b, namespacetest_b) besidetanh_coreand shows that their loggers keep separate levels, configurations and callbacks.