importizer

Are you looking to convert your header-based C++ codebase to C++20 modules, but afraid that modularizing is too cumbersome? importizer is here to help.

This project uses semantic versioning.

Note: This project is currently going through a complete rewrite using LibTooling to replace Regex (pre-2.0.0). Much pre-2.0.0 code are gone, but releases & git history are preserved.

Table of Contents

• Why C++ modules?
  • Native modules
  • Wrapped modules
• Prebuilt binaries
• Configuration & usage
  • Command-line interface (CLI)
  • Configuration file (TOML)
  • Example configuration file
• Contributing

Why C++ modules?

• Improved encapsulation: Modules allow you to choose what is exposed to users (exported), no need to hide stuff with a detail namespace. Includes & macros from a module will only stay in that module.

• arewemodulesyet.org

Native modules

Native modules mean using modules internally. Some advantages of native modules are:

• Improved compilation time: Modules don’t need to be recompiled every time it is imported, unlike headers.

• No ordering issues: Modules are compiled in a strict dependency order, and `import`s can be ordered freely.

Wrapped modules

Wrapped modules mean exposing a modules interface by wrapping the underlying headers. Some advantages of wrapping modules are:

• Support modules with headers: Support a growing amount modules user while not breaking headers.

Prebuilt binaries

Importizer provides pre-compiled binaries for major operating systems. Necessary shared libraries are bundled directly in the distribution archive.

	Linux	MacOS	Windows
Architecture	AMD64, ARM64
Minimum OS	None	MacOS 15+	Windows 10+
Format (release)	zst(bin)
Format (debug)	tzst(trampoline + bin + .so)	tzst(bin + .dylib)	tzst(bin + .dll)

• Stable release: Download optimized release builds from the releases page.

• Bleeding edge (debug): Download unoptimized builds from the Continuous release. Useful for testing latest features or reporting bugs.

Configuration & usage

Importizer primarily uses a TOML configuration file, complemented by a few command-line options.

Command-line interface (CLI)

By default, running importizer looks for an importizer.yml file in the current working directory. You can override this by passing the path as a positional argument: importizer path/to/configuration.yml.

Option	Description
-h, --help	Display available options.
--help-list	Display list of available options.
--version	Display version.
-o, --outDir	Override the output directory specified in the configuration file

Configuration file (TOML)

All relative paths in the configuration file are resolved relative to the file’s location, not the current working directory.

Option	Type	Description
inDir	string	Required. The directory containing the source code to process.
outDir	string	Required (unless provided via CLI). The directory for the modularized output.
compilationDb	string	Path to a compile_commands.json compilation database to provide context.
explicit	object	See the Explicit mode section.

Explicit mode

importizer supports projects without a JSON compilation database via the explicit object. This can be the case for projects using a build system without JSON compilation database generation. explicit is mutually exclusive with if compilationDb.

Option	Type	Description	Default
globs	string array	Glob patterns to match code files names. Last match wins. Prefixing patterns with '!' negates them. See here for more info.	["!CMakeLists.txt"]
compileFlags	string array	Compile flags for globbed files	[]

Example configuration file

inDir: src
outDir: modular_src
# compilationDb: build/compile_commands.json

explicit:
  globs:
    - !CMakeLists.txt
    - !Makefile
  compileFlags:
    - -Iinclude
    - -Ithird_party/libs
    - -DNDEBUG

Contributing