Why don't include guards make a circular #include work?

Question

I have three classes: GameEvents, Physics and GameObject. I have headers for each of them.

• GameEvents has one Physics and a list of GameObjects.
• Physics has a list of GameObjects.

Note the circular dependency. I'm trying to achieve that GameObject is able to access or own a Physics object.

If I simply #include "Physics.h" in GameObject, I get error C2111: 'ClassXXX' : 'class' type redifinition which I understand. This is where I thought include guards would help so I added an include guard to my Physics.h since that's the header I want to include twice.

This is how it looks

#ifndef PHYSICS_H
#define PHYSICS_H

#include "GameObject.h"
#include <list>

class Physics
{
private:
    double gravity;
    list<GameObject*> objects;
    list<GameObject*>::iterator i;
public:
    Physics(void);
    void ApplyPhysics(GameObject*);
    void UpdatePhysics(int);
    bool RectangleIntersect(SDL_Rect, SDL_Rect);
    Vector2X CheckCollisions(Vector2X, GameObject*);
};

#endif // PHYSICS_H

But if I #include "Physics.h" in my GameObject.h now like this:

#include "Texture2D.h"
#include "Vector2X.h"
#include <SDL.h>
#include "Physics.h"

class GameObject
{
private:
    SDL_Rect collisionBox;
public:
    Texture2D texture;
    Vector2X position;
    double gravityForce;
    int weight;
    bool isOnGround;
    GameObject(void);
    GameObject(Texture2D, Vector2X, int);
    void UpdateObject(int);
    void Draw(SDL_Surface*);
    void SetPosition(Vector2X);
    SDL_Rect GetCollisionBox();
};

I get multiple issues that don't understand why they're showing up. If I don't #include "Physics.h" my code runs just fine.

Waldheim

Answer 1

