[CMake] example how to find a library with PKG_CHECK_MODULES and FIND_PACKAGE_HANDLE_STANDARD_ARGS

[Claus Klein]

according to

Notes to authors of FindXXX.cmake files

We would like all FindXXX.cmake files to produce consistent variable  
names.

Please use the following consistent variable names for general use.

XXX_FOUND :
Set to false, or undefined, if we haven't found, or don't want to use  
XXX.
XXX_YYY_FOUND :
If False, optional YYY part of XXX sytem is not available.
XXX_INCLUDE_DIRS :
The final set of include directories listed in one variable for use by  
client code. This should not be a cache entry!
XXX_LIBRARIES :
The libraries to link against to use XXX. These should include full  
paths. This should not be a cache entry!
XXX_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!
XXX_DEFINITIONS :
Definitions to use when compiling code that uses XXX.
Note

This really shouldn't include options such as (-DHAS_JPEG) that a  
client source-code file uses to decide whether to #include <jpeg.h>.  
Too, it must not include any compiler flags like -O3 -Wall to be tool  
independent!
A FindXXX.cmake module will typically be loaded by the command:

FIND_PACKAGE(XXX [major[.minor[.patch[.tweak]]]] [EXACT]
              [QUIET] [[REQUIRED|COMPONENTS] [components...]])
If any version numbers are given to the command it will set the  
following variables before loading the module:

XXX_FIND_VERSION       = full requested version string
XXX_FIND_VERSION_MAJOR = major version if requested, else 0
XXX_FIND_VERSION_MINOR = minor version if requested, else 0
XXX_FIND_VERSION_PATCH = patch version if requested, else 0
XXX_FIND_VERSION_TWEAK = tweak version if requested, else 0
XXX_FIND_VERSION_COUNT = number of version components, 0 to 4
XXX_FIND_VERSION_EXACT = true if EXACT option was given
If the find module supports versioning it should locate a version of  
the package that is compatible with the version requested. If a  
compatible version of the package cannot be found the module should  
not report success. The version of the package found should be stored  
in "XXX_VERSION..." version variables documented by the module.

If the QUIET option is given to the command it will set the variable  
XXX_FIND_QUIETLY to true before loading the FindXXX.cmake module. If  
this variable is set the module should not complain about not being  
able to find the package.

If the REQUIRED option is given to the command it will set the  
variable XXX_FIND_REQUIRED to true before loading the FindXXX.cmake  
module. If this variable is set the module should issue a FATAL_ERROR  
if the package cannot be found. For each package-specific component,  
say YYY, listed after the REQUIRED option a  
variableXXX_FIND_REQUIRED_YYY to true.

The set of components listed after either the REQUIRED option or the  
COMPONENTS option will be specified in a XXX_FIND_COMPONENTS variable.  
This can be used by theFindXXX.cmake module to determine which sub- 
components of the package must be found.

If neither the QUIET nor REQUIRED options are given then the  
FindXXX.cmake module should look for the package and complain without  
error if the module is not found.

Tip

To get this behaviour you can use the  
FIND_PACKAGE_HANDLE_STANDARD_ARGS() macro, as an example see  
FindLibSmi.cmake.
# - Find LIBSMI
# Find the native LIBSMI includes and library
# This module defines
#  LIBSMI_INCLUDE_DIR, where to find smi.h, etc.
#  LIBSMI_LIBRARY, the LIBSMI library with full path.
#  LIBSMI_FOUND, If false, do not try to use LIBSMI.
# also defined, but not for general use are
#  LIBSMI_LIBRARIES, The libraries needed to use LIBSMI.
#  LIBSMI_LIBRARY_DIRS, where to find the LIBSMI library.
#  LIBSMI_DEFINITIONS - You should add_definitons($ 
{LIBSMI_DEFINITIONS}) before
#                       compiling code that includes netsnmp library  
files.

