Make header-only builds work from any number of translation units

CMakeLists.txt

@@ -8,6 +8,7 @@ option(INTEGRATORXX_HEADER_ONLY "Force header-only build" OFF)
 if(INTEGRATORXX_HEADER_ONLY)
   add_library( integratorxx INTERFACE )
   set(INTEGRATORXX_TARGET_TYPE INTERFACE)
+  target_compile_definitions( integratorxx INTERFACE INTEGRATORXX_HEADER_ONLY )
 else()
   add_subdirectory(src)
   set(INTEGRATORXX_TARGET_TYPE PUBLIC)

README.md

@@ -152,15 +152,23 @@ avoid excessive build times in complex projects with aggressive compiler
 optimization. **N.B. it is highly recommend that users maintain this default
 behavior to avoid excessive compilation sizes and build times**.
 
-IntegratorXX also allows for header-only use of the runtime generator by 
-setting `INTEGRATORXX_HEADER_ONLY=ON`. 
-This feature also allows for circumvention of
-the CMake build system by simply including the requisite implementation
-header.
-
-To use the runtime generator header-only, one needs to include 
-`<integratorxx/generators/impl/impl.hpp>` **exactly once** per project,
-otherwise duplicate / incompatible symbols will occur.
+IntegratorXX also allows for header-only use of the runtime generator by
+setting `INTEGRATORXX_HEADER_ONLY=ON`, which defines the
+`INTEGRATORXX_HEADER_ONLY` macro on the interface target. The public
+generator headers then carry their own implementations, so no additional
+include is required.
+
+To circumvent the CMake build system entirely, define
+`INTEGRATORXX_HEADER_ONLY` yourself and include the generator headers as
+usual. The implementations have inline linkage in this mode and may be
+included from any number of translation units.
+
+The choice has to be consistent across the whole link: define
+`INTEGRATORXX_HEADER_ONLY` in every translation unit, and do not also link
+the compiled library. A translation unit compiled without it sees only the
+declarations, so linking it against `libintegratorxx` while other translation
+units carry the inline definitions gives the same functions two definitions
+with different linkage, which is an ODR violation.
 
 ## Contributing and Bug Reports
 

include/integratorxx/generators/impl/impl.hpp

@@ -1,3 +1,5 @@
+#pragma once
+
 #include <integratorxx/generators/impl/unpruned_grid.hpp>
 #include <integratorxx/generators/impl/pruned_grid.hpp>
 #include <integratorxx/generators/impl/radial_factory.hpp>

include/integratorxx/generators/impl/pruned_grid.hpp

@@ -58,7 +58,7 @@ auto make_pruned_grid(const RadialQuadType& rq,
 
 } // Implementation Details
 
-SphericalGridFactory::spherical_grid_ptr 
+INTEGRATORXX_GENERATOR_LINKAGE SphericalGridFactory::spherical_grid_ptr 
   SphericalGridFactory::generate_pruned_grid( RadialQuad rq, 
   const RadialTraits& traits, 
   const std::vector<PruningRegion>& pruning_regions) { 
@@ -83,7 +83,7 @@ SphericalGridFactory::spherical_grid_ptr
 }
 
 
