[CMake] Request for better documentation of TRY_COMPILE

[Alan W. Irwin]

To get the experimental Ada language support to work, I needed access to the
source file name at link time.  As a workaround I used Bill's suggestion of
using the <TARGET> name.  That means ADD_EXECUTABLE now works with Ada (with
properly chosen lower-case target names which agrees with the root name of
the source code file which describes the main programme of the Ada executable.
However, that workaround interferes with the second form of TRY_COMPILE
since that uses a fixed target name of cmTryCompileExec.

This limitation got me curious about the first form of
TRY_COMPILE which is documented (2.4.6) as follows:

***********
Try compiling some code.

          TRY_COMPILE(RESULT_VAR bindir srcdir
                      projectName <targetname> <CMAKE_FLAGS <Flags>>
                      <OUTPUT_VARIABLE var>)

        Try compiling a program.  Return the success or failure in RESULT_VAR.
        If <target name> is specified then build just that target otherwise
        the all or ALL_BUILD target is built.
***********

I think that documentation needs to be expanded by roughly a factor of three
to make it consistent with the size of the documentation of the second form
of try_compile which is well documented from my perspective.  I certainly
did not "get" the above terse documentation when I first read it.  Now that
I have read it over a few times, I think it must mean you should set up a
complete test project case in srcdir with source file(s), CMakeList.txt
file(s), possible sub-directories (if you need them), etc., and this form of
try_compile attempts to build that complete project in bindir. So this is
fundamentally an infinitely flexible try_compile test, and something should
be said about that in the documentation.  If my interpretation is correct,
this first form should not have the limitations of the second form of
try_compile (at least from the Ada workaround perspective).

Due to the current terse documentation of the first form of try_compile I
missed the implications of its infinite flexibility so instead I replaced
the usual TRY_COMPILE test of a compiler that is part of all language
support with an EXECUTE_PROCESS test of gnatmake. I am reasonably happy with
that solution, but the exercise exposed the terse documentation issue for
the first form of try_compile so that is why I am mentioning that issue
here.

Alan
__________________________
Alan W. Irwin

Astronomical research affiliation with Department of Physics and Astronomy,
University of Victoria (astrowww.phys.uvic.ca).

Programming affiliations with the FreeEOS equation-of-state implementation
for stellar interiors (freeeos.sf.net); PLplot scientific plotting software
package (plplot.org); the Yorick front-end to PLplot (yplot.sf.net); the
Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project
(lbproject.sf.net).
__________________________

Linux-powered Science
__________________________