[Scummvm-devel] About the recent header dependency changes

[Ori Avtalion]

Hey all,

You might have noticed my big commit that added / removed #include
directives and forward declaration.

It subsequently broke most of the backends and buildbot turned blood-red.

First of all, I'd like to thank everyone who helped fix the breakages,
and who were patient through the whole process (and my various rushed
oops commits).

I'd also like to explain a bit about the change.

"Reducing header dependency" means:
1) Making sure a header file foo.h includes only those other headers it
must to assure an empty cpp file with '#include "foo.h"' compiles
successfully.
2) Making sure cpp files only include headers that contain symbols they
actually use.

This hopefully results in faster compilation times after modifying
headers, and easier code modification when moving symbols between files.

Most of the actual removal of code was done on common/ audio/ video/. It
then caused various engines and backends to fail, since they "assumed"
they got required symbols "magically" but now had to state explicitly
which header files they needed. A lot of those assumptions still exist,
but I didn't want to mess with the code too much, as most files require
many such #includes to add.

When deciding what changes to make, I consulted this nifty tool:
   https://code.google.com/p/include-what-you-use/

The guidelines are generally simple:
1) If a header only uses a symbol in a function signature (as an
argument or return value), it can be forward-declared.
2) Otherwise, if a header has a class that subclasses the class symbol,
has a member of that type - forward-declaring it is not enough. The
compiler will report an "incomplete type", usually because it has to
know the size of the type. Then it has to be #include-d explicitly.
3) Similarly, if a header file has inline code that mentions a function
or a global variable, the header that declares it should be #include-d
(it can also be forward-delcared, but include-what-you-use suggests
against it, and I'm a Follower).

If you wish, try following the guidelines when you make changes to
common header files. Don't bother about it too much, though. I think
it's too much work to have it always at the back of your head,
especially when compilers don't warn about such things.

Thanks again for the help and patience!

-Ori