lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]


On Feb 2, 2008 3:02 PM, Bradley Smith <gmane@baysmith.com> wrote:
> Brandon Van Every wrote:
> >
> > BTW the new style convention is lowercase for CMake commands.  All
> > caps is still used for keywords and CMake defined variables.  I agree
> > that it's more readable to have fewer things shouting at you.  Both
> > caps and lowercase work for commands though.  I think that has been
> > true for quite awhile, and it may have always been true, but the
> > documentation was written in all caps so people imitated that.  Now
> > the docs are lowercase where they can be.
> >
>
> Where online is the CMake documentation? Especially the new
> documentation with lowercase commands? I found
> http://www.cmake.org/HTML/Documentation.html, but that has uppercase
> commands.

Hm, you're right.  You've got the correct URL for the docs.  CMake
2.4.8 still uses uppercase commands in the documentation.  CMake CVS,
which is destined to become CMake 2.6.0, uses lowercase.  Uppercase
and lowercase work in both versions, however.

> Also where is the documentation of the details for CMake's
> custom language (how to use variables, literals, functions, etc.)?

It's lacking.  CMake doesn't currently have topic or chapter oriented
documentation.  Much of what one needs to do is easy to infer from
reading the command reference, i.e. set(foo blah) tells you how to set
things, foreach(var RANGE 1 5) tells you how to loop things, etc.  But
there are some warts regarding the differences between string and list
representations, and regarding quotes and escapes.  There are wiki
pages to provide more information on this stuff, but they're not
complete, comprehensive, or IMO particularly well organized.  They are
adequately organized for early adopters, i.e. nothing's stopping
anyone from getting real work done, but it isn't a professional
quality command reference.  It is claimed that CMake 2.6.0 will
document all CMake variables.  Also the documentation is assuming a
better structure, in that obsolescent commands are moved to their own
section, modules have their own section, and things like that.  There
is no plan, however for chapter oriented documentation, so this will
probably remain the weakest point about CMake in the near future.

A new version of the CMake book is due out imminently.  It's on a boat
and Kitware is waiting to receive the shipment.  I have not read the
previous CMake books, I learned CMake in open source hacker fashion.
I plan to buy a copy of the current book, so that I can evaluate it
and also pitch it if it's worthy.

Nothing's really stopping anyone from turning the current wiki docs
into more professional docs.  But like many open source projects,
people's time and energy go into more pressing matters.  "Better docs
that someone else is maintaining" is one of the arguments I've made in
favor of Lua.

Unfortunately, there are too many technical and support issues
regarding Kitware's process for that to be an overwhelming argument.
They know how to crank out code for CMake and to date, it sounds like
a big disruption for no particular gain.  I think the real question
is, do mainstream fullblown scripting languages offer any competitive
advantages for large projects, over the current CMake script?  Can
they do things that CMake script will never be able to do, even if
CMake script is modified and improved?  So far the answer seems to be
"no."


Cheers,
Brandon Van Every