[CMake] find_packge in Module Mode

aaron.meadows at thomsonreuters.com aaron.meadows at thomsonreuters.com
Fri Jun 24 18:19:15 EDT 2011


I was just noticing that the find_package command documentation talks
about how, in "Config" mode,  the PACKAGE_FIND_* variables are defined
for use by the "<config-file>-version.cmake" or
"<config-file>Version.cmake" scripts for libraries.  It further mentions
that when find_package is used in "Module" mode that the
"Find<package>.cmake" script is responsible for verifying the version.
However, it doesn't seem to document that the version variables are
defined for "Module" mode as <package>_FIND_*, e.g. PACKAGE_FIND_VERSION
for a package name FooBar would be passed to the FindFooBar.cmake as
FooBar_FIND_VERSION, and so on.

 

(I have not dealt with "Config" mode for find_package, so perhaps I'm
mistaken about the naming there.)

 

Anyway, I think the documentation should be updated to reflect those
variables, and I'd be happy to do that, so long as I am not missing this
being documented elsewhere.

 

Am I correct in this point?  For that matter, can someone tell me if in
the above example the "FooBar-version.cmake" would be passed
PACKAGE_FIND_VERSION and set PACKAGE_VERSION or would it be passed
FooBar_FIND_VERSION and set FooBar_VERSION?

 

 

Reference:
http://cmake.org/cmake/help/cmake-2-8-docs.html#command:find_package

 

Incidentally, this appears to be slightly different than the
XXX_VERSION_STRING being set by Modules, documented in the
Modules/readme.txt (Reference:
http://cmake.org/gitweb?p=cmake.git;a=blob;f=Modules/readme.txt).  

 

-----------------------------8<-----------------------------------------
------------------------------------

On a side note, it might be nice to update that document to use the same
<package> naming convention (possibly as <module>) as the main
documentation does, like:

For more information about how to contribute modules to CMake, see this
page:

http://www.itk.org/Wiki/CMake:Module_Maintainers

 

Note to authors of Find<module>.cmake files

 

We would like all Find<module>.cmake files to produce consistent
variable names.

 

Please use the following consistent variable names for general use.

 

<module>_INCLUDE_DIRS        The final set of include directories listed
in one variable for use by client code.  This should not be a cache
entry.

<module>_LIBRARIES           The libraries to link against to use
<module>. These should include full paths.  This should not be a cache
entry.

<module>_DEFINITIONS         Definitions to use when compiling code that
uses <module>. This really shouldn't include options such as
(-DHAS_JPEG)that a client source-code file uses to decide whether to
#include <jpeg.h>

<module>_EXECUTABLE          Where to find the <module> tool.

<module>_<tool>_EXECUTABLE   Where to find the <tool> tool that comes
with <module>.

<module>_LIBRARY_DIRS        Optionally, the final set of library
directories listed in one variable for use by client code.  This should
not be a cache entry.

<module>_ROOT_DIR            Where to find the base directory of
<module>.

<module>_VERSION_<version>   Expect Version <version> if true. Make sure
at most one of these is ever true.

<module>_WRAP_<command>      If False, do not try to use the relevent
CMake wrapping command.

<module>_<sub part>_FOUND    If False, optional <sub part> of <module>
system is not available.

<module>_FOUND               Set to false, or undefined, if we haven't
found, or don't want to use <module>.

<module>_RUNTIME_LIBRARY_DIRS Optionally, the runtime library search
path for use when running an executable linked to shared libraries.

                             The list should be used by user code to
create the PATH on windows or LD_LIBRARY_PATH on unix.

                             This should not be a cache entry.

<module>_VERSION_STRING      A human-readable string containing the
version of the package found, if any.

<module>_VERSION_MAJOR       The major version of the package found, if
any.

<module>_VERSION_MINOR       The minor version of the package found, if
any.

<module>_VERSION_PATCH       The patch version of the package found, if
any.

 

You do not have to provide all of the above variables. You should
provide <module>_FOUND under most circumstances. If <module> is a
library, then  <module>_LIBRARIES, should also be defined, and
<module>_INCLUDE_DIRS should usually be defined (I guess libm.a might be
an exception)

 

The following names should not usually be used in CMakeLists.txt files,
but they may be usefully modified in users' CMake Caches to control
stuff.

 

<module>_LIBRARY             Name of <module> Library. A User may set
this and <module>_INCLUDE_DIR to ignore to force non-use of <module>.

<module>_<sub_lib>_LIBRARY   Name of <sub_lib> library that is part of
the <module> system. It may or may not be required to use <module>.

<module>_INCLUDE_DIR         Where to find xxx.h, etc.
(<module>_INCLUDE_PATH was considered bad because a path includes an
actual filename.)

<module>_<part>_INCLUDE_DIR  Where to find xxx_<part>.h, etc.

 

Aaron Meadows
Software Engineer

Thomson Reuters

Phone: 314.468.3530
Mobile: 636.541.6139
aaron.meadows at thomsonreuters.com
thomsonreuters.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.cmake.org/pipermail/cmake/attachments/20110624/35933c61/attachment-0001.htm>


More information about the CMake mailing list