Preprocessor Definitions

When we build our code, it is not immediately compiled. Instead, it is first sent to the preprocessor.

The preprocessor is a behind-the-scenes tool. It modifies our code based on special instructions we insert into our source files, known as preprocessor directives.

The preprocessor does not modify our original code. It generates temporary, intermediate copies of our files, and modifies those. Therefore, we normally don't see the modifications the preprocessor does - it happens behind the scenes.

Once the preprocessor has finished generating these temporary copies, with all the changes based on the directives we supply, they are sent off for compilation.

In this lesson, we'll explore how to use these directives to make our projects more flexible and efficient.

Preprocessor Directives

We can give instructions to the preprocessor by including specific instructions in our source code files. These instructions are called directives and, when the preprocessor encounters one, it reacts accordingly.

These preprocessor directives are very powerful - they are a programming language in their own right. They have variables, conditional statements, function-like syntax, and more.

These preprocessor directives give us a range of new abilities, which we'll cover in this chapter. They include:

• Generating different versions of our software from the same source code.
• Defining reusable blocks of code, which we can then quickly add to our files
• Including code others have written, sometimes called library code, to let us build more advanced features quickly
• Splitting our project across multiple files, to keep everything organized.

Conditional Inclusion

A common use of the preprocessor is to determine what code is included in the software we build.

For example, we often want our software to behave differently when run by a developer, compared to a real-world user. To do this, we create different versions, or releases, of our software.

The development version might show a lot more information to help us debug issues. In the releases we use for demos, or ultimately send to customers, all of that additional code is stripped out.

We can do that by wrapping the code we want to conditionally include between #ifdef and #endif directives:

1#include <iostream>
2using namespace std;
3
4int main(){
5  cout << "Hello There";
6#ifdef DEVELOPMENT_BUILD
7  cout << "\nThis is a developer build";
8#endif
9}

In this example, DEVELOPMENT_BUILD is a preprocessor definition that we can choose to set or not. We show how to set this in the next section.

If we set DEVELOPMENT_BUILD, our output will be this:

1Hello There
2This is a developer build

If we don't, our program will output:

1Hello There

The opposite of #ifdef is #ifndef. This will include code if a flag is not defined:

1#include <iostream>
2using namespace std;
3
4int main(){
5  cout << "Hello There";
6#ifndef DEVELOPMENT_BUILD
7  cout << "\nThis is a public build";
8#endif
9}

We can also use #elif (which means "else if") and #else:

1#include <iostream>
2using namespace std;
3
4int main(){
5  cout << "Hello There";
6#ifdef DEVELOPER_BUILD
7  cout << "\nThis is a developer build";
8#elif DEMO_BUILD
9  cout << "\nThis is a demo build";
10#else
11  out << "\nThis is a public build";
12#endif
13}

Setting Preprocessor Definitions

How we set a preprocessor definition, such as our DEVELOPMENT_BUILD example, depends on our IDE.

In Visual Studio, we can set it by selecting Project from the top menu bar, and visiting Project -> Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions

Preprocessor definitions are part of Visual Studio's release configuration system. Within Visual Studio, we can define multiple configurations, and two are usually provided by default - Debug and Release.

We can create more configurations as needed. Each configuration can have its own set of preprocessor definitions (and other settings), and we can then switch between configurations quickly through the user interface.

Other IDEs commonly have similar options. In projects that use CMake, we can set preprocessor definitions using the add_compile_definitions() or target_compile_definitions() functions:

1add_compile_definitions(
2  DEVELOPER_BUILD
3  ANOTHER_DEFINITON
4  YET_ANOTHER
5)

1add_executable(MyProgram "main.cpp")
2
3target_compile_definitions(
4  MyProgram PUBLIC
5  DEVELOPER_BUILD
6  ANOTHER_DEFINITON
7  YET_ANOTHER
8)

The #define Directive

As we saw in the previous section, if we want to provide a preprocessor definition across our whole project, we typically do it through our build tools.

But we don't have to - we can just define things within our source files. For example, we can define a flag like this:

1#define DEVELOPMENT_BUILD

In files where this directive exists, the effect is equivalent to having set it through our tooling:

1#define DEVELOPMENT_BUILD
2
3#include <iostream>
4using namespace std;
5
6int main(){
7  cout << "Hello There";
8#ifdef DEVELOPMENT_BUILD
9  cout << "\nThis is a developer build";
10#endif
11}

