importizer

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

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 and git history are preserved.

Table of Contents

• Native modules
• Wrapped modules
• Installation
• Configuration and usage
  • Command-line interface (CLI)
  • Configuration file (YAML)
  • Example configuration file

Native modules

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

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

• Better encapsulation: Modules allow you to choose what is exposed to users (exported), no need to hide stuff with a detail namespace. Includes and macros from a module won’t leak.

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

Wrapped modules

Wrapped modules mean exposing a modules interface by wrapping the underlying headers. They allow supporting of a growing modules user base while not breaking headers.

Installation

Distribution of binary (bin) for major operating systems and architectures. Required shared libraries, if applicable, are bundled within the archive.

	Linux	MacOS	Windows
Architecture	AMD64, ARM64
Minimum OS	None	MacOS 15+	Windows 10+
Release distribution format	bin
Debug distribution format	tar.zst(trampoline + bin + .so)	tar.zst(bin + .dylib)	tar.zst(bin + .dll)

• Stable release: Download versioned builds from the releases page, latest version recommended.

• Bleeding edge: Download "nightly" builds from the continuous release.

Configuration and usage

Importizer primarily uses a YAML configuration file, along 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.
-w, --write	Actually rewrite files. Without this flag importizer does everything else but that. It’s useful for validating configuration, see if your project is modularizable, and see a summary of what will change.

Configuration file (YAML)

Relative paths in the configuration file are resolved relative to the file’s location, not the current working directory. For globs, it’s always:

• First match wins.

• Prefixing patterns with ! negates them.

• See here for more info.

Option	Type	Description
root	string	Required. Root of the project to run importizer on. Globs are resolved through this.
hdrGlobs	string array	Required. Glob patterns to match header files to be modularized.
compilationDB	string	Path to a compile_commands.json compilation database to provide context.
explicit	object	See the Explicit mode section.
stdImport	boolean	Replace C++ headers inclusion with import std; and if C wrappers headers are used, std.compat.

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 compilationDB but at least one of them must be specified.

Option	Type	Description
srcGlobs	string array	Required. Glob patterns to match source files to be modularized.
compileFlags	string array	Compile flags for source files. Defaults to [].

Example configuration file

root: .
hdrGlobs:
  - src/**.hh
# compilationDB: build/compile_commands.json
explicit:
  srcGlobs:
    - src/**.cc
  compileFlags:
    - -I3rd-party/clang/include
    - -I3rd-party/llvm/include
    - -I3rd-party/doctest/include