Rename include -> overrides and add documentation.

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" />
+   ```

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" />

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" />