diff options
Diffstat (limited to 'Help')
23 files changed, 291 insertions, 23 deletions
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index fcdcfd4..43805c3 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -7,15 +7,12 @@ Add options to the compilation of source files. add_compile_options(<option> ...) -Adds options to the compiler command line for targets in the current -directory and below that are added after this command is invoked. -See documentation of the :prop_dir:`directory <COMPILE_OPTIONS>` and -:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. +Adds options to the :prop_dir:`COMPILE_OPTIONS` directory property. +These options are used when compiling targets from the current +directory and below. -This command can be used to add any options, but alternative commands -exist to add preprocessor definitions (:command:`target_compile_definitions` -and :command:`add_compile_definitions`) or include directories -(:command:`target_include_directories` and :command:`include_directories`). +Arguments +^^^^^^^^^ Arguments to ``add_compile_options`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` @@ -23,3 +20,29 @@ manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. .. include:: OPTIONS_SHELL.txt + +Example +^^^^^^^ + +Since different compilers support different options, a typical use of +this command is in a compiler-specific conditional clause: + +.. code-block:: cmake + + if (MSVC) + # warning level 4 and all warnings as errors + add_compile_options(/W4 /WX) + else() + # lots of warnings and all warnings as errors + add_compile_options(-Wall -Wextra -pedantic -Werror) + endif() + +See Also +^^^^^^^^ + +This command can be used to add any options. However, for +adding preprocessor definitions and include directories it is recommended +to use the more specific commands :command:`add_compile_definitions` +and :command:`include_directories`. + +The command :command:`target_compile_options` adds target-specific options. diff --git a/Help/command/install.rst b/Help/command/install.rst index 55c8485..a0e8c37 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -547,6 +547,11 @@ example, the code will print a message during installation. +``<file>`` or ``<code>`` may use "generator expressions" with the syntax +``$<...>`` (in the case of ``<file>``, this refers to their use in the file +name, not the file's contents). See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + Installing Exports ^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index c26c926..47e7d86 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -9,22 +9,18 @@ Add compile options to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specifies compile options to use when compiling a given target. The -named ``<target>`` 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>`. +Adds options to the :prop_tgt:`COMPILE_OPTIONS` or +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties. These options +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>`. + +Arguments +^^^^^^^^^ If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. -This command can be used to add any options, but -alternative commands exist to add preprocessor definitions -(:command:`target_compile_definitions` and :command:`add_compile_definitions`) -or include directories (:command:`target_include_directories` and -:command:`include_directories`). See documentation of the -:prop_dir:`directory <COMPILE_OPTIONS>` and -:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. - The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS` property of @@ -40,3 +36,13 @@ manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. .. include:: OPTIONS_SHELL.txt + +See Also +^^^^^^^^ + +This command can be used to add any options. However, for adding +preprocessor definitions and include directories it is recommended +to use the more specific commands :command:`target_compile_definitions` +and :command:`target_include_directories`. + +For directory-wide settings, there is the command :command:`add_compile_options`. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index f50fcb6..cf9e06f 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -134,6 +134,11 @@ default values: If :policy:`CMP0056` is set to ``NEW``, then :variable:`CMAKE_EXE_LINKER_FLAGS` is passed in as well. +If :policy:`CMP0083` is set to ``NEW``, then in order to obtain correct +behavior at link time, the ``check_pie_supported()`` command from the +:module:`CheckPIESupported` module must be called before using the +:command:`try_compile` command. + The current settings of :policy:`CMP0065` and :policy:`CMP0083` are set in the generated project. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 2f08a04..940186a 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -35,6 +35,7 @@ These modules are loaded using the :command:`include` command. /module/CheckIncludeFiles /module/CheckLanguage /module/CheckLibraryExists + /module/CheckPIESupported /module/CheckPrototypeDefinition /module/CheckStructHasMember /module/CheckSymbolExists diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index ed61ae0..40ec1ef 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -57,6 +57,7 @@ Policies Introduced by CMake 3.14 .. toctree:: :maxdepth: 1 + CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087> CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086> CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085> CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084> diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 047859d..df8f12c 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -129,13 +129,16 @@ Properties on Targets /prop_tgt/AUTOGEN_TARGET_DEPENDS /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_EXECUTABLE /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC + /prop_tgt/AUTOUIC_EXECUTABLE /prop_tgt/AUTOUIC_OPTIONS /prop_tgt/AUTOUIC_SEARCH_PATHS /prop_tgt/AUTORCC + /prop_tgt/AUTORCC_EXECUTABLE /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 1ef20ab..8490e3d 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -109,13 +109,23 @@ Options This option tells CTest to write all its output to a log file. -``-N,--show-only`` +``-N,--show-only[=<format>]`` Disable actual execution of tests. This option tells CTest to list the tests that would be run but not actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. + ``<format>`` can be one of the following values. + + ``human`` + Human-friendly output. This is not guaranteed to be stable. + This is the default. + + ``json-v1`` + Dump the test information in JSON format. + See `Show as JSON Object Model`_. + ``-L <regex>, --label-regex <regex>`` Run tests with labels matching regular expression. @@ -1163,6 +1173,65 @@ Configuration settings include: * :module:`CTest` module variable: ``TRIGGER_SITE`` if set, else ``CTEST_TRIGGER_SITE`` +.. _`Show as JSON Object Model`: + +Show as JSON Object Model +========================= + +When the ``--show-only=json-v1`` command line option is given, the test +information is output in JSON format. Version 1.0 of the JSON object +model is defined as follows: + +``kind`` + The string "ctestInfo". + +``version`` + A JSON object specifying the version components. Its members are + + ``major`` + A non-negative integer specifying the major version component. + ``minor`` + A non-negative integer specifying the minor version component. + +``backtraceGraph`` + JSON object representing backtrace information with the + following members: + + ``commands`` + List of command names. + ``files`` + List of file names. + ``nodes`` + List of node JSON objects with members: + + ``command`` + Index into the ``commands`` member of the ``backtraceGraph``. + ``file`` + Index into the ``files`` member of the ``backtraceGraph``. + ``line`` + Line number in the file where the backtrace was added. + ``parent`` + Index into the ``nodes`` member of the ``backtraceGraph`` + representing the parent in the graph. + +``tests`` + A JSON array listing information about each test. Each entry + is a JSON object with members: + + ``name`` + Test name. + ``config`` + Configuration that the test can run on. + Empty string means any config. + ``command`` + List where the first element is the test command and the + remaining elements are the command arguments. + ``backtrace`` + Index into the ``nodes`` member of the ``backtraceGraph``. + ``properties`` + Test properties. + Can contain keys for each of the supported test properties. + See Also ======== diff --git a/Help/module/CheckPIESupported.rst b/Help/module/CheckPIESupported.rst new file mode 100644 index 0000000..02e7b43 --- /dev/null +++ b/Help/module/CheckPIESupported.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckPIESupported.cmake diff --git a/Help/policy/CMP0083.rst b/Help/policy/CMP0083.rst index 7b467b0..b26d6c8 100644 --- a/Help/policy/CMP0083.rst +++ b/Help/policy/CMP0083.rst @@ -17,8 +17,46 @@ is set: passed to the linker step. For example ``-no-pie`` for ``GCC``. * Not set: no flags are passed to the linker step. +Since a given linker may not support ``PIE`` flags in all environments in +which it is used, it is the project's responsibility to use the +:module:`CheckPIESupported` module to check for support to ensure that the +:prop_tgt:`POSITION_INDEPENDENT_CODE` target property for executables will be +honored at link time. + This policy was introduced in CMake version 3.14. 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 + +Examples +^^^^^^^^ + +Behave like CMake 3.13 and do not apply any ``PIE`` flags at link stage. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.13) + project(foo) + + # ... + + add_executable(foo ...) + set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) + +Use the :module:`CheckPIESupported` module to detect whether ``PIE`` is +supported by the current linker and environment. Apply ``PIE`` flags only +if the linker supports them. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.14) # CMP0083 NEW + project(foo) + + include(CheckPIESupported) + check_pie_supported() + + # ... + + add_executable(foo ...) + set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE) diff --git a/Help/policy/CMP0087.rst b/Help/policy/CMP0087.rst new file mode 100644 index 0000000..4c45b99 --- /dev/null +++ b/Help/policy/CMP0087.rst @@ -0,0 +1,29 @@ +CMP0087 +------- + +:command:`install(CODE)` and :command:`install(SCRIPT)` support generator +expressions. + +In CMake 3.13 and earlier, :command:`install(CODE)` and +:command:`install(SCRIPT)` did not evaluate generator expressions. CMake 3.14 +and later will evaluate generator expressions for :command:`install(CODE)` and +:command:`install(SCRIPT)`. + +The ``OLD`` behavior of this policy is for :command:`install(CODE)` and +:command:`install(SCRIPT)` to not evaluate generator expressions. The ``NEW`` +behavior is to evaluate generator expressions for :command:`install(CODE)` and +:command:`install(SCRIPT)`. + +Note that it is the value of this policy setting at the end of the directory +scope that is important, not its setting at the time of the call to +:command:`install(CODE)` or :command:`install(SCRIPT)`. This has implications +for calling these commands from places that have their own policy scope but not +their own directory scope (e.g. from files brought in via :command:`include()` +rather than :command:`add_subdirectory()`). + +This policy was introduced in CMake version 3.14. 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/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 7a3fd48..3e6d560 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -58,6 +58,9 @@ source files at build time and invoke moc accordingly. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. +The ``moc`` executable will be detected automatically, but can be forced to +a certain binary using the :prop_tgt:`AUTOMOC_EXECUTABLE` property. + Additional command line options for ``moc`` can be set via the :prop_tgt:`AUTOMOC_MOC_OPTIONS` property. diff --git a/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst b/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst new file mode 100644 index 0000000..6b66ce8 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_EXECUTABLE.rst @@ -0,0 +1,15 @@ +AUTOMOC_EXECUTABLE +------------------ + +:prop_tgt:`AUTOMOC_EXECUTABLE` is file path pointing to the ``moc`` +executable to use for :prop_tgt:`AUTOMOC` enabled files. Setting +this property will make CMake skip the automatic detection of the +``moc`` binary as well as the sanity-tests normally run to ensure +that the binary is available and working as expected. + +Usually this property does not need to be set. Only consider this +property if auto-detection of ``moc`` can not work -- e.g. because +you are building the ``moc`` binary as part of your project. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index 27fb149..5db6ed0 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -21,6 +21,9 @@ If the ``.qrc`` file is :prop_sf:`GENERATED` though, a Additional command line options for rcc can be set via the :prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file. +The ``rcc`` executable will be detected automatically, but can be forced to +a certain binary using the :prop_tgt:`AUTORCC_EXECUTABLE` property. + The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the autorcc targets together in an IDE, e.g. in MSVS. diff --git a/Help/prop_tgt/AUTORCC_EXECUTABLE.rst b/Help/prop_tgt/AUTORCC_EXECUTABLE.rst new file mode 100644 index 0000000..ca0fbd7 --- /dev/null +++ b/Help/prop_tgt/AUTORCC_EXECUTABLE.rst @@ -0,0 +1,15 @@ +AUTORCC_EXECUTABLE +------------------ + +:prop_tgt:`AUTORCC_EXECUTABLE` is file path pointing to the ``rcc`` +executable to use for :prop_tgt:`AUTORCC` enabled files. Setting +this property will make CMake skip the automatic detection of the +``rcc`` binary as well as the sanity-tests normally run to ensure +that the binary is available and working as expected. + +Usually this property does not need to be set. Only consider this +property if auto-detection of ``rcc`` can not work -- e.g. because +you are building the ``rcc`` binary as part of your project. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 4f58b35..85226c1 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -30,6 +30,9 @@ Additional command line options for ``uic`` can be set via the The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the autouic targets together in an IDE, e.g. in MSVS. +The ``uic`` executable will be detected automatically, but can be forced to +a certain binary using the :prop_tgt:`AUTOUIC_EXECUTABLE` property. + Source files can be excluded from :prop_tgt:`AUTOUIC` processing by enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. diff --git a/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst b/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst new file mode 100644 index 0000000..03bd554 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_EXECUTABLE.rst @@ -0,0 +1,15 @@ +AUTOUIC_EXECUTABLE +------------------ + +:prop_tgt:`AUTOUIC_EXECUTABLE` is file path pointing to the ``uic`` +executable to use for :prop_tgt:`AUTOUIC` enabled files. Setting +this property will make CMake skip the automatic detection of the +``uic`` binary as well as the sanity-tests normally run to ensure +that the binary is available and working as expected. + +Usually this property does not need to be set. Only consider this +property if auto-detection of ``uic`` can not work -- e.g. because +you are building the ``uic`` binary as part of your project. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst index 54af8c6..0aaf66b 100644 --- a/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst +++ b/Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst @@ -9,3 +9,8 @@ property is ``True`` by default for ``SHARED`` and ``MODULE`` library targets and ``False`` otherwise. This property is initialized by the value of the :variable:`CMAKE_POSITION_INDEPENDENT_CODE` variable if it is set when a target is created. + +.. note:: + + For executable targets, the link step is controlled by the :policy:`CMP0083` + policy and the :module:`CheckPIESupported` module. diff --git a/Help/release/dev/UseSWIG-source-file-ext.rst b/Help/release/dev/UseSWIG-source-file-ext.rst new file mode 100644 index 0000000..5d11dc6 --- /dev/null +++ b/Help/release/dev/UseSWIG-source-file-ext.rst @@ -0,0 +1,5 @@ +UseSWIG-source-file-ext +----------------------- + +* The :module:`UseSWIG` module gains capability to specify + ``SWIG`` source file extensions. diff --git a/Help/release/dev/autogen_executables.rst b/Help/release/dev/autogen_executables.rst new file mode 100644 index 0000000..5e967ea --- /dev/null +++ b/Help/release/dev/autogen_executables.rst @@ -0,0 +1,9 @@ +AUTO*_EXECUTABLE +---------------- + +* The :prop_tgt:`AUTOMOC_EXECUTABLE`, :prop_tgt:`AUTORCC_EXECUTABLE` and + :prop_tgt:`AUTOUIC_EXECUTABLE` target properties all take a path to an + executable and force automoc/autorcc/autouic to use this executable. + + Setting these will also prevent the configure time testing for these + executables. This is mainly useful when you build these tools yourself. diff --git a/Help/release/dev/ctest-show-only-json-v1.rst b/Help/release/dev/ctest-show-only-json-v1.rst new file mode 100644 index 0000000..f593e7e --- /dev/null +++ b/Help/release/dev/ctest-show-only-json-v1.rst @@ -0,0 +1,6 @@ +ctest-show-only-json-v1 +----------------------- + +* :manual:`ctest(1)` gained a ``--show-only=json-v1`` option to show the + list of tests in a machine-readable JSON format. + See the :ref:`Show as JSON Object Model` section of the manual. diff --git a/Help/release/dev/install-code-script-genex.rst b/Help/release/dev/install-code-script-genex.rst new file mode 100644 index 0000000..a28a466 --- /dev/null +++ b/Help/release/dev/install-code-script-genex.rst @@ -0,0 +1,5 @@ +install-code-script-genex +------------------------- + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + learned to support generator expressions. See policy :policy:`CMP0087`. diff --git a/Help/release/dev/link-option-PIE.rst b/Help/release/dev/link-option-PIE.rst index 824ab2c..872343c 100644 --- a/Help/release/dev/link-option-PIE.rst +++ b/Help/release/dev/link-option-PIE.rst @@ -2,5 +2,8 @@ link-option-PIE --------------- * Required link options to manage Position Independent Executable are now - added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. These flags are - controlled by policy :policy:`CMP0083`. + added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. The project is + responsible for using the :module:`CheckPIESupported` module to check for + ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` + target property will be honored at link time for executables. This behavior + is controlled by policy :policy:`CMP0083`. |