Conditional Inclusion - `#if`, `#ifdef`, `#endif` and friends

Conditional Inclusion (`#if`, `#ifdef`, etc) vs Runtime Conditionals (`if`, `else`, etc)

Header Guards and the `#pragma once` directive

Free, Unlimited Access

Comprehensive course covering advanced concepts, and how to use them on large-scale projects.

Professional C++





<Excerpt>


This lesson is a quick introductory tour of header files and the build process within C++.  It is not intended for those who are entirely new to programming.  Rather, the people who may find it useful include:

- those who have completed our introductory course, but want a quick review
- those who are already familiar with programming in another language, but are new to C++
- those who have used C++ in the past, but would benefit from a refresher

It summarises several lessons from our introductory course.  Those looking for more thorough explanations or additional context should consider completing _**Chapter 7**_ of that course.


</Excerpt>


<CoursePromo course="intro" />


## The Build Process


In C++, building code is broken into three steps:

- The **preprocessor** executes all our preprocessor directives, such as `#include`, to generate _translation units_
- The **compiler** translates each of these translation units into collections of machine code called _object files_
- The **linker** connects the object files together, into a single coherent package (eg, an executable file, or a library)

When we declare a function without defining it we are, in effect, telling the compiler that we’re going to define the function elsewhere.  We’re telling the compiler that the linker will take care of it.


So, as long as our function is defined _somewhere_ in the translation units that are sent to the compiler, the linker will be able to complete the build process successfully.


We previously mentioned functions can be declared and defined in different places.  This separation is most typically done to split our code into _**header files**_ and _**source files**_.


## Header Files


This is most common when dealing with class member functions


It is conventional for large classes to be split into two files - a “header” file to store the declarations, and a “source” file to store the definitions.  Header files typically have the `.h` extension, whilst source files often use `.cpp`:


```c++
// Character.h
class Character {
  int Health{100};
  void TakeDamage(int Damage);
};
```


```c++
// Character.cpp
#include "Character.h"

void Character::TakeDamage(int Damage) {
  Health -= Damage;
}
```


This is a convention not widely adopted outside of C++, so it’s worth giving a slightly longer explanation.


One benefit of this approach is that it gives us a quick way to get an overview of a class.  We only need to look at the header file to get a good sense of what it does.


However, more importantly, it allows us to adopt a convention where we only need to `#include` header files rather than the full implementations.  This keeps compilation times to a minimum.


## Preprocessor Directives


The way we communicate with the preprocessor is through _**preprocessor directives**_.  We already covered the `#include` directive, but there are a few more


### The `#define` directive


The `#define` directive lets us define a block of text, which we can then reuse across our file.  The thing we define is typically called a _**macro**_.  To distinguish macros from regular variables, we typically give them UPPERCASE names, but this is not required.


Note that preprocessor directives are not C++ statements, so we do not need to include semicolons.


In the following code, the preprocessor will replace `INTEGER_TYPE` with `int`


```c++
#define INTEGER_TYPE int

INTEGER_TYPE MyVariable{5};
```


As such, what the compiler sees will simply be:


```c++
int MyVariable{5};
```


There is a more advanced form of this, which allows us to pass arguments to our macros, effectively turning them into functions.  This is something we cover later in this course.


### Conditional Inclusion - `#if`, `#ifdef`, `#endif` and friends


The preprocessor includes support for conditional logic.  This allows us to control which parts of our code get included or excluded from the compilation process.


```c++
#include <iostream>
#define DAY 7

int main() {
#if DAY >= 6
  std::cout << "It's the weekend";
#endif
}
```


Typically, our conditional inclusion is based on whether or not we have defined a macro at all.  This is used to generate different versions of our software.  For example, we’re likely to have a “developer” or “debug” version of our software.


This version will include extra code to help us visualize what is going on during the development process, but we want it to be removed from what we ship to our users.


We can set this up by wrapping any such code in a directive that checks if a specific macro is defined


```c++
#include <iostream>

int main() {
#if defined(DEBUG_MODE)
  std::cout << "Logging extra diagnostics";
#endif
}
```


Our build tools will give us the option to inject a preprocessor definition across our entire project, thereby letting us create these alternative builds in a simple, automated way.


