CPP(1)

📦
version 10.5.0 · 3 versions
, in ubuntu jammy

Okay bestie, welcome to the manual for cpp, section 1, GNU edition 🎀 Part 1 of 3, so buckle up 🧚

✨ NAME ✨

cpp - The C Preprocessor 💖

✨ SYNOPSIS ✨

cpp [-Dmacro[=defn]...] [-Umacro]
    [-Idir...] [-iquotedir...]
    [-M|-MM] [-MG] [-MF filename]
    [-MP] [-MQ target...]
    [-MT target...]
    infile [[-o] outfile]

Only the most useful options are up top, so scroll for the full list of preprocessor-specific options 👀 cpp also takes most gcc driver options, which aren't listed here. For those, check the GCC documentation 📚

✨ DESCRIPTION ✨

The C preprocessor, aka cpp, is a macro processor that the C compiler uses automatically to transform your program before compilation 🧚 It's called a macro processor because it lets you define macros, which are brief abbreviations for longer constructs ✨

The C preprocessor is meant to be used only with C, C++, and Objective-C source code 💅 People have abused it as a general text processor in the past 💀, and it will choke on input that doesn't follow C's lexical rules. Apostrophes, for example, get read as the start of character constants and cause errors 🙈 You also can't rely on it keeping characteristics of the input that don't matter to C-family languages. If a Makefile gets preprocessed, all the hard tabs get removed and the Makefile won't work 😭

Warning, bestie: preprocess a Makefile and all the hard tabs disappear, so it won't work. Not it. 💀

Having said that, you can often get away with using cpp on things that aren't C 🦋 Other Algol-ish languages are often safe (Ada, etc.). Assembly is also okay, but with caution. -traditional-cpp mode preserves more white space and is otherwise more permissive. Lots of the problems can be avoided by writing C or C++ style comments instead of native language comments, and by keeping macros simple 🌸

Wherever possible, use a preprocessor geared to the language you're writing in 👑 Modern versions of the GNU assembler have macro facilities. Most high-level programming languages have their own conditional compilation and inclusion mechanisms. If all else fails, try a true general text processor, like GNU M4 🫶

C preprocessors vary in some details ✨ This manual is about the GNU C preprocessor, which provides a small superset of the features of ISO Standard C. In its default mode, the GNU C preprocessor skips a few things the standard requires. These are features that are rarely, if ever, used, and skipping them can cause surprising changes to the meaning of a program that doesn't expect them 🙈 To get strict ISO Standard C, use -std=c90, -std=c99, -std=c11 or -std=c17, depending on which version of the standard you want. To get all the mandatory diagnostics, you must also use -pedantic 💜

This manual describes the behavior of the ISO preprocessor. To minimize gratuitous differences, where the ISO preprocessor's behavior doesn't conflict with traditional semantics, the traditional preprocessor should behave the same way. The various differences that do exist are detailed in the section Traditional Mode 🍓

For clarity, unless noted otherwise, references to CPP in this manual refer to GNU CPP 🌈

✨ OPTIONS ✨

The cpp command expects two file names as arguments, infile and outfile 📁 The preprocessor reads infile together with any other files it specifies with #include. All the output generated by the combined input files is written in outfile ✨

Either infile or outfile may be -. As infile, it means read from standard input, and as outfile, it means write to standard output 🎀 If either file is omitted, it means the same as if - had been specified for that file. You can also use the -o outfile option to specify the output file 💅

Unless otherwise noted, or the option ends in =, all options which take an argument may have that argument appear either immediately after the option, or with a space between option and argument. -Ifoo and -I foo have the same effect 🦋

Many options have multi-letter names, so multiple single-letter options can't be grouped. -dM is very different from -d -M 💀

  • -D name — Predefine name as a macro, with definition 1 ✨
  • -D name=definition — The contents of definition are tokenized and processed as if they appeared during translation phase three in a #define directive. In particular, the definition gets truncated by embedded newline characters. If you're invoking the preprocessor from a shell or shell-like program, you may need the shell's quoting syntax to protect characters like spaces that have a meaning in shell syntax. If you want to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign (if any). Parentheses are meaningful to most shells, so quote the option. With sh and csh, -D'name(args...)=definition' works 🧠

