diff options
Diffstat (limited to 'Help')
220 files changed, 4532 insertions, 2694 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index bd55e24c7b..21236fa427 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -140,21 +140,40 @@ If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows: |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_SYSTEM_PREFIX_PATH` -1. .. versionadded:: 3.12 - If called from within a find module or any other script loaded by a call to - :command:`find_package(<PackageName>)`, search prefixes unique to the - current package being found. Specifically, look in the - :variable:`<PackageName>_ROOT` CMake variable and the - :envvar:`<PackageName>_ROOT` environment variable. - The package root variables are maintained as a stack, so if called from - nested find modules or config packages, root paths from the parent's find - module or config package will be searched after paths from the current - module or package. In other words, the search order would be - ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, - ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. - See policy :policy:`CMP0074`. +1. If called from within a find module or any other script loaded by a call to + :command:`find_package(<PackageName>)`, search prefixes unique to the + current package being found. See policy :policy:`CMP0074`. + + .. versionadded:: 3.12 + + Specifically, search paths specified by the following variables, in order: + + a. :variable:`<PackageName>_ROOT` CMake variable, + where ``<PackageName>`` is the case-preserved package name. + + b. :variable:`<PACKAGENAME>_ROOT` CMake variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + c. :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the case-preserved package name. + + d. :envvar:`<PACKAGENAME>_ROOT` environment variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + The package root variables are maintained as a stack, so if called from + nested find modules or config packages, root paths from the parent's find + module or config package will be searched after paths from the current + module or package. In other words, the search order would be + ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``, + ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| diff --git a/Help/command/UNSET_NOTE.txt b/Help/command/UNSET_NOTE.txt new file mode 100644 index 0000000000..8dc912533d --- /dev/null +++ b/Help/command/UNSET_NOTE.txt @@ -0,0 +1,9 @@ +.. note:: + + When evaluating :ref:`Variable References` of the form ``${VAR}``, CMake + first searches for a normal variable with that name. If no such normal + variable exists, CMake will then search for a cache entry with that name. + Because of this, **unsetting a normal variable can expose a cache variable + that was previously hidden**. To force a variable reference of the form + ``${VAR}`` to return an empty string, use ``set(<variable> "")``, which + clears the normal variable but leaves it defined. diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 0ccebc679b..869d0c2ced 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -11,6 +11,11 @@ Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property. These options are used when compiling targets from the current directory and below. +.. note:: + + These options are not used when linking. + See the :command:`add_link_options` command for that. + Arguments ^^^^^^^^^ @@ -48,5 +53,15 @@ See Also * The command :command:`target_compile_options` adds target-specific options. +* This command adds compile options for all languages. + Use the :genex:`COMPILE_LANGUAGE` generator expression to specify + per-language compile options. + * The source file property :prop_sf:`COMPILE_OPTIONS` adds options to one source file. + +* :command:`add_link_options` adds options for linking. + +* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` + add language-wide flags passed to all invocations of the compiler. + This includes invocations that drive compiling and those that drive linking. diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 293d3f01bc..1ccd4348ec 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -25,7 +25,8 @@ The first signature is for adding a custom command to produce an output: [DEPFILE depfile] [JOB_POOL job_pool] [VERBATIM] [APPEND] [USES_TERMINAL] - [COMMAND_EXPAND_LISTS]) + [COMMAND_EXPAND_LISTS] + [DEPENDS_EXPLICIT_ONLY]) This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) @@ -357,6 +358,24 @@ The options are: :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, and the :generator:`Xcode` generator. +``DEPENDS_EXPLICIT_ONLY`` + + .. versionadded:: 3.27 + + Indicate that the command's ``DEPENDS`` argument represents all files + required by the command and implicit dependencies are not required. + + Without this option, if any target uses the output of the custom command, + CMake will consider that target's dependencies as implicit dependencies for + the custom command in case this custom command requires files implicitly + created by those targets. + + This option can be enabled on all custom commands by setting + :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to ``ON``. + + Only the :ref:`Ninja Generators` actually use this information to remove + unnecessary implicit dependencies. + Examples: Generating Files ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/add_link_options.rst b/Help/command/add_link_options.rst index c09e106908..df72715431 100644 --- a/Help/command/add_link_options.rst +++ b/Help/command/add_link_options.rst @@ -38,3 +38,7 @@ See Also * :command:`link_libraries` * :command:`target_link_libraries` * :command:`target_link_options` + +* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` + add language-wide flags passed to all invocations of the compiler. + This includes invocations that drive compiling and those that drive linking. diff --git a/Help/command/add_test.rst b/Help/command/add_test.rst index 53555a4b04..02dd3986aa 100644 --- a/Help/command/add_test.rst +++ b/Help/command/add_test.rst @@ -12,13 +12,24 @@ Add a test to the project to be run by :manual:`ctest(1)`. Adds a test called ``<name>``. The test name may contain arbitrary characters, expressed as a :ref:`Quoted Argument` or :ref:`Bracket Argument` -if necessary. See policy :policy:`CMP0110`. The options are: +if necessary. See policy :policy:`CMP0110`. + +CMake only generates tests if the :command:`enable_testing` command has been +invoked. The :module:`CTest` module invokes ``enable_testing`` automatically +unless ``BUILD_TESTING`` is set to ``OFF``. + +Tests added with the ``add_test(NAME)`` signature support using +:manual:`generator expressions <cmake-generator-expressions(7)>` +in test properties set by :command:`set_property(TEST)` or +:command:`set_tests_properties`. Test properties may only be set in the +directory the test is created in. + +``add_test`` options are: ``COMMAND`` - Specify the test command-line. If ``<command>`` specifies an - executable target (created by :command:`add_executable`) it will - automatically be replaced by the location of the executable created - at build time. + Specify the test command-line. If ``<command>`` specifies an executable + target created by :command:`add_executable`, it will automatically be + replaced by the location of the executable created at build time. The command may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>`. @@ -27,38 +38,29 @@ if necessary. See policy :policy:`CMP0110`. The options are: Restrict execution of the test only to the named configurations. ``WORKING_DIRECTORY`` - Set the :prop_test:`WORKING_DIRECTORY` test property to - specify the working directory in which to execute the test. - If not specified the test will be run with the current working - directory set to the build directory corresponding to the - current source directory. - - The working directory may be specified using - :manual:`generator expressions <cmake-generator-expressions(7)>`. + Set the test property :prop_test:`WORKING_DIRECTORY` in which to execute the + test. If not specified, the test will be run in + :variable:`CMAKE_CURRENT_BINARY_DIR`. The working directory may be specified + using :manual:`generator expressions <cmake-generator-expressions(7)>`. ``COMMAND_EXPAND_LISTS`` .. versionadded:: 3.16 - Lists in ``COMMAND`` arguments will be expanded, including those - created with + Lists in ``COMMAND`` arguments will be expanded, including those created with :manual:`generator expressions <cmake-generator-expressions(7)>`. -The given test command is expected to exit with code ``0`` to pass and -non-zero to fail, or vice-versa if the :prop_test:`WILL_FAIL` test -property is set. Any output written to stdout or stderr will be -captured by :manual:`ctest(1)` but does not affect the pass/fail status -unless the :prop_test:`PASS_REGULAR_EXPRESSION`, -:prop_test:`FAIL_REGULAR_EXPRESSION` or -:prop_test:`SKIP_REGULAR_EXPRESSION` test property is used. +If the test command exits with code ``0`` the test passes. Non-zero exit code +is a "failed" test. The test property :prop_test:`WILL_FAIL` inverts this +logic. Note that system-level test failures such as segmentation faults or +heap errors will still fail the test even if ``WILL_FALL`` is true. Output +written to stdout or stderr is captured by :manual:`ctest(1)` and only +affects the pass/fail status via the :prop_test:`PASS_REGULAR_EXPRESSION`, +:prop_test:`FAIL_REGULAR_EXPRESSION`, or :prop_test:`SKIP_REGULAR_EXPRESSION` +test properties. .. versionadded:: 3.16 Added :prop_test:`SKIP_REGULAR_EXPRESSION` property. -Tests added with the ``add_test(NAME)`` signature support using -:manual:`generator expressions <cmake-generator-expressions(7)>` -in test properties set by :command:`set_property(TEST)` or -:command:`set_tests_properties`. - Example usage: .. code-block:: cmake @@ -71,16 +73,9 @@ This creates a test ``mytest`` whose command runs a ``testDriver`` tool passing the configuration name and the full path to the executable file produced by target ``myexe``. -.. note:: - - CMake will generate tests only if the :command:`enable_testing` - command has been invoked. The :module:`CTest` module invokes the - command automatically unless the ``BUILD_TESTING`` option is turned - ``OFF``. - --------------------------------------------------------------------- -This command also supports a simpler, but less flexible, signature: +The command syntax above is recommended over the older, less flexible form: .. code-block:: cmake diff --git a/Help/command/cmake_language.rst b/Help/command/cmake_language.rst index 8801a9fdfe..707568cf79 100644 --- a/Help/command/cmake_language.rst +++ b/Help/command/cmake_language.rst @@ -27,163 +27,155 @@ those created via the :command:`macro` or :command:`function` commands. Calling Commands ^^^^^^^^^^^^^^^^ -.. _CALL: - -.. code-block:: cmake - +.. signature:: cmake_language(CALL <command> [<arg>...]) -Calls the named ``<command>`` with the given arguments (if any). -For example, the code: + Calls the named ``<command>`` with the given arguments (if any). + For example, the code: -.. code-block:: cmake + .. code-block:: cmake - set(message_command "message") - cmake_language(CALL ${message_command} STATUS "Hello World!") + set(message_command "message") + cmake_language(CALL ${message_command} STATUS "Hello World!") -is equivalent to + is equivalent to -.. code-block:: cmake + .. code-block:: cmake - message(STATUS "Hello World!") + message(STATUS "Hello World!") -.. note:: - To ensure consistency of the code, the following commands are not allowed: + .. note:: + To ensure consistency of the code, the following commands are not allowed: - * ``if`` / ``elseif`` / ``else`` / ``endif`` - * ``block`` / ``endblock`` - * ``while`` / ``endwhile`` - * ``foreach`` / ``endforeach`` - * ``function`` / ``endfunction`` - * ``macro`` / ``endmacro`` + * ``if`` / ``elseif`` / ``else`` / ``endif`` + * ``block`` / ``endblock`` + * ``while`` / ``endwhile`` + * ``foreach`` / ``endforeach`` + * ``function`` / ``endfunction`` + * ``macro`` / ``endmacro`` Evaluating Code ^^^^^^^^^^^^^^^ -.. _EVAL: - -.. code-block:: cmake - +.. signature:: cmake_language(EVAL CODE <code>...) + :target: EVAL -Evaluates the ``<code>...`` as CMake code. + Evaluates the ``<code>...`` as CMake code. -For example, the code: + For example, the code: -.. code-block:: cmake + .. code-block:: cmake - set(A TRUE) - set(B TRUE) - set(C TRUE) - set(condition "(A AND B) OR C") + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") - cmake_language(EVAL CODE " - if (${condition}) - message(STATUS TRUE) - else() - message(STATUS FALSE) - endif()" - ) + cmake_language(EVAL CODE " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) -is equivalent to + is equivalent to -.. code-block:: cmake + .. code-block:: cmake - set(A TRUE) - set(B TRUE) - set(C TRUE) - set(condition "(A AND B) OR C") - - file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " - if (${condition}) - message(STATUS TRUE) - else() - message(STATUS FALSE) - endif()" - ) + set(A TRUE) + set(B TRUE) + set(C TRUE) + set(condition "(A AND B) OR C") - include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) + file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake " + if (${condition}) + message(STATUS TRUE) + else() + message(STATUS FALSE) + endif()" + ) + + include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake) Deferring Calls ^^^^^^^^^^^^^^^ .. versionadded:: 3.19 -.. _DEFER: - -.. code-block:: cmake - +.. signature:: cmake_language(DEFER <options>... CALL <command> [<arg>...]) -Schedules a call to the named ``<command>`` with the given arguments (if any) -to occur at a later time. By default, deferred calls are executed as if -written at the end of the current directory's ``CMakeLists.txt`` file, -except that they run even after a :command:`return` call. Variable -references in arguments are evaluated at the time the deferred call is -executed. + Schedules a call to the named ``<command>`` with the given arguments (if any) + to occur at a later time. By default, deferred calls are executed as if + written at the end of the current directory's ``CMakeLists.txt`` file, + except that they run even after a :command:`return` call. Variable + references in arguments are evaluated at the time the deferred call is + executed. -The options are: + The options are: -``DIRECTORY <dir>`` - Schedule the call for the end of the given directory instead of the - current directory. The ``<dir>`` may reference either a source - directory or its corresponding binary directory. Relative paths are - treated as relative to the current source directory. + ``DIRECTORY <dir>`` + Schedule the call for the end of the given directory instead of the + current directory. The ``<dir>`` may reference either a source + directory or its corresponding binary directory. Relative paths are + treated as relative to the current source directory. - The given directory must be known to CMake, being either the top-level - directory or one added by :command:`add_subdirectory`. Furthermore, - the given directory must not yet be finished processing. This means - it can be the current directory or one of its ancestors. + The given directory must be known to CMake, being either the top-level + directory or one added by :command:`add_subdirectory`. Furthermore, + the given directory must not yet be finished processing. This means + it can be the current directory or one of its ancestors. -``ID <id>`` - Specify an identification for the deferred call. - The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``. - The ``<id>`` may begin with an underscore (``_``) only if it was generated - automatically by an earlier call that used ``ID_VAR`` to get the id. + ``ID <id>`` + Specify an identification for the deferred call. + The ``<id>`` may not be empty and may not begin with a capital letter ``A-Z``. + The ``<id>`` may begin with an underscore (``_``) only if it was generated + automatically by an earlier call that used ``ID_VAR`` to get the id. -``ID_VAR <var>`` - Specify a variable in which to store the identification for the - deferred call. If ``ID <id>`` is not given, a new identification - will be generated and the generated id will start with an underscore (``_``). + ``ID_VAR <var>`` + Specify a variable in which to store the identification for the + deferred call. If ``ID <id>`` is not given, a new identification + will be generated and the generated id will start with an underscore (``_``). -The currently scheduled list of deferred calls may be retrieved: + The currently scheduled list of deferred calls may be retrieved: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>) + cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>) -This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language -Lists>` of deferred call ids. The ids are for the directory scope in which -the calls have been deferred to (i.e. where they will be executed), which can -be different to the scope in which they were created. The ``DIRECTORY`` -option can be used to specify the scope for which to retrieve the call ids. -If that option is not given, the call ids for the current directory scope will -be returned. + This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language + Lists>` of deferred call ids. The ids are for the directory scope in which + the calls have been deferred to (i.e. where they will be executed), which can + be different to the scope in which they were created. The ``DIRECTORY`` + option can be used to specify the scope for which to retrieve the call ids. + If that option is not given, the call ids for the current directory scope + will be returned. -Details of a specific call may be retrieved from its id: + Details of a specific call may be retrieved from its id: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>) + cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>) -This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language -Lists>` in which the first element is the name of the command to be -called, and the remaining elements are its unevaluated arguments (any -contained ``;`` characters are included literally and cannot be distinguished -from multiple arguments). If multiple calls are scheduled with the same id, -this retrieves the first one. If no call is scheduled with the given id in -the specified ``DIRECTORY`` scope (or the current directory scope if no -``DIRECTORY`` option is given), this stores an empty string in the variable. + This will store in ``<var>`` a :ref:`semicolon-separated list <CMake Language + Lists>` in which the first element is the name of the command to be + called, and the remaining elements are its unevaluated arguments (any + contained ``;`` characters are included literally and cannot be distinguished + from multiple arguments). If multiple calls are scheduled with the same id, + this retrieves the first one. If no call is scheduled with the given id in + the specified ``DIRECTORY`` scope (or the current directory scope if no + ``DIRECTORY`` option is given), this stores an empty string in the variable. -Deferred calls may be canceled by their id: + Deferred calls may be canceled by their id: -.. code-block:: cmake + .. code-block:: cmake - cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...) + cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...) -This cancels all deferred calls matching any of the given ids in the specified -``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option -is given). Unknown ids are silently ignored. + This cancels all deferred calls matching any of the given ids in the specified + ``DIRECTORY`` scope (or the current directory scope if no ``DIRECTORY`` option + is given). Unknown ids are silently ignored. Deferred Call Examples """""""""""""""""""""" @@ -229,8 +221,6 @@ also prints:: Deferred Message 1 Deferred Message 2 - -.. _SET_DEPENDENCY_PROVIDER: .. _dependency_providers: Dependency Providers @@ -241,51 +231,50 @@ Dependency Providers .. note:: A high-level introduction to this feature can be found in the :ref:`Using Dependencies Guide <dependency_providers_overview>`. -.. code-block:: cmake - +.. signature:: cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...) -When a call is made to :command:`find_package` or -:command:`FetchContent_MakeAvailable`, the call may be forwarded to a -dependency provider which then has the opportunity to fulfill the request. -If the request is for one of the ``<methods>`` specified when the provider -was set, CMake calls the provider's ``<command>`` with a set of -method-specific arguments. If the provider does not fulfill the request, -or if the provider doesn't support the request's method, or no provider -is set, the built-in :command:`find_package` or -:command:`FetchContent_MakeAvailable` implementation is used to fulfill -the request in the usual way. - -One or more of the following values can be specified for the ``<methods>`` -when setting the provider: - -``FIND_PACKAGE`` - The provider command accepts :command:`find_package` requests. - -``FETCHCONTENT_MAKEAVAILABLE_SERIAL`` - The provider command accepts :command:`FetchContent_MakeAvailable` - requests. It expects each dependency to be fed to the provider command - one at a time, not the whole list in one go. - -Only one provider can be set at any point in time. If a provider is already -set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new -provider replaces the previously set one. The specified ``<command>`` must -already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. -As a special case, providing an empty string for the ``<command>`` and no -``<methods>`` will discard any previously set provider. - -The dependency provider can only be set while processing one of the files -specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable. -Thus, dependency providers can only be set as part of the first call to -:command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)`` -outside of that context will result in an error. - -.. note:: - The choice of dependency provider should always be under the user's control. - As a convenience, a project may choose to provide a file that users can - list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but - the use of such a file should always be the user's choice. + When a call is made to :command:`find_package` or + :command:`FetchContent_MakeAvailable`, the call may be forwarded to a + dependency provider which then has the opportunity to fulfill the request. + If the request is for one of the ``<methods>`` specified when the provider + was set, CMake calls the provider's ``<command>`` with a set of + method-specific arguments. If the provider does not fulfill the request, + or if the provider doesn't support the request's method, or no provider + is set, the built-in :command:`find_package` or + :command:`FetchContent_MakeAvailable` implementation is used to fulfill + the request in the usual way. + + One or more of the following values can be specified for the ``<methods>`` + when setting the provider: + + ``FIND_PACKAGE`` + The provider command accepts :command:`find_package` requests. + + ``FETCHCONTENT_MAKEAVAILABLE_SERIAL`` + The provider command accepts :command:`FetchContent_MakeAvailable` + requests. It expects each dependency to be fed to the provider command + one at a time, not the whole list in one go. + + Only one provider can be set at any point in time. If a provider is already + set when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called, the new + provider replaces the previously set one. The specified ``<command>`` must + already exist when ``cmake_language(SET_DEPENDENCY_PROVIDER)`` is called. + As a special case, providing an empty string for the ``<command>`` and no + ``<methods>`` will discard any previously set provider. + + The dependency provider can only be set while processing one of the files + specified by the :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable. + Thus, dependency providers can only be set as part of the first call to + :command:`project`. Calling ``cmake_language(SET_DEPENDENCY_PROVIDER)`` + outside of that context will result in an error. + + .. note:: + The choice of dependency provider should always be under the user's control. + As a convenience, a project may choose to provide a file that users can + list in their :variable:`CMAKE_PROJECT_TOP_LEVEL_INCLUDES` variable, but + the use of such a file should always be the user's choice. Provider commands """"""""""""""""" @@ -499,23 +488,21 @@ Getting current message log level .. versionadded:: 3.25 -.. _GET_MESSAGE_LOG_LEVEL: .. _query_message_log_level: -.. code-block:: cmake - +.. signature:: cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>) -Writes the current :command:`message` logging level -into the given ``<output_variable>``. + Writes the current :command:`message` logging level + into the given ``<output_variable>``. -See :command:`message` for the possible logging levels. + See :command:`message` for the possible logging levels. -The current message logging level can be set either using the -:option:`--log-level <cmake --log-level>` -command line option of the :manual:`cmake(1)` program or using -the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. + The current message logging level can be set either using the + :option:`--log-level <cmake --log-level>` + command line option of the :manual:`cmake(1)` program or using + the :variable:`CMAKE_MESSAGE_LOG_LEVEL` variable. -If both the command line option and the variable are set, the command line -option takes precedence. If neither are set, the default logging level -is returned. + If both the command line option and the variable are set, the command line + option takes precedence. If neither are set, the default logging level + is returned. diff --git a/Help/command/file.rst b/Help/command/file.rst index df895d080b..30a7f4de7b 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -26,7 +26,7 @@ Synopsis `Reading`_ file(`READ`_ <filename> <out-var> [...]) file(`STRINGS`_ <filename> <out-var> [...]) - file(`\<HASH\> <HASH_>`_ <filename> <out-var>) + file(`\<HASH\>`_ <filename> <out-var>) file(`TIMESTAMP`_ <filename> <out-var> [...]) file(`GET_RUNTIME_DEPENDENCIES`_ [...]) @@ -68,1202 +68,1184 @@ Synopsis Reading ^^^^^^^ -.. _READ: - -.. code-block:: cmake - +.. signature:: file(READ <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>] [HEX]) -Read content from a file called ``<filename>`` and store it in a -``<variable>``. Optionally start from the given ``<offset>`` and -read at most ``<max-in>`` bytes. The ``HEX`` option causes data to -be converted to a hexadecimal representation (useful for binary data). If the -``HEX`` option is specified, letters in the output (``a`` through ``f``) are in -lowercase. - -.. _STRINGS: - -.. code-block:: cmake + Read content from a file called ``<filename>`` and store it in a + ``<variable>``. Optionally start from the given ``<offset>`` and + read at most ``<max-in>`` bytes. The ``HEX`` option causes data to + be converted to a hexadecimal representation (useful for binary data). + If the ``HEX`` option is specified, letters in the output + (``a`` through ``f``) are in lowercase. +.. signature:: file(STRINGS <filename> <variable> [<options>...]) -Parse a list of ASCII strings from ``<filename>`` and store it in -``<variable>``. Binary data in the file are ignored. Carriage return -(``\r``, CR) characters are ignored. The options are: - -``LENGTH_MAXIMUM <max-len>`` - Consider only strings of at most a given length. + Parse a list of ASCII strings from ``<filename>`` and store it in + ``<variable>``. Binary data in the file are ignored. Carriage return + (``\r``, CR) characters are ignored. The options are: -``LENGTH_MINIMUM <min-len>`` - Consider only strings of at least a given length. + ``LENGTH_MAXIMUM <max-len>`` + Consider only strings of at most a given length. -``LIMIT_COUNT <max-num>`` - Limit the number of distinct strings to be extracted. + ``LENGTH_MINIMUM <min-len>`` + Consider only strings of at least a given length. -``LIMIT_INPUT <max-in>`` - Limit the number of input bytes to read from the file. + ``LIMIT_COUNT <max-num>`` + Limit the number of distinct strings to be extracted. -``LIMIT_OUTPUT <max-out>`` - Limit the number of total bytes to store in the ``<variable>``. + ``LIMIT_INPUT <max-in>`` + Limit the number of input bytes to read from the file. -``NEWLINE_CONSUME`` - Treat newline characters (``\n``, LF) as part of string content - instead of terminating at them. + ``LIMIT_OUTPUT <max-out>`` + Limit the number of total bytes to store in the ``<variable>``. -``NO_HEX_CONVERSION`` - Intel Hex and Motorola S-record files are automatically converted to - binary while reading unless this option is given. + ``NEWLINE_CONSUME`` + Treat newline characters (``\n``, LF) as part of string content + instead of terminating at them. -``REGEX <regex>`` - Consider only strings that match the given regular expression, - as described under :ref:`string(REGEX) <Regex Specification>`. + ``NO_HEX_CONVERSION`` + Intel Hex and Motorola S-record files are automatically converted to + binary while reading unless this option is given. -``ENCODING <encoding-type>`` - .. versionadded:: 3.1 + ``REGEX <regex>`` + Consider only strings that match the given regular expression, + as described under :ref:`string(REGEX) <Regex Specification>`. - Consider strings of a given encoding. Currently supported encodings are: - ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``. - If the ``ENCODING`` option is not provided and the file has a Byte Order Mark, - the ``ENCODING`` option will be defaulted to respect the Byte Order Mark. + ``ENCODING <encoding-type>`` + .. versionadded:: 3.1 - .. versionadded:: 3.2 - Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. + Consider strings of a given encoding. Currently supported encodings are: + ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``. + If the ``ENCODING`` option is not provided and the file + has a Byte Order Mark, the ``ENCODING`` option will be defaulted + to respect the Byte Order Mark. -For example, the code + .. versionadded:: 3.2 + Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings. -.. code-block:: cmake + For example, the code - file(STRINGS myfile.txt myfile) + .. code-block:: cmake -stores a list in the variable ``myfile`` in which each item is a line -from the input file. + file(STRINGS myfile.txt myfile) -.. _HASH: - -.. code-block:: cmake + stores a list in the variable ``myfile`` in which each item is a line + from the input file. +.. signature:: file(<HASH> <filename> <variable>) + :target: <HASH> -Compute a cryptographic hash of the content of ``<filename>`` and -store it in a ``<variable>``. The supported ``<HASH>`` algorithm names -are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` -command. - -.. _TIMESTAMP: - -.. code-block:: cmake + Compute a cryptographic hash of the content of ``<filename>`` and + store it in a ``<variable>``. The supported ``<HASH>`` algorithm names + are those listed by the :command:`string(<HASH>)` command. +.. signature:: file(TIMESTAMP <filename> <variable> [<format>] [UTC]) -Compute a string representation of the modification time of ``<filename>`` -and store it in ``<variable>``. Should the command be unable to obtain a -timestamp variable will be set to the empty string (""). - -See the :command:`string(TIMESTAMP)` command for documentation of -the ``<format>`` and ``UTC`` options. + Compute a string representation of the modification time of ``<filename>`` + and store it in ``<variable>``. Should the command be unable to obtain a + timestamp variable will be set to the empty string (""). -.. _GET_RUNTIME_DEPENDENCIES: + See the :command:`string(TIMESTAMP)` command for documentation of + the ``<format>`` and ``UTC`` options. -.. code-block:: cmake +.. signature:: + file(GET_RUNTIME_DEPENDENCIES [...]) - file(GET_RUNTIME_DEPENDENCIES - [RESOLVED_DEPENDENCIES_VAR <deps_var>] - [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] - [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] - [EXECUTABLES [<executable_files>...]] - [LIBRARIES [<library_files>...]] - [MODULES [<module_files>...]] - [DIRECTORIES [<directories>...]] - [BUNDLE_EXECUTABLE <bundle_executable_file>] - [PRE_INCLUDE_REGEXES [<regexes>...]] - [PRE_EXCLUDE_REGEXES [<regexes>...]] - [POST_INCLUDE_REGEXES [<regexes>...]] - [POST_EXCLUDE_REGEXES [<regexes>...]] - [POST_INCLUDE_FILES [<files>...]] - [POST_EXCLUDE_FILES [<files>...]] - ) + .. versionadded:: 3.16 -.. versionadded:: 3.16 + Recursively get the list of libraries depended on by the given files: -Recursively get the list of libraries depended on by the given files. + .. code-block:: cmake -Please note that this sub-command is not intended to be used in project mode. -It is intended for use at install time, either from code generated by the -:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by -the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. -For example: - -.. code-block:: cmake - - install(CODE [[ file(GET_RUNTIME_DEPENDENCIES - # ... + [RESOLVED_DEPENDENCIES_VAR <deps_var>] + [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>] + [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>] + [EXECUTABLES [<executable_files>...]] + [LIBRARIES [<library_files>...]] + [MODULES [<module_files>...]] + [DIRECTORIES [<directories>...]] + [BUNDLE_EXECUTABLE <bundle_executable_file>] + [PRE_INCLUDE_REGEXES [<regexes>...]] + [PRE_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_REGEXES [<regexes>...]] + [POST_EXCLUDE_REGEXES [<regexes>...]] + [POST_INCLUDE_FILES [<files>...]] + [POST_EXCLUDE_FILES [<files>...]] ) - ]]) - -The arguments are as follows: - -``RESOLVED_DEPENDENCIES_VAR <deps_var>`` - Name of the variable in which to store the list of resolved dependencies. - -``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` - Name of the variable in which to store the list of unresolved dependencies. - If this variable is not specified, and there are any unresolved dependencies, - an error is issued. - -``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` - Variable prefix in which to store conflicting dependency information. - Dependencies are conflicting if two files with the same name are found in - two different directories. The list of filenames that conflict are stored in - ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list of paths - that were found for that filename are stored in - ``<conflicting_deps_prefix>_<filename>``. - -``EXECUTABLES <executable_files>`` - List of executable files to read for dependencies. These are executables that - are typically created with :command:`add_executable`, but they do not have to - be created by CMake. On Apple platforms, the paths to these files determine - the value of ``@executable_path`` when recursively resolving the libraries. - Specifying any kind of library (``STATIC``, ``MODULE``, or ``SHARED``) here - will result in undefined behavior. - -``LIBRARIES <library_files>`` - List of library files to read for dependencies. These are libraries that are - typically created with :command:`add_library(SHARED)`, but they do not have - to be created by CMake. Specifying ``STATIC`` libraries, ``MODULE`` - libraries, or executables here will result in undefined behavior. - -``MODULES <module_files>`` - List of loadable module files to read for dependencies. These are modules - that are typically created with :command:`add_library(MODULE)`, but they do - not have to be created by CMake. They are typically used by calling - ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. - Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables here - will result in undefined behavior. - -``DIRECTORIES <directories>`` - List of additional directories to search for dependencies. On Linux - platforms, these directories are searched if the dependency is not found in - any of the other usual paths. If it is found in such a directory, a warning - is issued, because it means that the file is incomplete (it does not list all - of the directories that contain its dependencies). On Windows platforms, - these directories are searched if the dependency is not found in any of the - other search paths, but no warning is issued, because searching other paths - is a normal part of Windows dependency resolution. On Apple platforms, this - argument has no effect. - -``BUNDLE_EXECUTABLE <bundle_executable_file>`` - Executable to treat as the "bundle executable" when resolving libraries. On - Apple platforms, this argument determines the value of ``@executable_path`` - when recursively resolving libraries for ``LIBRARIES`` and ``MODULES`` files. - It has no effect on ``EXECUTABLES`` files. On other platforms, it has no - effect. This is typically (but not always) one of the executables in the - ``EXECUTABLES`` argument which designates the "main" executable of the - package. - -The following arguments specify filters for including or excluding libraries to -be resolved. See below for a full description of how they work. - -``PRE_INCLUDE_REGEXES <regexes>`` - List of pre-include regexes through which to filter the names of - not-yet-resolved dependencies. - -``PRE_EXCLUDE_REGEXES <regexes>`` - List of pre-exclude regexes through which to filter the names of - not-yet-resolved dependencies. - -``POST_INCLUDE_REGEXES <regexes>`` - List of post-include regexes through which to filter the names of resolved - dependencies. - -``POST_EXCLUDE_REGEXES <regexes>`` - List of post-exclude regexes through which to filter the names of resolved - dependencies. - -``POST_INCLUDE_FILES <files>`` - .. versionadded:: 3.21 - - List of post-include filenames through which to filter the names of resolved - dependencies. Symlinks are resolved when attempting to match these filenames. - -``POST_EXCLUDE_FILES <files>`` - .. versionadded:: 3.21 - - List of post-exclude filenames through which to filter the names of resolved - dependencies. Symlinks are resolved when attempting to match these filenames. - -These arguments can be used to exclude unwanted system libraries when -resolving the dependencies, or to include libraries from a specific -directory. The filtering works as follows: - -1. If the not-yet-resolved dependency matches any of the - ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency - resolution proceeds to step 4. -2. If the not-yet-resolved dependency matches any of the - ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. -3. Otherwise, dependency resolution proceeds. -4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according to - the linking rules of the platform (see below). -5. If the dependency is found, and its full path matches one of the - ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added - to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` - recursively resolves that library's own dependencies. Otherwise, resolution - proceeds to step 6. -6. If the dependency is found, but its full path matches one of the - ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the - resolved dependencies, and dependency resolution stops for that dependency. -7. If the dependency is found, and its full path does not match either - ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, - or ``POST_EXCLUDE_FILES``, the full path is added to the resolved - dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves - that library's own dependencies. - -Different platforms have different rules for how dependencies are resolved. -These specifics are described here. - -On Linux platforms, library resolution works as follows: - -1. If the depending file does not have any ``RUNPATH`` entries, and the library - exists in one of the depending file's ``RPATH`` entries, or its parents', in - that order, the dependency is resolved to that file. -2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the - library exists in one of those entries, the dependency is resolved to that - file. -3. Otherwise, if the library exists in one of the directories listed by - ``ldconfig``, the dependency is resolved to that file. -4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, the - dependency is resolved to that file. In this case, a warning is issued, - because finding a file in one of the ``DIRECTORIES`` means that the - depending file is not complete (it does not list all the directories from - which it pulls dependencies). -5. Otherwise, the dependency is unresolved. - -On Windows platforms, library resolution works as follows: - -1. The dependent DLL name is converted to lowercase. Windows DLL names are - case-insensitive, and some linkers mangle the case of the DLL dependency - names. However, this makes it more difficult for ``PRE_INCLUDE_REGEXES``, - ``PRE_EXCLUDE_REGEXES``, ``POST_INCLUDE_REGEXES``, and - ``POST_EXCLUDE_REGEXES`` to properly filter DLL names - every regex would - have to check for both uppercase and lowercase letters. For example: - - .. code-block:: cmake - - file(GET_RUNTIME_DEPENDENCIES - # ... - PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" - ) - - Converting the DLL name to lowercase allows the regexes to only match - lowercase names, thus simplifying the regex. For example: - - .. code-block:: cmake - - file(GET_RUNTIME_DEPENDENCIES - # ... - PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" - ) - - This regex will match ``mylibrary.dll`` regardless of how it is cased, - either on disk or in the depending file. (For example, it will match - ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) - - Please note that the directory portion of any resolved DLLs retains its - casing and is not converted to lowercase. Only the filename portion is - converted. - -2. (**Not yet implemented**) If the depending file is a Windows Store app, and - the dependency is listed as a dependency in the application's package - manifest, the dependency is resolved to that file. -3. Otherwise, if the library exists in the same directory as the depending - file, the dependency is resolved to that file. -4. Otherwise, if the library exists in either the operating system's - ``system32`` directory or the ``Windows`` directory, in that order, the - dependency is resolved to that file. -5. Otherwise, if the library exists in one of the directories specified by - ``DIRECTORIES``, in the order they are listed, the dependency is resolved to - that file. In this case, a warning is not issued, because searching other - directories is a normal part of Windows library resolution. -6. Otherwise, the dependency is unresolved. - -On Apple platforms, library resolution works as follows: - -1. If the dependency starts with ``@executable_path/``, and an ``EXECUTABLES`` - argument is in the process of being resolved, and replacing - ``@executable_path/`` with the directory of the executable yields an - existing file, the dependency is resolved to that file. -2. Otherwise, if the dependency starts with ``@executable_path/``, and there is - a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` with - the directory of the bundle executable yields an existing file, the - dependency is resolved to that file. -3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing - ``@loader_path/`` with the directory of the depending file yields an - existing file, the dependency is resolved to that file. -4. Otherwise, if the dependency starts with ``@rpath/``, and replacing - ``@rpath/`` with one of the ``RPATH`` entries of the depending file yields - an existing file, the dependency is resolved to that file. Note that - ``RPATH`` entries that start with ``@executable_path/`` or ``@loader_path/`` - also have these items replaced with the appropriate path. -5. Otherwise, if the dependency is an absolute file that exists, the dependency - is resolved to that file. -6. Otherwise, the dependency is unresolved. - -This function accepts several variables that determine which tool is used for -dependency resolution: - -.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM - - Determines which operating system and executable format the files are built - for. This could be one of several values: - - * ``linux+elf`` - * ``windows+pe`` - * ``macos+macho`` - - If this variable is not specified, it is determined automatically by system - introspection. - -.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL - - Determines the tool to use for dependency resolution. It could be one of - several values, depending on the value of - :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: - - ================================================= ============================================= - ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` - ================================================= ============================================= - ``linux+elf`` ``objdump`` - ``windows+pe`` ``dumpbin`` - ``windows+pe`` ``objdump`` - ``macos+macho`` ``otool`` - ================================================= ============================================= - - If this variable is not specified, it is determined automatically by system - introspection. - -.. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND - - Determines the path to the tool to use for dependency resolution. This is the - actual path to ``objdump``, ``dumpbin``, or ``otool``. - - If this variable is not specified, it is determined by the value of - ``CMAKE_OBJDUMP`` if set, else by system introspection. - - .. versionadded:: 3.18 - Use ``CMAKE_OBJDUMP`` if set. - -Writing -^^^^^^^ - -.. _WRITE: -.. _APPEND: - -.. code-block:: cmake - - file(WRITE <filename> <content>...) - file(APPEND <filename> <content>...) - -Write ``<content>`` into a file called ``<filename>``. If the file does -not exist, it will be created. If the file already exists, ``WRITE`` -mode will overwrite it and ``APPEND`` mode will append to the end. -Any directories in the path specified by ``<filename>`` that do not -exist will be created. - -If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes. - -.. _TOUCH: -.. _TOUCH_NOCREATE: - -.. code-block:: cmake - - file(TOUCH [<files>...]) - file(TOUCH_NOCREATE [<files>...]) - -.. versionadded:: 3.12 -Create a file with no content if it does not yet exist. If the file already -exists, its access and/or modification will be updated to the time when the -function call is executed. + Please note that this sub-command is not intended to be used in project mode. + It is intended for use at install time, either from code generated by the + :command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by + the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. + For example: + + .. code-block:: cmake + + install(CODE [[ + file(GET_RUNTIME_DEPENDENCIES + # ... + ) + ]]) + + The arguments are as follows: + + ``RESOLVED_DEPENDENCIES_VAR <deps_var>`` + Name of the variable in which to store the list of resolved dependencies. + + ``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>`` + Name of the variable in which to store the list of unresolved + dependencies. If this variable is not specified, and there are any + unresolved dependencies, an error is issued. + + ``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>`` + Variable prefix in which to store conflicting dependency information. + Dependencies are conflicting if two files with the same name are found in + two different directories. The list of filenames that conflict are stored + in ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list + of paths that were found for that filename are stored in + ``<conflicting_deps_prefix>_<filename>``. + + ``EXECUTABLES <executable_files>`` + List of executable files to read for dependencies. These are executables + that are typically created with :command:`add_executable`, but they do + not have to be created by CMake. On Apple platforms, the paths to these + files determine the value of ``@executable_path`` when recursively + resolving the libraries. Specifying any kind of library (``STATIC``, + ``MODULE``, or ``SHARED``) here will result in undefined behavior. + + ``LIBRARIES <library_files>`` + List of library files to read for dependencies. These are libraries that + are typically created with :command:`add_library(SHARED)`, but they do + not have to be created by CMake. Specifying ``STATIC`` libraries, + ``MODULE`` libraries, or executables here will result in undefined + behavior. + + ``MODULES <module_files>`` + List of loadable module files to read for dependencies. These are modules + that are typically created with :command:`add_library(MODULE)`, but they + do not have to be created by CMake. They are typically used by calling + ``dlopen()`` at runtime rather than linked at link time with ``ld -l``. + Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables + here will result in undefined behavior. + + ``DIRECTORIES <directories>`` + List of additional directories to search for dependencies. On Linux + platforms, these directories are searched if the dependency is not found + in any of the other usual paths. If it is found in such a directory, a + warning is issued, because it means that the file is incomplete (it does + not list all of the directories that contain its dependencies). + On Windows platforms, these directories are searched if the dependency + is not found in any of the other search paths, but no warning is issued, + because searching other paths is a normal part of Windows dependency + resolution. On Apple platforms, this argument has no effect. + + ``BUNDLE_EXECUTABLE <bundle_executable_file>`` + Executable to treat as the "bundle executable" when resolving libraries. + On Apple platforms, this argument determines the value of + ``@executable_path`` when recursively resolving libraries for + ``LIBRARIES`` and ``MODULES`` files. It has no effect on ``EXECUTABLES`` + files. On other platforms, it has no effect. This is typically (but not + always) one of the executables in the ``EXECUTABLES`` argument which + designates the "main" executable of the package. + + The following arguments specify filters for including or excluding libraries + to be resolved. See below for a full description of how they work. + + ``PRE_INCLUDE_REGEXES <regexes>`` + List of pre-include regexes through which to filter the names of + not-yet-resolved dependencies. + + ``PRE_EXCLUDE_REGEXES <regexes>`` + List of pre-exclude regexes through which to filter the names of + not-yet-resolved dependencies. + + ``POST_INCLUDE_REGEXES <regexes>`` + List of post-include regexes through which to filter the names of + resolved dependencies. + + ``POST_EXCLUDE_REGEXES <regexes>`` + List of post-exclude regexes through which to filter the names of + resolved dependencies. + + ``POST_INCLUDE_FILES <files>`` + .. versionadded:: 3.21 + + List of post-include filenames through which to filter the names of + resolved dependencies. Symlinks are resolved when attempting to match + these filenames. + + ``POST_EXCLUDE_FILES <files>`` + .. versionadded:: 3.21 + + List of post-exclude filenames through which to filter the names of + resolved dependencies. Symlinks are resolved when attempting to match + these filenames. + + These arguments can be used to exclude unwanted system libraries when + resolving the dependencies, or to include libraries from a specific + directory. The filtering works as follows: + + 1. If the not-yet-resolved dependency matches any of the + ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency + resolution proceeds to step 4. + + 2. If the not-yet-resolved dependency matches any of the + ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency. + + 3. Otherwise, dependency resolution proceeds. + + 4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according + to the linking rules of the platform (see below). + + 5. If the dependency is found, and its full path matches one of the + ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added + to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` + recursively resolves that library's own dependencies. Otherwise, resolution + proceeds to step 6. + + 6. If the dependency is found, but its full path matches one of the + ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the + resolved dependencies, and dependency resolution stops for that dependency. + + 7. If the dependency is found, and its full path does not match either + ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``, + or ``POST_EXCLUDE_FILES``, the full path is added to the resolved + dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)`` recursively resolves + that library's own dependencies. + + Different platforms have different rules for how dependencies are resolved. + These specifics are described here. + + On Linux platforms, library resolution works as follows: + + 1. If the depending file does not have any ``RUNPATH`` entries, and the + library exists in one of the depending file's ``RPATH`` entries, or its + parents', in that order, the dependency is resolved to that file. + 2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the + library exists in one of those entries, the dependency is resolved to that + file. + 3. Otherwise, if the library exists in one of the directories listed by + ``ldconfig``, the dependency is resolved to that file. + 4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries, + the dependency is resolved to that file. In this case, a warning is + issued, because finding a file in one of the ``DIRECTORIES`` means that + the depending file is not complete (it does not list all the directories + from which it pulls dependencies). + + 5. Otherwise, the dependency is unresolved. -Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file -does not exist it will be silently ignored. + On Windows platforms, library resolution works as follows: -With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be -modified. + 1. DLL dependency names are converted to lowercase for matching filters. + Windows DLL names are case-insensitive, and some linkers mangle the + case of the DLL dependency names. However, this makes it more difficult + for ``PRE_INCLUDE_REGEXES``, ``PRE_EXCLUDE_REGEXES``, + ``POST_INCLUDE_REGEXES``, and ``POST_EXCLUDE_REGEXES`` to properly + filter DLL names - every regex would have to check for both uppercase + and lowercase letters. For example: -.. _GENERATE: + .. code-block:: cmake -.. code-block:: cmake + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$" + ) - file(GENERATE OUTPUT output-file - <INPUT input-file|CONTENT content> - [CONDITION expression] [TARGET target] - [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | - FILE_PERMISSIONS <permissions>...] - [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) - -Generate an output file for each build configuration supported by the current -:manual:`CMake Generator <cmake-generators(7)>`. Evaluate -:manual:`generator expressions <cmake-generator-expressions(7)>` -from the input content to produce the output content. The options are: + Converting the DLL name to lowercase allows the regexes to only match + lowercase names, thus simplifying the regex. For example: -``CONDITION <condition>`` - Generate the output file for a particular configuration only if - the condition is true. The condition must be either ``0`` or ``1`` - after evaluating generator expressions. + .. code-block:: cmake -``CONTENT <content>`` - Use the content given explicitly as input. + file(GET_RUNTIME_DEPENDENCIES + # ... + PRE_INCLUDE_REGEXES "^mylibrary\\.dll$" + ) -``INPUT <input-file>`` - Use the content from a given file as input. + This regex will match ``mylibrary.dll`` regardless of how it is cased, + either on disk or in the depending file. (For example, it will match + ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.) - .. versionchanged:: 3.10 - A relative path is treated with respect to the value of - :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. + .. versionchanged:: 3.27 -``OUTPUT <output-file>`` - Specify the output file name to generate. Use generator expressions - such as :genex:`$<CONFIG>` to specify a configuration-specific - output file name. Multiple configurations may generate the same output - file only if the generated content is identical. Otherwise, the - ``<output-file>`` must evaluate to an unique name for each configuration. + The conversion to lowercase only applies while matching filters. + Results reported after filtering case-preserve each DLL name as it is + found on disk, if resolved, and otherwise as it is referenced by the + dependent binary. - .. versionchanged:: 3.10 - A relative path (after evaluating generator expressions) is treated - with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - See policy :policy:`CMP0070`. + Prior to CMake 3.27, the results were reported with lowercase DLL + file names, but the directory portion retained its casing. -``TARGET <target>`` - .. versionadded:: 3.19 + 2. (**Not yet implemented**) If the depending file is a Windows Store app, + and the dependency is listed as a dependency in the application's package + manifest, the dependency is resolved to that file. - Specify which target to use when evaluating generator expressions that - require a target for evaluation (e.g. - :genex:`$<COMPILE_FEATURES:...>`, - :genex:`$<TARGET_PROPERTY:prop>`). + 3. Otherwise, if the library exists in the same directory as the depending + file, the dependency is resolved to that file. -``NO_SOURCE_PERMISSIONS`` - .. versionadded:: 3.20 + 4. Otherwise, if the library exists in either the operating system's + ``system32`` directory or the ``Windows`` directory, in that order, the + dependency is resolved to that file. - The generated file permissions default to the standard 644 value - (-rw-r--r--). + 5. Otherwise, if the library exists in one of the directories specified by + ``DIRECTORIES``, in the order they are listed, the dependency is resolved + to that file. In this case, a warning is not issued, because searching + other directories is a normal part of Windows library resolution. -``USE_SOURCE_PERMISSIONS`` - .. versionadded:: 3.20 + 6. Otherwise, the dependency is unresolved. - Transfer the file permissions of the ``INPUT`` file to the generated file. - This is already the default behavior if none of the three permissions-related - keywords are given (``NO_SOURCE_PERMISSIONS``, ``USE_SOURCE_PERMISSIONS`` - or ``FILE_PERMISSIONS``). The ``USE_SOURCE_PERMISSIONS`` keyword mostly - serves as a way of making the intended behavior clearer at the call site. - It is an error to specify this option without ``INPUT``. + On Apple platforms, library resolution works as follows: -``FILE_PERMISSIONS <permissions>...`` - .. versionadded:: 3.20 + 1. If the dependency starts with ``@executable_path/``, and an + ``EXECUTABLES`` argument is in the process of being resolved, and + replacing ``@executable_path/`` with the directory of the executable + yields an existing file, the dependency is resolved to that file. - Use the specified permissions for the generated file. + 2. Otherwise, if the dependency starts with ``@executable_path/``, and there + is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/`` + with the directory of the bundle executable yields an existing file, the + dependency is resolved to that file. -``NEWLINE_STYLE <style>`` - .. versionadded:: 3.20 + 3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing + ``@loader_path/`` with the directory of the depending file yields an + existing file, the dependency is resolved to that file. - Specify the newline style for the generated file. Specify - ``UNIX`` or ``LF`` for ``\n`` newlines, or specify - ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + 4. Otherwise, if the dependency starts with ``@rpath/``, and replacing + ``@rpath/`` with one of the ``RPATH`` entries of the depending file + yields an existing file, the dependency is resolved to that file. + Note that ``RPATH`` entries that start with ``@executable_path/`` or + ``@loader_path/`` also have these items replaced with the appropriate + path. -Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific -``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified and their timestamp updated on subsequent cmake -runs only if their content is changed. + 5. Otherwise, if the dependency is an absolute file that exists, + the dependency is resolved to that file. -Note also that ``file(GENERATE)`` does not create the output file until the -generation phase. The output file will not yet have been written when the -``file(GENERATE)`` command returns, it is written only after processing all -of a project's ``CMakeLists.txt`` files. + 6. Otherwise, the dependency is unresolved. -.. _CONFIGURE: + This function accepts several variables that determine which tool is used for + dependency resolution: -.. code-block:: cmake + .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM - file(CONFIGURE OUTPUT output-file - CONTENT content - [ESCAPE_QUOTES] [@ONLY] - [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + Determines which operating system and executable format the files are built + for. This could be one of several values: -.. versionadded:: 3.18 + * ``linux+elf`` + * ``windows+pe`` + * ``macos+macho`` -Generate an output file using the input given by ``CONTENT`` and substitute -variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The -substitution rules behave the same as the :command:`configure_file` command. -In order to match :command:`configure_file`'s behavior, generator expressions -are not supported for both ``OUTPUT`` and ``CONTENT``. + If this variable is not specified, it is determined automatically by system + introspection. -The arguments are: + .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL -``OUTPUT <output-file>`` - Specify the output file name to generate. A relative path is treated with - respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. - ``<output-file>`` does not support generator expressions. + Determines the tool to use for dependency resolution. It could be one of + several values, depending on the value of + :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`: -``CONTENT <content>`` - Use the content given explicitly as input. - ``<content>`` does not support generator expressions. + ================================================= ============================================= + ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`` ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL`` + ================================================= ============================================= + ``linux+elf`` ``objdump`` + ``windows+pe`` ``objdump`` or ``dumpbin`` + ``macos+macho`` ``otool`` + ================================================= ============================================= -``ESCAPE_QUOTES`` - Escape any substituted quotes with backslashes (C-style). - -``@ONLY`` - Restrict variable replacement to references of the form ``@VAR@``. - This is useful for configuring scripts that use ``${VAR}`` syntax. - -``NEWLINE_STYLE <style>`` - Specify the newline style for the output file. Specify - ``UNIX`` or ``LF`` for ``\n`` newlines, or specify - ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. - -Filesystem -^^^^^^^^^^ - -.. _GLOB: -.. _GLOB_RECURSE: - -.. code-block:: cmake - - file(GLOB <variable> - [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] - [<globbing-expressions>...]) - file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] - [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] - [<globbing-expressions>...]) + If this variable is not specified, it is determined automatically by system + introspection. -Generate a list of files that match the ``<globbing-expressions>`` and -store it into the ``<variable>``. Globbing expressions are similar to -regular expressions, but much simpler. If ``RELATIVE`` flag is -specified, the results will be returned as relative paths to the given -path. + .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND -.. versionchanged:: 3.6 - The results will be ordered lexicographically. + Determines the path to the tool to use for dependency resolution. This is + the actual path to ``objdump``, ``dumpbin``, or ``otool``. -On Windows and macOS, globbing is case-insensitive even if the underlying -filesystem is case-sensitive (both filenames and globbing expressions are -converted to lowercase before matching). On other platforms, globbing is -case-sensitive. + If this variable is not specified, it is determined by the value of + ``CMAKE_OBJDUMP`` if set, else by system introspection. -.. versionadded:: 3.3 - By default ``GLOB`` lists directories - directories are omitted in result if - ``LIST_DIRECTORIES`` is set to false. + .. versionadded:: 3.18 + Use ``CMAKE_OBJDUMP`` if set. -.. versionadded:: 3.12 - If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic - to the main build system check target to rerun the flagged ``GLOB`` commands - at build time. If any of the outputs change, CMake will regenerate the build - system. +Writing +^^^^^^^ -.. note:: - We do not recommend using GLOB to collect a list of source files from - your source tree. If no CMakeLists.txt file changes when a source is - added or removed then the generated build system cannot know when to - ask CMake to regenerate. - The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or if - a new generator is added in the future that cannot support it, projects using - it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there is - still a cost to perform the check on every rebuild. +.. signature:: + file(WRITE <filename> <content>...) + file(APPEND <filename> <content>...) -Examples of globbing expressions include:: + Write ``<content>`` into a file called ``<filename>``. If the file does + not exist, it will be created. If the file already exists, ``WRITE`` + mode will overwrite it and ``APPEND`` mode will append to the end. + Any directories in the path specified by ``<filename>`` that do not + exist will be created. - *.cxx - match all files with extension cxx - *.vt? - match all files with extension vta,...,vtz - f[3-5].txt - match files f3.txt, f4.txt, f5.txt + If the file is a build input, use the :command:`configure_file` command + to update the file only when its content changes. -The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the -matched directory and match the files. Subdirectories that are symlinks -are only traversed if ``FOLLOW_SYMLINKS`` is given or policy -:policy:`CMP0009` is not set to ``NEW``. +.. signature:: + file(TOUCH [<files>...]) + file(TOUCH_NOCREATE [<files>...]) -.. versionadded:: 3.3 - By default ``GLOB_RECURSE`` omits directories from result list - setting - ``LIST_DIRECTORIES`` to true adds directories to result list. - If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to - ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. + .. versionadded:: 3.12 -Examples of recursive globbing include:: + Create a file with no content if it does not yet exist. If the file already + exists, its access and/or modification will be updated to the time when the + function call is executed. - /dir/*.py - match all python files in /dir and subdirectories + Use ``TOUCH_NOCREATE`` to touch a file if it exists but not create it. + If a file does not exist it will be silently ignored. -.. _MAKE_DIRECTORY: + With ``TOUCH`` and ``TOUCH_NOCREATE``, the contents of an existing file + will not be modified. -.. code-block:: cmake +.. signature:: + file(GENERATE [...]) - file(MAKE_DIRECTORY [<directories>...]) + Generate an output file for each build configuration supported by the current + :manual:`CMake Generator <cmake-generators(7)>`. Evaluate + :manual:`generator expressions <cmake-generator-expressions(7)>` + from the input content to produce the output content. -Create the given directories and their parents as needed. + .. code-block:: cmake -.. _REMOVE: -.. _REMOVE_RECURSE: + file(GENERATE OUTPUT <output-file> + <INPUT <input-file>|CONTENT <content>> + [CONDITION <expression>] [TARGET <target>] + [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS | + FILE_PERMISSIONS <permissions>...] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) -.. code-block:: cmake + The options are: - file(REMOVE [<files>...]) - file(REMOVE_RECURSE [<files>...]) + ``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. -Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given -files and directories, also non-empty directories. No error is emitted if a -given file does not exist. Relative input paths are evaluated with respect -to the current source directory. + ``CONTENT <content>`` + Use the content given explicitly as input. -.. versionchanged:: 3.15 - Empty input paths are ignored with a warning. Previous versions of CMake - interpreted empty strings as a relative path with respect to the current - directory and removed its contents. + ``INPUT <input-file>`` + Use the content from a given file as input. -.. _RENAME: + .. versionchanged:: 3.10 + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. -.. code-block:: cmake + ``OUTPUT <output-file>`` + Specify the output file name to generate. Use generator expressions + such as :genex:`$<CONFIG>` to specify a configuration-specific + output file name. Multiple configurations may generate the same output + file only if the generated content is identical. Otherwise, the + ``<output-file>`` must evaluate to an unique name for each configuration. - file(RENAME <oldname> <newname> - [RESULT <result>] - [NO_REPLACE]) + .. versionchanged:: 3.10 + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. -Move a file or directory within a filesystem from ``<oldname>`` to -``<newname>``, replacing the destination atomically. + ``TARGET <target>`` + .. versionadded:: 3.19 -The options are: + Specify which target to use when evaluating generator expressions that + require a target for evaluation (e.g. + :genex:`$<COMPILE_FEATURES:...>`, + :genex:`$<TARGET_PROPERTY:prop>`). -``RESULT <result>`` - .. versionadded:: 3.21 + ``NO_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 - Set ``<result>`` variable to ``0`` on success or an error message otherwise. - If ``RESULT`` is not specified and the operation fails, an error is emitted. + The generated file permissions default to the standard 644 value + (-rw-r--r--). -``NO_REPLACE`` - .. versionadded:: 3.21 + ``USE_SOURCE_PERMISSIONS`` + .. versionadded:: 3.20 - If the ``<newname>`` path already exists, do not replace it. - If ``RESULT <result>`` is used, the result variable will be - set to ``NO_REPLACE``. Otherwise, an error is emitted. + Transfer the file permissions of the ``INPUT`` file to the generated + file. This is already the default behavior if none of the three + permissions-related keywords are given (``NO_SOURCE_PERMISSIONS``, + ``USE_SOURCE_PERMISSIONS`` or ``FILE_PERMISSIONS``). The + ``USE_SOURCE_PERMISSIONS`` keyword mostly serves as a way of making + the intended behavior clearer at the call site. It is an error to + specify this option without ``INPUT``. -.. _COPY_FILE: + ``FILE_PERMISSIONS <permissions>...`` + .. versionadded:: 3.20 -.. code-block:: cmake + Use the specified permissions for the generated file. - file(COPY_FILE <oldname> <newname> - [RESULT <result>] - [ONLY_IF_DIFFERENT] - [INPUT_MAY_BE_RECENT]) + ``NEWLINE_STYLE <style>`` + .. versionadded:: 3.20 -.. versionadded:: 3.21 + Specify the newline style for the generated file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. -Copy a file from ``<oldname>`` to ``<newname>``. Directories are not -supported. Symlinks are ignored and ``<oldfile>``'s content is read and -written to ``<newname>`` as a new file. + Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific + ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. + Generated files are modified and their timestamp updated on subsequent cmake + runs only if their content is changed. -The options are: + Note also that ``file(GENERATE)`` does not create the output file until the + generation phase. The output file will not yet have been written when the + ``file(GENERATE)`` command returns, it is written only after processing all + of a project's ``CMakeLists.txt`` files. -``RESULT <result>`` - Set ``<result>`` variable to ``0`` on success or an error message otherwise. - If ``RESULT`` is not specified and the operation fails, an error is emitted. +.. signature:: + file(CONFIGURE OUTPUT <output-file> + CONTENT <content> + [ESCAPE_QUOTES] [@ONLY] + [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) + :target: CONFIGURE -``ONLY_IF_DIFFERENT`` - If the ``<newname>`` path already exists, do not replace it if the file's - contents are already the same as ``<oldname>`` (this avoids updating - ``<newname>``'s timestamp). + .. versionadded:: 3.18 -``INPUT_MAY_BE_RECENT`` - .. versionadded:: 3.26 + Generate an output file using the input given by ``CONTENT`` and substitute + variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The + substitution rules behave the same as the :command:`configure_file` command. + In order to match :command:`configure_file`'s behavior, generator expressions + are not supported for both ``OUTPUT`` and ``CONTENT``. - Tell CMake that the input file may have been recently created. This is - meaningful only on Windows, where files may be inaccessible for a short - time after they are created. With this option, if permission is denied, - CMake will retry reading the input a few times. + The arguments are: -This sub-command has some similarities to :command:`configure_file` with the -``COPYONLY`` option. An important difference is that :command:`configure_file` -creates a dependency on the source file, so CMake will be re-run if it changes. -The ``file(COPY_FILE)`` sub-command does not create such a dependency. + ``OUTPUT <output-file>`` + Specify the output file name to generate. A relative path is treated with + respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + ``<output-file>`` does not support generator expressions. -See also the ``file(COPY)`` sub-command just below which provides -further file-copying capabilities. + ``CONTENT <content>`` + Use the content given explicitly as input. + ``<content>`` does not support generator expressions. -.. _COPY: -.. _INSTALL: + ``ESCAPE_QUOTES`` + Escape any substituted quotes with backslashes (C-style). -.. code-block:: cmake + ``@ONLY`` + Restrict variable replacement to references of the form ``@VAR@``. + This is useful for configuring scripts that use ``${VAR}`` syntax. - file(<COPY|INSTALL> <files>... DESTINATION <dir> - [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS] - [FILE_PERMISSIONS <permissions>...] - [DIRECTORY_PERMISSIONS <permissions>...] - [FOLLOW_SYMLINK_CHAIN] - [FILES_MATCHING] - [[PATTERN <pattern> | REGEX <regex>] - [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) + ``NEWLINE_STYLE <style>`` + Specify the newline style for the output file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. -.. note:: +Filesystem +^^^^^^^^^^ - For a simple file copying operation, the ``file(COPY_FILE)`` sub-command - just above may be easier to use. +.. signature:: + file(GLOB <variable> + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] + [<globbing-expressions>...]) + file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] + [<globbing-expressions>...]) -The ``COPY`` signature copies files, directories, and symlinks to a -destination folder. Relative input paths are evaluated with respect -to the current source directory, and a relative destination is -evaluated with respect to the current build directory. Copying -preserves input file timestamps, and optimizes out a file if it exists -at the destination with the same timestamp. Copying preserves input -permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` -are given (default is ``USE_SOURCE_PERMISSIONS``). + Generate a list of files that match the ``<globbing-expressions>`` and + store it into the ``<variable>``. Globbing expressions are similar to + regular expressions, but much simpler. If ``RELATIVE`` flag is + specified, the results will be returned as relative paths to the given + path. + + .. versionchanged:: 3.6 + The results will be ordered lexicographically. + + On Windows and macOS, globbing is case-insensitive even if the underlying + filesystem is case-sensitive (both filenames and globbing expressions are + converted to lowercase before matching). On other platforms, globbing is + case-sensitive. + + .. versionadded:: 3.3 + By default ``GLOB`` lists directories. Directories are omitted in the + result if ``LIST_DIRECTORIES`` is set to false. + + .. versionadded:: 3.12 + If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic + to the main build system check target to rerun the flagged ``GLOB`` + commands at build time. If any of the outputs change, CMake will regenerate + the build system. + + .. note:: + We do not recommend using GLOB to collect a list of source files from + your source tree. If no CMakeLists.txt file changes when a source is + added or removed then the generated build system cannot know when to + ask CMake to regenerate. + The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or + if a new generator is added in the future that cannot support it, projects + using it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there + is still a cost to perform the check on every rebuild. + + Examples of globbing expressions include: + + ============== ====================================================== + ``*.cxx`` match all files with extension ``cxx`` + ``*.vt?`` match all files with extension ``vta``, ..., ``vtz`` + ``f[3-5].txt`` match files ``f3.txt``, ``f4.txt``, ``f5.txt`` + ============== ====================================================== + + The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the + matched directory and match the files. Subdirectories that are symlinks + are only traversed if ``FOLLOW_SYMLINKS`` is given or policy + :policy:`CMP0009` is not set to ``NEW``. + + .. versionadded:: 3.3 + By default ``GLOB_RECURSE`` omits directories from result list. Setting + ``LIST_DIRECTORIES`` to true adds directories to result list. + If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to + ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories. + + Examples of recursive globbing include: + + ============== ====================================================== + ``/dir/*.py`` match all python files in ``/dir`` and subdirectories + ============== ====================================================== + +.. signature:: + file(MAKE_DIRECTORY [<directories>...]) -.. versionadded:: 3.15 - If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve - the symlinks at the paths given until a real file is found, and install - a corresponding symlink in the destination for each symlink encountered. For - each symlink that is installed, the resolution is stripped of the directory, - leaving only the filename, meaning that the new symlink points to a file in - the same directory as the symlink. This feature is useful on some Unix systems, - where libraries are installed as a chain of symlinks with version numbers, with - less specific versions pointing to more specific versions. - ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and the library - itself into the destination directory. For example, if you have the following - directory structure: + Create the given directories and their parents as needed. -* ``/opt/foo/lib/libfoo.so.1.2.3`` -* ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3`` -* ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2`` -* ``/opt/foo/lib/libfoo.so -> libfoo.so.1`` +.. signature:: + file(REMOVE [<files>...]) + file(REMOVE_RECURSE [<files>...]) -and you do: + Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given + files and directories, including non-empty directories. No error is emitted + if a given file does not exist. Relative input paths are evaluated with + respect to the current source directory. -.. code-block:: cmake + .. versionchanged:: 3.15 + Empty input paths are ignored with a warning. Previous versions of CMake + interpreted empty strings as a relative path with respect to the current + directory and removed its contents. - file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN) +.. signature:: + file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE]) -This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into -``lib``. + Move a file or directory within a filesystem from ``<oldname>`` to + ``<newname>``, replacing the destination atomically. -See the :command:`install(DIRECTORY)` command for documentation of -permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and -``EXCLUDE`` options. Copying directories preserves the structure -of their content even if options are used to select a subset of -files. + The options are: -The ``INSTALL`` signature differs slightly from ``COPY``: it prints -status messages, and ``NO_SOURCE_PERMISSIONS`` is default. + ``RESULT <result>`` + .. versionadded:: 3.21 -Installation scripts generated by the :command:`install` command -use this signature (with some undocumented options for internal use). + Set ``<result>`` variable to ``0`` on success or an error message + otherwise. If ``RESULT`` is not specified and the operation fails, + an error is emitted. -.. versionchanged:: 3.22 + ``NO_REPLACE`` + .. versionadded:: 3.21 - The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the - default copying behavior of :command:`file(INSTALL)`. + If the ``<newname>`` path already exists, do not replace it. + If ``RESULT <result>`` is used, the result variable will be + set to ``NO_REPLACE``. Otherwise, an error is emitted. -.. _SIZE: +.. signature:: + file(COPY_FILE <oldname> <newname> + [RESULT <result>] + [ONLY_IF_DIFFERENT] + [INPUT_MAY_BE_RECENT]) -.. code-block:: cmake + .. versionadded:: 3.21 + Copy a file from ``<oldname>`` to ``<newname>``. Directories are not + supported. Symlinks are ignored and ``<oldfile>``'s content is read and + written to ``<newname>`` as a new file. + + The options are: + + ``RESULT <result>`` + Set ``<result>`` variable to ``0`` on success or an error message + otherwise. If ``RESULT`` is not specified and the operation fails, + an error is emitted. + + ``ONLY_IF_DIFFERENT`` + If the ``<newname>`` path already exists, do not replace it if the file's + contents are already the same as ``<oldname>`` (this avoids updating + ``<newname>``'s timestamp). + + ``INPUT_MAY_BE_RECENT`` + .. versionadded:: 3.26 + + Tell CMake that the input file may have been recently created. This is + meaningful only on Windows, where files may be inaccessible for a short + time after they are created. With this option, if permission is denied, + CMake will retry reading the input a few times. + + This sub-command has some similarities to :command:`configure_file` + with the ``COPYONLY`` option. An important difference is that + :command:`configure_file` creates a dependency on the source file, + so CMake will be re-run if it changes. The ``file(COPY_FILE)`` + sub-command does not create such a dependency. + + See also the :command:`file(COPY)` sub-command just below which provides + further file-copying capabilities. + +.. signature:: + file(COPY [...]) + file(INSTALL [...]) + + The ``COPY`` signature copies files, directories, and symlinks to a + destination folder. Relative input paths are evaluated with respect + to the current source directory, and a relative destination is + evaluated with respect to the current build directory. Copying + preserves input file timestamps, and optimizes out a file if it exists + at the destination with the same timestamp. Copying preserves input + permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` + are given (default is ``USE_SOURCE_PERMISSIONS``). + + .. code-block:: cmake + + file(<COPY|INSTALL> <files>... DESTINATION <dir> + [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS] + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...] + [FOLLOW_SYMLINK_CHAIN] + [FILES_MATCHING] + [[PATTERN <pattern> | REGEX <regex>] + [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) + + .. note:: + + For a simple file copying operation, the :command:`file(COPY_FILE)` + sub-command just above may be easier to use. + + .. versionadded:: 3.15 + If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve + the symlinks at the paths given until a real file is found, and install + a corresponding symlink in the destination for each symlink encountered. + For each symlink that is installed, the resolution is stripped of the + directory, leaving only the filename, meaning that the new symlink points + to a file in the same directory as the symlink. This feature is useful on + some Unix systems, where libraries are installed as a chain of symlinks + with version numbers, with less specific versions pointing to more specific + versions. ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and + the library itself into the destination directory. For example, if you have + the following directory structure: + + * ``/opt/foo/lib/libfoo.so.1.2.3`` + * ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3`` + * ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2`` + * ``/opt/foo/lib/libfoo.so -> libfoo.so.1`` + + and you do: + + .. code-block:: cmake + + file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN) + + This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into + ``lib``. + + See the :command:`install(DIRECTORY)` command for documentation of + permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and + ``EXCLUDE`` options. Copying directories preserves the structure + of their content even if options are used to select a subset of + files. + + The ``INSTALL`` signature differs slightly from ``COPY``: it prints + status messages, and ``NO_SOURCE_PERMISSIONS`` is default. Installation + scripts generated by the :command:`install` command use this signature + (with some undocumented options for internal use). + + .. versionchanged:: 3.22 + + The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the + default copying behavior of :command:`file(INSTALL)`. + +.. signature:: file(SIZE <filename> <variable>) -.. versionadded:: 3.14 - -Determine the file size of the ``<filename>`` and put the result in -``<variable>`` variable. Requires that ``<filename>`` is a valid path -pointing to a file and is readable. - -.. _READ_SYMLINK: + .. versionadded:: 3.14 -.. code-block:: cmake + Determine the file size of the ``<filename>`` and put the result in + ``<variable>`` variable. Requires that ``<filename>`` is a valid path + pointing to a file and is readable. +.. signature:: file(READ_SYMLINK <linkname> <variable>) -.. versionadded:: 3.14 + .. versionadded:: 3.14 -This subcommand queries the symlink ``<linkname>`` and stores the path it -points to in the result ``<variable>``. If ``<linkname>`` does not exist or -is not a symlink, CMake issues a fatal error. + Query the symlink ``<linkname>`` and stores the path it points to + in the result ``<variable>``. If ``<linkname>`` does not exist + or is not a symlink, CMake issues a fatal error. -Note that this command returns the raw symlink path and does not resolve -a relative path. The following is an example of how to ensure that an -absolute path is obtained: + Note that this command returns the raw symlink path and does not resolve + a relative path. The following is an example of how to ensure that an + absolute path is obtained: -.. code-block:: cmake + .. code-block:: cmake - set(linkname "/path/to/foo.sym") - file(READ_SYMLINK "${linkname}" result) - if(NOT IS_ABSOLUTE "${result}") - get_filename_component(dir "${linkname}" DIRECTORY) - set(result "${dir}/${result}") - endif() - -.. _CREATE_LINK: - -.. code-block:: cmake + set(linkname "/path/to/foo.sym") + file(READ_SYMLINK "${linkname}" result) + if(NOT IS_ABSOLUTE "${result}") + get_filename_component(dir "${linkname}" DIRECTORY) + set(result "${dir}/${result}") + endif() +.. signature:: file(CREATE_LINK <original> <linkname> [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) -.. versionadded:: 3.14 - -Create a link ``<linkname>`` that points to ``<original>``. -It will be a hard link by default, but providing the ``SYMBOLIC`` option -results in a symbolic link instead. Hard links require that ``original`` -exists and is a file, not a directory. If ``<linkname>`` already exists, -it will be overwritten. - -The ``<result>`` variable, if specified, receives the status of the operation. -It is set to ``0`` upon success or an error message otherwise. If ``RESULT`` -is not specified and the operation fails, a fatal error is emitted. + .. versionadded:: 3.14 -Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if -creating the link fails. It can be useful for handling situations such as -``<original>`` and ``<linkname>`` being on different drives or mount points, -which would make them unable to support a hard link. + Create a link ``<linkname>`` that points to ``<original>``. + It will be a hard link by default, but providing the ``SYMBOLIC`` option + results in a symbolic link instead. Hard links require that ``original`` + exists and is a file, not a directory. If ``<linkname>`` already exists, + it will be overwritten. -.. _CHMOD: + The ``<result>`` variable, if specified, receives the status of the + operation. It is set to ``0`` upon success or an error message otherwise. + If ``RESULT`` is not specified and the operation fails, a fatal error is + emitted. -.. code-block:: cmake + Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if + creating the link fails. It can be useful for handling situations such as + ``<original>`` and ``<linkname>`` being on different drives or mount points, + which would make them unable to support a hard link. +.. signature:: file(CHMOD <files>... <directories>... - [PERMISSIONS <permissions>...] - [FILE_PERMISSIONS <permissions>...] - [DIRECTORY_PERMISSIONS <permissions>...]) - -.. versionadded:: 3.19 - -Set the permissions for the ``<files>...`` and ``<directories>...`` specified. -Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, -``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, -``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``. - -Valid combination of keywords are: + [PERMISSIONS <permissions>...] + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...]) -``PERMISSIONS`` - All items are changed. + .. versionadded:: 3.19 -``FILE_PERMISSIONS`` - Only files are changed. + Set the permissions for the ``<files>...`` and ``<directories>...`` + specified. Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, + ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, + ``WORLD_READ``, ``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``. -``DIRECTORY_PERMISSIONS`` - Only directories are changed. + Valid combination of keywords are: -``PERMISSIONS`` and ``FILE_PERMISSIONS`` - ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files. + ``PERMISSIONS`` + All items are changed. -``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` - ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories. + ``FILE_PERMISSIONS`` + Only files are changed. -``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` - Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for - directories. + ``DIRECTORY_PERMISSIONS`` + Only directories are changed. + ``PERMISSIONS`` and ``FILE_PERMISSIONS`` + ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files. -.. _CHMOD_RECURSE: + ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` + ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories. -.. code-block:: cmake + ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` + Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for + directories. +.. signature:: file(CHMOD_RECURSE <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...]) -.. versionadded:: 3.19 + .. versionadded:: 3.19 + + Same as :cref:`CHMOD`, but change the permissions of files and directories + present in the ``<directories>...`` recursively. -Same as `CHMOD`_, but change the permissions of files and directories present in -the ``<directories>...`` recursively. Path Conversion ^^^^^^^^^^^^^^^ -.. _REAL_PATH: - -.. code-block:: cmake - +.. signature:: file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE]) -.. versionadded:: 3.19 - -Compute the absolute path to an existing file or directory with symlinks -resolved. - -``BASE_DIRECTORY <dir>`` - If the provided ``<path>`` is a relative path, it is evaluated relative to the - given base directory ``<dir>``. If no base directory is provided, the default - base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. + .. versionadded:: 3.19 -``EXPAND_TILDE`` - .. versionadded:: 3.21 + Compute the absolute path to an existing file or directory with symlinks + resolved. The options are: - If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced by - the user's home directory. The path to the home directory is obtained from - environment variables. On Windows, the ``USERPROFILE`` environment variable - is used, falling back to the ``HOME`` environment variable if ``USERPROFILE`` - is not defined. On all other platforms, only ``HOME`` is used. + ``BASE_DIRECTORY <dir>`` + If the provided ``<path>`` is a relative path, it is evaluated relative + to the given base directory ``<dir>``. If no base directory is provided, + the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`. -.. _RELATIVE_PATH: + ``EXPAND_TILDE`` + .. versionadded:: 3.21 -.. code-block:: cmake + If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced + by the user's home directory. The path to the home directory is obtained + from environment variables. On Windows, the ``USERPROFILE`` environment + variable is used, falling back to the ``HOME`` environment variable + if ``USERPROFILE`` is not defined. On all other platforms, only ``HOME`` + is used. +.. signature:: file(RELATIVE_PATH <variable> <directory> <file>) -Compute the relative path from a ``<directory>`` to a ``<file>`` and -store it in the ``<variable>``. - -.. _TO_CMAKE_PATH: -.. _TO_NATIVE_PATH: - -.. code-block:: cmake + Compute the relative path from a ``<directory>`` to a ``<file>`` and + store it in the ``<variable>``. +.. signature:: file(TO_CMAKE_PATH "<path>" <variable>) file(TO_NATIVE_PATH "<path>" <variable>) -The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style -path with forward-slashes (``/``). The input can be a single path or a -system search path like ``$ENV{PATH}``. A search path will be converted -to a cmake-style list separated by ``;`` characters. + The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style + path with forward-slashes (``/``). The input can be a single path or a + system search path like ``$ENV{PATH}``. A search path will be converted + to a cmake-style list separated by ``;`` characters. -The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native -path with platform-specific slashes (``\`` on Windows hosts and ``/`` -elsewhere). + The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native + path with platform-specific slashes (``\`` on Windows hosts and ``/`` + elsewhere). -Always use double quotes around the ``<path>`` to be sure it is treated -as a single argument to this command. + Always use double quotes around the ``<path>`` to be sure it is treated + as a single argument to this command. Transfer ^^^^^^^^ -.. _DOWNLOAD: -.. _UPLOAD: +.. signature:: + file(DOWNLOAD <url> [<file>] [<options>...]) + file(UPLOAD <file> <url> [<options>...]) -.. code-block:: cmake + The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local + ``<file>``. The ``UPLOAD`` mode uploads a local ``<file>`` to a given + ``<url>``. - file(DOWNLOAD <url> [<file>] [<options>...]) - file(UPLOAD <file> <url> [<options>...]) + .. versionadded:: 3.19 + If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not + saved. This can be useful if you want to know if a file can be downloaded + (for example, to check that it exists) without actually saving it anywhere. -The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local ``<file>``. -The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``. + Options to both ``DOWNLOAD`` and ``UPLOAD`` are: -.. versionadded:: 3.19 - If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not saved. - This can be useful if you want to know if a file can be downloaded (for example, - to check that it exists) without actually saving it anywhere. + ``INACTIVITY_TIMEOUT <seconds>`` + Terminate the operation after a period of inactivity. -Options to both ``DOWNLOAD`` and ``UPLOAD`` are: + ``LOG <variable>`` + Store a human-readable log of the operation in a variable. -``INACTIVITY_TIMEOUT <seconds>`` - Terminate the operation after a period of inactivity. + ``SHOW_PROGRESS`` + Print progress information as status messages until the operation is + complete. -``LOG <variable>`` - Store a human-readable log of the operation in a variable. + ``STATUS <variable>`` + Store the resulting status of the operation in a variable. + The status is a ``;`` separated list of length 2. + The first element is the numeric return value for the operation, + and the second element is a string value for the error. + A ``0`` numeric error means no error in the operation. -``SHOW_PROGRESS`` - Print progress information as status messages until the operation is - complete. + ``TIMEOUT <seconds>`` + Terminate the operation after a given total time has elapsed. -``STATUS <variable>`` - Store the resulting status of the operation in a variable. - The status is a ``;`` separated list of length 2. - The first element is the numeric return value for the operation, - and the second element is a string value for the error. - A ``0`` numeric error means no error in the operation. + ``USERPWD <username>:<password>`` + .. versionadded:: 3.7 -``TIMEOUT <seconds>`` - Terminate the operation after a given total time has elapsed. + Set username and password for operation. -``USERPWD <username>:<password>`` - .. versionadded:: 3.7 + ``HTTPHEADER <HTTP-header>`` + .. versionadded:: 3.7 - Set username and password for operation. + HTTP header for ``DOWNLOAD`` and ``UPLOAD`` operations. ``HTTPHEADER`` + can be repeated for multiple options: -``HTTPHEADER <HTTP-header>`` - .. versionadded:: 3.7 + .. code-block:: cmake - HTTP header for operation. Suboption can be repeated several times. + file(DOWNLOAD <url> + HTTPHEADER "Authorization: Bearer <auth-token>" + HTTPHEADER "UserAgent: Mozilla/5.0") -``NETRC <level>`` - .. versionadded:: 3.11 + ``NETRC <level>`` + .. versionadded:: 3.11 - Specify whether the .netrc file is to be used for operation. If this - option is not specified, the value of the :variable:`CMAKE_NETRC` variable - will be used instead. - Valid levels are: + Specify whether the .netrc file is to be used for operation. If this + option is not specified, the value of the :variable:`CMAKE_NETRC` + variable will be used instead. - ``IGNORED`` - The .netrc file is ignored. - This is the default. - ``OPTIONAL`` - The .netrc file is optional, and information in the URL is preferred. - The file will be scanned to find which ever information is not specified - in the URL. - ``REQUIRED`` - The .netrc file is required, and information in the URL is ignored. + Valid levels are: -``NETRC_FILE <file>`` - .. versionadded:: 3.11 + ``IGNORED`` + The .netrc file is ignored. + This is the default. - Specify an alternative .netrc file to the one in your home directory, - if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option - is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable will - be used instead. + ``OPTIONAL`` + The .netrc file is optional, and information in the URL is preferred. + The file will be scanned to find which ever information is not + specified in the URL. -``TLS_VERIFY <ON|OFF>`` - Specify whether to verify the server certificate for ``https://`` URLs. - The default is to *not* verify. If this option is not specified, the value - of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead. + ``REQUIRED`` + The .netrc file is required, and information in the URL is ignored. - .. versionadded:: 3.18 - Added support to ``file(UPLOAD)``. + ``NETRC_FILE <file>`` + .. versionadded:: 3.11 -``TLS_CAINFO <file>`` - Specify a custom Certificate Authority file for ``https://`` URLs. If this - option is not specified, the value of the :variable:`CMAKE_TLS_CAINFO` - variable will be used instead. + Specify an alternative .netrc file to the one in your home directory, + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable + will be used instead. - .. versionadded:: 3.18 - Added support to ``file(UPLOAD)``. + ``TLS_VERIFY <ON|OFF>`` + Specify whether to verify the server certificate for ``https://`` URLs. + The default is to *not* verify. If this option is not specified, the + value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead. -For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` -certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to -check certificates. + .. versionadded:: 3.18 + Added support to ``file(UPLOAD)``. -Additional options to ``DOWNLOAD`` are: + ``TLS_CAINFO <file>`` + Specify a custom Certificate Authority file for ``https://`` URLs. + If this option is not specified, the value of the + :variable:`CMAKE_TLS_CAINFO` variable will be used instead. -``EXPECTED_HASH ALGO=<value>`` + .. versionadded:: 3.18 + Added support to ``file(UPLOAD)``. - Verify that the downloaded content hash matches the expected value, where - ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``. - If the file already exists and matches the hash, the download is skipped. - If the file already exists and does not match the hash, the file is - downloaded again. If after download the file does not match the hash, the - operation fails with an error. It is an error to specify this option if - ``DOWNLOAD`` is not given a ``<file>``. + For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` + certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to + check certificates. -``EXPECTED_MD5 <value>`` - Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error to - specify this if ``DOWNLOAD`` is not given a ``<file>``. + Additional options to ``DOWNLOAD`` are: -``RANGE_START <value>`` - .. versionadded:: 3.24 + ``EXPECTED_HASH <algorithm>=<value>`` + Verify that the downloaded content hash matches the expected value, where + ``<algorithm>`` is one of the algorithms supported by :cref:`<HASH>`. + If the file already exists and matches the hash, the download is skipped. + If the file already exists and does not match the hash, the file is + downloaded again. If after download the file does not match the hash, the + operation fails with an error. It is an error to specify this option if + ``DOWNLOAD`` is not given a ``<file>``. - Offset of the start of the range in file in bytes. Could be omitted to - download up to the specified ``RANGE_END``. + ``EXPECTED_MD5 <value>`` + Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error + to specify this if ``DOWNLOAD`` is not given a ``<file>``. -``RANGE_END <value>`` - .. versionadded:: 3.24 + ``RANGE_START <value>`` + .. versionadded:: 3.24 - Offset of the end of the range in file in bytes. Could be omitted to - download everything from the specified ``RANGE_START`` to the end of file. + Offset of the start of the range in file in bytes. Could be omitted to + download up to the specified ``RANGE_END``. -Locking -^^^^^^^ + ``RANGE_END <value>`` + .. versionadded:: 3.24 -.. _LOCK: + Offset of the end of the range in file in bytes. Could be omitted to + download everything from the specified ``RANGE_START`` to the end of + file. -.. code-block:: cmake +Locking +^^^^^^^ +.. signature:: file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] [RESULT_VARIABLE <variable>] [TIMEOUT <seconds>]) -.. versionadded:: 3.2 - -Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file -``<path>/cmake.lock`` otherwise. File will be locked for scope defined by -``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used -to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will -wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to -``0`` lock will be tried once and result will be reported immediately. If -``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified -by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no -``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>`` -and will be ``0`` on success or error message on failure. - -Note that lock is advisory - there is no guarantee that other processes will -respect this lock, i.e. lock synchronize two or more CMake instances sharing -some modifiable resources. Similar logic applied to ``DIRECTORY`` option - -locking parent directory doesn't prevent other ``LOCK`` commands to lock any -child directory or file. - -Trying to lock file twice is not allowed. Any intermediate directories and -file itself will be created if they not exist. ``GUARD`` and ``TIMEOUT`` -options ignored on ``RELEASE`` operation. + .. versionadded:: 3.2 + + Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and + file ``<path>/cmake.lock`` otherwise. The file will be locked for the scope + defined by the ``GUARD`` option (default value is ``PROCESS``). The + ``RELEASE`` option can be used to unlock the file explicitly. If the + ``TIMEOUT`` option is not specified, CMake will wait until the lock succeeds + or until a fatal error occurs. If ``TIMEOUT`` is set to ``0``, locking will + be tried once and the result will be reported immediately. If ``TIMEOUT`` + is not ``0``, CMake will try to lock the file for the period specified by + the ``TIMEOUT <seconds>`` value. Any errors will be interpreted as fatal if + there is no ``RESULT_VARIABLE`` option. Otherwise, the result will be stored + in ``<variable>`` and will be ``0`` on success or an error message on + failure. + + Note that lock is advisory; there is no guarantee that other processes will + respect this lock, i.e. lock synchronize two or more CMake instances sharing + some modifiable resources. Similar logic applies to the ``DIRECTORY`` option; + locking a parent directory doesn't prevent other ``LOCK`` commands from + locking any child directory or file. + + Trying to lock the same file twice is not allowed. Any intermediate + directories and the file itself will be created if they not exist. The + ``GUARD`` and ``TIMEOUT`` options are ignored on the ``RELEASE`` operation. Archiving ^^^^^^^^^ -.. _ARCHIVE_CREATE: - -.. code-block:: cmake - +.. signature:: file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [FORMAT <format>] - [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] + [COMPRESSION <compression> + [COMPRESSION_LEVEL <compression-level>]] [MTIME <mtime>] [VERBOSE]) + :target: ARCHIVE_CREATE + :break: verbatim -.. versionadded:: 3.18 - -Creates the specified ``<archive>`` file with the files and directories -listed in ``<paths>``. Note that ``<paths>`` must list actual files or -directories, wildcards are not supported. - -Use the ``FORMAT`` option to specify the archive format. Supported values -for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and -``zip``. If ``FORMAT`` is not given, the default format is ``paxr``. + .. versionadded:: 3.18 -Some archive formats allow the type of compression to be specified. -The ``7zip`` and ``zip`` archive formats already imply a specific type of -compression. The other formats use no compression by default, but can be -directed to do so with the ``COMPRESSION`` option. Valid values for -``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. + Creates the specified ``<archive>`` file with the files and directories + listed in ``<paths>``. Note that ``<paths>`` must list actual files or + directories; wildcards are not supported. -.. versionadded:: 3.19 - The compression level can be specified with the ``COMPRESSION_LEVEL`` option. - The ``<compression-level>`` should be between 0-9, with the default being 0. - The ``COMPRESSION`` option must be present when ``COMPRESSION_LEVEL`` is given. + Use the ``FORMAT`` option to specify the archive format. Supported values + for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and + ``zip``. If ``FORMAT`` is not given, the default format is ``paxr``. -.. versionadded:: 3.26 - The ``<compression-level>`` of the ``Zstd`` algorithm can be set between 0-19. + Some archive formats allow the type of compression to be specified. + The ``7zip`` and ``zip`` archive formats already imply a specific type of + compression. The other formats use no compression by default, but can be + directed to do so with the ``COMPRESSION`` option. Valid values for + ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``. -.. note:: - With ``FORMAT`` set to ``raw`` only one file will be compressed with the - compression type specified by ``COMPRESSION``. + .. versionadded:: 3.19 + The compression level can be specified with the ``COMPRESSION_LEVEL`` + option. The ``<compression-level>`` should be between 0-9, with the + default being 0. The ``COMPRESSION`` option must be present when + ``COMPRESSION_LEVEL`` is given. -The ``VERBOSE`` option enables verbose output for the archive operation. + .. versionadded:: 3.26 + The ``<compression-level>`` of the ``Zstd`` algorithm can be set + between 0-19. -To specify the modification time recorded in tarball entries, use -the ``MTIME`` option. + .. note:: + With ``FORMAT`` set to ``raw``, only one file will be compressed with the + compression type specified by ``COMPRESSION``. -.. _ARCHIVE_EXTRACT: + The ``VERBOSE`` option enables verbose output for the archive operation. -.. code-block:: cmake + To specify the modification time recorded in tarball entries, use + the ``MTIME`` option. - file(ARCHIVE_EXTRACT INPUT <archive> +.. signature:: + file(ARCHIVE_EXTRACT + INPUT <archive> [DESTINATION <dir>] [PATTERNS <patterns>...] [LIST_ONLY] [VERBOSE] [TOUCH]) + :target: ARCHIVE_EXTRACT -.. versionadded:: 3.18 + .. versionadded:: 3.18 -Extracts or lists the content of the specified ``<archive>``. + Extracts or lists the content of the specified ``<archive>``. -The directory where the content of the archive will be extracted to can -be specified using the ``DESTINATION`` option. If the directory does not -exist, it will be created. If ``DESTINATION`` is not given, the current -binary directory will be used. + The directory where the content of the archive will be extracted to can + be specified using the ``DESTINATION`` option. If the directory does not + exist, it will be created. If ``DESTINATION`` is not given, the current + binary directory will be used. -If required, you may select which files and directories to list or extract -from the archive using the specified ``<patterns>``. Wildcards are supported. -If the ``PATTERNS`` option is not given, the entire archive will be listed or -extracted. + If required, you may select which files and directories to list or extract + from the archive using the specified ``<patterns>``. Wildcards are + supported. If the ``PATTERNS`` option is not given, the entire archive will + be listed or extracted. -``LIST_ONLY`` will list the files in the archive rather than extract them. + ``LIST_ONLY`` will list the files in the archive rather than extract them. -.. versionadded:: 3.24 - The ``TOUCH`` option gives extracted files a current local - timestamp instead of extracting file timestamps from the archive. + .. versionadded:: 3.24 + The ``TOUCH`` option gives extracted files a current local + timestamp instead of extracting file timestamps from the archive. -With ``VERBOSE``, the command will produce verbose output. + With ``VERBOSE``, the command will produce verbose output. diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index de4cb88435..b82088eaa0 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -367,17 +367,37 @@ The set of installation prefixes is constructed using the following steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are enabled. -1. .. versionadded:: 3.12 - Search paths specified in the :variable:`<PackageName>_ROOT` CMake - variable and the :envvar:`<PackageName>_ROOT` environment variable, - where ``<PackageName>`` is the package to be found - (the case-preserved first argument to ``find_package``). - The package root variables are maintained as a stack so if - called from within a find module, root paths from the parent's find - module will also be searched after paths for the current package. - This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting - the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. - See policy :policy:`CMP0074`. +1. Search prefixes unique to the current ``<PackageName>`` being found. + See policy :policy:`CMP0074`. + + .. versionadded:: 3.12 + + Specifically, search prefixes specified by the following variables, + in order: + + a. :variable:`<PackageName>_ROOT` CMake variable, + where ``<PackageName>`` is the case-preserved package name. + + b. :variable:`<PACKAGENAME>_ROOT` CMake variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + c. :envvar:`<PackageName>_ROOT` environment variable, + where ``<PackageName>`` is the case-preserved package name. + + d. :envvar:`<PACKAGENAME>_ROOT` environment variable, + where ``<PACKAGENAME>`` is the upper-cased package name. + See policy :policy:`CMP0144`. + + .. versionadded:: 3.27 + + The package root variables are maintained as a stack so if + called from within a find module, root paths from the parent's find + module will also be searched after paths for the current package. + This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting + the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. 2. Search paths specified in cmake-specific cache variables. These are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`. diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 899ede60d5..7d74a33c57 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -4,9 +4,9 @@ get_filename_component Get a specific component of a full filename. .. versionchanged:: 3.20 - This command has been superseded by :command:`cmake_path` command, except - ``REALPATH`` now offered by :ref:`file(REAL_PATH)<REAL_PATH>` command and - ``PROGRAM`` now available in :command:`separate_arguments(PROGRAM)` command. + This command has been superseded by the :command:`cmake_path` command, except + for ``REALPATH``, which is now offered by :command:`file(REAL_PATH)`, and + ``PROGRAM``, now available in :command:`separate_arguments(PROGRAM)`. .. versionchanged:: 3.24 The undocumented feature offering the capability to query the ``Windows`` diff --git a/Help/command/if.rst b/Help/command/if.rst index 684c1135b1..be855e1e0b 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -39,7 +39,7 @@ the ``if``, ``elseif`` and :command:`while` clauses. Compound conditions are evaluated in the following order of precedence: -1. Parentheses. +1. `Parentheses`_. 2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_. @@ -57,262 +57,284 @@ Compound conditions are evaluated in the following order of precedence: Basic Expressions """"""""""""""""" -``if(<constant>)`` - True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, - or a non-zero number (including floating point numbers). - False if the constant is ``0``, ``OFF``, - ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, - or ends in the suffix ``-NOTFOUND``. Named boolean constants are - case-insensitive. If the argument is not one of these specific - constants, it is treated as a variable or string (see `Variable Expansion`_ - further below) and one of the following two forms applies. - -``if(<variable>)`` - True if given a variable that is defined to a value that is not a false - constant. False otherwise, including if the variable is undefined. - Note that macro arguments are not variables. - :ref:`Environment Variables <CMake Language Environment Variables>` also - cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate - to false. - -``if(<string>)`` - A quoted string always evaluates to false unless: - - * The string's value is one of the true constants, or - * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value - happens to be a variable name that is affected by :policy:`CMP0054`'s - behavior. +.. signature:: if(<constant>) + :target: constant + + True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``, + or a non-zero number (including floating point numbers). + False if the constant is ``0``, ``OFF``, + ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string, + or ends in the suffix ``-NOTFOUND``. Named boolean constants are + case-insensitive. If the argument is not one of these specific + constants, it is treated as a variable or string (see `Variable Expansion`_ + further below) and one of the following two forms applies. + +.. signature:: if(<variable>) + :target: variable + + True if given a variable that is defined to a value that is not a false + constant. False otherwise, including if the variable is undefined. + Note that macro arguments are not variables. + :ref:`Environment Variables <CMake Language Environment Variables>` also + cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate + to false. + +.. signature:: if(<string>) + :target: string + + A quoted string always evaluates to false unless: + + * The string's value is one of the true constants, or + * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value + happens to be a variable name that is affected by :policy:`CMP0054`'s + behavior. Logic Operators """"""""""""""" -.. _NOT: +.. signature:: if(NOT <condition>) + + True if the condition is not true. -``if(NOT <condition>)`` - True if the condition is not true. +.. signature:: if(<cond1> AND <cond2>) + :target: AND -.. _AND: + True if both conditions would be considered true individually. -``if(<cond1> AND <cond2>)`` - True if both conditions would be considered true individually. +.. signature:: if(<cond1> OR <cond2>) + :target: OR -.. _OR: + True if either condition would be considered true individually. -``if(<cond1> OR <cond2>)`` - True if either condition would be considered true individually. +.. signature:: if((condition) AND (condition OR (condition))) + :target: parentheses -``if((condition) AND (condition OR (condition)))`` - The conditions inside the parenthesis are evaluated first and then - the remaining condition is evaluated as in the other examples. - Where there are nested parenthesis the innermost are evaluated as part - of evaluating the condition that contains them. + The conditions inside the parenthesis are evaluated first and then + the remaining condition is evaluated as in the other examples. + Where there are nested parenthesis the innermost are evaluated as part + of evaluating the condition that contains them. Existence Checks """""""""""""""" -.. _COMMAND: +.. signature:: if(COMMAND <command-name>) + + True if the given name is a command, macro or function that can be + invoked. + +.. signature:: if(POLICY <policy-id>) + + True if the given name is an existing policy (of the form ``CMP<NNNN>``). -``if(COMMAND command-name)`` - True if the given name is a command, macro or function that can be - invoked. +.. signature:: if(TARGET <target-name>) -``if(POLICY policy-id)`` - True if the given name is an existing policy (of the form ``CMP<NNNN>``). + True if the given name is an existing logical target name created + by a call to the :command:`add_executable`, :command:`add_library`, + or :command:`add_custom_target` command that has already been invoked + (in any directory). -``if(TARGET target-name)`` - True if the given name is an existing logical target name created - by a call to the :command:`add_executable`, :command:`add_library`, - or :command:`add_custom_target` command that has already been invoked - (in any directory). +.. signature:: if(TEST <test-name>) + + .. versionadded:: 3.3 -``if(TEST test-name)`` - .. versionadded:: 3.3 True if the given name is an existing test name created by the :command:`add_test` command. -.. _DEFINED: +.. signature:: if(DEFINED <name>|CACHE{<name>}|ENV{<name>}) -``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})`` - True if a variable, cache variable or environment variable - with given ``<name>`` is defined. The value of the variable - does not matter. Note the following caveats: + True if a variable, cache variable or environment variable + with given ``<name>`` is defined. The value of the variable + does not matter. Note the following caveats: - * Macro arguments are not variables. - * It is not possible to test directly whether a `<name>` is a non-cache - variable. The expression ``if(DEFINED someName)`` will evaluate to true - if either a cache or non-cache variable ``someName`` exists. In - comparison, the expression ``if(DEFINED CACHE{someName})`` will only - evaluate to true if a cache variable ``someName`` exists. Both expressions - need to be tested if you need to know whether a non-cache variable exists: - ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``. + * Macro arguments are not variables. + * It is not possible to test directly whether a `<name>` is a non-cache + variable. The expression ``if(DEFINED someName)`` will evaluate to true + if either a cache or non-cache variable ``someName`` exists. In + comparison, the expression ``if(DEFINED CACHE{someName})`` will only + evaluate to true if a cache variable ``someName`` exists. Both expressions + need to be tested if you need to know whether a non-cache variable exists: + ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``. .. versionadded:: 3.14 Added support for ``CACHE{<name>}`` variables. -``if(<variable|string> IN_LIST <variable>)`` - .. versionadded:: 3.3 +.. signature:: if(<variable|string> IN_LIST <variable>) + :target: IN_LIST + + .. versionadded:: 3.3 + True if the given element is contained in the named list variable. File Operations """"""""""""""" -.. _EXISTS: +.. signature:: if(EXISTS <path-to-file-or-directory>) + + True if the named file or directory exists. Behavior is well-defined + only for explicit full paths (a leading ``~/`` is not expanded as + a home directory and is considered a relative path). + Resolves symbolic links, i.e. if the named file or directory is a + symbolic link, returns true if the target of the symbolic link exists. + + False if the given path is an empty string. -``if(EXISTS path-to-file-or-directory)`` - True if the named file or directory exists. Behavior is well-defined - only for explicit full paths (a leading ``~/`` is not expanded as - a home directory and is considered a relative path). - Resolves symbolic links, i.e. if the named file or directory is a - symbolic link, returns true if the target of the symbolic link exists. +.. signature:: if(<file1> IS_NEWER_THAN <file2>) + :target: IS_NEWER_THAN - False if the given path is an empty string. + True if ``file1`` is newer than ``file2`` or if one of the two files doesn't + exist. Behavior is well-defined only for full paths. If the file + time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns + true, so that any dependent build operations will occur in the event + of a tie. This includes the case of passing the same file name for + both file1 and file2. -``if(file1 IS_NEWER_THAN file2)`` - True if ``file1`` is newer than ``file2`` or if one of the two files doesn't - exist. Behavior is well-defined only for full paths. If the file - time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns - true, so that any dependent build operations will occur in the event - of a tie. This includes the case of passing the same file name for - both file1 and file2. +.. signature:: if(IS_DIRECTORY <path>) -``if(IS_DIRECTORY path)`` - True if ``path`` is a directory. Behavior is well-defined only - for full paths. + True if ``path`` is a directory. Behavior is well-defined only + for full paths. - False if the given path is an empty string. + False if the given path is an empty string. -``if(IS_SYMLINK file-name)`` - True if the given name is a symbolic link. Behavior is well-defined - only for full paths. +.. signature:: if(IS_SYMLINK <path>) -``if(IS_ABSOLUTE path)`` - True if the given path is an absolute path. Note the following special - cases: + True if the given path is a symbolic link. Behavior is well-defined + only for full paths. - * An empty ``path`` evaluates to false. - * On Windows hosts, any ``path`` that begins with a drive letter and colon - (e.g. ``C:``), a forward slash or a backslash will evaluate to true. - This means a path like ``C:no\base\dir`` will evaluate to true, even - though the non-drive part of the path is relative. - * On non-Windows hosts, any ``path`` that begins with a tilde (``~``) - evaluates to true. +.. signature:: if(IS_ABSOLUTE <path>) + + True if the given path is an absolute path. Note the following special + cases: + + * An empty ``path`` evaluates to false. + * On Windows hosts, any ``path`` that begins with a drive letter and colon + (e.g. ``C:``), a forward slash or a backslash will evaluate to true. + This means a path like ``C:no\base\dir`` will evaluate to true, even + though the non-drive part of the path is relative. + * On non-Windows hosts, any ``path`` that begins with a tilde (``~``) + evaluates to true. Comparisons """"""""""" -.. _MATCHES: +.. signature:: if(<variable|string> MATCHES <regex>) + :target: MATCHES -``if(<variable|string> MATCHES regex)`` - True if the given string or variable's value matches the given regular - expression. See :ref:`Regex Specification` for regex format. + True if the given string or variable's value matches the given regular + expression. See :ref:`Regex Specification` for regex format. - .. versionadded:: 3.9 - ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. + .. versionadded:: 3.9 + ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables. -.. _LESS: +.. signature:: if(<variable|string> LESS <variable|string>) + :target: LESS -``if(<variable|string> LESS <variable|string>)`` - True if the given string or variable's value is a valid number and less - than that on the right. + True if the given string or variable's value is a valid number and less + than that on the right. -.. _GREATER: +.. signature:: if(<variable|string> GREATER <variable|string>) + :target: GREATER + + True if the given string or variable's value is a valid number and greater + than that on the right. -``if(<variable|string> GREATER <variable|string>)`` - True if the given string or variable's value is a valid number and greater - than that on the right. +.. signature:: if(<variable|string> EQUAL <variable|string>) + :target: EQUAL -.. _EQUAL: + True if the given string or variable's value is a valid number and equal + to that on the right. -``if(<variable|string> EQUAL <variable|string>)`` - True if the given string or variable's value is a valid number and equal - to that on the right. +.. signature:: if(<variable|string> LESS_EQUAL <variable|string>) + :target: LESS_EQUAL -.. _LESS_EQUAL: + .. versionadded:: 3.7 -``if(<variable|string> LESS_EQUAL <variable|string>)`` - .. versionadded:: 3.7 True if the given string or variable's value is a valid number and less than or equal to that on the right. -.. _GREATER_EQUAL: +.. signature:: if(<variable|string> GREATER_EQUAL <variable|string>) + :target: GREATER_EQUAL + + .. versionadded:: 3.7 -``if(<variable|string> GREATER_EQUAL <variable|string>)`` - .. versionadded:: 3.7 True if the given string or variable's value is a valid number and greater than or equal to that on the right. -.. _STRLESS: +.. signature:: if(<variable|string> STRLESS <variable|string>) + :target: STRLESS -``if(<variable|string> STRLESS <variable|string>)`` - True if the given string or variable's value is lexicographically less - than the string or variable on the right. + True if the given string or variable's value is lexicographically less + than the string or variable on the right. -.. _STRGREATER: +.. signature:: if(<variable|string> STRGREATER <variable|string>) + :target: STRGREATER -``if(<variable|string> STRGREATER <variable|string>)`` - True if the given string or variable's value is lexicographically greater - than the string or variable on the right. + True if the given string or variable's value is lexicographically greater + than the string or variable on the right. -.. _STREQUAL: +.. signature:: if(<variable|string> STREQUAL <variable|string>) + :target: STREQUAL -``if(<variable|string> STREQUAL <variable|string>)`` - True if the given string or variable's value is lexicographically equal - to the string or variable on the right. + True if the given string or variable's value is lexicographically equal + to the string or variable on the right. -.. _STRLESS_EQUAL: +.. signature:: if(<variable|string> STRLESS_EQUAL <variable|string>) + :target: STRLESS_EQUAL + + .. versionadded:: 3.7 -``if(<variable|string> STRLESS_EQUAL <variable|string>)`` - .. versionadded:: 3.7 True if the given string or variable's value is lexicographically less than or equal to the string or variable on the right. -.. _STRGREATER_EQUAL: +.. signature:: if(<variable|string> STRGREATER_EQUAL <variable|string>) + :target: STRGREATER_EQUAL + + .. versionadded:: 3.7 -``if(<variable|string> STRGREATER_EQUAL <variable|string>)`` - .. versionadded:: 3.7 True if the given string or variable's value is lexicographically greater than or equal to the string or variable on the right. Version Comparisons """"""""""""""""""" -.. _VERSION_LESS: +.. signature:: if(<variable|string> VERSION_LESS <variable|string>) + :target: VERSION_LESS -``if(<variable|string> VERSION_LESS <variable|string>)`` - Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). - Any non-integer version component or non-integer trailing part of a version - component effectively truncates the string at that point. + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. -.. _VERSION_GREATER: +.. signature:: if(<variable|string> VERSION_GREATER <variable|string>) + :target: VERSION_GREATER -``if(<variable|string> VERSION_GREATER <variable|string>)`` - Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). - Any non-integer version component or non-integer trailing part of a version - component effectively truncates the string at that point. + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. -.. _VERSION_EQUAL: +.. signature:: if(<variable|string> VERSION_EQUAL <variable|string>) + :target: VERSION_EQUAL -``if(<variable|string> VERSION_EQUAL <variable|string>)`` - Component-wise integer version number comparison (version format is - ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). - Any non-integer version component or non-integer trailing part of a version - component effectively truncates the string at that point. + Component-wise integer version number comparison (version format is + ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). + Any non-integer version component or non-integer trailing part of a version + component effectively truncates the string at that point. -.. _VERSION_LESS_EQUAL: +.. signature:: if(<variable|string> VERSION_LESS_EQUAL <variable|string>) + :target: VERSION_LESS_EQUAL + + .. versionadded:: 3.7 -``if(<variable|string> VERSION_LESS_EQUAL <variable|string>)`` - .. versionadded:: 3.7 Component-wise integer version number comparison (version format is ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). Any non-integer version component or non-integer trailing part of a version component effectively truncates the string at that point. -.. _VERSION_GREATER_EQUAL: +.. signature:: if(<variable|string> VERSION_GREATER_EQUAL <variable|string>) + :target: VERSION_GREATER_EQUAL + + .. versionadded:: 3.7 -``if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)`` - .. versionadded:: 3.7 Component-wise integer version number comparison (version format is ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero). Any non-integer version component or non-integer trailing part of a version @@ -321,9 +343,9 @@ Version Comparisons Path Comparisons """""""""""""""" -.. _PATH_EQUAL: +.. signature:: if(<variable|string> PATH_EQUAL <variable|string>) + :target: PATH_EQUAL -``if(<variable|string> PATH_EQUAL <variable|string>)`` .. versionadded:: 3.24 Compares the two paths component-by-component. Only if every component of @@ -386,35 +408,35 @@ constant. Automatic evaluation applies in the other cases whenever the above-documented condition syntax accepts ``<variable|string>``: -* The left hand argument to ``MATCHES`` is first checked to see if it is - a defined variable, if so the variable's value is used, otherwise the +* The left hand argument to `MATCHES`_ is first checked to see if it is + a defined variable. If so, the variable's value is used, otherwise the original value is used. -* If the left hand argument to ``MATCHES`` is missing it returns false +* If the left hand argument to `MATCHES`_ is missing it returns false without error -* Both left and right hand arguments to ``LESS``, ``GREATER``, ``EQUAL``, - ``LESS_EQUAL``, and ``GREATER_EQUAL``, are independently tested to see if - they are defined variables, if so their defined values are used otherwise +* Both left and right hand arguments to `LESS`_, `GREATER`_, `EQUAL`_, + `LESS_EQUAL`_, and `GREATER_EQUAL`_, are independently tested to see if + they are defined variables. If so, their defined values are used otherwise the original value is used. -* Both left and right hand arguments to ``STRLESS``, ``STRGREATER``, - ``STREQUAL``, ``STRLESS_EQUAL``, and ``STRGREATER_EQUAL`` are independently - tested to see if they are defined variables, if so their defined values are +* Both left and right hand arguments to `STRLESS`_, `STRGREATER`_, + `STREQUAL`_, `STRLESS_EQUAL`_, and `STRGREATER_EQUAL`_ are independently + tested to see if they are defined variables. If so, their defined values are used otherwise the original value is used. -* Both left and right hand arguments to ``VERSION_LESS``, - ``VERSION_GREATER``, ``VERSION_EQUAL``, ``VERSION_LESS_EQUAL``, and - ``VERSION_GREATER_EQUAL`` are independently tested to see if they are defined - variables, if so their defined values are used otherwise the original value +* Both left and right hand arguments to `VERSION_LESS`_, + `VERSION_GREATER`_, `VERSION_EQUAL`_, `VERSION_LESS_EQUAL`_, and + `VERSION_GREATER_EQUAL`_ are independently tested to see if they are defined + variables. If so, their defined values are used otherwise the original value is used. -* The right hand argument to ``NOT`` is tested to see if it is a boolean - constant, if so the value is used, otherwise it is assumed to be a +* The right hand argument to `NOT`_ is tested to see if it is a boolean + constant. If so, the value is used, otherwise it is assumed to be a variable and it is dereferenced. -* The left and right hand arguments to ``AND`` and ``OR`` are independently - tested to see if they are boolean constants, if so they are used as +* The left and right hand arguments to `AND`_ and `OR`_ are independently + tested to see if they are boolean constants. If so, they are used as such, otherwise they are assumed to be variables and are dereferenced. .. versionchanged:: 3.1 diff --git a/Help/command/install.rst b/Help/command/install.rst index 126888aa7a..d5092ae12e 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -158,6 +158,9 @@ that may be installed: ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``); * On AIX, the *linker import file* created for executables with :prop_tgt:`ENABLE_EXPORTS` enabled. + * On macOS, the *linker import file* created for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled (except when marked as ``FRAMEWORK``, + see below). ``LIBRARY`` Target artifacts of this kind include: @@ -308,6 +311,11 @@ the following additional arguments: value of ``COMPONENT``. It is an error to use this parameter outside of a ``LIBRARY`` block. + .. versionchanged:: 3.27 + This parameter is also usable for an ``ARCHIVE`` block to manage + the linker import file created, on macOS, for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled. + Consider the following example: .. code-block:: cmake @@ -342,6 +350,11 @@ the following additional arguments: option installs nothing. It is an error to use this parameter outside of a ``LIBRARY`` block. + .. versionchanged:: 3.27 + This parameter is also usable for an ``ARCHIVE`` block to manage + the linker import file created, on macOS, for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled. + When ``NAMELINK_ONLY`` is given, either ``NAMELINK_COMPONENT`` or ``COMPONENT`` may be used to specify the installation component of the namelink, but ``COMPONENT`` should generally be preferred. @@ -355,6 +368,11 @@ the following additional arguments: installs the library. It is an error to use this parameter outside of a ``LIBRARY`` block. + .. versionchanged:: 3.27 + This parameter is also usable for an ``ARCHIVE`` block to manage + the linker import file created, on macOS, for shared libraries with + :prop_tgt:`ENABLE_EXPORTS` enabled. + If ``NAMELINK_SKIP`` is specified, ``NAMELINK_COMPONENT`` has no effect. It is not recommended to use ``NAMELINK_SKIP`` in conjunction with ``NAMELINK_COMPONENT``. diff --git a/Help/command/list.rst b/Help/command/list.rst index 33c4f80d24..191003a700 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -36,23 +36,25 @@ Synopsis Introduction ^^^^^^^^^^^^ -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``, -``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``, -``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create -new values for the list within the current CMake variable scope. Similar to -the :command:`set` command, the LIST command creates new variable values in -the current scope, even if the list itself is actually defined in a parent -scope. To propagate the results of these operations upwards, use -:command:`set` with ``PARENT_SCOPE``, :command:`set` with -``CACHE INTERNAL``, or some other means of value propagation. +The list subcommands :cref:`APPEND`, :cref:`INSERT`, :cref:`FILTER`, +:cref:`PREPEND`, :cref:`POP_BACK`, :cref:`POP_FRONT`, :cref:`REMOVE_AT`, +:cref:`REMOVE_ITEM`, :cref:`REMOVE_DUPLICATES`, :cref:`REVERSE` and +:cref:`SORT` may create new values for the list within the current CMake +variable scope. Similar to the :command:`set` command, the ``list`` command +creates new variable values in the current scope, even if the list itself is +actually defined in a parent scope. To propagate the results of these +operations upwards, use :command:`set` with ``PARENT_SCOPE``, +:command:`set` with ``CACHE INTERNAL``, or some other means of value +propagation. .. note:: A list in cmake is a ``;`` separated group of strings. To create a - list the set command can be used. For example, ``set(var a b c d e)`` - creates a list with ``a;b;c;d;e``, and ``set(var "a b c d e")`` creates a - string or a list with one item in it. (Note macro arguments are not - variables, and therefore cannot be used in LIST commands.) + list, the :command:`set` command can be used. For example, + ``set(var a b c d e)`` creates a list with ``a;b;c;d;e``, and + ``set(var "a b c d e")`` creates a string or a list with one item in it. + (Note that macro arguments are not variables, and therefore cannot be used + in ``LIST`` commands.) .. note:: @@ -66,76 +68,54 @@ scope. To propagate the results of these operations upwards, use Reading ^^^^^^^ -.. _LENGTH: - -.. code-block:: cmake - +.. signature:: list(LENGTH <list> <output variable>) -Returns the list's length. - -.. _GET: - -.. code-block:: cmake + Returns the list's length. +.. signature:: list(GET <list> <element index> [<element index> ...] <output variable>) -Returns the list of elements specified by indices from the list. - -.. _JOIN: + Returns the list of elements specified by indices from the list. -.. code-block:: cmake +.. signature:: list(JOIN <list> <glue> <output variable>) - list(JOIN <list> <glue> <output variable>) + .. versionadded:: 3.12 -.. versionadded:: 3.12 - -Returns a string joining all list's elements using the glue string. -To join multiple strings, which are not part of a list, use ``JOIN`` operator -from :command:`string` command. - -.. _SUBLIST: - -.. code-block:: cmake + Returns a string joining all list's elements using the glue string. + To join multiple strings, which are not part of a list, + use :command:`string(JOIN)`. +.. signature:: list(SUBLIST <list> <begin> <length> <output variable>) -.. versionadded:: 3.12 + .. versionadded:: 3.12 -Returns a sublist of the given list. -If ``<length>`` is 0, an empty list will be returned. -If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then -the remaining elements of the list starting at ``<begin>`` will be returned. + Returns a sublist of the given list. + If ``<length>`` is 0, an empty list will be returned. + If ``<length>`` is -1 or the list is smaller than ``<begin>+<length>`` then + the remaining elements of the list starting at ``<begin>`` will be returned. Search ^^^^^^ -.. _FIND: - -.. code-block:: cmake - +.. signature:: list(FIND <list> <value> <output variable>) -Returns the index of the element specified in the list or -1 -if it wasn't found. + Returns the index of the element specified in the list + or ``-1`` if it wasn't found. Modification ^^^^^^^^^^^^ -.. _APPEND: - -.. code-block:: cmake - +.. signature:: list(APPEND <list> [<element> ...]) -Appends elements to the list. If no variable named ``<list>`` exists in the -current scope its value is treated as empty and the elements are appended to -that empty list. - -.. _FILTER: - -.. code-block:: cmake + Appends elements to the list. If no variable named ``<list>`` exists in the + current scope its value is treated as empty and the elements are appended to + that empty list. +.. signature:: list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) .. versionadded:: 3.6 @@ -146,219 +126,205 @@ In ``REGEX`` mode, items will be matched against the given regular expression. For more information on regular expressions look under :ref:`string(REGEX) <Regex Specification>`. -.. _INSERT: - -.. code-block:: cmake - +.. signature:: list(INSERT <list> <element_index> <element> [<element> ...]) -Inserts elements to the list to the specified index. It is an -error to specify an out-of-range index. Valid indexes are 0 to `N` -where `N` is the length of the list, inclusive. An empty list -has length 0. If no variable named ``<list>`` exists in the -current scope its value is treated as empty and the elements are -inserted in that empty list. - -.. _POP_BACK: - -.. code-block:: cmake + Inserts elements to the list to the specified index. It is an + error to specify an out-of-range index. Valid indexes are 0 to `N` + where `N` is the length of the list, inclusive. An empty list + has length 0. If no variable named ``<list>`` exists in the + current scope its value is treated as empty and the elements are + inserted in that empty list. +.. signature:: list(POP_BACK <list> [<out-var>...]) -.. versionadded:: 3.15 + .. versionadded:: 3.15 -If no variable name is given, removes exactly one element. Otherwise, -with `N` variable names provided, assign the last `N` elements' values -to the given variables and then remove the last `N` values from -``<list>``. - -.. _POP_FRONT: - -.. code-block:: cmake + If no variable name is given, removes exactly one element. Otherwise, + with `N` variable names provided, assign the last `N` elements' values + to the given variables and then remove the last `N` values from + ``<list>``. +.. signature:: list(POP_FRONT <list> [<out-var>...]) -.. versionadded:: 3.15 - -If no variable name is given, removes exactly one element. Otherwise, -with `N` variable names provided, assign the first `N` elements' values -to the given variables and then remove the first `N` values from -``<list>``. + .. versionadded:: 3.15 -.. _PREPEND: - -.. code-block:: cmake + If no variable name is given, removes exactly one element. Otherwise, + with `N` variable names provided, assign the first `N` elements' values + to the given variables and then remove the first `N` values from + ``<list>``. +.. signature:: list(PREPEND <list> [<element> ...]) -.. versionadded:: 3.15 - -Insert elements to the 0th position in the list. If no variable named -``<list>`` exists in the current scope its value is treated as empty and -the elements are prepended to that empty list. + .. versionadded:: 3.15 -.. _REMOVE_ITEM: - -.. code-block:: cmake + Insert elements to the 0th position in the list. If no variable named + ``<list>`` exists in the current scope its value is treated as empty and + the elements are prepended to that empty list. +.. signature:: list(REMOVE_ITEM <list> <value> [<value> ...]) -Removes all instances of the given items from the list. - -.. _REMOVE_AT: - -.. code-block:: cmake + Removes all instances of the given items from the list. +.. signature:: list(REMOVE_AT <list> <index> [<index> ...]) -Removes items at given indices from the list. - -.. _REMOVE_DUPLICATES: - -.. code-block:: cmake + Removes items at given indices from the list. +.. signature:: list(REMOVE_DUPLICATES <list>) -Removes duplicated items in the list. The relative order of items is preserved, -but if duplicates are encountered, only the first instance is preserved. - -.. _TRANSFORM: - -.. code-block:: cmake + Removes duplicated items in the list. The relative order of items + is preserved, but if duplicates are encountered, + only the first instance is preserved. +.. signature:: list(TRANSFORM <list> <ACTION> [<SELECTOR>] - [OUTPUT_VARIABLE <output variable>]) + [OUTPUT_VARIABLE <output variable>]) -.. versionadded:: 3.12 + .. versionadded:: 3.12 -Transforms the list by applying an action to all or, by specifying a -``<SELECTOR>``, to the selected elements of the list, storing the result -in-place or in the specified output variable. + Transforms the list by applying an action to all or, by specifying a + ``<SELECTOR>``, to the selected elements of the list, storing the result + in-place or in the specified output variable. -.. note:: + .. note:: - The ``TRANSFORM`` sub-command does not change the number of elements in the - list. If a ``<SELECTOR>`` is specified, only some elements will be changed, - the other ones will remain the same as before the transformation. + The ``TRANSFORM`` sub-command does not change the number of elements in the + list. If a ``<SELECTOR>`` is specified, only some elements will be changed, + the other ones will remain the same as before the transformation. -``<ACTION>`` specifies the action to apply to the elements of the list. -The actions have exactly the same semantics as sub-commands of the -:command:`string` command. ``<ACTION>`` must be one of the following: + ``<ACTION>`` specifies the action to apply to the elements of the list. + The actions have exactly the same semantics as sub-commands of the + :command:`string` command. ``<ACTION>`` must be one of the following: -``APPEND``, ``PREPEND``: Append, prepend specified value to each element of -the list. + :command:`APPEND <string(APPEND)>`, :command:`PREPEND <string(PREPEND)>` + Append, prepend specified value to each element of the list. - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) + list(TRANSFORM <list> <APPEND|PREPEND> <value> ...) -``TOUPPER``, ``TOLOWER``: Convert each element of the list to upper, lower -characters. + :command:`TOUPPER <string(TOUPPER)>`, :command:`TOLOWER <string(TOLOWER)>` + Convert each element of the list to upper, lower characters. - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) + list(TRANSFORM <list> <TOLOWER|TOUPPER> ...) -``STRIP``: Remove leading and trailing spaces from each element of the -list. + :command:`STRIP <string(STRIP)>` + Remove leading and trailing spaces from each element of the list. - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> STRIP ...) + list(TRANSFORM <list> STRIP ...) -``GENEX_STRIP``: Strip any -:manual:`generator expressions <cmake-generator-expressions(7)>` from each -element of the list. + :command:`GENEX_STRIP <string(GENEX_STRIP)>` + Strip any + :manual:`generator expressions <cmake-generator-expressions(7)>` + from each element of the list. - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> GENEX_STRIP ...) + list(TRANSFORM <list> GENEX_STRIP ...) -``REPLACE``: Match the regular expression as many times as possible and -substitute the replacement expression for the match for each element -of the list -(Same semantic as ``REGEX REPLACE`` from :command:`string` command). + :command:`REPLACE <string(REGEX REPLACE)>`: + Match the regular expression as many times as possible and substitute + the replacement expression for the match for each element of the list + (same semantic as :command:`string(REGEX REPLACE)`). - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> REPLACE <regular_expression> - <replace_expression> ...) + list(TRANSFORM <list> REPLACE <regular_expression> + <replace_expression> ...) -``<SELECTOR>`` determines which elements of the list will be transformed. -Only one type of selector can be specified at a time. When given, -``<SELECTOR>`` must be one of the following: + ``<SELECTOR>`` determines which elements of the list will be transformed. + Only one type of selector can be specified at a time. + When given, ``<SELECTOR>`` must be one of the following: -``AT``: Specify a list of indexes. + ``AT`` + Specify a list of indexes. - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) + list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...) -``FOR``: Specify a range with, optionally, an increment used to iterate over -the range. + ``FOR`` + Specify a range with, optionally, + an increment used to iterate over the range. - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) + list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...) -``REGEX``: Specify a regular expression. Only elements matching the regular -expression will be transformed. + ``REGEX`` + Specify a regular expression. + Only elements matching the regular expression will be transformed. - .. code-block:: cmake + .. code-block:: cmake - list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) + list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...) Ordering ^^^^^^^^ -.. _REVERSE: +.. signature:: + list(REVERSE <list>) -.. code-block:: cmake + Reverses the contents of the list in-place. - list(REVERSE <list>) +.. signature:: + list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) -Reverses the contents of the list in-place. + Sorts the list in-place alphabetically. -.. _SORT: + .. versionadded:: 3.13 + Added the ``COMPARE``, ``CASE``, and ``ORDER`` options. -.. code-block:: cmake + .. versionadded:: 3.18 + Added the ``COMPARE NATURAL`` option. - list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>]) + Use the ``COMPARE`` keyword to select the comparison method for sorting. + The ``<compare>`` option should be one of: -Sorts the list in-place alphabetically. + ``STRING`` + Sorts a list of strings alphabetically. + This is the default behavior if the ``COMPARE`` option is not given. -.. versionadded:: 3.13 - Added the ``COMPARE``, ``CASE``, and ``ORDER`` options. + ``FILE_BASENAME`` + Sorts a list of pathnames of files by their basenames. -.. versionadded:: 3.18 - Added the ``COMPARE NATURAL`` option. + ``NATURAL`` + Sorts a list of strings using natural order + (see ``strverscmp(3)`` manual), i.e. such that contiguous digits + are compared as whole numbers. + For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1` + will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL`` + comparison is selected where it will be sorted as + `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison. -Use the ``COMPARE`` keyword to select the comparison method for sorting. -The ``<compare>`` option should be one of: + Use the ``CASE`` keyword to select a case sensitive or case insensitive + sort mode. The ``<case>`` option should be one of: -* ``STRING``: Sorts a list of strings alphabetically. This is the - default behavior if the ``COMPARE`` option is not given. -* ``FILE_BASENAME``: Sorts a list of pathnames of files by their basenames. -* ``NATURAL``: Sorts a list of strings using natural order - (see ``strverscmp(3)`` manual), i.e. such that contiguous digits - are compared as whole numbers. - For example: the following list `10.0 1.1 2.1 8.0 2.0 3.1` - will be sorted as `1.1 2.0 2.1 3.1 8.0 10.0` if the ``NATURAL`` - comparison is selected where it will be sorted as - `1.1 10.0 2.0 2.1 3.1 8.0` with the ``STRING`` comparison. + ``SENSITIVE`` + List items are sorted in a case-sensitive manner. + This is the default behavior if the ``CASE`` option is not given. -Use the ``CASE`` keyword to select a case sensitive or case insensitive -sort mode. The ``<case>`` option should be one of: + ``INSENSITIVE`` + List items are sorted case insensitively. The order of + items which differ only by upper/lowercase is not specified. -* ``SENSITIVE``: List items are sorted in a case-sensitive manner. This is - the default behavior if the ``CASE`` option is not given. -* ``INSENSITIVE``: List items are sorted case insensitively. The order of - items which differ only by upper/lowercase is not specified. + To control the sort order, the ``ORDER`` keyword can be given. + The ``<order>`` option should be one of: -To control the sort order, the ``ORDER`` keyword can be given. -The ``<order>`` option should be one of: + ``ASCENDING`` + Sorts the list in ascending order. + This is the default behavior when the ``ORDER`` option is not given. -* ``ASCENDING``: Sorts the list in ascending order. This is the default - behavior when the ``ORDER`` option is not given. -* ``DESCENDING``: Sorts the list in descending order. + ``DESCENDING`` + Sorts the list in descending order. diff --git a/Help/command/math.rst b/Help/command/math.rst index 8386aabc6f..6989ebcacd 100644 --- a/Help/command/math.rst +++ b/Help/command/math.rst @@ -9,7 +9,8 @@ Evaluate a mathematical expression. Evaluates a mathematical ``<expression>`` and sets ``<variable>`` to the resulting value. The result of the expression must be representable as a -64-bit signed integer. +64-bit signed integer. Floating point inputs are invalid e.g. ``1.1 * 10``. +Non-integer results e.g. ``3 / 2`` are truncated. The mathematical expression must be given as a string (i.e. enclosed in double quotation marks). An example is ``"5 * (10 + 13)"``. diff --git a/Help/command/separate_arguments.rst b/Help/command/separate_arguments.rst index f66af35a57..4f0b25eb26 100644 --- a/Help/command/separate_arguments.rst +++ b/Help/command/separate_arguments.rst @@ -69,7 +69,7 @@ be one of the following keywords: The contents of ``out`` will be: ``/path/to/cc;-c;main.c`` -.. _`Parsing C Command-Line Arguments`: https://msdn.microsoft.com/library/a1y7w461.aspx +.. _`Parsing C Command-Line Arguments`: https://learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments .. code-block:: cmake diff --git a/Help/command/set.rst b/Help/command/set.rst index c724844813..aeb88b360c 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -8,109 +8,119 @@ and cache entries. Signatures of this command that specify a ``<value>...`` placeholder expect zero or more arguments. Multiple arguments will be joined as -a :ref:`semicolon-separated list <CMake Language Lists>` to form the actual variable -value to be set. Zero arguments will cause normal variables to be -unset. See the :command:`unset` command to unset variables explicitly. +a :ref:`semicolon-separated list <CMake Language Lists>` to form the +actual variable value to be set. Set Normal Variable ^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: set(<variable> <value>... [PARENT_SCOPE]) + :target: normal + + Set or unset ``<variable>`` in the current function or directory scope: + + * If at least one ``<value>...`` is given, set the variable to that value. + * If no value is given, unset the variable. This is equivalent to + :command:`unset(<variable>) <unset>`. -Sets the given ``<variable>`` in the current function or directory scope. + If the ``PARENT_SCOPE`` option is given the variable will be set in + the scope above the current scope. Each new directory or :command:`function` + command creates a new scope. A scope can also be created with the + :command:`block` command. This command will set the value of a variable into + the parent directory, calling function or encompassing scope (whichever is + applicable to the case at hand). The previous state of the variable's value + stays the same in the current scope (e.g., if it was undefined before, it is + still undefined and if it had a value, it is still that value). -If the ``PARENT_SCOPE`` option is given the variable will be set in -the scope above the current scope. Each new directory or :command:`function` -command creates a new scope. A scope can also be created with the -:command:`block` command. This command will set the value of a variable into -the parent directory, calling function or encompassing scope (whichever is -applicable to the case at hand). The previous state of the variable's value -stays the same in the current scope (e.g., if it was undefined before, it is -still undefined and if it had a value, it is still that value). + The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands + can be used as an alternate method to the :command:`set(PARENT_SCOPE)` + and :command:`unset(PARENT_SCOPE)` commands to update the parent scope. -The :command:`block(PROPAGATE)` and :command:`return(PROPAGATE)` commands can -be used as an alternate method to the :command:`set(PARENT_SCOPE)` and -:command:`unset(PARENT_SCOPE)` commands to update the parent scope. +.. include:: UNSET_NOTE.txt Set Cache Entry ^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: set(<variable> <value>... CACHE <type> <docstring> [FORCE]) - -Sets the given cache ``<variable>`` (cache entry). Since cache entries -are meant to provide user-settable values this does not overwrite -existing cache entries by default. Use the ``FORCE`` option to -overwrite existing entries. - -The ``<type>`` must be specified as one of: - -``BOOL`` - Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox. - -``FILEPATH`` - Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog. - -``PATH`` - Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog. - -``STRING`` - A line of text. :manual:`cmake-gui(1)` offers a text field or a - drop-down selection if the :prop_cache:`STRINGS` cache entry - property is set. - -``INTERNAL`` - A line of text. :manual:`cmake-gui(1)` does not show internal entries. - They may be used to store variables persistently across runs. - Use of this type implies ``FORCE``. - -The ``<docstring>`` must be specified as a line of text providing -a quick summary of the option for presentation to :manual:`cmake-gui(1)` -users. - -If the cache entry does not exist prior to the call or the ``FORCE`` -option is given then the cache entry will be set to the given value. - -.. note:: - - The content of the cache variable will not be directly accessible if a normal - variable of the same name already exists (see :ref:`rules of variable - evaluation <CMake Language Variables>`). If policy :policy:`CMP0126` is set - to ``OLD``, any normal variable binding in the current scope will be removed. - -It is possible for the cache entry to exist prior to the call but -have no type set if it was created on the :manual:`cmake(1)` command -line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option without -specifying a type. In this case the ``set`` command will add the -type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH`` -and the ``<value>`` provided on the command line is a relative path, -then the ``set`` command will treat the path as relative to the -current working directory and convert it to an absolute path. + :target: CACHE + + Sets the given cache ``<variable>`` (cache entry). Since cache entries + are meant to provide user-settable values this does not overwrite + existing cache entries by default. Use the ``FORCE`` option to + overwrite existing entries. + + The ``<type>`` must be specified as one of: + + ``BOOL`` + Boolean ``ON/OFF`` value. + :manual:`cmake-gui(1)` offers a checkbox. + + ``FILEPATH`` + Path to a file on disk. + :manual:`cmake-gui(1)` offers a file dialog. + + ``PATH`` + Path to a directory on disk. + :manual:`cmake-gui(1)` offers a file dialog. + + ``STRING`` + A line of text. + :manual:`cmake-gui(1)` offers a text field or a drop-down selection + if the :prop_cache:`STRINGS` cache entry property is set. + + ``INTERNAL`` + A line of text. + :manual:`cmake-gui(1)` does not show internal entries. + They may be used to store variables persistently across runs. + Use of this type implies ``FORCE``. + + The ``<docstring>`` must be specified as a line of text + providing a quick summary of the option + for presentation to :manual:`cmake-gui(1)` users. + + If the cache entry does not exist prior to the call or the ``FORCE`` + option is given then the cache entry will be set to the given value. + + .. note:: + + The content of the cache variable will not be directly accessible + if a normal variable of the same name already exists + (see :ref:`rules of variable evaluation <CMake Language Variables>`). + If policy :policy:`CMP0126` is set to ``OLD``, any normal variable + binding in the current scope will be removed. + + It is possible for the cache entry to exist prior to the call but + have no type set if it was created on the :manual:`cmake(1)` command + line by a user through the :option:`-D\<var\>=\<value\> <cmake -D>` option + without specifying a type. In this case the ``set`` command will add the + type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH`` + and the ``<value>`` provided on the command line is a relative path, + then the ``set`` command will treat the path as relative to the + current working directory and convert it to an absolute path. Set Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake - +.. signature:: set(ENV{<variable>} [<value>]) + :target: ENV -Sets an :manual:`Environment Variable <cmake-env-variables(7)>` -to the given value. -Subsequent calls of ``$ENV{<variable>}`` will return this new value. + Sets an :manual:`Environment Variable <cmake-env-variables(7)>` + to the given value. + Subsequent calls of ``$ENV{<variable>}`` will return this new value. -This command affects only the current CMake process, not the process -from which CMake was called, nor the system environment at large, -nor the environment of subsequent build or test processes. + This command affects only the current CMake process, not the process + from which CMake was called, nor the system environment at large, + nor the environment of subsequent build or test processes. -If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is -an empty string, then this command will clear any existing value of the -environment variable. + If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is + an empty string, then this command will clear any existing value of the + environment variable. -Arguments after ``<value>`` are ignored. If extra arguments are found, -then an author warning is issued. + Arguments after ``<value>`` are ignored. If extra arguments are found, + then an author warning is issued. See Also ^^^^^^^^ diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index d446a2d6fe..8dd4b94b9f 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -82,15 +82,15 @@ It must be one of the following: to the installation prefix. ``TEST`` - Scope may name zero or more existing tests. - See also the :command:`set_tests_properties` command. + Scope is limited to the directory the command is called in. It may name zero + or more existing tests. See also command :command:`set_tests_properties`. Test property values may be specified using :manual:`generator expressions <cmake-generator-expressions(7)>` for tests created by the :command:`add_test(NAME)` signature. ``CACHE`` - Scope must name zero or more cache existing entries. + Scope must name zero or more existing cache entries. The required ``PROPERTY`` option is immediately followed by the name of the property to set. Remaining arguments are used to compose the diff --git a/Help/command/string.rst b/Help/command/string.rst index c24b9bc16a..e226aa1a48 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -32,7 +32,7 @@ Synopsis string(`COMPARE`_ <op> <string1> <string2> <out-var>) `Hashing`_ - string(`\<HASH\> <HASH_>`_ <out-var> <input>) + string(`\<HASH\>`_ <out-var> <input>) `Generation`_ string(`ASCII`_ <number>... <out-var>) @@ -45,16 +45,16 @@ Synopsis `JSON`_ string(JSON <out-var> [ERROR_VARIABLE <error-var>] - {:ref:`GET <JSON_GET>` | :ref:`TYPE <JSON_TYPE>` | :ref:`LENGTH <JSON_LENGTH>` | :ref:`REMOVE <JSON_REMOVE>`} + {`GET <JSON GET_>`_ | `TYPE <JSON TYPE_>`_ | `LENGTH <JSON LENGTH_>`_ | `REMOVE <JSON REMOVE_>`_} <json-string> <member|index> [<member|index> ...]) string(JSON <out-var> [ERROR_VARIABLE <error-var>] - :ref:`MEMBER <JSON_MEMBER>` <json-string> + `MEMBER <JSON MEMBER_>`_ <json-string> [<member|index> ...] <index>) string(JSON <out-var> [ERROR_VARIABLE <error-var>] - :ref:`SET <JSON_SET>` <json-string> + `SET <JSON SET_>`_ <json-string> <member|index> [<member|index> ...] <value>) string(JSON <out-var> [ERROR_VARIABLE <error-var>] - :ref:`EQUAL <JSON_EQUAL>` <json-string1> <json-string2>) + `EQUAL <JSON EQUAL_>`_ <json-string1> <json-string2>) Search and Replace ^^^^^^^^^^^^^^^^^^ @@ -62,75 +62,60 @@ Search and Replace Search and Replace With Plain Strings """"""""""""""""""""""""""""""""""""" -.. _FIND: - -.. code-block:: cmake - +.. signature:: string(FIND <string> <substring> <output_variable> [REVERSE]) -Return the position where the given ``<substring>`` was found in -the supplied ``<string>``. If the ``REVERSE`` flag was used, the command will -search for the position of the last occurrence of the specified -``<substring>``. If the ``<substring>`` is not found, a position of -1 is -returned. - -The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. -The index stored in ``<output_variable>`` will also be counted in bytes, -so strings containing multi-byte characters may lead to unexpected results. + Return the position where the given ``<substring>`` was found in + the supplied ``<string>``. If the ``REVERSE`` flag was used, the command + will search for the position of the last occurrence of the specified + ``<substring>``. If the ``<substring>`` is not found, a position of -1 is + returned. -.. _REPLACE: - -.. code-block:: cmake + The ``string(FIND)`` subcommand treats all strings as ASCII-only characters. + The index stored in ``<output_variable>`` will also be counted in bytes, + so strings containing multi-byte characters may lead to unexpected results. +.. signature:: string(REPLACE <match_string> <replace_string> <output_variable> <input> [<input>...]) -Replace all occurrences of ``<match_string>`` in the ``<input>`` -with ``<replace_string>`` and store the result in the ``<output_variable>``. + Replace all occurrences of ``<match_string>`` in the ``<input>`` + with ``<replace_string>`` and store the result in the ``<output_variable>``. Search and Replace With Regular Expressions """"""""""""""""""""""""""""""""""""""""""" -.. _`REGEX MATCH`: - -.. code-block:: cmake - +.. signature:: string(REGEX MATCH <regular_expression> <output_variable> <input> [<input>...]) -Match the ``<regular_expression>`` once and store the match in the -``<output_variable>``. -All ``<input>`` arguments are concatenated before matching. -Regular expressions are specified in the subsection just below. - -.. _`REGEX MATCHALL`: - -.. code-block:: cmake + Match the ``<regular_expression>`` once and store the match in the + ``<output_variable>``. + All ``<input>`` arguments are concatenated before matching. + Regular expressions are specified in the subsection just below. +.. signature:: string(REGEX MATCHALL <regular_expression> <output_variable> <input> [<input>...]) -Match the ``<regular_expression>`` as many times as possible and store the -matches in the ``<output_variable>`` as a list. -All ``<input>`` arguments are concatenated before matching. - -.. _`REGEX REPLACE`: - -.. code-block:: cmake + Match the ``<regular_expression>`` as many times as possible and store the + matches in the ``<output_variable>`` as a list. + All ``<input>`` arguments are concatenated before matching. +.. signature:: string(REGEX REPLACE <regular_expression> <replacement_expression> <output_variable> <input> [<input>...]) -Match the ``<regular_expression>`` as many times as possible and substitute -the ``<replacement_expression>`` for the match in the output. -All ``<input>`` arguments are concatenated before matching. + Match the ``<regular_expression>`` as many times as possible and substitute + the ``<replacement_expression>`` for the match in the output. + All ``<input>`` arguments are concatenated before matching. -The ``<replacement_expression>`` may refer to parenthesis-delimited -subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that -two backslashes (``\\1``) are required in CMake code to get a backslash -through argument parsing. + The ``<replacement_expression>`` may refer to parenthesis-delimited + subexpressions of the match using ``\1``, ``\2``, ..., ``\9``. Note that + two backslashes (``\\1``) are required in CMake code to get a backslash + through argument parsing. .. _`Regex Specification`: @@ -201,130 +186,100 @@ newlines, and backslashes (respectively) to pass in a regex. For example: Manipulation ^^^^^^^^^^^^ -.. _APPEND: - -.. code-block:: cmake - +.. signature:: string(APPEND <string_variable> [<input>...]) -.. versionadded:: 3.4 - -Append all the ``<input>`` arguments to the string. + .. versionadded:: 3.4 -.. _PREPEND: - -.. code-block:: cmake + Append all the ``<input>`` arguments to the string. +.. signature:: string(PREPEND <string_variable> [<input>...]) -.. versionadded:: 3.10 - -Prepend all the ``<input>`` arguments to the string. - -.. _CONCAT: + .. versionadded:: 3.10 -.. code-block:: cmake + Prepend all the ``<input>`` arguments to the string. +.. signature:: string(CONCAT <output_variable> [<input>...]) -Concatenate all the ``<input>`` arguments together and store -the result in the named ``<output_variable>``. - -.. _JOIN: - -.. code-block:: cmake + Concatenate all the ``<input>`` arguments together and store + the result in the named ``<output_variable>``. +.. signature:: string(JOIN <glue> <output_variable> [<input>...]) -.. versionadded:: 3.12 - -Join all the ``<input>`` arguments together using the ``<glue>`` -string and store the result in the named ``<output_variable>``. - -To join a list's elements, prefer to use the ``JOIN`` operator -from the :command:`list` command. This allows for the elements to have -special characters like ``;`` in them. + .. versionadded:: 3.12 -.. _TOLOWER: + Join all the ``<input>`` arguments together using the ``<glue>`` + string and store the result in the named ``<output_variable>``. -.. code-block:: cmake + To join a list's elements, prefer to use the ``JOIN`` operator + from the :command:`list` command. This allows for the elements to have + special characters like ``;`` in them. +.. signature:: string(TOLOWER <string> <output_variable>) -Convert ``<string>`` to lower characters. - -.. _TOUPPER: - -.. code-block:: cmake + Convert ``<string>`` to lower characters. +.. signature:: string(TOUPPER <string> <output_variable>) -Convert ``<string>`` to upper characters. - -.. _LENGTH: - -.. code-block:: cmake + Convert ``<string>`` to upper characters. +.. signature:: string(LENGTH <string> <output_variable>) -Store in an ``<output_variable>`` a given string's length in bytes. -Note that this means if ``<string>`` contains multi-byte characters, the -result stored in ``<output_variable>`` will *not* be the number of characters. - -.. _SUBSTRING: - -.. code-block:: cmake + Store in an ``<output_variable>`` a given string's length in bytes. + Note that this means if ``<string>`` contains multi-byte characters, + the result stored in ``<output_variable>`` will *not* be + the number of characters. +.. signature:: string(SUBSTRING <string> <begin> <length> <output_variable>) -Store in an ``<output_variable>`` a substring of a given ``<string>``. If -``<length>`` is ``-1`` the remainder of the string starting at ``<begin>`` -will be returned. - -.. versionchanged:: 3.2 - If ``<string>`` is shorter than ``<length>`` then the end of the string - is used instead. Previous versions of CMake reported an error in this case. - -Both ``<begin>`` and ``<length>`` are counted in bytes, so care must -be exercised if ``<string>`` could contain multi-byte characters. + Store in an ``<output_variable>`` a substring of a given ``<string>``. If + ``<length>`` is ``-1`` the remainder of the string starting at ``<begin>`` + will be returned. -.. _STRIP: + .. versionchanged:: 3.2 + If ``<string>`` is shorter than ``<length>`` + then the end of the string is used instead. + Previous versions of CMake reported an error in this case. -.. code-block:: cmake + Both ``<begin>`` and ``<length>`` are counted in bytes, so care must + be exercised if ``<string>`` could contain multi-byte characters. +.. signature:: string(STRIP <string> <output_variable>) -Store in an ``<output_variable>`` a substring of a given ``<string>`` with -leading and trailing spaces removed. - -.. _GENEX_STRIP: - -.. code-block:: cmake + Store in an ``<output_variable>`` a substring of a given ``<string>`` + with leading and trailing spaces removed. +.. signature:: string(GENEX_STRIP <string> <output_variable>) -.. versionadded:: 3.1 - -Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` -from the input ``<string>`` and store the result in the ``<output_variable>``. - -.. _REPEAT: + .. versionadded:: 3.1 -.. code-block:: cmake + Strip any :manual:`generator expressions <cmake-generator-expressions(7)>` + from the input ``<string>`` and store the result + in the ``<output_variable>``. +.. signature:: string(REPEAT <string> <count> <output_variable>) -.. versionadded:: 3.15 + .. versionadded:: 3.15 -Produce the output string as the input ``<string>`` repeated ``<count>`` times. + Produce the output string as the input ``<string>`` + repeated ``<count>`` times. Comparison ^^^^^^^^^^ .. _COMPARE: -.. code-block:: cmake - +.. signature:: string(COMPARE LESS <string1> <string2> <output_variable>) string(COMPARE GREATER <string1> <string2> <output_variable>) string(COMPARE EQUAL <string1> <string2> <output_variable>) @@ -332,240 +287,217 @@ Comparison string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>) string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>) -Compare the strings and store true or false in the ``<output_variable>``. + Compare the strings and store true or false in the ``<output_variable>``. -.. versionadded:: 3.7 - Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. + .. versionadded:: 3.7 + Added the ``LESS_EQUAL`` and ``GREATER_EQUAL`` options. .. _`Supported Hash Algorithms`: Hashing ^^^^^^^ -.. _`HASH`: - -.. code-block:: cmake - +.. signature:: string(<HASH> <output_variable> <input>) + :target: <HASH> + + Compute a cryptographic hash of the ``<input>`` string. + The supported ``<HASH>`` algorithm names are: + + ``MD5`` + Message-Digest Algorithm 5, RFC 1321. + ``SHA1`` + US Secure Hash Algorithm 1, RFC 3174. + ``SHA224`` + US Secure Hash Algorithms, RFC 4634. + ``SHA256`` + US Secure Hash Algorithms, RFC 4634. + ``SHA384`` + US Secure Hash Algorithms, RFC 4634. + ``SHA512`` + US Secure Hash Algorithms, RFC 4634. + ``SHA3_224`` + Keccak SHA-3. + ``SHA3_256`` + Keccak SHA-3. + ``SHA3_384`` + Keccak SHA-3. + ``SHA3_512`` + Keccak SHA-3. -Compute a cryptographic hash of the ``<input>`` string. -The supported ``<HASH>`` algorithm names are: - -``MD5`` - Message-Digest Algorithm 5, RFC 1321. -``SHA1`` - US Secure Hash Algorithm 1, RFC 3174. -``SHA224`` - US Secure Hash Algorithms, RFC 4634. -``SHA256`` - US Secure Hash Algorithms, RFC 4634. -``SHA384`` - US Secure Hash Algorithms, RFC 4634. -``SHA512`` - US Secure Hash Algorithms, RFC 4634. -``SHA3_224`` - Keccak SHA-3. -``SHA3_256`` - Keccak SHA-3. -``SHA3_384`` - Keccak SHA-3. -``SHA3_512`` - Keccak SHA-3. - -.. versionadded:: 3.8 - Added the ``SHA3_*`` hash algorithms. + .. versionadded:: 3.8 + Added the ``SHA3_*`` hash algorithms. Generation ^^^^^^^^^^ -.. _ASCII: - -.. code-block:: cmake - +.. signature:: string(ASCII <number> [<number> ...] <output_variable>) -Convert all numbers into corresponding ASCII characters. - -.. _HEX: - -.. code-block:: cmake + Convert all numbers into corresponding ASCII characters. +.. signature:: string(HEX <string> <output_variable>) -.. versionadded:: 3.18 - -Convert each byte in the input ``<string>`` to its hexadecimal representation -and store the concatenated hex digits in the ``<output_variable>``. Letters in -the output (``a`` through ``f``) are in lowercase. + .. versionadded:: 3.18 -.. _CONFIGURE: - -.. code-block:: cmake + Convert each byte in the input ``<string>`` to its hexadecimal representation + and store the concatenated hex digits in the ``<output_variable>``. + Letters in the output (``a`` through ``f``) are in lowercase. +.. signature:: string(CONFIGURE <string> <output_variable> [@ONLY] [ESCAPE_QUOTES]) -Transform a ``<string>`` like :command:`configure_file` transforms a file. - -.. _MAKE_C_IDENTIFIER: - -.. code-block:: cmake + Transform a ``<string>`` like :command:`configure_file` transforms a file. +.. signature:: string(MAKE_C_IDENTIFIER <string> <output_variable>) -Convert each non-alphanumeric character in the input ``<string>`` to an -underscore and store the result in the ``<output_variable>``. If the first -character of the ``<string>`` is a digit, an underscore will also be prepended -to the result. - -.. _RANDOM: - -.. code-block:: cmake + Convert each non-alphanumeric character in the input ``<string>`` to an + underscore and store the result in the ``<output_variable>``. If the first + character of the ``<string>`` is a digit, an underscore will also be + prepended to the result. +.. signature:: string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] [RANDOM_SEED <seed>] <output_variable>) -Return a random string of given ``<length>`` consisting of -characters from the given ``<alphabet>``. Default length is 5 characters -and default alphabet is all numbers and upper and lower case letters. -If an integer ``RANDOM_SEED`` is given, its value will be used to seed the -random number generator. - -.. _TIMESTAMP: - -.. code-block:: cmake + Return a random string of given ``<length>`` consisting of + characters from the given ``<alphabet>``. Default length is 5 characters + and default alphabet is all numbers and upper and lower case letters. + If an integer ``RANDOM_SEED`` is given, its value will be used to seed the + random number generator. +.. signature:: string(TIMESTAMP <output_variable> [<format_string>] [UTC]) -Write a string representation of the current date -and/or time to the ``<output_variable>``. - -If the command is unable to obtain a timestamp, the ``<output_variable>`` -will be set to the empty string ``""``. + Write a string representation of the current date + and/or time to the ``<output_variable>``. -The optional ``UTC`` flag requests the current date/time representation to -be in Coordinated Universal Time (UTC) rather than local time. + If the command is unable to obtain a timestamp, the ``<output_variable>`` + will be set to the empty string ``""``. -The optional ``<format_string>`` may contain the following format -specifiers: - -``%%`` - .. versionadded:: 3.8 + The optional ``UTC`` flag requests the current date/time representation to + be in Coordinated Universal Time (UTC) rather than local time. - A literal percent sign (%). + The optional ``<format_string>`` may contain the following format + specifiers: -``%d`` - The day of the current month (01-31). + ``%%`` + .. versionadded:: 3.8 -``%H`` - The hour on a 24-hour clock (00-23). + A literal percent sign (%). -``%I`` - The hour on a 12-hour clock (01-12). + ``%d`` + The day of the current month (01-31). -``%j`` - The day of the current year (001-366). + ``%H`` + The hour on a 24-hour clock (00-23). -``%m`` - The month of the current year (01-12). + ``%I`` + The hour on a 12-hour clock (01-12). -``%b`` - .. versionadded:: 3.7 + ``%j`` + The day of the current year (001-366). - Abbreviated month name (e.g. Oct). + ``%m`` + The month of the current year (01-12). -``%B`` - .. versionadded:: 3.10 + ``%b`` + .. versionadded:: 3.7 - Full month name (e.g. October). + Abbreviated month name (e.g. Oct). -``%M`` - The minute of the current hour (00-59). + ``%B`` + .. versionadded:: 3.10 -``%s`` - .. versionadded:: 3.6 + Full month name (e.g. October). - Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). + ``%M`` + The minute of the current hour (00-59). -``%S`` - The second of the current minute. 60 represents a leap second. (00-60) + ``%s`` + .. versionadded:: 3.6 -``%f`` - .. versionadded:: 3.23 + Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). - The microsecond of the current second (000000-999999). + ``%S`` + The second of the current minute. 60 represents a leap second. (00-60) -``%U`` - The week number of the current year (00-53). + ``%f`` + .. versionadded:: 3.23 -``%V`` - .. versionadded:: 3.22 + The microsecond of the current second (000000-999999). - The ISO 8601 week number of the current year (01-53). + ``%U`` + The week number of the current year (00-53). -``%w`` - The day of the current week. 0 is Sunday. (0-6) + ``%V`` + .. versionadded:: 3.22 -``%a`` - .. versionadded:: 3.7 + The ISO 8601 week number of the current year (01-53). - Abbreviated weekday name (e.g. Fri). + ``%w`` + The day of the current week. 0 is Sunday. (0-6) -``%A`` - .. versionadded:: 3.10 + ``%a`` + .. versionadded:: 3.7 - Full weekday name (e.g. Friday). + Abbreviated weekday name (e.g. Fri). -``%y`` - The last two digits of the current year (00-99). + ``%A`` + .. versionadded:: 3.10 -``%Y`` - The current year. + Full weekday name (e.g. Friday). -``%z`` - .. versionadded:: 3.26 + ``%y`` + The last two digits of the current year (00-99). - The offset of the time zone from UTC, in hours and minutes, - with format ``+hhmm`` or ``-hhmm``. + ``%Y`` + The current year. -``%Z`` - .. versionadded:: 3.26 + ``%z`` + .. versionadded:: 3.26 - The time zone name. + The offset of the time zone from UTC, in hours and minutes, + with format ``+hhmm`` or ``-hhmm``. -Unknown format specifiers will be ignored and copied to the output -as-is. + ``%Z`` + .. versionadded:: 3.26 -If no explicit ``<format_string>`` is given, it will default to: + The time zone name. -:: + Unknown format specifiers will be ignored and copied to the output + as-is. - %Y-%m-%dT%H:%M:%S for local time. - %Y-%m-%dT%H:%M:%SZ for UTC. + If no explicit ``<format_string>`` is given, it will default to: -.. versionadded:: 3.8 - If the ``SOURCE_DATE_EPOCH`` environment variable is set, - its value will be used instead of the current time. - See https://reproducible-builds.org/specs/source-date-epoch/ for details. + :: -.. _UUID: + %Y-%m-%dT%H:%M:%S for local time. + %Y-%m-%dT%H:%M:%SZ for UTC. -.. code-block:: cmake + .. versionadded:: 3.8 + If the ``SOURCE_DATE_EPOCH`` environment variable is set, + its value will be used instead of the current time. + See https://reproducible-builds.org/specs/source-date-epoch/ for details. +.. signature:: string(UUID <output_variable> NAMESPACE <namespace> NAME <name> TYPE <MD5|SHA1> [UPPER]) -.. versionadded:: 3.1 + .. versionadded:: 3.1 -Create a universally unique identifier (aka GUID) as per RFC4122 -based on the hash of the combined values of ``<namespace>`` -(which itself has to be a valid UUID) and ``<name>``. -The hash algorithm can be either ``MD5`` (Version 3 UUID) or -``SHA1`` (Version 5 UUID). -A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` -where each ``x`` represents a lower case hexadecimal character. -Where required, an uppercase representation can be requested -with the optional ``UPPER`` flag. + Create a universally unique identifier (aka GUID) as per RFC4122 + based on the hash of the combined values of ``<namespace>`` + (which itself has to be a valid UUID) and ``<name>``. + The hash algorithm can be either ``MD5`` (Version 3 UUID) or + ``SHA1`` (Version 5 UUID). + A UUID has the format ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` + where each ``x`` represents a lower case hexadecimal character. + Where required, an uppercase representation can be requested + with the optional ``UPPER`` flag. .. _JSON: @@ -586,78 +518,72 @@ Functionality for querying a JSON string. option is not present, a fatal error message is generated. If no error occurs, the ``<error-variable>`` will be set to ``NOTFOUND``. -.. _JSON_GET: -.. code-block:: cmake - +.. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-variable>] GET <json-string> <member|index> [<member|index> ...]) + :target: JSON GET -Get an element from ``<json-string>`` at the location given -by the list of ``<member|index>`` arguments. -Array and object elements will be returned as a JSON string. -Boolean elements will be returned as ``ON`` or ``OFF``. -Null elements will be returned as an empty string. -Number and string types will be returned as strings. - -.. _JSON_TYPE: -.. code-block:: cmake + Get an element from ``<json-string>`` at the location given + by the list of ``<member|index>`` arguments. + Array and object elements will be returned as a JSON string. + Boolean elements will be returned as ``ON`` or ``OFF``. + Null elements will be returned as an empty string. + Number and string types will be returned as strings. +.. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-variable>] TYPE <json-string> <member|index> [<member|index> ...]) + :target: JSON TYPE -Get the type of an element in ``<json-string>`` at the location -given by the list of ``<member|index>`` arguments. The ``<out-var>`` -will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, -``ARRAY``, or ``OBJECT``. - -.. _JSON_MEMBER: -.. code-block:: cmake + Get the type of an element in ``<json-string>`` at the location + given by the list of ``<member|index>`` arguments. The ``<out-var>`` + will be set to one of ``NULL``, ``NUMBER``, ``STRING``, ``BOOLEAN``, + ``ARRAY``, or ``OBJECT``. +.. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-var>] MEMBER <json-string> [<member|index> ...] <index>) + :target: JSON MEMBER -Get the name of the ``<index>``-th member in ``<json-string>`` at the location -given by the list of ``<member|index>`` arguments. -Requires an element of object type. - -.. _JSON_LENGTH: -.. code-block:: cmake + Get the name of the ``<index>``-th member in ``<json-string>`` + at the location given by the list of ``<member|index>`` arguments. + Requires an element of object type. +.. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-variable>] LENGTH <json-string> [<member|index> ...]) + :target: JSON LENGTH -Get the length of an element in ``<json-string>`` at the location -given by the list of ``<member|index>`` arguments. -Requires an element of array or object type. - -.. _JSON_REMOVE: -.. code-block:: cmake + Get the length of an element in ``<json-string>`` at the location + given by the list of ``<member|index>`` arguments. + Requires an element of array or object type. +.. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-variable>] REMOVE <json-string> <member|index> [<member|index> ...]) + :target: JSON REMOVE -Remove an element from ``<json-string>`` at the location -given by the list of ``<member|index>`` arguments. The JSON string -without the removed element will be stored in ``<out-var>``. - -.. _JSON_SET: -.. code-block:: cmake + Remove an element from ``<json-string>`` at the location + given by the list of ``<member|index>`` arguments. The JSON string + without the removed element will be stored in ``<out-var>``. +.. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-variable>] SET <json-string> <member|index> [<member|index> ...] <value>) + :target: JSON SET -Set an element in ``<json-string>`` at the location -given by the list of ``<member|index>`` arguments to ``<value>``. -The contents of ``<value>`` should be valid JSON. - -.. _JSON_EQUAL: -.. code-block:: cmake + Set an element in ``<json-string>`` at the location + given by the list of ``<member|index>`` arguments to ``<value>``. + The contents of ``<value>`` should be valid JSON. +.. signature:: string(JSON <out-var> [ERROR_VARIABLE <error-var>] EQUAL <json-string1> <json-string2>) + :target: JSON EQUAL -Compare the two JSON objects given by ``<json-string1>`` and ``<json-string2>`` -for equality. The contents of ``<json-string1>`` and ``<json-string2>`` -should be valid JSON. The ``<out-var>`` will be set to a true value if the -JSON objects are considered equal, or a false value otherwise. + Compare the two JSON objects given by ``<json-string1>`` + and ``<json-string2>`` for equality. The contents of ``<json-string1>`` + and ``<json-string2>`` should be valid JSON. The ``<out-var>`` + will be set to a true value if the JSON objects are considered equal, + or a false value otherwise. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 698f62d60a..7cfb24b18f 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -15,6 +15,11 @@ are used when compiling the given ``<target>``, which must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target <Alias Targets>`. +.. note:: + + These options are not used when linking the target. + See the :command:`target_link_options` command for that. + Arguments ^^^^^^^^^ @@ -50,9 +55,17 @@ See Also * For file-specific settings, there is the source file property :prop_sf:`COMPILE_OPTIONS`. +* This command adds compile options for all languages in a target. + Use the :genex:`COMPILE_LANGUAGE` generator expression to specify + per-language compile options. + * :command:`target_compile_features` * :command:`target_link_libraries` * :command:`target_link_directories` * :command:`target_link_options` * :command:`target_precompile_headers` * :command:`target_sources` + +* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` + add language-wide flags passed to all invocations of the compiler. + This includes invocations that drive compiling and those that drive linking. diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst index 0d026f2456..dca9598611 100644 --- a/Help/command/target_link_options.rst +++ b/Help/command/target_link_options.rst @@ -62,3 +62,7 @@ See Also * :command:`target_link_directories` * :command:`target_precompile_headers` * :command:`target_sources` + +* :variable:`CMAKE_<LANG>_FLAGS` and :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` + add language-wide flags passed to all invocations of the compiler. + This includes invocations that drive compiling and those that drive linking. diff --git a/Help/command/unset.rst b/Help/command/unset.rst index 1cd1398ac7..522be89800 100644 --- a/Help/command/unset.rst +++ b/Help/command/unset.rst @@ -12,19 +12,14 @@ Unset Normal Variable or Cache Entry Removes a normal variable from the current scope, causing it to become undefined. If ``CACHE`` is present, then a cache variable -is removed instead of a normal variable. Note that when evaluating -:ref:`Variable References` of the form ``${VAR}``, CMake first searches -for a normal variable with that name. If no such normal variable exists, -CMake will then search for a cache entry with that name. Because of this -unsetting a normal variable can expose a cache variable that was previously -hidden. To force a variable reference of the form ``${VAR}`` to return an -empty string, use ``set(<variable> "")``, which clears the normal variable -but leaves it defined. +is removed instead of a normal variable. If ``PARENT_SCOPE`` is present then the variable is removed from the scope above the current scope. See the same option in the :command:`set` command for further details. +.. include:: UNSET_NOTE.txt + Unset Environment Variable ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/cpack_gen/nuget.rst b/Help/cpack_gen/nuget.rst index 1f2e76281d..8ee2816903 100644 --- a/Help/cpack_gen/nuget.rst +++ b/Help/cpack_gen/nuget.rst @@ -258,7 +258,7 @@ List of CPack NuGet generator specific variables: .. _nuget.org: https://www.nuget.org .. _version specification: https://learn.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges -.. _SPDX license identifier: https://spdx.github.io/spdx-spec/SPDX-license-list -.. _SPDX specification: https://spdx.github.io/spdx-spec/SPDX-license-expressions +.. _SPDX license identifier: https://spdx.org/licenses +.. _SPDX specification: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions .. NuGet spec docs https://docs.microsoft.com/en-us/nuget/reference/nuspec diff --git a/Help/cpack_gen/wix.rst b/Help/cpack_gen/wix.rst index c880049320..af01252454 100644 --- a/Help/cpack_gen/wix.rst +++ b/Help/cpack_gen/wix.rst @@ -111,7 +111,7 @@ Windows using WiX. simply provide the name of the culture. If you specify more than one culture identifier in a comma or semicolon delimited list, the first one that is found will be used. You can find a list of supported languages at: - https://wixtoolset.org//documentation/manual/v3/wixui/wixui_localization.html + https://wixtoolset.org/docs/v3/wixui/wixui_localization/ .. variable:: CPACK_WIX_TEMPLATE @@ -319,7 +319,7 @@ Windows using WiX. for using WiX extensions. Each declaration should be in the form name=url, where name is the plain namespace without the usual xmlns: prefix and url is an unquoted namespace url. A list of commonly known WiX schemata can be found here: - https://wixtoolset.org/documentation/manual/v3/xsd/ + https://wixtoolset.org/docs/v3/xsd/ .. variable:: CPACK_WIX_SKIP_WIX_UI_EXTENSION diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index db92022089..c6fb7a653c 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -168,46 +168,175 @@ documentation: See the `cmake-variables(7)`_ manual and the `set()`_ command. -Documentation objects in the CMake Domain come from two sources. -First, the CMake extension to Sphinx transforms every document named -with the form ``Help/<type>/<file-name>.rst`` to a domain object with -type ``<type>``. The object name is extracted from the document title, -which is expected to be of the form:: - - <object-name> - ------------- - -and to appear at or near the top of the ``.rst`` file before any other -lines starting in a letter, digit, ``<``, or ``$``. If no such title appears -literally in the ``.rst`` file, the object name is the ``<file-name>``. -If a title does appear, it is expected that ``<file-name>`` is equal -to ``<object-name>`` with any ``<`` and ``>`` characters removed, -or in the case of a ``$<genex-name>`` or ``$<genex-name:...>``, the -``genex-name``. - -Second, the CMake Domain provides directives to define objects inside -other documents: +Documentation objects in the CMake Domain come from two sources: + +1. The CMake extension to Sphinx transforms every document named + with the form ``Help/<type>/<file-name>.rst`` to a domain object with + type ``<type>``. The object name is extracted from the document title, + which is expected to be of the form:: + + <object-name> + ------------- + + and to appear at or near the top of the ``.rst`` file before any other lines + starting in a letter, digit, ``<``, or ``$``. If no such title appears + literally in the ``.rst`` file, the object name is the ``<file-name>``. + If a title does appear, it is expected that ``<file-name>`` is equal + to ``<object-name>`` with any ``<`` and ``>`` characters removed, + or in the case of a ``$<genex-name>`` or ``$<genex-name:...>``, the + ``genex-name``. + +2. `CMake Domain directives`_ may be used in documents to explicitly define + some object types: + + * `command directive`_ + * `envvar directive`_ + * `genex directive`_ + * `variable directive`_ + + Object types for which no directive is available must be defined using + the document transform above. + +CMake Domain Directives +----------------------- + +The CMake Domain provides the following directives. + +``command`` directive +^^^^^^^^^^^^^^^^^^^^^ + +Document a "command" object: + +.. code-block:: rst + + .. command:: <command-name> + + This indented block documents <command-name>. + +The directive requires a single argument, the command name. + +``envvar`` directive +^^^^^^^^^^^^^^^^^^^^ + +Document an "envvar" object: .. code-block:: rst - .. command:: <command-name> + .. envvar:: <envvar-name> + + This indented block documents <envvar-name>. + +The directive requires a single argument, the environment variable name. - This indented block documents <command-name>. +``genex`` directive +^^^^^^^^^^^^^^^^^^^ - .. envvar:: <envvar-name> +Document a "genex" object: - This indented block documents <envvar-name>. +.. code-block:: rst .. genex:: <genex-name> This indented block documents <genex-name>. +The directive requires a single argument, the generator expression name. + +The optional ``:target:`` option allows a custom target name to be specified. +Because this will affect the ability to reference the "genex" object using the +``:genex:`` role, this option should be used very sparingly. + +``signature`` directive +^^^^^^^^^^^^^^^^^^^^^^^ + +Document `CMake Command Signatures <Style: CMake Command Signatures_>`_ +within a ``Help/command/<command-name>.rst`` document. + +.. code-block:: rst + + .. signature:: <command-name>(<signature>) + + This indented block documents one or more signatures of a CMake command. + +The ``signature`` directive requires one argument, the signature summary: + +* One or more signatures must immediately follow the ``::``. + The first signature may optionally be placed on the same line. + A blank line following the ``signature`` directive will result in a + documentation generation error: ``1 argument(s) required, 0 supplied``. + +* Signatures may be split across multiple lines, but the final ``)`` of each + signature must be the last character on its line. + +* Blank lines between signatures are not allowed. (Content after a blank line + is treated as part of the description.) + +* Whitespace in signatures is not preserved. To document a complex signature, + abbreviate it in the ``signature`` directive argument and specify the full + signature in a ``code-block`` in the description. + +The ``signature`` directive generates a hyperlink target for each signature: + +* Default target names are automatically extracted from leading "keyword" + arguments in the signatures, where a keyword is any sequence of + non-space starting with a letter. For example, the signature + ``string(REGEX REPLACE <match-regex> ...)`` generates the target + ``REGEX REPLACE``, similar to ``.. _`REGEX REPLACE`:``. + +* Custom target names may be specified using a ``:target:`` option. + For example: + + .. code-block:: rst + + .. signature:: + cmake_path(GET <path-var> ROOT_NAME <out-var>) + cmake_path(GET <path-var> ROOT_PATH <out-var>) + :target: + GET ROOT_NAME + GET ROOT_PATH + + Provide a custom target name for each signature, one per line. + The first target may optionally be placed on the same line as ``:target:``. + +* If a target name is already in use earlier in the document, no hyperlink + target will be generated. + +* The targets may be referenced from within the same document using + ```REF`_`` or ```TEXT <REF_>`_`` syntax. Like reStructuredText section + headers, the targets do not work with Sphinx ``:ref:`` syntax, however + they can be globally referenced using e.g. ``:command:`string(APPEND)```. + +Although whitespace in the signature is not preserved, by default, line breaks +are suppressed inside of square- or angle-brackets. This behavior can be +controlled using the ``:break:`` option; note, however, that there is no way +to *force* a line break. The default value is 'smart'. Allowable values are: + + ``all`` + Allow line breaks at any whitespace. + + ``smart`` (default) + Allow line breaks at whitespace, except between matched square- or + angle-brackets. For example, if a signature contains the text + ``<input>... [OUTPUT_VARIABLE <out-var>]``, a line break would be allowed + after ``<input>...`` but not between ``OUTPUT_VARIABLE`` and ``<out-var>``. + + ``verbatim`` + Allow line breaks only where the source document contains a newline. + +The directive treats its content as the documentation of the signature(s). +Indent the signature documentation accordingly. + +``variable`` directive +^^^^^^^^^^^^^^^^^^^^^^ + +Document a "variable" object: + +.. code-block:: rst + .. variable:: <variable-name> This indented block documents <variable-name>. -Object types for which no directive is available must be defined using -the first approach above. +The directive requires a single argument, the variable name. .. _`Sphinx Domain`: http://sphinx-doc.org/domains.html .. _`cmake(1)`: https://cmake.org/cmake/help/latest/manual/cmake.1.html @@ -266,6 +395,10 @@ object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``, with a space preceding ``<``, is still interpreted as a link text with an explicit target. +Additionally, the ``cref`` role may be used to create references +to local targets that have literal styling. This is especially +useful for referencing a subcommand in the command's documentation. + .. _`list()`: https://cmake.org/cmake/help/latest/command/list.html .. _`list(APPEND)`: https://cmake.org/cmake/help/latest/command/list.html .. _`list(APPEND) sub-command`: https://cmake.org/cmake/help/latest/command/list.html @@ -329,11 +462,11 @@ paragraph. Style: CMake Command Signatures ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Command signatures should be marked up as plain literal blocks, not as -cmake ``code-blocks``. - -Signatures are separated from preceding content by a section header. -That is, use: +A ``Help/command/<command-name>.rst`` document defines one ``command`` +object in the `CMake Domain`_, but some commands have multiple signatures. +Use the CMake Domain's `signature directive`_ to document each signature. +Separate signatures from preceding content by a section header. +For example: .. code-block:: rst @@ -342,17 +475,23 @@ That is, use: Normal Libraries ^^^^^^^^^^^^^^^^ - :: - + .. signature:: add_library(<lib> ...) - This signature is used for ... + This signature is used for ... + +Use the following conventions in command signature documentation: + +* Use an angle-bracket ``<placeholder>`` for arguments to be specified + by the caller. Refer to them in prose using + `inline literal <Style: Inline Literals_>`_ syntax. + +* Wrap optional parts with square brackets. + +* Mark repeatable parts with a trailing ellipsis (``...``). -Signatures of commands should wrap optional parts with square brackets, -and should mark list of optional arguments with an ellipsis (``...``). -Elements of the signature which are specified by the user should be -specified with angle brackets, and may be referred to in prose using -``inline-literal`` syntax. +The ``signature`` directive may be used multiple times for different +signatures of the same command. Style: Boolean Constants ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/envvar/CMAKE_MAXIMUM_RECURSION_DEPTH.rst b/Help/envvar/CMAKE_MAXIMUM_RECURSION_DEPTH.rst new file mode 100644 index 0000000000..2d65b60bc4 --- /dev/null +++ b/Help/envvar/CMAKE_MAXIMUM_RECURSION_DEPTH.rst @@ -0,0 +1,10 @@ +CMAKE_MAXIMUM_RECURSION_DEPTH +----------------------------- + +.. versionadded:: 3.27 + +.. include:: ENV_VAR.txt + +Maximum recursion depth for CMake scripts. This environment variable is +used if the :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH` variable is not set. +See that variable's documentation for details. diff --git a/Help/envvar/PackageName_ROOT.rst b/Help/envvar/PackageName_ROOT.rst index fa8c385f4c..6e9c7444fd 100644 --- a/Help/envvar/PackageName_ROOT.rst +++ b/Help/envvar/PackageName_ROOT.rst @@ -17,3 +17,17 @@ by ``:`` on UNIX or ``;`` on Windows (the same as the ``PATH`` environment variable convention on those platforms). See also the :variable:`<PackageName>_ROOT` CMake variable. + +.. envvar:: <PACKAGENAME>_ROOT + + .. versionadded:: 3.27 + + Calls to :command:`find_package(<PackageName>)` will also search in + prefixes specified by the upper-case ``<PACKAGENAME>_ROOT`` environment + variable. See policy :policy:`CMP0144`. + +.. note:: + + Note that the ``<PackageName>_ROOT`` and ``<PACKAGENAME>_ROOT`` + environment variables are distinct only on platforms that have + case-sensitive environments. diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index 85da71543c..5c48bc9d88 100644 --- a/Help/generator/CodeBlocks.rst +++ b/Help/generator/CodeBlocks.rst @@ -1,6 +1,12 @@ CodeBlocks ---------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates CodeBlocks project files. Project files for CodeBlocks will be created in the top directory and diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst index 4f276df718..faec9b9f7a 100644 --- a/Help/generator/CodeLite.rst +++ b/Help/generator/CodeLite.rst @@ -1,6 +1,12 @@ CodeLite ---------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates CodeLite project files. Project files for CodeLite will be created in the top directory and diff --git a/Help/generator/Eclipse CDT4.rst b/Help/generator/Eclipse CDT4.rst index 634e2b6ddf..9c1610d617 100644 --- a/Help/generator/Eclipse CDT4.rst +++ b/Help/generator/Eclipse CDT4.rst @@ -1,6 +1,12 @@ Eclipse CDT4 ------------ +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Eclipse CDT 4.0 project files. Project files for Eclipse will be created in the top directory. In diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst index 129bf631be..11354f28cd 100644 --- a/Help/generator/Kate.rst +++ b/Help/generator/Kate.rst @@ -1,6 +1,12 @@ Kate ---- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Kate project files. A project file for Kate will be created in the top directory in the top level @@ -22,5 +28,8 @@ This "extra" generator may be specified as: ``Kate - Ninja`` Generate with :generator:`Ninja`. +``Kate - Ninja Multi-Config`` + Generate with :generator:`Ninja Multi-Config`. + ``Kate - Unix Makefiles`` Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst index 0a07ea983b..a45ab08252 100644 --- a/Help/generator/Sublime Text 2.rst +++ b/Help/generator/Sublime Text 2.rst @@ -1,6 +1,12 @@ Sublime Text 2 -------------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Generates Sublime Text 2 project files. Project files for Sublime Text 2 will be created in the top directory diff --git a/Help/generator/Visual Studio 9 2008.rst b/Help/generator/Visual Studio 9 2008.rst index 34349560e3..816969dd28 100644 --- a/Help/generator/Visual Studio 9 2008.rst +++ b/Help/generator/Visual Studio 9 2008.rst @@ -1,7 +1,15 @@ Visual Studio 9 2008 -------------------- -Generates Visual Studio 9 2008 project files. +Deprecated. Generates Visual Studio 9 2008 project files. + +.. note:: + This generator is deprecated and will be removed in a future version + of CMake. It will still be possible to build with VS 9 2008 tools + using the :generator:`Visual Studio 12 2013` generator (or above, + and with VS 10 2010 also installed) with + :variable:`CMAKE_GENERATOR_TOOLSET` set to ``v90``, + or by using the :generator:`NMake Makefiles` generator. Platform Selection ^^^^^^^^^^^^^^^^^^ diff --git a/Help/guide/ide-integration/index.rst b/Help/guide/ide-integration/index.rst index e198789c79..3a11a34531 100644 --- a/Help/guide/ide-integration/index.rst +++ b/Help/guide/ide-integration/index.rst @@ -145,7 +145,7 @@ The following IDEs support CMake natively: * `VSCode`_ (via a plugin) .. _CLion: https://www.jetbrains.com/clion/ -.. _KDevelop: https://www.kdevelop.org/ +.. _KDevelop: https://kdevelop.org/ .. _QtCreator: https://www.qt.io/product/development-tools .. _Vim: https://www.vim.org/ .. _Visual Studio: https://visualstudio.microsoft.com/ diff --git a/Help/guide/tutorial/A Basic Starting Point.rst b/Help/guide/tutorial/A Basic Starting Point.rst index 3dac68a80f..37b0668d4e 100644 --- a/Help/guide/tutorial/A Basic Starting Point.rst +++ b/Help/guide/tutorial/A Basic Starting Point.rst @@ -160,7 +160,7 @@ The last command to call for a basic project is :name: CMakeLists.txt-add_executable :language: cmake :start-after: # add the executable - :end-before: # TODO 9: + :end-before: # TODO 3: .. raw:: html @@ -240,7 +240,7 @@ the following: :name: tutorial.cxx-cxx11 :language: c++ :start-after: // convert input to double - :end-before: // TODO 12: + :end-before: // TODO 6: .. raw:: html @@ -265,7 +265,7 @@ add the :variable:`CMAKE_CXX_STANDARD` declarations above the call to :name: CMakeLists.txt-CXX_STANDARD :language: cmake :start-after: # specify the C++ standard - :end-before: # TODO 7: + :end-before: # configure a header file .. raw:: html @@ -375,7 +375,7 @@ specified CMake variables replaced: :name: CMakeLists.txt-configure_file :language: cmake :start-after: # to the source code - :end-before: # TODO 8: + :end-before: # TODO 2: .. raw:: html @@ -420,7 +420,6 @@ be replaced with the corresponding version numbers from the project in :caption: TODO 10: TutorialConfig.h.in :name: TutorialConfig.h.in :language: c++ - :end-before: // TODO 13: .. raw:: html diff --git a/Help/guide/tutorial/Adding Generator Expressions.rst b/Help/guide/tutorial/Adding Generator Expressions.rst index 6f9714e474..aba9f7ad4d 100644 --- a/Help/guide/tutorial/Adding Generator Expressions.rst +++ b/Help/guide/tutorial/Adding Generator Expressions.rst @@ -105,7 +105,7 @@ The specific lines to remove are as follows: :name: CMakeLists.txt-CXX_STANDARD-variable-remove :language: cmake :start-after: # specify the C++ standard - :end-before: # TODO 5: Create helper variables + :end-before: # TODO 6: Create helper variables Next, we need to create an interface library, ``tutorial_compiler_flags``. And then use :command:`target_compile_features` to add the compiler feature @@ -128,7 +128,8 @@ then use :command:`target_compile_features` to add the compiler feature </details> Finally, with our interface library set up, we need to link our -executable ``Target`` and our ``MathFunctions`` library to our new +executable ``Target``, our ``MathFunctions`` library, and our ``SqrtLibrary`` +library to our new ``tutorial_compiler_flags`` library. Respectively, the code will look like this: @@ -147,7 +148,7 @@ this: </details> -and this: +this: .. raw:: html @@ -158,12 +159,30 @@ and this: :name: MathFunctions-CMakeLists.txt-target_link_libraries-step4 :language: cmake :start-after: # link our compiler flags interface library - :end-before: # TODO 1 + :end-before: target_link_libraries(MathFunctions + +.. raw:: html + + </details> + +and this: + +.. raw:: html + + <details><summary>TODO 4: Click to show/hide answer</summary> + +.. literalinclude:: Step5/MathFunctions/CMakeLists.txt + :caption: TODO 4: MathFunctions/CMakeLists.txt + :name: MathFunctions-SqrtLibrary-target_link_libraries-step4 + :language: cmake + :start-after: target_link_libraries(SqrtLibrary + :end-before: endif() .. raw:: html </details> + With this, all of our code still requires C++ 11 to build. Notice though that with this method, it gives us the ability to be specific about which targets get specific requirements. In addition, we create a single @@ -199,8 +218,8 @@ Files to Edit Getting Started --------------- -Start with the resulting files from Exercise 1. Complete ``TODO 4`` through -``TODO 7``. +Start with the resulting files from Exercise 1. Complete ``TODO 5`` through +``TODO 8``. First, in the top level ``CMakeLists.txt`` file, we need to set the :command:`cmake_minimum_required` to ``3.15``. In this exercise we are going @@ -230,10 +249,10 @@ version ``3.15``: .. raw:: html - <details><summary>TODO 4: Click to show/hide answer</summary> + <details><summary>TODO 5: Click to show/hide answer</summary> .. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 4: CMakeLists.txt + :caption: TODO 5: CMakeLists.txt :name: MathFunctions-CMakeLists.txt-minimum-required-step4 :language: cmake :end-before: # set the project name and version @@ -249,10 +268,10 @@ variables ``gcc_like_cxx`` and ``msvc_cxx`` as follows: .. raw:: html - <details><summary>TODO 5: Click to show/hide answer</summary> + <details><summary>TODO 6: Click to show/hide answer</summary> .. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 5: CMakeLists.txt + :caption: TODO 6: CMakeLists.txt :name: CMakeLists.txt-compile_lang_and_id :language: cmake :start-after: # the BUILD_INTERFACE genex @@ -270,10 +289,10 @@ interface library. .. raw:: html - <details><summary>TODO 6: Click to show/hide answer</summary> + <details><summary>TODO 7: Click to show/hide answer</summary> .. code-block:: cmake - :caption: TODO 6: CMakeLists.txt + :caption: TODO 7: CMakeLists.txt :name: CMakeLists.txt-compile_flags target_compile_options(tutorial_compiler_flags INTERFACE @@ -292,14 +311,14 @@ condition. The resulting full code looks like the following: .. raw:: html - <details><summary>TODO 7: Click to show/hide answer</summary> + <details><summary>TODO 8: Click to show/hide answer</summary> .. literalinclude:: Step5/CMakeLists.txt - :caption: TODO 7: CMakeLists.txt + :caption: TODO 8: CMakeLists.txt :name: CMakeLists.txt-target_compile_options-genex :language: cmake :start-after: set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>") - :end-before: # should we use our own math functions + :end-before: # configure a header file to pass some of the CMake settings .. raw:: html diff --git a/Help/guide/tutorial/Adding System Introspection.rst b/Help/guide/tutorial/Adding System Introspection.rst index b69abd2920..b3147736a3 100644 --- a/Help/guide/tutorial/Adding System Introspection.rst +++ b/Help/guide/tutorial/Adding System Introspection.rst @@ -119,7 +119,7 @@ our source code can tell what resources are available. If both ``log`` and :name: MathFunctions/CMakeLists.txt-target_compile_definitions :language: cmake :start-after: # add compile definitions - :end-before: # install libs + :end-before: # state .. raw:: html @@ -136,7 +136,8 @@ Since we may be using ``log`` and ``exp``, we need to modify :caption: TODO 4: MathFunctions/mysqrt.cxx :name: MathFunctions/mysqrt.cxx-include-cmath :language: c++ - :end-before: #include <iostream> + :start-after: #include "mysqrt.h" + :end-before: include <iostream> .. raw:: html diff --git a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst index 4aef050585..74b7496688 100644 --- a/Help/guide/tutorial/Adding Usage Requirements for a Library.rst +++ b/Help/guide/tutorial/Adding Usage Requirements for a Library.rst @@ -100,7 +100,7 @@ follows: :name: MathFunctions/CMakeLists.txt-target_include_directories-INTERFACE :language: cmake :start-after: # to find MathFunctions.h - :end-before: # TODO 3: Link to + :end-before: option .. raw:: html @@ -119,7 +119,7 @@ safely remove our uses of the ``EXTRA_INCLUDES`` variable from the top-level :name: CMakeLists.txt-remove-EXTRA_INCLUDES :language: cmake :start-after: # add the MathFunctions library - :end-before: # add the executable + :end-before: # TODO 2: Link to tutorial_compiler_flags .. raw:: html diff --git a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst index b1f984076d..c71a889725 100644 --- a/Help/guide/tutorial/Adding a Custom Command and Generated File.rst +++ b/Help/guide/tutorial/Adding a Custom Command and Generated File.rst @@ -18,41 +18,49 @@ In the ``MathFunctions`` subdirectory, a new source file named After reviewing the file, we can see that the table is produced as valid C++ code and that the output filename is passed in as an argument. -The next step is to add the appropriate commands to the -``MathFunctions/CMakeLists.txt`` file to build the MakeTable executable and +The next step is to create ``MathFunctions/MakeTable.cmake``. Then, add the +appropriate commands to the file to build the ``MakeTable`` executable and then run it as part of the build process. A few commands are needed to accomplish this. -First, at the top of ``MathFunctions/CMakeLists.txt``, the executable for -``MakeTable`` is added as any other executable would be added. +First, we add an executable for ``MakeTable``. -.. literalinclude:: Step9/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-add_executable-MakeTable +.. literalinclude:: Step9/MathFunctions/MakeTable.cmake + :caption: MathFunctions/MakeTable.cmake + :name: MathFunctions/MakeTable.cmake-add_executable-MakeTable :language: cmake :start-after: # first we add the executable that generates the table - :end-before: # add the command to generate the source code + :end-before: target_link_libraries + +After creating the executable, we add the ``tutorial_compiler_flags`` to our +executable using :command:`target_link_libraries`. + +.. literalinclude:: Step9/MathFunctions/MakeTable.cmake + :caption: MathFunctions/MakeTable.cmake + :name: MathFunctions/MakeTable.cmake-link-tutorial-compiler-flags + :language: cmake + :start-after: add_executable + :end-before: # add the command to generate Then we add a custom command that specifies how to produce ``Table.h`` by running MakeTable. -.. literalinclude:: Step9/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-add_custom_command-Table.h +.. literalinclude:: Step9/MathFunctions/MakeTable.cmake + :caption: MathFunctions/MakeTable.cmake + :name: MathFunctions/MakeTable.cmake-add_custom_command-Table.h :language: cmake :start-after: # add the command to generate the source code - :end-before: # add the main library Next we have to let CMake know that ``mysqrt.cxx`` depends on the generated file ``Table.h``. This is done by adding the generated ``Table.h`` to the list -of sources for the library MathFunctions. +of sources for the library ``SqrtLibrary``. .. literalinclude:: Step9/MathFunctions/CMakeLists.txt :caption: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add_library-Table.h :language: cmake - :start-after: # add the main library - :end-before: # state that anybody linking + :start-after: # library that just does sqrt + :end-before: # state that we depend on We also have to add the current binary directory to the list of include directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. @@ -62,7 +70,17 @@ directories so that ``Table.h`` can be found and included by ``mysqrt.cxx``. :name: MathFunctions/CMakeLists.txt-target_include_directories-Table.h :language: cmake :start-after: # state that we depend on our bin - :end-before: # install libs + :end-before: target_link_libraries + +As the last step, we need to include +``MakeTable.cmake`` at the top of the ``MathFunctions/CMakeLists.txt``. + +.. literalinclude:: Step9/MathFunctions/CMakeLists.txt + :caption: MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-include-MakeTable.cmake + :language: cmake + :start-after: # generate Table.h + :end-before: # library that just does sqrt Now let's use the generated table. First, modify ``mysqrt.cxx`` to include ``Table.h``. Next, we can rewrite the ``mysqrt`` function to use the table: diff --git a/Help/guide/tutorial/Adding a Library.rst b/Help/guide/tutorial/Adding a Library.rst index a56c327ee6..d606f305e8 100644 --- a/Help/guide/tutorial/Adding a Library.rst +++ b/Help/guide/tutorial/Adding a Library.rst @@ -51,11 +51,13 @@ then use this library instead of the standard square root function provided by the compiler. For this tutorial we will put the library into a subdirectory called -``MathFunctions``. This directory already contains a header file, -``MathFunctions.h``, and a source file ``mysqrt.cxx``. We will not need to -modify either of these files. The source file has one function called +``MathFunctions``. This directory already contains the header files +``MathFunctions.h`` and ``mysqrt.h``. Their respective source files +``MathFunctions.cxx`` and ``mysqrt.cxx`` are also provided. We will not need +to modify any of these files. ``mysqrt.cxx`` has one function called ``mysqrt`` that provides similar functionality to the compiler's ``sqrt`` -function. +function. ``MathFunctions.cxx`` contains one function ``sqrt`` which serves +to hide the implementation details of ``sqrt``. From the ``Help/guide/tutorial/Step2`` directory, start with ``TODO 1`` and complete through ``TODO 6``. @@ -91,18 +93,18 @@ Solution In the ``CMakeLists.txt`` file in the ``MathFunctions`` directory, we create a library target called ``MathFunctions`` with :command:`add_library`. The -source file for the library is passed as an argument to +source files for the library are passed as an argument to :command:`add_library`. This looks like the following line: -.. raw:: html +.. raw:: html/ <details><summary>TODO 1: Click to show/hide answer</summary> -.. literalinclude:: Step3/MathFunctions/CMakeLists.txt +.. code-block:: cmake :caption: TODO 1: MathFunctions/CMakeLists.txt :name: MathFunctions/CMakeLists.txt-add_library - :language: cmake - :end-before: # TODO 1 + + add_library(MathFunctions MathFunctions.cxx mysqrt.cxx) .. raw:: html @@ -171,36 +173,40 @@ Now let's use our library. In ``tutorial.cxx``, include ``MathFunctions.h``: <details><summary>TODO 5: Click to show/hide answer</summary> -.. code-block:: c++ - :caption: TODO 5 : tutorial.cxx - :name: tutorial.cxx-include_MathFunctions.h - - #include "MathFunctions.h" +.. literalinclude:: Step3/tutorial.cxx + :caption: TODO 5: tutorial.cxx + :name: CMakeLists.txt-include-MathFunctions.h + :language: cmake + :start-after: #include <string> + :end-before: #include "TutorialConfig.h" .. raw:: html </details> -Lastly, replace ``sqrt`` with our library function ``mysqrt``. +Lastly, replace ``sqrt`` with our library function ``mathfunctions::mysqrt``. .. raw:: html <details><summary>TODO 6: Click to show/hide answer</summary> -.. code-block:: c++ - :caption: TODO 6 : tutorial.cxx - :name: tutorial.cxx-call_mysqrt - - const double outputValue = mysqrt(inputValue); +.. literalinclude:: Step3/tutorial.cxx + :caption: TODO 6: tutorial.cxx + :name: CMakeLists.txt-option + :language: cmake + :start-after: const double inputValue = std::stod(argv[1]); + :end-before: std::cout .. raw:: html </details> -Exercise 2 - Making Our Library Optional -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Exercise 2 - Adding an Option +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Now let us make the MathFunctions library optional. While for the tutorial +Now let us add an option in the MathFunctions library to allow developers to +select either the custom square root implementation or the built in standard +implementation. While for the tutorial there really isn't any need to do so, for larger projects this is a common occurrence. @@ -219,30 +225,32 @@ Helpful Resources ----------------- * :command:`if` -* :command:`list` * :command:`option` -* :command:`cmakedefine <configure_file>` +* :command:`target_compile_definitions` Files to Edit ------------- -* ``CMakeLists.txt`` -* ``tutorial.cxx`` -* ``TutorialConfig.h.in`` +* ``MathFunctions/CMakeLists.txt`` +* ``MathFunctions/MathFunctions.cxx`` Getting Started --------------- Start with the resulting files from Exercise 1. Complete ``TODO 7`` through -``TODO 13``. +``TODO 14``. First create a variable ``USE_MYMATH`` using the :command:`option` command -in the top-level ``CMakeLists.txt`` file. In that same file, use that option -to determine whether to build and use the ``MathFunctions`` library. +in ``MathFunctions/CMakeLists.txt``. In that same file, use that option +to pass a compile definition to the ``MathFunctions`` library. -Then, update ``tutorial.cxx`` and ``TutorialConfig.h.in`` to use +Then, update ``MathFunctions.cxx`` to redirect compilation based on ``USE_MYMATH``. +Lastly, prevent ``mysqrt.cxx`` from being compiled when ``USE_MYMATH`` is on +by making it its own library inside of the ``USE_MYMATH`` block of +``MathFunctions/CMakeLists.txt``. + Build and Run ------------- @@ -279,7 +287,7 @@ or ``mysqrt``? Solution -------- -The first step is to add an option to the top-level ``CMakeLists.txt`` file. +The first step is to add an option to ``MathFunctions/CMakeLists.txt``. This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and :manual:`ccmake <ccmake(1)>` with a default value of ``ON`` that can be changed by the user. @@ -288,172 +296,159 @@ changed by the user. <details><summary>TODO 7: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 7: CMakeLists.txt - :name: CMakeLists.txt-option +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 7: MathFunctions/CMakeLists.txt + :name: CMakeLists.txt-option-library-level :language: cmake :start-after: # should we use our own math functions - :end-before: # configure a header file to pass some of the CMake settings + :end-before: if (USE_MYMATH) .. raw:: html </details> -Next, make building and linking the ``MathFunctions`` library -conditional. - -Start by creating a :command:`list` of the optional library targets for our -project. At the moment, it is just ``MathFunctions``. Let's name our list -``EXTRA_LIBS``. +Next, make building and linking our library with ``mysqrt`` function +conditional using this new option. -Similarly, we need to make a :command:`list` for the optional includes which -we will call ``EXTRA_INCLUDES``. In this list, we will ``APPEND`` the path of -the header file needed for our library. - -Next, create an :command:`if` statement which checks the value of +Create an :command:`if` statement which checks the value of ``USE_MYMATH``. Inside the :command:`if` block, put the -:command:`add_subdirectory` command from Exercise 1 with the additional -:command:`list` commands. - -When ``USE_MYMATH`` is ``ON``, the lists will be generated and will be added to -our project. When ``USE_MYMATH`` is ``OFF``, the lists stay empty. With this -strategy, we allow users to toggle ``USE_MYMATH`` to manipulate what library is -used in the build. - -The top-level CMakeLists.txt file will now look like the following: +:command:`target_compile_definitions` command with the compile +definition ``USE_MYMATH``. .. raw:: html <details><summary>TODO 8: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 8: CMakeLists.txt +.. code-block:: cmake + :caption: TODO 8: MathFunctions/CMakeLists.txt :name: CMakeLists.txt-USE_MYMATH - :language: cmake - :start-after: # add the MathFunctions library - :end-before: # add the executable + + if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + endif() .. raw:: html </details> -Now that we have these two lists, we need to update -:command:`target_link_libraries` and :command:`target_include_directories` to -use them. Changing them is fairly straightforward. +When ``USE_MYMATH`` is ``ON``, the compile definition ``USE_MYMATH`` will +be set. We can then use this compile definition to enable or disable +sections of our source code. -For :command:`target_link_libraries`, we replace the written out -library names with ``EXTRA_LIBS``. This looks like the following: +The corresponding changes to the source code are fairly straightforward. +In ``MathFunctions.cxx``, we make ``USE_MYMATH`` control which square root +function is used: .. raw:: html <details><summary>TODO 9: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 9: CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries-EXTRA_LIBS - :language: cmake - :start-after: add_executable(Tutorial tutorial.cxx) - :end-before: # TODO 3 +.. literalinclude:: Step3/MathFunctions/MathFunctions.cxx + :caption: TODO 9: MathFunctions/MathFunctions.cxx + :name: MathFunctions-USE_MYMATH-if + :language: c++ + :start-after: which square root function should we use? + :end-before: } .. raw:: html </details> -Then, we do the same thing with :command:`target_include_directories` and -``EXTRA_INCLUDES``. +Next, we need to include ``mysqrt.h`` if ``USE_MYMATH`` is defined. .. raw:: html <details><summary>TODO 10: Click to show/hide answer</summary> -.. literalinclude:: Step3/CMakeLists.txt - :caption: TODO 10 : CMakeLists.txt - :name: CMakeLists.txt-target_link_libraries-EXTRA_INCLUDES - :language: cmake - :start-after: # so that we will find TutorialConfig.h +.. literalinclude:: Step3/MathFunctions/MathFunctions.cxx + :caption: TODO 10: MathFunctions/MathFunctions.cxx + :name: MathFunctions-USE_MYMATH-if-include + :language: c++ + :start-after: include <cmath> + :end-before: namespace mathfunctions .. raw:: html </details> -Note that this is a classic approach when dealing with many components. We -will cover the modern approach in the Step 3 of the tutorial. - -The corresponding changes to the source code are fairly straightforward. -First, in ``tutorial.cxx``, we include the ``MathFunctions.h`` header if -``USE_MYMATH`` is defined. +Finally, we need to include ``cmath`` now that we are using ``std::sqrt``. .. raw:: html <details><summary>TODO 11: Click to show/hide answer</summary> -.. literalinclude:: Step3/tutorial.cxx - :caption: TODO 11 : tutorial.cxx - :name: tutorial.cxx-ifdef-include - :language: c++ - :start-after: // should we include the MathFunctions header - :end-before: int main +.. code-block:: c++ + :caption: TODO 11 : MathFunctions/MathFunctions.cxx + :name: tutorial.cxx-include_cmath + + #include <cmath> .. raw:: html </details> -Then, in the same file, we make ``USE_MYMATH`` control which square root -function is used: +At this point, if ``USE_MYMATH`` is ``OFF``, ``mysqrt.cxx`` would not be used +but it will still be compiled because the ``MathFunctions`` target has +``mysqrt.cxx`` listed under sources. + +There are a few ways to fix this. The first option is to use +:command:`target_sources` to add ``mysqrt.cxx`` from within the ``USE_MYMATH`` +block. Another option is to create an additional library within the +``USE_MYMATH`` block which is responsible for compiling ``mysqrt.cxx``. For +the sake of this tutorial, we are going to create an additional library. + +First, from within ``USE_MYMATH`` create a library called ``SqrtLibrary`` +that has sources ``mysqrt.cxx``. .. raw:: html <details><summary>TODO 12: Click to show/hide answer</summary> -.. literalinclude:: Step3/tutorial.cxx - :caption: TODO 12 : tutorial.cxx - :name: tutorial.cxx-ifdef-const - :language: c++ - :start-after: // which square root function should we use? - :end-before: std::cout << "The square root of +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 12 : MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-add_library-SqrtLibrary + :language: cmake + :start-after: # library that just does sqrt + :end-before: target_link_libraries(MathFunctions .. raw:: html </details> -Since the source code now requires ``USE_MYMATH`` we can add it to -``TutorialConfig.h.in`` with the following line: +Next, we link ``SqrtLibrary`` onto ``MathFunctions`` when ``USE_MYMATH`` is +enabled. .. raw:: html <details><summary>TODO 13: Click to show/hide answer</summary> -.. literalinclude:: Step3/TutorialConfig.h.in - :caption: TODO 13 : TutorialConfig.h.in - :name: TutorialConfig.h.in-cmakedefine - :language: c++ - :lines: 4 +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 13 : MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-target_link_libraries-SqrtLibrary + :language: cmake + :lines: 16-18 .. raw:: html </details> -With these changes, our library is now completely optional to whoever is -building and using it. - -Bonus Question --------------- - -Why is it important that we configure ``TutorialConfig.h.in`` -after the option for ``USE_MYMATH``? What would happen if we inverted the two? - -Answer ------- +Finally, we can remove ``mysqrt.cxx`` from our ``MathFunctions`` library +source list because it will be pulled in when ``SqrtLibrary`` is included. .. raw:: html - <details><summary>Click to show/hide answer</summary> + <details><summary>TODO 14: Click to show/hide answer</summary> -We configure after because ``TutorialConfig.h.in`` uses the value of -``USE_MYMATH``. If we configure the file before -calling :command:`option`, we won't be using the expected value of -``USE_MYMATH``. +.. literalinclude:: Step3/MathFunctions/CMakeLists.txt + :caption: TODO 14 : MathFunctions/CMakeLists.txt + :name: MathFunctions/CMakeLists.txt-remove-mysqrt.cxx-MathFunctions + :language: cmake + :end-before: # TODO 1: .. raw:: html </details> + +With these changes, the ``mysqrt`` function is now completely optional to +whoever is building and using the ``MathFunctions`` library. Users can toggle +``USE_MYMATH`` to manipulate what library is used in the build. diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt index d256db20a4..b22150643f 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt @@ -15,16 +15,7 @@ if(USE_MYMATH) target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - # first we add the executable that generates the table - add_executable(MakeTable MakeTable.cxx) - target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - - # add the command to generate the source code - add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) + include(MakeTable.cmake) # generates Table.h # library that just does sqrt add_library(SqrtLibrary STATIC diff --git a/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cmake new file mode 100644 index 0000000000..12865a9831 --- /dev/null +++ b/Help/guide/tutorial/Complete/MathFunctions/MakeTable.cmake @@ -0,0 +1,10 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) +target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) diff --git a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx index 0145300629..c0991b9b98 100644 --- a/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Complete/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst index 7befe1d3fd..504e42fd58 100644 --- a/Help/guide/tutorial/Selecting Static or Shared Libraries.rst +++ b/Help/guide/tutorial/Selecting Static or Shared Libraries.rst @@ -10,49 +10,22 @@ To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows users to optionally select if the value should be ``ON`` or ``OFF``. -Next we are going to refactor ``MathFunctions`` to become a real library that -encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling -code to do this logic. This will also mean that ``USE_MYMATH`` will not control -building ``MathFunctions``, but instead will control the behavior of this -library. - -The first step is to update the starting section of the top-level -``CMakeLists.txt`` to look like: - .. literalinclude:: Step11/CMakeLists.txt :caption: CMakeLists.txt :name: CMakeLists.txt-option-BUILD_SHARED_LIBS :language: cmake - :end-before: # add the binary tree - -Now that we have made ``MathFunctions`` always be used, we will need to update -the logic of that library. So, in ``MathFunctions/CMakeLists.txt`` we need to -create a SqrtLibrary that will conditionally be built and installed when -``USE_MYMATH`` is enabled. Now, since this is a tutorial, we are going to -explicitly require that SqrtLibrary is built statically. + :start-after: set(CMAKE_RUNTIME_OUTPUT_DIRECTORY + :end-before: # configure a header file to pass the version number only -The end result is that ``MathFunctions/CMakeLists.txt`` should look like: +Next, we need to specify output directories for our static and shared +libraries. -.. literalinclude:: Step11/MathFunctions/CMakeLists.txt - :caption: MathFunctions/CMakeLists.txt - :name: MathFunctions/CMakeLists.txt-add_library-STATIC +.. literalinclude:: Step11/CMakeLists.txt + :caption: CMakeLists.txt + :name: CMakeLists.txt-cmake-output-directories :language: cmake - :lines: 1-36,42- - -Next, update ``MathFunctions/mysqrt.cxx`` to use the ``mathfunctions`` and -``detail`` namespaces: - -.. literalinclude:: Step11/MathFunctions/mysqrt.cxx - :caption: MathFunctions/mysqrt.cxx - :name: MathFunctions/mysqrt.cxx-namespace - :language: c++ - -We also need to make some changes in ``tutorial.cxx``, so that it no longer -uses ``USE_MYMATH``: - -#. Always include ``MathFunctions.h`` -#. Always use ``mathfunctions::sqrt`` -#. Don't include ``cmath`` + :start-after: # we don't need to tinker with the path to run the executable + :end-before: # configure a header file to pass the version number only Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines: diff --git a/Help/guide/tutorial/Step10/CMakeLists.txt b/Help/guide/tutorial/Step10/CMakeLists.txt index 5c661aa229..2dd6db50f9 100644 --- a/Help/guide/tutorial/Step10/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/CMakeLists.txt @@ -16,22 +16,15 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - -# configure a header file to pass some of the CMake settings -# to the source code +# configure a header file to pass the version number only configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt index fa73321670..36b3fe10a5 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step10/MathFunctions/CMakeLists.txt @@ -1,32 +1,42 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) - -# add the main library -add_library(MathFunctions - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) +# add the library that runs +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. -# state that we depend on our binary dir to find Table.h target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${CMAKE_CURRENT_BINARY_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) -# link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if(USE_MYMATH) + + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + include(MakeTable.cmake) # generates Table.h + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() install(TARGETS ${installable_libs} DESTINATION lib) # install include headers install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cmake new file mode 100644 index 0000000000..12865a9831 --- /dev/null +++ b/Help/guide/tutorial/Step10/MathFunctions/MakeTable.cmake @@ -0,0 +1,10 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) +target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx index 0145300629..c0991b9b98 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h index cd36bccffd..1e916e1192 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step10/MathFunctions/MathFunctions.h @@ -1 +1,3 @@ -double mysqrt(double x); +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx index 7d80ee9648..8153f18bed 100644 --- a/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step10/MathFunctions/mysqrt.cxx @@ -5,6 +5,8 @@ // include the generated table #include "Table.h" +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -31,3 +33,5 @@ double mysqrt(double x) return result; } +} +} diff --git a/Help/guide/tutorial/Step10/TutorialConfig.h.in b/Help/guide/tutorial/Step10/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step10/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step10/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step10/tutorial.cxx b/Help/guide/tutorial/Step10/tutorial.cxx index b3c6a4f43c..37a03336ca 100644 --- a/Help/guide/tutorial/Step10/tutorial.cxx +++ b/Help/guide/tutorial/Step10/tutorial.cxx @@ -1,15 +1,11 @@ // A simple program that computes the square root of a number -#include <cmath> #include <iostream> +#include <sstream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt index a60fb633b5..813bf90c08 100644 --- a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt @@ -13,16 +13,7 @@ if(USE_MYMATH) target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - # first we add the executable that generates the table - add_executable(MakeTable MakeTable.cxx) - target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - - # add the command to generate the source code - add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) + include(MakeTable.cmake) # generates Table.h # library that just does sqrt add_library(SqrtLibrary STATIC diff --git a/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cmake new file mode 100644 index 0000000000..12865a9831 --- /dev/null +++ b/Help/guide/tutorial/Step11/MathFunctions/MakeTable.cmake @@ -0,0 +1,10 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) +target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) diff --git a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx index 0145300629..c0991b9b98 100644 --- a/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step11/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt index a85f3cb700..38694dd352 100644 --- a/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt @@ -15,16 +15,7 @@ if(USE_MYMATH) target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") - # first we add the executable that generates the table - add_executable(MakeTable MakeTable.cxx) - target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) - - # add the command to generate the source code - add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) + include(MakeTable.cmake) # generates Table.h # library that just does sqrt add_library(SqrtLibrary STATIC diff --git a/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cmake new file mode 100644 index 0000000000..12865a9831 --- /dev/null +++ b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cmake @@ -0,0 +1,10 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) +target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) diff --git a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx index 0145300629..c0991b9b98 100644 --- a/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx +++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx @@ -10,6 +10,7 @@ namespace mathfunctions { double sqrt(double x) { +// which square root function should we use? #ifdef USE_MYMATH return detail::mysqrt(x); #else diff --git a/Help/guide/tutorial/Step2/CMakeLists.txt b/Help/guide/tutorial/Step2/CMakeLists.txt index 2b96128e16..0a06ed7d49 100644 --- a/Help/guide/tutorial/Step2/CMakeLists.txt +++ b/Help/guide/tutorial/Step2/CMakeLists.txt @@ -7,36 +7,20 @@ project(Tutorial VERSION 1.0) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# TODO 7: Create a variable USE_MYMATH using option and set default to ON - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) -# TODO 8: Use list() and APPEND to create a list of optional libraries -# called EXTRA_LIBS and a list of optional include directories called -# EXTRA_INCLUDES. Add the MathFunctions library and source directory to -# the appropriate lists. -# -# Only call add_subdirectory and only add MathFunctions specific values -# to EXTRA_LIBS and EXTRA_INCLUDES if USE_MYMATH is true. - # TODO 2: Use add_subdirectory() to add MathFunctions to this project # add the executable add_executable(Tutorial tutorial.cxx) -# TODO 9: Use EXTRA_LIBS instead of the MathFunctions specific values -# in target_link_libraries. - # TODO 3: Use target_link_libraries to link the library to our executable # TODO 4: Add MathFunctions to Tutorial's target_include_directories() # Hint: ${PROJECT_SOURCE_DIR} is a path to the project source. AKA This folder! -# TODO 10: Use EXTRA_INCLUDES instead of the MathFunctions specific values -# in target_include_directories. - # add the binary tree to the search path for include files # so that we will find TutorialConfig.h target_include_directories(Tutorial PUBLIC diff --git a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt index b7779b7f28..c3cd806cff 100644 --- a/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step2/MathFunctions/CMakeLists.txt @@ -1,2 +1,15 @@ -# TODO 1: Add a library called MathFunctions +# TODO 14: Remove mysqrt.cxx from the list of sources + +# TODO 1: Add a library called MathFunctions with sources MathFunctions.cxx +# and mysqrt.cxx # Hint: You will need the add_library command + +# TODO 7: Create a variable USE_MYMATH using option and set default to ON + +# TODO 8: If USE_MYMATH is ON, use target_compile_definitions to pass +# USE_MYMATH as a precompiled definition to our source files + +# TODO 12: When USE_MYMATH is ON, add a library for SqrtLibrary with +# source mysqrt.cxx + +# TODO 13: When USE_MYMATH is ON, link SqrtLibrary to the MathFunctions Library diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..781d0ecc4e --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.cxx @@ -0,0 +1,15 @@ +#include "MathFunctions.h" + +// TODO 11: include cmath + +// TODO 10: Wrap the mysqrt include in a precompiled ifdef based on USE_MYMATH +#include "mysqrt.h" + +namespace mathfunctions { +double sqrt(double x) +{ + // TODO 9: If USE_MYMATH is defined, use detail::mysqrt. + // Otherwise, use std::sqrt. + return detail::mysqrt(x); +} +} diff --git a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step2/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx index 1e4d97ae7c..ba0ac645b5 100644 --- a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.cxx @@ -1,5 +1,9 @@ +#include "mysqrt.h" + #include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -20,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step2/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step2/TutorialConfig.h.in b/Help/guide/tutorial/Step2/TutorialConfig.h.in index 6c09e1aca4..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step2/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step2/TutorialConfig.h.in @@ -1,5 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ - -// TODO 13: use cmakedefine to define USE_MYMATH diff --git a/Help/guide/tutorial/Step2/tutorial.cxx b/Help/guide/tutorial/Step2/tutorial.cxx index 87f5e0f645..7a2a5951e6 100644 --- a/Help/guide/tutorial/Step2/tutorial.cxx +++ b/Help/guide/tutorial/Step2/tutorial.cxx @@ -3,11 +3,8 @@ #include <iostream> #include <string> -#include "TutorialConfig.h" - -// TODO 11: Only include MathFunctions if USE_MYMATH is defined - // TODO 5: Include MathFunctions.h +#include "TutorialConfig.h" int main(int argc, char* argv[]) { @@ -22,9 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // TODO 12: Use mysqrt if USE_MYMATH is defined and sqrt otherwise - - // TODO 6: Replace sqrt with mysqrt + // TODO 6: Replace sqrt with mathfunctions::sqrt // calculate square root const double outputValue = sqrt(inputValue); diff --git a/Help/guide/tutorial/Step3/CMakeLists.txt b/Help/guide/tutorial/Step3/CMakeLists.txt index 007770a373..f051826a7d 100644 --- a/Help/guide/tutorial/Step3/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/CMakeLists.txt @@ -7,9 +7,6 @@ project(Tutorial VERSION 1.0) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) @@ -17,16 +14,13 @@ configure_file(TutorialConfig.h.in TutorialConfig.h) # TODO 2: Remove EXTRA_INCLUDES list # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) - list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") -endif() +add_subdirectory(MathFunctions) +list(APPEND EXTRA_INCLUDES "${PROJECT_SOURCE_DIR}/MathFunctions") # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) +target_link_libraries(Tutorial PUBLIC MathFunctions) # TODO 3: Remove use of EXTRA_INCLUDES diff --git a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt index 7bf05e02c5..6f86ffef5b 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step3/MathFunctions/CMakeLists.txt @@ -1,5 +1,18 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx) # TODO 1: State that anybody linking to MathFunctions needs to include the # current source directory, while MathFunctions itself doesn't. # Hint: Use target_include_directories with the INTERFACE keyword + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ) + + target_link_libraries(MathFunctions PUBLIC SqrtLibrary) +endif() diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..dc28b4b530 --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step3/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx index abe767d5ae..ba0ac645b5 100644 --- a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step3/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step3/TutorialConfig.h.in b/Help/guide/tutorial/Step3/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step3/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step3/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step3/tutorial.cxx b/Help/guide/tutorial/Step3/tutorial.cxx index b3c6a4f43c..a3a2bdce00 100644 --- a/Help/guide/tutorial/Step3/tutorial.cxx +++ b/Help/guide/tutorial/Step3/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step4/CMakeLists.txt b/Help/guide/tutorial/Step4/CMakeLists.txt index fa4aab270b..7531fb41ab 100644 --- a/Help/guide/tutorial/Step4/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/CMakeLists.txt @@ -1,4 +1,4 @@ -# TODO 4: Update the minimum required version to 3.15 +# TODO 5: Update the minimum required version to 3.15 cmake_minimum_required(VERSION 3.10) @@ -15,41 +15,35 @@ project(Tutorial VERSION 1.0) set(CMAKE_CXX_STANDARD 11) set(CMAKE_CXX_STANDARD_REQUIRED True) -# TODO 5: Create helper variables to determine which compiler we are using: +# TODO 6: Create helper variables to determine which compiler we are using: # * Create a new variable gcc_like_cxx that is true if we are using CXX and # any of the following compilers: ARMClang, AppleClang, Clang, GNU, LCC # * Create a new variable msvc_cxx that is true if we are using CXX and MSVC # Hint: Use set() and COMPILE_LANG_AND_ID -# TODO 6: Add warning flag compile options to the interface library +# TODO 7: Add warning flag compile options to the interface library # tutorial_compiler_flags. # * For gcc_like_cxx, add flags -Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused # * For msvc_cxx, add flags -W3 # Hint: Use target_compile_options() -# TODO 7: With nested generator expressions, only use the flags for the +# TODO 8: With nested generator expressions, only use the flags for the # build-tree # Hint: Use BUILD_INTERFACE -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) # TODO 2: Link to tutorial_compiler_flags -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS}) +target_link_libraries(Tutorial PUBLIC MathFunctions) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt index 5f7369cae7..ffab4f0a80 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step4/MathFunctions/CMakeLists.txt @@ -1,9 +1,25 @@ -add_library(MathFunctions mysqrt.cxx) +# create the MathFunctions library +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ) + + # TODO 4: Link to tutorial_compiler_flags + + target_link_libraries(MathFunctions PUBLIC SqrtLibrary) +endif() # TODO 3: Link to tutorial_compiler_flags diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..dc28b4b530 --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step4/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx index abe767d5ae..ba0ac645b5 100644 --- a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step4/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step4/TutorialConfig.h.in b/Help/guide/tutorial/Step4/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step4/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step4/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step4/tutorial.cxx b/Help/guide/tutorial/Step4/tutorial.cxx index b3c6a4f43c..a3a2bdce00 100644 --- a/Help/guide/tutorial/Step4/tutorial.cxx +++ b/Help/guide/tutorial/Step4/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step5/CMakeLists.txt b/Help/guide/tutorial/Step5/CMakeLists.txt index 279ddf93a3..ad814f69eb 100644 --- a/Help/guide/tutorial/Step5/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt index 6cd88d7ec2..0c688f274d 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step5/MathFunctions/CMakeLists.txt @@ -1,13 +1,28 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ) + + # link our compiler flags interface library + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() # link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # TODO 1: Create a variable called installable_libs that is a list of all # libraries we want to install (e.g. MathFunctions and tutorial_compiler_flags) diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..dc28b4b530 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step5/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx index abe767d5ae..ba0ac645b5 100644 --- a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step5/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step5/TutorialConfig.h.in b/Help/guide/tutorial/Step5/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step5/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step5/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step5/tutorial.cxx b/Help/guide/tutorial/Step5/tutorial.cxx index b3c6a4f43c..a3a2bdce00 100644 --- a/Help/guide/tutorial/Step5/tutorial.cxx +++ b/Help/guide/tutorial/Step5/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step6/CMakeLists.txt b/Help/guide/tutorial/Step6/CMakeLists.txt index c11e307736..a86d60aae0 100644 --- a/Help/guide/tutorial/Step6/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt index b4724c4a10..b1b925eccc 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step6/MathFunctions/CMakeLists.txt @@ -1,16 +1,33 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() # link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() install(TARGETS ${installable_libs} DESTINATION lib) # install include headers install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..dc28b4b530 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step6/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx index abe767d5ae..ba0ac645b5 100644 --- a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.cxx @@ -1,7 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -22,3 +24,5 @@ double mysqrt(double x) } return result; } +} +} diff --git a/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step6/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step6/TutorialConfig.h.in b/Help/guide/tutorial/Step6/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step6/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step6/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step6/tutorial.cxx b/Help/guide/tutorial/Step6/tutorial.cxx index b3c6a4f43c..a3a2bdce00 100644 --- a/Help/guide/tutorial/Step6/tutorial.cxx +++ b/Help/guide/tutorial/Step6/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step7/CMakeLists.txt b/Help/guide/tutorial/Step7/CMakeLists.txt index d26a90cee8..97ec6aaa38 100644 --- a/Help/guide/tutorial/Step7/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt index e5bdc4da15..897ec0e644 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step7/MathFunctions/CMakeLists.txt @@ -1,36 +1,54 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) -# link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) -# TODO 1: Include CheckCXXSourceCompiles + # TODO 1: Include CheckCXXSourceCompiles -# TODO 2: Use check_cxx_source_compiles with simple C++ code to verify -# availability of: -# * std::log -# * std::exp -# Store the results in HAVE_LOG and HAVE_EXP respectively. + # TODO 2: Use check_cxx_source_compiles with simple C++ code to verify + # availability of: + # * std::log + # * std::exp + # Store the results in HAVE_LOG and HAVE_EXP respectively. -# Hint: Sample C++ code which uses log: -# #include <cmath> -# int main() { -# std::log(1.0); -# return 0; -# } + # Hint: Sample C++ code which uses log: + # #include <cmath> + # int main() { + # std::log(1.0); + # return 0; + # } -# TODO 3: Conditionally on HAVE_LOG and HAVE_EXP, add private compile -# definitions "HAVE_LOG" and "HAVE_EXP" to the MathFunctions target. + # TODO 3: Conditionally on HAVE_LOG and HAVE_EXP, add private compile + # definitions "HAVE_LOG" and "HAVE_EXP" to the SqrtLibrary target. -#Hint: Use target_compile_definitions() + # Hint: Use target_compile_definitions() + + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +# link our compiler flags interface library +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() install(TARGETS ${installable_libs} DESTINATION lib) # install include headers install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..dc28b4b530 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step7/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx index 3d2492a648..9963cff7dc 100644 --- a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.cxx @@ -1,8 +1,9 @@ -#include <iostream> +#include "mysqrt.h" -// TODO 4: include cmath -#include "MathFunctions.h" +#include <iostream> +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -32,3 +33,5 @@ double mysqrt(double x) return result; } +} +} diff --git a/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step7/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step7/TutorialConfig.h.in b/Help/guide/tutorial/Step7/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step7/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step7/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step7/tutorial.cxx b/Help/guide/tutorial/Step7/tutorial.cxx index b3c6a4f43c..a3a2bdce00 100644 --- a/Help/guide/tutorial/Step7/tutorial.cxx +++ b/Help/guide/tutorial/Step7/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step8/CMakeLists.txt b/Help/guide/tutorial/Step8/CMakeLists.txt index cb87281b9e..97ec6aaa38 100644 --- a/Help/guide/tutorial/Step8/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/CMakeLists.txt @@ -16,23 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) - -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt index f81b563409..872a24a80e 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step8/MathFunctions/CMakeLists.txt @@ -1,39 +1,58 @@ -add_library(MathFunctions mysqrt.cxx) +add_library(MathFunctions MathFunctions.cxx) + +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + + # does this system provide the log and exp functions? + include(CheckCXXSourceCompiles) + check_cxx_source_compiles(" + #include <cmath> + int main() { + std::log(1.0); + return 0; + } + " HAVE_LOG) + check_cxx_source_compiles(" + #include <cmath> + int main() { + std::exp(1.0); + return 0; + } + " HAVE_EXP) + + # add compile definitions + if(HAVE_LOG AND HAVE_EXP) + target_compile_definitions(SqrtLibrary + PRIVATE "HAVE_LOG" "HAVE_EXP" + ) + endif() + + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) # link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) - -# does this system provide the log and exp functions? -include(CheckCXXSourceCompiles) -check_cxx_source_compiles(" - #include <cmath> - int main() { - std::log(1.0); - return 0; - } -" HAVE_LOG) -check_cxx_source_compiles(" - #include <cmath> - int main() { - std::exp(1.0); - return 0; - } -" HAVE_EXP) - -# add compile definitions -if(HAVE_LOG AND HAVE_EXP) - target_compile_definitions(MathFunctions - PRIVATE "HAVE_LOG" "HAVE_EXP") -endif() +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() install(TARGETS ${installable_libs} DESTINATION lib) # install include headers install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..dc28b4b530 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step8/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx index 7eecd26b5d..28ab042de6 100644 --- a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.cxx @@ -1,8 +1,10 @@ +#include "mysqrt.h" + #include <cmath> #include <iostream> -#include "MathFunctions.h" - +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -30,3 +32,5 @@ double mysqrt(double x) #endif return result; } +} +} diff --git a/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step8/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step8/TutorialConfig.h.in b/Help/guide/tutorial/Step8/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step8/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step8/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step8/tutorial.cxx b/Help/guide/tutorial/Step8/tutorial.cxx index b3c6a4f43c..a3a2bdce00 100644 --- a/Help/guide/tutorial/Step8/tutorial.cxx +++ b/Help/guide/tutorial/Step8/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/guide/tutorial/Step9/CMakeLists.txt b/Help/guide/tutorial/Step9/CMakeLists.txt index d26a90cee8..97ec6aaa38 100644 --- a/Help/guide/tutorial/Step9/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/CMakeLists.txt @@ -16,22 +16,17 @@ target_compile_options(tutorial_compiler_flags INTERFACE "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>" ) -# should we use our own math functions -option(USE_MYMATH "Use tutorial provided math implementation" ON) - # configure a header file to pass some of the CMake settings # to the source code configure_file(TutorialConfig.h.in TutorialConfig.h) # add the MathFunctions library -if(USE_MYMATH) - add_subdirectory(MathFunctions) - list(APPEND EXTRA_LIBS MathFunctions) -endif() +add_subdirectory(MathFunctions) # add the executable add_executable(Tutorial tutorial.cxx) -target_link_libraries(Tutorial PUBLIC ${EXTRA_LIBS} tutorial_compiler_flags) + +target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags) # add the binary tree to the search path for include files # so that we will find TutorialConfig.h diff --git a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt index 8e04f97492..54cecf812d 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt +++ b/Help/guide/tutorial/Step9/MathFunctions/CMakeLists.txt @@ -1,34 +1,41 @@ -# first we add the executable that generates the table -add_executable(MakeTable MakeTable.cxx) - -# add the command to generate the source code -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h - COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h - DEPENDS MakeTable - ) - -# add the main library -add_library(MathFunctions - mysqrt.cxx - ${CMAKE_CURRENT_BINARY_DIR}/Table.h - ) +add_library(MathFunctions MathFunctions.cxx) # state that anybody linking to us needs to include the current source dir # to find MathFunctions.h, while we don't. -# state that we depend on Tutorial_BINARY_DIR but consumers don't, as the -# TutorialConfig.h include is an implementation detail -# state that we depend on our binary dir to find Table.h target_include_directories(MathFunctions - INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} - PRIVATE ${CMAKE_CURRENT_BINARY_DIR} - ) + INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} + ) -# link our compiler flags interface library -target_link_libraries(MathFunctions tutorial_compiler_flags) +# should we use our own math functions +option(USE_MYMATH "Use tutorial provided math implementation" ON) +if (USE_MYMATH) + target_compile_definitions(MathFunctions PRIVATE "USE_MYMATH") + + # generate Table.h + include(MakeTable.cmake) + + # library that just does sqrt + add_library(SqrtLibrary STATIC + mysqrt.cxx + ${CMAKE_CURRENT_BINARY_DIR}/Table.h + ) + + # state that we depend on our binary dir to find Table.h + target_include_directories(SqrtLibrary PRIVATE + ${CMAKE_CURRENT_BINARY_DIR} + ) + + target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags) + target_link_libraries(MathFunctions PRIVATE SqrtLibrary) +endif() + +target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags) # install libs set(installable_libs MathFunctions tutorial_compiler_flags) +if(TARGET SqrtLibrary) + list(APPEND installable_libs SqrtLibrary) +endif() install(TARGETS ${installable_libs} DESTINATION lib) # install include headers install(FILES MathFunctions.h DESTINATION include) diff --git a/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cmake b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cmake new file mode 100644 index 0000000000..12865a9831 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MakeTable.cmake @@ -0,0 +1,10 @@ +# first we add the executable that generates the table +add_executable(MakeTable MakeTable.cxx) +target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags) + +# add the command to generate the source code +add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h + COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h + DEPENDS MakeTable + ) diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx new file mode 100644 index 0000000000..dc28b4b530 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.cxx @@ -0,0 +1,19 @@ +#include "MathFunctions.h" + +#include <cmath> + +#ifdef USE_MYMATH +# include "mysqrt.h" +#endif + +namespace mathfunctions { +double sqrt(double x) +{ +// which square root function should we use? +#ifdef USE_MYMATH + return detail::mysqrt(x); +#else + return std::sqrt(x); +#endif +} +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h index cd36bccffd..d5c2f224bf 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h +++ b/Help/guide/tutorial/Step9/MathFunctions/MathFunctions.h @@ -1 +1,5 @@ -double mysqrt(double x); +#pragma once + +namespace mathfunctions { +double sqrt(double x); +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx index 7d80ee9648..477d715205 100644 --- a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.cxx @@ -1,10 +1,12 @@ -#include <iostream> +#include "mysqrt.h" -#include "MathFunctions.h" +#include <iostream> // include the generated table #include "Table.h" +namespace mathfunctions { +namespace detail { // a hack square root calculation using simple operations double mysqrt(double x) { @@ -31,3 +33,5 @@ double mysqrt(double x) return result; } +} +} diff --git a/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h new file mode 100644 index 0000000000..593d41e7a6 --- /dev/null +++ b/Help/guide/tutorial/Step9/MathFunctions/mysqrt.h @@ -0,0 +1,7 @@ +#pragma once + +namespace mathfunctions { +namespace detail { +double mysqrt(double x); +} +} diff --git a/Help/guide/tutorial/Step9/TutorialConfig.h.in b/Help/guide/tutorial/Step9/TutorialConfig.h.in index e23f5213c7..7e4d7fa1fa 100644 --- a/Help/guide/tutorial/Step9/TutorialConfig.h.in +++ b/Help/guide/tutorial/Step9/TutorialConfig.h.in @@ -1,4 +1,3 @@ // the configured options and settings for Tutorial #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@ #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@ -#cmakedefine USE_MYMATH diff --git a/Help/guide/tutorial/Step9/tutorial.cxx b/Help/guide/tutorial/Step9/tutorial.cxx index b3c6a4f43c..a3a2bdce00 100644 --- a/Help/guide/tutorial/Step9/tutorial.cxx +++ b/Help/guide/tutorial/Step9/tutorial.cxx @@ -3,13 +3,9 @@ #include <iostream> #include <string> +#include "MathFunctions.h" #include "TutorialConfig.h" -// should we include the MathFunctions header? -#ifdef USE_MYMATH -# include "MathFunctions.h" -#endif - int main(int argc, char* argv[]) { if (argc < 2) { @@ -23,12 +19,7 @@ int main(int argc, char* argv[]) // convert input to double const double inputValue = std::stod(argv[1]); - // which square root function should we use? -#ifdef USE_MYMATH - const double outputValue = mysqrt(inputValue); -#else - const double outputValue = sqrt(inputValue); -#endif + const double outputValue = mathfunctions::sqrt(inputValue); std::cout << "The square root of " << inputValue << " is " << outputValue << std::endl; diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst index a09857b3a7..5b118d1315 100644 --- a/Help/manual/ccmake.1.rst +++ b/Help/manual/ccmake.1.rst @@ -8,6 +8,7 @@ Synopsis .. parsed-literal:: + ccmake [<options>] -B <path-to-build> [-S <path-to-source>] ccmake [<options>] <path-to-source | path-to-existing-build> Description diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index b9d621bafa..b88b8645c8 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -37,6 +37,8 @@ is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is linked in. +.. _`Binary Executables`: + Binary Executables ------------------ @@ -797,6 +799,10 @@ An *archive* output artifact of a buildsystem target may be: created by the :command:`add_executable` command when its :prop_tgt:`ENABLE_EXPORTS` target property is set. +* On macOS: the linker import file (e.g. ``.tbd``) of a shared library target + created by the :command:`add_library` command with the ``SHARED`` option and + when its :prop_tgt:`ENABLE_EXPORTS` target property is set. + The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` target properties may be used to control archive output artifact locations and names in the build tree. diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index 4c29b80f13..1f0c9111aa 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -20,6 +20,7 @@ Environment Variables that Change Behavior .. toctree:: :maxdepth: 1 + /envvar/CMAKE_MAXIMUM_RECURSION_DEPTH /envvar/CMAKE_PREFIX_PATH /envvar/SSL_CERT_DIR /envvar/SSL_CERT_FILE diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c3e87d77c9..9da37999b1 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -446,16 +446,20 @@ command. All paths are expected to be in cmake-style format. components from a path. See :ref:`Path Structure And Terminology` for the meaning of each path component. + .. versionchanged:: 3.27 + All operations now accept a list of paths as argument. When a list of paths + is specified, the operation will be applied to each path. + :: - $<PATH:GET_ROOT_NAME,path> - $<PATH:GET_ROOT_DIRECTORY,path> - $<PATH:GET_ROOT_PATH,path> - $<PATH:GET_FILENAME,path> - $<PATH:GET_EXTENSION[,LAST_ONLY],path> - $<PATH:GET_STEM[,LAST_ONLY],path> - $<PATH:GET_RELATIVE_PART,path> - $<PATH:GET_PARENT_PATH,path> + $<PATH:GET_ROOT_NAME,path...> + $<PATH:GET_ROOT_DIRECTORY,path...> + $<PATH:GET_ROOT_PATH,path...> + $<PATH:GET_FILENAME,path...> + $<PATH:GET_EXTENSION[,LAST_ONLY],path...> + $<PATH:GET_STEM[,LAST_ONLY],path...> + $<PATH:GET_RELATIVE_PART,path...> + $<PATH:GET_PARENT_PATH,path...> If a requested component is not present in the path, an empty string is returned. @@ -470,9 +474,14 @@ These expressions provide the generation-time capabilities equivalent to the options of the :command:`cmake_path` command. All paths are expected to be in cmake-style format. +.. versionchanged:: 3.27 + All operations now accept a list of paths as argument. When a list of paths + is specified, the operation will be applied to each path. + + .. _GenEx PATH-CMAKE_PATH: -.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path> +.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path...> .. versionadded:: 3.24 @@ -483,7 +492,7 @@ in cmake-style format. When the ``NORMALIZE`` option is specified, the path is :ref:`normalized <Normalization>` after the conversion. -.. genex:: $<PATH:APPEND,path,input,...> +.. genex:: $<PATH:APPEND,path...,input,...> .. versionadded:: 3.24 @@ -493,7 +502,7 @@ in cmake-style format. See :ref:`cmake_path(APPEND) <APPEND>` for more details. -.. genex:: $<PATH:REMOVE_FILENAME,path> +.. genex:: $<PATH:REMOVE_FILENAME,path...> .. versionadded:: 3.24 @@ -503,7 +512,7 @@ in cmake-style format. See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details. -.. genex:: $<PATH:REPLACE_FILENAME,path,input> +.. genex:: $<PATH:REPLACE_FILENAME,path...,input> .. versionadded:: 3.24 @@ -513,7 +522,7 @@ in cmake-style format. See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details. -.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path> +.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...> .. versionadded:: 3.24 @@ -521,7 +530,7 @@ in cmake-style format. See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details. -.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path,input> +.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input> .. versionadded:: 3.24 @@ -530,14 +539,14 @@ in cmake-style format. See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details. -.. genex:: $<PATH:NORMAL_PATH,path> +.. genex:: $<PATH:NORMAL_PATH,path...> .. versionadded:: 3.24 Returns ``path`` normalized according to the steps described in :ref:`Normalization`. -.. genex:: $<PATH:RELATIVE_PATH,path,base_directory> +.. genex:: $<PATH:RELATIVE_PATH,path...,base_directory> .. versionadded:: 3.24 @@ -547,7 +556,7 @@ in cmake-style format. See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more details. -.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory> +.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory> .. versionadded:: 3.24 @@ -1409,6 +1418,7 @@ In the following, the phrase "the ``tgt`` filename" means the name of the expression is being evaluated. .. genex:: $<TARGET_PROPERTY:prop> + :target: TARGET_PROPERTY:prop Value of the property ``prop`` on the target for which the expression is being evaluated. Note that for generator expressions in @@ -1494,6 +1504,76 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Full path to the linker import file. On DLL platforms, it would be the + ``.lib`` file. On AIX, for the executables, and on macOS, for the shared + libraries, it could be, respectively, the ``.imp`` or ``.tbd`` import file, + depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + An empty string is returned when there is no import file associated with the + target. + +.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of file linker import file of the target ``tgt`` without prefix and + suffix. For example, if target file name is ``libbase.tbd``, the base name is + ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>` and :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file of the target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file of the target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file of the target target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_DIR:tgt> + + Directory of the import file of the target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_LINKER_FILE:tgt> File used when linking to the ``tgt`` target. This will usually @@ -1501,13 +1581,22 @@ In the following, the phrase "the ``tgt`` filename" means the name of the but for a shared library on DLL platforms, it would be the ``.lib`` import library associated with the DLL. + .. versionadded:: 3.27 + On macOS, it could be the ``.tbd`` import file associated with the shared + library, depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + This generator expression is equivalent to + :genex:`$<TARGET_LINKER_LIBRARY_FILE>` or + :genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending of the + characteristics of the target and the platform. + .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 Base name of file used to link the target ``tgt``, i.e. - ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, - if target file name is ``libbase.a``, the base name is ``base``. + :genex:`$<TARGET_LINKER_FILE_NAME:tgt>` without prefix and suffix. For + example, if target file name is ``libbase.a``, the base name is ``base``. See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration @@ -1561,9 +1650,151 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_LINKER_LIBRARY_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking o the ``tgt`` target is done using directly the + library, and not an import file. This will usually be the library that + ``tgt`` represents (``.a``, ``.so``, ``.dylib``). So, on DLL platforms, it + will be an empty string. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of library file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_LIBRARY_FILE_NAME:tgt>` without prefix and suffix. + For example, if target file name is ``libbase.a``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the library file used to link target ``tgt``. + + See also the :prop_tgt:`PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the library file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".a" or ".dylib"). + + See also the :prop_tgt:`SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking to the ``tgt`` target is done using an import + file. This will usually be the import file that ``tgt`` represents + (``.lib``, ``.tbd``). So, when no import file is involved in the link step, + an empty string is returned. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of the import file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>` without prefix and suffix. + For example, if target file name is ``libbase.tbd``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file used to link target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_SONAME_FILE:tgt> File with soname (``.so.3``) where ``tgt`` is the name of a target. + .. genex:: $<TARGET_SONAME_FILE_NAME:tgt> Name of file with soname (``.so.3``). @@ -1573,11 +1804,35 @@ In the following, the phrase "the ``tgt`` filename" means the name of the .. genex:: $<TARGET_SONAME_FILE_DIR:tgt> - Directory of with soname (``.so.3``). + Directory of file with soname (``.so.3``). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_SONAME_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Import file with soname (``.3.tbd``) where ``tgt`` is the name of a target. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_PDB_FILE:tgt> .. versionadded:: 3.1 @@ -1668,7 +1923,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the List of DLLs that the target depends on at runtime. This is determined by the locations of all the ``SHARED`` targets in the target's transitive - dependencies. Using this generator expression on targets other than + dependencies. If only the directories of the DLLs are needed, see the + :genex:`TARGET_RUNTIME_DLL_DIRS` generator expression. + Using this generator expression on targets other than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. **On non-DLL platforms, this expression always evaluates to an empty string**. @@ -1700,6 +1957,20 @@ On platforms that support runtime paths (``RPATH``), refer to the :prop_tgt:`INSTALL_RPATH` target property. On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. +.. genex:: $<TARGET_RUNTIME_DLL_DIRS:tgt> + + .. versionadded:: 3.27 + + List of the directories which contain the DLLs that the target depends on at + runtime (see :genex:`TARGET_RUNTIME_DLLS`). This is determined by + the locations of all the ``SHARED`` targets in the target's transitive + dependencies. Using this generator expression on targets other than + executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + **On non-DLL platforms, this expression always evaluates to an empty string**. + + This generator expression can e.g. be used to create a batch file using + :command:`file(GENERATE)` which sets the PATH environment variable accordingly. + Export And Install Expressions ------------------------------ @@ -1725,8 +1996,10 @@ Export And Install Expressions Content of the install prefix when the target is exported via :command:`install(EXPORT)`, or when evaluated in the - :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of - :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. + :prop_tgt:`INSTALL_NAME_DIR` property, the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, the code argument of + :command:`install(CODE)`, or the file argument of :command:`install(SCRIPT)`, + and empty otherwise. Multi-level Expression Evaluation --------------------------------- diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index ed5bbbf6cb..9647f0d11d 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -107,6 +107,12 @@ Other Generators Extra Generators ================ +.. deprecated:: 3.27 + + Support for "Extra Generators" is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` command-line tool :option:`--help <cmake --help>` output may have variants that specify an extra generator for an auxiliary IDE tool. diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index cdb860f3ff..26083ca245 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -9,9 +9,9 @@ Synopsis .. parsed-literal:: cmake-gui [<options>] + cmake-gui [<options>] -B <path-to-build> [-S <path-to-source>] cmake-gui [<options>] <path-to-source | path-to-existing-build> - cmake-gui [<options>] -S <path-to-source> -B <path-to-build> - cmake-gui [<options>] --browse-manual + cmake-gui [<options>] --browse-manual [<filename>] Description =========== @@ -46,9 +46,11 @@ Options Name of the preset to use from the project's :manual:`presets <cmake-presets(7)>` files, if it has them. -.. option:: --browse-manual +.. option:: --browse-manual [<filename>] - Open the CMake reference manual in a browser and immediately exit. + Open the CMake reference manual in a browser and immediately exit. If + ``<filename>`` is specified, open that file within the reference manual + instead of ``index.html``. .. include:: OPTIONS_HELP.txt diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 22e9eb2b6d..8c7189a72b 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,19 @@ 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.27 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0149: Visual Studio generators select latest Windows SDK by default. </policy/CMP0149> + CMP0148: The FindPythonInterp and FindPythonLibs modules are removed. </policy/CMP0148> + CMP0147: Visual Studio generators build custom commands in parallel. </policy/CMP0147> + CMP0146: The FindCUDA module is removed. </policy/CMP0146> + CMP0145: The Dart and FindDart modules are removed. </policy/CMP0145> + CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables. </policy/CMP0144> + Policies Introduced by CMake 3.26 ================================= diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index da699d86af..7794e45ce5 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -63,6 +63,9 @@ The root object recognizes the following fields: ``6`` .. versionadded:: 3.25 + ``7`` + .. versionadded:: 3.27 + ``cmakeMinimumRequired`` An optional object representing the minimum version of CMake needed to build this project. This object consists of the following fields: @@ -359,6 +362,52 @@ that may contain the following fields: An optional boolean. Setting this to ``true`` is equivalent to passing :option:`--debug-find <cmake --debug-find>` on the command line. +``trace`` + An optional object specifying trace options. This is allowed in preset + files specifying version ``7``. The object may contain the following fields: + + ``mode`` + An optional string that specifies the trace mode. Valid values are: + + ``on`` + Causes a trace of all calls made and from where to be printed. + Equivalent to passing :option:`--trace <cmake --trace>` on the command + line. + + ``off`` + A trace of all calls will not be printed. + + ``expand`` + Causes a trace with variables expanded of all calls made and from where + to be printed. Equivalent to passing :option:`--trace-expand <cmake --trace-expand>` + on the command line. + + ``format`` + An optional string that specifies the format output of the trace. + Valid values are: + + ``human`` + Prints each trace line in a human-readable format. + This is the default format. Equivalent to passing + :option:`--trace-format=human <cmake --trace-format>` + on the command line. + + ``json-v1`` + Prints each line as a separate JSON document. Equivalent to passing + :option:`--trace-format=json-v1 <cmake --trace-format>` + on the command line. + + ``source`` + An optional array of strings representing the paths of source files to + be traced. This field can also be a string, which is equivalent to an + array containing one string. Equivalent to passing + :option:`--trace-source <cmake --trace-source>` on the command line. + + ``redirect`` + An optional string specifying a path to a trace output file. Equivalent + to passing :option:`--trace-redirect <cmake --trace-redirect>` + on the command line. + Build Preset ^^^^^^^^^^^^ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index fb84f5ae2d..c0e2ee2bdc 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -175,7 +175,10 @@ Properties on Targets /prop_tgt/CONFIG_POSTFIX /prop_tgt/CROSSCOMPILING_EMULATOR /prop_tgt/CUDA_ARCHITECTURES + /prop_tgt/CUDA_CUBIN_COMPILATION /prop_tgt/CUDA_EXTENSIONS + /prop_tgt/CUDA_FATBIN_COMPILATION + /prop_tgt/CUDA_OPTIX_COMPILATION /prop_tgt/CUDA_PTX_COMPILATION /prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS /prop_tgt/CUDA_RUNTIME_LIBRARY @@ -202,6 +205,7 @@ Properties on Targets /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPRECATION /prop_tgt/DISABLE_PRECOMPILE_HEADERS + /prop_tgt/DLL_NAME_WITH_SOVERSION /prop_tgt/DOTNET_SDK /prop_tgt/DOTNET_TARGET_FRAMEWORK /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION @@ -269,6 +273,7 @@ Properties on Targets /prop_tgt/INSTALL_REMOVE_ENVIRONMENT_RPATH /prop_tgt/INSTALL_RPATH /prop_tgt/INSTALL_RPATH_USE_LINK_PATH + /prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES /prop_tgt/INTERFACE_AUTOUIC_OPTIONS /prop_tgt/INTERFACE_COMPILE_DEFINITIONS /prop_tgt/INTERFACE_COMPILE_FEATURES diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 8a83807149..a831fa6ef1 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -84,7 +84,7 @@ Toolchain Features ================== CMake provides the :command:`try_compile` command and wrapper macros such as -:module:`CheckCXXSourceCompiles`, :module:`CheckCXXSymbolExists` and +:module:`CheckSourceCompiles`, :module:`CheckCXXSymbolExists` and :module:`CheckIncludeFile` to test capability and availability of various toolchain features. These APIs test the toolchain in some way and cache the result so that the test does not have to be performed again the next time @@ -273,7 +273,7 @@ supported out of the box. Other versions may require one to set Cross Compiling for Windows 10 Universal Applications ----------------------------------------------------- -A toolchain file to configure a Visual Studio generator for a +A toolchain file to configure :ref:`Visual Studio Generators` for a Windows 10 Universal Application may look like this: .. code-block:: cmake @@ -283,9 +283,10 @@ Windows 10 Universal Application may look like this: A Windows 10 Universal Application targets both Windows Store and Windows Phone. Specify the :variable:`CMAKE_SYSTEM_VERSION` variable -to be ``10.0`` to build with the latest available Windows 10 SDK. -Specify a more specific version (e.g. ``10.0.10240.0`` for RTM) -to build with the corresponding SDK. +to be ``10.0`` or higher. + +CMake selects a Windows SDK as described by documentation of the +:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable. Cross Compiling for Windows Phone --------------------------------- diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 23d8256622..f3212de4df 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -132,6 +132,7 @@ Variables that Provide Information /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION /variable/CMAKE_VS_VERSION_BUILD_NUMBER + /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM /variable/CMAKE_XCODE_BUILD_SYSTEM @@ -166,6 +167,7 @@ Variables that Change Behavior /variable/BUILD_SHARED_LIBS /variable/CMAKE_ABSOLUTE_DESTINATION_FILES + /variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY /variable/CMAKE_APPBUNDLE_PATH /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY @@ -226,6 +228,8 @@ Variables that Change Behavior /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT + /variable/CMAKE_KATE_FILES_MODE + /variable/CMAKE_KATE_MAKE_ARGUMENTS /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS @@ -400,11 +404,14 @@ Variables that Control the Build /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTOMOC_PATH_PREFIX + /variable/CMAKE_AUTOMOC_EXECUTABLE /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS + /variable/CMAKE_AUTORCC_EXECUTABLE /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_AUTOUIC_SEARCH_PATHS + /variable/CMAKE_AUTOUIC_EXECUTABLE /variable/CMAKE_BUILD_RPATH /variable/CMAKE_BUILD_RPATH_USE_ORIGIN /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR @@ -424,7 +431,9 @@ Variables that Control the Build /variable/CMAKE_DEFAULT_CONFIGS /variable/CMAKE_DEPENDS_USE_COMPILER /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS + /variable/CMAKE_DLL_NAME_WITH_SOVERSION /variable/CMAKE_ENABLE_EXPORTS + /variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT @@ -504,6 +513,7 @@ Variables that Control the Build /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index e48ecd972d..1ea7626103 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,8 +9,8 @@ Synopsis .. parsed-literal:: `Generate a Project Buildsystem`_ + cmake [<options>] -B <path-to-build> [-S <path-to-source>] cmake [<options>] <path-to-source | path-to-existing-build> - cmake [<options>] -S <path-to-source> -B <path-to-build> `Build a Project`_ cmake --build <dir> [<options>] [-- <build-tool-options>] @@ -116,6 +116,20 @@ Generate a Project Buildsystem Run CMake with one of the following command signatures to specify the source and build trees and generate a buildsystem: +``cmake [<options>] -B <path-to-build> [-S <path-to-source>]`` + + .. versionadded:: 3.13 + + Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` + as the source tree. The specified paths may be absolute or relative + to the current working directory. The source tree must contain a + ``CMakeLists.txt`` file. The build tree will be created automatically + if it does not already exist. For example: + + .. code-block:: console + + $ cmake -S src -B build + ``cmake [<options>] <path-to-source>`` Uses the current working directory as the build tree, and ``<path-to-source>`` as the source tree. The specified path may @@ -141,20 +155,6 @@ source and build trees and generate a buildsystem: $ cd build $ cmake . -``cmake [<options>] -S <path-to-source> -B <path-to-build>`` - - .. versionadded:: 3.13 - - Uses ``<path-to-build>`` as the build tree and ``<path-to-source>`` - as the source tree. The specified paths may be absolute or relative - to the current working directory. The source tree must contain a - ``CMakeLists.txt`` file. The build tree will be created automatically - if it does not already exist. For example: - - .. code-block:: console - - $ cmake -S src -B build - In all cases the ``<options>`` may be zero or more of the `Options`_ below. The above styles for specifying the source and build trees may be mixed. @@ -167,14 +167,14 @@ the current working directory (cwd) is used for the other. For example: ============================== ============ =========== Command Line Source Dir Build Dir ============================== ============ =========== + ``cmake -B build`` `cwd` ``build`` + ``cmake -B build src`` ``src`` ``build`` + ``cmake -B build -S src`` ``src`` ``build`` ``cmake src`` ``src`` `cwd` ``cmake build`` (existing) `loaded` ``build`` ``cmake -S src`` ``src`` `cwd` ``cmake -S src build`` ``src`` ``build`` ``cmake -S src -B build`` ``src`` ``build`` - ``cmake -B build`` `cwd` ``build`` - ``cmake -B build src`` ``src`` ``build`` - ``cmake -B build -S src`` ``src`` ``build`` ============================== ============ =========== .. versionchanged:: 3.23 @@ -781,7 +781,7 @@ Available commands are: (:option:`-A ... <cmake -A>`). The value is a list of platforms known to be supported. ``extraGenerators`` - A list of strings with all the extra generators compatible with + A list of strings with all the :ref:`Extra Generators` compatible with the generator. ``fileApi`` @@ -1080,11 +1080,18 @@ Available commands are: situations instead. Use ``--`` to stop interpreting options and treat all remaining arguments as paths, even if they start with ``-``. -.. option:: sleep <number>... +.. option:: sleep <number> .. versionadded:: 3.0 - Sleep for given number of seconds. + Sleep for ``<number>`` seconds. ``<number>`` may be a floating point number. + A practical minimum is about 0.1 seconds due to overhead in starting/stopping + CMake executable. This can be useful in a CMake script to insert a delay: + + .. code-block:: cmake + + # Sleep for about 0.5 seconds + execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5) .. option:: tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...] @@ -1189,7 +1196,7 @@ Available commands are: .. option:: time <command> [<args>...] - Run command and display elapsed time. + Run ``<command>`` and display elapsed time (including overhead of CMake frontend). .. versionadded:: 3.5 The command now properly passes arguments with spaces or special characters diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 5e82faae0d..994ae47b77 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -11,7 +11,7 @@ Synopsis .. parsed-literal:: `Run Tests`_ - ctest [<options>] + ctest [<options>] [--test-dir <path-to-build>] `Build and Test Mode`_ ctest --build-and-test <path-to-source> <path-to-build> @@ -354,7 +354,8 @@ Run Tests .. option:: --test-dir <dir> - Specify the directory in which to look for tests. + Specify the directory in which to look for tests, typically a CMake project + build directory. If not specified, the current directory is used. .. option:: --test-output-size-passed <size> diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json index 348116b38a..adfb1cb135 100644 --- a/Help/manual/presets/schema.json +++ b/Help/manual/presets/schema.json @@ -89,6 +89,23 @@ "include": { "$ref": "#/definitions/include"} }, "additionalProperties": false + }, + { + "properties": { + "version": { + "const": 7, + "description": "A required integer representing the version of the JSON schema." + }, + "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"}, + "vendor": { "$ref": "#/definitions/vendor" }, + "configurePresets": { "$ref": "#/definitions/configurePresetsV7"}, + "buildPresets": { "$ref": "#/definitions/buildPresetsV4"}, + "testPresets": { "$ref": "#/definitions/testPresetsV6"}, + "packagePresets": { "$ref": "#/definitions/packagePresetsV6"}, + "workflowPresets": { "$ref": "#/definitions/workflowPresetsV6" }, + "include": { "$ref": "#/definitions/include"} + }, + "additionalProperties": false } ], "required": [ @@ -119,6 +136,59 @@ "description": "An optional map containing vendor-specific information. CMake does not interpret the contents of this field except to verify that it is a map if it does exist. However, the keys should be a vendor-specific domain name followed by a /-separated path. For example, the Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of each field can be anything desired by the vendor, though will typically be a map.", "properties": {} }, + "configurePresetsItemsV7": { + "type": "array", + "description": "A configure preset object.", + "items": { + "type": "object", + "description": "A configure preset object.", + "properties": { + "trace": { + "type": "object", + "description": "An optional object specifying trace options.", + "properties": { + "mode": { + "type": "string", + "description": "An optional string that specifies the trace mode.", + "enum": [ + "on", "off", "expand" + ] + }, + "format": { + "type": "string", + "description": "An optional string that specifies the trace output format.", + "enum": [ + "human", "json-v1" + ] + }, + "source": { + "anyOf": [ + { + "type": "string", + "description": "An optional string representing the path to one source file to be traced.", + "minLength": 1 + }, + { + "type": "array", + "description": "An optional array of strings representing the paths to source files to be traced.", + "items": { + "type": "string", + "description": "A string representing the path to one source file to be traced.", + "minLength": 1 + } + } + ] + }, + "redirect": { + "type": "string", + "description": "An optional string specifying a path to a trace output file." + } + }, + "additionalProperties": false + } + } + } + }, "configurePresetsItemsV3": { "type": "array", "description": "A configure preset object.", @@ -393,6 +463,43 @@ } } }, + "configurePresetsV7": { + "type": "array", + "description": "An optional array of configure preset objects.", + "allOf": [ + { "$ref": "#/definitions/configurePresetsItemsV1" }, + { "$ref": "#/definitions/configurePresetsItemsV3" }, + { "$ref": "#/definitions/configurePresetsItemsV7" } + ], + "items": { + "properties": { + "name": {}, + "hidden": {}, + "inherits": {}, + "vendor": {}, + "displayName": {}, + "description": {}, + "generator": {}, + "architecture": {}, + "toolset": {}, + "toolchainFile": {}, + "binaryDir": {}, + "installDir": {}, + "cmakeExecutable": {}, + "cacheVariables": {}, + "environment": {}, + "warnings": {}, + "errors": {}, + "debug": {}, + "condition": {}, + "trace": {} + }, + "required": [ + "name" + ], + "additionalProperties": false + } + }, "configurePresetsV3": { "type": "array", "description": "An optional array of configure preset objects.", diff --git a/Help/module/CMAKE_REQUIRED_DEFINITIONS.txt b/Help/module/CMAKE_REQUIRED_DEFINITIONS.txt new file mode 100644 index 0000000000..17289c378a --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_DEFINITIONS.txt @@ -0,0 +1,4 @@ + ``CMAKE_REQUIRED_DEFINITIONS`` + A :ref:`;-list <CMake Language Lists>` of compiler definitions of the form + ``-DFOO`` or ``-DFOO=bar``. A definition for the name specified by + ``<resultVar>`` will also be added automatically. diff --git a/Help/module/CMAKE_REQUIRED_FLAGS.txt b/Help/module/CMAKE_REQUIRED_FLAGS.txt new file mode 100644 index 0000000000..80ae23999b --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_FLAGS.txt @@ -0,0 +1,6 @@ + ``CMAKE_REQUIRED_FLAGS`` + String of additional flags to pass to the compiler. The string must be + space-delimited--a :ref:`;-list <CMake Language Lists>` will not work. + The contents of :variable:`CMAKE_<LANG>_FLAGS <CMAKE_<LANG>_FLAGS>` and + its associated configuration-specific variable are automatically added + to the compiler command before the contents of ``CMAKE_REQUIRED_FLAGS``. diff --git a/Help/module/CMAKE_REQUIRED_INCLUDES.txt b/Help/module/CMAKE_REQUIRED_INCLUDES.txt new file mode 100644 index 0000000000..c8993bbfce --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_INCLUDES.txt @@ -0,0 +1,4 @@ + ``CMAKE_REQUIRED_INCLUDES`` + A :ref:`;-list <CMake Language Lists>` of header search paths to pass to + the compiler. These will be the only header search paths used--the contents + of the :prop_dir:`INCLUDE_DIRECTORIES` directory property will be ignored. diff --git a/Help/module/CMAKE_REQUIRED_LIBRARIES.txt b/Help/module/CMAKE_REQUIRED_LIBRARIES.txt new file mode 100644 index 0000000000..8611b9edf6 --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_LIBRARIES.txt @@ -0,0 +1,5 @@ + ``CMAKE_REQUIRED_LIBRARIES`` + A :ref:`;-list <CMake Language Lists>` of libraries to add to the link + command. These can be the name of system libraries or they can be + :ref:`Imported Targets <Imported Targets>` (see :command:`try_compile` for + further details). diff --git a/Help/module/CMAKE_REQUIRED_LINK_OPTIONS.txt b/Help/module/CMAKE_REQUIRED_LINK_OPTIONS.txt new file mode 100644 index 0000000000..f2a2474374 --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_LINK_OPTIONS.txt @@ -0,0 +1,5 @@ + ``CMAKE_REQUIRED_LINK_OPTIONS`` + .. versionadded:: 3.14 + + A :ref:`;-list <CMake Language Lists>` of options to add to the link + command (see :command:`try_compile` for further details). diff --git a/Help/module/CMAKE_REQUIRED_QUIET.txt b/Help/module/CMAKE_REQUIRED_QUIET.txt new file mode 100644 index 0000000000..aae8059f6d --- /dev/null +++ b/Help/module/CMAKE_REQUIRED_QUIET.txt @@ -0,0 +1,5 @@ + ``CMAKE_REQUIRED_QUIET`` + .. versionadded:: 3.1 + + If this variable evaluates to a boolean true value, all status messages + associated with the check will be suppressed. diff --git a/Help/policy/CMP0144.rst b/Help/policy/CMP0144.rst new file mode 100644 index 0000000000..3959d96142 --- /dev/null +++ b/Help/policy/CMP0144.rst @@ -0,0 +1,26 @@ +CMP0144 +------- + +.. versionadded:: 3.27 + +:command:`find_package` uses upper-case ``<PACKAGENAME>_ROOT`` variables. + +In CMake 3.27 and above the :command:`find_package(<PackageName>)` command now +searches prefixes specified by the upper-case :variable:`<PACKAGENAME>_ROOT` +CMake variable and the :envvar:`<PACKAGENAME>_ROOT` environment variable +in addition to the case-preserved :variable:`<PackageName>_ROOT` and +:envvar:`<PackageName>_ROOT` variables used since policy :policy:`CMP0074`. +This policy provides compatibility with projects that have not been +updated to avoid using ``<PACKAGENAME>_ROOT`` variables for other purposes. + +The ``OLD`` behavior for this policy is to ignore ``<PACKAGENAME>_ROOT`` +variables if the original ``<PackageName>`` has lower-case characters. +The ``NEW`` behavior for this policy is to use ``<PACKAGENAME>_ROOT`` +variables. + +This policy was introduced in CMake version 3.27. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0145.rst b/Help/policy/CMP0145.rst new file mode 100644 index 0000000000..bb1c02eab0 --- /dev/null +++ b/Help/policy/CMP0145.rst @@ -0,0 +1,30 @@ +CMP0145 +------- + +.. versionadded:: 3.27 + +The :module:`Dart` and :module:`FindDart` modules are removed. + +These modules were added very early in CMake's development to support +driving tests with a "DART" tool, but DART has not been distributed or +maintained for many years. Projects would ``include(Dart)`` to use it, +and the ``Dart`` module would run ``find_package(Dart)`` internally. +Since :manual:`ctest(1)` was created, the ``Dart`` module has just been +a compatibility shim that finds ``Dart`` to support some legacy +functionality and then forwards to the :module:`CTest` module. + +CMake 3.27 and above prefer to not provide the :module:`Dart` or +:module:`FindDart` modules. This policy provides compatibility for +projects that have not been ported away from them. Projects using the +``Dart`` module should be updated to use the :module:`CTest` module directly. + +The ``OLD`` behavior of this policy is for ``include(Dart)`` and +``find_package(Dart)`` to load the deprecated modules. The ``NEW`` +behavior is for uses of the modules to fail as if they do not exist. + +This policy was introduced in CMake version 3.27. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0146.rst b/Help/policy/CMP0146.rst new file mode 100644 index 0000000000..c7cac22044 --- /dev/null +++ b/Help/policy/CMP0146.rst @@ -0,0 +1,29 @@ +CMP0146 +------- + +.. versionadded:: 3.27 + +The :module:`FindCUDA` module is removed. + +The :module:`FindCUDA` module has been deprecated since CMake 3.10. +CMake 3.27 and above prefer to not provide the module. +This policy provides compatibility for projects that have not been +ported away from it. + +Projects using the :module:`FindCUDA` module should be updated to use +CMake's first-class ``CUDA`` language support. List ``CUDA`` among the +languages named in the top-level call to the :command:`project` command, +or call the :command:`enable_language` command with ``CUDA``. +Then one can add CUDA (``.cu``) sources directly to targets, +similar to other languages. + +The ``OLD`` behavior of this policy is for ``find_package(CUDA)`` to +load the deprecated module. The ``NEW`` behavior is for uses of the +module to fail as if it does not exist. + +This policy was introduced in CMake version 3.27. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0147.rst b/Help/policy/CMP0147.rst new file mode 100644 index 0000000000..0f25096633 --- /dev/null +++ b/Help/policy/CMP0147.rst @@ -0,0 +1,24 @@ +CMP0147 +------- + +.. versionadded:: 3.27 + +:ref:`Visual Studio Generators` build custom commands in parallel. + +Visual Studio 15.8 (2017) and newer support building custom commands in +parallel. CMake 3.27 and above prefer to enable this behavior by adding +a ``BuildInParallel`` setting to custom commands in ``.vcxproj`` files. +This policy provides compatibility for projects that have not been updated +to expect this, e.g., because their custom commands were accidentally +relying on serial execution by MSBuild. + +The ``OLD`` behavior for this policy is to not add ``BuildInParallel``. +The ``NEW`` behavior for this policy is to add ``BuildInParallel`` for +VS 15.8 and newer. + +This policy was introduced in CMake version 3.27. 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/policy/CMP0148.rst b/Help/policy/CMP0148.rst new file mode 100644 index 0000000000..2f5c43d209 --- /dev/null +++ b/Help/policy/CMP0148.rst @@ -0,0 +1,29 @@ +CMP0148 +------- + +.. versionadded:: 3.27 + +The :module:`FindPythonInterp` and :module:`FindPythonLibs` modules are removed. + +These modules have been deprecated since CMake 3.12. +CMake 3.27 and above prefer to not provide the modules. +This policy provides compatibility for projects that have not been +ported away from them. + +Projects using the :module:`FindPythonInterp` and/or :module:`FindPythonLibs` +modules should be updated to use one of their replacements: + +* :module:`FindPython3` +* :module:`FindPython2` +* :module:`FindPython` + +The ``OLD`` behavior of this policy is for ``find_package(PythonInterp)`` +and ``find_package(PythonLibs)`` to load the deprecated modules. The ``NEW`` +behavior is for uses of the modules to fail as if they do not exist. + +This policy was introduced in CMake version 3.27. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0149.rst b/Help/policy/CMP0149.rst new file mode 100644 index 0000000000..714eeaff2b --- /dev/null +++ b/Help/policy/CMP0149.rst @@ -0,0 +1,47 @@ +CMP0149 +------- + +.. versionadded:: 3.27 + +:ref:`Visual Studio Generators` select latest Windows SDK by default. + +Visual Studio Generators select a Windows SDK version to put in the +``WindowsTargetPlatformVersion`` setting in ``.vcxproj`` files. +CMake sets the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` +variable to the selected SDK version. + +Prior to CMake 3.27, the SDK version was always selected by the value of +the :variable:`CMAKE_SYSTEM_VERSION` variable. Users or toolchain files +could set that variable to one of the exact Windows SDK versions available +on the host system. Since :variable:`CMAKE_SYSTEM_VERSION` defaults to +:variable:`CMAKE_HOST_SYSTEM_VERSION`, and it is not guaranteed that a +matching Windows SDK version is available, CMake had to fall back to +using the latest Windows SDK version if no exact match was available. +This approach was problematic: + +* The latest Windows SDK might or might not be selected based on whether + the host version of Windows happens to match an available SDK version. + +* An old Windows SDK version might be selected that has not been updated + for newer language standards such as C11. + +CMake 3.27 and higher prefer to ignore the exact value of +:variable:`CMAKE_SYSTEM_VERSION` and by default select the latest SDK +version available. An exact SDK version may be specified explicitly +using a ``version=`` field in the :variable:`CMAKE_GENERATOR_PLATFORM` +variable. See :ref:`Visual Studio Platform Selection`. + +This policy provides compatibility for projects, toolchain files, and +build scripts that have not been ported away from using +:variable:`CMAKE_SYSTEM_VERSION` to specify an exact SDK version. + +The ``OLD`` behavior for this policy is to use the exact value of +:variable:`CMAKE_SYSTEM_VERSION` if possible. The ``NEW`` behavior +for this policy is to ignore it. + +This policy was introduced in CMake version 3.27. 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_test/WILL_FAIL.rst b/Help/prop_test/WILL_FAIL.rst index f1f94a43a7..4926f40779 100644 --- a/Help/prop_test/WILL_FAIL.rst +++ b/Help/prop_test/WILL_FAIL.rst @@ -3,5 +3,6 @@ WILL_FAIL If set to true, this will invert the pass/fail flag of the test. -This property can be used for tests that are expected to fail and -return a non zero return code. +This property can be used for tests that are expected to fail and return a +non-zero return code. Note that system-level test failures such as segmentation +faults or heap errors will still fail the test even if ``WILL_FALL`` is true. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst index 677e06df0f..abb627cdad 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst @@ -6,4 +6,7 @@ ARCHIVE_OUTPUT_DIRECTORY .. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY` .. include:: XXX_OUTPUT_DIRECTORY.txt +.. |IDEM| replace:: in the same directory +.. include:: MACOS_IMPORT_FILES.txt + See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst index 6150193739..1f1c4671f1 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst @@ -5,4 +5,7 @@ ARCHIVE_OUTPUT_NAME .. |xxx| replace:: archive .. include:: XXX_OUTPUT_NAME.txt +.. |IDEM| replace:: with the same name +.. include:: MACOS_IMPORT_FILES.txt + See also the :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst index 072e7f732a..a4a9ba2303 100644 --- a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -3,7 +3,7 @@ AUTOMOC_MACRO_NAMES .. versionadded:: 3.10 -A :ref:`semicolon-separated list <CMake Language Lists>` list of macro names used by +A :ref:`semicolon-separated list <CMake Language Lists>` of macro names used by :prop_tgt:`AUTOMOC` to determine if a C++ file needs to be processed by ``moc``. This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` @@ -21,6 +21,8 @@ then the file will be processed by ``moc``. By default ``AUTOMOC_MACRO_NAMES`` is initialized from :variable:`CMAKE_AUTOMOC_MACRO_NAMES`. +See also the :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. @@ -29,6 +31,8 @@ Example In this case the ``Q_OBJECT`` macro is hidden inside another macro called ``CUSTOM_MACRO``. To let CMake know that source files that contain -``CUSTOM_MACRO`` need to be ``moc`` processed, we call:: +``CUSTOM_MACRO`` need to be ``moc`` processed, we call: + +.. code-block:: cmake set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 2b93db177f..8b032adeee 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -11,6 +11,10 @@ The options will be added after flags in the variables, but before those propagated from dependencies by the :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property. +This property adds compile options for all languages in a target. +Use the :genex:`COMPILE_LANGUAGE` generator expression to specify +per-language compile options. + This property is initialized by the :prop_dir:`COMPILE_OPTIONS` directory property when a target is created, and is used by the generators to set the options for the compiler. diff --git a/Help/prop_tgt/CUDA_CUBIN_COMPILATION.rst b/Help/prop_tgt/CUDA_CUBIN_COMPILATION.rst new file mode 100644 index 0000000000..f8860aeda3 --- /dev/null +++ b/Help/prop_tgt/CUDA_CUBIN_COMPILATION.rst @@ -0,0 +1,14 @@ +CUDA_CUBIN_COMPILATION +---------------------- + +.. versionadded:: 3.27 + +Compile CUDA sources to ``.cubin`` files instead of ``.obj`` files +within :ref:`Object Libraries`. + +For example: + +.. code-block:: cmake + + add_library(mycubin OBJECT a.cu b.cu) + set_property(TARGET mycubin PROPERTY CUDA_CUBIN_COMPILATION ON) diff --git a/Help/prop_tgt/CUDA_FATBIN_COMPILATION.rst b/Help/prop_tgt/CUDA_FATBIN_COMPILATION.rst new file mode 100644 index 0000000000..3d3c715339 --- /dev/null +++ b/Help/prop_tgt/CUDA_FATBIN_COMPILATION.rst @@ -0,0 +1,14 @@ +CUDA_FATBIN_COMPILATION +----------------------- + +.. versionadded:: 3.27 + +Compile CUDA sources to ``.fatbin`` files instead of ``.obj`` files +within :ref:`Object Libraries`. + +For example: + +.. code-block:: cmake + + add_library(myfbins OBJECT a.cu b.cu) + set_property(TARGET myfbins PROPERTY CUDA_FATBIN_COMPILATION ON) diff --git a/Help/prop_tgt/CUDA_OPTIX_COMPILATION.rst b/Help/prop_tgt/CUDA_OPTIX_COMPILATION.rst new file mode 100644 index 0000000000..c2a06a88b7 --- /dev/null +++ b/Help/prop_tgt/CUDA_OPTIX_COMPILATION.rst @@ -0,0 +1,14 @@ +CUDA_OPTIX_COMPILATION +---------------------- + +.. versionadded:: 3.27 + +Compile CUDA sources to ``.optixir`` files instead of ``.obj`` files +within :ref:`Object Libraries`. + +For example: + +.. code-block:: cmake + + add_library(myoptix OBJECT a.cu b.cu) + set_property(TARGET myoptix PROPERTY CUDA_OPTIX_COMPILATION ON) diff --git a/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst b/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst new file mode 100644 index 0000000000..59ef00f0a1 --- /dev/null +++ b/Help/prop_tgt/DLL_NAME_WITH_SOVERSION.rst @@ -0,0 +1,17 @@ +DLL_NAME_WITH_SOVERSION +----------------------- + +.. versionadded:: 3.27 + +This property control whether the :prop_tgt:`SOVERSION` target +property are added to the filename of generated DLL filenames +for the Windows platform, which is selected when the +:variable:`WIN32` variable is set. + +The value of the listed property is appended to the +basename of the runtime component of the shared library +target as ``-<SOVERSION>``. + +Please note that setting this property has no effect +if versioned filenames are globally disabled with the +:variable:`CMAKE_PLATFORM_NO_VERSIONED_SONAME` variable. diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst index 0b1064ab4e..3e9b285534 100644 --- a/Help/prop_tgt/ENABLE_EXPORTS.rst +++ b/Help/prop_tgt/ENABLE_EXPORTS.rst @@ -1,7 +1,7 @@ ENABLE_EXPORTS -------------- -Specify whether an executable exports symbols for loadable modules. +Specify whether an executable or a shared library exports symbols. Normally an executable does not export any symbols because it is the final program. It is possible for an executable to export symbols to @@ -28,4 +28,29 @@ varies by platform: automatically bind symbols when the module is loaded. This property is initialized by the value of the variable -:variable:`CMAKE_ENABLE_EXPORTS` if it is set when a target is created. +:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` if it is set when an executable +target is created. + +.. versionadded:: 3.27 + On macOS, to link with a shared library (standard one as well as framework), + a linker import file (e.g. a text-based stubs file, with ``.tbd`` extension) + can be used instead of the shared library itself. + +The generation of these linker import files, as well as the consumption, is +controlled by this property. When this property is set to true, CMake will +generate a ``.tbd`` file for each shared library created by +:command:`add_library` command. This allow other targets to use this ``.tbd`` +file to link to the library with the :command:`target_link_libraries` +command. + +.. note:: + + For compatibility purpose, this property will be ignored if + :prop_tgt:`XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <XCODE_ATTRIBUTE_<an-attribute>>` + target property or the + :variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <CMAKE_XCODE_ATTRIBUTE_<an-attribute>>` + variable is set to ``NO``. + +This property is initialized by the value of the variable +:variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` if it is set when a shared +library target is created. diff --git a/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst b/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst index 6de1baa235..a4746d3d16 100644 --- a/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst +++ b/Help/prop_tgt/IMPORTED_CONFIGURATIONS.rst @@ -1,11 +1,22 @@ IMPORTED_CONFIGURATIONS ----------------------- -Configurations provided for an IMPORTED target. - -Set this to the list of configuration names available for an IMPORTED -target. The names correspond to configurations defined in the project -from which the target is imported. If the importing project uses a -different set of configurations the names may be mapped using the -MAP_IMPORTED_CONFIG_<CONFIG> property. Ignored for non-imported -targets. +Configurations provided for an :ref:`imported target <Imported targets>`. + +Set this to the list of configuration names available for an imported +target. For each configuration named, the imported target's artifacts +must be specified in other target properties: + +* :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`, or +* :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>` (on DLL platforms, on AIX for + :ref:`Executables <Binary Executables>` or on Apple for + :ref:`Shared Libraries <Normal Libraries>`), or +* :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` (for :ref:`Object Libraries`), or +* :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>` (for :ref:`Interface Libraries`). + +The configuration names correspond to those defined in the project from +which the target is imported. If the importing project uses a different +set of configurations, the names may be mapped using the +:prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property. + +The ``IMPORTED_CONFIGURATIONS`` property is ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst index c8b6fde95c..e67acbaa54 100644 --- a/Help/prop_tgt/IMPORTED_IMPLIB.rst +++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst @@ -3,7 +3,22 @@ IMPORTED_IMPLIB Full path to the import library for an ``IMPORTED`` target. -Set this to the location of the ``.lib`` part of a Windows DLL, or on -AIX set it to an import file created for executables that export symbols -(see the :prop_tgt:`ENABLE_EXPORTS` target property). -Ignored for non-imported targets. +This property may be set: + +* On DLL platforms, to the location of the ``.lib`` part of the DLL. +* On AIX, to an import file (e.g. ``.imp``) created for executables that export + symbols (see the :prop_tgt:`ENABLE_EXPORTS` target property). +* On macOS, to an import file (e.g. ``.tbd``) created for shared libraries (see + the :prop_tgt:`ENABLE_EXPORTS` target property). For frameworks this is the + location of the ``.tbd`` file symlink just inside the framework folder. + +The ``IMPORTED_IMPLIB`` target property may be overridden for a +given configuration ``<CONFIG>`` by the configuration-specific +:prop_tgt:`IMPORTED_IMPLIB_<CONFIG>` target property. Furthermore, +the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property may be +used to map between a project's configurations and those of an imported +target. If none of these is set then the name of any other configuration +listed in the :prop_tgt:`IMPORTED_CONFIGURATIONS` target property may be +selected and its :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>` value used. + +This property is ignored for non-imported targets. diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst index ddd910aafb..a7207d845b 100644 --- a/Help/prop_tgt/IMPORTED_LOCATION.rst +++ b/Help/prop_tgt/IMPORTED_LOCATION.rst @@ -27,5 +27,5 @@ selected and its :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` value used. To get the location of an imported target read one of the :prop_tgt:`LOCATION` or ``LOCATION_<CONFIG>`` properties. -For platforms with import libraries (e.g. Windows) see also +For platforms with import libraries (e.g. Windows, AIX or macOS) see also :prop_tgt:`IMPORTED_IMPLIB`. diff --git a/Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000000..502775c8e3 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,89 @@ +INTERFACE_AUTOMOC_MACRO_NAMES +----------------------------- + +.. versionadded:: 3.27 + +A :ref:`semicolon-separated list <CMake Language Lists>` of macro names for +:prop_tgt:`AUTOMOC` to be propagated to consumers. + +When a target with :prop_tgt:`AUTOMOC` enabled links to a library that sets +``INTERFACE_AUTOMOC_MACRO_NAMES``, the target inherits the listed macro names +and merges them with those specified in its own :prop_tgt:`AUTOMOC_MACRO_NAMES` +property. The target will then automatically generate MOC files for source +files that contain the inherited macro names too, not just the macro names +specified in its own :prop_tgt:`AUTOMOC_MACRO_NAMES` property. + +By default ``INTERFACE_AUTOMOC_MACRO_NAMES`` is empty. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Example 1 +^^^^^^^^^ + +In this example, ``myapp`` inherits the macro names ``STATIC_LIB_1`` and +``STATIC_LIB_2`` from ``static_lib``. The ``moc`` tool will then automatically +be run on any of the ``myapp`` sources which contain ``STATIC_LIB_1`` or +``STATIC_LIB_2``. + +.. code-block:: cmake + + set(AUTOMOC ON) + add_executable(myapp main.cpp) + target_link_libraries(myapp PRIVATE static_lib) + + add_library(static_lib STATIC static.cpp) + set_property(TARGET static_lib PROPERTY + INTERFACE_AUTOMOC_MACRO_NAMES "STATIC_LIB_1;STATIC_LIB_2" + ) + +Example 2 +^^^^^^^^^ + +In this example, the ``INTERFACE_AUTOMOC_MACRO_NAMES`` target property of the +various ``*_deep_lib`` libraries will propagate to ``shared_lib``, +``static_lib`` and ``interface_lib``. Because the linking relationships are +specified as ``PUBLIC`` and ``INTERFACE``, those macro names will also further +propagate transitively up to ``app``. + +.. code-block:: cmake + + set(AUTOMOC ON) + + add_library(shared_deep_lib SHARED deep_lib.cpp) + add_library(static_deep_lib STATIC deep_lib.cpp) + add_library(interface_deep_lib INTERFACE) + + set_property(TARGET shared_deep_lib PROPERTY + INTERFACE_AUTOMOC_MACRO_NAMES "SHARED_LINK_LIB" + ) + set_property(TARGET static_deep_lib PROPERTY + INTERFACE_AUTOMOC_MACRO_NAMES "STATIC_LINK_LIB" + ) + set_property(TARGET interface_deep_lib PROPERTY + INTERFACE_AUTOMOC_MACRO_NAMES "INTERFACE_LINK_LIB" + ) + + add_library(shared_lib SHARED lib.cpp) + add_library(static_lib STATIC lib.cpp) + add_library(interface_lib INTERFACE) + + # PUBLIC and INTERFACE here ensure the macro names propagate to any + # consumers of shared_lib, static_lib or interface_lib too + target_link_libraries(shared_lib PUBLIC shared_deep_lib) + target_link_libraries(static_lib PUBLIC static_deep_lib) + target_link_libraries(interface_lib INTERFACE interface_deep_lib) + + # This consumer will receive all three of the above custom macro names as + # transitive usage requirements + add_executable(app main.cpp) + target_link_libraries(app PRIVATE shared_lib static_lib interface_lib) + +In the above: + +* ``shared_lib`` sources will be processed by ``moc`` if they contain + ``SHARED_LINK_LIB``. +* ``static_lib`` sources will be processed by ``moc`` if they contain + ``STATIC_LINK_LIB``. +* ``app`` sources will be processed by ``moc`` if they contain + ``SHARED_LINK_LIB``, ``STATIC_LINK_LIB`` or ``INTERFACE_LINK_LIB``. diff --git a/Help/prop_tgt/LANG_CLANG_TIDY.rst b/Help/prop_tgt/LANG_CLANG_TIDY.rst index 31f1876e3b..1e109334b8 100644 --- a/Help/prop_tgt/LANG_CLANG_TIDY.rst +++ b/Help/prop_tgt/LANG_CLANG_TIDY.rst @@ -25,3 +25,8 @@ command line. This property is initialized by the value of the :variable:`CMAKE_<LANG>_CLANG_TIDY` variable if it is set when a target is created. + +.. versionadded:: 3.27 + + This property supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/LANG_CPPCHECK.rst b/Help/prop_tgt/LANG_CPPCHECK.rst index 80acbc02a9..0b2dee6e6c 100644 --- a/Help/prop_tgt/LANG_CPPCHECK.rst +++ b/Help/prop_tgt/LANG_CPPCHECK.rst @@ -15,3 +15,8 @@ tool returns non-zero. This property is initialized by the value of the :variable:`CMAKE_<LANG>_CPPCHECK` variable if it is set when a target is created. + +.. versionadded:: 3.27 + + This property supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/LANG_CPPLINT.rst b/Help/prop_tgt/LANG_CPPLINT.rst index be6db46b36..38a1669c13 100644 --- a/Help/prop_tgt/LANG_CPPLINT.rst +++ b/Help/prop_tgt/LANG_CPPLINT.rst @@ -13,3 +13,8 @@ and report any problems. This property is initialized by the value of the :variable:`CMAKE_<LANG>_CPPLINT` variable if it is set when a target is created. + +.. versionadded:: 3.27 + + This property supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst index eebef561bb..19b97f7a47 100644 --- a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst +++ b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst @@ -13,3 +13,8 @@ compiler and report a warning if the tool reports any problems. This property is initialized by the value of the :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable if it is set when a target is created. + +.. versionadded:: 3.27 + + This property supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst index f6ca5ad43d..d39ec203aa 100644 --- a/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_LINKER_LAUNCHER.rst @@ -14,3 +14,8 @@ arguments to the tool. This is useful for tools such as static analyzers. This property is initialized by the value of the :variable:`CMAKE_<LANG>_LINKER_LAUNCHER` variable if it is set when a target is created. + +.. versionadded:: 3.27 + + The property value may use + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/MACOS_IMPORT_FILES.txt b/Help/prop_tgt/MACOS_IMPORT_FILES.txt new file mode 100644 index 0000000000..3c98fc8ca8 --- /dev/null +++ b/Help/prop_tgt/MACOS_IMPORT_FILES.txt @@ -0,0 +1,12 @@ +.. note:: + + On macOS, this property will be ignored for the linker import files (e.g. + ``.tbd`` files, see :prop_tgt:`ENABLE_EXPORTS` property for details) when: + + * The :prop_tgt:`FRAMEWORK` is set, because the framework layout cannot be + changed. + * The :generator:`Xcode` generator is used, due to the limitations and + constraints of the ``Xcode`` tool. + + In both cases, the linker import files will be generated |IDEM| as the shared + library. diff --git a/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst b/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst index 50cf203b06..ef3ceb0f76 100644 --- a/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst +++ b/Help/prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst @@ -7,6 +7,11 @@ Visual Studio Windows Target Platform Minimum Version For Windows 10. Specifies the minimum version of the OS that is being targeted. For example ``10.0.10240.0``. If the value is not specified, the -value of :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` will be used on -WindowsStore projects otherwise the target platform minimum version will not -be specified for the project. +value of the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable +will be used on WindowsStore projects. Otherwise the target platform +minimum version will not be specified for the project. + +.. versionadded:: 3.27 + This property is initialized by the value of the + :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` variable + if it is set when a target is created. diff --git a/Help/release/3.11.rst b/Help/release/3.11.rst index 957dd4f1ff..6e1520aaed 100644 --- a/Help/release/3.11.rst +++ b/Help/release/3.11.rst @@ -174,7 +174,7 @@ Modules to removal of the ``javah`` tool by `JEP 313`_. .. _`FLAME`: https://github.com/flame -.. _`JEP 313`: https://openjdk.java.net/jeps/313 +.. _`JEP 313`: https://openjdk.org/jeps/313 Autogen ------- diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000000..e4cc01e23f --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/Apple-tbd-files-management.rst b/Help/release/dev/Apple-tbd-files-management.rst new file mode 100644 index 0000000000..edcfe55436 --- /dev/null +++ b/Help/release/dev/Apple-tbd-files-management.rst @@ -0,0 +1,6 @@ +Apple-tbd-files-management +-------------------------- + +* Support for text-based stubs (i.e. ``.tbd`` files) was added on macOS + platform. This capability is managed through the :prop_tgt:`ENABLE_EXPORTS` + property. diff --git a/Help/release/dev/FindCUDA-remove.rst b/Help/release/dev/FindCUDA-remove.rst new file mode 100644 index 0000000000..e8b09d4759 --- /dev/null +++ b/Help/release/dev/FindCUDA-remove.rst @@ -0,0 +1,6 @@ +FindCUDA-remove +--------------- + +* The :module:`FindCUDA` module has been fully deprecated via policy + :policy:`CMP0146`. Port projects to CMake's first-class ``CUDA`` + language support. diff --git a/Help/release/dev/FindCUDAToolkit-target-for-cudla.rst b/Help/release/dev/FindCUDAToolkit-target-for-cudla.rst new file mode 100644 index 0000000000..9de456ec90 --- /dev/null +++ b/Help/release/dev/FindCUDAToolkit-target-for-cudla.rst @@ -0,0 +1,4 @@ +FindCUDAToolkit-target-for-cudla +-------------------------------- + +* The :module:`FindCUDAToolkit` module now provides an imported target for ``cudla``, if found. diff --git a/Help/release/dev/FindOpenGL-gles.rst b/Help/release/dev/FindOpenGL-gles.rst new file mode 100644 index 0000000000..fcbc5167a1 --- /dev/null +++ b/Help/release/dev/FindOpenGL-gles.rst @@ -0,0 +1,5 @@ +FindOpenGL-gles +--------------- + +* The :module:`FindOpenGL` module gained support for components + ``GLES2`` and ``GLES3``. diff --git a/Help/release/dev/FindPython-Windows-ARM.rst b/Help/release/dev/FindPython-Windows-ARM.rst new file mode 100644 index 0000000000..d88a65acb0 --- /dev/null +++ b/Help/release/dev/FindPython-Windows-ARM.rst @@ -0,0 +1,5 @@ +FindPython-Windows-ARM +---------------------- + +* :module:`FindPython`, :module:`FindPython2` and :module:`FindPython3` modules + learn to manage ``Windows/ARM`` platform. diff --git a/Help/release/dev/FindwxWidgets-imported-target.rst b/Help/release/dev/FindwxWidgets-imported-target.rst new file mode 100644 index 0000000000..c04e0acf58 --- /dev/null +++ b/Help/release/dev/FindwxWidgets-imported-target.rst @@ -0,0 +1,4 @@ +FindwxWidgets-imported-target +----------------------------- + +* The :module:`FindwxWidgets` module now provides an imported target. diff --git a/Help/release/dev/PATH-genex-support-list.rst b/Help/release/dev/PATH-genex-support-list.rst new file mode 100644 index 0000000000..ce87fddd43 --- /dev/null +++ b/Help/release/dev/PATH-genex-support-list.rst @@ -0,0 +1,5 @@ +PATH-genex-supports-list +------------------------ + +* The :genex:`$<PATH>` generator expression learned to process list of paths + for decomposition and transformation operations. diff --git a/Help/release/dev/autogen-exe-vars.rst b/Help/release/dev/autogen-exe-vars.rst new file mode 100644 index 0000000000..a386b4f231 --- /dev/null +++ b/Help/release/dev/autogen-exe-vars.rst @@ -0,0 +1,7 @@ +autogen-exe-vars +---------------- + +* The :variable:`CMAKE_AUTOMOC_EXECUTABLE`, + :variable:`CMAKE_AUTORCC_EXECUTABLE`, and + :variable:`CMAKE_AUTOUIC_EXECUTABLE` variables were added to initialize the + corresponding target properties as targets are created. diff --git a/Help/release/dev/automoc-macro-names.rst b/Help/release/dev/automoc-macro-names.rst new file mode 100644 index 0000000000..9c037b3472 --- /dev/null +++ b/Help/release/dev/automoc-macro-names.rst @@ -0,0 +1,5 @@ +automoc-macro-names +------------------- + +* The :prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES` target property was added to + specify macro names for ``moc`` as a transitive usage requirement. diff --git a/Help/release/dev/cuda-support-new-compile-modes.rst b/Help/release/dev/cuda-support-new-compile-modes.rst new file mode 100644 index 0000000000..2d24c167a4 --- /dev/null +++ b/Help/release/dev/cuda-support-new-compile-modes.rst @@ -0,0 +1,14 @@ +cuda-support-new-compile-modes +------------------------------ + +* A :prop_tgt:`CUDA_CUBIN_COMPILATION` target property was added to + :ref:`Object Libraries` to support compiling to ``.cubin`` files + instead of host object files. Currently only supported with NVIDIA. + +* A :prop_tgt:`CUDA_FATBIN_COMPILATION` target property was added to + :ref:`Object Libraries` to support compiling to ``.fatbin`` files + instead of host object files. Currently only supported with NVIDIA. + +* A :prop_tgt:`CUDA_OPTIX_COMPILATION` target property was added to + :ref:`Object Libraries` to support compiling to ``.optixir`` files + instead of host object files. Currently only supported with NVIDIA. diff --git a/Help/release/dev/cxx-module-extensions.rst b/Help/release/dev/cxx-module-extensions.rst new file mode 100644 index 0000000000..92df86a51e --- /dev/null +++ b/Help/release/dev/cxx-module-extensions.rst @@ -0,0 +1,5 @@ +cxx-module-extensions +--------------------- + +* Source file extensions ``.ccm``, ``.cxxm``, or ``.c++m`` are now + treated as C++. diff --git a/Help/release/dev/deprecate-extra-generators.rst b/Help/release/dev/deprecate-extra-generators.rst new file mode 100644 index 0000000000..ceb2f4e1a8 --- /dev/null +++ b/Help/release/dev/deprecate-extra-generators.rst @@ -0,0 +1,5 @@ +deprecate-extra-generators +-------------------------- + +* The :ref:`Extra Generators` have been deprecated. IDEs may use the + :manual:`cmake-file-api(7)` to view CMake-generated project build trees. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000000..9c388665aa --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,7 @@ +deprecate-policy-old +-------------------- + +* Compatibility with versions of CMake older than 3.5 is now deprecated + and will be removed from a future version. Calls to + :command:`cmake_minimum_required` or :command:`cmake_policy` that set + the policy version to an older value now issue a deprecation diagnostic. diff --git a/Help/release/dev/dll-name-soversion.rst b/Help/release/dev/dll-name-soversion.rst new file mode 100644 index 0000000000..56d0842d82 --- /dev/null +++ b/Help/release/dev/dll-name-soversion.rst @@ -0,0 +1,7 @@ +dll-name-soversion +------------------ + +* The :variable:`CMAKE_DLL_NAME_WITH_SOVERSION` variable and associated + :prop_tgt:`DLL_NAME_WITH_SOVERSION` target property were added to + optionally append the :prop_tgt:`SOVERSION` to the filename of the + ``.dll`` part of a shared library on Windows. diff --git a/Help/release/dev/file-GET_RUNTIME_DEPENDENCIES-windows-casing.rst b/Help/release/dev/file-GET_RUNTIME_DEPENDENCIES-windows-casing.rst new file mode 100644 index 0000000000..858f8b3a99 --- /dev/null +++ b/Help/release/dev/file-GET_RUNTIME_DEPENDENCIES-windows-casing.rst @@ -0,0 +1,7 @@ +file-GET_RUNTIME_DEPENDENCIES-windows-casing +-------------------------------------------- + + +* The :command:`file(GET_RUNTIME_DEPENDENCIES)` command now case-preserves + DLL names reported on Windows. They are still converted to lowercase + for filter matching. diff --git a/Help/release/dev/find_package-PACKAGENAME_ROOT.rst b/Help/release/dev/find_package-PACKAGENAME_ROOT.rst new file mode 100644 index 0000000000..03882717fa --- /dev/null +++ b/Help/release/dev/find_package-PACKAGENAME_ROOT.rst @@ -0,0 +1,7 @@ +find_package-PACKAGENAME_ROOT +----------------------------- + +* The :command:`find_package` command now searches prefixes specified by + upper-case :variable:`<PACKAGENAME>_ROOT` CMake variables and upper-case + :envvar:`<PACKAGENAME>_ROOT` environment variables. + See policy :policy:`CMP0144`. diff --git a/Help/release/dev/install-prefix-genex-install-code-script.rst b/Help/release/dev/install-prefix-genex-install-code-script.rst new file mode 100644 index 0000000000..810f4483c1 --- /dev/null +++ b/Help/release/dev/install-prefix-genex-install-code-script.rst @@ -0,0 +1,5 @@ +install-prefix-genex-install-code-script +---------------------------------------- + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + now support the :genex:`$<INSTALL_PREFIX>` generator expression. diff --git a/Help/release/dev/lang-linker-launcher-genex.rst b/Help/release/dev/lang-linker-launcher-genex.rst new file mode 100644 index 0000000000..b6494eb104 --- /dev/null +++ b/Help/release/dev/lang-linker-launcher-genex.rst @@ -0,0 +1,5 @@ +lang-linker-launcher-genex +-------------------------- + +* The :prop_tgt:`<LANG>_LINKER_LAUNCHER` target property now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/lint-genex.rst b/Help/release/dev/lint-genex.rst new file mode 100644 index 0000000000..8da30b0333 --- /dev/null +++ b/Help/release/dev/lint-genex.rst @@ -0,0 +1,7 @@ +lint-genex +---------- + +* The :prop_tgt:`<LANG>_CLANG_TIDY`, :prop_tgt:`<LANG>_CPPCHECK`, + :prop_tgt:`<LANG>_CPPLINT`, and :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE`, + target properties now support + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/ninja-custom-command-depends.rst b/Help/release/dev/ninja-custom-command-depends.rst new file mode 100644 index 0000000000..0b7840c940 --- /dev/null +++ b/Help/release/dev/ninja-custom-command-depends.rst @@ -0,0 +1,11 @@ +ninja-custom-command-depends +---------------------------- + +* The :command:`add_custom_command` command gained a new + ``DEPENDS_EXPLICIT_ONLY`` option to tell the :ref:`Ninja Generators` + not to add any dependencies implied by the target to which it is + attached. + +* The :variable:`CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` variable can + be set to enable ``DEPENDS_EXPLICIT_ONLY`` in all uses of + :command:`add_custom_command` command. diff --git a/Help/release/dev/remove-FindPythonInterp-FindPythonLibs.rst b/Help/release/dev/remove-FindPythonInterp-FindPythonLibs.rst new file mode 100644 index 0000000000..426febb50c --- /dev/null +++ b/Help/release/dev/remove-FindPythonInterp-FindPythonLibs.rst @@ -0,0 +1,6 @@ +remove-FindPythonInterp-FindPythonLibs +-------------------------------------- + +* The :module:`FindPythonInterp` and :module:`FindPythonLibs` modules have + been fully deprecated via policy :policy:`CMP0148`. Port projects to + :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython`. diff --git a/Help/release/dev/remove-dart-modules.rst b/Help/release/dev/remove-dart-modules.rst new file mode 100644 index 0000000000..5da2edaeee --- /dev/null +++ b/Help/release/dev/remove-dart-modules.rst @@ -0,0 +1,5 @@ +remove-dart-modules +------------------- + +* The :module:`Dart` and :module:`FindDart` modules have been deprecated via + policy :policy:`CMP0145`. Port projects to the :module:`CTest` module. diff --git a/Help/release/dev/vs-BuildInParallel.rst b/Help/release/dev/vs-BuildInParallel.rst new file mode 100644 index 0000000000..ef344c7135 --- /dev/null +++ b/Help/release/dev/vs-BuildInParallel.rst @@ -0,0 +1,5 @@ +vs-BuildInParallel +------------------ + +* :ref:`Visual Studio Generators`, for VS 15.8 (2017) and newer, now + build custom commands in parallel. See policy :policy:`CMP0147`. diff --git a/Help/release/dev/vs-sdk-selection.rst b/Help/release/dev/vs-sdk-selection.rst new file mode 100644 index 0000000000..856a2033c5 --- /dev/null +++ b/Help/release/dev/vs-sdk-selection.rst @@ -0,0 +1,7 @@ +vs-sdk-selection +---------------- + +* The :ref:`Visual Studio Generators` for VS 2015 and above learned to + select the Windows SDK version explicitly using a ``version=`` field + in the :variable:`CMAKE_GENERATOR_PLATFORM` variable. + See :ref:`Visual Studio Platform Selection`. diff --git a/Help/release/dev/vs-windows-min-version.rst b/Help/release/dev/vs-windows-min-version.rst new file mode 100644 index 0000000000..cb39159441 --- /dev/null +++ b/Help/release/dev/vs-windows-min-version.rst @@ -0,0 +1,6 @@ +vs-windows-min-version +---------------------- + +* The :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` variable + was added to initialize the :prop_tgt:`VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` + target property on all targets when they are created. diff --git a/Help/release/dev/vs9-deprecate.rst b/Help/release/dev/vs9-deprecate.rst new file mode 100644 index 0000000000..46568f8bc5 --- /dev/null +++ b/Help/release/dev/vs9-deprecate.rst @@ -0,0 +1,5 @@ +vs9-deprecate +------------- + +* The :generator:`Visual Studio 9 2008` generator is now deprecated + and will be removed in a future version of CMake. diff --git a/Help/release/index.rst b/Help/release/index.rst index c82889f3a0..d434a3ab05 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst b/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst new file mode 100644 index 0000000000..9c9bd2c225 --- /dev/null +++ b/Help/variable/CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY.rst @@ -0,0 +1,11 @@ +CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY +---------------------------------------------- + +.. versionadded:: 3.27 + +Whether to enable DEPENDS_EXPLICIT_ONLY option by default in +:command:`add_custom_command`. + +This variable affects the default behavior of the :command:`add_custom_command` +command. Setting this variable to ``ON`` is equivalent to using the ``DEPENDS_EXPLICIT_ONLY`` +option in all uses of that command. diff --git a/Help/variable/CMAKE_AUTOMOC_EXECUTABLE.rst b/Help/variable/CMAKE_AUTOMOC_EXECUTABLE.rst new file mode 100644 index 0000000000..150a73ab41 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_EXECUTABLE.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOMOC_EXECUTABLE +------------------------ + +.. versionadded:: 3.27 + +This variable is used to initialize the :prop_tgt:`AUTOMOC_EXECUTABLE` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_AUTORCC_EXECUTABLE.rst b/Help/variable/CMAKE_AUTORCC_EXECUTABLE.rst new file mode 100644 index 0000000000..52d7faa873 --- /dev/null +++ b/Help/variable/CMAKE_AUTORCC_EXECUTABLE.rst @@ -0,0 +1,10 @@ +CMAKE_AUTORCC_EXECUTABLE +------------------------ + +.. versionadded:: 3.27 + +This variable is used to initialize the :prop_tgt:`AUTORCC_EXECUTABLE` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_AUTOUIC_EXECUTABLE.rst b/Help/variable/CMAKE_AUTOUIC_EXECUTABLE.rst new file mode 100644 index 0000000000..b2ebd7fb39 --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_EXECUTABLE.rst @@ -0,0 +1,10 @@ +CMAKE_AUTOUIC_EXECUTABLE +------------------------ + +.. versionadded:: 3.27 + +This variable is used to initialize the :prop_tgt:`AUTOUIC_EXECUTABLE` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst index 7e6ec3371f..16dbfa59c5 100644 --- a/Help/variable/CMAKE_CROSSCOMPILING.rst +++ b/Help/variable/CMAKE_CROSSCOMPILING.rst @@ -1,15 +1,15 @@ CMAKE_CROSSCOMPILING -------------------- -Intended to indicate whether CMake is cross compiling, but note limitations -discussed below. +This variable is set by CMake to indicate whether it is cross compiling, +but note limitations discussed below. This variable will be set to true by CMake if the :variable:`CMAKE_SYSTEM_NAME` variable has been set manually (i.e. in a toolchain file or as a cache entry from the :manual:`cmake <cmake(1)>` command line). In most cases, manually -setting :variable:`CMAKE_SYSTEM_NAME` will only be done when cross compiling, -since it will otherwise be given the same value as -:variable:`CMAKE_HOST_SYSTEM_NAME` if not manually set, which is correct for +setting :variable:`CMAKE_SYSTEM_NAME` will only be done when cross compiling +since, if not manually set, it will be given the same value as +:variable:`CMAKE_HOST_SYSTEM_NAME`, which is correct for the non-cross-compiling case. In the event that :variable:`CMAKE_SYSTEM_NAME` is manually set to the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`, then ``CMAKE_CROSSCOMPILING`` will still be set to true. diff --git a/Help/variable/CMAKE_DLL_NAME_WITH_SOVERSION.rst b/Help/variable/CMAKE_DLL_NAME_WITH_SOVERSION.rst new file mode 100644 index 0000000000..5fa49dede4 --- /dev/null +++ b/Help/variable/CMAKE_DLL_NAME_WITH_SOVERSION.rst @@ -0,0 +1,14 @@ +CMAKE_DLL_NAME_WITH_SOVERSION +----------------------------- + +.. versionadded:: 3.27 + +This variable is used to initialize the :prop_tgt:`DLL_NAME_WITH_SOVERSION` +property on shared library targets for the Windows platform, which is selected +when the :variable:`WIN32` variable is set. + +See this target property for additional information. + +Please note that setting this variable has no effect if versioned filenames +are globally disabled with the :variable:`CMAKE_PLATFORM_NO_VERSIONED_SONAME` +variable. diff --git a/Help/variable/CMAKE_EDIT_COMMAND.rst b/Help/variable/CMAKE_EDIT_COMMAND.rst index 2f4ab1f62a..b21434f7ff 100644 --- a/Help/variable/CMAKE_EDIT_COMMAND.rst +++ b/Help/variable/CMAKE_EDIT_COMMAND.rst @@ -2,7 +2,8 @@ CMAKE_EDIT_COMMAND ------------------ Full path to :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. Defined only for -:ref:`Makefile Generators` when not using an "extra" generator for an IDE. +:ref:`Makefile Generators` and :ref:`Ninja Generators` when not using any +:ref:`Extra Generators`. This is the full path to the CMake executable that can graphically edit the cache. For example, :manual:`cmake-gui(1)` or :manual:`ccmake(1)`. diff --git a/Help/variable/CMAKE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_ENABLE_EXPORTS.rst index 9f43de3fac..d2c5ed086e 100644 --- a/Help/variable/CMAKE_ENABLE_EXPORTS.rst +++ b/Help/variable/CMAKE_ENABLE_EXPORTS.rst @@ -8,3 +8,7 @@ Specify whether executables export symbols for loadable modules. This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target property for executable targets when they are created by calls to the :command:`add_executable` command. See the property documentation for details. + +This command has been superseded by the +:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` command. It is provided for +compatibility with older CMake code. diff --git a/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst new file mode 100644 index 0000000000..aa6dda2219 --- /dev/null +++ b/Help/variable/CMAKE_EXECUTABLE_ENABLE_EXPORTS.rst @@ -0,0 +1,12 @@ +CMAKE_EXECUTABLE_ENABLE_EXPORTS +------------------------------- + +.. versionadded:: 3.27 + +Specify whether executables export symbols for loadable modules. + +This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target +property for executable targets when they are created by calls to the +:command:`add_executable` command. See the property documentation for details. + +This variable supersede the :variable:`CMAKE_ENABLE_EXPORTS` variable. diff --git a/Help/variable/CMAKE_EXTRA_GENERATOR.rst b/Help/variable/CMAKE_EXTRA_GENERATOR.rst index 2c9232345f..0a113a5ae6 100644 --- a/Help/variable/CMAKE_EXTRA_GENERATOR.rst +++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst @@ -1,6 +1,12 @@ CMAKE_EXTRA_GENERATOR --------------------- +.. deprecated:: 3.27 + + Support for :ref:`Extra Generators` is deprecated and will be removed from + a future version of CMake. IDEs may use the :manual:`cmake-file-api(7)` + to view CMake-generated project build trees. + The extra generator used to build the project. See :manual:`cmake-generators(7)`. diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst index acb7b2e1a2..416ff60f34 100644 --- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -26,8 +26,46 @@ Platform specification is supported only on specific generators: See native build system documentation for allowed platform names. +.. _`Visual Studio Platform Selection`: + Visual Studio Platform Selection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -On :ref:`Visual Studio Generators` the selected platform name -is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable. +The :ref:`Visual Studio Generators` support platform specification +using one of these forms: + +* ``platform`` +* ``platform[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``platform`` specifies the target platform (VS target architecture), +such as ``x64``, ``ARM64``, or ``Win32``. The selected platform +name is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable. + +The ``key=value`` pairs form a comma-separated list of options to +specify generator-specific details of the platform selection. +Supported pairs are: + +``version=<version>`` + .. versionadded:: 3.27 + + Specify the Windows SDK version to use. This is supported by VS 2015 and + above when targeting Windows 10.0+ or Windows Store. CMake will set the + :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` variable to the + selected SDK version. + + The ``<version>`` may be one of: + + ``10.0`` + Specify that any 10.0 SDK version may be used, and let Visual Studio + pick one. This is supported by VS 2019 and above. + + ``10.0.<build>.<increment>`` + Specify the exact 4-component SDK version, e.g., ``10.0.19041.0``. + The specified version of the SDK must be installed. It may not exceed + the value of :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM`, + if that variable is set. + + If the ``version`` field is not specified, CMake selects a version as + described in the :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION` + variable documentation. diff --git a/Help/variable/CMAKE_KATE_FILES_MODE.rst b/Help/variable/CMAKE_KATE_FILES_MODE.rst new file mode 100644 index 0000000000..195c15d3ce --- /dev/null +++ b/Help/variable/CMAKE_KATE_FILES_MODE.rst @@ -0,0 +1,20 @@ +CMAKE_KATE_FILES_MODE +--------------------- + +.. versionadded:: 3.27 + +This cache variable is used by the Kate project generator and controls +to what mode the ``files`` entry in the project file will be set. See +:manual:`cmake-generators(7)`. + +Possible values are ``AUTO``, ``SVN``, ``GIT``, ``HG``, ``FOSSIL`` and ``LIST``. + +When set to ``LIST``, CMake will put the list of source files known to CMake +in the project file. +When set to ``SVN``, ``GIT``, ``HG`` or ``FOSSIL``, CMake will set +the generated project accordingly to Subversion, git, Mercurial +or Fossil, and Kate will then use the respective command line tool to +retrieve the list of files in the project. +When unset or set to ``AUTO``, CMake will try to detect whether the +source directory is part of a git or svn checkout or not, and put the +respective entry into the project file. diff --git a/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst b/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst new file mode 100644 index 0000000000..c830332557 --- /dev/null +++ b/Help/variable/CMAKE_KATE_MAKE_ARGUMENTS.rst @@ -0,0 +1,11 @@ +CMAKE_KATE_MAKE_ARGUMENTS +------------------------- + +.. versionadded:: 3.0 + +This cache variable is used by the Kate project generator. See +:manual:`cmake-generators(7)`. + +This variable holds arguments which are used when Kate invokes the make +tool. By default it is initialized to hold flags to enable parallel builds +(using -j typically). diff --git a/Help/variable/CMAKE_LANG_FLAGS.rst b/Help/variable/CMAKE_LANG_FLAGS.rst index 4b39b1deff..909a001a9c 100644 --- a/Help/variable/CMAKE_LANG_FLAGS.rst +++ b/Help/variable/CMAKE_LANG_FLAGS.rst @@ -1,9 +1,10 @@ CMAKE_<LANG>_FLAGS ------------------ -Flags for all build types. - -``<LANG>`` flags used regardless of the value of :variable:`CMAKE_BUILD_TYPE`. +Language-wide flags for language ``<LANG>`` used when building for +all configurations. These flags will be passed to all invocations +of the compiler. This includes invocations that drive compiling +and those that drive linking. For each language, if this variable is not defined, it is initialized and stored in the cache using values from environment variables in @@ -27,7 +28,10 @@ combination with CMake's builtin defaults for the toolchain: This value is a command-line string fragment. Therefore, multiple options should be separated by spaces, and options with spaces should be quoted. -The flags in this variable will be passed to the compiler before those -in the per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variant, -and before flags added by the :command:`add_compile_options` or -:command:`target_compile_options` commands. +The flags in this variable will be passed before those in the +per-configuration :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variable. +On invocations driving compiling, flags from both variables will be passed +before flags added by commands such as :command:`add_compile_options` and +:command:`target_compile_options`. On invocations driving linking, +they will be passed before flags added by commands such as +:command:`add_link_options` and :command:`target_link_options`. diff --git a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst index f0900fdc8d..5daa4c06a1 100644 --- a/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst +++ b/Help/variable/CMAKE_LANG_FLAGS_CONFIG.rst @@ -1,9 +1,16 @@ CMAKE_<LANG>_FLAGS_<CONFIG> --------------------------- -Flags for language ``<LANG>`` when building for the ``<CONFIG>`` configuration. +Language-wide flags for language ``<LANG>`` used when building for +the ``<CONFIG>`` configuration. These flags will be passed to all +invocations of the compiler in the corresponding configuration. +This includes invocations that drive compiling and those that drive +linking. -The flags in this variable will be passed to the compiler after those -in the :variable:`CMAKE_<LANG>_FLAGS` variable, but before flags added -by the :command:`add_compile_options` or :command:`target_compile_options` -commands. +The flags in this variable will be passed after those in the +:variable:`CMAKE_<LANG>_FLAGS` variable. On invocations driving compiling, +flags from both variables will be passed before flags added by commands +such as :command:`add_compile_options` and :command:`target_compile_options`. +On invocations driving linking, they will be passed before flags added by +commands such as :command:`add_link_options` and +:command:`target_link_options`. diff --git a/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst index 59c60d3acc..b611967c86 100644 --- a/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst +++ b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst @@ -33,3 +33,5 @@ Calling any of the following commands increases the recursion depth: depth) * Reading or writing variables that are being watched by a :command:`variable_watch` + +See also the :envvar:`CMAKE_MAXIMUM_RECURSION_DEPTH` environment variable. diff --git a/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst index a8c40359a5..79a65b8c9d 100644 --- a/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst +++ b/Help/variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX.rst @@ -3,27 +3,38 @@ CMAKE_NINJA_OUTPUT_PATH_PREFIX .. versionadded:: 3.6 -Set output files path prefix for the :generator:`Ninja` generator. +Tell the :ref:`Ninja Generators` to add a prefix to every output path in +``build.ninja``. A trailing slash is appended to the prefix, if missing. -Every output files listed in the generated ``build.ninja`` will be -prefixed by the contents of this variable (a trailing slash is -appended if missing). This is useful when the generated ninja file is -meant to be embedded as a ``subninja`` file into a *super* ninja -project. For example, a ninja build file generated with a command -like:: +This is useful when the generated ninja file is meant to be embedded as a +``subninja`` file into a *super* ninja project. For example, the command: - cd top-build-dir/sub && - cmake -G Ninja -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ path/to/source +.. code-block:: shell -can be embedded in ``top-build-dir/build.ninja`` with a directive like -this:: + cd super-build-dir && + cmake -G Ninja -S /path/to/src -B sub -DCMAKE_NINJA_OUTPUT_PATH_PREFIX=sub/ + # ^^^---------- these match -----------^^^ + +generates a build directory with its top-level (:variable:`CMAKE_BINARY_DIR`) +in ``super-build-dir/sub``. The path to the build directory ends in the +output path prefix. This makes it suitable for use in a separately-written +``super-build-dir/build.ninja`` file with a directive like this:: subninja sub/build.ninja -The ``auto-regeneration`` rule in ``top-build-dir/build.ninja`` must have an -order-only dependency on ``sub/build.ninja``. +The ``auto-regeneration`` rule in ``super-build-dir/build.ninja`` must +have an order-only dependency on ``sub/build.ninja``. + +.. versionadded:: 3.27 + + The :generator:`Ninja Multi-Config` generator supports this variable. .. note:: When ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` is set, the project generated by CMake cannot be used as a standalone project. No default targets are specified. + + The value of ``CMAKE_NINJA_OUTPUT_PATH_PREFIX`` must match one or more + path components at the *end* of :variable:`CMAKE_BINARY_DIR`, or the + behavior is undefined. However, this requirement is not checked + automatically. diff --git a/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst b/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst new file mode 100644 index 0000000000..3e2c6df8f7 --- /dev/null +++ b/Help/variable/CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS.rst @@ -0,0 +1,10 @@ +CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS +----------------------------------- + +.. versionadded:: 3.27 + +Specify whether shared library generates an import file. + +This variable is used to initialize the :prop_tgt:`ENABLE_EXPORTS` target +property for shared library targets when they are created by calls to the +:command:`add_library` command. See the property documentation for details. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst new file mode 100644 index 0000000000..8ef54cdb0f --- /dev/null +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION.rst @@ -0,0 +1,12 @@ +CMAKE_VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION +-------------------------------------------- + +.. versionadded:: 3.27 + +Tell :ref:`Visual Studio Generators` to use the given +Windows Target Platform Minimum Version. + +This variable is used to initialize the +:prop_tgt:`VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION` property on all +targets when they are created. See that target property for +additional information. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst index eb7104998a..2c14d3900d 100644 --- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION.rst @@ -5,11 +5,30 @@ CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION Visual Studio Windows Target Platform Version. -When targeting Windows 10 and above Visual Studio 2015 and above support -specification of a target Windows version to select a corresponding SDK. -The :variable:`CMAKE_SYSTEM_VERSION` variable may be set to specify a -version. Otherwise CMake computes a default version based on the Windows -SDK versions available. The chosen Windows target version number is provided +When targeting Windows 10 and above, :ref:`Visual Studio Generators` for +VS 2015 and above support specification of a Windows SDK version: + +* If :variable:`CMAKE_GENERATOR_PLATFORM` specifies a ``version=`` field, + as documented by :ref:`Visual Studio Platform Selection`, that SDK + version is selected. + +* Otherwise, if the ``WindowsSDKVersion`` environment variable + is set to an available SDK version, that version is selected. + This is intended for use in environments established by ``vcvarsall.bat`` + or similar scripts. + + .. versionadded:: 3.27 + This is enabled by policy :policy:`CMP0149`. + +* Otherwise, if :variable:`CMAKE_SYSTEM_VERSION` is set to an available + SDK version, that version is selected. + + .. versionchanged:: 3.27 + This is disabled by policy :policy:`CMP0149`. + +* Otherwise, CMake uses the latest Windows SDK version available. + +The chosen Windows target version number is provided in ``CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION``. If no Windows 10 SDK is available this value will be empty. diff --git a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst index f1a1977448..727ccc95be 100644 --- a/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst +++ b/Help/variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM.rst @@ -10,5 +10,5 @@ be set to a false value (e.g. ``OFF``, ``FALSE``, or ``0``) or the SDK version to use as the maximum (e.g. ``10.0.14393.0``). If unset, the default depends on which version of Visual Studio is targeted by the current generator. -This can be used in conjunction with :variable:`CMAKE_SYSTEM_VERSION`, which -CMake uses to select :variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`. +This can be used to exclude Windows SDK versions from consideration for +:variable:`CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION`. diff --git a/Help/variable/PackageName_ROOT.rst b/Help/variable/PackageName_ROOT.rst index 6b17be3bad..8b728ba175 100644 --- a/Help/variable/PackageName_ROOT.rst +++ b/Help/variable/PackageName_ROOT.rst @@ -14,3 +14,11 @@ This variable may hold a single prefix or a :ref:`semicolon-separated list <CMake Language Lists>` of multiple prefixes. See also the :envvar:`<PackageName>_ROOT` environment variable. + +.. variable:: <PACKAGENAME>_ROOT + + .. versionadded:: 3.27 + + Calls to :command:`find_package(<PackageName>)` will also search in + prefixes specified by the upper-case ``<PACKAGENAME>_ROOT`` CMake + variable. See policy :policy:`CMP0144`. |