cpp-modules

C++20 モジュール

目的

C++20 モジュールの作成、ビルド、デバッグについて、名前付きモジュールとヘッダーユニットの違い、モジュールパーティション、CMake との統合、コンパイラー固有のフラグ、従来のヘッダーとの相互運用性をエージェントに案内します。

トリガー

• 「C++20 モジュールはどのように書けばよいですか？」
• 「CMake でモジュールをインポートするにはどうすればよいですか？」
• 「名前付きモジュールとヘッダーユニットの違いは何ですか？」
• 「モジュールで 'cannot find module' エラーが発生します」
• 「Clang で C++20 モジュールを使うにはどうすればよいですか？」
• 「ヘッダーからモジュールに移行するにはどうすればよいですか？」

ワークフロー

1. モジュールの概要

C++20 module kinds:
├── Named module interface unit  (.cppm / .ixx)  — exports declarations
├── Module implementation unit   (.cpp)           — defines module members
├── Module partition             (.cppm)          — internal module subdivision
└── Header unit                  (any header)     — import a legacy header as module

主な対象は名前付きモジュールです。ヘッダーユニットは従来のコードとの橋渡しとして使います。マクロへのアクセスが必要な場合を除き、グローバルモジュールフラグメントは避けてください。

2. 名前付きモジュール — 最小限の例

// math.cppm — module interface unit
export module math;          // declares the module name

export int add(int a, int b) { return a + b; }
export double pi = 3.14159;

// Non-exported (module-private)
int internal_helper() { return 42; }

// main.cpp — consumer
import math;                 // import the module
#include <iostream>          // legacy header (still works)

int main() {
    std::cout << add(2, 3) << "\n";  // 5
    std::cout << pi << "\n";
}

3. モジュールパーティション

// math-core.cppm — partition
export module math:core;     // partition 'core' of module 'math'

export int add(int a, int b) { return a + b; }

// math.cppm — primary module interface
export module math;
export import :core;         // re-export the partition

// math-impl.cpp — implementation unit (no export)
module math;                 // belongs to 'math' module, not a partition
// has access to all math declarations, but exports nothing

4. ヘッダーユニット — 従来のヘッダーとの橋渡し

// Import a standard library header as a module unit
import <iostream>;           // header unit (compiler generates BMI)
import <vector>;

// Or import a project header (must be compilable as header unit)
import "myheader.h";

ヘッダーユニットは、インポート側にマクロを提供しません。マクロにアクセスするには、グローバルモジュールフラグメントを使用します。

module;                      // Global Module Fragment starts here
#include <cassert>           // macros like assert() are available
export module mymod;
// ... rest of module

5. Clang でのビルド

# Compile module interface → produces .pcm (precompiled module)
clang++ -std=c++20 --precompile math.cppm -o math.pcm

# Compile implementation using the .pcm
clang++ -std=c++20 -fmodule-file=math=math.pcm -c math.cpp -o math.o

# Compile consumer
clang++ -std=c++20 -fmodule-file=math=math.pcm main.cpp math.o -o prog

6. GCC でのビルド

# GCC ≥11 supports modules (experimental ≥11, better ≥14)
# Compile interface unit → produces .gcm in gcm.cache/
g++ -std=c++20 -fmodules-ts math.cppm -c -o math.o

# Compiler auto-discovers .gcm files in gcm.cache/
g++ -std=c++20 -fmodules-ts main.cpp math.o -o prog

7. CMake との統合（CMake ≥3.28）

cmake_minimum_required(VERSION 3.28)
project(myproject LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)

add_library(math)
target_sources(math
    PUBLIC
        FILE_SET CXX_MODULES FILES    # module interface units
            src/math.cppm
            src/math-core.cppm
    PRIVATE
        src/math-impl.cpp             # implementation unit
)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE math)

# Requires a generator that supports modules (Ninja ≥1.11 or MSBuild)
cmake -S . -B build -G Ninja
cmake --build build

CMake 3.25～3.27 の場合（試験的機能）：

cmake_minimum_required(VERSION 3.25)
set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "3c375311-a3c9-4396-a187-3227ef642046")
set(CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP ON)

8. よくあるエラー

エラー	原因	修正方法
module 'math' not found	検索パスに BMI が見つからない	先にインターフェースユニットをコンパイルし、-fmodule-file= フラグを確認します
cannot import header in module	モジュールの領域内に #include がある	#include をグローバルモジュールフラグメントに移動するか、import <> を使います
redefinition of module 'math'	2 つの .cppm ファイルで同じモジュールを宣言している	各モジュールのプライマリインターフェースは 1 つだけにします
macro not available after import	マクロはモジュール境界を越えない	マクロに依存するコードを GMF に移動するか、#include を使います
ODR violation	複数のパーティションで同じ名前が使われている	各名前は 1 つのパーティションからのみエクスポートします
BMI cache stale	変更後に .pcm／.gcm が再ビルドされていない	ビルドをクリーンにするか、依存関係の追跡が機能していることを確認します

9. 従来のヘッダーとの相互運用

// Wrapping a C library for module use
export module cjson;

module;                       // Global Module Fragment
#include <cjson/cJSON.h>      // C header with macros

export module cjson;          // back to module purview

// Re-export key types (optional)
export using ::cJSON;
export using ::cJSON_Parse;

CMake のモジュールサポートの詳細については、references/modules-cmake-support.md を参照してください。

関連スキル

• モジュールの代替として PCH を使う場合は、skills/build-systems/build-acceleration を使います
• コンパイラー固有のモジュールフラグについては、skills/compilers/gcc または skills/compilers/clang を使います
• CMake プロジェクトの設定には、skills/build-systems/cmake を使います