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

[Philip Lowman]

On Wed, Dec 3, 2008 at 9:44 PM, Bill Hoffman <bill.hoffman at kitware.com>wrote:

> Bartlett, Roscoe A wrote:
>
>> Hello,
>>  Is there a way in a CMakeLists.txt file to get a list of all of the
>> defined CMake cache variables, get their properties, and their
>> documentation?  I would like to have this so that I can build more general
>> documentation for our CMake project.  I could of course just parse the
>> CMakeCache.txt file myself but if there is a way to do this in CMake then
>> that might be better.  Otherwise, I will need to create a tool that would do
>> a configure, then read the CMakeCache.txt file and build documentation
>> output like you would see for our current autotools build system.
>>
>>
>
> There is no such tool.  There are also problems with such a tool.  The main
> problem is the if statement.  To get complete docs for a project you would
> have to evaluate each if both true and false to make sure you found all
> possible cache values for a project.   It has come up on the list a few
> imes, but no general solution has been discovered.


There is also the problem of what to do with all of the cache variables you
wouldn't want in your documentation.  And also what to do when you aren't
happy with the docstring provided by the maintainer of FindFoo.cmake and
want to override it with your own (perhaps to explain the effect of having
or not having FOO_LIBRARY on your project if it's an optional dependency).

That being said, it probably still would be a useful feature even if it
doesn't overcome the if/else issue the first go-around.  Many people would
probably be OK with this limitation.

Incidentally, I don't think the if() else() issue would be that hard to
solve once you had a basic cache documentation generator implemented.  At
least there would be more of an incentive to fix this use case then.  :)
The simple (probably naive) approach would seem to be to just set
cmIfFunctionBlocker::isBlocking always to false when the cache documentation
generator is running, and see what happens.  Not sure if this would work
correctly or not and result in "all" branches being taken, but it probably
would be a good start.

It seems to me the hard part would be disabling all of the "harmful" CMake
commands you wouldn't want to run while generating the documentation .  And
getting CMake to not save everything to the cache, and all of the other
crazy stuff you wouldn't want it to do while trying to detect cache
variables.  (A new virtual hook on cmCommand similar to InvokeInitialPass()
that gets run in the special generation mode which would either simply
return or call InvokeInitialPass() would probably be a good start).

Obviously a CMakeCache.txt file parser might be quicker to implement but it
would have at least these drawbacks:

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

-- 
Philip Lowman
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.cmake.org/pipermail/cmake/attachments/20081204/97d3d326/attachment-0001.htm>