Runtime instantiantion details

All shipped instantiations are compiled into translation units listed in the src directory.

Baseline only

The shipped set is a pay-once baseline for select configurations (e.g the 2D/3D kernels baseline, transformation strategies), pre-compiled into the .so and suppressed in consumers via extern template. It is not a closed enumeration of every ReactionData x ReactionKernels x DataCalculator combination — the library’s open-combinatorial design intentionally pushes non-baseline compositions onto the consumer, which compiles them from headers.

Instantiating unsupported combinations

The library only ships with a few combinations but every other combination is still open.

If they’re needed then: include the public headers (via #include <reactions/reactions.hpp>), and rely on implicit instantiation in the consumer TU.

Alternatively, after defining a template struct/class in a .hpp file, add an extern template class … declaration to it, add the corresponding template class … explicit instantiation in a dedicated .cpp.

In the public headers, an example would be, vranic_merging_kernels.hpp which includes a template struct definition and extern template class declarations. The corresponding explicit template instantiations live in vranic_merging_kernels.cpp.

Adding to this framework is really only feasible if at least a few of the template instantiations of the templated objects are known. For example, this would not be fully applicable if using template parameter packs, where only a subset of all possible combinations in that case might be known and could be added. In that case, it’s recommended to simply lean on implicit instantiation in the consumer TUs that may use it.

Verifying the installed library

A standalone CMake project lives at test/external_consumer/ that configures against only the installed tree via find_package(VANTAGE-Reactions), links the installed library, and ODR-uses (via a null pointer) every shipped template instantiation. Therefore if any new instantiations are added to the shipped set then be sure to add their usage to test/external_consumer/consumer_smoke.cpp.

Each ODR-use forces the consumer TU to respect the matching extern template declaration and let the library provide the definition, so a missing instantiation surfaces as an unresolved symbol at link time. It is intended to be run as a post-install smoke test to confirm the runtime library is genuinely linkable without the source tree. To test it, install and load VANTAGE-Reactions via spack install && spack load vantagereactions, then from the repo directory configure and build it via

cmake -S test/external_consumer -B build-consumer -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build-consumer
./build-consumer/consumer_smoke