CPP(1)

📦
version 16-20260322 · 2 versions
, in ubuntu resolute

✨ CPP(1) from GNU ✨

Okay bestie, this is the manual page for cpp, and it's giving main character energy 💖 Let's get into it 🎀

🌸 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 don't panic 😭 There's a fuller list of preprocessor-specific options down below. cpp also takes most gcc driver options, but those aren't listed here, so check the GCC documentation for the details 💅

💅 DESCRIPTION

Okay so the C preprocessor, aka cpp, is a macro processor that the C compiler runs automatically to transform your program before it gets compiled ✨ 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 💀 For example, apostrophes get read as the start of character constants and cause errors. You also can't count on it keeping characteristics of the input that don't matter to C-family languages. If a Makefile gets preprocessed, all the hard tabs will be removed, and the Makefile won't work 😭

Having said that, you can often get away with using cpp on things that aren't C. Other Algol-ish programming languages are usually safe (Ada, etc.) and assembly is safe too, with caution 🫶 -traditional-cpp mode preserves more white space and is otherwise more permissive. Most 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, you should use a preprocessor geared to the language you're writing in. Modern versions of the GNU assembler have macro facilities, and most high level programming languages have their own conditional compilation and inclusion mechanism. If all else fails, try a true general text processor, such as GNU M4 👑

C preprocessors vary in some details. This manual talks 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, but they can cause surprising changes to the meaning of a program that doesn't expect them 🙈

Heads up: to get strict ISO Standard C, use the -std=c90, -std=c99, -std=c11 or -std=c17 options, 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, the traditional preprocessor should behave the same way wherever the ISO preprocessor's behavior doesn't conflict with traditional semantics. The differences that do exist are detailed in the section Traditional Mode 🍓

For clarity, unless noted otherwise, references to CPP in this manual mean 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 pulls in with #include, and all the output from those combined input files gets written to outfile 💖

Either infile or outfile can be -. As infile, it means read from standard input, and as outfile, it means write to standard output. If either file is left out, it works the same as if - had been given for that file. You can also use the -o outfile option to pick the output file ✨

Unless otherwise noted, or the option ends in =, every option that takes an argument can have that argument right after the option or with a space in between. -Ifoo and -I foo do the exact same thing 🦋

Lowkey tricky: many options have multi-letter names, so you can't group multiple single-letter options together. -dM is very different from -d -M 💀

  • -D name, --define-macro=name, --define-macro name — Predefines name as a macro, with the definition 1 🌸
  • -D name=definition, --define-macro=name=definition, --define-macro name=definition — The contents of definition get tokenized and processed as if they showed up during translation phase three in a #define directive. Important: the definition gets truncated by embedded newline characters 🫶
    • If you're invoking the preprocessor from a shell (or something shell-like), you might need the shell's quoting syntax to protect characters like spaces that mean something in shell syntax 💅
    • Want to define a function-like macro on the command line? Write its argument list with surrounding parentheses before the equals sign (if there is one). Parentheses mean something to most shells, so you should quote the option. With sh and csh, -D'name(args...)=definition' works 🧚
    • -D and -U options are processed in the order they're given on the command line. All -imacros file and -include file options get processed after all -D and -U options 👑
  • -U name, --undefine-macro=name, --undefine-macro name — Cancels any previous definition of name, whether it was built in or provided with a -D option 🙅‍♀️
  • -include file, --include=file, --include file — Processes file as if #include "file" showed up as the first line of the primary source file. The first directory searched for file is the preprocessor's working directory instead of the directory with the main source file. If it's not found there, it gets searched for in the rest of the #include "..." search chain as normal 🔍
    • If you give multiple -include options, the files get included in the order they appear on the command line 📚
  • -imacros file, --imacros=file, --imacros file — Exactly like -include, except any output produced by scanning file is thrown away. The macros it defines stay defined. This lets you grab all the macros from a header without also processing its declarations 🍰
    • All files given with -imacros get processed before all files given with -include 🌈
  • -undef — Don't predefine any system-specific or GCC-specific macros. The standard predefined macros stay defined 🧼
  • -pthread — Defines additional macros needed for using the POSIX threads library. 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, --dependencies — Instead of outputting the result of preprocessing, this outputs a rule suitable for make that describes 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 that come from -include or -imacros command-line options 🦋
    • Unless you specify it explicitly (with -MT or -MQ), the object file name is the source file's name with any suffix swapped for the object file suffix and any leading directory parts removed. If there are lots of included files, the rule gets 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, you should explicitly specify the dependency output file with -MF, or use an environment variable like DEPENDENCIES_OUTPUT. Debug output still gets sent to the regular output stream as normal 🙈
    • Passing -M to the driver implies -E, and suppresses warnings with an implicit -w 🔥
  • -MM, --user-dependencies — Like -M, but don't mention header files that are found in system header directories, or header files that get included, directly or indirectly, from such a header 🌈
    • This implies that choosing angle brackets or double quotes in an #include directive doesn't, on its own, decide whether that header shows up 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 -, the dependencies get written to stdout ✨
  • -MG, --print-missing-file-dependencies — In conjunction with an option like -M that requests 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, since a missing header file makes that useless 🙃
    • This feature is used in automatic updating of makefiles 🧚
  • -Mno-modules — Disables dependency generation for compiled module interfaces 🚫
  • -MP — This option instructs CPP to add a phony target for each dependency other than the main file, causing each one 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:
  • -MT target — Changes the target of the rule emitted by dependency generation. By default CPP takes the name of the main input file, deletes any directory components and any file suffix such as .c, and appends the platform's usual object suffix. The result is the target 🎯
    • An -MT option sets the target to be exactly the string you specify. If you want multiple targets, you can specify them as a single argument to -MT, or use multiple -MT options 💜
    • For example, -MT '$(objpfx)foo.o' might give:
