[webkit-dev] What's the rationale for not including config.h in any header files?

[Alicia Boya García]

Hi all.

The other day I noticed this in the Code Style Guidelines
(https://webkit.org/code-style-guidelines/#include-statements):

> Header files should never include config.h.

Is there a rationale for it?

config.h is a header file that pulls the compilation flags set in CMake,
some macro functions to query them plus some defaults for specific
platforms (e.g. if platform is Cocoa and WebRTC is enabled,
USE_LIBWEBRTC is defined automatically in WTF/wtf/Platform.h).

As of now, there are lots of instances of header files where macros such
as USE() or ENABLED() are used, yet config.h is not included (even
transitively) by that header file, thus breaking the "include what you
use" rule.

This is not a big deal for the compiler, as every .cpp file in the
project includes config.h before any other header, so by the time those
usages are really compiled those macros will be already defined.

On the other hand, static analysis tools, such as those in IDEs may not
be able to notice this. Unlike compilers, editors and human programmers
often treat files as independent units. For instance, in an editor you
open "LibWebRTCAudioCaptureSource.h", not "LibWebRTCAudioCaptureSource.h
as included by LibWebRTCAudioCaptureSource.cpp in line 28".

Ultimately this can be blamed to C++ fault because includes are a really
sloppy way to require dependencies, but I think we can agree that we
want headers to work as if they were independent units most of the time.

I've seen this issue manifest in QtCreator, as the IDE grays out all the
code inside #if USE() blocks as these macros are not defined or the
expressions inside evaluate to false in the context of that header file.

As an experiment to improve this situation, I first added #pragma once
in config.h files so that they can be included by any header file. Then,
I wrote a Python script that finds all usages of USE() and ENABLED()
macros in header files and adds a #include "config.h" where required.
Objective C headers are ignored by the script using some heuristics.

I built webkitgtk successfully both with and without the patch in gcc
and did not found any noticeable increase in compilation time: the
#pragma once guard is very fast, as expected, so that cannot be ruled as
a reason against. The result is the same but with better static analysis.

As the guidelines are right now I can't get this patch upstream because
they forbid from including config.h... but at least I would like to know
if there a compelling reason for them doing so.

(I attached the patch for the script and a few small edits needed so
that the includes work in all compilation contexts. More edits may be
needed in order for it to build in other platforms, but I could not test
that.)

Regards,
Alicia.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: include-config-h.patch
Type: text/x-patch
Size: 5802 bytes
Desc: not available
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20170731/7fef2445/attachment.bin>