diff options
Diffstat (limited to 'Help')
172 files changed, 3569 insertions, 595 deletions
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 5d71e11..214f4be 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -14,7 +14,7 @@ alternative commands exist to add preprocessor definitions include directories (:command:`target_include_directories` and :command:`include_directories`). See documentation of the :prop_tgt:`directory <COMPILE_OPTIONS>` and -:prop_tgt:` target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. +:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. Arguments to ``add_compile_options`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst index b0c5446..028ca5a 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -156,3 +156,7 @@ target is built before any target using this custom command. Additionally, if the target is an executable or library a file-level dependency is created to cause the custom command to re-run whenever the target is recompiled. + +Arguments to ``DEPENDS`` may use "generator expressions" with the syntax +``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for +available expressions. diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index 231eeed..4ed10e1 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -35,8 +35,11 @@ If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` target property for details. -See the :manual:`cmake-buildsystem(7)` manual for more on defining -buildsystem properties. +Source arguments to ``add_executable`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. + -------------------------------------------------------------------------- diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 0944269..f19b5c0 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -1,8 +1,15 @@ add_library ----------- +.. only:: html + + .. contents:: + Add a library to the project using the specified source files. +Normal Libraries +^^^^^^^^^^^^^^^^ + :: add_library(<name> [STATIC | SHARED | MODULE] @@ -39,10 +46,13 @@ If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` target property for details. -See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem -properties. +Source arguments to ``add_library`` may use "generator expressions" with +the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. --------------------------------------------------------------------------- +Imported Libraries +^^^^^^^^^^^^^^^^^^ :: @@ -63,14 +73,15 @@ variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the location of the main library file on disk. See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. --------------------------------------------------------------------------- +Object Libraries +^^^^^^^^^^^^^^^^ :: add_library(<name> OBJECT <src>...) -Creates a special "object library" target. An object library compiles -source files but does not archive or link their object files into a +Creates an :ref:`Object Library <Object Libraries>`. An object library +compiles source files but does not archive or link their object files into a library. Instead other targets created by :command:`add_library` or :command:`add_executable` may reference the objects using an expression of the form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the @@ -91,7 +102,8 @@ 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>``. --------------------------------------------------------------------------- +Alias Libraries +^^^^^^^^^^^^^^^ :: @@ -109,7 +121,8 @@ operand of :command:`set_property`, :command:`set_target_properties`, :command:`target_link_libraries` etc. An ``ALIAS`` target may not be installed or exported. --------------------------------------------------------------------------- +Interface Libraries +^^^^^^^^^^^^^^^^^^^ :: @@ -122,8 +135,9 @@ imported. Typically the ``INTERFACE_*`` properties are populated on the interface target using the :command:`set_property`, :command:`target_link_libraries(INTERFACE)`, :command:`target_include_directories(INTERFACE)`, -:command:`target_compile_options(INTERFACE)` -and :command:`target_compile_definitions(INTERFACE)` commands, and then it +:command:`target_compile_options(INTERFACE)`, +:command:`target_compile_definitions(INTERFACE)`, +and :command:`target_sources(INTERFACE)` commands, and then it is used as an argument to :command:`target_link_libraries` like any other target. diff --git a/Help/command/cmake_policy.rst b/Help/command/cmake_policy.rst index 46db8d3..2bc3287 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -1,77 +1,93 @@ cmake_policy ------------ -Manage CMake Policy settings. +Manage CMake Policy settings. See the :manual:`cmake-policies(7)` +manual for defined policies. As CMake evolves it is sometimes necessary to change existing behavior in order to fix bugs or improve implementations of existing features. The CMake Policy mechanism is designed to help keep existing projects building as new versions of CMake introduce changes in behavior. Each new policy (behavioral change) is given an identifier of the form -"CMP<NNNN>" where "<NNNN>" is an integer index. Documentation -associated with each policy describes the OLD and NEW behavior and the -reason the policy was introduced. Projects may set each policy to -select the desired behavior. When CMake needs to know which behavior +``CMP<NNNN>`` where ``<NNNN>`` is an integer index. Documentation +associated with each policy describes the ``OLD`` and ``NEW`` behavior +and the reason the policy was introduced. Projects may set each policy +to select the desired behavior. When CMake needs to know which behavior to use it checks for a setting specified by the project. If no -setting is available the OLD behavior is assumed and a warning is +setting is available the ``OLD`` behavior is assumed and a warning is produced requesting that the policy be set. -The cmake_policy command is used to set policies to OLD or NEW -behavior. While setting policies individually is supported, we -encourage projects to set policies based on CMake versions. +Setting Policies by CMake Version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -:: +The ``cmake_policy`` command is used to set policies to ``OLD`` or ``NEW`` +behavior. While setting policies individually is supported, we +encourage projects to set policies based on CMake versions:: cmake_policy(VERSION major.minor[.patch[.tweak]]) -Specify that the current CMake list file is written for the given +Specify that the current CMake code is written for the given version of CMake. All policies introduced in the specified version or -earlier will be set to use NEW behavior. All policies introduced -after the specified version will be unset (unless variable -CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default). This effectively -requests behavior preferred as of a given CMake version and tells -newer CMake versions to warn about their new policies. The policy -version specified must be at least 2.4 or the command will report an -error. In order to get compatibility features supporting versions -earlier than 2.4 see documentation of policy CMP0001. +earlier will be set to use ``NEW`` behavior. All policies introduced +after the specified version will be unset (unless the +:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable sets a default). +This effectively requests behavior preferred as of a given CMake +version and tells newer CMake versions to warn about their new policies. +The policy version specified must be at least 2.4 or the command will +report an error. + +Note that the :command:`cmake_minimum_required(VERSION)` +command implicitly calls ``cmake_policy(VERSION)`` too. + +Setting Policies Explicitly +^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: cmake_policy(SET CMP<NNNN> NEW) cmake_policy(SET CMP<NNNN> OLD) -Tell CMake to use the OLD or NEW behavior for a given policy. +Tell CMake to use the ``OLD`` or ``NEW`` behavior for a given policy. Projects depending on the old behavior of a given policy may silence a -policy warning by setting the policy state to OLD. Alternatively one -may fix the project to work with the new behavior and set the policy -state to NEW. +policy warning by setting the policy state to ``OLD``. Alternatively +one may fix the project to work with the new behavior and set the +policy state to ``NEW``. + +Checking Policy Settings +^^^^^^^^^^^^^^^^^^^^^^^^ :: cmake_policy(GET CMP<NNNN> <variable>) -Check whether a given policy is set to OLD or NEW behavior. The -output variable value will be "OLD" or "NEW" if the policy is set, and -empty otherwise. +Check whether a given policy is set to ``OLD`` or ``NEW`` behavior. +The output ``<variable>`` value will be ``OLD`` or ``NEW`` if the +policy is set, and empty otherwise. + +CMake Policy Stack +^^^^^^^^^^^^^^^^^^ CMake keeps policy settings on a stack, so changes made by the cmake_policy command affect only the top of the stack. A new entry on the policy stack is managed automatically for each subdirectory to protect its parents and siblings. CMake also manages a new entry for -scripts loaded by include() and find_package() commands except when -invoked with the NO_POLICY_SCOPE option (see also policy CMP0011). -The cmake_policy command provides an interface to manage custom -entries on the policy stack: - -:: +scripts loaded by :command:`include` and :command:`find_package` commands +except when invoked with the ``NO_POLICY_SCOPE`` option +(see also policy :policy:`CMP0011`). +The ``cmake_policy`` command provides an interface to manage custom +entries on the policy stack:: cmake_policy(PUSH) cmake_policy(POP) -Each PUSH must have a matching POP to erase any changes. This is -useful to make temporary changes to policy settings. +Each ``PUSH`` must have a matching ``POP`` to erase any changes. +This is useful to make temporary changes to policy settings. +Calls to the :command:`cmake_minimum_required(VERSION)`, +``cmake_policy(VERSION)``, or ``cmake_policy(SET)`` commands +influence only the current top of the policy stack. -Functions and macros record policy settings when they are created and +Commands created by the :command:`function` and :command:`macro` +commands record policy settings when they are created and use the pre-record policies when they are invoked. If the function or macro implementation sets policies, the changes automatically propagate up through callers until they reach the closest nested diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index ac2a0c1..4a95cdd 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -22,3 +22,8 @@ of build errors and warnings detected. The APPEND option marks results for append to those previously submitted to a dashboard server since the last ctest_start. Append semantics are defined by the dashboard server in use. + +If set, the contents of the variable CTEST_BUILD_FLAGS are passed as +additional arguments to the underlying build command. This can e.g. be +used to trigger a parallel build using the -j option of make. See +:module:`ProcessorCount` for an example. diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index f16142e..d7472db 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -10,7 +10,15 @@ Starts the testing for a given model Starts the testing for a given model. The command should be called after the binary directory is initialized. If the 'source' and 'binary' directory are not specified, it reads the -CTEST_SOURCE_DIRECTORY and CTEST_BINARY_DIRECTORY. If the track is +:variable:`CTEST_SOURCE_DIRECTORY` and :variable:`CTEST_BINARY_DIRECTORY`. +If the track is specified, the submissions will go to the specified track. If APPEND is used, the existing TAG is used rather than creating a new one based on the current time stamp. + +If the :variable:`CTEST_CHECKOUT_COMMAND` variable +(or the :variable:`CTEST_CVS_CHECKOUT` variable) +is set, its content is treated as command-line. The command is +invoked with the current working directory set to the parent of the source +directory, even if the source directory already exists. This can be used +to create the source tree from a version control repository. diff --git a/Help/command/export.rst b/Help/command/export.rst index 6b83587..d4bab35 100644 --- a/Help/command/export.rst +++ b/Help/command/export.rst @@ -51,4 +51,7 @@ projects find and use a package from the current project's build tree without help from the user. Note that the entry in the package registry that this command creates works only in conjunction with a package configuration file (<name>Config.cmake) that works with the -build tree. +build tree. In some cases, for example for packaging and for system +wide installations, it is not desirable to write the user package +registry. If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable +is enabled, the ``export(PACKAGE)`` command will do nothing. diff --git a/Help/command/file.rst b/Help/command/file.rst index 83ade1d..58e3a26 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -3,211 +3,302 @@ file File manipulation command. +------------------------------------------------------------------------------ + :: - file(WRITE filename "message to write"... ) - file(APPEND filename "message to write"... ) - file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX]) - file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable) - file(STRINGS filename variable [LIMIT_COUNT num] - [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes] - [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes] - [NEWLINE_CONSUME] [REGEX regex] - [NO_HEX_CONVERSION]) - file(GLOB variable [RELATIVE path] [globbing expressions]...) - file(GLOB_RECURSE variable [RELATIVE path] - [FOLLOW_SYMLINKS] [globbing expressions]...) - file(RENAME <oldname> <newname>) - file(REMOVE [file1 ...]) - file(REMOVE_RECURSE [file1 ...]) - file(MAKE_DIRECTORY [directory1 directory2 ...]) - file(RELATIVE_PATH variable directory file) - file(TO_CMAKE_PATH path result) - file(TO_NATIVE_PATH path result) - file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout] - [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS] - [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum] - [TLS_VERIFY on|off] [TLS_CAINFO file]) - file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout] - [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]) - file(TIMESTAMP filename variable [<format string>] [UTC]) - file(GENERATE OUTPUT output_file - <INPUT input_file|CONTENT input_content> - [CONDITION expression]) - -WRITE will write a message into a file called 'filename'. It -overwrites the file if it already exists, and creates the file if it -does not exist. (If the file is a build input, use configure_file to -update the file only when its content changes.) - -APPEND will write a message into a file same as WRITE, except it will -append it to the end of the file - -READ will read the content of a file and store it into the variable. -It will start at the given offset and read up to numBytes. If the -argument HEX is given, the binary data will be converted to -hexadecimal representation and this will be stored in the variable. - -MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a -cryptographic hash of the content of a file. - -STRINGS will parse a list of ASCII strings from a file and store it in -a variable. Binary data in the file are ignored. Carriage return -(CR) characters are ignored. It works also for Intel Hex and Motorola -S-record files, which are automatically converted to binary format -when reading them. Disable this using NO_HEX_CONVERSION. - -LIMIT_COUNT sets the maximum number of strings to return. LIMIT_INPUT -sets the maximum number of bytes to read from the input file. -LIMIT_OUTPUT sets the maximum number of bytes to store in the output -variable. LENGTH_MINIMUM sets the minimum length of a string to -return. Shorter strings are ignored. LENGTH_MAXIMUM sets the maximum -length of a string to return. Longer strings are split into strings -no longer than the maximum length. NEWLINE_CONSUME allows newlines to -be included in strings instead of terminating them. - -REGEX specifies a regular expression that a string must match to be -returned. Typical usage + file(WRITE <filename> <content>...) + file(APPEND <filename> <content>...) + +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.) + +------------------------------------------------------------------------------ + +:: + + file(READ <filename> <variable> + [OFFSET <offset>] [LIMIT <max-in>] [HEX]) + +Read content from a file called ``<filename>`` and store it in a +``<variable>``. Optionally start from the given ``<offset>`` and +read at most ``<max-in>`` bytes. The ``HEX`` option causes data to +be converted to a hexadecimal representation (useful for binary data). + +------------------------------------------------------------------------------ :: + file(STRINGS <filename> <variable> [<options>...]) + +Parse a list of ASCII strings from ``<filename>`` and store it in +``<variable>``. Binary data in the file are ignored. Carriage return +(``\r``, CR) characters are ignored. The options are: + +``LENGTH_MAXIMUM <max-len>`` + Consider only strings of at most a given length. + +``LENGTH_MINIMUM <min-len>`` + Consider only strings of at least a given length. + +``LIMIT_COUNT <max-num>`` + Limit the number of distinct strings to be extracted. + +``LIMIT_INPUT <max-in>`` + Limit the number of input bytes to read from the file. + +``LIMIT_OUTPUT <max-out>`` + Limit the number of total bytes to store in the ``<variable>``. + +``NEWLINE_CONSUME`` + Treat newline characters (``\n``, LF) as part of string content + instead of terminating at them. + +``NO_HEX_CONVERSION`` + Intel Hex and Motorola S-record files are automatically converted to + binary while reading unless this option is given. + +``REGEX <regex>`` + Consider only strings that match the given regular expression. + +For example, the code + +.. code-block:: cmake + file(STRINGS myfile.txt myfile) -stores a list in the variable "myfile" in which each item is a line +stores a list in the variable ``myfile`` in which each item is a line from the input file. -GLOB will generate a list of all 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 for an expression, the results will be returned as a -relative path to the given path. (We do not recommend using GLOB to -collect a list of source files from your source tree. If no -CMakeLists.txt file changes when a source is added or removed then the -generated build system cannot know when to ask CMake to regenerate.) +------------------------------------------------------------------------------ + +:: + + file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>) + +Compute a cryptographic hash of the content of ``<filename>`` and +store it in a ``<variable>``. + +------------------------------------------------------------------------------ + +:: + + file(GLOB <variable> [RELATIVE <path>] [<globbing-expressions>...]) + file(GLOB_RECURSE <variable> [RELATIVE <path>] + [FOLLOW_SYMLINKS] [<globbing-expressions>...]) + +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. + +.. note:: + We do not recommend using GLOB to collect a list of source files from + your source tree. If no CMakeLists.txt file changes when a source is + added or removed then the generated build system cannot know when to + ask CMake to regenerate. + +Examples of globbing expressions include:: + + *.cxx - match all files with extension cxx + *.vt? - match all files with extension vta,...,vtz + f[3-5].txt - match files f3.txt, f4.txt, f5.txt + +The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the +matched directory and match the files. Subdirectories that are symlinks +are only traversed if ``FOLLOW_SYMLINKS`` is given or policy +:policy:`CMP0009` is not set to ``NEW``. + +Examples of recursive globbing include:: + + /dir/*.py - match all python files in /dir and subdirectories + +------------------------------------------------------------------------------ + +:: + + file(RENAME <oldname> <newname>) + +Move a file or directory within a filesystem from ``<oldname>`` to +``<newname>``, replacing the destination atomically. + +------------------------------------------------------------------------------ + +:: + + file(REMOVE [<files>...]) + file(REMOVE_RECURSE [<files>...]) + +Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given +files and directories, also non-empty directories + +------------------------------------------------------------------------------ + +:: + + file(MAKE_DIRECTORY [<directories>...]) -Examples of globbing expressions include: +Create the given directories and their parents as needed. + +------------------------------------------------------------------------------ :: - *.cxx - match all files with extension cxx - *.vt? - match all files with extension vta,...,vtz - f[3-5].txt - match files f3.txt, f4.txt, f5.txt + file(RELATIVE_PATH <variable> <directory> <file>) -GLOB_RECURSE will generate a list similar to the regular GLOB, except -it will traverse all the subdirectories of the matched directory and -match the files. Subdirectories that are symlinks are only traversed -if FOLLOW_SYMLINKS is given or cmake policy CMP0009 is not set to NEW. -See cmake --help-policy CMP0009 for more information. +Compute the relative path from a ``<directory>`` to a ``<file>`` and +store it in the ``<variable>``. -Examples of recursive globbing include: +------------------------------------------------------------------------------ :: - /dir/*.py - match all python files in /dir and subdirectories - -MAKE_DIRECTORY will create the given directories, also if their parent -directories don't exist yet - -RENAME moves a file or directory within a filesystem, replacing the -destination atomically. - -REMOVE will remove the given files, also in subdirectories - -REMOVE_RECURSE will remove the given files and directories, also -non-empty directories - -RELATIVE_PATH will determine relative path from directory to the given -file. - -TO_CMAKE_PATH will convert path into a cmake style path with unix /. -The input can be a single path or a system path like "$ENV{PATH}". -Note the double quotes around the ENV call TO_CMAKE_PATH only takes -one argument. This command will also convert the native list -delimiters for a list of paths like the PATH environment variable. - -TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert from a -cmake style path into the native path style \ for windows and / for -UNIX. - -DOWNLOAD will download the given URL to the given file. If LOG var is -specified a log of the download will be put in var. If STATUS var is -specified the status of the operation will be put in var. The status -is returned in a list of length 2. The first element is the numeric -return value for the operation, and the second element is a string -value for the error. A 0 numeric error means no error in the -operation. If TIMEOUT time is specified, the operation will timeout -after time seconds, time should be specified as an integer. The -INACTIVITY_TIMEOUT specifies an integer number of seconds of -inactivity after which the operation should terminate. If -EXPECTED_HASH ALGO=value is specified, the operation will verify that -the downloaded file's actual hash matches the expected value, where -ALGO is one of MD5, SHA1, SHA224, SHA256, SHA384, or SHA512. If it -does not match, the operation fails with an error. ("EXPECTED_MD5 -sum" is short-hand for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is -specified, progress information will be printed as status messages -until the operation is complete. For https URLs CMake must be built -with OpenSSL. TLS/SSL certificates are not checked by default. Set -TLS_VERIFY to ON to check certificates and/or use EXPECTED_HASH to -verify downloaded content. Set TLS_CAINFO to specify a custom -Certificate Authority file. If either TLS option is not given CMake -will check variables CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO, -respectively. - -UPLOAD will upload the given file to the given URL. If LOG var is -specified a log of the upload will be put in var. If STATUS var is -specified the status of the operation will be put in var. The status -is returned in a list of length 2. The first element is the numeric -return value for the operation, and the second element is a string -value for the error. A 0 numeric error means no error in the -operation. If TIMEOUT time is specified, the operation will timeout -after time seconds, time should be specified as an integer. The -INACTIVITY_TIMEOUT specifies an integer number of seconds of -inactivity after which the operation should terminate. If -SHOW_PROGRESS is specified, progress information will be printed as -status messages until the operation is complete. - -TIMESTAMP will write a string representation of the modification time -of filename to variable. - -Should the command be unable to obtain a timestamp variable will be -set to the empty string "". - -See documentation of the string TIMESTAMP sub-command for more -details. - -The file() command also provides COPY and INSTALL signatures: + file(TO_CMAKE_PATH "<path>" <variable>) + file(TO_NATIVE_PATH "<path>" <variable>) + +The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style +path with forward-slashes (``/``). The input can be a single path or a +system search path like ``$ENV{PATH}``. A search path will be converted +to a cmake-style list separated by ``;`` characters. + +The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native +path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere). + +Always use double quotes around the ``<path>`` to be sure it is treated +as a single argument to this command. + +------------------------------------------------------------------------------ + +:: + + file(DOWNLOAD <url> <file> [<options>...]) + file(UPLOAD <file> <url> [<options>...]) + +The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``. +The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``. + +Options to both ``DOWNLOAD`` and ``UPLOAD`` are: + +``INACTIVITY_TIMEOUT <seconds>`` + Terminate the operation after a period of inactivity. + +``LOG <variable>`` + Store a human-readable log of the operation in a variable. + +``SHOW_PROGRESS`` + Print progress information as status messages until the operation is + complete. + +``STATUS <variable>`` + Store the resulting status of the operation in a variable. + The status is a ``;`` separated list of length 2. + The first element is the numeric return value for the operation, + and the second element is a string value for the error. + A ``0`` numeric error means no error in the operation. + +``TIMEOUT <seconds>`` + Terminate the operation after a given total time has elapsed. + +Additional options to ``DOWNLOAD`` are: + +``EXPECTED_HASH ALGO=<value>`` + + Verify that the downloaded content hash matches the expected value, where + ``ALGO`` is one of ``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, or + ``SHA512``. If it does not match, the operation fails with an error. + +``EXPECTED_MD5 <value>`` + Historical short-hand for ``EXPECTED_HASH MD5=<value>``. + +``TLS_VERIFY <ON|OFF>`` + Specify whether to verify the server certificate for ``https://`` URLs. + The default is to *not* verify. + +``TLS_CAINFO <file>`` + Specify a custom Certificate Authority file for ``https://`` URLs. + +For ``https://`` URLs CMake must be built with OpenSSL support. ``TLS/SSL`` +certificates are not checked by default. Set ``TLS_VERIFY`` to ``ON`` to +check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content. +If neither ``TLS`` option is given CMake will check variables +``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively. + +------------------------------------------------------------------------------ + +:: + + file(TIMESTAMP <filename> <variable> [<format>] [UTC]) + +Compute a string representation of the modification time of ``<filename>`` +and store it in ``<variable>``. Should the command be unable to obtain a +timestamp variable will be set to the empty string (""). + +See the :command:`string(TIMESTAMP)` command for documentation of +the ``<format>`` and ``UTC`` options. + +------------------------------------------------------------------------------ + +:: + + file(GENERATE <options>...) + +Generate an output file for each build configuration supported by the current +:manual:`CMake Generator <cmake-generators(7)>`. Evaluate +:manual:`generator expressions <cmake-generator-expressions(7)>` +from the input content to produce the output content. The options are: + +``CONDITION <condition>`` + Generate the output file for a particular configuration only if + the condition is true. The condition must be either ``0`` or ``1`` + after evaluating generator expressions. + +``CONTENT <content>`` + Use the content given explicitly as input. + +``INPUT <input-file>`` + Use the content from a given file as input. + +``OUTPUT <output-file>`` + Specify the output file name to generate. Use generator expressions + such as ``$<CONFIG>`` to specify a configuration-specific output file + 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. + +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. + +------------------------------------------------------------------------------ :: - file(<COPY|INSTALL> files... DESTINATION <dir> - [FILE_PERMISSIONS permissions...] - [DIRECTORY_PERMISSIONS permissions...] + file(<COPY|INSTALL> <files>... DESTINATION <dir> + [FILE_PERMISSIONS <permissions>...] + [DIRECTORY_PERMISSIONS <permissions>...] [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS] [FILES_MATCHING] [[PATTERN <pattern> | REGEX <regex>] - [EXCLUDE] [PERMISSIONS permissions...]] [...]) + [EXCLUDE] [PERMISSIONS <permissions>...]] [...]) -The COPY signature copies files, directories, and symlinks to a +The ``COPY`` signature copies files, directories, and symlinks to a destination folder. Relative input paths are evaluated with respect to the current source directory, and a relative destination is evaluated with respect to the current build directory. Copying preserves input file timestamps, and optimizes out a file if it exists at the destination with the same timestamp. Copying preserves input -permissions unless explicit permissions or NO_SOURCE_PERMISSIONS are -given (default is USE_SOURCE_PERMISSIONS). See the install(DIRECTORY) -command for documentation of permissions, PATTERN, REGEX, and EXCLUDE -options. - -The INSTALL signature differs slightly from COPY: it prints status -messages, and NO_SOURCE_PERMISSIONS is default. Installation scripts -generated by the install() command use this signature (with some -undocumented options for internal use). - -GENERATE will write an <output_file> with content from an -<input_file>, or from <input_content>. The output is generated -conditionally based on the content of the <condition>. The file is -written at CMake generate-time and the input may contain generator -expressions. The <condition>, <output_file> and <input_file> may also -contain generator expressions. The <condition> must evaluate to -either '0' or '1'. The <output_file> must evaluate to a unique name -among all configurations and among all invocations of file(GENERATE). +permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS`` +are given (default is ``USE_SOURCE_PERMISSIONS``). +See the :command:`install(DIRECTORY)` command for documentation of +permissions, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options. + +The ``INSTALL`` signature differs slightly from ``COPY``: it prints +status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), +and ``NO_SOURCE_PERMISSIONS`` is default. +Installation scripts generated by the :command:`install` command +use this signature (with some undocumented options for internal use). diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 5d9aea6..190d05c 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -272,7 +272,9 @@ enabled. (This step is implemented only on Windows.) 6. Search paths stored in the CMake :ref:`User Package Registry`. - This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed. + This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by + setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` + to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the user package registry. @@ -285,7 +287,9 @@ enabled. CMAKE_SYSTEM_APPBUNDLE_PATH 8. Search paths stored in the CMake :ref:`System Package Registry`. - This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed. + This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed + or by setting the + :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. See the :manual:`cmake-packages(7)` manual for details on the system package registry. diff --git a/Help/command/install.rst b/Help/command/install.rst index 47108f0..4c52abf 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1,8 +1,15 @@ install ------- +.. only:: html + + .. contents:: + Specify rules to run at install time. +Introduction +^^^^^^^^^^^^ + This command generates installation rules for a project. Rules specified by calls to this command within a source directory are executed in order during installation. The order across directories @@ -52,7 +59,12 @@ signatures that specify them. The common options are: Specify that it is not an error if the file to be installed does not exist. ------------------------------------------------------------------------------- +Command signatures that install files may print messages during +installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable +to control which messages are printed. + +Installing Targets +^^^^^^^^^^^^^^^^^^ :: @@ -147,7 +159,8 @@ file itself, call ``install(EXPORT)``, documented below. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. ------------------------------------------------------------------------------- +Installing Files +^^^^^^^^^^^^^^^^ :: @@ -175,14 +188,15 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use However, if any item begins in a generator expression it must evaluate to a full path. ------------------------------------------------------------------------------- +Installing Directories +^^^^^^^^^^^^^^^^^^^^^^ :: install(DIRECTORY dirs... DESTINATION <dir> [FILE_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS permissions...] - [USE_SOURCE_PERMISSIONS] [OPTIONAL] + [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] [FILES_MATCHING] [[PATTERN <pattern> | REGEX <regex>] @@ -205,6 +219,8 @@ permissions specified in the ``FILES`` form of the command, and the directories will be given the default permissions specified in the ``PROGRAMS`` form of the command. +The ``MESSAGE_NEVER`` option disables file installation status output. + Installation of directories may be controlled with fine granularity using the ``PATTERN`` or ``REGEX`` options. These "match" options specify a globbing pattern or regular expression to match directories or files @@ -247,7 +263,8 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the file permissions, the scripts will be given specific permissions, and any ``CVS`` directories will be excluded. ------------------------------------------------------------------------------- +Custom Installation Logic +^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -266,7 +283,8 @@ example, the code will print a message during installation. ------------------------------------------------------------------------------- +Installing Exports +^^^^^^^^^^^^^^^^^^ :: diff --git a/Help/command/string.rst b/Help/command/string.rst index af18825..abde6ee 100644 --- a/Help/command/string.rst +++ b/Help/command/string.rst @@ -35,6 +35,7 @@ String operations. string(FIND <string> <substring> <output variable> [REVERSE]) string(TIMESTAMP <output variable> [<format string>] [UTC]) string(MAKE_C_IDENTIFIER <input string> <output variable>) + string(GENEX_STRIP <input string> <output variable>) REGEX MATCH will match the regular expression once and store the match in the output variable. @@ -154,3 +155,7 @@ If no explicit <format string> is given it will default to: MAKE_C_IDENTIFIER will write a string which can be used as an identifier in C. + +``GENEX_STRIP`` will strip any +:manual:`generator expressions <cmake-generator-expressions(7)>` from the +``input string`` and store the result in the ``output variable``. diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst new file mode 100644 index 0000000..29a8b41 --- /dev/null +++ b/Help/command/target_compile_features.rst @@ -0,0 +1,32 @@ +target_compile_features +----------------------- + +Add expected compiler features to a target. + +:: + + target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...]) + +Specify compiler features required when compiling a given target. If the +feature is not listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable +or :variable:`CMAKE_CXX_COMPILE_FEATURES` variable, +then an error will be reported by CMake. If the use of the feature requires +an additional compiler flag, such as ``-std=gnu++11``, the flag will be added +automatically. + +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. + +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. + +Arguments to ``target_compile_features`` may use "generator expressions" +with the syntax ``$<...>``. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-compile-features(7)` manual for +information on compile features. diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst new file mode 100644 index 0000000..ff756b4 --- /dev/null +++ b/Help/command/target_sources.rst @@ -0,0 +1,28 @@ +target_sources +-------------- + +Add sources to a target. + +:: + + target_sources(<target> + <INTERFACE|PUBLIC|PRIVATE> [items1...] + [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) + +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 +:prop_tgt:`IMPORTED Target`. + +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 +``<target>`` append items in the order called. + +Arguments to ``target_sources`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/index.rst b/Help/index.rst index a4abfbf..2d3f156 100644 --- a/Help/index.rst +++ b/Help/index.rst @@ -27,6 +27,7 @@ Reference Manuals /manual/cmake-buildsystem.7 /manual/cmake-commands.7 + /manual/cmake-compile-features.7 /manual/cmake-developer.7 /manual/cmake-generator-expressions.7 /manual/cmake-generators.7 diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index f3a5770..a7402f7 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -19,8 +19,8 @@ and the rules for regeneration in response to change. Binary Targets ============== -Executables and libraries are defined using the :command:`add_library` -and :command:`add_executable` commands. The resulting binary files have +Executables and libraries are defined using the :command:`add_executable` +and :command:`add_library` commands. The resulting binary files have appropriate prefixes, suffixes and extensions for the platform targeted. Dependencies between binary targets are expressed using the :command:`target_link_libraries` command: @@ -37,9 +37,28 @@ is defined as an executable formed by compiling and linking ``zipapp.cpp``. When linking the ``zipapp`` executable, the ``archive`` static library is linked in. +Binary Executables +------------------ + +The :command:`add_executable` command defines an executable target: + +.. code-block:: cmake + + add_executable(mytool mytool.cpp) + +Commands such as :command:`add_custom_command`, which generates rules to be +run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>` +target as a ``COMMAND`` executable. The buildsystem rules will ensure that +the executable is built before attempting to run the command. + Binary Library Types -------------------- +.. _`Normal Libraries`: + +Normal Libraries +^^^^^^^^^^^^^^^^ + By default, the :command:`add_library` command defines a static library, unless a type is specified. A type may be specified when using the command: @@ -66,6 +85,11 @@ It is a type which is loaded as a plugin using runtime techniques. add_library(archive MODULE 7z.cpp) +.. _`Object Libraries`: + +Object Libraries +^^^^^^^^^^^^^^^^ + The ``OBJECT`` library type is also not linked to. It defines a non-archival collection of object files resulting from compiling the given source files. The object files collection can be used as source inputs to other targets: @@ -83,11 +107,6 @@ they may not be installed, exported, or used in the right hand side of :command:`target_link_libraries`. They also may not be used as the ``TARGET`` in a use of the :command:`add_custom_command(TARGET)` command signature. -Commands such as :command:`add_custom_command`, which generates rules to be -run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>` -target as a ``COMMAND`` executable. The buildsystem rules will ensure that -the executable is built before attempting to run the command. - Build Specification and Usage Requirements ========================================== @@ -551,7 +570,7 @@ exporting see the :manual:`cmake-packages(7)` manual. .. _`Include Directories and Usage Requirements`: Include Directories and Usage Requirements -'''''''''''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Include directories require some special consideration when specified as usage requirements and when used with generator expressions. The @@ -786,11 +805,12 @@ It may specify usage requirements such as :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`, :prop_tgt:`INTERFACE_COMPILE_OPTIONS`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and +:prop_tgt:`INTERFACE_SOURCES`, :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. Only the ``INTERFACE`` modes of the :command:`target_include_directories`, :command:`target_compile_definitions`, :command:`target_compile_options`, -and :command:`target_link_libraries` commands may be used with ``INTERFACE`` -libraries. +:command:`target_sources`, and :command:`target_link_libraries` commands +may be used with ``INTERFACE`` libraries. A primary use-case for ``INTERFACE`` libraries is header-only libraries. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index fb0d2b5..8ff73a4 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -91,9 +91,11 @@ These commands may be used freely in CMake projects. /command/source_group /command/string /command/target_compile_definitions + /command/target_compile_features /command/target_compile_options /command/target_include_directories /command/target_link_libraries + /command/target_sources /command/try_compile /command/try_run /command/unset @@ -126,6 +128,8 @@ versions of CMake. Do not use them in new code. /command/variable_requires /command/write_file +.. _`CTest Commands`: + CTest Commands ============== diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst new file mode 100644 index 0000000..8a2fe30 --- /dev/null +++ b/Help/manual/cmake-compile-features.7.rst @@ -0,0 +1,294 @@ +.. cmake-manual-description: CMake Compile Features Reference + +cmake-compile-features(7) +************************* + +.. only:: html or latex + + .. contents:: + +Introduction +============ + +Project source code may depend on, or be conditional on, the availability +of certain features of the compiler. There are three use-cases which arise: +`Compile Feature Requirements`_, `Optional Compile Features`_ +and `Conditional Compilation Options`_. + +While features are typically specified in programming language standards, +CMake provides a primary user interface based on granular handling of +the features, not the language standard that introduced the feature. + +The :prop_gbl:`CMAKE_C_KNOWN_FEATURES` and +:prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` global properties contain all the +features known to CMake, regardless of compiler support for the feature. +The :variable:`CMAKE_C_COMPILE_FEATURES` and +:variable:`CMAKE_CXX_COMPILE_FEATURES` variables contain all features +CMake knows are known to the compiler, regardless of language standard +or compile flags needed to use them. + +Features known to CMake are named mostly following the same convention +as the Clang feature test macros. The are some execptions, such as +CMake using ``cxx_final`` and ``cxx_override`` instead of the single +``cxx_override_control`` used by Clang. + +Compile Feature Requirements +============================ + +Compile feature requirements may be specified with the +:command:`target_compile_features` command. For example, if a target must +be compiled with compiler support for the +:prop_gbl:`cxx_constexpr <CMAKE_CXX_KNOWN_FEATURES>` feature: + +.. code-block:: cmake + + add_library(mylib requires_constexpr.cpp) + target_compile_features(mylib PRIVATE cxx_constexpr) + +In processing the requirement for the ``cxx_constexpr`` feature, +:manual:`cmake(1)` will ensure that the in-use C++ compiler is capable +of the feature, and will add any necessary flags such as ``-std=gnu++11`` +to the compile lines of C++ files in the ``mylib`` target. A +``FATAL_ERROR`` is issued if the compiler is not capable of the +feature. + +The exact compile flags and language standard are deliberately not part +of the user interface for this use-case. CMake will compute the +appropriate compile flags to use by considering the features specified +for each target. + +Such compile flags are added even if the compiler supports the +particular feature without the flag. For example, the GNU compiler +supports variadic templates (with a warning) even if ``-std=gnu++98`` is +used. CMake adds the ``-std=gnu++11`` flag if ``cxx_variadic_templates`` +is specified as a requirement. + +In the above example, ``mylib`` requires ``cxx_constexpr`` when it +is built itself, but consumers of ``mylib`` are not required to use a +compiler which supports ``cxx_constexpr``. If the interface of +``mylib`` does require the ``cxx_constexpr`` feature (or any other +known feature), that may be specified with the ``PUBLIC`` or +``INTERFACE`` signatures of :command:`target_compile_features`: + +.. code-block:: cmake + + add_library(mylib requires_constexpr.cpp) + # cxx_constexpr is a usage-requirement + target_compile_features(mylib PUBLIC cxx_constexpr) + + # main.cpp will be compiled with -std=gnu++11 on GNU for cxx_constexpr. + add_executable(myexe main.cpp) + target_link_libraries(myexe mylib) + +Feature requirements are evaluated transitively by consuming the link +implementation. See :manual:`cmake-buildsystem(7)` for more on +transitive behavior of build properties and usage requirements. + +Because the :prop_tgt:`CXX_EXTENSIONS` target property is ``ON`` by default, +CMake uses extended variants of language dialects by default, such as +``-std=gnu++11`` instead of ``-std=c++11``. That target property may be +set to ``OFF`` to use the non-extended variant of the dialect flag. Note +that because most compilers enable extensions by default, this could +expose cross-platform bugs in user code or in the headers of third-party +dependencies. + +Optional Compile Features +========================= + +Compile features may be preferred if available, without creating a hard +requirement. For example, a library may provides alternative +implementations depending on whether the ``cxx_variadic_templates`` +feature is available: + +.. code-block:: c++ + + #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES + template<int I, int... Is> + struct Interface; + + template<int I> + struct Interface<I> + { + static int accumulate() + { + return I; + } + }; + + template<int I, int... Is> + struct Interface + { + static int accumulate() + { + return I + Interface<Is...>::accumulate(); + } + }; + #else + template<int I1, int I2 = 0, int I3 = 0, int I4 = 0> + struct Interface + { + static int accumulate() { return I1 + I2 + I3 + I4; } + }; + #endif + +Such an interface depends on using the correct preprocessor defines for the +compiler features. CMake can generate a header file containing such +defines using the :module:`WriteCompilerDetectionHeader` module. The +module contains the ``write_compiler_detection_header`` function which +accepts parameters to control the content of the generated header file: + +.. code-block:: cmake + + write_compiler_detection_header( + FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h" + PREFIX Foo + COMPILERS GNU + FEATURES + cxx_variadic_templates + ) + +Such a header file may be used internally in the source code of a project, +and it may be installed and used in the interface of library code. + +For each feature listed in ``FEATURES``, a preprocessor definition +is created in the header file, and defined to either ``1`` or ``0``. + +Additionally, some features call for additional defines, such as the +``cxx_final`` and ``cxx_override`` features. Rather than being used in +``#ifdef`` code, the ``final`` keyword is abstracted by a symbol +which is defined to either ``final``, a compiler-specific equivalent, or +to empty. That way, C++ code can be written to unconditionally use the +symbol, and compiler support determines what it is expanded to: + +.. code-block:: c++ + + struct Interface { + virtual void Execute() = 0; + }; + + struct Concrete Foo_FINAL { + void Execute() Foo_OVERRIDE; + }; + +In this case, ``Foo_FINAL`` will expand to ``final`` if the +compiler supports the keyword, or to empty otherwise. + +In this use-case, the CMake code will wish to enable a particular language +standard if available from the compiler. The :prop_tgt:`CXX_STANDARD` +target property variable may be set to the desired language standard +for a particular target, and the :variable:`CMAKE_CXX_STANDARD` may be +set to influence all following targets: + +.. code-block:: cmake + + write_compiler_detection_header( + FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h" + PREFIX Foo + COMPILERS GNU + FEATURES + cxx_final cxx_override + ) + + # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol + # which will expand to 'final' if the compiler supports the requested + # CXX_STANDARD. + add_library(foo foo.cpp) + set_property(TARGET foo PROPERTY CXX_STANDARD 11) + + # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol + # which will expand to 'final' if the compiler supports the feature, + # even though CXX_STANDARD is not set explicitly. The requirement of + # cxx_constexpr causes CMake to set CXX_STANDARD internally, which + # affects the compile flags. + add_library(foo_impl foo_impl.cpp) + target_compile_features(foo_impl PRIVATE cxx_constexpr) + +The ``write_compiler_detection_header`` function also creates compatibility +code for other features which have standard equivalents. For example, the +``cxx_static_assert`` feature is emulated with a template and abstracted +via the ``<PREFIX>_STATIC_ASSERT`` and ``<PREFIX>_STATIC_ASSERT_MSG`` +function-macros. + +Conditional Compilation Options +=============================== + +Libraries may provide entirely different header files depending on +requested compiler features. + +For example, a header at ``with_variadics/interface.h`` may contain: + +.. code-block:: c++ + + template<int I, int... Is> + struct Interface; + + template<int I> + struct Interface<I> + { + static int accumulate() + { + return I; + } + }; + + template<int I, int... Is> + struct Interface + { + static int accumulate() + { + return I + Interface<Is...>::accumulate(); + } + }; + +while a header at ``no_variadics/interface.h`` may contain: + +.. code-block:: c++ + + template<int I1, int I2 = 0, int I3 = 0, int I4 = 0> + struct Interface + { + static int accumulate() { return I1 + I2 + I3 + I4; } + }; + +It would be possible to write a abstraction ``interface.h`` header +containing something like: + +.. code-block:: c++ + + #include "foo_compiler_detection.h" + #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES + #include "with_variadics/interface.h" + #else + #include "no_variadics/interface.h" + #endif + +However this could be unmaintainable if there are many files to +abstract. What is needed is to use alternative include directories +depending on the compiler capabilities. + +CMake provides a ``COMPILE_FEATURES`` +:manual:`generator expression <cmake-generator-expressions(7)>` to implement +such conditions. This may be used with the build-property commands such as +:command:`target_include_directories` and :command:`target_link_libraries` +to set the appropriate :manual:`buildsystem <cmake-buildsystem(7)>` +properties: + +.. code-block:: cmake + + add_library(foo INTERFACE) + target_link_libraries(foo + INTERFACE + "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${CMAKE_CURRENT_SOURCE_DIR}/with_variadics>" + "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${CMAKE_CURRENT_SOURCE_DIR}/no_variadics>") + +Consuming code then simply links to the ``foo`` target as usual and uses +the feature-appropriate include directory + +.. code-block:: cmake + + add_executable(consumer_with consumer_with.cpp) + target_link_libraries(consumer_with foo) + set_property(TARGET consumer_with CXX_STANDARD 11) + + add_executable(consumer_no consumer_no.cpp) + target_link_libraries(consumer_no foo) diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 376b56c..cd979c9 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -55,7 +55,7 @@ used in a comparison with the iterator returned by ``end()``: .. code-block:: c++ - const std::set<cmStdString>& someSet = getSet(); + const std::set<std::string>& someSet = getSet(); if (someSet.find("needle") == someSet.end()) // Wrong { // ... @@ -66,8 +66,8 @@ The return value of ``find()`` must be assigned to an intermediate .. code-block:: c++ - const std::set<cmStdString>& someSet; - const std::set<cmStdString>::const_iterator i = someSet.find("needle"); + const std::set<std::string>& someSet; + const std::set<std::string>::const_iterator i = someSet.find("needle"); if (i != propSet.end()) // Ok { // ... @@ -110,7 +110,7 @@ conversion is not allowed: .. code-block:: c++ - std::set<cmStdString> theSet; + std::set<const char*> theSet; std::vector<std::string> theVector; theVector.insert(theVector.end(), theSet.begin(), theSet.end()); // Wrong @@ -118,9 +118,9 @@ A loop must be used instead: .. code-block:: c++ - std::set<cmStdString> theSet; + std::set<const char*> theSet; std::vector<std::string> theVector; - for(std::set<cmStdString>::iterator li = theSet.begin(); + for(std::set<const char*>::iterator li = theSet.begin(); li != theSet.end(); ++li) { theVector.push_back(*li); @@ -197,6 +197,51 @@ Templates Some template code is permitted, but with some limitations. Member templates may not be used, and template friends may not be used. +Adding Compile Features +======================= + +CMake reports an error if a compiler whose features are known does not report +support for a particular requested feature. A compiler is considered to have +known features if it reports support for at least one feature. + +When adding a new compile feature to CMake, it is therefore necessary to list +support for the feature for all CompilerIds which already have one or more +feature supported, if the new feature is available for any version of the +compiler. + +When adding the first supported feature to a particular CompilerId, it is +necessary to list support for all features known to cmake (See +:variable:`CMAKE_C_COMPILE_FEATURES` and +:variable:`CMAKE_CXX_COMPILE_FEATURES` as appropriate), where available for +the compiler. + +It is sensible to record the features for the most recent version of a +particular CompilerId first, and then work backwards. It is sensible to +try to create a continuous range of versions of feature releases of the +compiler. Gaps in the range indicate incorrect features recorded for +intermediate releases. + +Generally, features are made available for a particular version if the +compiler vendor documents availability of the feature with that +version. Note that sometimes partially implemented features appear to +be functional in previous releases (such as ``cxx_constexpr`` in GNU 4.6, +though availability is documented in GNU 4.7), and sometimes compiler vendors +document availability of features, though supporting infrastructure is +not available (such as ``__has_feature(cxx_generic_lambdas)`` indicating +non-availability in Clang 3.4, though it is documented as available, and +fixed in Clang 3.5). Similar cases for other compilers and versions +need to be investigated when extending CMake to support them. + +When a vendor releases a new version of a known compiler which supports +a previously unsupported feature, and there are already known features for +that compiler, the feature should be listed as supported in CMake for +that version of the compiler as soon as reasonably possible. + +Standard-specific/compiler-specific variables such +``CMAKE_CXX98_COMPILE_FEATURES`` are deliberately not documented. They +only exist for the compiler-specific implementation of adding the ``-std`` +compile flag for compilers which need that. + Help ==== @@ -331,10 +376,10 @@ documentation: See the :manual:`cmake-policies(7)` manual and the :command:`cmake_policy` command. -``prop_cache, prop_dir, prop_gbl, prop_sf, prop_test, prop_tgt`` - A CMake cache, directory, global, source file, test, or target - property, respectively. See the :manual:`cmake-properties(7)` manual - and the :command:`set_property` command. +``prop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt`` + A CMake cache, directory, global, source file, installed file, test, + or target property, respectively. See the :manual:`cmake-properties(7)` + manual and the :command:`set_property` command. ``variable`` A CMake language variable. @@ -420,168 +465,196 @@ with an explicit target. Style ----- -1) - Command signatures should be marked up as plain literal blocks, not as - cmake ``code-blocks``. +Style: Section Headers +^^^^^^^^^^^^^^^^^^^^^^ + +When marking section titles, make the section decoration line as long as +the title text. Use only a line below the title, not above. For +example: + +.. code-block:: rst + + Title Text + ---------- + +Capitalize the first letter of each non-minor word in the title. + +The section header underline character hierarchy is + +* ``#``: Manual group (part) in the master document +* ``*``: Manual (chapter) title +* ``=``: Section within a manual +* ``-``: Subsection or `CMake Domain`_ object document title +* ``^``: Subsubsection or `CMake Domain`_ object document section +* ``"``: Paragraph or `CMake Domain`_ object document subsection + +Style: Whitespace +^^^^^^^^^^^^^^^^^ + +Use two spaces for indentation. Use two spaces between sentences in +prose. -2) - Signatures are separated from preceding content by a horizontal - line. That is, use: +Style: Line Length +^^^^^^^^^^^^^^^^^^ - .. code-block:: rst +Prefer to restrict the width of lines to 75-80 columns. This is not a +hard restriction, but writing new paragraphs wrapped at 75 columns +allows space for adding minor content without significant re-wrapping of +content. - ... preceding paragraph. +Style: Prose +^^^^^^^^^^^^ - --------------------------------------------------------------------- +Use American English spellings in prose. - :: +Style: Starting Literal Blocks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - add_library(<lib> ...) +Prefer to mark the start of literal blocks with ``::`` at the end of +the preceding paragraph. In cases where the following block gets +a ``code-block`` marker, put a single ``:`` at the end of the preceding +paragraph. - This signature is used for ... +Style: CMake Command Signatures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -3) - Use "``OFF``" and "``ON``" for boolean values which can be modified by - the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties - may be "enabled" and "disabled". Use "``True``" and "``False``" for - inherent values which can't be modified after being set, such as the - :prop_tgt:`IMPORTED` property of a build target. +Command signatures should be marked up as plain literal blocks, not as +cmake ``code-blocks``. -4) - Use two spaces for indentation. Use two spaces between sentences in - prose. +Signatures are separated from preceding content by a section header. +That is, use: -5) - Prefer to mark the start of literal blocks with ``::`` at the end of - the preceding paragraph. In cases where the following block gets - a ``code-block`` marker, put a single ``:`` at the end of the preceding - paragraph. +.. code-block:: rst + + ... preceding paragraph. + + Normal Libraries + ^^^^^^^^^^^^^^^^ -6) - Prefer to restrict the width of lines to 75-80 columns. This is not a - hard restriction, but writing new paragraphs wrapped at 75 columns - allows space for adding minor content without significant re-wrapping of - content. + :: -7) - Mark up self-references with ``inline-literal`` syntax. For example, - within the add_executable command documentation, use + add_library(<lib> ...) - .. code-block:: rst + This signature is used for ... - ``add_executable`` +Signatures of commands should wrap optional parts with square brackets, +and should mark list of optional arguments with an ellipsis (``...``). +Elements of the signature which are specified by the user should be +specified with angle brackets, and may be referred to in prose using +``inline-literal`` syntax. - not +Style: Boolean Constants +^^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: rst +Use "``OFF``" and "``ON``" for boolean values which can be modified by +the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties +may be "enabled" and "disabled". Use "``True``" and "``False``" for +inherent values which can't be modified after being set, such as the +:prop_tgt:`IMPORTED` property of a build target. - :command:`add_executable` +Style: Inline Literals +^^^^^^^^^^^^^^^^^^^^^^ - which is used elsewhere. +Mark up references to keywords in signatures, file names, and other +technical terms with ``inline-literal`` syntax, for example: + +.. code-block:: rst -8) - Mark up all other linkable references as links, including repeats. An - alternative, which is used by wikipedia (`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_), - is to link to a reference only once per article. That style is not used - in CMake documentation. + If ``WIN32`` is used with :command:`add_executable`, the + :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command + creates the file ``<name>.exe`` on Windows. -9) - Mark up references to keywords in signatures, file names, and other - technical terms with ``inline-literl`` syntax, for example: +Style: Cross-References +^^^^^^^^^^^^^^^^^^^^^^^ - .. code-block:: rst +Mark up linkable references as links, including repeats. +An alternative, which is used by wikipedia +(`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_), +is to link to a reference only once per article. That style is not used +in CMake documentation. - If ``WIN32`` is used with :command:`add_executable`, the - :prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command - creates the file ``<name>.exe`` on Windows. +Style: Referencing CMake Concepts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If referring to a concept which corresponds to a property, and that +concept is described in a high-level manual, prefer to link to the +manual section instead of the property. For example: -10) - If referring to a concept which corresponds to a property, and that - concept is described in a high-level manual, prefer to link to the - manual section instead of the property. For example: +.. code-block:: rst - .. code-block:: rst + This command creates an :ref:`Imported Target <Imported Targets>`. - This command creates an :ref:`Imported Target <Imported Targets>`. +instead of: - instead of: +.. code-block:: rst - .. code-block:: rst + This command creates an :prop_tgt:`IMPORTED` target. - This command creates an :prop_tgt:`IMPORTED` target. +The latter should be used only when referring specifically to the +property. - The latter should be used only when referring specifically to the - property. +References to manual sections are not automatically created by creating +a section, but code such as: - References to manual sections are not automatically created by creating - a section, but code such as: +.. code-block:: rst - .. code-block:: rst + .. _`Imported Targets`: - .. _`Imported Targets`: +creates a suitable anchor. Use an anchor name which matches the name +of the corresponding section. Refer to the anchor using a +cross-reference with specified text. - creates a suitable anchor. Use an anchor name which matches the name - of the corresponding section. Refer to the anchor using a - cross-reference with specified text. +Imported Targets need the ``IMPORTED`` term marked up with care in +particular because the term may refer to a command keyword +(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a +concept (:ref:`Imported Targets`). - Imported Targets need the ``IMPORTED`` term marked up with care in - particular because the term may refer to a command keyword - (``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a - concept (:ref:`Imported Targets`). +Where a property, command or variable is related conceptually to others, +by for example, being related to the buildsystem description, generator +expressions or Qt, each relevant property, command or variable should +link to the primary manual, which provides high-level information. Only +particular information relating to the command should be in the +documentation of the command. -11) - Where a property, command or variable is related conceptually to others, - by for example, being related to the buildsystem description, generator - expressions or Qt, each relevant property, command or variable should - link to the primary manual, which provides high-level information. Only - particular information relating to the command should be in the - documentation of the command. +Style: Referencing CMake Domain Objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -12) - When marking section titles, make the section decoration line as long as - the title text. Use only a line below the title, not above. For - example: +When referring to `CMake Domain`_ objects such as properties, variables, +commands etc, prefer to link to the target object and follow that with +the type of object it is. For example: - .. code-block:: rst +.. code-block:: rst - Title Text - ---------- + Set the :prop_tgt:`AUTOMOC` target property to ``ON``. - Capitalize the first letter of each non-minor word in the title. +Instead of -13) - When referring to properties, variables, commands etc, prefer to link - to the target object and follow that with the type of object it is. - For example: +.. code-block:: rst - .. code-block:: rst + Set the target property :prop_tgt:`AUTOMOC` to ``ON``. - Set the :prop_tgt:`AUTOMOC` target property to ``ON``. +The ``policy`` directive is an exception, and the type us usually +referred to before the link: - Instead of +.. code-block:: rst - .. code-block:: rst + If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... - Set the target property :prop_tgt:`AUTOMOC` to ``ON``. +However, markup self-references with ``inline-literal`` syntax. +For example, within the :command:`add_executable` command +documentation, use - The ``policy`` directive is an exception, and the type us usually - referred to before the link: +.. code-block:: rst - .. code-block:: rst + ``add_executable`` - If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ... +not -14) - Signatures of commands should wrap optional parts with square brackets, - and should mark list of optional arguments with an ellipsis (``...``). - Elements of the signature which are specified by the user should be - specified with angle brackets, and may be referred to in prose using - ``inline-literal`` syntax. +.. code-block:: rst -15) - Use American English spellings in prose. + :command:`add_executable` +which is used elsewhere. Modules ======= @@ -664,213 +737,408 @@ For example, a ``Modules/Findxxx.cmake`` module may contain: <code> endmacro() +After the top documentation block, leave a *BLANK* line, and then add a +copyright and licence notice block like this one (change only the year +range and name) + +.. code-block:: cmake + + #============================================================================= + # Copyright 2009-2011 Your Name + # + # Distributed under the OSI-approved BSD License (the "License"); + # see accompanying file Copyright.txt for details. + # + # This software is distributed WITHOUT ANY WARRANTY; without even the + # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + # See the License for more information. + #============================================================================= + # (To distribute this file outside of CMake, substitute the full + # License text for the above reference.) + +Test the documentation formatting by running +``cmake --help-module <module-name>``, and also by enabling the +``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. +Edit the comments until generated documentation looks satisfactory. To +have a .cmake file in this directory NOT show up in the modules +documentation, simply leave out the ``Help/module/<module-name>.rst`` +file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. + + Find Modules ------------ A "find module" is a ``Modules/Find<package>.cmake`` file to be loaded by the :command:`find_package` command when invoked for ``<package>``. -We would like all ``FindXxx.cmake`` files to produce consistent variable -names. Please use the following consistent variable names for general use. +The primary task of a find module is to determine whether a package +exists on the system, set the ``<package>_FOUND`` variable to reflect +this and provide any variables, macros and imported targets required to +use the package. + +The traditional approach is to use variables for everything, including +libraries and executables: see the `Standard Variable Names`_ section +below. This is what most of the existing find modules provided by CMake +do. + +The more modern approach is to behave as much like +``<package>Config.cmake`` files as possible, by providing imported +targets. As well as matching how ``*Config.cmake`` files work, the +libraries, include directories and compile definitions are all set just +by using the target in a :command:`target_link_libraries` call. The +disadvantage is that ``*Config.cmake`` files of projects that use +imported targets from find modules may require more work to make sure +those imported targets that are in the link interface are available. + +In either case (or even when providing both variables and imported +targets), find modules should provide backwards compatibility with old +versions that had the same name. + +A FindFoo.cmake module will typically be loaded by the command:: + + find_package(Foo [major[.minor[.patch[.tweak]]]] + [EXACT] [QUIET] [REQUIRED] + [[COMPONENTS] [components...]] + [OPTIONAL_COMPONENTS components...] + [NO_POLICY_SCOPE]) + +See the :command:`find_package` documentation for details on what +variables are set for the find module. Most of these are dealt with by +using :module:`FindPackageHandleStandardArgs`. + +Briefly, the module should only locate versions of the package +compatible with the requested version, as described by the +``Foo_FIND_VERSION`` family of variables. If ``Foo_FIND_QUIETLY`` is +set to true, it should avoid printing messages, including anything +complaining about the package not being found. If ``Foo_FIND_REQUIRED`` +is set to true, the module should issue a ``FATAL_ERROR`` if the package +cannot be found. If neither are set to true, it should print a +non-fatal message if it cannot find the package. + +Packages that find multiple semi-independent parts (like bundles of +libraries) should search for the components listed in +``Foo_FIND_COMPONENTS`` if it is set , and only set ``Foo_FOUND`` to +true if for each searched-for component ``<c>`` that was not found, +``Foo_FIND_REQUIRED_<c>`` is not set to true. The ``HANDLE_COMPONENTS`` +argument of ``find_package_handle_standard_args()`` can be used to +implement this. + +If ``Foo_FIND_COMPONENTS`` is not set, which modules are searched for +and required is up to the find module, but should be documented. + +For internal implementation, it is a generally accepted convention that +variables starting with underscore are for temporary use only. + +Like all modules, find modules should be properly documented. To add a +module to the CMake documentation, follow the steps in the `Module +Documentation`_ section above. + + + +Standard Variable Names +^^^^^^^^^^^^^^^^^^^^^^^ + +For a ``FindXxx.cmake`` module that takes the approach of setting +variables (either instead of or in addition to creating imported +targets), the following variable names should be used to keep things +consistent between find modules. Note that all variables start with +``Xxx_`` to make sure they do not interfere with other find modules; the +same consideration applies to macros, functions and imported targets. + +``Xxx_INCLUDE_DIRS`` + The final set of include directories listed in one variable for use by + client code. This should not be a cache entry. + +``Xxx_LIBRARIES`` + The libraries to link against to use Xxx. These should include full + paths. This should not be a cache entry. + +``Xxx_DEFINITIONS`` + Definitions to use when compiling code that uses Xxx. This really + shouldn't include options such as ``-DHAS_JPEG`` that a client + source-code file uses to decide whether to ``#include <jpeg.h>`` + +``Xxx_EXECUTABLE`` + Where to find the Xxx tool. + +``Xxx_Yyy_EXECUTABLE`` + Where to find the Yyy tool that comes with Xxx. + +``Xxx_LIBRARY_DIRS`` + Optionally, the final set of library directories listed in one + variable for use by client code. This should not be a cache entry. + +``Xxx_ROOT_DIR`` + Where to find the base directory of Xxx. + +``Xxx_VERSION_Yy`` + Expect Version Yy if true. Make sure at most one of these is ever true. + +``Xxx_WRAP_Yy`` + If False, do not try to use the relevant CMake wrapping command. + +``Xxx_Yy_FOUND`` + If False, optional Yy part of Xxx sytem is not available. -Xxx_INCLUDE_DIRS - The final set of include directories listed in one variable for use by client - code. This should not be a cache entry. +``Xxx_FOUND`` + Set to false, or undefined, if we haven't found, or don't want to use + Xxx. -Xxx_LIBRARIES - The libraries to link against to use Xxx. These should include full paths. - This should not be a cache entry. +``Xxx_NOT_FOUND_MESSAGE`` + Should be set by config-files in the case that it has set + ``Xxx_FOUND`` to FALSE. The contained message will be printed by the + :command:`find_package` command and by + ``find_package_handle_standard_args()`` to inform the user about the + problem. -Xxx_DEFINITIONS - Definitions to use when compiling code that uses Xxx. This really shouldn't - include options such as (-DHAS_JPEG)that a client source-code file uses to - decide whether to #include <jpeg.h> +``Xxx_RUNTIME_LIBRARY_DIRS`` + Optionally, the runtime library search path for use when running an + executable linked to shared libraries. The list should be used by + user code to create the ``PATH`` on windows or ``LD_LIBRARY_PATH`` on + UNIX. This should not be a cache entry. -Xxx_EXECUTABLE - Where to find the Xxx tool. +``Xxx_VERSION`` + The full version string of the package found, if any. Note that many + existing modules provide ``Xxx_VERSION_STRING`` instead. -Xxx_Yyy_EXECUTABLE - Where to find the Yyy tool that comes with Xxx. +``Xxx_VERSION_MAJOR`` + The major version of the package found, if any. -Xxx_LIBRARY_DIRS - Optionally, the final set of library directories listed in one variable for - use by client code. This should not be a cache entry. +``Xxx_VERSION_MINOR`` + The minor version of the package found, if any. -Xxx_ROOT_DIR - Where to find the base directory of Xxx. +``Xxx_VERSION_PATCH`` + The patch version of the package found, if any. -Xxx_VERSION_Yy - Expect Version Yy if true. Make sure at most one of these is ever true. +The following names should not usually be used in CMakeLists.txt files, but +are typically cache variables for users to edit and control the +behaviour of find modules (like entering the path to a library manually) -Xxx_WRAP_Yy - If False, do not try to use the relevant CMake wrapping command. +``Xxx_LIBRARY`` + The path of the Xxx library (as used with :command:`find_library`, for + example). -Xxx_Yy_FOUND - If False, optional Yy part of Xxx sytem is not available. +``Xxx_Yy_LIBRARY`` + The path of the Yy library that is part of the Xxx system. It may or + may not be required to use Xxx. -Xxx_FOUND - Set to false, or undefined, if we haven't found, or don't want to use Xxx. +``Xxx_INCLUDE_DIR`` + Where to find headers for using the Xxx library. -Xxx_NOT_FOUND_MESSAGE - Should be set by config-files in the case that it has set Xxx_FOUND to FALSE. - The contained message will be printed by the find_package() command and by - find_package_handle_standard_args() to inform the user about the problem. +``Xxx_Yy_INCLUDE_DIR`` + Where to find headers for using the Yy library of the Xxx system. -Xxx_RUNTIME_LIBRARY_DIRS - Optionally, the runtime library search path for use when running an - executable linked to shared libraries. The list should be used by user code - to create the PATH on windows or LD_LIBRARY_PATH on unix. This should not be - a cache entry. +To prevent users being overwhelmed with settings to configure, try to +keep as many options as possible out of the cache, leaving at least one +option which can be used to disable use of the module, or locate a +not-found library (e.g. ``Xxx_ROOT_DIR``). For the same reason, mark +most cache options as advanced. -Xxx_VERSION_STRING - A human-readable string containing the version of the package found, if any. +While these are the standard variable names, you should provide +backwards compatibility for any old names that were actually in use. +Make sure you comment them as deprecated, so that no-one starts using +them. -Xxx_VERSION_MAJOR - The major version of the package found, if any. -Xxx_VERSION_MINOR - The minor version of the package found, if any. -Xxx_VERSION_PATCH - The patch version of the package found, if any. +A Sample Find Module +^^^^^^^^^^^^^^^^^^^^ -You do not have to provide all of the above variables. You should provide -Xxx_FOUND under most circumstances. If Xxx is a library, then Xxx_LIBRARIES, -should also be defined, and Xxx_INCLUDE_DIRS should usually be defined (I -guess libm.a might be an exception) +We will describe how to create a simple find module for a library +``Foo``. -The following names should not usually be used in CMakeLists.txt files, but -they may be usefully modified in users' CMake Caches to control stuff. +The first thing that is needed is documentation. CMake's documentation +system requires you to start the file with a documentation marker and +the name of the module. You should follow this with a simple statement +of what the module does. -Xxx_LIBRARY - Name of Xxx Library. A User may set this and Xxx_INCLUDE_DIR to ignore to - force non-use of Xxx. +.. code-block:: cmake -Xxx_Yy_LIBRARY - Name of Yy library that is part of the Xxx system. It may or may not be - required to use Xxx. + #.rst: + # FindFoo + # ------- + # + # Finds the Foo library + # -Xxx_INCLUDE_DIR - Where to find xxx.h, etc. (Xxx_INCLUDE_PATH was considered bad because a path - includes an actual filename.) +More description may be required for some packages. If there are +caveats or other details users of the module should be aware of, you can +add further paragraphs below this. Then you need to document what +variables and imported targets are set by the module, such as -Xxx_Yy_INCLUDE_DIR - Where to find xxx_yy.h, etc. +.. code-block:: cmake -For tidiness's sake, try to keep as many options as possible out of the cache, -leaving at least one option which can be used to disable use of the module, or -locate a not-found library (e.g. Xxx_ROOT_DIR). For the same reason, mark -most cache options as advanced. + # This will define the following variables:: + # + # Foo_FOUND - True if the system has the Foo library + # Foo_VERSION - The version of the Foo library which was found + # + # and the following imported targets:: + # + # Foo::Foo - The Foo library -If you need other commands to do special things then it should still begin -with ``Xxx_``. This gives a sort of namespace effect and keeps things tidy for the -user. You should put comments describing all the exported settings, plus -descriptions of any the users can use to control stuff. +If the package provides any macros, they should be listed here, but can +be documented where they are defined. See the `Module +Documentation`_ section above for more details. -You really should also provide backwards compatibility any old settings that -were actually in use. Make sure you comment them as deprecated, so that -no-one starts using them. +After the documentation, leave a blank line, and then add a copyright and +licence notice block -To add a module to the CMake documentation, follow the steps in the -`Module Documentation`_ section above. Test the documentation formatting -by running ``cmake --help-module FindXxx``, and also by enabling the -``SPHINX_HTML`` and ``SPHINX_MAN`` options to build the documentation. -Edit the comments until generated documentation looks satisfactory. -To have a .cmake file in this directory NOT show up in the modules -documentation, simply leave out the ``Help/module/<module-name>.rst`` file -and the ``Help/manual/cmake-modules.7.rst`` toctree entry. +.. code-block:: cmake -After the documentation, leave a *BLANK* line, and then add a -copyright and licence notice block like this one:: + #============================================================================= + # Copyright 2009-2011 Your Name + # + # Distributed under the OSI-approved BSD License (the "License"); + # see accompanying file Copyright.txt for details. + # + # This software is distributed WITHOUT ANY WARRANTY; without even the + # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + # See the License for more information. + #============================================================================= + # (To distribute this file outside of CMake, substitute the full + # License text for the above reference.) + +If the module is new to CMake, you may want to provide a warning for +projects that do not require a high enough CMake version. - #============================================================================= - # Copyright 2009-2011 Your Name - # - # Distributed under the OSI-approved BSD License (the "License"); - # see accompanying file Copyright.txt for details. - # - # This software is distributed WITHOUT ANY WARRANTY; without even the - # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - # See the License for more information. - #============================================================================= - # (To distribute this file outside of CMake, substitute the full - # License text for the above reference.) - -The layout of the notice block is strictly enforced by the ``ModuleNotices`` -test. Only the year range and name may be changed freely. - -A FindXxx.cmake module will typically be loaded by the command:: - - FIND_PACKAGE(Xxx [major[.minor[.patch[.tweak]]]] [EXACT] - [QUIET] [[REQUIRED|COMPONENTS] [components...]]) - -If any version numbers are given to the command it will set the following -variables before loading the module: - -Xxx_FIND_VERSION - full requested version string - -Xxx_FIND_VERSION_MAJOR - major version if requested, else 0 - -Xxx_FIND_VERSION_MINOR - minor version if requested, else 0 - -Xxx_FIND_VERSION_PATCH - patch version if requested, else 0 - -Xxx_FIND_VERSION_TWEAK - tweak version if requested, else 0 - -Xxx_FIND_VERSION_COUNT - number of version components, 0 to 4 - -Xxx_FIND_VERSION_EXACT - true if EXACT option was given - -If the find module supports versioning it should locate a version of -the package that is compatible with the version requested. If a -compatible version of the package cannot be found the module should -not report success. The version of the package found should be stored -in "Xxx_VERSION..." version variables documented by the module. - -If the QUIET option is given to the command it will set the variable -Xxx_FIND_QUIETLY to true before loading the FindXxx.cmake module. If -this variable is set the module should not complain about not being -able to find the package. If the -REQUIRED option is given to the command it will set the variable -Xxx_FIND_REQUIRED to true before loading the FindXxx.cmake module. If -this variable is set the module should issue a FATAL_ERROR if the -package cannot be found. -If neither the QUIET nor REQUIRED options are given then the -FindXxx.cmake module should look for the package and complain without -error if the module is not found. - -FIND_PACKAGE() will set the variable CMAKE_FIND_PACKAGE_NAME to -contain the actual name of the package. - -A package can provide sub-components. -Those components can be listed after the COMPONENTS (or REQUIRED) or -OPTIONAL_COMPONENTS keywords. The set of all listed components will be -specified in a Xxx_FIND_COMPONENTS variable. -For each package-specific component, say Yyy, a variable Xxx_FIND_REQUIRED_Yyy -will be set to true if it listed after COMPONENTS and it will be set to false -if it was listed after OPTIONAL_COMPONENTS. -Using those variables a FindXxx.cmake module and also a XxxConfig.cmake -package configuration file can determine whether and which components have -been requested, and whether they were requested as required or as optional. -For each of the requested components a Xxx_Yyy_FOUND variable should be set -accordingly. -The per-package Xxx_FOUND variable should be only set to true if all requested -required components have been found. A missing optional component should not -keep the Xxx_FOUND variable from being set to true. -If the package provides Xxx_INCLUDE_DIRS and Xxx_LIBRARIES variables, the -include dirs and libraries for all components which were requested and which -have been found should be added to those two variables. - -To get this behavior you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS() -macro, as an example see FindJPEG.cmake. - -For internal implementation, it's a generally accepted convention that -variables starting with underscore are for temporary use only. (variable -starting with an underscore are not intended as a reserved prefix). +.. code-block:: cmake + + if(CMAKE_MINIMUM_REQUIRED_VERSION VERSION_LESS 3.0.0) + message(AUTHOR_WARNING "Your project should require at least CMake 3.0.0 to use FindFoo.cmake") + endif() + +Now the actual libraries and so on have to be found. The code here will +obviously vary from module to module (dealing with that, after all, is the +point of find modules), but there tends to be a common pattern for libraries. + +First, we try to use ``pkg-config`` to find the library. Note that we +cannot rely on this, as it may not be available, but it provides a good +starting point. + +.. code-block:: cmake + + find_package(PkgConfig) + pkg_check_modules(PC_Foo QUIET Foo) + +This should define some variables starting ``PC_Foo_`` that contain the +information from the ``Foo.pc`` file. + +Now we need to find the libraries and include files; we use the +information from ``pkg-config`` to provide hints to CMake about where to +look. + +.. code-block:: cmake + + find_path(Foo_INCLUDE_DIR + NAMES foo.h + PATHS ${PC_Foo_INCLUDE_DIRS} + # if you need to put #include <Foo/foo.h> in your code, add: + PATH_SUFFIXES Foo + ) + find_library(Foo_LIBRARY + NAMES foo + PATHS ${PC_Foo_LIBRARY_DIRS} + ) + +If you have a good way of getting the version (from a header file, for +example), you can use that information to set ``Foo_VERSION`` (although +note that find modules have traditionally used ``Foo_VERSION_STRING``, +so you may want to set both). Otherwise, attempt to use the information +from ``pkg-config`` + +.. code-block:: cmake + + set(Foo_VERSION ${PC_Foo_VERSION}) + +Now we can use :module:`FindPackageHandleStandardArgs` to do most of the +rest of the work for us + +.. code-block:: cmake + + include(FindPackageHandleStandardArgs) + find_package_handle_standard_args(Foo + FOUND_VAR Foo_FOUND + REQUIRED_VARS + Foo_LIBRARY + Foo_INCLUDE_DIR + VERSION_VAR Foo_VERSION + ) + +This will check that the ``REQUIRED_VARS`` contain values (that do not +end in ``-NOTFOUND``) and set ``Foo_FOUND`` appropriately. It will also +cache those values. If ``Foo_VERSION`` is set, and a required version +was passed to :command:`find_package`, it will check the requested version +against the one in ``Foo_VERSION``. It will also print messages as +appropriate; note that if the package was found, it will print the +contents of the first required variable to indicate where it was found. + +At this point, we have to provide a way for users of the find module to +link to the library or libraries that were found. There are two +approaches, as discussed in the `Find Modules`_ section above. The +traditional variable approach looks like + +.. code-block:: cmake + + if(Foo_FOUND) + set(Foo_LIBRARIES ${Foo_LIBRARY}) + set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR}) + set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER}) + endif() + +If more than one library was found, all of them should be included in +these variables (see the `Standard Variable Names`_ section for more +information). + +When providing imported targets, these should be namespaced (hence the +``Foo::`` prefix); CMake will recognize that values passed to +:command:`target_link_libraries` that contain ``::`` in their name are +supposed to be imported targets (rather than just library names), and +will produce appropriate diagnostic messages if that target does not +exist (see policy :policy:`CMP0028`). + +.. code-block:: cmake + + if(Foo_FOUND AND NOT TARGET Foo::Foo) + add_library(Foo::Foo UNKNOWN IMPORTED) + set_target_properties(Foo::Foo PROPERTIES + IMPORTED_LOCATION "${Foo_LIBRARY}" + INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" + INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" + ) + endif() + +One thing to note about this is that the ``INTERFACE_INCLUDE_DIRECTORIES`` and +similar properties should only contain information about the target itself, and +not any of its dependencies. Instead, those dependencies should also be +targets, and CMake should be told that they are dependencies of this target. +CMake will then combine all the necessary information automatically. + +We should also provide some information about the package, such as where to +download it. + +.. code-block:: cmake + + include(FeatureSummary) + set_package_properties(Foo PROPERTIES + URL "http://www.foo.example.com/" + DESCRIPTION "A library for doing useful things" + ) + +Most of the cache variables should be hidden in the ``ccmake`` interface unless +the user explicitly asks to edit them. + +.. code-block:: cmake + + mark_as_advanced( + Foo_INCLUDE_DIR + Foo_LIBRARY + ) + +If this module replaces an older version, you should set compatibility variables +to cause the least disruption possible. + +.. code-block:: cmake + + # compatibility variables + set(Foo_VERSION_STRING ${Foo_VERSION}) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index ac8c3f8..f04702e 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -83,6 +83,14 @@ otherwise expands to nothing. else ``0``. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies. +``$<COMPILE_FEATURES:feature[,feature]...>`` + ``1`` if all of the ``feature`` features are available for the 'head' + target, and ``0`` otherwise. If this expression is used while evaluating + the link implementation of a target and if any dependency transitively + increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` + for the 'head' target, an error is reported. See the + :manual:`cmake-compile-features(7)` manual for information on + compile features. Informational Expressions ========================= @@ -188,3 +196,8 @@ property is non-empty:: Content of ``...`` converted to upper case. ``$<MAKE_C_IDENTIFIER:...>`` Content of ``...`` converted to a C identifier. +``$<TARGET_OBJECTS:objLib>`` + List of objects resulting from build of ``objLib``. ``objLib`` must be an + object of type ``OBJECT_LIBRARY``. This expression may only be used in + the sources of :command:`add_library` and :command:`add_executable` + commands. diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 1e4c6c5..b83dcad 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -287,6 +287,8 @@ For example: Instead use a `Quoted Argument`_ or a `Bracket Argument`_ to represent the content. +.. _`Escape Sequences`: + Escape Sequences ---------------- @@ -294,16 +296,20 @@ An *escape sequence* is a ``\`` followed by one character: .. productionlist:: escape_sequence: `escape_identity` | `escape_encoded` | `escape_semicolon` - escape_identity: '\(' | '\)' | '\#' | '\"' | '\ ' | - : '\\' | '\$' | '\@' | '\^' + escape_identity: '\' <match '[^A-Za-z0-9;]'> escape_encoded: '\t' | '\r' | '\n' escape_semicolon: '\;' -A ``\`` followed by one of ``()#" \#@^`` simply encodes the literal +A ``\`` followed by a non-alphanumeric character simply encodes the literal character without interpreting it as syntax. A ``\t``, ``\r``, or ``\n`` -encodes a tab, carriage return, or newline character, respectively. -A ``\;`` encodes itself but may be used in an `Unquoted Argument`_ -to encode the ``;`` without dividing the argument value on it. +encodes a tab, carriage return, or newline character, respectively. A ``\;`` +outside of any `Variable References`_ encodes itself but may be used in an +`Unquoted Argument`_ to encode the ``;`` without dividing the argument +value on it. A ``\;`` inside `Variable References`_ encodes the literal +``;`` character. (See also policy :policy:`CMP0053` documentation for +historical considerations.) + +.. _`Variable References`: Variable References ------------------- @@ -315,6 +321,11 @@ or by the empty string if the variable is not set. Variable references can nest and are evaluated from the inside out, e.g. ``${outer_${inner_variable}_variable}``. +Literal variable references may consist of alphanumeric characters, +the characters ``/_.+-``, and `Escape Sequences`_. Nested references +may be used to evaluate variables of any name. (See also policy +:policy:`CMP0053` documentation for historical considerations.) + The `Variables`_ section documents the scope of variable names and how their values are set. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index 7a06be6..ecc9cc4 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -138,6 +138,7 @@ All Modules /module/FindMPEG /module/FindMPI /module/FindOpenAL + /module/FindOpenCL /module/FindOpenGL /module/FindOpenMP /module/FindOpenSceneGraph @@ -231,3 +232,4 @@ All Modules /module/UsewxWidgets /module/Use_wxWindows /module/WriteBasicConfigVersionFile + /module/WriteCompilerDetectionHeader diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 1723826..c4cca6d 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -564,6 +564,21 @@ containing the package configuration file. There is no system package registry on non-Windows platforms. +.. _`Disabling the Package Registry`: + +Disabling the Package Registry +------------------------------ + +In some cases using the Package Registries is not desirable. CMake +allows to disable them using the following variables: + + * :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` disables the + :command:`export(PACKAGE)` command. + * :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` disables the + User Package Registry in all the :command:`find_package` calls. + * :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` disables + the System Package Registry in all the :command:`find_package` calls. + Package Registry Example ------------------------ diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 8650a58..136cf5c 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -102,3 +102,6 @@ All Policies /policy/CMP0048 /policy/CMP0049 /policy/CMP0050 + /policy/CMP0051 + /policy/CMP0052 + /policy/CMP0053 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index d315fcb..e4546c1 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -16,6 +16,8 @@ Properties of Global Scope /prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS /prop_gbl/AUTOGEN_TARGETS_FOLDER /prop_gbl/AUTOMOC_TARGETS_FOLDER + /prop_gbl/CMAKE_C_KNOWN_FEATURES + /prop_gbl/CMAKE_CXX_KNOWN_FEATURES /prop_gbl/DEBUG_CONFIGURATIONS /prop_gbl/DISABLED_FEATURES /prop_gbl/ENABLED_FEATURES @@ -92,16 +94,27 @@ Properties on Targets /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION /prop_tgt/BUNDLE + /prop_tgt/C_EXTENSIONS + /prop_tgt/C_STANDARD + /prop_tgt/C_STANDARD_REQUIRED /prop_tgt/COMPATIBLE_INTERFACE_BOOL /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX /prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN /prop_tgt/COMPATIBLE_INTERFACE_STRING /prop_tgt/COMPILE_DEFINITIONS_CONFIG /prop_tgt/COMPILE_DEFINITIONS + /prop_tgt/COMPILE_FEATURES /prop_tgt/COMPILE_FLAGS /prop_tgt/COMPILE_OPTIONS + /prop_tgt/COMPILE_PDB_NAME + /prop_tgt/COMPILE_PDB_NAME_CONFIG + /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY + /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX + /prop_tgt/CXX_EXTENSIONS + /prop_tgt/CXX_STANDARD + /prop_tgt/CXX_STANDARD_REQUIRED /prop_tgt/DEBUG_POSTFIX /prop_tgt/DEFINE_SYMBOL /prop_tgt/EchoString @@ -144,10 +157,12 @@ Properties on Targets /prop_tgt/INSTALL_RPATH_USE_LINK_PATH /prop_tgt/INTERFACE_AUTOUIC_OPTIONS /prop_tgt/INTERFACE_COMPILE_DEFINITIONS + /prop_tgt/INTERFACE_COMPILE_FEATURES /prop_tgt/INTERFACE_COMPILE_OPTIONS /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES /prop_tgt/INTERFACE_LINK_LIBRARIES /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE + /prop_tgt/INTERFACE_SOURCES /prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES /prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG /prop_tgt/INTERPROCEDURAL_OPTIMIZATION @@ -278,6 +293,8 @@ Properties on Source Files /prop_sf/OBJECT_OUTPUTS /prop_sf/SYMBOLIC /prop_sf/WRAP_EXCLUDE + /prop_sf/XCODE_EXPLICIT_FILE_TYPE + /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE Properties on Cache Entries =========================== @@ -291,3 +308,12 @@ Properties on Cache Entries /prop_cache/STRINGS /prop_cache/TYPE /prop_cache/VALUE + +Properties on Installed Files +============================= + +.. toctree:: + :maxdepth: 1 + + /prop_inst/CPACK_NEVER_OVERWRITE.rst + /prop_inst/CPACK_PERMANENT.rst diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index cad4951..fe8d62d 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -54,7 +54,7 @@ CMake. Target dependencies may be added to that custom target by adding them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property. AUTOMOC -''''''' +^^^^^^^ 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 @@ -84,7 +84,7 @@ variable may be populated to pre-set the options for all following targets. .. _`Qt AUTOUIC`: AUTOUIC -''''''' +^^^^^^^ The :prop_tgt:`AUTOUIC` target property controls whether :manual:`cmake(1)` inspects the C++ files in the target to determine if they require ``uic`` to @@ -147,7 +147,7 @@ result of linking with the :prop_tgt:`IMPORTED` target: .. _`Qt AUTORCC`: AUTORCC -''''''' +^^^^^^^ The :prop_tgt:`AUTORCC` target property controls whether :manual:`cmake(1)` creates rules to execute ``rcc`` at the appropriate time on source files diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index f4b9666..0e4c4a0 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -109,10 +109,13 @@ Variables that Change Behavior /variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName /variable/CMAKE_ERROR_DEPRECATED /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION + /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY /variable/CMAKE_SYSROOT /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_NO_INSTALL_PREFIX + /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY + /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE @@ -125,6 +128,7 @@ Variables that Change Behavior /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME + /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_MFC_FLAG @@ -201,6 +205,8 @@ Variables that Control the Build /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS /variable/CMAKE_BUILD_WITH_INSTALL_RPATH + /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY + /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG @@ -255,6 +261,14 @@ Variables for Languages :maxdepth: 1 /variable/CMAKE_COMPILER_IS_GNULANG + /variable/CMAKE_C_COMPILE_FEATURES + /variable/CMAKE_C_EXTENSIONS + /variable/CMAKE_C_STANDARD + /variable/CMAKE_C_STANDARD_REQUIRED + /variable/CMAKE_CXX_COMPILE_FEATURES + /variable/CMAKE_CXX_EXTENSIONS + /variable/CMAKE_CXX_STANDARD + /variable/CMAKE_CXX_STANDARD_REQUIRED /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG @@ -295,6 +309,57 @@ Variables for Languages /variable/CMAKE_LANG_SOURCE_FILE_EXTENSIONS /variable/CMAKE_USER_MAKE_RULES_OVERRIDE_LANG +Variables for CTest +=================== + +.. toctree:: + :maxdepth: 1 + + /variable/CTEST_BINARY_DIRECTORY + /variable/CTEST_BUILD_COMMAND + /variable/CTEST_BUILD_NAME + /variable/CTEST_BZR_COMMAND + /variable/CTEST_BZR_UPDATE_OPTIONS + /variable/CTEST_CHECKOUT_COMMAND + /variable/CTEST_CONFIGURATION_TYPE + /variable/CTEST_CONFIGURE_COMMAND + /variable/CTEST_COVERAGE_COMMAND + /variable/CTEST_COVERAGE_EXTRA_FLAGS + /variable/CTEST_CURL_OPTIONS + /variable/CTEST_CVS_CHECKOUT + /variable/CTEST_CVS_COMMAND + /variable/CTEST_CVS_UPDATE_OPTIONS + /variable/CTEST_DROP_LOCATION + /variable/CTEST_DROP_METHOD + /variable/CTEST_DROP_SITE + /variable/CTEST_DROP_SITE_CDASH + /variable/CTEST_DROP_SITE_PASSWORD + /variable/CTEST_DROP_SITE_USER + /variable/CTEST_GIT_COMMAND + /variable/CTEST_GIT_UPDATE_CUSTOM + /variable/CTEST_GIT_UPDATE_OPTIONS + /variable/CTEST_HG_COMMAND + /variable/CTEST_HG_UPDATE_OPTIONS + /variable/CTEST_MEMORYCHECK_COMMAND + /variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS + /variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE + /variable/CTEST_NIGHTLY_START_TIME + /variable/CTEST_P4_CLIENT + /variable/CTEST_P4_COMMAND + /variable/CTEST_P4_OPTIONS + /variable/CTEST_P4_UPDATE_OPTIONS + /variable/CTEST_SCP_COMMAND + /variable/CTEST_SITE + /variable/CTEST_SOURCE_DIRECTORY + /variable/CTEST_SVN_COMMAND + /variable/CTEST_SVN_OPTIONS + /variable/CTEST_SVN_UPDATE_OPTIONS + /variable/CTEST_TEST_TIMEOUT + /variable/CTEST_TRIGGER_SITE + /variable/CTEST_UPDATE_COMMAND + /variable/CTEST_UPDATE_OPTIONS + /variable/CTEST_USE_LAUNCHERS + Variables for CPack =================== diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 5743ab7..8dfc16a 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -38,7 +38,7 @@ Options For true platform independence, CMake provides a list of commands that can be used on all systems. Run with -E help for the usage information. Commands available are: chdir, compare_files, copy, - copy_directory, copy_if_different, echo, echo_append, environment, + copy_directory, copy_if_different, echo, echo_append, env, environment, make_directory, md5sum, remove, remove_directory, rename, sleep, tar, time, touch, touch_nocreate. In addition, some platform specific commands are available. On Windows: delete_regv, write_regv. On diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 60d08dd..a57a8f0 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -365,6 +365,607 @@ Options .. include:: OPTIONS_HELP.txt +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 +---------------------- + +CTest defines an ordered list of testing steps of which some or all may +be run as a dashboard client: + +``Start`` + Start a new dashboard submission to be composed of results recorded + by the following steps. + See the `CTest Start Step`_ section below. + +``Update`` + Update the source tree from its version control repository. + Record the old and new versions and the list of updated source files. + See the `CTest Update Step`_ section below. + +``Configure`` + Configure the software by running a command in the build tree. + Record the configuration output log. + See the `CTest Configure Step`_ section below. + +``Build`` + Build the software by running a command in the build tree. + Record the build output log and detect warnings and errors. + See the `CTest Build Step`_ section below. + +``Test`` + Test the software by loading a ``CTestTestfile.cmake`` + from the build tree and executing the defined tests. + Record the output and result of each test. + See the `CTest Test Step`_ section below. + +``Coverage`` + Compute coverage of the source code by running a coverage + analysis tool and recording its output. + See the `CTest Coverage Step`_ section below. + +``MemCheck`` + Run the software test suite through a memory check tool. + Record the test output, results, and issues reported by the tool. + See the `CTest MemCheck Step`_ section below. + +``Submit`` + Submit results recorded from other testing steps to the + software quality dashboard server. + See the `CTest Submit Step`_ section below. + +Dashboard Client Modes +---------------------- + +CTest defines three modes of operation as a dashboard client: + +``Nightly`` + This mode is intended to be invoked once per day, typically at night. + It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit`` steps by default. Selected steps run even + if the ``Update`` step reports no changes to the source tree. + +``Continuous`` + This mode is intended to be invoked repeatedly throughout the day. + It enables the ``Start``, ``Update``, ``Configure``, ``Build``, ``Test``, + ``Coverage``, and ``Submit`` steps by default, but exits after the + ``Update`` step if it reports no changes to the source tree. + +``Experimental`` + This mode is intended to be invoked by a developer to test local changes. + It enables the ``Start``, ``Configure``, ``Build``, ``Test``, ``Coverage``, + and ``Submit`` steps by default. + +Dashboard Client via CTest Command-Line +--------------------------------------- + +CTest can perform testing on an already-generated build tree. +Run the ``ctest`` command with the current working directory set +to the build tree and use one of these signatures:: + + ctest -D <mode>[<step>] + ctest -M <mode> [ -T <step> ]... + +The ``<mode>`` must be one of the above `Dashboard Client Modes`_, +and each ``<step>`` must be one of the above `Dashboard Client Steps`_. + +CTest reads the `Dashboard Client Configuration`_ settings from +a file in the build tree called either ``CTestConfiguration.ini`` +or ``DartConfiguration.tcl`` (the names are historical). The format +of the file is:: + + # Lines starting in '#' are comments. + # Other non-blank lines are key-value pairs. + <setting>: <value> + +where ``<setting>`` is the setting name and ``<value>`` is the +setting value. + +In build trees generated by CMake, this configuration file is +generated by the :module:`CTest` module if included by the project. +The module uses variables to obtain a value for each setting +as documented with the settings below. + +.. _`CTest Script`: + +Dashboard Client via CTest Script +--------------------------------- + +CTest can perform testing driven by a :manual:`cmake-language(7)` +script that creates and maintains the source and build tree as +well as performing the testing steps. Run the ``ctest`` command +with the current working directory set outside of any build tree +and use one of these signatures:: + + ctest -S <script> + ctest -SP <script> + +The ``<script>`` file must call :ref:`CTest Commands` commands +to run testing steps explicitly as documented below. The commands +obtain `Dashboard Client Configuration`_ settings from their +arguments or from variables set in the script. + +Dashboard Client Configuration +============================== + +The `Dashboard Client Steps`_ may be configured by named +settings as documented in the following sections. + +.. _`CTest Start Step`: + +CTest Start Step +---------------- + +Start a new dashboard submission to be composed of results recorded +by the following steps. + +In a `CTest Script`_, the :command:`ctest_start` command runs this step. +Arguments to the command may specify some of the step settings. +The command first runs the command-line specified by the +``CTEST_CHECKOUT_COMMAND`` variable, if set, to initialize the source +directory. + +Configuration settings include: + +``BuildDirectory`` + The full path to the project build tree. + + * `CTest Script`_ variable: :variable:`CTEST_BINARY_DIRECTORY` + * :module:`CTest` module variable: :variable:`PROJECT_BINARY_DIR` + +``SourceDirectory`` + The full path to the project source tree. + + * `CTest Script`_ variable: :variable:`CTEST_SOURCE_DIRECTORY` + * :module:`CTest` module variable: :variable:`PROJECT_SOURCE_DIR` + +.. _`CTest Update Step`: + +CTest Update Step +----------------- + +In a `CTest Script`_, the :command:`ctest_update` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings to specify the version control tool include: + +``BZRCommand`` + ``bzr`` command-line tool to use if source tree is managed by Bazaar. + + * `CTest Script`_ variable: :variable:`CTEST_BZR_COMMAND` + * :module:`CTest` module variable: none + +``BZRUpdateOptions`` + Command-line options to the ``BZRCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_BZR_UPDATE_OPTIONS` + * :module:`CTest` module variable: none + +``CVSCommand`` + ``cvs`` command-line tool to use if source tree is managed by CVS. + + * `CTest Script`_ variable: :variable:`CTEST_CVS_COMMAND` + * :module:`CTest` module variable: ``CVSCOMMAND`` + +``CVSUpdateOptions`` + Command-line options to the ``CVSCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_CVS_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``CVS_UPDATE_OPTIONS`` + +``GITCommand`` + ``git`` command-line tool to use if source tree is managed by Git. + + * `CTest Script`_ variable: :variable:`CTEST_GIT_COMMAND` + * :module:`CTest` module variable: ``GITCOMMAND`` + +``GITUpdateCustom`` + Specify a semicolon-separated list of custom command lines to run + in the source tree (Git work tree) to update it instead of running + the ``GITCommand``. + + * `CTest Script`_ variable: :variable:`CTEST_GIT_UPDATE_CUSTOM` + * :module:`CTest` module variable: ``CTEST_GIT_UPDATE_CUSTOM`` + +``GITUpdateOptions`` + Command-line options to the ``GITCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_GIT_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``GIT_UPDATE_OPTIONS`` + +``HGCommand`` + ``hg`` command-line tool to use if source tree is managed by Mercurial. + + * `CTest Script`_ variable: :variable:`CTEST_HG_COMMAND` + * :module:`CTest` module variable: none + +``HGUpdateOptions`` + Command-line options to the ``HGCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_HG_UPDATE_OPTIONS` + * :module:`CTest` module variable: none + +``P4Client`` + Value of the ``-c`` option to the ``P4Command``. + + * `CTest Script`_ variable: :variable:`CTEST_P4_CLIENT` + * :module:`CTest` module variable: ``CTEST_P4_CLIENT`` + +``P4Command`` + ``p4`` command-line tool to use if source tree is managed by Perforce. + + * `CTest Script`_ variable: :variable:`CTEST_P4_COMMAND` + * :module:`CTest` module variable: ``P4COMMAND`` + +``P4Options`` + Command-line options to the ``P4Command`` for all invocations. + + * `CTest Script`_ variable: :variable:`CTEST_P4_OPTIONS` + * :module:`CTest` module variable: ``CTEST_P4_OPTIONS`` + +``P4UpdateCustom`` + Specify a semicolon-separated list of custom command lines to run + in the source tree (Perforce tree) to update it instead of running + the ``P4Command``. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``CTEST_P4_UPDATE_CUSTOM`` + +``P4UpdateOptions`` + Command-line options to the ``P4Command`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_P4_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``CTEST_P4_UPDATE_OPTIONS`` + +``SVNCommand`` + ``svn`` command-line tool to use if source tree is managed by Subversion. + + * `CTest Script`_ variable: :variable:`CTEST_SVN_COMMAND` + * :module:`CTest` module variable: ``SVNCOMMAND`` + +``SVNOptions`` + Command-line options to the ``SVNCommand`` for all invocations. + + * `CTest Script`_ variable: :variable:`CTEST_SVN_OPTIONS` + * :module:`CTest` module variable: ``CTEST_SVN_OPTIONS`` + +``SVNUpdateOptions`` + Command-line options to the ``SVNCommand`` when updating the source. + + * `CTest Script`_ variable: :variable:`CTEST_SVN_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``SVN_UPDATE_OPTIONS`` + +``UpdateCommand`` + Specify the version-control command-line tool to use without + detecting the VCS that manages the source tree. + + * `CTest Script`_ variable: :variable:`CTEST_UPDATE_COMMAND` + * :module:`CTest` module variable: ``<VCS>COMMAND`` + when ``UPDATE_TYPE`` is ``<vcs>``, else ``UPDATE_COMMAND`` + +``UpdateOptions`` + Command-line options to the ``UpdateCommand``. + + * `CTest Script`_ variable: :variable:`CTEST_UPDATE_OPTIONS` + * :module:`CTest` module variable: ``<VCS>_UPDATE_OPTIONS`` + when ``UPDATE_TYPE`` is ``<vcs>``, else ``UPDATE_OPTIONS`` + +``UpdateType`` + Specify the version-control system that manages the source + tree if it cannot be detected automatically. + The value may be ``bzr``, ``cvs``, ``git``, ``hg``, + ``p4``, or ``svn``. + + * `CTest Script`_ variable: none, detected from source tree + * :module:`CTest` module variable: ``UPDATE_TYPE`` if set, + else ``CTEST_UPDATE_TYPE`` + +Additional configuration settings include: + +``NightlyStartTime`` + In the ``Nightly`` dashboard mode, specify the "nightly start time". + With centralized version control systems (``cvs`` and ``svn``), + the ``Update`` step checks out the version of the software as of + this time so that multiple clients choose a common version to test. + This is not well-defined in distributed version-control systems so + the setting is ignored. + + * `CTest Script`_ variable: :variable:`CTEST_NIGHTLY_START_TIME` + * :module:`CTest` module variable: ``NIGHTLY_START_TIME`` if set, + else ``CTEST_NIGHTLY_START_TIME`` + +.. _`CTest Configure Step`: + +CTest Configure Step +-------------------- + +In a `CTest Script`_, the :command:`ctest_configure` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``ConfigureCommand`` + Command-line to launch the software configuration process. + It will be executed in the location specified by the + ``BuildDirectory`` setting. + + * `CTest Script`_ variable: :variable:`CTEST_CONFIGURE_COMMAND` + * :module:`CTest` module variable: :variable:`CMAKE_COMMAND` + followed by :variable:`PROJECT_SOURCE_DIR` + +.. _`CTest Build Step`: + +CTest Build Step +---------------- + +In a `CTest Script`_, the :command:`ctest_build` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``DefaultCTestConfigurationType`` + When the build system to be launched allows build-time selection + of the configuration (e.g. ``Debug``, ``Release``), this specifies + the default configuration to be built when no ``-C`` option is + given to the ``ctest`` command. The value will be substituted into + the value of ``MakeCommand`` to replace the literal string + ``${CTEST_CONFIGURATION_TYPE}`` if it appears. + + * `CTest Script`_ variable: :variable:`CTEST_CONFIGURATION_TYPE` + * :module:`CTest` module variable: ``DEFAULT_CTEST_CONFIGURATION_TYPE``, + initialized by the ``CMAKE_CONFIG_TYPE`` environment variable + +``MakeCommand`` + Command-line to launch the software build process. + It will be executed in the location specified by the + ``BuildDirectory`` setting. + + * `CTest Script`_ variable: :variable:`CTEST_BUILD_COMMAND` + * :module:`CTest` module variable: ``MAKECOMMAND``, + initialized by the :command:`build_command` command + +``UseLaunchers`` + For build trees generated by CMake using a Makefile generator + or the :generator:`Ninja` generator, specify whether the + ``CTEST_USE_LAUNCHERS`` feature is enabled by the + :module:`CTestUseLaunchers` module (also included by the + :module:`CTest` module). When enabled, the generated build + system wraps each invocation of the compiler, linker, or + custom command line with a "launcher" that communicates + with CTest via environment variables and files to report + granular build warning and error information. Otherwise, + CTest must "scrape" the build output log for diagnostics. + + * `CTest Script`_ variable: :variable:`CTEST_USE_LAUNCHERS` + * :module:`CTest` module variable: ``CTEST_USE_LAUNCHERS`` + +.. _`CTest Test Step`: + +CTest Test Step +--------------- + +In a `CTest Script`_, the :command:`ctest_test` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``TimeOut`` + The default timeout for each test if not specified by the + :prop_test:`TIMEOUT` test property. + + * `CTest Script`_ variable: :variable:`CTEST_TEST_TIMEOUT` + * :module:`CTest` module variable: ``DART_TESTING_TIMEOUT`` + +.. _`CTest Coverage Step`: + +CTest Coverage Step +------------------- + +In a `CTest Script`_, the :command:`ctest_coverage` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``CoverageCommand`` + Command-line tool to perform software coverage analysis. + It will be executed in the location specified by the + ``BuildDirectory`` setting. + + * `CTest Script`_ variable: :variable:`CTEST_COVERAGE_COMMAND` + * :module:`CTest` module variable: ``COVERAGE_COMMAND`` + +``CoverageExtraFlags`` + Specify command-line options to the ``CoverageCommand`` tool. + + * `CTest Script`_ variable: :variable:`CTEST_COVERAGE_EXTRA_FLAGS` + * :module:`CTest` module variable: ``COVERAGE_EXTRA_FLAGS`` + +.. _`CTest MemCheck Step`: + +CTest MemCheck Step +------------------- + +In a `CTest Script`_, the :command:`ctest_memcheck` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``MemoryCheckCommand`` + Command-line tool to perform dynamic analysis. Test command lines + will be launched through this tool. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_COMMAND` + * :module:`CTest` module variable: ``MEMORYCHECK_COMMAND`` + +``MemoryCheckCommandOptions`` + Specify command-line options to the ``MemoryCheckCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_COMMAND_OPTIONS` + * :module:`CTest` module variable: ``MEMORYCHECK_COMMAND_OPTIONS`` + +``MemoryCheckSuppressionFile`` + Specify a file containing suppression rules for the + ``MemoryCheckCommand`` tool. It will be passed with options + appropriate to the tool. + + * `CTest Script`_ variable: :variable:`CTEST_MEMORYCHECK_SUPPRESSIONS_FILE` + * :module:`CTest` module variable: ``MEMORYCHECK_SUPPRESSIONS_FILE`` + +Additional configuration settings include: + +``BoundsCheckerCommand`` + Specify a ``MemoryCheckCommand`` that is known to be command-line + compatible with Bounds Checker. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: none + +``PurifyCommand`` + Specify a ``MemoryCheckCommand`` that is known to be command-line + compatible with Purify. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``PURIFYCOMMAND`` + +``ValgrindCommand`` + Specify a ``MemoryCheckCommand`` that is known to be command-line + compatible with Valgrind. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``VALGRIND_COMMAND`` + +``ValgrindCommandOptions`` + Specify command-line options to the ``ValgrindCommand`` tool. + They will be placed prior to the test command line. + + * `CTest Script`_ variable: none + * :module:`CTest` module variable: ``VALGRIND_COMMAND_OPTIONS`` + +.. _`CTest Submit Step`: + +CTest Submit Step +----------------- + +In a `CTest Script`_, the :command:`ctest_submit` command runs this step. +Arguments to the command may specify some of the step settings. + +Configuration settings include: + +``BuildName`` + Describe the dashboard client platform with a short string. + (Operating system, compiler, etc.) + + * `CTest Script`_ variable: :variable:`CTEST_BUILD_NAME` + * :module:`CTest` module variable: ``BUILDNAME`` + +``CDashVersion`` + Specify the version of `CDash`_ on the server. + + * `CTest Script`_ variable: none, detected from server + * :module:`CTest` module variable: ``CTEST_CDASH_VERSION`` + +``CTestSubmitRetryCount`` + Specify a number of attempts to retry submission on network failure. + + * `CTest Script`_ variable: none, + use the :command:`ctest_submit` ``RETRY_COUNT`` option. + * :module:`CTest` module variable: ``CTEST_SUBMIT_RETRY_COUNT`` + +``CTestSubmitRetryDelay`` + Specify a delay before retrying submission on network failure. + + * `CTest Script`_ variable: none, + use the :command:`ctest_submit` ``RETRY_DELAY`` option. + * :module:`CTest` module variable: ``CTEST_SUBMIT_RETRY_DELAY`` + +``CurlOptions`` + Specify a semicolon-separated list of options to control the + Curl library that CTest uses internally to connect to the + server. Possible options are ``CURLOPT_SSL_VERIFYPEER_OFF`` + and ``CURLOPT_SSL_VERIFYHOST_OFF``. + + * `CTest Script`_ variable: :variable:`CTEST_CURL_OPTIONS` + * :module:`CTest` module variable: ``CTEST_CURL_OPTIONS`` + +``DropLocation`` + The path on the dashboard server to send the submission. + + * `CTest Script`_ variable: :variable:`CTEST_DROP_LOCATION` + * :module:`CTest` module variable: ``DROP_LOCATION`` if set, + else ``CTEST_DROP_LOCATION`` + +``DropMethod`` + Specify the method by which results should be submitted to the + dashboard server. The value may be ``cp``, ``ftp``, ``http``, + ``https``, ``scp``, or ``xmlrpc`` (if CMake was built with + support for it). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_METHOD` + * :module:`CTest` module variable: ``DROP_METHOD`` if set, + else ``CTEST_DROP_METHOD`` + +``DropSite`` + The dashboard server name + (for ``ftp``, ``http``, and ``https``, ``scp``, and ``xmlrpc``). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE` + * :module:`CTest` module variable: ``DROP_SITE`` if set, + else ``CTEST_DROP_SITE`` + +``DropSitePassword`` + The dashboard server login password, if any + (for ``ftp``, ``http``, and ``https``). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_PASSWORD` + * :module:`CTest` module variable: ``DROP_SITE_PASSWORD`` if set, + else ``CTEST_DROP_SITE_PASWORD`` + +``DropSiteUser`` + The dashboard server login user name, if any + (for ``ftp``, ``http``, and ``https``). + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_USER` + * :module:`CTest` module variable: ``DROP_SITE_USER`` if set, + else ``CTEST_DROP_SITE_USER`` + +``IsCDash`` + Specify whether the dashboard server is `CDash`_ or an older + dashboard server implementation requiring ``TriggerSite``. + + * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_CDASH` + * :module:`CTest` module variable: ``CTEST_DROP_SITE_CDASH`` + +``ScpCommand`` + ``scp`` command-line tool to use when ``DropMethod`` is ``scp``. + + * `CTest Script`_ variable: :variable:`CTEST_SCP_COMMAND` + * :module:`CTest` module variable: ``SCPCOMMAND`` + +``Site`` + Describe the dashboard client host site with a short string. + (Hostname, domain, etc.) + + * `CTest Script`_ variable: :variable:`CTEST_SITE` + * :module:`CTest` module variable: ``SITE``, + initialized by the :command:`site_name` command + +``TriggerSite`` + Legacy option to support older dashboard server implementations. + Not used when ``IsCDash`` is true. + + * `CTest Script`_ variable: :variable:`CTEST_TRIGGER_SITE` + * :module:`CTest` module variable: ``TRIGGER_SITE`` if set, + else ``CTEST_TRIGGER_SITE`` + See Also ======== diff --git a/Help/module/FindOpenCL.rst b/Help/module/FindOpenCL.rst new file mode 100644 index 0000000..e87e289 --- /dev/null +++ b/Help/module/FindOpenCL.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindOpenCL.cmake diff --git a/Help/module/WriteCompilerDetectionHeader.rst b/Help/module/WriteCompilerDetectionHeader.rst new file mode 100644 index 0000000..4c81b48 --- /dev/null +++ b/Help/module/WriteCompilerDetectionHeader.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/WriteCompilerDetectionHeader.cmake diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst index 01699e1..9d2eb76 100644 --- a/Help/policy/CMP0010.rst +++ b/Help/policy/CMP0010.rst @@ -10,6 +10,9 @@ variable reference is an error. The OLD behavior for this policy is to warn about the error, leave the string untouched, and continue. The NEW behavior for this policy is to report an error. +If :policy:`CMP0053` is set to ``NEW``, this policy has no effect +and is treated as always being ``NEW``. + This policy was introduced in CMake version 2.6.3. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. diff --git a/Help/policy/CMP0020.rst b/Help/policy/CMP0020.rst index ad664b0..6767d08 100644 --- a/Help/policy/CMP0020.rst +++ b/Help/policy/CMP0020.rst @@ -16,7 +16,7 @@ this automatic linking will need to be disabled as per the documentation. The OLD behavior for this policy is not to link executables to -qtmain.lib automatically when they link to the QtCore IMPORTEDtarget. +qtmain.lib automatically when they link to the QtCore IMPORTED target. The NEW behavior for this policy is to link executables to qtmain.lib automatically when they link to QtCore IMPORTED target. diff --git a/Help/policy/CMP0051.rst b/Help/policy/CMP0051.rst new file mode 100644 index 0000000..1b56cb0 --- /dev/null +++ b/Help/policy/CMP0051.rst @@ -0,0 +1,24 @@ +CMP0051 +------- + +List TARGET_OBJECTS in SOURCES target property. + +CMake 3.0 and lower did not include the ``TARGET_OBJECTS`` +:manual:`generator expression <cmake-generator-expressions(7)>` when +returning the :prop_tgt:`SOURCES` target property. + +Configure-time CMake code is not able to handle generator expressions. If +using the :prop_tgt:`SOURCES` target property at configure time, it may be +necessary to first remove generator expressions using the +:command:`string(GENEX_STRIP)` command. Generate-time CMake code such as +:command:`file(GENERATE)` can handle the content without stripping. + +The ``OLD`` behavior for this policy is to omit ``TARGET_OBJECTS`` +expressions from the :prop_tgt:`SOURCES` target property. The ``NEW`` +behavior for this policy is to include ``TARGET_OBJECTS`` expressions +in the output. + +This policy was introduced in CMake version 3.1. +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. diff --git a/Help/policy/CMP0052.rst b/Help/policy/CMP0052.rst new file mode 100644 index 0000000..48cfc9c --- /dev/null +++ b/Help/policy/CMP0052.rst @@ -0,0 +1,24 @@ +CMP0052 +------- + +Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. + +CMake 3.0 and lower allowed subdirectories of the source directory or build +directory to be in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of +installed and exported targets, if the directory was also a subdirectory of +the installation prefix. This makes the installation depend on the +existence of the source dir or binary dir, and the installation will be +broken if either are removed after installation. + +See :ref:`Include Directories and Usage Requirements` for more on +specifying include directories for targets. + +The OLD behavior for this policy is to export the content of the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` with the source or binary +directory. The NEW behavior for this +policy is to issue an error if such a directory is used. + +This policy was introduced in CMake version 3.1. +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. diff --git a/Help/policy/CMP0053.rst b/Help/policy/CMP0053.rst new file mode 100644 index 0000000..fac430e --- /dev/null +++ b/Help/policy/CMP0053.rst @@ -0,0 +1,44 @@ +CMP0053 +------- + +Simplify variable reference and escape sequence evaluation. + +CMake 3.1 introduced a much faster implementation of evaluation of the +:ref:`Variable References` and :ref:`Escape Sequences` documented in the +:manual:`cmake-language(7)` manual. While the behavior is identical +to the legacy implementation in most cases, some corner cases were +cleaned up to simplify the behavior. Specifically: + +* Expansion of ``@VAR@`` reference syntax defined by the + :command:`configure_file` and :command:`string(CONFIGURE)` + commands is no longer performed in other contexts. + +* Literal ``${VAR}`` reference syntax may contain only + alphanumeric characters (``A-Z``, ``a-z``, ``0-9``) and + the characters ``_``, ``.``, ``/``, ``-``, and ``+``. + Variables with other characters in their name may still + be referenced indirectly, e.g. + + .. code-block:: cmake + + set(varname "otherwise & disallowed $ characters") + message("${${varname}}") + +* The setting of policy :policy:`CMP0010` is not considered, + so improper variable reference syntax is always an error. + +* More characters are allowed to be escaped in variable names. + Previously, only ``()#" \#@^`` were valid characters to + escape. Now any non-alphanumeric, non-semicolon, non-NUL + character may be escaped following the ``escape_identity`` + production in the :ref:`Escape Sequences` section of the + :manual:`cmake-language(7)` manual. + +The ``OLD`` behavior for this policy is to honor the legacy behavior for +variable references and escape sequences. The ``NEW`` behavior is to +use the simpler variable expansion and escape sequence evaluation rules. + +This policy was introduced in CMake version 3.1. +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. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst new file mode 100644 index 0000000..bdeabdb --- /dev/null +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -0,0 +1,298 @@ +CMAKE_CXX_KNOWN_FEATURES +------------------------ + +List of C++ features known to this version of CMake. + +The features listed in this global property may be known to be available to the +C++ compiler. If the feature is available with the C++ compiler, it will +be listed in the :variable:`CMAKE_CXX_COMPILE_FEATURES` variable. + +The features listed here may be used with the :command:`target_compile_features` +command. See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + + +The features known to this version of CMake are: + +``cxx_aggregate_default_initializers`` + Aggregate default initializers, as defined in N3605_. + + .. _N3605: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3605.html + +``cxx_alias_templates`` + Template aliases, as defined in N2258_. + + .. _N2258: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2258.pdf + +``cxx_alignas`` + Alignment control ``alignas``, as defined in N2341_. + + .. _N2341: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf + +``cxx_alignof`` + Alignment control ``alignof``, as defined in N2341_. + + .. _N2341: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2341.pdf + +``cxx_attributes`` + Generic attributes, as defined in N2761_. + + .. _N2761: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2761.pdf + +``cxx_attribute_deprecated`` + ``[[deprecated]]`` attribute, as defined in N3760_. + + .. _N3760: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html + +``cxx_auto_type`` + Automatic type deduction, as defined in N1984_. + + .. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf + +``cxx_binary_literals`` + Binary literals, as defined in N3472_. + + .. _N3472: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3472.pdf + +``cxx_constexpr`` + Constant expressions, as defined in N2235_. + + .. _N2235: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2235.pdf + +``cxx_contextual_conversions`` + Contextual conversions, as defined in N3323_. + + .. _N3323: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3323.pdf + +``cxx_decltype_incomplete_return_types`` + Decltype on incomplete return types, as defined in N3276_. + + .. _N3276 : http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3276.pdf + +``cxx_decltype`` + Decltype, as defined in N2343_. + + .. _N2343: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf + +``cxx_decltype_auto`` + ``decltype(auto)`` semantics, as defined in N3638_. + + .. _N3638: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3638.html + +``cxx_default_function_template_args`` + Default template arguments for function templates, as defined in DR226_ + + .. _DR226: http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#226 + +``cxx_defaulted_functions`` + Defaulted functions, as defined in N2346_. + + .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm + +``cxx_defaulted_move_initializers`` + Defaulted move initializers, as defined in N3053_. + + .. _N3053: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3053.html + +``cxx_delegating_constructors`` + Delegating constructors, as defined in N1986_. + + .. _N1986: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1986.pdf + +``cxx_deleted_functions`` + Deleted functions, as defined in N2346_. + + .. _N2346: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm + +``cxx_digit_separators`` + Digit separators, as defined in N3781_. + + .. _N3781: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3781.pdf + +``cxx_enum_forward_declarations`` + Enum forward declarations, as defined in N2764_. + + .. _N2764: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2764.pdf + +``cxx_explicit_conversions`` + Explicit conversion operators, as defined in N2437_. + + .. _N2437: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2437.pdf + +``cxx_extended_friend_declarations`` + Extended friend declarations, as defined in N1791_. + + .. _N1791: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1791.pdf + +``cxx_extern_templates`` + Extern templates, as defined in N1987_. + + .. _N1987: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1987.htm + +``cxx_final`` + Override control ``final`` keyword, as defined in N2928_. + + .. _N2928: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm + +``cxx_func_identifier`` + Predefined ``__func__`` identifier, as defined in N2340_. + + .. _N2340: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2340.htm + +``cxx_generalized_initializers`` + Initializer lists, as defined in N2672_. + + .. _N2672: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2672.htm + +``cxx_generic_lambdas`` + Generic lambdas, ss defined in N3649_. + + .. _N3649: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3649.html + +``cxx_inheriting_constructors`` + Inheriting constructors, as defined in N2540_. + + .. _N2540: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2540.htm + +``cxx_inline_namespaces`` + Inline namespaces, as defined in N2535_. + + .. _N2535: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2535.htm + +``cxx_lambdas`` + Lambda functions, as defined in N2927_. + + .. _N2927: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2927.pdf + +``cxx_lambda_init_captures`` + Initialized lambda captures, as defined in N3648_. + + .. _N3648: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3648.html + +``cxx_local_type_template_args`` + Local and unnamed types as template arguments, as defined in N2657_. + + .. _N2657: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm + +``cxx_long_long_type`` + ``long long`` type, as defined in N1811_. + + .. _N1811: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1811.pdf + +``cxx_noexcept`` + Exception specifications, as defined in N3050_. + + .. _N3050: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3050.html + +``cxx_nonstatic_member_init`` + Non-static data member initialization, as defined in N2756_. + + .. _N2756: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2756.htm + +``cxx_nullptr`` + Null pointer, as defined in N2431_. + + .. _N2431: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf + +``cxx_override`` + Override control ``override`` keyword, as defined in N2928_. + + .. _N2928: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm + +``cxx_range_for`` + Range-based for, as defined in N2930_. + + .. _N2930: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2930.html + +``cxx_raw_string_literals`` + Raw string literals, as defined in N2442_. + + .. _N2442: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm + +``cxx_reference_qualified_functions`` + Reference qualified functions, as defined in N2439_. + + .. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm + +``cxx_relaxed_constexpr`` + Relaxed constexpr, as defined in N3652_. + + .. _N3652: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3652.html + +``cxx_return_type_deduction`` + Return type deduction on normal functions, as defined in N3386_. + + .. _N3386: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3386.html + +``cxx_right_angle_brackets`` + Right angle bracket parsing, as defined in N1757_. + + .. _N1757: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1757.html + +``cxx_rvalue_references`` + R-value references, as defined in N2118_. + + .. _N2118: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html + +``cxx_sizeof_member`` + Size of non-static data members, as defined in N2253_. + + .. _N2253: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2253.html + +``cxx_static_assert`` + Static assert, as defined in N1720_. + + .. _N1720: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html + +``cxx_strong_enums`` + Strongly typed enums, as defined in N2347_. + + .. _N2347: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf + +``cxx_thread_local`` + Thread-local variables, as defined in N2659_. + + .. _N2659: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2659.htm + +``cxx_trailing_return_types`` + Automatic function return type, as defined in N2541_. + + .. _N2541: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm + +``cxx_unicode_literals`` + Unicode string literals, as defined in N2442_. + + .. _N2442: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2442.htm + +``cxx_uniform_initialization`` + Uniform intialization, as defined in N2640_. + + .. _N2640: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2640.pdf + +``cxx_unrestricted_unions`` + Unrestricted unions, as defined in N2544_. + + .. _N2544: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2544.pdf + +``cxx_user_literals`` + User-defined literals, as defined in N2765_. + + .. _N2765: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf + +``cxx_variable_templates`` + Variable templates, as defined in N3651_. + + .. _N3651: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3651.pdf + +``cxx_variadic_macros`` + Variadic macros, as defined in N1653_. + + .. _N1653: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1653.htm + +``cxx_variadic_templates`` + Variadic templates, as defined in N2242_. + + .. _N2242: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf + +``cxx_template_template_parameters`` + Template template parameters, as defined in ``ISO/IEC 14882:1998``. diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst new file mode 100644 index 0000000..18cd030 --- /dev/null +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -0,0 +1,26 @@ +CMAKE_C_KNOWN_FEATURES +---------------------- + +List of C features known to this version of CMake. + +The features listed in this global property may be known to be available to the +C compiler. If the feature is available with the C compiler, it will +be listed in the :variable:`CMAKE_C_COMPILE_FEATURES` variable. + +The features listed here may be used with the :command:`target_compile_features` +command. See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +The features known to this version of CMake are: + +``c_function_prototypes`` + Function prototypes, as defined in ``ISO/IEC 9899:1990``. + +``c_restrict`` + ``restrict`` keyword, as defined in ``ISO/IEC 9899:1999``. + +``c_static_assert`` + Static assert, as defined in ``ISO/IEC 9899:2011``. + +``c_variadic_macros`` + Variadic macros, as defined in ``ISO/IEC 9899:1999``. diff --git a/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst new file mode 100644 index 0000000..11f44d0 --- /dev/null +++ b/Help/prop_inst/CPACK_NEVER_OVERWRITE.rst @@ -0,0 +1,6 @@ +CPACK_NEVER_OVERWRITE +--------------------- + +Request that this file not be overwritten on install or reinstall. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_inst/CPACK_PERMANENT.rst b/Help/prop_inst/CPACK_PERMANENT.rst new file mode 100644 index 0000000..5e191d0 --- /dev/null +++ b/Help/prop_inst/CPACK_PERMANENT.rst @@ -0,0 +1,6 @@ +CPACK_PERMANENT +--------------- + +Request that this file not be removed on uninstall. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst new file mode 100644 index 0000000..1b24701 --- /dev/null +++ b/Help/prop_sf/XCODE_EXPLICIT_FILE_TYPE.rst @@ -0,0 +1,8 @@ +XCODE_EXPLICIT_FILE_TYPE +------------------------ + +Set the Xcode ``explicitFileType`` attribute on its reference to a +source file. CMake computes a default based on file extension but +can be told explicitly with this property. + +See also :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE`. diff --git a/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst new file mode 100644 index 0000000..42e3757 --- /dev/null +++ b/Help/prop_sf/XCODE_LAST_KNOWN_FILE_TYPE.rst @@ -0,0 +1,9 @@ +XCODE_LAST_KNOWN_FILE_TYPE +-------------------------- + +Set the Xcode ``lastKnownFileType`` attribute on its reference to a +source file. CMake computes a default based on file extension but +can be told explicitly with this property. + +See also :prop_sf:`XCODE_EXPLICIT_FILE_TYPE`, which is preferred +over this property if set. diff --git a/Help/prop_tgt/COMPILE_FEATURES.rst b/Help/prop_tgt/COMPILE_FEATURES.rst new file mode 100644 index 0000000..225ffee --- /dev/null +++ b/Help/prop_tgt/COMPILE_FEATURES.rst @@ -0,0 +1,12 @@ +COMPILE_FEATURES +---------------- + +Compiler features enabled for this target. + +The list of features in this property are a subset of the features listed +in the :variable:`CMAKE_CXX_COMPILE_FEATURES` variable. + +Contents of ``COMPILE_FEATURES`` may use "generator expressions" with the +syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for +available expressions. See the :manual:`cmake-compile-features(7)` manual +for information on compile features. diff --git a/Help/prop_tgt/COMPILE_PDB_NAME.rst b/Help/prop_tgt/COMPILE_PDB_NAME.rst new file mode 100644 index 0000000..24a9f62 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NAME.rst @@ -0,0 +1,11 @@ +COMPILE_PDB_NAME +---------------- + +Output name for the MS debug symbol ``.pdb`` file generated by the +compiler while building source files. + +This property specifies the base name for the debug symbols file. +If not set, the default is unspecified. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_NAME` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst new file mode 100644 index 0000000..e4077f5 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NAME_CONFIG.rst @@ -0,0 +1,10 @@ +COMPILE_PDB_NAME_<CONFIG> +------------------------- + +Per-configuration output name for the MS debug symbol ``.pdb`` file +generated by the compiler while building source files. + +This is the configuration-specific version of :prop_tgt:`COMPILE_PDB_NAME`. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_NAME_<CONFIG>` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/COMPILE_PDB_NOTE.txt b/Help/prop_tgt/COMPILE_PDB_NOTE.txt new file mode 100644 index 0000000..5941d72 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_NOTE.txt @@ -0,0 +1,8 @@ +.. note:: + The compiler-generated program database files are specified by the + ``/Fd`` compiler flag and are not the same as linker-generated + program database files specified by the ``/pdb`` linker flag. + Use the |PDB_XXX| property to specify the latter. + + This property is not implemented by the :generator:`Visual Studio 6` + generator. diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..34f49be --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,13 @@ +COMPILE_PDB_OUTPUT_DIRECTORY +---------------------------- + +Output directory for the MS debug symbol ``.pdb`` file +generated by the compiler while building source files. + +This property specifies the directory into which the MS debug symbols +will be placed by the compiler. This property is initialized by the +value of the :variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY` variable +if it is set when a target is created. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..52ef013 --- /dev/null +++ b/Help/prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,16 @@ +COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> +------------------------------------- + +Per-configuration output directory for the MS debug symbol ``.pdb`` file +generated by the compiler while building source files. + +This is a per-configuration version of +:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY`, +but multi-configuration generators (VS, Xcode) do NOT append a +per-configuration subdirectory to the specified directory. This +property is initialized by the value of the +:variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable +if it is set when a target is created. + +.. |PDB_XXX| replace:: :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>` +.. include:: COMPILE_PDB_NOTE.txt diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst new file mode 100644 index 0000000..67c5cb0 --- /dev/null +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -0,0 +1,16 @@ +CXX_EXTENSIONS +-------------- + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This +property is ``ON`` by default. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +This property is initialized by the value of +the :variable:`CMAKE_CXX_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst new file mode 100644 index 0000000..b50cdf9 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -0,0 +1,30 @@ +CXX_STANDARD +------------ + +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. + +Supported values are ``98`` and ``11``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY CXX_STANDARD 11) + +with a compiler which does not support ``-std=gnu++11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu++98`` flag if supported. This "decay" behavior may be controlled +with the :prop_tgt:`CXX_STANDARD_REQUIRED` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +This property is initialized by the value of +the :variable:`CMAKE_CXX_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..ac103a4 --- /dev/null +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,17 @@ +CXX_STANDARD_REQUIRED +--------------------- + +Boolean describing whether the value of :prop_tgt:`CXX_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`CXX_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`CXX_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +This property is initialized by the value of +the :variable:`CMAKE_CXX_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst new file mode 100644 index 0000000..dc48cc6 --- /dev/null +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -0,0 +1,16 @@ +C_EXTENSIONS +------------ + +Boolean specifying whether compiler specific extensions are requested. + +This property specifies whether compiler specific extensions should be +used. For some compilers, this results in adding a flag such +as ``-std=gnu11`` instead of ``-std=c11`` to the compile line. This +property is ``ON`` by default. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +This property is initialized by the value of +the :variable:`CMAKE_C_EXTENSIONS` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst new file mode 100644 index 0000000..88ca926 --- /dev/null +++ b/Help/prop_tgt/C_STANDARD.rst @@ -0,0 +1,30 @@ +C_STANDARD +---------- + +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. + +Supported values are ``90``, ``99`` and ``11``. + +If the value requested does not result in a compile flag being added for +the compiler in use, a previous standard flag will be added instead. This +means that using: + +.. code-block:: cmake + + set_property(TARGET tgt PROPERTY C_STANDARD 11) + +with a compiler which does not support ``-std=gnu11`` or an equivalent +flag will not result in an error or warning, but will instead add the +``-std=gnu99`` or ``-std=gnu90`` flag if supported. This "decay" behavior may +be controlled with the :prop_tgt:`C_STANDARD_REQUIRED` target property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +This property is initialized by the value of +the :variable:`CMAKE_C_STANDARD` variable if it is set when a target +is created. diff --git a/Help/prop_tgt/C_STANDARD_REQUIRED.rst b/Help/prop_tgt/C_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..a7304f4 --- /dev/null +++ b/Help/prop_tgt/C_STANDARD_REQUIRED.rst @@ -0,0 +1,17 @@ +C_STANDARD_REQUIRED +------------------- + +Boolean describing whether the value of :prop_tgt:`C_STANDARD` is a requirement. + +If this property is set to ``ON``, then the value of the +:prop_tgt:`C_STANDARD` target property is treated as a requirement. If this +property is ``OFF`` or unset, the :prop_tgt:`C_STANDARD` target property is +treated as optional and may "decay" to a previous standard if the requested is +not available. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. + +This property is initialized by the value of +the :variable:`CMAKE_C_STANDARD_REQUIRED` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst new file mode 100644 index 0000000..7abdecb --- /dev/null +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -0,0 +1,16 @@ +INTERFACE_COMPILE_FEATURES +-------------------------- + +List of public compile requirements for a library. + +Targets may populate this property to publish the compiler features +required to compile against the headers for the target. Consuming +targets can add entries to their own :prop_tgt:`COMPILE_FEATURES` +property such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_FEATURES>`` +to require the features specified in the interface of ``foo``. + +Contents of ``INTERFACE_COMPILE_FEATURES`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the +:manual:`cmake-compile-features(7)` manual for information on compile +features. diff --git a/Help/prop_tgt/INTERFACE_SOURCES.rst b/Help/prop_tgt/INTERFACE_SOURCES.rst new file mode 100644 index 0000000..fb28231 --- /dev/null +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -0,0 +1,15 @@ +INTERFACE_SOURCES +----------------- + +List of interface sources to pass to the compiler. + +Targets may populate this property to publish the sources +for consuming targets to compile. Consuming +targets can add entries to their own :prop_tgt:`SOURCES` property +such as ``$<TARGET_PROPERTY:foo,INTERFACE_SOURCES>`` to use the +sources specified in the interface of ``foo``. + +Contents of ``INTERFACE_SOURCES`` may use "generator expressions" +with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` +manual for available expressions. See the :manual:`cmake-buildsystem(7)` +manual for more on defining buildsystem properties. diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst index e8fc3be..479dec3 100644 --- a/Help/prop_tgt/PDB_NAME.rst +++ b/Help/prop_tgt/PDB_NAME.rst @@ -7,7 +7,5 @@ linker for an executable or shared library target. This property specifies the base name for the debug symbols file. If not set, the logical target name is used by default. +.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME` .. include:: PDB_NOTE.txt - -This property is not implemented by the :generator:`Visual Studio 6` -generator. diff --git a/Help/prop_tgt/PDB_NAME_CONFIG.rst b/Help/prop_tgt/PDB_NAME_CONFIG.rst index c846b57..cb3121c 100644 --- a/Help/prop_tgt/PDB_NAME_CONFIG.rst +++ b/Help/prop_tgt/PDB_NAME_CONFIG.rst @@ -6,5 +6,5 @@ generated by the linker for an executable or shared library target. This is the configuration-specific version of :prop_tgt:`PDB_NAME`. -This property is not implemented by the :generator:`Visual Studio 6` -generator. +.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME_<CONFIG>` +.. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/PDB_NOTE.txt b/Help/prop_tgt/PDB_NOTE.txt index e55aba2..f90ea81 100644 --- a/Help/prop_tgt/PDB_NOTE.txt +++ b/Help/prop_tgt/PDB_NOTE.txt @@ -3,6 +3,10 @@ is invoked to produce them so they have no linker-generated ``.pdb`` file containing debug symbols. - The compiler-generated program database files specified by the MSVC - ``/Fd`` flag are not the same as linker-generated program database - files and so are not influenced by this property. + The linker-generated program database files are specified by the + ``/pdb`` linker flag and are not the same as compiler-generated + program database files specified by the ``/Fd`` compiler flag. + Use the |COMPILE_PDB_XXX| property to specify the latter. + + This property is not implemented by the :generator:`Visual Studio 6` + generator. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst index 9a863a1..730cf57 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY.rst @@ -9,7 +9,5 @@ will be placed by the linker. This property is initialized by the value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY` variable if it is set when a target is created. +.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` .. include:: PDB_NOTE.txt - -This property is not implemented by the :generator:`Visual Studio 6` -generator. diff --git a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst index caec2de..6037fa0 100644 --- a/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -11,5 +11,5 @@ property is initialized by the value of the :variable:`CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>` variable if it is set when a target is created. -This property is not implemented by the :generator:`Visual Studio 6` -generator. +.. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` +.. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/SOURCES.rst b/Help/prop_tgt/SOURCES.rst index 833b65a..493643e 100644 --- a/Help/prop_tgt/SOURCES.rst +++ b/Help/prop_tgt/SOURCES.rst @@ -3,5 +3,4 @@ SOURCES Source names specified for a target. -Read-only list of sources specified for a target. The names returned -are suitable for passing to the set_source_files_properties command. +List of sources specified for a target. 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/CMP0052.rst b/Help/release/dev/CMP0052.rst new file mode 100644 index 0000000..adb3d44 --- /dev/null +++ b/Help/release/dev/CMP0052.rst @@ -0,0 +1,5 @@ +CMP0052 +------- + +* Policy :policy:`CMP0052` introduced to control directories in the + :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of exported targets. diff --git a/Help/release/dev/CMP0053.rst b/Help/release/dev/CMP0053.rst new file mode 100644 index 0000000..3b835fb --- /dev/null +++ b/Help/release/dev/CMP0053.rst @@ -0,0 +1,6 @@ +CMP0053 +------- + +* The :manual:`cmake-language(7)` syntax for :ref:`Variable References` and + :ref:`Escape Sequences` was simplified in order to allow a much faster + implementation. See policy :policy:`CMP0053`. diff --git a/Help/release/dev/CMakeDetermineVSServicePack.rst b/Help/release/dev/CMakeDetermineVSServicePack.rst new file mode 100644 index 0000000..d9d7b41 --- /dev/null +++ b/Help/release/dev/CMakeDetermineVSServicePack.rst @@ -0,0 +1,6 @@ +CMakeDetermineVSServicePack +--------------------------- + +* The :module:`CMakeDetermineVSServicePack` module now warns that + it is deprecated and should not longer be used. Use the + :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable instead. diff --git a/Help/release/dev/ExternalData-missing-not-fatal.rst b/Help/release/dev/ExternalData-missing-not-fatal.rst new file mode 100644 index 0000000..e9f1f04 --- /dev/null +++ b/Help/release/dev/ExternalData-missing-not-fatal.rst @@ -0,0 +1,8 @@ +ExternalData-missing-not-fatal +------------------------------ + +* The :module:`ExternalData` module learned to tolerate a ``DATA{}`` + reference to a missing source file with a warning instead of + rejecting it with an error. This helps developers write new + ``DATA{}`` references to test reference outputs that have not + yet been created. diff --git a/Help/release/dev/ExternalProject-BUILD_ALWAYS.rst b/Help/release/dev/ExternalProject-BUILD_ALWAYS.rst new file mode 100644 index 0000000..5384671 --- /dev/null +++ b/Help/release/dev/ExternalProject-BUILD_ALWAYS.rst @@ -0,0 +1,6 @@ +ExternalProject-BUILD_ALWAYS +---------------------------- + +* The :module:`ExternalProject` module ``ExternalProject_Add`` command + learned a new ``BUILD_ALWAYS`` option to cause the external project + build step to run every time the host project is built. diff --git a/Help/release/dev/ExternalProject-no-download-progress.rst b/Help/release/dev/ExternalProject-no-download-progress.rst new file mode 100644 index 0000000..41db55d --- /dev/null +++ b/Help/release/dev/ExternalProject-no-download-progress.rst @@ -0,0 +1,6 @@ +ExternalProject-no-download-progress +------------------------------------ + +* The :module:`ExternalProject` module ``ExternalProject_Add`` command + learned a new ``DOWNLOAD_NO_PROGRESS`` option to disable progress + output while downloading the source tarball. diff --git a/Help/release/dev/ExternalProject_exclude-from-all.rst b/Help/release/dev/ExternalProject_exclude-from-all.rst new file mode 100644 index 0000000..1d62b3a --- /dev/null +++ b/Help/release/dev/ExternalProject_exclude-from-all.rst @@ -0,0 +1,11 @@ +ExternalProject_exclude-from-all +-------------------------------- + +* The :module:`ExternalProject` module ``ExternalProject_Add`` command + learned a new ``EXCLUDE_FROM_ALL`` option to cause the external + project target to have the :prop_tgt:`EXCLUDE_FROM_ALL` target + property set. + +* The :module:`ExternalProject` module ``ExternalProject_Add_Step`` command + learned a new ``EXCLUDE_FROM_MAIN`` option to cause the step to not be + a direct dependency of the main external project target. diff --git a/Help/release/dev/FeatureSummary_combine_WHAT_values.rst b/Help/release/dev/FeatureSummary_combine_WHAT_values.rst new file mode 100644 index 0000000..174ef15 --- /dev/null +++ b/Help/release/dev/FeatureSummary_combine_WHAT_values.rst @@ -0,0 +1,6 @@ +FeatureSummary_combine_WHAT_values +---------------------------------- + +* The :module:`FeatureSummary` module ``feature_summary`` API + learned to accept multiple values for the ``WHAT`` option and + combine them appropriately. diff --git a/Help/release/dev/FindCUDA-cubin-fatbin.rst b/Help/release/dev/FindCUDA-cubin-fatbin.rst new file mode 100644 index 0000000..d44da8e --- /dev/null +++ b/Help/release/dev/FindCUDA-cubin-fatbin.rst @@ -0,0 +1,5 @@ +FindCUDA-cubin-fatbin +--------------------- + +* The :module:`FindCUDA` module learned to support ``fatbin`` and ``cubin`` + modules. diff --git a/Help/release/dev/FindGTest-AUTO-SOURCES.rst b/Help/release/dev/FindGTest-AUTO-SOURCES.rst new file mode 100644 index 0000000..17b2a1b --- /dev/null +++ b/Help/release/dev/FindGTest-AUTO-SOURCES.rst @@ -0,0 +1,7 @@ +FindGTest-AUTO-SOURCES +---------------------- + +* The :module:`FindGTest` module ``gtest_add_tests`` macro learned + a new ``AUTO`` option to automatically read the :prop_tgt:`SOURCES` + target property of the test executable and scan the source files + for tests to be added. diff --git a/Help/release/dev/FindHg-WC_INFO.rst b/Help/release/dev/FindHg-WC_INFO.rst new file mode 100644 index 0000000..0caf2b3 --- /dev/null +++ b/Help/release/dev/FindHg-WC_INFO.rst @@ -0,0 +1,5 @@ +FindHg-WC_INFO +-------------- + +* The :module:`FindHg` module gained a new ``Hg_WC_INFO`` macro to + help run ``hg`` to extract information about a Mercurial work copy. diff --git a/Help/release/dev/FindOpenGL-target.rst b/Help/release/dev/FindOpenGL-target.rst new file mode 100644 index 0000000..670507e --- /dev/null +++ b/Help/release/dev/FindOpenGL-target.rst @@ -0,0 +1,5 @@ +FindOpenGL-target +----------------- + +* The :module:`FindOpenGL` module now provides imported targets + ``OpenGL::GL`` and ``OpenGL::GLU`` when the libraries are found. diff --git a/Help/release/dev/FindPkgConfig-PKG_CONFIG.rst b/Help/release/dev/FindPkgConfig-PKG_CONFIG.rst new file mode 100644 index 0000000..c0f6471 --- /dev/null +++ b/Help/release/dev/FindPkgConfig-PKG_CONFIG.rst @@ -0,0 +1,5 @@ +FindPkgConfig-PKG_CONFIG +------------------------ + +* The :module:`FindPkgConfig` module learned to use the ``PKG_CONFIG`` + environment variable value as the ``pkg-config`` executable, if set. diff --git a/Help/release/dev/OpenWatcom.rst b/Help/release/dev/OpenWatcom.rst new file mode 100644 index 0000000..63f6e8c --- /dev/null +++ b/Help/release/dev/OpenWatcom.rst @@ -0,0 +1,9 @@ +OpenWatcom +---------- + +* Support for the Open Watcom compiler has been overhauled. + The :variable:`CMAKE_<LANG>_COMPILER_ID` is now ``OpenWatcom``, + and the :variable:`CMAKE_<LANG>_COMPILER_VERSION` now uses + the Open Watcom external version numbering. The external + version numbers are lower than the internal version number + by 11. diff --git a/Help/release/dev/UseSWIG-guess_module_name.rst b/Help/release/dev/UseSWIG-guess_module_name.rst new file mode 100644 index 0000000..c895046 --- /dev/null +++ b/Help/release/dev/UseSWIG-guess_module_name.rst @@ -0,0 +1,6 @@ +UseSWIG-guess_module_name +------------------------- + +* The :module:`UseSWIG` module learned to detect the module name + from ``.i`` source files if possible to avoid the need to set + the ``SWIG_MODULE_NAME`` source file property explicitly. diff --git a/Help/release/dev/add-FindOpenCL.rst b/Help/release/dev/add-FindOpenCL.rst new file mode 100644 index 0000000..e1e30d1 --- /dev/null +++ b/Help/release/dev/add-FindOpenCL.rst @@ -0,0 +1,4 @@ +add-FindOpenCL +-------------- + +* The :module:`FindOpenCL` module was introduced. diff --git a/Help/release/dev/add_custom_command-DEPENDS-genex.rst b/Help/release/dev/add_custom_command-DEPENDS-genex.rst new file mode 100644 index 0000000..1e528e6 --- /dev/null +++ b/Help/release/dev/add_custom_command-DEPENDS-genex.rst @@ -0,0 +1,5 @@ +add_custom_command-DEPENDS-genex +-------------------------------- + +* The :command:`add_custom_command` command learned to interpret + :manual:`cmake-generator-expressions(7)` in arguments to ``DEPENDS``. diff --git a/Help/release/dev/cmake-E-env.rst b/Help/release/dev/cmake-E-env.rst new file mode 100644 index 0000000..4bdcd0c --- /dev/null +++ b/Help/release/dev/cmake-E-env.rst @@ -0,0 +1,4 @@ +cmake-E-env +----------- + +* The :manual:`cmake(1)` ``-E`` option learned a new ``env`` command. diff --git a/Help/release/dev/cmake-gui-capture-output.rst b/Help/release/dev/cmake-gui-capture-output.rst new file mode 100644 index 0000000..40cd25e --- /dev/null +++ b/Help/release/dev/cmake-gui-capture-output.rst @@ -0,0 +1,6 @@ +cmake-gui-capture-output +------------------------ + +* The :manual:`cmake-gui(1)` learned to capture output from child + processes started by the :command:`execute_process` command + and display it in the output window. diff --git a/Help/release/dev/compile-language-features.rst b/Help/release/dev/compile-language-features.rst new file mode 100644 index 0000000..d10e22b --- /dev/null +++ b/Help/release/dev/compile-language-features.rst @@ -0,0 +1,28 @@ +target-language-features +------------------------ + +* New :prop_tgt:`CXX_STANDARD` and :prop_tgt:`CXX_EXTENSIONS` target + properties may specify values which CMake uses to compute required + compile options such as ``-std=c++11`` or ``-std=gnu++11``. The + :variable:`CMAKE_CXX_STANDARD` and :variable:`CMAKE_CXX_EXTENSIONS` + variables may be set to initialize the target properties. + +* New :prop_tgt:`C_STANDARD` and :prop_tgt:`C_EXTENSIONS` target + properties may specify values which CMake uses to compute required + compile options such as ``-std=c11`` or ``-std=gnu11``. The + :variable:`CMAKE_C_STANDARD` and :variable:`CMAKE_C_EXTENSIONS` + variables may be set to initialize the target properties. + +* New :prop_tgt:`COMPILE_FEATURES` target property may contain a list + of features required to compile a target. CMake uses this + information to ensure that the compiler in use is capable of building + the target, and to add any necessary compile flags to support language + features. + +* New :command:`target_compile_features` command allows populating the + :prop_tgt:`COMPILE_FEATURES` target property, just like any other + build variable. + +* New ``COMPILE_FEATURES`` + :manual:`generator expression <cmake-generator-expressions(7)>` allows + setting build properties based on available compiler features. diff --git a/Help/release/dev/cpack-deb-compression-types.rst b/Help/release/dev/cpack-deb-compression-types.rst new file mode 100644 index 0000000..a33e333 --- /dev/null +++ b/Help/release/dev/cpack-deb-compression-types.rst @@ -0,0 +1,6 @@ +cpack-deb-compression-types +--------------------------- + +* The :module:`CPackDeb` module learned a new + :variable:`CPACK_DEBIAN_COMPRESSION_TYPE` variable to set the + tarball compression type. diff --git a/Help/release/dev/ctest-coverage-extra.rst b/Help/release/dev/ctest-coverage-extra.rst new file mode 100644 index 0000000..85d023b --- /dev/null +++ b/Help/release/dev/ctest-coverage-extra.rst @@ -0,0 +1,5 @@ +ctest-coverage-extra +-------------------- + +* The :command:`ctest_coverage` command learned to read variable + ``CTEST_COVERAGE_EXTRA_FLAGS`` to set ``CoverageExtraFlags``. diff --git a/Help/release/dev/ctest-intel-coverage.rst b/Help/release/dev/ctest-intel-coverage.rst new file mode 100644 index 0000000..11455a5 --- /dev/null +++ b/Help/release/dev/ctest-intel-coverage.rst @@ -0,0 +1,5 @@ +ctest-intel-coverage +-------------------- + +* The :command:`ctest_coverage` command learned to support + Intel coverage files with the ``codecov`` tool. diff --git a/Help/release/dev/custom-ninja-deptypes.rst b/Help/release/dev/custom-ninja-deptypes.rst new file mode 100644 index 0000000..7750da8 --- /dev/null +++ b/Help/release/dev/custom-ninja-deptypes.rst @@ -0,0 +1,5 @@ +custom-ninja-deptypes +--------------------- + +* Add a `CMAKE_NINJA_DEPTYPE_<LANG>` variable so that compilers may set the + deptype for use in Ninja other than those CMake itself knows about. diff --git a/Help/release/dev/delay-generator-toolset.rst b/Help/release/dev/delay-generator-toolset.rst new file mode 100644 index 0000000..0512834 --- /dev/null +++ b/Help/release/dev/delay-generator-toolset.rst @@ -0,0 +1,8 @@ +delay-generator-toolset +----------------------- + +* The :variable:`CMAKE_GENERATOR_TOOLSET` variable may now be + initialized in a toolchain file specified by the + :variable:`CMAKE_TOOLCHAIN_FILE` variable. This is useful + when cross-compiling with the Xcode or Visual Studio + generators. diff --git a/Help/release/dev/faster-parsers.rst b/Help/release/dev/faster-parsers.rst new file mode 100644 index 0000000..c2a8bfb --- /dev/null +++ b/Help/release/dev/faster-parsers.rst @@ -0,0 +1,6 @@ +faster-parsers +-------------- + +* The :manual:`cmake-language(7)` internal implementation of generator + expression and list expansion parsers have been optimized and shows + non-trivial speedup on large projects. diff --git a/Help/release/dev/find-module-targets.rst b/Help/release/dev/find-module-targets.rst new file mode 100644 index 0000000..98ea283 --- /dev/null +++ b/Help/release/dev/find-module-targets.rst @@ -0,0 +1,8 @@ +find-module-targets +------------------- + +* The :module:`FindGLUT` module now provides imported targets. + +* The :module:`FindGLEW` module now provides imported targets. + +* The :module:`FindZLIB` module now provides imported targets. diff --git a/Help/release/dev/install-messages.rst b/Help/release/dev/install-messages.rst new file mode 100644 index 0000000..e023ef7 --- /dev/null +++ b/Help/release/dev/install-messages.rst @@ -0,0 +1,8 @@ +install-messages +---------------- + +* The :command:`install` command learned a ``MESSAGE_NEVER`` option + to avoid output during installation. + +* The :variable:`CMAKE_INSTALL_MESSAGE` variable was introduced to + optionally reduce output installation. diff --git a/Help/release/dev/link-libraries-response-files.rst b/Help/release/dev/link-libraries-response-files.rst new file mode 100644 index 0000000..cecf7f6 --- /dev/null +++ b/Help/release/dev/link-libraries-response-files.rst @@ -0,0 +1,5 @@ +link-libraries-response-files +----------------------------- + +* The Makefile generators learned to use response files with GNU tools + on Windows to pass library directories and names to the linker. diff --git a/Help/release/dev/module-WriteCompilerDetectionHeader.rst b/Help/release/dev/module-WriteCompilerDetectionHeader.rst new file mode 100644 index 0000000..10e7b86 --- /dev/null +++ b/Help/release/dev/module-WriteCompilerDetectionHeader.rst @@ -0,0 +1,5 @@ +module-WriteCompilerDetectionHeader +----------------------------------- + +* The :module:`WriteCompilerDetectionHeader` module was added to allow + creation of a portable header file for compiler optional feature detection. diff --git a/Help/release/dev/msvc-compiler-pdb-files.rst b/Help/release/dev/msvc-compiler-pdb-files.rst new file mode 100644 index 0000000..d06d202 --- /dev/null +++ b/Help/release/dev/msvc-compiler-pdb-files.rst @@ -0,0 +1,10 @@ +msvc-compiler-pdb-files +----------------------- + +* New :prop_tgt:`COMPILE_PDB_NAME` and + :prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` target properties + were introduced to specify the MSVC compiler program database + file location (``cl /Fd``). This complements the existing + :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` + target properties that specify the linker program database + file location (``link /pdb``). diff --git a/Help/release/dev/package-disable-registry.rst b/Help/release/dev/package-disable-registry.rst new file mode 100644 index 0000000..1b23fde --- /dev/null +++ b/Help/release/dev/package-disable-registry.rst @@ -0,0 +1,11 @@ +package-disable-registry +------------------------ + +* The :command:`export(PACKAGE)` command learned to check the + :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable to skip + exporting the package. + +* The :command:`find_package` command learned to check the + :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` and + :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` + variables to skip searching the package registries. diff --git a/Help/release/dev/string-GENEX_STRIP.rst b/Help/release/dev/string-GENEX_STRIP.rst new file mode 100644 index 0000000..b5b1074 --- /dev/null +++ b/Help/release/dev/string-GENEX_STRIP.rst @@ -0,0 +1,6 @@ +string-GENEX_STRIP +------------------ + +* The :command:`string` command learned a new ``GENEX_STRIP`` subcommand + which removes + :manual:`generator expression <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/target-INTERFACE_SOURCES.rst b/Help/release/dev/target-INTERFACE_SOURCES.rst new file mode 100644 index 0000000..4e34943 --- /dev/null +++ b/Help/release/dev/target-INTERFACE_SOURCES.rst @@ -0,0 +1,5 @@ +target-INTERFACE_SOURCES +------------------------ + +* A new :prop_tgt:`INTERFACE_SOURCES` target property was introduced. This is + consumed by dependent targets, which compile and link the listed sources. diff --git a/Help/release/dev/target-SOURCES-genex.rst b/Help/release/dev/target-SOURCES-genex.rst new file mode 100644 index 0000000..9a65101 --- /dev/null +++ b/Help/release/dev/target-SOURCES-genex.rst @@ -0,0 +1,12 @@ +target-SOURCES-genex +-------------------- + +* The :prop_tgt:`SOURCES` target property now contains + :manual:`generator expression <cmake-generator-expressions(7)>` + such as ``TARGET_OBJECTS`` when read at configure time, if + policy :policy:`CMP0051` is ``NEW``. + +* The :prop_tgt:`SOURCES` target property now generally supports + :manual:`generator expression <cmake-generator-expressions(7)>`. The + generator expressions may be used in the :command:`add_library` and + :command:`add_executable` commands. diff --git a/Help/release/dev/target-SOURCES-write.rst b/Help/release/dev/target-SOURCES-write.rst new file mode 100644 index 0000000..a754a73 --- /dev/null +++ b/Help/release/dev/target-SOURCES-write.rst @@ -0,0 +1,6 @@ +target-SOURCES-write.rst +------------------------ + +* It is now possible to write and append to the :prop_tgt:`SOURCES` target + property. The :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable may be + used to trace the origin of sources. diff --git a/Help/release/dev/target_sources-command.rst b/Help/release/dev/target_sources-command.rst new file mode 100644 index 0000000..abfb303 --- /dev/null +++ b/Help/release/dev/target_sources-command.rst @@ -0,0 +1,5 @@ +target_sources-command +---------------------- + +* The :command:`target_sources` command was added to add to the + :prop_tgt:`SOURCES` target property. diff --git a/Help/release/dev/variable_watch-no-allowed-access.rst b/Help/release/dev/variable_watch-no-allowed-access.rst new file mode 100644 index 0000000..ba7b4a5 --- /dev/null +++ b/Help/release/dev/variable_watch-no-allowed-access.rst @@ -0,0 +1,8 @@ +variable_watch-no-allowed-access +-------------------------------- + +* Callbacks established by the :command:`variable_watch` command will no + longer receive the ``ALLOWED_UNKNOWN_READ_ACCESS`` access type when + the undocumented ``CMAKE_ALLOW_UNKNOWN_VARIABLE_READ_ACCESS`` variable is + set. Uninitialized variable accesses will always be reported as + ``UNKNOWN_READ_ACCESS``. diff --git a/Help/release/dev/xcode-file-type.rst b/Help/release/dev/xcode-file-type.rst new file mode 100644 index 0000000..6f637f7 --- /dev/null +++ b/Help/release/dev/xcode-file-type.rst @@ -0,0 +1,7 @@ +xcode-file-type +--------------- + +* The :generator:`Xcode` generator learned to check source + file properties :prop_sf:`XCODE_EXPLICIT_FILE_TYPE` and + :prop_sf:`XCODE_LAST_KNOWN_FILE_TYPE` for a custom Xcode + file reference type. diff --git a/Help/release/index.rst b/Help/release/index.rst index 752c568..15ce065 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,6 +5,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst new file mode 100644 index 0000000..ea33c7d --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY.rst @@ -0,0 +1,8 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY +---------------------------------- + +Output directory for MS debug symbol ``.pdb`` files +generated by the compiler while building source files. + +This variable is used to initialize the +:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY` property on all the targets. diff --git a/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..fdeb9ab --- /dev/null +++ b/Help/variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,11 @@ +CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG> +------------------------------------------- + +Per-configuration output directory for MS debug symbol ``.pdb`` files +generated by the compiler while building source files. + +This is a per-configuration version of +:variable:`CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY`. +This variable is used to initialize the +:prop_tgt:`COMPILE_PDB_OUTPUT_DIRECTORY_<CONFIG>` +property on all the targets. diff --git a/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst new file mode 100644 index 0000000..460c78c --- /dev/null +++ b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_COMPILE_FEATURES +-------------------------- + +List of features known to the C++ compiler + +These features are known to be available for use with the C++ compiler. This +list is a subset of the features listed in the :prop_gbl:`CMAKE_CXX_KNOWN_FEATURES` +global property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst new file mode 100644 index 0000000..6448371 --- /dev/null +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_EXTENSIONS +-------------------- + +Default value for ``CXX_EXTENSIONS`` property of targets. + +This variable is used to initialize the :prop_tgt:`CXX_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst new file mode 100644 index 0000000..963a42a --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_STANDARD +------------------ + +Default value for ``CXX_STANDARD`` property of targets. + +This variable is used to initialize the :prop_tgt:`CXX_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..f7750fa --- /dev/null +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_CXX_STANDARD_REQUIRED +--------------------------- + +Default value for ``CXX_STANDARD_REQUIRED`` property of targets. + +This variable is used to initialize the :prop_tgt:`CXX_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_C_COMPILE_FEATURES.rst b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst new file mode 100644 index 0000000..1106246 --- /dev/null +++ b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst @@ -0,0 +1,11 @@ +CMAKE_C_COMPILE_FEATURES +------------------------ + +List of features known to the C compiler + +These features are known to be available for use with the C compiler. This +list is a subset of the features listed in the :prop_gbl:`CMAKE_C_KNOWN_FEATURES` +global property. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst new file mode 100644 index 0000000..5e935fc --- /dev/null +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -0,0 +1,11 @@ +CMAKE_C_EXTENSIONS +------------------ + +Default value for ``C_EXTENSIONS`` property of targets. + +This variable is used to initialize the :prop_tgt:`C_EXTENSIONS` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst new file mode 100644 index 0000000..3098ce5 --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -0,0 +1,11 @@ +CMAKE_C_STANDARD +---------------- + +Default value for ``C_STANDARD`` property of targets. + +This variable is used to initialize the :prop_tgt:`C_STANDARD` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst new file mode 100644 index 0000000..c24eea4 --- /dev/null +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -0,0 +1,11 @@ +CMAKE_C_STANDARD_REQUIRED +------------------------- + +Default value for ``C_STANDARD_REQUIRED`` property of targets. + +This variable is used to initialize the :prop_tgt:`C_STANDARD_REQUIRED` +property on all targets. See that target property for additional +information. + +See the :manual:`cmake-compile-features(7)` manual for information on +compile features. diff --git a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst index 11aed0c..e200b86 100644 --- a/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst +++ b/Help/variable/CMAKE_DEBUG_TARGET_PROPERTIES.rst @@ -6,7 +6,8 @@ Enables tracing output for target properties. This variable can be populated with a list of properties to generate debug output for when evaluating target properties. Currently it can only be used when evaluating the :prop_tgt:`INCLUDE_DIRECTORIES`, -:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`, :prop_tgt:`AUTOUIC_OPTIONS`, +:prop_tgt:`COMPILE_DEFINITIONS`, :prop_tgt:`COMPILE_OPTIONS`, +:prop_tgt:`AUTOUIC_OPTIONS`, :prop_tgt:`SOURCES`, :prop_tgt:`COMPILE_FEATURES`, :prop_tgt:`POSITION_INDEPENDENT_CODE` target properties and any other property listed in :prop_tgt:`COMPATIBLE_INTERFACE_STRING` and other ``COMPATIBLE_INTERFACE_`` properties. It outputs an origin for each entry in the target property. diff --git a/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..ee109ba --- /dev/null +++ b/Help/variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,11 @@ +CMAKE_EXPORT_NO_PACKAGE_REGISTRY +-------------------------------- + +Disable the :command:`export(PACKAGE)` command. + +In some cases, for example for packaging and for system wide +installations, it is not desirable to write the user package registry. +If the :variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` variable is enabled, +the :command:`export(PACKAGE)` command will do nothing. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..9058471 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY.rst @@ -0,0 +1,13 @@ +CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY +-------------------------------------- + +Skip :ref:`User Package Registry` in :command:`find_package` calls. + +In some cases, for example to locate only system wide installations, it +is not desirable to use the :ref:`User Package Registry` when searching +for packages. If the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` +variable is enabled, all the :command:`find_package` commands will skip +the :ref:`User Package Registry` as if they were called with the +``NO_CMAKE_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst new file mode 100644 index 0000000..44588b1 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY.rst @@ -0,0 +1,13 @@ +CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY +--------------------------------------------- + +Skip :ref:`System Package Registry` in :command:`find_package` calls. + +In some cases, it is not desirable to use the +:ref:`System Package Registry` when searching for packages. If the +:variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` variable is +enabled, all the :command:`find_package` commands will skip +the :ref:`System Package Registry` as if they were called with the +``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` argument. + +See also :ref:`Disabling the Package Registry`. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 4540eaa..9ccc8b3 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -7,3 +7,9 @@ Some CMake generators support a toolset name to be given to the native build system to choose a compiler. If the user specifies a toolset name (e.g. via the cmake -T option) 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_TOOLSET``. Once a given +build tree has been initialized with a particular value for this +variable, changing the value has undefined behavior. diff --git a/Help/variable/CMAKE_HOST_SYSTEM.rst b/Help/variable/CMAKE_HOST_SYSTEM.rst index 4366ee3..c2a8f1a 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM.rst @@ -1,7 +1,10 @@ CMAKE_HOST_SYSTEM ----------------- -Name of system cmake is being run on. +Composit Name of OS CMake is being run on. -The same as CMAKE_SYSTEM but for the host system instead of the target -system when cross compiling. +This variable is the composite of :variable:`CMAKE_HOST_SYSTEM_NAME` and +:variable:`CMAKE_HOST_SYSTEM_VERSION`, e.g. +``${CMAKE_HOST_SYSTEM_NAME}-${CMAKE_HOST_SYSTEM_VERSION}``. If +:variable:`CMAKE_HOST_SYSTEM_VERSION` is not set, then this variable is +the same as :variable:`CMAKE_HOST_SYSTEM_NAME`. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst index 718208a..a221de9 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst @@ -3,5 +3,6 @@ CMAKE_HOST_SYSTEM_NAME Name of the OS CMake is running on. -The same as CMAKE_SYSTEM_NAME but for the host system instead of the -target system when cross compiling. +On systems that have the uname command, this variable is set to the +output of uname -s. ``Linux``, ``Windows``, and ``Darwin`` for Mac OS X +are the values found on the big three operating systems. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst index 2700b66..790565a 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_PROCESSOR.rst @@ -3,5 +3,6 @@ CMAKE_HOST_SYSTEM_PROCESSOR The name of the CPU CMake is running on. -The same as CMAKE_SYSTEM_PROCESSOR but for the host system instead of -the target system when cross compiling. +On systems that support uname, this variable is set to the output of +uname -p, on windows it is set to the value of the environment variable +``PROCESSOR_ARCHITECTURE``. diff --git a/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst b/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst index a8451e8..e7e0052 100644 --- a/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst +++ b/Help/variable/CMAKE_HOST_SYSTEM_VERSION.rst @@ -1,7 +1,8 @@ CMAKE_HOST_SYSTEM_VERSION ------------------------- -OS version CMake is running on. +The OS version CMake is running on. -The same as CMAKE_SYSTEM_VERSION but for the host system instead of -the target system when cross compiling. +A numeric version string for the system. On systems that support +uname, this variable is set to the output of uname -r. On other +systems this is set to major-minor version numbers. diff --git a/Help/variable/CMAKE_INSTALL_MESSAGE.rst b/Help/variable/CMAKE_INSTALL_MESSAGE.rst new file mode 100644 index 0000000..304df26 --- /dev/null +++ b/Help/variable/CMAKE_INSTALL_MESSAGE.rst @@ -0,0 +1,30 @@ +CMAKE_INSTALL_MESSAGE +--------------------- + +Specify verbosity of installation script code generated by the +:command:`install` command (using the :command:`file(INSTALL)` command). +For paths that are newly installed or updated, installation +may print lines like:: + + -- Installing: /some/destination/path + +For paths that are already up to date, installation may print +lines like:: + + -- Up-to-date: /some/destination/path + +The ``CMAKE_INSTALL_MESSAGE`` variable may be set to control +which messages are printed: + +``ALWAYS`` + Print both ``Installing`` and ``Up-to-date`` messages. + +``LAZY`` + Print ``Installing`` but not ``Up-to-date`` messages. + +``NEVER`` + Print neither ``Installing`` nor ``Up-to-date`` messages. + +Other values have undefined behavior and may not be diagnosed. + +If this variable is not set, the default behavior is ``ALWAYS``. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index cf9c386..f554f4e 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -20,13 +20,13 @@ include: Intel = Intel Compiler (intel.com) MIPSpro = SGI MIPSpro (sgi.com) MSVC = Microsoft Visual Studio (microsoft.com) + OpenWatcom = Open Watcom (openwatcom.org) PGI = The Portland Group (pgroup.com) PathScale = PathScale (pathscale.com) SDCC = Small Device C Compiler (sdcc.sourceforge.net) SunPro = Oracle Solaris Studio (oracle.com) TI = Texas Instruments (ti.com) TinyCC = Tiny C Compiler (tinycc.org) - Watcom = Open Watcom (openwatcom.org) XL, VisualAge, zOS = IBM XL (ibm.com) This variable is not guaranteed to be defined for all compilers or diff --git a/Help/variable/CMAKE_SYSTEM.rst b/Help/variable/CMAKE_SYSTEM.rst index 283d0be..23f5980 100644 --- a/Help/variable/CMAKE_SYSTEM.rst +++ b/Help/variable/CMAKE_SYSTEM.rst @@ -1,9 +1,10 @@ CMAKE_SYSTEM ------------ -Name of system cmake is compiling for. +Composit Name of OS CMake is compiling for. -This variable is the composite of CMAKE_SYSTEM_NAME and -CMAKE_SYSTEM_VERSION, like this -${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VERSION}. If CMAKE_SYSTEM_VERSION -is not set, then CMAKE_SYSTEM is the same as CMAKE_SYSTEM_NAME. +This variable is the composite of :variable:`CMAKE_SYSTEM_NAME` and +:variable:`CMAKE_SYSTEM_VERSION`, e.g. +``${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_VERSION}``. If +:variable:`CMAKE_SYSTEM_VERSION` is not set, then this variable is +the same as :variable:`CMAKE_SYSTEM_NAME`. diff --git a/Help/variable/CMAKE_SYSTEM_NAME.rst b/Help/variable/CMAKE_SYSTEM_NAME.rst index 9871dd9..189dc18 100644 --- a/Help/variable/CMAKE_SYSTEM_NAME.rst +++ b/Help/variable/CMAKE_SYSTEM_NAME.rst @@ -3,7 +3,6 @@ CMAKE_SYSTEM_NAME Name of the OS CMake is building for. -This is the name of the operating system on which CMake is targeting. -On systems that have the uname command, this variable is set to the -output of uname -s. Linux, Windows, and Darwin for Mac OS X are the -values found on the big three operating systems. +This is the name of the OS on which CMake is targeting. This variable +is the same as :variable:`CMAKE_HOST_SYSTEM_NAME` if you build for the +host system instead of the target system when cross compiling. diff --git a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst index 1655ada..8ad89f1 100644 --- a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -3,6 +3,6 @@ CMAKE_SYSTEM_PROCESSOR The name of the CPU CMake is building for. -On systems that support uname, this variable is set to the output of -uname -p, on windows it is set to the value of the environment -variable PROCESSOR_ARCHITECTURE +This variable is the same as :variable:`CMAKE_HOST_SYSTEM_PROCESSOR` if +you build for the host system instead of the target system when +cross compiling. diff --git a/Help/variable/CMAKE_SYSTEM_VERSION.rst b/Help/variable/CMAKE_SYSTEM_VERSION.rst index 61bb40e..33510bb 100644 --- a/Help/variable/CMAKE_SYSTEM_VERSION.rst +++ b/Help/variable/CMAKE_SYSTEM_VERSION.rst @@ -1,8 +1,8 @@ CMAKE_SYSTEM_VERSION -------------------- -OS version CMake is building for. +The OS version CMake is building for. -A numeric version string for the system, on systems that support -uname, this variable is set to the output of uname -r. On other -systems this is set to major-minor version numbers. +This variable is the same as :variable:`CMAKE_HOST_SYSTEM_VERSION` if +you build for the host system instead of the target system when +cross compiling. diff --git a/Help/variable/CTEST_BINARY_DIRECTORY.rst b/Help/variable/CTEST_BINARY_DIRECTORY.rst new file mode 100644 index 0000000..fd8461f --- /dev/null +++ b/Help/variable/CTEST_BINARY_DIRECTORY.rst @@ -0,0 +1,5 @@ +CTEST_BINARY_DIRECTORY +---------------------- + +Specify the CTest ``BuildDirectory`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BUILD_COMMAND.rst b/Help/variable/CTEST_BUILD_COMMAND.rst new file mode 100644 index 0000000..7b13ba0 --- /dev/null +++ b/Help/variable/CTEST_BUILD_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_BUILD_COMMAND +------------------- + +Specify the CTest ``MakeCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BUILD_NAME.rst b/Help/variable/CTEST_BUILD_NAME.rst new file mode 100644 index 0000000..d25d84c --- /dev/null +++ b/Help/variable/CTEST_BUILD_NAME.rst @@ -0,0 +1,5 @@ +CTEST_BUILD_NAME +---------------- + +Specify the CTest ``BuildName`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BZR_COMMAND.rst b/Help/variable/CTEST_BZR_COMMAND.rst new file mode 100644 index 0000000..474d621 --- /dev/null +++ b/Help/variable/CTEST_BZR_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_BZR_COMMAND +----------------- + +Specify the CTest ``BZRCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..d0f9579 --- /dev/null +++ b/Help/variable/CTEST_BZR_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_BZR_UPDATE_OPTIONS +------------------------ + +Specify the CTest ``BZRUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CHECKOUT_COMMAND.rst b/Help/variable/CTEST_CHECKOUT_COMMAND.rst new file mode 100644 index 0000000..da256f2 --- /dev/null +++ b/Help/variable/CTEST_CHECKOUT_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_CHECKOUT_COMMAND +---------------------- + +Tell the :command:`ctest_start` command how to checkout or initialize +the source directory in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CONFIGURATION_TYPE.rst b/Help/variable/CTEST_CONFIGURATION_TYPE.rst new file mode 100644 index 0000000..c905480 --- /dev/null +++ b/Help/variable/CTEST_CONFIGURATION_TYPE.rst @@ -0,0 +1,5 @@ +CTEST_CONFIGURATION_TYPE +------------------------ + +Specify the CTest ``DefaultCTestConfigurationType`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CONFIGURE_COMMAND.rst b/Help/variable/CTEST_CONFIGURE_COMMAND.rst new file mode 100644 index 0000000..5561b6d --- /dev/null +++ b/Help/variable/CTEST_CONFIGURE_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_CONFIGURE_COMMAND +----------------------- + +Specify the CTest ``ConfigureCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_COVERAGE_COMMAND.rst b/Help/variable/CTEST_COVERAGE_COMMAND.rst new file mode 100644 index 0000000..a669dd7 --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_COMMAND.rst @@ -0,0 +1,60 @@ +CTEST_COVERAGE_COMMAND +---------------------- + +Specify the CTest ``CoverageCommand`` setting +in a :manual:`ctest(1)` dashboard client script. + +Cobertura +''''''''' + +Using `Cobertura`_ as the coverage generation within your multi-module +Java project can generate a series of XML files. + +The Cobertura Coverage parser expects to read the coverage data from a +single XML file which contains the coverage data for all modules. +Cobertura has a program with the ability to merge given cobertura.ser files +and then another program to generate a combined XML file from the previous +merged file. For command line testing, this can be done by hand prior to +CTest looking for the coverage files. For script builds, +set the ``CTEST_COVERAGE_COMMAND`` variable to point to a file which will +perform these same steps, such as a .sh or .bat file. + +.. code-block:: cmake + + set(CTEST_COVERAGE_COMMAND .../run-coverage-and-consolidate.sh) + +where the ``run-coverage-and-consolidate.sh`` script is perhaps created by +the :command:`configure_file` command and might contain the following code: + +.. code-block:: bash + + #!/usr/bin/env bash + CoberturaFiles="$(find "/path/to/source" -name "cobertura.ser")" + SourceDirs="$(find "/path/to/source" -name "java" -type d)" + cobertura-merge --datafile coberturamerge.ser $CoberturaFiles + cobertura-report --datafile coberturamerge.ser --destination . \ + --format xml $SourceDirs + +The script uses ``find`` to capture the paths to all of the cobertura.ser files +found below the project's source directory. It keeps the list of files and +supplies it as an argument to the ``cobertura-merge`` program. The ``--datafile`` +argument signifies where the result of the merge will be kept. + +The combined ``coberturamerge.ser`` file is then used to generate the XML report +using the ``cobertura-report`` program. The call to the cobertura-report program +requires some named arguments. + +``--datafila`` + path to the merged .ser file + +``--destination`` + path to put the output files(s) + +``--format`` + file format to write output in: xml or html + +The rest of the supplied arguments consist of the full paths to the +/src/main/java directories of each module within the souce tree. These +directories are needed and should not be forgotten. + +.. _`Cobertura`: http://cobertura.github.io/cobertura/ diff --git a/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst new file mode 100644 index 0000000..2981955 --- /dev/null +++ b/Help/variable/CTEST_COVERAGE_EXTRA_FLAGS.rst @@ -0,0 +1,5 @@ +CTEST_COVERAGE_EXTRA_FLAGS +-------------------------- + +Specify the CTest ``CoverageExtraFlags`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CURL_OPTIONS.rst b/Help/variable/CTEST_CURL_OPTIONS.rst new file mode 100644 index 0000000..fc5dfc4 --- /dev/null +++ b/Help/variable/CTEST_CURL_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_CURL_OPTIONS +------------------ + +Specify the CTest ``CurlOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CVS_CHECKOUT.rst b/Help/variable/CTEST_CVS_CHECKOUT.rst new file mode 100644 index 0000000..6431c02 --- /dev/null +++ b/Help/variable/CTEST_CVS_CHECKOUT.rst @@ -0,0 +1,4 @@ +CTEST_CVS_CHECKOUT +------------------ + +Deprecated. Use :variable:`CTEST_CHECKOUT_COMMAND` instead. diff --git a/Help/variable/CTEST_CVS_COMMAND.rst b/Help/variable/CTEST_CVS_COMMAND.rst new file mode 100644 index 0000000..049700b --- /dev/null +++ b/Help/variable/CTEST_CVS_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_CVS_COMMAND +----------------- + +Specify the CTest ``CVSCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..d7f2f7c --- /dev/null +++ b/Help/variable/CTEST_CVS_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_CVS_UPDATE_OPTIONS +------------------------ + +Specify the CTest ``CVSUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_LOCATION.rst b/Help/variable/CTEST_DROP_LOCATION.rst new file mode 100644 index 0000000..c0f2215 --- /dev/null +++ b/Help/variable/CTEST_DROP_LOCATION.rst @@ -0,0 +1,5 @@ +CTEST_DROP_LOCATION +------------------- + +Specify the CTest ``DropLocation`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_METHOD.rst b/Help/variable/CTEST_DROP_METHOD.rst new file mode 100644 index 0000000..50fbd4d --- /dev/null +++ b/Help/variable/CTEST_DROP_METHOD.rst @@ -0,0 +1,5 @@ +CTEST_DROP_METHOD +----------------- + +Specify the CTest ``DropMethod`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE.rst b/Help/variable/CTEST_DROP_SITE.rst new file mode 100644 index 0000000..d15d99b --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE +--------------- + +Specify the CTest ``DropSite`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_CDASH.rst b/Help/variable/CTEST_DROP_SITE_CDASH.rst new file mode 100644 index 0000000..22b9776 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_CDASH.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE_CDASH +--------------------- + +Specify the CTest ``IsCDash`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_PASSWORD.rst b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst new file mode 100644 index 0000000..904d2c8 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_PASSWORD.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE_PASSWORD +------------------------ + +Specify the CTest ``DropSitePassword`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_DROP_SITE_USER.rst b/Help/variable/CTEST_DROP_SITE_USER.rst new file mode 100644 index 0000000..a860a03 --- /dev/null +++ b/Help/variable/CTEST_DROP_SITE_USER.rst @@ -0,0 +1,5 @@ +CTEST_DROP_SITE_USER +-------------------- + +Specify the CTest ``DropSiteUser`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_COMMAND.rst b/Help/variable/CTEST_GIT_COMMAND.rst new file mode 100644 index 0000000..eb83792 --- /dev/null +++ b/Help/variable/CTEST_GIT_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_GIT_COMMAND +----------------- + +Specify the CTest ``GITCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst new file mode 100644 index 0000000..0c479e6 --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_CUSTOM.rst @@ -0,0 +1,5 @@ +CTEST_GIT_UPDATE_CUSTOM +----------------------- + +Specify the CTest ``GITUpdateCustom`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..4590a78 --- /dev/null +++ b/Help/variable/CTEST_GIT_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_GIT_UPDATE_OPTIONS +------------------------ + +Specify the CTest ``GITUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_HG_COMMAND.rst b/Help/variable/CTEST_HG_COMMAND.rst new file mode 100644 index 0000000..3854950 --- /dev/null +++ b/Help/variable/CTEST_HG_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_HG_COMMAND +---------------- + +Specify the CTest ``HGCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..9049c1f --- /dev/null +++ b/Help/variable/CTEST_HG_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_HG_UPDATE_OPTIONS +----------------------- + +Specify the CTest ``HGUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst new file mode 100644 index 0000000..8c199ba --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_MEMORYCHECK_COMMAND +------------------------- + +Specify the CTest ``MemoryCheckCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst new file mode 100644 index 0000000..3e26ab5 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_COMMAND_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_MEMORYCHECK_COMMAND_OPTIONS +--------------------------------- + +Specify the CTest ``MemoryCheckCommandOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst new file mode 100644 index 0000000..1147ee8 --- /dev/null +++ b/Help/variable/CTEST_MEMORYCHECK_SUPPRESSIONS_FILE.rst @@ -0,0 +1,5 @@ +CTEST_MEMORYCHECK_SUPPRESSIONS_FILE +----------------------------------- + +Specify the CTest ``MemoryCheckSuppressionFile`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_NIGHTLY_START_TIME.rst b/Help/variable/CTEST_NIGHTLY_START_TIME.rst new file mode 100644 index 0000000..bc80276 --- /dev/null +++ b/Help/variable/CTEST_NIGHTLY_START_TIME.rst @@ -0,0 +1,5 @@ +CTEST_NIGHTLY_START_TIME +------------------------ + +Specify the CTest ``NightlyStartTime`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_CLIENT.rst b/Help/variable/CTEST_P4_CLIENT.rst new file mode 100644 index 0000000..347ea54 --- /dev/null +++ b/Help/variable/CTEST_P4_CLIENT.rst @@ -0,0 +1,5 @@ +CTEST_P4_CLIENT +--------------- + +Specify the CTest ``P4Client`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_COMMAND.rst b/Help/variable/CTEST_P4_COMMAND.rst new file mode 100644 index 0000000..defab12 --- /dev/null +++ b/Help/variable/CTEST_P4_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_P4_COMMAND +---------------- + +Specify the CTest ``P4Command`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_OPTIONS.rst b/Help/variable/CTEST_P4_OPTIONS.rst new file mode 100644 index 0000000..fee4ce2 --- /dev/null +++ b/Help/variable/CTEST_P4_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_P4_OPTIONS +---------------- + +Specify the CTest ``P4Options`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..0e2790f --- /dev/null +++ b/Help/variable/CTEST_P4_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_P4_UPDATE_OPTIONS +----------------------- + +Specify the CTest ``P4UpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SCP_COMMAND.rst b/Help/variable/CTEST_SCP_COMMAND.rst new file mode 100644 index 0000000..0f128b1 --- /dev/null +++ b/Help/variable/CTEST_SCP_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_SCP_COMMAND +----------------- + +Specify the CTest ``SCPCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SITE.rst b/Help/variable/CTEST_SITE.rst new file mode 100644 index 0000000..8a5ec25 --- /dev/null +++ b/Help/variable/CTEST_SITE.rst @@ -0,0 +1,5 @@ +CTEST_SITE +---------- + +Specify the CTest ``Site`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SOURCE_DIRECTORY.rst b/Help/variable/CTEST_SOURCE_DIRECTORY.rst new file mode 100644 index 0000000..b6837d1 --- /dev/null +++ b/Help/variable/CTEST_SOURCE_DIRECTORY.rst @@ -0,0 +1,5 @@ +CTEST_SOURCE_DIRECTORY +---------------------- + +Specify the CTest ``SourceDirectory`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_COMMAND.rst b/Help/variable/CTEST_SVN_COMMAND.rst new file mode 100644 index 0000000..af90143 --- /dev/null +++ b/Help/variable/CTEST_SVN_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_SVN_COMMAND +----------------- + +Specify the CTest ``SVNCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_OPTIONS.rst b/Help/variable/CTEST_SVN_OPTIONS.rst new file mode 100644 index 0000000..76551dc --- /dev/null +++ b/Help/variable/CTEST_SVN_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_SVN_OPTIONS +----------------- + +Specify the CTest ``SVNOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..5f01a19 --- /dev/null +++ b/Help/variable/CTEST_SVN_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_SVN_UPDATE_OPTIONS +------------------------ + +Specify the CTest ``SVNUpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_TEST_TIMEOUT.rst b/Help/variable/CTEST_TEST_TIMEOUT.rst new file mode 100644 index 0000000..c031437 --- /dev/null +++ b/Help/variable/CTEST_TEST_TIMEOUT.rst @@ -0,0 +1,5 @@ +CTEST_TEST_TIMEOUT +------------------ + +Specify the CTest ``TimeOut`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_TRIGGER_SITE.rst b/Help/variable/CTEST_TRIGGER_SITE.rst new file mode 100644 index 0000000..de92428 --- /dev/null +++ b/Help/variable/CTEST_TRIGGER_SITE.rst @@ -0,0 +1,5 @@ +CTEST_TRIGGER_SITE +------------------ + +Specify the CTest ``TriggerSite`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_COMMAND.rst b/Help/variable/CTEST_UPDATE_COMMAND.rst new file mode 100644 index 0000000..90155d0 --- /dev/null +++ b/Help/variable/CTEST_UPDATE_COMMAND.rst @@ -0,0 +1,5 @@ +CTEST_UPDATE_COMMAND +-------------------- + +Specify the CTest ``UpdateCommand`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_UPDATE_OPTIONS.rst b/Help/variable/CTEST_UPDATE_OPTIONS.rst new file mode 100644 index 0000000..e43d61d --- /dev/null +++ b/Help/variable/CTEST_UPDATE_OPTIONS.rst @@ -0,0 +1,5 @@ +CTEST_UPDATE_OPTIONS +-------------------- + +Specify the CTest ``UpdateOptions`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/CTEST_USE_LAUNCHERS.rst b/Help/variable/CTEST_USE_LAUNCHERS.rst new file mode 100644 index 0000000..9f48a2e --- /dev/null +++ b/Help/variable/CTEST_USE_LAUNCHERS.rst @@ -0,0 +1,5 @@ +CTEST_USE_LAUNCHERS +------------------- + +Specify the CTest ``UseLaunchers`` setting +in a :manual:`ctest(1)` dashboard client script. |