kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'FindPkgConfig-revise-docs' 

49ef91d7 FindPkgConfig: restructure documentation and document commands and variables
This commit is contained in:
Brad King 2014-03-12 10:13:17 -04:00 committed by CMake Topic Stage
parent 4d2545f41c 49ef91d7a6
commit 7122f6b1a8
1 changed files with 118 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

253
Modules/FindPkgConfig.cmake
View File

@ -2,141 +2,15 @@
# FindPkgConfig
# -------------
#
# a pkg-config module for CMake
# A `pkg-config` module for CMake.
#
# Finds the ``pkg-config`` executable and add the
# :command:`pkg_check_modules` and :command:`pkg_search_module`
# commands.
#
#
# To find the pkg-config executable, it uses the variable
# PKG_CONFIG_EXECUTABLE or the environment variable PKG_CONFIG first.
#
#
#
# Usage:
#
# ::
#
# pkg_check_modules(<PREFIX> [REQUIRED] [QUIET] <MODULE> [<MODULE>]*)
# checks for all the given modules
#
#
#
# ::
#
# pkg_search_module(<PREFIX> [REQUIRED] [QUIET] <MODULE> [<MODULE>]*)
# checks for given modules and uses the first working one
#
#
#
# When the 'REQUIRED' argument was set, macros will fail with an error
# when module(s) could not be found
#
# When the 'QUIET' argument is set, no status messages will be printed.
#
# It sets the following variables:
#
# ::
#
# PKG_CONFIG_FOUND ... if pkg-config executable was found
# PKG_CONFIG_EXECUTABLE ... pathname of the pkg-config program
# PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
# (since CMake 2.8.8)
#
#
#
# For the following variables two sets of values exist; first one is the
# common one and has the given PREFIX. The second set contains flags
# which are given out when pkgconfig was called with the '--static'
# option.
#
# ::
#
# <XPREFIX>_FOUND ... set to 1 if module(s) exist
# <XPREFIX>_LIBRARIES ... only the libraries (w/o the '-l')
# <XPREFIX>_LIBRARY_DIRS ... the paths of the libraries (w/o the '-L')
# <XPREFIX>_LDFLAGS ... all required linker flags
# <XPREFIX>_LDFLAGS_OTHER ... all other linker flags
# <XPREFIX>_INCLUDE_DIRS ... the '-I' preprocessor flags (w/o the '-I')
# <XPREFIX>_CFLAGS ... all required cflags
# <XPREFIX>_CFLAGS_OTHER ... the other compiler flags
#
#
#
# ::
#
# <XPREFIX> = <PREFIX> for common case
# <XPREFIX> = <PREFIX>_STATIC for static linking
#
#
#
# There are some special variables whose prefix depends on the count of
# given modules. When there is only one module, <PREFIX> stays
# unchanged. When there are multiple modules, the prefix will be
# changed to <PREFIX>_<MODNAME>:
#
# ::
#
# <XPREFIX>_VERSION ... version of the module
# <XPREFIX>_PREFIX ... prefix-directory of the module
# <XPREFIX>_INCLUDEDIR ... include-dir of the module
# <XPREFIX>_LIBDIR ... lib-dir of the module
#
#
#
# ::
#
# <XPREFIX> = <PREFIX> when |MODULES| == 1, else
# <XPREFIX> = <PREFIX>_<MODNAME>
#
#
#
# A <MODULE> parameter can have the following formats:
#
# ::
#
# {MODNAME} ... matches any version
# {MODNAME}>={VERSION} ... at least version <VERSION> is required
# {MODNAME}={VERSION} ... exactly version <VERSION> is required
# {MODNAME}<={VERSION} ... modules must not be newer than <VERSION>
#
#
#
# Examples
#
# ::
#
# pkg_check_modules (GLIB2 glib-2.0)
#
#
#
# ::
#
# pkg_check_modules (GLIB2 glib-2.0>=2.10)
# requires at least version 2.10 of glib2 and defines e.g.
# GLIB2_VERSION=2.10.3
#
#
#
# ::
#
# pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
# requires both glib2 and gtk2, and defines e.g.
# FOO_glib-2.0_VERSION=2.10.3
# FOO_gtk+-2.0_VERSION=2.8.20
#
#
#
# ::
#
# pkg_check_modules (XRENDER REQUIRED xrender)
# defines e.g.:
# XRENDER_LIBRARIES=Xrender;X11
# XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
#
#
#
# ::
#
# pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
# In order to find the ``pkg-config`` executable, it uses the
# :variable:`PKG_CONFIG_EXECUTABLE` variable or the ``PKG_CONFIG``
# environment variable first.
#=============================================================================
# Copyright 2006-2014 Kitware, Inc.
@ -397,7 +271,94 @@ endmacro()
### User visible macros start here
###
###
#[========================================[.rst:
.. command:: pkg_check_modules
Checks for all the given modules. ::
pkg_check_modules(<PREFIX> [REQUIRED] [QUIET] <MODULE> [<MODULE>]*)
When the ``REQUIRED`` argument was set, macros will fail with an error
when module(s) could not be found.
When the ``QUIET`` argument is set, no status messages will be printed.
It sets the following variables: ::
PKG_CONFIG_FOUND ... if pkg-config executable was found
PKG_CONFIG_EXECUTABLE ... pathname of the pkg-config program
PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
(since CMake 2.8.8)
For the following variables two sets of values exist; first one is the
common one and has the given PREFIX. The second set contains flags
which are given out when ``pkg-config`` was called with the ``--static``
option. ::
<XPREFIX>_FOUND ... set to 1 if module(s) exist
<XPREFIX>_LIBRARIES ... only the libraries (w/o the '-l')
<XPREFIX>_LIBRARY_DIRS ... the paths of the libraries (w/o the '-L')
<XPREFIX>_LDFLAGS ... all required linker flags
<XPREFIX>_LDFLAGS_OTHER ... all other linker flags
<XPREFIX>_INCLUDE_DIRS ... the '-I' preprocessor flags (w/o the '-I')
<XPREFIX>_CFLAGS ... all required cflags
<XPREFIX>_CFLAGS_OTHER ... the other compiler flags
::
<XPREFIX> = <PREFIX> for common case
<XPREFIX> = <PREFIX>_STATIC for static linking
There are some special variables whose prefix depends on the count of
given modules. When there is only one module, <PREFIX> stays
unchanged. When there are multiple modules, the prefix will be
changed to <PREFIX>_<MODNAME>: ::
<XPREFIX>_VERSION ... version of the module
<XPREFIX>_PREFIX ... prefix-directory of the module
<XPREFIX>_INCLUDEDIR ... include-dir of the module
<XPREFIX>_LIBDIR ... lib-dir of the module
::
<XPREFIX> = <PREFIX> when |MODULES| == 1, else
<XPREFIX> = <PREFIX>_<MODNAME>
A <MODULE> parameter can have the following formats: ::
{MODNAME} ... matches any version
{MODNAME}>={VERSION} ... at least version <VERSION> is required
{MODNAME}={VERSION} ... exactly version <VERSION> is required
{MODNAME}<={VERSION} ... modules must not be newer than <VERSION>
Examples
.. code-block:: cmake
pkg_check_modules (GLIB2 glib-2.0)
.. code-block:: cmake
pkg_check_modules (GLIB2 glib-2.0>=2.10)
Requires at least version 2.10 of glib2 and defines e.g.
``GLIB2_VERSION=2.10.3``
.. code-block:: cmake
pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
Requires both glib2 and gtk2, and defines e.g.
``FOO_glib-2.0_VERSION=2.10.3`` and ``FOO_gtk+-2.0_VERSION=2.8.20``
.. code-block:: cmake
pkg_check_modules (XRENDER REQUIRED xrender)
Defines e.g.:
``XRENDER_LIBRARIES=Xrender;X11`` and
``XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp``
#]========================================]
macro(pkg_check_modules _prefix _module0)
# check cached value
if (NOT DEFINED __pkg_config_checked_${_prefix} OR __pkg_config_checked_${_prefix} LESS ${PKG_CONFIG_VERSION} OR NOT ${_prefix}_FOUND)
@ -408,7 +369,21 @@ macro(pkg_check_modules _prefix _module0)
endif()
endmacro()
###
#[========================================[.rst:
.. command:: pkg_search_module
Same as :command:`pkg_check_modules`, but instead it checks for given
modules and uses the first working one. ::
pkg_search_module(<PREFIX> [REQUIRED] [QUIET] <MODULE> [<MODULE>]*)
Examples
.. code-block:: cmake
pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
#]========================================]
macro(pkg_search_module _prefix _module0)
# check cached value
if (NOT DEFINED __pkg_config_checked_${_prefix} OR __pkg_config_checked_${_prefix} LESS ${PKG_CONFIG_VERSION} OR NOT ${_prefix}_FOUND)
@ -440,6 +415,14 @@ macro(pkg_search_module _prefix _module0)
endif()
endmacro()
#[========================================[.rst:
.. variable:: PKG_CONFIG_EXECUTABLE
Path to the pkg-config executable.
#]========================================]
### Local Variables:
### mode: cmake
### End: