모듈을 쓰면 헤더를 완전히 없앨 수 있나요?

점진적 이행이 일반적입니다. 기존 라이브러리가 헤더만 제공하면 브리지가 필요하고, 툴체인 지원도 확인해야 합니다.

빌드 시간이 얼마나 줄어드나요?

파싱 중복이 줄어 이론상 이득이 큽니다. 실제로는 프로젝트 구조·컴파일러 버전에 따라 다르므로 측정이 필요합니다.

export할 단위는 어떻게 나누나요?

공개 API 경계를 모듈 인터페이스로 두고, 내부 구현은 별도 모듈로 숨깁니다. 순환 의존을 피하는 것이 헤더 때와 동일하게 중요합니다.

CMake에서 모듈을 쓰려면?

컴파일러 플래그·파일 확장·스캔 규칙을 맞춰야 합니다. 최신 CMake와 예제 프로젝트를 참고해 팀 툴체인에서 검증하세요.

C++20 Modules 완벽 가이드 | 헤더 파일을 넘어서

2026년 3월 12일 · 19분 읽기 · 수정 2026년 3월 12일 고급 튜토리얼

이 글의 핵심

C++20 Modules 완벽 가이드에 대한 실전 가이드입니다. 헤더 파일을 넘어서 등을 예제와 함께 상세히 설명합니다.

C++20 Modules란? 왜 필요한가

문제 시나리오: 헤더 파일의 고통

문제 1: 중복 컴파일
<iostream>을 100개 파일에서 #include하면, 전처리기가 100번 iostream 헤더를 파싱합니다. 대형 프로젝트에서는 같은 헤더를 수천 번 파싱해 빌드 시간이 수십 분으로 늘어납니다.

문제 2: 매크로 오염
#define MAX 100을 헤더에 쓰면, 이 헤더를 include한 모든 파일에서 MAX가 정의됩니다. 다른 라이브러리의 MAX와 충돌하면 디버깅이 지옥입니다.

문제 3: include 순서
헤더 A가 헤더 B에 의존하면, #include "B.h" → #include "A.h" 순서로 써야 합니다. 순서가 바뀌면 컴파일 에러가 나고, 순서를 맞추는 것이 번거롭습니다.

해결: C++20 Modules는 헤더 파일을 대체하는 새로운 모듈 시스템입니다. 모듈은 한 번만 컴파일되고, 매크로가 격리되며, import 순서가 자유롭습니다. 빌드 시간이 크게 단축되고, 코드가 깔끔해집니다.

flowchart TD
    subgraph header["헤더 방식"]
        h1["main.cpp #include iostream"]
        h2["utils.cpp #include iostream"]
        h3["config.cpp #include iostream"]
        parse1["iostream 파싱 3번"]
    end
    subgraph module["모듈 방식"]
        m1["main.cpp import std"]
        m2["utils.cpp import std"]
        m3["config.cpp import std"]
        parse2["std 모듈 컴파일 1번"]
    end
    h1 --> parse1
    h2 --> parse1
    h3 --> parse1
    m1 --> parse2
    m2 --> parse2
    m3 --> parse2

1. 기본 문법: export, import

최소 모듈

math.cppm (모듈 인터페이스 파일):

export module math;

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

export int multiply(int a, int b) {
    return a * b;
}

// export 없음 → private
int helper() {
    return 42;
}

main.cpp:

import math;
import <iostream>;

int main() {
    std::cout << add(3, 4) << '\n';      // 7
    std::cout << multiply(5, 6) << '\n'; // 30
    // helper();  // Error: not exported
}

export 문법

export module mymodule;

// 개별 export
export int func1() { return 1; }
export int func2() { return 2; }

// 그룹 export
export {
    int func3() { return 3; }
    int func4() { return 4; }
}

// 클래스 export
export class MyClass {
public:
    void method();
};

// 네임스페이스 export
export namespace mylib {
    int helper() { return 0; }
}

// 타입 별칭 export
export using MyInt = int;

