CMake Section: Complete re-write.

Completely re-wrote the section.  New file names that do
not use the numbers also.

Change-Id: I443feb41cf83d760a57179473439e89e7b71f9c5
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

1 files changed, 114 insertions, 0 deletions

diff --git a/docs/dev_guide/advanced-customization.md b/docs/dev_guide/advanced-customization.md
new file mode 100755
index 0000000..dacc2e8
--- /dev/null
+++ b/docs/dev_guide/advanced-customization.md
@@ -0,0 +1,114 @@
+# Advanced Customization
+
+Beyond the configurations described in the
+[Configuring CMake Templates](configuring-cmake.html) section,
+you can provide some advanced configurations.
+
+This section describes how you can include additional CMake files
+and custom template scripts.
+
+## Including Additional CMake Files
+
+You can include machine and system custom CMake files and
+operating system custom CMake files.
+
+### Machine and System Custom CMake Files
+
+Advanced configuration is possible by automatically including
+additional CMake files from specific locations.
+Following are the locations from which you can add CMake
+files.
+Inclusions occur in the order shown here:
+
+- `<project-root-path>/conf.d/app-templates/cmake/cmake.d` - normally located CMake project files
+- `$HOME/.config/app-templates/cmake.d` - the home location
+- `/etc/app-templates/cmake.d` - the system location
+
+The CMake files you include must be named using either of the following conventions:
+
+- `XX-common*.cmake`
+- `XX-${PROJECT_NAME}*.cmake`
+
+In both formats, `XX` are numbers and indicate the order in which the file
+is included.
+The `*` character represents the filename.
+
+When naming the file, consider the projects in which the file needs to be
+included.
+If you want to include the file in all projects, use the keyword `common`.
+If you want to include the file in a specific project, use the `${PROJECT_NAME}`
+value.
+
+For example, if you want a CMake file whose name is `my_custom_file`
+included first and you want it included in all projects, name the file
+`01-common-my_custom_file.cmake`.
+If you want the same file included in a single project defined by the
+`PROJECT_NAME` variable, and you want it included after all other files,
+name the file `99-${PROJECT_NAME}-my_custom_file.cmake`.
+
+When you include CMake files that use CMake variables, the values override
+variables with the same name.
+The exception to this rule is if you use a cached variable.
+Following is an example:
+
+```cmake
+set(VARIABLE_NAME 'value string random' CACHE STRING 'docstring')
+```
+
+In this example, the `VARIABLE_NAME` variable is defined as a cached
+variable by using the **CACHE** keyword.
+Consequently, `VARIABLE_NAME` does not get overridden as a result of
+including a CMake file that sets the same variable.
+
+### Operating System Custom CMake Files
+
+Including custom CMake files based on the operating system
+lets you personalize a project depending on the operating system
+you are using.
+
+At the end of the `config.cmake` file `common.cmake` includes
+CMake files to customize your project build depending on your platform.
+The operating system is detected by using `/etc/os-release`,
+which is the default method used in almost all Linux distributions.
+Consequently, you can use the value of field **ID_LIKE** to
+add a CMake file for that distribution.
+The file comes from your `conf.d/cmake/` directory or relatively
+from your `app-templates` submodule path `app-templates/../cmake/`.
+
+**NOTE:** If the **ID_LIKE** field does not exist, you can use the
+**ID** field.
+
+Files that you add must be named according to the following file naming
+convention:
+
+- `XX-${OSRELEASE}*.cmake`
+
+In the naming convention, `XX` represents numbers and is the order in which
+you want a file included.
+The ${OSRELEASE} value is taken from either the **ID_LIKE** or **ID** field
+of the `/etc/os-release` file.
+
+You can also configure a CMake file to be included in cases where no
+specific operating system can be found.
+To do so, name your CMake file as follows:
+
+- `XX-default*.cmake`
+
+A good use case example for these two naming conventions is when you have
+a several Linux distributions and all but one can use the same module.
+For that case, name one CMake file using the `${OSRELEASE}` value and
+name the CMake file to be used with the other distributions using
+the `XX-default*.cmake` method.
+
+## Including Custom Template Scripts
+
+You can include your own custom template scripts that are passed to the
+CMake command `configure_file`.
+
+Just create your own script and place it in either of the following directories:
+
+- `$HOME/.config/app-templates/scripts` - the home location
+- `/etc/app-templates/scripts` - the system location
+
+Scripts only need to use the extension `.in` to be parsed and configured by
+CMake.