The `#if defined(SOMETHING)` pattern is so common, there is a shortened form - `#ifdef`:


```c++
#ifdef DEBUG_MODE
 // ...
#endif
```


<Aside>


### Conditional Inclusion (`#if`, `#ifdef`, etc) vs Runtime Conditionals (`if`, `else`, etc)


Note that conditional inclusion is not equivalent to standard conditional logic, such as an `if` statement.  Conditional inclusion is done at compile time, whilst `if` statements are at run time.  This has two implications:

- Conditional inclusion has no performance cost at run time
- Conditional inclusion entirely removes code from our build. This means our program is smaller, and those features cannot be discovered or re-enabled by users reverse-engineering our software

</Aside>


We also have some additional preprocessor directives that can help us build more advanced conditional logic:

- `#else` - The basic equivalent of an else statement
- `#elif` - The preprocessor equivalent of an else-if statement
- `#ifndef` - “if not defined” - for example, `#ifndef SOMETHING` is equivalent to `#if !defined(SOMETHING)`

The following uses these directives in a more complex example, which includes nested conditionals:


```c++
#include <iostream>
#define DAY 7

int main(){
#ifndef DAY
  std::cout << "I don't know what day it is";
#elif DAY >= 6
  std::cout << "It's the weekend";
  #if DAY == 6
    std::cout << " (Saturday)";
  #else
    std::cout << " (Sunday)";
  #endif
#else
  std::cout << "It's a weekday";
#endif
}
```


```c++
//<o>
It's the weekend (Sunday)
```


Two additional directives were added in the C++23 language specification, and may not yet be available in all compilers:

- `#elifdef` - “else if defined” - for example, `#elifdef SOMETHING` is equivalent to `#elif defined(SOMETHING)`
- `#elifndef` - “else if not defined” - for example, `#elifndef SOMETHING` is equivalent to `#elif !defined(SOMETHING)`

### Header Guards and the `#pragma once` directive


When we use the `#include` directive, code from one file effectively gets copied and pasted into another.  This can cause problems when a file gets included multiple times.  This usually happens indirectly - for example:

- if `File A` includes `File B` and `File C`
- and `File B` includes `File C`

Then `File A` ends up including `File C` twice.  Once directly, and once indirectly through `File B`


We prevent this using header guards, which are a form of conditional inclusion:


```c++
#ifndef MyClass
#define MyClass

class MyClass {
  // ...
};

#endif
```


The first time the above file gets included, `MyClass` is not defined within the preprocessor, so the entire contents of the file are copied across.


That includes a definition for `MyClass` so, after the first inclusion, `MyClass` is then defined.  If the file is included a second time, the `#ifndef` directive detects the definition, so everything until `#endif` (effectively the whole file) gets excluded.


This pattern is so common that a dedicated directive is available to handle the use case - the `#pragma once` directive:


```c++
#pragma once

class MyClass {
  // ...
};
```


<Aside>


### This is Weird


At this point, seems like the preprocessor is pretty much a programming language in its own right.


If the concept of a programming language within a programming language seems slightly off, you’re not alone in thinking that.  It is a long-term goal of C++ to reduce the relevance of the preprocessor, by covering its use cases within the base C++ language.


For example, the C++17 spec introduced `if constexpr` statements.  These are a variant of the basic `if` statement that eliminates branches of code at compile time and is, therefore, an alternative to the preprocessor’s conditional inclusion features


C++20 introduced _**modules**_, which allow us to organize our code into smaller parts without requiring any `#include` directives to bring it back together.


We cover both of these later in this course, but C++ development tends to be slower and more cautious than what we might be accustomed to from other languages.


It can take years for compilers to support new language features, and decades for them to become widely adopted within real-world projects.  So, we need to be comfortable with the preprocessor for quite some time yet.


</Aside>


## Summary


The C++ build process involves three main steps: preprocessing, compiling, and linking. Preprocessor directives, header files, and source files play crucial roles in organizing and manipulating code before compilation.  Key takeaways:

- The preprocessor executes directives and generates translation units
- The compiler translates translation units into object files
- The linker connects object files into an executable or library
- Header files (.h) typically contain class and function declarations
- Source files (.cpp) contain the corresponding definitions
- Key preprocessor directives: #include, #define, conditional inclusion (#if, #ifdef, etc.), and #pragma once

