Commit df4ed1e9 authored by Kitware Robot's avatar Kitware Robot Committed by Kyle Edwards

Help: Convert remaining modules to block-style comments

parent 7115aa6c
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# AddFileDependencies
# -------------------
#
# Add dependencies to a source file.
#
# .. code-block:: cmake
#
# ADD_FILE_DEPENDENCIES(<source> <files>)
#
# Adds the given ``<files>`` to the dependencies of file ``<source>``.
#[=======================================================================[.rst:
AddFileDependencies
-------------------
Add dependencies to a source file.
.. code-block:: cmake
ADD_FILE_DEPENDENCIES(<source> <files>)
Adds the given ``<files>`` to the dependencies of file ``<source>``.
#]=======================================================================]
macro(ADD_FILE_DEPENDENCIES _file)
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeAddFortranSubdirectory
# ---------------------------
#
# Use MinGW gfortran from VS if a fortran compiler is not found.
#
# The 'add_fortran_subdirectory' function adds a subdirectory to a
# project that contains a fortran only sub-project. The module will
# check the current compiler and see if it can support fortran. If no
# fortran compiler is found and the compiler is MSVC, then this module
# will find the MinGW gfortran. It will then use an external project to
# 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 BUILD_SHARED_LIBS is turned on in the project.
# In addition the CMAKE_GNUtoMS option is set to on, so that the MS .lib
# files are created. Usage is as follows:
#
# ::
#
# cmake_add_fortran_subdirectory(
# <subdir> # name of subdirectory
# PROJECT <project_name> # project name in subdir top CMakeLists.txt
# ARCHIVE_DIR <dir> # dir where project places .lib files
# RUNTIME_DIR <dir> # dir where project places .dll files
# LIBRARIES <lib>... # names of library targets to import
# LINK_LIBRARIES # link interface libraries for LIBRARIES
# [LINK_LIBS <lib> <dep>...]...
# CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
# NO_EXTERNAL_INSTALL # skip installation of external project
# )
#
# 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
# future version that supports installation of the external project
# binaries during "make install".
#[=======================================================================[.rst:
CMakeAddFortranSubdirectory
---------------------------
Use MinGW gfortran from VS if a fortran compiler is not found.
The 'add_fortran_subdirectory' function adds a subdirectory to a
project that contains a fortran only sub-project. The module will
check the current compiler and see if it can support fortran. If no
fortran compiler is found and the compiler is MSVC, then this module
will find the MinGW gfortran. It will then use an external project to
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 BUILD_SHARED_LIBS is turned on in the project.
In addition the CMAKE_GNUtoMS option is set to on, so that the MS .lib
files are created. Usage is as follows:
::
cmake_add_fortran_subdirectory(
<subdir> # name of subdirectory
PROJECT <project_name> # project name in subdir top CMakeLists.txt
ARCHIVE_DIR <dir> # dir where project places .lib files
RUNTIME_DIR <dir> # dir where project places .dll files
LIBRARIES <lib>... # names of library targets to import
LINK_LIBRARIES # link interface libraries for LIBRARIES
[LINK_LIBS <lib> <dep>...]...
CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
NO_EXTERNAL_INSTALL # skip installation of external project
)
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
future version that supports installation of the external project
binaries during "make install".
#]=======================================================================]
set(_MS_MINGW_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR})
include(CheckLanguage)
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeBackwardCompatibilityCXX
# -----------------------------
#
# define a bunch of backwards compatibility variables
#
# ::
#
# CMAKE_ANSI_CXXFLAGS - flag for ansi c++
# CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
# include(TestForANSIStreamHeaders)
# include(CheckIncludeFileCXX)
# include(TestForSTDNamespace)
# include(TestForANSIForScope)
#[=======================================================================[.rst:
CMakeBackwardCompatibilityCXX
-----------------------------
define a bunch of backwards compatibility variables
::
CMAKE_ANSI_CXXFLAGS - flag for ansi c++
CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
include(TestForANSIStreamHeaders)
include(CheckIncludeFileCXX)
include(TestForSTDNamespace)
include(TestForANSIForScope)
#]=======================================================================]
if(NOT CMAKE_SKIP_COMPATIBILITY_TESTS)
# check for some ANSI flags in the CXX compiler if it is not gnu
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeDependentOption
# --------------------
#
# Macro to provide an option dependent on other options.
#
# This macro presents an option to the user only if a set of other
# conditions are true. When the option is not presented a default value
# is used, but any value set by the user is preserved for when the
# option is presented again. Example invocation:
#
# ::
#
# CMAKE_DEPENDENT_OPTION(USE_FOO "Use Foo" ON
# "USE_BAR;NOT USE_ZOT" OFF)
#
# If USE_BAR is true and USE_ZOT is false, this provides an option
# called USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to
# OFF. If the status of USE_BAR or USE_ZOT ever changes, any value for
# the USE_FOO option is saved so that when the option is re-enabled it
# retains its old value.
#[=======================================================================[.rst:
CMakeDependentOption
--------------------
Macro to provide an option dependent on other options.
This macro presents an option to the user only if a set of other
conditions are true. When the option is not presented a default value
is used, but any value set by the user is preserved for when the
option is presented again. Example invocation:
::
CMAKE_DEPENDENT_OPTION(USE_FOO "Use Foo" ON
"USE_BAR;NOT USE_ZOT" OFF)
If USE_BAR is true and USE_ZOT is false, this provides an option
called USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to
OFF. If the status of USE_BAR or USE_ZOT ever changes, any value for
the USE_FOO option is saved so that when the option is re-enabled it
retains its old value.
#]=======================================================================]
macro(CMAKE_DEPENDENT_OPTION option doc default depends force)
if(${option}_ISSET MATCHES "^${option}_ISSET$")
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeDetermineVSServicePack
# ---------------------------
#
# Deprecated. Do not use.
#
# The functionality of this module has been superseded by the
# :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable that contains
# the compiler version number.
#
# Determine the Visual Studio service pack of the 'cl' in use.
#
# Usage::
#
# if(MSVC)
# include(CMakeDetermineVSServicePack)
# DetermineVSServicePack( my_service_pack )
# if( my_service_pack )
# message(STATUS "Detected: ${my_service_pack}")
# endif()
# endif()
#
# Function DetermineVSServicePack sets the given variable to one of the
# following values or an empty string if unknown::
#
# vc80, vc80sp1
# vc90, vc90sp1
# vc100, vc100sp1
# vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
#[=======================================================================[.rst:
CMakeDetermineVSServicePack
---------------------------
Deprecated. Do not use.
The functionality of this module has been superseded by the
:variable:`CMAKE_<LANG>_COMPILER_VERSION` variable that contains
the compiler version number.
Determine the Visual Studio service pack of the 'cl' in use.
Usage::
if(MSVC)
include(CMakeDetermineVSServicePack)
DetermineVSServicePack( my_service_pack )
if( my_service_pack )
message(STATUS "Detected: ${my_service_pack}")
endif()
endif()
Function DetermineVSServicePack sets the given variable to one of the
following values or an empty string if unknown::
vc80, vc80sp1
vc90, vc90sp1
vc100, vc100sp1
vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
#]=======================================================================]
if(NOT CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 2.8.8)
message(DEPRECATION
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeExpandImportedTargets
# --------------------------
#
# Deprecated. Do not use.
#
# This module was once needed to expand imported targets to the underlying
# libraries they reference on disk for use with the :command:`try_compile`
# and :command:`try_run` commands. These commands now support imported
# libraries in their ``LINK_LIBRARIES`` options (since CMake 2.8.11
# for :command:`try_compile` and since CMake 3.2 for :command:`try_run`).
#
# This module does not support the policy :policy:`CMP0022` ``NEW``
# behavior or use of the :prop_tgt:`INTERFACE_LINK_LIBRARIES` property
# because :manual:`generator expressions <cmake-generator-expressions(7)>`
# cannot be evaluated during configuration.
#
# ::
#
# CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
# [CONFIGURATION <config>])
#
# CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
# all imported targets contained in this list with their actual file
# paths of the referenced libraries on disk, including the libraries
# from their link interfaces. If a CONFIGURATION is given, it uses the
# respective configuration of the imported targets if it exists. If no
# CONFIGURATION is given, it uses the first configuration from
# ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
#
# ::
#
# cmake_expand_imported_targets(expandedLibs
# LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
# CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
#[=======================================================================[.rst:
CMakeExpandImportedTargets
--------------------------
Deprecated. Do not use.
This module was once needed to expand imported targets to the underlying
libraries they reference on disk for use with the :command:`try_compile`
and :command:`try_run` commands. These commands now support imported
libraries in their ``LINK_LIBRARIES`` options (since CMake 2.8.11
for :command:`try_compile` and since CMake 3.2 for :command:`try_run`).
This module does not support the policy :policy:`CMP0022` ``NEW``
behavior or use of the :prop_tgt:`INTERFACE_LINK_LIBRARIES` property
because :manual:`generator expressions <cmake-generator-expressions(7)>`
cannot be evaluated during configuration.
::
CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
[CONFIGURATION <config>])
CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
all imported targets contained in this list with their actual file
paths of the referenced libraries on disk, including the libraries
from their link interfaces. If a CONFIGURATION is given, it uses the
respective configuration of the imported targets if it exists. If no
CONFIGURATION is given, it uses the first configuration from
${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
::
cmake_expand_imported_targets(expandedLibs
LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
#]=======================================================================]
function(CMAKE_EXPAND_IMPORTED_TARGETS _RESULT )
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeFindFrameworks
# -------------------
#
# helper module to find OSX frameworks
#
# This module reads hints about search locations from variables::
#
# CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
#[=======================================================================[.rst:
CMakeFindFrameworks
-------------------
helper module to find OSX frameworks
This module reads hints about search locations from variables::
CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
#]=======================================================================]
if(NOT CMAKE_FIND_FRAMEWORKS_INCLUDED)
set(CMAKE_FIND_FRAMEWORKS_INCLUDED 1)
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeFindPackageMode
# --------------------
#
#
#
# This file is executed by cmake when invoked with --find-package. It
# expects that the following variables are set using -D:
#
# ``NAME``
# name of the package
# ``COMPILER_ID``
# the CMake compiler ID for which the result is,
# i.e. GNU/Intel/Clang/MSVC, etc.
# ``LANGUAGE``
# language for which the result will be used,
# i.e. C/CXX/Fortran/ASM
# ``MODE``
# ``EXIST``
# only check for existence of the given package
# ``COMPILE``
# print the flags needed for compiling an object file which uses
# the given package
# ``LINK``
# print the flags needed for linking when using the given package
# ``QUIET``
# if TRUE, don't print anything
#[=======================================================================[.rst:
CMakeFindPackageMode
--------------------
This file is executed by cmake when invoked with --find-package. It
expects that the following variables are set using -D:
``NAME``
name of the package
``COMPILER_ID``
the CMake compiler ID for which the result is,
i.e. GNU/Intel/Clang/MSVC, etc.
``LANGUAGE``
language for which the result will be used,
i.e. C/CXX/Fortran/ASM
``MODE``
``EXIST``
only check for existence of the given package
``COMPILE``
print the flags needed for compiling an object file which uses
the given package
``LINK``
print the flags needed for linking when using the given package
``QUIET``
if TRUE, don't print anything
#]=======================================================================]
if(NOT NAME)
message(FATAL_ERROR "Name of the package to be searched not specified. Set the CMake variable NAME, e.g. -DNAME=JPEG .")
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeForceCompiler
# ------------------
#
# Deprecated. Do not use.
#
# The macros provided by this module were once intended for use by
# cross-compiling toolchain files when CMake was not able to automatically
# detect the compiler identification. Since the introduction of this module,
# CMake's compiler identification capabilities have improved and can now be
# taught to recognize any compiler. Furthermore, the suite of information
# CMake detects from a compiler is now too extensive to be provided by
# toolchain files using these macros.
#
# One common use case for this module was to skip CMake's checks for a
# working compiler when using a cross-compiler that cannot link binaries
# without special flags or custom linker scripts. This case is now supported
# by setting the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable in the
# toolchain file instead.
#
# -------------------------------------------------------------------------
#
# 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.
#
# 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.
#
# 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.
#
# So a simple toolchain file could look like this:
#
# ::
#
# include (CMakeForceCompiler)
# set(CMAKE_SYSTEM_NAME Generic)
# CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
# CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
#[=======================================================================[.rst:
CMakeForceCompiler
------------------
Deprecated. Do not use.
The macros provided by this module were once intended for use by
cross-compiling toolchain files when CMake was not able to automatically
detect the compiler identification. Since the introduction of this module,
CMake's compiler identification capabilities have improved and can now be
taught to recognize any compiler. Furthermore, the suite of information
CMake detects from a compiler is now too extensive to be provided by
toolchain files using these macros.
One common use case for this module was to skip CMake's checks for a
working compiler when using a cross-compiler that cannot link binaries
without special flags or custom linker scripts. This case is now supported
by setting the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable in the
toolchain file instead.
-------------------------------------------------------------------------
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.
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.
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.
So a simple toolchain file could look like this:
::
include (CMakeForceCompiler)
set(CMAKE_SYSTEM_NAME Generic)
CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
#]=======================================================================]
macro(CMAKE_FORCE_C_COMPILER compiler id)
message(DEPRECATION "The CMAKE_FORCE_C_COMPILER macro is deprecated. "
......
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# CMakeGraphVizOptions
# --------------------
#
# The builtin graphviz support of CMake.
#
# Variables specific to the graphviz support
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#
# CMake
# can generate `graphviz <http://www.graphviz.org/>`_ files, showing the dependencies between the
# targets in a project and also external libraries which are linked
# against. When CMake is run with the ``--graphviz=foo.dot`` option, it will
# produce:
#
# * a ``foo.dot`` file showing all dependencies in the project
# * a ``foo.dot.<target>`` file for each target, file showing on which other targets the respective target depends
# * a ``foo.dot.<target>.dependers`` file, showing which other targets depend on the respective target
#
# The different dependency types ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
# are represented as solid, dashed and dotted edges.
#
# This can result in huge graphs. Using the file
# ``CMakeGraphVizOptions.cmake`` the look and content of the generated
# graphs can be influenced. This file is searched first in
# :variable:`CMAKE_BINARY_DIR` and then in :variable:`CMAKE_SOURCE_DIR`. If found, it is
# read and the variables set in it are used to adjust options for the
# generated graphviz files.
#
# .. variable:: GRAPHVIZ_GRAPH_TYPE
#
# The graph type.
#
# * Mandatory : NO
# * Default : "digraph"
#
# Valid graph types are:
#
# * "graph" : Nodes are joined with lines
# * "digraph" : Nodes are joined with arrows showing direction
# * "strict graph" : Like "graph" but max one line between each node
# * "strict digraph" : Like "graph" but max one line between each node in each direction
#
# .. variable:: GRAPHVIZ_GRAPH_NAME
#
# The graph name.
#
# * Mandatory : NO
# * Default : "GG"
#
# .. variable:: GRAPHVIZ_GRAPH_HEADER
#
# The header written at the top of the graphviz file.
#
# * Mandatory : NO
# * Default : "node [n fontsize = "12"];"
#
# .. variable:: GRAPHVIZ_NODE_PREFIX
#
# The prefix for each node in the graphviz file.
#
# * Mandatory : NO
# * Default : "node"
#
# .. variable:: GRAPHVIZ_EXECUTABLES
#
# Set this to FALSE to exclude executables from the generated graphs.
#
# * Mandatory : NO
# * Default : TRUE
#
# .. variable:: GRAPHVIZ_STATIC_LIBS
#
# Set this to FALSE to exclude static libraries from the generated graphs.
#
# * Mandatory : NO
# * Default : TRUE
#
# .. variable:: GRAPHVIZ_SHARED_LIBS
#
# Set this to FALSE to exclude shared libraries from the generated graphs.
#
# * Mandatory : NO
# * Default : TRUE
#
# .. variable:: GRAPHVIZ_MODULE_LIBS
#
# Set this to FALSE to exclude module libraries from the generated graphs.
#
# * Mandatory : NO