From 49ef91d7a6dc75b5bbc7a6b06ed909b23d13fd72 Mon Sep 17 00:00:00 2001 From: "Daniele E. Domenichelli" Date: Thu, 6 Mar 2014 18:54:52 +0100 Subject: [PATCH] FindPkgConfig: restructure documentation and document commands and variables --- Modules/FindPkgConfig.cmake | 253 +++++++++++++++++------------------- 1 file changed, 118 insertions(+), 135 deletions(-) diff --git a/Modules/FindPkgConfig.cmake b/Modules/FindPkgConfig.cmake index 7179d17d8..b0ceb2b24 100644 --- a/Modules/FindPkgConfig.cmake +++ b/Modules/FindPkgConfig.cmake @@ -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( [REQUIRED] [QUIET] []*) -# checks for all the given modules -# -# -# -# :: -# -# pkg_search_module( [REQUIRED] [QUIET] []*) -# 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. -# -# :: -# -# _FOUND ... set to 1 if module(s) exist -# _LIBRARIES ... only the libraries (w/o the '-l') -# _LIBRARY_DIRS ... the paths of the libraries (w/o the '-L') -# _LDFLAGS ... all required linker flags -# _LDFLAGS_OTHER ... all other linker flags -# _INCLUDE_DIRS ... the '-I' preprocessor flags (w/o the '-I') -# _CFLAGS ... all required cflags -# _CFLAGS_OTHER ... the other compiler flags -# -# -# -# :: -# -# = for common case -# = _STATIC for static linking -# -# -# -# There are some special variables whose prefix depends on the count of -# given modules. When there is only one module, stays -# unchanged. When there are multiple modules, the prefix will be -# changed to _: -# -# :: -# -# _VERSION ... version of the module -# _PREFIX ... prefix-directory of the module -# _INCLUDEDIR ... include-dir of the module -# _LIBDIR ... lib-dir of the module -# -# -# -# :: -# -# = when |MODULES| == 1, else -# = _ -# -# -# -# A parameter can have the following formats: -# -# :: -# -# {MODNAME} ... matches any version -# {MODNAME}>={VERSION} ... at least version is required -# {MODNAME}={VERSION} ... exactly version is required -# {MODNAME}<={VERSION} ... modules must not be newer than -# -# -# -# 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( [REQUIRED] [QUIET] []*) + + 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. :: + + _FOUND ... set to 1 if module(s) exist + _LIBRARIES ... only the libraries (w/o the '-l') + _LIBRARY_DIRS ... the paths of the libraries (w/o the '-L') + _LDFLAGS ... all required linker flags + _LDFLAGS_OTHER ... all other linker flags + _INCLUDE_DIRS ... the '-I' preprocessor flags (w/o the '-I') + _CFLAGS ... all required cflags + _CFLAGS_OTHER ... the other compiler flags + + :: + + = for common case + = _STATIC for static linking + + There are some special variables whose prefix depends on the count of + given modules. When there is only one module, stays + unchanged. When there are multiple modules, the prefix will be + changed to _: :: + + _VERSION ... version of the module + _PREFIX ... prefix-directory of the module + _INCLUDEDIR ... include-dir of the module + _LIBDIR ... lib-dir of the module + + :: + + = when |MODULES| == 1, else + = _ + + A parameter can have the following formats: :: + + {MODNAME} ... matches any version + {MODNAME}>={VERSION} ... at least version is required + {MODNAME}={VERSION} ... exactly version is required + {MODNAME}<={VERSION} ... modules must not be newer than + + 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( [REQUIRED] [QUIET] []*) + + 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: