diff options
Diffstat (limited to 'Help')
25 files changed, 213 insertions, 25 deletions
diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index 6db9a485a8..f0704aca54 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,9 +5,9 @@ Starts the testing for a given model :: - ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET]) + ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET]) - ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET]) + ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET]) Starts the testing for a given model. The command should be called after the binary directory is initialized. @@ -26,20 +26,21 @@ The parameters are as follows: Set the binary directory. If not specified, the value of :variable:`CTEST_BINARY_DIRECTORY` is used instead. -``TRACK <track>`` - If ``TRACK`` is used, the submissions will go to the specified track on the - CDash server. If no ``TRACK`` is specified, the name of the model is used by - default. +``GROUP <group>`` + If ``GROUP`` is used, the submissions will go to the specified group on the + CDash server. If no ``GROUP`` is specified, the name of the model is used by + default. This replaces the deprecated option ``TRACK``. Despite the name + change its behavior is unchanged. ``APPEND`` If ``APPEND`` is used, the existing ``TAG`` is used rather than creating a new one based on the current time stamp. If you use ``APPEND``, you can omit the - ``<model>`` and ``TRACK <track>`` parameters, because they will be read from + ``<model>`` and ``GROUP <group>`` parameters, because they will be read from the generated ``TAG`` file. For example: .. code-block:: cmake - ctest_start(Experimental TRACK TrackExperimental) + ctest_start(Experimental GROUP GroupExperimental) Later, in another ``ctest -S`` script: @@ -48,11 +49,11 @@ The parameters are as follows: ctest_start(APPEND) When the second script runs ``ctest_start(APPEND)``, it will read the - ``Experimental`` model and ``TrackExperimental`` track from the ``TAG`` file + ``Experimental`` model and ``GroupExperimental`` group from the ``TAG`` file generated by the first ``ctest_start()`` command. Please note that if you - call ``ctest_start(APPEND)`` and specify a different model or track than + call ``ctest_start(APPEND)`` and specify a different model or group than in the first ``ctest_start()`` command, a warning will be issued, and the - new model and track will be used. + new model and group will be used. ``QUIET`` If ``QUIET`` is used, CTest will suppress any non-error messages that it @@ -65,11 +66,11 @@ equivalent: .. code-block:: cmake - ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND) + ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND) - ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary) + ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary) - ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary) + ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary) However, for the sake of readability, it is recommended that you order your parameters in the order listed at the top of this page. diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst new file mode 100644 index 0000000000..3e28265953 --- /dev/null +++ b/Help/command/target_precompile_headers.rst @@ -0,0 +1,56 @@ +target_precompile_headers +------------------------- + +Add a list of header files to precompile. + +.. code-block:: cmake + + target_precompile_headers(<target> + <INTERFACE|PUBLIC|PRIVATE> [header1...] + [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...]) + +Adds header files to :prop_tgt:`PRECOMPILE_HEADERS` or +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` target properties. + +Precompiling header files can speed up compilation by creating a partially +processed version of some header files, and then using that version during +compilations rather than repeatedly parsing the original headers. + +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>`. + +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:`PRECOMPILE_HEADERS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +Repeated calls for the same ``<target>`` append items in the order called. + +Arguments to ``target_precompile_headers`` may use "generator expressions" +with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-compile-features(7)` manual for +information on compile features and a list of supported compilers. + +.. code-block:: cmake + + target_precompile_headers(<target> + PUBLIC + "project_header.h" + PRIVATE + <unordered_map> + ) + +Header files will be double quoted if they are not specified with double +quotes or angle brackets. + +See Also +^^^^^^^^ + +For disabling precompile headers for specific targets there is the +property :prop_tgt:`DISABLE_PRECOMPILE_HEADERS`. + +For skipping certain source files there is the source file property +:prop_sf:`SKIP_PRECOMPILE_HEADERS`. diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 47baff42da..0f7488be09 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -74,6 +74,8 @@ The CMake source tree is organized as follows. * ``Utilities/Release/``: Scripts used to package CMake itself for distribution on ``cmake.org``. + See `Utilities/Release/README.rst`_. .. _`CMake Documentation Guide`: documentation.rst .. _`Tests/README.rst`: ../../Tests/README.rst +.. _`Utilities/Release/README.rst`: ../../Utilities/Release/README.rst diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 810aaa914c..0947e41cbf 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -18,6 +18,9 @@ containing :command:`set` commands that use the ``CACHE`` option, not a cache-format file. + References to :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR` + within the script evaluate to the top-level source and build tree. + ``-D <var>:<type>=<value>, -D <var>=<value>`` Create or update a CMake ``CACHE`` entry. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index a3bc46519e..59ba897279 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -112,6 +112,7 @@ These commands are available only in CMake projects. /command/target_link_directories /command/target_link_libraries /command/target_link_options + /command/target_precompile_headers /command/target_sources /command/try_compile /command/try_run diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 62d23c7d4a..25d6b247da 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -181,6 +181,7 @@ Properties on Targets /prop_tgt/DEFINE_SYMBOL /prop_tgt/DEPLOYMENT_REMOTE_DIRECTORY /prop_tgt/DEPLOYMENT_ADDITIONAL_FILES + /prop_tgt/DISABLE_PRECOMPILE_HEADERS /prop_tgt/DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/EchoString /prop_tgt/ENABLE_EXPORTS @@ -240,6 +241,7 @@ Properties on Targets /prop_tgt/INTERFACE_LINK_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES /prop_tgt/INTERFACE_LINK_OPTIONS + /prop_tgt/INTERFACE_PRECOMPILE_HEADERS /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES @@ -295,6 +297,7 @@ Properties on Targets /prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/PDB_OUTPUT_DIRECTORY /prop_tgt/POSITION_INDEPENDENT_CODE + /prop_tgt/PRECOMPILE_HEADERS /prop_tgt/PREFIX /prop_tgt/PRIVATE_HEADER /prop_tgt/PROJECT_LABEL @@ -316,6 +319,7 @@ Properties on Targets /prop_tgt/STATIC_LIBRARY_OPTIONS /prop_tgt/SUFFIX /prop_tgt/Swift_DEPENDENCIES_FILE + /prop_tgt/Swift_LANGUAGE_VERSION /prop_tgt/Swift_MODULE_DIRECTORY /prop_tgt/Swift_MODULE_NAME /prop_tgt/TYPE @@ -445,6 +449,7 @@ Properties on Source Files /prop_sf/SKIP_AUTOMOC /prop_sf/SKIP_AUTORCC /prop_sf/SKIP_AUTOUIC + /prop_sf/SKIP_PRECOMPILE_HEADERS /prop_sf/Swift_DEPENDENCIES_FILE /prop_sf/Swift_DIAGNOSTICS_FILE /prop_sf/SYMBOLIC diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index d6836b87d6..08e2de44a6 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -62,6 +62,7 @@ Variables that Provide Information /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB + /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_SEARCH_END_STATIC /variable/CMAKE_LINK_SEARCH_START_STATIC @@ -356,6 +357,7 @@ Variables that Control the Build /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_CUDA_RESOLVE_DEVICE_SYMBOLS /variable/CMAKE_DEBUG_POSTFIX + /variable/CMAKE_DISABLE_PRECOMPILE_HEADERS /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG @@ -385,6 +387,7 @@ Variables that Control the Build /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE + /variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG /variable/CMAKE_LANG_LINK_LIBRARY_FLAG /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst index 10f617e681..f82c466a91 100644 --- a/Help/manual/cpack.1.rst +++ b/Help/manual/cpack.1.rst @@ -48,9 +48,11 @@ Options the :variable:`CPACK_GENERATOR` variable determines the default set of generators that will be used. -``-C <Configuration>`` - Specify the project configuration to be packaged (e.g. ``Debug``, - ``Release``, etc.). When the CMake project uses a multi-configuration +``-C <configs>`` + Specify the project configuration(s) to be packaged (e.g. ``Debug``, + ``Release``, etc.), where ``<configs>`` is a + :ref:`semicolon-separated list <CMake Language Lists>`. + When the CMake project uses a multi-configuration generator such as Xcode or Visual Studio, this option is needed to tell ``cpack`` which built executables to include in the package. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index c6b1425601..9d93bb8ebd 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -482,14 +482,17 @@ a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: Options for Dashboard Client include: -``--track <track>`` - Specify the track to submit dashboard to +``--group <group>`` + Specify what group you'd like to submit results to - Submit dashboard to specified track instead of default one. By + Submit dashboard to specified group instead of default one. By default, the dashboard is submitted to Nightly, Experimental, or - Continuous track, but by specifying this option, the track can be + Continuous group, but by specifying this option, the group can be arbitrary. + This replaces the deprecated option ``--track``. + Despite the name change its behavior is unchanged. + ``-A <file>, --add-notes <file>`` Add a notes file with submission. diff --git a/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000000..5f39f30aa0 --- /dev/null +++ b/Help/prop_sf/SKIP_PRECOMPILE_HEADERS.rst @@ -0,0 +1,13 @@ +SKIP_PRECOMPILE_HEADERS +----------------------- + +Is this source file skipped by :prop_tgt:`PRECOMPILE_HEADERS` feature. + +This property helps with build problems that one would run into +when using the :prop_tgt:`PRECOMPILE_HEADERS` feature. + +One example would be the usage of Objective-C (*.m) files, and +Objective-C++ (*.mm) files, which lead to compilation failure +because they are treated (in case of Ninja / Makefile generator) +as C, and CXX respectively. The precompile headers are not +compatible between languages. diff --git a/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000000..4cef0231af --- /dev/null +++ b/Help/prop_tgt/DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,8 @@ +DISABLE_PRECOMPILE_HEADERS +-------------------------- + +Disables the precompilation of header files specified by +:prop_tgt:`PRECOMPILE_HEADERS` property. + +If the property is not set, CMake will use the value provided +by :variable:`CMAKE_DISABLE_PRECOMPILE_HEADERS`. diff --git a/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000000..8ff7e8ba1d --- /dev/null +++ b/Help/prop_tgt/INTERFACE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,14 @@ +INTERFACE_PRECOMPILE_HEADERS +---------------------------- + +List of interface header files to precompile into consuming targets. + +Targets may populate this property to publish the header files +for consuming targets to precompile. The :command:`target_precompile_headers` +command populates this property with values given to the ``PUBLIC`` and +``INTERFACE`` keywords. Projects may also get and set the property directly. + +Contents of ``INTERFACE_PRECOMPILE_HEADERS`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/prop_tgt/PRECOMPILE_HEADERS.rst b/Help/prop_tgt/PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000000..9e70b654d0 --- /dev/null +++ b/Help/prop_tgt/PRECOMPILE_HEADERS.rst @@ -0,0 +1,12 @@ +PRECOMPILE_HEADERS +------------------ + +List of header files to precompile. + +This property holds a :ref:`semicolon-separated list <CMake Language Lists>` +of header files to precompile specified so far for its target. +Use the :command:`target_precompile_headers` command to append more header +files. + +This property supports +:manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst new file mode 100644 index 0000000000..7579447a47 --- /dev/null +++ b/Help/prop_tgt/Swift_LANGUAGE_VERSION.rst @@ -0,0 +1,6 @@ +Swift_LANGUAGE_VERSION +---------------------- + +This property sets the language version for the Swift sources in the target. If +one is not specified, it will default to ``<CMAKE_Swift_LANGUAGE_VERSION>`` if +specified, otherwise it is the latest version supported by the compiler. diff --git a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst index ff987ffb81..640bed596a 100644 --- a/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst +++ b/Help/prop_tgt/VS_CONFIGURATION_TYPE.rst @@ -4,6 +4,8 @@ VS_CONFIGURATION_TYPE Visual Studio project configuration type. Sets the ``ConfigurationType`` attribute for a generated Visual Studio project. +The property value may use +:manual:`generator expressions <cmake-generator-expressions(7)>`. If this property is set, it overrides the default setting that is based on the target type (e.g. ``StaticLibrary``, ``Application``, ...). diff --git a/Help/release/3.15.rst b/Help/release/3.15.rst index b0365bac2c..48f3aa4fbf 100644 --- a/Help/release/3.15.rst +++ b/Help/release/3.15.rst @@ -369,3 +369,10 @@ Changes made since CMake 3.15.0 include the following. * In CMake 3.15.0 and 3.15.1 the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable caused the :command:`find_package` command to fail on a missing package even without the ``REQUIRED`` option. This has been fixed. + +3.15.3 +------ + +* ``CrayPrgEnv`` compiler wrapper support has been updated for the 19.06 + release of the Cray Programming Environment for which the default linking + mode on XC Cray systems is now dynamic instead of static. diff --git a/Help/release/dev/FindPkgConfig-module-name.rst b/Help/release/dev/FindPkgConfig-module-name.rst new file mode 100644 index 0000000000..9f1cd3615f --- /dev/null +++ b/Help/release/dev/FindPkgConfig-module-name.rst @@ -0,0 +1,6 @@ +FindPkgConfig-module-name +------------------------- + +* The :module:`FindPkgConfig` module :command:`pkg_search_module` macro + now defines a ``<prefix>_MODULE_NAME`` result variable containing the + first matching module name. diff --git a/Help/release/dev/cmake-initial-cache-dirs.rst b/Help/release/dev/cmake-initial-cache-dirs.rst new file mode 100644 index 0000000000..be9190212b --- /dev/null +++ b/Help/release/dev/cmake-initial-cache-dirs.rst @@ -0,0 +1,6 @@ +cmake-initial-cache-dirs +------------------------ + +* The :manual:`cmake(1)` ``-C <initial-cache>`` option now evaluates the + initial cache script with :variable:`CMAKE_SOURCE_DIR` and + :variable:`CMAKE_BINARY_DIR` set to the top-level source and build trees. diff --git a/Help/release/dev/cpack-install-multiple-configurations.rst b/Help/release/dev/cpack-install-multiple-configurations.rst new file mode 100644 index 0000000000..d1692dcb69 --- /dev/null +++ b/Help/release/dev/cpack-install-multiple-configurations.rst @@ -0,0 +1,5 @@ +cpack-install-multiple-configurations +------------------------------------- + +* CPack learned :variable:`CPACK_INSTALL_CMAKE_CONFIGURATIONS` to control + what configurations going to be packaged for multi-configuration generators. diff --git a/Help/release/dev/per-lang-link-library-flag.rst b/Help/release/dev/per-lang-link-library-flag.rst index ca1181d526..4f5966d273 100644 --- a/Help/release/dev/per-lang-link-library-flag.rst +++ b/Help/release/dev/per-lang-link-library-flag.rst @@ -1,7 +1,9 @@ per-lang-link-library-flag -------------------------- -* The new :variable:`CMAKE_<LANG>_LINK_LIBRARY_FLAG` flag allows you to now - control the flag used to specify linking to a library on a per-language basis. - This is useful for mixed-language projects where the different drivers may use - different flags. +* New variables :variable:`CMAKE_<LANG>_LINK_LIBRARY_FLAG`, + :variable:`CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG`, and + :variable:`CMAKE_<LANG>_LINK_LIBRARY_SUFFIX` allow control of the + flag used to specify linking to a library on a per-language basis. + This is useful for mixed-language projects where the different + drivers may use different flags. diff --git a/Help/release/dev/precompile-headers.rst b/Help/release/dev/precompile-headers.rst new file mode 100644 index 0000000000..8b62da76cd --- /dev/null +++ b/Help/release/dev/precompile-headers.rst @@ -0,0 +1,6 @@ +Precompile Headers +------------------ + +* The :prop_tgt:`PRECOMPILE_HEADERS` target property was added to tell + generators to use a list of precompile headers for faster compilation + times. diff --git a/Help/release/dev/vs-configuration-type-genex.rst b/Help/release/dev/vs-configuration-type-genex.rst new file mode 100644 index 0000000000..d930d5b916 --- /dev/null +++ b/Help/release/dev/vs-configuration-type-genex.rst @@ -0,0 +1,5 @@ +vs-configuration-type-genex +--------------------------- + +* :prop_tgt:`VS_CONFIGURATION_TYPE` now supports + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst new file mode 100644 index 0000000000..7c30edebcd --- /dev/null +++ b/Help/variable/CMAKE_DISABLE_PRECOMPILE_HEADERS.rst @@ -0,0 +1,6 @@ +CMAKE_DISABLE_PRECOMPILE_HEADERS +-------------------------------- + +Default value for :prop_tgt:`DISABLE_PRECOMPILE_HEADERS` of targets. + +By default ``CMAKE_DISABLE_PRECOMPILE_HEADERS`` is ``OFF``. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst new file mode 100644 index 0000000000..d54f080222 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FILE_FLAG.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_LINK_LIBRARY_FILE_FLAG +----------------------------------- + +Language-specific flag to be used to link a library specified by +a path to its file. + +The flag will be used before a library file path is given to the +linker. This is needed only on very few platforms. diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst new file mode 100644 index 0000000000..a378657955 --- /dev/null +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_LINK_LIBRARY_SUFFIX +-------------------------------- + +Language-specific suffix for libraries that you link to. + +The suffix to use for the end of a library filename, ``.lib`` on Windows. |