1Hello There
2This is a developer build

Some things to note about #define are:

• The things we define with this directive are typically called "macros" - eg, DEVELOPMENT_BUILD is a macro
• To distinguish macros from other C++ code, we typically use all uppercase names with _ as a separator
• We do not end macros with a semi-colon - they are not C++ statements
• Macros are typically defined at or near the top of files. A macro is available from the line it was defined until the end of the file.

Text Replacement Macros

The utility of macros goes beyond simple defined or not-defined logic.

Text substitution macros allow us to #define blocks of code, and then easily insert those blocks of code elsewhere in our project as needed.

The following sections can make people a little nervous, but don't worry. It's fairly uncommon that we need to create text replacement macros. As a beginner, we're much more likely to be using these macros than defining them.

So if the following examples are a bit uncomfortable, just treat them as demonstrations of the types of things that are possible with macros.

Below, we create a DEFINE_INT macro. This will replace any instances of DEFINE_INT in our file with the code to create an integer variable with a value of 4.

1#define DEFINE_INT int MyInt{4};
2
3#include <iostream>
4using namespace std;
5
6struct MyType {
7  DEFINE_INT
8};
9
10int main(){
11  DEFINE_INT
12  cout << "MyInt: " << MyInt << '\n';
13
14  MyType MyObject;
15  cout << "MyObject.MyInt: " << MyObject.MyInt;
16}

1MyInt: 4
2MyObject.MyInt: 4

Below, we define a macro for creating functions. We then use this macro to add a member function to our MyType struct, as well as a free function defined above our main function.

Preprocessor definitions can span multiple lines, by using the \ character as a line break. In the following examples, we added additional white space to distinguish our C++ code from preprocessor code, but it's not required:

1#define DEFINE_GREET         \
2void Greet(){                \
3  cout << "Hello There\n";   \
4};
5
6#include <iostream>
7using namespace std;
8
9struct MyType {
10  DEFINE_GREET
11};
12
13DEFINE_GREET
14
15int main(){
16  Greet();
17
18  MyType MyObject;
19  MyObject.Greet();
20}

1Hello There
2Hello There

Function-Like Macros

Macros can also accept arguments to use within their replacement text. This can make them behave somewhat like functions.

The following version of the macro accepts two arguments to be used in the replacement:

1#define DEFINE_GREET(Greeting, Name)      \
2void Greet() {                            \
3  cout << Greeting << ", I am " << Name   \
4    << "\nNice to meet you!\n\n";         \
5};
6
7#include <iostream>
8using namespace std;
9
10struct Goblin {
11  DEFINE_GREET("Howdy", "a Goblin object")
12};
13
14DEFINE_GREET("Hi there", "a free function")
15
16int main(){
17  Greet();
18
19  Goblin SomeGoblin;
20  SomeGoblin.Greet();
21}

1Hi there, I am a free function
2Nice to meet you!
3
4Howdy, I am a Goblin object
5Nice to meet you!

Again, don't worry if this all looks a little weird. We're unlikely to need to write code like this as a beginner. It's more important at this stage to understand what macros are and how to use them.

A common way to identify when you're using a macro is that they tend to have a UPPERCASE_NAME, for example:

1PROBABLY_A_MACRO("Hello World")

1UE_LOG(LogTemp, Error, TEXT("Hello!"))

Summary

In this lesson, we've explored the essentials of the preprocessor. We covered:

• Preprocessor Role: Explored the preprocessor's function in preparing code for compilation.
• Conditional Inclusion: Covered the use of #ifdef, #ifndef, and related directives for compiling code conditionally.
• Macro Definitions: Discussed defining and using macros to simplify repetitive tasks and code management.
• Text Replacement and Function-Like Macros: Introduced advanced macro uses, used for text replacement within our code.

Preview: The #include directive

Aside from conditional inclusion, the other main preprocessor directive we use is #include.

This allows us to import code from other places into our files, like we've been doing with #include <iostream>.

In the next lesson, we'll cover how the #include directive works, and how we can make full use of it.

Free and Unlimited Access

Professional C++

Unlock the true power of C++ by mastering complex features, optimizing performance, and learning expert workflows used in professional development

View Course