// 템플릿 export
export template<typename T>
T max(T a, T b) {
    return (a > b) ? a : b;
}

2. 모듈 파티션

파티션으로 모듈 분할

큰 모듈을 여러 파일로 나눌 때 파티션을 사용합니다.

math-add.cppm (파티션):

export module math:add;

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

math-multiply.cppm (파티션):

export module math:multiply;

export int multiply(int a, int b) {
    return a * b;
}

math.cppm (주 모듈 인터페이스):

export module math;

export import :add;
export import :multiply;

main.cpp:

import math;  // 모든 파티션 자동 import

int main() {
    add(1, 2);
    multiply(3, 4);
}

내부 파티션 (export 없음)

// math-impl.cppm (내부 파티션)
module math:impl;

int helperFunction() {
    return 42;
}

// math.cppm
export module math;
import :impl;  // 내부에서만 사용

export int compute() {
    return helperFunction();
}

3. 구현 유닛

인터페이스와 구현 분리

vector.cppm (인터페이스):

export module vector;

export class Vector {
public:
    Vector(int size);
    void push(int value);
    int get(int index) const;
    
private:
    int* data;
    int size;
    int capacity;
};

vector.cpp (구현 유닛):

module vector;  // module 선언 (export 없음)

#include <cstring>
#include <stdexcept>

Vector::Vector(int size) 
    : size(0), capacity(size) {
    data = new int[capacity];
}

void Vector::push(int value) {
    if (size >= capacity) {
        throw std::runtime_error("Vector full");
    }
    data[size++] = value;
}

int Vector::get(int index) const {
    if (index >= size) {
        throw std::out_of_range("Index out of range");
    }
    return data[index];
}

4. 표준 라이브러리 모듈

import std (C++23)

import std;

int main() {
    std::vector<int> v = {1, 2, 3};
    std::cout << "Size: " << v.size() << '\n';
    
    std::ranges::sort(v);
    
    for (auto x : v) {
        std::cout << x << ' ';
    }
}

장점: <iostream>, <vector>, <algorithm> 등을 개별로 import하지 않고, import std 하나로 모든 표준 라이브러리를 사용할 수 있습니다.

5. 헤더 유닛

기존 헤더를 import

C++20에서는 기존 헤더를 헤더 유닛으로 import할 수 있습니다.

// 기존 방식
#include <iostream>
#include <vector>

// C++20 헤더 유닛
import <iostream>;
import <vector>;

int main() {
    std::cout << "Hello\n";
    std::vector<int> v = {1, 2, 3};
}

주의: 헤더 유닛은 컴파일러 지원이 제한적입니다. GCC 11+, Clang 16+에서 실험적으로 지원합니다.

6. 자주 발생하는 문제와 해결법

문제 1: 컴파일러 지원 부족

증상: error: module not supported.

원인: 컴파일러가 모듈을 지원하지 않거나, 플래그가 누락됨.

# GCC 11+ (실험적)
g++ -std=c++20 -fmodules-ts -xc++-system-header iostream
g++ -std=c++20 -fmodules-ts -c math.cppm
g++ -std=c++20 -fmodules-ts main.cpp math.o -o myapp

# Clang 16+ (실험적)
clang++ -std=c++20 -fmodules -c math.cppm -o math.pcm
clang++ -std=c++20 -fmodules -fprebuilt-module-path=. main.cpp -o myapp

# MSVC 2019+ (안정적)
cl /std:c++20 /interface /c math.ixx
cl /std:c++20 main.cpp math.obj

문제 2: import 순서

원인: import는 모든 선언보다 앞에 와야 합니다.

// ❌ 잘못된 사용
int x = 42;
import math;  // Error: import는 맨 앞에

// ✅ 올바른 사용
import math;
import <iostream>;

int x = 42;

문제 3: export 누락

증상: error: 'add' was not declared in this scope.

원인: 모듈에서 함수를 export하지 않음.

// ❌ 잘못된 사용
module math;
int add(int a, int b) { return a + b; }