Heads up, these ordering rules matter! -D and -U options are processed in the order they're given on the command line. All -imacros file and -include file options are processed after all -D and -U options 🔥

  • -U name — Cancel any previous definition of name, either built in or provided with a -D option 🧹
  • -include file — Process file as if #include "file" appeared as the first line of the primary source file. However, the first directory searched for file is the preprocessor's working directory instead of the directory containing the main source file. If it's not found there, it's searched for in the remainder of the #include "..." search chain as normal. If multiple -include options are given, the files are included in the order they appear on the command line 📂
  • -imacros file — Exactly like -include, except that any output produced by scanning file is thrown away. Macros it defines remain defined. This lets you acquire all the macros from a header without also processing its declarations 🧚 All files specified by -imacros are processed before all files specified by -include ✨
  • -undef — Don't predefine any system-specific or GCC-specific macros. The standard predefined macros remain defined 🙅
  • -pthread — Define additional macros required for using the POSIX threads library. You should use this option consistently for both compilation and linking 🧵 It's supported on GNU/Linux targets, most other Unix derivatives, and also on x86 Cygwin and MinGW targets 🌈
  • -M — Instead of outputting the result of preprocessing, output a rule suitable for make describing the dependencies of the main source file. The preprocessor outputs one make rule containing the object file name for that source file, a colon, and the names of all the included files, including those coming from -include or -imacros command-line options. Unless specified explicitly (with -MT or -MQ), the object file name consists of the name of the source file with any suffix replaced with the object file suffix and with any leading directory parts removed. If there are many included files, the rule is split into several lines using \-newline. The rule has no commands. This option does not suppress the preprocessor's debug output, such as -dM. To avoid mixing that debug output with the dependency rules, explicitly specify the dependency output file with -MF, or use an environment variable like DEPENDENCIES_OUTPUT. Debug output is still sent to the regular output stream as normal. Passing -M to the driver implies -E, and suppresses warnings with an implicit -w 🧠
  • -MM — Like -M, but don't mention header files that are found in system header directories, nor header files that are included, directly or indirectly, from such a header. This implies that the choice of angle brackets or double quotes in an #include directive doesn't in itself determine whether that header appears in -MM dependency output 🦋
  • -MF file — When used with -M or -MM, specifies a file to write the dependencies to. If no -MF switch is given, the preprocessor sends the rules to the same place it would send preprocessed output. When used with the driver options -MD or -MMD, -MF overrides the default dependency output file. If file is -, then the dependencies are written to stdout 📝
  • -MG — In conjunction with an option such as -M requesting dependency generation, -MG assumes missing header files are generated files and adds them to the dependency list without raising an error. The dependency filename is taken directly from the #include directive without prepending any path. -MG also suppresses preprocessed output, as a missing header file renders this useless. This feature is used in automatic updating of makefiles 🛠️
  • -MP — This option instructs CPP to add a phony target for each dependency other than the main file, causing each to depend on nothing. These dummy rules work around errors make gives if you remove header files without updating the Makefile to match 🧹 This is typical output:
test.o: test.c test.h

test.h:

