[WIP] Support installation of C++20 modules (with non-ROOT functionality)

[wdconinc]

This PR aims to add C++20 modules support to allow data models to be provided as compile-once binary modules, and used as:

import podio.core;
import edm4hep.datamodel;
edm4hep::MCParticle mcp;

without needing to include (and process) headers in all translation units.

The ROOT (and, presumably, SIO) headers are not ready to support modules, so they are excluded here (modules and headers can be mixed in user code downstream). A single podio.core module is provided here, and it is tested with the example data models which each create a module as well.

Modules cannot include TU-local entities (translation-unit local). That is the reason for the changes from static inline to inline in several of the cases here. In the case of ROOT, the core headers include TU-local entities, so they cannot be included in any headers used in a module. The same is true for Python.h, so the implementation of the pythonization had to move from a header to an implementation file.

BEGINRELEASENOTES

• Support C++20 modules: podio.core and creation of module for data models

ENDRELEASENOTES

(with help from copilot)

[tmadlener]

Very nice, thanks a lot for this. I have left a few comments / questions below, that probably mostly demonstrate that I simply don't know enough about modules (yet). As a very general question, I wonder whether it should be mandated at the podio level whether a datamodel is built with module support or not, or whether we would like to give downstream consumers the ability to choose. IIUC, it should at least be possible to build the datamodel without modules even if podio is built with modules, but not the other way around?

For backend support, I suppose we will need to have the backend with module support first? E.g. once ROOT has module support, we can also start to export a podio.root_io (or similar) module.

---

changes from static inline to inline in several of the cases here

This seems to be what we should have probably done from the beginning in any case, as far as I can tell. Again from a quick glance at the commits, it doesn't look entirely trivial to factor that out into a separate PR, right?

[tmadlener]

I am wondering whether this should be an explicit argument to the datamodel generation. For my understanding: This requires podio.core to be available as a module? Or would it still be possible to have podio built without modules and have the datamodel compiled into a module?

[wdconinc]

Right now the data model module definition (from python/templates/datamodel_module.ixx.jinja2) uses just regular includes, not another module import. That means that it is not necessary to have a podio.core module in order to use the edm4hep.datamodel module.

The only thing from podio that is re-exported is:

export namespace podio {
  using podio::CollectionBase;
  using podio::ICollectionProvider;
  using podio::SchemaEvolution;
  using podio::SchemaVersionT;
}

That is significantly less than what's in src/podio_core_module.ixx which turns into the podio.core module.

As long as we don't re-export a different entity under the same name this is fine. They are ultimately just using statements.

[tmadlener]

I suppose we don't have a build already with a recent enough clang that we could simply test drive as well?

[wdconinc]

I think clang itself is recent enough (19 should work) but I think lcg has clang setup with the GCC libstdc++ instead of clang's libc++. That makes it harder. But I haven't really tried much to make it work.

[tmadlener]

OK, let's see if @andresailer has a special LCG stack that would make this easy.

[wdconinc]

I wonder whether it should be mandated at the podio level whether a datamodel is built with module support or not, or whether we would like to give downstream consumers the ability to choose. IIUC, it should at least be possible to build the datamodel without modules even if podio is built with modules, but not the other way around?

Modules are not actually built (in the binary sense) by the podio or data model build. All the build does is build (in the templating engine sense) the source code for the module. It remains up to the consumer downstream (the project that currently includes data model headers) to build and use the module.

That means that podio can always generate the module code for a data model, regardless of support in the compiler that is being used. But that module code can only be tested with a compiler that supports using modules.

So, I could imagine that module code is generated and installed by default.

[wdconinc]

For backend support, I suppose we will need to have the backend with module support first?

The backends primarily need to have headers that can be included in modules. It is sufficient for podio if only the used headers are module safe. Primarily that means removing TU-local entities from e.g. TObject.h. That may be an easier ask, and podio may be a convenient project to start this discussion with ROOT since the scope is well-defined.

[tmadlener]

I am planning to make a new podio tag (v01-07), so that we can also create an EDM4hep v1.0. I would keep this out of that tag, but we can always make another one after that (i.e. v01-08).

[wdconinc]

Rebased with #908 and #909.

[wdconinc]

Fails pre-commit with error: module 'podio.core' not found [clang-diagnostic-error].

[wdconinc]

This may not be necessary... Revisit.

[wdconinc]

This feature is complete and functional but limited in the CI test in two ways:

• using modules for unit tests is not currently possible since catch2 is not compatible (requires import std),
• it seems that cppcheck and clang-tidy in pre-commit are having trouble with this (not sure why for clang-tidy).

In any case, I'll mark as ready for review and see what copilot has to say about this.

[Copilot]

Pull request overview

This PR introduces experimental C++20 modules support to podio, allowing datamodels to be compiled as binary modules for faster compilation times. The implementation provides a podio.core module exporting ROOT-independent core functionality and generates datamodel-specific modules (e.g., datamodel.datamodel). Module support is optional and controlled via the PODIO_ENABLE_CXX_MODULES CMake option, with automatic fallback to traditional headers when requirements (CMake 3.29+, Ninja generator, GCC 14+/Clang 18+) are not met.

Key changes:

• New podio.core module interface exporting core types without ROOT dependencies
• Auto-generated datamodel module interfaces via Jinja2 templates
• CMake infrastructure for module generation, compilation, and installation
• Threading support changed from -pthread compile option to Threads::Threads target for better portability
• Comprehensive documentation of module usage, requirements, and limitations

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tests/test_module_import.cpp	New standalone test validating module imports and basic operations without Catch2 dependency
tests/CMakeLists.txt	Test setup for module import test (requires CMake 3.30+ for direct import in .cpp files)
src/podio_core_module.ixx	C++20 module interface exporting ROOT-independent podio core types and utilities
src/CMakeLists.txt	Integration of podio.core module, improved threading support using Threads::Threads target
src/Pythonizations.cc	Whitespace fix (trailing whitespace removal)
python/templates/datamodel_module.ixx.jinja2	Jinja2 template for generating datamodel-specific module interfaces
python/templates/CMakeLists.txt	Registration of new datamodel_module.ixx.jinja2 template
python/podio_gen/generator_utils.py	New qualified_for_modules() method for generating properly qualified C++ names in module exports
python/podio_gen/cpp_generator.py	Module generation logic including _write_datamodel_module() and enable_modules parameter
python/podio_class_generator.py	CLI argument --enable-modules to control module generation
doc/modules.md	Comprehensive documentation covering requirements, usage, architecture, and troubleshooting
cmake/podioModules.cmake	Core CMake infrastructure for module support including version/compiler checks and utility functions
cmake/podioMacros.cmake	Integration of module generation into PODIO_GENERATE_DATAMODEL and PODIO_ADD_DATAMODEL_CORE_LIB
cmake/podioConfig.cmake.in	Added Threads dependency for downstream projects
CMakeLists.txt	Include podioModules.cmake to enable module support infrastructure
.github/workflows/test.yml	Enable module testing on GCC 15 builds
.github/workflows/pre-commit.yml	Explicitly disable modules for pre-commit checks

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.