[CMake] Getting a list of the defined CMake cache variables along with properties and documentation?

[Bill Hoffman]

Philip Lowman wrote:

> 1. A chicken and the egg problem, a configure has to occur and 
> CMakeCache.txt created first before you can even parse it for 
> documentation.  Depending on the system being configured generation of a 
> CMakeCache.txt can take some time due to all of the time needed to do 
> compilation checks, etc.  It's not as if the user is going to be able to 
> run "cmake --configure-help ." and have it immediately spit out 
> documentation like GNU AutoTools prior to the user even configuring the 
> build.  There would have to be an initial delay as the cache is 
> created.  Obviously there is the apriori option here though (distribute 
> configuration help ahead of time or require the user to configure 
> manually first).
> 
> 2. The generated documentation (as Bill alluded to) would be dependent 
> on which branches were taken during the configure
> 

Every time we talk about this, I think the only way to solve it is to 
have all the options in some central place.   Basically add some sort of 
argv/argc handler code into CMake.   It would be up to the project 
maintainer to put the publishable options into that file.   Any sort of 
code that makes all if statement branches true will just not work, and 
will be a huge hack.

Something like:
ProjectOptions.cmake
add_option(enable-testing "Enable the testing part of the project" 
ENABLE_TESTING)
add_option(build-with-mpi "Use MPI with this project" BUILD_WITH_MPI)

The option would have a command line option, the documentation, and the 
cache variable.   A documentation feature could search the project 
source tree for PRojectOptions.cmake files and quickly find them all.

-Bill