// ✅ 올바른 사용
export module math;
export int add(int a, int b) { return a + b; }

문제 4: 헤더와 모듈 혼용

증상: 매크로가 모듈에 영향을 줌.

// ❌ 잘못된 사용
export module mymodule;
#include <legacy_header.h>  // 매크로 오염

// ✅ 올바른 사용: global module fragment
module;
#include <legacy_header.h>  // 매크로는 여기서만
export module mymodule;
// 모듈 코드 (매크로 격리됨)

문제 5: 순환 의존성

증상: error: circular dependency between modules.

원인: 모듈 A가 B를 import하고, B가 A를 import함.

// ❌ 잘못된 사용
// moduleA.cppm
export module A;
import B;

// moduleB.cppm
export module B;
import A;  // 순환!

// ✅ 올바른 사용: 공통 모듈 분리
// common.cppm
export module common;
export int shared_func();

// moduleA.cppm
export module A;
import common;

// moduleB.cppm
export module B;
import common;

7. 프로덕션 패턴

패턴 1: 점진적 마이그레이션

// 1단계: 헤더 유닛 사용
import <iostream>;
import <vector>;
#include "legacy.h"  // 레거시 헤더는 그대로

// 2단계: 새 코드는 모듈로
export module mymodule;
import <iostream>;

// 3단계: 레거시 코드도 모듈로 전환
export module legacy;

패턴 2: CMake 통합 (실험적)

cmake_minimum_required(VERSION 3.28)
project(MyProject)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API "aa1f7df0-828a-4fcd-9afc-2dc80491aca7")

add_executable(myapp
    main.cpp
    FILE_SET CXX_MODULES FILES
        math.cppm
        utils.cppm
)

패턴 3: 모듈 네이밍 컨벤션

// 프로젝트명.기능명
export module myproject.math;
export module myproject.utils;
export module myproject.io;

// 계층 구조
export module myproject.math.algebra;
export module myproject.math.geometry;

8. 완전한 예제: 수학 라이브러리

프로젝트 구조

mathlib/
├── CMakeLists.txt
├── modules/
│   ├── math.cppm
│   ├── math-algebra.cppm
│   ├── math-geometry.cppm
│   └── math-impl.cpp
└── src/
    └── main.cpp

math-algebra.cppm

export module math:algebra;

export namespace math::algebra {
    int gcd(int a, int b) {
        while (b != 0) {
            int temp = b;
            b = a % b;
            a = temp;
        }
        return a;
    }
    
    int lcm(int a, int b) {
        return (a * b) / gcd(a, b);
    }
}

math-geometry.cppm

export module math:geometry;

export namespace math::geometry {
    constexpr double PI = 3.14159265358979323846;
    
    double circleArea(double radius) {
        return PI * radius * radius;
    }
    
    double circleCircumference(double radius) {
        return 2 * PI * radius;
    }
    
    class Point {
    public:
        double x, y;
        
        Point(double x, double y) : x(x), y(y) {}
        
        double distanceTo(const Point& other) const {
            double dx = x - other.x;
            double dy = y - other.y;
            return std::sqrt(dx*dx + dy*dy);
        }
    };
}

math.cppm (주 모듈)

export module math;

export import :algebra;
export import :geometry;

export namespace math {
    const char* version() {
        return "1.0.0";
    }
}

main.cpp

import math;
import <iostream>;

int main() {
    std::cout << "Math Library " << math::version() << '\n';
    
    // 대수
    std::cout << "GCD(12, 18) = " << math::algebra::gcd(12, 18) << '\n';
    std::cout << "LCM(12, 18) = " << math::algebra::lcm(12, 18) << '\n';
    
    // 기하
    std::cout << "Circle area (r=5) = " << math::geometry::circleArea(5.0) << '\n';
    
    math::geometry::Point p1(0, 0);
    math::geometry::Point p2(3, 4);
    std::cout << "Distance = " << p1.distanceTo(p2) << '\n';  // 5
}

