diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 153 | ||||
| -rw-r--r-- | Help/manual/cmake-compile-features.7.rst | 11 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 3 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 6 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 9 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 8 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 13 |
7 files changed, 160 insertions, 43 deletions
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 7008383..2f43070 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -21,9 +21,9 @@ Binary Targets Executables and libraries are defined using the :command:`add_executable` and :command:`add_library` commands. The resulting binary files have -appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the platform targeted. -Dependencies between binary targets are expressed using the -:command:`target_link_libraries` command: +appropriate :prop_tgt:`PREFIX`, :prop_tgt:`SUFFIX` and extensions for the +platform targeted. Dependencies between binary targets are expressed using +the :command:`target_link_libraries` command: .. code-block:: cmake @@ -530,38 +530,6 @@ the calculated "compatible" value of a property may be read with the In this case, the ``exe1`` source files will be compiled with ``-DCONTAINER_SIZE=200``. -Configuration determined build specifications may be conveniently set using -the ``CONFIG`` generator expression. - -.. code-block:: cmake - - target_compile_definitions(exe1 PRIVATE - $<$<CONFIG:Debug>:DEBUG_BUILD> - ) - -The ``CONFIG`` parameter is compared case-insensitively with the configuration -being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of -:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also -accounted for by this expression. - -Some buildsystems generated by :manual:`cmake(1)` have a predetermined -build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The -buildsystem for the IDEs such as Visual Studio and Xcode are generated -independent of the build-configuration, and the actual build configuration -is not known until build-time. Therefore, code such as - -.. code-block:: cmake - - string(TOLOWER ${CMAKE_BUILD_TYPE} _type) - if (_type STREQUAL debug) - target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) - endif() - -may appear to work for :ref:`Makefile Generators` and :generator:`Ninja` -generators, but is not portable to IDE generators. Additionally, -the :prop_tgt:`IMPORTED` configuration-mappings are not accounted for -with code like this, so it should be avoided. - The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY`` generator expression are evaluated with the consuming target context. This means that a usage requirement specification may be evaluated differently based @@ -840,6 +808,121 @@ target at a time. The commands :command:`add_compile_definitions`, a similar function, but operate at directory scope instead of target scope for convenience. +.. _`Build Configurations`: + +Build Configurations +==================== + +Configurations determine specifications for a certain type of build, such +as ``Release`` or ``Debug``. The way this is specified depends on the type +of :manual:`generator <cmake-generators(7)>` being used. For single +configuration generators like :ref:`Makefile Generators` and +:generator:`Ninja`, the configuration is specified at configure time by the +:variable:`CMAKE_BUILD_TYPE` variable. For multi-configuration generators +like :ref:`Visual Studio <Visual Studio Generators>`, :generator:`Xcode`, and +:generator:`Ninja Multi-Config`, the configuration is chosen by the user at +build time and :variable:`CMAKE_BUILD_TYPE` is ignored. In the +multi-configuration case, the set of *available* configurations is specified +at configure time by the :variable:`CMAKE_CONFIGURATION_TYPES` variable, +but the actual configuration used cannot be known until the build stage. +This difference is often misunderstood, leading to problematic code like the +following: + +.. code-block:: cmake + + # WARNING: This is wrong for multi-config generators because they don't use + # and typically don't even set CMAKE_BUILD_TYPE + string(TOLOWER ${CMAKE_BUILD_TYPE} build_type) + if (build_type STREQUAL debug) + target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) + endif() + +:manual:`Generator expressions <cmake-generator-expressions(7)>` should be +used instead to handle configuration-specific logic correctly, regardless of +the generator used. For example: + +.. code-block:: cmake + + # Works correctly for both single and multi-config generators + target_compile_definitions(exe1 PRIVATE + $<$<CONFIG:Debug>:DEBUG_BUILD> + ) + +In the presence of :prop_tgt:`IMPORTED` targets, the content of +:prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also +accounted for by the above ``$<CONFIG:Debug>`` expression. + + +Case Sensitivity +---------------- + +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` are +just like other variables in that any string comparisons made with their +values will be case-sensitive. The ``$<CONFIG>`` generator expression also +preserves the casing of the configuration as set by the user or CMake defaults. +For example: + +.. code-block:: cmake + + # NOTE: Don't use these patterns, they are for illustration purposes only. + + set(CMAKE_BUILD_TYPE Debug) + if(CMAKE_BUILD_TYPE STREQUAL DEBUG) + # ... will never get here, "Debug" != "DEBUG" + endif() + add_custom_target(print_config ALL + # Prints "Config is Debug" in this single-config case + COMMAND ${CMAKE_COMMAND} -E echo "Config is $<CONFIG>" + VERBATIM + ) + + set(CMAKE_CONFIGURATION_TYPES Debug Release) + if(DEBUG IN_LIST CMAKE_CONFIGURATION_TYPES) + # ... will never get here, "Debug" != "DEBUG" + endif() + +In contrast, CMake treats the configuration type case-insensitively when +using it internally in places that modify behavior based on the configuration. +For example, the ``$<CONFIG:Debug>`` generator expression will evaluate to 1 +for a configuration of not only ``Debug``, but also ``DEBUG``, ``debug`` or +even ``DeBuG``. Therefore, you can specify configuration types in +:variable:`CMAKE_BUILD_TYPE` and :variable:`CMAKE_CONFIGURATION_TYPES` with +any mixture of upper and lowercase, although there are strong conventions +(see the next section). If you must test the value in string comparisons, +always convert the value to upper or lowercase first and adjust the test +accordingly. + +Default And Custom Configurations +--------------------------------- + +By default, CMake defines a number of standard configurations: + +* ``Debug`` +* ``Release`` +* ``RelWithDebInfo`` +* ``MinSizeRel`` + +In multi-config generators, the :variable:`CMAKE_CONFIGURATION_TYPES` variable +will be populated with (potentially a subset of) the above list by default, +unless overridden by the project or user. The actual configuration used is +selected by the user at build time. + +For single-config generators, the configuration is specified with the +:variable:`CMAKE_BUILD_TYPE` variable at configure time and cannot be changed +at build time. The default value will often be none of the above standard +configurations and will instead be an empty string. A common misunderstanding +is that this is the same as ``Debug``, but that is not the case. Users should +always explicitly specify the build type instead to avoid this common problem. + +The above standard configuration types provide reasonable behavior on most +platforms, but they can be extended to provide other types. Each configuration +defines a set of compiler and linker flag variables for the language in use. +These variables follow the convention :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>`, +where ``<CONFIG>`` is always the uppercase configuration name. When defining +a custom configuration type, make sure these variables are set appropriately, +typically as cache variables. + + Pseudo Targets ============== diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 2b0de11..a0459fa 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -118,14 +118,13 @@ as well as any dependents (that may include headers from ``mylib``). Availability of Compiler Extensions ----------------------------------- -Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, -CMake uses extended variants of language dialects by default, such as -``-std=gnu++11`` instead of ``-std=c++11``. That target property may be -set to ``OFF`` to use the non-extended variant of the dialect flag. Note -that because most compilers enable extensions by default, this could -expose cross-platform bugs in user code or in the headers of third-party +The :prop_tgt:`<LANG>_EXTENSIONS` target property defaults to the compiler's +efault. Note that because most compilers enable extensions by default, this +may expose cross-platform bugs in user code or in the headers of third-party dependencies. +:prop_tgt:`<LANG>_EXTENSIONS` used to default to ``ON``. See :policy:`CMP0128`. + Optional Compile Features ========================= diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index fa38588..0799fdd 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -30,12 +30,15 @@ Environment Variables that Control the Build /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL + /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS /envvar/CMAKE_GENERATOR /envvar/CMAKE_GENERATOR_INSTANCE /envvar/CMAKE_GENERATOR_PLATFORM /envvar/CMAKE_GENERATOR_TOOLSET + /envvar/CMAKE_INSTALL_MODE /envvar/CMAKE_LANG_COMPILER_LAUNCHER /envvar/CMAKE_LANG_LINKER_LAUNCHER /envvar/CMAKE_MSVCIDE_RUN_PATH diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 4b2934a..5c109ff 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -74,7 +74,9 @@ package. By setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``, the ``<PackageName>`` package will not be searched, and will always -be ``NOTFOUND``. +be ``NOTFOUND``. Likewise, setting the +:variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` to ``TRUE`` will make the +package REQUIRED. .. _`Config File Packages`: @@ -447,7 +449,7 @@ be true. This can be tested with logic in the package configuration file: set(_supported_components Plot Table) foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) - if (NOT ";${_supported_components};" MATCHES _comp) + if (NOT ";${_supported_components};" MATCHES ";${_comp};") set(ClimbingStats_FOUND False) set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index b9e3d45..3df4f9f 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,15 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.22 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0128: Selection of language standard and extension flags improved. </policy/CMP0128> + CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127> + Policies Introduced by CMake 3.21 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 5f18a82..bb5dba3 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -202,6 +202,7 @@ Properties on Targets /prop_tgt/EXPORT_NAME /prop_tgt/EXPORT_PROPERTIES /prop_tgt/FOLDER + /prop_tgt/Fortran_BUILDING_INSTRINSIC_MODULES /prop_tgt/Fortran_FORMAT /prop_tgt/Fortran_MODULE_DIRECTORY /prop_tgt/Fortran_PREPROCESS @@ -214,6 +215,9 @@ Properties on Targets /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/HIP_ARCHITECTURES + /prop_tgt/HIP_EXTENSIONS + /prop_tgt/HIP_STANDARD + /prop_tgt/HIP_STANDARD_REQUIRED /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED /prop_tgt/IMPORTED_COMMON_LANGUAGE_RUNTIME @@ -273,8 +277,11 @@ Properties on Targets /prop_tgt/LANG_COMPILER_LAUNCHER /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT + /prop_tgt/LANG_EXTENSIONS /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_LINKER_LAUNCHER + /prop_tgt/LANG_STANDARD + /prop_tgt/LANG_STANDARD_REQUIRED /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -450,6 +457,7 @@ Properties on Tests /prop_test/DEPENDS /prop_test/DISABLED /prop_test/ENVIRONMENT + /prop_test/ENVIRONMENT_MODIFICATION /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP /prop_test/FIXTURES_REQUIRED diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 9cea0fb..a2103f7 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -71,6 +71,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOL_PRECOMPILE_HEADER /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR + /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -231,6 +232,7 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_INCLUDE_BEFORE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE_BEFORE + /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS @@ -246,6 +248,7 @@ Variables that Change Behavior /variable/CMAKE_SYSTEM_LIBRARY_PATH /variable/CMAKE_SYSTEM_PREFIX_PATH /variable/CMAKE_SYSTEM_PROGRAM_PATH + /variable/CMAKE_TLS_CAINFO /variable/CMAKE_TLS_VERIFY /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED @@ -428,6 +431,7 @@ Variables that Control the Build /variable/CMAKE_LANG_LINKER_LAUNCHER /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG + /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -438,6 +442,7 @@ Variables that Control the Build /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG /variable/CMAKE_LINK_WHAT_YOU_USE + /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG @@ -525,6 +530,9 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG /variable/CMAKE_HIP_ARCHITECTURES + /variable/CMAKE_HIP_EXTENSIONS + /variable/CMAKE_HIP_STANDARD + /variable/CMAKE_HIP_STANDARD_REQUIRED /variable/CMAKE_ISPC_HEADER_DIRECTORY /variable/CMAKE_ISPC_HEADER_SUFFIX /variable/CMAKE_ISPC_INSTRUCTION_SETS @@ -546,6 +554,8 @@ Variables for Languages /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_EXTENSIONS + /variable/CMAKE_LANG_EXTENSIONS_DEFAULT /variable/CMAKE_LANG_FLAGS /variable/CMAKE_LANG_FLAGS_CONFIG /variable/CMAKE_LANG_FLAGS_CONFIG_INIT @@ -574,8 +584,11 @@ Variables for Languages /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS + /variable/CMAKE_LANG_STANDARD + /variable/CMAKE_LANG_STANDARD_DEFAULT /variable/CMAKE_LANG_STANDARD_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_STANDARD_LIBRARIES + /variable/CMAKE_LANG_STANDARD_REQUIRED /variable/CMAKE_OBJC_EXTENSIONS /variable/CMAKE_OBJC_STANDARD /variable/CMAKE_OBJC_STANDARD_REQUIRED |