(part 1 of 3, more on the way 💜)

  • -fpreprocessed — okay so this one tells the preprocessor "hey bestie, this file is already preprocessed, don't redo the work" 💅 That means macro expansion, trigraph conversion, escaped newline splicing, and most directive processing get skipped ✨ The preprocessor still recognizes and removes comments, so you can pass it a file preprocessed with -C and it'll be totally fine 🫶 In this mode the integrated preprocessor is little more than a tokenizer for the front ends 🧚 Also, -fpreprocessed is implicit if the input file ends in .i, .ii or .mi. Those are the extensions GCC uses for preprocessed files made by -save-temps 🌸
  • -fdirectives-only — when preprocessing, handle directives but do NOT expand macros 🦋 How it acts depends on -E and -fpreprocessed, so let's break it down:
    • With -E, it only handles directives like #define, #ifdef, and #error 💖 Other stuff like macro expansion and trigraph conversion doesn't happen. The -dD option also gets turned on automatically ✨
    • With -fpreprocessed, predefining command line macros and most builtin macros is turned off 🙈 Context-dependent macros like __LINE__ are still handled normally. This lets you compile files that were previously preprocessed with -E -fdirectives-only 👑
    • With both -E and -fpreprocessed, the -fpreprocessed rules win 💅 That gives you full preprocessing of files previously preprocessed with -E -fdirectives-only 🔥
  • -fdollars-in-identifiers — lets $ be used inside identifiers 💲
  • -fextended-identifiers — accepts universal character names and extended characters in identifiers 🌈 This one is enabled by default for C99 (and later C standard versions) and C++ 💜
  • -fno-canonical-system-headers — when preprocessing, don't shorten system header paths with canonicalization 🙅‍♀️
  • -fmax-include-depth=depth — sets the maximum depth of nested #includes. The default is 200 🧚
  • -ftabstop=width — sets the distance between tab stops ⭐ This helps the preprocessor report correct column numbers in warnings or errors, even when tabs show up on the line 🎀 If the value is less than 1 or greater than 100, the option gets ignored. The default is 8 🍓
  • -ftrack-macro-expansion[=level] — tracks token locations across macro expansions 🔍 This lets the compiler show the current macro expansion stack when an error happens inside a macro expansion. Heads up though: using it makes the preprocessor and the compiler eat more memory 💀 The level parameter picks how precise the location tracking is, so you can drop memory use if you need to:
    • Level 0 de-activates this option.
    • Level 1 tracks token locations in a degraded mode to keep memory overhead minimal. In this mode, every token from expanding an argument of a function-like macro has the same location.
    • Level 2 tracks token locations completely. It's the most memory hungry option 🐘

