[Cmake] Documentation suggestions.

[Mark Foskey]

I guess this is in the category of "feature request", with
the features being bits of documentation.  Here are some
things that would really help me a lot:

1. A good general description, maybe with an example
CMakeLists.txt file, of how to link with libraries that know
nothing of CMake.  Some of these libraries require that
specific compiler flags be set, and the user needs to know
how to do that.  Also, one needs to know how to handle
multiple libraries, when, say, one of them is CMake-unaware,
one has a FindFOO.cmake module, and a third has a
FOOConfig.cmake file.

Some libraries give poor documentation of how to set up a
project to use them.  They just provide a sample application
with maybe a makefile and .ds{w,p} files.  It would be good
to have some guidance on how to go from such examples to a
good CMakeLists.txt file.

2. Implicit in the above suggestion is a request for an
annotated example of a moderately sophisticated
CMakeLists.txt file -- one that shows off what CMake can do.
Such an example would be immensely helpful.  The
CMakeLists.txt file for one of the Insight applications
might be a good starting point, but it wouldn't show how to
deal with libraries that are "mutually unaware" with CMake.
And I know the modules are recommended, but they don't
really show what a large standalone project should look
like.

3. It would make some of the explanations for individual
functions more helpful if they made reference to other
related functions.  For instance, there are FIND_FILE,
FIND_PATH, FIND_LIBRARY, and FIND_PROGRAM.  Do all of these
find full paths?  Or does FIND_PATH just find a path to the
directory containing the given file?  Why are all four
needed?  If each one explained how it was different from the
others, I would feel more confident when writing
CMakeLists.txt files.

Similarly, the descriptions of LINK_LIBRARIES and
TARGET_LINK_LIBRARIES would benefit from referencing each
other, with an explicit mention of what the difference is.

Anyway, these are just some suggestions, although item (3)
can be read as a request for information also.  I hope this
wasn't the wrong place to bring these up.

-- 
Mark Foskey    (919) 843-5436   Computer-Aided Diagnosis and Display Lab
mark_foskey at unc.edu             Department of Radiology, CB 7515, UNC
http://www.cs.unc.edu/~foskey   Chapel Hill, NC  27599-7515