[CMake] lexical comparison of cmake version numbers

[Brandon J. Van Every]

David Cole wrote:
> Brandon J. Van Every wrote:
>
>> Alexander Neundorf wrote:
>>
>>> Von: "Brandon J. Van Every" <bvanevery at gmail.com>
>>>
>>>  
>>>
>>>> Alexander Neundorf wrote:
>>>>   
>>>>> Von: "Brandon J. Van Every" <bvanevery at gmail.com>
>>>>>
>>>>>  
>>>>>     
>>>>>> I would like more direct access to the CMake version number, and 
>>>>>> the ability to make easy lexical comparisons between version 
>>>>>> numbers.
>>>>>>          
>>>>> Since cmake 2.4.3 you can use CMAKE_PATCH_VERSION. 
>>>>> CMAKE_MINOR_VERSION
>>>>>     
>>>> and CMAKE_MAJOR version existed already before.
>>>>   
>>>>>  
>>>>>     
>>>> Thank you much for this info, Alex.
>>>>
>>>> But, holy !$%!%$!#@%#%.  This is infuriating!  I chew up my evening 
>>>> reinventing the wheel, because this stuff ISN'T IN THE DOCS, and 
>>>> ISN'T ON THE WIKI "USEFUL VARIABLES" PAGE!
>>>>   
>>>
>>> Sorry that I didn't get around to add it there...
>>> But you know, it's a Wiki :-)
>>>  
>>>
>>
>> They're there now, I added them.  Of course, people can't add things 
>> they don't know about.  Which reminds me: is there a variable that 
>> has major.minor.patch all together?  i.e. "2.4.3"
>>
>
>
> Searching the sample data on this page for the string "version" leads 
> you to all the variables of interest:
> http://www.cmake.org/Wiki/CMake_Useful_Variables/Get_Variables_From_CMake_Dashboards 
>
>
> What search string would you have used if this were documented?

I wouldn't have used any search string at all.  I would have manually 
eyeball scanned the CMake doc in its entireity, as I generally do, and 
in fact did.  This is the only practical way I find to stay aware of all 
the stuff in CMake.  The doc is short enough that this is reasonable.  I 
would have expected to see a reference to what I need at 
CMAKE_MINIMUM_REQUIRED.  I didn't see it, so I checked the Useful 
Variables, in their entireity.  Striking out there, I went to the 
command line.  I found the --version banner and no clean number like 
--release, as some other programs have.

I could look here, look there, for a long time.  I don't do that.  When 
I've passed my threshold for how much time I'm willing to spend looking 
up stuff, I start implementing if I can, or ask on the mailing list if I 
can't.  Extracting the version from the CMake banner is straightforward, 
or would have been, if not for the \n wrinkle which caused a redesign.  
After doing all of that, I figured ok, I've solved it, but this isn't 
very good.  So I posted on the mailing list about it, planning to make a 
feature request, and having more than adequately motivated the feature 
request with working code.

"Dashboard Variables" didn't even remotely enter my mind as somewhere I 
should be looking for anything.  I have a cursory knowledge of what a 
Dashboard is.  I've posted an experimental one for Chicken.  A Dashboard 
isn't CMake.  I have a local copy of "Useful Variables," because I'm on 
cell phone dialup and not permanently wired to the net.  When I didn't 
find what I was after there, I thought, hm, maybe my copy of "Useful 
Variables" is out of date.  So I see this new "Dashboard Variables" 
thing at the top of it, and I say, "WTF is that?" and completely ignore 
it.  I've read it more closely now that you've posted.  I would still 
ignore it.  If its purpose is to provide more info about how to find 
CMake variables, it does not explain its purpose well at all.  It is 
written in some kind of Engineer-speak about the mechanisms it employs 
to do god knows what, and does not simply say that it's a comprehensive 
list of all the variables in CMake.  Moreover, even looking at that list 
of variables, there's no clarity about what's a public or a private 
variable.  It is very raw, matching the rawness of its description.  I 
don't even know if it's good policy to put such an under-the-hood 
document front-and-center.  Do you really want people to get in the 
habit of poking at every Dashboard Variable they can find?

Anyways, I'll be happy to improve the readability of the Dashboard 
Variables description when I'm more awake.

My point is, there are only so many layers that a busy programmer is 
going to look through.  I've got code to think about.  I don't want to 
sit around thinking about the documentation also.  Second-guessing, did 
I look here, should I look there, maybe if I just search here....  I 
went through about 4 steps of due diligence as it was this evening.  I 
always do!  But the documentation is not centralized, it is scattered 
about, and that is just not any good.  Sorry, it's too late in the 
evening / morning, I can't restrain myself from saying it any longer.  
Doing things this way is no good!

I know that everyone here understands this.  That clear, accessible 
documentation matters.  I'm happy to contribute to incremental Wiki 
improvement as you suggest below, as my time and energy allow.  But 
realize, this documentation needs to be centralized and shipped with 
CMake.  I've filed some feature requests / content bugs about it:

#3676 Table Of Contents for documentation
#3752 add CMake variables to documentation
#3757 ship FAQ as part of documentation
#3778 document all "CMake -E" commands


Cheers,
Brandon Van Every

>
>
> Anybody who has the time can feel free to use the sample data as a 
> starting point for documenting even more variables on the Wiki...
>
> Even if it's just the five minutes needed to sort out a simple list of 
> them all with "TODO:" or some such as the temporary doc string until 
> someone in the know can fill it in...