$(objpfx)foo.o: foo.c
  • -MQ target — Same as -MT, but it quotes any characters that are special to Make. -MQ '$(objpfx)foo.o' gives:
$$(objpfx)foo.o: foo.c

The default target is automatically quoted, as if it were given with -MQ 🥹

  • -MD, --write-dependencies — okay so this is basically -M -MF file, except -E is NOT implied 🫶 The driver works out the file name by itself, and it depends on whether you passed an -o:
    • If there's an -o, the driver uses its argument and just adds a .d suffix.
    • If there isn't one, it takes the input file's name, strips off any directory components and the suffix, and slaps a .d on the end.
    • If -MD is used together with -E, any -o switch is understood to specify the dependency output file. But if you use it without -E, each -o is understood to specify a target object file.
    • Since -E isn't implied, -MD can make a dependency output file as a side effect of the compilation process. main character energy 🔥
  • -MMD, --write-user-dependencies — same energy as -MD, but it only mentions your own header files 🌸 and skips the system header files 🙈
  • -fpreprocessed — tells the preprocessor "hey, this input is already preprocessed, don't redo it" 💅 It suppresses things like macro expansion, trigraph conversion, escaped newline splicing, and processing of most directives. The preprocessor still recognizes and removes comments, so you can pass a file preprocessed with -C to the compiler with zero drama. In this mode the integrated preprocessor is basically just a tokenizer for the front ends 🧚 -fpreprocessed is implicit if the input file has one of the extensions .i, .ii or .mi. Those are the extensions GCC uses for preprocessed files created by -save-temps 🎀
  • -fdirectives-only — handles directives but does NOT expand macros 🦋 Its behavior depends on -E and -fpreprocessed:
    • With -E, preprocessing is limited to handling directives such as "#define", "#ifdef", and "#error". Other preprocessor operations, like macro expansion and trigraph conversion, are not performed. The -dD option is also implicitly enabled.
    • With -fpreprocessed, predefinition of command line and most builtin macros is disabled. Macros such as __LINE__, which are contextually dependent, are handled normally. This enables compilation of files previously preprocessed with -E -fdirectives-only.
    • With both -E and -fpreprocessed, the rules for -fpreprocessed take precedence. This enables full preprocessing of files previously preprocessed with -E -fdirectives-only.
  • -fdollars-in-identifiers — lets $ into identifiers 💖
  • -fextended-identifiers — accepts universal character names and extended characters in identifiers 🌈 This one's on by default for C99 (and later C standard versions) and C++.
  • -fno-canonical-system-headers — when preprocessing, leaves system header paths alone instead of shortening them with canonicalization 🧹
  • -fmax-include-depth=depth — sets the max depth of nested #includes. The default is 200 📚
  • -fsearch-include-path[=kind] — looks for input files on the #include path, not just the current directory 🔍 This is especially handy with C++20 modules, where both header units and module interface units need to be compiled directly, like so:
