Preprocessor Directives in C++

Before your C++ code is compiled into a program, a special step runs first called preprocessing. The preprocessor is like an assistant that reads through your code and makes changes before handing it to the compiler. Instructions given to the preprocessor are called preprocessor directives, and they always start with the # symbol.

Think of the preprocessor like a chef who preps ingredients before cooking begins — chopping, mixing, and arranging everything so the actual cooking (compiling) goes smoothly.

Types of Preprocessor Directives

┌──────────────────────┬────────────────────────────────────────────┐
│ Directive            │ Purpose                                    │
├──────────────────────┼────────────────────────────────────────────┤
│ #include             │ Insert another file's content here         │
│ #define              │ Create a macro (name for a value or code)  │
│ #undef               │ Remove a previously defined macro          │
│ #ifdef / #ifndef     │ Compile code only if macro is defined      │
│ #if / #elif / #else  │ Conditional compilation with expressions   │
│ #endif               │ End an #if / #ifdef block                  │
│ #pragma              │ Compiler-specific instructions             │
└──────────────────────┴────────────────────────────────────────────┘

#include — Including Files

#include tells the preprocessor to paste the contents of another file right at that line. It is the most commonly used directive.

System Headers (angle brackets):

#include <iostream>    // standard input/output
#include <string>      // string class
#include <vector>      // vector container
#include <cmath>       // math functions

User-Defined Headers (double quotes):

#include "myutils.h"   // your own header file

Angle brackets tell the compiler to look in the system's library folders. Double quotes tell it to look in the current project folder first.

#define — Creating Macros

#define creates a macro — a name that the preprocessor replaces with something else everywhere in the code. It is like creating a shortcut or an alias.

Simple Constant Macro:

#include <iostream>
using namespace std;

#define PI 3.14159
#define MAX_SIZE 100

int main() {
    double area = PI * 5 * 5;
    cout << "Area of circle: " << area << endl;
    cout << "Max size: " << MAX_SIZE << endl;
    return 0;
}

Output:

Area of circle: 78.5397
Max size: 100

Before compilation, the preprocessor replaces every occurrence of PI with 3.14159 and MAX_SIZE with 100. The compiler never sees the names — only the values.

Function-Like Macros:

Macros can also behave like small functions using parentheses.

#define SQUARE(x) ((x) * (x))
#define MAX(a, b) ((a) > (b) ? (a) : (b))

int main() {
    cout << SQUARE(5) << endl;      // 25
    cout << MAX(10, 20) << endl;    // 20
    return 0;
}

Always wrap macro arguments in parentheses. Without them, expressions like SQUARE(2+3) would expand to 2+3 * 2+3 instead of (2+3) * (2+3), giving wrong results.

#undef — Removing a Macro

#undef removes a previously defined macro. After this line, that name is no longer recognized as a macro.

#define TEMP 100
// ... use TEMP ...
#undef TEMP
// now TEMP is undefined — using it here causes a compile error

Conditional Compilation

Conditional directives let you include or exclude parts of code based on whether a macro is defined or what its value is. This is very useful for writing code that works differently on different platforms (Windows vs Linux) or in debug vs release mode.

#ifdef and #ifndef

#include <iostream>
using namespace std;

#define DEBUG_MODE

int main() {
    int result = 42;

#ifdef DEBUG_MODE
    cout << "[DEBUG] Result = " << result << endl;
#endif

    cout << "Program complete." << endl;
    return 0;
}

Output (when DEBUG_MODE is defined):

[DEBUG] Result = 42
Program complete.

If you comment out or remove #define DEBUG_MODE, the debug output line disappears from the compiled code completely — it is as if it was never written.

#ifndef — If NOT Defined

#ifndef PI
    #define PI 3.14159
#endif

This defines PI only if it has not been defined already. This pattern is common in header files to prevent defining the same macro twice.

#if, #elif, #else

#define VERSION 2

#if VERSION == 1
    // code for version 1
#elif VERSION == 2
    // code for version 2
#else
    // code for any other version
#endif

Header Guards — Preventing Double Inclusion

If a header file is included twice in the same program, the compiler sees duplicate declarations and throws an error. Header guards prevent this using #ifndef, #define, and #endif.

Diagram: Header Guard Pattern

// mymath.h

#ifndef MYMATH_H       ← "Has MYMATH_H been defined yet?"
#define MYMATH_H       ← "No? OK, define it now."

int add(int a, int b);
int multiply(int a, int b);

#endif                 ← "Done. End of guarded block."

The second time this file is included, MYMATH_H is already defined, so everything between #ifndef and #endif is skipped. No duplicate declarations reach the compiler.

Modern Alternative: #pragma once

#pragma once   // put this at the top of a header file

int add(int a, int b);

#pragma once achieves the same result as header guards with less code. Most modern compilers support it.

#pragma — Compiler Instructions

#pragma sends special instructions to the compiler. These vary by compiler but common ones include:

#pragma once              // prevent double inclusion (widely supported)
#pragma comment(lib, "somelib.lib")  // link a library (MSVC)
#pragma warning(disable : 4996)      // suppress a specific warning (MSVC)

Predefined Macros

C++ provides built-in macros that give useful information about the code at compile time.

#include <iostream>
using namespace std;

int main() {
    cout << "File: "    << __FILE__  << endl;
    cout << "Line: "    << __LINE__  << endl;
    cout << "Date: "    << __DATE__  << endl;
    cout << "Time: "    << __TIME__  << endl;
    return 0;
}

Sample Output:

File: main.cpp
Line: 6
Date: Sep 17 2026
Time: 10:45:30

Key Takeaways

• Preprocessor directives run before compilation and start with #.
• #include pastes another file's content into your code.
• #define creates macros — names the preprocessor replaces with values or code.
• Conditional directives like #ifdef let you compile different code in different situations.
• Header guards prevent duplicate declarations when a header file is included multiple times.
• #pragma once is a simpler modern alternative to traditional header guards.