diff options
Diffstat (limited to 'Help/manual')
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 51 | ||||
| -rw-r--r-- | Help/manual/cmake-env-variables.7.rst | 2 | ||||
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 271 | ||||
| -rw-r--r-- | Help/manual/cmake-language.7.rst | 10 | ||||
| -rw-r--r-- | Help/manual/cmake-modules.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-policies.7.rst | 15 | ||||
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 19 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 10 | ||||
| -rw-r--r-- | Help/manual/cmake-toolchains.7.rst | 22 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 20 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 69 | ||||
| -rw-r--r-- | Help/manual/ctest.1.rst | 10 | ||||
| -rw-r--r-- | Help/manual/presets/example.json | 2 | ||||
| -rw-r--r-- | Help/manual/presets/schema.json | 73 |
14 files changed, 522 insertions, 53 deletions
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index f48313a..bceff2d 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -1040,24 +1040,26 @@ Additionally, IDEs will show the source files as part of the target for interactive reading and editing. A primary use-case for ``INTERFACE`` libraries is header-only libraries. +Since CMake 3.23, header files may be associated with a library by adding +them to a header set using the :command:`target_sources` command: .. code-block:: cmake - add_library(Eigen INTERFACE - src/eigen.h - src/vector.h - src/matrix.h - ) - target_include_directories(Eigen INTERFACE - $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> - $<INSTALL_INTERFACE:include/Eigen> + add_library(Eigen INTERFACE) + + target_sources(Eigen INTERFACE + FILE_SET HEADERS + BASE_DIRS src + FILES src/eigen.h src/vector.h src/matrix.h ) add_executable(exe1 exe1.cpp) target_link_libraries(exe1 Eigen) -Here, the usage requirements from the ``Eigen`` target are consumed and used -when compiling, but it has no effect on linking. +When we specify the ``FILE_SET`` here, the ``BASE_DIRS`` we define automatically +become include directories in the usage requirements for the target ``Eigen``. +The usage requirements from the target are consumed and used when compiling, but +have no effect on linking. Another use-case is to employ an entirely target-focussed design for usage requirements: @@ -1081,26 +1083,25 @@ This way, the build specification of ``exe1`` is expressed entirely as linked targets, and the complexity of compiler-specific flags is encapsulated in an ``INTERFACE`` library target. -``INTERFACE`` libraries may be installed and exported. Any content they refer -to must be installed separately: +``INTERFACE`` libraries may be installed and exported. We can install the +default header set along with the target: .. code-block:: cmake - set(Eigen_headers - src/eigen.h - src/vector.h - src/matrix.h - ) - add_library(Eigen INTERFACE ${Eigen_headers}) - target_include_directories(Eigen INTERFACE - $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> - $<INSTALL_INTERFACE:include/Eigen> + add_library(Eigen INTERFACE) + + target_sources(Eigen INTERFACE + FILE_SET HEADERS + BASE_DIRS src + FILES src/eigen.h src/vector.h src/matrix.h ) - install(TARGETS Eigen EXPORT eigenExport) + install(TARGETS Eigen EXPORT eigenExport + FILE_SET HEADERS DESTINATION include/Eigen) install(EXPORT eigenExport NAMESPACE Upstream:: DESTINATION lib/cmake/Eigen ) - install(FILES ${Eigen_headers} - DESTINATION include/Eigen - ) + +Here, the headers defined in the header set are installed to ``include/Eigen``. +The install destination automatically becomes an include directory that is a +usage requirement for consumers. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 0799fdd..737b22c 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -28,9 +28,11 @@ Environment Variables that Control the Build .. toctree:: :maxdepth: 1 + /envvar/ADSP_ROOT /envvar/CMAKE_APPLE_SILICON_PROCESSOR /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_BUILD_TYPE + /envvar/CMAKE_COLOR_DIAGNOSTICS /envvar/CMAKE_CONFIGURATION_TYPES /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_EXPORT_COMPILE_COMMANDS diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index d0f708a..22c14df 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -599,7 +599,9 @@ String Transformations .. versionadded:: 3.15 - Removes duplicated items in the given ``list``. + Removes duplicated items in the given ``list``. The relative order of items + is preserved, but if duplicates are encountered, only the first instance is + preserved. .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> @@ -1019,8 +1021,19 @@ which is just the string ``tgt``. .. versionadded:: 3.9 - Full path to the bundle directory (``my.app``, ``my.framework``, or - ``my.bundle``) where ``tgt`` is the name of a target. + Full path to the bundle directory (``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/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`). + +.. genex:: $<TARGET_BUNDLE_DIR_NAME:tgt> + + .. versionadded:: 3.24 + + Name of 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`). @@ -1030,10 +1043,11 @@ which is just the string ``tgt``. .. versionadded:: 3.9 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. + target. For the macOS SDK it leads to ``/path/to/my.app/Contents``, + ``/path/to/my.framework``, or ``/path/to/my.bundle/Contents``. + For all other SDKs (e.g. iOS) it leads to ``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/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`). @@ -1106,12 +1120,243 @@ Output-Related Expressions .. versionadded:: 3.1 - Content of ``...`` except when evaluated in a link interface while - propagating :ref:`Target Usage Requirements`, in which case it is the - empty string. - Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target - property, perhaps via the :command:`target_link_libraries` command, - to specify private link dependencies without other usage requirements. + Content of ``...``, except while collecting :ref:`Target Usage Requirements`, + in which case it is the empty string. This is intended for use in an + :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated + via the :command:`target_link_libraries` command, to specify private link + dependencies without other usage requirements. + + .. versionadded:: 3.24 + ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target + property. See policy :policy:`CMP0131`. + +.. genex:: $<LINK_LIBRARY:feature,library-list> + + .. versionadded:: 3.24 + + Manage how libraries are specified during the link step. + This expression may be used to specify how to link libraries in a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:load_archive,lib1>") + + This specify to use the ``lib1`` target with feature ``load_archive`` for + linking target ``lib2``. The feature must have be defined by + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable or, if + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is false, + by :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + Each target or external library involved in the link step must have only one + kind of feature (the absence of feature is also incompatible with any + feature). For example: + + .. code-block:: cmake + + add_library(lib1 ...) + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # an error will be raised here because lib1 has two different features + + To resolve such incompatibilities, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` + and :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be + used. + + .. note:: + + This expression does not guarantee that the list of specified libraries + will be kept grouped. So, to manage constructs like ``start-group`` and + ``end-group``, as supported by ``GNU ld``, the :genex:`LINK_GROUP` + generator expression can be used. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt + +.. genex:: $<LINK_GROUP:feature,library-list> + + .. versionadded:: 3.24 + + Manage the grouping of libraries during the link step. + This expression may be used to specify how to kept groups of libraries during + the link of a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + + This specify to use the ``lib1`` target and ``external`` library with the + group feature ``cross_refs`` for linking target ``lib2``. The feature must + have be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + variable or, if :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + is false, by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + .. note:: + + This expression is compatible with the :genex:`LINK_LIBRARY` generator + expression. The libraries involved in a group can be specified using the + :genex:`LINK_LIBRARY` generator expression. + + Each target or external library involved in the link step can be part of + different groups as far as these groups use the same feature, so mixing + different group features for the same target or library is forbidden. The + different groups will be part of the link step. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>") + # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3} + + add_library(lib5 ...) + target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>") + # an error will be raised here because lib1 is part of two groups with + # different features + + When a target or an external library is involved in the link step as part of + a group and also as standalone, any occurrence of the standalone link item + will be replaced by the group or groups it belong to. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC lib1) + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + Be aware that the precedence of the group over the standalone link item can + result in some circular dependency between groups, which will raise an + error because circular dependencies are not allowed for groups. + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC lib2A) + target_link_libraries(lib2B PUBLIC lib1B) + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>") + target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>") + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + So, we have a circular dependency between groups ``{lib1A,lib1B}`` and + ``{lib2A,lib2B}``. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt .. genex:: $<INSTALL_INTERFACE:...> diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index e7d2694..02cfa7e 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -582,7 +582,8 @@ Scope They are never cached. References - `Variable References`_ have the form ``$ENV{<variable>}``. + `Variable References`_ have the form ``$ENV{<variable>}``, using the + :variable:`ENV` operator. Initialization Initial values of the CMake environment variables are those of @@ -594,6 +595,13 @@ Initialization Changed values are not written back to the calling process, and they are not seen by subsequent build or test processes. + See the :ref:`cmake -E env <Run a Command-Line Tool>` command-line + tool to run a command in a modified environment. + +Inspection + See the :ref:`cmake -E environment <Run a Command-Line Tool>` command-line + tool to display all current environment variables. + The :manual:`cmake-env-variables(7)` manual documents environment variables that have special meaning to CMake. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 141eeaa..93beea9 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -317,7 +317,6 @@ used directly. /module/CPackFreeBSD /module/CPackNSIS /module/CPackNuGet - /module/CPackPackageMaker /module/CPackProductBuild /module/CPackRPM /module/CPackWIX diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 0939a82..788d086 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -52,6 +52,21 @@ to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.24 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137> + CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136> + CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135> + CMP0134: Fallback to \"HOST\" Windows registry view when \"TARGET\" view is not usable. </policy/CMP0134> + CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133> + CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132> + CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131> + CMP0130: while() diagnoses condition evaluation errors. </policy/CMP0130> + Policies Introduced by CMake 3.23 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 03bb5aa..948d87a 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -42,7 +42,7 @@ The root object recognizes the following fields: ``version`` A required integer representing the version of the JSON schema. - The supported versions are ``1``, ``2``, ``3``, and ``4``. + The supported versions are ``1``, ``2``, ``3``, ``4``, and ``5``. ``cmakeMinimumRequired`` @@ -715,6 +715,12 @@ that may contain the following fields: bytes. Equivalent to passing ``--test-output-size-failed`` on the command line. + ``testOutputTruncation`` + + An optional string specifying the test output truncation mode. Equivalent + to passing ``--test-output-truncation`` on the command line." + This is allowed in preset files specifying version ``5`` or above. + ``maxTestNameWidth`` An optional integer specifying the maximum width of a test name to @@ -1062,6 +1068,17 @@ Recognized macros include: A literal dollar sign (``$``). +``${pathListSep}`` + + Native character for separating lists of paths, such as ``:`` or ``;``. + + For example, by setting ``PATH`` to + ``/path/to/ninja/bin${pathListSep}$env{PATH}``, ``${pathListSep}`` will + expand to the underlying operating system's character used for + concatenation in ``PATH``. + + This is allowed in preset files specifying version ``5`` or above. + ``$env{<variable-name>}`` Environment variable with name ``<variable-name>``. The variable name may diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index ddb917a..20b62c5 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -171,6 +171,7 @@ Properties on Targets /prop_tgt/COMPILE_PDB_NAME_CONFIG /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /prop_tgt/COMPILE_WARNING_AS_ERROR /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX /prop_tgt/CROSSCOMPILING_EMULATOR @@ -266,6 +267,8 @@ Properties on Targets /prop_tgt/INTERFACE_LINK_DEPENDS /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES + /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT + /prop_tgt/INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE /prop_tgt/INTERFACE_LINK_OPTIONS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_PRECOMPILE_HEADERS @@ -306,6 +309,8 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_LIBRARIES /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS + /prop_tgt/LINK_LIBRARY_OVERRIDE + /prop_tgt/LINK_LIBRARY_OVERRIDE_LIBRARY /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC @@ -376,6 +381,7 @@ Properties on Targets /prop_tgt/UNITY_BUILD_CODE_BEFORE_INCLUDE /prop_tgt/UNITY_BUILD_MODE /prop_tgt/UNITY_BUILD_UNIQUE_ID + /prop_tgt/VERIFY_HEADER_SETS /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE @@ -389,6 +395,7 @@ Properties on Targets /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL + /prop_tgt/VS_DOTNET_STARTUP_OBJECT /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/VS_DPI_AWARE /prop_tgt/VS_GLOBAL_KEYWORD @@ -400,6 +407,7 @@ Properties on Targets /prop_tgt/VS_JUST_MY_CODE_DEBUGGING /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION + /prop_tgt/VS_NO_COMPILE_BATCHING /prop_tgt/VS_NO_SOLUTION_DEPLOY /prop_tgt/VS_PACKAGE_REFERENCES /prop_tgt/VS_PLATFORM_TOOLSET @@ -416,6 +424,7 @@ Properties on Targets /prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_EXTENSIONS /prop_tgt/VS_WINRT_REFERENCES + /prop_tgt/WATCOM_RUNTIME_LIBRARY /prop_tgt/WIN32_EXECUTABLE /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS /prop_tgt/XCODE_ATTRIBUTE_an-attribute @@ -451,6 +460,7 @@ Properties on Targets /prop_tgt/XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP /prop_tgt/XCODE_SCHEME_WORKING_DIRECTORY /prop_tgt/XCODE_SCHEME_ZOMBIE_OBJECTS + /prop_tgt/XCODE_XCCONFIG /prop_tgt/XCTEST .. _`Test Properties`: diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index a941310..e194df0 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -301,6 +301,28 @@ Windows Store may look like this: set(CMAKE_SYSTEM_NAME WindowsStore) set(CMAKE_SYSTEM_VERSION 8.1) +.. _`Cross Compiling for ADSP SHARC/Blackfin`: + +Cross Compiling for ADSP SHARC/Blackfin +--------------------------------------- + +Cross-compiling for ADSP SHARC or Blackfin can be configured +by setting the :variable:`CMAKE_SYSTEM_NAME` variable to ``ADSP`` +and the :variable:`CMAKE_SYSTEM_PROCESSOR` variable +to the "part number", excluding the ``ADSP-`` prefix, +for example, ``21594``, ``SC589``, etc. +This value is case insensitive. + +CMake will automatically search for CCES or VDSP++ installs +in their default install locations +and select the most recent version found. +CCES will be selected over VDSP++ if both are installed. +Custom install paths can be set via the :variable:`CMAKE_ADSP_ROOT` variable +or the :envvar:`ADSP_ROOT` environment variable. + +The compiler (``cc21k`` vs. ``ccblkfn``) is selected automatically +based on the :variable:`CMAKE_SYSTEM_PROCESSOR` value provided. + .. _`Cross Compiling for Android`: Cross Compiling for Android diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 4df0237..ff431ad 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -59,6 +59,7 @@ Variables that Provide Information /variable/CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES /variable/CMAKE_FIND_DEBUG_MODE /variable/CMAKE_FIND_PACKAGE_NAME + /variable/CMAKE_FIND_PACKAGE_REDIRECTS_DIR /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR @@ -172,6 +173,7 @@ Variables that Change Behavior /variable/CMAKE_CODEBLOCKS_COMPILER_ID /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS + /variable/CMAKE_COLOR_DIAGNOSTICS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES /variable/CMAKE_DEPENDS_IN_PROJECT_ONLY @@ -197,6 +199,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_PREFER_CONFIG /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS + /variable/CMAKE_FIND_PACKAGE_TARGETS_GLOBAL /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE @@ -204,6 +207,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_ROOT_PATH_MODE_PACKAGE /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM /variable/CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH + /variable/CMAKE_FIND_USE_INSTALL_PREFIX /variable/CMAKE_FIND_USE_CMAKE_PATH /variable/CMAKE_FIND_USE_CMAKE_SYSTEM_PATH /variable/CMAKE_FIND_USE_PACKAGE_REGISTRY @@ -239,6 +243,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_PROJECT_TOP_LEVEL_INCLUDES /variable/CMAKE_REQUIRE_FIND_PACKAGE_PackageName /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX @@ -283,6 +288,7 @@ Variables that Change Behavior /variable/CMAKE_XCODE_SCHEME_UNDEFINED_BEHAVIOUR_SANITIZER_STOP /variable/CMAKE_XCODE_SCHEME_WORKING_DIRECTORY /variable/CMAKE_XCODE_SCHEME_ZOMBIE_OBJECTS + /variable/CMAKE_XCODE_XCCONFIG /variable/PackageName_ROOT Variables that Describe the System @@ -344,6 +350,7 @@ Variables that Control the Build .. toctree:: :maxdepth: 1 + /variable/CMAKE_ADSP_ROOT /variable/CMAKE_AIX_EXPORT_ALL_SYMBOLS /variable/CMAKE_ANDROID_ANT_ADDITIONAL_OPTIONS /variable/CMAKE_ANDROID_API @@ -395,6 +402,7 @@ Variables that Control the Build /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_COMPILE_WARNING_AS_ERROR /variable/CMAKE_CONFIG_POSTFIX /variable/CMAKE_CROSS_CONFIGS /variable/CMAKE_CTEST_ARGUMENTS @@ -437,7 +445,11 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE + /variable/CMAKE_LANG_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINKER_LAUNCHER + /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE + /variable/CMAKE_LANG_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_LINK_WHAT_YOU_USE_FLAG @@ -447,9 +459,13 @@ Variables that Control the Build /variable/CMAKE_LIBRARY_PATH_FLAG /variable/CMAKE_LINK_DEF_FILE_FLAG /variable/CMAKE_LINK_DEPENDS_NO_SHARED + /variable/CMAKE_LINK_GROUP_USING_FEATURE + /variable/CMAKE_LINK_GROUP_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_INTERFACE_LIBRARIES /variable/CMAKE_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LINK_LIBRARY_FLAG + /variable/CMAKE_LINK_LIBRARY_USING_FEATURE + /variable/CMAKE_LINK_LIBRARY_USING_FEATURE_SUPPORTED /variable/CMAKE_LINK_WHAT_YOU_USE /variable/CMAKE_LINK_WHAT_YOU_USE_CHECK /variable/CMAKE_MACOSX_BUNDLE @@ -487,12 +503,14 @@ Variables that Control the Build /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_STATIC_LINKER_FLAGS_INIT /variable/CMAKE_TRY_COMPILE_CONFIGURATION + /variable/CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES /variable/CMAKE_TRY_COMPILE_TARGET_TYPE /variable/CMAKE_UNITY_BUILD /variable/CMAKE_UNITY_BUILD_BATCH_SIZE /variable/CMAKE_UNITY_BUILD_UNIQUE_ID /variable/CMAKE_USE_RELATIVE_PATHS + /variable/CMAKE_VERIFY_HEADER_SETS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_GLOBALS /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD @@ -506,6 +524,7 @@ Variables that Control the Build /variable/CMAKE_VS_SDK_REFERENCE_DIRECTORIES /variable/CMAKE_VS_SDK_SOURCE_DIRECTORIES /variable/CMAKE_VS_WINRT_BY_DEFAULT + /variable/CMAKE_WATCOM_RUNTIME_LIBRARY /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute @@ -633,6 +652,7 @@ Variables for CTest /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_ERRORS /variable/CTEST_CUSTOM_MAXIMUM_NUMBER_OF_WARNINGS /variable/CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE + /variable/CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION /variable/CTEST_CUSTOM_MEMCHECK_IGNORE /variable/CTEST_CUSTOM_POST_MEMCHECK /variable/CTEST_CUSTOM_POST_TEST diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 18bdc5f..e0cb708 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -197,6 +197,13 @@ Options .. include:: OPTIONS_BUILD.txt +``--fresh`` + .. versionadded:: 3.24 + + Perform a fresh configuration of the build tree. + This removes any existing ``CMakeCache.txt`` file and associated + ``CMakeFiles/`` directory, and recreates them from scratch. + ``-L[A][H]`` List non-advanced cached variables. @@ -326,7 +333,8 @@ Options "cmd": "add_executable", "args": ["foo", "bar"], "time": 1579512535.9687231, - "frame": 2 + "frame": 2, + "global_frame": 4 } The members are: @@ -336,7 +344,13 @@ Options was called. ``line`` - The line in ``file`` of the function call. + The line in ``file`` where the function call begins. + + ``line_end`` + If the function call spans multiple lines, this field will + be set to the line where the function call ends. If the function + calls spans a single line, this field will be unset. This field + was added in minor version 2 of the ``json-v1`` format. ``defer`` Optional member that is present when the function call was deferred @@ -353,7 +367,13 @@ Options Timestamp (seconds since epoch) of the function call. ``frame`` - Stack frame depth of the function that was called. + Stack frame depth of the function that was called, within the + context of the ``CMakeLists.txt`` being processed currently. + + ``global_frame`` + Stack frame depth of the function that was called, tracked globally + across all ``CMakeLists.txt`` files involved in the trace. This field + was added in minor version 2 of the ``json-v1`` format. Additionally, the first JSON document outputted contains the ``version`` key for the current major and minor version of the @@ -365,7 +385,7 @@ Options { "version": { "major": 1, - "minor": 1 + "minor": 2 } } @@ -599,6 +619,8 @@ in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the script (including the ``--`` itself). +.. _`Run a Command-Line Tool`: + Run a Command-Line Tool ======================= @@ -673,11 +695,17 @@ Available commands are: ``true`` if cmake supports server-mode and ``false`` otherwise. Always false since CMake 3.20. -``cat <files>...`` +``cat [--] <files>...`` .. versionadded:: 3.18 Concatenate files and print on the standard output. + .. versionadded:: 3.24 + Added support for the double dash argument ``--``. This basic implementation + of ``cat`` does not support any options, so using a option starting with + ``-`` will result in an error. Use ``--`` to indicate the end of options, in + case a file starts with ``-``. + ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. @@ -746,11 +774,16 @@ Available commands are: ``echo_append [<string>...]`` Displays arguments as text but no new line. -``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...`` +``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]`` .. versionadded:: 3.1 Run command in a modified environment. + .. versionadded:: 3.24 + Added support for the double dash argument ``--``. Use ``--`` to stop + interpreting options/environment variables and treat the next argument as + the command, even if it start with ``-`` or contains a ``=``. + ``environment`` Display the current environment variables. @@ -843,16 +876,16 @@ Available commands are: Rename a file or directory (on one volume). If file with the ``<newname>`` name already exists, then it will be silently replaced. -``rm [-rRf] <file> <dir>...`` +``rm [-rRf] [--] <file|dir>...`` .. versionadded:: 3.17 Remove the files ``<file>`` or directories ``<dir>``. - Use ``-r`` or ``-R`` to remove directories and their contents recursively. If any of the listed files/directories do not exist, the command returns a non-zero exit code, but no message is logged. The ``-f`` option changes the behavior to return a zero exit code (i.e. success) in such - situations instead. + situations instead. Use ``--`` to stop interpreting options and treat all + remaining arguments as paths, even if they start with ``-``. ``server`` Launch :manual:`cmake-server(7)` mode. @@ -924,6 +957,12 @@ Available commands are: Specify modification time recorded in tarball entries. + ``--touch`` + .. versionadded:: 3.24 + + Use current local timestamp instead of extracting file timestamps + from the archive. + ``--`` .. versionadded:: 3.1 @@ -1022,6 +1061,18 @@ To view the presets available for a project, use cmake <source-dir> --list-presets + +.. _`CMake Exit Code`: + +Return Value (Exit Code) +======================== + +Upon regular termination, the ``cmake`` executable returns the exit code ``0``. + +If termination is caused by the command :command:`message(FATAL_ERROR)`, +or another error condition, then a non-zero exit code is returned. + + See Also ======== diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 1e7b077..06f0d4e 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -357,11 +357,21 @@ See `Build and Test Mode`_. Specify the directory in which to look for tests. ``--test-output-size-passed <size>`` + .. versionadded:: 3.4 + Limit the output for passed tests to ``<size>`` bytes. ``--test-output-size-failed <size>`` + .. versionadded:: 3.4 + Limit the output for failed tests to ``<size>`` bytes. +``--test-output-truncation <mode>`` + .. versionadded:: 3.24 + + Truncate ``tail`` (default), ``middle`` or ``head`` of test output once + maximum output size is reached. + ``--overwrite`` Overwrite CTest configuration option. diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json index 873c4ad..be5c791 100644 --- a/Help/manual/presets/example.json +++ b/Help/manual/presets/example.json @@ -1,5 +1,5 @@ { - "version": 4, + "version": 5, "cmakeMinimumRequired": { "major": 3, "minor": 23, diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 12f8b5e..c96405c 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -57,6 +57,21 @@ "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 5, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV3"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV5"}, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false } ], "required": [ @@ -673,6 +688,28 @@ "additionalProperties": false } }, + "testPresetsItemsV5": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", + "items": { + "type": "object", + "properties": { + "output": { + "type": "object", + "description": "An optional object specifying output options.", + "properties": { + "testOutputTruncation": { + "type": "string", + "description": "An optional string specifying the test output truncation mode. Equivalent to passing --test-output-truncation on the command line. Must be one of the following values: \"tail\", \"middle\", or \"head\".", + "enum": [ + "tail", "middle", "head" + ] + } + } + } + } + } + }, "testPresetsItemsV3": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", @@ -821,8 +858,7 @@ "type": "integer", "description": "An optional integer specifying the maximum width of a test name to output. Equivalent to passing --max-width on the command line." } - }, - "additionalProperties": false + } }, "filter": { "type": "object", @@ -998,6 +1034,39 @@ ] } }, + "testPresetsV5": { + "type": "array", + "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 5 and higher.", + "allOf": [ + { "$ref": "#/definitions/testPresetsItemsV2" }, + { "$ref": "#/definitions/testPresetsItemsV3" }, + { "$ref": "#/definitions/testPresetsItemsV5" } + ], + "items": { + "type": "object", + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "configurePreset": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "inheritConfigureEnvironment": {}, + "environment": {}, + "configuration": {}, + "overwriteConfigurationFile": {}, + "output": {}, + "filter": {}, + "execution": {}, + "condition": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "testPresetsV3": { "type": "array", "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.", |