[CMake-Promote] understanding the CMake build

[William A. Hoffman]

At 10:14 PM 9/9/2006, Brandon J. Van Every wrote:
>William A. Hoffman wrote: 
>>
>>At 05:07 PM 9/9/2006, Brandon J. Van Every wrote:
>>
>>  
>>>
>>>Not anymore!  A Chicken tarball distribution is now fully bootable without Chicken, under both CMake and Autoconf.  We have a development snapshot on the Chicken homepage, which only works on some platforms.  
>>>We've fixed most of the problems with that snapshot; it's about time for another one.  We have a CMake script that builds a distribution by typing "make dist" .  It actually runs the Autotools and includes everything needed for that as well; it's a unified distribution.  It's now the canonical method for building a Chicken distro.
>>>    
>>
>>
>>Sure, but maybe he was building from darcs in which case it needs chicken.  
>>  
>
>Actually he probably was building from Darcs and probably did need Chicken.  But he didn't say this was his problem.  He hasn't said what his Chicken problems actually were; I've asked him to post his errors.
>
>>
>>Anyway, I don't think the problem here was a lack of CMake documentation.
>>  
>
>Not for building Chicken on MinGW / MSYS, at any rate.  On MacOS X, maybe.  Depends on if there are any weird requirements I'm unaware of, that he tried to look up and then supply.  Watcom, maybe; haven't tried it myself.  I said I'd support it if he actually needs it + does regular testing.  Otherwise, it doesn't make a lot of sense for me to take the trouble, if nobody's actually using it.
>
>>
>>He did not want to write a cmake list file he just wanted to run cmake.
>>That should be documented by the project.
>>  
>
>
>It is, and has been for quite some time, in INSTALL-CMake.txt.

OK, so we agree that the issue is not a lack of CMake Docs here.
Brandon, I don't think you are doing CMake promotion much good, by
replying to folks who have issues with CMake, by saying the online docs
are no good.   The could use improvement, and they are being improved and
those points should be made.   How about:

1. every function in CMake is automatically documented in the code, and
you can find those docs on line or with --help-command.

2. every module in CMake is automatically documented in the code, and you can
find that on line or from the cmake command line.

3. The variables are not yet documented, but there is a wiki page with
a groing list of variables documented.  

4. With the adoption of cmake by kde4 there are a large number of open source projects
switching over to CMake.  These projects provide good real world examples and lots
of folks that know CMake.

5. The CMake test suite contains a lot of good stuff as well.  Including the source
to the tutorial from the book Mastering CMake.

6. There exists a published book "Mastering CMake".

7.  Finally the cmake mailing list is very active and if you don't find the answer to
your question in the cmake home page, command line help, or wiki, then there is a very
good chance someone will answer your question on the list.

For an example of how easy it is for an outsider to learn cmake, see this blog from
the scribus folks:

http://kde-artists.org/node/235


It would be nice if you posted something to this affect to the cmake mailing list.
I do think your emails about how cmake developers have no time for docs hurt the project
and it is just not true.  There are new wiki entries all the time, and the automated
docs for the commands and modules are constantly being updated.  If you are promoting something,
it does no good to focus on the negative.  

-Bill