diff options
Diffstat (limited to 'Help')
198 files changed, 2119 insertions, 745 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 5889e90..9358329 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -53,6 +53,10 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows: .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH +.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace:: + <prefix>/|XXX_SUBDIR| for each <prefix>/[s]bin in PATH, and + <entry>/|XXX_SUBDIR| for other entries in PATH + .. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace:: <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index 10997ec..7a66143 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -7,13 +7,17 @@ Add a dependency between top-level targets. add_dependencies(<target> [<target-dependency>]...) -Make a top-level <target> depend on other top-level targets to ensure -that they build before <target> does. A top-level target is one -created by ADD_EXECUTABLE, ADD_LIBRARY, or ADD_CUSTOM_TARGET. -Dependencies added to an IMPORTED target are followed transitively in -its place since the target itself does not build. +Make a top-level ``<target>`` depend on other top-level targets to +ensure that they build before ``<target>`` does. A top-level target +is one created by one of the :command:`add_executable`, +:command:`add_library`, or :command:`add_custom_target` commands +(but not targets generated by CMake like ``install``). -See the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND for -adding file-level dependencies in custom rules. See the -OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add file-level -dependencies to object files. +Dependencies added to an :ref:`imported target <Imported Targets>` +or an :ref:`interface library <Interface Libraries>` are followed +transitively in its place since the target itself does not build. + +See the ``DEPENDS`` option of :command:`add_custom_target` and +:command:`add_custom_command` commands for adding file-level +dependencies in custom rules. See the :prop_sf:`OBJECT_DEPENDS` +source file property to add file-level dependencies to object files. diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index 82a9a42..1298c1f 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -19,7 +19,8 @@ Sets the given ``<variable>`` to a command-line string of the form:: where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line tool, and ``<config>`` and ``<target>`` are the values provided to the ``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i`` -option is added for Makefile generators. +option is added for :ref:`Makefile Generators` if policy :policy:`CMP0061` +is not set to ``NEW``. When invoked, this ``cmake --build`` command line will launch the underlying build system tool. @@ -32,7 +33,7 @@ This second signature is deprecated, but still available for backwards compatibility. Use the first signature instead. It sets the given ``<cachevariable>`` to a command-line string as -above but without the ``--config`` or ``--target`` options. +above but without the ``--target`` option. The ``<makecommand>`` is ignored but should be the full path to msdev, devenv, nmake, make or one of the end user build tools for legacy invocations. diff --git a/Help/command/cmake_minimum_required.rst b/Help/command/cmake_minimum_required.rst index 1bdffa4..9865eeb 100644 --- a/Help/command/cmake_minimum_required.rst +++ b/Help/command/cmake_minimum_required.rst @@ -28,3 +28,14 @@ which enables compatibility features for CMake 2.4 and lower. The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher. It should be specified so CMake versions 2.4 and lower fail with an error instead of just a warning. + +.. note:: + Call the ``cmake_minimum_required()`` command at the beginning of + the top-level ``CMakeLists.txt`` file even before calling the + :command:`project` command. It is important to establish version + and policy settings before invoking other commands whose behavior + they may affect. See also policy :policy:`CMP0000`. + + Calling ``cmake_minimum_required()`` inside a :command:`function` + limits some effects to the function scope when invoked. Such calls + should not be made with the intention of having global effects. diff --git a/Help/command/configure_file.rst b/Help/command/configure_file.rst index 70357f2..4304f09 100644 --- a/Help/command/configure_file.rst +++ b/Help/command/configure_file.rst @@ -9,38 +9,103 @@ Copy a file to another location and modify its contents. [COPYONLY] [ESCAPE_QUOTES] [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ]) -Copies a file <input> to file <output> and substitutes variable values -referenced in the file content. If <input> is a relative path it is -evaluated with respect to the current source directory. The <input> -must be a file, not a directory. If <output> is a relative path it is -evaluated with respect to the current binary directory. If <output> -names an existing directory the input file is placed in that directory -with its original name. - -If the <input> file is modified the build system will re-run CMake to +Copies an ``<input>`` file to an ``<output>`` file and substitutes +variable values referenced as ``@VAR@`` or ``${VAR}`` in the input +file content. Each variable reference will be replaced with the +current value of the variable, or the empty string if the variable +is not defined. Furthermore, input lines of the form:: + + #cmakedefine VAR ... + +will be replaced with either:: + + #define VAR ... + +or:: + + /* #undef VAR */ + +depending on whether ``VAR`` is set in CMake to any value not considered +a false constant by the :command:`if` command. The "..." content on the +line after the variable name, if any, is processed as above. +Input file lines of the form ``#cmakedefine01 VAR`` will be replaced with +either ``#define VAR 1`` or ``#define VAR 0`` similarly. + +If the input file is modified the build system will re-run CMake to re-configure the file and generate the build system again. -This command replaces any variables in the input file referenced as -${VAR} or @VAR@ with their values as determined by CMake. If a -variable is not defined, it will be replaced with nothing. If -COPYONLY is specified, then no variable expansion will take place. If -ESCAPE_QUOTES is specified then any substituted quotes will be C-style -escaped. The file will be configured with the current values of CMake -variables. If @ONLY is specified, only variables of the form @VAR@ -will be replaced and ${VAR} will be ignored. This is useful for -configuring scripts that use ${VAR}. - -Input file lines of the form "#cmakedefine VAR ..." will be replaced -with either "#define VAR ..." or ``/* #undef VAR */`` depending on -whether VAR is set in CMake to any value not considered a false -constant by the if() command. (Content of "...", if any, is processed -as above.) Input file lines of the form "#cmakedefine01 VAR" will be -replaced with either "#define VAR 1" or "#define VAR 0" similarly. - -With NEWLINE_STYLE the line ending could be adjusted: +The arguments are: -:: +``<input>`` + Path to the input file. A relative path is treated with respect to + the value of :variable:`CMAKE_CURRENT_SOURCE_DIR`. The input path + must be a file, not a directory. + +``<output>`` + Path to the output file or directory. A relative path is treated + with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`. + If the path names an existing directory the output file is placed + in that directory with the same file name as the input file. + +``COPYONLY`` + Copy the file without replacing any variable references or other + content. This option may not be used with ``NEWLINE_STYLE``. + +``ESCAPE_QUOTES`` + Escape any substituted quotes with backslashes (C-style). + +``@ONLY`` + Restrict variable replacement to references of the form ``@VAR@``. + This is useful for configuring scripts that use ``${VAR}`` syntax. + +``NEWLINE_STYLE <style>`` + Specify the newline style for the output file. Specify + ``UNIX`` or ``LF`` for ``\n`` newlines, or specify + ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines. + This option may not be used with ``COPYONLY``. + +Example +^^^^^^^ + +Consider a source tree containing a ``foo.h.in`` file: + +.. code-block:: c + + #cmakedefine FOO_ENABLE + #cmakedefine FOO_STRING "@FOO_STRING@" + +An adjacent ``CMakeLists.txt`` may use ``configure_file`` to +configure the header: + +.. code-block:: cmake + + option(FOO_ENABLE "Enable Foo" ON) + if(FOO_ENABLE) + set(FOO_STRING "foo") + endif() + configure_file(foo.h.in foo.h @ONLY) + +This creates a ``foo.h`` in the build directory corresponding to +this source directory. If the ``FOO_ENABLE`` option is on, the +configured file will contain: + +.. code-block:: c + + #define FOO_ENABLE + #define FOO_STRING "foo" + +Otherwise it will contain: + +.. code-block:: c + + /* #undef FOO_ENABLE */ + /* #undef FOO_STRING */ + +One may then use the :command:`include_directories` command to +specify the output directory as an include directory: + +.. code-block:: cmake - 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n. + include_directories(${CMAKE_CURRENT_BINARY_DIR}) -COPYONLY must not be used with NEWLINE_STYLE. +so that sources may include the header as ``#include <foo.h>``. diff --git a/Help/command/ctest_build.rst b/Help/command/ctest_build.rst index 4a95cdd..e1b7793 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -1,29 +1,73 @@ ctest_build ----------- -Build the project. +Perform the :ref:`CTest Build Step` as a :ref:`Dashboard Client`. :: - ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res] - [APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val]) + ctest_build([BUILD <build-dir>] [APPEND] + [CONFIGURATION <config>] + [FLAGS <flags>] + [PROJECT_NAME <project-name>] + [TARGET <target-name>] + [NUMBER_ERRORS <num-err-var>] + [NUMBER_WARNINGS <num-warn-var>] + [RETURN_VALUE <result-var>] + ) -Builds the given build directory and stores results in Build.xml. If -no BUILD is given, the CTEST_BINARY_DIRECTORY variable is used. +Build the project and store results in ``Build.xml`` +for submission with the :command:`ctest_submit` command. -The TARGET variable can be used to specify a build target. If none is -specified, the "all" target will be built. +The :variable:`CTEST_BUILD_COMMAND` variable may be set to explicitly +specify the build command line. Otherwise the build command line is +computed automatically based on the options given. -The RETURN_VALUE option specifies a variable in which to store the -return value of the native build tool. The NUMBER_ERRORS and -NUMBER_WARNINGS options specify variables in which to store the number -of build errors and warnings detected. +The options are: -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. +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. -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. +``APPEND`` + Mark results for append to those previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + +``CONFIGURATION <config>`` + Specify the build configuration (e.g. ``Debug``). If not + specified the ``CTEST_BUILD_CONFIGURATION`` variable will be checked. + Otherwise the ``-C <cfg>`` option given to the :manual:`ctest(1)` + command will be used, if any. + +``FLAGS <flags>`` + Pass additional arguments to the underlying build command. + If not specified the ``CTEST_BUILD_FLAGS`` variable will be checked. + This can, e.g., be used to trigger a parallel build using the + ``-j`` option of make. See the :module:`ProcessorCount` module + for an example. + +``PROJECT_NAME <project-name>`` + Set the name of the project to build. This should correspond + to the top-level call to the :command:`project` command. + If not specified the ``CTEST_PROJECT_NAME`` variable will be checked. + +``TARGET <target-name>`` + Specify the name of a target to build. If not specified the + ``CTEST_BUILD_TARGET`` variable will be checked. Otherwise the + default target will be built. This is the "all" target + (called ``ALL_BUILD`` in :ref:`Visual Studio Generators`). + +``NUMBER_ERRORS <num-err-var>`` + Store the number of build errors detected in the given variable. + +``NUMBER_WARNINGS <num-warn-var>`` + Store the number of build warnings detected in the given variable. + +``RETURN_VALUE <result-var>`` + Store the return value of the native build tool in the given variable. + +``QUIET`` + Suppress any CTest-specific non-error output that would have been + printed to the console otherwise. The summary of warnings / errors, + as well as the output from the native build tool is unaffected by + this option. diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index 2c4e305..851c292 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst @@ -1,21 +1,39 @@ ctest_configure --------------- -Configure the project build tree. +Perform the :ref:`CTest Configure Step` as a :ref:`Dashboard Client`. :: - ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND] - [OPTIONS options] [RETURN_VALUE res]) + ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND] + [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]) -Configures the given build directory and stores results in -Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY -variable is used. If no SOURCE is given, the CTEST_SOURCE_DIRECTORY -variable is used. The OPTIONS argument specifies command line -arguments to pass to the configuration tool. The RETURN_VALUE option -specifies a variable in which to store the return value of the native -build tool. +Configure the project build tree and record results in ``Configure.xml`` +for submission with the :command:`ctest_submit` command. -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. +The options are: + +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``SOURCE <source-dir>`` + Specify the source directory. If not given, the + :variable:`CTEST_SOURCE_DIRECTORY` variable is used. + +``APPEND`` + Mark results for append to those previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + +``OPTIONS <options>`` + Specify command-line arguments to pass to the configuration tool. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable the return value of the native + configuration tool. + +``QUIET`` + Suppress any CTest-specific non-error messages that would have + otherwise been printed to the console. Output from the underlying + configure command is not affected. diff --git a/Help/command/ctest_coverage.rst b/Help/command/ctest_coverage.rst index 4c90f9c..12429b9 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -1,20 +1,39 @@ ctest_coverage -------------- -Collect coverage tool results. +Perform the :ref:`CTest Coverage Step` as a :ref:`Dashboard Client`. :: - ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND] - [LABELS label1 [label2 [...]]]) + ctest_coverage([BUILD <build-dir>] [APPEND] + [LABELS <label>...] + [RETURN_VALUE <result-var>] + [QUIET] + ) -Perform the coverage of the given build directory and stores results -in Coverage.xml. The second argument is a variable that will hold -value. +Collect coverage tool results and stores them in ``Coverage.xml`` +for submission with the :command:`ctest_submit` command. -The LABELS option filters the coverage report to include only source -files labeled with at least one of the labels specified. +The options are: -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. +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``APPEND`` + Mark results for append to those previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + +``LABELS`` + Filter the coverage report to include only source files labeled + with at least one of the labels specified. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable ``0`` if coverage tools + ran without error and non-zero otherwise. + +``QUIET`` + Suppress any CTest-specific non-error output that would have been + printed to the console otherwise. The summary indicating how many + lines of code were covered is unaffected by this option. diff --git a/Help/command/ctest_memcheck.rst b/Help/command/ctest_memcheck.rst index ca47ed0..2800511 100644 --- a/Help/command/ctest_memcheck.rst +++ b/Help/command/ctest_memcheck.rst @@ -1,28 +1,28 @@ ctest_memcheck -------------- -Run tests with a dynamic analysis tool. +Perform the :ref:`CTest MemCheck Step` as a :ref:`Dashboard Client`. :: - ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND] - [START start number] [END end number] - [STRIDE stride number] [EXCLUDE exclude regex ] - [INCLUDE include regex] - [EXCLUDE_LABEL exclude regex] - [INCLUDE_LABEL label regex] - [PARALLEL_LEVEL level] ) + ctest_memcheck([BUILD <build-dir>] [APPEND] + [START <start-number>] + [END <end-number>] + [STRIDE <stride-number>] + [EXCLUDE <exclude-regex>] + [INCLUDE <include-regex>] + [EXCLUDE_LABEL <label-exclude-regex>] + [INCLUDE_LABEL <label-include-regex>] + [PARALLEL_LEVEL <level>] + [SCHEDULE_RANDOM <ON|OFF>] + [STOP_TIME <time-of-day>] + [RETURN_VALUE <result-var>] + [QUIET] + ) -Tests the given build directory and stores results in MemCheck.xml. -The second argument is a variable that will hold value. Optionally, -you can specify the starting test number START, the ending test number -END, the number of tests to skip between each test STRIDE, a regular -expression for tests to run INCLUDE, or a regular expression for tests -not to run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular -expressions for tests to be included or excluded by the test property -LABEL. PARALLEL_LEVEL should be set to a positive number representing -the number of tests to be run in parallel. -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. +Run tests with a dynamic analysis tool and store results in +``MemCheck.xml`` for submission with the :command:`ctest_submit` +command. + +The options are the same as those for the :command:`ctest_test` command. diff --git a/Help/command/ctest_start.rst b/Help/command/ctest_start.rst index d7472db..b5c7b34 100644 --- a/Help/command/ctest_start.rst +++ b/Help/command/ctest_start.rst @@ -5,7 +5,7 @@ Starts the testing for a given model :: - ctest_start(Model [TRACK <track>] [APPEND] [source [binary]]) + ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET]) Starts the testing for a given model. The command should be called after the binary directory is initialized. If the 'source' and @@ -14,7 +14,8 @@ after the binary directory is initialized. If the 'source' and 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. +on the current time stamp. If QUIET is used, CTest will suppress any +non-error messages that it otherwise would have printed to the console. If the :variable:`CTEST_CHECKOUT_COMMAND` variable (or the :variable:`CTEST_CVS_CHECKOUT` variable) diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 2b83ed9..6830b59 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -1,42 +1,55 @@ ctest_submit ------------ -Submit results to a dashboard server. +Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. :: - ctest_submit([PARTS ...] [FILES ...] - [RETRY_COUNT count] - [RETRY_DELAY delay] - [RETURN_VALUE res] + ctest_submit([PARTS <part>...] [FILES <file>...] + [RETRY_COUNT <count>] + [RETRY_DELAY <delay>] + [RETURN_VALUE <result-var>] + [QUIET] ) -By default all available parts are submitted if no PARTS or FILES are -specified. The PARTS option lists a subset of parts to be submitted. -Valid part names are: +Submit results to a dashboard server. +By default all available parts are submitted. -:: +The options are: + +``PARTS <part>...`` + Specify a subset of parts to submit. Valid part names are:: + + Start = nothing + Update = ctest_update results, in Update.xml + Configure = ctest_configure results, in Configure.xml + Build = ctest_build results, in Build.xml + Test = ctest_test results, in Test.xml + Coverage = ctest_coverage results, in Coverage.xml + MemCheck = ctest_memcheck results, in DynamicAnalysis.xml + Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml + ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES + Upload = Files prepared for upload by ctest_upload(), in Upload.xml + Submit = nothing + +``FILES <file>...`` + Specify an explicit list of specific files to be submitted. + Each individual file must exist at the time of the call. + +``RETRY_COUNT <count>`` + Specify how many times to retry a timed-out submission. + +``RETRY_DELAY <delay>`` + Specify how long (in seconds) to wait after a timed-out submission + before attempting to re-submit. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable ``0`` for success and + non-zero on failure. - Start = nothing - Update = ctest_update results, in Update.xml - Configure = ctest_configure results, in Configure.xml - Build = ctest_build results, in Build.xml - Test = ctest_test results, in Test.xml - Coverage = ctest_coverage results, in Coverage.xml - MemCheck = ctest_memcheck results, in DynamicAnalysis.xml - Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml - ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES - Upload = Files prepared for upload by ctest_upload(), in Upload.xml - Submit = nothing - -The FILES option explicitly lists specific files to be submitted. -Each individual file must exist at the time of the call. - -The RETRY_DELAY option specifies how long in seconds to wait after a -timed-out submission before attempting to re-submit. - -The RETRY_COUNT option specifies how many times to retry a timed-out -submission. +``QUIET`` + Suppress all non-error messages that would have otherwise been + printed to the console. Submit to CDash Upload API ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 5f28083..8cbb9ec 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -1,33 +1,79 @@ ctest_test ---------- -Run tests in the project build tree. +Perform the :ref:`CTest Test Step` as a :ref:`Dashboard Client`. :: - ctest_test([BUILD build_dir] [APPEND] - [START start number] [END end number] - [STRIDE stride number] [EXCLUDE exclude regex ] - [INCLUDE include regex] [RETURN_VALUE res] - [EXCLUDE_LABEL exclude regex] - [INCLUDE_LABEL label regex] - [PARALLEL_LEVEL level] - [SCHEDULE_RANDOM on] - [STOP_TIME time of day]) - -Tests the given build directory and stores results in Test.xml. The -second argument is a variable that will hold value. Optionally, you -can specify the starting test number START, the ending test number -END, the number of tests to skip between each test STRIDE, a regular -expression for tests to run INCLUDE, or a regular expression for tests -to not run EXCLUDE. EXCLUDE_LABEL and INCLUDE_LABEL are regular -expression for test to be included or excluded by the test property -LABEL. PARALLEL_LEVEL should be set to a positive number representing -the number of tests to be run in parallel. SCHEDULE_RANDOM will -launch tests in a random order, and is typically used to detect -implicit test dependencies. STOP_TIME is the time of day at which the -tests should all stop running. - -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. + ctest_test([BUILD <build-dir>] [APPEND] + [START <start-number>] + [END <end-number>] + [STRIDE <stride-number>] + [EXCLUDE <exclude-regex>] + [INCLUDE <include-regex>] + [EXCLUDE_LABEL <label-exclude-regex>] + [INCLUDE_LABEL <label-include-regex>] + [PARALLEL_LEVEL <level>] + [SCHEDULE_RANDOM <ON|OFF>] + [STOP_TIME <time-of-day>] + [RETURN_VALUE <result-var>] + [QUIET] + ) + +Run tests in the project build tree and store results in +``Test.xml`` for submission with the :command:`ctest_submit` command. + +The options are: + +``BUILD <build-dir>`` + Specify the top-level build directory. If not given, the + :variable:`CTEST_BINARY_DIRECTORY` variable is used. + +``APPEND`` + Mark results for append to those previously submitted to a + dashboard server since the last :command:`ctest_start` call. + Append semantics are defined by the dashboard server in use. + +``START <start-number>`` + Specify the beginning of a range of test numbers. + +``END <end-number>`` + Specify the end of a range of test numbers. + +``STRIDE <stride-number>`` + Specify the stride by which to step acorss a range of test numbers. + +``EXCLUDE <exclude-regex>`` + Specify a regular expression matching test names to exclude. + +``INCLUDE <include-regex>`` + Specify a regular expression matching test names to include. + Tests not matching this expression are excluded. + +``EXCLUDE_LABEL <label-exclude-regex>`` + Specify a regular expression matching test labels to exclude. + +``INCLUDE_LABEL <label-include-regex>`` + Specify a regular expression matching test labels to include. + Tests not matching this expression are excluded. + +``PARALLEL_LEVEL <level>`` + Specify a positive number representing the number of tests to + be run in parallel. + +``SCHEDULE_RANDOM <ON|OFF>`` + Launch tests in a random order. This may be useful for detecting + implicit test dependencies. + +``STOP_TIME <time-of-day>`` + Specify a time of day at which the tests should all stop running. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable ``0`` if all tests passed. + Store non-zero if anything went wrong. + +``QUIET`` + Suppress any CTest-specific non-error messages that would have otherwise + been printed to the console. Output from the underlying test command is not + affected. Summary info detailing the percentage of passing tests is also + unaffected by the ``QUIET`` option. diff --git a/Help/command/ctest_update.rst b/Help/command/ctest_update.rst index d34e192..74af1f7 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -1,13 +1,27 @@ ctest_update ------------ -Update the work tree from version control. +Perform the :ref:`CTest Update Step` as a :ref:`Dashboard Client`. :: - ctest_update([SOURCE source] [RETURN_VALUE res]) + ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET]) -Updates the given source directory and stores results in Update.xml. -If no SOURCE is given, the CTEST_SOURCE_DIRECTORY variable is used. -The RETURN_VALUE option specifies a variable in which to store the -result, which is the number of files updated or -1 on error. +Update the source tree from version control and record results in +``Update.xml`` for submission with the :command:`ctest_submit` command. + +The options are: + +``SOURCE <source-dir>`` + Specify the source directory. If not given, the + :variable:`CTEST_SOURCE_DIRECTORY` variable is used. + +``RETURN_VALUE <result-var>`` + Store in the ``<result-var>`` variable the number of files + updated or ``-1`` on error. + +``QUIET`` + Tell CTest to suppress most non-error messages that it would + have otherwise printed to the console. CTest will still report + the new revision of the repository and any conflicting files + that were found. diff --git a/Help/command/ctest_upload.rst b/Help/command/ctest_upload.rst index 9156af5..d9630d2 100644 --- a/Help/command/ctest_upload.rst +++ b/Help/command/ctest_upload.rst @@ -1,11 +1,18 @@ ctest_upload ------------ -Upload files to a dashboard server. +Upload files to a dashboard server as a :ref:`Dashboard Client`. :: - ctest_upload(FILES ...) + ctest_upload(FILES <file>... [QUIET]) -Pass a list of files to be sent along with the build results to the -dashboard server. +The options are: + +``FILES <file>...`` + Specify a list of files to be sent along with the build results to the + dashboard server. + +``QUIET`` + Suppress any CTest-specific non-error output that would have been + printed to the console otherwise. diff --git a/Help/command/execute_process.rst b/Help/command/execute_process.rst index 478b30e..c38ec1a 100644 --- a/Help/command/execute_process.rst +++ b/Help/command/execute_process.rst @@ -57,7 +57,8 @@ OUTPUT_VARIABLE, ERROR_VARIABLE INPUT_FILE, OUTPUT_FILE, ERROR_FILE The file named will be attached to the standard input of the first process, standard output of the last process, or standard error of - all processes, respectively. + all processes, respectively. If the same file is named for both + output and error then it will be used for both. OUTPUT_QUIET, ERROR_QUIET The standard output or standard error results will be quietly ignored. diff --git a/Help/command/file.rst b/Help/command/file.rst index 73d4cfa..bbddd40 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -92,9 +92,12 @@ store it in a ``<variable>``. :: - file(GLOB <variable> [RELATIVE <path>] [<globbing-expressions>...]) - file(GLOB_RECURSE <variable> [RELATIVE <path>] - [FOLLOW_SYMLINKS] [<globbing-expressions>...]) + file(GLOB <variable> + [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [<globbing-expressions>...]) + file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] + [LIST_DIRECTORIES true|false] [RELATIVE <path>] + [<globbing-expressions>...]) Generate a list of files that match the ``<globbing-expressions>`` and store it into the ``<variable>``. Globbing expressions are similar to @@ -102,6 +105,9 @@ regular expressions, but much simpler. If ``RELATIVE`` flag is specified, the results will be returned as relative paths to the given path. +By default ``GLOB`` lists directories - directories are omited in result if +``LIST_DIRECTORIES`` is set to false. + .. 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 @@ -119,6 +125,11 @@ 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``. +By default ``GLOB_RECURSE`` omits directories from result list - setting +``LIST_DIRECTORIES`` to true adds directories to result list. +If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to +``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories. + Examples of recursive globbing include:: /dir/*.py - match all python files in /dir and subdirectories @@ -302,8 +313,12 @@ 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 :command:`install(DIRECTORY)` command for documentation of -permissions, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options. +permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and +``EXCLUDE`` options. Copying directories preserves the structure +of their content even if options are used to select a subset of +files. The ``INSTALL`` signature differs slightly from ``COPY``: it prints status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable), diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst index db7e151..be309a5 100644 --- a/Help/command/find_file.rst +++ b/Help/command/find_file.rst @@ -13,7 +13,10 @@ find_file .. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH .. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE, + <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, + and the directories in PATH itself. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 91342ba..e3dcd2b 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -13,7 +13,10 @@ find_library .. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH .. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and LIB +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in LIB, + <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, + and the directories in PATH itself. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and @@ -31,6 +34,12 @@ default will consider one name at a time and search every directory for it. The NAMES_PER_DIR option tells this command to consider one directory at a time and search for all names in it. +Each library name given to the ``NAMES`` option is first considered +as a library file name and then considered with platform-specific +prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``). Therefore one +may specify library file names such as ``libfoo.a`` directly. +This can be used to locate static libraries on UNIX-like systems. + If the library found is a framework, then VAR will be set to the full path to the framework <fullPath>/A.framework. When a full path to a framework is used as a library, CMake will use a -framework A, and a diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index 7f518a6..a5efba6 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -68,7 +68,7 @@ The complete Config mode command signature is:: [NO_CMAKE_PATH] [NO_SYSTEM_ENVIRONMENT_PATH] [NO_CMAKE_PACKAGE_REGISTRY] - [NO_CMAKE_BUILDS_PATH] + [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing. [NO_CMAKE_SYSTEM_PATH] [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY] [CMAKE_FIND_ROOT_PATH_BOTH | @@ -265,20 +265,14 @@ enabled. PATH -5. Search project build trees recently configured in a :manual:`cmake-gui(1)`. - This can be skipped if ``NO_CMAKE_BUILDS_PATH`` is passed. It is intended - for the case when a user is building multiple dependent projects one - after another. - (This step is implemented only on Windows.) - -6. Search paths stored in the CMake :ref:`User Package Registry`. +5. Search paths stored in the CMake :ref:`User Package Registry`. 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. -7. Search cmake variables defined in the Platform files for the +6. Search cmake variables defined in the Platform files for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed:: @@ -286,14 +280,14 @@ enabled. CMAKE_SYSTEM_FRAMEWORK_PATH CMAKE_SYSTEM_APPBUNDLE_PATH -8. Search paths stored in the CMake :ref:`System Package Registry`. +7. Search paths stored in the CMake :ref:`System Package Registry`. 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. -9. Search paths specified by the ``PATHS`` option. These are typically +8. Search paths specified by the ``PATHS`` option. These are typically hard-coded guesses. .. |FIND_XXX| replace:: find_package diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst index 95d49e7..b5a6e37 100644 --- a/Help/command/find_path.rst +++ b/Help/command/find_path.rst @@ -13,7 +13,10 @@ find_path .. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH .. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH -.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE +.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE, + <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and + |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, + and the directories in PATH itself. .. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace:: <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and diff --git a/Help/command/function.rst b/Help/command/function.rst index b18e03c..7ffdfee 100644 --- a/Help/command/function.rst +++ b/Help/command/function.rst @@ -1,9 +1,7 @@ function -------- -Start recording a function for later invocation as a command. - -:: +Start recording a function for later invocation as a command:: function(<name> [arg1 [arg2 [arg3 ...]]]) COMMAND1(ARGS ...) @@ -11,21 +9,28 @@ Start recording a function for later invocation as a command. ... endfunction(<name>) -Define a function named <name> that takes arguments named arg1 arg2 -arg3 (...). Commands listed after function, but before the matching -endfunction, are not invoked until the function is invoked. When it -is invoked, the commands recorded in the function are first modified -by replacing formal parameters (${arg1}) with the arguments passed, -and then invoked as normal commands. In addition to referencing the -formal parameters you can reference the variable ARGC which will be -set to the number of arguments passed into the function as well as -ARGV0 ARGV1 ARGV2 ... which will have the actual values of the -arguments passed in. This facilitates creating functions with -optional arguments. Additionally ARGV holds the list of all arguments -given to the function and ARGN holds the list of arguments past the -last expected argument. +Define a function named ``<name>`` that takes arguments named ``arg1``, +``arg2``, ``arg3``, (...). +Commands listed after function, but before the matching +:command:`endfunction()`, are not invoked until the function is invoked. +When it is invoked, the commands recorded in the function are first +modified by replacing formal parameters (``${arg1}``) with the arguments +passed, and then invoked as normal commands. +In addition to referencing the formal parameters you can reference the +``ARGC`` variable which will be set to the number of arguments passed +into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ... which +will have the actual values of the arguments passed in. +This facilitates creating functions with optional arguments. +Additionally ``ARGV`` holds the list of all arguments given to the +function and ``ARGN`` holds the list of arguments past the last expected +argument. +Referencing to ``ARGV#`` arguments beyond ``ARGC`` have undefined +behavior. Checking that ``ARGC`` is greater than ``#`` is the only way +to ensure that ``ARGV#`` was passed to the function as an extra +argument. -A function opens a new scope: see set(var PARENT_SCOPE) for details. +A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for +details. -See the cmake_policy() command documentation for the behavior of -policies inside functions. +See the :command:`cmake_policy()` command documentation for the behavior +of policies inside functions. diff --git a/Help/command/if.rst b/Help/command/if.rst index d50b14c..396becf 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -134,6 +134,9 @@ Possible expressions are: Component-wise integer version number comparison (version format is ``major[.minor[.patch[.tweak]]]``). +``if(<variable|string> IN_LIST <variable>)`` + True if the given element is contained in the named list variable. + ``if(DEFINED <variable>)`` True if the given variable is defined. It does not matter if the variable is true or false just if it has been set. (Note macro diff --git a/Help/command/install.rst b/Help/command/install.rst index 5dd5aaa..c99ed73 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -159,6 +159,10 @@ 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. +The install destination given to the target install ``DESTINATION`` may +use "generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + Installing Files ^^^^^^^^^^^^^^^^ diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 258dc50..6bee69c 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -1,9 +1,7 @@ macro ----- -Start recording a macro for later invocation as a command. - -:: +Start recording a macro for later invocation as a command:: macro(<name> [arg1 [arg2 [arg3 ...]]]) COMMAND1(ARGS ...) @@ -11,22 +9,28 @@ Start recording a macro for later invocation as a command. ... endmacro(<name>) -Define a macro named <name> that takes arguments named arg1 arg2 arg3 -(...). Commands listed after macro, but before the matching endmacro, -are not invoked until the macro is invoked. When it is invoked, the -commands recorded in the macro are first modified by replacing formal -parameters (``${arg1}``) with the arguments passed, and then invoked as -normal commands. In addition to referencing the formal parameters you -can reference the values ``${ARGC}`` which will be set to the number of -arguments passed into the function as well as ``${ARGV0}`` ``${ARGV1}`` -``${ARGV2}`` ... which will have the actual values of the arguments -passed in. This facilitates creating macros with optional arguments. +Define a macro named ``<name>`` that takes arguments named ``arg1``, +``arg2``, ``arg3``, (...). +Commands listed after macro, but before the matching +:command:`endmacro()`, are not invoked until the macro is invoked. +When it is invoked, the commands recorded in the macro are first +modified by replacing formal parameters (``${arg1}``) with the arguments +passed, and then invoked as normal commands. +In addition to referencing the formal parameters you can reference the +values ``${ARGC}`` which will be set to the number of arguments passed +into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``, +... which will have the actual values of the arguments passed in. +This facilitates creating macros with optional arguments. Additionally ``${ARGV}`` holds the list of all arguments given to the macro and ``${ARGN}`` holds the list of arguments past the last expected argument. +Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined +behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only +way to ensure that ``${ARGV#}`` was passed to the function as an extra +argument. -See the cmake_policy() command documentation for the behavior of -policies inside macros. +See the :command:`cmake_policy()` command documentation for the behavior +of policies inside macros. Macro Argument Caveats ^^^^^^^^^^^^^^^^^^^^^^ @@ -37,10 +41,15 @@ replacements much like the C preprocessor would do with a macro. Therefore you will NOT be able to use commands like:: if(ARGV1) # ARGV1 is not a variable + if(DEFINED ARGV2) # ARGV2 is not a variable + if(ARGC GREATER 2) # ARGC is not a variable foreach(loop_var IN LISTS ARGN) # ARGN is not a variable -In the first case you can use ``if(${ARGV1})``, in the second case, you can -use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments. +In the first case, you can use ``if(${ARGV1})``. +In the second and third case, the proper way to check if an optional +variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``. +In the last case, you can use ``foreach(loop_var ${ARGN})`` but this +will skip empty arguments. If you need to include them, you can use:: set(list_var "${ARGN}") diff --git a/Help/command/project.rst b/Help/command/project.rst index c601a01..6c5ace7 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -55,3 +55,10 @@ literal, direct call to the :command:`project` command; loading one through the :command:`include` command is not sufficient. If no such call exists CMake will implicitly add one to the top that enables the default languages (``C`` and ``CXX``). + +.. note:: + Call the :command:`cmake_minimum_required` command at the beginning + of the top-level ``CMakeLists.txt`` file even before calling the + ``project()`` command. It is important to establish version and + policy settings before invoking other commands whose behavior they + may affect. See also policy :policy:`CMP0000`. diff --git a/Help/command/set.rst b/Help/command/set.rst index 7a59550..d04b880 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -1,116 +1,89 @@ set --- -Set a CMake, cache or environment variable to a given value. +Set a normal, cache, or environment variable to a given value. +See the :ref:`cmake-language(7) variables <CMake Language Variables>` +documentation for the scopes and interaction of normal variables +and cache entries. + +Signatures of this command that specify a ``<value>...`` placeholder +expect zero or more arguments. Multiple arguments will be joined as +a :ref:`;-list <CMake Language Lists>` to form the actual variable +value to be set. Zero arguments will cause normal variables to be +unset. See the :command:`unset` command to unset variables explicitly. + +Set Normal Variable +^^^^^^^^^^^^^^^^^^^ :: - set(<variable> <value> - [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE]) + set(<variable> <value>... [PARENT_SCOPE]) + +Set the given ``<variable>`` in the current function or directory scope. -Within CMake sets <variable> to the value <value>. <value> is -expanded before <variable> is set to it. Normally, set will set a -regular CMake variable. If CACHE is present, then the <variable> is -put in the cache instead, unless it is already in the cache. See -section 'Variable types in CMake' below for details of regular and -cache variables and their interactions. If CACHE is used, <type> and -<docstring> are required. <type> is used by the CMake GUI to choose a -widget with which the user sets a value. The value for <type> may be -one of +If the ``PARENT_SCOPE`` option is given the variable will be set in +the scope above the current scope. Each new directory or function +creates a new scope. This command will set the value of a variable +into the parent directory or calling function (whichever is applicable +to the case at hand). + +Set Cache Entry +^^^^^^^^^^^^^^^ :: - FILEPATH = File chooser dialog. - PATH = Directory chooser dialog. - STRING = Arbitrary string. - BOOL = Boolean ON/OFF checkbox. - INTERNAL = No GUI entry (used for persistent variables). + set(<variable> <value>... CACHE <type> <docstring> [FORCE]) -If <type> is INTERNAL, the cache variable is marked as internal, and -will not be shown to the user in tools like cmake-gui. This is -intended for values that should be persisted in the cache, but which -users should not normally change. INTERNAL implies FORCE. +Set the given cache ``<variable>`` (cache entry). Since cache entries +are meant to provide user-settable values this does not overwrite +existing cache entries by default. Use the ``FORCE`` option to +overwrite existing entries. -Normally, set(...CACHE...) creates cache variables, but does not -modify them. If FORCE is specified, the value of the cache variable -is set, even if the variable is already in the cache. This should -normally be avoided, as it will remove any changes to the cache -variable's value by the user. +The ``<type>`` must be specified as one of: -If PARENT_SCOPE is present, the variable will be set in the scope -above the current scope. Each new directory or function creates a new -scope. This command will set the value of a variable into the parent -directory or calling function (whichever is applicable to the case at -hand). PARENT_SCOPE cannot be combined with CACHE. +``BOOL`` + Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox. -If <value> is not specified then the variable is removed instead of -set. See also: the unset() command. +``FILEPATH`` + Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog. -:: +``PATH`` + Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog. - set(<variable> <value1> ... <valueN>) +``STRING`` + A line of text. :manual:`cmake-gui(1)` offers a text field or a + drop-down selection if the :prop_cache:`STRINGS` cache entry + property is set. -In this case <variable> is set to a semicolon separated list of -values. +``INTERNAL`` + A line of text. :manual:`cmake-gui(1)` does not show internal entries. + They may be used to store variables persistently across runs. + Use of this type implies ``FORCE``. -<variable> can be an environment variable such as: +The ``<docstring>`` must be specified as a line of text providing +a quick summary of the option for presentation to :manual:`cmake-gui(1)` +users. + +If the cache entry does not exist prior to the call or the ``FORCE`` +option is given then the cache entry will be set to the given value. +Furthermore, any normal variable binding in the current scope will +be removed to expose the newly cached value to any immediately +following evaluation. + +It is possible for the cache entry to exist prior to the call but +have no type set if it was created on the :manual:`cmake(1)` command +line by a user through the ``-D<var>=<value>`` option without +specifying a type. In this case the ``set`` command will add the +type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH`` +and the ``<value>`` provided on the command line is a relative path, +then the ``set`` command will treat the path as relative to the +current working directory and convert it to an absolute path. + +Set Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^ :: - set( ENV{PATH} /home/martink ) - -in which case the environment variable will be set. - -*** Variable types in CMake *** - -In CMake there are two types of variables: normal variables and cache -variables. Normal variables are meant for the internal use of the -script (just like variables in most programming languages); they are -not persisted across CMake runs. Cache variables (unless set with -INTERNAL) are mostly intended for configuration settings where the -first CMake run determines a suitable default value, which the user -can then override, by editing the cache with tools such as ccmake or -cmake-gui. Cache variables are stored in the CMake cache file, and -are persisted across CMake runs. - -Both types can exist at the same time with the same name but different -values. When ${FOO} is evaluated, CMake first looks for a normal -variable 'FOO' in scope and uses it if set. If and only if no normal -variable exists then it falls back to the cache variable 'FOO'. - -Some examples: - -The code 'set(FOO "x")' sets the normal variable 'FOO'. It does not -touch the cache, but it will hide any existing cache value 'FOO'. - -The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache, -ignoring any normal variable of the same name. If 'FOO' is in the -cache then nothing happens to either the normal variable or the cache -variable. If 'FOO' is not in the cache, then it is added to the -cache. - -Finally, whenever a cache variable is added or modified by a command, -CMake also *removes* the normal variable of the same name from the -current scope so that an immediately following evaluation of it will -expose the newly cached value. - -Normally projects should avoid using normal and cache variables of the -same name, as this interaction can be hard to follow. However, in -some situations it can be useful. One example (used by some -projects): - -A project has a subproject in its source tree. The child project has -its own CMakeLists.txt, which is included from the parent -CMakeLists.txt using add_subdirectory(). Now, if the parent and the -child project provide the same option (for example a compiler option), -the parent gets the first chance to add a user-editable option to the -cache. Normally, the child would then use the same value that the -parent uses. However, it may be necessary to hard-code the value for -the child project's option while still allowing the user to edit the -value used by the parent project. The parent project can achieve this -simply by setting a normal variable with the same name as the option -in a scope sufficient to hide the option's cache variable from the -child completely. The parent has already set the cache variable, so -the child's set(...CACHE...) will do nothing, and evaluating the -option variable will use the value from the normal variable, which -hides the cache variable. + set(ENV{<variable>} <value>...) + +Set the current process environment ``<variable>`` to the given value. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index 834013a..e485fce 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -7,9 +7,6 @@ Set a property of the directory. set_directory_properties(PROPERTIES prop1 value1 prop2 value2) -Set a property for the current directory and subdirectories. If the -property is not found, CMake will report an error. The properties -include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES, -INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES. -ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be cleaned as -a part of "make clean" stage. +Set a property for the current directory and subdirectories. See +:ref:`Directory Properties` for the list of properties known +to CMake. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index 8ea02a3..b4904e8 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -10,6 +10,6 @@ Source files can have properties that affect how they are built. [prop2 value2 [...]]) Set properties associated with source files using a key/value paired -list. See properties documentation for those known to CMake. -Unrecognized properties are ignored. Source file properties are -visible only to targets added in the same directory (CMakeLists.txt). +list. See :ref:`Source File Properties` for the list of properties known +to CMake. Source file properties are visible only to targets added +in the same directory (CMakeLists.txt). diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst index afac847..3efb165 100644 --- a/Help/command/set_tests_properties.rst +++ b/Help/command/set_tests_properties.rst @@ -8,29 +8,7 @@ Set a property of the tests. set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2) Set a property for the tests. If the test is not found, CMake -will report an error. Generator expressions will be expanded the same -as supported by the test's add_test call. The properties include: - -WILL_FAIL: If set to true, this will invert the pass/fail flag of the -test. - -PASS_REGULAR_EXPRESSION: If set, the test output will be checked -against the specified regular expressions and at least one of the -regular expressions has to match, otherwise the test will fail. - -:: - - Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok" - -FAIL_REGULAR_EXPRESSION: If set, if the output will match to one of -specified regular expressions, the test will fail. - -:: - - Example: FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed" - -Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect a list -of regular expressions. - -TIMEOUT: Setting this will limit the test runtime to the number of -seconds specified. +will report an error. +:manual:`Generator expressions <cmake-generator-expressions(7)>` will be +expanded the same as supported by the test's :command:`add_test` call. See +:ref:`Test Properties` for the list of properties known to CMake. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 3c9fe87..8bd3233 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -9,7 +9,7 @@ Add compile definitions to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify compile definitions to use when compiling a given <target. The +Specify compile definitions to use when compiling a given ``<target>``. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`Imported Target <Imported Targets>`. diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 29a8b41..b66a4ec 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -29,4 +29,4 @@ 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. +information on compile features and a list of supported compilers. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 3362c5d..73e01e7 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -20,8 +20,8 @@ alternative commands exist to add preprocessor definitions (:command:`target_compile_definitions` and :command:`add_definitions`) or 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_dir:`directory <COMPILE_OPTIONS>` and +:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 1d236ce..30ec2cb 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -55,5 +55,8 @@ installation prefix. For example: $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib ) +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index e6a82b6..d903d05 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -1,38 +1,113 @@ target_link_libraries --------------------- -Link a target to given libraries. +.. only:: html + + .. contents:: + +Specify libraries or flags to use when linking a given target and/or +its dependents. :ref:`Usage requirements <Target Usage Requirements>` +from linked library targets will be propagated. Usage requirements +of a target's dependencies affect compilation of its own sources. + +Overview +^^^^^^^^ + +This command has several signatures as detailed in subsections below. +All of them have the general form:: + + target_link_libraries(<target> ... <item>... ...) + +The named ``<target>`` must have been created in the current directory by +a command such as :command:`add_executable` or :command:`add_library`. +Repeated calls for the same ``<target>`` append items in the order called. +Each ``<item>`` may be: + +* **A library target name**: The generated link line will have the + full path to the linkable library file associated with the target. + The buildsystem will have a dependency to re-link ``<target>`` if + the library file changes. + + The named target must be created by :command:`add_library` within + the project or as an :ref:`IMPORTED library <Imported Targets>`. + If it is created within the project an ordering dependency will + automatically be added in the build system to make sure the named + library target is up-to-date before the ``<target>`` links. + + If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME` + target property set, CMake may ask the linker to search for + the library instead of using the full path + (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). + +* **A full path to a library file**: The generated link line will + normally preserve the full path to the file. The buildsystem will + have a dependency to re-link ``<target>`` if the library file changes. + + There are some cases where CMake may ask the linker to search for + the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such + as when a shared library is detected to have no ``SONAME`` field. + See policy :policy:`CMP0060` for discussion of another case. + + If the library file is in a Mac OSX framework, the ``Headers`` directory + of the framework will also be processed as a + :ref:`usage requirement <Target Usage Requirements>`. This has the same + effect as passing the framework directory as an include directory. + +* **A plain library name**: The generated link line will ask the linker + to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``). + +* **A link flag**: Item names starting with ``-``, but not ``-l`` or + ``-framework``, are treated as linker flags. Note that such flags will + be treated like any other library link item for purposes of transitive + dependencies, so they are generally safe to specify only as private link + items that will not propagate to dependents. + +* A ``debug``, ``optimized``, or ``general`` keyword immediately followed + by another ``<item>``. The item following such a keyword will be used + only for the corresponding build configuration. The ``debug`` keyword + corresponds to the ``Debug`` configuration (or to configurations named + in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). + The ``optimized`` keyword corresponds to all other configurations. The + ``general`` keyword corresponds to all configurations, and is purely + optional. Higher granularity may be achieved for per-configuration + rules by creating and linking to + :ref:`IMPORTED library targets <Imported Targets>`. + +Items containing ``::``, such as ``Foo::Bar``, are assumed to be +:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library +target names and will cause an error if no such target exists. +See policy :policy:`CMP0028`. + +Arguments to ``target_link_libraries`` may use "generator expressions" +with the syntax ``$<...>``. Note however, that generator expressions +will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-buildsystem(7)` manual for more on +defining buildsystem properties. + +Libraries for a Target and/or its Dependents +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + target_link_libraries(<target> + <PRIVATE|PUBLIC|INTERFACE> <item>... + [<PRIVATE|PUBLIC|INTERFACE> <item>...]...) + +The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to +specify both the link dependencies and the link interface in one command. +Libraries and targets following ``PUBLIC`` are linked to, and are made +part of the link interface. Libraries and targets following ``PRIVATE`` +are linked to, but are not made part of the link interface. Libraries +following ``INTERFACE`` are appended to the link interface and are not +used for linking ``<target>``. + +Libraries for both a Target and its Dependents +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - target_link_libraries(<target> [item1 [item2 [...]]] - [[debug|optimized|general] <item>] ...) - -Specify libraries or flags to use when linking a given target. The -named ``<target>`` must have been created in the current directory by a -command such as :command:`add_executable` or :command:`add_library`. The -remaining arguments specify library names or flags. Repeated calls for -the same ``<target>`` append items in the order called. - -If a library name matches that of another target in the project a -dependency will automatically be added in the build system to make sure -the library being linked is up-to-date before the target links. Item names -starting with ``-``, but not ``-l`` or ``-framework``, are treated as -linker flags. Note that such flags will be treated like any other library -link item for purposes of transitive dependencies, so they are generally -safe to specify only as private link items that will not propagate to -dependents of ``<target>``. - -A ``debug``, ``optimized``, or ``general`` keyword indicates that the -library immediately following it is to be used only for the -corresponding build configuration. The ``debug`` keyword corresponds to -the Debug configuration (or to configurations named in the -:prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). The -``optimized`` keyword corresponds to all other configurations. The -``general`` keyword corresponds to all configurations, and is purely -optional (assumed if omitted). Higher granularity may be achieved for -per-configuration rules by creating and linking to -:ref:`IMPORTED library targets <Imported Targets>`. + target_link_libraries(<target> <item>...) Library dependencies are transitive by default with this signature. When this target is linked into another target then the libraries @@ -45,40 +120,34 @@ by setting the property directly. When :policy:`CMP0022` is not set to of this command may set the property making any libraries linked exclusively by this signature private. -CMake will also propagate :ref:`usage requirements <Target Usage Requirements>` -from linked library targets. Usage requirements of dependencies affect -compilation of sources in the ``<target>``. - -.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` -.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt - -If an ``<item>`` is a library in a Mac OX framework, the ``Headers`` -directory of the framework will also be processed as a -:ref:`usage requirement <Target Usage Requirements>`. This has the same -effect as passing the framework directory as an include directory. - --------------------------------------------------------------------------- +Libraries for a Target and/or its Dependents (Legacy) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: target_link_libraries(<target> - <PRIVATE|PUBLIC|INTERFACE> <lib> ... - [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...]) + <LINK_PRIVATE|LINK_PUBLIC> <lib>... + [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...) -The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to -specify both the link dependencies and the link interface in one command. -Libraries and targets following ``PUBLIC`` are linked to, and are made -part of the link interface. Libraries and targets following ``PRIVATE`` -are linked to, but are not made part of the link interface. Libraries -following ``INTERFACE`` are appended to the link interface and are not -used for linking ``<target>``. +The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both +the link dependencies and the link interface in one command. + +This signature is for compatibility only. Prefer the ``PUBLIC`` or +``PRIVATE`` keywords instead. + +Libraries and targets following ``LINK_PUBLIC`` are linked to, and are +made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy +:policy:`CMP0022` is not ``NEW``, they are also made part of the +:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following +``LINK_PRIVATE`` are linked to, but are not made part of the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`). --------------------------------------------------------------------------- +Libraries for Dependents Only (Legacy) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - target_link_libraries(<target> LINK_INTERFACE_LIBRARIES - [[debug|optimized|general] <lib>] ...) + target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...) The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them @@ -102,28 +171,8 @@ is not ``NEW``, they are also appended to the ``general`` (or without any keyword) are treated as if specified for both ``debug`` and ``optimized``. --------------------------------------------------------------------------- - -:: - - target_link_libraries(<target> - <LINK_PRIVATE|LINK_PUBLIC> - [[debug|optimized|general] <lib>] ... - [<LINK_PRIVATE|LINK_PUBLIC> - [[debug|optimized|general] <lib>] ...]) - -The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both -the link dependencies and the link interface in one command. - -This signature is for compatibility only. Prefer the ``PUBLIC`` or -``PRIVATE`` keywords instead. - -Libraries and targets following ``LINK_PUBLIC`` are linked to, and are -made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy -:policy:`CMP0022` is not ``NEW``, they are also made part of the -:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following -``LINK_PRIVATE`` are linked to, but are not made part of the -:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`). +Cyclic Dependencies of Static Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The library dependency graph is normally acyclic (a DAG), but in the case of mutually-dependent ``STATIC`` libraries CMake allows the graph to @@ -142,14 +191,14 @@ For example, the code links ``main`` to ``A B A B``. While one repetition is usually sufficient, pathological object file and symbol arrangements can require -more. One may handle such cases by manually repeating the component in -the last ``target_link_libraries`` call. However, if two archives are -really so interdependent they should probably be combined into a single -archive. +more. One may handle such cases by using the +:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually +repeating the component in the last ``target_link_libraries`` call. +However, if two archives are really so interdependent they should probably +be combined into a single archive, perhaps by using :ref:`Object Libraries`. -Arguments to target_link_libraries may use "generator expressions" -with the syntax ``$<...>``. Note however, that generator expressions -will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. See the :manual:`cmake-buildsystem(7)` manual for more on -defining buildsystem properties. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 832240a..d6f148d 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -22,10 +22,6 @@ items will populate the :prop_tgt:`SOURCES` property of following arguments specify sources. Repeated calls for the same ``<target>`` append items in the order called. -Targets with :prop_tgt:`INTERFACE_SOURCES` may not be exported with the -:command:`export` or :command:`install(EXPORT)` commands. This limitation may be -lifted in a future version of CMake. - 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)` diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 43ee219..e3bd57d 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -73,7 +73,8 @@ When cross compiling, the executable compiled in the first step usually cannot be run on the build host. The ``try_run`` command checks the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in cross-compiling mode. If that is the case, it will still try to compile -the executable, but it will not try to run the executable. Instead it +the executable, but it will not try to run the executable unless the +:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable is set. Instead it will create cache variables which must be filled by the user or by presetting them in some CMake script file to the values the executable would have produced if it had been run on its actual target platform. diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst new file mode 100644 index 0000000..4d31690 --- /dev/null +++ b/Help/generator/Green Hills MULTI.rst @@ -0,0 +1,16 @@ +Green Hills MULTI +----------------- + +Generates Green Hills MULTI project files (experimental, work-in-progress). + +Customizations are available through the following cache variables: + +* ``GHS_BSP_NAME`` +* ``GHS_CUSTOMIZATION`` +* ``GHS_GPJ_MACROS`` +* ``GHS_OS_DIR`` + +.. note:: + This generator is deemed experimental as of CMake |release| + and is still a work in progress. Future versions of CMake + may make breaking changes as the generator matures. diff --git a/Help/generator/Ninja.rst b/Help/generator/Ninja.rst index 08f74fb..920abcb 100644 --- a/Help/generator/Ninja.rst +++ b/Help/generator/Ninja.rst @@ -1,7 +1,7 @@ Ninja ----- -Generates build.ninja files (experimental). +Generates build.ninja files. A build.ninja file is generated into the build tree. Recent versions of the ninja program can build the project through the "all" target. diff --git a/Help/generator/Visual Studio 6.rst b/Help/generator/Visual Studio 6.rst index d619354..855589c 100644 --- a/Help/generator/Visual Studio 6.rst +++ b/Help/generator/Visual Studio 6.rst @@ -1,4 +1,10 @@ Visual Studio 6 --------------- -Generates Visual Studio 6 project files. +Deprected. Generates Visual Studio 6 project files. + +.. note:: + This generator is deprecated and will be removed + in a future version of CMake. It will still be + possible to build with VS 6 tools using the + :generator:`NMake Makefiles` generator. diff --git a/Help/generator/Visual Studio 7.rst b/Help/generator/Visual Studio 7.rst index d0eb719..eb426f4 100644 --- a/Help/generator/Visual Studio 7.rst +++ b/Help/generator/Visual Studio 7.rst @@ -1,4 +1,10 @@ Visual Studio 7 --------------- -Generates Visual Studio .NET 2002 project files. +Deprected. Generates Visual Studio .NET 2002 project files. + +.. note:: + This generator is deprecated and will be removed + in a future version of CMake. It will still be + possible to build with VS 7.0 tools using the + :generator:`NMake Makefiles` generator. diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt index 33f7183..a54d728 100644 --- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt +++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt @@ -1,30 +1,18 @@ Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the -|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. -That would hard-code into installed packages the include directory paths -for dependencies **as found on the machine the package was made on**. +|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include +directories of dependencies. That would hard-code into installed packages +the include directory paths for dependencies +**as found on the machine the package was made on**. The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only -suitable for specifying the required include directories of the target itself, -not its dependencies. +suitable for specifying the required include directories for headers +provided with the target itself, not those provided by the transitive +dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target +property. Those dependencies should themselves be targets that specify +their own header locations in |INTERFACE_PROPERTY_LINK|. -That is, code like this is incorrect for targets which will be used to -generate :manual:`cmake-packages(7)`: - -.. code-block:: cmake - - target_include_directories(mylib INTERFACE - $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}> - ) - -Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>` -which have their own |INTERFACE_PROPERTY_LINK| populated -appropriately. Those :ref:`IMPORTED targets <Imported Targets>` may then be -used with the :command:`target_link_libraries` command for ``mylib``. - -That way, when a consumer uses the installed package, the -consumer will run the appropriate :command:`find_package` command to find -the dependencies on their own machine and populate the -:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See -:ref:`Creating Packages` for more. Note that many modules currently shipped -with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`. +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt index ceefa4d..46e84ac 100644 --- a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt +++ b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt @@ -1,23 +1,10 @@ Note that it is not advisable to populate the -|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies. -That would hard-code into installed packages the include directory paths +|INTERFACE_PROPERTY_LINK| of a target with absolute paths to dependencies. +That would hard-code into installed packages the library file paths for dependencies **as found on the machine the package was made on**. -That is, code like this is incorrect for targets which will be used to -generate :manual:`cmake-packages(7)`: - -.. code-block:: cmake - - target_link_libraries(mylib INTERFACE - ${Boost_LIBRARIES};${OtherDep_LIBRARIES} - ) - -Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>` -which have their own :prop_tgt:`IMPORTED_LOCATION` populated -appropriately. That way, when a consumer uses the installed package, the -consumer will run the appropriate :command:`find_package` command to find -the dependencies on their own machine and populate the -:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. See -:ref:`Creating Packages` for more. Note that many modules currently shipped -with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`. +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 363d0aa..4207db4 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -10,7 +10,7 @@ containing SET commands that use the CACHE option, not a cache-format file. -``-D <var>:<type>=<value>`` +``-D <var>:<type>=<value>, -D <var>=<value>`` Create a cmake cache entry. When cmake is first run in an empty build tree, it creates a @@ -19,6 +19,17 @@ takes priority over the project's default value. The option may be repeated for as many cache entries as desired. + If the ``:<type>`` portion is given it must be one of the types + specified by the :command:`set` command documentation for its + ``CACHE`` signature. + If the ``:<type>`` portion is omitted the entry will be created + with no type if it does not exist with a type already. If a + command in the project sets the type to ``PATH`` or ``FILEPATH`` + then the ``<value>`` will be converted to an absolute path. + + This option may also be given as a single argument: + ``-D<var>:<type>=<value>`` or ``-D<var>=<value>``. + ``-U <globbing_expr>`` Remove matching entries from CMake cache. @@ -35,7 +46,7 @@ CMake may support multiple native build systems on certain platforms. A generator is responsible for generating a particular build system. Possible generator names are specified in the - Generators section. + :manual:`cmake-generators(7)` manual. ``-T <toolset-name>`` Specify toolset name if supported by generator. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 002f2c2..c456590 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -143,6 +143,11 @@ use particular :prop_tgt:`COMPILE_OPTIONS` or the properties must be **requirements**, not merely recommendations or convenience. +See the :ref:`Creating Relocatable Packages` section of the +:manual:`cmake-packages(7)` manual for discussion of additional care +that must be taken when specifying usage requirements while creating +packages for redistribution. + Target Properties ----------------- @@ -690,8 +695,10 @@ edge of linking ``exe1`` is determined by the same :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case. -Output Files ------------- +.. _`Output Artifacts`: + +Output Artifacts +---------------- The buildsystem targets created by the :command:`add_library` and :command:`add_executable` commands create rules to create binary outputs. @@ -703,6 +710,71 @@ name and location of generated binaries. These expressions do not work for ``OBJECT`` libraries however, as there is no single file generated by such libraries which is relevant to the expressions. +There are three kinds of output artifacts that may be build by targets +as detailed in the following sections. Their classification differs +between DLL platforms and non-DLL platforms. All Windows-based +systems including Cygwin are DLL platforms. + +.. _`Runtime Output Artifacts`: + +Runtime Output Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^ + +A *runtime* output artifact of a buildsystem target may be: + +* The executable file (e.g. ``.exe``) of an executable target + created by the :command:`add_executable` command. + +* On DLL platforms: the executable file (e.g. ``.dll``) of a shared + library target created by the :command:`add_library` command + with the ``SHARED`` option. + +The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME` +target properties may be used to control runtime output artifact locations +and names in the build tree. + +.. _`Library Output Artifacts`: + +Library Output Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^ + +A *library* output artifact of a buildsystem target may be: + +* The loadable module file (e.g. ``.dll`` or ``.so``) of a module + library target created by the :command:`add_library` command + with the ``MODULE`` option. + +* On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``) + of a shared shared library target created by the :command:`add_library` + command with the ``SHARED`` option. + +The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME` +target properties may be used to control library output artifact locations +and names in the build tree. + +.. _`Archive Output Artifacts`: + +Archive Output Artifacts +^^^^^^^^^^^^^^^^^^^^^^^^ + +An *archive* output artifact of a buildsystem target may be: + +* The static library file (e.g. ``.lib`` or ``.a``) of a static + library target created by the :command:`add_library` command + with the ``STATIC`` option. + +* On DLL platforms: the import library file (e.g. ``.lib``) of a shared + library target created by the :command:`add_library` command + with the ``SHARED`` option. + +* On DLL platforms: the import library file (e.g. ``.lib``) of an + executable target created by the :command:`add_executable` command + when its :prop_tgt:`ENABLE_EXPORTS` target property is set. + +The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` +target properties may be used to control archive output artifact locations +and names in the build tree. + Directory-Scoped Commands ------------------------- @@ -814,9 +886,9 @@ It may specify usage requirements such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`, :prop_tgt:`INTERFACE_COMPILE_OPTIONS`, -:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, :prop_tgt:`INTERFACE_SOURCES`, -:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. +and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`. Only the ``INTERFACE`` modes of the :command:`target_include_directories`, :command:`target_compile_definitions`, :command:`target_compile_options`, :command:`target_sources`, and :command:`target_link_libraries` commands diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 7a6c249..caf5bac 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -278,7 +278,7 @@ properties: add_library(foo INTERFACE) set(with_variadics ${CMAKE_CURRENT_SOURCE_DIR}/with_variadics) set(no_variadics ${CMAKE_CURRENT_SOURCE_DIR}/no_variadics) - target_link_libraries(foo + target_include_directories(foo INTERFACE "$<$<COMPILE_FEATURES:cxx_variadic_templates>:${with_variadics}>" "$<$<NOT:$<COMPILE_FEATURES:cxx_variadic_templates>>:${no_variadics}>" @@ -295,3 +295,17 @@ the feature-appropriate include directory add_executable(consumer_no consumer_no.cpp) target_link_libraries(consumer_no foo) + +Supported Compilers +=================== + +CMake is currently aware of the :prop_tgt:`language standards <CXX_STANDARD>` +and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from +the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2. +* ``Clang``: Clang compiler versions 2.9 through 3.4. +* ``GNU``: GNU compiler versions 4.4 through 5.0. +* ``MSVC``: Microsoft Visual Studio versions 2010 through 2015. +* ``SunPro``: Oracle SolarisStudio version 12.4. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index e18250c..ab74140 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -28,34 +28,6 @@ Some implementations have a ``std::auto_ptr`` which can not be used as a return value from a function. ``std::auto_ptr`` may not be used. Use ``cmsys::auto_ptr`` instead. -Template Parameter Defaults ---------------------------- - -On ancient compilers, C++ template must use template parameters in function -arguments. If no parameter of that type is needed, the common workaround is -to add a defaulted pointer to the type to the templated function. However, -this does not work with other ancient compilers: - -.. code-block:: c++ - - template<typename PropertyType> - PropertyType getTypedProperty(cmTarget* tgt, const char* prop, - PropertyType* = 0) // Wrong - { - - } - -.. code-block:: c++ - - template<typename PropertyType> - PropertyType getTypedProperty(cmTarget* tgt, const char* prop, - PropertyType*) // Ok - { - - } - -and invoke it with the value ``0`` explicitly in all cases. - size_t ------ @@ -633,6 +605,7 @@ 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`: Find Modules ------------ diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c47a7c4..189c3ef 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -40,10 +40,6 @@ otherwise expands to nothing. Available logical expressions are: -``$<0:...>`` - Empty string (ignores ``...``) -``$<1:...>`` - Content of ``...`` ``$<BOOL:...>`` ``1`` if the ``...`` is true, else ``0`` ``$<AND:?[,?]...>`` @@ -92,7 +88,47 @@ Available logical expressions are: 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. + compile features and a list of supported compilers. +``$<COMPILE_LANGUAGE:lang>`` + ``1`` when the language used for compilation unit matches ``lang``, + otherwise ``0``. This expression used to specify compile options for + source files of a particular language in a target. For example, to specify + the use of the ``-fno-exceptions`` compile option (compiler id checks + elided): + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp) + target_compile_options(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> + ) + + This generator expression has limited use because it is not possible to + use it with the Visual Studio generators. Portable buildsystems would + not use this expression, and would create separate libraries for each + source file language instead: + + .. code-block:: cmake + + add_library(myapp_c foo.c) + add_library(myapp_cxx foo.c) + target_compile_options(myapp_cxx PUBLIC -fno-exceptions) + add_executable(myapp main.cpp) + target_link_libraries(myapp myapp_c myapp_cxx) + + The ``Makefile`` and ``Ninja`` based generators can also use this + expression to specify compile-language specific compile definitions + and include directories: + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> + ) + target_include_directories(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> + ) Informational Expressions ========================= @@ -174,6 +210,10 @@ Available informational expressions are: ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)` and empty otherwise. +``$<COMPILE_LANGUAGE>`` + The compile language of source files when evaluating compile options. See + the unary version for notes about portability of this generator + expression. Output Expressions ================== @@ -197,6 +237,10 @@ where ``${prop}`` refers to a helper variable:: Available output expressions are: +``$<0:...>`` + Empty string (ignores ``...``) +``$<1:...>`` + Content of ``...`` ``$<JOIN:list,...>`` Joins the list with the content of ``...`` ``$<ANGLE-R>`` diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index bda7eef..cde8de8 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -34,6 +34,11 @@ These generators support command-line build tools. In order to use them, one must launch CMake from a command-line prompt whose environment is already configured for the chosen compiler and build tool. +.. _`Makefile Generators`: + +Makefile Generators +^^^^^^^^^^^^^^^^^^^ + .. toctree:: :maxdepth: 1 @@ -42,10 +47,17 @@ already configured for the chosen compiler and build tool. /generator/MinGW Makefiles /generator/NMake Makefiles /generator/NMake Makefiles JOM - /generator/Ninja /generator/Unix Makefiles /generator/Watcom WMake +Ninja Generator +^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/Ninja + IDE Build Tool Generators ------------------------- @@ -53,6 +65,11 @@ These generators support Integrated Development Environment (IDE) project files. Since the IDEs configure their own environment one may launch CMake from any environment. +.. _`Visual Studio Generators`: + +Visual Studio Generators +^^^^^^^^^^^^^^^^^^^^^^^^ + .. toctree:: :maxdepth: 1 @@ -65,6 +82,14 @@ one may launch CMake from any environment. /generator/Visual Studio 11 2012 /generator/Visual Studio 12 2013 /generator/Visual Studio 14 2015 + +Other Generators +^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + /generator/Green Hills MULTI /generator/Xcode Extra Generators diff --git a/Help/manual/cmake-language.7.rst b/Help/manual/cmake-language.7.rst index 3e0297c..41542c9 100644 --- a/Help/manual/cmake-language.7.rst +++ b/Help/manual/cmake-language.7.rst @@ -485,6 +485,8 @@ The :command:`macro`/:command:`endmacro`, and :command:`function`/:command:`endfunction` commands delimit code blocks to be recorded for later invocation as commands. +.. _`CMake Language Variables`: + Variables ========= @@ -538,6 +540,8 @@ The :manual:`cmake-variables(7)` manual documents many variables that are provided by CMake or have meaning to CMake when set by project code. +.. _`CMake Language Lists`: + Lists ===== diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index db56010..c9219d5 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -22,6 +22,7 @@ All Modules /module/CheckCXXSourceCompiles /module/CheckCXXSourceRuns /module/CheckCXXSymbolExists + /module/CheckFortranCompilerFlag /module/CheckFortranFunctionExists /module/CheckFortranSourceCompiles /module/CheckFunctionExists @@ -126,7 +127,6 @@ All Modules /module/FindJava /module/FindJNI /module/FindJPEG - /module/FindJsonCpp /module/FindKDE3 /module/FindKDE4 /module/FindLAPACK @@ -212,6 +212,7 @@ All Modules /module/FindWish /module/FindwxWidgets /module/FindwxWindows + /module/FindXCTest /module/FindXercesC /module/FindX11 /module/FindXMLRPC diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 3367ba4..b9073a5 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -373,38 +373,6 @@ attempt to use version 3 together with version 4. Packages can choose to employ such a pattern if different major versions of the package are designed to be incompatible. -Note that it is not advisable to populate any properties which may contain -paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and -:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevnt to dependencies. -That would hard-code into installed packages the include directory or library -paths for dependencies **as found on the machine the package was made on**. - -That is, code like this is incorrect for targets which will be used to -generate config file packages: - -.. code-block:: cmake - - target_link_libraries(ClimbingStats INTERFACE - ${Boost_LIBRARIES};${OtherDep_LIBRARIES}> - ) - target_include_directories(ClimbingStats INTERFACE - $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}> - ) - -Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>` -which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and -:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those -:ref:`IMPORTED targets <Imported Targets>` may then be -used with the :command:`target_link_libraries` command for ``ClimbingStats``. - -That way, when a consumer uses the installed package, the -consumer will run the appropriate :command:`find_package` command (via the -find_dependency macro described below) to find -the dependencies on their own machine and populate the -:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that -many modules currently shipped with CMake do not currently provide -:ref:`IMPORTED targets <Imported Targets>`. - A ``NAMESPACE`` with double-colons is specified when exporting the targets for installation. This convention of double-colons gives CMake a hint that the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams @@ -418,6 +386,9 @@ directory in the :variable:`CMAKE_INSTALL_PREFIX`. When the ``IMPORTED`` target is used by downsteam, it automatically consumes the entries from that property. +Creating a Package Configuration File +------------------------------------- + In this case, the ``ClimbingStatsConfig.cmake`` file could be as simple as: .. code-block:: cmake @@ -429,44 +400,6 @@ should be provided by the ``ClimbingStats`` package, they should be in a separate file which is installed to the same location as the ``ClimbingStatsConfig.cmake`` file, and included from there. -Packages created by :command:`install(EXPORT)` are designed to be relocatable, -using paths relative to the location of the package itself. When defining -the interface of a target for ``EXPORT``, keep in mind that the include -directories should be specified as relative paths which are relative to the -:variable:`CMAKE_INSTALL_PREFIX`: - -.. code-block:: cmake - - target_include_directories(tgt INTERFACE - # Wrong, not relocatable: - $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName> - ) - - target_include_directories(tgt INTERFACE - # Ok, relocatable: - $<INSTALL_INTERFACE:include/TgtName> - ) - -The ``$<INSTALL_PREFIX>`` -:manual:`generator expression <cmake-generator-expressions(7)>` may be used as -a placeholder for the install prefix without resulting in a non-relocatable -package. This is necessary if complex generator expressions are used: - -.. code-block:: cmake - - target_include_directories(tgt INTERFACE - # Ok, relocatable: - $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>> - ) - -The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets -definition file which is specific to the build-tree, and is not relocatable. -This can similiarly be used with a suitable package configuration file and -package version file to define a package for the build tree which may be used -without installation. Consumers of the build tree can simply ensure that the -:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the -``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache. - This can also be extended to cover dependencies: .. code-block:: cmake @@ -526,6 +459,111 @@ could not be found because an invalid component was specified. This message variable can be set for any case where the ``_FOUND`` variable is set to ``False``, and will be displayed to the user. +Creating a Package Configuration File for the Build Tree +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :command:`export(EXPORT)` command creates an :prop_tgt:`IMPORTED` targets +definition file which is specific to the build-tree, and is not relocatable. +This can similiarly be used with a suitable package configuration file and +package version file to define a package for the build tree which may be used +without installation. Consumers of the build tree can simply ensure that the +:variable:`CMAKE_PREFIX_PATH` contains the build directory, or set the +``ClimbingStats_DIR`` to ``<build_dir>/ClimbingStats`` in the cache. + +.. _`Creating Relocatable Packages`: + +Creating Relocatable Packages +----------------------------- + +A relocatable package must not reference absolute paths of files on +the machine where the package is built that will not exist on the +machines where the package may be installed. + +Packages created by :command:`install(EXPORT)` are designed to be relocatable, +using paths relative to the location of the package itself. When defining +the interface of a target for ``EXPORT``, keep in mind that the include +directories should be specified as relative paths which are relative to the +:variable:`CMAKE_INSTALL_PREFIX`: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Wrong, not relocatable: + $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName> + ) + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $<INSTALL_INTERFACE:include/TgtName> + ) + +The ``$<INSTALL_PREFIX>`` +:manual:`generator expression <cmake-generator-expressions(7)>` may be used as +a placeholder for the install prefix without resulting in a non-relocatable +package. This is necessary if complex generator expressions are used: + +.. code-block:: cmake + + target_include_directories(tgt INTERFACE + # Ok, relocatable: + $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>> + ) + +This also applies to paths referencing external dependencies. +It is not advisable to populate any properties which may contain +paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and +:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevant to dependencies. +For example, this code may not work well for a relocatable package: + +.. code-block:: cmake + + target_link_libraries(ClimbingStats INTERFACE + ${Foo_LIBRARIES} ${Bar_LIBRARIES} + ) + target_include_directories(ClimbingStats INTERFACE + "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>" + ) + +The referenced variables may contain the absolute paths to libraries +and include directories **as found on the machine the package was made on**. +This would create a package with hard-coded paths to dependencies and not +suitable for relocation. + +Ideally such dependencies should be used through their own +:ref:`IMPORTED targets <Imported Targets>` that have their own +:prop_tgt:`IMPORTED_LOCATION` and usage requirement properties +such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` populated +appropriately. Those imported targets may then be used with +the :command:`target_link_libraries` command for ``ClimbingStats``: + +.. code-block:: cmake + + target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar) + +With this approach the package references its external dependencies +only through the names of :ref:`IMPORTED targets <Imported Targets>`. +When a consumer uses the installed package, the consumer will run the +appropriate :command:`find_package` commands (via the ``find_dependency`` +macro described above) to find the dependencies and populate the +imported targets with appropriate paths on their own machine. + +Unfortunately many :manual:`modules <cmake-modules(7)>` shipped with +CMake do not yet provide :ref:`IMPORTED targets <Imported Targets>` +because their development pre-dated this approach. This may improve +incrementally over time. Workarounds to create relocatable packages +using such modules include: + +* When building the package, specify each ``Foo_LIBRARY`` cache + entry as just a library name, e.g. ``-DFoo_LIBRARY=foo``. This + tells the corresponding find module to populate the ``Foo_LIBRARIES`` + with just ``foo`` to ask the linker to search for the library + instead of hard-coding a path. + +* Or, after installing the package content but before creating the + package installation binary for redistribution, manually replace + the absolute paths with placeholders for substitution by the + installation tool when the package is installed. + .. _`Package Registry`: Package Registry diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 96f39e6..c5970bb 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -114,3 +114,10 @@ All Policies /policy/CMP0054 /policy/CMP0055 /policy/CMP0056 + /policy/CMP0057 + /policy/CMP0058 + /policy/CMP0059 + /policy/CMP0060 + /policy/CMP0061 + /policy/CMP0062 + /policy/CMP0063 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 25f989f..615254e 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -7,6 +7,8 @@ cmake-properties(7) .. contents:: +.. _`Global Properties`: + Properties of Global Scope ========================== @@ -41,6 +43,8 @@ Properties of Global Scope /prop_gbl/TARGET_SUPPORTS_SHARED_LIBS /prop_gbl/USE_FOLDERS +.. _`Directory Properties`: + Properties on Directories ========================= @@ -72,6 +76,8 @@ Properties on Directories /prop_dir/VS_GLOBAL_SECTION_POST_section /prop_dir/VS_GLOBAL_SECTION_PRE_section +.. _`Target Properties`: + Properties on Targets ===================== @@ -113,6 +119,7 @@ Properties on Targets /prop_tgt/COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /prop_tgt/CONFIG_OUTPUT_NAME /prop_tgt/CONFIG_POSTFIX + /prop_tgt/CROSSCOMPILING_EMULATOR /prop_tgt/CXX_EXTENSIONS /prop_tgt/CXX_STANDARD /prop_tgt/CXX_STANDARD_REQUIRED @@ -170,6 +177,7 @@ Properties on Targets /prop_tgt/JOB_POOL_COMPILE /prop_tgt/JOB_POOL_LINK /prop_tgt/LABELS + /prop_tgt/LANG_INCLUDE_WHAT_YOU_USE /prop_tgt/LANG_VISIBILITY_PRESET /prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG /prop_tgt/LIBRARY_OUTPUT_DIRECTORY @@ -243,6 +251,9 @@ Properties on Targets /prop_tgt/VS_WINRT_REFERENCES /prop_tgt/WIN32_EXECUTABLE /prop_tgt/XCODE_ATTRIBUTE_an-attribute + /prop_tgt/XCTEST + +.. _`Test Properties`: Properties on Tests =================== @@ -268,6 +279,8 @@ Properties on Tests /prop_test/WILL_FAIL /prop_test/WORKING_DIRECTORY +.. _`Source File Properties`: + Properties on Source Files ========================== @@ -297,10 +310,13 @@ Properties on Source Files /prop_sf/VS_SHADER_FLAGS /prop_sf/VS_SHADER_MODEL /prop_sf/VS_SHADER_TYPE + /prop_sf/VS_XAML_TYPE /prop_sf/WRAP_EXCLUDE /prop_sf/XCODE_EXPLICIT_FILE_TYPE /prop_sf/XCODE_LAST_KNOWN_FILE_TYPE +.. _`Cache Entry Properties`: + Properties on Cache Entries =========================== @@ -314,19 +330,24 @@ Properties on Cache Entries /prop_cache/TYPE /prop_cache/VALUE +.. _`Installed File Properties`: + Properties on Installed Files ============================= .. toctree:: :maxdepth: 1 + /prop_inst/CPACK_DESKTOP_SHORTCUTS.rst /prop_inst/CPACK_NEVER_OVERWRITE.rst /prop_inst/CPACK_PERMANENT.rst + /prop_inst/CPACK_START_MENU_SHORTCUTS.rst + /prop_inst/CPACK_STARTUP_SHORTCUTS.rst /prop_inst/CPACK_WIX_ACL.rst Deprecated Properties on Directories -===================================== +==================================== .. toctree:: :maxdepth: 1 diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index c342dbe..bd02f8b 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -25,6 +25,7 @@ Variables that Provide Information /variable/CMAKE_CFG_INTDIR /variable/CMAKE_COMMAND /variable/CMAKE_CROSSCOMPILING + /variable/CMAKE_CROSSCOMPILING_EMULATOR /variable/CMAKE_CTEST_COMMAND /variable/CMAKE_CURRENT_BINARY_DIR /variable/CMAKE_CURRENT_LIST_DIR @@ -181,6 +182,7 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN /variable/ENV + /variable/GHS-MULTI /variable/MINGW /variable/MSVC10 /variable/MSVC11 @@ -211,6 +213,7 @@ Variables that Control the Build /variable/CMAKE_ANDROID_API_MIN /variable/CMAKE_ANDROID_GUI /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY + /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTOMOC /variable/CMAKE_AUTORCC @@ -232,8 +235,10 @@ Variables that Control the Build /variable/CMAKE_INSTALL_NAME_DIR /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH + /variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE /variable/CMAKE_LANG_VISIBILITY_PRESET /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY + /variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_LIBRARY_PATH_FLAG /variable/CMAKE_LINK_DEF_FILE_FLAG /variable/CMAKE_LINK_DEPENDS_NO_SHARED @@ -254,6 +259,7 @@ Variables that Control the Build /variable/CMAKE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY + /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SKIP_BUILD_RPATH @@ -263,6 +269,7 @@ Variables that Control the Build /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_USE_RELATIVE_PATHS /variable/CMAKE_VISIBILITY_INLINES_HIDDEN + /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD /variable/CMAKE_WIN32_EXECUTABLE /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute /variable/EXECUTABLE_OUTPUT_PATH @@ -306,6 +313,10 @@ Variables for Languages /variable/CMAKE_LANG_FLAGS_RELEASE /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE + /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index da41bbb..4bd5a5e 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -9,7 +9,7 @@ Synopsis .. parsed-literal:: cmake [<options>] (<path-to-source> | <path-to-existing-build>) - cmake [(-D<var>=<value>)...] -P <cmake-script-file> + cmake [(-D <var>=<value>)...] -P <cmake-script-file> cmake --build <dir> [<options>] [-- <build-tool-options>...] cmake -E <command> [<options>...] cmake --find-package <options>... @@ -215,6 +215,10 @@ Available commands are: names start in ``-``. ``--mtime=<date>`` Specify modification time recorded in tarball entries. + ``--format=<format>`` + Specify the format of the archive to be created. + Supported formats are: ``7zip``, ``gnutar``, ``pax``, + ``paxr`` (restricted pax, default), and ``zip``. ``time <command> [<args>...]`` Run command and return elapsed time. diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst index cc132c2..c91321b 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -48,7 +48,9 @@ Options useful for debugging dashboard problems. ``--output-on-failure`` - Output anything outputted by the test program if the test should fail. This option can also be enabled by setting the environment variable CTEST_OUTPUT_ON_FAILURE + Output anything outputted by the test program if the test should fail. + This option can also be enabled by setting the environment variable + ``CTEST_OUTPUT_ON_FAILURE``. ``-F`` Enable failover. @@ -62,7 +64,7 @@ Options This option tells ctest to run the tests in parallel using given number of jobs. This option can also be set by setting the - environment variable CTEST_PARALLEL_LEVEL. + environment variable ``CTEST_PARALLEL_LEVEL``. ``-Q,--quiet`` Make ctest quiet. @@ -194,6 +196,11 @@ Options subsequent calls to ctest with the --rerun-failed option will run the set of tests that most recently failed (if any). +``--repeat-until-fail <n>`` + Require each test to run ``<n>`` times without failing in order to pass. + + This is useful in finding sporadic failures in test cases. + ``--max-width <width>`` Set the max width for a test name to output @@ -365,6 +372,8 @@ Options .. include:: OPTIONS_HELP.txt +.. _`Dashboard Client`: + Dashboard Client ================ @@ -568,7 +577,7 @@ Configuration settings to specify the version control tool include: * :module:`CTest` module variable: ``GITCOMMAND`` ``GITUpdateCustom`` - Specify a semicolon-separated list of custom command lines to run + Specify a custom command line (as a semicolon-separated list) to run in the source tree (Git work tree) to update it instead of running the ``GITCommand``. @@ -612,7 +621,7 @@ Configuration settings to specify the version control tool include: * :module:`CTest` module variable: ``CTEST_P4_OPTIONS`` ``P4UpdateCustom`` - Specify a semicolon-separated list of custom command lines to run + Specify a custom command line (as a semicolon-separated list) to run in the source tree (Perforce tree) to update it instead of running the ``P4Command``. @@ -742,8 +751,9 @@ Configuration settings include: 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 + For build trees generated by CMake using one of the + :ref:`Makefile Generators` 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 diff --git a/Help/module/CheckFortranCompilerFlag.rst b/Help/module/CheckFortranCompilerFlag.rst new file mode 100644 index 0000000..58bf6ec --- /dev/null +++ b/Help/module/CheckFortranCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFortranCompilerFlag.cmake diff --git a/Help/module/FindJsonCpp.rst b/Help/module/FindJsonCpp.rst deleted file mode 100644 index ba87ece..0000000 --- a/Help/module/FindJsonCpp.rst +++ /dev/null @@ -1 +0,0 @@ -.. cmake-module:: ../../Modules/FindJsonCpp.cmake diff --git a/Help/module/FindXCTest.rst b/Help/module/FindXCTest.rst new file mode 100644 index 0000000..ff6273c --- /dev/null +++ b/Help/module/FindXCTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/FindXCTest.cmake diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst index 177b655..4889249 100644 --- a/Help/policy/CMP0026.rst +++ b/Help/policy/CMP0026.rst @@ -1,7 +1,7 @@ CMP0026 ------- -Disallow use of the LOCATION target property. +Disallow use of the LOCATION property for build targets. CMake 2.8.12 and lower allowed reading the LOCATION target property (and configuration-specific variants) to diff --git a/Help/policy/CMP0054.rst b/Help/policy/CMP0054.rst index 39f0c40..3754fda 100644 --- a/Help/policy/CMP0054.rst +++ b/Help/policy/CMP0054.rst @@ -16,29 +16,33 @@ Given the following partial example: :: - set(MONKEY 1) - set(ANIMAL MONKEY) + set(A E) + set(E "") - if("${ANIMAL}" STREQUAL "MONKEY") + if("${A}" STREQUAL "") + message("Result is TRUE before CMake 3.1 or when CMP0054 is OLD") + else() + message("Result is FALSE in CMake 3.1 and above if CMP0054 is NEW") + endif() After explicit expansion of variables this gives: :: - if("MONKEY" STREQUAL "MONKEY") + if("E" STREQUAL "") With the policy set to ``OLD`` implicit expansion reduces this semantically to: :: - if("1" STREQUAL "1") + if("" STREQUAL "") With the policy set to ``NEW`` the quoted arguments will not be further dereferenced: :: - if("MONKEY" STREQUAL "MONKEY") + if("E" STREQUAL "") This policy was introduced in CMake version 3.1. CMake version |release| warns when the policy is not set and uses diff --git a/Help/policy/CMP0057.rst b/Help/policy/CMP0057.rst new file mode 100644 index 0000000..1298a16 --- /dev/null +++ b/Help/policy/CMP0057.rst @@ -0,0 +1,14 @@ +CMP0057 +------- + +Support new :command:`if` IN_LIST operator. + +CMake 3.3 adds support for the new IN_LIST operator. + +The ``OLD`` behavior for this policy is to ignore the IN_LIST operator. +The ``NEW`` behavior is to interpret the IN_LIST operator. + +This policy was introduced in CMake version 3.3. +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/CMP0058.rst b/Help/policy/CMP0058.rst new file mode 100644 index 0000000..0f20383 --- /dev/null +++ b/Help/policy/CMP0058.rst @@ -0,0 +1,108 @@ +CMP0058 +------- + +Ninja requires custom command byproducts to be explicit. + +When an intermediate file generated during the build is consumed +by an expensive operation or a large tree of dependents, one may +reduce the work needed for an incremental rebuild by updating the +file timestamp only when its content changes. With this approach +the generation rule must have a separate output file that is always +updated with a new timestamp that is newer than any dependencies of +the rule so that the build tool re-runs the rule only when the input +changes. We refer to the separate output file as a rule's *witness* +and the generated file as a rule's *byproduct*. + +Byproducts may not be listed as outputs because their timestamps are +allowed to be older than the inputs. No build tools (like ``make``) +that existed when CMake was designed have a way to express byproducts. +Therefore CMake versions prior to 3.2 had no way to specify them. +Projects typically left byproducts undeclared in the rules that +generate them. For example: + +.. code-block:: cmake + + add_custom_command( + OUTPUT witness.txt + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + byproduct.txt # timestamp may not change + COMMAND ${CMAKE_COMMAND} -E touch witness.txt + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + ) + add_custom_target(Provider DEPENDS witness.txt) + add_custom_command( + OUTPUT generated.c + COMMAND expensive-task -i byproduct.txt -o generated.c + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt + ) + add_library(Consumer generated.c) + add_dependencies(Consumer Provider) + +This works well for all generators except :generator:`Ninja`. +The Ninja build tool sees a rule listing ``byproduct.txt`` +as a dependency and no rule listing it as an output. Ninja then +complains that there is no way to satisfy the dependency and +stops building even though there are order-only dependencies +that ensure ``byproduct.txt`` will exist before its consumers +need it. See discussion of this problem in `Ninja Issue 760`_ +for further details on why Ninja works this way. + +.. _`Ninja Issue 760`: https://github.com/martine/ninja/issues/760 + +Instead of leaving byproducts undeclared in the rules that generate +them, Ninja expects byproducts to be listed along with other outputs. +Such rules may be marked with a ``restat`` option that tells Ninja +to check the timestamps of outputs after the rules run. This +prevents byproducts whose timestamps do not change from causing +their dependents to re-build unnecessarily. + +Since the above approach does not tell CMake what custom command +generates ``byproduct.txt``, the Ninja generator does not have +enough information to add the byproduct as an output of any rule. +CMake 2.8.12 and above work around this problem and allow projects +using the above approach to build by generating ``phony`` build +rules to tell Ninja to tolerate such missing files. However, this +workaround prevents Ninja from diagnosing a dependency that is +really missing. It also works poorly in in-source builds where +every custom command dependency, even on source files, needs to +be treated this way because CMake does not have enough information +to know which files are generated as byproducts of custom commands. + +CMake 3.2 introduced the ``BYPRODUCTS`` option to the +:command:`add_custom_command` and :command:`add_custom_target` +commands. This option allows byproducts to be specified explicitly: + +.. code-block:: cmake + + add_custom_command( + OUTPUT witness.txt + BYPRODUCTS byproduct.txt # explicit byproduct specification + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + byproduct.txt # timestamp may not change + ... + +The ``BYPRODUCTS`` option is used by the :generator:`Ninja` generator +to list byproducts among the outputs of the custom commands that +generate them, and is ignored by other generators. + +CMake 3.3 and above prefer to require projects to specify custom +command byproducts explicitly so that it can avoid using the +``phony`` rule workaround altogether. Policy ``CMP0058`` was +introduced to provide compatibility with existing projects that +still need the workaround. + +This policy has no effect on generators other than :generator:`Ninja`. +The ``OLD`` behavior for this policy is to generate Ninja ``phony`` +rules for unknown dependencies in the build tree. The ``NEW`` +behavior for this policy is to not generate these and instead +require projects to specify custom command ``BYPRODUCTS`` explicitly. + +This policy was introduced in CMake version 3.3. +CMake version |release| warns when it sees unknown dependencies in +out-of-source build trees if the policy is not set and then uses +``OLD`` behavior. Use the :command:`cmake_policy` command to set +the policy to ``OLD`` or ``NEW`` explicitly. The policy setting +must be in scope at the end of the top-level ``CMakeLists.txt`` +file of the project and has global effect. diff --git a/Help/policy/CMP0059.rst b/Help/policy/CMP0059.rst new file mode 100644 index 0000000..e40f450 --- /dev/null +++ b/Help/policy/CMP0059.rst @@ -0,0 +1,17 @@ +CMP0059 +------- + +Don't treat ``DEFINITIONS`` as a built-in directory property. + +CMake 3.3 and above no longer make a list of definitions available through +the :prop_dir:`DEFINITIONS` directory property. The +:prop_dir:`COMPILE_DEFINITIONS` directory property may be used instead. + +The ``OLD`` behavior for this policy is to provide the list of flags given +so far to the :command:`add_definitions` command. The ``NEW`` behavior is +to behave as a normal user-defined directory property. + +This policy was introduced in CMake version 3.3. +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/CMP0060.rst b/Help/policy/CMP0060.rst new file mode 100644 index 0000000..cc37b1b --- /dev/null +++ b/Help/policy/CMP0060.rst @@ -0,0 +1,63 @@ +CMP0060 +------- + +Link libraries by full path even in implicit directories. + +Policy :policy:`CMP0003` was introduced with the intention of always +linking library files by full path when a full path is given to the +:command:`target_link_libraries` command. However, on some platforms +(e.g. HP-UX) the compiler front-end adds alternative library search paths +for the current architecture (e.g. ``/usr/lib/<arch>`` has alternatives +to libraries in ``/usr/lib`` for the current architecture). +On such platforms the :command:`find_library` may find a library such as +``/usr/lib/libfoo.so`` that does not belong to the current architecture. + +Prior to policy :policy:`CMP0003` projects would still build in such +cases because the incorrect library path would be converted to ``-lfoo`` +on the link line and the linker would find the proper library in the +arch-specific search path provided by the compiler front-end implicitly. +At the time we chose to remain compatible with such projects by always +converting library files found in implicit link directories to ``-lfoo`` +flags to ask the linker to search for them. This approach allowed existing +projects to continue to build while still linking to libraries outside +implicit link directories via full path (such as those in the build tree). + +CMake does allow projects to override this behavior by using an +:ref:`IMPORTED library target <Imported Targets>` with its +:prop_tgt:`IMPORTED_LOCATION` property set to the desired full path to +a library file. In fact, many :ref:`Find Modules` are learning to provide +:ref:`Imported Targets` instead of just the traditional ``Foo_LIBRARIES`` +variable listing library files. However, this makes the link line +generated for a library found by a Find Module depend on whether it +is linked through an imported target or not, which is inconsistent. +Furthermore, this behavior has been a source of confusion because the +generated link line for a library file depends on its location. It is +also problematic for projects trying to link statically because flags +like ``-Wl,-Bstatic -lfoo -Wl,-Bdynamic`` may be used to help the linker +select ``libfoo.a`` instead of ``libfoo.so`` but then leak dynamic linking +to following libraries. (See the :prop_tgt:`LINK_SEARCH_END_STATIC` +target property for a solution typically used for that problem.) + +When the special case for libraries in implicit link directories was first +introduced the list of implicit link directories was simply hard-coded +(e.g. ``/lib``, ``/usr/lib``, and a few others). Since that time, CMake +has learned to detect the implicit link directories used by the compiler +front-end. If necessary, the :command:`find_library` command could be +taught to use this information to help find libraries of the proper +architecture. + +For these reasons, CMake 3.3 and above prefer to drop the special case +and link libraries by full path even when they are in implicit link +directories. Policy ``CMP0060`` provides compatibility for existing +projects. + +The OLD behavior for this policy is to ask the linker to search for +libraries whose full paths are known to be in implicit link directories. +The NEW behavior for this policy is to link libraries by full path even +if they are in implicit link directories. + +This policy was introduced in CMake version 3.3. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/policy/CMP0061.rst b/Help/policy/CMP0061.rst new file mode 100644 index 0000000..069a1ab --- /dev/null +++ b/Help/policy/CMP0061.rst @@ -0,0 +1,24 @@ +CMP0061 +------- + +CTest does not by default tell ``make`` to ignore errors (``-i``). + +The :command:`ctest_build` and :command:`build_command` commands no +longer generate build commands for :ref:`Makefile Generators` with +the ``-i`` option. Previously this was done to help build as much +of tested projects as possible. However, this behavior is not +consistent with other generators and also causes the return code +of the ``make`` tool to be meaningless. + +Of course users may still add this option manually by setting +:variable:`CTEST_BUILD_COMMAND` or the ``MAKECOMMAND`` cache entry. +See the :ref:`CTest Build Step` ``MakeCommand`` setting documentation +for their effects. + +The ``OLD`` behavior for this policy is to add ``-i`` to ``make`` +calls in CTest. The ``NEW`` behavior for this policy is to not +add ``-i``. + +This policy was introduced in CMake version 3.3. Unlike most policies, +CMake version |release| does *not* warn when this policy is not set and +simply uses OLD behavior. diff --git a/Help/policy/CMP0062.rst b/Help/policy/CMP0062.rst new file mode 100644 index 0000000..e2f5a5a --- /dev/null +++ b/Help/policy/CMP0062.rst @@ -0,0 +1,27 @@ +CMP0062 +------- + +Disallow install() of export() result. + +The :command:`export()` command generates a file containing +:ref:`Imported Targets`, which is suitable for use from the build +directory. It is not suitable for installation because it contains absolute +paths to buildsystem locations, and is particular to a single build +configuration. + +The :command:`install(EXPORT)` generates and installs files which contain +:ref:`Imported Targets`. These files are generated with relative paths +(unless the user specifies absolute paths), and are designed for +multi-configuration use. See :ref:`Creating Packages` for more. + +CMake 3.3 no longer allows the use of the :command:`install(FILES)` command +with the result of the :command:`export()` command. + +The ``OLD`` behavior for this policy is to allow installing the result of +an :command:`export()` command. The ``NEW`` behavior for this policy is +not to allow installing the result of an :command:`export()` command. + +This policy was introduced in CMake version 3.3. 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/CMP0063.rst b/Help/policy/CMP0063.rst new file mode 100644 index 0000000..298e9c2 --- /dev/null +++ b/Help/policy/CMP0063.rst @@ -0,0 +1,26 @@ +CMP0063 +------- + +Honor visibility properties for all target types. + +The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and +:prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties affect visibility +of symbols during dynamic linking. When first introduced these properties +affected compilation of sources only in shared libraries, module libraries, +and executables with the :prop_tgt:`ENABLE_EXPORTS` property set. This +was sufficient for the basic use cases of shared libraries and executables +with plugins. However, some sources may be compiled as part of static +libraries or object libraries and then linked into a shared library later. +CMake 3.3 and above prefer to honor these properties for sources compiled +in all target types. This policy preserves compatibility for projects +expecting the properties to work only for some target types. + +The ``OLD`` behavior for this policy is to ignore the visibility properties +for static libraries, object libraries, and executables without exports. +The ``NEW`` behavior for this policy is to honor the visibility properties +for all target types. + +This policy was introduced in CMake version 3.3. 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_dir/COMPILE_OPTIONS.rst b/Help/prop_dir/COMPILE_OPTIONS.rst index 5530860..877deb0 100644 --- a/Help/prop_dir/COMPILE_OPTIONS.rst +++ b/Help/prop_dir/COMPILE_OPTIONS.rst @@ -3,8 +3,8 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property specifies the list of options given so far to the -:command:`add_compile_options` command. +This property holds a :ref:`;-list <CMake Language Lists>` of options +given so far to the :command:`add_compile_options` command. This property is used to initialize the :prop_tgt:`COMPILE_OPTIONS` target property when a target is created, which is used by the generators to set diff --git a/Help/prop_dir/DEFINITIONS.rst b/Help/prop_dir/DEFINITIONS.rst index 22f7c15..79ac3f3 100644 --- a/Help/prop_dir/DEFINITIONS.rst +++ b/Help/prop_dir/DEFINITIONS.rst @@ -1,8 +1,13 @@ DEFINITIONS ----------- -For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS instead. +For CMake 2.4 compatibility only. Use :prop_dir:`COMPILE_DEFINITIONS` +instead. This read-only property specifies the list of flags given so far to -the add_definitions command. It is intended for debugging purposes. -Use the COMPILE_DEFINITIONS instead. +the :command:`add_definitions` command. It is intended for debugging +purposes. Use the :prop_dir:`COMPILE_DEFINITIONS` directory property +instead. + +This built-in read-only property does not exist if policy +:policy:`CMP0059` is set to ``NEW``. diff --git a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst index 163ae34..3db4f18 100644 --- a/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_CXX_KNOWN_FEATURES.rst @@ -9,7 +9,7 @@ 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. +compile features and a list of supported compilers. The features known to this version of CMake are: diff --git a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst index 18cd030..a08af00 100644 --- a/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst +++ b/Help/prop_gbl/CMAKE_C_KNOWN_FEATURES.rst @@ -9,7 +9,7 @@ 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. +compile features and a list of supported compilers. The features known to this version of CMake are: diff --git a/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst new file mode 100644 index 0000000..11f2c03 --- /dev/null +++ b/Help/prop_inst/CPACK_DESKTOP_SHORTCUTS.rst @@ -0,0 +1,7 @@ +CPACK_DESKTOP_SHORTCUTS +----------------------- + +Species a list of shortcut names that should be created on the Desktop +for this file. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst new file mode 100644 index 0000000..8a16022 --- /dev/null +++ b/Help/prop_inst/CPACK_STARTUP_SHORTCUTS.rst @@ -0,0 +1,7 @@ +CPACK_STARTUP_SHORTCUTS +----------------------- + +Species a list of shortcut names that should be created in the Startup folder +for this file. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst new file mode 100644 index 0000000..d30ea39 --- /dev/null +++ b/Help/prop_inst/CPACK_START_MENU_SHORTCUTS.rst @@ -0,0 +1,7 @@ +CPACK_START_MENU_SHORTCUTS +-------------------------- + +Species a list of shortcut names that should be created in the Start Menu +for this file. + +The property is currently only supported by the WIX generator. diff --git a/Help/prop_sf/VS_XAML_TYPE.rst b/Help/prop_sf/VS_XAML_TYPE.rst new file mode 100644 index 0000000..e92191d --- /dev/null +++ b/Help/prop_sf/VS_XAML_TYPE.rst @@ -0,0 +1,6 @@ +VS_XAML_TYPE +------------ + +Mark a XAML source file as a different type than the default ``Page``. +The most common usage would be to set the default App.xaml file as +ApplicationDefinition. diff --git a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst index b02d17d..facf902 100644 --- a/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/FAIL_REGULAR_EXPRESSION.rst @@ -4,5 +4,12 @@ FAIL_REGULAR_EXPRESSION If the output matches this regular expression the test will fail. If set, if the output matches one of specified regular expressions, -the test will fail.For example: FAIL_REGULAR_EXPRESSION -"[^a-z]Error;ERROR;Failed" +the test will fail. Example: + +.. code-block:: cmake + + set_tests_properties(mytest PROPERTIES + FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed" + ) + +``FAIL_REGULAR_EXPRESSION`` expects a list of regular expressions. diff --git a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst index bb35f77..0cd6215 100644 --- a/Help/prop_test/PASS_REGULAR_EXPRESSION.rst +++ b/Help/prop_test/PASS_REGULAR_EXPRESSION.rst @@ -5,4 +5,12 @@ The output must match this regular expression for the test to pass. If set, the test output will be checked against the specified regular expressions and at least one of the regular expressions has to match, -otherwise the test will fail. +otherwise the test will fail. Example: + +.. code-block:: cmake + + set_tests_properties(mytest PROPERTIES + PASS_REGULAR_EXPRESSION "TestPassed;All ok" + ) + +``PASS_REGULAR_EXPRESSION`` expects a list of regular expressions. diff --git a/Help/prop_test/TIMEOUT.rst b/Help/prop_test/TIMEOUT.rst index 0b247b8..d1cb90d 100644 --- a/Help/prop_test/TIMEOUT.rst +++ b/Help/prop_test/TIMEOUT.rst @@ -6,4 +6,4 @@ How many seconds to allow for this test. This property if set will limit a test to not take more than the specified number of seconds to run. If it exceeds that the test process will be killed and ctest will move to the next test. This -setting takes precedence over CTEST_TESTING_TIMEOUT. +setting takes precedence over :variable:`CTEST_TEST_TIMEOUT`. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst index df57dba..4221069 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst @@ -1,7 +1,9 @@ ARCHIVE_OUTPUT_DIRECTORY ------------------------ -.. |XXX| replace:: ARCHIVE +.. |XXX| replace:: :ref:`ARCHIVE <Archive Output Artifacts>` .. |xxx| replace:: archive .. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_ARCHIVE_OUTPUT_DIRECTORY .. include:: XXX_OUTPUT_DIRECTORY.txt + +See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst index 3c0c4fd..29991eb 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -1,11 +1,13 @@ ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> --------------------------------- -Per-configuration output directory for ARCHIVE target files. +Per-configuration output directory for +:ref:`ARCHIVE <Archive Output Artifacts>` target files. -This is a per-configuration version of ARCHIVE_OUTPUT_DIRECTORY, but +This is a per-configuration version of the +:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` target property, 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_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is -created. +property is initialized by the value of the +:variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` variable if +it is set when a target is created. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst index a137bb8..6150193 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst @@ -1,6 +1,8 @@ ARCHIVE_OUTPUT_NAME ------------------- -.. |XXX| replace:: ARCHIVE +.. |XXX| replace:: :ref:`ARCHIVE <Archive Output Artifacts>` .. |xxx| replace:: archive .. include:: XXX_OUTPUT_NAME.txt + +See also the :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst index 314fa58..4f62eb9 100644 --- a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst +++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG.rst @@ -1,6 +1,8 @@ ARCHIVE_OUTPUT_NAME_<CONFIG> ---------------------------- -Per-configuration output name for ARCHIVE target files. +Per-configuration output name for +:ref:`ARCHIVE <Archive Output Artifacts>` target files. -This is the configuration-specific version of ARCHIVE_OUTPUT_NAME. +This is the configuration-specific version of the +:prop_tgt:`ARCHIVE_OUTPUT_NAME` target property. diff --git a/Help/prop_tgt/COMPILE_FEATURES.rst b/Help/prop_tgt/COMPILE_FEATURES.rst index 225ffee..195215e 100644 --- a/Help/prop_tgt/COMPILE_FEATURES.rst +++ b/Help/prop_tgt/COMPILE_FEATURES.rst @@ -9,4 +9,4 @@ 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. +for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 27cbec1..36d786a 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -3,12 +3,13 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property specifies the list of options specified so far for this -property. +This property holds a :ref:`;-list <CMake Language Lists>` of options +specified so far for its target. Use the :command:`target_compile_options` +command to append more options. This property is intialized by the :prop_dir:`COMPILE_OPTIONS` directory -property, which is used by the generators to set the options for the -compiler. +property when a target is created, and is used by the generators to set +the options for the compiler. Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst new file mode 100644 index 0000000..3ef8e03 --- /dev/null +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,6 @@ +CROSSCOMPILING_EMULATOR +----------------------- + +Use the given emulator to run executables created when crosscompiling. This +command will be added as a prefix to :command:`add_test` test commands for +built target system executables. diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst index 67c5cb0..0f547e2 100644 --- a/Help/prop_tgt/CXX_EXTENSIONS.rst +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -9,7 +9,7 @@ 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. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_CXX_EXTENSIONS` variable if it is set when a target diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 65b30ec..edc9ba5 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -24,7 +24,7 @@ flag will not result in an error or warning, but will instead add the with the :prop_tgt:`CXX_STANDARD_REQUIRED` target property. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_CXX_STANDARD` variable if it is set when a target diff --git a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst index 4e24e5e..697d7f6 100644 --- a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -11,7 +11,7 @@ not available. For compilers that have no notion of a standard level, such as MSVC, this has no effect. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_CXX_STANDARD_REQUIRED` variable if it is set when a diff --git a/Help/prop_tgt/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst index dc48cc6..fce67f4 100644 --- a/Help/prop_tgt/C_EXTENSIONS.rst +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -9,7 +9,7 @@ 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. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_C_EXTENSIONS` variable if it is set when a target diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 3aa74af..5e36821 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -24,7 +24,7 @@ flag will not result in an error or warning, but will instead add the be controlled with the :prop_tgt:`C_STANDARD_REQUIRED` target property. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_C_STANDARD` variable if it is set when a target diff --git a/Help/prop_tgt/C_STANDARD_REQUIRED.rst b/Help/prop_tgt/C_STANDARD_REQUIRED.rst index 743d568..acfad98 100644 --- a/Help/prop_tgt/C_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/C_STANDARD_REQUIRED.rst @@ -11,7 +11,7 @@ not available. For compilers that have no notion of a standard level, such as MSVC, this has no effect. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_C_STANDARD_REQUIRED` variable if it is set when a diff --git a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst index 8dfec5f..31b594f 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -9,4 +9,4 @@ INTERFACE_COMPILE_FEATURES .. include:: INTERFACE_BUILD_PROPERTY.txt See the :manual:`cmake-compile-features(7)` manual for information on compile -features. +features and a list of supported compilers. diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index 1cfd7a8..b1c40b2 100644 --- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -22,5 +22,8 @@ installation prefix. For example: $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib ) +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index 55b7b8d..832d12b 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -17,5 +17,8 @@ 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. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES`` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_SOURCES.rst b/Help/prop_tgt/INTERFACE_SOURCES.rst index 696ee95..a224b68 100644 --- a/Help/prop_tgt/INTERFACE_SOURCES.rst +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -12,10 +12,6 @@ When target dependencies are specified using :command:`target_link_libraries`, CMake will read this property from all target dependencies to determine the sources of the consumer. -Targets with ``INTERFACE_SOURCES`` may not be exported with the -:command:`export` or :command:`install(EXPORT)` commands. This limitation may be -lifted in a future version of CMake. - 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)` diff --git a/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst new file mode 100644 index 0000000..26f6d16 --- /dev/null +++ b/Help/prop_tgt/LANG_INCLUDE_WHAT_YOU_USE.rst @@ -0,0 +1,13 @@ +<LANG>_INCLUDE_WHAT_YOU_USE +--------------------------- + +This property is implemented only when ``<LANG>`` is ``C`` or ``CXX``. + +Specify a :ref:`;-list <CMake Language Lists>` containing a command +line for the ``include-what-you-use`` tool. The :ref:`Makefile Generators` +and the :generator:`Ninja` generator will run this tool along with the +compiler and report a warning if the tool reports any problems. + +This property is initialized by the value of +the :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable if it is set +when a target is created. diff --git a/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst b/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst index d4bde17..5d34e20 100644 --- a/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst +++ b/Help/prop_tgt/LANG_VISIBILITY_PRESET.rst @@ -3,8 +3,11 @@ Value for symbol visibility compile flags -The <LANG>_VISIBILITY_PRESET property determines the value passed in a -visibility related compile option, such as -fvisibility= for <LANG>. -This property only has an affect for libraries and executables with -exports. This property is initialized by the value of the variable -CMAKE_<LANG>_VISIBILITY_PRESET if it is set when a target is created. +The ``<LANG>_VISIBILITY_PRESET`` property determines the value passed in a +visibility related compile option, such as ``-fvisibility=`` for ``<LANG>``. +This property affects compilation in sources of all types of targets +(subject to policy :policy:`CMP0063`). + +This property is initialized by the value of the +:variable:`CMAKE_<LANG>_VISIBILITY_PRESET` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst index e1d3a82..785a57b 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY.rst @@ -1,7 +1,9 @@ LIBRARY_OUTPUT_DIRECTORY ------------------------ -.. |XXX| replace:: LIBRARY +.. |XXX| replace:: :ref:`LIBRARY <Library Output Artifacts>` .. |xxx| replace:: library .. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_LIBRARY_OUTPUT_DIRECTORY .. include:: XXX_OUTPUT_DIRECTORY.txt + +See also the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst index 2a38373..6fc0142 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -1,11 +1,13 @@ LIBRARY_OUTPUT_DIRECTORY_<CONFIG> --------------------------------- -Per-configuration output directory for LIBRARY target files. +Per-configuration output directory for +:ref:`LIBRARY <Library Output Artifacts>` target files. -This is a per-configuration version of LIBRARY_OUTPUT_DIRECTORY, but +This is a per-configuration version of the +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` target property, 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_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is -created. +property is initialized by the value of the +:variable:`CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` variable if +it is set when a target is created. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst index 9e9d401..6027f7f 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME.rst @@ -1,6 +1,8 @@ LIBRARY_OUTPUT_NAME ------------------- -.. |XXX| replace:: LIBRARY +.. |XXX| replace:: :ref:`LIBRARY <Library Output Artifacts>` .. |xxx| replace:: library .. include:: XXX_OUTPUT_NAME.txt + +See also the :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst index 785d1b2..1994c7b 100644 --- a/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst +++ b/Help/prop_tgt/LIBRARY_OUTPUT_NAME_CONFIG.rst @@ -1,6 +1,8 @@ LIBRARY_OUTPUT_NAME_<CONFIG> ---------------------------- -Per-configuration output name for LIBRARY target files. +Per-configuration output name for +:ref:`LIBRARY <Library Output Artifacts>` target files. -This is the configuration-specific version of LIBRARY_OUTPUT_NAME. +This is the configuration-specific version of the +:prop_tgt:`LIBRARY_OUTPUT_NAME` target property. diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst index 2e859eb..2dcf45c 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst @@ -24,5 +24,8 @@ property if policy :policy:`CMP0022` is ``NEW``. This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES`` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst index 7f2b5dd..22ee5a6 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst +++ b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst @@ -13,5 +13,8 @@ property if policy :policy:`CMP0022` is ``NEW``. This property is deprecated. Use :prop_tgt:`INTERFACE_LINK_LIBRARIES` instead. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES_<CONFIG>`` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/PDB_NAME.rst b/Help/prop_tgt/PDB_NAME.rst index 479dec3..3a65796 100644 --- a/Help/prop_tgt/PDB_NAME.rst +++ b/Help/prop_tgt/PDB_NAME.rst @@ -5,7 +5,8 @@ Output name for the MS debug symbol ``.pdb`` file generated by the 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. +If not set, the :prop_tgt:`OUTPUT_NAME` target property value or +logical target name is used by default. .. |COMPILE_PDB_XXX| replace:: :prop_tgt:`COMPILE_PDB_NAME` .. include:: PDB_NOTE.txt diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst index af5ef44..12390f5 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY.rst @@ -1,7 +1,9 @@ RUNTIME_OUTPUT_DIRECTORY ------------------------ -.. |XXX| replace:: RUNTIME +.. |XXX| replace:: :ref:`RUNTIME <Runtime Output Artifacts>` .. |xxx| replace:: runtime .. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: CMAKE_RUNTIME_OUTPUT_DIRECTORY .. include:: XXX_OUTPUT_DIRECTORY.txt + +See also the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` target property. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst index 10be6cf..c100346 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -1,11 +1,13 @@ RUNTIME_OUTPUT_DIRECTORY_<CONFIG> --------------------------------- -Per-configuration output directory for RUNTIME target files. +Per-configuration output directory for +:ref:`RUNTIME <Runtime Output Artifacts>` target files. -This is a per-configuration version of RUNTIME_OUTPUT_DIRECTORY, but +This is a per-configuration version of the +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property, 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_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is -created. +property is initialized by the value of the +:variable:`CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` variable if +it is set when a target is created. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst index dc7dba4..11729c3 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME.rst @@ -1,6 +1,8 @@ RUNTIME_OUTPUT_NAME ------------------- -.. |XXX| replace:: RUNTIME +.. |XXX| replace:: :ref:`RUNTIME <Runtime Output Artifacts>` .. |xxx| replace:: runtime .. include:: XXX_OUTPUT_NAME.txt + +See also the :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>` target property. diff --git a/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst b/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst index f9029e5..b6a31bf 100644 --- a/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst +++ b/Help/prop_tgt/RUNTIME_OUTPUT_NAME_CONFIG.rst @@ -1,6 +1,8 @@ RUNTIME_OUTPUT_NAME_<CONFIG> ---------------------------- -Per-configuration output name for RUNTIME target files. +Per-configuration output name for +:ref:`RUNTIME <Runtime Output Artifacts>` target files. -This is the configuration-specific version of RUNTIME_OUTPUT_NAME. +This is the configuration-specific version of the +:prop_tgt:`RUNTIME_OUTPUT_NAME` target property. diff --git a/Help/prop_tgt/TARGET_FILE_TYPES.txt b/Help/prop_tgt/TARGET_FILE_TYPES.txt deleted file mode 100644 index 18489c7..0000000 --- a/Help/prop_tgt/TARGET_FILE_TYPES.txt +++ /dev/null @@ -1,9 +0,0 @@ -There are three kinds of target files that may be built: archive, -library, and runtime. Executables are always treated as runtime -targets. Static libraries are always treated as archive targets. -Module libraries are always treated as library targets. For -non-DLL platforms shared libraries are treated as library -targets. For DLL platforms the DLL part of a shared library is -treated as a runtime target and the corresponding import library -is treated as an archive target. All Windows-based systems -including Cygwin are DLL platforms. diff --git a/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst b/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst index e06d35c..adbbc71 100644 --- a/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst +++ b/Help/prop_tgt/VISIBILITY_INLINES_HIDDEN.rst @@ -3,9 +3,11 @@ VISIBILITY_INLINES_HIDDEN Whether to add a compile flag to hide symbols of inline functions -The VISIBILITY_INLINES_HIDDEN property determines whether a flag for -hiding symbols for inline functions, such as -fvisibility-inlines-hidden, -should be used when invoking the compiler. This property only has an affect -for libraries and executables with exports. This property is initialized by -the value of the :variable:`CMAKE_VISIBILITY_INLINES_HIDDEN` if it is set -when a target is created. +The ``VISIBILITY_INLINES_HIDDEN`` property determines whether a flag for +hiding symbols for inline functions, such as ``-fvisibility-inlines-hidden``, +should be used when invoking the compiler. This property affects compilation +in sources of all types of targets (subject to policy :policy:`CMP0063`). + +This property is initialized by +the value of the :variable:`CMAKE_VISIBILITY_INLINES_HIDDEN` variable if it +is set when a target is created. diff --git a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst index de98c37..7e00ac4 100644 --- a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst +++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst @@ -8,3 +8,9 @@ the generated Xcode project. Ignored on other generators. See the :variable:`CMAKE_XCODE_ATTRIBUTE_<an-attribute>` variable to set attributes on all targets in a directory tree. + +Contents of ``XCODE_ATTRIBUTE_<an-attribute>`` 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/XCTEST.rst b/Help/prop_tgt/XCTEST.rst new file mode 100644 index 0000000..eb47e60 --- /dev/null +++ b/Help/prop_tgt/XCTEST.rst @@ -0,0 +1,13 @@ +XCTEST +------ + +This target is a XCTest CFBundle on the Mac. + +This property will usually get set via the :command:`xctest_add_bundle` +macro in :module:`FindXCTest` module. + +If a module library target has this property set to true it will be +built as a CFBundle when built on the Mac. It will have the directory +structure required for a CFBundle. + +This property depends on :prop_tgt:`BUNDLE` to be effective. diff --git a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt index 65abbce..0b3d31c 100644 --- a/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt +++ b/Help/prop_tgt/XXX_OUTPUT_DIRECTORY.txt @@ -4,7 +4,5 @@ This property specifies the directory into which |xxx| target files should be built. Multi-configuration generators (VS, Xcode) append a per-configuration subdirectory to the specified directory. -.. include:: TARGET_FILE_TYPES.txt - This property is initialized by the value of the variable |CMAKE_XXX_OUTPUT_DIRECTORY| if it is set when a target is created. diff --git a/Help/prop_tgt/XXX_OUTPUT_NAME.txt b/Help/prop_tgt/XXX_OUTPUT_NAME.txt index 9c4fc7c..126f391 100644 --- a/Help/prop_tgt/XXX_OUTPUT_NAME.txt +++ b/Help/prop_tgt/XXX_OUTPUT_NAME.txt @@ -1,6 +1,5 @@ Output name for |XXX| target files. This property specifies the base name for |xxx| target files. It -overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties. - -.. include:: TARGET_FILE_TYPES.txt +overrides :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`OUTPUT_NAME_<CONFIG>` +properties. diff --git a/Help/release/3.2.rst b/Help/release/3.2.rst index ddc3d86..8abb1ca 100644 --- a/Help/release/3.2.rst +++ b/Help/release/3.2.rst @@ -124,19 +124,10 @@ Modules * A :module:`FindIntl` module was introduced to find the Gettext ``libintl`` library. -* A :module:`FindJsonCpp` module was introduced to find the - JsonCpp package. - * The :module:`FindLATEX` module learned to support components. * The :module:`FindMPI` module learned to find MS-MPI on Windows. -* The :module:`FindOpenGL` module no longer explicitly searches - for any dependency on X11 libraries with the :module:`FindX11` - module. Such dependencies should not need to be explicit. - Applications using X11 APIs themselves should find and link - to X11 libraries explicitly. - * The :module:`FindOpenSSL` module now reports ``crypto`` and ``ssl`` libraries separately in ``OPENSSL_CRYPTO_LIBRARY`` and ``OPENSSL_SSL_LIBRARY``, respectively, to allow applications to @@ -231,6 +222,12 @@ Deprecated and Removed Features compatible. If files were in a different encoding, including Latin 1, they will need to be converted. +* The :module:`FindOpenGL` module no longer explicitly searches + for any dependency on X11 libraries with the :module:`FindX11` + module. Such dependencies should not need to be explicit. + Applications using X11 APIs themselves should find and link + to X11 libraries explicitly. + * The implementation of CMake now relies on some C++ compiler features which are not supported by some older compilers. As a result, those old compilers can no longer be used to build CMake itself. CMake continues to be able to diff --git a/Help/release/dev/ExternalData-no-symlinks.rst b/Help/release/dev/ExternalData-no-symlinks.rst new file mode 100644 index 0000000..9323cca --- /dev/null +++ b/Help/release/dev/ExternalData-no-symlinks.rst @@ -0,0 +1,7 @@ +ExternalData-no-symlinks +------------------------ + +* The :module:`ExternalData` module learned a new + :variable:`ExternalData_NO_SYMLINKS` option to disable use of + symbolic links to populate the real data files and use copies + instead. diff --git a/Help/release/dev/ExternalData-recursive-match.rst b/Help/release/dev/ExternalData-recursive-match.rst new file mode 100644 index 0000000..4d8c789 --- /dev/null +++ b/Help/release/dev/ExternalData-recursive-match.rst @@ -0,0 +1,7 @@ +ExternalData-recursive-match +---------------------------- + +* The :module:`ExternalData` module learned a new ``RECURSE:`` + option in ``DATA{}`` references specifying directories. + This allows an entire directory tree of associated files + to be matched. diff --git a/Help/release/dev/ExternalData-url-algo-map.rst b/Help/release/dev/ExternalData-url-algo-map.rst new file mode 100644 index 0000000..baf661f --- /dev/null +++ b/Help/release/dev/ExternalData-url-algo-map.rst @@ -0,0 +1,8 @@ +ExternalData-url-algo-map +------------------------- + +* The :module:`ExternalData` module learned a new URL template + placeholder ``%(algo:<key>)`` to allow custom mapping from + algorithm name to URL component through configuration of new + :variable:`ExternalData_URL_ALGO_<algo>_<key>` variables. + This allows more flexibility in remote URLs. diff --git a/Help/release/dev/ExternalProject-byproducts-tokens.rst b/Help/release/dev/ExternalProject-byproducts-tokens.rst new file mode 100644 index 0000000..20b4dd4 --- /dev/null +++ b/Help/release/dev/ExternalProject-byproducts-tokens.rst @@ -0,0 +1,5 @@ +ExternalProject-byproducts-tokens +--------------------------------- + +* The :module:`ExternalProject` module learned to replace tokens + like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step. diff --git a/Help/release/dev/ExternalProject-genex.rst b/Help/release/dev/ExternalProject-genex.rst new file mode 100644 index 0000000..2c7bf8a --- /dev/null +++ b/Help/release/dev/ExternalProject-genex.rst @@ -0,0 +1,6 @@ +ExternalProject-genex +--------------------- + +* The :module:`ExternalProject` module APIs learned to support + :manual:`generator expressions <cmake-generator-expressions(7)>` + when using ``LOG_*`` options and in CMake initial cache options. diff --git a/Help/release/dev/FPHSA-ExactCase-name.rst b/Help/release/dev/FPHSA-ExactCase-name.rst new file mode 100644 index 0000000..675547c --- /dev/null +++ b/Help/release/dev/FPHSA-ExactCase-name.rst @@ -0,0 +1,10 @@ +FPHSA-ExactCase-name +-------------------- + +* The :module:`FindPackageHandleStandardArgs` module + ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now + always populates the both ``<PackageName>_FOUND`` + and ``<UPPERCASE_NAME>_FOUND`` variables (the latter + for backwards compatibility). The ``FOUND_VAR`` + option is now ignored except to enforce its allowed + values. diff --git a/Help/release/dev/FindCUDA-StaticRuntime.rst b/Help/release/dev/FindCUDA-StaticRuntime.rst new file mode 100644 index 0000000..112596c --- /dev/null +++ b/Help/release/dev/FindCUDA-StaticRuntime.rst @@ -0,0 +1,7 @@ +FindCUDA-StaticRuntime +---------------------- + +* The :module:`FindCUDA` module now defaults to using the static + CUDA runtime library if it is available. A new + ``CUDA_USE_STATIC_CUDA_RUNTIME`` option is offered to control + this behavior. diff --git a/Help/release/dev/FindMatlab-rewrite.rst b/Help/release/dev/FindMatlab-rewrite.rst new file mode 100644 index 0000000..07727b8 --- /dev/null +++ b/Help/release/dev/FindMatlab-rewrite.rst @@ -0,0 +1,7 @@ +FindMatlab-rewrite +------------------ + +* The :module:`FindMatlab` module was completely rewritten. It learned + about versions and components and to find Matlab in a more precise and + multiplatform way. The module now offers APIs to create mex extensions, + documentation, and unit tests. diff --git a/Help/release/dev/InstallRequiredSystemLibraries-COMPONENT.rst b/Help/release/dev/InstallRequiredSystemLibraries-COMPONENT.rst new file mode 100644 index 0000000..e6ebc2d --- /dev/null +++ b/Help/release/dev/InstallRequiredSystemLibraries-COMPONENT.rst @@ -0,0 +1,6 @@ +InstallRequiredSystemLibraries-COMPONENT +---------------------------------------- + +* The :module:`InstallRequiredSystemLibraries` module learned a new + ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the + installation component. diff --git a/Help/release/dev/UseSWIG-no-MAIN_DEPENDENCY.rst b/Help/release/dev/UseSWIG-no-MAIN_DEPENDENCY.rst new file mode 100644 index 0000000..5311cf1 --- /dev/null +++ b/Help/release/dev/UseSWIG-no-MAIN_DEPENDENCY.rst @@ -0,0 +1,9 @@ +UseSWIG-no-MAIN_DEPENDENCY +-------------------------- + +* The :module:`UseSWIG` module ``SWIG_ADD_MODULE`` macro no + longer attaches the swig invocation custom command to the + ``.i`` source file in IDE projects. This is because only + one custom command can be safely attached to a given source + file, and adding multiple modules with the same ``.i`` file + for different languages requires more than one such command. diff --git a/Help/release/dev/add-CheckFortranCompilerFlag.rst b/Help/release/dev/add-CheckFortranCompilerFlag.rst new file mode 100644 index 0000000..718b53e --- /dev/null +++ b/Help/release/dev/add-CheckFortranCompilerFlag.rst @@ -0,0 +1,6 @@ +add-CheckFortranCompilerFlag +---------------------------- + +* The :module:`CheckFortranCompilerFlag` module was introduced + to check ``Fortran`` compiler flags, much like the + :module:`CheckCCompilerFlag` module already does for ``C``. diff --git a/Help/release/dev/add-GreenHills-MULTI-generator.rst b/Help/release/dev/add-GreenHills-MULTI-generator.rst new file mode 100644 index 0000000..b4c5c5a --- /dev/null +++ b/Help/release/dev/add-GreenHills-MULTI-generator.rst @@ -0,0 +1,8 @@ +add-GreenHills-MULTI-generator +------------------------------ + +* A new experimental :generator:`Green Hills MULTI` generator was + added on Windows. `Green Hills MULTI`_ is an IDE for embedded + real-time systems. + +.. _`Green Hills MULTI`: http://www.ghs.com/products/MULTI_IDE.html diff --git a/Help/release/dev/add_dependencies-INTERFACE-libraries.rst b/Help/release/dev/add_dependencies-INTERFACE-libraries.rst new file mode 100644 index 0000000..dfac2af --- /dev/null +++ b/Help/release/dev/add_dependencies-INTERFACE-libraries.rst @@ -0,0 +1,7 @@ +add_dependencies-INTERFACE-libraries +------------------------------------ + +* The :command:`add_dependencies` command learned to allow dependencies + to be added to :ref:`interface libraries <Interface Libraries>`. + Dependencies added to an interface library are followed transitively + in its place since the target itself does not build. diff --git a/Help/release/dev/cmake-gui-osx-install-command-line.rst b/Help/release/dev/cmake-gui-osx-install-command-line.rst new file mode 100644 index 0000000..e0f0369 --- /dev/null +++ b/Help/release/dev/cmake-gui-osx-install-command-line.rst @@ -0,0 +1,10 @@ +cmake-gui-osx-install-command-line +---------------------------------- + +* On OS X the :manual:`cmake-gui(1)` no longer has the + ``Install For Command Line Use`` menu item. Instead there + is a ``How to Install For Command Line Use`` menu item + that shows an informational dialog box explaining how to + make the command line tools available. For example:: + + /Applications/CMake.app/Contents/bin/cmake-gui --install diff --git a/Help/release/dev/compiler-version-Fortran.rst b/Help/release/dev/compiler-version-Fortran.rst new file mode 100644 index 0000000..e10b206 --- /dev/null +++ b/Help/release/dev/compiler-version-Fortran.rst @@ -0,0 +1,6 @@ +compiler-version-Fortran +------------------------ + +* The version of some Fortran compilers is now detected and stored in the + :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` + variable. diff --git a/Help/release/dev/cpack-deb-component-auto-discovery.rst b/Help/release/dev/cpack-deb-component-auto-discovery.rst new file mode 100644 index 0000000..cc74db2 --- /dev/null +++ b/Help/release/dev/cpack-deb-component-auto-discovery.rst @@ -0,0 +1,6 @@ +cpack-deb-component-auto-discovery +---------------------------------- + +* The :module:`CPackDeb` module learned a new + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` + variable to specify per-component use of ``dpkg-shlibdeps``. diff --git a/Help/release/dev/cpack-deb-component-dependencies.rst b/Help/release/dev/cpack-deb-component-dependencies.rst new file mode 100644 index 0000000..de9f457 --- /dev/null +++ b/Help/release/dev/cpack-deb-component-dependencies.rst @@ -0,0 +1,6 @@ +cpack-deb-component-dependencies +-------------------------------- + +* The :module:`CPackDeb` module learned a new + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` + option to specify per-component dependencies. diff --git a/Help/release/dev/cpack-ifw-updates.rst b/Help/release/dev/cpack-ifw-updates.rst new file mode 100644 index 0000000..c01f04b --- /dev/null +++ b/Help/release/dev/cpack-ifw-updates.rst @@ -0,0 +1,5 @@ +cpack-ifw-updates +----------------- + +* The :manual:`cpack(1)` ``IFW`` generator and the :module:`CPackIFW` + module learned to support Qt Framework Installer 2.0 tools. diff --git a/Help/release/dev/cpack-rpm-basic-symlink-handling.rst b/Help/release/dev/cpack-rpm-basic-symlink-handling.rst new file mode 100644 index 0000000..3af4cf1 --- /dev/null +++ b/Help/release/dev/cpack-rpm-basic-symlink-handling.rst @@ -0,0 +1,6 @@ +cpack-rpm-basic-symlink-handling +-------------------------------- + +* The :module:`CPackRPM` module learned to package symbolic links + more cleanly and now supports directory symlinks with recent + ``rpmbuild`` versions. diff --git a/Help/release/dev/cpack-rpm-refactored-file-listing.rst b/Help/release/dev/cpack-rpm-refactored-file-listing.rst new file mode 100644 index 0000000..b4a5025 --- /dev/null +++ b/Help/release/dev/cpack-rpm-refactored-file-listing.rst @@ -0,0 +1,6 @@ +cpack-rpm-refactored-file-listing +--------------------------------- + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_ADDITIONAL_MAN_DIRS` variable to specify + directories containing man pages for the brp-compress RPM macro. diff --git a/Help/release/dev/ctest-no-make-i.rst b/Help/release/dev/ctest-no-make-i.rst new file mode 100644 index 0000000..96da0bd --- /dev/null +++ b/Help/release/dev/ctest-no-make-i.rst @@ -0,0 +1,7 @@ +ctest-no-make-i +--------------- + +* The :command:`ctest_build` and :command:`build_command` commands + no longer tell ``make`` tools to ignore errors with the ``-i`` option. + Previously this was done for :ref:`Makefile Generators` but not others. + See policy :policy:`CMP0061`. diff --git a/Help/release/dev/ctest-repeat-until-fail.rst b/Help/release/dev/ctest-repeat-until-fail.rst new file mode 100644 index 0000000..8a679c6 --- /dev/null +++ b/Help/release/dev/ctest-repeat-until-fail.rst @@ -0,0 +1,5 @@ +ctest-repeat-until-fail +----------------------- + +* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>`` + option to help find sporadic test failures. diff --git a/Help/release/dev/disallow-install-of-export.rst b/Help/release/dev/disallow-install-of-export.rst new file mode 100644 index 0000000..baee26d --- /dev/null +++ b/Help/release/dev/disallow-install-of-export.rst @@ -0,0 +1,5 @@ +disallow-install-of-export +-------------------------- + +* Using the output of :command:`export()` with the :command:`install(FILES)` + command is no longer allowed. See policy :policy:`CMP0062` for details. diff --git a/Help/release/dev/emulator-property.rst b/Help/release/dev/emulator-property.rst new file mode 100644 index 0000000..1bc2f2d --- /dev/null +++ b/Help/release/dev/emulator-property.rst @@ -0,0 +1,7 @@ +emulator-property +----------------- + +* A :prop_tgt:`CROSSCOMPILING_EMULATOR` target property and supporting + :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable were introduced + to allow target platform binaries to run on the host during cross + compiling. diff --git a/Help/release/dev/execute_process-merge-output.rst b/Help/release/dev/execute_process-merge-output.rst new file mode 100644 index 0000000..4c80cdd --- /dev/null +++ b/Help/release/dev/execute_process-merge-output.rst @@ -0,0 +1,5 @@ +execute_process-merge-output +---------------------------- + +* The :command:`execute_process` command learned to support specifying + the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``. diff --git a/Help/release/dev/export-interface-source-files.rst b/Help/release/dev/export-interface-source-files.rst new file mode 100644 index 0000000..00dcd25 --- /dev/null +++ b/Help/release/dev/export-interface-source-files.rst @@ -0,0 +1,6 @@ +export-interface-source-files +----------------------------- + +* It is now possible to export targets which populate the + :prop_tgt:`INTERFACE_SOURCES` target property using the + :command:`install(EXPORT)` and :command:`export()` commands. diff --git a/Help/release/dev/extend-visibility-properties.rst b/Help/release/dev/extend-visibility-properties.rst new file mode 100644 index 0000000..6b4489d --- /dev/null +++ b/Help/release/dev/extend-visibility-properties.rst @@ -0,0 +1,7 @@ +extend-visibility-properties +---------------------------- + +* The :prop_tgt:`<LANG>_VISIBILITY_PRESET` and + :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target properties now + affect compilation in sources of all target types. See + policy :policy:`CMP0063`. diff --git a/Help/release/dev/file-globbing-directory-listing.rst b/Help/release/dev/file-globbing-directory-listing.rst new file mode 100644 index 0000000..c4d7ba5 --- /dev/null +++ b/Help/release/dev/file-globbing-directory-listing.rst @@ -0,0 +1,6 @@ +file-globbing-directory-listing +------------------------------- + +* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands + learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether + the glob result should include directories. diff --git a/Help/release/dev/find-command-prefix-from-PATH.rst b/Help/release/dev/find-command-prefix-from-PATH.rst new file mode 100644 index 0000000..f9aae2a --- /dev/null +++ b/Help/release/dev/find-command-prefix-from-PATH.rst @@ -0,0 +1,6 @@ +find-command-prefix-from-PATH +----------------------------- + +* The :command:`find_library`, :command:`find_path`, and :command:`find_file` + commands now search in installation prefixes derived from the ``PATH`` + environment variable. diff --git a/Help/release/dev/find_package-no-cmake-gui-paths.rst b/Help/release/dev/find_package-no-cmake-gui-paths.rst new file mode 100644 index 0000000..3914559 --- /dev/null +++ b/Help/release/dev/find_package-no-cmake-gui-paths.rst @@ -0,0 +1,10 @@ +find_package-no-cmake-gui-paths +------------------------------- + +* The :command:`find_package` command no longer considers project + build trees recently configured in a :manual:`cmake-gui(1)`. + This was previously done only on Windows and is now never done. + The ``NO_CMAKE_BUILDS_PATH`` option is now ignored if given + and effectively always on. + Projects may populate the :ref:`User Package Registry` to aid + users building multiple dependent projects one after another. diff --git a/Help/release/dev/gcov-module-coverage-exclude.rst b/Help/release/dev/gcov-module-coverage-exclude.rst new file mode 100644 index 0000000..ee4ebae --- /dev/null +++ b/Help/release/dev/gcov-module-coverage-exclude.rst @@ -0,0 +1,6 @@ +gcov-module-coverage-exclude +---------------------------- + +* The :module:`CTestCoverageCollectGCOV` module learned to support + the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the + :command:`ctest_coverage` command. diff --git a/Help/release/dev/if-IN_LIST.rst b/Help/release/dev/if-IN_LIST.rst new file mode 100644 index 0000000..9dd0725 --- /dev/null +++ b/Help/release/dev/if-IN_LIST.rst @@ -0,0 +1,5 @@ +if-IN_LIST +---------- + +* Add a new IN_LIST operator to if() that evaluates true + if a given element is contained in a named list. diff --git a/Help/release/dev/install-DESTINATION-genex.rst b/Help/release/dev/install-DESTINATION-genex.rst new file mode 100644 index 0000000..4c4bbed --- /dev/null +++ b/Help/release/dev/install-DESTINATION-genex.rst @@ -0,0 +1,5 @@ +install-DESTINATION-genex +------------------------- + +* The :command:`install(TARGETS)` command learned to support + generator expressions in the ``DESTINATION`` value. diff --git a/Help/release/dev/link-implicit-libs-full-path.rst b/Help/release/dev/link-implicit-libs-full-path.rst new file mode 100644 index 0000000..7ed7245 --- /dev/null +++ b/Help/release/dev/link-implicit-libs-full-path.rst @@ -0,0 +1,6 @@ +link-implicit-libs-full-path +---------------------------- + +* Linking to library files by a full path in an implicit linker search + directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to + search for the library (e.g. ``-lfoo``). See policy :policy:`CMP0060`. diff --git a/Help/release/dev/makefile-DELETE_ON_ERROR.rst b/Help/release/dev/makefile-DELETE_ON_ERROR.rst new file mode 100644 index 0000000..c7c45fd --- /dev/null +++ b/Help/release/dev/makefile-DELETE_ON_ERROR.rst @@ -0,0 +1,7 @@ +makefile-DELETE_ON_ERROR +------------------------ + +* The Makefile generators now add ``.DELETE_ON_ERROR`` to the + makefiles that contain the actual build rules for files on disk. + This tells GNU make to remove rule outputs when their recipe + modifies an output but fails. diff --git a/Help/release/dev/makefile-progress-improvements.rst b/Help/release/dev/makefile-progress-improvements.rst new file mode 100644 index 0000000..9cc9706 --- /dev/null +++ b/Help/release/dev/makefile-progress-improvements.rst @@ -0,0 +1,7 @@ +makefile-progress-improvements +------------------------------ + +* With Makefile generators, the build-time progress output has been improved. + It no longer mixes progress and build rule messages during parallel builds. + The link rule messages now have progress and are displayed as bold green + instead of bold red (since red is often associated with an error message). diff --git a/Help/release/dev/mingw-compile-features.rst b/Help/release/dev/mingw-compile-features.rst new file mode 100644 index 0000000..e2ed30b --- /dev/null +++ b/Help/release/dev/mingw-compile-features.rst @@ -0,0 +1,6 @@ +mingw-compile-features +---------------------- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by GNU compilers on Windows, versions + 4.4 through 5.0. diff --git a/Help/release/dev/mingw-no-find_library-dll.rst b/Help/release/dev/mingw-no-find_library-dll.rst new file mode 100644 index 0000000..1b0c19b --- /dev/null +++ b/Help/release/dev/mingw-no-find_library-dll.rst @@ -0,0 +1,8 @@ +mingw-no-find_library-dll +------------------------- + +* When building with GNU tools on Windows (MinGW tools), the + :command:`find_library` command will no longer consider + ``.dll`` files to be linkable libraries. All dynamic link + libraries are expected to provide separate ``.dll.a`` or + ``.lib`` import libraries. diff --git a/Help/release/dev/ninja-require-byproducts.rst b/Help/release/dev/ninja-require-byproducts.rst new file mode 100644 index 0000000..ccde4bc --- /dev/null +++ b/Help/release/dev/ninja-require-byproducts.rst @@ -0,0 +1,9 @@ +ninja-require-byproducts +------------------------ + +* The :generator:`Ninja` generator now requires that calls to the + :command:`add_custom_command` and :command:`add_custom_target` + commands use the ``BYPRODUCTS`` option to explicitly specify any + files generated by the custom commands that are not listed as + outputs (perhaps because their timestamps are allowed to be older + than the inputs). See policy :policy:`CMP0058`. diff --git a/Help/release/dev/remove-DEFINITIONS-directory-property.rst b/Help/release/dev/remove-DEFINITIONS-directory-property.rst new file mode 100644 index 0000000..d8e50f0 --- /dev/null +++ b/Help/release/dev/remove-DEFINITIONS-directory-property.rst @@ -0,0 +1,6 @@ +remove-DEFINITIONS-property +--------------------------- + +* The :command:`add_definitions()` command no longer causes a + :prop_dir:`DEFINITIONS` directory property to be populated. See policy + :policy:`CMP0059`. diff --git a/Help/release/dev/rpm_package_architecture.rst b/Help/release/dev/rpm_package_architecture.rst new file mode 100644 index 0000000..5bec51d --- /dev/null +++ b/Help/release/dev/rpm_package_architecture.rst @@ -0,0 +1,6 @@ +rpm_package_architecture +------------------------ + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable + to specify a component-specific package architecture. diff --git a/Help/release/dev/run-include-what-you-use.rst b/Help/release/dev/run-include-what-you-use.rst new file mode 100644 index 0000000..baac21f --- /dev/null +++ b/Help/release/dev/run-include-what-you-use.rst @@ -0,0 +1,8 @@ +run-include-what-you-use +------------------------ + +* The :ref:`Makefile Generators` and the :generator:`Ninja` generator + learned to optionally run ``include-what-you-use`` along with the + compiler for ``C`` and ``CXX`` languages. See the + :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable and + :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property for details. diff --git a/Help/release/dev/tar-write-format.rst b/Help/release/dev/tar-write-format.rst new file mode 100644 index 0000000..004df21 --- /dev/null +++ b/Help/release/dev/tar-write-format.rst @@ -0,0 +1,6 @@ +tar-write-format +---------------- + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--format<format>`` option to specify the archive format to + be written. diff --git a/Help/release/dev/target-language-genex.rst b/Help/release/dev/target-language-genex.rst new file mode 100644 index 0000000..ed4cb5e --- /dev/null +++ b/Help/release/dev/target-language-genex.rst @@ -0,0 +1,9 @@ +target-language-genex +--------------------- + +* A new ``COMPILE_LANGUAGE`` generator expression was introduced to + allow specification of compile options for target files based on the + :prop_sf:`LANGUAGE` of each source file. Due to limitations of the + underlying native build tools, this feature has varying support across + generators. See the :manual:`cmake-generator-expressions(7)` manual + for details. diff --git a/Help/release/dev/vs-install-in-default-build.rst b/Help/release/dev/vs-install-in-default-build.rst new file mode 100644 index 0000000..b57592e --- /dev/null +++ b/Help/release/dev/vs-install-in-default-build.rst @@ -0,0 +1,7 @@ +vs-install-in-default-build +--------------------------- + +* The :ref:`Visual Studio Generators` learned a new + :variable:`CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD` option + to put the ``INSTALL`` target in the default build of a + solution (``.sln``) file. diff --git a/Help/release/dev/vs-xaml.rst b/Help/release/dev/vs-xaml.rst new file mode 100644 index 0000000..575899f --- /dev/null +++ b/Help/release/dev/vs-xaml.rst @@ -0,0 +1,6 @@ +vs-xaml +------- + +* The :ref:`Visual Studio Generators` learned to support ``.xaml`` + source files and automatically associate them with corresponding + ``.h`` and ``.cpp`` sources. diff --git a/Help/release/dev/vs10-no-macros.rst b/Help/release/dev/vs10-no-macros.rst new file mode 100644 index 0000000..89377dc --- /dev/null +++ b/Help/release/dev/vs10-no-macros.rst @@ -0,0 +1,9 @@ +vs10-no-macros +-------------- + +* The :generator:`Visual Studio 10 2010` generator no longer checks + for running VS IDEs with the project open or asks them to reload. + This was originally done for VS 10 because it had been done for + VS 7 through 9 to avoid prompting for every project in a solution. + Since VS >= 10 allow the whole solution to reload at once they + do not need CMake to help them. diff --git a/Help/release/dev/vs6-deprecate.rst b/Help/release/dev/vs6-deprecate.rst new file mode 100644 index 0000000..83f9afb --- /dev/null +++ b/Help/release/dev/vs6-deprecate.rst @@ -0,0 +1,5 @@ +vs6-deprecate +------------- + +* The :generator:`Visual Studio 6` generator is now deprecated + and will be removed in a future version of CMake. diff --git a/Help/release/dev/vs7-OutputDirectory.rst b/Help/release/dev/vs7-OutputDirectory.rst new file mode 100644 index 0000000..2725d0c --- /dev/null +++ b/Help/release/dev/vs7-OutputDirectory.rst @@ -0,0 +1,10 @@ +vs7-OutputDirectory +------------------- + +* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio + 7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``. + This should have no effect on the intended use cases of the variable. + +* With Visual Studio 7, 8, and 9 generators the value of the ``$(OutDir)`` + placeholder no longer evaluates to the configuration name. Projects + should use ``$(ConfigurationName)`` for that instead. diff --git a/Help/release/dev/vs70-deprecate.rst b/Help/release/dev/vs70-deprecate.rst new file mode 100644 index 0000000..fb94110 --- /dev/null +++ b/Help/release/dev/vs70-deprecate.rst @@ -0,0 +1,5 @@ +vs70-deprecate +-------------- + +* The :generator:`Visual Studio 7` generator (.NET 2002) is now + deprecated and will be removed in a future version of CMake. diff --git a/Help/release/dev/wix-shortcut-properties.rst b/Help/release/dev/wix-shortcut-properties.rst new file mode 100644 index 0000000..bdd6485 --- /dev/null +++ b/Help/release/dev/wix-shortcut-properties.rst @@ -0,0 +1,9 @@ +wix-shortcut-properties +----------------------- + +* The CPack WIX generator learned the new + :prop_inst:`CPACK_START_MENU_SHORTCUTS`, + :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and + :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can + be used to install shorcuts in the Start Menu, on the Desktop and + in the Startup Folder respectively. diff --git a/Help/release/dev/xcode-attribute-genex.rst b/Help/release/dev/xcode-attribute-genex.rst new file mode 100644 index 0000000..3fd5b1c --- /dev/null +++ b/Help/release/dev/xcode-attribute-genex.rst @@ -0,0 +1,5 @@ +xcode-attribute-genex +--------------------- + +* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned + to support generator expressions. diff --git a/Help/release/dev/xcode-xctest.rst b/Help/release/dev/xcode-xctest.rst new file mode 100644 index 0000000..7a2f07b --- /dev/null +++ b/Help/release/dev/xcode-xctest.rst @@ -0,0 +1,6 @@ +xcode-xctest +------------ + +* On OS X, CMake learned to create XCTest bundles to test Frameworks + and App Bundles within Xcode. The :module:`FindXCTest` module + provides convenience functions to handle :prop_tgt:`XCTEST` bundles. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst index 6a22f73..c889321 100644 --- a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY.rst @@ -1,8 +1,9 @@ CMAKE_ARCHIVE_OUTPUT_DIRECTORY ------------------------------ -Where to put all the ARCHIVE targets when built. +Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>` +target files when built. -This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY +This variable is used to initialize the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` property on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..94c2b6e --- /dev/null +++ b/Help/variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,9 @@ +CMAKE_ARCHIVE_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +Where to put all the :ref:`ARCHIVE <Archive Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_CFG_INTDIR.rst b/Help/variable/CMAKE_CFG_INTDIR.rst index 20435e5..55f7b01 100644 --- a/Help/variable/CMAKE_CFG_INTDIR.rst +++ b/Help/variable/CMAKE_CFG_INTDIR.rst @@ -12,11 +12,11 @@ values: :: - $(IntDir) = Visual Studio 6 - $(OutDir) = Visual Studio 7, 8, 9 - $(Configuration) = Visual Studio 10 - $(CONFIGURATION) = Xcode - . = Make-based tools + $(IntDir) = Visual Studio 6 + $(ConfigurationName) = Visual Studio 7, 8, 9 + $(Configuration) = Visual Studio 10 + $(CONFIGURATION) = Xcode + . = Make-based tools Since these values are evaluated by the native build system, this variable is suitable only for use in command lines that will be diff --git a/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst new file mode 100644 index 0000000..95d2c7f --- /dev/null +++ b/Help/variable/CMAKE_CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,12 @@ +CMAKE_CROSSCOMPILING_EMULATOR +----------------------------- + +This variable is only used when :variable:`CMAKE_CROSSCOMPILING` is on. It +should point to a command on the host system that can run executable built +for the target system. + +The command will be used to run :command:`try_run` generated executables, +which avoids manual population of the TryRunResults.cmake file. + +It is also used as the default value for the +:prop_tgt:`CROSSCOMPILING_EMULATOR` target property of executables. diff --git a/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst index 460c78c..f003227 100644 --- a/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst +++ b/Help/variable/CMAKE_CXX_COMPILE_FEATURES.rst @@ -8,4 +8,4 @@ list is a subset of the features listed in the :prop_gbl:`CMAKE_CXX_KNOWN_FEATUR global property. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_EXTENSIONS.rst b/Help/variable/CMAKE_CXX_EXTENSIONS.rst index 6448371..b14d753 100644 --- a/Help/variable/CMAKE_CXX_EXTENSIONS.rst +++ b/Help/variable/CMAKE_CXX_EXTENSIONS.rst @@ -8,4 +8,4 @@ property on all targets. See that target property for additional information. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD.rst b/Help/variable/CMAKE_CXX_STANDARD.rst index 963a42a..2bc4525 100644 --- a/Help/variable/CMAKE_CXX_STANDARD.rst +++ b/Help/variable/CMAKE_CXX_STANDARD.rst @@ -8,4 +8,4 @@ property on all targets. See that target property for additional information. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst index f7750fa..14ffcd1 100644 --- a/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_CXX_STANDARD_REQUIRED.rst @@ -8,4 +8,4 @@ property on all targets. See that target property for additional information. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_COMPILE_FEATURES.rst b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst index 1106246..df66eae 100644 --- a/Help/variable/CMAKE_C_COMPILE_FEATURES.rst +++ b/Help/variable/CMAKE_C_COMPILE_FEATURES.rst @@ -8,4 +8,4 @@ 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. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_EXTENSIONS.rst b/Help/variable/CMAKE_C_EXTENSIONS.rst index 5e935fc..25bec12 100644 --- a/Help/variable/CMAKE_C_EXTENSIONS.rst +++ b/Help/variable/CMAKE_C_EXTENSIONS.rst @@ -8,4 +8,4 @@ property on all targets. See that target property for additional information. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD.rst b/Help/variable/CMAKE_C_STANDARD.rst index 3098ce5..2eb4e43 100644 --- a/Help/variable/CMAKE_C_STANDARD.rst +++ b/Help/variable/CMAKE_C_STANDARD.rst @@ -8,4 +8,4 @@ property on all targets. See that target property for additional information. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst index c24eea4..5e415da 100644 --- a/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst +++ b/Help/variable/CMAKE_C_STANDARD_REQUIRED.rst @@ -8,4 +8,4 @@ property on all targets. See that target property for additional information. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst new file mode 100644 index 0000000..c5915c3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_DEBUG +----------------------------------- + +GHS kernel flags for Debug build type or configuration. + +<LANG> flags used when CMAKE_BUILD_TYPE is Debug. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst new file mode 100644 index 0000000..f80e785 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_MINSIZEREL +---------------------------------------- + +GHS kernel flags for MinSizeRel build type or configuration. + +<LANG> flags used when CMAKE_BUILD_TYPE is MinSizeRel.Short for +minimum size release. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst new file mode 100644 index 0000000..fe02bc3 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELEASE +------------------------------------- + +GHS kernel flags for Release build type or configuration. + +<LANG> flags used when CMAKE_BUILD_TYPE is Release diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst new file mode 100644 index 0000000..220f7f9 --- /dev/null +++ b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELWITHDEBINFO +-------------------------------------------- + +GHS kernel flags for RelWithDebInfo type or configuration. + +<LANG> flags used when CMAKE_BUILD_TYPE is RelWithDebInfo. Short for +Release With Debug Information. diff --git a/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst b/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst new file mode 100644 index 0000000..2c8028a --- /dev/null +++ b/Help/variable/CMAKE_LANG_INCLUDE_WHAT_YOU_USE.rst @@ -0,0 +1,6 @@ +CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE +--------------------------------- + +Default value for :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property. +This variable is used to initialize the property on each target as it is +created. This is done only when ``<LANG>`` is ``C`` or ``CXX``. diff --git a/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst index bef670f..1961ea0 100644 --- a/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst +++ b/Help/variable/CMAKE_LANG_VISIBILITY_PRESET.rst @@ -1,8 +1,5 @@ CMAKE_<LANG>_VISIBILITY_PRESET ------------------------------ -Default value for <LANG>_VISIBILITY_PRESET of targets. - -This variable is used to initialize the <LANG>_VISIBILITY_PRESET -property on all the targets. See that target property for additional -information. +Default value for the :prop_tgt:`<LANG>_VISIBILITY_PRESET` target +property when a target is created. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst index 3bdd348..e97296d 100644 --- a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY.rst @@ -1,8 +1,9 @@ CMAKE_LIBRARY_OUTPUT_DIRECTORY ------------------------------ -Where to put all the LIBRARY targets when built. +Where to put all the :ref:`LIBRARY <Library Output Artifacts>` +target files when built. -This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY +This variable is used to initialize the :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` property on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..e069cdd --- /dev/null +++ b/Help/variable/CMAKE_LIBRARY_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,9 @@ +CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +Where to put all the :ref:`LIBRARY <Library Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index f1d88a5..85b098b 100644 --- a/Help/variable/CMAKE_MAKE_PROGRAM.rst +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -56,6 +56,10 @@ to configure the project: the CMake cache then CMake will use the specified value if possible. +* The :generator:`Green Hills MULTI` generator sets this to ``gbuild``. + If a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to + the CMake cache then CMake will use the specified value. + The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code. The value is also used by the :manual:`cmake(1)` ``--build`` and :manual:`ctest(1)` ``--build-and-test`` tools to launch the native diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index a83c807..092fe3e 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -11,6 +11,8 @@ warn by default: policy :policy:`CMP0047`. * ``CMAKE_POLICY_WARNING_CMP0056`` controls the warning for policy :policy:`CMP0056`. +* ``CMAKE_POLICY_WARNING_CMP0060`` controls the warning for + policy :policy:`CMP0060`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst index 366ca66..6253d4a 100644 --- a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY.rst @@ -1,8 +1,9 @@ CMAKE_RUNTIME_OUTPUT_DIRECTORY ------------------------------ -Where to put all the RUNTIME targets when built. +Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>` +target files when built. -This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY +This variable is used to initialize the :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` property on all the targets. See that target property for additional information. diff --git a/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst new file mode 100644 index 0000000..080dea6 --- /dev/null +++ b/Help/variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG.rst @@ -0,0 +1,9 @@ +CMAKE_RUNTIME_OUTPUT_DIRECTORY_<CONFIG> +--------------------------------------- + +Where to put all the :ref:`RUNTIME <Runtime Output Artifacts>` +target files when built for a specific configuration. + +This variable is used to initialize the +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY_<CONFIG>` property on all the targets. +See that target property for additional information. diff --git a/Help/variable/CMAKE_SIZEOF_VOID_P.rst b/Help/variable/CMAKE_SIZEOF_VOID_P.rst index 2697fad..98dbed6 100644 --- a/Help/variable/CMAKE_SIZEOF_VOID_P.rst +++ b/Help/variable/CMAKE_SIZEOF_VOID_P.rst @@ -3,6 +3,6 @@ CMAKE_SIZEOF_VOID_P Size of a void pointer. -This is set to the size of a pointer on the machine, and is determined +This is set to the size of a pointer on the target machine, and is determined by a try compile. If a 64 bit size is found, then the library search path is modified to look for 64 bit libraries first. diff --git a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst index 8ad89f1..2f5313b 100644 --- a/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst +++ b/Help/variable/CMAKE_SYSTEM_PROCESSOR.rst @@ -6,3 +6,5 @@ The name of the CPU CMake is building for. 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. + +* The Green Hills MULTI generator sets this to ``ARM`` by default diff --git a/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst b/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst index f55c7b1..150bacc 100644 --- a/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst +++ b/Help/variable/CMAKE_VISIBILITY_INLINES_HIDDEN.rst @@ -1,8 +1,5 @@ CMAKE_VISIBILITY_INLINES_HIDDEN ------------------------------- -Default value for VISIBILITY_INLINES_HIDDEN of targets. - -This variable is used to initialize the VISIBILITY_INLINES_HIDDEN -property on all the targets. See that target property for additional -information. +Default value for the :prop_tgt:`VISIBILITY_INLINES_HIDDEN` target +property when a target is created. diff --git a/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst new file mode 100644 index 0000000..68f1ff6 --- /dev/null +++ b/Help/variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD.rst @@ -0,0 +1,8 @@ +CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD +----------------------------------------- + +Include INSTALL target to default build. + +In Visual Studio solution, by default the INSTALL target will not be part of +the default build. Setting this variable will enable the INSTALL target to be +part of the default build. diff --git a/Help/variable/GHS-MULTI.rst b/Help/variable/GHS-MULTI.rst new file mode 100644 index 0000000..0f91be8 --- /dev/null +++ b/Help/variable/GHS-MULTI.rst @@ -0,0 +1,4 @@ +GHS-MULTI +--------- + +True when using Green Hills MULTI |