diff options
Diffstat (limited to 'Help')
37 files changed, 1101 insertions, 18 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 9279748..231f9da 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -102,13 +102,22 @@ The options are: a target later in the command line (i.e. as a command argument rather than as the command to execute). - Whenever a target is used as a command to execute or is mentioned in a - generator expression as a command argument, a target-level dependency - will be added automatically so that the mentioned target will be built - before any target using this custom command. However this does NOT add - a file-level dependency that would cause the custom command to re-run - whenever the executable is recompiled. List target names with - the ``DEPENDS`` option to add such file-level dependencies. + Whenever one of the following target based generator expressions are used as + a command to execute or is mentioned in a command argument, a target-level + dependency will be added automatically so that the mentioned target will be + built before any target using this custom command + (see policy :policy:`CMP0112`). + + * ``TARGET_FILE`` + * ``TARGET_LINKER_FILE`` + * ``TARGET_SONAME_FILE`` + * ``TARGET_PDB_FILE`` + + This target-level dependency does NOT add a file-level dependency that would + cause the custom command to re-run whenever the executable is recompiled. + List target names with the ``DEPENDS`` option to add such file-level + dependencies. + ``COMMENT`` Display the given message before the commands are executed at diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 56ab414..2eb0c88 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -81,10 +81,15 @@ The options are: a target later in the command line (i.e. as a command argument rather than as the command to execute). - Whenever a target is used as a command to execute or is mentioned in a - generator expression as a command argument, a target-level dependency - will be added automatically so that the mentioned target will be built - before this custom target. + Whenever one of the following target based generator expressions are used as + a command to execute or is mentioned in a command argument, a target-level + dependency will be added automatically so that the mentioned target will be + built before this custom target (see policy :policy:`CMP0112`). + + * ``TARGET_FILE`` + * ``TARGET_LINKER_FILE`` + * ``TARGET_SONAME_FILE`` + * ``TARGET_PDB_FILE`` The command and arguments are optional and if not specified an empty target will be created. diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index f3df631..b7dfabc 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -14,7 +14,7 @@ Normal Libraries add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] - [source1] [source2 ...]) + [<source>...]) Adds a library target called ``<name>`` to be built from the source files listed in the command invocation. (The source files can be omitted here @@ -69,7 +69,7 @@ Object Libraries .. code-block:: cmake - add_library(<name> OBJECT <src>...) + add_library(<name> OBJECT [<source>...]) Creates an :ref:`Object Library <Object Libraries>`. An object library compiles source files but does not archive or link their object files into a diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst new file mode 100644 index 0000000..9248eae --- /dev/null +++ b/Help/command/cmake_path.rst @@ -0,0 +1,641 @@ +cmake_path +---------- + +.. versionadded:: 3.19 + +Filesystem path manipulation command. + +This command is dedicated to the manipulation of objects of type path which +represent paths on a filesystem. Only syntactic aspects of paths are handled: +the pathname may represent a non-existing path or even one that is not allowed +to exist on the current file system or OS. + +For operations involving the filesystem, have a look at the :command:`file` +command. + +The path name has the following syntax: + +1. ``root-name`` (optional): identifies the root on a filesystem with multiple + roots (such as ``"C:"`` or ``"//myserver"``). + +2. ``root-directory`` (optional): a directory separator that, if present, marks + this path as absolute. If it is missing (and the first element other than + the root name is a file name), then the path is relative. + +Zero or more of the following: + +3. ``file-name``: sequence of characters that aren't directory separators. This + name may identify a file, a hard link, a symbolic link, or a directory. Two + special file-names are recognized: + + * ``dot``: the file name consisting of a single dot character ``.`` is a + directory name that refers to the current directory. + + * ``dot-dot``: the file name consisting of two dot characters ``..`` is a + directory name that refers to the parent directory. + +4. ``directory-separator``: the forward slash character ``/``. If this + character is repeated, it is treated as a single directory separator: + ``/usr///////lib`` is the same as ``/usr/lib``. + +.. _EXTENSION_DEF: + +A ``file-name`` can have an extension. By default, the extension is defined as +the sub-string beginning at the leftmost period (including the period) and +until the end of the pathname. When the option ``LAST_ONLY`` is specified, the +extension is the sub-string beginning at the rightmost period. + +.. note:: + + ``cmake_path`` command handles paths in the format of the build system, not + the target system. So this is not generally applicable to the target system + in cross-compiling environment. + +For all commands, ``<path>`` placeholder expect a variable name. An error will +be raised if the variable does not exist, except for `APPEND`_ and +`CMAKE_PATH`_ sub-commands. ``<input>`` placeholder expect a string literal. +``[<input>...]`` placeholder expect zero or more arguments. ``<output>`` +placeholder expect a variable name. + +.. note:: + + ``cmake_path`` command does not support list of paths. The ``<path>`` + placeholder must store only one path name. + +To initialize a path variable, three possibilities can be used: + +1. :command:`set` command. +2. :ref:`cmake_path(APPEND) <APPEND>` command. Can be used to build a path from + already available path fragments. +3. :ref:`cmake_path(CMAKE_PATH) <CMAKE_PATH>` command. Mainly used to build a + path variable from a native path. + + .. code-block:: cmake + + # To build the path "${CMAKE_CURRENT_SOURCE_DIR}/data" + + set (path1 "${CMAKE_CURRENT_SOURCE_DIR}/data") + + cmake_path(APPEND path2 "${CMAKE_CURRENT_SOURCE_DIR}" "data") + + cmake_path(CMAKE_PATH path3 "${CMAKE_CURRENT_SOURCE_DIR}/data") + +`Modification`_ and `Generation`_ sub-commands store the result in-place or in +the variable specified by ``OUTPUT_VARIABLE`` option. All other sub-commands, +except `CMAKE_PATH`_, store the result in the required ``<output>`` variable. + +Sub-commands supporting ``NORMALIZE`` option will :ref:`normalize <NORMAL_PATH>` +the path. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Decomposition`_ + cmake_path(`GET`_ <path> :ref:`ROOT_NAME <GET_ROOT_NAME>` <output>) + cmake_path(`GET`_ <path> :ref:`ROOT_DIRECTORY <GET_ROOT_DIRECTORY>` <output>) + cmake_path(`GET`_ <path> :ref:`ROOT_PATH <GET_ROOT_PATH>` <output>) + cmake_path(`GET`_ <path> :ref:`FILENAME <GET_FILENAME>` <output>) + cmake_path(`GET`_ <path> :ref:`EXTENSION <GET_EXTENSION>` [LAST_ONLY] <output>) + cmake_path(`GET`_ <path> :ref:`STEM <GET_STEM>` [LAST_ONLY] <output>) + cmake_path(`GET`_ <path> :ref:`RELATIVE_PATH <GET_RELATIVE_PATH>` <output>) + cmake_path(`GET`_ <path> :ref:`PARENT_PATH <GET_PARENT_PATH>` <output>) + + `Modification`_ + cmake_path(`APPEND`_ <path> [<input>...] [OUTPUT_VARIABLE <output>]) + cmake_path(`CONCAT`_ <path> [<input>...] [OUTPUT_VARIABLE <output>]) + cmake_path(`REMOVE_FILENAME`_ <path> [OUTPUT_VARIABLE <output>]) + cmake_path(`REPLACE_FILENAME`_ <path> <input> [OUTPUT_VARIABLE <output>]) + cmake_path(`REMOVE_EXTENSION`_ <path> [LAST_ONLY] + [OUTPUT_VARIABLE <output>]) + cmake_path(`REPLACE_EXTENSION`_ <path> [LAST_ONLY] <input> + [OUTPUT_VARIABLE <output>]) + + `Generation`_ + cmake_path(`NORMAL_PATH`_ <path> [OUTPUT_VARIABLE <output>]) + cmake_path(`RELATIVE_PATH`_ <path> [BASE_DIRECTORY <path>] + [OUTPUT_VARIABLE <output>]) + cmake_path(`PROXIMATE_PATH`_ <path> [BASE_DIRECTORY <path>] + [OUTPUT_VARIABLE <output>]) + cmake_path(`ABSOLUTE_PATH`_ <path> [BASE_DIRECTORY <path>] [NORMALIZE] + [OUTPUT_VARIABLE <output>]) + + `Conversion`_ + cmake_path(`CMAKE_PATH`_ <path> [NORMALIZE] <input>) + cmake_path(`NATIVE_PATH`_ <path> [NORMALIZE] <output>) + cmake_path(`CONVERT`_ <input> `TO_CMAKE_PATH_LIST`_ <output>) + cmake_path(`CONVERT`_ <input> `TO_NATIVE_PATH_LIST`_ <output>) + + `Comparison`_ + cmake_path(`COMPARE`_ <path> <OP> <input> <output>) + + `Query`_ + cmake_path(`HAS_ROOT_NAME`_ <path> <output>) + cmake_path(`HAS_ROOT_DIRECTORY`_ <path> <output>) + cmake_path(`HAS_ROOT_PATH`_ <path> <output>) + cmake_path(`HAS_FILENAME`_ <path> <output>) + cmake_path(`HAS_EXTENSION`_ <path> <output>) + cmake_path(`HAS_STEM`_ <path> <output>) + cmake_path(`HAS_RELATIVE_PATH`_ <path> <output>) + cmake_path(`HAS_PARENT_PATH`_ <path> <output>) + cmake_path(`IS_ABSOLUTE`_ <path> <output>) + cmake_path(`IS_RELATIVE`_ <path> <output>) + cmake_path(`IS_PREFIX`_ <path> <input> [NORMALIZE] <output>) + + `Hashing`_ + cmake_path(`HASH`_ <path> [NORMALIZE] <output>) + +Decomposition +^^^^^^^^^^^^^ + +.. _GET: +.. _GET_ROOT_NAME: + +.. code-block:: cmake + + cmake_path(GET <path> ROOT_NAME <output>) + +Returns the root name of the path. If the path does not include a root name, +returns an empty path. + +.. _GET_ROOT_DIRECTORY: + +.. code-block:: cmake + + cmake_path(GET <path> ROOT_DIRECTORY <output>) + +Returns the root directory of the path. If the path does not include a root +directory, returns an empty path. + +.. _GET_ROOT_PATH: + +.. code-block:: cmake + + cmake_path(GET <path> ROOT_PATH <output>) + +Returns the root path of the path. If the path does not include a root path, +returns an empty path. + +Effectively, returns the following: ``root-name / root-directory``. + +.. _GET_FILENAME: + +.. code-block:: cmake + + cmake_path(GET <path> FILENAME <output>) + +Returns the filename component of the path. If the path ends with a +``directory-separator``, there is no filename, so returns an empty path. + +.. _GET_EXTENSION: + +.. code-block:: cmake + + cmake_path(GET <path> EXTENSION [LAST_ONLY] <output>) + +Returns the :ref:`extension <EXTENSION_DEF>` of the filename component. + +If the ``FILENAME`` component of the path contains a period (``.``), and is not +one of the special filesystem elements ``dot`` or ``dot-dot``, then the +:ref:`extension <EXTENSION_DEF>` is returned. + + .. code-block:: cmake + + set (path "name.ext1.ext2") + cmake_path (GET path EXTENSION result) + cmake_path (GET path EXTENSION LAST_ONLY result) + +First extension extraction will return ``.ex1.ext2``, while the second one will +return only ``.ext2``. + +The following exceptions apply: + + * If the first character in the filename is a period, that period is ignored + (a filename like ``".profile"`` is not treated as an extension). + + * If the pathname is either ``.`` or ``..``, or if ``FILENAME`` component + does not contain the ``.`` character, then an empty path is returned. + +.. _GET_STEM: + +.. code-block:: cmake + + cmake_path(GET <path> STEM [LAST_ONLY] <output>) + +Returns the ``FILENAME`` component of the path stripped of its +:ref:`extension <EXTENSION_DEF>`. + + .. code-block:: cmake + + set (path "name.ext1.ext2") + cmake_path (GET path STEM result) + cmake_path (GET path STEM LAST_ONLY result) + +First stem extraction will return only ``name``, while the second one will +return ``name.ext1``. + +The following exceptions apply: + + * If the first character in the filename is a period, that period is ignored + (a filename like ``".profile"`` is not treated as an extension). + + * If the filename is one of the special filesystem components ``dot`` or + ``dot-dot``, or if it has no periods, the function returns the entire + ``FILENAME`` component. + +.. _GET_RELATIVE_PATH: + +.. code-block:: cmake + + cmake_path(GET <path> RELATIVE_PATH <output>) + +Returns path relative to ``root-path``, that is, a pathname composed of +every component of ``<path>`` after ``root-path``. If ``<path>`` is an empty +path, returns an empty path. + +.. _GET_PARENT_PATH: + +.. code-block:: cmake + + cmake_path(GET <path> PARENT_PATH <output>) + +Returns the path to the parent directory. + +If `HAS_RELATIVE_PATH`_ sub-command returns false, the result is a copy of +``<path>``. Otherwise, the result is ``<path>`` with one fewer element. + +Modification +^^^^^^^^^^^^ + +.. _APPEND: + +.. code-block:: cmake + + cmake_path(APPEND <path> [<input>...] [OUTPUT_VARIABLE <output>]) + +Append all the ``<input>`` arguments to the ``<path>`` using ``/`` as +``directory-separator``. + +For each ``<input>`` argument, the following algorithm (pseudo-code) applies: + + .. code-block:: cmake + + IF (<input>.is_absolute() OR + (<input>.has_root_name() AND + NOT <input>.root_name() STREQUAL <path>.root_name())) + replaces <path> with <input> + RETURN() + ENDIF() + + IF (<input>.has_root_directory()) + remove any root-directory and the entire relative path from <path> + ELSEIF (<path>.has_filename() OR + (NOT <path>.has_root_directory() OR <path>.is_absolute())) + appends directory-separator to <path> + ENDIF() + + appends <input> omitting any root-name to <path> + +.. _CONCAT: + +.. code-block:: cmake + + cmake_path(CONCAT <path> [<input>...] [OUTPUT_VARIABLE <output>]) + +Concatenates all the ``<input>`` arguments to the ``<path>`` without +``directory-separator``. + +.. _REMOVE_FILENAME: + +.. code-block:: cmake + + cmake_path(REMOVE_FILENAME <path> [OUTPUT_VARIABLE <output>]) + +Removes a single filename component (as returned by +:ref:`GET ... FILENAME <GET_FILENAME>`) from ``<path>``. + +After this function returns, if change is done in-place, `HAS_FILENAME`_ +returns false for ``<path>``. + +.. _REPLACE_FILENAME: + +.. code-block:: cmake + + cmake_path(REPLACE_FILENAME <path> <input> [OUTPUT_VARIABLE <output>]) + +Replaces a single filename component from ``<path>`` with ``<input>``. + +Equivalent to the following: + + .. code-block:: cmake + + cmake_path(REMOVE_FILENAME path) + cmake_path(APPEND path "replacement"); + +If ``<path>`` has no filename component (`HAS_FILENAME`_ returns false), the +path is unchanged. + +.. _REMOVE_EXTENSION: + +.. code-block:: cmake + + cmake_path(REMOVE_EXTENSION <path> [LAST_ONLY] [OUTPUT_VARIABLE <output>]) + +Removes the :ref:`extension <EXTENSION_DEF>`, if any, from ``<path>``. + +.. _REPLACE_EXTENSION: + +.. code-block:: cmake + + cmake_path(REPLACE_EXTENSION <path> [LAST_ONLY] <input> + [OUTPUT_VARIABLE <output>]) + +Replaces the :ref:`extension <EXTENSION_DEF>` with ``<input>``. + +First, if ``<path>`` has an :ref:`extension <EXTENSION_DEF>` (`HAS_EXTENSION`_ +is true), it is removed. Then, a ``dot`` character is appended to ``<path>``, +if ``<input>`` is not empty or does not begin with a ``dot`` character. + +Then ``<input>`` is appended as if `CONCAT`_ was used. + +Generation +^^^^^^^^^^ + +.. _NORMAL_PATH: + +.. code-block:: cmake + + cmake_path(NORMAL_PATH <path> [OUTPUT_VARIABLE <output>]) + +Normalize ``<path>``. + +A path can be normalized by following this algorithm: + + 1. If the path is empty, stop (normal form of an empty path is an empty + path). + 2. Replace each ``directory-separator`` (which may consist of multiple + separators) with a single ``/``. + 3. Replace each ``directory-separator`` character in the ``root-name`` with + ``/``. + 4. Remove each ``dot`` and any immediately following ``directory-separator``. + 5. Remove each non-dot-dot filename immediately followed by a + ``directory-separator`` and a ``dot-dot``, along with any immediately + following ``directory-separator``. + 6. If there is ``root-directory``, remove all ``dot-dots`` and any + ``directory-separators`` immediately following them. + 7. If the last filename is ``dot-dot``, remove any trailing + ``directory-separator``. + 8. If the path is empty, add a ``dot`` (normal form of ``./`` is ``.``). + +.. _cmake_path-RELATIVE_PATH: +.. _RELATIVE_PATH: + +.. code-block:: cmake + + cmake_path(RELATIVE_PATH <path> [BASE_DIRECTORY <path>] + [OUTPUT_VARIABLE <output>]) + +Returns ``<path>`` made relative to ``BASE_DIRECTORY`` argument. If +``BASE_DIRECTORY`` is not specified, the default base directory will be +:variable:`CMAKE_CURRENT_SOURCE_DIR`. + +For reference, the algorithm used to compute the relative path is described +`here <https://en.cppreference.com/w/cpp/filesystem/path/lexically_normal>`_. + +.. _PROXIMATE_PATH: + +.. code-block:: cmake + + cmake_path(PROXIMATE_PATH <path> [BASE_DIRECTORY <path>] + [OUTPUT_VARIABLE <output>]) + +If the value of `RELATIVE_PATH`_ is not an empty path, return +it. Otherwise return ``<path>``. + +If ``BASE_DIRECTORY`` is not specified, the default base directory will be +:variable:`CMAKE_CURRENT_SOURCE_DIR`. + +.. _ABSOLUTE_PATH: + +.. code-block:: cmake + + cmake_path(ABSOLUTE_PATH <path> [BASE_DIRECTORY <path>] [NORMALIZE] + [OUTPUT_VARIABLE <output>]) + +If ``<path>`` is a relative path, it is evaluated relative to the given base +directory specified by ``BASE_DIRECTORY`` option. If no base directory is +provided, the default base directory will be +:variable:`CMAKE_CURRENT_SOURCE_DIR`. + +When ``NORMALIZE`` option is specified, the path is :ref:`normalized +<NORMAL_PATH>` after the path computation. + +Because ``cmake_path`` does not access to the filesystem, symbolic links are +not resolved. To compute a real path, use :command:`get_filename_component` +command with ``REALPATH`` sub-command. + +Conversion +^^^^^^^^^^ + +.. _cmake_path-CMAKE_PATH: +.. _CMAKE_PATH: + +.. code-block:: cmake + + cmake_path(CMAKE_PATH <path> [NORMALIZE] <input>) + +Converts a native ``<input>`` path into cmake-style path with forward-slashes +(``/``). On Windows, the long filename marker is taken into account. + +When ``NORMALIZE`` option is specified, the path is :ref:`normalized +<NORMAL_PATH>` before the conversion. + +.. _cmake_path-NATIVE_PATH: +.. _NATIVE_PATH: + +.. code-block:: cmake + + cmake_path(NATIVE_PATH <path> [NORMALIZE] <output>) + +Converts a cmake-style ``<path>`` into a native +path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). + +When ``NORMALIZE`` option is specified, the path is :ref:`normalized +<NORMAL_PATH>` before the conversion. + +.. _CONVERT: +.. _cmake_path-TO_CMAKE_PATH_LIST: +.. _TO_CMAKE_PATH_LIST: + +.. code-block:: cmake + + cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <output> [NORMALIZE]) + +Converts a native ``<input>`` path into cmake-style path with forward-slashes +(``/``). On Windows, the long filename marker is taken into account. The input can +be a single path or a system search path like ``$ENV{PATH}``. A search path +will be converted to a cmake-style list separated by ``;`` characters. The +result of the conversion is stored in the ``<output>`` variable. + +When ``NORMALIZE`` option is specified, the path is :ref:`normalized +<NORMAL_PATH>` before the conversion. + +.. _cmake_path-TO_NATIVE_PATH_LIST: +.. _TO_NATIVE_PATH_LIST: + +.. code-block:: cmake + + cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <output> [NORMALIZE]) + +Converts a cmake-style ``<input>`` path into a native path with +platform-specific slashes (``\`` on Windows and ``/`` elsewhere). The input can +be a single path or a cmake-style list. A list will be converted into a native +search path. The result of the conversion is stored in the ``<output>`` +variable. + +When ``NORMALIZE`` option is specified, the path is :ref:`normalized +<NORMAL_PATH>` before the conversion. + +Comparison +^^^^^^^^^^ + +.. _COMPARE: + +.. code-block:: cmake + + cmake_path(COMPARE <path> EQUAL <input> <output>) + cmake_path(COMPARE <path> NOT_EQUAL <input> <output>) + +Compares the lexical representations of the path and another path. + +For testing equality, the following algorithm (pseudo-code) apply: + + .. code-block:: cmake + + IF (NOT <path>.root_name() STREQUAL <input>.root_name()) + returns FALSE + ELSEIF (<path>.has_root_directory() XOR <input>.has_root_directory()) + returns FALSE + ENDIF() + + returns TRUE or FALSE if the relative portion of <path> is + lexicographically equal or not to the relative portion of <input>. + Comparison is performed path component-wise + +Query +^^^^^ + +.. _HAS_ROOT_NAME: + +.. code-block:: cmake + + cmake_path(HAS_ROOT_NAME <path> <output>) + +Checks if ``<path>`` has ``root-name``. + +.. _HAS_ROOT_DIRECTORY: + +.. code-block:: cmake + + cmake_path(HAS_ROOT_DIRECTORY <path> <output>) + +Checks if ``<path>`` has ``root-directory``. + +.. _HAS_ROOT_PATH: + +.. code-block:: cmake + + cmake_path(HAS_ROOT_PATH <path> <output>) + +Checks if ``<path>`` has root path. + +Effectively, checks the following: ``root-name / root-directory``. + +.. _HAS_FILENAME: + +.. code-block:: cmake + + cmake_path(HAS_FILENAME <path> <output>) + +Checks if ``<path>`` has ``file-name``. + +.. _HAS_EXTENSION: + +.. code-block:: cmake + + cmake_path(HAS_EXTENSION <path> <output>) + +Checks if ``<path>`` has an :ref:`<extension <EXTENSION_DEF>`. If the first +character in the filename is a period, it is not treated as an extension (for +example ".profile"). + +.. _HAS_STEM: + +.. code-block:: cmake + + cmake_path(HAS_STEM <path> <output>) + +Checks if ``<path>`` has stem. + +.. _HAS_RELATIVE_PATH: + +.. code-block:: cmake + + cmake_path(HAS_RELATIVE_PATH <path> <output>) + +Checks if ``<path>`` has relative path. + +.. _HAS_PARENT_PATH: + +.. code-block:: cmake + + cmake_path(HAS_PARENT_PATH <path> <output>) + +Checks if ``<path>`` has parent path. + +.. _IS_ABSOLUTE: + +.. code-block:: cmake + + cmake_path(IS_ABSOLUTE <path> <output>) + +Checks if ``<path>`` is absolute. + +An absolute path is a path that unambiguously identifies the location of a file +without reference to an additional starting location. + +.. _IS_RELATIVE: + +.. code-block:: cmake + + cmake_path(IS_RELATIVE <path> <output>) + +Checks if path is relative. + +.. _IS_PREFIX: + +.. code-block:: cmake + + cmake_path(IS_PREFIX <path> <input> [NORMALIZE] <output>) + +Checks if ``<path>`` is the prefix of ``<input>``. + +When ``NORMALIZE`` option is specified, the paths are :ref:`normalized +<NORMAL_PATH>` before the check. + +Hashing +^^^^^^^ + +.. _HASH: + +.. code-block:: cmake + + cmake_path(HASH <path> [NORMALIZE] <output>) + +Compute hash value of ``<path>`` such that if for two paths (``p1`` and ``p2``) +are equal (:ref:`COMPARE ... EQUAL <COMPARE>`) then hash value of p1 is equal +to hash value of p2. + +When ``NORMALIZE`` option is specified, the paths are :ref:`normalized +<NORMAL_PATH>` before the check. diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index fdc44f2..e8640ea 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -9,7 +9,8 @@ Enable a language (CXX/C/OBJC/OBJCXX/Fortran/etc) Enables support for the named language in CMake. This is the same as the :command:`project` command but does not create any of the extra variables that are created by the project command. Example languages -are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, and ``ASM``. +are ``CXX``, ``C``, ``CUDA``, ``OBJC``, ``OBJCXX``, ``Fortran``, +``ISPC``, and ``ASM``. If enabling ``ASM``, enable it last so that CMake can check whether compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/file.rst b/Help/command/file.rst index 953172b..d77ad2d 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,6 +3,21 @@ file File manipulation command. +This command is dedicated to file and path manipulation requiring access to the +filesystem. + +For other path manipulation, handling only syntactic aspects, have a look at +:command:`cmake_path` command. + +.. note:: + + The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has + been superseded, respectively, by sub-commands + :ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`, + :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and + :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of + :command:`cmake_path` command. + Synopsis ^^^^^^^^ @@ -30,8 +45,11 @@ Synopsis file(`SIZE`_ <filename> <out-var>) file(`READ_SYMLINK`_ <linkname> <out-var>) file(`CREATE_LINK`_ <original> <linkname> [...]) + file(`CHMOD`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) + file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...]) `Path Conversion`_ + file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>]) file(`RELATIVE_PATH`_ <out-var> <directory> <file>) file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>) @@ -741,9 +759,67 @@ creating the link fails. It can be useful for handling situations such as ``<original>`` and ``<linkname>`` being on different drives or mount points, which would make them unable to support a hard link. +.. _CHMOD: + +.. code-block:: cmake + + file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...] + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...]) + +Set the permissions for the ``<files>...`` and ``<directories>...`` specified. +Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, +``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, +``WORLD_WRITE``, ``WORLD_EXECUTE``. + +Valid combination of keywords are: + +``PERMISSIONS`` + all items are changed + +``FILE_PERMISSIONS`` + only files are changed + +``DIRECTORY_PERMISSIONS`` + only directories are changed + +``PERMISSIONS`` and ``FILE_PERMISSIONS`` + ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files + +``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` + ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories + +``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` + use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for + directories + + +.. _CHMOD_RECURSE: + +.. code-block:: cmake + + file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... + FILE_PERMISSIONS <permissions>... DIRECTORY_PERMISSIONS <permissions>...) + +Same as `CHMOD`_, but change the permissions of files and directories present in +the ``<directories>..`` recursively. + Path Conversion ^^^^^^^^^^^^^^^ +.. _REAL_PATH: + +.. code-block:: cmake + + file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>]) + +Compute the absolute path to an existing file or directory with symlinks +resolved. + +If the provided ``<path>`` is a relative path, it is evaluated relative to the +given base directory ``<dir>``. If no base directory is provided, the default +base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. + .. _RELATIVE_PATH: .. code-block:: cmake diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 9bbf877..e8c68b2 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -44,6 +44,12 @@ Paths are returned with forward slashes and have no trailing slashes. If the optional ``CACHE`` argument is specified, the result variable is added to the cache. +.. note:: + + All previous sub-commands has been superseded by + :command:`cmake_path` command, except ``REALPATH`` now offered by + :ref:`file(REAL_PATH) <REAL_PATH>` command. + .. code-block:: cmake get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE]) diff --git a/Help/command/project.rst b/Help/command/project.rst index b6093d3..c325050 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -88,7 +88,7 @@ The options are: Selects which programming languages are needed to build the project. Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, - ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, and ``ASM``. + ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``ISPC``, and ``ASM``. By default ``C`` and ``CXX`` are enabled if no language options are given. Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages, to skip enabling any languages. diff --git a/Help/dev/source.rst b/Help/dev/source.rst index d93e55c..9be4451 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -158,6 +158,9 @@ These are: * ``cm::is_unique_ptr``: Checks if a type is a ``std::unique_ptr`` type. +CMake assumes the compiler supports ``#pragma once``. Use this for all +hand-written header files. + Dynamic Memory Management ========================= diff --git a/Help/envvar/ISPC.rst b/Help/envvar/ISPC.rst new file mode 100644 index 0000000..bcd6260 --- /dev/null +++ b/Help/envvar/ISPC.rst @@ -0,0 +1,13 @@ +ISPC +------- + +.. versionadded:: 3.19 + +.. include:: ENV_VAR.txt + +Preferred executable for compiling ``ISPC`` language files. Will only be used by +CMake on the first configuration to determine ``ISPC`` compiler, after which the +value for ``ISPC`` is stored in the cache as +:variable:`CMAKE_ISPC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_ISPC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/ISPCFLAGS.rst b/Help/envvar/ISPCFLAGS.rst new file mode 100644 index 0000000..21df037 --- /dev/null +++ b/Help/envvar/ISPCFLAGS.rst @@ -0,0 +1,15 @@ +ISPCFLAGS +--------- + +.. versionadded:: 3.19 + +.. include:: ENV_VAR.txt + +Default compilation flags to be used when compiling ``ISPC`` files. Will only be +used by CMake on the first configuration to determine ``ISPC`` default +compilation flags, after which the value for ``ISPCFLAGS`` is stored in the +cache as :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_ISPC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. + +See also :variable:`CMAKE_ISPC_FLAGS_INIT <CMAKE_<LANG>_FLAGS_INIT>`. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 0aa4f75..036fa8f 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -20,6 +20,7 @@ These commands are always available. /command/cmake_language /command/cmake_minimum_required /command/cmake_parse_arguments + /command/cmake_path /command/cmake_policy /command/configure_file /command/continue diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index ce1e360..13e0d39 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -63,6 +63,8 @@ Environment Variables for Languages /envvar/CXXFLAGS /envvar/FC /envvar/FFLAGS + /envvar/ISPC + /envvar/ISPCFLAGS /envvar/OBJC /envvar/OBJCXX /envvar/RC diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c7f6b27..ff9d1bf 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -146,6 +146,11 @@ Variable Queries ``1`` if the CMake's compiler id of the Fortran compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<ISPC_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the ISPC compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION:version>`` ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -164,6 +169,9 @@ Variable Queries ``$<Fortran_COMPILER_VERSION:version>`` ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<ISPC_COMPILER_VERSION:version>`` + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<TARGET_POLICY:policy>`` ``1`` if the ``policy`` was NEW when the 'head' target was created, else ``0``. If the ``policy`` was not set, the warning message for the policy @@ -543,6 +551,9 @@ Variable Queries ``$<Fortran_COMPILER_ID>`` The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<ISPC_COMPILER_ID>`` + The CMake's compiler id of the ISPC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION>`` The version of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -561,6 +572,9 @@ Variable Queries ``$<Fortran_COMPILER_VERSION>`` The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<ISPC_COMPILER_VERSION>`` + The version of the ISPC compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<COMPILE_LANGUAGE>`` The compile language of source files when evaluating compile options. See :ref:`the related boolean expression @@ -596,6 +610,9 @@ which is just the string ``tgt``. ``$<TARGET_NAME_IF_EXISTS:tgt>`` The target name ``tgt`` if the target exists, an empty string otherwise. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_FILE:tgt>`` Full path to the ``tgt`` binary file. ``$<TARGET_FILE_BASE_NAME:tgt>`` @@ -633,6 +650,9 @@ which is just the string ``tgt``. The ``tgt`` filename. ``$<TARGET_FILE_DIR:tgt>`` Directory of the ``tgt`` binary file. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_LINKER_FILE:tgt>`` File used when linking to the ``tgt`` target. This will usually be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), @@ -674,14 +694,26 @@ which is just the string ``tgt``. expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` Name of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_LINKER_FILE_DIR:tgt>`` Directory of file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_SONAME_FILE:tgt>`` File with soname (``.so.3``) where ``tgt`` is the name of a target. ``$<TARGET_SONAME_FILE_NAME:tgt>`` Name of file with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_SONAME_FILE_DIR:tgt>`` Directory of with soname (``.so.3``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PDB_FILE:tgt>`` Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -707,17 +739,29 @@ which is just the string ``tgt``. expression is evaluated on. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PDB_FILE_DIR:tgt>`` Directory of the linker generated program database file (.pdb). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_BUNDLE_DIR:tgt>`` Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle structure. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). ``$<TARGET_PROPERTY:tgt,prop>`` Value of the property ``prop`` on the target ``tgt``. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index ce8969b..3821dc3 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,8 @@ Policies Introduced by CMake 3.19 .. toctree:: :maxdepth: 1 + CMP0113: Makefile generators do not repeat custom commands from target dependencies. </policy/CMP0113> + CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112> CMP0111: An imported target with a missing location fails during generation. </policy/CMP0111> CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110> CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109> diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index b2e3995..cb9579e 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -258,6 +258,8 @@ Properties on Targets /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_tgt/INTERPROCEDURAL_OPTIMIZATION /prop_tgt/IOS_INSTALL_COMBINED + /prop_tgt/ISPC_HEADER_DIRECTORY + /prop_tgt/ISPC_INSTRUCTION_SETS /prop_tgt/JOB_POOL_COMPILE /prop_tgt/JOB_POOL_LINK /prop_tgt/JOB_POOL_PRECOMPILE_HEADER @@ -396,6 +398,7 @@ Properties on Targets /prop_tgt/XCODE_ATTRIBUTE_an-attribute /prop_tgt/XCODE_EXPLICIT_FILE_TYPE /prop_tgt/XCODE_GENERATE_SCHEME + /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE /prop_tgt/XCODE_PRODUCT_TYPE /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index baf4a55..d50005c 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -247,6 +247,7 @@ Variables that Change Behavior /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY + /variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING @@ -511,6 +512,8 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG + /variable/CMAKE_ISPC_HEADER_DIRECTORY + /variable/CMAKE_ISPC_INSTRUCTION_SETS /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX diff --git a/Help/policy/CMP0112.rst b/Help/policy/CMP0112.rst new file mode 100644 index 0000000..3eab6d2 --- /dev/null +++ b/Help/policy/CMP0112.rst @@ -0,0 +1,39 @@ +CMP0112 +------- + +.. versionadded:: 3.19 + +Target file component generator expressions do not add target dependencies. + +The following target-based generator expressions that query for directory or +file name components no longer add a dependency on the evaluated target. + + - ``TARGET_FILE_DIR`` + - ``TARGET_LINKER_FILE_BASE_NAME`` + - ``TARGET_LINKER_FILE_NAME`` + - ``TARGET_LINKER_FILE_DIR`` + - ``TARGET_SONAME_FILE_NAME`` + - ``TARGET_SONAME_FILE_DIR`` + - ``TARGET_PDB_FILE_NAME`` + - ``TARGET_PDB_FILE_DIR`` + - ``TARGET_BUNDLE_DIR`` + - ``TARGET_BUNDLE_CONTENT_DIR`` + + +In CMake 3.18 and lower a dependency on the evaluated target of the above +generator expressions would be always added. CMake 3.19 and above prefer +to not add this dependency. This policy provides compatibility for projects +that have not been updated to expect the new behavior. + +The ``OLD`` behavior for this policy is to add a dependency on the evaluated +target for the the above generator expressions. The ``NEW`` behavior of +this policy is to not add a dependency on the evaluated target for the the +above generator expressions. + +This policy was introduced in CMake version 3.19. Unlike many policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses ``OLD`` behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0112 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0113.rst b/Help/policy/CMP0113.rst new file mode 100644 index 0000000..6f56902 --- /dev/null +++ b/Help/policy/CMP0113.rst @@ -0,0 +1,43 @@ +CMP0113 +------- + +.. versionadded:: 3.19 + +:ref:`Makefile Generators` do not repeat custom commands from target +dependencies. + +Consider a chain of custom commands split across two dependent targets: + +.. code-block:: cmake + + add_custom_command(OUTPUT output-not-created + COMMAND ... DEPENDS ...) + set_property(SOURCE output-not-created PROPERTY SYMBOLIC 1) + add_custom_command(OUTPUT output-created + COMMAND ... DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/output-not-created) + add_custom_target(first DEPENDS output-not-created) + add_custom_target(second DEPENDS output-created) + add_dependencies(second first) + +In CMake 3.18 and lower, the Makefile generators put a copy of both custom +commands in the Makefile for target ``second`` even though its dependency on +target ``first`` ensures that the first custom command runs before the second. +Running ``make second`` would cause the first custom command to run once in +the ``first`` target and then again in the ``second`` target. + +CMake 3.19 and above prefer to not duplicate custom commands in a target that +are already generated in other targets on which the target depends (directly or +indirectly). This policy provides compatibility for projects that have not +been updated to expect the new behavior. In particular, projects that relied +on the duplicate execution or that did not properly set the :prop_sf:`SYMBOLIC` +source file property may be affected. + +The ``OLD`` behavior for this policy is to duplicate custom commands in +dependent targets. The ``NEW`` behavior of this policy is to not duplicate +custom commands in dependent targets. + +This policy was introduced in CMake version 3.19. Unlike many policies, +CMake version |release| does *not* warn when this policy is not set and +simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_sf/LANGUAGE.rst b/Help/prop_sf/LANGUAGE.rst index 88d438e..1dd2554 100644 --- a/Help/prop_sf/LANGUAGE.rst +++ b/Help/prop_sf/LANGUAGE.rst @@ -6,6 +6,6 @@ What programming language is the file. 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``, and ``ASM``. Setting this +``CSharp``, ``CUDA``, ``Fortran``, ``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. diff --git a/Help/prop_tgt/ISPC_HEADER_DIRECTORY.rst b/Help/prop_tgt/ISPC_HEADER_DIRECTORY.rst new file mode 100644 index 0000000..2a3a8bc --- /dev/null +++ b/Help/prop_tgt/ISPC_HEADER_DIRECTORY.rst @@ -0,0 +1,13 @@ +ISPC_HEADER_DIRECTORY +--------------------- + +.. versionadded:: 3.19 + +Specify relative output directory for ISPC headers provided by the target. + +If the target contains ISPC source files, this specifies the directory in which +the generated headers will be placed. Relative paths are treated with respect to +the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. When this property is not set, the +headers will be placed a generator defined build directory. If the variable +:variable:`CMAKE_ISPC_HEADER_DIRECTORY` is set when a target is created +its value is used to initialize this property. diff --git a/Help/prop_tgt/ISPC_INSTRUCTION_SETS.rst b/Help/prop_tgt/ISPC_INSTRUCTION_SETS.rst new file mode 100644 index 0000000..cad116f --- /dev/null +++ b/Help/prop_tgt/ISPC_INSTRUCTION_SETS.rst @@ -0,0 +1,21 @@ +ISPC_INSTRUCTION_SETS +--------------------- + +.. versionadded:: 3.19 + +List of instruction set architectures to generate code for. + +This property is initialized by the value of the :variable:`CMAKE_ISPC_INSTRUCTION_SETS` +variable if it is set when a target is created. + +The ``ISPC_INSTRUCTION_SETS`` target property must be used when generating for multiple +instruction sets so that CMake can track what object files will be generated. + +Examples +^^^^^^^^ + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY ISPC_INSTRUCTION_SETS avx2-i32x4 avx512skx-i32x835) + +Generates code for avx2 and avx512skx target architectures. diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 77ae1f6..16be3cd 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -4,7 +4,7 @@ .. versionadded:: 3.4 This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, -``Fortran``, ``OBJC``, ``OBJCXX``, or ``CUDA``. +``Fortran``, ``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. Specify a :ref:`semicolon-separated list <CMake Language Lists>` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the diff --git a/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst b/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst new file mode 100644 index 0000000..10cdedc --- /dev/null +++ b/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst @@ -0,0 +1,52 @@ +XCODE_LINK_BUILD_PHASE_MODE +--------------------------- + +When using the :generator:`Xcode` generator, libraries to be linked will be +specified in the Xcode project file using either the "Link Binary With +Libraries" build phase or directly as linker flags. The former allows Xcode +to manage build paths, which may be necessary when creating Xcode archives +because it may use different build paths to a regular build. + +This property controls usage of "Link Binary With Libraries" build phase for +a target that is an app bundle, executable, shared library, shared framework +or a module library. + +Possible values are: + +* ``NONE`` + The libraries will be linked by specifying the linker flags directly. + +* ``BUILT_ONLY`` + The "Link Binary With Libraries" build phase will be used to link to another + target under the following conditions: + + - The target to be linked to is a regular non-imported, non-interface library + target. + - The output directory of the target being built has not been changed from + its default (see :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and + :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`). + +* ``KNOWN_LOCATION`` + The "Link Binary With Libraries" build phase will be used to link to another + target under the same conditions as with ``BUILT_ONLY`` and also: + - Imported library targets except those of type ``UNKNOWN``. + - Any non-target library specified directly with a path. + +For all other cases, the libraries will be linked by specifying the linker +flags directly. + +.. warning:: + Libraries linked using "Link Binary With Libraries" are linked after the + ones linked through regular linker flags. This order should be taken into + account when different static libraries contain symbols with the same name, + as the former ones will take precedence over the latter. + +.. warning:: + If two or more directories contain libraries with identical file names and + some libraries are linked from those directories, the library search path + lookup will end up linking libraries from the first directory. This is a + known limitation of Xcode. + +This property is initialized by the value of the +:variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE` variable if it is set when a +target is created. diff --git a/Help/release/dev/cmake_path-command.rst b/Help/release/dev/cmake_path-command.rst new file mode 100644 index 0000000..f4d9f27 --- /dev/null +++ b/Help/release/dev/cmake_path-command.rst @@ -0,0 +1,5 @@ +cmake_path-command +------------------ + +* The :command:`cmake_path` command was added for operations on + filesystem paths. diff --git a/Help/release/dev/cuda-fail-fast.rst b/Help/release/dev/cuda-fail-fast.rst new file mode 100644 index 0000000..d857eb2 --- /dev/null +++ b/Help/release/dev/cuda-fail-fast.rst @@ -0,0 +1,6 @@ +cuda-fail-fast +-------------- + +* If ``CUDA`` compiler detection fails with user-specified + :variable:`CMAKE_CUDA_ARCHITECTURES` or :variable:`CMAKE_CUDA_HOST_COMPILER` + an error is raised. diff --git a/Help/release/dev/custom-command-dedup.rst b/Help/release/dev/custom-command-dedup.rst new file mode 100644 index 0000000..65fa303 --- /dev/null +++ b/Help/release/dev/custom-command-dedup.rst @@ -0,0 +1,5 @@ +custom-command-dedup +-------------------- + +* :ref:`Makefile Generators` no longer repeat custom commands from target + dependencies. See policy :policy:`CMP0113`. diff --git a/Help/release/dev/file-CHMOD.rst b/Help/release/dev/file-CHMOD.rst new file mode 100644 index 0000000..994b529 --- /dev/null +++ b/Help/release/dev/file-CHMOD.rst @@ -0,0 +1,5 @@ +file-CHMOD +---------- + +* Add :command:`file(CHMOD)` and :command:`file(CHMOD_RECURSE)` to + set permissions of files and directories. diff --git a/Help/release/dev/file-REAL_PATH.rst b/Help/release/dev/file-REAL_PATH.rst new file mode 100644 index 0000000..32768ca --- /dev/null +++ b/Help/release/dev/file-REAL_PATH.rst @@ -0,0 +1,5 @@ +file-REAL_PATH +-------------- + +* The :command:`file` gained sub-command `REAL_PATH` to compute a path with + symlinks resolved. diff --git a/Help/release/dev/ispc-language-support.rst b/Help/release/dev/ispc-language-support.rst new file mode 100644 index 0000000..254442e --- /dev/null +++ b/Help/release/dev/ispc-language-support.rst @@ -0,0 +1,11 @@ +cmake-ispc-support +------------------ + + +* CMake learned to support ``ISPC`` as a first-class language that can be + enabled via the :command:`project` and :command:`enable_language` commands. + +* ``ISPC`` is currently supported by the :ref:`Makefile Generators` + and the :generator:`Ninja` generator on Linux, macOS, and Windows. + +* The Intel ISPC compiler (``ispc``) is supported. diff --git a/Help/release/dev/relax-target-generator-expression-dependency-addition.rst b/Help/release/dev/relax-target-generator-expression-dependency-addition.rst new file mode 100644 index 0000000..6d30596 --- /dev/null +++ b/Help/release/dev/relax-target-generator-expression-dependency-addition.rst @@ -0,0 +1,17 @@ +relax-target-generator-expression-dependency-addition +----------------------------------------------------- + +* The following target-based generator expressions that query for directory or + file name components no longer add a dependency on the evaluated target. + See policy :policy:`CMP0112`. + + - ``TARGET_FILE_DIR`` + - ``TARGET_LINKER_FILE_BASE_NAME`` + - ``TARGET_LINKER_FILE_NAME`` + - ``TARGET_LINKER_FILE_DIR`` + - ``TARGET_SONAME_FILE_NAME`` + - ``TARGET_SONAME_FILE_DIR`` + - ``TARGET_PDB_FILE_NAME`` + - ``TARGET_PDB_FILE_DIR`` + - ``TARGET_BUNDLE_DIR`` + - ``TARGET_BUNDLE_CONTENT_DIR`` diff --git a/Help/release/dev/xcode-link-phase-all.rst b/Help/release/dev/xcode-link-phase-all.rst new file mode 100644 index 0000000..a38f70c --- /dev/null +++ b/Help/release/dev/xcode-link-phase-all.rst @@ -0,0 +1,9 @@ +xcode-link-phase-all +-------------------- + +* The Xcode generator gained support for linking libraries and frameworks + via the *Link Binaries With Libraries* build phase instead of always by + embedding linker flags directly. This behavior is controlled by a new + :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is + initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE` + variable. diff --git a/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst b/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst new file mode 100644 index 0000000..a7c9cf6 --- /dev/null +++ b/Help/variable/CMAKE_ISPC_HEADER_DIRECTORY.rst @@ -0,0 +1,10 @@ +CMAKE_ISPC_HEADER_DIRECTORY +---------------------------- + +.. versionadded:: 3.19 + +ISPC generated header output directory. + +This variable is used to initialize the :prop_tgt:`ISPC_HEADER_DIRECTORY` +property on all the targets. See the target property for additional +information. diff --git a/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst b/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst new file mode 100644 index 0000000..8a6005e --- /dev/null +++ b/Help/variable/CMAKE_ISPC_INSTRUCTION_SETS.rst @@ -0,0 +1,9 @@ +CMAKE_ISPC_INSTRUCTION_SETS +--------------------------- + +.. versionadded:: 3.19 + +Default value for :prop_tgt:`ISPC_INSTRUCTION_SETS` property of targets. + +This variable is used to initialize the :prop_tgt:`ISPC_INSTRUCTION_SETS` property +on all targets. See the target property for additional information. diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index 98634c2..89fd7bc 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -6,7 +6,7 @@ CMAKE_<LANG>_COMPILER_LAUNCHER Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property. This variable is used to initialize the property on each target as it is created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, -``OBJC``, ``OBJCXX``, or ``CUDA``. +``ISPC``, ``OBJC``, ``OBJCXX``, or ``CUDA``. This variable is initialized to the :envvar:`CMAKE_<LANG>_COMPILER_LAUNCHER` environment variable if it is set. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index de71d0e..d35595a 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -25,6 +25,8 @@ warn by default: policy :policy:`CMP0089`. * ``CMAKE_POLICY_WARNING_CMP0102`` controls the warning for policy :policy:`CMP0102`. +* ``CMAKE_POLICY_WARNING_CMP0112`` controls the warning for + policy :policy:`CMP0112`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst new file mode 100644 index 0000000..ee4d37e --- /dev/null +++ b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst @@ -0,0 +1,7 @@ +CMAKE_XCODE_LINK_BUILD_PHASE_MODE +--------------------------------- + +This variable is used to initialize the +:prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` property on targets. +It affects the methods that the :generator:`Xcode` generator uses to link +different kinds of libraries. Its default value is ``NONE``. |