Commit cb811d11 authored by Bartosz Kosiorek's avatar Bartosz Kosiorek

Help: Improve description of modules

parent 4ff7706f
......@@ -20,7 +20,7 @@ preprocessor definitions.
* Use :command:`include_directories` to add include directories.
* Use :command:`add_compile_options` to add other options.
Flags beginning in -D or /D that look like preprocessor definitions are
Flags beginning in ``-D`` or ``/D`` that look like preprocessor definitions are
automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory
property for the current directory. Definitions with non-trivial values
may be left in the set of flags instead of being converted for reasons of
......
......@@ -80,7 +80,7 @@ CMake Policy Stack
^^^^^^^^^^^^^^^^^^
CMake keeps policy settings on a stack, so changes made by the
cmake_policy command affect only the top of the stack. A new entry on
``cmake_policy`` command affect only the top of the stack. A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings. CMake also manages a new entry for
scripts loaded by :command:`include` and :command:`find_package` commands
......
......@@ -17,7 +17,7 @@ named ``[projectname]``. This can be used in the :command:`add_dependencies`
command to make things depend on the external project.
``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to
specify the type of project, id (GUID) of the project and the name of
specify the type of project, id (``GUID``) of the project and the name of
the target platform. This is useful for projects requiring values
other than the default (e.g. WIX projects).
......
......@@ -25,7 +25,7 @@ The optional ``<mode>`` keyword determines the type of message:
The CMake command-line tool displays STATUS messages on stdout and all
other message types on stderr. The CMake GUI displays all messages in
its log area. The interactive dialogs (ccmake and CMakeSetup) show
STATUS messages one at a time on a status line and other messages in
``STATUS`` messages one at a time on a status line and other messages in
interactive pop-up boxes.
CMake Warning and Error message text displays using a simple markup
......
......@@ -35,7 +35,7 @@ It must be one of the following:
``SOURCE``
Scope may name zero or more source files. Note that source
file properties are visible only to targets added in the same
directory (CMakeLists.txt).
directory (``CMakeLists.txt``).
See also the :command:`set_source_files_properties` command.
``INSTALL``
......@@ -48,7 +48,7 @@ It must be one of the following:
Path components have to be separated by forward slashes,
must be normalized and are case sensitive.
To reference the installation prefix itself with a relative path use ".".
To reference the installation prefix itself with a relative path use ``.``.
Currently installed file properties are only defined for
the WIX generator where the given paths are relative
......
......@@ -16,4 +16,4 @@ See also the :command:`set_property(SOURCE)` command.
See :ref:`Source File Properties` for the list of properties known
to CMake. Source file properties are visible only to targets added
in the same directory (CMakeLists.txt).
in the same directory (``CMakeLists.txt``).
......@@ -16,7 +16,7 @@ build with the MinGW tools. It will also create imported targets for
the libraries created. This will only work if the fortran code is
built into a dll, so :variable:`BUILD_SHARED_LIBS` is turned on in
the project. In addition the :variable:`CMAKE_GNUtoMS` option is set
to on, so that Microsoft .lib files are created. Usage is as follows:
to on, so that Microsoft ``.lib`` files are created. Usage is as follows:
::
......@@ -32,15 +32,15 @@ to on, so that Microsoft .lib files are created. Usage is as follows:
NO_EXTERNAL_INSTALL # skip installation of external project
)
Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with
Relative paths in ``ARCHIVE_DIR`` and ``RUNTIME_DIR`` are interpreted with
respect to the build directory corresponding to the source directory
in which the function is invoked.
Limitations:
NO_EXTERNAL_INSTALL is required for forward compatibility with a
``NO_EXTERNAL_INSTALL`` is required for forward compatibility with a
future version that supports installation of the external project
binaries during "make install".
binaries during ``make install``.
#]=======================================================================]
set(_MS_MINGW_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR})
......
This file provides a few notes to CMake developers about how to add
support for a new language to CMake. It is also possible to place
these files in CMAKE_MODULE_PATH within an outside project to add
languages not supported by upstream CMake. However, this is not
these files in :variable:`CMAKE_MODULE_PATH` within an outside project
to add languages not supported by upstream CMake. However, this is not
a fully supported use case.
The implementation behind the scenes of project/enable_language,
......@@ -29,5 +29,3 @@ CMake(LANG)Information.cmake -> set up rule variables for LANG :
CMAKE_(LANG)_CREATE_STATIC_LIBRARY
CMAKE_(LANG)_COMPILE_OBJECT
CMAKE_(LANG)_LINK_EXECUTABLE
......@@ -25,38 +25,41 @@ toolchain file instead.
-------------------------------------------------------------------------
Macro CMAKE_FORCE_C_COMPILER has the following signature:
Macro ``CMAKE_FORCE_C_COMPILER`` has the following signature:
::
CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
variable CMAKE_C_COMPILER_ID to the given compiler-id. It also
bypasses the check for working compiler and basic compiler information
tests.
It sets :variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` to
the given compiler and the cmake internal variable
:variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` to the given
compiler-id. It also bypasses the check for working compiler and basic
compiler information tests.
Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
Macro ``CMAKE_FORCE_CXX_COMPILER`` has the following signature:
::
CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
It sets CMAKE_CXX_COMPILER to the given compiler and the cmake
internal variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It
also bypasses the check for working compiler and basic compiler
information tests.
It sets :variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` to
the given compiler and the cmake internal variable
:variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` to the given
compiler-id. It also bypasses the check for working compiler and basic
compiler information tests.
Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
Macro ``CMAKE_FORCE_Fortran_COMPILER`` has the following signature:
::
CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake
internal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id.
It also bypasses the check for working compiler and basic compiler
information tests.
It sets :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>` to
the given compiler and the cmake internal variable
:variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` to the given
compiler-id. It also bypasses the check for working compiler and basic
compiler information tests.
So a simple toolchain file could look like this:
......
......@@ -13,11 +13,11 @@ Usage:
check_language(<lang>)
where <lang> is a language that may be passed to enable_language()
such as "Fortran". If CMAKE_<lang>_COMPILER is already defined the
check does nothing. Otherwise it tries enabling the language in a
test project. The result is cached in CMAKE_<lang>_COMPILER as the
compiler that was found, or NOTFOUND if the language cannot be
where ``<lang>`` is a language that may be passed to :command:`enable_language`
such as ``Fortran``. If :variable:`CMAKE_<LANG>_COMPILER` is already defined
the check does nothing. Otherwise it tries enabling the language in a
test project. The result is cached in :variable:`CMAKE_<LANG>_COMPILER`
as the compiler that was found, or ``NOTFOUND`` if the language cannot be
enabled.
Example:
......
......@@ -5,8 +5,8 @@
CheckPIESupported
-----------------
Check whether the linker supports position independent code (PIE) or no
position independent code (NO_PIE) for executables.
Check whether the linker supports Position Independent Code (PIE) or No
Position Independent Code (NO_PIE) for executables.
Use this to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
property for executables will be honored at link time.
......
......@@ -5,9 +5,9 @@
FindALSA
--------
Find alsa
Find Advanced Linux Sound Architecture (ALSA)
Find the alsa libraries (asound)
Find the alsa libraries (``asound``)
IMPORTED Targets
^^^^^^^^^^^^^^^^
......
......@@ -7,7 +7,7 @@ FindAVIFile
Locate AVIFILE library and include paths
AVIFILE (http://avifile.sourceforge.net/)is a set of libraries for
AVIFILE (http://avifile.sourceforge.net/) is a set of libraries for
i386 machines to use various AVI codecs. Support is limited beyond
Linux. Windows provides native AVI support, and so doesn't need this
library. This module defines
......
......@@ -5,9 +5,8 @@
FindArmadillo
-------------
Find Armadillo
Find the Armadillo C++ library
Find the Armadillo C++ library.
Armadillo is library for linear algebra & scientific computing.
Using Armadillo:
......
......@@ -16,7 +16,7 @@ The module defines the following variables:
version of ``bison``
``BISON_FOUND``
true if the program was found
"True" if the program was found
The minimum required version of ``bison`` can be specified using the
standard CMake syntax, e.g. :command:`find_package(BISON 2.1.3)`.
......
......@@ -5,30 +5,30 @@
FindBacktrace
-------------
Find provider for backtrace(3).
Find provider for `backtrace(3) <http://man7.org/linux/man-pages/man3/backtrace.3.html>`__.
Checks if OS supports backtrace(3) via either libc or custom library.
Checks if OS supports ``backtrace(3)`` via either ``libc`` or custom library.
This module defines the following variables:
``Backtrace_HEADER``
The header file needed for backtrace(3). Cached.
The header file needed for ``backtrace(3)``. Cached.
Could be forcibly set by user.
``Backtrace_INCLUDE_DIRS``
The include directories needed to use backtrace(3) header.
The include directories needed to use ``backtrace(3)`` header.
``Backtrace_LIBRARIES``
The libraries (linker flags) needed to use backtrace(3), if any.
The libraries (linker flags) needed to use ``backtrace(3)``, if any.
``Backtrace_FOUND``
Is set if and only if backtrace(3) support detected.
Is set if and only if ``backtrace(3)`` support detected.
The following cache variables are also available to set or use:
``Backtrace_LIBRARY``
The external library providing backtrace, if any.
``Backtrace_INCLUDE_DIR``
The directory holding the backtrace(3) header.
The directory holding the ``backtrace(3)`` header.
Typical usage is to generate of header file using configure_file() with the
contents like the following::
Typical usage is to generate of header file using :command:`configure_file`
with the contents like the following::
#cmakedefine01 Backtrace_FOUND
#if Backtrace_FOUND
......
......@@ -27,16 +27,16 @@ Result Variables
This module defines the following variables:
``CURL_FOUND``
True if curl found.
"True" if ``curl`` found.
``CURL_INCLUDE_DIRS``
where to find curl/curl.h, etc.
where to find ``curl``/``curl.h``, etc.
``CURL_LIBRARIES``
List of libraries when using curl.
List of libraries when using ``curl``.
``CURL_VERSION_STRING``
The version of curl found.
The version of ``curl`` found.
#]=======================================================================]
find_package(PkgConfig QUIET)
......
......@@ -5,7 +5,7 @@
FindCVS
-------
Find the Concurrent Versions System (CVS).
The module defines the following variables:
......
......@@ -5,7 +5,7 @@
FindCups
--------
Find the CUPS printing system.
Find the Common UNIX Printing System (CUPS).
Set ``CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE`` to ``TRUE`` if you need a version which
features this function (i.e. at least ``1.1.19``)
......
......@@ -5,7 +5,7 @@
FindCxxTest
-----------
Find CxxTest
Find CxxTest unit testing framework.
Find the CxxTest suite and declare a helper macro for creating unit
tests and integrating them with CTest. For more details on CxxTest
......
......@@ -5,7 +5,8 @@
FindCygwin
----------
this module looks for Cygwin
Find Cygwin, a POSIX-compatible environment that runs natively
on Microsoft Windows
#]=======================================================================]
if (WIN32)
......
......@@ -5,7 +5,7 @@
FindDCMTK
---------
Find DCMTK libraries and applications
Find DICOM ToolKit (DCMTK) libraries and applications
The module defines the following variables::
......
......@@ -6,6 +6,7 @@ FindEXPAT
---------
Find the native Expat headers and library.
Expat is a stream-oriented XML parser library written in C.
Imported Targets
^^^^^^^^^^^^^^^^
......
......@@ -5,7 +5,8 @@
FindFLEX
--------
Find flex executable and provides a macro to generate custom build rules
Find Fast Lexical Analyzer (Flex) executable and provides a macro
to generate custom build rules
......@@ -22,7 +23,7 @@ The module defines the following variables:
The minimum required version of flex can be specified using the
standard syntax, e.g. find_package(FLEX 2.5.13)
standard syntax, e.g. :command:`find_package(FLEX 2.5.13)`
......
......@@ -5,14 +5,14 @@
FindFLTK
--------
Find the FLTK library
Find the Fast Light Toolkit (FLTK) library
Input Variables
^^^^^^^^^^^^^^^
By default this module will search for all of the FLTK components and
add them to the FLTK_LIBRARIES variable. You can limit the components
which get placed in FLTK_LIBRARIES by defining one or more of the
add them to the ``FLTK_LIBRARIES`` variable. You can limit the components
which get placed in ``FLTK_LIBRARIES`` by defining one or more of the
following three options:
``FLTK_SKIP_OPENGL``
......
......@@ -5,7 +5,7 @@
FindFLTK2
---------
Find the native FLTK2 includes and library
Find the native FLTK 2.0 includes and library
The following settings are defined
......@@ -243,4 +243,3 @@ else()
endif()
endif()
endif()
......@@ -5,7 +5,7 @@
FindGDAL
--------
Find GDAL.
Find Geospatial Data Abstraction Library (GDAL).
IMPORTED Targets
^^^^^^^^^^^^^^^^
......
......@@ -5,7 +5,7 @@
FindGIF
-------
This finds the GIF library (giflib)
This finds the Graphics Interchange Format (GIF) library (``giflib``)
Imported targets
^^^^^^^^^^^^^^^^
......@@ -13,7 +13,7 @@ Imported targets
This module defines the following :prop_tgt:`IMPORTED` target:
``GIF::GIF``
The giflib library, if found.
The ``giflib`` library, if found.
Result variables
^^^^^^^^^^^^^^^^
......
......@@ -15,4 +15,3 @@ if (OPENGL_GLU_FOUND)
set (GLU_LIBRARY ${OPENGL_LIBRARIES})
set (GLU_INCLUDE_PATH ${OPENGL_INCLUDE_DIR})
endif ()
......@@ -5,7 +5,7 @@
FindGLUT
--------
try to find glut library and include files.
Find OpenGL Utility Toolkit (GLUT) library and include files.
IMPORTED Targets
^^^^^^^^^^^^^^^^
......
......@@ -5,7 +5,7 @@
FindGSL
--------
Find the native GSL includes and libraries.
Find the native GNU Scientific Library (GSL) includes and libraries.
The GNU Scientific Library (GSL) is a numerical library for C and C++
programmers. It is free software under the GNU General Public
......
......@@ -5,7 +5,7 @@
FindGTK
-------
try to find GTK (and glib) and GTKGLArea
Find GTK, glib and GTKGLArea
::
......@@ -151,6 +151,3 @@ if(UNIX)
)
endif()
......@@ -5,10 +5,8 @@
FindGTK2
--------
FindGTK2.cmake
This module can find the GTK2 widget libraries and several of its
other optional components like gtkmm, glade, and glademm.
Find the GTK2 widget libraries and several of its
other optional components like ``gtkmm``, ``glade``, and ``glademm``.
NOTE: If you intend to use version checking, CMake 2.6.2 or later is
......
......@@ -5,7 +5,7 @@
FindGnuTLS
----------
Try to find the GNU Transport Layer Security library (gnutls)
Find the GNU Transport Layer Security library (gnutls)
......
......@@ -5,43 +5,44 @@
FindHDF5
--------
Find HDF5, a library for reading and writing self describing array data.
Find Hierarchical Data Format (HDF5), a library for reading and writing
self describing array data.
This module invokes the HDF5 wrapper compiler that should be installed
alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
compiler is called either h5cc or h5pcc. If this succeeds, the module
will then call the compiler with the -show argument to see what flags
are used when compiling an HDF5 client application.
This module invokes the ``HDF5`` wrapper compiler that should be installed
alongside ``HDF5``. Depending upon the ``HDF5`` Configuration, the wrapper
compiler is called either ``h5cc`` or ``h5pcc``. If this succeeds, the module
will then call the compiler with the show argument to see what flags
are used when compiling an ``HDF5`` client application.
The module will optionally accept the COMPONENTS argument. If no
COMPONENTS are specified, then the find module will default to finding
only the HDF5 C library. If one or more COMPONENTS are specified, the
The module will optionally accept the ``COMPONENTS`` argument. If no
``COMPONENTS`` are specified, then the find module will default to finding
only the ``HDF5`` C library. If one or more ``COMPONENTS`` are specified, the
module will attempt to find the language bindings for the specified
components. The only valid components are C, CXX, Fortran, HL, and
Fortran_HL. If the COMPONENTS argument is not given, the module will
components. The only valid components are ``C``, ``CXX``, ``Fortran``, ``HL``,
and ``Fortran_HL``. If the ``COMPONENTS`` argument is not given, the module will
attempt to find only the C bindings.
This module will read the variable
HDF5_USE_STATIC_LIBRARIES to determine whether or not to prefer a
static link to a dynamic link for HDF5 and all of it's dependencies.
To use this feature, make sure that the HDF5_USE_STATIC_LIBRARIES
``HDF5_USE_STATIC_LIBRARIES`` to determine whether or not to prefer a
static link to a dynamic link for ``HDF5`` and all of it's dependencies.
To use this feature, make sure that the ``HDF5_USE_STATIC_LIBRARIES``
variable is set before the call to find_package.
To provide the module with a hint about where to find your HDF5
installation, you can set the environment variable HDF5_ROOT. The
Find module will then look in this path when searching for HDF5
To provide the module with a hint about where to find your ``HDF5``
installation, you can set the environment variable ``HDF5_ROOT``. The
Find module will then look in this path when searching for ``HDF5``
executables, paths, and libraries.
Both the serial and parallel HDF5 wrappers are considered and the first
Both the serial and parallel ``HDF5`` wrappers are considered and the first
directory to contain either one will be used. In the event that both appear
in the same directory the serial version is preferentially selected. This
behavior can be reversed by setting the variable HDF5_PREFER_PARALLEL to
true.
behavior can be reversed by setting the variable ``HDF5_PREFER_PARALLEL`` to
``True``.
In addition to finding the includes and libraries required to compile
an HDF5 client application, this module also makes an effort to find
tools that come with the HDF5 distribution that may be useful for
an ``HDF5`` client application, this module also makes an effort to find
tools that come with the ``HDF5`` distribution that may be useful for
regression testing.
Result Variables
......
......@@ -5,7 +5,7 @@
FindHSPELL
----------
Try to find Hspell
Try to find Hebrew spell-checker (Hspell) and morphology engine.
Once done this will define
......
......@@ -7,8 +7,8 @@ FindIcotool
Find icotool
This module looks for icotool. This module defines the following
values:
This module looks for icotool. Convert and create Win32 icon and cursor files.
This module defines the following values:
::
......
......@@ -5,11 +5,11 @@
FindImageMagick
---------------
Find the ImageMagick binary suite.
Find ImageMagick binary suite.
This module will search for a set of ImageMagick tools specified as
components in the FIND_PACKAGE call. Typical components include, but
are not limited to (future versions of ImageMagick might have
components in the :command:`find_package` call. Typical components include,
but are not limited to (future versions of ImageMagick might have
additional components not listed here):
::
......@@ -28,7 +28,7 @@ additional components not listed here):
If no component is specified in the FIND_PACKAGE call, then it only
If no component is specified in the :command:`find_package` call, then it only
searches for the ImageMagick executable directory. This code defines
the following variables:
......@@ -43,7 +43,7 @@ the following variables:
ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
``ImageMagick_VERSION_STRING`` will not work for old versions like 5.2.3.
There are also components for the following ImageMagick APIs:
......@@ -80,8 +80,8 @@ Example Usages:
Note that the standard FIND_PACKAGE features are supported (i.e.,
QUIET, REQUIRED, etc.).
Note that the standard :command:`find_package` features are supported (i.e.,
``QUIET``, ``REQUIRED``, etc.).
#]=======================================================================]
find_package(PkgConfig QUIET)
......
......@@ -5,7 +5,7 @@
FindJPEG
--------
Find the JPEG library (libjpeg)
Find the Joint Photographic Experts Group (JPEG) library (``libjpeg``)
Imported targets
^^^^^^^^^^^^^^^^
......
......@@ -35,7 +35,7 @@ The following user adjustable options are provided:
``KDE3_BUILD_TESTS``
enable this to build KDE testcases
It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
It also adds the following macros (from ``KDE3Macros.cmake``) ``SRCS_VAR`` is
always the variable which contains the list of source files for your
application or library.
......@@ -358,4 +358,3 @@ endif ()
#add the found Qt and KDE include directories to the current include path
set(KDE3_INCLUDE_DIRS ${QT_INCLUDE_DIR} ${KDE3_INCLUDE_DIR})
......@@ -19,7 +19,7 @@ the given order:
Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more
Please look in ``FindKDE4Internal.cmake`` and ``KDE4Macros.cmake`` for more
information. They are installed with the KDE 4 libraries in
$KDEDIRS/share/apps/cmake/modules/.
......
......@@ -5,13 +5,13 @@
FindLAPACK
----------
Find LAPACK library
Find Linear Algebra PACKage (LAPACK) library
This module finds an installed fortran library that implements the
LAPACK linear-algebra interface (see http://www.netlib.org/lapack/).
The approach follows that taken for the autoconf macro file,
acx_lapack.m4 (distributed at
``acx_lapack.m4`` (distributed at
http://ac-archive.sourceforge.net/ac-archive/acx_lapack.html).
Input Variables
......
......@@ -5,9 +5,9 @@
FindLATEX
---------
Find Latex
Find LaTeX
This module finds an installed Latex and determines the location
This module finds an installed LaTeX and determines the location
of the compiler. Additionally the module looks for Latex-related
software like BibTeX.
......
......@@ -5,7 +5,8 @@
FindLTTngUST
------------
This module finds the `LTTng-UST <http://lttng.org/>`__ library.
Find
`Linux Trace Toolkit Next Generation (LTTng-UST) <http://lttng.org/>`__ library.
Imported target
^^^^^^^^^^^^^^^
......
......@@ -5,7 +5,8 @@
FindLibArchive
--------------
Find libarchive library and headers
Find libarchive library and headers.
Libarchive is multi-format archive and compression library.
The module defines the following variables:
......
......@@ -5,7 +5,8 @@
FindLibXslt
-----------
Try to find the LibXslt library
Find the XSL Transformations, Extensible Stylesheet Language
Transformations (XSLT) library (LibXslt)
Once done this will define
......
......@@ -7,7 +7,9 @@ FindLua
Locate Lua library This module defines
Locate Lua library.
This module defines::
::
......
......@@ -7,7 +7,8 @@ FindLua50
Locate Lua library This module defines
Locate Lua library.
This module defines::
::
......@@ -87,4 +88,3 @@ include(${CMAKE_CURRENT_LIST_DIR}/FindPackageHandleStandardArgs.cmake)
FIND_PACKAGE_HANDLE_STANDARD_ARGS(Lua50 DEFAULT_MSG LUA_LIBRARIES LUA_INCLUDE_DIR)