doc: Update docs with codegen instructions

diff --git a/BUILD.md b/BUILD.md
index 7bc0253..8befabe 100644 (file)
--- a/BUILD.md
+++ b/BUILD.md
@@ -175,6 +175,19 @@ specific requirements for configuring and building these components.
 - Please use `update_deps.py --help` to list additional options and read the
   internal documentation in `update_deps.py` for further information.
 
+### Generated source code
+
+This repository contains generated source code in the `icd/generated`
+directory which is not intended to be modified directly. Instead, changes should be
+made to the corresponding generator in the `scripts` directory. The source files can
+then be regenerated using `scripts/generate_source.py`:
+
+    python3 scripts/generate_source.py PATH_TO_VULKAN_HEADERS_REGISTRY_DIR
+
+A helper CMake target `VulkanTools_generated_source` is also provided to simplify
+the invocation of `scripts/generate_source.py` from the build directory:
+
+    cmake --build . --target VulkanTools_generated_source
 
 ### Build Options
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 805528c..41e0269 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,8 +66,17 @@ That said, please ensure that the repository compiles and passes tests without e
 that to be accepted into the repository, the pull request must [pass all tests](#testing your changes) on all supported platforms
 -- the automatic Github Travis and AppVeyor continuous integration features will assist in enforcing this requirement.
 
+#### Generated Source Code
+
+The `icd/generated` directory contains source code that is created by several
+generator scripts in the `scripts` directory. All changes to these scripts _must_ be submitted with the
+corresponding generated output to keep the repository self-consistent. This requirement is enforced by both
+Travis CI and AppVeyor test configurations. Regenerate source files after modifying any of the generator
+scripts and before building and testing your changes. More details can be found in
+[BUILD.md](https://github.com/KhronosGroup/Vulkan-Tools/blob/master/BUILD.md#generated-source-code).
+
 #### **Testing Your Changes**
-* Run the repository components with the Vulkan Validation Layers before and after each if your commits to check for any regressions.
+* Run the repository components with the Vulkan Validation Layers before and after each of your commits to check for any regressions.
 
   (These instructions are for Linux)
 * In the `cube` directory, run: