diff options
Diffstat (limited to 'Help')
41 files changed, 406 insertions, 156 deletions
diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index ca44b53..e9a5eb0 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -20,7 +20,7 @@ Execute one or more child processes. [OUTPUT_STRIP_TRAILING_WHITESPACE] [ERROR_STRIP_TRAILING_WHITESPACE]) -Runs the given sequence of one or more commands with the standard +Runs the given sequence of one or more commands in parallel with the standard output of each process piped to the standard input of the next. A single standard error pipe is used for all processes. @@ -36,6 +36,9 @@ Options: (Use the ``INPUT_*``, ``OUTPUT_*``, and ``ERROR_*`` options to redirect stdin, stdout, and stderr.) + If a sequential execution of multiple commands is required, use multiple + :command:`execute_process` calls with a single ``COMMAND`` argument. + ``WORKING_DIRECTORY`` The named directory will be set as the current working directory of the child processes. diff --git a/Help/command/file.rst b/Help/command/file.rst index 77e9f62..8da46cb 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -153,7 +153,8 @@ Move a file or directory within a filesystem from ``<oldname>`` to file(REMOVE_RECURSE [<files>...]) Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given -files and directories, also non-empty directories +files and directories, also non-empty directories. No error is emitted if a +given file does not exist. ------------------------------------------------------------------------------ diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt new file mode 100644 index 0000000..58e9223 --- /dev/null +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -0,0 +1,10 @@ +For each toolset that comes with this version of Visual Studio, there are +variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts +(independent of the architecture they target). By default Visual Studio +chooses the 32-bit variant even on a 64-bit host. One may request use of the +64-bit host tools by adding ``host=x64`` to the toolset specification: + +``host=x64`` + Select the 64-bit variant of the default toolset. +``<toolset>,host=x64`` + Select the 64-bit variant of the ``<toolset>`` toolset. diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst index c694443..04eef10 100644 --- a/Help/generator/Visual Studio 10 2010.rst +++ b/Help/generator/Visual Studio 10 2010.rst @@ -17,3 +17,10 @@ a target platform name optionally at the end of this generator name: For compatibility with CMake versions prior to 3.0, one may specify this generator using the name ``Visual Studio 10`` without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v100`` toolset that comes with Visual Studio 10 2010 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst index 2f1e729..347a153 100644 --- a/Help/generator/Visual Studio 11 2012.rst +++ b/Help/generator/Visual Studio 11 2012.rst @@ -20,3 +20,10 @@ a target platform name optionally at the end of this generator name: For compatibility with CMake versions prior to 3.0, one may specify this generator using the name "Visual Studio 11" without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index 6e8545b..5071b20 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -17,3 +17,12 @@ a target platform name optionally at the end of this generator name: For compatibility with CMake versions prior to 3.0, one may specify this generator using the name "Visual Studio 12" without the year component. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index 707caf9..64254b5 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -14,3 +14,12 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 14 2015 ARM`` Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 15.rst b/Help/generator/Visual Studio 15.rst index ae456eb..2eb9052 100644 --- a/Help/generator/Visual Studio 15.rst +++ b/Help/generator/Visual Studio 15.rst @@ -14,3 +14,12 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 15 ARM`` Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v141`` toolset that comes with Visual Studio 15 is selected by +default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. + +.. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index d8a6790..25ff4c7 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -2,3 +2,10 @@ Xcode ----- Generate Xcode project files. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +By default Xcode is allowed to select its own default toolchain. +The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps +via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index fa0e4c1..9b3f717 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -52,13 +52,12 @@ Specify toolset name if supported by generator. Some CMake generators support a toolset name to be given to the - native build system to choose a compiler. This is supported only on - specific generators: - - :: + native build system to choose a compiler. + See the :variable:`CMAKE_GENERATOR_TOOLSET` variable. + This is supported only on specific generators: - Visual Studio >= 10 - Xcode >= 3.0 + * :ref:`Visual Studio Generators` for VS 2010 and above + * The :generator:`Xcode` generator for Xcode 3.0 and above See native build system documentation for allowed toolset names. diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 7289e61..13f7d16 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -84,6 +84,33 @@ Feature requirements are evaluated transitively by consuming the link implementation. See :manual:`cmake-buildsystem(7)` for more on transitive behavior of build properties and usage requirements. +Requiring Language Standards +---------------------------- + +In projects that use a large number of commonly available features from +a particular language standard (e.g. C++ 11) one may specify a +meta-feature (e.g. ``cxx_std_11``) that requires use of a compiler mode +aware of that standard. This is simpler than specifying all the +features individually, but does not guarantee the existence of any +particular feature. Diagnosis of use of unsupported features will be +delayed until compile time. + +For example, if C++ 11 features are used extensively in a project's +header files, then clients must use a compiler mode aware of C++ 11 +or above. This can be requested with the code: + +.. code-block:: cmake + + target_compile_features(mylib PUBLIC cxx_std_11) + +In this example, CMake will ensure the compiler is invoked in a mode +that is aware of C++ 11 (or above), adding flags such as +``-std=gnu++11`` if necessary. This applies to sources within ``mylib`` +as well as any dependents (that may include headers from ``mylib``). + +Availability of Compiler Extensions +----------------------------------- + Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, CMake uses extended variants of language dialects by default, such as ``-std=gnu++11`` instead of ``-std=c++11``. That target property may be @@ -309,4 +336,4 @@ versions specified for each: * ``GNU``: GNU compiler versions 4.4 through 5.0. * ``MSVC``: Microsoft Visual Studio versions 2010 through 2015. * ``SunPro``: Oracle SolarisStudio version 12.4. -* ``Intel``: Intel compiler versions 12.1 through 16.0 on UNIX platforms. +* ``Intel``: Intel compiler versions 12.1 through 17.0. diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 271f497..fa21a1f 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -121,6 +121,7 @@ Properties on Targets /prop_tgt/AUTORCC /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR + /prop_tgt/BUILD_RPATH /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION /prop_tgt/BUNDLE diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index e8a2c1e..7827065 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -29,7 +29,7 @@ Qt 4 and Qt 5 may be used together in the same set(CMAKE_AUTOMOC ON) set(CMAKE_INCLUDE_CURRENT_DIR ON) - find_package(Qt5Widgets REQUIRED) + find_package(Qt5 COMPONENTS Widgets DBus REQUIRED) add_executable(publisher publisher.cpp) target_link_libraries(publisher Qt5::Widgets Qt5::DBus) diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index afd4e2b..9520cc1 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -57,17 +57,17 @@ or using a named pipe (with the ``--pipe <NAMED_PIPE>`` parameter). When connecting to the server (via named pipe or by starting it in ``--debug`` mode), the server will reply with a hello message:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"supportedProtocolVersions":[{"major":1,"minor":0}],"type":"hello"} - ]== CMake Server ==] + ]== "CMake Server" ==] Messages sent to and from the process are wrapped in magic strings:: - [== CMake Server ==[ + [== "CMake Server" ==[ { ... some JSON message ... } - ]== CMake Server ==] + ]== "CMake Server" ==] The server is now ready to accept further requests via the named pipe or stdin. @@ -87,7 +87,7 @@ the response into the given filename. This is a response from the cmake server with "showStats" set to true:: - [== CMake Server ==[ + [== "CMake Server" ==[ { "cookie":"", "errorMessage":"Waiting for type \"handshake\".", @@ -100,7 +100,7 @@ This is a response from the cmake server with "showStats" set to true:: "totalTime":0.025995 } } - ]== CMake Server ==] + ]== "CMake Server" ==] The server has made a copy of this response into the file /tmp/error.txt and took 0.011 seconds to turn the JSON response into a string, and it took 0.025 @@ -137,9 +137,9 @@ contain values. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} - ]== CMake Server ==] + ]== "CMake Server" ==] Type "error" @@ -150,9 +150,9 @@ contain an "errorMessage". Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"cookie":"","errorMessage":"Protocol version not supported.","inReplyTo":"handshake","type":"error"} - ]== CMake Server ==] + ]== "CMake Server" ==] Type "progress" @@ -181,9 +181,9 @@ box title. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"cookie":"","message":"Something happened.","title":"Title Text","inReplyTo":"handshake","type":"message"} - ]== CMake Server ==] + ]== "CMake Server" ==] Type "signal" @@ -208,13 +208,13 @@ an influence on the build system is changed. The "dirty" signal may look like this:: - [== CMake Server ==[ + [== "CMake Server" ==[ { "cookie":"", "inReplyTo":"", "name":"dirty", "type":"signal"} - ]== CMake Server ==] + ]== "CMake Server" ==] "fileChange" Signal @@ -226,7 +226,7 @@ that was detected. Possible changes are "change" and "rename". The "fileChange" signal looks like this:: - [== CMake Server ==[ + [== "CMake Server" ==[ { "cookie":"", "inReplyTo":"", @@ -234,7 +234,7 @@ The "fileChange" signal looks like this:: "path":"/absolute/CMakeLists.txt", "properties":["change"], "type":"signal"} - ]== CMake Server ==] + ]== "CMake Server" ==] Specific Message Types @@ -250,13 +250,15 @@ This is the only message ever sent by the server that is not of type "reply", It will contain "supportedProtocolVersions" with an array of server protocol versions supported by the cmake server. These are JSON objects with "major" and -"minor" keys containing non-negative integer values. +"minor" keys containing non-negative integer values. Some versions may be marked +as experimental. These will contain the "isExperimental" key set to true. Enabling +these requires a special command line argument when starting the cmake server mode. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"supportedProtocolVersions":[{"major":0,"minor":1}],"type":"hello"} - ]== CMake Server ==] + ]== "CMake Server" ==] Type "handshake" @@ -274,21 +276,23 @@ Protocol version 1.0 requires the following attributes to be set: * "sourceDirectory" with a path to the sources * "buildDirectory" with a path to the build directory * "generator" with the generator name - * "extraGenerator" (optional!) with the extra generator to be used. + * "extraGenerator" (optional!) with the extra generator to be used + * "platform" with the generator platform (if supported by the generator) + * "toolset" with the generator toolset (if supported by the generator) Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"cookie":"zimtstern","type":"handshake","protocolVersion":{"major":0}, "sourceDirectory":"/home/code/cmake", "buildDirectory":"/tmp/testbuild", "generator":"Ninja"} - ]== CMake Server ==] + ]== "CMake Server" ==] which will result in a response type "reply":: - [== CMake Server ==[ + [== "CMake Server" ==[ {"cookie":"zimtstern","inReplyTo":"handshake","type":"reply"} - ]== CMake Server ==] + ]== "CMake Server" ==] indicating that the server is ready for action. @@ -301,13 +305,13 @@ JSON structure with information on cmake state. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"type":"globalSettings"} - ]== CMake Server ==] + ]== "CMake Server" ==] which will result in a response type "reply":: - [== CMake Server ==[ + [== "CMake Server" ==[ { "buildDirectory": "/tmp/test-build", "capabilities": { @@ -344,7 +348,7 @@ which will result in a response type "reply":: "warnUnused": false, "warnUnusedCli": true } - ]== CMake Server ==] + ]== "CMake Server" ==] Type "setGlobalSettings" @@ -362,15 +366,15 @@ The server will respond with an empty reply message or an error. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"type":"setGlobalSettings","debugOutput":true} - ]== CMake Server ==] + ]== "CMake Server" ==] CMake will reply to this with:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"inReplyTo":"setGlobalSettings","type":"reply"} - ]== CMake Server ==] + ]== "CMake Server" ==] Type "configure" @@ -389,34 +393,34 @@ cache handling that are passed to the cmake command line client. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"type":"configure", "cacheArguments":["-Dsomething=else"]} - ]== CMake Server ==] + ]== "CMake Server" ==] CMake will reply like this (after reporting progress for some time):: - [== CMake Server ==[ + [== "CMake Server" ==[ {"cookie":"","inReplyTo":"configure","type":"reply"} - ]== CMake Server ==] + ]== "CMake Server" ==] Type "compute" ^^^^^^^^^^^^^^ -This requist will generate build system files in the build directory and +This request will generate build system files in the build directory and is only available after a project was successfully "configure"d. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"type":"compute"} - ]== CMake Server ==] + ]== "CMake Server" ==] CMake will reply (after reporting progress information):: - [== CMake Server ==[ + [== "CMake Server" ==[ {"cookie":"","inReplyTo":"compute","type":"reply"} - ]== CMake Server ==] + ]== "CMake Server" ==] Type "codemodel" @@ -426,8 +430,19 @@ The "codemodel" request can be used after a project was "compute"d successfully. It will list the complete project structure as it is known to cmake. -The reply will contain a key "projects", which will contain a list of -project objects, one for each (sub-)project defined in the cmake build system. +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. Each project object can have the following keys: @@ -437,19 +452,8 @@ Each project object can have the following keys: contains the current source directory "buildDirectory" contains the current build directory. -"configurations" - contains a list of configuration objects. - -Configuration objects are used to destinquish between different -configurations the build directory might have enabled. While most generators -only support one configuration, others support several. - -Each configuration object can have the following keys: - -"name" - contains the name of the configuration. The name may be empty. "targets" - contains a list of target objects, one for each build target. + contains a list of build system target objects. Target objects define individual build targets for a certain configuration. @@ -519,88 +523,53 @@ sourceDirectory of the target. Example:: - [== CMake Server ==[ - {"type":"project"} - ]== CMake Server ==] + [== "CMake Server" ==[ + {"type":"codemodel"} + ]== "CMake Server" ==] CMake will reply:: - [== CMake Server ==[ + [== "CMake Server" ==[ { - "cookie":"", - "type":"reply", - "inReplyTo":"project", - - "projects": - [ + "configurations": [ { - "name":"CMAKE_FORM", - "sourceDirectory":"/home/code/src/cmake/Source/CursesDialog/form" - "buildDirectory":"/tmp/cmake-build-test/Source/CursesDialog/form", - "configurations": - [ + "name": "", + "projects": [ { - "name":"", - "targets": - [ + "buildDirectory": "/tmp/build/Source/CursesDialog/form", + "name": "CMAKE_FORM", + "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", + "targets": [ { - "artifactDirectory":"/tmp/cmake/Source/CursesDialog/form", - "fileGroups": - [ + "artifacts": [ "/tmp/build/Source/CursesDialog/form/libcmForm.a" ], + "buildDirectory": "/tmp/build/Source/CursesDialog/form", + "fileGroups": [ { - "compileFlags":" -std=gnu11", - "defines": - [ - "SOMETHING=1", - "LIBARCHIVE_STATIC" - ], - "includePath": - [ - { "path":"/tmp/cmake-build-test/Utilities" }, - { "isSystem": true, "path":"/usr/include/something" }, - ... - ] - "language":"C", - "sources": - [ - "fld_arg.c", - ... - "fty_regex.c" - ] + "compileFlags": " -std=gnu11", + "defines": [ "CURL_STATICLIB", "LIBARCHIVE_STATIC" ], + "includePath": [ { "path": "/tmp/build/Utilities" }, <...> ], + "isGenerated": false, + "language": "C", + "sources": [ "fld_arg.c", <...> ] } ], - "fullName":"libcmForm.a", - "linkerLanguage":"C", - "name":"cmForm", - "type":"STATIC_LIBRARY" + "fullName": "libcmForm.a", + "linkerLanguage": "C", + "name": "cmForm", + "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", + "type": "STATIC_LIBRARY" } ] - } - ], - }, - ... - ] + }, + <...> + ] + } + ], + "cookie": "", + "inReplyTo": "codemodel", + "type": "reply" } - ]== CMake Server ==] - -The output can be tailored to the specific needs via parameter passed when -requesting "project" information. - -You can have a "depth" key, which accepts "project", "configuration" and -"target" as string values. These cause the output to be trimmed at the -appropriate depth of the output tree. - -You can also set "configurations" to an array of strings with configuration -names to list. This will cause any configuration that is not listed to be -trimmed from the output. - -Generated files can be included in the listing by setting "includeGeneratedFiles" -to "true". This setting defaults to "false", so generated files are not -listed by default. - -Finally you can limit the target types that are going to be listed. This is -done by providing a list of target types as an array of strings to the -"targetTypes" key. + ]== "CMake Server" ==] Type "cmakeInputs" @@ -614,13 +583,13 @@ This request is only available after a project was successfully Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"type":"cmakeInputs"} - ]== CMake Server ==] + ]== "CMake Server" ==] CMake will reply with the following information:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"buildFiles": [ {"isCMake":true,"isTemporary":false,"sources":["/usr/lib/cmake/...", ... ]}, @@ -633,7 +602,7 @@ CMake will reply with the following information:: "inReplyTo":"cmakeInputs", "type":"reply" } - ]== CMake Server ==] + ]== "CMake Server" ==] All file names are either relative to the top level source directory or absolute. @@ -652,13 +621,13 @@ list the cached configuration values. Example:: - [== CMake Server ==[ + [== "CMake Server" ==[ {"type":"cache"} - ]== CMake Server ==] + ]== "CMake Server" ==] CMake will respond with the following output:: - [== CMake Server ==[ + [== "CMake Server" ==[ { "cookie":"","inReplyTo":"cache","type":"reply", "cache": @@ -674,7 +643,7 @@ CMake will respond with the following output:: "value":"TEST"} ] } - ]== CMake Server ==] + ]== "CMake Server" ==] The output can be limited to a list of keys by passing an array of key names to the "keys" optional field of the "cache" request. @@ -688,16 +657,16 @@ command will report on the files and directories watched. Example:: - [== CMake Server ==] + [== "CMake Server" ==[ {"type":"fileSystemWatchers"} - [== CMake Server ==] + ]== "CMake Server" ==] CMake will respond with the following output:: - [== CMake Server ==] + [== "CMake Server" ==[ { "cookie":"","inReplyTo":"fileSystemWatchers","type":"reply", "watchedFiles": [ "/absolute/path" ], "watchedDirectories": [ "/absolute" ] } - [== CMake Server ==] + ]== "CMake Server" ==] diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index b74f867..93e809a 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -82,6 +82,7 @@ Variables that Provide Information /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME /variable/CMAKE_VS_PLATFORM_TOOLSET + /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT_BINARY_DIR @@ -159,6 +160,8 @@ Variables that Change Behavior /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY /variable/CMAKE_STAGING_PREFIX + /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH @@ -257,6 +260,7 @@ Variables that Control the Build /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS + /variable/CMAKE_BUILD_RPATH /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index e8f4d2a..00a5104 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -14,6 +14,15 @@ compile features and a list of supported compilers. The features known to this version of CMake are: +``cxx_std_98`` + Compiler mode is aware of C++ 98. + +``cxx_std_11`` + Compiler mode is aware of C++ 11. + +``cxx_std_14`` + Compiler mode is aware of C++ 14. + ``cxx_aggregate_default_initializers`` Aggregate default initializers, as defined in N3605_. diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index a08af00..3707fef 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -13,6 +13,15 @@ compile features and a list of supported compilers. The features known to this version of CMake are: +``c_std_90`` + Compiler mode is aware of C 90. + +``c_std_99`` + Compiler mode is aware of C 99. + +``c_std_11`` + Compiler mode is aware of C 11. + ``c_function_prototypes`` Function prototypes, as defined in ``ISO/IEC 9899:1990``. diff --git a/Help/prop_sf/COMPILE_FLAGS.rst b/Help/prop_sf/COMPILE_FLAGS.rst index 086a063..1012164 100644 --- a/Help/prop_sf/COMPILE_FLAGS.rst +++ b/Help/prop_sf/COMPILE_FLAGS.rst @@ -6,3 +6,10 @@ Additional flags to be added when compiling this source file. These flags will be added to the list of compile flags when this source file builds. Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. + +Contents of ``COMPILE_FLAGS`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. However, :generator:`Xcode` +does not support per-config per-source settings, so expressions +that depend on the build configuration are not allowed with that +generator. diff --git a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst index a191a9c..d607992 100644 --- a/Help/prop_test/TIMEOUT_AFTER_MATCH.rst +++ b/Help/prop_test/TIMEOUT_AFTER_MATCH.rst @@ -22,7 +22,9 @@ When the test outputs a line that matches ``regex`` its start time is reset to the current time and its timeout duration is changed to ``seconds``. Prior to this, the timeout duration is determined by the :prop_test:`TIMEOUT` property or the :variable:`CTEST_TEST_TIMEOUT` -variable if either of these are set. +variable if either of these are set. Because the test's start time is +reset, its execution time will not include any time that was spent +waiting for the matching output. :prop_test:`TIMEOUT_AFTER_MATCH` is useful for avoiding spurious timeouts when your test must wait for some system resource to become diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst new file mode 100644 index 0000000..27393f5 --- /dev/null +++ b/Help/prop_tgt/BUILD_RPATH.rst @@ -0,0 +1,10 @@ +BUILD_RPATH +----------- + +A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``) +entries to add to binaries linked in the build tree (for platforms that +support it). The entries will *not* be used for binaries in the install +tree. See also the :prop_tgt:`INSTALL_RPATH` target property. + +This property is initialized by the value of the variable +:variable:`CMAKE_BUILD_RPATH` if it is set when a target is created. diff --git a/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst index 09ff0ce..4da855b 100644 --- a/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst +++ b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst @@ -1,19 +1,25 @@ MAP_IMPORTED_CONFIG_<CONFIG> ---------------------------- -Map from project configuration to IMPORTED target's configuration. +Map from project configuration to +:ref:`imported target <IMPORTED targets>`'s configuration. Set this to the list of configurations of an imported target that may -be used for the current project's <CONFIG> configuration. Targets +be used for the current project's ``<CONFIG>`` configuration. Targets imported from another project may not provide the same set of configuration names available in the current project. Setting this property tells CMake what imported configurations are suitable for use -when building the <CONFIG> configuration. The first configuration in -the list found to be provided by the imported target is selected. If -this property is set and no matching configurations are available, +when building the ``<CONFIG>`` configuration. The first configuration in +the list found to be provided by the imported target (i.e. via +:prop_tgt:`IMPORTED_LOCATION_<CONFIG>` for the mapped-to ``<CONFIG>``) +is selected. As a special case, an empty list element refers to the +configuration-less imported target location +(i.e. :prop_tgt:`IMPORTED_LOCATION`). + +If this property is set and no matching configurations are available, then the imported target is considered to be not found. This property is ignored for non-imported targets. -This property is initialized by the value of the variable -CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> if it is set when a target is -created. +This property is initialized by the value of the +:variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable if it is set when a +target is created. diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst index 9794267..3b8ade6 100644 --- a/Help/release/3.7.rst +++ b/Help/release/3.7.rst @@ -32,7 +32,7 @@ Generators with :ref:`Makefile Generators`. * The :generator:`Visual Studio 15` generator was added. This is - experimental and based on Preview 4 because this version of VS + experimental and based on Preview 5 because this version of VS has not been released. * :ref:`Visual Studio Generators` for VS 2010 and above learned to diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /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/ExternalData-multiple-hashes.rst b/Help/release/dev/ExternalData-multiple-hashes.rst new file mode 100644 index 0000000..608a277 --- /dev/null +++ b/Help/release/dev/ExternalData-multiple-hashes.rst @@ -0,0 +1,7 @@ +ExternalData-multiple-hashes +---------------------------- + +* The :module:`ExternalData` module learned to support multiple + content links for one data file using different hashes, e.g. + ``img.png.sha256`` and ``img.png.sha1``. This allows objects + to be fetched from sources indexed by different hash algorithms. diff --git a/Help/release/dev/UseSWIG-SWIG_OUTFILE_DIR.rst b/Help/release/dev/UseSWIG-SWIG_OUTFILE_DIR.rst new file mode 100644 index 0000000..c001a88 --- /dev/null +++ b/Help/release/dev/UseSWIG-SWIG_OUTFILE_DIR.rst @@ -0,0 +1,6 @@ +UseSWIG-SWIG_OUTFILE_DIR +------------------------ + +* The :module:`UseSWIG` module ``swig_add_source_to_module`` command + learned a new ``SWIG_OUTFILE_DIR`` option to control the output + file location (``swig -o``). diff --git a/Help/release/dev/add-BUILD_RPATH.rst b/Help/release/dev/add-BUILD_RPATH.rst new file mode 100644 index 0000000..0d69e45 --- /dev/null +++ b/Help/release/dev/add-BUILD_RPATH.rst @@ -0,0 +1,6 @@ +add-BUILD_RPATH +--------------- + +* A :variable:`CMAKE_BUILD_RPATH` variable and corresponding + :prop_tgt:`BUILD_RPATH` target property were added to support custom + ``RPATH`` locations to be added to binaries in the build tree. diff --git a/Help/release/dev/allow-fallback-config-mapping.rst b/Help/release/dev/allow-fallback-config-mapping.rst new file mode 100644 index 0000000..2522e10 --- /dev/null +++ b/Help/release/dev/allow-fallback-config-mapping.rst @@ -0,0 +1,6 @@ +allow-fallback-config-mapping +----------------------------- + +* The :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property learned + to interpret empty list elements as referring to the configuration-less + imported location specified by :prop_tgt:`IMPORTED_LOCATION`. diff --git a/Help/release/dev/compile-features-for-language-standards.rst b/Help/release/dev/compile-features-for-language-standards.rst new file mode 100644 index 0000000..20473b7 --- /dev/null +++ b/Help/release/dev/compile-features-for-language-standards.rst @@ -0,0 +1,7 @@ +compile-features-for-language-standards +--------------------------------------- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now offers meta-features that request compiler modes for specific language + standard levels. See :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and + :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES`. diff --git a/Help/release/dev/cpack-rpm-single-debuginfo.rst b/Help/release/dev/cpack-rpm-single-debuginfo.rst new file mode 100644 index 0000000..34a710d --- /dev/null +++ b/Help/release/dev/cpack-rpm-single-debuginfo.rst @@ -0,0 +1,11 @@ +cpack-rpm-single-debuginfo +-------------------------- + +* The :module:`CPackRPM` module learned to generate main component package + which forces generation of a rpm for defined component without component + suffix in filename and package name. + See :variable:`CPACK_RPM_MAIN_COMPONENT` variable. + +* The :module:`CPackRPM` module learned to generate a single debuginfo package + on demand even if components packagin is used. + See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable. diff --git a/Help/release/dev/external-project-clone-progress.rst b/Help/release/dev/external-project-clone-progress.rst new file mode 100644 index 0000000..766a1a3 --- /dev/null +++ b/Help/release/dev/external-project-clone-progress.rst @@ -0,0 +1,5 @@ +external-project-clone-progress +------------------------------- + +* The :module:`ExternalProject` module gained the ``GIT_PROGRESS`` option to + force Git to show progress when cloning repositories. diff --git a/Help/release/dev/intel-compile-features-windows.rst b/Help/release/dev/intel-compile-features-windows.rst new file mode 100644 index 0000000..6a2cdfe --- /dev/null +++ b/Help/release/dev/intel-compile-features-windows.rst @@ -0,0 +1,6 @@ +intel-compile-features-windows +------------------------------ + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by Intel C++ compilers versions 12.1 + through 17.0 on UNIX and Windows platforms. diff --git a/Help/release/dev/math-EXPR-unary.rst b/Help/release/dev/math-EXPR-unary.rst new file mode 100644 index 0000000..d4af15b --- /dev/null +++ b/Help/release/dev/math-EXPR-unary.rst @@ -0,0 +1,5 @@ +math-EXPR-unary +--------------- + +* The :command:`math(EXPR)` command gained support for unary + ``+`` and ``-`` expressions. diff --git a/Help/release/dev/src-COMPILE_FLAGS-genex.rst b/Help/release/dev/src-COMPILE_FLAGS-genex.rst new file mode 100644 index 0000000..26cd3ef --- /dev/null +++ b/Help/release/dev/src-COMPILE_FLAGS-genex.rst @@ -0,0 +1,5 @@ +src-COMPILE_FLAGS-genex +----------------------- + +* The :prop_sf:`COMPILE_FLAGS` source file property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/st2-env-settings.rst b/Help/release/dev/st2-env-settings.rst new file mode 100644 index 0000000..7b36347 --- /dev/null +++ b/Help/release/dev/st2-env-settings.rst @@ -0,0 +1,6 @@ +st2-env-settings +---------------- + +* The :generator:`Sublime Text 2` extra generator learned to place + environment variables in the generated ``.sublime-project``. + See the :variable:`CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS` variable. diff --git a/Help/release/dev/st2-exclude-patterns-variable.rst b/Help/release/dev/st2-exclude-patterns-variable.rst new file mode 100644 index 0000000..8706c1f --- /dev/null +++ b/Help/release/dev/st2-exclude-patterns-variable.rst @@ -0,0 +1,7 @@ +st2-exclude-patterns-variable +----------------------------- + +* The :generator:`Sublime Text 2` extra generator no longer excludes the + build tree from the ``.sublime-project`` when it is inside the source tree. + The :variable:`CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable + was added to control the behavior explicitly. diff --git a/Help/release/dev/vs-host-x64-tools.rst b/Help/release/dev/vs-host-x64-tools.rst new file mode 100644 index 0000000..e42881a --- /dev/null +++ b/Help/release/dev/vs-host-x64-tools.rst @@ -0,0 +1,7 @@ +vs-host-x64-tools +----------------- + +* The :ref:`Visual Studio Generators` for VS 2013 and above learned to + support a ``host=x64`` option in the :variable:`CMAKE_GENERATOR_TOOLSET` + value (e.g. via the :manual:`cmake(1)` ``-T`` option) to request use + of a VS 64-bit toolchain on 64-bit hosts. diff --git a/Help/release/index.rst b/Help/release/index.rst index 25c6c3e..30decd5 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,6 +5,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_BUILD_RPATH.rst b/Help/variable/CMAKE_BUILD_RPATH.rst new file mode 100644 index 0000000..f20eb41 --- /dev/null +++ b/Help/variable/CMAKE_BUILD_RPATH.rst @@ -0,0 +1,10 @@ +CMAKE_BUILD_RPATH +----------------- + +A :ref:`;-list <CMake Language Lists>` specifying runtime path (``RPATH``) +entries to add to binaries linked in the build tree (for platforms that +support it). The entries will *not* be used for binaries in the install +tree. See also the :variable:`CMAKE_INSTALL_RPATH` variable. + +This is used to initialize the :prop_tgt:`BUILD_RPATH` target property +for all targets. diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst new file mode 100644 index 0000000..02c8663 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS.rst @@ -0,0 +1,25 @@ +CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS +--------------------------------- + +This variable contains a list of env vars as a list of tokens with the +syntax ``var=value``. + +Example: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "FOO=FOO1\;FOO2\;FOON" + "BAR=BAR1\;BAR2\;BARN" + "BAZ=BAZ1\;BAZ2\;BAZN" + "FOOBAR=FOOBAR1\;FOOBAR2\;FOOBARN" + "VALID=" + ) + +In case of malformed variables CMake will fail: + +.. code-block:: cmake + + set(CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS + "THIS_IS_NOT_VALID" + ) diff --git a/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst new file mode 100644 index 0000000..d654425 --- /dev/null +++ b/Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst @@ -0,0 +1,7 @@ +CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE +--------------------------------------- + +If this variable evaluates to ``ON`` at the end of the top-level +``CMakeLists.txt`` file, the :generator:`Sublime Text 2` extra generator +excludes the build tree from the ``.sublime-project`` if it is inside the +source tree. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst new file mode 100644 index 0000000..4c04e97 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -0,0 +1,10 @@ +CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE +------------------------------------------- + +Visual Studio preferred tool architecture. + +The :ref:`Visual Studio Generators` for VS 2013 and above support optional +selection of a 64-bit toolchain on 64-bit hosts by specifying a ``host=64`` +value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides +the selected toolchain architecture preference in this variable (either +``x64`` or empty). |