cpp

cpp [options] input_file [output_file]

-D macro[=definition]
    Define a macro with an optional definition before preprocessing begins. Equivalent to a #define directive at the beginning of the file.

-U macro
    Undefine a previously defined macro. Equivalent to a #undef directive.

-I dir
    Add dir to the list of directories to be searched for header files during #include directives. Directories are searched in the order specified.

-include file
    Include the contents of file before processing the main input file. This is useful for including common definitions or configuration headers.

-P
    Inhibit the generation of #line directives. This results in cleaner output, but it loses information about original file and line numbers, which can complicate debugging.

-C
    Do not strip C-style comments from the output. By default, cpp removes comments.

-M
    Generate a list of make rules suitable for recompilation from the command line. This option outputs dependency information (e.g., all header files included by the source) to standard output.

-o file
    Specify file as the output file name. If omitted, the output is sent to standard output.

--version
    Display the version number of cpp.

--help
    Display help information for cpp command-line options.

The cpp command, an acronym for C Preprocessor, is the first phase of compilation for C, C++, and Objective-C source code. While rarely invoked directly by users, it is an essential component of the GNU Compiler Collection (GCC), typically run automatically by the gcc command.

Its primary functions include:
Header Inclusion: Processing #include directives to insert the contents of specified header files into the source code. It searches for headers in standard system directories and user-specified paths.
Macro Expansion: Performing text substitution for #define macros, replacing macro names with their defined values or code snippets.
Conditional Compilation: Handling directives like #ifdef, #ifndef, #if, #else, and #endif to selectively include or exclude blocks of code based on conditions, useful for platform-specific code or debugging.
Other Directives: Processing directives such as #line (to control line numbers for debugging), #error (to issue compilation errors), and #warning (to issue warnings).

The output of cpp is a single, expanded source file that is then passed to the compiler (e.g., cc1 for C) for syntax analysis and code generation. It does not perform any syntax checking or code generation itself.

The cpp command is typically an internal component of the compiler suite (like GCC) and is rarely executed directly by users. When users compile C/C++ code, gcc automatically invokes cpp as part of its multi-stage compilation process. Direct invocation is mostly for debugging preprocessor issues, such as examining macro expansions or include paths. Its output is not directly executable and requires further processing by the compiler, assembler, and linker.

When you run gcc source.c, the compilation process typically involves four stages: 1. Preprocessing (handled by cpp), 2. Compilation (generating assembly code), 3. Assembly (converting assembly to machine code), and 4. Linking (combining object files and libraries). You can explicitly invoke only the preprocessing stage with gcc -E source.c -o output.i, which essentially runs cpp on the source file.

By default, cpp inserts #line directives (e.g., # 1 "file.c") into its output. These directives inform the subsequent compiler stage about the original source file and line number for the code that follows. This is crucial for accurate error reporting and debugging, as it allows tools to trace errors back to the original source location even after preprocessing transformations.

The concept of a C preprocessor has been integral to the C language since its inception in the early 1970s. It provided essential features like file inclusion and macro definitions that were crucial for code modularity and abstraction in a low-level language. The GNU C Preprocessor (GCPP), which is part of the GNU Compiler Collection (GCC), is the most widely used implementation on Linux systems. It has evolved to conform to the C and C++ language standards (e.g., C99, C11, C++98, C++11, C++17) and supports numerous extensions while maintaining backward compatibility. Its development tracks closely with the evolution of the GCC compiler suite itself.

gcc(1), make(1), as(1), ld(1)