-PrunedSphericalGridSpecification create_pruned_spec(
+INTEGRATORXX_GENERATOR_LINKAGE PrunedSphericalGridSpecification create_pruned_spec(
   PruningScheme scheme, UnprunedSphericalGridSpecification unp
 ) {
 

include/integratorxx/generators/impl/radial_factory.hpp

@@ -7,7 +7,7 @@
 
 namespace IntegratorXX {
 
-RadialQuad radial_from_string(std::string name) {
+INTEGRATORXX_GENERATOR_LINKAGE RadialQuad radial_from_string(std::string name) {
   std::transform(name.begin(), name.end(), name.begin(),
     [](unsigned char c){ return static_cast<char>(std::toupper(c)); });
   if(name == "BECKE")             return RadialQuad::Becke;
@@ -21,7 +21,7 @@ RadialQuad radial_from_string(std::string name) {
   throw std::runtime_error("Unrecognized Radial Quadrature");
 }
 
-RadialFactory::radial_grid_ptr RadialFactory::generate(RadialQuad rq, const RadialTraits& traits) {
+INTEGRATORXX_GENERATOR_LINKAGE RadialFactory::radial_grid_ptr RadialFactory::generate(RadialQuad rq, const RadialTraits& traits) {
 
   switch(rq) {
     case RadialQuad::Becke:

include/integratorxx/generators/impl/robust_pruning.hpp

@@ -24,7 +24,7 @@ auto get_robust_low_med_sizes(AngularSize asz) {
 }
 
 
-PrunedSphericalGridSpecification robust_psi4_pruning_scheme_impl(
+INTEGRATORXX_GENERATOR_LINKAGE PrunedSphericalGridSpecification robust_psi4_pruning_scheme_impl(
   size_t low_sz, size_t med_sz, AngularQuad angular_quad, 
   UnprunedSphericalGridSpecification unp ) {
 
@@ -46,7 +46,7 @@ PrunedSphericalGridSpecification robust_psi4_pruning_scheme_impl(
 } // Implementation Details
 
 
-PrunedSphericalGridSpecification robust_psi4_pruning_scheme(
+INTEGRATORXX_GENERATOR_LINKAGE PrunedSphericalGridSpecification robust_psi4_pruning_scheme(
   UnprunedSphericalGridSpecification unp ) {
 
   size_t low_sz, med_sz;

include/integratorxx/generators/impl/s2_factory.hpp

@@ -7,7 +7,7 @@
 
 namespace IntegratorXX {
 
-AngularQuad angular_from_string(std::string name) {
+INTEGRATORXX_GENERATOR_LINKAGE AngularQuad angular_from_string(std::string name) {
   std::transform(name.begin(), name.end(), name.begin(),
     [](unsigned char c){ return static_cast<char>(std::toupper(c)); });
   if(name == "AHRENSBEYLKIN") return AngularQuad::AhrensBeylkin;
@@ -21,7 +21,7 @@ AngularQuad angular_from_string(std::string name) {
   throw std::runtime_error("Unrecognized Angular Quadrature");
 }
 
-S2Factory::s2_grid_ptr S2Factory::generate(AngularQuad aq, size_t npts) {
+INTEGRATORXX_GENERATOR_LINKAGE S2Factory::s2_grid_ptr S2Factory::generate(AngularQuad aq, size_t npts) {
 
   switch(aq) {
     case AngularQuad::AhrensBeylkin:

include/integratorxx/generators/impl/treutler_pruning.hpp

@@ -16,7 +16,7 @@ auto get_treutler_low_med_sizes() {
   return std::make_pair(low_sz, med_sz);
 }
 
-PrunedSphericalGridSpecification treutler_pruning_scheme_impl(
+INTEGRATORXX_GENERATOR_LINKAGE PrunedSphericalGridSpecification treutler_pruning_scheme_impl(
   size_t low_sz, size_t med_sz, AngularQuad angular_quad, 
   UnprunedSphericalGridSpecification unp ) {
 
@@ -39,7 +39,7 @@ PrunedSphericalGridSpecification treutler_pruning_scheme_impl(
 
 
 
-PrunedSphericalGridSpecification treutler_pruning_scheme(
+INTEGRATORXX_GENERATOR_LINKAGE PrunedSphericalGridSpecification treutler_pruning_scheme(
   UnprunedSphericalGridSpecification unp ) {
 
   size_t low_sz, med_sz;

include/integratorxx/generators/impl/unpruned_grid.hpp

@@ -37,7 +37,7 @@ auto generate_unpruned_grid_impl(RadialQuad rq, const RadialTraits& traits,
 
 } // Implementation details
 
-SphericalGridFactory::spherical_grid_ptr 
+INTEGRATORXX_GENERATOR_LINKAGE SphericalGridFactory::spherical_grid_ptr 
   SphericalGridFactory::generate_unpruned_grid( RadialQuad rq, 
   const RadialTraits& traits, AngularQuad aq, AngularSize nang) {
 

include/integratorxx/generators/radial_factory.hpp

@@ -76,3 +76,10 @@ struct RadialFactory {
 };
 
 }
+
+// Header-only builds carry the implementation with the declarations. This is
+// included last so that the declarations above are already visible; the impl
+// headers include this one back, which #pragma once makes a no-op.
+#ifdef INTEGRATORXX_HEADER_ONLY
+#include <integratorxx/generators/impl/radial_factory.hpp>
+#endif

include/integratorxx/generators/s2_factory.hpp

@@ -39,3 +39,10 @@ struct S2Factory {
 };
 
 }
+
+// Header-only builds carry the implementation with the declarations. This is
+// included last so that the declarations above are already visible; the impl
+// headers include this one back, which #pragma once makes a no-op.
+#ifdef INTEGRATORXX_HEADER_ONLY
+#include <integratorxx/generators/impl/s2_factory.hpp>
+#endif

include/integratorxx/generators/spherical_factory.hpp

@@ -188,3 +188,11 @@ struct SphericalGridFactory {
 };
 
 }
+
+// Header-only builds carry the implementation with the declarations. This is
+// included last so that the declarations above are already visible; the impl
+// headers include this one back, which #pragma once makes a no-op.
+#ifdef INTEGRATORXX_HEADER_ONLY
+#include <integratorxx/generators/impl/unpruned_grid.hpp>
+#include <integratorxx/generators/impl/pruned_grid.hpp>
+#endif

include/integratorxx/quadrature.hpp

@@ -7,6 +7,22 @@
 #include <utility>
 #include <integratorxx/type_traits.hpp>
 
+/**
+ *  @brief Linkage of the runtime grid generator.
+ *
+ *  By default the runtime generator is compiled once into libintegratorxx and
+ *  consumers see only the declarations in generators/*.hpp, which keeps the
+ *  large angular grid dispatch out of every translation unit. When
+ *  INTEGRATORXX_HEADER_ONLY is defined the same definitions are emitted inline
+ *  in each translation unit that uses them, and the public generator headers
+ *  pull in their own implementations.
+ */
+#ifdef INTEGRATORXX_HEADER_ONLY
+#define INTEGRATORXX_GENERATOR_LINKAGE inline
+#else
+#define INTEGRATORXX_GENERATOR_LINKAGE
+#endif
+
 namespace IntegratorXX {
 
 // Forward decl of quadrature traits

test/CMakeLists.txt

@@ -23,15 +23,14 @@ else()
 endif()
 
 add_library(integratorxx_common_ut quad_matcher.cxx)
-if(INTEGRATORXX_HEADER_ONLY)
-  target_sources(integratorxx_common_ut PRIVATE lib_impl.cxx)
-endif()
 target_link_libraries( integratorxx_common_ut PUBLIC Catch2::Catch2WithMain integratorxx )
 
 add_executable( quadrature_manipulation quadrature_manipulation.cxx )
 target_link_libraries( quadrature_manipulation PUBLIC integratorxx_common_ut )
 
-add_executable( spherical_generator spherical_generator.cxx )
+# generator_second_tu.cxx only includes the generator headers: it is here so
+# that a header-only build links two TUs that carry the implementations.
+add_executable( spherical_generator spherical_generator.cxx generator_second_tu.cxx )
 target_link_libraries( spherical_generator PUBLIC integratorxx_common_ut )
 
 add_executable( 1d_quadratures 1d_quadratures.cxx )

test/generator_second_tu.cxx

@@ -0,0 +1,16 @@
+// A second translation unit that includes the generator headers, so that the
+// property this executable exists to check -- that a header-only build links
+// from any number of translation units -- is actually exercised. In header-only
+// mode these headers carry their own definitions, and any definition that loses
+// its inline linkage collides with spherical_generator.cxx at link time.
+//
+// This has to sit in the executable rather than in integratorxx_common_ut: an
+// object in a static library is pulled in only when something references it, so
+// a duplicate definition there would go unnoticed.
+//
+// Including the headers is the whole test. A non-inline function with external
+// linkage is emitted whether or not it is called, so no reference is needed.
+
+#include <integratorxx/generators/spherical_factory.hpp>
+#include <integratorxx/generators/radial_factory.hpp>
+#include <integratorxx/generators/s2_factory.hpp>