[CMake-Promote] understanding the CMake build

[Brandon J. Van Every]

William A. Hoffman wrote:
> 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.

Er, you are conflating 2 issues here.  Thomas Chust had Chicken build 
problems, which are probably not related to the docs.  He also went 
through the docs for both Chicken and VTK purposes, *AND* declared, "Not 
only is the CMake documentation scarce, it also frequently seems to be 
wrong and in the past four weeks I have not managed, even after 
modifications in the CMakeLists.txt files, to get two large CMake 
powered projects, namely CHICKEN and VTK, to build using CMake 2.4.3 on 
either...."

His words, not mine. 

>    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.  
>   

Sounds like feeble excuses for why the docs are incomplete.  I prefer to 
tell the people that yes, the docs are the weakest point of CMake, but 
the responsiveness of the mailing list more than makes up for it.  
Especially if they have already condemned the docs.  Anyways, I don't 
want people hunting and pecking through the docs.  It's the main thing 
that causes potential converts to give up.  I want them to ask questions 
and get on appropriate mailing lists, whether CMake or Chicken, so that 
they do not suffer in silence.

> 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.
>   

I will get up to speed on what tutorials are available, and emphasize 
"mailing list and tutorials" as antidotes to the docs.  As for projects, 
I need to see if they're scrutable before recommending them.  Sure they 
exist, and that's good to know that people are doing stuff.  But I hear 
a lot of complaints when people are steered towards the VTK.  A fair 
number of people say it is too big and complicated to swallow.  If I 
tutorialize the Chicken build, that may be a more appropriate size, as 
it's only 75K lines of code.

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

The problem with that recommendation, is at last count it was out of 
date.  I'm not willing to recommend it until it's up to date.

>
> 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.  

Um, frankly, it's true from where I sit.  I've been on board about a 
year now.  Sure lotsa tutorial stuff has happend.  But the steenkin' 
variables still aren't part of the core docs and this is embarrassing.  
I haven't had time to deal with it; neither have you.

> 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.  
>   

I don't focus on the negative.  I state the negative and then hit the 
positive (the mailing list).  In that way, I establish credibility.  I'm 
honest; I will say what's bad about CMake.  Then when I say what's good 
about CMake, people have a reason to believe me.  They don't think I'm 
some fanboy or salesman who's just gonna pump sunshine up their skirt to 
get them to use CMake.  I'm not changing my stance in this regard.  
Weaknesses will be stated; I may sift the weaknesses more carefully from 
now on, but they will be stated.  I think overall, CMake will win and 
survive this, because it has far more strengths than weaknesses.

If / when I get into a vicious fight with someone about whether they're 
blasting CMake for no good reason, like they're an Autoconf booster or 
whatnot, how do you think I prove my case?  With the truth.  You 
remember that article I showed you about C's macro system blowing goat 
dick?  Techies want to hear the truth, not some spin.

You are sensitive about this; I hope you channel that sensitivity into 
putting the variables into the standard docs.  ;-)


Cheers,
Brandon Van Every

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/cmake-promote/attachments/20060911/2d84c60b/attachment-0001.html>