From 3e3f8b456f5d205d0f5126df80950903c4bd4412 Mon Sep 17 00:00:00 2001 From: Stephen Kelly Date: Tue, 26 Nov 2013 19:58:07 +0100 Subject: [PATCH] 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. --- Help/command/FIND_XXX_ROOT.txt | 10 +++++----- Help/command/find_file.rst | 2 +- Help/command/find_library.rst | 2 +- Help/command/find_package.rst | 2 +- Help/command/find_path.rst | 2 +- Help/command/find_program.rst | 2 +- Help/manual/cmake-variables.7.rst | 7 ++++++- Help/variable/CMAKE_FIND_ROOT_PATH.rst | 8 ++++++++ Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst | 6 ++++++ Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst | 6 ++++++ Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst | 6 ++++++ Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst | 6 ++++++ Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt | 8 ++++++++ 13 files changed, 56 insertions(+), 11 deletions(-) create mode 100644 Help/variable/CMAKE_FIND_ROOT_PATH.rst create mode 100644 Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst create mode 100644 Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst create mode 100644 Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst create mode 100644 Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst create mode 100644 Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt index efc076fb2..b5cab68b8 100644 --- a/Help/command/FIND_XXX_ROOT.txt +++ b/Help/command/FIND_XXX_ROOT.txt @@ -1,9 +1,9 @@ -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. diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index 549b3170d..db7e1518e 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -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 diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 8598be784..91342bad3 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -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 diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index c394a0809..f09cb41ab 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -320,7 +320,7 @@ hard-coded guesses. .. |FIND_XXX| replace:: find_package .. |FIND_ARGS_XXX| replace:: .. |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 diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index c85011a78..95d49e77a 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -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 diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst index da5a41d14..c62a8a5d2 100644 --- a/Help/command/find_program.rst +++ b/Help/command/find_program.rst @@ -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 diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1f6698b4f..1a32d3034 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -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 diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst new file mode 100644 index 000000000..67948f7ce --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -0,0 +1,8 @@ +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. diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst new file mode 100644 index 000000000..df1af5a88 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_INCLUDE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_file` and :command:`find_path` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst new file mode 100644 index 000000000..52ab89dc5 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_LIBRARY +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_library` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst new file mode 100644 index 000000000..387294797 --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PACKAGE +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_package` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst new file mode 100644 index 000000000..d24a78a3f --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.rst @@ -0,0 +1,6 @@ +CMAKE_FIND_ROOT_PATH_MODE_PROGRAM +--------------------------------- + +.. |FIND_XXX| replace:: :command:`find_program` + +.. include:: CMAKE_FIND_ROOT_PATH_MODE_XXX.txt diff --git a/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt new file mode 100644 index 000000000..ab65e090e --- /dev/null +++ b/Help/variable/CMAKE_FIND_ROOT_PATH_MODE_XXX.txt @@ -0,0 +1,8 @@ +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.