.CPP File Format – Preprocessor

Directives

A directive is a line whose first token, after any white space, is # [cpp.pre]. It ends at the next new-line, so a long directive needs a backslash at the end of each continued line.

The operator _Pragma("text") (C++11) has the same effect as a #pragma line, but can be produced by macro expansion [cpp.pragma.op].

Conditional inclusion

if-group:
    # if constant-expression new-line [group]
    # ifdef identifier new-line [group]
    # ifndef identifier new-line [group]

elif-group:
    # elif constant-expression new-line [group]
    # elifdef identifier new-line [group]
    # elifndef identifier new-line [group]

defined-macro-expression:
    defined identifier
    defined ( identifier )

has-include-expression:
    __has_include ( header-name )
    __has_include ( header-name-tokens )

has-attribute-expression:
    __has_cpp_attribute ( pp-tokens )

After macro expansion and the evaluation of defined, __has_include and __has_cpp_attribute, every identifier and keyword that is left, other than true and false, is replaced by 0 [cpp.cond]. An undefined macro name therefore silently counts as 0. The expression uses std::intmax_t or std::uintmax_t. It cannot use sizeof, casts or enumerators, since the preprocessor does not know about them.

#if defined(_WIN32) && !defined(NOMINMAX)
#  define NOMINMAX
#endif

#ifdef FEATURE_X
    void run_x();
#elifdef FEATURE_Y        // C++23
    void run_y();
#else
#  error "No feature selected"
#endif

Including files

Nesting depth is limited only by the implementation. The standard’s minimum recommended quantity is 256 levels (Annex B). #include does not check whether a file was already included, which is why headers need include guards.

#if __has_include(<optional>)
#  include <optional>
#  define HAVE_OPTIONAL 1
#elif __has_include("legacy_optional.h")
#  include "legacy_optional.h"
#  define HAVE_OPTIONAL 2
#else
#  define HAVE_OPTIONAL 0
#endif

Macros

control-line:
    # define identifier replacement-list new-line
    # define identifier lparen [identifier-list] ) replacement-list new-line
    # define identifier lparen ... ) replacement-list new-line
    # define identifier lparen identifier-list , ... ) replacement-list new-line
    # undef identifier new-line

A macro name is an identifier, and may be a keyword. Defining or undefining a predefined macro is undefined behaviour. A macro may be redefined only with an identical definition; otherwise it must be #undef’d first [cpp.replace]. An object-like macro has no parameter list. For a function-like macro, the ( must follow the name immediately, with no space, or it becomes part of the replacement.

#define STR(x)   #x
#define XSTR(x)  STR(x)
#define VER      12

STR(VER)    // "VER": the argument is not expanded before #
XSTR(VER)   // "12": the outer macro expands it first

#define JOIN(a, b)  a##b
JOIN(foo, 1)  // foo1

#define LOG(fmt, ...)  printf(fmt __VA_OPT__(,) __VA_ARGS__)

LOG("hello\n");           // printf("hello\n")
LOG("x=%d\n", 42);        // printf("x=%d\n", 42)

Predefined macros

These are always defined [cpp.predefined].

Some are defined only conditionally:

__func__ looks like a macro but is not: it is a predefined local variable of a function, holding the function’s name [dcl.fct.def.general]. Names like __FUNCTION__ and __PRETTY_FUNCTION__ are compiler extensions.

Feature-test macros

C++20 standardised macros that report which features a compiler supports. The value is the year and month the feature reached its listed form, so later values mean more complete support. Language macros are predefined, and start with __cpp_ [cpp.predefined]. Library macros start with __cpp_lib_ and are defined in <version> and in each header that has the feature.

#if defined(__cpp_concepts) && __cpp_concepts >= 201907L
    template<std::integral T> T twice(T v) { return v * 2; }
#else
    template<class T> T twice(T v) { return v * 2; }
#endif

#include <version>
#ifdef __cpp_lib_format
#  include <format>
#endif

The language macros in the C++23 working draft (N4950) are:

Pragmas in common use

The standard defines no pragmas. The meaning of each is up to the compiler, and an unrecognised one is ignored. These are widely supported extensions.