diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/FIND_XXX.txt | 5 | ||||
| -rw-r--r-- | Help/command/find_package.rst | 5 | ||||
| -rw-r--r-- | Help/prop_sf/LANGUAGE.rst | 4 | ||||
| -rw-r--r-- | Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst | 7 | ||||
| -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 |
13 files changed, 103 insertions, 57 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 1a79a8a..5acefad 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -363,6 +363,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/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index a9b5638..92bd227 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -7,8 +7,8 @@ A property that can be set to indicate what programming language the source file is. If it is not set the language is determined based on the file extension. Typical values are ``CXX`` (i.e. C++), ``C``, ``CSharp``, ``CUDA``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``. Setting -this property for a file means this file will be compiled. Do not set this -for headers or files that should not be compiled. +this property for a file means this file will be compiled, unless +:prop_sf:`HEADER_FILE_ONLY` is set. .. versionchanged:: 3.20 Setting this property causes the source file to be compiled as the diff --git a/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst index 78fbb02..a9af74d 100644 --- a/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst +++ b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst @@ -20,17 +20,16 @@ This property is initialized by the value of the target is created. The property may be explicitly enabled on an imported target to check its link interface. -For example, the following code: +In the following example, CMake will halt with an error at configure time +because ``miLib`` is not a target: .. code-block:: cmake set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON) - add_executable(myLib STATIC myLib.c) + add_library(myLib STATIC myLib.c) add_executable(myExe myExe.c) target_link_libraries(myExe PRIVATE miLib) # typo for myLib -will produce a CMake-time error that ``miLib`` is not a target. - In order to link toolchain-provided libraries by name while still enforcing ``LINK_LIBRARIES_ONLY_TARGETS``, use an :ref:`imported <Imported Targets>` 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. |