The preprocessor is a program that takes your program, makes some changes (for example include files (#include), macro expansion (#define), and basically everything that starts with #) and gives the "clean" result to the compiler.

The preprocessor works like this when it sees #include:

When you write:

#include "some_file"

The contents of some_file almost literally get copy pasted into the file including it. Now if you have:

a.h:
class A { int a; };

And:

b.h:
#include "a.h"
class B { int b; };

And:

main.cpp:
#include "a.h"
#include "b.h"

You get:

main.cpp:
class A { int a; };  // From #include "a.h"
class A { int a; };  // From #include "b.h"
class B { int b; };  // From #include "b.h"

Now you can see how A is redefined.

When you write guards, they become like this:

a.h:
#ifndef A_H
#define A_H
class A { int a; };
#endif

b.h:
#ifndef B_H
#define B_H
#include "a.h"
class B { int b; };
#endif

So now let's look at how #includes in main would be expanded (this is exactly, like the previous case: copy-paste)

main.cpp:
// From #include "a.h"
#ifndef A_H
#define A_H
class A { int a; };
#endif
// From #include "b.h"
#ifndef B_H
#define B_H
#ifndef A_H          // From
#define A_H          // #include "a.h"
class A { int a; };  // inside
#endif               // "b.h"
class B { int b; };
#endif

Now let's follow the preprocessor and see what "real" code comes out of this. I will go line by line:

// From #include "a.h"

Comment. Ignore! Continue:

#ifndef A_H

Is A_H defined? No! Then continue:

#define A_H

Ok now A_H is defined. Continue:

class A { int a; };

This is not something for preprocessor, so just leave it be. Continue:

#endif

The previous if finished here. Continue:

// From #include "b.h"

Comment. Ignore! Continue:

#ifndef B_H

Is B_H defined? No! Then continue:

#define B_H

Ok now B_H is defined. Continue:

#ifndef A_H          // From

Is A_H defined? YES! Then ignore until corresponding #endif:

#define A_H          // #include "a.h"

Ignore

class A { int a; };  // inside

Ignore

#endif               // "b.h"

The previous if finished here. Continue:

class B { int b; };

This is not something for preprocessor, so just leave it be. Continue:

#endif

The previous if finished here.

That is, after the preprocessor is done with the file, this is what the compiler sees:

main.cpp
class A { int a; };
class B { int b; };

So as you can see, anything that can get #included in the same file twice, whether directly or indirectly needs to be guarded. Since .h files are always very likely to be included twice, it is good if you guard ALL your .h files.

P.S. Note that you also have circular #includes. Imagine the preprocessor copy-pasting the code of Physics.h into GameObject.h which sees there is an #include "GameObject.h" which means copy GameObject.h into itself. When you copy, you again get #include "Pysics.h" and you are stuck in a loop forever. Compilers prevent that, but that means your #includes are half-done.

Before saying how to fix this, you should know another thing.

If you have:

#include "b.h"

class A
{
    B b;
};

Then the compiler needs to know everything about b, most importantly, what variables it has etc so that it would know how many bytes it should put in place of b in A.

However, if you have:

class A
{
    B *b;
};

Then the compiler doesn't really need to know anything about B (since pointers, regardless of the type have the same size). The only thing it needs to know about B is that it exists!

So you do something called "forward declaration":

class B;  // This line just says B exists

class A
{
    B *b;
};

This is very similar to many other things you do in header files such as:

int function(int x);  // This is forward declaration

class A
{
public:
    void do_something(); // This is forward declaration
}

Shig

Thanks, this has helped me a lot and I have a better understanding of what's happening. I have successfully forward declared a Physics *physics in my GameObject.h. but if I understand it correctly I cannot create a Physics in my GameObject, I have to pass an existing pointer to my GameObject.cpp? – Waldheim

I can't seem to understand how I access the physics pointer in my GameObject.cpp If I attempt physics->CheckCollisions() I get "pointer to incomplete class type is not allowed" and no member found. – Waldheim

I solved it, but I'm still a little confused. I forward declared class Physics; in my GameObject.h as well as a Physics *physics; in the GameObject.h body. Then in GameObject.cpp I included "Physics.h" and let the GameEvents pass down a *Physics in the GameObject constructor. This works for me now. Please tell me if this will cause problems in the future. Anyhow I'm very grateful for all your help. – Waldheim

@Waldheim I don't see a Physics object or pointer in your GameObject class, but I see a lot of GameObject *s in your Physics class. This suggests forward declaring GameObject in Physics.h rather than the other way around. Either way, when you want to use the class (that is in the .cpp files), you need to include each header itself. Since you don't include .cpp files, there is no risk of circular includes! – Shig

How does the compiler interpret A_H and B_H in #define which have not appeared (defined) before? How does it know these are related to a.h or b.h? – Teacher

@hans, it doesn't know they are related to a.h and b.h! The preprocessor first copies a.h and b.h where they are #included. Then it starts looking at what's inside. The first time it sees #define A_H, well it defines it. In fact this define shouldn't happen twice – Shig

I was wondering where things like A_H was defined, like a file named A_H. I think what you are saying is that the lines between #define A_H and #endif is the definition of A_H. So actually you can say anything completely unrelated to a.h or b.h. Am I right? – Teacher

If the answer to my previous question is positive, my followup question is, when the content (definition) of #define A_H is not sandwiched between #ifndef and #endif but elsewhere, and extends several lines below #define, how does the compiler know where the definition of A_H ends if there is no such notation as #enddef? – Teacher

@hans, no no, the definition of a symbol through #define is contained in the same line. For example #define SOME_SYMBOL (some_expression) means the preprocessor would replace SOME_SYMBOL where it sees from that point on with (some_expression). If you have #define SOME_SYMBOL with nothing in front of it, it would replace it every it sees it with nothing. So #define A_H means "define a symbol named A_H which replaces with nothing". The part that is important to us is the "define a symbol named A_H", because later we want to have an if on whether the symbol is defined (#ifndef). – Shig

By the way, I arbitrarily chose A_H for file named a.h just to resemble it. You could have used any other symbol, such as SWEET_HEADER_OF_MINE. However, naming the guard symbol the same as the header file (or derived from it) helps avoid name collision among many headers. If you use the same guard symbol for two headers, you can imagine what would happen (the second header included would be ignored since that symbol is already defined in the first header). – Shig

Try reading on the C preprocessor too. – Shig

So, class A {int a} has nothing to do with #define A_H and is truly part of #ifndef...#endif' right? Also #define A_H` with A_H being assigned nothing is there only to formally make A_H defined, right? – Teacher

"since pointers, regardless of the type have the same size" That is not true. Pointers to structs and classes have the same size, but pointers to other types can be different. char* and void* must be big enough that you can cast to them and back without loss of data. (There have been implementations where sizeof (void*) > sizeof(struct t*).) – Fleur

Answer 2

You have circular references here: Physics.h includes GameObject.h which includes Physics.h. Your class Physics uses GameObject* (pointer) type so you don't need to include GameObject.h in Physics.h but just use forward declaration - instead of

#include "GameObject.h" 

put

class GameObject;   

Furthermore, put guards in each header file.

Humid

Answer 3

The issue is that your GameObject.h does not have guards, so when you #include "GameObject.h" in Physics.h it gets included when GameObject.h includes Physics.h.

Beeswing

Answer 4

Add include guards in all your *.h or *.hh header files (unless you have specific reasons to not do that).

To understand what is happening, try to get the preprocessed form of your source code. With GCC, it is something like g++ -Wall -C -E yourcode.cc > yourcode.i (I have no idea on how Microsoft compilers do that). You can also ask which files are included, with GCC as g++ -Wall -H -c yourcode.cc

Eveliaevelin

Answer 5

Firstly you need include guards on gameobject too, but that's not the real problem here

If something else includes physics.h first, physics.h includes gameobject.h, you get something like this:

class GameObject {
...
};

#include physics.h

class Physics {
...
};

and the #include physics.h gets discarded because of the include guards, and you end up with a declaration of GameObject before the declaration of Physics.

But that's a problem if you want GameObject to have a pointer to a Physics, because for htat physics would have to be declared first.

To resolve the cycle, you can forward-declare a class instead, but only if you are just using it as a pointer or a reference in the declaration following, i.e.:

#ifndef PHYSICS_H
#define PHYSICS_H

//  no need for this now #include "GameObject.h"

#include <list>

class GameObject;

class Physics
{
private:
    list<GameObject*> objects;
    list<GameObject*>::iterator i;
public:
    void ApplyPhysics(GameObject*);
    Vector2X CheckCollisions(Vector2X, GameObject*);
};

#endif // PHYSICS_H

Basilius

I've added guards for all headers but when I replace the #include "GameObject.h" with Class GameObject; Visual Studio returns error for every single line of code in both Physics.cpp and Physics.h. The same happens if I try to forward declare any other class in any header. – Waldheim

Answer 6

Use include guards in ALL your header files. Since you are using Visual Studio you could use the #pragma once as the first preprocessor definition in all your headers.

However I suggest to use the classical approach:

#ifndef CLASS_NAME_H_
#define CLASS_NAME_H_

// Header code here

#endif //CLASS_NAME_H_

Second read about forward declaration and apply it.

Cathcart

Answer 7

The goal of a header guard is to avoid including the same file many times. But the header guard that is currently used in C ++ can be improved. The current guard is:

#ifndef AAA_H
#define AAA_H

class AAA
{ /* ... */ };

#endif

My new guard proposal is:

#ifndef AAA_H
#define AAA_H

class AAA
{ /* ... */ };

#else
class AAA;  // Forward declaration
#endif

This resolves the annoying problem that occurs when the AAA class needs the BBB class declaration, while the BBB class needs the AAA class declaration, typically because there are crossed pointers from one class to the other:

// File AAA.h
#ifndef AAA_H
#define AAA_H

#include "BBB.h"

class AAA
{ 
  BBB *bbb;
/* ... */ 
};

#else
class AAA;  // Forward declaration
#endif

//+++++++++++++++++++++++++++++++++++++++

// File BBB.h
#ifndef BBB_H
#define BBB_H

#include "AAA.h"

class BBB
{ 
  AAA *aaa;
/* ... */ 
};

#else
class BBB;  // Forward declaration
#endif

I would love for this to be included in the IDEs that automatically generate code from templates.

Pattison

Answer 8

" #pragma once " ::: serves the same purpose as header guards, and has the added benefit of being shorter and less error-prone.

Many compilers support a simpler, alternate form of header guards using the #pragma directive: " #pragma once " // your code here

However, #pragma once is not an official part of the C++ language, and not all compilers support it (although most modern compilers do).

For compatibility purposes, people recommend sticking to traditional header guards. They aren’t much more work and they’re guaranteed to be supported on all compliant compilers.

Cassandracassandre