diff options
Diffstat (limited to 'Help')
171 files changed, 2325 insertions, 333 deletions
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index d038406..1b0aa14 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -225,3 +225,13 @@ of the following is specified: :command:`add_custom_target` command. ``POST_BUILD`` Run after all other rules within the target have been executed. + +.. note:: + Because generator expressions can be used in custom commands, + it is possible to define ``COMMAND`` lines or whole custom commands + which evaluate to empty strings for certain configurations. + For **Visual Studio 2010 (and newer)** generators these command + lines or custom commands will be omitted for the specific + configuration and no "empty-string-command" will be added. + + This allows to add individual build events for every configuration. diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index c088796..c7a30d7 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -7,14 +7,15 @@ Add an executable to the project using the specified source files. add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds an executable target called ``<name>`` to be built from the source -files listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the executable built is constructed based on -conventions of the native platform (such as ``<name>.exe`` or just -``<name>``). +files listed in the command invocation. (The source files can be omitted +here if they are added later using :command:`target_sources`.) The +``<name>`` corresponds to the logical target name and must be globally +unique within a project. The actual file name of the executable built is +constructed based on conventions of the native platform (such as +``<name>.exe`` or just ``<name>``). By default the executable file will be created in the build tree directory corresponding to the source tree directory in which the @@ -73,8 +74,9 @@ properties for more information. Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be used to refer to ``<target>`` in subsequent commands. The ``<name>`` does not appear in the generated buildsystem as a make target. The -``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an -``ALIAS``. ``ALIAS`` targets can be used as targets to read properties +``<target>`` may not be a non-``GLOBAL`` +:ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +``ALIAS`` targets can be used as targets to read properties from, executables for custom commands and custom targets. They can also be tested for existence with the regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used to modify properties of ``<target>``, that diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index de5335e..3706153 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -14,13 +14,14 @@ Normal Libraries add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] - source1 [source2 ...]) + [source1] [source2 ...]) Adds a library target called ``<name>`` to be built from the source files -listed in the command invocation. The ``<name>`` corresponds to the -logical target name and must be globally unique within a project. The -actual file name of the library built is constructed based on -conventions of the native platform (such as ``lib<name>.a`` or +listed in the command invocation. (The source files can be omitted here +if they are added later using :command:`target_sources`.) The ``<name>`` +corresponds to the logical target name and must be globally unique within +a project. The actual file name of the library built is constructed based +on conventions of the native platform (such as ``lib<name>.a`` or ``<name>.lib``). ``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of @@ -110,9 +111,9 @@ may contain only sources that compile, header files, and other files that would not affect linking of a normal library (e.g. ``.txt``). They may contain custom commands generating such sources, but not ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries -cannot be linked. Some native build systems may not like targets that -have only object files, so consider adding at least one real source file -to any target that references ``$<TARGET_OBJECTS:objlib>``. +cannot be linked. Some native build systems (such as Xcode) may not like +targets that have only object files, so consider adding at least one real +source file to any target that references ``$<TARGET_OBJECTS:objlib>``. Alias Libraries ^^^^^^^^^^^^^^^ @@ -124,7 +125,8 @@ Alias Libraries Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be used to refer to ``<target>`` in subsequent commands. The ``<name>`` does not appear in the generated buildsystem as a make target. The ``<target>`` -may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +may not be a non-``GLOBAL`` :ref:`Imported Target <Imported Targets>` or an +``ALIAS``. ``ALIAS`` targets can be used as linkable targets and as targets to read properties from. They can also be tested for existence with the regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used diff --git a/Help/command/add_subdirectory.rst b/Help/command/add_subdirectory.rst index e979253..012ded4 100644 --- a/Help/command/add_subdirectory.rst +++ b/Help/command/add_subdirectory.rst @@ -30,7 +30,7 @@ project that is useful but not necessary, such as a set of examples. Typically the subdirectory should contain its own :command:`project` command invocation so that a full build system will be generated in the subdirectory (such as a VS IDE solution file). Note that inter-target -dependencies supercede this exclusion. If a target built by the +dependencies supersede this exclusion. If a target built by the parent project depends on a target in the subdirectory, the dependee target will be included in the parent project build system to satisfy the dependency. diff --git a/Help/command/cmake_host_system_information.rst b/Help/command/cmake_host_system_information.rst index 9402d57..7199874 100644 --- a/Help/command/cmake_host_system_information.rst +++ b/Help/command/cmake_host_system_information.rst @@ -13,13 +13,34 @@ queried. The list of queried values is stored in ``<variable>``. ``<key>`` can be one of the following values: -:: - - NUMBER_OF_LOGICAL_CORES = Number of logical cores. - NUMBER_OF_PHYSICAL_CORES = Number of physical cores. - HOSTNAME = Hostname. - FQDN = Fully qualified domain name. - TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes. - AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes. - TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes. - AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes. +============================= ================================================ +Key Description +============================= ================================================ +``NUMBER_OF_LOGICAL_CORES`` Number of logical cores +``NUMBER_OF_PHYSICAL_CORES`` Number of physical cores +``HOSTNAME`` Hostname +``FQDN`` Fully qualified domain name +``TOTAL_VIRTUAL_MEMORY`` Total virtual memory in megabytes +``AVAILABLE_VIRTUAL_MEMORY`` Available virtual memory in megabytes +``TOTAL_PHYSICAL_MEMORY`` Total physical memory in megabytes +``AVAILABLE_PHYSICAL_MEMORY`` Available physical memory in megabytes +``IS_64BIT`` One if processor is 64Bit +``HAS_FPU`` One if processor has floating point unit +``HAS_MMX`` One if processor supports MMX instructions +``HAS_MMX_PLUS`` One if porcessor supports Ext. MMX instructions +``HAS_SSE`` One if porcessor supports SSE instructions +``HAS_SSE2`` One if porcessor supports SSE2 instructions +``HAS_SSE_FP`` One if porcessor supports SSE FP instructions +``HAS_SSE_MMX`` One if porcessor supports SSE MMX instructions +``HAS_AMD_3DNOW`` One if porcessor supports 3DNow instructions +``HAS_AMD_3DNOW_PLUS`` One if porcessor supports 3DNow+ instructions +``HAS_IA64`` One if IA64 processor emulating x86 +``HAS_SERIAL_NUMBER`` One if processor has serial number +``PROCESSOR_SERIAL_NUMBER`` Processor serial number +``PROCESSOR_NAME`` Human readable processor name +``PROCESSOR_DESCRIPTION`` Human readable full processor description +``OS_NAME`` See :variable:`CMAKE_HOST_SYSTEM_NAME` +``OS_RELEASE`` The OS sub-type e.g. on Windows ``Professional`` +``OS_VERSION`` The OS build ID +``OS_PLATFORM`` See :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` +============================= ================================================ diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index ec4ffed..b334a89 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -43,15 +43,18 @@ macro which can be followed by more than one value, like e.g. the ``<multi_value_keywords>``. A warning will be emitted if uniqueness is violated. -When done, ``cmake_parse_arguments`` will have defined for each of the +When done, ``cmake_parse_arguments`` will consider for each of the keywords listed in ``<options>``, ``<one_value_keywords>`` and ``<multi_value_keywords>`` a variable composed of the given ``<prefix>`` followed by ``"_"`` and the name of the respective keyword. These -variables will then hold the respective value from the argument list. -For the ``<options>`` keywords this will be ``TRUE`` or ``FALSE``. +variables will then hold the respective value from the argument list +or be undefined if the associated option could not be found. +For the ``<options>`` keywords, these will always be defined, +to ``TRUE`` or ``FALSE``, whether the option is in the argument list or not. All remaining arguments are collected in a variable -``<prefix>_UNPARSED_ARGUMENTS``, this can be checked afterwards to see +``<prefix>_UNPARSED_ARGUMENTS`` that will be undefined if all argument +where recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. As an example here a ``my_install()`` macro, which takes similar arguments @@ -74,16 +77,16 @@ Assume ``my_install()`` has been called like this: my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) -After the ``cmake_parse_arguments`` call the macro will have set the -following variables:: +After the ``cmake_parse_arguments`` call the macro will have set or undefined +the following variables:: MY_INSTALL_OPTIONAL = TRUE - MY_INSTALL_FAST = FALSE (was not used in call to my_install) + MY_INSTALL_FAST = FALSE # was not used in call to my_install MY_INSTALL_DESTINATION = "bin" - MY_INSTALL_RENAME = "" (was not used) + MY_INSTALL_RENAME <UNDEFINED> # was not used MY_INSTALL_TARGETS = "foo;bar" - MY_INSTALL_CONFIGURATIONS = "" (was not used) - MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (nothing expected after "OPTIONAL") + MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used + MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" You can then continue and process these variables. diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 4304f09..e08c573 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -30,9 +30,23 @@ a false constant by the :command:`if` command. The "..." content on the line after the variable name, if any, is processed as above. Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with either ``#define VAR 1`` or ``#define VAR 0`` similarly. +The result lines (with the exception of the ``#undef`` comments) can be +indented using spaces and/or tabs between the ``#`` character +and the ``cmakedefine`` or ``cmakedefine01`` words. This whitespace +indentation will be preserved in the output lines:: + + # cmakedefine VAR + # cmakedefine01 VAR + +will be replaced, if ``VAR`` is defined, with:: + + # define VAR + # define VAR 1 If the input file is modified the build system will re-run CMake to re-configure the file and generate the build system again. +The generated file is modified and its timestamp updated on subsequent +cmake runs only if its content is changed. The arguments are: diff --git a/Help/command/enable_language.rst b/Help/command/enable_language.rst index 4445561..871ac4e 100644 --- a/Help/command/enable_language.rst +++ b/Help/command/enable_language.rst @@ -19,4 +19,5 @@ indirectly through link dependencies. It is simplest to enable all needed languages in the top-level directory of a project. The ``OPTIONAL`` keyword is a placeholder for future implementation and -does not currently work. +does not currently work. Instead you can use the :module:`CheckLanguage` +module to verify support before enabling. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index d617243..799493f 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -10,6 +10,7 @@ Execute one or more child processes. [WORKING_DIRECTORY <directory>] [TIMEOUT <seconds>] [RESULT_VARIABLE <variable>] + [RESULTS_VARIABLE <variable>] [OUTPUT_VARIABLE <variable>] [ERROR_VARIABLE <variable>] [INPUT_FILE <file>] @@ -49,10 +50,16 @@ Options: specified number of seconds (fractions are allowed). ``RESULT_VARIABLE`` - The variable will be set to contain the result of running the processes. + The variable will be set to contain the result of last child process. This will be an integer return code from the last child or a string describing an error condition. +``RESULTS_VARIABLE <variable>`` + The variable will be set to contain the result of all processes as a + :ref:`;-list <CMake Language Lists>`, in order of the given ``COMMAND`` + arguments. Each entry will be an integer return code from the + corresponding child or a string describing an error condition. + ``OUTPUT_VARIABLE``, ``ERROR_VARIABLE`` The variable named will be set with the contents of the standard output and standard error pipes, respectively. If the same variable is named diff --git a/Help/command/file.rst b/Help/command/file.rst index b2e4eea..5ce86e5 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -13,8 +13,11 @@ File manipulation command. Write ``<content>`` into a file called ``<filename>``. If the file does not exist, it will be created. If the file already exists, ``WRITE`` mode will overwrite it and ``APPEND`` mode will append to the end. -(If the file is a build input, use the :command:`configure_file` command -to update the file only when its content changes.) +Any directories in the path specified by ``<filename>`` that do not +exist will be created. + +If the file is a build input, use the :command:`configure_file` command +to update the file only when its content changes. ------------------------------------------------------------------------------ @@ -105,11 +108,9 @@ Generate a list of files that match the ``<globbing-expressions>`` and store it into the ``<variable>``. Globbing expressions are similar to regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given -path. No specific order of results is defined other than that it is -deterministic. If order is important then sort the list explicitly -(e.g. using the :command:`list(SORT)` command). +path. The results will be ordered lexicographically. -By default ``GLOB`` lists directories - directories are omited in result if +By default ``GLOB`` lists directories - directories are omitted in result if ``LIST_DIRECTORIES`` is set to false. .. note:: @@ -231,6 +232,31 @@ Options to both ``DOWNLOAD`` and ``UPLOAD`` are: ``HTTPHEADER <HTTP-header>`` HTTP header for operation. Suboption can be repeated several times. +``NETRC <level>`` + Specify whether the .netrc file is to be used for operation. If this + option is not specified, the value of the ``CMAKE_NETRC`` variable + will be used instead. + Valid levels are: + + ``IGNORED`` + The .netrc file is ignored. + This is the default. + ``OPTIONAL`` + The .netrc file is optional, and information in the URL is preferred. + The file will be scanned to find which ever information is not specified + in the URL. + ``REQUIRED`` + The .netrc file is required, and information in the URL is ignored. + +``NETRC_FILE <file>`` + Specify an alternative .netrc file to the one in your home directory, + if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option + is not specified, the value of the ``CMAKE_NETRC_FILE`` variable will + be used instead. + +If neither ``NETRC`` option is given CMake will check variables +``CMAKE_NETRC`` and ``CMAKE_NETRC_FILE``, respectively. + Additional options to ``DOWNLOAD`` are: ``EXPECTED_HASH ALGO=<value>`` @@ -291,6 +317,8 @@ from the input content to produce the output content. The options are: ``INPUT <input-file>`` Use the content from a given file as input. + A relative path is treated with respect to the value of + :variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`. ``OUTPUT <output-file>`` Specify the output file name to generate. Use generator expressions @@ -298,11 +326,14 @@ from the input content to produce the output content. The options are: name. Multiple configurations may generate the same output file only if the generated content is identical. Otherwise, the ``<output-file>`` must evaluate to an unique name for each configuration. + A relative path (after evaluating generator expressions) is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + See policy :policy:`CMP0070`. Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``. -Generated files are modified on subsequent cmake runs only if their content -is changed. +Generated files are modified and their timestamp updated on subsequent cmake +runs only if their content is changed. Note also that ``file(GENERATE)`` does not create the output file until the generation phase. The output file will not yet have been written when the diff --git a/Help/command/if.rst b/Help/command/if.rst index edd343d..f04f233 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -30,7 +30,7 @@ else and endif clause is optional. Long expressions can be used and there is a traditional order of precedence. Parenthetical expressions are evaluated first followed by unary tests such as ``EXISTS``, ``COMMAND``, and ``DEFINED``. Then any binary tests such as -``EQUAL``, ``LESS``, ``LESS_EQUAL, ``GREATER``, ``GREATER_EQUAL``, +``EQUAL``, ``LESS``, ``LESS_EQUAL``, ``GREATER``, ``GREATER_EQUAL``, ``STREQUAL``, ``STRLESS``, ``STRLESS_EQUAL``, ``STRGREATER``, ``STRGREATER_EQUAL``, ``VERSION_EQUAL``, ``VERSION_LESS``, ``VERSION_LESS_EQUAL``, ``VERSION_GREATER``, ``VERSION_GREATER_EQUAL``, diff --git a/Help/command/include_guard.rst b/Help/command/include_guard.rst new file mode 100644 index 0000000..62cce22 --- /dev/null +++ b/Help/command/include_guard.rst @@ -0,0 +1,46 @@ +include_guard +------------- + +Provides an include guard for the file currently being processed by CMake. + +:: + + include_guard([DIRECTORY|GLOBAL]) + +Sets up an include guard for the current CMake file (see the +:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation). + +CMake will end its processing of the current file at the location of the +:command:`include_guard` command if the current file has already been +processed for the applicable scope (see below). This provides functionality +similar to the include guards commonly used in source headers or to the +``#pragma once`` directive. If the current file has been processed previously +for the applicable scope, the effect is as though :command:`return` had been +called. Do not call this command from inside a function being defined within +the current file. + +An optional argument specifying the scope of the guard may be provided. +Possible values for the option are: + +``DIRECTORY`` + The include guard applies within the current directory and below. The file + will only be included once within this directory scope, but may be included + again by other files outside of this directory (i.e. a parent directory or + another directory not pulled in by :command:`add_subdirectory` or + :command:`include` from the current file or its children). + +``GLOBAL`` + The include guard applies globally to the whole build. The current file + will only be included once regardless of the scope. + +If no arguments given, ``include_guard`` has the same scope as a variable, +meaning that the include guard effect is isolated by the most recent +function scope or current directory if no inner function scopes exist. +In this case the command behavior is the same as: + +.. code-block:: cmake + + if(__CURRENT_FILE_VAR__) + return() + endif() + set(__CURRENT_FILE_VAR__ TRUE) diff --git a/Help/command/install.rst b/Help/command/install.rst index 58438b7..9f9ee13 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -346,7 +346,7 @@ specified that does not match that given to the targets associated with included in the export but a target to which it links is not included the behavior is unspecified. -In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe +In addition to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe used to specifiy an export to the android ndk build system. The Android NDK supports the use of prebuilt libraries, both static and shared. This allows cmake to build the libraries of a project and make them available diff --git a/Help/command/string.rst b/Help/command/string.rst index 4f0c45c..fb3893f 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -132,6 +132,15 @@ APPEND Append all the input arguments to the string. +PREPEND +""""""" + +:: + + string(PREPEND <string variable> [<input>...]) + +Prepend all the input arguments to the string. + CONCAT """""" @@ -315,6 +324,7 @@ specifiers: %j The day of the current year (001-366). %m The month of the current year (01-12). %b Abbreviated month name (e.g. Oct). + %B Full month name (e.g. October). %M The minute of the current hour (00-59). %s Seconds since midnight (UTC) 1-Jan-1970 (UNIX time). %S The second of the current minute. @@ -322,6 +332,7 @@ specifiers: %U The week number of the current year (00-53). %w The day of the current week. 0 is Sunday. (0-6) %a Abbreviated weekday name (e.g. Fri). + %A Full weekday name (e.g. Friday). %y The last two digits of the current year (00-99) %Y The current year. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 8bd3233..3709e7a 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -12,14 +12,15 @@ Add compile definitions to a target. Specify compile definitions to use when compiling a given ``<target>``. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:ref:`Imported Target <Imported Targets>`. +:ref:`ALIAS target <Alias Targets>`. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. The -following arguments specify compile definitions. Repeated calls for the +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile definitions. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_compile_definitions`` may use "generator expressions" diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index b66a4ec..bf413bf 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -18,12 +18,13 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the features. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_FEATURES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``. Repeated -calls for the same ``<target>`` append items. +:prop_tgt:`INTERFACE_COMPILE_FEATURES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +Repeated calls for the same ``<target>`` append items. The named ``<target>`` must have been created by a command such as -:command:`add_executable` or :command:`add_library` and must not be -an ``IMPORTED`` target. +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`ALIAS target <Alias Targets>`. Arguments to ``target_compile_features`` may use "generator expressions" with the syntax ``$<...>``. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 73e01e7..3e7dc47 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -12,8 +12,10 @@ Add compile options to a target. Specify compile options to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:ref:`IMPORTED Target <Imported Targets>`. If ``BEFORE`` is specified, -the content will be prepended to the property instead of being appended. +:ref:`ALIAS target <Alias Targets>`. + +If ``BEFORE`` is specified, the content will be prepended to the property +instead of being appended. This command can be used to add any options, but alternative commands exist to add preprocessor definitions @@ -27,8 +29,9 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. The -following arguments specify compile options. Repeated calls for the same +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify compile options. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_compile_options`` may use "generator expressions" diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 30ec2cb..e71be64 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -12,7 +12,7 @@ Add include directories to a target. Specify include directories to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:prop_tgt:`IMPORTED` target. +:ref:`ALIAS target <Alias Targets>`. If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. @@ -21,9 +21,9 @@ The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` -property of ``<target>``. The following arguments specify include -directories. +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify include directories. Specified include directories may be absolute paths or relative paths. Repeated calls for the same <target> append items in the order called. If diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 30d69f2..2ec8744 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -19,7 +19,8 @@ All of them have the general form:: target_link_libraries(<target> ... <item>... ...) The named ``<target>`` must have been created in the current directory by -a command such as :command:`add_executable` or :command:`add_library`. +a command such as :command:`add_executable` or :command:`add_library` and +must not be an :ref:`ALIAS target <Alias Targets>`. Repeated calls for the same ``<target>`` append items in the order called. Each ``<item>`` may be: diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index d6f148d..a4f5196 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -12,14 +12,15 @@ Add sources to a target. Specify sources to use when compiling a given target. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an -:ref:`IMPORTED Target <Imported Targets>`. +:ref:`ALIAS target <Alias Targets>`. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES` property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. The -following arguments specify sources. Repeated calls for the same +:prop_tgt:`INTERFACE_SOURCES` property of ``<target>``. +(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items.) +The following arguments specify sources. Repeated calls for the same ``<target>`` append items in the order called. Arguments to ``target_sources`` may use "generator expressions" diff --git a/Help/dev/maint.rst b/Help/dev/maint.rst index 78c06df..bdfb3d0 100644 --- a/Help/dev/maint.rst +++ b/Help/dev/maint.rst @@ -8,6 +8,80 @@ See documentation on `CMake Development`_ for more information. .. contents:: Maintainer Processes: +Review a Merge Request +====================== + +The `CMake Review Process`_ requires a maintainer to issue the ``Do: merge`` +command to integrate a merge request. Please check at least the following: + +* If the MR source branch is not named well for the change it makes + (e.g. it is just ``master`` or the patch changed during review), + add a ``Topic-rename: <topic>`` trailing line to the MR description + to provide a better topic name. + +* If the MR introduces a new feature or a user-facing behavior change, + such as a policy, ensure that a ``Help/release/dev/$topic.rst`` file + is added with a release note. + +* If a commit changes a specific area, such as a module, its commit + message should have an ``area:`` prefix on its first line. + +* If a commit fixes a tracked issue, its commit message should have + a trailing line such as ``Fixes: #00000``. + +* Ensure that the MR adds sufficient documentation and test cases. + +* Ensure that the MR has been tested sufficiently. Typically it should + be staged for nightly testing with ``Do: stage``. Then manually + review the `CMake CDash Page`_ to verify that no regressions were + introduced. (Learn to tolerate spurious failures due to idiosyncrasies + of various nightly builders.) + +* Ensure that the MR targets the ``master`` branch. A MR intended for + the ``release`` branch should be based on ``release`` but still merged + to ``master`` first (via ``Do: merge``). A maintainer may then merge + the MR topic to ``release`` manually. + +Maintain Current Release +======================== + +The ``release`` branch is used to maintain the current release or release +candidate. The branch is published with no version number but maintained +using a local branch named ``release-$ver``, where ``$ver`` is the version +number of the current release in the form ``$major.$minor``. It is always +merged into ``master`` before publishing. + +To merge some ``$topic`` branch into ``release``, first create the local +branch: + +.. code-block:: shell + + git fetch origin + git checkout -b release-$ver origin/release + +Merge the ``$topic`` branch into the local ``release-$ver`` branch: + +.. code-block:: shell + + git merge --no-ff $topic + +Merge the ``release-$ver`` branch to ``master``: + +.. code-block:: shell + + git checkout master + git pull + git merge --no-ff release-$ver + +Publish both ``master`` and ``release`` simultaneously: + +.. code-block:: shell + + git push --atomic origin master release-$ver:release + +.. _`CMake Review Process`: review.rst +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake + Branch a New Release ==================== diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 9450bf0..be02a1a 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -185,6 +185,83 @@ commands to ``@kwrobot`` using the form ``Do: ...``: See the corresponding sections for details on permissions and options for each command. +Commit Messages +--------------- + +Part of the human review is to check that each commit message is appropriate. +The first line of the message should begin with one or two words indicating the +area the commit applies to, followed by a colon and then a brief summary. +Committers should aim to keep this first line short. Any subsequent lines +should be separated from the first by a blank line and provide relevant, useful +information. + +Area Prefix on Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The appropriateness of the initial word describing the area the commit applies +to is not something the automatic robot review can judge, so it is up to the +human reviewer to confirm that the area is specified and that it is +appropriate. Good area words include the module name the commit is primarily +fixing, the main C++ source file being edited, ``Help`` for generic +documentation changes or a feature or functionality theme the changes apply to +(e.g. ``server`` or ``Autogen``). Examples of suitable first lines of a commit +message include: + +* ``Help: Fix example in cmake-buildsystem(7) manual`` +* ``FindBoost: Add support for 1.64`` +* ``Autogen: Extended mocInclude tests`` +* ``cmLocalGenerator: Explain standard flag selection logic in comments`` + +Referencing Issues in Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the commit fixes a particular reported issue, this information should +ideally also be part of the commit message. The recommended way to do this is +to place a line at the end of the message in the form ``Fixes: #xxxxx`` where +``xxxxx`` is the GitLab issue number and to separate it from the rest of the +text by a blank line. For example:: + + Help: Fix FooBar example robustness issue + + FooBar supports option X, but the example provided + would not work if Y was also specified. + + Fixes: #12345 + +GitLab will automatically create relevant links to the merge request and will +close the issue when the commit is merged into master. GitLab understands a few +other synonyms for ``Fixes`` and allows much more flexible forms than the +above, but committers should aim for this format for consistency. Note that +such details can alternatively be specified in the merge request description. + +Referencing Commits in Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The preferred form for references to other commits is +``commit <commit> (<subject>, <date>)``, where: + +* ``<commit>``: + If available, a tag-relative name of the commit produced by + ``git describe --contains <commit-ish>``. Otherwise, the first + 8-10 characters of the commit ``<hash>``. + +* ``<subject>``: + The first line of the commit message. + +* ``<date>``: + The author date of the commit, in its original time zone, formatted as + ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. + +Alternatively, the full commit ``<hash>`` may be used. + +Revising Commit Messages +^^^^^^^^^^^^^^^^^^^^^^^^ + +Reviewers are encouraged to ask the committer to amend commit messages to +follow these guidelines, but prefer to focus on the changes themselves as a +first priority. Maintainers will also make a check of commit messages before +merging. + Topic Testing ============= diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 7e44995..d0c19eb 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -23,24 +23,12 @@ format only a subset of files, such as those that are locally modified. C++ Subset Permitted ==================== -CMake supports compiling as C++98 in addition to C++11 and C++14. -In order to support building on older toolchains some constructs -need to be handled with care: +CMake requires compiling as C++11 or above. However, in order to support +building on older toolchains some constructs need to be handled with care: -* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``. +* Do not use ``std::auto_ptr``. - The ``std::auto_ptr`` template is deprecated in C++11. We want to use it - so we can build on C++98 compilers but we do not want to turn off compiler - warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR`` - macro instead. - -* Use ``CM_EQ_DELETE;`` instead of ``= delete;``. - - Defining functions as *deleted* is not supported in C++98. Using - ``CM_EQ_DELETE`` will delete the functions if the compiler supports it and - give them no implementation otherwise. Calling such a function will lead - to compiler errors if the compiler supports *deleted* functions and linker - errors otherwise. + The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``. * Use ``CM_DISABLE_COPY(Class)`` to mark classes as non-copyable. @@ -58,3 +46,50 @@ need to be handled with care: When assigning the result of ``.size()`` on a container for example, the result should be assigned to ``size_t`` not to ``std::size_t``, ``unsigned int`` or similar types. + +Source Tree Layout +================== + +The CMake source tree is organized as follows. + +* ``Auxiliary/``: + Shell and editor integration files. + +* ``Help/``: + Documentation. + + * ``Help/dev/``: + Developer documentation. + + * ``Help/release/dev/``: + Release note snippets for development since last release. + +* ``Licenses/``: + License files for third-party libraries in binary distributions. + +* ``Modules/``: + CMake language modules installed with CMake. + +* ``Packaging/``: + Files used for packaging CMake itself for distribution. + +* ``Source/``: + Source code of CMake itself. + +* ``Templates/``: + Files distributed with CMake as implementation details for generators, + packagers, etc. + +* ``Tests/``: + The test suite. See `Tests/README.rst`_. + +* ``Utilities/``: + Scripts, third-party source code. + + * ``Utilities/Sphinx/``: + Sphinx configuration to build CMake user documentation. + + * ``Utilities/Release/``: + Scripts used to package CMake itself for distribution on ``cmake.org``. + +.. _`Tests/README.rst`: ../../Tests/README.rst diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst index 731930c..1b29acf 100644 --- a/Help/dev/testing.rst +++ b/Help/dev/testing.rst @@ -16,7 +16,7 @@ welcome to provide testing machines in order to help keep support for their platforms working. The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive -nightly, continous, and experimental testing of CMake. Use the following +nightly, continuous, and experimental testing of CMake. Use the following commands to set up a new integration testing client: .. code-block:: console diff --git a/Help/envvar/ASM_DIALECT.rst b/Help/envvar/ASM_DIALECT.rst new file mode 100644 index 0000000..ec48f71 --- /dev/null +++ b/Help/envvar/ASM_DIALECT.rst @@ -0,0 +1,11 @@ +ASM<DIALECT> +------------ + +Preferred executable for compiling a specific dialect of assembly language +files. ``ASM<DIALECT>`` can be ``ASM``, ``ASM_NASM``, ``ASM_MASM`` or +``ASM-ATT``. Will only be used by CMake on the first configuration to determine +``ASM<DIALECT>`` compiler, after which the value for ``ASM<DIALECT>`` is stored +in the cache as +:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. For subsequent +configuration runs, the environment variable will be ignored in favor of +:variable:`CMAKE_ASM<DIALECT>_COMPILER <CMAKE_<LANG>_COMPILER>`. diff --git a/Help/envvar/ASM_DIALECTFLAGS.rst b/Help/envvar/ASM_DIALECTFLAGS.rst new file mode 100644 index 0000000..4ed02fe --- /dev/null +++ b/Help/envvar/ASM_DIALECTFLAGS.rst @@ -0,0 +1,11 @@ +ASM<DIALECT>FLAGS +----------------- + +Default compilation flags to be used when compiling a specific dialect of an +assembly language. ``ASM<DIALECT>FLAGS`` can be ``ASMFLAGS``, ``ASM_NASMFLAGS``, +``ASM_MASMFLAGS`` or ``ASM-ATTFLAGS``. Will only be used by CMake on the +first configuration to determine ``ASM<DIALECT>`` default compilation flags, after +which the value for ``ASM<DIALECT>FLAGS`` is stored in the cache as +:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_ASM<DIALECT>_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CC.rst b/Help/envvar/CC.rst new file mode 100644 index 0000000..7e68110 --- /dev/null +++ b/Help/envvar/CC.rst @@ -0,0 +1,9 @@ +CC +-- + +Preferred executable for compiling ``C`` language files. Will only be used by +CMake on the first configuration to determine ``C`` compiler, after which the +value for ``CC`` is stored in the cache as +:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_C_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CFLAGS.rst b/Help/envvar/CFLAGS.rst new file mode 100644 index 0000000..60b2cd3 --- /dev/null +++ b/Help/envvar/CFLAGS.rst @@ -0,0 +1,9 @@ +CFLAGS +------ + +Default compilation flags to be used when compiling ``C`` files. Will only be +used by CMake on the first configuration to determine ``CC`` default compilation +flags, after which the value for ``CFLAGS`` is stored in the cache +as :variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_C_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CMAKE_CONFIG_TYPE.rst b/Help/envvar/CMAKE_CONFIG_TYPE.rst new file mode 100644 index 0000000..1306b47 --- /dev/null +++ b/Help/envvar/CMAKE_CONFIG_TYPE.rst @@ -0,0 +1,5 @@ +CMAKE_CONFIG_TYPE +----------------- + +The default build configuration for :ref:`Build Tool Mode` and +``ctest`` build handler when there is no explicit configuration given. diff --git a/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 0000000..54d5f9e --- /dev/null +++ b/Help/envvar/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,8 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +Extra PATH locations for custom commands when using +:generator:`Visual Studio 9 2008` (or above) generators. + +The ``CMAKE_MSVCIDE_RUN_PATH`` environment variable sets the default value for +the :variable:`CMAKE_MSVCIDE_RUN_PATH` variable if not already explicitly set. diff --git a/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst new file mode 100644 index 0000000..8bbf993 --- /dev/null +++ b/Help/envvar/CMAKE_OSX_ARCHITECTURES.rst @@ -0,0 +1,8 @@ +CMAKE_OSX_ARCHITECTURES +----------------------- + +Target specific architectures for OS X. + +The ``CMAKE_OSX_ARCHITECTURES`` environment variable sets the default value for +the :variable:`CMAKE_OSX_ARCHITECTURES` variable. See +:prop_tgt:`OSX_ARCHITECTURES` for more information. diff --git a/Help/envvar/CSFLAGS.rst b/Help/envvar/CSFLAGS.rst new file mode 100644 index 0000000..251ddc5 --- /dev/null +++ b/Help/envvar/CSFLAGS.rst @@ -0,0 +1,9 @@ +CSFLAGS +------- + +Preferred executable for compiling ``CSharp`` language files. Will only be +used by CMake on the first configuration to determine ``CSharp`` default +compilation flags, after which the value for ``CSFLAGS`` is stored in the cache +as :variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CSharp_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst new file mode 100644 index 0000000..25ed14f --- /dev/null +++ b/Help/envvar/CTEST_INTERACTIVE_DEBUG_MODE.rst @@ -0,0 +1,5 @@ +CTEST_INTERACTIVE_DEBUG_MODE +---------------------------- + +Environment variable that will exist and be set to ``1`` when a test executed +by CTest is run in interactive mode. diff --git a/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst new file mode 100644 index 0000000..1fcf42b --- /dev/null +++ b/Help/envvar/CTEST_OUTPUT_ON_FAILURE.rst @@ -0,0 +1,7 @@ +CTEST_OUTPUT_ON_FAILURE +----------------------- + +Boolean environment variable that controls if the output should be logged for +failed tests. Set the value to 1, True, or ON to enable output on failure. +See :manual:`ctest(1)` for more information on controlling output of failed +tests. diff --git a/Help/envvar/CTEST_PARALLEL_LEVEL.rst b/Help/envvar/CTEST_PARALLEL_LEVEL.rst new file mode 100644 index 0000000..c767a01 --- /dev/null +++ b/Help/envvar/CTEST_PARALLEL_LEVEL.rst @@ -0,0 +1,5 @@ +CTEST_PARALLEL_LEVEL +-------------------- + +Specify the number of tests for CTest to run in parallel. See :manual:`ctest(1)` +for more information on parallel test execution. diff --git a/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst new file mode 100644 index 0000000..8d8eea5 --- /dev/null +++ b/Help/envvar/CTEST_USE_LAUNCHERS_DEFAULT.rst @@ -0,0 +1,4 @@ +CTEST_USE_LAUNCHERS_DEFAULT +--------------------------- + +Initializes the :variable:`CTEST_USE_LAUNCHERS` variable if not already defined. diff --git a/Help/envvar/CUDACXX.rst b/Help/envvar/CUDACXX.rst new file mode 100644 index 0000000..8a5fd4b --- /dev/null +++ b/Help/envvar/CUDACXX.rst @@ -0,0 +1,9 @@ +CUDACXX +------- + +Preferred executable for compiling ``CUDA`` language files. Will only be used by +CMake on the first configuration to determine ``CUDA`` compiler, after which the +value for ``CUDA`` is stored in the cache as +:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CUDA_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CUDAFLAGS.rst b/Help/envvar/CUDAFLAGS.rst new file mode 100644 index 0000000..3dff49f --- /dev/null +++ b/Help/envvar/CUDAFLAGS.rst @@ -0,0 +1,9 @@ +CUDAFLAGS +--------- + +Default compilation flags to be used when compiling ``CUDA`` files. Will only be +used by CMake on the first configuration to determine ``CUDA`` default +compilation flags, after which the value for ``CUDAFLAGS`` is stored in the +cache as :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_CUDA_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/CUDAHOSTCXX.rst b/Help/envvar/CUDAHOSTCXX.rst new file mode 100644 index 0000000..f0f94f6 --- /dev/null +++ b/Help/envvar/CUDAHOSTCXX.rst @@ -0,0 +1,9 @@ +CUDAHOSTCXX +----------- + +Preferred executable for compiling host code when compiling ``CUDA`` +language files. Will only be used by CMake on the first configuration to +determine ``CUDA`` host compiler, after which the value for ``CUDAHOSTCXX`` is +stored in the cache as :variable:`CMAKE_CUDA_HOST_COMPILER`. For any +configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE_CUDA_HOST_COMPILER` variable is defined. diff --git a/Help/envvar/CXX.rst b/Help/envvar/CXX.rst new file mode 100644 index 0000000..3b1e445 --- /dev/null +++ b/Help/envvar/CXX.rst @@ -0,0 +1,9 @@ +CXX +--- + +Preferred executable for compiling ``CXX`` language files. Will only be used by +CMake on the first configuration to determine ``CXX`` compiler, after which the +value for ``CXX`` is stored in the cache as +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration +run (including the first), the environment variable will be ignored if the +:variable:`CMAKE_CXX_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/CXXFLAGS.rst b/Help/envvar/CXXFLAGS.rst new file mode 100644 index 0000000..8b58abd --- /dev/null +++ b/Help/envvar/CXXFLAGS.rst @@ -0,0 +1,9 @@ +CXXFLAGS +-------- + +Default compilation flags to be used when compiling ``CXX`` (C++) files. Will +only be used by CMake on the first configuration to determine ``CXX`` default +compilation flags, after which the value for ``CXXFLAGS`` is stored in the cache +as :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration run ( +including the first), the environment variable will be ignored if +the :variable:`CMAKE_CXX_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst new file mode 100644 index 0000000..fab1c0c --- /dev/null +++ b/Help/envvar/DASHBOARD_TEST_FROM_CTEST.rst @@ -0,0 +1,5 @@ +DASHBOARD_TEST_FROM_CTEST +------------------------- + +Environment variable that will exist when a test executed by CTest is run +in non-interactive mode. The value will be equal to :variable:`CMAKE_VERSION`. diff --git a/Help/envvar/FC.rst b/Help/envvar/FC.rst new file mode 100644 index 0000000..7d293fd --- /dev/null +++ b/Help/envvar/FC.rst @@ -0,0 +1,10 @@ +FC +-- + +Preferred executable for compiling ``Fortran`` language files. Will only be used +by CMake on the first configuration to determine ``Fortran`` compiler, after +which the value for ``Fortran`` is stored in the cache as +:variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>`. For any +configuration run (including the first), the environment variable will be +ignored if the :variable:`CMAKE_Fortran_COMPILER <CMAKE_<LANG>_COMPILER>` +variable is defined. diff --git a/Help/envvar/FFLAGS.rst b/Help/envvar/FFLAGS.rst new file mode 100644 index 0000000..19d6169 --- /dev/null +++ b/Help/envvar/FFLAGS.rst @@ -0,0 +1,9 @@ +FFLAGS +------ + +Default compilation flags to be used when compiling ``Fortran`` files. Will only +be used by CMake on the first configuration to determine ``Fortran`` default +compilation flags, after which the value for ``FFLAGS`` is stored in the cache +as :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>`. For any configuration +run (including the first), the environment variable will be ignored if +the :variable:`CMAKE_Fortran_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/envvar/LDFLAGS.rst b/Help/envvar/LDFLAGS.rst new file mode 100644 index 0000000..52da99c --- /dev/null +++ b/Help/envvar/LDFLAGS.rst @@ -0,0 +1,10 @@ +LDFLAGS +------- + +Will only be used by CMake on the first configuration to determine the default +linker flags, after which the value for ``LDFLAGS`` is stored in the cache +as :variable:`CMAKE_EXE_LINKER_FLAGS_INIT`, +:variable:`CMAKE_SHARED_LINKER_FLAGS_INIT`, and +:variable:`CMAKE_MODULE_LINKER_FLAGS_INIT`. For any configuration run +(including the first), the environment variable will be ignored if the +equivalent ``CMAKE_<TYPE>_LINKER_FLAGS_INIT`` variable is defined. diff --git a/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst new file mode 100644 index 0000000..e6051b4 --- /dev/null +++ b/Help/envvar/MACOSX_DEPLOYMENT_TARGET.rst @@ -0,0 +1,8 @@ +MACOSX_DEPLOYMENT_TARGET +------------------------ + +Specify the minimum version of OS X on which the target binaries are +to be deployed. + +The ``MACOSX_DEPLOYMENT_TARGET`` environment variable sets the default value for +the :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` variable. diff --git a/Help/envvar/RC.rst b/Help/envvar/RC.rst new file mode 100644 index 0000000..6c2db19 --- /dev/null +++ b/Help/envvar/RC.rst @@ -0,0 +1,9 @@ +RC +-- + +Preferred executable for compiling ``resource`` files. Will only be used by CMake +on the first configuration to determine ``resource`` compiler, after which the +value for ``RC`` is stored in the cache as +:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>`. For any configuration run +(including the first), the environment variable will be ignored if the +:variable:`CMAKE_RC_COMPILER <CMAKE_<LANG>_COMPILER>` variable is defined. diff --git a/Help/envvar/RCFLAGS.rst b/Help/envvar/RCFLAGS.rst new file mode 100644 index 0000000..4f2f31c --- /dev/null +++ b/Help/envvar/RCFLAGS.rst @@ -0,0 +1,9 @@ +RCFLAGS +------- + +Default compilation flags to be used when compiling ``resource`` files. Will +only be used by CMake on the first configuration to determine ``resource`` +default compilation flags, after which the value for ``RCFLAGS`` is stored in +the cache as :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>`. For any +configuration run (including the first), the environment variable will be ignored +if the :variable:`CMAKE_RC_FLAGS <CMAKE_<LANG>_FLAGS>` variable is defined. diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index d03cb0c..06cc746 100644 --- a/Help/generator/CodeBlocks.rst +++ b/Help/generator/CodeBlocks.rst @@ -6,7 +6,11 @@ Generates CodeBlocks project files. Project files for CodeBlocks will be created in the top directory and in every subdirectory which features a CMakeLists.txt file containing a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the +into the build tree. +The :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable may +be set to ``ON`` to exclude any files which are located outside of +the project root directory. +The appropriate make program can build the project through the default make target. A "make install" target is also provided. diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 2ac0449..2cf1aa0 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -19,13 +19,17 @@ Instance Selection ^^^^^^^^^^^^^^^^^^ VS 2017 supports multiple installations on the same machine. -CMake queries the Visual Studio Installer to locate VS instances. -If more than one instance is installed we do not define which one -is chosen by default. If the ``VS150COMNTOOLS`` environment variable -is set and points to the ``Common7/Tools`` directory within one of -the instances, that instance will be used. The environment variable -must remain consistently set whenever CMake is re-run within a given -build tree. +The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a +cache entry containing the absolute path to a Visual Studio instance. +If the value is not specified explicitly by the user or a toolchain file, +CMake queries the Visual Studio Installer to locate VS instances, chooses +one, and sets the variable as a cache entry to hold the value persistently. + +When CMake first chooses an instance, if the ``VS150COMNTOOLS`` environment +variable is set and points to the ``Common7/Tools`` directory within +one of the instances, that instance will be used. Otherwise, if more +than one instance is installed we do not define which one is chosen +by default. Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/index.rst b/Help/index.rst index 97cd107..3dccdda 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -40,6 +40,7 @@ Reference Manuals /manual/cmake-qt.7 /manual/cmake-toolchains.7 /manual/cmake-variables.7 + /manual/cmake-env-variables.7 .. only:: html or text diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 95f5b87..ae538ed 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -266,7 +266,7 @@ The :command:`target_link_libraries` command has ``PRIVATE``, Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the usage requirements of it are propagated to ``consumer`` too. Because -``serialization`` is a ``PRIVATE`` dependency of ``archive``, the usage +``serialization`` is a ``PRIVATE`` dependency of ``archiveExtras``, the usage requirements of it are not propagated to ``consumer``. Generally, a dependency should be specified in a use of @@ -687,7 +687,8 @@ property are treated as ``SYSTEM`` include directories, as if they were listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the dependency. This can result in omission of compiler warnings for headers found in those directories. This behavior for :ref:`imported targets` may -be controlled with the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property. +be controlled by setting the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target +property on the *consumers* of imported targets. If a binary target is linked transitively to a Mac OX framework, the ``Headers`` directory of the framework is also treated as a usage requirement. @@ -970,7 +971,6 @@ are: * ``EXPORT_NAME`` * ``IMPORTED`` * ``NAME`` -* ``NO_SYSTEM_FROM_IMPORTED`` * Properties matching ``IMPORTED_LIBNAME_*`` * Properties matching ``MAP_IMPORTED_CONFIG_*`` diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index 611c989..f8bfb32 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -44,6 +44,7 @@ These commands are always available. /command/get_property /command/if /command/include + /command/include_guard /command/list /command/macro /command/mark_as_advanced diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst new file mode 100644 index 0000000..fed129e --- /dev/null +++ b/Help/manual/cmake-env-variables.7.rst @@ -0,0 +1,54 @@ +.. cmake-manual-description: CMake Environment Variables Reference + +cmake-env-variables(7) +********************** + +.. only:: html + + .. contents:: + +Environment Variables that Control the Build +============================================ + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_CONFIG_TYPE + /envvar/CMAKE_MSVCIDE_RUN_PATH + /envvar/CMAKE_OSX_ARCHITECTURES + /envvar/LDFLAGS + /envvar/MACOSX_DEPLOYMENT_TARGET + +Environment Variables for Languages +=================================== + +.. toctree:: + :maxdepth: 1 + + /envvar/ASM_DIALECT + /envvar/ASM_DIALECTFLAGS + /envvar/CC + /envvar/CFLAGS + /envvar/CSFLAGS + /envvar/CUDACXX + /envvar/CUDAFLAGS + /envvar/CUDAHOSTCXX + /envvar/CXX + /envvar/CXXFLAGS + /envvar/FC + /envvar/FFLAGS + /envvar/RC + /envvar/RCFLAGS + +Environment Variables for CTest +=============================== + +.. toctree:: + :maxdepth: 1 + + /envvar/CMAKE_CONFIG_TYPE + /envvar/CTEST_INTERACTIVE_DEBUG_MODE + /envvar/CTEST_OUTPUT_ON_FAILURE + /envvar/CTEST_PARALLEL_LEVEL + /envvar/CTEST_USE_LAUNCHERS_DEFAULT + /envvar/DASHBOARD_TEST_FROM_CTEST diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bddb174..dc5621a 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -97,7 +97,7 @@ Available logical expressions are: compile features and a list of supported compilers. ``$<COMPILE_LANGUAGE:lang>`` ``1`` when the language used for compilation unit matches ``lang``, - otherwise ``0``. This expression used to specify compile options for + otherwise ``0``. This expression may be used to specify compile options for source files of a particular language in a target. For example, to specify the use of the ``-fno-exceptions`` compile option (compiler id checks elided): @@ -109,10 +109,12 @@ Available logical expressions are: PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> ) - This generator expression has limited use because it is not possible to - use it with the Visual Studio generators. Portable buildsystems would - not use this expression, and would create separate libraries for each - source file language instead: + Note that with :ref:`Visual Studio Generators` there is no way to represent + target-wide flags separately for ``C`` and ``CXX`` languages. Under these + generators, target-wide flags for both C and C++ sources will be evaluated + using ``CXX`` if there are any C++ sources and otherwise using ``C``. + A workaround is to create separate libraries for each source file language + instead: .. code-block:: cmake diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 27b5d30..87f8f9d 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -183,18 +183,18 @@ same length: .. productionlist:: bracket_argument: `bracket_open` `bracket_content` `bracket_close` - bracket_open: '[' '='{len} '[' - bracket_content: <any text not containing a `bracket_close` - : of the same {len} as the `bracket_open`> - bracket_close: ']' '='{len} ']' + bracket_open: '[' '='* '[' + bracket_content: <any text not containing a `bracket_close` with + : the same number of '=' as the `bracket_open`> + bracket_close: ']' '='* ']' .. raw:: latex \end{small} -An opening bracket of length *len >= 0* is written ``[`` followed -by *len* ``=`` followed by ``[`` and the corresponding closing -bracket is written ``]`` followed by *len* ``=`` followed by ``]``. +An opening bracket is written ``[`` followed by zero or more ``=`` followed +by ``[``. The corresponding closing bracket is written ``]`` followed +by the same number of ``=`` followed by ``]``. Brackets do not nest. A unique length may always be chosen for the opening and closing brackets to contain closing brackets of other lengths. @@ -334,6 +334,8 @@ For example: 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. + They may instead be written as quoted arguments ``"-Da=\"b c\""``, + ``"-Da=$(v)"``, and ``"a\" \"b\"c\"d"``, respectively. Make-style references are treated literally as part of the content and do not undergo variable expansion. They are treated as part @@ -514,7 +516,7 @@ Function Scope create commands that, when invoked, process the recorded commands in a new variable binding scope. A variable "set" or "unset" binds in this scope and is visible for the current function and - any nested calls, but not after the function returns. + any nested calls within it, but not after the function returns. Directory Scope Each of the `Directories`_ in a source tree has its own variable diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 4a03b7a..694bae5 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -60,6 +60,7 @@ All Modules /module/CPackCygwin /module/CPackDeb /module/CPackDMG + /module/CPackFreeBSD /module/CPackIFW /module/CPackIFWConfigureFile /module/CPackNSIS @@ -79,6 +80,7 @@ All Modules /module/ExternalData /module/ExternalProject /module/FeatureSummary + /module/FetchContent /module/FindALSA /module/FindArmadillo /module/FindASPELL @@ -128,6 +130,7 @@ All Modules /module/FindIcotool /module/FindICU /module/FindImageMagick + /module/FindIconv /module/FindIntl /module/FindITK /module/FindJasper @@ -152,6 +155,7 @@ All Modules /module/FindMPEG2 /module/FindMPEG /module/FindMPI + /module/FindOpenACC /module/FindOpenAL /module/FindOpenCL /module/FindOpenGL @@ -181,6 +185,7 @@ All Modules /module/FindosgWidget /module/FindPackageHandleStandardArgs /module/FindPackageMessage + /module/FindPatch /module/FindPerlLibs /module/FindPerl /module/FindPHP4 diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 7b85817..96d5c7d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,23 @@ 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.11 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072> + +Policies Introduced by CMake 3.10 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0071: Let AUTOMOC and AUTOUIC process GENERATED files. </policy/CMP0071> + CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070> + Policies Introduced by CMake 3.9 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index ec25596..2c63c4b 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -74,6 +74,7 @@ Properties on Directories /prop_dir/INCLUDE_REGULAR_EXPRESSION /prop_dir/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_dir/INTERPROCEDURAL_OPTIMIZATION + /prop_dir/LABELS /prop_dir/LINK_DIRECTORIES /prop_dir/LISTFILE_STACK /prop_dir/MACROS @@ -83,7 +84,7 @@ Properties on Directories /prop_dir/RULE_LAUNCH_LINK /prop_dir/SOURCE_DIR /prop_dir/SUBDIRECTORIES - /prop_dir/TEST_INCLUDE_FILE + /prop_dir/TEST_INCLUDE_FILES /prop_dir/VARIABLES /prop_dir/VS_GLOBAL_SECTION_POST_section /prop_dir/VS_GLOBAL_SECTION_PRE_section @@ -121,7 +122,9 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_BUILD_DIR /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC_COMPILER_PREDEFINES /prop_tgt/AUTOMOC_DEPEND_FILTERS + /prop_tgt/AUTOMOC_MACRO_NAMES /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC @@ -181,6 +184,7 @@ Properties on Targets /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM /prop_tgt/IMPORTED_CONFIGURATIONS + /prop_tgt/IMPORTED_GLOBAL /prop_tgt/IMPORTED_IMPLIB_CONFIG /prop_tgt/IMPORTED_IMPLIB /prop_tgt/IMPORTED_LIBNAME_CONFIG @@ -225,6 +229,7 @@ Properties on Targets /prop_tgt/LABELS /prop_tgt/LANG_CLANG_TIDY /prop_tgt/LANG_COMPILER_LAUNCHER + /prop_tgt/LANG_CPPCHECK /prop_tgt/LANG_CPPLINT /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_VISIBILITY_PRESET @@ -291,6 +296,7 @@ Properties on Targets /prop_tgt/VS_DEBUGGER_WORKING_DIRECTORY /prop_tgt/VS_DESKTOP_EXTENSIONS_VERSION /prop_tgt/VS_DOTNET_REFERENCE_refname + /prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname /prop_tgt/VS_DOTNET_REFERENCES /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION @@ -385,10 +391,14 @@ Properties on Source Files /prop_sf/VS_DEPLOYMENT_LOCATION /prop_sf/VS_INCLUDE_IN_VSIX /prop_sf/VS_RESOURCE_GENERATOR + /prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS + /prop_sf/VS_SHADER_ENABLE_DEBUG /prop_sf/VS_SHADER_ENTRYPOINT /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL + /prop_sf/VS_SHADER_OUTPUT_HEADER_FILE /prop_sf/VS_SHADER_TYPE + /prop_sf/VS_SHADER_VARIABLE_NAME /prop_sf/VS_TOOL_OVERRIDE.rst /prop_sf/VS_XAML_TYPE /prop_sf/WRAP_EXCLUDE @@ -434,6 +444,7 @@ Deprecated Properties on Directories :maxdepth: 1 /prop_dir/COMPILE_DEFINITIONS_CONFIG + /prop_dir/TEST_INCLUDE_FILE Deprecated Properties on Targets diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index 00d6e6e..cafeae1 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -59,9 +59,10 @@ The :prop_tgt:`AUTOMOC` target property controls whether :manual:`cmake(1)` inspects the C++ files in the target to determine if they require ``moc`` to be run, and to create rules to execute ``moc`` at the appropriate time. -If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` -will be run on the file. The result will be put into a file named according -to ``moc_<basename>.cpp``. If the macro is found in a C++ implementation +If a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is found in a header file, +``moc`` will be run on the file. The result will be put into a file named +according to ``moc_<basename>.cpp``. +If the macro is found in a C++ implementation file, the moc output will be put into a file named according to ``<basename>.moc``, following the Qt conventions. The ``<basename>.moc`` must be included by the user in the C++ implementation file with a preprocessor @@ -70,7 +71,11 @@ be included by the user in the C++ implementation file with a preprocessor Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the ``<AUTOGEN_BUILD_DIR>/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.) + +* This differs from CMake 3.7 and below; see their documentation for details. + +* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. * See :prop_tgt:`AUTOGEN_BUILD_DIR`. @@ -91,6 +96,8 @@ following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. +Additional macro names to search for can be added to :prop_tgt:`AUTOMOC_MACRO_NAMES`. + Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. @@ -107,15 +114,26 @@ inspects the C++ files in the target to determine if they require ``uic`` to be run, and to create rules to execute ``uic`` at the appropriate time. 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. The ``<basename>.ui`` file is -searched for first in the vicinity of including file and afterwards in the -optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. +``<path>ui_<basename>.h``, and a ``<basename>.ui`` file exists, +then ``uic`` will be executed to generate the appropriate file. +The ``<basename>.ui`` file is searched for in the following places + +1. ``<source_dir>/<basename>.ui`` +2. ``<source_dir>/<path><basename>.ui`` +3. ``<AUTOUIC_SEARCH_PATHS>/<basename>.ui`` +4. ``<AUTOUIC_SEARCH_PATHS>/<path><basename>.ui`` + +where ``<source_dir>`` is the directory of the C++ file and +:prop_tgt:`AUTOUIC_SEARCH_PATHS` is a list of additional search paths. The generated generated ``ui_*.h`` files are placed in the ``<AUTOGEN_BUILD_DIR>/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.) + +* This differs from CMake 3.7 and below; see their documentation for details. + +* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. * See :prop_tgt:`AUTOGEN_BUILD_DIR`. @@ -195,6 +213,24 @@ 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`. +Visual Studio Generators +======================== + +When using the :manual:`Visual Studio generators <cmake-generators(7)>` +CMake tries to use a ``PRE_BUILD`` +:command:`custom command <add_custom_command>` instead +of a :command:`custom target <add_custom_target>` for autogen. +``PRE_BUILD`` can't be used when the autogen target depends on files. +This happens when + +- :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` is enabled and the origin target + depends on :prop_sf:`GENERATED` files which aren't excluded from autogen by + :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` + or :policy:`CMP0071` +- :prop_tgt:`AUTORCC` is enabled and a ``.qrc`` file is listed in + the origin target sources +- :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file + qtmain.lib on Windows ===================== diff --git a/Help/manual/cmake-server.7.rst b/Help/manual/cmake-server.7.rst index 9520cc1..c2aef99 100644 --- a/Help/manual/cmake-server.7.rst +++ b/Help/manual/cmake-server.7.rst @@ -254,6 +254,11 @@ versions supported by the cmake server. These are JSON objects with "major" and as experimental. These will contain the "isExperimental" key set to true. Enabling these requires a special command line argument when starting the cmake server mode. +Within a "major" version all "minor" versions are fully backwards compatible. +New "minor" versions may introduce functionality in such a way that existing +clients of the same "major" version will continue to work, provided they +ignore keys in the output that they do not know about. + Example:: [== "CMake Server" ==[ @@ -268,8 +273,13 @@ The first request that the client may send to the server is of type "handshake". This request needs to pass one of the "supportedProtocolVersions" of the "hello" type response received earlier back to the server in the "protocolVersion" field. +Giving the "major" version of the requested protocol version will make the server +use the latest minor version of that protocol. Use this if you do not explicitly +need to depend on a specific minor version. -Each protocol version may request additional attributes to be present. +If the build directory already contains a CMake cache, it is sufficient to set +the "buildDirectory" attribute. To create a fresh build directory, additional +attributes are required depending on the protocol version. Protocol version 1.0 requires the following attributes to be set: @@ -448,6 +458,11 @@ Each project object can have the following keys: "name" contains the (sub-)projects name. +"minimumCMakeVersion" + contains the minimum cmake version allowed for this project, null if the + project doesn't specify one. +"hasInstallRule" + true if the project contains any install rules, false otherwise. "sourceDirectory" contains the current source directory "buildDirectory" @@ -471,6 +486,12 @@ Each target object can have the following keys: contains the current source directory. "buildDirectory" contains the current build directory. +"isGeneratorProvided" + true if the target is auto-created by a generator, false otherwise +"hasInstallRule" + true if the target contains any install rules, false otherwise. +"installPaths" + full path to the destination directories defined by target install rules. "artifacts" with a list of build artifacts. The list is sorted with the most important artifacts first (e.g. a .DLL file is listed before a @@ -496,6 +517,9 @@ Each target object can have the following keys: with the sysroot path. "fileGroups" contains the source files making up the target. +"crossReferences" + contains the location of the target in the corresponding CMakeLists.txt + file and the locations of the related statements like "target_link_libraries" FileGroups are used to group sources using similar settings together. @@ -521,6 +545,16 @@ Each fileGroup object may contain the following keys: All file paths in the fileGroup are either absolute or relative to the sourceDirectory of the target. +CrossReferences object is used to report the location of the target (including +the entire call stack if the target is defined in a function) and the related +"target_link_libraries", "target_include_directories", "target_compile_definitions" +and "target_compile_options" statements. + +See the example below for details on the internal format of the "crossReferences" object. +Line numbers stated in the "backtrace" entries are 1-based. The last entry of a backtrace +is a special entry with missing "line" and "name" fields that specifies the initial +CMakeLists.txt file. + Example:: [== "CMake Server" ==[ @@ -557,7 +591,34 @@ CMake will reply:: "linkerLanguage": "C", "name": "cmForm", "sourceDirectory": "/home/code/src/cmake/Source/CursesDialog/form", - "type": "STATIC_LIBRARY" + "type": "STATIC_LIBRARY", + "crossReferences": { + "backtrace": [ + { + "line": 7, + "name": "add_executable", + "path": "C:/full/path/CMakeLists.txt" + }, + { + "path": "c:/full/path/CMakeLists.txt" + } + ], + "relatedStatements": [ + { + "backtrace": [ + { + "line": 8, + "name": "target_link_libraries", + "path": "c:/full/path/CMakeLists.txt" + }, + { + "path": "c:/full/path/CMakeLists.txt" + } + ], + "type": "target_link_libraries" + } + ] + } } ] }, @@ -572,6 +633,62 @@ CMake will reply:: ]== "CMake Server" ==] +Type "ctestInfo" +^^^^^^^^^^^^^^^^ + +The "ctestInfo" request can be used after a project was "compute"d successfully. + +It will list the complete project test structure as it is known to cmake. + +The reply will contain a key "configurations", which will contain a list of +configuration objects. Configuration objects are used to destinquish between +different configurations the build directory might have enabled. While most +generators only support one configuration, others might support several. + +Each configuration object can have the following keys: + +"name" + contains the name of the configuration. The name may be empty. +"projects" + contains a list of project objects, one for each build project. + +Project objects define one (sub-)project defined in the cmake build system. + +Each project object can have the following keys: + +"name" + contains the (sub-)projects name. +"ctestInfo" + contains a list of test objects. + +Each test object can have the following keys: + +"ctestName" + contains the name of the test. +"ctestCommand" + contains the test command. +"properties" + contains a list of test property objects. +"backtrace" + contains a list of backtrace objects that specify where the test was defined. + +Each backtrace object can have the following keys: + +"path" + contains the full path to the file containing the statement. +"line" + contains the line number in the file where the statement was defined. +"name" + contains the name of the statement that added the test. + +Each test property object can have the following keys: + +"key" + contains the test property key. +"value" + contains the test property value. + + Type "cmakeInputs" ^^^^^^^^^^^^^^^^^^ @@ -616,8 +733,7 @@ and will not survive the build directory getting cleaned out. Type "cache" ^^^^^^^^^^^^ -The "cache" request can be used once a project is configured and will -list the cached configuration values. +The "cache" request will list the cached configuration values. Example:: diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 1a2726d..735b93b 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -32,6 +32,7 @@ Variables that Provide Information /variable/CMAKE_CURRENT_LIST_FILE /variable/CMAKE_CURRENT_LIST_LINE /variable/CMAKE_CURRENT_SOURCE_DIR + /variable/CMAKE_DIRECTORY_LABELS /variable/CMAKE_DL_LIBS /variable/CMAKE_EDIT_COMMAND /variable/CMAKE_EXECUTABLE_SUFFIX @@ -41,6 +42,7 @@ Variables that Provide Information /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION /variable/CMAKE_FIND_PACKAGE_SORT_ORDER /variable/CMAKE_GENERATOR + /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET /variable/CMAKE_HOME_DIRECTORY @@ -48,6 +50,7 @@ Variables that Provide Information /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_JOB_POOLS /variable/CMAKE_LANG_COMPILER_AR /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LINK_LIBRARY_SUFFIX @@ -59,6 +62,8 @@ Variables that Provide Information /variable/CMAKE_MATCH_n /variable/CMAKE_MINIMUM_REQUIRED_VERSION /variable/CMAKE_MINOR_VERSION + /variable/CMAKE_NETRC + /variable/CMAKE_NETRC_FILE /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION @@ -120,6 +125,8 @@ Variables that Change Behavior /variable/CMAKE_AUTOMOC_RELAXED_MODE /variable/CMAKE_BACKWARDS_COMPATIBILITY /variable/CMAKE_BUILD_TYPE + /variable/CMAKE_CODEBLOCKS_COMPILER_ID + /variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES /variable/CMAKE_CODELITE_USE_TARGETS /variable/CMAKE_COLOR_MAKEFILE /variable/CMAKE_CONFIGURATION_TYPES @@ -154,6 +161,7 @@ Variables that Change Behavior /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME + /variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT @@ -183,6 +191,7 @@ Variables that Change Behavior /variable/CMAKE_USER_MAKE_RULES_OVERRIDE /variable/CMAKE_WARN_DEPRECATED /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY Variables that Describe the System ================================== @@ -268,7 +277,9 @@ Variables that Control the Build /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_AUTOMOC + /variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /variable/CMAKE_AUTOMOC_MACRO_NAMES /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS @@ -281,6 +292,7 @@ Variables that Control the Build /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX + /variable/CMAKE_CUDA_SEPARABLE_COMPILATION /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_ENABLE_EXPORTS /variable/CMAKE_EXE_LINKER_FLAGS @@ -300,6 +312,7 @@ Variables that Control the Build /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_CLANG_TIDY /variable/CMAKE_LANG_COMPILER_LAUNCHER + /variable/CMAKE_LANG_CPPCHECK /variable/CMAKE_LANG_CPPLINT /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE /variable/CMAKE_LANG_VISIBILITY_PRESET @@ -319,6 +332,7 @@ Variables that Control the Build /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT /variable/CMAKE_MODULE_LINKER_FLAGS_INIT + /variable/CMAKE_MSVCIDE_RUN_PATH /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH /variable/CMAKE_NO_SYSTEM_FROM_IMPORTED @@ -362,6 +376,7 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 + /variable/CMAKE_CUDA_HOST_COMPILER /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_STANDARD /variable/CMAKE_CUDA_STANDARD_REQUIRED @@ -386,11 +401,14 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_COMPILER /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED + /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION + /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE @@ -480,6 +498,7 @@ Variables for CTest /variable/CTEST_GIT_UPDATE_OPTIONS /variable/CTEST_HG_COMMAND /variable/CTEST_HG_UPDATE_OPTIONS + /variable/CTEST_LABELS_FOR_SUBPROJECTS /variable/CTEST_MEMORYCHECK_COMMAND /variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS /variable/CTEST_MEMORYCHECK_SANITIZER_OPTIONS @@ -514,6 +533,7 @@ Variables for CPack /variable/CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY /variable/CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CPACK_INCLUDE_TOPLEVEL_DIRECTORY + /variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS /variable/CPACK_INSTALL_SCRIPT /variable/CPACK_PACKAGING_INSTALL_PREFIX /variable/CPACK_SET_DESTDIR diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index ba925e8..ff8c6c7 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -11,6 +11,7 @@ Synopsis cmake [<options>] (<path-to-source> | <path-to-existing-build>) cmake [(-D <var>=<value>)...] -P <cmake-script-file> cmake --build <dir> [<options>...] [-- <build-tool-options>...] + cmake --open <dir> cmake -E <command> [<options>...] cmake --find-package <options>... @@ -51,6 +52,10 @@ Options ``--build <dir>`` See `Build Tool Mode`_. +``--open <dir>`` + Open the generated project in the associated application. This is + only supported by some generators. + ``-N`` View mode only. @@ -69,11 +74,11 @@ Options See `Find-Package Tool Mode`_. ``--graphviz=[file]`` - Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more. + Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more. Generate a graphviz input file that will contain all the library and executable dependencies in the project. See the documentation for - CMakeGraphVizOptions.cmake for more details. + :module:`CMakeGraphVizOptions` for more details. ``--system-information [file]`` Dump information about this system. @@ -138,6 +143,8 @@ Options .. include:: OPTIONS_HELP.txt +.. _`Build Tool Mode`: + Build Tool Mode =============== @@ -262,6 +269,36 @@ Available commands are: 351abe79cd3800b38cdfb25d45015a15 file1.txt 052f86c15bbde68af55c7f7b340ab639 file2.txt +``sha1sum <file>...`` + Create SHA1 checksum of files in ``sha1sum`` compatible format:: + + 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt + 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt + +``sha224sum <file>...`` + Create SHA224 checksum of files in ``sha224sum`` compatible format:: + + b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt + 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt + +``sha256sum <file>...`` + Create SHA256 checksum of files in ``sha256sum`` compatible format:: + + 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt + 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt + +``sha384sum <file>...`` + Create SHA384 checksum of files in ``sha384sum`` compatible format:: + + acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt + 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt + +``sha512sum <file>...`` + Create SHA512 checksum of files in ``sha512sum`` compatible format:: + + 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt + 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt + ``remove [-f] <file>...`` Remove the file(s). If any of the listed files already do not exist, the command returns a non-zero exit code, but no message diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index a89c4e9..d9af3bc 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -3,12 +3,18 @@ ctest(1) ******** +.. contents:: + Synopsis ======== .. parsed-literal:: ctest [<options>] + ctest <path-to-source> <path-to-build> --build-generator <generator> + [<options>...] [-- <build-options>...] [--test-command <test>] + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] Description =========== @@ -55,17 +61,21 @@ Options ``-F`` Enable failover. - This option allows ctest to resume a test set execution that was + This option allows CTest to resume a test set execution that was previously interrupted. If no interruption occurred, the ``-F`` option will have no effect. ``-j <jobs>, --parallel <jobs>`` Run the tests in parallel using the given number of jobs. - This option tells ctest to run the tests in parallel using given - number of jobs. This option can also be set by setting the + This option tells CTest to run the tests in parallel using given + number of jobs. This option can also be set by setting the environment variable ``CTEST_PARALLEL_LEVEL``. + This option can be used with the :prop_test:`PROCESSORS` test property. + + See `Label and Subproject Summary`_. + ``--test-load <level>`` While running tests in parallel (e.g. with ``-j``), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -74,7 +84,7 @@ Options ``TestLoad`` option of the `CTest Test Step`_. ``-Q,--quiet`` - Make ctest quiet. + Make CTest quiet. This option will suppress all the output. The output log file will still be generated if the ``--output-log`` is specified. Options such @@ -84,37 +94,37 @@ Options ``-O <file>, --output-log <file>`` Output to log file. - This option tells ctest to write all its output to a log file. + This option tells CTest to write all its output to a log file. ``-N,--show-only`` Disable actual execution of tests. - This option tells ctest to list the tests that would be run but not + This option tells CTest to list the tests that would be run but not actually run them. Useful in conjunction with the ``-R`` and ``-E`` options. ``-L <regex>, --label-regex <regex>`` Run tests with labels matching regular expression. - This option tells ctest to run only the tests whose labels match the + This option tells CTest to run only the tests whose labels match the given regular expression. ``-R <regex>, --tests-regex <regex>`` Run tests matching regular expression. - This option tells ctest to run only the tests whose names match the + This option tells CTest to run only the tests whose names match the given regular expression. ``-E <regex>, --exclude-regex <regex>`` Exclude tests matching regular expression. - This option tells ctest to NOT run the tests whose names match the + This option tells CTest to NOT run the tests whose names match the given regular expression. ``-LE <regex>, --label-exclude <regex>`` Exclude tests with labels matching regular expression. - This option tells ctest to NOT run the tests whose labels match the + This option tells CTest to NOT run the tests whose labels match the given regular expression. ``-FA <regex>, --fixture-exclude-any <regex>`` @@ -137,11 +147,13 @@ Options ``-D <dashboard>, --dashboard <dashboard>`` Execute dashboard test. - This option tells ctest to act as a CDash client and perform a + This option tells CTest to act as a CDash client and perform a dashboard test. All tests are <Mode><Test>, where Mode can be Experimental, Nightly, and Continuous, and Test can be Start, Update, Configure, Build, Test, Coverage, and Submit. + See `Dashboard Client`_. + ``-D <var>:<type>=<value>`` Define a variable for script mode. @@ -153,35 +165,33 @@ Options ``-M <model>, --test-model <model>`` Sets the model for a dashboard. - This option tells ctest to act as a CDash client where the ``<model>`` + This option tells CTest to act as a CDash client where the ``<model>`` can be ``Experimental``, ``Nightly``, and ``Continuous``. Combining ``-M`` and ``-T`` is similar to ``-D``. + See `Dashboard Client`_. + ``-T <action>, --test-action <action>`` Sets the dashboard action to perform. - This option tells ctest to act as a CDash client and perform some + This option tells CTest to act as a CDash client and perform some action such as ``start``, ``build``, ``test`` etc. See `Dashboard Client Steps`_ for the full list of actions. Combining ``-M`` and ``-T`` is similar to ``-D``. -``--track <track>`` - Specify the track to submit dashboard to - - Submit dashboard to specified track instead of default one. By - default, the dashboard is submitted to Nightly, Experimental, or - Continuous track, but by specifying this option, the track can be - arbitrary. + See `Dashboard Client`_. ``-S <script>, --script <script>`` Execute a dashboard for a configuration. - This option tells ctest to load in a configuration script which sets + This option tells CTest to load in a configuration script which sets a number of parameters such as the binary and source directories. - Then ctest will do what is required to create and run a dashboard. + Then CTest will do what is required to create and run a dashboard. This option basically sets up a dashboard and then runs ``ctest -D`` with the appropriate options. + See `Dashboard Client`_. + ``-SP <script>, --script-new-process <script>`` Execute a dashboard for a configuration. @@ -190,16 +200,12 @@ Options script may modify the environment and you do not want the modified environment to impact other ``-S`` scripts. -``-A <file>, --add-notes <file>`` - Add a notes file with submission. - - This option tells ctest to include a notes file when submitting - dashboard. + See `Dashboard Client`_. ``-I [Start,End,Stride,test#,test#|Test file], --tests-information`` Run a specific number of tests by number. - This option causes ctest to run tests starting at number Start, + This option causes CTest to run tests starting at number Start, ending at number End, and incrementing by Stride. Any additional numbers after Stride are considered individual test numbers. Start, End,or stride can be empty. Optionally a file can be given that @@ -214,11 +220,11 @@ Options ``--rerun-failed`` Run only the tests that failed previously. - This option tells ctest to perform only the tests that failed during - its previous run. When this option is specified, ctest ignores all + This option tells CTest to perform only the tests that failed during + its previous run. When this option is specified, CTest ignores all other options intended to modify the list of tests to run (``-L``, ``-R``, ``-E``, ``-LE``, ``-I``, etc). In the event that CTest runs and no tests - fail, subsequent calls to ctest with the ``--rerun-failed`` option will run + fail, subsequent calls to CTest with the ``--rerun-failed`` option will run the set of tests that most recently failed (if any). ``--repeat-until-fail <n>`` @@ -236,7 +242,7 @@ Options ``--interactive-debug-mode [0|1]`` Set the interactive mode to 0 or 1. - This option causes ctest to run tests in either an interactive mode + This option causes CTest to run tests in either an interactive mode or a non-interactive mode. On Windows this means that in non-interactive mode, all system debug pop up windows are blocked. In dashboard mode (Experimental, Nightly, Continuous), the default @@ -246,29 +252,111 @@ Options ``--no-label-summary`` Disable timing summary information for labels. - This option tells ctest not to print summary information for each + This option tells CTest not to print summary information for each label associated with the tests run. If there are no labels on the tests, nothing extra is printed. -``--build-and-test <path-to-source> <path-to-build>`` - Configure, build and run a test. + See `Label and Subproject Summary`_. + +``--no-subproject-summary`` + Disable timing summary information for subprojects. + + This option tells CTest not to print summary information for each + subproject associated with the tests run. If there are no subprojects on the + tests, nothing extra is printed. + + See `Label and Subproject Summary`_. + +``--build-and-test`` +See `Build and Test Mode`_. + +``--test-output-size-passed <size>`` + Limit the output for passed tests to ``<size>`` bytes. + +``--test-output-size-failed <size>`` + Limit the output for failed tests to ``<size>`` bytes. + +``--overwrite`` + Overwrite CTest configuration option. + + By default CTest uses configuration options from configuration file. + This option will overwrite the configuration option. + +``--force-new-ctest-process`` + Run child CTest instances as new processes. + + By default CTest will run child CTest instances within the same + process. If this behavior is not desired, this argument will + enforce new processes for child CTest processes. + +``--schedule-random`` + Use a random order for scheduling tests. + + This option will run the tests in a random order. It is commonly + used to detect implicit dependencies in a test suite. + +``--submit-index`` + Legacy option for old Dart2 dashboard server feature. + Do not use. + +``--timeout <seconds>`` + Set a global timeout on all tests. + + This option will set a global timeout on all tests that do not + already have a timeout set on them. + +``--stop-time <time>`` + Set a time at which all tests should stop running. - This option tells ctest to configure (i.e. run cmake on), build, - and or execute a test. The configure and test steps are optional. - The arguments to this command line are the source and binary - directories. - The ``--build-generator`` option *must* be provided to use - ``--build-and-test``. If ``--test-command`` is specified then that will be - run after the build is complete. Other options that affect this - mode are ``--build-target``, ``--build-nocmake``, ``--build-run-dir``, - ``--build-two-config``, ``--build-exe-dir``, - ``--build-project``, ``--build-noclean`` and ``--build-options``. + Set a real time of day at which all tests should timeout. Example: + ``7:00:00 -0400``. Any time format understood by the curl date parser + is accepted. Local time is assumed if no timezone is specified. + +``--print-labels`` + Print all available test labels. + + This option will not run any tests, it will simply print the list of + all labels associated with the test set. + +.. include:: OPTIONS_HELP.txt + +.. _`Label and Subproject Summary`: + +Label and Subproject Summary +============================ + +CTest prints timing summary information for each label and subproject +associated with the tests run. The label time summary will not include labels +that are mapped to subprojects. + +When the :prop_test:`PROCESSORS` test property is set, CTest will display a +weighted test timing result in label and subproject summaries. The wall clock +time for the test run will be multiplied by this property to give a better +idea of how much cpu resource CTest allocated for the test. The time is +reported with `sec*proc` instead of just `sec`. + +.. _`Build and Test Mode`: + +Build and Test Mode +=================== + +CTest provides a command-line signature to to configure (i.e. run cmake on), +build, and or execute a test:: + + ctest --build-and-test <path-to-source> <path-to-build> + --build-generator <generator> [<options>...] [-- <build-options>...] + [--test-command <test>] + +The configure and test steps are optional. The arguments to this command line +are the source and binary directories. The ``--build-generator`` option *must* +be provided to use ``--build-and-test``. If ``--test-command`` is specified +then that will be run after the build is complete. Other options that affect +this mode include: ``--build-target`` Specify a specific target to build. - This option goes with the ``--build-and-test`` option, if left out the - ``all`` target is built. + If left out the ``all`` target is built. ``--build-nocmake`` Run the build without running cmake first. @@ -317,67 +405,47 @@ Options ``--test-command`` The test to run with the ``--build-and-test`` option. -``--test-output-size-passed <size>`` - Limit the output for passed tests to ``<size>`` bytes. - -``--test-output-size-failed <size>`` - Limit the output for failed tests to ``<size>`` bytes. - ``--test-timeout`` - The time limit in seconds, internal use only. - -``--tomorrow-tag`` - Nightly or experimental starts with next day tag. - - This is useful if the build will not finish in one day. - -``--ctest-config`` - The configuration file used to initialize CTest state when submitting dashboards. - - This option tells CTest to use different initialization file instead - of CTestConfiguration.tcl. This way multiple initialization files - can be used for example to submit to multiple dashboards. + The time limit in seconds -``--overwrite`` - Overwrite CTest configuration option. +.. _`Dashboard Client`: - By default ctest uses configuration options from configuration file. - This option will overwrite the configuration option. +Dashboard Client +================ -``--extra-submit <file>[;<file>]`` - Submit extra files to the dashboard. +CTest can operate as a client for the `CDash`_ software quality dashboard +application. As a dashboard client, CTest performs a sequence of steps +to configure, build, and test software, and then submits the results to +a `CDash`_ server. The command-line signature used to submit to `CDash`_ is:: - This option will submit extra files to the dashboard. + ctest (-D <dashboard> | -M <model> -T <action> | -S <script> | -SP <script>) + [-- <dashboard-options>...] -``--force-new-ctest-process`` - Run child CTest instances as new processes. +Options for Dashboard Client include: - By default CTest will run child CTest instances within the same - process. If this behavior is not desired, this argument will - enforce new processes for child CTest processes. +``--track <track>`` + Specify the track to submit dashboard to -``--schedule-random`` - Use a random order for scheduling tests. + Submit dashboard to specified track instead of default one. By + default, the dashboard is submitted to Nightly, Experimental, or + Continuous track, but by specifying this option, the track can be + arbitrary. - This option will run the tests in a random order. It is commonly - used to detect implicit dependencies in a test suite. +``-A <file>, --add-notes <file>`` + Add a notes file with submission. -``--submit-index`` - Legacy option for old Dart2 dashboard server feature. - Do not use. + This option tells CTest to include a notes file when submitting + dashboard. -``--timeout <seconds>`` - Set a global timeout on all tests. +``--tomorrow-tag`` + Nightly or experimental starts with next day tag. - This option will set a global timeout on all tests that do not - already have a timeout set on them. + This is useful if the build will not finish in one day. -``--stop-time <time>`` - Set a time at which all tests should stop running. +``--extra-submit <file>[;<file>]`` + Submit extra files to the dashboard. - Set a real time of day at which all tests should timeout. Example: - ``7:00:00 -0400``. Any time format understood by the curl date parser - is accepted. Local time is assumed if no timezone is specified. + This option will submit extra files to the dashboard. ``--http1.0`` Submit using HTTP 1.0. @@ -392,26 +460,6 @@ Options this to maintain compatibility with an older version of CDash which doesn't support compressed test output. -``--print-labels`` - Print all available test labels. - - This option will not run any tests, it will simply print the list of - all labels associated with the test set. - -.. include:: OPTIONS_HELP.txt - -.. _`Dashboard Client`: - -Dashboard Client -================ - -CTest can operate as a client for the `CDash`_ software quality dashboard -application. As a dashboard client, CTest performs a sequence of steps -to configure, build, and test software, and then submits the results to -a `CDash`_ server. - -.. _`CDash`: http://cdash.org/ - Dashboard Client Steps ---------------------- @@ -724,7 +772,6 @@ Configuration settings to specify the version control tool include: * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY` - Additional configuration settings include: ``NightlyStartTime`` @@ -758,6 +805,16 @@ Configuration settings include: * :module:`CTest` module variable: :variable:`CMAKE_COMMAND` followed by :variable:`PROJECT_SOURCE_DIR` +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. + .. _`CTest Build Step`: CTest Build Step @@ -780,6 +837,16 @@ Configuration settings include: * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, initialized by the ``CMAKE_CONFIG_TYPE`` environment variable +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. + ``MakeCommand`` Command-line to launch the software build process. It will be executed in the location specified by the @@ -815,6 +882,16 @@ Arguments to the command may specify some of the step settings. Configuration settings include: +``LabelsForSubprojects`` + Specify a semicolon-separated list of labels that will be treated as + subprojects. This mapping will be passed on to CDash when configure, test or + build results are submitted. + + * `CTest Script`_ variable: :variable:`CTEST_LABELS_FOR_SUBPROJECTS` + * :module:`CTest` module variable: ``CTEST_LABELS_FOR_SUBPROJECTS`` + + See `Label and Subproject Summary`_. + ``TestLoad`` While running tests in parallel (e.g. with ``-j``), try not to start tests when they may cause the CPU load to pass above a given threshold. @@ -853,6 +930,8 @@ Configuration settings include: * `CTest Script`_ variable: :variable:`CTEST_COVERAGE_EXTRA_FLAGS` * :module:`CTest` module variable: ``COVERAGE_EXTRA_FLAGS`` + These options are the first arguments passed to ``CoverageCommand``. + .. _`CTest MemCheck Step`: CTest MemCheck Step @@ -1047,3 +1126,5 @@ See Also ======== .. include:: LINKS.txt + +.. _`CDash`: http://cdash.org/ diff --git a/Help/module/CPackFreeBSD.rst b/Help/module/CPackFreeBSD.rst new file mode 100644 index 0000000..083f0cb --- /dev/null +++ b/Help/module/CPackFreeBSD.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CPackFreeBSD.cmake diff --git a/Help/module/FetchContent.rst b/Help/module/FetchContent.rst new file mode 100644 index 0000000..c130a6d --- /dev/null +++ b/Help/module/FetchContent.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FetchContent.cmake diff --git a/Help/module/FindIconv.rst b/Help/module/FindIconv.rst new file mode 100644 index 0000000..c1f3ed0 --- /dev/null +++ b/Help/module/FindIconv.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindIconv.cmake diff --git a/Help/module/FindOpenACC.rst b/Help/module/FindOpenACC.rst new file mode 100644 index 0000000..dda3308 --- /dev/null +++ b/Help/module/FindOpenACC.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenACC.cmake diff --git a/Help/module/FindPatch.rst b/Help/module/FindPatch.rst new file mode 100644 index 0000000..ba5e910 --- /dev/null +++ b/Help/module/FindPatch.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindPatch.cmake diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index 9f8457c..8041960 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -14,7 +14,12 @@ character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS targets and IMPORTED targets may contain two consequtive colons. Target names reserved by one or more CMake generators are not allowed. -Among others these include "all", "help" and "test". +Among others these include "all", "clean", "help", and "install". + +Target names associated with optional features, such as "test" and "package", +may also be reserved. CMake 3.10 and below always reserve them. CMake 3.11 +and above reserve them only when the corresponding feature is enabled +(e.g. by including the :module:`CTest` or :module:`CPack` modules). The OLD behavior for this policy is to allow creating targets with reserved names or which do not match the validity pattern. diff --git a/Help/policy/CMP0040.rst b/Help/policy/CMP0040.rst index d46baf6..0afe589 100644 --- a/Help/policy/CMP0040.rst +++ b/Help/policy/CMP0040.rst @@ -2,7 +2,7 @@ CMP0040 ------- The target in the ``TARGET`` signature of :command:`add_custom_command` -must exist and must be defined in current directory. +must exist and must be defined in the current directory. CMake 2.8.12 and lower silently ignored a custom command created with the ``TARGET`` signature of :command:`add_custom_command` diff --git a/Help/policy/CMP0070.rst b/Help/policy/CMP0070.rst new file mode 100644 index 0000000..0fb3617 --- /dev/null +++ b/Help/policy/CMP0070.rst @@ -0,0 +1,25 @@ +CMP0070 +------- + +Define :command:`file(GENERATE)` behavior for relative paths. + +CMake 3.10 and newer define that relative paths given to ``INPUT`` and +``OUTPUT`` arguments of ``file(GENERATE)`` are interpreted relative to the +current source and binary directories, respectively. CMake 3.9 and lower did +not define any behavior for relative paths but did not diagnose them either +and accidentally treated them relative to the process working directory. +Policy ``CMP0070`` provides compatibility with projects that used the old +undefined behavior. + +This policy affects behavior of relative paths given to ``file(GENERATE)``. +The ``OLD`` behavior for this policy is to treat the paths relative to the +working directory of CMake. The ``NEW`` behavior for this policy is to +interpret relative paths with respect to the current source or binary +directory of the caller. + +This policy was introduced in CMake version 3.10. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0071.rst b/Help/policy/CMP0071.rst new file mode 100644 index 0000000..ee33aa1 --- /dev/null +++ b/Help/policy/CMP0071.rst @@ -0,0 +1,42 @@ +CMP0071 +------- + +Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process +:prop_sf:`GENERATED` files. + +Since version 3.10, CMake processes **regular** and :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. +In earlier CMake versions, only **regular** source files were processed. +:prop_sf:`GENERATED` source files were ignored silently. + +This policy affects how source files that are :prop_sf:`GENERATED` +get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``OLD`` behavior for this policy is to ignore :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`. + +The ``NEW`` behavior for this policy is to process :prop_sf:`GENERATED` +source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like regular +source files. + +.. note:: + + To silence the CMP0071 warning source files can be excluded from + :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the + source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or + :prop_sf:`SKIP_AUTOGEN`. + +Source skip example:: + + # ... + set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON) + set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON) + # ... + +This policy was introduced in CMake version 3.10. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0072.rst b/Help/policy/CMP0072.rst new file mode 100644 index 0000000..3abbad7 --- /dev/null +++ b/Help/policy/CMP0072.rst @@ -0,0 +1,26 @@ +CMP0072 +------- + +:module:`FindOpenGL` prefers GLVND by default when available. + +The :module:`FindOpenGL` module provides an ``OpenGL::GL`` target and an +``OPENGL_LIBRARIES`` variable for projects to use for legacy GL interfaces. +When both a legacy GL library (e.g. ``libGL.so``) and GLVND libraries +for OpenGL and GLX (e.g. ``libOpenGL.so`` and ``libGLX.so``) are available, +the module must choose between them. It documents an ``OpenGL_GL_PREFERENCE`` +variable that can be used to specify an explicit preference. When no such +preference is set, the module must choose a default preference. + +CMake 3.11 and above prefer to choose GLVND libraries. This policy provides +compatibility with projects that expect the legacy GL library to be used. + +The ``OLD`` behavior for this policy is to set ``OpenGL_GL_PREFERENCE`` to +``LEGACY``. The ``NEW`` behavior for this policy is to set +``OpenGL_GL_PREFERENCE`` to ``GLVND``. + +This policy was introduced in CMake version 3.11. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_dir/LABELS.rst b/Help/prop_dir/LABELS.rst new file mode 100644 index 0000000..de27d90 --- /dev/null +++ b/Help/prop_dir/LABELS.rst @@ -0,0 +1,13 @@ +LABELS +------ + +Specify a list of text labels associated with a directory and all of its +subdirectories. This is equivalent to setting the :prop_tgt:`LABELS` target +property and the :prop_test:`LABELS` test property on all targets and tests in +the current directory and subdirectories. Note: Launchers must enabled to +propagate labels to targets. + +The :variable:`CMAKE_DIRECTORY_LABELS` variable can be used to initialize this +property. + +The list is reported in dashboard submissions. diff --git a/Help/prop_dir/TEST_INCLUDE_FILE.rst b/Help/prop_dir/TEST_INCLUDE_FILE.rst index e477951..31b2382 100644 --- a/Help/prop_dir/TEST_INCLUDE_FILE.rst +++ b/Help/prop_dir/TEST_INCLUDE_FILE.rst @@ -1,7 +1,9 @@ TEST_INCLUDE_FILE ----------------- +Deprecated. Use :prop_dir:`TEST_INCLUDE_FILES` instead. + A cmake file that will be included when ctest is run. -If you specify TEST_INCLUDE_FILE, that file will be included and +If you specify ``TEST_INCLUDE_FILE``, that file will be included and processed when ctest is run on the directory. diff --git a/Help/prop_dir/TEST_INCLUDE_FILES.rst b/Help/prop_dir/TEST_INCLUDE_FILES.rst new file mode 100644 index 0000000..c3e4602 --- /dev/null +++ b/Help/prop_dir/TEST_INCLUDE_FILES.rst @@ -0,0 +1,7 @@ +TEST_INCLUDE_FILES +------------------ + +A list of cmake files that will be included when ctest is run. + +If you specify ``TEST_INCLUDE_FILES``, those files will be included and +processed when ctest is run on the directory. diff --git a/Help/prop_gbl/JOB_POOLS.rst b/Help/prop_gbl/JOB_POOLS.rst index 2ce74b8..b904f7a 100644 --- a/Help/prop_gbl/JOB_POOLS.rst +++ b/Help/prop_gbl/JOB_POOLS.rst @@ -19,5 +19,8 @@ Defined pools could be used globally by setting or per target by setting the target properties :prop_tgt:`JOB_POOL_COMPILE` and :prop_tgt:`JOB_POOL_LINK`. +If not set, this property uses the value of the :variable:`CMAKE_JOB_POOLS` +variable. + Build targets provided by CMake that are meant for individual interactive use, such as ``install``, are placed in the ``console`` pool automatically. diff --git a/Help/prop_sf/AUTORCC_OPTIONS.rst b/Help/prop_sf/AUTORCC_OPTIONS.rst index d9dc4d3..2bec033 100644 --- a/Help/prop_sf/AUTORCC_OPTIONS.rst +++ b/Help/prop_sf/AUTORCC_OPTIONS.rst @@ -9,5 +9,14 @@ optional ``OPTIONS`` argument of the :module:`qt4_add_resources() <FindQt4>` mac By default it is empty. -The options set on the ``.qrc`` source file may override :prop_tgt:`AUTORCC_OPTIONS` set -on the target. +The options set on the ``.qrc`` source file may override +:prop_tgt:`AUTORCC_OPTIONS` set on the target. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE resources.qrc PROPERTY AUTORCC_OPTIONS "--compress;9") + # ... diff --git a/Help/prop_sf/AUTOUIC_OPTIONS.rst b/Help/prop_sf/AUTOUIC_OPTIONS.rst index bb48da9..e2f47ec 100644 --- a/Help/prop_sf/AUTOUIC_OPTIONS.rst +++ b/Help/prop_sf/AUTOUIC_OPTIONS.rst @@ -4,11 +4,20 @@ AUTOUIC_OPTIONS Additional options for ``uic`` when using :prop_tgt:`AUTOUIC` This property holds additional command line options -which will be used when ``uic`` is executed during the build via :prop_tgt:`AUTOUIC`, -i.e. it is equivalent to the optional ``OPTIONS`` argument of the -:module:`qt4_wrap_ui() <FindQt4>` macro. +which will be used when ``uic`` is executed during the build via +:prop_tgt:`AUTOUIC`, i.e. it is equivalent to the optional ``OPTIONS`` +argument of the :module:`qt4_wrap_ui() <FindQt4>` macro. By default it is empty. -The options set on the ``.ui`` source file may override :prop_tgt:`AUTOUIC_OPTIONS` set -on the target. +The options set on the ``.ui`` source file may override +:prop_tgt:`AUTOUIC_OPTIONS` set on the target. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE widget.ui PROPERTY AUTOUIC_OPTIONS "--no-protection") + # ... diff --git a/Help/prop_sf/SKIP_AUTOGEN.rst b/Help/prop_sf/SKIP_AUTOGEN.rst index 6bf2409..f31185a 100644 --- a/Help/prop_sf/SKIP_AUTOGEN.rst +++ b/Help/prop_sf/SKIP_AUTOGEN.rst @@ -4,5 +4,14 @@ 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`. +For finer exclusion control see :prop_sf:`SKIP_AUTOMOC`, +:prop_sf:`SKIP_AUTOUIC` and :prop_sf:`SKIP_AUTORCC`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON) + # ... diff --git a/Help/prop_sf/SKIP_AUTOMOC.rst b/Help/prop_sf/SKIP_AUTOMOC.rst index 2245ca6..a929448 100644 --- a/Help/prop_sf/SKIP_AUTOMOC.rst +++ b/Help/prop_sf/SKIP_AUTOMOC.rst @@ -3,4 +3,13 @@ SKIP_AUTOMOC Exclude the source file from :prop_tgt:`AUTOMOC` processing (for Qt projects). -For broader control see :prop_sf:`SKIP_AUTOGEN` +For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON) + # ... diff --git a/Help/prop_sf/SKIP_AUTORCC.rst b/Help/prop_sf/SKIP_AUTORCC.rst index 394d8f8..bccccfc 100644 --- a/Help/prop_sf/SKIP_AUTORCC.rst +++ b/Help/prop_sf/SKIP_AUTORCC.rst @@ -3,4 +3,13 @@ SKIP_AUTORCC Exclude the source file from :prop_tgt:`AUTORCC` processing (for Qt projects). -For broader control see :prop_sf:`SKIP_AUTOGEN` +For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON) + # ... diff --git a/Help/prop_sf/SKIP_AUTOUIC.rst b/Help/prop_sf/SKIP_AUTOUIC.rst index 50f78ef..8c962db 100644 --- a/Help/prop_sf/SKIP_AUTOUIC.rst +++ b/Help/prop_sf/SKIP_AUTOUIC.rst @@ -3,4 +3,18 @@ SKIP_AUTOUIC Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects). -For broader control see :prop_sf:`SKIP_AUTOGEN` +:prop_sf:`SKIP_AUTOUIC` can be set on C++ header and source files and on +``.ui`` files. + +For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE file.cpp PROPERTY SKIP_AUTOUIC ON) + set_property(SOURCE widget.ui PROPERTY SKIP_AUTOUIC ON) + # ... diff --git a/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst new file mode 100644 index 0000000..446dd26 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_DISABLE_OPTIMIZATIONS.rst @@ -0,0 +1,6 @@ +VS_SHADER_DISABLE_OPTIMIZATIONS +------------------------------- + +Disable compiler optimizations for an ``.hlsl`` source file. This adds the +``-Od`` flag to the command line for the FxCompiler tool. Specify the value +``true`` for this property to disable compiler optimizations. diff --git a/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst new file mode 100644 index 0000000..c0e60a3 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_ENABLE_DEBUG.rst @@ -0,0 +1,6 @@ +VS_SHADER_ENABLE_DEBUG +---------------------- + +Enable debugging information for an ``.hlsl`` source file. This adds the +``-Zi`` flag to the command line for the FxCompiler tool. Specify the value +``true`` to generate debugging information for the compiled shader. diff --git a/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst b/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst new file mode 100644 index 0000000..e6763d3 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_OUTPUT_HEADER_FILE.rst @@ -0,0 +1,5 @@ +VS_SHADER_OUTPUT_HEADER_FILE +---------------------------- + +Set filename for output header file containing object code of a ``.hlsl`` +source file. diff --git a/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst b/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst new file mode 100644 index 0000000..1a5e369 --- /dev/null +++ b/Help/prop_sf/VS_SHADER_VARIABLE_NAME.rst @@ -0,0 +1,5 @@ +VS_SHADER_VARIABLE_NAME +----------------------- + +Set name of variable in header file containing object code of a ``.hlsl`` +source file. diff --git a/Help/prop_test/FIXTURES_CLEANUP.rst b/Help/prop_test/FIXTURES_CLEANUP.rst index f0a4be0..3075b4d 100644 --- a/Help/prop_test/FIXTURES_CLEANUP.rst +++ b/Help/prop_test/FIXTURES_CLEANUP.rst @@ -2,7 +2,8 @@ FIXTURES_CLEANUP ---------------- Specifies a list of fixtures for which the test is to be treated as a cleanup -test. +test. These fixture names are distinct from test case names and are not +required to have any similarity to the names of tests associated with them. Fixture cleanup tests are ordinary tests with all of the usual test functionality. Setting the ``FIXTURES_CLEANUP`` property for a test has two diff --git a/Help/prop_test/FIXTURES_REQUIRED.rst b/Help/prop_test/FIXTURES_REQUIRED.rst index e37dfb5..e3f60c4 100644 --- a/Help/prop_test/FIXTURES_REQUIRED.rst +++ b/Help/prop_test/FIXTURES_REQUIRED.rst @@ -2,7 +2,7 @@ FIXTURES_REQUIRED ----------------- Specifies a list of fixtures the test requires. Fixture names are case -sensitive. +sensitive and they are not required to have any similarity to test names. Fixtures are a way to attach setup and cleanup tasks to a set of tests. If a test requires a given fixture, then all tests marked as setup tasks for that @@ -19,7 +19,9 @@ some setup tests fail. When CTest is asked to execute only a subset of tests (e.g. by the use of regular expressions or when run with the ``--rerun-failed`` command line option), it will automatically add any setup or cleanup tests for fixtures -required by any of the tests that are in the execution set. +required by any of the tests that are in the execution set. This behavior can +be overridden with the ``-FS``, ``-FC`` and ``-FA`` command line options to +:manual:`ctest(1)` if desired. Since setup and cleanup tasks are also tests, they can have an ordering specified by the :prop_test:`DEPENDS` test property just like any other tests. diff --git a/Help/prop_test/FIXTURES_SETUP.rst b/Help/prop_test/FIXTURES_SETUP.rst index a220215..fdb21cc 100644 --- a/Help/prop_test/FIXTURES_SETUP.rst +++ b/Help/prop_test/FIXTURES_SETUP.rst @@ -2,14 +2,15 @@ FIXTURES_SETUP -------------- Specifies a list of fixtures for which the test is to be treated as a setup -test. +test. These fixture names are distinct from test case names and are not +required to have any similarity to the names of tests associated with them. Fixture setup tests are ordinary tests with all of the usual test functionality. Setting the ``FIXTURES_SETUP`` property for a test has two primary effects: - CTest will ensure the test executes before any other test which lists the - fixture(s) in its :prop_test:`FIXTURES_REQUIRED` property. + fixture name(s) in its :prop_test:`FIXTURES_REQUIRED` property. - If CTest is asked to run only a subset of tests (e.g. using regular expressions or the ``--rerun-failed`` option) and the setup test is not in diff --git a/Help/prop_test/PROCESSORS.rst b/Help/prop_test/PROCESSORS.rst index 763b6d0..a1211fb 100644 --- a/Help/prop_test/PROCESSORS.rst +++ b/Help/prop_test/PROCESSORS.rst @@ -1,8 +1,13 @@ PROCESSORS ---------- -How many process slots this test requires +Set to specify how many process slots this test requires. Denotes the number of processors that this test will require. This is typically used for MPI tests, and should be used in conjunction with -the ctest_test PARALLEL_LEVEL option. +the :command:`ctest_test` ``PARALLEL_LEVEL`` option. + +This will also be used to display a weighted test timing result in label and +subproject summaries in the command line output of :manual:`ctest(1)`. The wall +clock time for the test run will be multiplied by this property to give a +better idea of how much cpu resource CTest allocated for the test. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index 0171d20..9e5261f 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -5,44 +5,49 @@ Should the target be processed with automoc (for Qt projects). AUTOMOC is a boolean specifying whether CMake will handle the Qt ``moc`` preprocessor automatically, i.e. without having to use the -:module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are -supported. +:module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. +Currently Qt4 and Qt5 are supported. When this property is set ``ON``, CMake will scan the header and source files at build time and invoke moc accordingly. * If an ``#include`` statement like ``#include "moc_<basename>.cpp"`` is found, - the ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in an otherwise empty - line of the ``<basename>.h(xx)`` header file. ``moc`` is run on the header + a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is expected to appear in the + ``<basename>.h(xx)`` header file. ``moc`` is run on the header file to generate ``moc_<basename>.cpp`` in the ``<AUTOGEN_BUILD_DIR>/include`` directory which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. This allows the compiler to find the included ``moc_<basename>.cpp`` file regardless of the location the original source. + * For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. * If an ``#include`` statement like ``#include "<basename>.moc"`` is found, - then ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in the current source - file and ``moc`` is run on the source file itself. + a macro from :prop_tgt:`AUTOMOC_MACRO_NAMES` is expected to appear in the + source file and ``moc`` is run on the source file itself. * Header files that are not included by an ``#include "moc_<basename>.cpp"`` - statement are nonetheless scanned for ``Q_OBJECT`` or ``Q_GADGET`` macros. + statement are nonetheless scanned for a macro out of + :prop_tgt:`AUTOMOC_MACRO_NAMES`. The resulting ``moc_<basename>.cpp`` files are generated in custom directories and automatically included in a generated ``<AUTOGEN_BUILD_DIR>/mocs_compilation.cpp`` file, which is compiled as part of the target. * The custom directories with checksum - based names help to avoid name collisions for moc files with the same + based names help to avoid name collisions for ``moc`` files with the same ``<basename>``. * See :prop_tgt:`AUTOGEN_BUILD_DIR`. * Additionally, header files with the same base name as a source file, (like ``<basename>.h``) or ``_p`` appended to the base name (like - ``<basename>_p.h``), are parsed for ``Q_OBJECT`` or ``Q_GADGET`` macros, - and if found, ``moc`` is also executed on those files. + ``<basename>_p.h``), are scanned for a macro out of + :prop_tgt:`AUTOMOC_MACRO_NAMES`, and if found, ``moc`` + is also executed on those files. * ``AUTOMOC`` always checks multiple header alternative extensions, such as ``hpp``, ``hxx``, etc. when searching for headers. @@ -53,11 +58,11 @@ source files at build time and invoke moc accordingly. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. -Additional command line options for moc can be set via the +Additional command line options for ``moc`` can be set via the :prop_tgt:`AUTOMOC_MOC_OPTIONS` property. By enabling the :variable:`CMAKE_AUTOMOC_RELAXED_MODE` variable the -rules for searching the files which will be processed by moc can be relaxed. +rules for searching the files which will be processed by ``moc`` can be relaxed. See the documentation for this variable for more details. The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the @@ -66,9 +71,14 @@ automoc targets together in an IDE, e.g. in MSVS. The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS. +Additional macro names to search for can be added to :prop_tgt:`AUTOMOC_MACRO_NAMES`. + Additional ``moc`` dependency file names can be extracted from source code by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. +Compiler pre definitions for ``moc`` are written to a ``moc_predefs.h`` file +which is controlled by :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`. + Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. diff --git a/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst new file mode 100644 index 0000000..57a647f --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,24 @@ +AUTOMOC_COMPILER_PREDEFINES +--------------------------- + +Boolean value used by :prop_tgt:`AUTOMOC` to determine if the +compiler pre definitions file ``moc_predefs.h`` should be generated. + +CMake generates a ``moc_predefs.h`` file with compiler pre definitions +from the output of the command defined in +:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` +when + +- :prop_tgt:`AUTOMOC` is enabled, +- :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is enabled, +- :variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` isn't empty and +- the Qt version is greater or equal 5.8. + +The ``moc_predefs.h`` file, which is generated in :prop_tgt:`AUTOGEN_BUILD_DIR`, +is passed to ``moc`` as the argument to the ``--include`` option. + +By default :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` is initialized from +:variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES`, which is ON by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst index 810cbf4..b738ecf 100644 --- a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -25,7 +25,7 @@ with Qt. Example -------- +^^^^^^^ Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we want the ``moc`` file to depend on the macro`s file name argument:: diff --git a/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000..a5ad9d5 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,32 @@ +AUTOMOC_MACRO_NAMES +------------------- + +A :ref:`;-list <CMake Language Lists>` list of macro names used by +:prop_tgt:`AUTOMOC` to determine if a C++ file needs to be processed by ``moc``. + +This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` +for this target. + +When running :prop_tgt:`AUTOMOC`, CMake searches for the strings listed in +:prop_tgt:`AUTOMOC_MACRO_NAMES` in C++ source and header files. +If any of the strings is found + +- as the first non space string on a new line or +- as the first non space string after a ``{`` on a new line, + +then the file will be processed by ``moc``. + +By default :prop_tgt:`AUTOMOC_MACRO_NAMES` is initialized from +:variable:`CMAKE_AUTOMOC_MACRO_NAMES`. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + +Example +^^^^^^^ + +In this case the the ``Q_OBJECT`` macro is hidden inside an other macro +called ``CUSTOM_MACRO``. To let CMake know that source files, that contain +``CUSTOM_MACRO``, need to be ``moc`` processed, we call:: + + set_property(TARGET tgt APPEND PROPERTY AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/prop_tgt/AUTORCC_OPTIONS.rst b/Help/prop_tgt/AUTORCC_OPTIONS.rst index 8a0f632..d6ade5a 100644 --- a/Help/prop_tgt/AUTORCC_OPTIONS.rst +++ b/Help/prop_tgt/AUTORCC_OPTIONS.rst @@ -19,3 +19,12 @@ set on the ``.qrc`` source file. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(TARGET tgt PROPERTY AUTORCC_OPTIONS "--compress;9") + # ... diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index 6493bbc..1791384 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -17,6 +17,9 @@ optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. ``<AUTOGEN_BUILD_DIR>/include``, which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. +* For :prop_gbl:`multi configuration generators <GENERATOR_IS_MULTI_CONFIG>`, + the include directory is ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>``. + * See :prop_tgt:`AUTOGEN_BUILD_DIR`. This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst index 9fb042e..3f613b9 100644 --- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -23,3 +23,12 @@ expressions. See the :manual:`cmake-qt(7)` manual for more information on using CMake with Qt. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(TARGET tgt PROPERTY AUTOUIC_OPTIONS "--no-protection") + # ... diff --git a/Help/prop_tgt/COMPILE_FLAGS.rst b/Help/prop_tgt/COMPILE_FLAGS.rst index 1a5389e..8fe651b 100644 --- a/Help/prop_tgt/COMPILE_FLAGS.rst +++ b/Help/prop_tgt/COMPILE_FLAGS.rst @@ -8,4 +8,4 @@ build sources within the target. Use :prop_tgt:`COMPILE_DEFINITIONS` to pass additional preprocessor definitions. This property is deprecated. Use the :prop_tgt:`COMPILE_OPTIONS` -property or the command:`target_compile_options` command instead. +property or the :command:`target_compile_options` command instead. diff --git a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst index 1c7dd80..d306d7f 100644 --- a/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst +++ b/Help/prop_tgt/CUDA_SEPARABLE_COMPILATION.rst @@ -11,3 +11,7 @@ For instance: .. code-block:: cmake set_property(TARGET myexe PROPERTY CUDA_SEPARABLE_COMPILATION ON) + +This property is initialized by the value of the +:variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/CUDA_STANDARD.rst b/Help/prop_tgt/CUDA_STANDARD.rst index b262814..a3a2f56 100644 --- a/Help/prop_tgt/CUDA_STANDARD.rst +++ b/Help/prop_tgt/CUDA_STANDARD.rst @@ -7,7 +7,7 @@ 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``. +Supported values are ``98``, ``11``, ``14``. 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/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 30a612d..0762033 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -6,7 +6,8 @@ The C++ standard whose features are requested to build this target. This property specifies the 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. For compilers that -have no notion of a standard level, such as MSVC, this has no effect. +have no notion of a standard level, such as Microsoft Visual C++ before +2015 Update 3, this has no effect. Supported values are ``98``, ``11``, ``14``, and ``17``. diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 815a686..e7f7904 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -6,7 +6,8 @@ The C standard whose features are requested to build this target. This property specifies the C standard whose features are requested to build this target. For some compilers, this results in adding a flag such as ``-std=gnu11`` to the compile line. For compilers that -have no notion of a standard level, such as MSVC, this has no effect. +have no notion of a standard level, such as Microsoft Visual C++ before +2015 Update 3, this has no effect. Supported values are ``90``, ``99`` and ``11``. diff --git a/Help/prop_tgt/IMPORTED_GLOBAL.rst b/Help/prop_tgt/IMPORTED_GLOBAL.rst new file mode 100644 index 0000000..1feca04 --- /dev/null +++ b/Help/prop_tgt/IMPORTED_GLOBAL.rst @@ -0,0 +1,22 @@ +IMPORTED_GLOBAL +--------------- + +Indication of whether an :ref:`IMPORTED target <Imported Targets>` is +globally visible. + +The boolean value of this property is True for targets created with the +``IMPORTED`` ``GLOBAL`` options to :command:`add_executable()` or +:command:`add_library()`. It is always False for targets built within the +project. + +For targets created with the ``IMPORTED`` option to +:command:`add_executable()` or :command:`add_library()` but without the +additional option ``GLOBAL`` this is False, too. However, setting this +property for such a locally ``IMPORTED`` target to True promotes that +target to global scope. This promotion can only be done in the same +directory where that ``IMPORTED`` target was created in the first place. + +Once an imported target has been made global, it cannot be changed back to +non-global. Therefore, if a project sets this property, it may only +provide a value of True. CMake will issue an error if the project tries to +set the property to a non-True value, even if the value was already False. diff --git a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst index 0fe0b31..b63d6d7 100644 --- a/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst +++ b/Help/prop_tgt/LANG_COMPILER_LAUNCHER.rst @@ -1,7 +1,8 @@ <LANG>_COMPILER_LAUNCHER ------------------------ -This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. +This property is implemented only when ``<LANG>`` is ``C``, ``CXX``, +``Fortran``, or ``CUDA``. Specify a :ref:`;-list <CMake Language Lists>` containing a command line for a compiler launching tool. The :ref:`Makefile Generators` and the diff --git a/Help/prop_tgt/LANG_CPPCHECK.rst b/Help/prop_tgt/LANG_CPPCHECK.rst new file mode 100644 index 0000000..5f8be00 --- /dev/null +++ b/Help/prop_tgt/LANG_CPPCHECK.rst @@ -0,0 +1,13 @@ +<LANG>_CPPCHECK +--------------- + +This property is supported only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`;-list <CMake Language Lists>` containing a command line +for the ``cppcheck`` static analysis tool. The :ref:`Makefile Generators` +and the :generator:`Ninja` generator will run ``cppcheck`` along with the +compiler and report any problems. + +This property is initialized by the value of the +:variable:`CMAKE_<LANG>_CPPCHECK` variable if it is set when a target is +created. diff --git a/Help/prop_tgt/MACOSX_BUNDLE.rst b/Help/prop_tgt/MACOSX_BUNDLE.rst index 7cd8046..f9e11ee 100644 --- a/Help/prop_tgt/MACOSX_BUNDLE.rst +++ b/Help/prop_tgt/MACOSX_BUNDLE.rst @@ -6,7 +6,7 @@ Build an executable as an Application Bundle on OS X or iOS. When this property is set to ``TRUE`` the executable when built on OS X or iOS will be created as an application bundle. This makes it a GUI executable that can be launched from the Finder. See the -:prop_tgt:`MACOSX_FRAMEWORK_INFO_PLIST` target property for information about +:prop_tgt:`MACOSX_BUNDLE_INFO_PLIST` target property for information about creation of the ``Info.plist`` file for the application bundle. This property is initialized by the value of the variable :variable:`CMAKE_MACOSX_BUNDLE` if it is set when a target is created. diff --git a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst index 070dd30..880343d 100644 --- a/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst +++ b/Help/prop_tgt/NO_SYSTEM_FROM_IMPORTED.rst @@ -1,11 +1,15 @@ NO_SYSTEM_FROM_IMPORTED ----------------------- -Do not treat includes from IMPORTED target interfaces as SYSTEM. +Do not treat include directories from the interfaces of consumed +:ref:`imported targets` as ``SYSTEM``. -The contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED targets -are treated as SYSTEM includes by default. If this property is -enabled, the contents of the INTERFACE_INCLUDE_DIRECTORIES of IMPORTED -targets are not treated as system includes. This property is -initialized by the value of the variable CMAKE_NO_SYSTEM_FROM_IMPORTED -if it is set when a target is created. +The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property +of imported targets are treated as ``SYSTEM`` includes by default. If this +property is enabled on a target, compilation of sources in that target will +not treat the contents of the ``INTERFACE_INCLUDE_DIRECTORIES`` of consumed +imported targets as system includes. + +This property is initialized by the value of the +:variable:`CMAKE_NO_SYSTEM_FROM_IMPORTED` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst new file mode 100644 index 0000000..ab311ea --- /dev/null +++ b/Help/prop_tgt/VS_DOTNET_REFERENCEPROP_refname_TAG_tagname.rst @@ -0,0 +1,14 @@ +VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname> +----------------------------------------------- + +Defines an XML property ``<tagname>`` for a .NET reference +``<refname>``. + +Reference properties can be set for .NET references which are +defined by the target properties :prop_tgt:`VS_DOTNET_REFERENCES`, +:prop_tgt:`VS_DOTNET_REFERENCE_<refname>` +and also for project references to other C# targets which are +established by :command:`target_link_libraries()`. + +This property is only applicable to C# targets and Visual Studio +generators 2010 and later. diff --git a/Help/release/3.10.rst b/Help/release/3.10.rst new file mode 100644 index 0000000..35fe602 --- /dev/null +++ b/Help/release/3.10.rst @@ -0,0 +1,257 @@ +CMake 3.10 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.9 include the following. + +New Features +============ + +Platforms +--------- + +* The `flang`_ Fortran compiler is now supported, with compiler id ``Flang``. + +* A new minimal platform file for ``Midipix`` was added. + +* Support for the MSVC ARM64 architecture was added. + Visual Studio 2017 Update 4 and above offer an ARM64 toolchain. + +* Support for the IAR ARM Compiler was improved. + +.. _`flang`: https://github.com/flang-compiler/flang + +Generators +---------- + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned + to add compiler launcher tools like ccache along with the compiler for the + ``CUDA`` language (``C`` and ``CXX`` were supported previously). See the + :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and + :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details. + +* The :generator:`CodeBlocks` extra generator learned to optionally exclude + files from outside the project root directory from the generated project. + See the :variable:`CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES` variable. + +Commands +-------- + +* The :command:`cmake_host_system_information` command learned more keys + to get information about the processor capabilities and the host OS + version. + +* The :command:`configure_file` command learned to support indented + ``# cmakedefine`` and ``# cmakedefine01``. Spaces and/or tabs between + the ``#`` character and the ``cmakedefine``/``cmakedefine01`` words + are now understood and preserved in the output. + +* The :command:`execute_process` command gained a ``RESULTS_VARIABLE`` + option to collect a list of results from all children in a pipeline + of processes when multiple ``COMMAND`` arguments are given. + +* The :command:`include_guard` command was introduced to allow guarding + CMake scripts from being included more than once. The command supports + ``DIRECTORY`` and ``GLOBAL`` options to adjust the corresponding include guard + scope. If no options given, include guard is similar to basic variable-based + check. + +* The :command:`string` command learned a new ``PREPEND`` subcommand. + +* The :command:`string(TIMESTAMP)` command now supports ``%A`` + for full weekday name and ``%B`` for full month name. + +Variables +--------- + +* A :variable:`CMAKE_DIRECTORY_LABELS` variable was added to specify + labels for all tests in a directory. + +Properties +---------- + +* A :prop_tgt:`<LANG>_CPPCHECK` target property and supporting + :variable:`CMAKE_<LANG>_CPPCHECK` variable were introduced to tell + the :ref:`Makefile Generators` and the :generator:`Ninja` generator to + run ``cppcheck`` with the compiler for ``C`` and ``CXX`` languages. + +* A :prop_dir:`LABELS` directory property was added to specify labels + for all targets and tests in a directory. + +* A :prop_dir:`TEST_INCLUDE_FILES` directory property was added to + list any number of files to be included when running tests with + :manual:`ctest(1)`. This generalizes the :prop_dir:`TEST_INCLUDE_FILE` + property. + +* The :prop_tgt:`VS_DOTNET_REFERENCEPROP_<refname>_TAG_<tagname>` + target property was added to support custom XML tags for reference + assemblies in C# targets. + +* Source file properties :prop_sf:`VS_SHADER_OUTPUT_HEADER_FILE` and + :prop_sf:`VS_SHADER_VARIABLE_NAME` have been added to specify more + details of ``.hlsl`` sources with :ref:`Visual Studio Generators`. + +Modules +------- + +* The :module:`FindCurses` module gained a ``CURSES_NEED_WIDE`` option + to request the wide-character variant. + +* The :module:`FindEXPAT` module now provides imported targets. + +* The :module:`FindFreetype` module now provides imported targets. + +* :module:`FindMPI` gained a number of new features, including: + + * Language-specific components have been added to the module. + * Many more MPI environments are now supported. + * The environmental support for Fortran has been improved. + * A user now has fine-grained control over the MPI selection process, + including passing custom parameters to the MPI compiler. + * The version of the implemented MPI standard is now being exposed. + * MPI-2 C++ bindings can now be detected and also suppressed if so desired. + * The available Fortran bindings are now being detected and verified. + * Various MPI-3 information can be requested, including the library version + and Fortran capabilities of the individual bindings. + * Statically linked MPI implementations are supported. + +* A :module:`FindOpenACC` module was added to detect compiler support + for OpenACC. Currently only supports PGI, GNU and Cray compilers. + +* The :module:`FindOpenGL` module gained support for GLVND on Linux. + +* The :module:`FindOpenMP` module gained support for + language-specific components. + +* A :module:`FindPatch` module was added to find the ``patch`` + command-line executable. + +* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp` command + gained a ``DESCRIPTORS`` option to generate descriptor files. + +* The :module:`GoogleTest` module gained a new command + :command:`gtest_discover_tests` implementing dynamic (build-time) test + discovery. Unlike the source parsing approach, dynamic discovery executes + the test (in 'list available tests' mode) at build time to discover tests. + This is robust against unusual ways of labeling tests, provides much better + support for advanced features such as parameterized tests, and does not + require re-running CMake to discover added or removed tests within a test + executable. + +* The :module:`InstallRequiredSystemLibraries` module gained support + for installing Intel compiler runtimes. + +Autogen +------- + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC` with a + multi configuration generator (e.g. :generator:`Xcode`), + included ``*.moc``, ``moc_*.cpp`` and ``ui_*.h`` files are generated in + ``<AUTOGEN_BUILD_DIR>/include_<CONFIG>`` instead of + ``<AUTOGEN_BUILD_DIR>/include``. + +* When using :prop_tgt:`AUTOMOC` or :prop_tgt:`AUTOUIC`, + source files that are :prop_sf:`GENERATED` will be processed as well. + They were ignored by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` + in earlier releases. + See policy :policy:`CMP0071`. + +* When using :prop_tgt:`AUTOMOC`, CMake searches for the strings ``Q_OBJECT``, + ``Q_GADGET`` or ``Q_NAMESPACE`` in a source file to determine if it needs + to be ``moc`` processed. The new :variable:`CMAKE_AUTOMOC_MACRO_NAMES` + variable and :prop_tgt:`AUTOMOC_MACRO_NAMES` target property may be set + to register additional strings (macro names) to search for. + +* When using :prop_tgt:`AUTOMOC`, the new + :variable:`CMAKE_AUTOMOC_COMPILER_PREDEFINES` variable and + :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` target property specify whether + to enable or disable the generation of the compiler pre definitions file + ``moc_predefs.h``. + +CTest +----- + +* A :variable:`CTEST_LABELS_FOR_SUBPROJECTS` CTest module variable and CTest + script variable were added to specify a list of labels that should be + treated as subprojects by CDash. To use this value in both the CTest module + and the ctest command line :ref:`Dashboard Client` mode (e.g. ``ctest -S``) + set it in the ``CTestConfig.cmake`` config file. + +CPack +----- + +* CPack gained a ``FREEBSD`` generator for FreeBSD ``pkg(8)``, configured + by the :module:`CPackFreeBSD` module. + +* The CPack ``DEB`` generator, configured by the :module:`CPackDeb` module, + was enabled on Windows. While not fully featured (due to the lack of + external UNIX tools) this will allow building basic cross-platform Debian + packages. + +* The :module:`CPackDeb` module learned to set package release version in + ``Version`` info property. + See the :variable:`CPACK_DEBIAN_PACKAGE_RELEASE` variable. + +* The :module:`CPackDeb` module learned more strict package version checking + that complies with Debian rules. + +* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and + :command:`cpack_ifw_configure_component_group` commands gained a new + ``REPLACES`` and ``CHECKABLE`` options. + +* The :module:`CPackIFW` module gained new + :variable:`CPACK_IFW_PACKAGE_FILE_EXTENSION` variable to customize + target binary format. + +* The :module:`CPackIFW` module gained new + :variable:`CPACK_IFW_REPOSITORIES_DIRECTORIES` variable to specify + additional repositories dirs that will be used to resolve and + repack dependent components. This feature is only available when + using QtIFW 3.1 or later. + +* Modules :module:`CPackRPM` and :module:`CPackDeb` learned to set package epoch + version. + See :variable:`CPACK_RPM_PACKAGE_EPOCH` and + :variable:`CPACK_DEBIAN_PACKAGE_EPOCH` variables. + +Other +----- + +* The :manual:`cmake(1)` ``-E`` mode gained support for ``sha1sum``, + ``sha224sum``, ``sha256sum``, ``sha384sum``, and ``sha512sum``. + +* The graphviz output now distinguishes among the different dependency types + ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` and represents them in the output + graph as solid, dashed and dotted edges. + +Deprecated and Removed Features +=============================== + +* Support for building CMake itself with C++98 compilers was dropped. + CMake is now implemented using C++11. + +* Support for building CMake on HP-UX has been dropped pending better + support for C++11 and a port of libuv. See `CMake Issue 17137`_. + Use CMake 3.9 or lower instead for HP-UX support. + +.. _`CMake Issue 17137`: https://gitlab.kitware.com/cmake/cmake/issues/17137 + +Other Changes +============= + +* On FreeBSD the C++ compiler named ``c++`` is now the preferred default. + +* The :command:`file(GENERATE)` command now interprets relative paths + given to its ``OUTPUT`` and ``INPUT`` arguments with respect to the + caller's current binary and source directories, respectively. + See policy :policy:`CMP0070`. + +* The :command:`get_filename_component` ``PROGRAM`` mode semantics + have been revised to not tolerate unquoted spaces in the path + to the program while also accepting arguments. While technically + incompatible with the old behavior, it is expected that behavior + under typical use cases with properly-quoted command-lines has + not changed. diff --git a/Help/release/3.4.rst b/Help/release/3.4.rst index 89c5561..468627e 100644 --- a/Help/release/3.4.rst +++ b/Help/release/3.4.rst @@ -66,7 +66,7 @@ Variables Properties ---------- -* :ref:`Visual Studio Generators` learned to support additonal +* :ref:`Visual Studio Generators` learned to support additional target properties to customize projects for NVIDIA Nsight Tegra Visual Studio Edition: diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index 144537d..a542b77 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -111,7 +111,7 @@ Modules * The :module:`ExternalProject` module learned to initialize Git submodules recursively and also to initialize new submodules on updates. Use the - ``GIT_SUBMODULES`` option to restrict which submodules are initalized and + ``GIT_SUBMODULES`` option to restrict which submodules are initialized and updated. * The :module:`ExternalProject` module leared the ``DOWNLOAD_NO_EXTRACT 1`` diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst index 4c51af4..d4d374b 100644 --- a/Help/release/3.7.rst +++ b/Help/release/3.7.rst @@ -237,7 +237,7 @@ CPack * The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and :command:`cpack_ifw_configure_component_group` commands gained a new - ``USER_INTERFACES`` option to add a list of additonal pages to the IFW + ``USER_INTERFACES`` option to add a list of additional pages to the IFW installer. * The :module:`CPackRPM` module learned to generate debuginfo diff --git a/Help/release/3.9.rst b/Help/release/3.9.rst index ae55105..897e268 100644 --- a/Help/release/3.9.rst +++ b/Help/release/3.9.rst @@ -34,8 +34,6 @@ Generators This is an experimental feature and can be activated by setting the :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value. -* The :generator:`Xcode` generator now supports Xcode 9. - Commands -------- @@ -310,9 +308,6 @@ Other Changes in dependent targets may now compile without waiting for their targets' dependencies to link. -* On macOS, the default application bundle ``Info.plist`` file now enables - Hi-DPI support. - * On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. @@ -333,3 +328,15 @@ Changes made since CMake 3.9.0 include the following. CMake 3.9.0 has been removed for the 3.9 series due to regressions caused by new use of ``<PackageName>_ROOT`` variables. The behavior may be re-introduced in the future in a more-compatible way. + +3.9.2 +----- + +* On macOS, the default application bundle ``Info.plist`` file no longer + enables Hi-DPI support as it did in 3.9.0 and 3.9.1. The change had + to be reverted because it broke iOS applications. + +* The Xcode generator no longer adds "outputPaths" to custom script + build phases as it did in 3.9.0 and 3.9.1. This was added in an + attempt to support Xcode 9's new build system, but broke incremental + rebuilds for both the old and new Xcode build systems. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/CheckIncludeFiles-language-CXX.rst b/Help/release/dev/CheckIncludeFiles-language-CXX.rst new file mode 100644 index 0000000..1631a5e --- /dev/null +++ b/Help/release/dev/CheckIncludeFiles-language-CXX.rst @@ -0,0 +1,6 @@ +CheckIncludeFiles-language-CXX +------------------------------ + +* The :module:`CheckIncludeFiles` module :command:`CHECK_INCLUDE_FILES` + command gained a ``LANGUAGE`` option to specify whether to check using the + ``C`` or ``CXX`` compiler. diff --git a/Help/release/dev/CodeBlocks-custom-compiler-id.rst b/Help/release/dev/CodeBlocks-custom-compiler-id.rst new file mode 100644 index 0000000..893bd5c --- /dev/null +++ b/Help/release/dev/CodeBlocks-custom-compiler-id.rst @@ -0,0 +1,6 @@ +CodeBlocks-custom-compiler-id +----------------------------- + +* The :generator:`CodeBlocks` extra generator learned to check a + :variable:`CMAKE_CODEBLOCKS_COMPILER_ID` variable for a custom + compiler identification value to place in the project file. diff --git a/Help/release/dev/FetchContent.rst b/Help/release/dev/FetchContent.rst new file mode 100644 index 0000000..3b12977 --- /dev/null +++ b/Help/release/dev/FetchContent.rst @@ -0,0 +1,11 @@ +FetchContent +------------ + +* A new :module:`FetchContent` module was added which supports populating + content at configure time using any of the download/update methods + supported by :command:`ExternalProject_Add`. This allows the content + to be used immediately during the configure stage, such as with + :command:`add_subdirectory`, etc. Hierarchical project structures are + well supported, allowing parent projects to override the content details + of child projects and ensuring content is not populated multiple times + throughout the whole project tree. diff --git a/Help/release/dev/FindIconv.rst b/Help/release/dev/FindIconv.rst new file mode 100644 index 0000000..98f2591 --- /dev/null +++ b/Help/release/dev/FindIconv.rst @@ -0,0 +1,4 @@ +FindIconv +--------- + +* A :module:`FindIconv` module was added to locate iconv support. diff --git a/Help/release/dev/FindOpenGL-glvnd-policy.rst b/Help/release/dev/FindOpenGL-glvnd-policy.rst new file mode 100644 index 0000000..3348acf --- /dev/null +++ b/Help/release/dev/FindOpenGL-glvnd-policy.rst @@ -0,0 +1,5 @@ +FindOpenGL-glvnd-policy +----------------------- + +* The :module:`FindOpenGL` module now prefers GLVND libraries if available. + See policy :policy:`CMP0072`. diff --git a/Help/release/dev/WriteBasicConfigVersionFile_SameMinorVersion.rst b/Help/release/dev/WriteBasicConfigVersionFile_SameMinorVersion.rst new file mode 100644 index 0000000..7f1c4d0 --- /dev/null +++ b/Help/release/dev/WriteBasicConfigVersionFile_SameMinorVersion.rst @@ -0,0 +1,5 @@ +WriteBasicConfigFile_SameMinorVersion +------------------------------------- + +* The :command:`write_basic_package_version_file` understands a new + ``SameMinorVersion`` option for the ``COMPATIBILITY`` argument. diff --git a/Help/release/dev/blas-lapack-flame.rst b/Help/release/dev/blas-lapack-flame.rst new file mode 100644 index 0000000..fdc3a69 --- /dev/null +++ b/Help/release/dev/blas-lapack-flame.rst @@ -0,0 +1,5 @@ +blas-lapack-flame +----------------- + +* The :module:`FindBLAS` and :module:`FindLAPACK` modules learned to support + `FLAME <https://github.com/flame>`__ ``blis`` and ``libflame``. diff --git a/Help/release/dev/cmake-default-dir-install-permissions.rst b/Help/release/dev/cmake-default-dir-install-permissions.rst new file mode 100644 index 0000000..8325fda --- /dev/null +++ b/Help/release/dev/cmake-default-dir-install-permissions.rst @@ -0,0 +1,12 @@ +cmake-default-dir-install-permissions +------------------------------------- + +* The :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added + to enable setting of default permissions for directories created implicitly + during installation of files by :command:`install` and + :command:`file(INSTALL)`. + +* The :variable:`CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable was added + which serves the same purpose during packaging as the + :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable serves during + installation (e.g. ``make install``). diff --git a/Help/release/dev/cmake-job-pool.rst b/Help/release/dev/cmake-job-pool.rst new file mode 100644 index 0000000..836d9c1 --- /dev/null +++ b/Help/release/dev/cmake-job-pool.rst @@ -0,0 +1,7 @@ +cmake-job-pool +-------------- + +* A :variable:`CMAKE_JOB_POOLS` variable was added specify a value to use for + the :prop_gbl:`JOB_POOLS` property. This enables control over build + parallelism with command line configuration parameters when using the Ninja + generator. diff --git a/Help/release/dev/cmake-open.rst b/Help/release/dev/cmake-open.rst new file mode 100644 index 0000000..a8f77ae --- /dev/null +++ b/Help/release/dev/cmake-open.rst @@ -0,0 +1,6 @@ +cmake-open +---------- + +* The :manual:`cmake(1)` ``--open <dir>`` command line option can now + be used to open generated IDE projects like Visual Studio solutions + or Xcode projects. diff --git a/Help/release/dev/cuda-sep-comp-var.rst b/Help/release/dev/cuda-sep-comp-var.rst new file mode 100644 index 0000000..23536ef --- /dev/null +++ b/Help/release/dev/cuda-sep-comp-var.rst @@ -0,0 +1,6 @@ +cuda-sep-comp-var +----------------- + +* A :variable:`CMAKE_CUDA_SEPARABLE_COMPILATION` variable was added to + initialize the :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property + on targets when they are created. diff --git a/Help/release/dev/curl_netrc_options.rst b/Help/release/dev/curl_netrc_options.rst new file mode 100644 index 0000000..850c9ce --- /dev/null +++ b/Help/release/dev/curl_netrc_options.rst @@ -0,0 +1,14 @@ +curl_netrc_options +------------------ + +* The :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands + gained ``NETRC`` and ``NETRC_FILE`` options to specify use of a + ``.netrc`` file. + +* The :module:`ExternalProject` module gained ``NETRC`` and ``NETRC_FILE`` + options to specify use of a ``.netrc`` file. + +* The :variable:`CMAKE_NETRC` and :variable:`CMAKE_NETRC_FILE` variables + were added to specify use of a ``.netrc`` file by the + :command:`file(DOWNLOAD)` and :command:`file(UPLOAD)` commands and + the :module:`ExternalProject` module. diff --git a/Help/release/dev/defer-target-source-check.rst b/Help/release/dev/defer-target-source-check.rst new file mode 100644 index 0000000..65f5488 --- /dev/null +++ b/Help/release/dev/defer-target-source-check.rst @@ -0,0 +1,6 @@ +defer-target-source-check +------------------------- + +* :command:`add_library` and :command:`add_executable` commands can now be + called without any sources and will not complain as long as sources will + be added later via :command:`target_sources`. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..bcfa70a --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* An explicit deprecation diagnostic was added for policies ``CMP0037`` + through ``CMP0054`` (``CMP0036`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. diff --git a/Help/release/dev/extend-compile-language-genex.rst b/Help/release/dev/extend-compile-language-genex.rst new file mode 100644 index 0000000..0a0a669 --- /dev/null +++ b/Help/release/dev/extend-compile-language-genex.rst @@ -0,0 +1,7 @@ +extend-compile-language-genex +----------------------------- + +* The ``COMPILE_LANGUAGE`` :manual:`generator expression + <cmake-generator-expressions(7)>` may now be used with + :ref:`Visual Studio Generators` in :prop_tgt:`COMPILE_OPTIONS` + and :command:`file(GENERATE)`. diff --git a/Help/release/dev/fortran-compiler-launcher.rst b/Help/release/dev/fortran-compiler-launcher.rst new file mode 100644 index 0000000..ce254f1 --- /dev/null +++ b/Help/release/dev/fortran-compiler-launcher.rst @@ -0,0 +1,8 @@ +fortran-compiler-launcher +------------------------- + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator learned + to add compiler launcher tools along with the compiler for the ``Fortran`` + language (``C``, ``CXX``, and ``CUDA`` were supported previously). + See the :variable:`CMAKE_<LANG>_COMPILER_LAUNCHER` variable and + :prop_tgt:`<LANG>_COMPILER_LAUNCHER` target property for details. diff --git a/Help/release/dev/generalize-importedtargets-behavior.rst b/Help/release/dev/generalize-importedtargets-behavior.rst new file mode 100644 index 0000000..c6f4523 --- /dev/null +++ b/Help/release/dev/generalize-importedtargets-behavior.rst @@ -0,0 +1,25 @@ +generalize-importedtargets-behavior +----------------------------------- + +* The :command:`target_compile_definitions` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property on + :ref:`Imported Targets`. + +* The :command:`target_compile_features` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_FEATURES` property on :ref:`Imported Targets`. + +* The :command:`target_compile_options` command learned to set the + :prop_tgt:`INTERFACE_COMPILE_OPTIONS` property on :ref:`Imported Targets`. + +* The :command:`target_include_directories` command learned to set the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property on + :ref:`Imported Targets`. + +* The :command:`target_sources` command learned to set the + :prop_tgt:`INTERFACE_SOURCES` property on :ref:`Imported Targets`. + +* The :command:`target_link_libraries` command learned to set the + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property on :ref:`Imported Targets`. + +* :ref:`Alias Targets` may now alias :ref:`Imported Targets` that are + created with the ``GLOBAL`` option to :command:`add_library`. diff --git a/Help/release/dev/generator-instance.rst b/Help/release/dev/generator-instance.rst new file mode 100644 index 0000000..a3ff658 --- /dev/null +++ b/Help/release/dev/generator-instance.rst @@ -0,0 +1,8 @@ +generator-instance +------------------ + +* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced + to hold the selected instance of the generator's corresponding + native tools if multiple are available. This is used by the + :generator:`Visual Studio 15 2017` generator to hold the + selected instance of Visual Studio persistently. diff --git a/Help/release/dev/imported-promotion.rst b/Help/release/dev/imported-promotion.rst new file mode 100644 index 0000000..d184178 --- /dev/null +++ b/Help/release/dev/imported-promotion.rst @@ -0,0 +1,15 @@ +imported-promotion +------------------ + +* Added new target-property :prop_tgt:`IMPORTED_GLOBAL` which + indicates if an :ref:`IMPORTED target <Imported Targets>` is + globally visible. + It will be set automatically if such an imported target is + created with the ``GLOBAL`` flag. + +* Additionally, it is now also possible to promote a local imported + target to become globally visible by setting its + :prop_tgt:`IMPORTED_GLOBAL` property to `TRUE`. (However, this + promotion can only succeed if it is done from within the same + directory where the imported target was created in the first + place.) Setting it to `FALSE` is not supported! diff --git a/Help/release/dev/ti-compiler-depfile-support.rst b/Help/release/dev/ti-compiler-depfile-support.rst new file mode 100644 index 0000000..f870afd --- /dev/null +++ b/Help/release/dev/ti-compiler-depfile-support.rst @@ -0,0 +1,4 @@ +ti-compiler-depfile-support +--------------------------- + +* TI C/C++ compilers are now supported by the :generator:`Ninja` generator. diff --git a/Help/release/dev/vs-hlsl-opt-dbg.rst b/Help/release/dev/vs-hlsl-opt-dbg.rst new file mode 100644 index 0000000..8f398ae --- /dev/null +++ b/Help/release/dev/vs-hlsl-opt-dbg.rst @@ -0,0 +1,6 @@ +vs-hlsl-opt-dbg +--------------- + +* Source file properties :prop_sf:`VS_SHADER_DISABLE_OPTIMIZATIONS` and + :prop_sf:`VS_SHADER_ENABLE_DEBUG` have been added to specify more + details of ``.hlsl`` sources with :ref:`Visual Studio Generators`. diff --git a/Help/release/dev/whitelist-more-interface-properties.rst b/Help/release/dev/whitelist-more-interface-properties.rst new file mode 100644 index 0000000..793361c --- /dev/null +++ b/Help/release/dev/whitelist-more-interface-properties.rst @@ -0,0 +1,7 @@ +whitelist-more-interface-properties +----------------------------------- + +* ``INTERFACE`` libraries may now have custom properties set on them if they + start with either an underscore (``_``) or a lowercase ASCII character. The + original intention was to only allow properties which made sense for + ``INTERFACE`` libraries, but it also blocked usage of custom properties. diff --git a/Help/release/dev/write-single-xcodeproj.rst b/Help/release/dev/write-single-xcodeproj.rst new file mode 100644 index 0000000..d5e9fef --- /dev/null +++ b/Help/release/dev/write-single-xcodeproj.rst @@ -0,0 +1,8 @@ +write-single-xcodeproj +---------------------- + +* The :generator:`Xcode` generator behavior of generating one project + file per :command:`project()` command could now be controlled with the + :variable:`CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY` variable. + This could be useful to speed up the CMake generation step for + large projects and to work-around a bug in the ``ZERO_CHECK`` logic. diff --git a/Help/release/index.rst b/Help/release/index.rst index 6af282c..6472b51 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,12 +7,15 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== .. toctree:: :maxdepth: 1 + 3.10 <3.10> 3.9 <3.9> 3.8 <3.8> 3.7 <3.7> diff --git a/Help/variable/APPLE.rst b/Help/variable/APPLE.rst index 75eecf1..810d5fc 100644 --- a/Help/variable/APPLE.rst +++ b/Help/variable/APPLE.rst @@ -1,6 +1,5 @@ APPLE ----- -``True`` if running on OS X. - -Set to ``true`` on OS X. +Set to ``True`` when the target system is an Apple platform +(macOS, iOS, tvOS or watchOS). diff --git a/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst new file mode 100644 index 0000000..7e1c53d --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_COMPILER_PREDEFINES.rst @@ -0,0 +1,8 @@ +CMAKE_AUTOMOC_COMPILER_PREDEFINES +--------------------------------- + +This variable is used to initialize the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES` +property on all the targets. See that target property for additional +information. + +By default it is ON. diff --git a/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst new file mode 100644 index 0000000..5b79c40 --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_MACRO_NAMES.rst @@ -0,0 +1,20 @@ +CMAKE_AUTOMOC_MACRO_NAMES +---------------------------- + +A :ref:`;-list <CMake Language Lists>` list of macro names used by +:variable:`CMAKE_AUTOMOC` to determine if a C++ file needs to be +processed by ``moc``. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_MACRO_NAMES` +property on all the targets. See that target property for additional +information. + +The default value is ``Q_OBJECT;Q_GADGET;Q_NAMESPACE``. + +Example +------- +Let CMake know that source files that contain ``CUSTOM_MACRO`` must be ``moc`` +processed as well:: + + set(CMAKE_AUTOMOC ON) + list(APPEND CMAKE_AUTOMOC_MACRO_NAMES "CUSTOM_MACRO") diff --git a/Help/variable/CMAKE_AUTORCC_OPTIONS.rst b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst index 298cb6b..815d39d 100644 --- a/Help/variable/CMAKE_AUTORCC_OPTIONS.rst +++ b/Help/variable/CMAKE_AUTORCC_OPTIONS.rst @@ -1,7 +1,16 @@ CMAKE_AUTORCC_OPTIONS --------------------- -Whether to handle ``rcc`` automatically for Qt targets. +Additional options for ``rcc`` when using :variable:`CMAKE_AUTORCC`. This variable is used to initialize the :prop_tgt:`AUTORCC_OPTIONS` property on all the targets. See that target property for additional information. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set(CMAKE_AUTORCC_OPTIONS "--compress;9") + # ... diff --git a/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst index 3c9b8c4..28fa92f 100644 --- a/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst +++ b/Help/variable/CMAKE_AUTOUIC_OPTIONS.rst @@ -1,7 +1,16 @@ CMAKE_AUTOUIC_OPTIONS --------------------- -Whether to handle ``uic`` automatically for Qt targets. +Additional options for ``uic`` when using :variable:`CMAKE_AUTOUIC`. This variable is used to initialize the :prop_tgt:`AUTOUIC_OPTIONS` property on all the targets. See that target property for additional information. + +EXAMPLE +^^^^^^^ + +.. code-block:: cmake + + # ... + set_property(CMAKE_AUTOUIC_OPTIONS "--no-protection") + # ... diff --git a/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst new file mode 100644 index 0000000..ad2709d --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_COMPILER_ID.rst @@ -0,0 +1,13 @@ +CMAKE_CODEBLOCKS_COMPILER_ID +---------------------------- + +Change the compiler id in the generated CodeBlocks project files. + +CodeBlocks uses its own compiler id string which differs from +:variable:`CMAKE_<LANG>_COMPILER_ID`. If this variable is left empty, +CMake tries to recognize the CodeBlocks compiler id automatically. +Otherwise the specified string is used in the CodeBlocks project file. +See the CodeBlocks documentation for valid compiler id strings. + +Other IDEs like QtCreator that also use the CodeBlocks generator may ignore +this setting. diff --git a/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst new file mode 100644 index 0000000..80ffce3 --- /dev/null +++ b/Help/variable/CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES.rst @@ -0,0 +1,7 @@ +CMAKE_CODEBLOCKS_EXCLUDE_EXTERNAL_FILES +--------------------------------------- + +Change the way the CodeBlocks generator creates project files. + +If this variable evaluates to ``ON`` the generator excludes from +the project file any files that are located outside the project root. diff --git a/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst new file mode 100644 index 0000000..72e8e66 --- /dev/null +++ b/Help/variable/CMAKE_CUDA_HOST_COMPILER.rst @@ -0,0 +1,7 @@ +CMAKE_CUDA_HOST_COMPILER +------------------------ + +Executable to use when compiling host code when compiling ``CUDA`` language +files. Maps to the nvcc -ccbin option. Will only be used by CMake on the first +configuration to determine a valid host compiler for ``CUDA``. After a valid +host compiler has been found, this value is read-only. diff --git a/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst new file mode 100644 index 0000000..eef92fb --- /dev/null +++ b/Help/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.rst @@ -0,0 +1,6 @@ +CMAKE_CUDA_SEPARABLE_COMPILATION +-------------------------------- + +Default value for :prop_tgt:`CUDA_SEPARABLE_COMPILATION` target property. +This variable is used to initialize the property on each target as it is +created. diff --git a/Help/variable/CMAKE_DIRECTORY_LABELS.rst b/Help/variable/CMAKE_DIRECTORY_LABELS.rst new file mode 100644 index 0000000..2a6c410 --- /dev/null +++ b/Help/variable/CMAKE_DIRECTORY_LABELS.rst @@ -0,0 +1,6 @@ +CMAKE_DIRECTORY_LABELS +----------------------- + +Specify labels for the current directory. + +This is used to initialize the :prop_dir:`LABELS` directory property. diff --git a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst index c49d264..789dc99 100644 --- a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst +++ b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst @@ -1,15 +1,19 @@ CMAKE_FIND_NO_INSTALL_PREFIX ---------------------------- -Ignore the :variable:`CMAKE_INSTALL_PREFIX` when searching for assets. +Exclude the values of the :variable:`CMAKE_INSTALL_PREFIX` and +:variable:`CMAKE_STAGING_PREFIX` variables from +:variable:`CMAKE_SYSTEM_PREFIX_PATH`. CMake adds these project-destination +prefixes to :variable:`CMAKE_SYSTEM_PREFIX_PATH` by default in order to +support building a series of dependent packages and installing them into +a common prefix. Set ``CMAKE_FIND_NO_INSTALL_PREFIX`` to ``TRUE`` +to suppress this behavior. -CMake adds the :variable:`CMAKE_INSTALL_PREFIX` and the -:variable:`CMAKE_STAGING_PREFIX` variable to the -:variable:`CMAKE_SYSTEM_PREFIX_PATH` by default. This variable may be set -on the command line to control that behavior. +The :variable:`CMAKE_SYSTEM_PREFIX_PATH` is initialized on the first call to a +:command:`project` or :command:`enable_language` command. Therefore one must +set ``CMAKE_FIND_NO_INSTALL_PREFIX`` before this in order to take effect. A +user may set the variable as a cache entry on the command line to achieve this. -Set ``CMAKE_FIND_NO_INSTALL_PREFIX`` to ``TRUE`` to tell -:command:`find_package` not to search in the :variable:`CMAKE_INSTALL_PREFIX` -or :variable:`CMAKE_STAGING_PREFIX` by default. Note that the -prefix may still be searched for other reasons, such as being the same prefix -as the CMake installation, or for being a built-in system prefix. +Note that the prefix(es) may still be searched for other reasons, such as being +the same prefix as the CMake installation, or for being a built-in system +prefix. diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst new file mode 100644 index 0000000..78c81b1 --- /dev/null +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -0,0 +1,24 @@ +CMAKE_GENERATOR_INSTANCE +------------------------ + +Generator-specific instance specification provided by user. + +Some CMake generators support selection of an instance of the native build +system when multiple instances are available. If the user specifies an +instance (e.g. by setting this cache entry), or after a default instance is +chosen when a build tree is first configured, the value will be available in +this variable. + +The value of this variable should never be modified by project code. +A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` +variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry. +Once a given build tree has been initialized with a particular value +for this variable, changing the value has undefined behavior. + +Instance specification is supported only on specific generators: + +* For the :generator:`Visual Studio 15 2017` generator (and above) + this specifies the absolute path to the VS installation directory + of the selected VS instance. + +See native build system documentation for allowed instance values. diff --git a/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 0000000..f994fbe --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,29 @@ +CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for directories created implicitly during installation +of files by :command:`install` and :command:`file(INSTALL)`. + +If ``make install`` is invoked and directories are implicitly created they +get permissions set by :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable or platform specific default permissions if the variable is not set. + +Implicitly created directories are created if they are not explicitly installed +by :command:`install` command but are needed to install a file on a certain +path. Example of such locations are directories created due to the setting of +:variable:`CMAKE_INSTALL_PREFIX`. + +Expected content of the :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` +variable is a list of permissions that can be used by :command:`install` command +`PERMISSIONS` section. + +Example usage: + +:: + + set(CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS + OWNER_READ + OWNER_WRITE + OWNER_EXECUTE + GROUP_READ + ) diff --git a/Help/variable/CMAKE_JOB_POOLS.rst b/Help/variable/CMAKE_JOB_POOLS.rst new file mode 100644 index 0000000..72b50b4 --- /dev/null +++ b/Help/variable/CMAKE_JOB_POOLS.rst @@ -0,0 +1,6 @@ +CMAKE_JOB_POOLS +--------------- + +If the :prop_gbl:`JOB_POOLS` global property is not set, the value +of this variable is used in its place. See :prop_gbl:`JOB_POOLS` +for additional information. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst new file mode 100644 index 0000000..054c648 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_ARCHITECTURE_ID +------------------------------------- + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on its target +architecture. For some compilers this is needed to determine the correct +usage. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 0fab10c..2264269 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -20,12 +20,14 @@ include: G95 = G95 Fortran (g95.org) GNU = GNU Compiler Collection (gcc.gnu.org) HP = Hewlett-Packard Compiler (hp.com) + IAR = IAR Systems (iar.com) 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) + Flang = Flang Fortran Compiler PathScale = PathScale (pathscale.com) SDCC = Small Device C Compiler (sdcc.sourceforge.net) SunPro = Oracle Solaris Studio (oracle.com) diff --git a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst index 7961f60..e6c8bb5 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LAUNCHER.rst @@ -3,4 +3,5 @@ CMAKE_<LANG>_COMPILER_LAUNCHER Default value for :prop_tgt:`<LANG>_COMPILER_LAUNCHER` 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``. +created. This is done only when ``<LANG>`` is ``C``, ``CXX``, ``Fortran``, +or ``CUDA``. diff --git a/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst new file mode 100644 index 0000000..e050f43 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND +---------------------------------------- + +Command that outputs the compiler pre definitions. + +See :prop_tgt:`AUTOMOC` which uses +:variable:`CMAKE_CXX_COMPILER_PREDEFINES_COMMAND <CMAKE_<LANG>_COMPILER_PREDEFINES_COMMAND>` +to generate the :prop_tgt:`AUTOMOC_COMPILER_PREDEFINES`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst new file mode 100644 index 0000000..c3cd980 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL.rst @@ -0,0 +1,8 @@ +CMAKE_<LANG>_COMPILER_VERSION_INTERNAL +-------------------------------------- + +An internal variable subject to change. + +This is used to identify the variant of a compiler based on an internal +version number. For some compilers this is needed to determine the +correct usage. diff --git a/Help/variable/CMAKE_LANG_CPPCHECK.rst b/Help/variable/CMAKE_LANG_CPPCHECK.rst new file mode 100644 index 0000000..50b478f --- /dev/null +++ b/Help/variable/CMAKE_LANG_CPPCHECK.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_CPPCHECK +--------------------- + +Default value for :prop_tgt:`<LANG>_CPPCHECK` 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_MSVCIDE_RUN_PATH.rst b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst new file mode 100644 index 0000000..22e727f --- /dev/null +++ b/Help/variable/CMAKE_MSVCIDE_RUN_PATH.rst @@ -0,0 +1,10 @@ +CMAKE_MSVCIDE_RUN_PATH +---------------------- + +Extra PATH locations that should be used when executing +:command:`add_custom_command` or :command:`add_custom_target` when using the +:generator:`Visual Studio 9 2008` (or above) generator. This allows +for running commands and using dll's that the IDE environment is not aware of. + +If not set explicitly the value is initialized by the ``CMAKE_MSVCIDE_RUN_PATH`` +environment variable, if set, and otherwise left empty. diff --git a/Help/variable/CMAKE_NETRC.rst b/Help/variable/CMAKE_NETRC.rst new file mode 100644 index 0000000..52f857e --- /dev/null +++ b/Help/variable/CMAKE_NETRC.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC +----------- + +This variable is used to initialize the ``NETRC`` option for +:command:`file(DOWNLOAD)` and :command:`file(DOWNLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_NETRC_FILE.rst b/Help/variable/CMAKE_NETRC_FILE.rst new file mode 100644 index 0000000..1508f1e --- /dev/null +++ b/Help/variable/CMAKE_NETRC_FILE.rst @@ -0,0 +1,9 @@ +CMAKE_NETRC_FILE +---------------- + +This variable is used to initialize the ``NETRC_FILE`` option for +:command:`file(DOWNLOAD)` and :command:`file(DOWNLOAD)` commands and the +module :module:`ExternalProject`. See those commands for additional +information. + +The local option takes precedence over this variable. diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst index e74dfad..38b2f8d 100644 --- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -10,8 +10,11 @@ documentation. By default this contains the standard directories for the current system, the :variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`. -It is *not* intended to be modified by the project; use -:variable:`CMAKE_PREFIX_PATH` for this. +The installation and staging prefixes may be excluded by setting +the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` variable. + +``CMAKE_SYSTEM_PREFIX_PATH`` is *not* intended to be modified by the project; +use :variable:`CMAKE_PREFIX_PATH` for this. See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, :variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_PROGRAM_PATH`, diff --git a/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst new file mode 100644 index 0000000..ea3e240 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY.rst @@ -0,0 +1,9 @@ +CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY +------------------------------------------- + +If enabled, the :generator:`Xcode` generator will generate only a +single Xcode project file for the topmost :command:`project()` command +instead of generating one for every ``project()`` command. + +This could be useful to speed up the CMake generation step for +large projects and to work-around a bug in the ``ZERO_CHECK`` logic. diff --git a/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst new file mode 100644 index 0000000..83d5ce7 --- /dev/null +++ b/Help/variable/CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS.rst @@ -0,0 +1,11 @@ +CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS +------------------------------------------- + +Default permissions for implicitly created directories during packaging. + +This variable serves the same purpose during packaging as the +:variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS` variable +serves during installation (e.g. ``make install``). + +If `include(CPack)` is used then by default this variable is set to the content +of :variable:`CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS`. diff --git a/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst new file mode 100644 index 0000000..959596b --- /dev/null +++ b/Help/variable/CTEST_LABELS_FOR_SUBPROJECTS.rst @@ -0,0 +1,5 @@ +CTEST_LABELS_FOR_SUBPROJECTS +---------------------------- + +Specify the CTest ``LabelsForSubprojects`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/LIBRARY_OUTPUT_PATH.rst b/Help/variable/LIBRARY_OUTPUT_PATH.rst index ba02911..bb4328f 100644 --- a/Help/variable/LIBRARY_OUTPUT_PATH.rst +++ b/Help/variable/LIBRARY_OUTPUT_PATH.rst @@ -5,5 +5,5 @@ Old library location variable. The target properties :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` -supercede this variable for a target if they are set. Library targets are +supersede this variable for a target if they are set. Library targets are otherwise placed in this directory. diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst index 8932147..0a3a7a6 100644 --- a/Help/variable/MSVC_VERSION.rst +++ b/Help/variable/MSVC_VERSION.rst @@ -5,13 +5,15 @@ The version of Microsoft Visual C/C++ being used if any. Known version numbers are:: - 1200 = VS 6.0 - 1300 = VS 7.0 - 1310 = VS 7.1 - 1400 = VS 8.0 - 1500 = VS 9.0 - 1600 = VS 10.0 - 1700 = VS 11.0 - 1800 = VS 12.0 - 1900 = VS 14.0 - 1910 = VS 15.0 + 1200 = VS 6.0 + 1300 = VS 7.0 + 1310 = VS 7.1 + 1400 = VS 8.0 (v80 toolset) + 1500 = VS 9.0 (v90 toolset) + 1600 = VS 10.0 (v100 toolset) + 1700 = VS 11.0 (v110 toolset) + 1800 = VS 12.0 (v120 toolset) + 1900 = VS 14.0 (v140 toolset) + 1910-1919 = VS 15.0 (v141 toolset) + +See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. diff --git a/Help/variable/UNIX.rst b/Help/variable/UNIX.rst index 0877b7c..49d8668 100644 --- a/Help/variable/UNIX.rst +++ b/Help/variable/UNIX.rst @@ -1,7 +1,7 @@ UNIX ---- -``True`` for UNIX and UNIX like operating systems. - -Set to ``true`` when the target system is UNIX or UNIX like (i.e. -:variable:`APPLE` and :variable:`CYGWIN`). +Set to ``True`` when the target system is UNIX or UNIX-like +(e.g. :variable:`APPLE` and :variable:`CYGWIN`). The +:variable:`CMAKE_SYSTEM_NAME` variable should be queried if +a more specific understanding of the target system is required. diff --git a/Help/variable/WIN32.rst b/Help/variable/WIN32.rst index 2189069..78ab772 100644 --- a/Help/variable/WIN32.rst +++ b/Help/variable/WIN32.rst @@ -1,6 +1,4 @@ WIN32 ----- -``True`` on Windows systems, including Win64. - -Set to ``true`` when the target system is Windows. +Set to ``True`` when the target system is Windows, including Win64. |