9. 성능 비교

빌드 시간 (예시)

프로젝트 규모	헤더 방식	모듈 방식	개선
소형 (10 파일)	5초	4초	20%
중형 (100 파일)	60초	30초	50%
대형 (1000 파일)	30분	10분	67%

이유: 모듈은 한 번만 컴파일되고, 이후 import는 컴파일된 결과를 재사용합니다. 헤더는 매번 파싱됩니다.

메모리 사용

모듈은 전처리기가 매번 헤더를 파싱하지 않아, 컴파일러 메모리 사용량도 줄어듭니다.

10. 마이그레이션 가이드

단계별 전환

단계	작업	예시
1	헤더 유닛 사용	`#include <iostream>` → `import <iostream>;`
2	새 코드는 모듈로	새 기능을 `export module new_feature`로 작성
3	레거시 헤더 래핑	레거시 헤더를 import하는 모듈 작성
4	점진적 전환	파일별로 헤더 → 모듈 전환

헤더 → 모듈 변환 예시

Before (헤더):

// math.h
#ifndef MATH_H
#define MATH_H

namespace math {
    int add(int a, int b);
}

#endif

// math.cpp
#include "math.h"

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

// main.cpp
#include "math.h"
int main() {
    math::add(1, 2);
}

After (모듈):

// math.cppm
export module math;

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

// main.cpp
import math;
int main() {
    math::add(1, 2);
}

정리

개념	설명
Module	헤더 파일 대체 시스템
export	외부에 공개
import	모듈 사용
파티션	모듈을 여러 파일로 분할
구현 유닛	인터페이스와 구현 분리
헤더 유닛	기존 헤더를 import

C++20 Modules는 빌드 시간 단축, 매크로 격리, 명확한 인터페이스를 제공해, 대형 프로젝트에서 헤더 파일의 문제를 해결합니다.

FAQ

Q1: 모듈 vs 헤더 차이는?

A: 모듈은 한 번만 컴파일되고, 매크로가 격리되며, import 순서가 자유롭습니다. 헤더는 매번 파싱되고, 매크로가 전파되며, include 순서가 중요합니다.

Q2: 언제 모듈을 써야 하나요?

A: 새 프로젝트나 빌드 시간이 긴 대형 프로젝트에서 사용하세요. 레거시 프로젝트는 점진적으로 전환할 수 있습니다.

Q3: 컴파일러 지원은?

MSVC 2019+: 안정적 지원
GCC 11+: 실험적 지원 (-fmodules-ts)
Clang 16+: 실험적 지원 (-fmodules)

2026년 현재 MSVC가 가장 안정적입니다.

Q4: CMake 지원은?

A: CMake 3.28+에서 실험적 지원합니다. CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API를 설정해야 합니다.

Q5: 기존 헤더와 혼용 가능한가요?

A: 네. global module fragment를 사용하면 레거시 헤더를 include하고, 모듈 코드에서는 매크로가 격리됩니다.

Q6: Modules 학습 리소스는?

cppreference - Modules
“C++20: The Complete Guide” by Nicolai Josuttis
MSVC Modules 문서

한 줄 요약: C++20 Modules로 빌드 시간을 단축하고 코드를 깔끔하게 만들 수 있습니다. 다음으로 Concepts를 읽어보면 좋습니다.

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

C++20 Concepts 완벽 가이드 | 템플릿 제약의 새 시대
C++20 Coroutines 완벽 가이드 | 비동기 프로그래밍의 새 시대
C++20 consteval 완벽 가이드 | 컴파일 타임 전용 함수

C++20 Modules |
C++ 기존 프로젝트를 Module로 전환 | 단계별 마이그레이션 [#24-2]
C++20 Concepts 완벽 가이드 | 템플릿 제약의 새 시대
C++20 consteval 완벽 가이드 | 컴파일 타임 전용 함수
C++20 Coroutines 완벽 가이드 | 비동기 프로그래밍의 새 시대