INCLUDE(FindPkgConfig)
IF (PKG_CONFIG_FOUND)
   IF (LIBSMI_FIND_REQUIRED AND LIBSMI_FIND_VERSION)
     SET(_PACKAGE_ARGS libsmi>=${LIBSMI_FIND_VERSION} REQUIRED)
   else ()
     SET(_PACKAGE_ARGS libsmi)
   ENDIF ()
   PKG_CHECK_MODULES(LIBSMI ${_PACKAGE_ARGS})
ENDIF (PKG_CONFIG_FOUND)
SET(LIBSMI_DEFINITIONS ${LIBSMI_CFLAGS_OTHER})

FIND_PATH(LIBSMI_INCLUDE_DIR smi.h HINTS ${LIBSMI_INCLUDE_DIRS})

FIND_LIBRARY(LIBSMI_LIBRARY NAMES smi HINTS ${LIBSMI_LIBRARY_DIRS})
IF (NOT PKG_CONFIG_FOUND)
   SET(LIBSMI_LIBRARIES smi)
   GET_FILENAME_COMPONENT(LIBSMI_LIBRARY_DIRS ${LIBSMI_LIBRARY} PATH)
ENDIF (NOT PKG_CONFIG_FOUND)

# handle the QUIETLY and REQUIRED arguments and set LIBSMI_FOUND to  
TRUE if all
# listed variables are TRUE
INCLUDE(FindPackageHandleStandardArgs)
FIND_PACKAGE_HANDLE_STANDARD_ARGS(LIBSMI DEFAULT_MSG LIBSMI_LIBRARY  
LIBSMI_INCLUDE_DIR
     LIBSMI_LIBRARIES LIBSMI_LIBRARY_DIRS)
MARK_AS_ADVANCED(LIBSMI_LIBRARY LIBSMI_INCLUDE_DIR
     LIBSMI_LIBRARIES LIBSMI_LIBRARY_DIRS LIBSMI_DEFINITIONS)



--------------------------------------------------------------------
I have tried to get the most of the information available from the  
system.
This example is trivial, more important would be FindLibXml2.cmake,  
which does not work in this way!
-- LIBXML2_PREFIX /opt/local
-- LIBXML2_VERSION 2.7.6
-- LIBXML2_INCLUDE_DIR: /usr/include/libxml2
-- LIBXML2_LIBRARY: 
-- LIBXML2_LIBRARIES: xml2;pthread;z;iconv;m
-- LIBXML2_LIBRARY_DIRS: /opt/local/lib
-- LIBXML2_DEFINITIONS: 
-- LIBXML2_CFLAGS: -I/opt/local/include/libxml2
-- LIBXML2_LDFLAGS: -L/opt/local/lib;-lxml2;-lpthread;-lz;-liconv;-lm
-- 
-- LIBXSLT_PREFIX /opt/local
-- LIBXSLT_VERSION 1.1.26
-- LIBXSLT_INCLUDE_DIR: /opt/local/include/libxml2
-- LIBXSLT_LIBRARY: /usr/lib/libxslt.dylib
-- LIBXSLT_LIBRARIES: xslt;xml2;pthread;z;iconv;m
-- LIBXSLT_LIBRARY_DIRS: /opt/local/lib
-- LIBXSLT_DEFINITIONS: 
-- LIBXSLT_CFLAGS: -I/opt/local/include;-I/opt/local/include/libxml2
-- LIBXSLT_LDFLAGS: -L/opt/local/lib;-lxslt;-lxml2;-lpthread;-lz;- 
liconv;-lm
-- 
-- LIBSMI_PREFIX /opt/local
-- LIBSMI_VERSION 0.4.8
-- LIBSMI_INCLUDE_DIR: /opt/local/include
-- LIBSMI_LIBRARY: /opt/local/lib/libsmi.dylib
-- LIBSMI_LIBRARIES: smi
-- LIBSMI_LIBRARY_DIRS: /opt/local/lib
-- LIBSMI_DEFINITIONS: 
-- LIBSMI_CFLAGS: -I/opt/local/include
-- LIBSMI_LDFLAGS: -L/opt/local/lib;-lsmi

I can send you a patch to get this behavior, if you are interested.
//regards
Claus Klein
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.cmake.org/pipermail/cmake/attachments/20091230/df20e478/attachment.htm>