diff options
| -rw-r--r-- | Help/command/FIND_XXX.txt | 5 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_IGNORE_PATH.rst | 26 | ||||
| -rw-r--r-- | Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst | 25 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst | 26 | ||||
| -rw-r--r-- | Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst | 26 | ||||
| -rw-r--r-- | Help/variable/IGNORE_SEARCH_LOCATIONS.txt | 4 | ||||
| -rw-r--r-- | Help/variable/IGNORE_SEARCH_NONSYSTEM.txt | 2 | ||||
| -rw-r--r-- | Help/variable/IGNORE_SEARCH_PATH.txt | 19 | ||||
| -rw-r--r-- | Help/variable/IGNORE_SEARCH_PREFIX.txt | 6 | ||||
| -rw-r--r-- | Help/variable/IGNORE_SEARCH_SYSTEM.txt | 5 |
11 files changed, 98 insertions, 51 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 5b63e1c..ee6c1cc 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -170,6 +170,11 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: or in the short-hand version of the command. These are typically hard-coded guesses. +The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_IGNORE_PATH` and +:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some +of the above locations to be ignored. + .. versionadded:: 3.16 Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable various search locations. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 4a381fb..e43b7bd 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -369,6 +369,11 @@ enabled. 9. Search paths specified by the ``PATHS`` option. These are typically hard-coded guesses. +The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_IGNORE_PATH` and +:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some +of the above locations to be ignored. + .. versionadded:: 3.16 Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable various search locations. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst index 4bca34b..4b2bd8a 100644 --- a/Help/variable/CMAKE_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -1,18 +1,18 @@ CMAKE_IGNORE_PATH ----------------- -:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by -the :command:`find_program`, :command:`find_library`, :command:`find_file`, -and :command:`find_path` commands. This is useful in cross-compiling -environments where some system directories contain incompatible but -possibly linkable libraries. For example, on cross-compiled cluster -environments, this allows a user to ignore directories containing -libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` -By default this is empty; it is intended to be set by the project. -Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not* -a list of prefixes. To ignore paths under prefixes (``bin``, ``include``, -``lib``, etc.), specify them explicitly. +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt -See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`, -:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst index 317c771..b81cc57 100644 --- a/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_IGNORE_PREFIX_PATH.rst @@ -3,17 +3,18 @@ CMAKE_IGNORE_PREFIX_PATH .. versionadded:: 3.23 -:ref:`Semicolon-separated list <CMake Language Lists>` of prefixes to be -*ignored* by the :command:`find_program`, :command:`find_library`, -:command:`find_file`, :command:`find_path`, and :command:`find_package` -commands. This is useful in cross-compiling environments where some -system directories contain incompatible but possibly linkable libraries. -For example, on cross-compiled cluster environments, this allows a user -to ignore directories containing libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` -By default this is empty; it is intended to be set by the project and/or -the end user. Note that ``CMAKE_IGNORE_PREFIX_PATH`` takes a list of -prefixes, *not* a list of directory names. +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_NONSYSTEM.txt -See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`, -:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_PREFIX_PATH` +- :variable:`CMAKE_LIBRARY_PATH` +- :variable:`CMAKE_INCLUDE_PATH` +- :variable:`CMAKE_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst index 6afbd33..a6d8016 100644 --- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -1,18 +1,18 @@ CMAKE_SYSTEM_IGNORE_PATH ------------------------ -:ref:`Semicolon-separated list <CMake Language Lists>` of directories to be *ignored* by -the :command:`find_program`, :command:`find_library`, :command:`find_file`, -and :command:`find_path` commands. This is useful in cross-compiling -environments where some system directories contain incompatible but -possibly linkable libraries. For example, on cross-compiled cluster -environments, this allows a user to ignore directories containing -libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PATH`` +.. |CMAKE_IGNORE_PREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PATH` -By default this contains a list of directories containing incompatible -binaries for the host system. See the :variable:`CMAKE_IGNORE_PATH` variable -that is intended to be set by the project. +.. include:: IGNORE_SEARCH_PATH.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt -See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`, -:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, -and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst index ce52f5a..48a2994 100644 --- a/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PREFIX_PATH.rst @@ -3,18 +3,18 @@ CMAKE_SYSTEM_IGNORE_PREFIX_PATH .. versionadded:: 3.23 -:ref:`Semicolon-separated list <CMake Language Lists>` of prefixes to be -*ignored* by the :command:`find_program`, :command:`find_library`, -:command:`find_file`, :command:`find_path`, and :command:`find_package` -commands. This is useful in cross-compiling environments where some -system directories contain incompatible but possibly linkable libraries. -For example, on cross-compiled cluster environments, this allows a user -to ignore directories containing libraries meant for the front-end machine. +.. |CMAKE_IGNORE_VAR| replace:: ``CMAKE_SYSTEM_IGNORE_PREFIX_PATH`` +.. |CMAKE_IGNORE_NONPREFIX_VAR| replace:: :variable:`CMAKE_SYSTEM_IGNORE_PATH` +.. |CMAKE_IGNORE_NONSYSTEM_VAR| replace:: :variable:`CMAKE_IGNORE_PREFIX_PATH` -By default this contains a list of directories containing incompatible -binaries for the host system. See the :variable:`CMAKE_IGNORE_PREFIX_PATH` -variable that is intended to be set by the project and/or the end user. +.. include:: IGNORE_SEARCH_PREFIX.txt +.. include:: IGNORE_SEARCH_LOCATIONS.txt +.. include:: IGNORE_SEARCH_SYSTEM.txt -See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`, -:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, -and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables. +See also the following variables: + +- :variable:`CMAKE_SYSTEM_IGNORE_PATH` +- :variable:`CMAKE_SYSTEM_PREFIX_PATH` +- :variable:`CMAKE_SYSTEM_LIBRARY_PATH` +- :variable:`CMAKE_SYSTEM_INCLUDE_PATH` +- :variable:`CMAKE_SYSTEM_PROGRAM_PATH` diff --git a/Help/variable/IGNORE_SEARCH_LOCATIONS.txt b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt new file mode 100644 index 0000000..a98f359 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_LOCATIONS.txt @@ -0,0 +1,4 @@ +Ignoring search locations can be useful in cross-compiling environments where +some system directories contain incompatible but possibly linkable libraries. +For example, on cross-compiled cluster environments, this allows a user to +ignore directories containing libraries meant for the front-end machine. diff --git a/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt new file mode 100644 index 0000000..a32a189 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_NONSYSTEM.txt @@ -0,0 +1,2 @@ +By default, |CMAKE_IGNORE_VAR| is empty. It is intended to be set by the +project or the end user. diff --git a/Help/variable/IGNORE_SEARCH_PATH.txt b/Help/variable/IGNORE_SEARCH_PATH.txt new file mode 100644 index 0000000..0811e02 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PATH.txt @@ -0,0 +1,19 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of directories +to be ignored by the various ``find...()`` commands. + +For :command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path`, any file found in one of the listed directories +will be ignored. The listed directories do not apply recursively, so any +subdirectories to be ignored must also be explicitly listed. +|CMAKE_IGNORE_VAR| does not affect the search *prefixes* used by these +four commands. To ignore individual paths under a search prefix +(e.g. ``bin``, ``include``, ``lib``, etc.), each path must be listed in +|CMAKE_IGNORE_VAR| as a full absolute path. |CMAKE_IGNORE_PREFIX_VAR| +provides a more appropriate way to ignore a whole search prefix. + +:command:`find_package` is also affected by |CMAKE_IGNORE_VAR|, but only +for *Config mode* searches. Any ``<Name>Config.cmake`` or +``<name>-config.cmake`` file found in one of the specified directories +will be ignored. In addition, any search *prefix* found in |CMAKE_IGNORE_VAR| +will be skipped for backward compatibility reasons, but new code should +prefer to use |CMAKE_IGNORE_PREFIX_VAR| to ignore prefixes instead. diff --git a/Help/variable/IGNORE_SEARCH_PREFIX.txt b/Help/variable/IGNORE_SEARCH_PREFIX.txt new file mode 100644 index 0000000..f5ec3dc --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_PREFIX.txt @@ -0,0 +1,6 @@ +:ref:`Semicolon-separated list <CMake Language Lists>` of search *prefixes* +to be ignored by the :command:`find_program`, :command:`find_library`, +:command:`find_file`, and :command:`find_path` commands. +The prefixes are also ignored by the *Config mode* of the +:command:`find_package` command (*Module mode* is unaffected). +To ignore specific directories instead, see |CMAKE_IGNORE_NONPREFIX_VAR|. diff --git a/Help/variable/IGNORE_SEARCH_SYSTEM.txt b/Help/variable/IGNORE_SEARCH_SYSTEM.txt new file mode 100644 index 0000000..78b285d6 --- /dev/null +++ b/Help/variable/IGNORE_SEARCH_SYSTEM.txt @@ -0,0 +1,5 @@ +|CMAKE_IGNORE_VAR| is populated by CMake as part of its platform +and toolchain setup. Its purpose is to ignore locations containing +incompatible binaries meant for the host rather than the target platform. +The project or end user should not modify this variable, they should use +|CMAKE_IGNORE_NONSYSTEM_VAR| instead. |