diff options
Diffstat (limited to 'Help')
88 files changed, 1261 insertions, 73 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index 4ab4298..80e7edf 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -21,7 +21,8 @@ The first signature is for adding a custom command to produce an output:: [WORKING_DIRECTORY dir] [COMMENT comment] [DEPFILE depfile] - [VERBATIM] [APPEND] [USES_TERMINAL]) + [VERBATIM] [APPEND] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS]) This defines a command to generate specified ``OUTPUT`` file(s). A target created in the same directory (``CMakeLists.txt`` file) @@ -122,6 +123,14 @@ The options are: Arguments to ``DEPENDS`` may use :manual:`generator expressions <cmake-generator-expressions(7)>`. +``COMMAND_EXPAND_LISTS`` + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`, + allowing ``COMMAND`` arguments such as + ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` + to be properly expanded. + ``IMPLICIT_DEPENDS`` Request scanning of implicit dependencies of an input file. The language given specifies the programming language whose diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst index 6980d61..bd61c8b 100644 --- a/Help/command/add_custom_target.rst +++ b/Help/command/add_custom_target.rst @@ -12,6 +12,7 @@ Add a target with no output so it will always be built. [WORKING_DIRECTORY dir] [COMMENT comment] [VERBATIM] [USES_TERMINAL] + [COMMAND_EXPAND_LISTS] [SOURCES src1 [src2...]]) Adds a target with the given name that executes the given commands. @@ -88,6 +89,14 @@ The options are: Use the :command:`add_dependencies` command to add dependencies on other targets. +``COMMAND_EXPAND_LISTS`` + Lists in ``COMMAND`` arguments will be expanded, including those + created with + :manual:`generator expressions <cmake-generator-expressions(7)>`, + allowing ``COMMAND`` arguments such as + ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` + to be properly expanded. + ``SOURCES`` Specify additional source files to be included in the custom target. Specified source files will be added to IDE project files for diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 36adcbe..af75a39 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -33,7 +33,7 @@ type is ``STATIC`` or ``SHARED`` based on whether the current value of the variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and ``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property is set to ``ON`` automatically. -A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK` +A ``SHARED`` or ``STATIC`` library may be marked with the :prop_tgt:`FRAMEWORK` target property to create an OS X Framework. If a library does not export any symbols, it must not be declared as a diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst index 29bdf7d..a983d68 100644 --- a/Help/command/ctest_memcheck.rst +++ b/Help/command/ctest_memcheck.rst @@ -18,6 +18,7 @@ Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`. [SCHEDULE_RANDOM <ON|OFF>] [STOP_TIME <time-of-day>] [RETURN_VALUE <result-var>] + [DEFECT_COUNT <defect-count-var>] [QUIET] ) @@ -26,4 +27,9 @@ Run tests with a dynamic analysis tool and store results in ``MemCheck.xml`` for submission with the :command:`ctest_submit` command. -The options are the same as those for the :command:`ctest_test` command. +Most options are the same as those for the :command:`ctest_test` command. + +The options unique to this command are: + +``DEFECT_COUNT <defect-count-var>`` + Store in the ``<defect-count-var>`` the number of defects found. diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 6830b59..a7d9708 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -56,10 +56,16 @@ Submit to CDash Upload API :: - ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]) + ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>] + [RETRY_COUNT <count>] + [RETRY_DELAY <delay>] + [QUIET]) This second signature is used to upload files to CDash via the CDash file upload API. The api first sends a request to upload to CDash along with a content hash of the file. If CDash does not already have the file, then it is uploaded. Along with the file, a CDash type string is specified to tell CDash which handler to use to process the data. + +This signature accepts the ``RETRY_COUNT``, ``RETRY_DELAY``, and ``QUIET`` +options as described above. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index ca44b53..d617243 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -18,9 +18,10 @@ Execute one or more child processes. [OUTPUT_QUIET] [ERROR_QUIET] [OUTPUT_STRIP_TRAILING_WHITESPACE] - [ERROR_STRIP_TRAILING_WHITESPACE]) + [ERROR_STRIP_TRAILING_WHITESPACE] + [ENCODING <name>]) -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 +37,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. @@ -63,6 +67,25 @@ Options: ``OUTPUT_QUIET``, ``ERROR_QUIET`` The standard output or standard error results will be quietly ignored. +``ENCODING <name>`` + On Windows, the encoding that is used to decode output from the process. + Ignored on other platforms. + Valid encoding names are: + + ``NONE`` + Perform no decoding. This assumes that the process output is encoded + in the same way as CMake's internal encoding (UTF-8). + This is the default. + ``AUTO`` + Use the current active console's codepage or if that isn't + available then use ANSI. + ``ANSI`` + Use the ANSI codepage. + ``OEM`` + Use the original equipment manufacturer (OEM) code page. + ``UTF8`` + Use the UTF-8 codepage. + If more than one ``OUTPUT_*`` or ``ERROR_*`` option is given for the same pipe the precedence is not specified. If no ``OUTPUT_*`` or ``ERROR_*`` options are given the output will diff --git a/Help/command/file.rst b/Help/command/file.rst index 77e9f62..3e669c2 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -83,10 +83,12 @@ from the input file. :: - file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>) + file(<HASH> <filename> <variable>) Compute a cryptographic hash of the content of ``<filename>`` and -store it in a ``<variable>``. +store it in a ``<variable>``. The supported ``<HASH>`` algorithm names +are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>` +command. ------------------------------------------------------------------------------ @@ -153,7 +155,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. ------------------------------------------------------------------------------ @@ -233,8 +236,8 @@ Additional options to ``DOWNLOAD`` are: ``EXPECTED_HASH ALGO=<value>`` Verify that the downloaded content hash matches the expected value, where - ``ALGO`` is one of ``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, or - ``SHA512``. If it does not match, the operation fails with an error. + ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``. + If it does not match, the operation fails with an error. ``EXPECTED_MD5 <value>`` Historical short-hand for ``EXPECTED_HASH MD5=<value>``. diff --git a/Help/command/if.rst b/Help/command/if.rst index 0941029..2a087d0 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -9,17 +9,17 @@ Conditionally execute a group of commands. # then section. COMMAND1(ARGS ...) COMMAND2(ARGS ...) - ... + #... elseif(expression2) # elseif section. COMMAND1(ARGS ...) COMMAND2(ARGS ...) - ... + #... else(expression) # else section. COMMAND1(ARGS ...) COMMAND2(ARGS ...) - ... + #... endif(expression) Evaluates the given expression. If the result is true, the commands diff --git a/Help/command/install.rst b/Help/command/install.rst index d57dd75..70087a4 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -90,8 +90,10 @@ project. There are five kinds of target files that may be installed: ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE`` -targets on OS X. Static libraries are always treated as ``ARCHIVE`` -targets. Module libraries are always treated as ``LIBRARY`` targets. +targets on OS X. Static libraries are treated as ``ARCHIVE`` targets, +except that those marked with the ``FRAMEWORK`` property are treated +as ``FRAMEWORK`` targets on OS X. +Module libraries are always treated as ``LIBRARY`` targets. For non-DLL platforms shared libraries are treated as ``LIBRARY`` targets, except that those marked with the ``FRAMEWORK`` property are treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL diff --git a/Help/command/source_group.rst b/Help/command/source_group.rst index 6e3829c..938ca40 100644 --- a/Help/command/source_group.rst +++ b/Help/command/source_group.rst @@ -2,15 +2,27 @@ source_group ------------ Define a grouping for source files in IDE project generation. +There are two different signatures to create source groups. -.. code-block:: cmake +:: source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>]) + source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...]) Defines a group into which sources will be placed in project files. This is intended to set up file tabs in Visual Studio. The options are: +``TREE`` + CMake will automatically detect, from ``<src>`` files paths, source groups + it needs to create, to keep structure of source groups analogically to the + actual files and directories structure in the project. Paths of ``<src>`` + files will be cut to be relative to ``<root>``. + +``PREFIX`` + Source group and files located directly in ``<root>`` path, will be placed + in ``<prefix>`` source groups. + ``FILES`` Any source file specified explicitly will be placed in group ``<name>``. Relative paths are interpreted with respect to the @@ -25,11 +37,13 @@ explicitly lists the file with ``FILES`` will be favored, if any. If no group explicitly lists the file, the *last* group whose regular expression matches the file will be favored. -The ``<name>`` of the group may contain backslashes to specify subgroups: +The ``<name>`` of the group and ``<prefix>`` argument may contain backslashes +to specify subgroups: .. code-block:: cmake source_group(outer\\inner ...) + source_group(TREE <root> PREFIX sources\\inc ...) For backwards compatibility, the short-hand signature diff --git a/Help/command/string.rst b/Help/command/string.rst index 8028333..698a91d 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -206,15 +206,38 @@ Comparison Compare the strings and store true or false in the output variable. +.. _`Supported Hash Algorithms`: + Hashing ^^^^^^^ :: - string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> - <output variable> <input>) + string(<HASH> <output variable> <input>) 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. Generation ^^^^^^^^^^ @@ -273,6 +296,7 @@ specifiers: :: + %% A literal percent sign (%). %d The day of the current month (01-31). %H The hour on a 24-hour clock (00-23). %I The hour on a 12-hour clock (01-12). @@ -306,6 +330,12 @@ If no explicit ``<format string>`` is given it will default to: Write a string which can be used as an identifier in C. +.. note:: + + 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 """" diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 90b6575..30d69f2 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -53,6 +53,11 @@ Each ``<item>`` may be: :ref:`usage requirement <Target Usage Requirements>`. This has the same effect as passing the framework directory as an include directory. + On :ref:`Visual Studio Generators` for VS 2010 and above, library files + ending in ``.targets`` will be treated as MSBuild targets files and + imported into generated project files. This is not supported by other + generators. + * **A plain library name**: The generated link line will ask the linker to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``). diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 7830deb..66ea3d7 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -35,7 +35,11 @@ Try Compiling Source Files [COMPILE_DEFINITIONS <defs>...] [LINK_LIBRARIES <libs>...] [OUTPUT_VARIABLE <var>] - [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]) + [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]] + [<LANG>_STANDARD <std>] + [<LANG>_STANDARD_REQUIRED <bool>] + [<LANG>_EXTENSIONS <bool>] + ) Try building an executable from one or more source files. The success or failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is @@ -82,6 +86,19 @@ The options are: ``OUTPUT_VARIABLE <var>`` Store the output from the build process the given variable. +``<LANG>_STANDARD <std>`` + Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, + or :prop_tgt:`CUDA_STANDARD` target property of the generated project. + +``<LANG>_STANDARD_REQUIRED <bool>`` + Specify the :prop_tgt:`C_STANDARD_REQUIRED`, + :prop_tgt:`CXX_STANDARD_REQUIRED`, or :prop_tgt:`CUDA_STANDARD_REQUIRED` + target property of the generated project. + +``<LANG>_EXTENSIONS <bool>`` + Specify the :prop_tgt:`C_EXTENSIONS`, :prop_tgt:`CXX_EXTENSIONS`, + or :prop_tgt:`CUDA_EXTENSIONS` target property of the generated project. + In this version all files in ``<bindir>/CMakeFiles/CMakeTmp`` will be cleaned automatically. For debugging, ``--debug-trycompile`` can be passed to ``cmake`` to avoid this clean. However, multiple sequential @@ -119,3 +136,20 @@ the type of target used for the source file signature. Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify variables that must be propagated into the test project. This variable is meant for use only in toolchain files. + +If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``, +``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used, +then the language standard variables are honored: + +* :variable:`CMAKE_C_STANDARD` +* :variable:`CMAKE_C_STANDARD_REQUIRED` +* :variable:`CMAKE_C_EXTENSIONS` +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_CUDA_STANDARD` +* :variable:`CMAKE_CUDA_STANDARD_REQUIRED` +* :variable:`CMAKE_CUDA_EXTENSIONS` + +Their values are used to set the corresponding target properties in +the generated project (unless overridden by an explicit option). diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index 01798c7..d03cb0c 100644 --- a/Help/generator/CodeBlocks.rst +++ b/Help/generator/CodeBlocks.rst @@ -18,6 +18,9 @@ This "extra" generator may be specified as: ``CodeBlocks - NMake Makefiles`` Generate with :generator:`NMake Makefiles`. +``CodeBlocks - NMake Makefiles JOM`` + Generate with :generator:`NMake Makefiles JOM`. + ``CodeBlocks - Ninja`` Generate with :generator:`Ninja`. 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 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 18b0131..a88f8bc 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -14,3 +14,12 @@ a target platform name optionally at the end of this generator name: ``Visual Studio 15 2017 ARM`` Specify target platform ``ARM``. + +Toolset Selection +^^^^^^^^^^^^^^^^^ + +The ``v141`` toolset that comes with Visual Studio 15 2017 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-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 4950fee..2e6a803 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -964,6 +964,8 @@ are: * ``EXPORT_NAME`` * ``IMPORTED`` * ``NAME`` +* ``NO_SYSTEM_FROM_IMPORTED`` +* Properties matching ``IMPORTED_LIBNAME_*`` * Properties matching ``MAP_IMPORTED_CONFIG_*`` ``INTERFACE`` libraries may be installed and exported. Any content they refer diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 7289e61..448fe9a 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 @@ -299,7 +326,7 @@ the feature-appropriate include directory Supported Compilers =================== -CMake is currently aware of the :prop_tgt:`language standards <CXX_STANDARD>` +CMake is currently aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the versions specified for each: @@ -309,4 +336,18 @@ 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. + +CMake is currently aware of the :prop_tgt:`C standards <C_STANDARD>` +and :prop_gbl:`compile features <CMAKE_C_KNOWN_FEATURES>` available from +the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* all compilers and versions listed above for C++ +* ``GNU``: GNU compiler versions 3.4 through 5.0. + +CMake is currently aware of the :prop_tgt:`CUDA standards <CUDA_STANDARD>` +from the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* ``NVIDIA``: NVIDIA nvcc compiler 7.5 though 8.0. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 6557686..f77d8c0 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -11,7 +11,7 @@ Introduction ============ This manual is intended for reference by developers modifying the CMake -source tree itself. +source tree itself, and by those authoring externally-maintained modules. Permitted C++ Subset @@ -540,7 +540,7 @@ a :ref:`Line Comment` block of the form: or a :ref:`Bracket Comment` of the form: -.. code-block:: cmake +:: #[[.rst: <module-name> @@ -558,7 +558,7 @@ All such comments must start with ``#`` in the first column. For example, a ``Modules/Findxxx.cmake`` module may contain: -.. code-block:: cmake +:: # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 64d15a9..3a225ad 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -51,6 +51,8 @@ Available logical expressions are: ``0`` if all ``?`` are ``0``, else ``1`` ``$<NOT:?>`` ``0`` if ``?`` is ``1``, else ``1`` +``$<IF:?,true-value...,false-value...>``` + ``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0`` ``$<STREQUAL:a,b>`` ``1`` if ``a`` is STREQUAL ``b``, else ``0`` ``$<EQUAL:a,b>`` diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 41542c9..27b5d30 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -255,7 +255,7 @@ invocation as exactly one argument. For example: -.. code-block:: cmake +:: message("This is a quoted argument containing multiple lines. This is always one argument even though it contains a ; character. @@ -329,11 +329,17 @@ For example: To support legacy CMake code, unquoted arguments may also contain double-quoted strings (``"..."``, possibly enclosing horizontal whitespace), and make-style variable references (``$(MAKEVAR)``). + Unescaped double-quotes must balance, may not appear at the beginning of an unquoted argument, and are treated as part of the content. For example, the unquoted arguments ``-Da="b c"``, ``-Da=$(v)``, and ``a" "b"c"d`` are each interpreted literally. + Make-style references are treated literally as part of the content + and do not undergo variable expansion. They are treated as part + of a single argument (rather than as separate ``$``, ``(``, + ``MAKEVAR``, and ``)`` arguments). + The above "unquoted_legacy" production represents such arguments. We do not recommend using legacy unquoted arguments in new code. Instead use a `Quoted Argument`_ or a `Bracket Argument`_ to @@ -421,7 +427,7 @@ A ``#`` immediately followed by a `Bracket Argument`_ forms a For example: -.. code-block:: cmake +:: #[[This is a bracket comment. It runs until the close bracket.]] diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 015e36e..d4712ba 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -59,6 +59,7 @@ All Modules /module/CPackDeb /module/CPackDMG /module/CPackIFW + /module/CPackIFWConfigureFile /module/CPackNSIS /module/CPackPackageMaker /module/CPackProductBuild diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index c27c612..c9442bc 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -449,12 +449,12 @@ be true. This can be tested with logic in the package configuration file: foreach(_comp ${ClimbingStats_FIND_COMPONENTS}) if (NOT ";${_supported_components};" MATCHES _comp) set(ClimbingStats_FOUND False) - set(ClimbingStats_NOTFOUND_MESSAGE "Unsupported component: ${_comp}") + set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}") endif() include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake") endforeach() -Here, the ``ClimbingStats_NOTFOUND_MESSAGE`` is set to a diagnosis that the package +Here, the ``ClimbingStats_NOT_FOUND_MESSAGE`` is set to a diagnosis that the package could not be found because an invalid component was specified. This message variable can be set for any case where the ``_FOUND`` variable is set to ``False``, and will be displayed to the user. diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 0cfe983..3266958 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,14 @@ 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.8 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0067: Honor language standard in try_compile() source-file signature. </policy/CMP0067> + Policies Introduced by CMake 3.7 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 271f497..38aba81 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -44,6 +44,7 @@ Properties of Global Scope /prop_gbl/TARGET_MESSAGES /prop_gbl/TARGET_SUPPORTS_SHARED_LIBS /prop_gbl/USE_FOLDERS + /prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME .. _`Directory Properties`: @@ -121,6 +122,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 @@ -142,6 +144,10 @@ Properties on Targets /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX /prop_tgt/CROSSCOMPILING_EMULATOR + /prop_tgt/CUDA_SEPARABLE_COMPILATION + /prop_tgt/CUDA_EXTENSIONS + /prop_tgt/CUDA_STANDARD + /prop_tgt/CUDA_STANDARD_REQUIRED /prop_tgt/CXX_EXTENSIONS /prop_tgt/CXX_STANDARD /prop_tgt/CXX_STANDARD_REQUIRED @@ -166,6 +172,8 @@ Properties on Targets /prop_tgt/IMPORTED_CONFIGURATIONS /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB + /prop_tgt/IMPORTED_LIBNAME_CONFIG + /prop_tgt/IMPORTED_LIBNAME /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG @@ -204,6 +212,7 @@ Properties on Targets /prop_tgt/LABELS /prop_tgt/LANG_CLANG_TIDY /prop_tgt/LANG_COMPILER_LAUNCHER + /prop_tgt/LANG_CPPLINT /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG @@ -229,6 +238,7 @@ Properties on Targets /prop_tgt/MACOSX_BUNDLE /prop_tgt/MACOSX_FRAMEWORK_INFO_PLIST /prop_tgt/MACOSX_RPATH + /prop_tgt/MANUALLY_ADDED_DEPENDENCIES /prop_tgt/MAP_IMPORTED_CONFIG_CONFIG /prop_tgt/NAME /prop_tgt/NO_SONAME @@ -265,8 +275,11 @@ Properties on Targets /prop_tgt/VERSION /prop_tgt/VISIBILITY_INLINES_HIDDEN /prop_tgt/VS_CONFIGURATION_TYPE + /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION + /prop_tgt/VS_DOTNET_REFERENCE_refname /prop_tgt/VS_DOTNET_REFERENCES + /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION /prop_tgt/VS_GLOBAL_KEYWORD /prop_tgt/VS_GLOBAL_PROJECT_TYPES @@ -281,6 +294,7 @@ Properties on Targets /prop_tgt/VS_SCC_PROJECTNAME /prop_tgt/VS_SCC_PROVIDER /prop_tgt/VS_SDK_REFERENCES + /prop_tgt/VS_USER_PROPS /prop_tgt/VS_WINDOWS_TARGET_PLATFORM_MIN_VERSION /prop_tgt/VS_WINRT_COMPONENT /prop_tgt/VS_WINRT_EXTENSIONS @@ -288,6 +302,8 @@ Properties on Targets /prop_tgt/WIN32_EXECUTABLE /prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS /prop_tgt/XCODE_ATTRIBUTE_an-attribute + /prop_tgt/XCODE_EXPLICIT_FILE_TYPE + /prop_tgt/XCODE_PRODUCT_TYPE /prop_tgt/XCTEST .. _`Test Properties`: @@ -344,9 +360,16 @@ Properties on Source Files /prop_sf/MACOSX_PACKAGE_LOCATION /prop_sf/OBJECT_DEPENDS /prop_sf/OBJECT_OUTPUTS + /prop_sf/SKIP_AUTOGEN + /prop_sf/SKIP_AUTOMOC + /prop_sf/SKIP_AUTORCC + /prop_sf/SKIP_AUTOUIC /prop_sf/SYMBOLIC + /prop_sf/VS_COPY_TO_OUT_DIR /prop_sf/VS_DEPLOYMENT_CONTENT /prop_sf/VS_DEPLOYMENT_LOCATION + /prop_sf/VS_INCLUDE_IN_VSIX + /prop_sf/VS_RESOURCE_GENERATOR /prop_sf/VS_SHADER_ENTRYPOINT /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index 7827065..56d4ca7 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -22,12 +22,11 @@ Qt 4 and Qt 5 may be used together in the same .. code-block:: cmake - cmake_minimum_required(VERSION 3.0.0 FATAL_ERROR) + cmake_minimum_required(VERSION 3.8.0 FATAL_ERROR) project(Qt4And5) set(CMAKE_AUTOMOC ON) - set(CMAKE_INCLUDE_CURRENT_DIR ON) find_package(Qt5 COMPONENTS Widgets DBus REQUIRED) add_executable(publisher publisher.cpp) @@ -73,14 +72,20 @@ The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being invoked for, and for the appropriate build configuration. -Generated ``moc_*.cpp`` and ``*.moc`` files are placed in the build directory -so it is convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` -variable. The :prop_tgt:`AUTOMOC` target property may be pre-set for all +The generated ``moc_*.cpp`` and ``*.moc`` files are placed in the +``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is +automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. +(This differs from CMake 3.7 and below; see their documentation for details.) + +The :prop_tgt:`AUTOMOC` target property may be pre-set for all following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The :prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. +Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by +enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. + .. _`Qt AUTOUIC`: AUTOUIC @@ -94,10 +99,13 @@ If a preprocessor ``#include`` directive is found which matches ``ui_<basename>.h``, and a ``<basename>.ui`` file exists, then ``uic`` will be executed to generate the appropriate file. -Generated ``ui_*.h`` files are placed in the build directory so it is -convenient to set the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable. The -:prop_tgt:`AUTOUIC` target property may be pre-set for all following targets -by setting the :variable:`CMAKE_AUTOUIC` variable. The +The generated generated ``ui_*.h`` files are placed in the +``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is +automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. +(This differs from CMake 3.7 and below; see their documentation for details.) + +The :prop_tgt:`AUTOUIC` target property may be pre-set for all following +targets by setting the :variable:`CMAKE_AUTOUIC` variable. The :prop_tgt:`AUTOUIC_OPTIONS` target property may be populated to set options to pass to ``uic``. The :variable:`CMAKE_AUTOUIC_OPTIONS` variable may be populated to pre-set the options for all following targets. The @@ -144,6 +152,9 @@ result of linking with the :prop_tgt:`IMPORTED` target: Qt5::Widgets ) +Source files can be excluded from :prop_tgt:`AUTOUIC` processing by +enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. + .. _`Qt AUTORCC`: AUTORCC @@ -166,6 +177,9 @@ populated to pre-set the options for all following targets. The ``<name>.qrc`` file to set particular options for the file. This overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property. +Source files can be excluded from :prop_tgt:`AUTORCC` processing by +enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. + qtmain.lib on Windows ===================== diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 31c0a84..38444d1 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 @@ -160,6 +161,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 @@ -259,6 +262,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 @@ -280,6 +284,7 @@ Variables that Control the Build /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_CLANG_TIDY /variable/CMAKE_LANG_COMPILER_LAUNCHER + /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY @@ -325,6 +330,7 @@ Variables that Control the Build /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD + /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute @@ -344,6 +350,10 @@ Variables for Languages /variable/CMAKE_C_EXTENSIONS /variable/CMAKE_C_STANDARD /variable/CMAKE_C_STANDARD_REQUIRED + /variable/CMAKE_CUDA_EXTENSIONS + /variable/CMAKE_CUDA_STANDARD + /variable/CMAKE_CUDA_STANDARD_REQUIRED + /variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES /variable/CMAKE_CXX_COMPILE_FEATURES /variable/CMAKE_CXX_EXTENSIONS /variable/CMAKE_CXX_STANDARD diff --git a/Help/module/CPackIFWConfigureFile.rst b/Help/module/CPackIFWConfigureFile.rst new file mode 100644 index 0000000..e88517c --- /dev/null +++ b/Help/module/CPackIFWConfigureFile.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackIFWConfigureFile.cmake diff --git a/Help/policy/CMP0067.rst b/Help/policy/CMP0067.rst new file mode 100644 index 0000000..e6dda80 --- /dev/null +++ b/Help/policy/CMP0067.rst @@ -0,0 +1,37 @@ +CMP0067 +------- + +Honor language standard in :command:`try_compile` source-file signature. + +The :command:`try_compile` source file signature is intended to allow +callers to check whether they will be able to compile a given source file +with the current toolchain. In order to match compiler behavior, any +language standard mode should match. However, CMake 3.7 and below did not +do this. CMake 3.8 and above prefer to honor the language standard settings +for ``C``, ``CXX`` (C++), and ``CUDA`` using the values of the variables: + +* :variable:`CMAKE_C_STANDARD` +* :variable:`CMAKE_C_STANDARD_REQUIRED` +* :variable:`CMAKE_C_EXTENSIONS` +* :variable:`CMAKE_CXX_STANDARD` +* :variable:`CMAKE_CXX_STANDARD_REQUIRED` +* :variable:`CMAKE_CXX_EXTENSIONS` +* :variable:`CMAKE_CUDA_STANDARD` +* :variable:`CMAKE_CUDA_STANDARD_REQUIRED` +* :variable:`CMAKE_CUDA_EXTENSIONS` + +This policy provides compatibility for projects that do not expect +the language standard settings to be used automatically. + +The ``OLD`` behavior of this policy is to ignore language standard +setting variables when generating the ``try_compile`` test project. +The ``NEW`` behavior of this policy is to honor language standard +setting variables. + +This policy was introduced in CMake version 3.8. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0067 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst index 5a69ef3..fae5626 100644 --- a/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst +++ b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst @@ -1,7 +1,7 @@ AUTOGEN_TARGETS_FOLDER ---------------------- -Name of :prop_tgt:`FOLDER` for ``*_automoc`` targets that are added automatically by +Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added automatically by CMake for targets for which :prop_tgt:`AUTOMOC` is enabled. If not set, CMake uses the :prop_tgt:`FOLDER` property of the parent target as a diff --git a/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst b/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst index 671f86a..17666e4 100644 --- a/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst +++ b/Help/prop_gbl/AUTOMOC_TARGETS_FOLDER.rst @@ -1,7 +1,7 @@ AUTOMOC_TARGETS_FOLDER ---------------------- -Name of :prop_tgt:`FOLDER` for ``*_automoc`` targets that are added automatically by +Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added automatically by CMake for targets for which :prop_tgt:`AUTOMOC` is enabled. This property is obsolete. Use :prop_gbl:`AUTOGEN_TARGETS_FOLDER` instead. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index e8f4d2a..2ad8157 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -14,6 +14,18 @@ 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_std_17`` + Compiler mode is aware of C++ 17. + ``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_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst new file mode 100644 index 0000000..9a6086e --- /dev/null +++ b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst @@ -0,0 +1,24 @@ +XCODE_EMIT_EFFECTIVE_PLATFORM_NAME +---------------------------------- + +Control emission of ``EFFECTIVE_PLATFORM_NAME`` by the Xcode generator. + +It is required for building the same target with multiple SDKs. A +common use case is the parallel use of ``iphoneos`` and +``iphonesimulator`` SDKs. + +Three different states possible that control when the Xcode generator +emits the ``EFFECTIVE_PLATFORM_NAME`` variable: + +- If set to ``ON`` it will always be emitted +- If set to ``OFF`` it will never be emitted +- If unset (the default) it will only be emitted when the project was + configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any + of the simulators. + +.. note:: + + When this behavior is enable for generated Xcode projects, the + ``EFFECTIVE_PLATFORM_NAME`` variable will leak into + :manual:`Generator expressions <cmake-generator-expressions(7)>` + like ``TARGET_FILE`` and will render those mostly unusable. 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_sf/SKIP_AUTOGEN.rst b/Help/prop_sf/SKIP_AUTOGEN.rst new file mode 100644 index 0000000..6bf2409 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOGEN.rst @@ -0,0 +1,8 @@ +SKIP_AUTOGEN +------------ + +Exclude the source file from :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and +:prop_tgt:`AUTORCC` processing (for Qt projects). + +For finer control see :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` and +:prop_sf:`SKIP_AUTORCC`. diff --git a/Help/prop_sf/SKIP_AUTOMOC.rst b/Help/prop_sf/SKIP_AUTOMOC.rst new file mode 100644 index 0000000..2245ca6 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOMOC.rst @@ -0,0 +1,6 @@ +SKIP_AUTOMOC +------------ + +Exclude the source file from :prop_tgt:`AUTOMOC` processing (for Qt projects). + +For broader control see :prop_sf:`SKIP_AUTOGEN` diff --git a/Help/prop_sf/SKIP_AUTORCC.rst b/Help/prop_sf/SKIP_AUTORCC.rst new file mode 100644 index 0000000..394d8f8 --- /dev/null +++ b/Help/prop_sf/SKIP_AUTORCC.rst @@ -0,0 +1,6 @@ +SKIP_AUTORCC +------------ + +Exclude the source file from :prop_tgt:`AUTORCC` processing (for Qt projects). + +For broader control see :prop_sf:`SKIP_AUTOGEN` diff --git a/Help/prop_sf/SKIP_AUTOUIC.rst b/Help/prop_sf/SKIP_AUTOUIC.rst new file mode 100644 index 0000000..50f78ef --- /dev/null +++ b/Help/prop_sf/SKIP_AUTOUIC.rst @@ -0,0 +1,6 @@ +SKIP_AUTOUIC +------------ + +Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects). + +For broader control see :prop_sf:`SKIP_AUTOGEN` diff --git a/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst b/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst new file mode 100644 index 0000000..16c8d83 --- /dev/null +++ b/Help/prop_sf/VS_COPY_TO_OUT_DIR.rst @@ -0,0 +1,6 @@ +VS_COPY_TO_OUT_DIR +------------------ + +Sets the ``<CopyToOutputDirectory>`` tag for a source file in a +Visual Studio project file. Valid values are ``Never``, ``Always`` +and ``PreserveNewest``. diff --git a/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst new file mode 100644 index 0000000..30f471d --- /dev/null +++ b/Help/prop_sf/VS_INCLUDE_IN_VSIX.rst @@ -0,0 +1,6 @@ +VS_INCLUDE_IN_VSIX +------------------ + +Boolean property to specify if the file should be included within a VSIX +extension package. This is needed for development of Visual Studio +extensions. diff --git a/Help/prop_sf/VS_RESOURCE_GENERATOR.rst b/Help/prop_sf/VS_RESOURCE_GENERATOR.rst new file mode 100644 index 0000000..97e5aac --- /dev/null +++ b/Help/prop_sf/VS_RESOURCE_GENERATOR.rst @@ -0,0 +1,8 @@ +VS_RESOURCE_GENERATOR +--------------------- + +This property allows to specify the resource generator to be used +on this file. It defaults to ``PublicResXFileCodeGenerator`` if +not set. + +This property only applies to C# projects. 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/AUTOGEN_TARGET_DEPENDS.rst b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst index 5063244..f522c6b 100644 --- a/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst +++ b/Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst @@ -1,16 +1,16 @@ AUTOGEN_TARGET_DEPENDS ---------------------- -Target dependencies of the corresponding ``_automoc`` target. +Target dependencies of the corresponding ``_autogen`` target. Targets which have their :prop_tgt:`AUTOMOC` target ``ON`` have a -corresponding ``_automoc`` target which is used to autogenerate generate moc -files. As this ``_automoc`` target is created at generate-time, it is not +corresponding ``_autogen`` target which is used to autogenerate generate moc +files. As this ``_autogen`` target is created at generate-time, it is not possible to define dependencies of it, such as to create inputs for the ``moc`` executable. The ``AUTOGEN_TARGET_DEPENDS`` target property can be set instead to a list of -dependencies for the ``_automoc`` target. The buildsystem will be generated to +dependencies for the ``_autogen`` target. The buildsystem will be generated to depend on its contents. See the :manual:`cmake-qt(7)` manual for more information on using CMake diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 8143ba9..b42643f 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -15,11 +15,12 @@ source files at build time and invoke moc accordingly. the ``Q_OBJECT`` class declaration is expected in the header, and ``moc`` is run on the header file. A ``moc_foo.cpp`` file will be generated from the source's header into the - :variable:`CMAKE_CURRENT_BINARY_DIR` directory. This allows the - compiler to find the included ``moc_foo.cpp`` file regardless of the - location the original source. However, if multiple source files - in different directories do this then their generated moc files would - collide. In this case a diagnostic will be issued. + ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` + directory which is automatically added to the target's + :prop_tgt:`INCLUDE_DIRECTORIES`. This allows the compiler to find the + included ``moc_foo.cpp`` file regardless of the location the original source. + However, if multiple source files in different directories do this then their + generated moc files would collide. In this case a diagnostic will be issued. * If an ``#include`` statement like ``#include "foo.moc"`` is found, then a ``Q_OBJECT`` is expected in the current source file and ``moc`` @@ -30,7 +31,7 @@ source files at build time and invoke moc accordingly. alternative extensions, such as ``hpp``, ``hxx`` etc when searching for headers. The resulting moc files, which are not included as shown above in any of the source files are included in a generated - ``<targetname>_automoc.cpp`` file, which is compiled as part of the + ``moc_compilation.cpp`` file, which is compiled as part of the target. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` @@ -46,5 +47,8 @@ See the documentation for this variable for more details. The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the automoc targets together in an IDE, e.g. in MSVS. +Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by +enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. + 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 158fdf8..1ad0895 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -24,5 +24,8 @@ generate unspecified unique names for ``rcc``. Therefore if ``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the ``.qrc`` file name must be unique. +Source files can be excluded from :prop_tgt:`AUTORCC` processing by +enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`. + 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 4e60ec3..fbf24c3 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -20,5 +20,8 @@ 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. +Source files can be excluded from :prop_tgt:`AUTOUIC` processing by +enabling :prop_sf:`SKIP_AUTOUIC` or the broader :prop_sf:`SKIP_AUTOGEN`. + See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. 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/CUDA_EXTENSIONS.rst b/Help/prop_tgt/CUDA_EXTENSIONS.rst new file mode 100644 index 0000000..098ca3c --- /dev/null +++ b/Help/prop_tgt/CUDA_EXTENSIONS.rst @@ -0,0 +1,17 @@ +CUDA_EXTENSIONS +--------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. The basic CUDA/C++ standard level is +controlled by the :prop_tgt:`CUDA_STANDARD` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_CUDA_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..1c7dd80 --- /dev/null +++ b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,13 @@ +CUDA_SEPARABLE_COMPILATION +-------------------------- + +CUDA only: Enables separate compilation of device code + +If set this will enable separable compilation for all CUDA files for +the given target. + +For instance: + +.. code-block:: cmake + + set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON) diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst new file mode 100644 index 0000000..b262814 --- /dev/null +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -0,0 +1,32 @@ +CUDA_STANDARD +------------- + +The CUDA/C++ standard whose features are requested to build this target. + +This property specifies the CUDA/C++ standard whose features are requested +to build this target. For some compilers, this results in adding a +flag such as ``-std=gnu++11`` to the compile line. + +Supported values are ``98``, ``11``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY CUDA_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`CUDA_STANDARD_REQUIRED` target property. +Additionally, the :prop_tgt:`CUDA_EXTENSIONS` target property may be used to +control whether compiler-specific extensions are enabled on a per-target basis. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_CUDA_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CUDA_STANDARD_REQUIRED.rst b/Help/prop_tgt/CUDA_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..b2d5b28 --- /dev/null +++ b/Help/prop_tgt/CUDA_STANDARD_REQUIRED.rst @@ -0,0 +1,18 @@ +CUDA_STANDARD_REQUIRED +---------------------- + +Boolean describing whether the value of :prop_tgt:`CUDA_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`CUDA_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`CUDA_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. For compilers that have no notion of a standard level, such as +MSVC, this has no effect. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. + +This property is initialized by the value of +the :variable:`CMAKE_CUDA_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 5b186c1..30a612d 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -8,7 +8,7 @@ to build this target. For some compilers, this results in adding a flag such as ``-std=gnu++11`` to the compile line. For compilers that have no notion of a standard level, such as MSVC, this has no effect. -Supported values are ``98``, ``11`` and ``14``. +Supported values are ``98``, ``11``, ``14``, and ``17``. If the value requested does not result in a compile flag being added for the compiler in use, a previous standard flag will be added instead. This diff --git a/Help/prop_tgt/FRAMEWORK.rst b/Help/prop_tgt/FRAMEWORK.rst index 8120c36..495d30e 100644 --- a/Help/prop_tgt/FRAMEWORK.rst +++ b/Help/prop_tgt/FRAMEWORK.rst @@ -1,9 +1,9 @@ FRAMEWORK --------- -Build ``SHARED`` library as Framework Bundle on the OS X and iOS. +Build ``SHARED`` or ``STATIC`` library as Framework Bundle on the OS X and iOS. -If a ``SHARED`` library target has this property set to ``TRUE`` it will be +If such a library target has this property set to ``TRUE`` it will be built as a framework when built on the OS X and iOS. It will have the directory structure required for a framework and will be suitable to be used with the ``-framework`` option diff --git a/Help/prop_tgt/IMPORTED_LIBNAME.rst b/Help/prop_tgt/IMPORTED_LIBNAME.rst new file mode 100644 index 0000000..1943dba --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LIBNAME.rst @@ -0,0 +1,23 @@ +IMPORTED_LIBNAME +---------------- + +Specify the link library name for an :ref:`imported <Imported Targets>` +:ref:`Interface Library <Interface Libraries>`. + +An interface library builds no library file itself but does specify +usage requirements for its consumers. The ``IMPORTED_LIBNAME`` +property may be set to specify a single library name to be placed +on the link line in place of the interface library target name as +a requirement for using the interface. + +This property is intended for use in naming libraries provided by +a platform SDK for which the full path to a library file may not +be known. The value may be a plain library name such as ``foo`` +but may *not* be a path (e.g. ``/usr/lib/libfoo.so``) or a flag +(e.g. ``-Wl,...``). The name is never treated as a library target +name even if it happens to name one. + +The ``IMPORTED_LIBNAME`` property is allowed only on +:ref:`imported <Imported Targets>` :ref:`Interface Libraries` +and is rejected on targets of other types (for which +the :prop_tgt:`IMPORTED_LOCATION` target property may be used). diff --git a/Help/prop_tgt/IMPORTED_LIBNAME_CONFIG.rst b/Help/prop_tgt/IMPORTED_LIBNAME_CONFIG.rst new file mode 100644 index 0000000..a28b838 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_LIBNAME_CONFIG.rst @@ -0,0 +1,7 @@ +IMPORTED_LIBNAME_<CONFIG> +------------------------- + +<CONFIG>-specific version of :prop_tgt:`IMPORTED_LIBNAME` property. + +Configuration names correspond to those provided by the project from +which the target is imported. diff --git a/Help/prop_tgt/LANG_CPPLINT.rst b/Help/prop_tgt/LANG_CPPLINT.rst new file mode 100644 index 0000000..14f47d4 --- /dev/null +++ b/Help/prop_tgt/LANG_CPPLINT.rst @@ -0,0 +1,13 @@ +<LANG>_CPPLINT +-------------- + +This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`;-list <CMake Language Lists>` containing a command line +for the ``cpplint`` style checker. The :ref:`Makefile Generators` and the +:generator:`Ninja` generator will run ``cpplint`` along with the compiler +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. diff --git a/Help/prop_tgt/MANUALLY_ADDED_DEPENDENCIES.rst b/Help/prop_tgt/MANUALLY_ADDED_DEPENDENCIES.rst new file mode 100644 index 0000000..c12ea14 --- /dev/null +++ b/Help/prop_tgt/MANUALLY_ADDED_DEPENDENCIES.rst @@ -0,0 +1,8 @@ +MANUALLY_ADDED_DEPENDENCIES +--------------------------- + +Get manually added dependencies to other top-level targets. + +This read-only property can be used to query all dependencies that +were added for this target with the :command:`add_dependencies` +command. 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/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst new file mode 100644 index 0000000..0af85cb --- /dev/null +++ b/Help/prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY.rst @@ -0,0 +1,6 @@ +VS_DEBUGGER_WORKING_DIRECTORY +----------------------------- + +Sets the local debugger working directory for Visual Studio C++ targets. +This is defined in ``<LocalDebuggerWorkingDirectory>`` in the Visual Studio +project file. diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL.rst b/Help/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL.rst new file mode 100644 index 0000000..7641ba5 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL.rst @@ -0,0 +1,7 @@ +VS_DOTNET_REFERENCES_COPY_LOCAL +------------------------------- + +Sets the **Copy Local** property for all .NET hint references in the target + +Boolean property to enable/disable copying of .NET hint references to +output directory. The default is ``ON``. diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCE_refname.rst b/Help/prop_tgt/VS_DOTNET_REFERENCE_refname.rst new file mode 100644 index 0000000..5814005 --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCE_refname.rst @@ -0,0 +1,12 @@ +VS_DOTNET_REFERENCE_<refname> +----------------------------- + +Visual Studio managed project .NET reference with name ``<refname>`` +and hint path. + +Adds one .NET reference to generated Visual Studio project. The +reference will have the name ``<refname>`` and will point to the +assembly given as value of the property. + +See also :prop_tgt:`VS_DOTNET_REFERENCES` and +:prop_tgt:`VS_DOTNET_REFERENCES_COPY_LOCAL` diff --git a/Help/prop_tgt/VS_USER_PROPS.rst b/Help/prop_tgt/VS_USER_PROPS.rst new file mode 100644 index 0000000..1be222b --- /dev/null +++ b/Help/prop_tgt/VS_USER_PROPS.rst @@ -0,0 +1,12 @@ +VS_USER_PROPS +------------- + +Sets the user props file to be included in the visual studio +C++ project file. The standard path is +``$(UserRootDir)\\Microsoft.Cpp.$(Platform).user.props``, which is +in most cases the same as +``%LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.Win32.user.props`` +or ``%LOCALAPPDATA%\\Microsoft\\MSBuild\\v4.0\\Microsoft.Cpp.x64.user.props``. + +The ``*.user.props`` files can be used for Visual Studio wide +configuration which is independent from cmake. diff --git a/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst b/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst new file mode 100644 index 0000000..dc92902 --- /dev/null +++ b/Help/prop_tgt/XCODE_EXPLICIT_FILE_TYPE.rst @@ -0,0 +1,8 @@ +XCODE_EXPLICIT_FILE_TYPE +------------------------ + +Set the Xcode ``explicitFileType`` attribute on its reference to a +target. CMake computes a default based on target type but +can be told explicitly with this property. + +See also :prop_tgt:`XCODE_PRODUCT_TYPE`. diff --git a/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst b/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst new file mode 100644 index 0000000..f4ef5c0 --- /dev/null +++ b/Help/prop_tgt/XCODE_PRODUCT_TYPE.rst @@ -0,0 +1,8 @@ +XCODE_PRODUCT_TYPE +------------------ + +Set the Xcode ``productType`` attribute on its reference to a +target. CMake computes a default based on target type but +can be told explicitly with this property. + +See also :prop_tgt:`XCODE_EXPLICIT_FILE_TYPE`. diff --git a/Help/release/3.8.rst b/Help/release/3.8.rst new file mode 100644 index 0000000..d427a63 --- /dev/null +++ b/Help/release/3.8.rst @@ -0,0 +1,421 @@ +CMake 3.8 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.7 include the following. + +New Features +============ + +Languages +--------- + +C# +^^ + +* CMake learned to support ``CSharp`` (C#) as a first-class language that + can be enabled via the :command:`project` and :command:`enable_language` + commands. It is currently supported by the :ref:`Visual Studio Generators` + for VS 2010 and above. + + C# assemblies and programs can be added just like common C++ targets using + the :command:`add_library` and :command:`add_executable` commands. + References between C# targets in the same source tree may be specified by + :command:`target_link_libraries` like for C++. References to system or + 3rd-party assemblies may be specified by the target properties + :prop_tgt:`VS_DOTNET_REFERENCE_<refname>` and + :prop_tgt:`VS_DOTNET_REFERENCES`. + +* More fine tuning of C# targets may be done using target and source + file properties. Specifically the target properties related to + Visual Studio (``VS_*``) are worth a look (for setting toolset + versions, root namespaces, assembly icons, ...). + +* Auto-linking in ``.csproj`` files: In C#/.NET development with + Visual Studio there are a number of visual editors used which + generate code. Both the generated files and the ones edited + with the UI are connected in the ``.csproj`` file using + ``<DependentUpon>`` tags. If CMake finds within a C# project + any source file with extension ``.Designer.cs`` or ``.xaml.cs``, + it checks sibling files with extension ``.xaml``, ``.settings``, + ``.resx`` or ``.cs`` and establishes the dependency connection. + +CUDA +^^^^ + +* CMake learned to support ``CUDA`` as a first-class language that can be + enabled via the :command:`project` and :command:`enable_language` commands. + +* ``CUDA`` is currently supported by the :ref:`Makefile Generators` + and the :generator:`Ninja` generator on Linux, macOS, and Windows. + Support for the Visual Studio IDE is under development but not + included in this release. + +* The NVIDIA CUDA Toolkit compiler (``nvcc``) is supported. + +C & C++ +^^^^^^^ + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + now offers meta-features that request compiler modes for specific language + standard levels (e.g. ``cxx_std_11``). See + :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES`. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of C++ 17. No specific features are yet enumerated besides + the ``cxx_std_17`` meta-feature. + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of the availability of C99 in gcc since version 3.4. + +Platforms +--------- + +* A new minimal platform file for ``Fuchsia`` was added. + +Generators +---------- + +* The :generator:`CodeBlocks` extra generator may now be used to + generate with :generator:`NMake Makefiles JOM`. + +* 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. + +* The :ref:`Visual Studio Generators` learned to treat files passed to + :command:`target_link_libraries` whose names end in ``.targets`` + as MSBuild "targets" files to be imported into generated project files. + +Commands +-------- + +* The :command:`add_custom_command` and :command:`add_custom_target` commands + learned the option ``COMMAND_EXPAND_LISTS`` which causes lists in the + ``COMMAND`` argument to be expanded, including lists created by generator + expressions. + +* The :command:`execute_process` command gained an ``ENCODING`` option to + specify on Windows which encoding is used for output from child process. + +* The :command:`math(EXPR)` command gained support for unary + ``+`` and ``-`` operators. + +* The :command:`source_group` command gained ``TREE`` and ``PREFIX`` + options to add groups following source tree directory structure. + +* The :command:`string(TIMESTAMP)` command learned to treat ``%%`` + as a way to encode plain ``%``. + +* The :command:`string(TIMESTAMP)` command will now honor the + ``SOURCE_DATE_EPOCH`` environment variable and use its value + instead of the current time. + +* The :command:`try_compile` command source file signature gained new options + to specify the language standard to use in the generated test project. + +* The :command:`try_compile` command source file signature now honors + language standard variables like :variable:`CMAKE_CXX_STANDARD`. + See policy :policy:`CMP0067`. + +Variables +--------- + +* A :variable:`CMAKE_CODELITE_USE_TARGETS` variable was added to tell the + :generator:`CodeLite` extra generator to change the generated project + to have target-centric organization. + The ``build``, ``rebuild``, and ``clean`` operations within ``CodeLite`` + then work on a selected target rather than the whole workspace. + (Note that the :generator:`Ninja` clean operation on a target + includes its dependencies, though.) + +* The :variable:`CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS` variable was added to + tell the :generator:`Sublime Text 2` extra generator to place specified + environment variables in the generated ``.sublime-project``. + +* The :variable:`CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable was added + to tell the :generator:`Sublime Text 2` extra generator whether to exclude + the build tree from the ``.sublime-project`` when it is inside the source + tree. + +* A :variable:`CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD` variable was + added to tell :ref:`Visual Studio Generators` for VS 2010 and above + to include the ``PACKAGE`` target in the default build, similar to + the existing :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` + variable for the ``INSTALL`` target. + +Properties +---------- + +* A :prop_tgt:`BUILD_RPATH` target property and corresponding + :variable:`CMAKE_BUILD_RPATH` variable were added to support custom + ``RPATH`` locations to be added to binaries in the build tree. + +* The :prop_sf:`COMPILE_FLAGS` source file property learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>`. + +* The :prop_tgt:`FRAMEWORK` target property may now also be applied to + static libraries on Apple targets. It will result in a proper + Framework but with a static library inside. + +* :ref:`Imported <Imported Targets>` :ref:`Interface Libraries` learned new + :prop_tgt:`IMPORTED_LIBNAME` and :prop_tgt:`IMPORTED_LIBNAME_<CONFIG>` + target properties to specify a link library name since interface libraries + do not build their own library files. + +* A :prop_tgt:`<LANG>_CPPLINT` target property and supporting + :variable:`CMAKE_<LANG>_CPPLINT` variable were introduced to tell + the :ref:`Makefile Generators` and the :generator:`Ninja` generator to + run the ``cpplint`` style checker along with the compiler for ``C`` and + ``CXX`` languages. + +* A :prop_tgt:`MANUALLY_ADDED_DEPENDENCIES` target property has been added. + It provides a read-only list of dependencies that have been added with + the :command:`add_dependencies` command. + +* 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`. + +* The :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property is now supported + on :ref:`Imported <Imported Targets>` :ref:`Interface Libraries`. + +* New source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, + :prop_sf:`SKIP_AUTORCC`, and :prop_sf:`SKIP_AUTOGEN` were added to allow + source files to be excluded from processing by :prop_tgt:`AUTOMOC`, + :prop_tgt:`AUTOUIC`, and :prop_tgt:`AUTORCC` target properties. + +* A :prop_sf:`VS_COPY_TO_OUT_DIR` source file property was added to + tell :ref:`Visual Studio Generators` for VS 2010 and above whether + or not a file should e copied to the output directory. + +* A :prop_tgt:`VS_DEBUGGER_WORKING_DIRECTORY` target property was added + to tell :ref:`Visual Studio Generators` for VS 2010 and above what + debugger working directory should be set for the target. + +* A :prop_tgt:`VS_DOTNET_REFERENCES_COPY_LOCAL` target property was added + to specify whether to copy referenced assemblies to the output directory. + +* A :prop_tgt:`VS_DOTNET_REFERENCE_<refname>` target property was added + to tell :ref:`Visual Studio Generators` for VS 2010 and above to add + a .NET reference with a given hint path. + +* A :prop_sf:`VS_INCLUDE_IN_VSIX` source file property was added to + tell :ref:`Visual Studio Generators` for VS 2010 and above whether + to include the file in a Visual Studio extension package. + +* A :prop_sf:`VS_RESOURCE_GENERATOR` source file property was added to + give :ref:`Visual Studio Generators` for VS 2010 and above a setting + for the resource generator (``C#`` only). + +* A :prop_tgt:`VS_USER_PROPS` target property was added to tell + :ref:`Visual Studio Generators` for VS 2010 and above to use a + custom MSBuild user ``.props`` file. + +* A :prop_gbl:`XCODE_EMIT_EFFECTIVE_PLATFORM_NAME` global property was + added to tell the :generator:`Xcode` generator whether to emit the + ``EFFECTIVE_PLATFORM_NAME`` variable. This is useful when building + with multiple SDKs like ``macosx`` and ``iphoneos`` in parallel. + +* New :prop_tgt:`XCODE_PRODUCT_TYPE` and :prop_tgt:`XCODE_EXPLICIT_FILE_TYPE` + target properties were created to tell the :generator:`Xcode` generator + to use custom values of the corresponding attributes for a target in the + generated Xcode project. + +Modules +------- + +* 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. + +* The :module:`ExternalProject` module gained the ``GIT_PROGRESS`` option to + force Git to show progress when cloning repositories. + +* The :module:`ExternalProject` module gained a ``GIT_CONFIG`` option + to pass ``--config`` options to Git when cloning repositories. + +* The :module:`FeatureSummary` module :command:`feature_summary` command now + accepts a new ``QUIET_ON_EMPTY`` option that suppresses the output when + the list of packages that belong to the selected category is empty. + +* The :module:`FeatureSummary` module :command:`add_feature_info` command + now accepts lists of dependencies for deciding whether a feature is enabled + or not. + +* The package types accepted by the :module:`FeatureSummary` module can now + be tweaked by changing the :variable:`FeatureSummary_PKG_TYPES`, + :variable:`FeatureSummary_REQUIRED_PKG_TYPES` and + :variable:`FeatureSummary_DEFAULT_PKG_TYPE` global properties. + +* The :module:`FindOpenGL` module now provides imported targets + ``OpenGL::GL`` and ``OpenGL::GLU`` when the libraries are found. + +* The :module:`UseSWIG` module gained a ``swig_add_library`` command + to give more flexibility over the old ``swig_add_module`` command. + +* 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``). + +* The :module:`WriteCompilerDetectionHeader` module gained the + ``ALLOW_UNKNOWN_COMPILERS`` and ``ALLOW_UNKNOWN_COMPILER_VERSIONS`` options + that allow creation of headers that will work also with unknown or old + compilers by simply assuming they do not support any of the requested + features. + +CTest +----- + +* The :command:`ctest_memcheck` command gained a ``DEFECT_COUNT <var>`` + option to capture the number of memory defects detected. + +* The :command:`ctest_memcheck` command learned to read the location of + suppressions files for sanitizers from the + :variable:`CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` variable. + +* The :command:`ctest_memcheck` command learned to support ``LeakSanitizer`` + independently from ``AddressSanitizer``. + +* The :command:`ctest_update` command ``CDASH_UPLOAD`` signature was taught + to honor the ``RETRY_COUNT``, ``RETRY_DELAY``, and ``QUIET`` options. + +CPack +----- + +* The :module:`CPackIFWConfigureFile` module was added to define a new + :command:`cpack_ifw_configure_file` command to configure file templates + prepared in QtIFW/SDK/Creator style. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands gained a new + ``DEFAULT``, ``VIRTUAL``, ``FORCED_INSTALLATION``, ``REQUIRES_ADMIN_RIGHTS``, + ``DISPLAY_NAME``, ``UPDATE_TEXT``, ``DESCRIPTION``, ``RELEASE_DATE``, + ``AUTO_DEPEND_ON`` and ``TRANSLATIONS`` options to more specific + configuration. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` + command gained a new ``DEPENDENCIES`` alias for ``DEPENDS`` option. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component_group` + command gained a new ``DEPENDS`` option. The ``DEPENDENCIES`` alias also + added. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands ``PRIORITY`` + option now is deprecated and will be removed in a future version of CMake. + Please use new ``SORTING_PRIORITY`` option instead. + +* The :module:`CPackIFW` module gained new + :variable:`CPACK_IFW_PACKAGE_WATERMARK`, + :variable:`CPACK_IFW_PACKAGE_BANNER`, + :variable:`CPACK_IFW_PACKAGE_BACKGROUND`, + :variable:`CPACK_IFW_PACKAGE_WIZARD_STYLE`, + :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_WIDTH`, + :variable:`CPACK_IFW_PACKAGE_WIZARD_DEFAULT_HEIGHT`, and + :variable:`CPACK_IFW_PACKAGE_TITLE_COLOR` + variables to customize a QtIFW installer look. + +* The :module:`CPackProductBuild` module gained options to sign packages. + See the variables :variable:`CPACK_PRODUCTBUILD_IDENTITY_NAME`, + :variable:`CPACK_PRODUCTBUILD_KEYCHAIN_PATH`, + :variable:`CPACK_PKGBUILD_IDENTITY_NAME`, and + :variable:`CPACK_PKGBUILD_KEYCHAIN_PATH`. + +* The :module:`CPackRPM` module learned to omit tags that are not supported by + provided ``rpmbuild`` tool. If unsupported tags are set they are ignored + and a developer warning is printed out. + +* 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 packaging is used. + See :variable:`CPACK_RPM_DEBUGINFO_SINGLE_PACKAGE` variable. + +* The :module:`CPackRPM` module learned to support + multiple directives per file when using + :variable:`CPACK_RPM_USER_FILELIST` variable. + +Other +----- + +* CMake functionality using cryptographic hashes now supports SHA-3 algorithms. + +* A new generator expression ``$<IF:cond,true-value,false-value>`` was added. + It resolves to the true-value if the condition is ``1`` and resolves to + the false-value if the condition is ``0``. + +Deprecated and Removed Features +=============================== + +* The :module:`FeatureSummary` module commands :command:`set_package_info`, + :command:`set_feature_info`, :command:`print_enabled_features`, and + :command:`print_disabled_features` are now deprecated. + +* The :module:`UseSWIG` module ``swig_add_module`` command is now + deprecated in favor of ``swig_add_library``. + +Other Changes +============= + +* If a command specified by the :prop_tgt:`<LANG>_CLANG_TIDY` target property + returns non-zero at build time this is now treated as an error instead of + silently ignored. + +* The :command:`ctest_memcheck` command no longer automatically adds + ``leak_check=1`` to the options used by ``AddressSanitizer``. The default + behavior of ``AddressSanitizer`` is to run `LeakSanitizer` to check leaks + unless ``leak_check=0``. + +* The :command:`ctest_memcheck` command was fixed to correctly append extra + sanitizer options read from the + :variable:`CTEST_MEMORYCHECK_SANITIZER_OPTIONS` variable to the environment + variables used internally by the sanitizers. + +* The :module:`FeatureSummary` module :command:`set_package_properties` + command no longer forces the package type to ``OPTIONAL`` when the type + is not explicitly set. + +* 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. + +* Calls to the :module:`FindPkgConfig` module :command:`pkg_check_modules` + command following a successful call learned to re-evaluate the cached values + for a given prefix after changes to the parameters to the command for that + prefix. + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, generated + ``moc_*``, ``*.moc`` and ``ui_*`` are placed in the + ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which + is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + It is therefore not necessary anymore to have + :variable:`CMAKE_CURRENT_BINARY_DIR` in the target's + :prop_tgt:`INCLUDE_DIRECTORIES`. + +* The :generator:`Sublime Text 2` generator no longer runs the native + build command (e.g. ``ninja`` or ``make``) with verbose build output + enabled. + +* The :command:`try_compile` command source file signature now + honors the :variable:`CMAKE_WARN_DEPRECATED` variable value + in the generated test project. + +* The :ref:`Visual Studio Generators` for VS 2010 and above now place + per-source file flags after target-wide flags when they are classified + as raw flags with no project file setting (``AdditionalOptions``). + This behavior is more consistent with the ordering of flags produced + by other generators, and allows flags on more-specific properties + (per-source) to override those on more general ones (per-target). + +* The precompiled Windows binary MSI package provided on ``cmake.org`` now + records the installation directory in the Windows Registry under the key + ``HKLM\Software\Kitware\CMake`` with a value named ``InstallDir``. diff --git a/Help/release/index.rst b/Help/release/index.rst index 25c6c3e..8f0f252 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -11,6 +11,7 @@ Releases .. toctree:: :maxdepth: 1 + 3.8 <3.8> 3.7 <3.7> 3.6 <3.6> 3.5 <3.5> 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_CL_64.rst b/Help/variable/CMAKE_CL_64.rst index a1e86a5..4e80d1f 100644 --- a/Help/variable/CMAKE_CL_64.rst +++ b/Help/variable/CMAKE_CL_64.rst @@ -1,6 +1,7 @@ CMAKE_CL_64 ----------- -Using the 64-bit compiler from Microsoft +Discouraged. Use :variable:`CMAKE_SIZEOF_VOID_P` instead. -Set to ``true`` when using the 64-bit ``cl`` compiler from Microsoft. +Set to a true value when using a Microsoft Visual Studio ``cl`` compiler that +*targets* a 64-bit architecture. diff --git a/Help/variable/CMAKE_CUDA_EXTENSIONS.rst b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst new file mode 100644 index 0000000..4fe758e --- /dev/null +++ b/Help/variable/CMAKE_CUDA_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_EXTENSIONS +--------------------- + +Default value for :prop_tgt:`CUDA_EXTENSIONS` property of targets. + +This variable is used to initialize the :prop_tgt:`CUDA_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_STANDARD.rst b/Help/variable/CMAKE_CUDA_STANDARD.rst new file mode 100644 index 0000000..6c23031 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_STANDARD +------------------- + +Default value for :prop_tgt:`CUDA_STANDARD` property of targets. + +This variable is used to initialize the :prop_tgt:`CUDA_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..935d605 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_CUDA_STANDARD_REQUIRED +---------------------------- + +Default value for :prop_tgt:`CUDA_STANDARD_REQUIRED` property of targets. + +This variable is used to initialize the :prop_tgt:`CUDA_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst new file mode 100644 index 0000000..768f571 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES.rst @@ -0,0 +1,7 @@ +CMAKE_CUDA_TOOLKIT_INCLUDE_DIRECTORIES +-------------------------------------- + +When the ``CUDA`` language has been enabled, this provides a +:ref:`;-list <CMake Language Lists>` of include directories provided +by the CUDA Toolkit. The value may be useful for C++ source files +to include CUDA headers. diff --git a/Help/variable/CMAKE_DL_LIBS.rst b/Help/variable/CMAKE_DL_LIBS.rst index 1fe7641..50d313d 100644 --- a/Help/variable/CMAKE_DL_LIBS.rst +++ b/Help/variable/CMAKE_DL_LIBS.rst @@ -1,7 +1,7 @@ CMAKE_DL_LIBS ------------- -Name of library containing ``dlopen`` and ``dlcose``. +Name of library containing ``dlopen`` and ``dlclose``. The name of the library that has ``dlopen`` and ``dlclose`` in it, usually ``-ldl`` on most UNIX machines. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index ebd616e..0fab10c 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -23,6 +23,7 @@ include: Intel = Intel Compiler (intel.com) MIPSpro = SGI MIPSpro (sgi.com) MSVC = Microsoft Visual Studio (microsoft.com) + NVIDIA = NVIDIA CUDA Compiler (nvidia.com) OpenWatcom = Open Watcom (openwatcom.org) PGI = The Portland Group (pgroup.com) PathScale = PathScale (pathscale.com) diff --git a/Help/variable/CMAKE_LANG_CPPLINT.rst b/Help/variable/CMAKE_LANG_CPPLINT.rst new file mode 100644 index 0000000..3b6f452 --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPLINT.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_CPPLINT +-------------------- + +Default value for :prop_tgt:`<LANG>_CPPLINT` target property. This variable +is used to initialize the property on each target as it is created. This +is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index 36cf75f..aa23b65 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -17,6 +17,8 @@ warn by default: policy :policy:`CMP0065`. * ``CMAKE_POLICY_WARNING_CMP0066`` controls the warning for policy :policy:`CMP0066`. +* ``CMAKE_POLICY_WARNING_CMP0067`` controls the warning for + policy :policy:`CMP0067`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to 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_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst new file mode 100644 index 0000000..693ba45 --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD.rst @@ -0,0 +1,8 @@ +CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD +----------------------------------------- + +Include ``PACKAGE`` target to default build. + +In Visual Studio solution, by default the ``PACKAGE`` target will not be part +of the default build. Setting this variable will enable the ``PACKAGE`` target +to be part of the default build. 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). diff --git a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst index b963293..b8b4c30 100644 --- a/Help/variable/CTEST_MEMORYCHECK_TYPE.rst +++ b/Help/variable/CTEST_MEMORYCHECK_TYPE.rst @@ -4,5 +4,5 @@ CTEST_MEMORYCHECK_TYPE Specify the CTest ``MemoryCheckType`` setting in a :manual:`ctest(1)` dashboard client script. Valid values are ``Valgrind``, ``Purify``, ``BoundsChecker``, and -``ThreadSanitizer``, ``AddressSanitizer``, ``MemorySanitizer``, and +``ThreadSanitizer``, ``AddressSanitizer``, ``LeakSanitizer``, ``MemorySanitizer``, and ``UndefinedBehaviorSanitizer``. |