diff options
Diffstat (limited to 'Help')
221 files changed, 2167 insertions, 854 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_custom_command.rst b/Help/command/add_custom_command.rst index e646c56..ecbf9dd 100644 --- a/Help/command/add_custom_command.rst +++ b/Help/command/add_custom_command.rst @@ -79,6 +79,9 @@ The options are: If ``COMMAND`` specifies an executable target (created by the :command:`add_executable` command) it will automatically be replaced by the location of the executable created at build time. + (Use the ``TARGET_FILE`` + :manual:`generator expression <cmake-generator-expressions(7)>` to + reference an executable later in the command line.) Additionally a target-level dependency will be added so that the executable target will be built before any target using this custom command. However this does NOT add a file-level dependency that 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/cmake_policy.rst b/Help/command/cmake_policy.rst index 2bc3287..b51b951 100644 --- a/Help/command/cmake_policy.rst +++ b/Help/command/cmake_policy.rst @@ -53,6 +53,8 @@ policy warning by setting the policy state to ``OLD``. Alternatively one may fix the project to work with the new behavior and set the policy state to ``NEW``. +.. include:: ../policy/DEPRECATED.txt + Checking Policy Settings ^^^^^^^^^^^^^^^^^^^^^^^^ 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/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/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..aefdb71 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 ----------------- @@ -627,7 +632,7 @@ may be enabled, with an equivalent effect to: .. code-block:: cmake - set_property(TARGET tgt APPEND PROPERTY + set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}> ) @@ -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..90a081d 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 ------------ @@ -894,7 +867,6 @@ look. find_path(Foo_INCLUDE_DIR NAMES foo.h PATHS ${PC_Foo_INCLUDE_DIRS} - # if you need to put #include <Foo/foo.h> in your code, add: PATH_SUFFIXES Foo ) find_library(Foo_LIBRARY 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 76058f9..c9219d5 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -127,7 +127,6 @@ All Modules /module/FindJava /module/FindJNI /module/FindJPEG - /module/FindJsonCpp /module/FindKDE3 /module/FindKDE4 /module/FindLAPACK @@ -213,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..0a313cd 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -20,11 +20,11 @@ for a policy, also avoiding the warning. Each policy can also be set to either ``NEW`` or ``OLD`` behavior explicitly on the command line with the :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable. -Note that policies are not reliable feature toggles. A policy should -almost never be set to ``OLD``, except to silence warnings in an otherwise -frozen or stable codebase, or temporarily as part of a larger migration -path. The ``OLD`` behavior of each policy is undesirable and will be -replaced with an error condition in a future release. +A policy is a deprecation mechanism and not a reliable feature toggle. +A policy should almost never be set to ``OLD``, except to silence warnings +in an otherwise frozen or stable codebase, or temporarily as part of a +larger migration path. The ``OLD`` behavior of each policy is undesirable +and will be replaced with an error condition in a future release. The :command:`cmake_minimum_required` command does more than report an error if a too-old version of CMake is used to build a project. It @@ -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/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/CMP0000.rst b/Help/policy/CMP0000.rst index 9fbf842..97ea633 100644 --- a/Help/policy/CMP0000.rst +++ b/Help/policy/CMP0000.rst @@ -28,3 +28,5 @@ a warning. An included file may set CMP0000 explicitly to affect how this policy is enforced for the main CMakeLists.txt file. This policy was introduced in CMake version 2.6.0. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0001.rst b/Help/policy/CMP0001.rst index 344f1e2..09ad387 100644 --- a/Help/policy/CMP0001.rst +++ b/Help/policy/CMP0001.rst @@ -17,3 +17,5 @@ below. This policy was introduced in CMake version 2.6.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0002.rst b/Help/policy/CMP0002.rst index 2c15bd4..7cc53ef 100644 --- a/Help/policy/CMP0002.rst +++ b/Help/policy/CMP0002.rst @@ -24,3 +24,5 @@ property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator). This policy was introduced in CMake version 2.6.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0003.rst b/Help/policy/CMP0003.rst index 27b83f8..16b0451 100644 --- a/Help/policy/CMP0003.rst +++ b/Help/policy/CMP0003.rst @@ -100,3 +100,5 @@ when setting the policy once will probably fix all targets. This policy was introduced in CMake version 2.6.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0004.rst b/Help/policy/CMP0004.rst index 80045f5..55da4d2 100644 --- a/Help/policy/CMP0004.rst +++ b/Help/policy/CMP0004.rst @@ -21,3 +21,5 @@ target is created by an add_executable or add_library command. This policy was introduced in CMake version 2.6.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0005.rst b/Help/policy/CMP0005.rst index c11a9e6..66d125f 100644 --- a/Help/policy/CMP0005.rst +++ b/Help/policy/CMP0005.rst @@ -22,3 +22,5 @@ limitations of the escaping implementation. This policy was introduced in CMake version 2.6.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0006.rst b/Help/policy/CMP0006.rst index 8d1e5bd..d1b9ece 100644 --- a/Help/policy/CMP0006.rst +++ b/Help/policy/CMP0006.rst @@ -20,3 +20,5 @@ without a BUNDLE DESTINATION. This policy was introduced in CMake version 2.6.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0007.rst b/Help/policy/CMP0007.rst index f0d8c16..3927645 100644 --- a/Help/policy/CMP0007.rst +++ b/Help/policy/CMP0007.rst @@ -13,3 +13,5 @@ empty elements in a list. This policy was introduced in CMake version 2.6.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0008.rst b/Help/policy/CMP0008.rst index b118ece..f1e2ddd 100644 --- a/Help/policy/CMP0008.rst +++ b/Help/policy/CMP0008.rst @@ -30,3 +30,5 @@ pass it directly to the native build tool unchanged. This policy was introduced in CMake version 2.6.1. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0009.rst b/Help/policy/CMP0009.rst index 481af1a..44baeb4 100644 --- a/Help/policy/CMP0009.rst +++ b/Help/policy/CMP0009.rst @@ -17,3 +17,5 @@ as an additional argument to the FILE command. This policy was introduced in CMake version 2.6.2. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst index 9d2eb76..344d704 100644 --- a/Help/policy/CMP0010.rst +++ b/Help/policy/CMP0010.rst @@ -16,3 +16,5 @@ and is treated as always being ``NEW``. This policy was introduced in CMake version 2.6.3. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0011.rst b/Help/policy/CMP0011.rst index 0f41fff..d281e0e 100644 --- a/Help/policy/CMP0011.rst +++ b/Help/policy/CMP0011.rst @@ -20,3 +20,5 @@ cmake_policy PUSH and POP. This policy was introduced in CMake version 2.6.3. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0012.rst b/Help/policy/CMP0012.rst index 7a749bf..85d64f4 100644 --- a/Help/policy/CMP0012.rst +++ b/Help/policy/CMP0012.rst @@ -23,3 +23,5 @@ dereferencing variables with such names. This policy was introduced in CMake version 2.8.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0013.rst b/Help/policy/CMP0013.rst index e99997b..2fabb89 100644 --- a/Help/policy/CMP0013.rst +++ b/Help/policy/CMP0013.rst @@ -17,3 +17,5 @@ with an error. This policy was introduced in CMake version 2.8.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0014.rst b/Help/policy/CMP0014.rst index 37178d1..f1f7b77 100644 --- a/Help/policy/CMP0014.rst +++ b/Help/policy/CMP0014.rst @@ -13,3 +13,5 @@ behavior for this policy is to report an error. This policy was introduced in CMake version 2.8.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0015.rst b/Help/policy/CMP0015.rst index 1b54979..9a48e3d 100644 --- a/Help/policy/CMP0015.rst +++ b/Help/policy/CMP0015.rst @@ -15,3 +15,5 @@ paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR. This policy was introduced in CMake version 2.8.1. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0016.rst b/Help/policy/CMP0016.rst index 743b1a9..cc898c8 100644 --- a/Help/policy/CMP0016.rst +++ b/Help/policy/CMP0016.rst @@ -11,3 +11,5 @@ in this case. This policy was introduced in CMake version 2.8.3. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0017.rst b/Help/policy/CMP0017.rst index f74e6f0..9f0f038 100644 --- a/Help/policy/CMP0017.rst +++ b/Help/policy/CMP0017.rst @@ -17,3 +17,5 @@ from the CMake modules directory. This policy was introduced in CMake version 2.8.4. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0018.rst b/Help/policy/CMP0018.rst index 0f68267..a3a7a12 100644 --- a/Help/policy/CMP0018.rst +++ b/Help/policy/CMP0018.rst @@ -30,3 +30,5 @@ honor the POSITION_INDEPENDENT_CODE target property. This policy was introduced in CMake version 2.8.9. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0019.rst b/Help/policy/CMP0019.rst index 2b37fa1..2e3557d 100644 --- a/Help/policy/CMP0019.rst +++ b/Help/policy/CMP0019.rst @@ -18,3 +18,5 @@ the values untouched. This policy was introduced in CMake version 2.8.11. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0020.rst b/Help/policy/CMP0020.rst index 6767d08..75ca9de 100644 --- a/Help/policy/CMP0020.rst +++ b/Help/policy/CMP0020.rst @@ -23,3 +23,5 @@ automatically when they link to QtCore IMPORTED target. This policy was introduced in CMake version 2.8.11. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0021.rst b/Help/policy/CMP0021.rst index 3f5bd03..3a792ca 100644 --- a/Help/policy/CMP0021.rst +++ b/Help/policy/CMP0021.rst @@ -16,3 +16,5 @@ relative path. This policy was introduced in CMake version 2.8.12. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0022.rst b/Help/policy/CMP0022.rst index 22c7c4f..579d09a 100644 --- a/Help/policy/CMP0022.rst +++ b/Help/policy/CMP0022.rst @@ -35,3 +35,5 @@ property for in-build targets, and ignore the old properties matching This policy was introduced in CMake version 2.8.12. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0023.rst b/Help/policy/CMP0023.rst index 962b624..76a4900 100644 --- a/Help/policy/CMP0023.rst +++ b/Help/policy/CMP0023.rst @@ -31,3 +31,5 @@ signatures. This policy was introduced in CMake version 2.8.12. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0024.rst b/Help/policy/CMP0024.rst index ee53d5f..272a56c 100644 --- a/Help/policy/CMP0024.rst +++ b/Help/policy/CMP0024.rst @@ -20,3 +20,5 @@ allow including the result of an export() command. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst index 8d19edf..62dd509 100644 --- a/Help/policy/CMP0025.rst +++ b/Help/policy/CMP0025.rst @@ -25,3 +25,5 @@ by default when this policy is not set and simply uses OLD behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst index 177b655..3fe1374 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 @@ -24,3 +24,5 @@ not to allow reading the LOCATION properties from build-targets. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0027.rst b/Help/policy/CMP0027.rst index bedaffe..28913ce 100644 --- a/Help/policy/CMP0027.rst +++ b/Help/policy/CMP0027.rst @@ -23,3 +23,5 @@ conditionally linked IMPORTED target does not exist. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst index 24889ec..be57125 100644 --- a/Help/policy/CMP0028.rst +++ b/Help/policy/CMP0028.rst @@ -21,3 +21,5 @@ double-colons but is not an IMPORTED target or an ALIAS target. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0029.rst b/Help/policy/CMP0029.rst index 8f58a12..aa10b97 100644 --- a/Help/policy/CMP0029.rst +++ b/Help/policy/CMP0029.rst @@ -8,3 +8,5 @@ but was kept in CMake for compatibility for a long time. .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0030.rst b/Help/policy/CMP0030.rst index 9e31b38..81bbb84 100644 --- a/Help/policy/CMP0030.rst +++ b/Help/policy/CMP0030.rst @@ -9,3 +9,5 @@ not used it in years. .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0031.rst b/Help/policy/CMP0031.rst index 6b89558..8c3eef6 100644 --- a/Help/policy/CMP0031.rst +++ b/Help/policy/CMP0031.rst @@ -11,3 +11,5 @@ the CMake process. It has been mostly superseded by the .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0032.rst b/Help/policy/CMP0032.rst index f394a06..5c1fa4b 100644 --- a/Help/policy/CMP0032.rst +++ b/Help/policy/CMP0032.rst @@ -11,3 +11,5 @@ functionality is better achieved through dedicated outside tools. .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0033.rst b/Help/policy/CMP0033.rst index b420065..4a6cc59 100644 --- a/Help/policy/CMP0033.rst +++ b/Help/policy/CMP0033.rst @@ -12,3 +12,5 @@ The functionality has been superseded by the :command:`export` and .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0034.rst b/Help/policy/CMP0034.rst index 2133997..0f3934a 100644 --- a/Help/policy/CMP0034.rst +++ b/Help/policy/CMP0034.rst @@ -9,3 +9,5 @@ generate other files. This approach has long been replaced by .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0035.rst b/Help/policy/CMP0035.rst index 7335b22..58199a4 100644 --- a/Help/policy/CMP0035.rst +++ b/Help/policy/CMP0035.rst @@ -8,3 +8,5 @@ logic. It has long been replaced by the :command:`if` command. .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0036.rst b/Help/policy/CMP0036.rst index 817f156..4bcfc54 100644 --- a/Help/policy/CMP0036.rst +++ b/Help/policy/CMP0036.rst @@ -10,3 +10,5 @@ and :variable:`CMAKE_<LANG>_COMPILER` variables. .. |disallowed_version| replace:: 3.0 .. include:: DISALLOWED_COMMAND.txt + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index 4d485bf..9f8457c 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -24,3 +24,5 @@ if an add_* command is used with an invalid target name. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0038.rst b/Help/policy/CMP0038.rst index df5af6a..a306d90 100644 --- a/Help/policy/CMP0038.rst +++ b/Help/policy/CMP0038.rst @@ -14,3 +14,5 @@ report an error if a target attempts to link to itself. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0039.rst b/Help/policy/CMP0039.rst index 58ccc41..97d78ae 100644 --- a/Help/policy/CMP0039.rst +++ b/Help/policy/CMP0039.rst @@ -15,3 +15,5 @@ utility target. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0040.rst b/Help/policy/CMP0040.rst index 77a3c81..e746c03 100644 --- a/Help/policy/CMP0040.rst +++ b/Help/policy/CMP0040.rst @@ -14,3 +14,5 @@ if the target referenced in :command:`add_custom_command` is unknown. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0041.rst b/Help/policy/CMP0041.rst index 5a47de0..f027d5d 100644 --- a/Help/policy/CMP0041.rst +++ b/Help/policy/CMP0041.rst @@ -23,3 +23,5 @@ relative. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0042.rst b/Help/policy/CMP0042.rst index fce870c..31314b2 100644 --- a/Help/policy/CMP0042.rst +++ b/Help/policy/CMP0042.rst @@ -17,3 +17,5 @@ variables. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0043.rst b/Help/policy/CMP0043.rst index 629e502..9e427c3 100644 --- a/Help/policy/CMP0043.rst +++ b/Help/policy/CMP0043.rst @@ -43,3 +43,5 @@ of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property . This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0044.rst b/Help/policy/CMP0044.rst index 4a3e215..02afa9f 100644 --- a/Help/policy/CMP0044.rst +++ b/Help/policy/CMP0044.rst @@ -17,3 +17,5 @@ the ``<LANG>_COMPILER_ID`` expression. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0045.rst b/Help/policy/CMP0045.rst index 58c422f..c7e1a90f6 100644 --- a/Help/policy/CMP0045.rst +++ b/Help/policy/CMP0045.rst @@ -15,3 +15,5 @@ non-existent target. This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0046.rst b/Help/policy/CMP0046.rst index 1a3bc65..576d1b1 100644 --- a/Help/policy/CMP0046.rst +++ b/Help/policy/CMP0046.rst @@ -15,3 +15,5 @@ This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0047.rst b/Help/policy/CMP0047.rst index 26ae439..882dd78 100644 --- a/Help/policy/CMP0047.rst +++ b/Help/policy/CMP0047.rst @@ -26,3 +26,5 @@ by default when this policy is not set and simply uses OLD behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0048.rst b/Help/policy/CMP0048.rst index a54205e..0e7e606 100644 --- a/Help/policy/CMP0048.rst +++ b/Help/policy/CMP0048.rst @@ -20,3 +20,5 @@ This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0049.rst b/Help/policy/CMP0049.rst index 5c8d4a8..a3ce4b1 100644 --- a/Help/policy/CMP0049.rst +++ b/Help/policy/CMP0049.rst @@ -21,3 +21,5 @@ This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0050.rst b/Help/policy/CMP0050.rst index 76ae0aa..39e40b6 100644 --- a/Help/policy/CMP0050.rst +++ b/Help/policy/CMP0050.rst @@ -16,3 +16,5 @@ This policy was introduced in CMake version 3.0. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0051.rst b/Help/policy/CMP0051.rst index 1b56cb0..6b679e5 100644 --- a/Help/policy/CMP0051.rst +++ b/Help/policy/CMP0051.rst @@ -22,3 +22,5 @@ This policy was introduced in CMake version 3.1. CMake version |release| warns when the policy is not set and uses ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0052.rst b/Help/policy/CMP0052.rst index 48cfc9c..0ea5ace 100644 --- a/Help/policy/CMP0052.rst +++ b/Help/policy/CMP0052.rst @@ -22,3 +22,5 @@ This policy was introduced in CMake version 3.1. CMake version |release| warns when the policy is not set and uses ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0053.rst b/Help/policy/CMP0053.rst index bb0ff8b..2620a60 100644 --- a/Help/policy/CMP0053.rst +++ b/Help/policy/CMP0053.rst @@ -42,3 +42,5 @@ This policy was introduced in CMake version 3.1. CMake version |release| warns when the policy is not set and uses ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0054.rst b/Help/policy/CMP0054.rst index 39f0c40..1e000a6 100644 --- a/Help/policy/CMP0054.rst +++ b/Help/policy/CMP0054.rst @@ -16,31 +16,37 @@ 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 ``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0055.rst b/Help/policy/CMP0055.rst index fe7ab6f..b3df758 100644 --- a/Help/policy/CMP0055.rst +++ b/Help/policy/CMP0055.rst @@ -15,3 +15,5 @@ This policy was introduced in CMake version 3.2. CMake version |release| warns when the policy is not set and uses OLD behavior. Use the cmake_policy command to set it to OLD or NEW explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0056.rst b/Help/policy/CMP0056.rst index 3c75ff4..3ba89d5 100644 --- a/Help/policy/CMP0056.rst +++ b/Help/policy/CMP0056.rst @@ -30,3 +30,5 @@ 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_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0057.rst b/Help/policy/CMP0057.rst new file mode 100644 index 0000000..83db186 --- /dev/null +++ b/Help/policy/CMP0057.rst @@ -0,0 +1,16 @@ +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0058.rst b/Help/policy/CMP0058.rst new file mode 100644 index 0000000..05efd48 --- /dev/null +++ b/Help/policy/CMP0058.rst @@ -0,0 +1,110 @@ +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0059.rst b/Help/policy/CMP0059.rst new file mode 100644 index 0000000..5da479a --- /dev/null +++ b/Help/policy/CMP0059.rst @@ -0,0 +1,19 @@ +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0060.rst b/Help/policy/CMP0060.rst new file mode 100644 index 0000000..8611aff --- /dev/null +++ b/Help/policy/CMP0060.rst @@ -0,0 +1,65 @@ +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0061.rst b/Help/policy/CMP0061.rst new file mode 100644 index 0000000..cb2ac28 --- /dev/null +++ b/Help/policy/CMP0061.rst @@ -0,0 +1,26 @@ +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0062.rst b/Help/policy/CMP0062.rst new file mode 100644 index 0000000..9047fff --- /dev/null +++ b/Help/policy/CMP0062.rst @@ -0,0 +1,29 @@ +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0063.rst b/Help/policy/CMP0063.rst new file mode 100644 index 0000000..d736d06 --- /dev/null +++ b/Help/policy/CMP0063.rst @@ -0,0 +1,28 @@ +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. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/DEPRECATED.txt b/Help/policy/DEPRECATED.txt new file mode 100644 index 0000000..f66de55 --- /dev/null +++ b/Help/policy/DEPRECATED.txt @@ -0,0 +1,4 @@ +.. note:: + The ``OLD`` behavior of a policy is + :manual:`deprecated by definition <cmake-policies(7)>` + and may be removed in a future version of CMake. 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_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/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/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 843d65d..8abb1ca 100644 --- a/Help/release/3.2.rst +++ b/Help/release/3.2.rst @@ -124,9 +124,6 @@ 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. diff --git a/Help/release/3.3.rst b/Help/release/3.3.rst new file mode 100644 index 0000000..0beb354 --- /dev/null +++ b/Help/release/3.3.rst @@ -0,0 +1,287 @@ +CMake 3.3 Release Notes +*********************** + +.. only:: html + + .. contents:: + +Changes made since CMake 3.2 include the following. + +New Features +============ + +Generators +---------- + +* The :ref:`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. + +* The :ref:`Visual Studio Generators` learned to support ``.xaml`` + source files and automatically associate them with corresponding + ``.h`` and ``.cpp`` sources. + +* 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 + +Commands +-------- + +* 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. + +* The :command:`execute_process` command learned to support specifying + the same file for ``OUTPUT_FILE`` and ``ERROR_FILE``. + +* 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. + +* The :command:`find_library`, :command:`find_path`, and :command:`find_file` + commands now search in installation prefixes derived from the ``PATH`` + environment variable. + +* The :command:`if` command learned a new ``IN_LIST`` operator that + evaluates to true if a given element is contained in a named list. + +* The :command:`install(EXPORT)` and :command:`export()` commands + learned to export targets that populate the :prop_tgt:`INTERFACE_SOURCES` + target property. + +* The :command:`install(TARGETS)` command learned to support + generator expressions in the ``DESTINATION`` value. + +Variables +--------- + +* The version of some Fortran compilers is now detected and stored in the + :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` + variable. + +* 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. + +Properties +---------- + +* 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. + +* A :prop_tgt:`<LANG>_INCLUDE_WHAT_YOU_USE` target property and supporting + :variable:`CMAKE_<LANG>_INCLUDE_WHAT_YOU_USE` variable were introduced + to tell the :ref:`Makefile Generators` and the :generator:`Ninja` generator + to run ``include-what-you-use`` along with the compiler for ``C`` and + ``CXX`` languages. + +* 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`. + +* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned + to support generator expressions. + +Modules +------- + +* The :module:`CheckFortranCompilerFlag` module was introduced + to check ``Fortran`` compiler flags, much like the + :module:`CheckCCompilerFlag` module already does for ``C``. + +* 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. + +* 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. + +* 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. + +* The :module:`ExternalProject` module learned to replace tokens + like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step. + +* 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. + +* The :module:`FindBoost` module now tracks the directories containing + libraries separately for RELEASE and DEBUG configurations. + +* 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. + +* 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. + +* The :module:`FindPackageHandleStandardArgs` module + ``FIND_PACKAGE_HANDLE_STANDARD_ARGS`` function now + always populates both the ``<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. + +* The :module:`InstallRequiredSystemLibraries` module learned a new + ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the + installation component. + +Generator Expressions +--------------------- + +* 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. + +CTest +----- + +* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>`` + option to help find sporadic test failures. + +* The :module:`CTestCoverageCollectGCOV` module learned to support + the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the + :command:`ctest_coverage` command. + +CPack +----- + +* The :manual:`cpack(1)` ``IFW`` generator and the :module:`CPackIFW` + module learned to support Qt Framework Installer 2.0 tools. + +* The :module:`CPackDeb` module learned a new + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_SHLIBDEPS` + variable to specify per-component use of ``dpkg-shlibdeps``. + +* The :module:`CPackDeb` module learned a new + :variable:`CPACK_DEBIAN_<COMPONENT>_PACKAGE_DEPENDS` + option to specify per-component dependencies. + +* The :module:`CPackRPM` module learned to package symbolic links + more cleanly and now supports directory symlinks with recent + ``rpmbuild`` versions. + +* 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. + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable + to specify a component-specific package architecture. + +* 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. + +Other +----- + +* 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. + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--format<format>`` option to specify the archive format to + be written. + +* 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. + +Deprecated and Removed Features +=============================== + +* 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 + +* 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`. + +* 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. + +* The :generator:`Visual Studio 7` generator (.NET 2002) is now + deprecated and will be removed in a future version of CMake. + +* The :generator:`Visual Studio 6` generator is now deprecated + and will be removed in a future version of CMake. + +* 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. + +* The :command:`add_definitions()` command no longer causes a + :prop_dir:`DEFINITIONS` directory property to be populated. See policy + :policy:`CMP0059`. + +* 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. + +* Using the output of :command:`export()` with the :command:`install(FILES)` + command is no longer allowed. See policy :policy:`CMP0062` for details. + +Other Changes +============= + +* 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`. + +* Build-time progress output of :ref:`Makefile Generators` 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). + +* 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. + +* 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``) and now links by full path. + See policy :policy:`CMP0060`. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst deleted file mode 100644 index e4cc01e..0000000 --- a/Help/release/dev/0-sample-topic.rst +++ /dev/null @@ -1,7 +0,0 @@ -0-sample-topic --------------- - -* This is a sample release note for the change in a topic. - Developers should add similar notes for each topic branch - making a noteworthy change. Each document should be named - and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/FindBoost-per-config-libraries.rst b/Help/release/dev/FindBoost-per-config-libraries.rst deleted file mode 100644 index e6ef70f..0000000 --- a/Help/release/dev/FindBoost-per-config-libraries.rst +++ /dev/null @@ -1,5 +0,0 @@ -FindBoost-per-config-libraries ------------------------------- - -* The :module:`FindBoost` module now tracks the directories containing - libraries separately for RELEASE and DEBUG configurations. diff --git a/Help/release/dev/add-CheckFortranCompilerFlag.rst b/Help/release/dev/add-CheckFortranCompilerFlag.rst deleted file mode 100644 index 718b53e..0000000 --- a/Help/release/dev/add-CheckFortranCompilerFlag.rst +++ /dev/null @@ -1,6 +0,0 @@ -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/compiler-version-Fortran.rst b/Help/release/dev/compiler-version-Fortran.rst deleted file mode 100644 index e10b206..0000000 --- a/Help/release/dev/compiler-version-Fortran.rst +++ /dev/null @@ -1,6 +0,0 @@ -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/export-interface-source-files.rst b/Help/release/dev/export-interface-source-files.rst deleted file mode 100644 index 00dcd25..0000000 --- a/Help/release/dev/export-interface-source-files.rst +++ /dev/null @@ -1,6 +0,0 @@ -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/install-DESTINATION-genex.rst b/Help/release/dev/install-DESTINATION-genex.rst deleted file mode 100644 index 4c4bbed..0000000 --- a/Help/release/dev/install-DESTINATION-genex.rst +++ /dev/null @@ -1,5 +0,0 @@ -install-DESTINATION-genex -------------------------- - -* The :command:`install(TARGETS)` command learned to support - generator expressions in the ``DESTINATION`` value. diff --git a/Help/release/dev/makefile-progress-improvements.rst b/Help/release/dev/makefile-progress-improvements.rst deleted file mode 100644 index 9cc9706..0000000 --- a/Help/release/dev/makefile-progress-improvements.rst +++ /dev/null @@ -1,7 +0,0 @@ -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/xcode-attribute-genex.rst b/Help/release/dev/xcode-attribute-genex.rst deleted file mode 100644 index 3fd5b1c..0000000 --- a/Help/release/dev/xcode-attribute-genex.rst +++ /dev/null @@ -1,5 +0,0 @@ -xcode-attribute-genex ---------------------- - -* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned - to support generator expressions. diff --git a/Help/release/index.rst b/Help/release/index.rst index 45d0a69..6b98e48 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,14 +5,13 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. -.. include:: dev.txt - Releases ======== .. toctree:: :maxdepth: 1 + 3.3 <3.3> 3.2 <3.2> 3.1 <3.1> 3.0 <3.0> diff --git a/Help/variable/CMAKE_APPBUNDLE_PATH.rst b/Help/variable/CMAKE_APPBUNDLE_PATH.rst index 469b316..2bc79ac 100644 --- a/Help/variable/CMAKE_APPBUNDLE_PATH.rst +++ b/Help/variable/CMAKE_APPBUNDLE_PATH.rst @@ -1,5 +1,6 @@ CMAKE_APPBUNDLE_PATH -------------------- -Search path for OS X application bundles used by the :command:`find_program`, -and :command:`find_package` commands. +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for OS X application bundles used by the :command:`find_program`, and +:command:`find_package` commands. 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_FIND_ROOT_PATH.rst b/Help/variable/CMAKE_FIND_ROOT_PATH.rst index 67948f7..ccf5234 100644 --- a/Help/variable/CMAKE_FIND_ROOT_PATH.rst +++ b/Help/variable/CMAKE_FIND_ROOT_PATH.rst @@ -1,7 +1,7 @@ CMAKE_FIND_ROOT_PATH -------------------- -List of root paths to search on the filesystem. +:ref:`;-list <CMake Language Lists>` of root paths to search on the filesystem. This variable is most useful when cross-compiling. CMake uses the paths in this list as alternative roots to find filesystem items with :command:`find_package`, diff --git a/Help/variable/CMAKE_FRAMEWORK_PATH.rst b/Help/variable/CMAKE_FRAMEWORK_PATH.rst index f1bc75e..5ff08e6 100644 --- a/Help/variable/CMAKE_FRAMEWORK_PATH.rst +++ b/Help/variable/CMAKE_FRAMEWORK_PATH.rst @@ -1,6 +1,7 @@ CMAKE_FRAMEWORK_PATH -------------------- -Search path for OS X frameworks used by the :command:`find_library`, +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for OS X frameworks used by the :command:`find_library`, :command:`find_package`, :command:`find_path`, and :command:`find_file` commands. diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst index 5809b6a..5559eb7 100644 --- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -5,7 +5,7 @@ Generator-specific target platform name specified by user. Some CMake generators support a target platform name to be given to the native build system to choose a compiler toolchain. -If the user specifies a toolset name (e.g. via the cmake -A option) +If the user specifies a platform name (e.g. via the cmake -A option) the value will be available in this variable. The value of this variable should never be modified by project code. diff --git a/Help/variable/CMAKE_IGNORE_PATH.rst b/Help/variable/CMAKE_IGNORE_PATH.rst index a818f74..92f3770 100644 --- a/Help/variable/CMAKE_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_IGNORE_PATH.rst @@ -1,17 +1,18 @@ CMAKE_IGNORE_PATH ----------------- -Path to be ignored by FIND_XXX() commands. +:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by +the :command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path` commands. This is useful in cross-compiling +environments where some system directories contain incompatible but +possibly linkable libraries. For example, on cross-compiled cluster +environments, this allows a user to ignore directories containing +libraries meant for the front-end machine. -Specifies directories to be ignored by searches in FIND_XXX() -commands. This is useful in cross-compiled environments where some -system directories contain incompatible but possibly linkable -libraries. For example, on cross-compiled cluster environments, this -allows a user to ignore directories containing libraries meant for the -front-end machine that modules like FindX11 (and others) would -normally search. By default this is empty; it is intended to be set -by the project. Note that CMAKE_IGNORE_PATH takes a list of directory -names, NOT a list of prefixes. If you want to ignore paths under -prefixes (bin, include, lib, etc.), you'll need to specify them -explicitly. See also CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH, -CMAKE_INCLUDE_PATH, CMAKE_PROGRAM_PATH. +By default this is empty; it is intended to be set by the project. +Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not* +a list of prefixes. To ignore paths under prefixes (``bin``, ``include``, +``lib``, etc.), specify them explicitly. + +See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`, +:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables. diff --git a/Help/variable/CMAKE_INCLUDE_PATH.rst b/Help/variable/CMAKE_INCLUDE_PATH.rst index 360b403..e4e7f2c 100644 --- a/Help/variable/CMAKE_INCLUDE_PATH.rst +++ b/Help/variable/CMAKE_INCLUDE_PATH.rst @@ -1,10 +1,7 @@ CMAKE_INCLUDE_PATH ------------------ -Path used for searching by FIND_FILE() and FIND_PATH(). - -Specifies a path which will be used both by FIND_FILE() and -FIND_PATH(). Both commands will check each of the contained -directories for the existence of the file which is currently searched. -By default it is empty, it is intended to be set by the project. See -also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_PREFIX_PATH. +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_file` and :command:`find_path` commands. By default it +is empty, it is intended to be set by the project. See also +:variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`. 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_LIBRARY_PATH.rst b/Help/variable/CMAKE_LIBRARY_PATH.rst index e77dd34..b1770dc 100644 --- a/Help/variable/CMAKE_LIBRARY_PATH.rst +++ b/Help/variable/CMAKE_LIBRARY_PATH.rst @@ -1,10 +1,7 @@ CMAKE_LIBRARY_PATH ------------------ -Path used for searching by FIND_LIBRARY(). - -Specifies a path which will be used by FIND_LIBRARY(). FIND_LIBRARY() -will check each of the contained directories for the existence of the -library which is currently searched. By default it is empty, it is +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_library` command. By default it is empty, it is intended to be set by the project. See also -CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_PREFIX_PATH. +:variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`. 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_MODULE_PATH.rst b/Help/variable/CMAKE_MODULE_PATH.rst index a2dde45..5ea7cbb 100644 --- a/Help/variable/CMAKE_MODULE_PATH.rst +++ b/Help/variable/CMAKE_MODULE_PATH.rst @@ -1,8 +1,7 @@ CMAKE_MODULE_PATH ----------------- -List of directories to search for CMake modules. - -Commands like include() and find_package() search for files in -directories listed by this variable before checking the default -modules that come with CMake. +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for CMake modules to be loaded by the the :command:`include` or +:command:`find_package` commands before checking the default modules that come +with CMake. By default it is empty, it is intended to be set by the project. 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_PREFIX_PATH.rst b/Help/variable/CMAKE_PREFIX_PATH.rst index 4c21d5e..c2a4a60 100644 --- a/Help/variable/CMAKE_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_PREFIX_PATH.rst @@ -1,13 +1,15 @@ CMAKE_PREFIX_PATH ----------------- -Path used for searching by FIND_XXX(), with appropriate suffixes added. +:ref:`;-list <CMake Language Lists>` of directories specifying installation +*prefixes* to be searched by the :command:`find_package`, +:command:`find_program`, :command:`find_library`, :command:`find_file`, and +:command:`find_path` commands. Each command will add appropriate +subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own +documentation. -Specifies a path which will be used by the FIND_XXX() commands. It -contains the "base" directories, the FIND_XXX() commands append -appropriate subdirectories to the base directories. So FIND_PROGRAM() -adds /bin to each of the directories in the path, FIND_LIBRARY() -appends /lib to each of the directories, and FIND_PATH() and -FIND_FILE() append /include . By default it is empty, it is intended -to be set by the project. See also CMAKE_SYSTEM_PREFIX_PATH, -CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH. +By default this is empty. It is intended to be set by the project. + +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`, :variable:`CMAKE_INCLUDE_PATH`, +:variable:`CMAKE_LIBRARY_PATH`, :variable:`CMAKE_PROGRAM_PATH`, and +:variable:`CMAKE_IGNORE_PATH`. diff --git a/Help/variable/CMAKE_PROGRAM_PATH.rst b/Help/variable/CMAKE_PROGRAM_PATH.rst index 02c5e02..799e119 100644 --- a/Help/variable/CMAKE_PROGRAM_PATH.rst +++ b/Help/variable/CMAKE_PROGRAM_PATH.rst @@ -1,10 +1,7 @@ CMAKE_PROGRAM_PATH ------------------ -Path used for searching by FIND_PROGRAM(). - -Specifies a path which will be used by FIND_PROGRAM(). FIND_PROGRAM() -will check each of the contained directories for the existence of the -program which is currently searched. By default it is empty, it is +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_program` command. By default it is empty, it is intended to be set by the project. See also -CMAKE_SYSTEM_PROGRAM_PATH, CMAKE_PREFIX_PATH. +:variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`. 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_IGNORE_PATH.rst b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst index 9e6b195..4ad7e33 100644 --- a/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst @@ -1,15 +1,18 @@ CMAKE_SYSTEM_IGNORE_PATH ------------------------ -Path to be ignored by FIND_XXX() commands. +:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by +the :command:`find_program`, :command:`find_library`, :command:`find_file`, +and :command:`find_path` commands. This is useful in cross-compiling +environments where some system directories contain incompatible but +possibly linkable libraries. For example, on cross-compiled cluster +environments, this allows a user to ignore directories containing +libraries meant for the front-end machine. -Specifies directories to be ignored by searches in FIND_XXX() -commands. This is useful in cross-compiled environments where some -system directories contain incompatible but possibly linkable -libraries. For example, on cross-compiled cluster environments, this -allows a user to ignore directories containing libraries meant for the -front-end machine that modules like FindX11 (and others) would -normally search. By default this contains a list of directories -containing incompatible binaries for the host system. See also -CMAKE_SYSTEM_PREFIX_PATH, CMAKE_SYSTEM_LIBRARY_PATH, -CMAKE_SYSTEM_INCLUDE_PATH, and CMAKE_SYSTEM_PROGRAM_PATH. +By default this contains a list of directories containing incompatible +binaries for the host system. See the :variable:`CMAKE_IGNORE_PATH` variable +that is intended to be set by the project. + +See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`, +:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, +and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables. diff --git a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst index 1734185..2c14345 100644 --- a/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst @@ -1,11 +1,8 @@ CMAKE_SYSTEM_INCLUDE_PATH ------------------------- -Path used for searching by FIND_FILE() and FIND_PATH(). - -Specifies a path which will be used both by FIND_FILE() and -FIND_PATH(). Both commands will check each of the contained -directories for the existence of the file which is currently searched. -By default it contains the standard directories for the current -system. It is NOT intended to be modified by the project, use -CMAKE_INCLUDE_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH. +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_file` and :command:`find_path` commands. By default +this contains the standard directories for the current system. It is *not* +intended to be modified by the project; use :variable:`CMAKE_INCLUDE_PATH` for +this. See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst index 4778646..3969cb9 100644 --- a/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst @@ -1,11 +1,8 @@ CMAKE_SYSTEM_LIBRARY_PATH ------------------------- -Path used for searching by FIND_LIBRARY(). - -Specifies a path which will be used by FIND_LIBRARY(). FIND_LIBRARY() -will check each of the contained directories for the existence of the -library which is currently searched. By default it contains the -standard directories for the current system. It is NOT intended to be -modified by the project, use CMAKE_LIBRARY_PATH for this. See also -CMAKE_SYSTEM_PREFIX_PATH. +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_library` command. By default this contains the +standard directories for the current system. It is *not* intended to be +modified by the project; use :variable:`CMAKE_LIBRARY_PATH` for this. +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst index 537eaba..e74dfad 100644 --- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst @@ -1,16 +1,18 @@ CMAKE_SYSTEM_PREFIX_PATH ------------------------ -Path used for searching by FIND_XXX(), with appropriate suffixes added. +:ref:`;-list <CMake Language Lists>` of directories specifying installation +*prefixes* to be searched by the :command:`find_package`, +:command:`find_program`, :command:`find_library`, :command:`find_file`, and +:command:`find_path` commands. Each command will add appropriate +subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own +documentation. -Specifies a path which will be used by the FIND_XXX() commands. It -contains the "base" directories, the FIND_XXX() commands append -appropriate subdirectories to the base directories. So FIND_PROGRAM() -adds /bin to each of the directories in the path, FIND_LIBRARY() -appends /lib to each of the directories, and FIND_PATH() and -FIND_FILE() append /include . By default this contains the standard -directories for the current system, the CMAKE_INSTALL_PREFIX and -the :variable:`CMAKE_STAGING_PREFIX`. It is NOT intended to be modified by -the project, use CMAKE_PREFIX_PATH for this. See also CMAKE_SYSTEM_INCLUDE_PATH, -CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PROGRAM_PATH, and -CMAKE_SYSTEM_IGNORE_PATH. +By default this contains the standard directories for the current system, the +:variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`. +It is *not* intended to be modified by the project; use +:variable:`CMAKE_PREFIX_PATH` for this. + +See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH`, +:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_PROGRAM_PATH`, +and :variable:`CMAKE_SYSTEM_IGNORE_PATH`. 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_SYSTEM_PROGRAM_PATH.rst b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst index e1fad63..cf1b83e 100644 --- a/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst +++ b/Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst @@ -1,11 +1,8 @@ CMAKE_SYSTEM_PROGRAM_PATH ------------------------- -Path used for searching by FIND_PROGRAM(). - -Specifies a path which will be used by FIND_PROGRAM(). FIND_PROGRAM() -will check each of the contained directories for the existence of the -program which is currently searched. By default it contains the -standard directories for the current system. It is NOT intended to be -modified by the project, use CMAKE_PROGRAM_PATH for this. See also -CMAKE_SYSTEM_PREFIX_PATH. +:ref:`;-list <CMake Language Lists>` of directories specifying a search path +for the :command:`find_program` command. By default this contains the +standard directories for the current system. It is *not* intended to be +modified by the project; use :variable:`CMAKE_PROGRAM_PATH` for this. +See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`. 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 |