diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 6 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 269 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 2 |
5 files changed, 278 insertions, 4 deletions
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index b9d621b..b88b864 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -37,6 +37,8 @@ is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is linked in. +.. _`Binary Executables`: + Binary Executables ------------------ @@ -797,6 +799,10 @@ An *archive* output artifact of a buildsystem target may be: created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. +* On macOS: the linker import file (e.g. ``.tbd``) of a shared library target + created by the :command:`add_library` command with the ``SHARED`` option and + when its :prop_tgt:`ENABLE_EXPORTS` target property is set. + The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties may be used to control archive output artifact locations and names in the build tree. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index ae52ba1..a640c13 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1503,6 +1503,76 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Full path to the linker import file. On DLL platforms, it would be the + ``.lib`` file. On AIX, for the executables, and on macOS, for the shared + libraries, it could be, respectively, the ``.imp`` or ``.tbd`` import file, + depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + An empty string is returned when there is no import file associated with the + target. + +.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of file linker import file of the target ``tgt`` without prefix and + suffix. For example, if target file name is ``libbase.tbd``, the base name is + ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>` and :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file of the target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file of the target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file of the target target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_DIR:tgt> + + Directory of the import file of the target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_LINKER_FILE:tgt> File used when linking to the ``tgt`` target. This will usually @@ -1510,13 +1580,22 @@ In the following, the phrase "the ``tgt`` filename" means the name of the but for a shared library on DLL platforms, it would be the ``.lib`` import library associated with the DLL. + .. versionadded:: 3.27 + On macOS, it could be the ``.tbd`` import file associated with the shared + library, depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + This generator expression is equivalent to + :genex:`$<TARGET_LINKER_LIBRARY_FILE>` or + :genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending of the + characteristics of the target and the platform. + .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 Base name of file used to link the target ``tgt``, i.e. - ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, - if target file name is ``libbase.a``, the base name is ``base``. + :genex:`$<TARGET_LINKER_FILE_NAME:tgt>` without prefix and suffix. For + example, if target file name is ``libbase.a``, the base name is ``base``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration @@ -1570,9 +1649,151 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_LINKER_LIBRARY_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking o the ``tgt`` target is done using directly the + library, and not an import file. This will usually be the library that + ``tgt`` represents (``.a``, ``.so``, ``.dylib``). So, on DLL platforms, it + will be an empty string. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of library file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>` without prefix and suffix. + For example, if target file name is ``libbase.a``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the library file used to link target ``tgt``. + + See also the :prop_tgt:`PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the library file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".a" or ".dylib"). + + See also the :prop_tgt:`SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking to the ``tgt`` target is done using an import + file. This will usually be the import file that ``tgt`` represents + (``.lib``, ``.tbd``). So, when no import file is involved in the link step, + an empty string is returned. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of the import file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>` without prefix and suffix. + For example, if target file name is ``libbase.tbd``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file used to link target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_SONAME_FILE:tgt> File with soname (``.so.3``) where ``tgt`` is the name of a target. + .. genex:: $<TARGET_SONAME_FILE_NAME:tgt> Name of file with soname (``.so.3``). @@ -1582,11 +1803,35 @@ In the following, the phrase "the ``tgt`` filename" means the name of the .. genex:: $<TARGET_SONAME_FILE_DIR:tgt> - Directory of with soname (``.so.3``). + Directory 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`). +.. genex:: $<TARGET_SONAME_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Import file with soname (``.3.tbd``) where ``tgt`` is the name of a target. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_PDB_FILE:tgt> .. versionadded:: 3.1 @@ -1677,7 +1922,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the List of DLLs that the target depends on at runtime. This is determined by the locations of all the ``SHARED`` targets in the target's transitive - dependencies. Using this generator expression on targets other than + dependencies. If only the directories of the DLLs are needed, see the + :genex:`TARGET_RUNTIME_DLL_DIRS` generator expression. + Using this generator expression on targets other than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. **On non-DLL platforms, this expression always evaluates to an empty string**. @@ -1709,6 +1956,20 @@ On platforms that support runtime paths (``RPATH``), refer to the :prop_tgt:`INSTALL_RPATH` target property. On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. +.. genex:: $<TARGET_RUNTIME_DLL_DIRS:tgt> + + .. versionadded:: 3.27 + + List of the directories which contain the DLLs that the target depends on at + runtime (see :genex:`TARGET_RUNTIME_DLLS`). This is determined by + the locations of all the ``SHARED`` targets in the target's transitive + dependencies. Using this generator expression on targets other than + executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + **On non-DLL platforms, this expression always evaluates to an empty string**. + + This generator expression can e.g. be used to create a batch file using + :command:`file(GENERATE)` which sets the PATH environment variable accordingly. + Export And Install Expressions ------------------------------ diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index a0d872f..d0774cb 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -530,6 +530,9 @@ of alphanumeric characters plus ``_`` and ``-``. Variables have dynamic scope. Each variable "set" or "unset" creates a binding in the current scope: +Block Scope + The :command:`block` command may create a new scope for variable bindings. + Function Scope `Command Definitions`_ created by the :command:`function` command create commands that, when invoked, process the recorded commands diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 28272ad..a37a45c 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,8 @@ Policies Introduced by CMake 3.27 .. toctree:: :maxdepth: 1 + CMP0147: Visual Studio generators build custom commands in parallel. </policy/CMP0147> + CMP0146: The FindCUDA module is removed. </policy/CMP0146> CMP0145: The Dart and FindDart modules are removed. </policy/CMP0145> CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables. </policy/CMP0144> diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 373450d..99ea564 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -429,6 +429,7 @@ Variables that Control the Build /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_DLL_NAME_WITH_SOVERSION /variable/CMAKE_ENABLE_EXPORTS + /variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT @@ -508,6 +509,7 @@ Variables that Control the Build /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT |