diff --git a/.clang-format b/.clang-format index cba23d604..813a84d87 100644 --- a/.clang-format +++ b/.clang-format @@ -1,5 +1,5 @@ --- -# This configuration requires clang-format version 6.0 exactly. +# This configuration requires clang-format version 15 exactly. BasedOnStyle: Mozilla AlignOperands: false AllowShortFunctionsOnASingleLine: InlineOnly diff --git a/.clang-tidy b/.clang-tidy index a86f39acf..c790467ae 100644 --- a/.clang-tidy +++ b/.clang-tidy @@ -1,24 +1,31 @@ --- Checks: "-*,\ bugprone-*,\ +-bugprone-assignment-in-if-condition,\ -bugprone-easily-swappable-parameters,\ -bugprone-implicit-widening-of-multiplication-result,\ -bugprone-macro-parentheses,\ -bugprone-misplaced-widening-cast,\ -bugprone-narrowing-conversions,\ -bugprone-too-small-loop-variable,\ +-bugprone-unchecked-optional-access,\ misc-*,\ +-misc-confusable-identifiers,\ +-misc-const-correctness,\ -misc-no-recursion,\ -misc-non-private-member-variables-in-classes,\ -misc-static-assert,\ modernize-*,\ -modernize-avoid-c-arrays,\ +-modernize-macro-to-enum,\ -modernize-return-braced-init-list,\ +-modernize-use-emplace,\ -modernize-use-nodiscard,\ -modernize-use-noexcept,\ -modernize-use-trailing-return-type,\ -modernize-use-transparent-functors,\ performance-*,\ +-performance-inefficient-vector-operation,\ readability-*,\ -readability-convert-member-functions-to-static,\ -readability-function-cognitive-complexity,\ @@ -28,11 +35,17 @@ readability-*,\ -readability-implicit-bool-conversion,\ -readability-inconsistent-declaration-parameter-name,\ -readability-magic-numbers,\ +-readability-make-member-function-const,\ -readability-named-parameter,\ -readability-redundant-declaration,\ -readability-redundant-member-init,\ +-readability-simplify-boolean-expr,\ -readability-suspicious-call-argument,\ -readability-uppercase-literal-suffix,\ +cmake-*,\ +-cmake-ostringstream-use-cmstrcat,\ +-cmake-string-concatenation-use-cmstrcat,\ +-cmake-use-bespoke-enum-class,\ " HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$' CheckOptions: diff --git a/Auxiliary/vim/syntax/cmake.vim b/Auxiliary/vim/syntax/cmake.vim index 9eb993abf..5e936c29d 100644 --- a/Auxiliary/vim/syntax/cmake.vim +++ b/Auxiliary/vim/syntax/cmake.vim @@ -2013,6 +2013,7 @@ syn keyword cmakeKWExternalProject contained \ IGNORED \ INACTIVITY_TIMEOUT \ INDEPENDENT_STEP_TARGETS + \ INSTALL_BYPRODUCTS \ INSTALL_COMMAND \ INSTALL_DIR \ JOB_POOLS diff --git a/CMakeCPack.cmake b/CMakeCPack.cmake index 38fec3f91..798affd2f 100644 --- a/CMakeCPack.cmake +++ b/CMakeCPack.cmake @@ -264,5 +264,9 @@ set(CPACK_SOURCE_IGNORE_FILES "~$" ) +if(CMake_CPACK_CUSTOM_SCRIPT) + include(${CMake_CPACK_CUSTOM_SCRIPT}) +endif() + # include CPack model once all variables are set include(CPack) diff --git a/CMakeLists.txt b/CMakeLists.txt index 2b9eb2d56..0ce42fb3a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,14 +1,10 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -cmake_minimum_required(VERSION 3.13...3.23 FATAL_ERROR) +cmake_minimum_required(VERSION 3.13...3.24 FATAL_ERROR) set(CMAKE_USER_MAKE_RULES_OVERRIDE_C ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideC.cmake) set(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX ${CMAKE_CURRENT_SOURCE_DIR}/Source/Modules/OverrideCXX.cmake) -if(POLICY CMP0129) - cmake_policy(SET CMP0129 NEW) # CMake 3.23 -endif() - project(CMake) unset(CMAKE_USER_MAKE_RULES_OVERRIDE_CXX) unset(CMAKE_USER_MAKE_RULES_OVERRIDE_C) @@ -73,11 +69,7 @@ if(NOT DEFINED CMAKE_CXX_STANDARD AND NOT CMake_NO_CXX_STANDARD) if(CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.14) set(CMAKE_CXX_STANDARD 98) else() - if(NOT CMAKE_VERSION VERSION_LESS 3.8) - include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx17_check.cmake) - else() - set(CMake_CXX17_BROKEN 1) - endif() + include(${CMake_SOURCE_DIR}/Source/Checks/cm_cxx17_check.cmake) if(NOT CMake_CXX17_BROKEN) set(CMAKE_CXX_STANDARD 17) else() @@ -130,14 +122,12 @@ option(CMake_BUILD_DEVELOPER_REFERENCE mark_as_advanced(CMake_BUILD_DEVELOPER_REFERENCE) # option to build using interprocedural optimizations (IPO/LTO) -if(NOT CMAKE_VERSION VERSION_LESS 3.12.2) - option(CMake_BUILD_LTO "Compile CMake with link-time optimization if supported" OFF) - if(CMake_BUILD_LTO) - include(CheckIPOSupported) - check_ipo_supported(RESULT HAVE_IPO) - if(HAVE_IPO) - set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE) - endif() +option(CMake_BUILD_LTO "Compile CMake with link-time optimization if supported" OFF) +if(CMake_BUILD_LTO) + include(CheckIPOSupported) + check_ipo_supported(RESULT HAVE_IPO) + if(HAVE_IPO) + set(CMAKE_INTERPROCEDURAL_OPTIMIZATION TRUE) endif() endif() @@ -251,10 +241,6 @@ macro(CMAKE_SETUP_TESTING) configure_file(Tests/.NoDartCoverage Tests/.NoDartCoverage) configure_file(Tests/.NoDartCoverage Modules/.NoDartCoverage) configure_file(CTestCustom.cmake.in CTestCustom.cmake @ONLY) - if(BUILD_TESTING AND DART_ROOT) - configure_file(CMakeLogo.gif Testing/HTML/TestingResults/Icons/Logo.gif COPYONLY) - endif() - mark_as_advanced(DART_ROOT) endmacro() @@ -277,6 +263,25 @@ if(CMake_RUN_CLANG_TIDY) endif() set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_COMMAND}") + option(CMake_USE_CLANG_TIDY_MODULE "Use CMake's clang-tidy module." OFF) + if(CMake_USE_CLANG_TIDY_MODULE) + find_library(CMake_CLANG_TIDY_MODULE NAMES cmake-clang-tidy-module DOC "Location of the clang-tidy module") + if(NOT CMake_CLANG_TIDY_MODULE) + message(FATAL_ERROR "CMake_USE_CLANG_TIDY_MODULE is ON but cmake-clang-tidy-module is not found!") + endif() + list(APPEND CMAKE_CXX_CLANG_TIDY "--load=${CMake_CLANG_TIDY_MODULE}") + set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${CMake_CLANG_TIDY_MODULE}") + endif() + + set(CMake_CLANG_TIDY_EXPORT_FIXES_DIR "" CACHE PATH "Directory to put clang-tidy fix files in.") + mark_as_advanced(CMake_CLANG_TIDY_EXPORT_FIXES_DIR) + if(CMake_CLANG_TIDY_EXPORT_FIXES_DIR) + if(NOT IS_ABSOLUTE "${CMake_CLANG_TIDY_EXPORT_FIXES_DIR}") + message(FATAL_ERROR "CMake_CLANG_TIDY_EXPORT_FIXES_DIR must be an absolute path!") + endif() + set(CMAKE_CXX_CLANG_TIDY_EXPORT_FIXES_DIR "${CMake_CLANG_TIDY_EXPORT_FIXES_DIR}") + endif() + # Create a preprocessor definition that depends on .clang-tidy content so # the compile command will change when .clang-tidy changes. This ensures # that a subsequent build re-runs clang-tidy on all sources even if they @@ -286,6 +291,11 @@ if(CMake_RUN_CLANG_TIDY) file(SHA1 ${CMAKE_CURRENT_SOURCE_DIR}/.clang-tidy clang_tidy_sha1) set(CLANG_TIDY_DEFINITIONS "CLANG_TIDY_SHA1=${clang_tidy_sha1}") unset(clang_tidy_sha1) + if(CMake_USE_CLANG_TIDY_MODULE) + file(SHA1 "${CMake_CLANG_TIDY_MODULE}" clang_tidy_module_sha1) + list(APPEND CLANG_TIDY_DEFINITIONS "CLANG_TIDY_MODULE_SHA1=${clang_tidy_module_sha1}") + unset(clang_tidy_module_sha1) + endif() endif() configure_file(.clang-tidy .clang-tidy COPYONLY) @@ -299,6 +309,11 @@ if(CMake_RUN_IWYU) endif() set(CMAKE_CXX_INCLUDE_WHAT_YOU_USE "${IWYU_COMMAND};-Xiwyu;--mapping_file=${CMake_SOURCE_DIR}/Utilities/IWYU/mapping.imp;-w") + option(CMake_IWYU_VERBOSE "Run include-what-you-use in verbose mode" OFF) + if (CMake_IWYU_VERBOSE) + list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE + -Xiwyu -v7) + endif () list(APPEND CMAKE_CXX_INCLUDE_WHAT_YOU_USE ${CMake_IWYU_OPTIONS}) endif() @@ -342,9 +357,7 @@ endif() #----------------------------------------------------------------------- include(Source/CMakeVersion.cmake) -# Include the standard Dart testing module -enable_testing() -include(${CMAKE_ROOT}/Modules/Dart.cmake) +include(CTest) # Set up test-time configuration. set_directory_properties(PROPERTIES diff --git a/CompileFlags.cmake b/CompileFlags.cmake index bf8a08218..6331af11c 100644 --- a/CompileFlags.cmake +++ b/CompileFlags.cmake @@ -87,11 +87,6 @@ if (CMAKE_CXX_COMPILER_ID STREQUAL SunPro AND if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.13) if (NOT CMAKE_CXX_STANDARD OR CMAKE_CXX_STANDARD EQUAL 98) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++03") - elseif(CMAKE_VERSION VERSION_LESS 3.8.20170502) - # CMake knows how to add this flag for compilation as C++11, - # but has not been taught that SunPro needs it for linking too. - # Add it in a place that will be used for both. - set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11") endif() else() set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -library=stlport4") diff --git a/Copyright.txt b/Copyright.txt index bd45dd1f3..515e403a2 100644 --- a/Copyright.txt +++ b/Copyright.txt @@ -1,5 +1,5 @@ CMake - Cross Platform Makefile Generator -Copyright 2000-2022 Kitware, Inc. and Contributors +Copyright 2000-2023 Kitware, Inc. and Contributors All rights reserved. Redistribution and use in source and binary forms, with or without diff --git a/Help/command/DEVICE_LINK_OPTIONS.txt b/Help/command/DEVICE_LINK_OPTIONS.txt index 3d5020816..878754ddf 100644 --- a/Help/command/DEVICE_LINK_OPTIONS.txt +++ b/Help/command/DEVICE_LINK_OPTIONS.txt @@ -7,8 +7,6 @@ Host And Device Specific Link Options :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`, the raw options will be delivered to the host and device link steps (wrapped in ``-Xcompiler`` or equivalent for device link). Options wrapped with - ``$`` - :manual:`generator expression ` will be used - only for the device link step. Options wrapped with ``$`` - :manual:`generator expression ` will be used - only for the host link step. + :genex:`$` generator expression will be used + only for the device link step. Options wrapped with :genex:`$` + generator expression will be used only for the host link step. diff --git a/Help/command/GENEX_NOTE.txt b/Help/command/GENEX_NOTE.txt new file mode 100644 index 000000000..4a7906ce9 --- /dev/null +++ b/Help/command/GENEX_NOTE.txt @@ -0,0 +1,6 @@ +.. |more_see_also| replace:: See the :manual:`cmake-buildsystem(7)` manual + for more on defining buildsystem properties. + +Arguments to |command_name| may use generator expressions +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. |more_see_also| diff --git a/Help/command/SUPPORTED_LANGUAGES.txt b/Help/command/SUPPORTED_LANGUAGES.txt new file mode 100644 index 000000000..a98c07a5d --- /dev/null +++ b/Help/command/SUPPORTED_LANGUAGES.txt @@ -0,0 +1,25 @@ + +Supported languages are ``C``, ``CXX`` (i.e. C++), ``CSharp`` (i.e. C#), ``CUDA``, +``OBJC`` (i.e. Objective-C), ``OBJCXX`` (i.e. Objective-C++), ``Fortran``, ``HIP``, +``ISPC``, ``Swift``, ``ASM``, ``ASM_NASM``, ``ASM_MARMASM``, ``ASM_MASM``, and ``ASM-ATT``. + + .. versionadded:: 3.8 + Added ``CSharp`` and ``CUDA`` support. + + .. versionadded:: 3.15 + Added ``Swift`` support. + + .. versionadded:: 3.16 + Added ``OBJC`` and ``OBJCXX`` support. + + .. versionadded:: 3.18 + Added ``ISPC`` support. + + .. versionadded:: 3.21 + Added ``HIP`` support. + + .. versionadded:: 3.26 + Added ``ASM_MARMASM`` support. + +If enabling ``ASM``, list it last so that CMake can check whether +compilers for other languages like ``C`` work for assembly too. diff --git a/Help/command/add_compile_definitions.rst b/Help/command/add_compile_definitions.rst index 48e33be63..b2eb2af3b 100644 --- a/Help/command/add_compile_definitions.rst +++ b/Help/command/add_compile_definitions.rst @@ -21,7 +21,13 @@ Function-style definitions are not supported. CMake will automatically escape the value correctly for the native build system (note that CMake language syntax may require escapes to specify some values). -Arguments to ``add_compile_definitions`` may use "generator expressions" with -the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` -manual for available expressions. See the :manual:`cmake-buildsystem(7)` -manual for more on defining buildsystem properties. +.. versionadded:: 3.26 + Any leading ``-D`` on an item will be removed. + +.. |command_name| replace:: ``add_compile_definitions`` +.. include:: GENEX_NOTE.txt + +See Also +^^^^^^^^ + +* The command :command:`target_compile_definitions` adds target-specific definitions. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 36f403c8a..0ccebc679 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -14,10 +14,8 @@ directory and below. Arguments ^^^^^^^^^ -Arguments to ``add_compile_options`` may use "generator expressions" with -the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` -manual for available expressions. See the :manual:`cmake-buildsystem(7)` -manual for more on defining buildsystem properties. +.. |command_name| replace:: ``add_compile_options`` +.. include:: GENEX_NOTE.txt .. include:: OPTIONS_SHELL.txt @@ -30,22 +28,25 @@ this command is in a compiler-specific conditional clause: .. code-block:: cmake if (MSVC) - # warning level 4 and all warnings as errors - add_compile_options(/W4 /WX) + # warning level 4 + add_compile_options(/W4) else() - # lots of warnings and all warnings as errors - add_compile_options(-Wall -Wextra -pedantic -Werror) + # additional warnings + add_compile_options(-Wall -Wextra -Wpedantic) endif() +To set per-language options, use the :genex:`$` +or :genex:`$` generator expressions. + See Also ^^^^^^^^ -This command can be used to add any options. However, for -adding preprocessor definitions and include directories it is recommended -to use the more specific commands :command:`add_compile_definitions` -and :command:`include_directories`. +* This command can be used to add any options. However, for + adding preprocessor definitions and include directories it is recommended + to use the more specific commands :command:`add_compile_definitions` + and :command:`include_directories`. -The command :command:`target_compile_options` adds target-specific options. +* The command :command:`target_compile_options` adds target-specific options. -The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one -source file. +* The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one + source file. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 99adc85c1..293d3f01b 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -31,14 +31,12 @@ This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) that specifies any output of the custom command as a source file is given a rule to generate the file using the command at build time. -Do not list the output in more than one independent target that -may build in parallel or the two instances of the rule may conflict -(instead use the :command:`add_custom_target` command to drive the -command and make the other targets depend on that one). -In makefile terms this creates a new target in the following form:: - OUTPUT: MAIN_DEPENDENCY DEPENDS - COMMAND +Do not list the output in more than one independent target that +may build in parallel or the instances of the rule may conflict. +Instead, use the :command:`add_custom_target` command to drive the +command and make the other targets depend on that one. See the +`Example: Generating Files for Multiple Targets`_ below. The options are: @@ -140,6 +138,10 @@ The options are: Display the given message before the commands are executed at build time. + .. versionadded:: 3.26 + Arguments to ``COMMENT`` may use + :manual:`generator expressions `. + ``DEPENDS`` Specify files on which the command depends. Each argument is converted to a dependency as follows: @@ -229,15 +231,24 @@ The options are: ``OUTPUT`` Specify the output files the command is expected to produce. - If an output name is a relative path it will be interpreted - relative to the build tree directory corresponding to the - current source directory. Each output file will be marked with the :prop_sf:`GENERATED` source file property automatically. If the output of the custom command is not actually created as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` source file property. + If an output file name is a relative path, its absolute path is + determined by interpreting it relative to: + + 1. the build directory corresponding to the current source directory + (:variable:`CMAKE_CURRENT_BINARY_DIR`), or + + 2. the current source directory (:variable:`CMAKE_CURRENT_SOURCE_DIR`). + + The path in the build directory is preferred unless the path in the + source tree is mentioned as an absolute source file path elsewhere + in the current directory. + .. versionadded:: 3.20 Arguments to ``OUTPUT`` may use a restricted set of :manual:`generator expressions `. @@ -385,6 +396,49 @@ will re-run whenever ``in.txt`` changes. where ```` is the build configuration, and then compile the generated source as part of a library. +Example: Generating Files for Multiple Targets +"""""""""""""""""""""""""""""""""""""""""""""" + +If multiple independent targets need the same custom command output, +it must be attached to a single custom target on which they all depend. +Consider the following example: + +.. code-block:: cmake + + add_custom_command( + OUTPUT table.csv + COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat + -o table.csv + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat + VERBATIM) + add_custom_target(generate_table_csv DEPENDS table.csv) + + add_custom_command( + OUTPUT foo.cxx + COMMAND genFromTable -i table.csv -case foo -o foo.cxx + DEPENDS table.csv # file-level dependency + generate_table_csv # target-level dependency + VERBATIM) + add_library(foo foo.cxx) + + add_custom_command( + OUTPUT bar.cxx + COMMAND genFromTable -i table.csv -case bar -o bar.cxx + DEPENDS table.csv # file-level dependency + generate_table_csv # target-level dependency + VERBATIM) + add_library(bar bar.cxx) + +Output ``foo.cxx`` is needed only by target ``foo`` and output ``bar.cxx`` +is needed only by target ``bar``, but *both* targets need ``table.csv``, +transitively. Since ``foo`` and ``bar`` are independent targets that may +build concurrently, we prevent them from racing to generate ``table.csv`` +by placing its custom command in a separate target, ``generate_table_csv``. +The custom commands generating ``foo.cxx`` and ``bar.cxx`` each specify a +target-level dependency on ``generate_table_csv``, so the targets using them, +``foo`` and ``bar``, will not build until after target ``generate_table_csv`` +is built. + .. _`add_custom_command(TARGET)`: Build Events @@ -490,3 +544,8 @@ Ninja Multi-Config ``add_custom_command`` supports the :generator:`Ninja Multi-Config` generator's cross-config capabilities. See the generator documentation for more information. + +See Also +^^^^^^^^ + +* :command:`add_custom_target` diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index d8882ca99..545b9a5ae 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -109,6 +109,10 @@ The options are: Display the given message before the commands are executed at build time. + .. versionadded:: 3.26 + Arguments to ``COMMENT`` may use + :manual:`generator expressions `. + ``DEPENDS`` Reference files and outputs of custom commands created with :command:`add_custom_command` command calls in the same directory @@ -181,3 +185,8 @@ Ninja Multi-Config ``add_custom_target`` supports the :generator:`Ninja Multi-Config` generator's cross-config capabilities. See the generator documentation for more information. + +See Also +^^^^^^^^ + +* :command:`add_custom_command` diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index fe6918836..5c1f7b43b 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -1,7 +1,7 @@ add_definitions --------------- -Add -D define flags to the compilation of source files. +Add ``-D`` define flags to the compilation of source files. .. code-block:: cmake @@ -31,5 +31,8 @@ backwards compatibility. See documentation of the properties for details on adding preprocessor definitions to specific scopes and configurations. -See the :manual:`cmake-buildsystem(7)` manual for more on defining -buildsystem properties. +See Also +^^^^^^^^ + +* The :manual:`cmake-buildsystem(7)` manual for more on defining + buildsystem properties. diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index 14c018303..23cb4058f 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -20,7 +20,12 @@ transitively in its place since the target itself does not build. .. versionadded:: 3.3 Allow adding dependencies to interface libraries. -See the ``DEPENDS`` option of :command:`add_custom_target` and -:command:`add_custom_command` commands for adding file-level -dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS` -source file property to add file-level dependencies to object files. +See Also +^^^^^^^^ + +* The ``DEPENDS`` option of :command:`add_custom_target` and + :command:`add_custom_command` commands for adding file-level + dependencies in custom rules. + +* The :prop_sf:`OBJECT_DEPENDS` source file property to add + file-level dependencies to object files. diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index dde94293e..d9ea0da1a 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -107,3 +107,8 @@ The ```` may not be used to modify properties of ````, that is, it may not be used as the operand of :command:`set_property`, :command:`set_target_properties`, :command:`target_link_libraries` etc. An ``ALIAS`` target may not be installed or exported. + +See Also +^^^^^^^^ + +* :command:`add_library` diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 7dc4365e6..07c8babd2 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -83,10 +83,10 @@ Object Libraries Creates an :ref:`Object Library `. An object library compiles source files but does not archive or link their object files into a -library. Instead other targets created by :command:`add_library` or +library. Instead other targets created by ``add_library`` or :command:`add_executable` may reference the objects using an expression of the -form ``$`` as a source, where ``objlib`` is the -object library name. For example: +form :genex:`$\ ` as a source, where +``objlib`` is the object library name. For example: .. code-block:: cmake @@ -101,7 +101,7 @@ They may contain custom commands generating such sources, but not ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build systems (such as Xcode) may not like targets that have only object files, so consider adding at least one real source file to any target that references -``$``. +:genex:`$\ `. .. versionadded:: 3.12 Object libraries can be linked to with :command:`target_link_libraries`. @@ -261,3 +261,8 @@ to modify properties of ````, that is, it may not be used as the operand of :command:`set_property`, :command:`set_target_properties`, :command:`target_link_libraries` etc. An ``ALIAS`` target may not be installed or exported. + +See Also +^^^^^^^^ + +* :command:`add_executable` diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index f03e7c0e4..c09e10690 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -23,13 +23,18 @@ exist to add libraries (:command:`target_link_libraries` or since they do not use a linker. To add archiver or MSVC librarian flags, see the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property. -Arguments to ``add_link_options`` may use "generator expressions" with -the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` -manual for available expressions. See the :manual:`cmake-buildsystem(7)` -manual for more on defining buildsystem properties. +.. |command_name| replace:: ``add_link_options`` +.. include:: GENEX_NOTE.txt .. include:: DEVICE_LINK_OPTIONS.txt .. include:: OPTIONS_SHELL.txt .. include:: LINK_OPTIONS_LINKER.txt + +See Also +^^^^^^^^ + +* :command:`link_libraries` +* :command:`target_link_libraries` +* :command:`target_link_options` diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index 13cae1000..ae063e6d6 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -7,16 +7,16 @@ Add a subdirectory to the build. add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM]) -Adds a subdirectory to the build. The source_dir specifies the -directory in which the source CMakeLists.txt and code files are -located. If it is a relative path it will be evaluated with respect +Adds a subdirectory to the build. The ``source_dir`` specifies the +directory in which the source ``CMakeLists.txt`` and code files are +located. If it is a relative path, it will be evaluated with respect to the current directory (the typical usage), but it may also be an absolute path. The ``binary_dir`` specifies the directory in which to -place the output files. If it is a relative path it will be evaluated +place the output files. If it is a relative path, it will be evaluated with respect to the current output directory, but it may also be an absolute path. If ``binary_dir`` is not specified, the value of ``source_dir``, before expanding any relative path, will be used (the -typical usage). The CMakeLists.txt file in the specified source +typical usage). The ``CMakeLists.txt`` file in the specified source directory will be processed immediately by CMake before processing in the current input file continues beyond this command. @@ -28,15 +28,14 @@ meant for use when the subdirectory contains a separate part of the project that is useful but not necessary, such as a set of examples. Typically the subdirectory should contain its own :command:`project` command invocation so that a full build system will be generated in the -subdirectory (such as a VS IDE solution file). Note that inter-target -dependencies supersede this exclusion. If a target built by the -parent project depends on a target in the subdirectory, the dependee +subdirectory (such as a Visual Studio IDE solution file). Note that +inter-target dependencies supersede this exclusion. If a target built by +the parent project depends on a target in the subdirectory, the dependee target will be included in the parent project build system to satisfy the dependency. -If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory -property of the subdirectory will be set to true. This property is -used to initialize the :prop_tgt:`SYSTEM` property of each target -created in that subdirectory. The include directories of targets with -:prop_tgt:`SYSTEM` set to true will be treated as ``SYSTEM`` when -compiling consumers. +.. versionadded:: 3.25 + If the ``SYSTEM`` argument is provided, the :prop_dir:`SYSTEM` directory + property of the subdirectory will be set to true. This property is + used to initialize the :prop_tgt:`SYSTEM` property of each non-imported + target created in that subdirectory. diff --git a/Help/command/block.rst b/Help/command/block.rst index dfd60d446..a352e8365 100644 --- a/Help/command/block.rst +++ b/Help/command/block.rst @@ -71,6 +71,6 @@ inside the block. See Also ^^^^^^^^ - * :command:`endblock` - * :command:`return` - * :command:`cmake_policy` +* :command:`endblock` +* :command:`return` +* :command:`cmake_policy` diff --git a/Help/command/build_name.rst b/Help/command/build_name.rst index 2a1fbae62..5acf85830 100644 --- a/Help/command/build_name.rst +++ b/Help/command/build_name.rst @@ -5,7 +5,7 @@ Disallowed since version 3.0. See CMake Policy :policy:`CMP0036`. Use ``${CMAKE_SYSTEM}`` and ``${CMAKE_CXX_COMPILER}`` instead. -:: +.. code-block:: cmake build_name(variable) diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index c84c5b57b..76824ef1f 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -17,7 +17,7 @@ Synopsis Query host system specific information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +.. code-block:: cmake cmake_host_system_information(RESULT QUERY ...) diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index d15977049..031bd5690 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -79,3 +79,8 @@ invokes cmake_policy(VERSION 2.4[...]) which enables compatibility features for CMake 2.4 and lower. + +See Also +^^^^^^^^ + +* :command:`cmake_policy` diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index 7c85da610..0bb1d91bb 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -113,3 +113,9 @@ interpreted as the beginning of the new option. E.g. is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. + +See Also +^^^^^^^^ + +* :command:`function` +* :command:`macro` diff --git a/Help/command/cmake_path.rst b/Help/command/cmake_path.rst index eb7da07e3..4e6bedb65 100644 --- a/Help/command/cmake_path.rst +++ b/Help/command/cmake_path.rst @@ -237,7 +237,7 @@ The following forms of the ``GET`` subcommand each retrieve a different component or group of components from a path. See `Path Structure And Terminology`_ for the meaning of each path component. -:: +.. code-block:: cmake cmake_path(GET ROOT_NAME ) cmake_path(GET ROOT_DIRECTORY ) @@ -408,7 +408,7 @@ meaning of each path component. .. _HAS_RELATIVE_PART: .. _HAS_PARENT_PATH: -:: +.. code-block:: cmake cmake_path(HAS_ROOT_NAME ) cmake_path(HAS_ROOT_DIRECTORY ) @@ -432,7 +432,7 @@ Note the following special cases: .. _IS_ABSOLUTE: -:: +.. code-block:: cmake cmake_path(IS_ABSOLUTE ) @@ -446,7 +446,7 @@ false while ``HAS_ROOT_DIRECTORY`` can be true. .. _IS_RELATIVE: -:: +.. code-block:: cmake cmake_path(IS_RELATIVE ) @@ -454,7 +454,7 @@ This will store the opposite of ``IS_ABSOLUTE`` in ````. .. _IS_PREFIX: -:: +.. code-block:: cmake cmake_path(IS_PREFIX [NORMALIZE] ) @@ -476,7 +476,7 @@ are :ref:`normalized ` before the check. .. _Path COMPARE: .. _COMPARE: -:: +.. code-block:: cmake cmake_path(COMPARE EQUAL ) cmake_path(COMPARE NOT_EQUAL ) @@ -510,7 +510,7 @@ Modification .. _cmake_path-SET: -:: +.. code-block:: cmake cmake_path(SET [NORMALIZE] ) @@ -539,7 +539,7 @@ Output:: .. _APPEND: -:: +.. code-block:: cmake cmake_path(APPEND [...] [OUTPUT_VARIABLE ]) @@ -570,7 +570,7 @@ the following algorithm (pseudo-code) applies: .. _APPEND_STRING: -:: +.. code-block:: cmake cmake_path(APPEND_STRING [...] [OUTPUT_VARIABLE ]) @@ -579,7 +579,7 @@ Append all the ```` arguments to the ```` without adding any .. _REMOVE_FILENAME: -:: +.. code-block:: cmake cmake_path(REMOVE_FILENAME [OUTPUT_VARIABLE ]) @@ -609,7 +609,7 @@ Output:: .. _REPLACE_FILENAME: -:: +.. code-block:: cmake cmake_path(REPLACE_FILENAME [OUTPUT_VARIABLE ]) @@ -628,7 +628,7 @@ equivalent to the following: .. _REMOVE_EXTENSION: -:: +.. code-block:: cmake cmake_path(REMOVE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) @@ -637,7 +637,7 @@ Removes the :ref:`extension `, if any, from ````. .. _REPLACE_EXTENSION: -:: +.. code-block:: cmake cmake_path(REPLACE_EXTENSION [LAST_ONLY] [OUTPUT_VARIABLE ]) @@ -661,7 +661,7 @@ Generation .. _NORMAL_PATH: -:: +.. code-block:: cmake cmake_path(NORMAL_PATH [OUTPUT_VARIABLE ]) @@ -670,7 +670,7 @@ Normalize ```` according the steps described in :ref:`Normalization`. .. _cmake_path-RELATIVE_PATH: .. _RELATIVE_PATH: -:: +.. code-block:: cmake cmake_path(RELATIVE_PATH [BASE_DIRECTORY ] [OUTPUT_VARIABLE ]) @@ -686,7 +686,7 @@ as that used by C++ .. _ABSOLUTE_PATH: -:: +.. code-block:: cmake cmake_path(ABSOLUTE_PATH [BASE_DIRECTORY ] [NORMALIZE] [OUTPUT_VARIABLE ]) @@ -713,7 +713,7 @@ target platform when cross-compiling. .. _cmake_path-NATIVE_PATH: .. _NATIVE_PATH: -:: +.. code-block:: cmake cmake_path(NATIVE_PATH [NORMALIZE] ) @@ -727,7 +727,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized .. _cmake_path-TO_CMAKE_PATH_LIST: .. _TO_CMAKE_PATH_LIST: -:: +.. code-block:: cmake cmake_path(CONVERT TO_CMAKE_PATH_LIST [NORMALIZE]) @@ -749,7 +749,7 @@ When the ``NORMALIZE`` option is specified, the path is :ref:`normalized .. _cmake_path-TO_NATIVE_PATH_LIST: .. _TO_NATIVE_PATH_LIST: -:: +.. code-block:: cmake cmake_path(CONVERT TO_NATIVE_PATH_LIST [NORMALIZE]) @@ -788,7 +788,7 @@ Hashing .. _HASH: -:: +.. code-block:: cmake cmake_path(HASH ) diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index 54fc54815..cde74a733 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -150,3 +150,8 @@ use the pre-record policies when they are invoked. If the function or macro implementation sets policies, the changes automatically propagate up through callers until they reach the closest nested policy stack entry. + +See Also +^^^^^^^^ + +* :command:`cmake_minimum_required` diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 1d8142351..6f4cedfa6 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -58,7 +58,7 @@ or #define VAR 1 Input lines of the form ``#cmakedefine01 VAR ...`` will expand -as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 0``, +as ``#cmakedefine01 VAR ... 0`` or ``#cmakedefine01 VAR ... 1``, which may lead to undefined behavior. .. versionadded:: 3.10 @@ -174,11 +174,16 @@ Otherwise it will contain: /* #undef FOO_ENABLE */ /* #undef FOO_STRING */ -One may then use the :command:`include_directories` command to +One may then use the :command:`target_include_directories` command to specify the output directory as an include directory: .. code-block:: cmake - include_directories(${CMAKE_CURRENT_BINARY_DIR}) + target_include_directories( [SYSTEM] "${CMAKE_CURRENT_BINARY_DIR}") so that sources may include the header as ``#include ``. + +See Also +^^^^^^^^ + +* :command:`file(GENERATE)` diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 8c81f2d52..bce17396e 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -3,7 +3,7 @@ ctest_build Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_build([BUILD ] [APPEND] [CONFIGURATION ] diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index 95712aac0..f23dd2224 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst @@ -3,7 +3,7 @@ ctest_configure Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_configure([BUILD ] [SOURCE ] [APPEND] [OPTIONS ] [RETURN_VALUE ] [QUIET] diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index a6c643bbc..319c97855 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -3,7 +3,7 @@ ctest_coverage Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. -:: +.. code-block:: cmake ctest_coverage([BUILD ] [APPEND] [LABELS