Documentation

Start with the first command

This page covers installation, target GCC selection, common command lines, PCH, diagnostics, and troubleshooting. The full implementation and test matrix are authoritative in the GitHub repository.

Installation

Download the Windows x64 archive and extract it to any directory. CrucibleCpp is a statically linked single-file program, so no runtime needs to be installed.

cruciblecpp-preprocessor.exe --version # cruciblecpp-preprocessor 3.0.1
Current production target: Windows x64 + MinGW-w64 UCRT64. Other platforms, ABIs, and GCC versions are not guaranteed to be supported.

Quick start

First check that PATH contains the target g++.exe. Then simply replace your existing g++ -E:

# Preprocess .\cruciblecpp-preprocessor.exe -P -std=c++20 src\main.cpp -o build\main.i # Compile with the same GCC g++ -std=c++20 build\main.i -o build\main.exe

If the target GCC is not in PATH, use --gcc to specify it explicitly:

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

Select GCC

CrucibleCpp uses the target GCC's predefined macros, __has_* data and include search paths. Do not use a GCC 15 profile to preprocess GCC 14 headers.

MethodBehavior
--gcc-version=13|14|15Find the highest supported compiler in PATH that matches the major version
--gcc <g++.exe>Use the specified compiler directly and read its version and include paths
Not specifiedScan PATH and choose the highest supported version by default (15 → 14 → 13)
Auto-detection scans PATH only. If it is installed elsewhere, add it to PATH, or use --gcc, and do not rely on a fixed drive letter.

Supported standard profiles:

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

Common command lines

ParametersPurpose
-PDo not output line markers
-o <file>Output file
-I <dir>Add include directory
-isystem <dir>System header directories
-D / -UDefine / undefine macros
-include <file>Force include
-MD -MF -MTGenerate Make/CMake dependency files
-finput-charset / -fexec-charsetInput / execution character set
--embed-dir <dir>#embed search directories
--analysis-json <file>Output include graph, macro trace, and PCH records

PCH

GCC's g++ -E does not use .gch; PCH is only used during real compilation. By default CrucibleCpp reads header sources, and can optionally validate, register, and cache externally generated PCHs.

# Warn when a .gch is found --pch=warn # Fail immediately when a .gch is found --pch=error # Record ignored PCHs in the analysis JSON --pch=report

Enable PCH caching:

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

The cache manifest records the compiler path, version, compiler hash, and options hash. PCHs from GCC 13/14/15 do not collide with each other.

Diagnostics

By default it outputs GCC-style source lines and caret. You can turn this off or adjust it:

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

Supports #pragma GCC diagnostic push/pop/ignored/warning/error and #pragma GCC system_header. Headers included via -isystem suppress ordinary warnings by default, and -Wsystem-headers can show them again.

Troubleshooting

Standard library headers not found

The target compiler is not in PATH. Use --gcc to specify it, or add its bin directory to PATH. You can also use -isystem to pass it explicitly.

Wrong GCC version selected

Use --gcc-version=13|14|15 to pin the major version, or use --gcc to point at a specific g++.exe. Do not mix a target profile with headers from another version.

PCH cache reports corrupt

The PCH does not match the current compiler/options, or the file is corrupt. Delete the matching cache entry and regenerate it; alternatively, turn PCH caching off entirely and let it read the header sources.

GCC cannot compile the output

First make sure preprocessing and compilation use the same GCC version and -std. Then compile the “.i” generated by CrucibleCpp separately to check whether the problem comes from the preprocessing stage.

CrucibleCpp is a preprocessor, not a compiler. It does not handle code generation, optimization, linking, or parsing GCC's internal binary PCH format.