C struct compilation fails

You have a circular header dependency, which is bad design and almost always leads to failures. The problem is complicated by an overly-complicated naming strategy which makes the code really difficult to read.

Here's the basic problem, using significantly simplified names:

File driver.h

#ifndef DRIVER_H
#define DRIVER_H

#include "state.h"

/* See answer text for an explanation of this declaration style. */
typedef struct Driver Driver;
struct Driver {
  // ...
  State state;
  // ...
};

#endif

File state.h

#ifndef STATE_H
#define STATE_H

// Needed because the Driver type is used in a prototype
#include "driver.h"

typedef struct State State;
struct State {
  // ...
};

// Attempt to fix circular dependency with a redundant declaration.
typedef struct Driver Driver;
int32_t stateTask(Driver* driver);
#endif

So these two headers include each other. The header guards will keep them from being included twice, but they won't guarantee that the declarations are read in the correct order. What will happen depends on which order you #include the two headers:

• If you first #include "driver.h", it will set its header guard and immediately #include "state.h". It hasn't been included before, so the header guard isn't set and the compiler starts processing it. It immediately hits #include driver.h", but that header guard is now set, even though the header hasn't really yet been processed, so circular inclusion is avoided. Eventually reaches the prototype which references the type Driver, which hasn't been defined yet.

  I assume you already hit this problem because of the redundant struct declarations in state.h. After inserting these declarations, you could have removed the #include "driver.h" but perhaps you had some other need for it.

• On the other hand, if you first #include "state.h", the compiler sees that its header guard hasn't been set, sets the header guard, and proceeds with the header. It immediately sees #include "driver.h"; that header guard has not yet been set, so it sets that header guard and proceeds with that header. Now when it hits the #include "state.h" in the driver.h header, it does nothing because the header guard has now been set.

  Unfortunately, that #include is really necessary. Compilation fails when an attempt is made to define a member of type State, which has not yet been defined. In this case, you're actually including an entire State object, not just using a pointer, so you can't get away with just forward declaring the struct tab.

In short, things will work OK with one header include order, but fail with a different one. Unfortunately, it's very hard to predict the order in which headers will be included in a complex project, because header includes are not always visible. They may occur inside other headers which are being included. This can lead to headers being included in the "wrong" order.

In general, it is not a good idea to write headers which must be #included in a particular order. It almost always ends in this kind of problem.

When you have several inter-related types all being used by the same small component, you are better off putting all of them into a single header. You will still need to sort the order out correctly, but at least they are all in one place. In that single header file, it may be necessary to forward-declare structures in order to allow pointers to them from other structures. Putting the type definitions ahead of the prototypes reduces the need to forward-declare for prototype references.

If you have a lot of types, you could put all of their declarations in a single internal project/types.h header. Then you can arrange the prototypes in whatever complicated file organisation you fancy. This is a pretty common paradigm. For external prototype headers -- that is, headers which declare functions intended to be globally visible -- you might be able to reduce clutter by just forward declaring the structs being used by the prototypes. Assuming the prototype only uses a pointer to the struct, which is certainly the most common, there is no need to make the definition of the struct visible.

Warning: Opinionated style recommendations follow. If you don't like that sort of thing, you can stop reading here.

Once you have your headers sorted out, assuming they are only being used internally, you can simplify things for yourself and your readers by dropping unnecessary prefixes from internal structure and enum names. Typedefs, structure and union tags, and enums do not have linkage; they cannot leak into another separately compiled translation unit. So there is no need to make them globally unique if they are not intended for global use.

Regardless of what you might see in other people's code, there is absolutely no need to make typedef names different from struct tags, even if you someday intend to compile with C++. In C, the names are in two completely separate namespaces; a struct tag is only recognised as such when preceded with the token struct. So

typedef struct MyStructure MyStructure;

is absolutely valid. In fact, it is valid even if struct MyStructure has not yet been fleshed out, making it convenient for structure types which include pointers to the same type.

I tend to use the style shown in the code snippets above, always putting the typedef before the struct definition. I find that more readable than having the typedef name way down at the end of the struct definition, even if in my style the names are always the same. Also, the forward typedefs can simply be copied to headers which need them. C does not complain if you typedef the same name to the same type more than once, so this is totally safe.