From 92613e9665657e69aafcd12b289c464e9990df82 Mon Sep 17 00:00:00 2001
From: Joseph Cloutier <jkcloutier@gmail.com>
Date: Sat, 7 May 2022 17:16:03 -0400
Subject: [PATCH] Rename include -> overrides and add documentation.

---
 project/lib/README.md                         | 27 +++++++++++++++++++
 project/lib/cairo-files.xml                   |  7 +++--
 .../{include => overrides}/pixman/config.h    |  0
 .../pixman/pixman-version.h                   |  0
 project/lib/pixman-files.xml                  |  2 +-
 5 files changed, 33 insertions(+), 3 deletions(-)
 rename project/lib/{include => overrides}/pixman/config.h (100%)
 rename project/lib/{include => overrides}/pixman/pixman-version.h (100%)

diff --git a/project/lib/README.md b/project/lib/README.md
index df8a8785d..fb6ba61ce 100644
--- a/project/lib/README.md
+++ b/project/lib/README.md
@@ -40,3 +40,30 @@ libvpx: [homepage](https://www.webmproject.org/tools/) | [repo](https://chromium
 libwebm: [homepage](https://www.webmproject.org/about/) | [repo](https://chromium.googlesource.com/webm/libwebm) | [GitHub mirror](https://github.com/webmproject/libwebm)
 
 zlib: [homepage](https://zlib.net/) | [repo](https://github.com/madler/zlib)
+
+Overrides
+---------
+
+The overrides folder contains a number of customized headers and source files, to be used instead of the equivalent file(s) in the submodule. (Or in addition to: some submodules intentionally omit files, expecting the user to generate them.)
+
+All cases require updating the corresponding files.xml file.
+
+- To add or override a header, include the overrides folder first (if not already included).
+
+   ```diff
+   +<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/overrides/sdl/" />
+   <compilerflag value="-I${NATIVE_TOOLKIT_PATH}/sdl/include/" />
+   ```
+
+- To add a source file, insert a `<file />` tag.
+
+   ```diff
+   +<file name="${NATIVE_TOOLKIT_PATH}/overrides/sdl/SDL_extra.c" />
+   ```
+
+- To override a source file, replace the `<file />` tag.
+
+   ```diff
+   -<file name="${NATIVE_TOOLKIT_PATH}/sdl/src/SDL_log.c" />
+   +<file name="${NATIVE_TOOLKIT_PATH}/overrides/sdl/SDL_log.c" />
+   ```
diff --git a/project/lib/cairo-files.xml b/project/lib/cairo-files.xml
index 3a7d0a371..ae19cdc3e 100644
--- a/project/lib/cairo-files.xml
+++ b/project/lib/cairo-files.xml
@@ -2,16 +2,19 @@
 
 	<files id="native-toolkit-cairo" >
 
-		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/pixman/pixman/" />
+		<!-- <compilerflag value="-I${NATIVE_TOOLKIT_PATH}/overrides/cairo/" /> -->
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/include/" />
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/include/configs/default/" unless="windows || mac || linux" />
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/include/configs/linux/" if="linux" />
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/include/configs/windows/" if="windows" />
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/include/configs/mac/" if="mac" />
-		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/include/pixman/" /> <!-- Pixman's config.h must come after Cairo's. -->
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/src" />
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/freetype/include" />
 
+		<!-- Include Pixman's headers last so Cairo's headers will override them. -->
+		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/overrides/pixman/" />
+		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/pixman/pixman/" />
+
 		<compilerflag value="-DNDEBUG" unless="debug" />
 		<compilerflag value="-DHAVE_CONFIG_H" />
 		<compilerflag value="-DCAIRO_WIN32_STATIC_BUILD" if="windows" />
diff --git a/project/lib/include/pixman/config.h b/project/lib/overrides/pixman/config.h
similarity index 100%
rename from project/lib/include/pixman/config.h
rename to project/lib/overrides/pixman/config.h
diff --git a/project/lib/include/pixman/pixman-version.h b/project/lib/overrides/pixman/pixman-version.h
similarity index 100%
rename from project/lib/include/pixman/pixman-version.h
rename to project/lib/overrides/pixman/pixman-version.h
diff --git a/project/lib/pixman-files.xml b/project/lib/pixman-files.xml
index 7d6c8e63e..d5d7529d7 100644
--- a/project/lib/pixman-files.xml
+++ b/project/lib/pixman-files.xml
@@ -7,7 +7,7 @@
 
 	<files id="native-toolkit-pixman" >
 
-		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/include/pixman" />
+		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/overrides/pixman" />
 		<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/pixman/pixman" />
 		<compilerflag value="-DHAVE_CONFIG_H" />
 		<compilerflag value="-DPIXMAN_NO_TLS" if="windows" />