<FAQ>


```javascript
//<m>
{
  slug: 'defining-macros-with-arguments',
  title: 'Defining Macros with Arguments',
  question: 'How can I define a macro that takes arguments in C++?',
}
```


You can define macros with arguments using the `#define` directive. Here's an example:


```c++
#include <iostream>

#define MULTIPLY(a, b) ((a) * (b))//<h>

int main() {
  std::cout << MULTIPLY(3, 4) << "\n";
  std::cout << MULTIPLY(2 + 3, 4 + 5) << "\n";
}
```


```text
//<o>
12
45
```


When defining macros with arguments, it's important to surround the arguments with parentheses to ensure proper precedence. This prevents unexpected behavior when the macro is expanded with complex expressions as arguments.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'ifdef-vs-if-defined',
  title: '`#ifdef` vs `#if defined()`',
  question: 'What is the difference between `#ifdef` and `#if defined()` in C++?',
}
```


Both `#ifdef` and `#if defined()` are used for conditional compilation in C++, but they have a slight difference in syntax.


The `#ifdef MACRO` checks if `MACRO` is defined. If it is, the code block following the directive is included in the compilation.


```c++
#include <iostream>
#define DEBUG

int main() {
#ifdef DEBUG  //<h>
  std::cout << "Debug mode is on\n";
#endif
}
```


```c++
//<o>
Debug mode is on
```


`#if defined(MACRO)` also checks if `MACRO` is defined, but it allows for more complex expressions.


```c++
#include <iostream>
#define DEBUG

int main() {
#if defined(DEBUG) && !defined(RELEASE)  //<h>
  std::cout << "Debug mode is on,"
    " Release mode is off\n";
#endif
}
```


```c++
//<o>
Debug mode is on, Release mode is off
```


In most cases, `#ifdef` and `#if defined()` can be used interchangeably. However, `#if defined()` provides more flexibility when combining multiple conditions using logical operators like `&&` and `||`.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'preventing-multiple-header-inclusion',
  title: 'Preventing Multiple Header Inclusion',
  question: 'What are the best practices to prevent multiple inclusion of header files?',
}
```


To prevent multiple inclusion of header files, you can use either header guards or the `#pragma once` directive.


### Header Guards


Header guards work by checking if a unique macro is defined. If it's not defined, the header content is included, and the macro is defined to prevent subsequent inclusions.


```c++
// MyHeader.h
#ifndef MYHEADER_H//<h>
#define MYHEADER_H

// Header content goes here

#endif
```


### `#pragma once`


The `#pragma once` directive tells the compiler to include the header file only once during compilation. It's a simpler alternative to header guards.


```c++
// MyHeader.h
#pragma once//<h>

// Header content goes here
```


Best practices:

- Use either header guards or `#pragma once` in all your header files.
- Choose a consistent naming convention for header guards (e.g., `MYPROJECT_MYHEADER_H`).
- Prefer `#pragma once` if your compiler supports it, as it's more concise and less error-prone.

By following these practices, you can avoid common issues like redefinition errors and circular dependencies caused by multiple header inclusions.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'using-ifdef-for-platform-specific-code',
  title: 'Using `#ifdef` for Platform-Specific Code',
  question: 'How can I use `#ifdef` to write platform-specific code in C++?',
}
```


You can use `#ifdef` along with platform-specific macros to conditionally compile code for different platforms. Here's an example:


```c++
#include <iostream>

#ifdef _WIN32  //<h>
#include <windows.h>
void PlatformSpecificFunction() {
  // Windows-specific code
  std::cout << "Running on Windows\n";
}

#elif defined(__APPLE__)  //<h>
#include <CoreFoundation/CoreFoundation.h>
void PlatformSpecificFunction() {
  // macOS-specific code
  std::cout << "Running on macOS\n";
}

#elif defined(__linux__)  //<h>
#include <unistd.h>
void PlatformSpecificFunction() {
  // Linux-specific code
  std::cout << "Running on Linux\n";
}

#else
#error "Unsupported platform"//<h>
#endif

int main() {
  PlatformSpecificFunction();
}
```


```c++
//<o>
Running on Windows
```


In this example:

