maint: Fix header includes once and for all

Previously #include statements were a bit of a mess across the codebase.
This commit is the result of a pass by the IWYU (Include What You Use)
tool, which suggests headers to add or remove based on what is in the
file, and can also suggest forward-declaring classes instead of
including their headers, if they are only used as a pointer in a
particular file. Cleaning this up should in general speed up compile
times.

IWYU isn't perfect, it produces a number of false positives, so we don't
try to automate this process and we don't accept all of its
recommendations. We do add a script and configuration file to the tools/
directory so that IWYU can be every so often in the future.

We also clean up all the includes according to a consistent style, which
is now described clearly in the C++ style guide.

3 files changed, 118 insertions, 0 deletions

diff --git a/tools/gjs-private-iwyu.imp b/tools/gjs-private-iwyu.imp
new file mode 100644
index 00000000..6d3a097c
--- /dev/null
+++ b/tools/gjs-private-iwyu.imp
@@ -0,0 +1,53 @@
+# IWYU mapping file for files that are part of libgjs
+[
+  {"include": ["<bits/std_abs.h>", "private", "<stdlib.h>", "public"]},
+  {"include": ["<bits/std_function.h>", "private", "<functional>", "public"]},
+  {"include": ["@<bits/stdint-.*>", "private", "<stdint.h>", "public"]},
+  {"include": ["<bits/types/sigevent_t.h>", "private", "<sys/signal.h>", "public"]},
+  {"include": ["<bits/types/siginfo_t.h>", "private", "<sys/signal.h>", "public"]},
+  {"include": ["<bits/types/struct_itimerspec.h>", "private", "<time.h>", "public"]},
+  {"include": ["<bits/types/struct_timespec.h>", "private", "<time.h>", "public"]},
+  {"include": ["<bits/types/timer_t.h>", "private", "<sys/types.h>", "public"]},
+  {"include": ["<ext/alloc_traits.h>", "private", "<memory>", "public"]},
+
+  {"include": ["@<ffi.*>", "private", "<ffi.h>", "public"]},
+  {"include": ["@\"gio/.*\"", "private", "<gio/gio.h>", "public"]},
+  {"include": ["@<gio/.*>", "private", "<gio/gio.h>", "public"]},
+  {"include": ["<glib/gtypes.h>", "private", "<glib.h>", "public"]},
+  {"include": ["@\"gobject/.*\"", "private", "<glib-object.h>", "public"]},
+  {"include": ["@<gobject/.*>", "private", "<glib-object.h>", "public"]},
+  {"include": ["<libintl.h>", "private", "<glib/gi18n.h>", "public"]},
+  {"include": ["@\"sysprof-capture-.*\"", "private", "<sysprof-capture.h>", "public"]},
+  {"include": ["@<sysprof-capture-.*>", "private", "<sysprof-capture.h>", "public"]},
+  {"include": ["<X11/Xlib.h>", "private", "<cairo-xlib.h>", "public"]},
+
+  # Remove when it is no longer necessary to include jsapi-wrapper.h
+  {"include": ["\"js/AllocPolicy.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/CallArgs.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/CharacterEncoding.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/Class.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/Conversions.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/GCAPI.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/GCPolicyAPI.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/GCVector.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/HashTable.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/HeapAPI.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/Id.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/RootingAPI.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/TracingAPI.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/TypeDecls.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/Utility.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"js/Value.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"jspubtd.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"include": ["\"jstypes.h\"", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JS::GCPolicy<T>", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JS::Symbol", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JS::Value", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JS::WeakCache<T>", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JSContext", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JSFlatString", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JSFunction", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JSLinearString", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JSObject", "private", "\"gjs/jsapi-wrapper.h\"", "public"]},
+  {"symbol": ["JSString", "private", "\"gjs/jsapi-wrapper.h\"", "public"]}
+]
\ No newline at end of file
diff --git a/tools/gjs-public-iwyu.imp b/tools/gjs-public-iwyu.imp
new file mode 100644
index 00000000..7f805e4b
--- /dev/null
+++ b/tools/gjs-public-iwyu.imp
@@ -0,0 +1,6 @@
+# IWYU mapping file for files that use the API of libgjs
+[
+  {"ref": "gjs-private-iwyu.imp"},
+
+  {"include": ["\"gjs/macros.h\"", "private", "<gjs/gjs.h>", "public"]}
+]
\ No newline at end of file
diff --git a/tools/run_iwyu.sh.in b/tools/run_iwyu.sh.in
new file mode 100755
index 00000000..705e09c6
--- /dev/null
+++ b/tools/run_iwyu.sh.in
@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# run with 'make iwyu | tee iwyu.log'
+
+if test -z "$BUILDDIR" -o -z "$SRCDIR"; then
+    echo "SRCDIR and BUILDDIR must be defined. Try running 'make iwyu' instead."
+    exit 1
+fi
+
+cd "$SRCDIR"
+
+PRIVATE_MAPPING="-Xiwyu --mapping_file=tools/gjs-private-iwyu.imp"
+PUBLIC_MAPPING="-Xiwyu --mapping_file=tools/gjs-public-iwyu.imp"
+
+LIBS_INCLUDES=$(pkg-config --cflags \
+    "@AX_PACKAGE_REQUIRES@ @AX_PACKAGE_REQUIRES_PRIVATE@")
+INCLUDES="-I. -I$BUILDDIR"
+DEFINES="-DGJS_COMPILATION -DPKGLIBDIR=\"\" -DINSTTESTDIR=\"\" -DGJS_JS_DIR=\"\""
+CPP_ARGS="$LIBS_INCLUDES @SYSPROF_CAPTURE_CFLAGS@ $INCLUDES $DEFINES"
+
+LANG_CXX="--language=c++ -std=c++14"
+LANG_C="--language=c"
+CXX_STDLIB_INCLUDES=$(clang -Wp,-v $LANG_CXX -fsyntax-only /dev/null 2>&1 | \
+    grep '^ ' | sed -e 's/^ /-I/')
+C_STDLIB_INCLUDES=$(clang -Wp,-v $LANG_C -fsyntax-only /dev/null 2>&1 | \
+    grep '^ ' | sed -e 's/^ /-I/')
+CXX_ARGS="$LANG_CXX $CXX_STDLIB_INCLUDES $CPP_ARGS"
+C_ARGS="$LANG_C $C_STDLIB_INCLUDES $CPP_ARGS"
+
+for FILE in gi/*.cpp gi/gjs_gi_trace.h gjs/atoms.cpp gjs/byteArray.cpp \
+    gjs/coverage.cpp gjs/debugger.cpp gjs/deprecation.cpp gjs/error-types.cpp \
+    gjs/engine.cpp gjs/global.cpp gjs/importer.cpp gjs/jsapi-util-args.h \
+    gjs/jsapi-util-error.cpp gjs/jsapi-util-root.h gjs/jsapi-util-string.cpp \
+    gjs/jsapi-util.cpp gjs/module.cpp gjs/native.cpp gjs/stack.cpp \
+    modules/cairo-*.cpp modules/console.cpp modules/system.cpp test/*.cpp \
+    util/*.cpp
+do
+    iwyu $PRIVATE_MAPPING $CXX_ARGS $FILE
+done
+iwyu $PRIVATE_MAPPING $CXX_ARGS gjs/context.cpp \
+    -Xiwyu --check_also=gjs/context-private.h
+iwyu $PRIVATE_MAPPING $CXX_ARGS gjs/jsapi-dynamic-class.cpp \
+    -Xiwyu --check_also=gjs/jsapi-class.h
+iwyu $PRIVATE_MAPPING $CXX_ARGS gjs/mem.cpp \
+    -Xiwyu --check_also=gjs/mem-private.h
+iwyu $PRIVATE_MAPPING $CXX_ARGS gjs/profiler.cpp \
+    -Xiwyu --check_also=gjs/profiler-private.h
+iwyu $PRIVATE_MAPPING $CXX_ARGS modules/cairo.cpp \
+    -Xiwyu --check_also=modules/cairo-module.h \
+    -Xiwyu --check_also=modules/cairo-private.h
+
+for FILE in gjs/console.cpp installed-tests/minijasmine.cpp; do
+    iwyu $PUBLIC_MAPPING $CXX_ARGS $FILE
+done
+
+for FILE in libgjs-private/*.c; do
+    iwyu $PRIVATE_MAPPING $C_ARGS $FILE
+done
+iwyu $PUBLIC_MAPPING $C_ARGS gjs/macros.h