g++ -c -std=c++20 -fmodules -fsearch-include-path bits/stdc++.h bits/std.cc

kind defaults to user, which looks on the #include "..." search path. You can also explicitly specify system for the #include <...> search path ✨

  • -ftabstop=width — sets the distance between tab stops 📏 This helps the preprocessor report correct column numbers in warnings or errors, even if tabs show up on the line. If the value is less than 1 or greater than 100, the option is ignored. The default is 8.
  • -ftrack-macro-expansion[=level] — tracks token locations across macro expansions 🕵️ This lets the compiler show diagnostics about the current macro expansion stack when a compile error happens inside a macro expansion. Heads up: using it makes the preprocessor and the compiler eat more memory 🍓 The level parameter picks how precise the token location tracking is, so you can lower memory use if you need to:
    • Value 0 of level de-activates this option.
    • Value 1 tracks token locations in a degraded mode for minimal memory overhead. In this mode all tokens resulting from the expansion of an argument of a function-like macro have the same location.
    • Value 2 tracks token locations completely. This value is the most memory hungry.

When this option is given no argument, the default parameter value is 2. Note that -ftrack-macro-expansion=2 is activated by default 👑

  • -fmacro-prefix-map=old=new — when preprocessing files living in directory old, expands the __FILE__ and __BASE_FILE__ macros as if the files lived in directory new instead 🗺️ This can change an absolute path to a relative one by using . for new, which can lead to more reproducible, location-independent builds. This option also affects __builtin_FILE() during compilation. See also -ffile-prefix-map and -fcanon-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 being used for code generation. As with -fexec-charset, charset can be any encoding supported by the system's iconv library routine. However, you will have problems with encodings that do not fit exactly in wchar_t. 💀
  • -finput-charset=charset — sets the input character set, used for translating from the input file's character set to the source character set GCC uses 📥 If the locale doesn't specify one, or GCC can't get that info from the locale, the default is UTF-8. This can be overridden by either the locale or this command-line option. Currently the command-line option takes precedence if there's a conflict. charset can be any encoding supported by the system's iconv library routine.
  • -fworking-directory — turns on linemarkers in the preprocessor output that let the compiler know the current working directory at preprocessing time 🗂️ When this is enabled, the preprocessor emits, after the initial linemarker, a second linemarker with the current working directory followed by two slashes. GCC uses this directory, when it's present in the preprocessed input, as the directory emitted as the current working directory in some debugging information formats. This option is implicitly enabled if debugging information is enabled, but you can inhibit that with the negated form -fno-working-directory. If the -P flag is present in the command line, this option has no effect, since no #line directives are emitted whatsoever 🙅
  • -A predicate=answer, --assert predicate=answer, --assert=predicate=answer — makes an assertion with the predicate predicate and the answer answer 📝 This is the form to use over the older -A predicate(answer) form, which is still supported, because it doesn't use shell special characters. Assertions are an obsolete feature of the preprocessor, supported only for compatibility with legacy system headers on some targets.
  • -A -predicate=answer, --assert -predicate=answer, --assert=-predicate=answer — cancels an assertion with the predicate predicate and the answer answer 🚫
  • -C, --comments — doesn't throw comments away 💬 All comments are passed through to the output file, except comments in processed directives, which get deleted along with the directive.
Be prepared for side effects when using -C 😭 It causes the preprocessor to treat comments as tokens in their own right. For example, comments appearing at the start of what would be a directive line turn that line into an ordinary source line, since the first token on the line is no longer a #.
  • -CC, --comments-in-macros — doesn't discard comments, including during macro expansion ✨ This is like -C, except comments contained within macros are also passed through to the output file where the macro is expanded. On top of the side effects of -C, -CC converts all C++-style comments inside a macro to C-style comments. This stops a later use of that macro from accidentally commenting out the rest of the source line. The -CC option is generally used to support lint comments 🧼
  • -P, --no-line-commands — stops linemarkers from being generated in the preprocessor output 🚫 This might be useful when running the preprocessor on something that isn't C code and will be sent to a program that might get confused by the linemarkers.
  • -traditional, --traditional, -traditional-cpp, --traditional-cpp — tries to imitate pre-standard C preprocessors, as opposed to ISO C preprocessors 🕰️ 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, --trigraphs — supports ISO C trigraphs 🔺 These are three-character sequences, all starting with ??, that 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, --trace-includes — prints the name of each header file used, alongside all the other normal activity 🦋 Each name is indented to show how deep it sits in the #include stack. Precompiled header files get printed too, even when they turn out to be invalid: an invalid one shows up with ...x, and a valid one with ...!.
  • -dletters, --dump=letters, --dump letters — okay so this one lets you ask for debugging dumps while compiling, and the letters you pass decide which dump you get 🔍✨. The flags here are the preprocessor ones. Any other letters are handled by the actual compiler, reserved for future GCC versions, or quietly ignored, so no drama there 💅. ⚠️ If you mix letters whose behaviour conflicts, the result is undefined, so please don't 🙈
    • -dM, --dump=M — instead of your normal output, you get a list of #define directives for every macro defined while the preprocessor runs, predefined ones included 🌈. It's the best way to see what your preprocessor already has baked in. Assuming you don't have a file called foo.h, this command shows all the predefined macros:
