diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/string.rst | 9 | ||||
| -rw-r--r-- | Help/command/try_compile.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 55 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/policy/CMP0091.rst | 47 | ||||
| -rw-r--r-- | Help/prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt | 15 | ||||
| -rw-r--r-- | Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst | 26 | ||||
| -rw-r--r-- | Help/prop_tgt/VS_PROJECT_IMPORT.rst | 8 | ||||
| -rw-r--r-- | Help/release/dev/genex-TARGET_FILE_BASE_NAME.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/genex-TARGET_OUTPUT_NAME.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/msvc-runtime-library.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/string-repeat.rst | 4 | ||||
| -rw-r--r-- | Help/release/dev/vs-project-import.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst | 27 |
16 files changed, 200 insertions, 22 deletions
diff --git a/Help/command/string.rst b/Help/command/string.rst index 893fb43..2e89d7b 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -28,6 +28,7 @@ Synopsis string(`SUBSTRING`_ <string> <begin> <length> <out-var>) string(`STRIP`_ <string> <out-var>) string(`GENEX_STRIP`_ <string> <out-var>) + string(`REPEAT`_ <string> <count> <out-var>) `Comparison`_ string(`COMPARE`_ <op> <string1> <string2> <out-var>) @@ -269,6 +270,14 @@ trailing spaces removed. Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` from the ``input string`` and store the result in the ``output variable``. +.. _REPEAT: + +.. code-block:: cmake + + string(REPEAT <input string> <count> <output variable>) + +Produce the output string as repetion of ``input string`` ``count`` times. + Comparison ^^^^^^^^^^ diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index ca8fc77..0bc2ca3 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -135,6 +135,7 @@ default values: * :variable:`CMAKE_ENABLE_EXPORTS` * :variable:`CMAKE_LINK_SEARCH_START_STATIC` * :variable:`CMAKE_LINK_SEARCH_END_STATIC` +* :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` * :variable:`CMAKE_POSITION_INDEPENDENT_CODE` If :policy:`CMP0056` is set to ``NEW``, then diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index e9b3f4c..7f4761f 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -387,14 +387,25 @@ Target-Dependent Queries ``$<TARGET_NAME_IF_EXISTS:tgt>`` Expands to the ``tgt`` if the given target exists, an empty string otherwise. -``$<TARGET_OUTPUT_NAME:tgt>`` +``$<TARGET_FILE:tgt>`` + Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a + target. +``$<TARGET_FILE_BASE_NAME:tgt>`` Base name of main file where ``tgt`` is the name of a target. + The base name corresponds to the target file name (see + ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if + target file name is ``libbase.so``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`. + Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$<TARGET_FILE:tgt>`` - Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a - target. ``$<TARGET_FILE_PREFIX:tgt>`` Prefix of main file where ``tgt`` is the name of a target. @@ -409,13 +420,23 @@ Target-Dependent Queries Name of main file (.exe, .so.1.2, .a). ``$<TARGET_FILE_DIR:tgt>`` Directory of main file (.exe, .so.1.2, .a). -``$<TARGET_LINKER_OUTPUT_NAME:tgt>`` +``$<TARGET_LINKER_FILE:tgt>`` + File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. +``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` Base name of file used to link where ``tgt`` is the name of a target. + The base name corresponds to the target linker file name (see + ``$<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 + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$<TARGET_LINKER_FILE:tgt>`` - File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. ``$<TARGET_LINKER_FILE_PREFIX:tgt>`` Prefix of file used to link where ``tgt`` is the name of a target. @@ -436,22 +457,26 @@ Target-Dependent Queries Name of file with soname (.so.3). ``$<TARGET_SONAME_FILE_DIR:tgt>`` Directory of with soname (.so.3). -``$<TARGET_PDB_OUTPUT_NAME:tgt>`` +``$<TARGET_PDB_FILE:tgt>`` + Full path to the linker generated program database file (.pdb) + where ``tgt`` is the name of a target. + + See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` + target properties and their configuration specific variants + :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. +``$<TARGET_PDB_FILE_BASE_NAME:tgt>`` Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. + The base name corresponds to the target PDB file name (see + ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``base.pdb``, the base name is ``base``. + See also the :prop_tgt:`PDB_NAME` target property and its configuration specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$<TARGET_PDB_FILE:tgt>`` - Full path to the linker generated program database file (.pdb) - where ``tgt`` is the name of a target. - - See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` - target properties and their configuration specific variants - :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). ``$<TARGET_PDB_FILE_DIR:tgt>`` diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index e89ea3da..043fb5c 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.15 .. toctree:: :maxdepth: 1 + CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091> CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090> CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089> diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 4d4b9ff..c11496c 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -280,6 +280,7 @@ Properties on Targets /prop_tgt/MACOSX_RPATH /prop_tgt/MANUALLY_ADDED_DEPENDENCIES /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG + /prop_tgt/MSVC_RUNTIME_LIBRARY /prop_tgt/NAME /prop_tgt/NO_SONAME /prop_tgt/NO_SYSTEM_FROM_IMPORTED @@ -335,6 +336,7 @@ Properties on Targets /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION /prop_tgt/VS_NO_SOLUTION_DEPLOY + /prop_tgt/VS_PROJECT_IMPORT /prop_tgt/VS_SCC_AUXPATH /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 18dd9d7..22e8add 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -386,6 +386,7 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS_INIT /variable/CMAKE_MSVCIDE_RUN_PATH + /variable/CMAKE_MSVC_RUNTIME_LIBRARY /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED diff --git a/Help/policy/CMP0091.rst b/Help/policy/CMP0091.rst new file mode 100644 index 0000000..5b7c4e3 --- /dev/null +++ b/Help/policy/CMP0091.rst @@ -0,0 +1,47 @@ +CMP0091 +------- + +MSVC runtime library flags are selected by an abstraction. + +Compilers targeting the MSVC ABI have flags to select the MSVC runtime library. +Runtime library selection typically varies with build configuration because +there is a separate runtime library for Debug builds. + +In CMake 3.14 and below, MSVC runtime library selection flags are added to +the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake +automatically. This allows users to edit their cache entries to adjust the +flags. However, the presence of such default flags is problematic for +projects that want to choose a different runtime library programmatically. +In particular, it requires string editing of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the +CMake builtin defaults so they can be replaced. + +CMake 3.15 and above prefer to leave the MSVC runtime library selection flags +out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead +offer a first-class abstraction. The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` +variable and :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property may be set to +select the MSVC runtime library. + +This policy provides compatibility with projects that have not been updated +to be aware of the abstraction. The policy setting takes effect as of the +first :command:`project` or :command:`enable_language` command that enables +a language whose compiler targets the MSVC ABI. + +.. note:: + + Once the policy has taken effect at the top of a project, that choice + must be used throughout the tree. In projects that have nested projects + in subdirectories, be sure to convert everything together. + +The ``OLD`` behavior for this policy is to place MSVC runtime library +flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entries and ignore the :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` abstraction. +The ``NEW`` behavior for this policy is to *not* place MSVC runtime +library flags in the default cache entries and use the abstraction instead. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +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_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt new file mode 100644 index 0000000..2bf71a9 --- /dev/null +++ b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt @@ -0,0 +1,15 @@ +``MultiThreaded`` + Compile with ``-MT`` or equivalent flag(s) to use a multi-threaded + statically-linked runtime library. +``MultiThreadedDLL`` + Compile with ``-MD`` or equivalent flag(s) to use a multi-threaded + dynamically-linked runtime library. +``MultiThreadedDebug`` + Compile with ``-MTd`` or equivalent flag(s) to use a multi-threaded + statically-linked runtime library. +``MultiThreadedDebugDLL`` + Compile with ``-MDd`` or equivalent flag(s) to use a multi-threaded + dynamically-linked runtime library. + +The value is ignored on non-MSVC compilers but an unsupported value will +be rejected as an error when using a compiler targeting the MSVC ABI. diff --git a/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..1e3f5e9 --- /dev/null +++ b/Help/prop_tgt/MSVC_RUNTIME_LIBRARY.rst @@ -0,0 +1,26 @@ +MSVC_RUNTIME_LIBRARY +-------------------- + +Select the MSVC runtime library for use by compilers targeting the MSVC ABI. + +The allowed values are: + +.. include:: MSVC_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. For example, the code: + +.. code-block:: cmake + + add_executable(foo foo.c) + set_property(TARGET foo PROPERTY + MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>") + +selects for the target ``foo`` a multi-threaded statically-linked runtime +library with or without debug information depending on the configuration. + +.. note:: + + This property has effect only when policy :policy:`CMP0091` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the MSVC ABI. diff --git a/Help/prop_tgt/VS_PROJECT_IMPORT.rst b/Help/prop_tgt/VS_PROJECT_IMPORT.rst new file mode 100644 index 0000000..569c8ea --- /dev/null +++ b/Help/prop_tgt/VS_PROJECT_IMPORT.rst @@ -0,0 +1,8 @@ +VS_PROJECT_IMPORT +----------------- + +Visual Studio managed project imports + +Adds to a generated Visual Studio project one or more semicolon-delimited paths +to .props files needed when building projects from some NuGet packages. +For example, ``my_packages_path/MyPackage.1.0.0/build/MyPackage.props``. diff --git a/Help/release/dev/genex-TARGET_FILE_BASE_NAME.rst b/Help/release/dev/genex-TARGET_FILE_BASE_NAME.rst new file mode 100644 index 0000000..d8b2b21 --- /dev/null +++ b/Help/release/dev/genex-TARGET_FILE_BASE_NAME.rst @@ -0,0 +1,7 @@ +genex-TARGET_FILE_BASE_NAME +--------------------------- + +* New ``$<TARGET_FILE_BASE_NAME:...>``, ``$<TARGET_LINKER_FILE_BASE_NAME:...>`` + and ``$<TARGET_PDB_FILE_BASE_NAME:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` have been + added to retrieve the base name of various artifacts. diff --git a/Help/release/dev/genex-TARGET_OUTPUT_NAME.rst b/Help/release/dev/genex-TARGET_OUTPUT_NAME.rst deleted file mode 100644 index e3ffe57..0000000 --- a/Help/release/dev/genex-TARGET_OUTPUT_NAME.rst +++ /dev/null @@ -1,7 +0,0 @@ -genex-TARGET_OUTPUT_NAME ------------------------- - -* New ``$<TARGET_OUTPUT_NAME:...>``, ``$<TARGET_LINKER_OUTPUT_NAME:...>`` and - ``$<TARGET_PDB_OUTPUT_NAME:...>`` - :manual:`generator expressions <cmake-generator-expressions(7)>` have been - added to retrieve the base name of various artifacts. diff --git a/Help/release/dev/msvc-runtime-library.rst b/Help/release/dev/msvc-runtime-library.rst new file mode 100644 index 0000000..4dddac2 --- /dev/null +++ b/Help/release/dev/msvc-runtime-library.rst @@ -0,0 +1,7 @@ +msvc-runtime-library +-------------------- + +* The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` variable and + :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property were introduced to + select the runtime library used by compilers targeting the MSVC ABI. + See policy :policy:`CMP0091`. diff --git a/Help/release/dev/string-repeat.rst b/Help/release/dev/string-repeat.rst new file mode 100644 index 0000000..4be0d5c --- /dev/null +++ b/Help/release/dev/string-repeat.rst @@ -0,0 +1,4 @@ +string-repeat +-------------- + +* The :command:`string` learned a new sub-command ``REPEAT``. diff --git a/Help/release/dev/vs-project-import.rst b/Help/release/dev/vs-project-import.rst new file mode 100644 index 0000000..de6024d --- /dev/null +++ b/Help/release/dev/vs-project-import.rst @@ -0,0 +1,5 @@ +vs-project-import +----------------- + +* The :prop_tgt:`VS_PROJECT_IMPORT` target property was added which allows + to import external .props files in managed Visual Studio targets. diff --git a/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst new file mode 100644 index 0000000..6ed68c9 --- /dev/null +++ b/Help/variable/CMAKE_MSVC_RUNTIME_LIBRARY.rst @@ -0,0 +1,27 @@ +CMAKE_MSVC_RUNTIME_LIBRARY +-------------------------- + +Select the MSVC runtime library for use by compilers targeting the MSVC ABI. +This variable is used to initialize the :prop_tgt:`MSVC_RUNTIME_LIBRARY` +property on all targets as they are created. It is also propagated by +calls to the :command:`try_compile` command into the test project. + +The allowed values are: + +.. include:: ../prop_tgt/MSVC_RUNTIME_LIBRARY-VALUES.txt + +Use :manual:`generator expressions <cmake-generator-expressions(7)>` to +support per-configuration specification. For example, the code: + +.. code-block:: cmake + + set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>") + +selects for all following targets a multi-threaded statically-linked runtime +library with or without debug information depending on the configuration. + +.. note:: + + This variable has effect only when policy :policy:`CMP0091` is set to ``NEW`` + prior to the first :command:`project` or :command:`enable_language` command + that enables a language using a compiler targeting the MSVC ABI. |