Documentation

첫 명령부터 시작하세요

이 페이지에서는 설치, 타깃 GCC 선택, 자주 쓰는 명령줄, PCH, 진단, 문제 해결을 다룹니다. 전체 구현과 테스트 매트릭스는 GitHub 저장소를 기준으로 합니다.

설치

Windows x64 압축 파일을 내려받아 아무 디렉터리에나 풀면 됩니다. CrucibleCpp는 정적 링크된 단일 파일 프로그램이라 런타임을 설치할 필요가 없습니다.

cruciblecpp-preprocessor.exe --version # cruciblecpp-preprocessor 3.0.1
현재 프로덕션 타깃: Windows x64 + MinGW-w64 UCRT64. 다른 플랫폼과 ABI, GCC 버전은 지원을 보장하지 않습니다.

빠른 시작

먼저 PATH에서 대상 컴파일러를 확인하세요: g++.exe. 그런 다음 기존 g++ -E:

# 전처리 .\cruciblecpp-preprocessor.exe -P -std=c++20 src\main.cpp -o build\main.i # 같은 GCC로 컴파일 g++ -std=c++20 build\main.i -o build\main.exe

대상 GCC를 PATH에 넣지 않았다면 --gcc 옵션으로 명시적으로 지정하세요:

.\cruciblecpp-preprocessor.exe ` --gcc "D:\GCC1413\gcc14\bin\g++.exe" ` -P -std=c++20 src\main.cpp -o build\main.i

GCC 선택

CrucibleCpp는 타깃 GCC의 사전 정의 매크로, __has_* 데이터, include 검색 경로를 사용합니다. GCC15의 profile로 GCC14의 헤더를 전처리하지 마세요.

방식동작
--gcc-version=13|14|15PATH에서 해당 메이저 버전에 맞는 지원 최고 버전 컴파일러를 찾습니다
--gcc <g++.exe>지정한 컴파일러를 그대로 사용하고 버전과 include 경로를 읽습니다
지정 안 함PATH를 스캔해 지원되는 최고 버전을 기본값으로 선택(15 → 14 → 13)
자동 감지는 PATH만 스캔합니다. 다른 디렉터리에 설치했다면 PATH에 추가하거나 --gcc를 사용하세요. 고정된 드라이브 문자에 의존하지 마세요.

지원하는 표준 프로필:

-std=c++11 C++11 profile -std=c++14 C++14 profile -std=c++17 C++17 profile -std=c++20 C++20 profile

자주 쓰는 명령줄

매개변수역할
-Pline marker를 출력하지 않음
-o <file>출력 파일
-I <dir>include 디렉터리 추가
-isystem <dir>시스템 헤더 디렉터리
-D / -U매크로 정의 / 해제
-include <file>강제 포함
-MD -MF -MTMake/CMake 의존 파일 생성
-finput-charset / -fexec-charset입력 / 실행 문자 집합
--embed-dir <dir>#embed 검색 디렉터리
--analysis-json <file>include 그래프, 매크로 trace, PCH 기록 출력

PCH

GCC의 g++ -E 옵션은 다음 파일을 사용하지 않습니다: .gch; PCH는 실제 컴파일할 때만 사용됩니다. CrucibleCpp는 기본적으로 헤더 소스를 읽고, 선택적으로 외부에서 생성된 PCH를 검증·등록·캐시합니다.

# .gch 발견 시 warning 출력 --pch=warn # .gch 발견 시 바로 오류 --pch=error # analysis JSON에 무시된 PCH 기록 --pch=report

PCH 캐시 활성화:

.\cruciblecpp-preprocessor.exe ` --pch-cache .cache\pch ` --pch-cache-stats .cache\pch\stats.json ` -P src\main.cpp -o build\main.i

캐시 manifest에는 컴파일러 경로, 버전, 컴파일러 해시, 옵션 hash가 기록됩니다. GCC13/14/15의 PCH가 서로 잘못 재사용되지 않습니다.

진단

기본적으로 GCC 스타일 소스 줄과 caret을 출력합니다. 끄거나 조정할 수 있습니다:

-fdiagnostics-color=auto|always|never -fno-diagnostics-show-caret -fno-diagnostics-show-option -Werror -Wno-error=name --max-errors 20

지원: #pragma GCC diagnostic push/pop/ignored/warning/error 및 #pragma GCC system_header. 한편, -isystem 옵션으로 지정된 헤더는 기본적으로 일반 경고를 억제하며, -Wsystem-headers 옵션으로 다시 표시할 수 있습니다.

문제 해결

표준 라이브러리 헤더를 찾을 수 없음

대상 컴파일러가 PATH에 없습니다. --gcc 옵션으로 지정하거나, 해당 bin 디렉터리를 PATH에 추가하세요. -isystem 옵션으로 직접 전달할 수도 있습니다.

잘못된 GCC 버전 선택

먼저 --gcc-version=13|14|15 옵션으로 메이저 버전을 고정하거나, --gcc 옵션으로 구체적인 g++.exe를 지정하세요. 대상 프로필과 다른 버전의 헤더를 섞지 마세요.

PCH 캐시에서 corrupt 발생

PCH가 현재 컴파일러/옵션과 맞지 않거나 파일이 손상된 경우입니다. 해당 캐시 항목을 삭제한 뒤 다시 생성하세요. PCH 캐시를 아예 끄고 헤더 소스를 읽게 할 수도 있습니다.

출력이 GCC에서 컴파일되지 않음

먼저 전처리와 컴파일이 같은 GCC 버전과 -std를 사용하는지 확인하세요. 그런 다음 “CrucibleCpp가 생성한 .i”를 따로 컴파일해 문제가 전처리 단계에서 비롯된 것인지 확인하세요.

CrucibleCpp는 전처리기이며 컴파일러가 아닙니다. 코드 생성, 최적화, 링크, GCC 바이너리 PCH 내부 형식 파싱은 담당하지 않습니다.