touch foo.h; cpp -dM foo.h
  • -dD, --dump=D — same as -dM, but now you get the #define directives and the result of preprocessing. Both kinds of output go to standard output 📜
  • -dN, --dump=N — like -dD, but only the macro names show up, not their expansions 🫶
  • -dI, --dump=I — adds #include directives to the result of preprocessing 🦋
  • -dU, --dump=U — like -dD, except only macros that get expanded, or whose existence gets tested in preprocessor directives, are output 👑. The output waits until that macro is used or tested, and #undef directives are also output for macros that were tested but were undefined at that moment 🧚
  • -fdebug-cpp — this one is only really useful if you're debugging GCC itself 🙈. When you use it from CPP or with -E, it dumps debugging info about location maps, and every token in the output gets the dump of the map its location belongs to 🔥. When you use it from GCC without -E, it does absolutely nothing 💀
  • -I dir, -iquote dir, -isystem dir, -idirafter dir, --include-directory-after=dir, --include-directory-after dir, --include-directory=dir, --include-directory dir — this is how you tell the compiler about extra directories to hunt through for header files during preprocessing 🗂️. --include-directory is just another name for -I, and --include-directory-after is another name for -idirafter 💖

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

Heads up on the scope here: -iquote directories only apply to the quote form of the directive, "#include "file"". -I, -isystem, and -idirafter directories apply to both "#include "file"" and #include <file> lookups 🎀

You can stack as many of these as you want to search several directories. The lookup order goes like this:

  1. For the quote form of the include directive, the directory of the current file gets searched first 🥇
  2. For the quote form, the -iquote directories are searched left to right, in the order they show up on the command line 🥈
  3. -I directories are scanned left to right 🥉
  4. -isystem directories are scanned left to right 🫧
  5. Standard system directories are scanned 🏛️
  6. -idirafter directories are scanned left to right, last but not least 🌙

You can use -I to override a system header and swap in your own version, since these directories get searched before the standard system header directories 💅. ⚠️ But please don't use -I to add directories full of vendor-supplied system headers. That's what -isystem is for 🙏

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

Now, if a standard system include directory, or a directory given with -isystem, is also given with -I, the -I option gets ignored. The directory still gets searched, just as a system directory in its normal spot in the system include chain. This is so GCC's procedure for fixing buggy system headers and the ordering for the #include_next directive don't get messed up by accident 😭. If you truly need to change the search order for system directories, use the -nostdinc and/or -isystem options instead 🫶

  • -I-, --include-barrier — this splits the include path, but it's been deprecated, so please don't build your life around it 💀. Use -iquote instead for the -I directories that come before -I-, then remove -I- entirely 🧹

Any directories given with -I before -I- only get searched for headers requested with "#include "file"". They don't get searched for #include <file>. If you add more -I directories after the -I-, those get searched for all #include directives 🦋

-I- also stops the directory of the current file from being used as the first search directory for "#include "file"". There's no way to override that effect of -I- 😤

  • -iprefix prefix, --include-prefix=prefix, --include-prefix prefix — sets prefix as the prefix for any later -iwithprefix options 🍓. If the prefix is a directory, include the final / 📂
  • -iwithprefix dir, -iwithprefixbefore dir, --include-with-prefix=prefix, --include-with-prefix prefix, --include-with-prefix-after=prefix, --include-with-prefix-after prefix, --include-with-prefix-before=prefix, --include-with-prefix-before prefix — this tacks dir onto the prefix you set earlier with -iprefix, then adds the resulting directory to the include search path 🛤️. -iwithprefixbefore puts it in the same spot -I would, while -iwithprefix puts it where -idirafter would 🌈

