$LastChangedDate: 2009-10-14 21:32:37 -0400 (Wed, 14 Oct 2009) $

Notes about the cmake files.

Naming convention:
------------------
variable names:      all upper-case
values of variables: not all upper-case if possible

This avoids potential problem of ${VAR} interpolating a value
which coincidentally is the name of a variable.

SET( DEBUG "1" )
SET( PROJECT_BUILD_TYPE "DEBUG" )            # troublesome name for value
IF( ${PROJECT_BUILD_TYPE} MATCHES "DEBUG" )  # interpolates DEBUG, result is "1" (oops)
IF( PROJECT_BUILD_TYPE MATCHES "DEBUG" )     # ok
IF( PROJECT_BUILD_TYPE MATCHES "Debug" )     # ok (suggested)

Find*.cmake vs. *.cmake
-----------------------
Find*.cmake should be written very generic.

The other *.cmake files should be mostly generic,
but do have some knowledge/assumptions for specific coding style.

For example, if FindLIB.cmake finds LIB, it sets LIB_FOUND.
FindLIB.cmake won't do any project-specific actions.
Then libraries.cmake might do any project-specific actions
such #define COMPILE_LIB 1 (for a specific coding style)
or modify SYSTEM_LIBS (used within the higher-level *.cmake files).

Scope/context:
--------------
In cmake, a new scope is created by ADD_SUBDIRECTORY().

For clarity, cmake code is separated by scope:
- The project directory (project.cmake) has its own scope.
- Every module (module.cmake) has its own own scope.

Limited modifications of a global is possible in cmake.
From a module/subdirectory, a "global" in a higher scope can be modified by:
SET(VAR VALUE PARENT_SCOPE)
