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/manual/cmake-language.7.rst | 42 | ||||
| -rw-r--r-- | Help/prop_sf/LANGUAGE.rst | 4 | ||||
| -rw-r--r-- | Help/prop_test/ENVIRONMENT.rst | 8 | ||||
| -rw-r--r-- | Help/prop_test/ENVIRONMENT_MODIFICATION.rst | 9 | ||||
| -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 |
15 files changed, 151 insertions, 61 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/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index b7f0861..e7d2694 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -627,3 +627,45 @@ in list elements, thus flattening nested lists: .. code-block:: cmake set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c" + +In general, lists do not support elements containing ``;`` characters. +To avoid problems, consider the following advice: + +* The interfaces of many CMake commands, variables, and properties accept + semicolon-separated lists. Avoid passing lists with elements containing + semicolons to these interfaces unless they document either direct support + or some way to escape or encode semicolons. + +* When constructing a list, substitute an otherwise-unused placeholder + for ``;`` in elements when. Then substitute ``;`` for the placeholder + when processing list elements. + For example, the following code uses ``|`` in place of ``;`` characters: + + .. code-block:: cmake + + set(mylist a "b|c") + foreach(entry IN LISTS mylist) + string(REPLACE "|" ";" entry "${entry}") + # use "${entry}" normally + endforeach() + + The :module:`ExternalProject` module's ``LIST_SEPARATOR`` option is an + example of an interface built using this approach. + +* In lists of :manual:`generator expressions <cmake-generator-expressions(7)>`, + use the :genex:`$<SEMICOLON>` generator expression. + +* In command calls, use `Quoted Argument`_ syntax whenever possible. + The called command will receive the content of the argument with + semicolons preserved. An `Unquoted Argument`_ will be split on + semicolons. + +* In :command:`function` implementations, avoid ``ARGV`` and ``ARGN``, + which do not distinguish semicolons in values from those separating values. + Instead, prefer using named positional arguments and the ``ARGC`` and + ``ARGV#`` variables. + When using :command:`cmake_parse_arguments` to parse arguments, prefer + its ``PARSE_ARGV`` signature, which uses the ``ARGV#`` variables. + + Note that this approach does not apply to :command:`macro` implementations + because they reference arguments using placeholders, not real variables. 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_test/ENVIRONMENT.rst b/Help/prop_test/ENVIRONMENT.rst index 43bcdbe..07b96bb 100644 --- a/Help/prop_test/ENVIRONMENT.rst +++ b/Help/prop_test/ENVIRONMENT.rst @@ -3,7 +3,7 @@ ENVIRONMENT Specify environment variables that should be defined for running a test. -If set to a list of environment variables and values of the form -``MYVAR=value`` those environment variables will be defined while running -the test. The environment changes from this property do not affect other -tests. +Set to a :ref:`semicolon-separated list <CMake Language Lists>` list +of environment variables and values of the form ``MYVAR=value``. +Those environment variables will be defined while running the test. +The environment changes from this property do not affect other tests. diff --git a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst index 99ff512..ad3e190 100644 --- a/Help/prop_test/ENVIRONMENT_MODIFICATION.rst +++ b/Help/prop_test/ENVIRONMENT_MODIFICATION.rst @@ -7,10 +7,11 @@ Specify environment variables that should be modified for running a test. Note that the operations performed by this property are performed after the :prop_test:`ENVIRONMENT` property is already applied. -If set to a list of environment variables and values of the form -``MYVAR=OP:VALUE``, where ``MYVAR`` is the case-sensitive name of an -environment variable to be modified. Entries are considered in the -order specified in the property's value. The ``OP`` may be one of: +Set to a :ref:`semicolon-separated list <CMake Language Lists>` of +environment variables and values of the form ``MYVAR=OP:VALUE``, +where ``MYVAR`` is the case-sensitive name of an environment variable +to be modified. Entries are considered in the order specified in the +property's value. The ``OP`` may be one of: - ``reset``: Reset to the unmodified value, ignoring all modifications to ``MYVAR`` prior to this entry. Note that this will reset the variable to 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. |