--include-with-prefix and --include-with-prefix-after are both aliases for -iwithprefix, and --include-with-prefix-before is an alias for -iwithprefixbefore 💜

  • -isysroot dir — this is 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 the full story ✨
  • -imultilib dir — uses dir as a subdirectory of the directory that holds target-specific C++ headers 🧚
  • -imultiarch dir — uses dir as a subdirectory of the directory that holds architecture-specific C++ headers 🌸
  • -nostdinc, --no-standard-includes — no more searching the standard system directories for header files 🙅‍♀️. Only the directories you explicitly gave with -I, -iquote, -isystem, and/or -idirafter get searched, plus the directory of the current file if it's relevant 💖
  • -nostdinc++ — skips the C++-specific standard directories when hunting for headers, but still searches the other standard directories 🫶. (This one gets used when building the C++ library, so it's very much a behind-the-scenes kind of flag 🛠️)
  • --embed-dir=dir, --embed-directory=dir, --embed-directory dir — adds dir to the list of searched directories for the #embed preprocessing directive or the __has_embed macro 🪄. There are no default directories for #embed, so you're on your own with this one 🥹

If dir starts with = or $SYSROOT, that gets swapped for the sysroot prefix, same as before. See --sysroot and -isysroot 🌷

  • -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 show up that might change what your 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 get 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, so keep an eye out 🫣
  • -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, so this one is a whole vibe check 🚫. 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 gets 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 🙌

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

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

✨ ENVIRONMENT ✨

okay so this section is all about the environment variables that change how CPP behaves 🌸 you can use them to point at directories or prefixes for hunting down include files, or to control dependency output 🔥

ngl, you can also pass search places with options like -I, and control dependency output with options like -M. These take precedence over environment variables, and environment variables take precedence over the configuration of GCC 👑 so the pecking order is options, then env vars, then GCC config 💅

CPATH, C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH 🗂️

each of these holds a list of directories, separated by a special character (much like PATH 🦋), and CPP looks in them for header files. That separator is PATH_SEPARATOR, and it's target-dependent, decided when GCC gets built 🧚 it's a semicolon on Microsoft Windows-based targets and a colon on almost everything else ✨

  • CPATH — searched as if you'd typed -I, but after any -I paths on the command line. This one gets used no matter which language is being preprocessed 🎀
  • C_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJC_INCLUDE_PATH — these only apply when preprocessing the matching language. Each is searched as if you'd typed -isystem, but after any -isystem paths on the command line 💜

in all of these, an empty element tells the compiler to search its current working directory 🌈 empty elements can go at the beginning or end of a path. For example, if CPATH is ":/special/include", that's the exact same as -I. -I/special/include 🫶

DEPENDENCIES_OUTPUT 📝

if this is set, its value tells CPP how to output Make dependencies for the non-system header files it processes. System header files get ignored in this output 🙈

the value can be just a file name, in which case the Make rules get written to that file, and the target name is guessed from the source file name. Or the value can look like file target, in which case the rules are written to file and target is used as the target name 🍓

in other words, this variable is the same as combining -MM and -MF, with an optional -MT switch too 💖

SUNPRO_DEPENDENCIES 🌸

this one is basically DEPENDENCIES_OUTPUT, except system header files are not ignored 😳 so it implies -M rather than -MM. However, the dependence on the main input file is omitted 💀

SOURCE_DATE_EPOCH ⏰

if this is set, its value is a UNIX timestamp used instead of the current date and time in the "__DATE__" and "__TIME__" macros, so the embedded timestamps stay reproducible 🔁

the value must be a UNIX timestamp, which means the number of seconds (excluding leap seconds) since 01 Jan 1970 00:00:00, written in ASCII. It's identical to the output of 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 it should be set by the build process. Don't just wing it! 🚨

📚 SEE ALSO 📚

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

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

okay the legal stuff, but make it cute 🎀 you're allowed 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. 💜

bestie, that's the whole CPP page 🎀 GCC 16 energy, last dated March 22nd, 2026, and you are now officially dangerous with CPATH ✨👑💅

📦 where this page comes from