Commit 3e3f8b45 authored by Stephen Kelly's avatar Stephen Kelly
Browse files

Help: Document the CMAKE_FIND_ROOT_PATH* variables.

Add a replacement template for the variables, and link to them from
the documentation for the find_* commands.
parent 531c108d
The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
The CMake variable :variable:`CMAKE_FIND_ROOT_PATH` specifies one or more
directories to be prepended to all other search directories. This
effectively "re-roots" the entire search under given locations.
Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded
from this re-rooting, because that variable is always a path on the host system.
By default the CMAKE_FIND_ROOT_PATH is empty.
By default the :variable:`CMAKE_FIND_ROOT_PATH` is empty.
The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one
directory to use as a prefix. Setting :variable:`CMAKE_SYSROOT` also has other
......@@ -12,12 +12,12 @@ effects. See the documentation for that variable for more.
These variables are especially useful when cross-compiling to
point to the root directory of the target environment and CMake will
search there too. By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the :variable:`CMAKE_SYSROOT` directory is
searched, and then the non-rooted directories will be
:variable:`CMAKE_FIND_ROOT_PATH` are searched, then the :variable:`CMAKE_SYSROOT`
directory is searched, and then the non-rooted directories will be
searched. The default behavior can be adjusted by setting
|CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually
overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
the search order will be as described above. If
NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be
used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched.
......@@ -22,6 +22,6 @@ find_file
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
:variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
.. include:: FIND_XXX.txt
......@@ -22,7 +22,7 @@ find_library
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
:variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`
.. include:: FIND_XXX.txt
......
......@@ -320,7 +320,7 @@ hard-coded guesses.
.. |FIND_XXX| replace:: find_package
.. |FIND_ARGS_XXX| replace:: <package>
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
.. include:: FIND_XXX_MAC.txt
.. include:: FIND_XXX_ROOT.txt
......
......@@ -22,7 +22,7 @@ find_path
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
:variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
.. include:: FIND_XXX.txt
......
......@@ -20,6 +20,6 @@ find_program
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`
.. include:: FIND_XXX.txt
......@@ -97,8 +97,13 @@ Variables that Change Behavior
/variable/CMAKE_SYSROOT
/variable/CMAKE_FIND_LIBRARY_PREFIXES
/variable/CMAKE_FIND_LIBRARY_SUFFIXES
/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
/variable/CMAKE_FIND_NO_INSTALL_PREFIX
/variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE
/variable/CMAKE_FIND_ROOT_PATH
/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
/variable/CMAKE_IGNORE_PATH
/variable/CMAKE_INCLUDE_PATH
/variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE
......
CMAKE_FIND_ROOT_PATH
--------------------
List of root paths to search on the filesystem.
This variable is most useful when cross-compiling. CMake uses the paths in
this list as alternative roots to find filesystem items with :command:`find_package`,
:command:`find_library` etc.
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
---------------------------------
.. |FIND_XXX| replace:: :command:`find_file` and :command:`find_path`
.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
---------------------------------
.. |FIND_XXX| replace:: :command:`find_library`
.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
---------------------------------
.. |FIND_XXX| replace:: :command:`find_package`
.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
---------------------------------
.. |FIND_XXX| replace:: :command:`find_program`
.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt
This variable controls whether the :variable:`CMAKE_FIND_ROOT_PATH` and
:variable:`CMAKE_SYSROOT` are used by |FIND_XXX|.
If set to ``ONLY``, then only the roots in :variable:`CMAKE_FIND_ROOT_PATH`
will be searched. If set to ``NEVER``, then the roots in
:variable:`CMAKE_FIND_ROOT_PATH` will be ignored and only the host system
root will be used. If set to ``BOTH``, then the host system paths and the
paths in :variable:`CMAKE_FIND_ROOT_PATH` will be searched.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment