On Wed, Dec 3, 2008 at 9:44 PM, Bill Hoffman <span dir="ltr"><<a href="mailto:bill.hoffman@kitware.com">bill.hoffman@kitware.com</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="Ih2E3d">Bartlett, Roscoe A wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Hello,<br>
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.<br>
<br>
</blockquote>
<br></div>
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.</blockquote>
<div><br>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).<br>
<br>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.<br><br>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.<br>
<br>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).<br><br>Obviously a CMakeCache.txt file parser might be quicker to implement but it would have at least these drawbacks:<br>
<br>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).<br>
<br>2. The generated documentation (as Bill alluded to) would be dependent on which branches were taken during the configure<br>
<br></div></div>-- <br>Philip Lowman<br>