If you give the option no argument at all, the default level is 2 🫶 Also note that -ftrack-macro-expansion=2 is activated by default ✨

  • -fmacro-prefix-map=old=new — when preprocessing files living in directory old, expands __FILE__ and __BASE_FILE__ as if those files were in directory new instead 🗺️ You can use this to swap an absolute path for a relative one by putting . in for new, which can lead to more reproducible builds that don't depend on location 🌿 This option also affects __builtin_FILE() during compilation. See also -ffile-prefix-map.
  • -fexec-charset=charset — sets the execution character set, used for string and character constants 💌 The default is UTF-8. charset can be any encoding supported by the system's iconv library routine 🌍
  • -fwide-exec-charset=charset — sets the wide execution character set, used for wide string and character constants 🌸 The default is one of UTF-32BE, UTF-32LE, UTF-16BE, or UTF-16LE, whichever matches the width of wchar_t and the big-endian or little-endian byte order used for code generation 🦋 Same as with -fexec-charset, charset can be any encoding supported by the system's iconv library routine. Warning: you'll have problems with encodings that don't fit exactly in wchar_t 😭
  • -finput-charset=charset — sets the input character set, used for translating from the input file's character set into the source character set GCC uses 📜 If the locale doesn't say, or GCC can't get the info from the locale, the default is UTF-8. The locale or this command-line option can override it, and if they conflict, the command-line option wins for now 👑 charset can be any encoding supported by the system's iconv library routine 🫧
  • -fworking-directory — turns on linemarkers in the preprocessor output so the compiler knows the working directory at preprocessing time 🗂️ When it's on, the preprocessor emits a second linemarker after the initial one, with the current working directory followed by two slashes 🧭 GCC uses that directory, when it's in the preprocessed input, as the working directory in some debugging information formats 🐞 This is implicitly enabled when debugging info is enabled, but you can block it with the negated form -fno-working-directory 🙅‍♀️ If the -P flag is in the command line, this option does nothing, because no #line directives get emitted whatsoever 💀
  • -A predicate=answer — makes an assertion with the predicate predicate and the answer answer 🎀 This form is preferred over the older -A predicate(answer) form. The old one still works, but this one doesn't use shell special characters, so it's way less messy ✨
  • -A -predicate=answer — cancels an assertion with the predicate predicate and the answer answer 🚫
  • -C — do NOT discard comments 💬 All comments get passed through to the output file, except for comments inside processed directives, which get deleted along with the directive 🗑️ Heads up: you should be ready for side effects with -C. It makes the preprocessor treat comments as tokens in their own right 🧐 For example, a comment at the start of what would be a directive line turns that line into an ordinary source line, since the first token on the line is no longer a # 😳
  • -CC — do NOT discard comments, even during macro expansion 🫶 It's like -C, except comments inside macros also get passed through to the output file wherever the macro gets expanded 🌈 On top of the -C side effects, -CC converts all C++-style comments inside a macro into C-style comments 🛡️ That's to stop a later use of the macro from accidentally commenting out the rest of the source line 🙈 -CC is generally used to support lint comments 🔍
  • -P — inhibits the generation of linemarkers in the preprocessor output 🚫📍 This might be useful when you run the preprocessor on something that isn't C code and send it to a program that could get confused by linemarkers 🧩
  • -traditional, -traditional-cpp — tries to imitate the behavior of pre-standard C preprocessors instead of ISO C preprocessors 🕰️ Note: GCC doesn't otherwise try to emulate a pre-standard C compiler, and these options are only supported with the -E switch or when invoking CPP explicitly 🎩
  • -trigraphs — supports ISO C trigraphs 🔺 These are three-character sequences that all start with ??, which ISO C defines to stand for single characters. For example, ??/ stands for \, so '??/n' is a character constant for a newline 🍃 By default, GCC ignores trigraphs, but in standard-conforming modes it converts them. See the -std and -ansi options 📚
  • -remap — enables special code to work around file systems that only allow super short file names, like MS-DOS 💾
  • -H — prints the name of each header file used, on top of the other normal stuff 📋 Each name is indented to show how deep it is in the #include stack 🪜 Precompiled header files get printed too, even if they turn out to be invalid. An invalid precompiled header gets printed with ...x, and a valid one with ...! ✅❌
  • -dletters — makes debugging dumps during compilation, as specified by letters 🧪 The flags documented here are the ones relevant to the preprocessor. Other letters are interpreted by the compiler proper, or reserved for future versions of GCC, so they're silently ignored 🤫 Careful: if you specify letters whose behavior conflicts, the result is undefined 💀
    • -dM — instead of the normal output, generates a list of #define directives for all the macros defined during the execution of the preprocessor, including predefined macros 📜 This is a way to find out what's predefined in your version of the preprocessor 🔎 Assuming you have no file foo.h, you can run this to see all the predefined macros:
touch foo.h; cpp -dM foo.h
  • -dD — like -dM, except it does NOT include the predefined macros, and it outputs both the #define directives and the result of preprocessing 🌷 Both kinds of output go to the standard output file 🖨️
  • -dN — like -dD, but only emits the macro names, not their expansions 🏷️
  • -dI — outputs #include directives in addition to the result of preprocessing 📥
  • -dU — like -dD, except only macros that are expanded, or whose definedness is tested in preprocessor directives, get output 🎯 The output is delayed until the use or test of the macro, and #undef directives are also output for macros that were tested but were undefined at the time 🧠
  • -fdebug-cpp — only useful for debugging GCC 🐛 When used from CPP or with -E, it dumps debugging info about location maps. Every token in the output is preceded by the dump of the map its location belongs to 🗺️ When used from GCC without -E, this option has no effect 🙃
  • -I dir, -iquote dir, -isystem dir, -idirafter dir — adds the directory dir to the list of directories searched for header files during preprocessing 📂✨

If dir starts with = or $SYSROOT 🌸, that part gets swapped out for the sysroot prefix ✨. Check out --sysroot and -isysroot for the deets 💅.