- `#ifdef _WIN32` checks if the code is being compiled for Windows.
- `#elif defined(__APPLE__)` checks if the code is being compiled for macOS.
- `#elif defined(__linux__)` checks if the code is being compiled for Linux.
- `#else` block handles unsupported platforms and raises a compilation error with `#error`.

By using platform-specific macros and `#ifdef`, you can include platform-specific headers, define platform-specific functions, and write code tailored for different operating systems.


Note: The exact macros and headers used may vary depending on the compiler and platform. Consult your compiler's documentation for the appropriate macros to use.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'defining-constants-with-define',
  title: 'Defining Constants with `#define`',
  question: 'Should I use `#define` to define constants in C++?',
}
```


While `#define` can be used to define constants in C++, it's generally recommended to use `const` or `constexpr` variables instead. Here's why:


### Type Safety


With `#define`, the preprocessor performs a simple text replacement. The constant `PI` doesn't have a type, which can lead to unexpected behavior or type mismatches.


```c++
#define PI 3.14159//<h>

double area = PI * radius * radius;
```


### Scoping and Namespaces


Using `const` or `constexpr`, the constant `PI` is a typed variable with a specific scope. It respects namespaces and follows the usual scoping rules, preventing name clashes.


```c++
const double PI = 3.14159;//<h>

double area = PI * radius * radius;
```


### Debugging


When using `#define`, the preprocessor replaces `MAX_SIZE` with `100` before compilation. If you encounter an issue related to `MAX_SIZE`, the debugger will show `100` instead of `MAX_SIZE`, making it harder to understand the code.


```c++
#define MAX_SIZE 100//<h>

int array[MAX_SIZE];
```


### Consistency with Variables


By using `const` or `constexpr`, you define constants in the same way as variables, making the code more consistent and readable.


```c++
constexpr int MAX_SIZE = 100;//<h>

int array[MAX_SIZE];
```


In modern C++, `const` and `constexpr` provide a type-safe and more maintainable way to define constants. They offer better type checking, scoping, and debugging capabilities compared to `#define`. Therefore, it's recommended to prefer `const` and `constexpr` over `#define` for defining constants in C++.


</FAQ>


<FAQ>


```javascript
//<m>
{
  slug: 'using-pragma-once-in-header-files',
  title: 'Using `#pragma once` in Header Files',
  question: 'What are the advantages of using `#pragma once` in header files?',
}
```


Using `#pragma once` in header files offers several advantages over traditional header guards:


### Simplicity and Readability


With `#pragma once`, you only need a single line at the beginning of the header file. It makes the code cleaner and more readable compared to header guards, which require three lines of code.


```c++
// MyHeader.h
#pragma once//<h>

// Header content goes here
```


### Reduced Typing and Maintenance:


When using header guards, you need to choose a unique name for each header file and ensure that the same name is used for the `#ifndef`, `#define`, and `#endif` directives. With `#pragma once`, you don't need to worry about unique names or maintaining the consistency of guard macros.


```c++
// MyHeader.h
#ifndef MYHEADER_H//<h>
#define MYHEADER_H

// Header content goes here

#endif
```


### Compilation Speed


The `#pragma once` directive is typically faster for the compiler to process compared to header guards. When the compiler encounters `#pragma once`, it can quickly check if the header file has already been included and skip processing it again, improving compilation speed.


```c++
// MyHeader.h
#pragma once//<h>

// Header content goes here
```


### Compatibility


Most modern compilers support `#pragma once`, including GCC, Clang, and Microsoft Visual C++. However, if you need to support older compilers or ensure maximum portability, you can use a combination of `#pragma once` and header guards, as shown in the example above.


```c++
// MyHeader.h
#if defined(__GNUC__)   \
  || defined(__clang__) \
  || defined(_MSC_VER)    
  #pragma once
#else
  #ifndef MYHEADER_H
  #define MYHEADER_H

// Header content goes here

  #endif
#endif
```


While `#pragma once` offers several advantages, it's important to note that it's a non-standard extension. If portability across all compilers is a concern, you may still choose to use header guards. However, for most modern C++ projects, `#pragma once` is widely supported and provides a simpler and more efficient way to prevent multiple header inclusions.


</FAQ>



Learn the fundamentals of the C++ build process, including the roles of the preprocessor, compiler, and linker.