C++ Include Directive

In the previous lesson, we introduced the preprocessor, and how we can use it to conditionally remove parts of our code before we send it off for compilation.

The second aspect of the preprocessor that we're looking at essentially does the opposite. It give us a way to add additional code to our files.

This can be done using the #include directive. You may have noticed we've already been using an include directive this whole time:

1#include <iostream>
2

We can finally explain what that line is doing!

When we build our project, the preprocessor will see this include directive, and it will replace it with a load of code that is stored in a different file.

With the #include <iostream> instruction specifically, it adds all the code that we've been using to log out to the console. This includes things like cout and endl.

More generally, the #include directive unlocks the ability for us to split our code into multiple files. This is vital for organising non-trivial projects.

With our project seperated into multiple files, we can then use the #include directive any time the code in one file needs to use something in one of our other files.

Commonly, this will be our classes. We can, for example, have the code for our Character class in a different file, such as Character.cpp, and still create Characters in our main.cpp file, as long as we use #include properly:

1// Character.cpp
2class Character {};
3

1// main.cpp
2#include <iostream>
3#include "Character.cpp"
4
5int main() {
6  Character PlayerCharacter;
7}
8

Once the preprocessor encounters #include "Character.cpp" in our main.cpp, it will jump into action and replace that directive with the contains of our Character.cpp file.

Because of this, the code that our compiler receives will be this:

1// main.cpp
2#include <iostream>
3class Character {};
4
5int main() {
6  Character PlayerCharacter;
7}
8

This file now looks very similar to what we've seen in the past. Now, however, instead of having to work with a main.cpp that constantly gets bigger, we're able to organise our project into multiple files, each of them much easier to work with.

Something might be immediately apparent here: when including <iostream> we wrapped it in chevrons - < and > whilst, when we included "Character.cpp" we used double quotes.

The difference in syntax is essentially telling the compiler where to look for the files we're trying to include.

C++ Include Directories - Where does #include look for files?

When we use the < and > syntax, we are letting our tools decide where to look for the requested file. This is covered in more detail in the _Setting Include Directories section below.

The other way we can use the directive is with double quotes " , ie, #include "SomeFile.cpp". The behavior of this approach is that the preprocessor will look in the directory of the requesting file.

For example, if we had this directive in main.cpp, the preprocessor would look in the folder where main.cpp is located, to see if it can find a file called SomeFile.cpp.

If it can't, it will fall back to the checking the locations defined by the compiler or the IDE.

This means that, whether we use <> or "", the preprocessor will probably be able to find the file we need. The difference is mostly just convention.

Typically the "" form would indicate we are trying to import a file we created, or a file we added to our project directly.

On the other hand, the < and > notation often indicates we are trying to import something from a library - often the C++ Standard Library.

The standard library is a collection of generally useful code - such as iostream - that ships alongside C++.

By being separate to the language, we can #include only the parts of the standard library that we need, keeping unnecessary bloat out of our software.

We'll cover the standard library more in later chapters.

Including C++ Files in Different Directories

Not all the files we will want to #include will be in the same directory as the file we're adding the #include directive to.

To solve this, we can add path traversal to our #include directives, as shown below. These paths are relative to the file where the #include directive is beign used.

1// Look in the same directory as the current file
2#include "Math.cpp"
3
4// Look in a directory called Helpers, in the same directory as the current file
5#include "Helpers/Math.cpp"
6
7// Traverse up a level to look in the parent directory of the current file
8#include "../Math.cpp"
9
10// Traverse up two levels, and then into a directory called Helpers
11#include "../../Helpers/Math.cpp"
12

Setting C++ Include Directories

In the previous section, we discussed how our tools (eg, the IDE) would control where the preprocessor looks for files referenced by the #include directive.

Most of the time, our IDEs will set sensible default values for this. However, they will also let us add or modify these locations. In Visual Studio, this is under Project Settings > C/C++ > Include Directories

This is quite useful as, if we have a directory we import from frequently, we can add that to our project settings.

This can make our lives easier, and simplify our #include directives greatly. We could go from something like this:

1#include "../../Math.cpp"
2#include "../../../Shared/Static/Physics.cpp"
3

To something much simpler:

1#include "Math.cpp"
2#include "Physics.cpp"
3

This also makes our projects easier to re-organise. Any time we try to update our directory structure, we could potentially have to update dozens of relative #include directives. Instead, if the path is defined in the include directories, we would only have to update it in that one place.

1// Before
2#include "Character.cpp"
3
4// After
5import Character;
6