Directories you give with -iquote only count for the quote form, #include "file" 🎀. Directories from -I, -isystem, or -idirafter work for both #include "file" and #include <file> 🫶.

You can stack as many of these as you want on the command line to search a bunch of folders 🦋. The lookup order goes like this:

  1. For the quote form, the folder of the current file gets checked first 💖.
  2. For the quote form, -iquote folders get searched left-to-right, in the order you typed them 🌈.
  3. -I folders get scanned left-to-right 🧚.
  4. -isystem folders get scanned left-to-right 👑.
  5. Standard system directories get scanned 💅.
  6. -idirafter folders get scanned left-to-right 🍓.

You can use -I to override a system header file and swap in your own version, since those folders get searched before the standard system header directories 🔥. But bestie, don't use this to add folders with vendor-supplied system headers. Use -isystem for that 💀.

The -isystem and -idirafter options also mark the directory as a system directory, so it gets the same special treatment as the standard system directories 🦋.

If a standard system include directory, or a directory given with -isystem, also shows up with -I, the -I option gets ignored 🙈. The directory still gets searched, but as a system directory at its normal spot in the system include chain. This is so GCC's procedure to fix buggy system headers and the ordering for the #include_next directive don't get accidentally changed 🫶. If you really need to change the search order for system directories, use the -nostdinc and/or -isystem options 💜.

  • -I- — Splits the include path. This one is deprecated 😭, so please use -iquote instead for -I directories before the -I-, and remove the -I- option. Any -I directories before -I- only get searched for headers requested with #include "file". They are NOT searched for #include <file>. If extra -I directories show up after the -I-, those get searched for all #include directives. On top of that, -I- stops the folder of the current file from being the first search spot for #include "file", and there's no way to undo that effect of -I-.
  • -iprefix prefix — Sets prefix as the prefix for later -iwithprefix options. If the prefix is a directory, include the final / 🌷.
  • -iwithprefix dir, -iwithprefixbefore dir — Tacks dir onto the prefix you set earlier with -iprefix, then adds the result to the include search path ✨. -iwithprefixbefore puts it in the same place -I would, and -iwithprefix puts it where -idirafter would.
  • -isysroot dir — Basically --sysroot, but it only applies to header files 🧸. The exception is Darwin targets, where it applies to both header files and libraries. Check the --sysroot option for more info.
  • -imultilib dir — Uses dir as a subdirectory of the folder holding target-specific C++ headers 🎀.
  • -nostdinc — Skips the standard system directories for header files 🙅. Only the folders you explicitly give with -I, -iquote, -isystem, and/or -idirafter get searched, plus the folder of the current file if it's relevant.
  • -nostdinc++ — Skips the C++-specific standard directories for header files, but still searches the other standard directories 💖. (This one is used when building the C++ library.)
  • -Wcomment, -Wcomments — Warns whenever a /* comment-start sequence shows up inside a /* comment, or whenever a backslash-newline shows up in a // comment 👀. This warning is enabled by -Wall.
  • -Wtrigraphs — Warns if any trigraphs pop up that might change what the program means 🔮. Trigraphs inside comments don't get warned about, except the ones that would form escaped newlines.

This option is implied by -Wall. If -Wall isn't given, this option is still enabled unless trigraphs are enabled. Want trigraph conversion without the warnings, but still want the other -Wall warnings? Use -trigraphs -Wall -Wno-trigraphs 🌈.

  • -Wundef — Warns if an undefined identifier gets evaluated in an #if directive 🫠. Those identifiers get replaced with zero.
  • -Wexpansion-to-defined — Warns whenever defined shows up in the expansion of a macro, including when the macro gets expanded by an #if directive 🚫. That usage isn't portable. This warning is also enabled by -Wpedantic and -Wextra.
  • -Wunused-macros — Warns about macros defined in the main file that never get used 🧹. A macro counts as used if it's expanded or tested for existence at least once. The preprocessor also warns if the macro hasn't been used by the time it gets redefined or undefined.

Built-in macros, macros defined on the command line, and macros defined in include files don't get warned about.

Heads up: if a macro is used, but only inside skipped conditional blocks, the preprocessor still reports it as unused. To dodge the warning in that case, you could improve the scope of the macro's definition, like moving it into the first skipped block. Or you could provide a dummy use with something like:
#if defined the_macro_causing_the_warning
#endif
  • -Wno-endif-labels — Turns off the warning for when an #else or an #endif is followed by text 🙈. This sometimes happens in older programs with code like this:
#if FOO
...
#else FOO
...
#endif FOO

The second and third FOO should be in comments. This warning is on by default.

✨ ENVIRONMENT ✨

This section covers the environment variables that change how CPP operates 🧚. You can use them to specify directories or prefixes for searching include files, or to control dependency output 💜.

You can also specify places to search with options like -I, and control dependency output with options like -M. These take precedence over environment variables, which in turn take precedence over the configuration of GCC 👑.

  • CPATH, C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH — Each of these holds a list of directories, separated by a special character, kind of like PATH, and that's where the compiler looks for header files 🗺️. The special character, "PATH_SEPARATOR", depends on the target and gets set at GCC build time. For Microsoft Windows-based targets it's a semicolon, and for almost every other target it's a colon.

CPATH specifies directories to search as if they were given with -I, but after any paths given with -I options on the command line. This variable gets used no matter which language is being preprocessed 🌸.

The remaining variables only apply when preprocessing the particular language they're named for. Each one specifies directories to search as if they were given with -isystem, but after any paths given with -isystem options on the command line 🎀.

In all of these variables, an empty element tells the compiler to search its current working directory 🦋. Empty elements can show up at the beginning or end of a path. For instance, if the value of CPATH is ":/special/include", that does the same thing as -I. -I/special/include ✨.

  • DEPENDENCIES_OUTPUT — If this variable is set, its value tells CPP how to output dependencies for Make, based on the non-system header files the compiler processes 📝. System header files get ignored in the dependency output.

The value can be just a file name. In that case, the Make rules get written to that file, and the target name gets guessed from the source file name. Or the value can have the form file target, where the rules get written to file using target as the target name 💅.

In other words, this variable does the same job as combining the options -MM and -MF, with an optional -MT switch too 🫶.

  • SUNPRO_DEPENDENCIES — This one is the same as DEPENDENCIES_OUTPUT (see above), except system header files are NOT ignored, so it implies -M rather than -MM 🌷. However, the dependence on the main input file gets left out.
  • SOURCE_DATE_EPOCH — If this variable is set, its value is a UNIX timestamp that replaces the current date and time in the "__DATE__" and "__TIME__" macros ⏰. That way, the embedded timestamps stay reproducible 🔁.

The value of SOURCE_DATE_EPOCH has to be a UNIX timestamp, which is the number of seconds (excluding leap seconds) since 01 Jan 1970 00:00:00, written in ASCII 🧮. It's identical to the output of @command{date +%s} on GNU/Linux and other systems that support the %s extension in the "date" command.

The value should be a known timestamp, like the last modification time of the source or package, and the build process should set it 🛠️.

✨ SEE ALSO ✨

gpl(7), gfdl(7), fsf-funding(7), gcc(1), and the Info entries for cpp and gcc 📚🫶.

Copyright (c) 1987-2020 Free Software Foundation, Inc. 💜

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation 🌈. A copy of the license is included in the man page gfdl(7). This manual contains no Invariant Sections. The Front-Cover Texts are (a) (see below), and the Back-Cover Texts are (b) (see below).

(a) The FSF's Front-Cover Text is: A GNU Manual

(b) The FSF's Back-Cover Text is: You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development 🎉.

That's a wrap, bestie! 🎀💖 This page came from the gcc-10 release and was last stamped 2023-07-07 🦋. Go be iconic with your header files 💅✨

📦 where this page comes from