diff options
Diffstat (limited to 'Help')
128 files changed, 1250 insertions, 471 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt index 5889e90..9358329 100644 --- a/Help/command/FIND_XXX.txt +++ b/Help/command/FIND_XXX.txt @@ -53,6 +53,10 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows: .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace:: <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH +.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace:: + <prefix>/|XXX_SUBDIR| for each <prefix>/[s]bin in PATH, and + <entry>/|XXX_SUBDIR| for other entries in PATH + .. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace:: <prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH diff --git a/Help/command/add_dependencies.rst b/Help/command/add_dependencies.rst index 10997ec..c3583cf 100644 --- a/Help/command/add_dependencies.rst +++ b/Help/command/add_dependencies.rst @@ -7,13 +7,16 @@ 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. -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/ctest_build.rst b/Help/command/ctest_build.rst index 4a95cdd..e7a54d1 100644 --- a/Help/command/ctest_build.rst +++ b/Help/command/ctest_build.rst @@ -23,6 +23,11 @@ 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 QUIET option suppresses 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. + 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 diff --git a/Help/command/ctest_configure.rst b/Help/command/ctest_configure.rst index 2c4e305..61d9320 100644 --- a/Help/command/ctest_configure.rst +++ b/Help/command/ctest_configure.rst @@ -6,7 +6,7 @@ Configure the project build tree. :: ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND] - [OPTIONS options] [RETURN_VALUE res]) + [OPTIONS options] [RETURN_VALUE res] [QUIET]) Configures the given build directory and stores results in Configure.xml. If no BUILD is given, the CTEST_BINARY_DIRECTORY @@ -19,3 +19,7 @@ build tool. 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 QUIET option suppresses 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..bac5c1c 100644 --- a/Help/command/ctest_coverage.rst +++ b/Help/command/ctest_coverage.rst @@ -18,3 +18,8 @@ files labeled with at least one of the labels specified. 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 QUIET option suppresses 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..56a2490 100644 --- a/Help/command/ctest_memcheck.rst +++ b/Help/command/ctest_memcheck.rst @@ -26,3 +26,7 @@ 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. + +The QUIET option suppresses any CTest-specific non-error messages +that would have otherwise been printed to the console. Output from +the underlying tests are not affected. 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..6fa1191 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -9,6 +9,7 @@ Submit results to a dashboard server. [RETRY_COUNT count] [RETRY_DELAY delay] [RETURN_VALUE res] + [QUIET] ) By default all available parts are submitted if no PARTS or FILES are @@ -38,6 +39,9 @@ timed-out submission before attempting to re-submit. The RETRY_COUNT option specifies how many times to retry a timed-out submission. +The QUIET option suppresses all non-error messages that would have +otherwise been printed by this call to ctest_submit(). + Submit to CDash Upload API ^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Help/command/ctest_test.rst b/Help/command/ctest_test.rst index 5f28083..ee76e91 100644 --- a/Help/command/ctest_test.rst +++ b/Help/command/ctest_test.rst @@ -31,3 +31,9 @@ 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. + +The QUIET option suppresses 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..01e357b 100644 --- a/Help/command/ctest_update.rst +++ b/Help/command/ctest_update.rst @@ -5,9 +5,14 @@ Update the work tree from version control. :: - ctest_update([SOURCE source] [RETURN_VALUE res]) + ctest_update([SOURCE source] [RETURN_VALUE res] [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. + +If QUIET is specified then CTest will 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..fcd9fe4 100644 --- a/Help/command/ctest_upload.rst +++ b/Help/command/ctest_upload.rst @@ -5,7 +5,10 @@ Upload files to a dashboard server. :: - ctest_upload(FILES ...) + ctest_upload(FILES ... [QUIET]) Pass a list of files to be sent along with the build results to the dashboard server. + +The QUIET option suppresses any CTest-specific non-error output +that would have been printed to the console otherwise. diff --git a/Help/command/file.rst b/Help/command/file.rst index 73d4cfa..2fe7414 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 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..09df688 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 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/install.rst b/Help/command/install.rst index 5dd5aaa..c99ed73 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -159,6 +159,10 @@ file itself, call ``install(EXPORT)``, documented below. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. +The install destination given to the target install ``DESTINATION`` may +use "generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available expressions. + Installing Files ^^^^^^^^^^^^^^^^ diff --git a/Help/command/macro.rst b/Help/command/macro.rst index 258dc50..6bee69c 100644 --- a/Help/command/macro.rst +++ b/Help/command/macro.rst @@ -1,9 +1,7 @@ macro ----- -Start recording a macro for later invocation as a command. - -:: +Start recording a macro for later invocation as a command:: macro(<name> [arg1 [arg2 [arg3 ...]]]) COMMAND1(ARGS ...) @@ -11,22 +9,28 @@ Start recording a macro for later invocation as a command. ... endmacro(<name>) -Define a macro named <name> that takes arguments named arg1 arg2 arg3 -(...). Commands listed after macro, but before the matching endmacro, -are not invoked until the macro is invoked. When it is invoked, the -commands recorded in the macro are first modified by replacing formal -parameters (``${arg1}``) with the arguments passed, and then invoked as -normal commands. In addition to referencing the formal parameters you -can reference the values ``${ARGC}`` which will be set to the number of -arguments passed into the function as well as ``${ARGV0}`` ``${ARGV1}`` -``${ARGV2}`` ... which will have the actual values of the arguments -passed in. This facilitates creating macros with optional arguments. +Define a macro named ``<name>`` that takes arguments named ``arg1``, +``arg2``, ``arg3``, (...). +Commands listed after macro, but before the matching +:command:`endmacro()`, are not invoked until the macro is invoked. +When it is invoked, the commands recorded in the macro are first +modified by replacing formal parameters (``${arg1}``) with the arguments +passed, and then invoked as normal commands. +In addition to referencing the formal parameters you can reference the +values ``${ARGC}`` which will be set to the number of arguments passed +into the function as well as ``${ARGV0}``, ``${ARGV1}``, ``${ARGV2}``, +... which will have the actual values of the arguments passed in. +This facilitates creating macros with optional arguments. Additionally ``${ARGV}`` holds the list of all arguments given to the macro and ``${ARGN}`` holds the list of arguments past the last expected argument. +Referencing to ``${ARGV#}`` arguments beyond ``${ARGC}`` have undefined +behavior. Checking that ``${ARGC}`` is greater than ``#`` is the only +way to ensure that ``${ARGV#}`` was passed to the function as an extra +argument. -See the cmake_policy() command documentation for the behavior of -policies inside macros. +See the :command:`cmake_policy()` command documentation for the behavior +of policies inside macros. Macro Argument Caveats ^^^^^^^^^^^^^^^^^^^^^^ @@ -37,10 +41,15 @@ replacements much like the C preprocessor would do with a macro. Therefore you will NOT be able to use commands like:: if(ARGV1) # ARGV1 is not a variable + if(DEFINED ARGV2) # ARGV2 is not a variable + if(ARGC GREATER 2) # ARGC is not a variable foreach(loop_var IN LISTS ARGN) # ARGN is not a variable -In the first case you can use ``if(${ARGV1})``, in the second case, you can -use ``foreach(loop_var ${ARGN})`` but this will skip empty arguments. +In the first case, you can use ``if(${ARGV1})``. +In the second and third case, the proper way to check if an optional +variable was passed to the macro is to use ``if(${ARGC} GREATER 2)``. +In the last case, you can use ``foreach(loop_var ${ARGN})`` but this +will skip empty arguments. If you need to include them, you can use:: set(list_var "${ARGN}") diff --git a/Help/command/set.rst b/Help/command/set.rst index 7a59550..d04b880 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -1,116 +1,89 @@ set --- -Set a CMake, cache or environment variable to a given value. +Set a normal, cache, or environment variable to a given value. +See the :ref:`cmake-language(7) variables <CMake Language Variables>` +documentation for the scopes and interaction of normal variables +and cache entries. + +Signatures of this command that specify a ``<value>...`` placeholder +expect zero or more arguments. Multiple arguments will be joined as +a :ref:`;-list <CMake Language Lists>` to form the actual variable +value to be set. Zero arguments will cause normal variables to be +unset. See the :command:`unset` command to unset variables explicitly. + +Set Normal Variable +^^^^^^^^^^^^^^^^^^^ :: - set(<variable> <value> - [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE]) + set(<variable> <value>... [PARENT_SCOPE]) + +Set the given ``<variable>`` in the current function or directory scope. -Within CMake sets <variable> to the value <value>. <value> is -expanded before <variable> is set to it. Normally, set will set a -regular CMake variable. If CACHE is present, then the <variable> is -put in the cache instead, unless it is already in the cache. See -section 'Variable types in CMake' below for details of regular and -cache variables and their interactions. If CACHE is used, <type> and -<docstring> are required. <type> is used by the CMake GUI to choose a -widget with which the user sets a value. The value for <type> may be -one of +If the ``PARENT_SCOPE`` option is given the variable will be set in +the scope above the current scope. Each new directory or function +creates a new scope. This command will set the value of a variable +into the parent directory or calling function (whichever is applicable +to the case at hand). + +Set Cache Entry +^^^^^^^^^^^^^^^ :: - FILEPATH = File chooser dialog. - PATH = Directory chooser dialog. - STRING = Arbitrary string. - BOOL = Boolean ON/OFF checkbox. - INTERNAL = No GUI entry (used for persistent variables). + set(<variable> <value>... CACHE <type> <docstring> [FORCE]) -If <type> is INTERNAL, the cache variable is marked as internal, and -will not be shown to the user in tools like cmake-gui. This is -intended for values that should be persisted in the cache, but which -users should not normally change. INTERNAL implies FORCE. +Set the given cache ``<variable>`` (cache entry). Since cache entries +are meant to provide user-settable values this does not overwrite +existing cache entries by default. Use the ``FORCE`` option to +overwrite existing entries. -Normally, set(...CACHE...) creates cache variables, but does not -modify them. If FORCE is specified, the value of the cache variable -is set, even if the variable is already in the cache. This should -normally be avoided, as it will remove any changes to the cache -variable's value by the user. +The ``<type>`` must be specified as one of: -If PARENT_SCOPE is present, the variable will be set in the scope -above the current scope. Each new directory or function creates a new -scope. This command will set the value of a variable into the parent -directory or calling function (whichever is applicable to the case at -hand). PARENT_SCOPE cannot be combined with CACHE. +``BOOL`` + Boolean ``ON/OFF`` value. :manual:`cmake-gui(1)` offers a checkbox. -If <value> is not specified then the variable is removed instead of -set. See also: the unset() command. +``FILEPATH`` + Path to a file on disk. :manual:`cmake-gui(1)` offers a file dialog. -:: +``PATH`` + Path to a directory on disk. :manual:`cmake-gui(1)` offers a file dialog. - set(<variable> <value1> ... <valueN>) +``STRING`` + A line of text. :manual:`cmake-gui(1)` offers a text field or a + drop-down selection if the :prop_cache:`STRINGS` cache entry + property is set. -In this case <variable> is set to a semicolon separated list of -values. +``INTERNAL`` + A line of text. :manual:`cmake-gui(1)` does not show internal entries. + They may be used to store variables persistently across runs. + Use of this type implies ``FORCE``. -<variable> can be an environment variable such as: +The ``<docstring>`` must be specified as a line of text providing +a quick summary of the option for presentation to :manual:`cmake-gui(1)` +users. + +If the cache entry does not exist prior to the call or the ``FORCE`` +option is given then the cache entry will be set to the given value. +Furthermore, any normal variable binding in the current scope will +be removed to expose the newly cached value to any immediately +following evaluation. + +It is possible for the cache entry to exist prior to the call but +have no type set if it was created on the :manual:`cmake(1)` command +line by a user through the ``-D<var>=<value>`` option without +specifying a type. In this case the ``set`` command will add the +type. Furthermore, if the ``<type>`` is ``PATH`` or ``FILEPATH`` +and the ``<value>`` provided on the command line is a relative path, +then the ``set`` command will treat the path as relative to the +current working directory and convert it to an absolute path. + +Set Environment Variable +^^^^^^^^^^^^^^^^^^^^^^^^ :: - set( ENV{PATH} /home/martink ) - -in which case the environment variable will be set. - -*** Variable types in CMake *** - -In CMake there are two types of variables: normal variables and cache -variables. Normal variables are meant for the internal use of the -script (just like variables in most programming languages); they are -not persisted across CMake runs. Cache variables (unless set with -INTERNAL) are mostly intended for configuration settings where the -first CMake run determines a suitable default value, which the user -can then override, by editing the cache with tools such as ccmake or -cmake-gui. Cache variables are stored in the CMake cache file, and -are persisted across CMake runs. - -Both types can exist at the same time with the same name but different -values. When ${FOO} is evaluated, CMake first looks for a normal -variable 'FOO' in scope and uses it if set. If and only if no normal -variable exists then it falls back to the cache variable 'FOO'. - -Some examples: - -The code 'set(FOO "x")' sets the normal variable 'FOO'. It does not -touch the cache, but it will hide any existing cache value 'FOO'. - -The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache, -ignoring any normal variable of the same name. If 'FOO' is in the -cache then nothing happens to either the normal variable or the cache -variable. If 'FOO' is not in the cache, then it is added to the -cache. - -Finally, whenever a cache variable is added or modified by a command, -CMake also *removes* the normal variable of the same name from the -current scope so that an immediately following evaluation of it will -expose the newly cached value. - -Normally projects should avoid using normal and cache variables of the -same name, as this interaction can be hard to follow. However, in -some situations it can be useful. One example (used by some -projects): - -A project has a subproject in its source tree. The child project has -its own CMakeLists.txt, which is included from the parent -CMakeLists.txt using add_subdirectory(). Now, if the parent and the -child project provide the same option (for example a compiler option), -the parent gets the first chance to add a user-editable option to the -cache. Normally, the child would then use the same value that the -parent uses. However, it may be necessary to hard-code the value for -the child project's option while still allowing the user to edit the -value used by the parent project. The parent project can achieve this -simply by setting a normal variable with the same name as the option -in a scope sufficient to hide the option's cache variable from the -child completely. The parent has already set the cache variable, so -the child's set(...CACHE...) will do nothing, and evaluating the -option variable will use the value from the normal variable, which -hides the cache variable. + set(ENV{<variable>} <value>...) + +Set the current process environment ``<variable>`` to the given value. diff --git a/Help/command/set_directory_properties.rst b/Help/command/set_directory_properties.rst index 834013a..e485fce 100644 --- a/Help/command/set_directory_properties.rst +++ b/Help/command/set_directory_properties.rst @@ -7,9 +7,6 @@ Set a property of the directory. set_directory_properties(PROPERTIES prop1 value1 prop2 value2) -Set a property for the current directory and subdirectories. If the -property is not found, CMake will report an error. The properties -include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES, -INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES. -ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be cleaned as -a part of "make clean" stage. +Set a property for the current directory and subdirectories. See +:ref:`Directory Properties` for the list of properties known +to CMake. diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index 8ea02a3..b4904e8 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -10,6 +10,6 @@ Source files can have properties that affect how they are built. [prop2 value2 [...]]) Set properties associated with source files using a key/value paired -list. See properties documentation for those known to CMake. -Unrecognized properties are ignored. Source file properties are -visible only to targets added in the same directory (CMakeLists.txt). +list. See :ref:`Source File Properties` for the list of properties known +to CMake. Source file properties are visible only to targets added +in the same directory (CMakeLists.txt). diff --git a/Help/command/set_tests_properties.rst b/Help/command/set_tests_properties.rst index afac847..3efb165 100644 --- a/Help/command/set_tests_properties.rst +++ b/Help/command/set_tests_properties.rst @@ -8,29 +8,7 @@ Set a property of the tests. set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2) Set a property for the tests. If the test is not found, CMake -will report an error. Generator expressions will be expanded the same -as supported by the test's add_test call. The properties include: - -WILL_FAIL: If set to true, this will invert the pass/fail flag of the -test. - -PASS_REGULAR_EXPRESSION: If set, the test output will be checked -against the specified regular expressions and at least one of the -regular expressions has to match, otherwise the test will fail. - -:: - - Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok" - -FAIL_REGULAR_EXPRESSION: If set, if the output will match to one of -specified regular expressions, the test will fail. - -:: - - Example: FAIL_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed" - -Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect a list -of regular expressions. - -TIMEOUT: Setting this will limit the test runtime to the number of -seconds specified. +will report an error. +:manual:`Generator expressions <cmake-generator-expressions(7)>` will be +expanded the same as supported by the test's :command:`add_test` call. See +:ref:`Test Properties` for the list of properties known to CMake. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index 3c9fe87..8bd3233 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -9,7 +9,7 @@ Add compile definitions to a target. <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify compile definitions to use when compiling a given <target. The +Specify compile definitions to use when compiling a given ``<target>``. The named ``<target>`` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`Imported Target <Imported Targets>`. diff --git a/Help/command/target_compile_features.rst b/Help/command/target_compile_features.rst index 29a8b41..b66a4ec 100644 --- a/Help/command/target_compile_features.rst +++ b/Help/command/target_compile_features.rst @@ -29,4 +29,4 @@ Arguments to ``target_compile_features`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-compile-features(7)` manual for -information on compile features. +information on compile features and a list of supported compilers. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 3362c5d..73e01e7 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -20,8 +20,8 @@ alternative commands exist to add preprocessor definitions (:command:`target_compile_definitions` and :command:`add_definitions`) or include directories (:command:`target_include_directories` and :command:`include_directories`). See documentation of the -:prop_tgt:`directory <COMPILE_OPTIONS>` and -:prop_tgt:` target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. +:prop_dir:`directory <COMPILE_OPTIONS>` and +:prop_tgt:`target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 1d236ce..30ec2cb 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -55,5 +55,8 @@ installation prefix. For example: $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib ) +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index e6a82b6..d903d05 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -1,38 +1,113 @@ target_link_libraries --------------------- -Link a target to given libraries. +.. only:: html + + .. contents:: + +Specify libraries or flags to use when linking a given target and/or +its dependents. :ref:`Usage requirements <Target Usage Requirements>` +from linked library targets will be propagated. Usage requirements +of a target's dependencies affect compilation of its own sources. + +Overview +^^^^^^^^ + +This command has several signatures as detailed in subsections below. +All of them have the general form:: + + target_link_libraries(<target> ... <item>... ...) + +The named ``<target>`` must have been created in the current directory by +a command such as :command:`add_executable` or :command:`add_library`. +Repeated calls for the same ``<target>`` append items in the order called. +Each ``<item>`` may be: + +* **A library target name**: The generated link line will have the + full path to the linkable library file associated with the target. + The buildsystem will have a dependency to re-link ``<target>`` if + the library file changes. + + The named target must be created by :command:`add_library` within + the project or as an :ref:`IMPORTED library <Imported Targets>`. + If it is created within the project an ordering dependency will + automatically be added in the build system to make sure the named + library target is up-to-date before the ``<target>`` links. + + If an imported library has the :prop_tgt:`IMPORTED_NO_SONAME` + target property set, CMake may ask the linker to search for + the library instead of using the full path + (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``). + +* **A full path to a library file**: The generated link line will + normally preserve the full path to the file. The buildsystem will + have a dependency to re-link ``<target>`` if the library file changes. + + There are some cases where CMake may ask the linker to search for + the library (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such + as when a shared library is detected to have no ``SONAME`` field. + See policy :policy:`CMP0060` for discussion of another case. + + If the library file is in a Mac OSX framework, the ``Headers`` directory + of the framework will also be processed as a + :ref:`usage requirement <Target Usage Requirements>`. This has the same + effect as passing the framework directory as an include directory. + +* **A plain library name**: The generated link line will ask the linker + to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``). + +* **A link flag**: Item names starting with ``-``, but not ``-l`` or + ``-framework``, are treated as linker flags. Note that such flags will + be treated like any other library link item for purposes of transitive + dependencies, so they are generally safe to specify only as private link + items that will not propagate to dependents. + +* A ``debug``, ``optimized``, or ``general`` keyword immediately followed + by another ``<item>``. The item following such a keyword will be used + only for the corresponding build configuration. The ``debug`` keyword + corresponds to the ``Debug`` configuration (or to configurations named + in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). + The ``optimized`` keyword corresponds to all other configurations. The + ``general`` keyword corresponds to all configurations, and is purely + optional. Higher granularity may be achieved for per-configuration + rules by creating and linking to + :ref:`IMPORTED library targets <Imported Targets>`. + +Items containing ``::``, such as ``Foo::Bar``, are assumed to be +:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library +target names and will cause an error if no such target exists. +See policy :policy:`CMP0028`. + +Arguments to ``target_link_libraries`` may use "generator expressions" +with the syntax ``$<...>``. Note however, that generator expressions +will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. +See the :manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-buildsystem(7)` manual for more on +defining buildsystem properties. + +Libraries for a Target and/or its Dependents +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + target_link_libraries(<target> + <PRIVATE|PUBLIC|INTERFACE> <item>... + [<PRIVATE|PUBLIC|INTERFACE> <item>...]...) + +The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to +specify both the link dependencies and the link interface in one command. +Libraries and targets following ``PUBLIC`` are linked to, and are made +part of the link interface. Libraries and targets following ``PRIVATE`` +are linked to, but are not made part of the link interface. Libraries +following ``INTERFACE`` are appended to the link interface and are not +used for linking ``<target>``. + +Libraries for both a Target and its Dependents +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - target_link_libraries(<target> [item1 [item2 [...]]] - [[debug|optimized|general] <item>] ...) - -Specify libraries or flags to use when linking a given target. The -named ``<target>`` must have been created in the current directory by a -command such as :command:`add_executable` or :command:`add_library`. The -remaining arguments specify library names or flags. Repeated calls for -the same ``<target>`` append items in the order called. - -If a library name matches that of another target in the project a -dependency will automatically be added in the build system to make sure -the library being linked is up-to-date before the target links. Item names -starting with ``-``, but not ``-l`` or ``-framework``, are treated as -linker flags. Note that such flags will be treated like any other library -link item for purposes of transitive dependencies, so they are generally -safe to specify only as private link items that will not propagate to -dependents of ``<target>``. - -A ``debug``, ``optimized``, or ``general`` keyword indicates that the -library immediately following it is to be used only for the -corresponding build configuration. The ``debug`` keyword corresponds to -the Debug configuration (or to configurations named in the -:prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). The -``optimized`` keyword corresponds to all other configurations. The -``general`` keyword corresponds to all configurations, and is purely -optional (assumed if omitted). Higher granularity may be achieved for -per-configuration rules by creating and linking to -:ref:`IMPORTED library targets <Imported Targets>`. + target_link_libraries(<target> <item>...) Library dependencies are transitive by default with this signature. When this target is linked into another target then the libraries @@ -45,40 +120,34 @@ by setting the property directly. When :policy:`CMP0022` is not set to of this command may set the property making any libraries linked exclusively by this signature private. -CMake will also propagate :ref:`usage requirements <Target Usage Requirements>` -from linked library targets. Usage requirements of dependencies affect -compilation of sources in the ``<target>``. - -.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` -.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt - -If an ``<item>`` is a library in a Mac OX framework, the ``Headers`` -directory of the framework will also be processed as a -:ref:`usage requirement <Target Usage Requirements>`. This has the same -effect as passing the framework directory as an include directory. - --------------------------------------------------------------------------- +Libraries for a Target and/or its Dependents (Legacy) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: target_link_libraries(<target> - <PRIVATE|PUBLIC|INTERFACE> <lib> ... - [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...]) + <LINK_PRIVATE|LINK_PUBLIC> <lib>... + [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...) -The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to -specify both the link dependencies and the link interface in one command. -Libraries and targets following ``PUBLIC`` are linked to, and are made -part of the link interface. Libraries and targets following ``PRIVATE`` -are linked to, but are not made part of the link interface. Libraries -following ``INTERFACE`` are appended to the link interface and are not -used for linking ``<target>``. +The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both +the link dependencies and the link interface in one command. + +This signature is for compatibility only. Prefer the ``PUBLIC`` or +``PRIVATE`` keywords instead. + +Libraries and targets following ``LINK_PUBLIC`` are linked to, and are +made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy +:policy:`CMP0022` is not ``NEW``, they are also made part of the +:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following +``LINK_PRIVATE`` are linked to, but are not made part of the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`). --------------------------------------------------------------------------- +Libraries for Dependents Only (Legacy) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: - target_link_libraries(<target> LINK_INTERFACE_LIBRARIES - [[debug|optimized|general] <lib>] ...) + target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...) The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them @@ -102,28 +171,8 @@ is not ``NEW``, they are also appended to the ``general`` (or without any keyword) are treated as if specified for both ``debug`` and ``optimized``. --------------------------------------------------------------------------- - -:: - - target_link_libraries(<target> - <LINK_PRIVATE|LINK_PUBLIC> - [[debug|optimized|general] <lib>] ... - [<LINK_PRIVATE|LINK_PUBLIC> - [[debug|optimized|general] <lib>] ...]) - -The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both -the link dependencies and the link interface in one command. - -This signature is for compatibility only. Prefer the ``PUBLIC`` or -``PRIVATE`` keywords instead. - -Libraries and targets following ``LINK_PUBLIC`` are linked to, and are -made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy -:policy:`CMP0022` is not ``NEW``, they are also made part of the -:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following -``LINK_PRIVATE`` are linked to, but are not made part of the -:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`). +Cyclic Dependencies of Static Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The library dependency graph is normally acyclic (a DAG), but in the case of mutually-dependent ``STATIC`` libraries CMake allows the graph to @@ -142,14 +191,14 @@ For example, the code links ``main`` to ``A B A B``. While one repetition is usually sufficient, pathological object file and symbol arrangements can require -more. One may handle such cases by manually repeating the component in -the last ``target_link_libraries`` call. However, if two archives are -really so interdependent they should probably be combined into a single -archive. +more. One may handle such cases by using the +:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually +repeating the component in the last ``target_link_libraries`` call. +However, if two archives are really so interdependent they should probably +be combined into a single archive, perhaps by using :ref:`Object Libraries`. -Arguments to target_link_libraries may use "generator expressions" -with the syntax ``$<...>``. Note however, that generator expressions -will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. See the :manual:`cmake-buildsystem(7)` manual for more on -defining buildsystem properties. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 832240a..d6f148d 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -22,10 +22,6 @@ items will populate the :prop_tgt:`SOURCES` property of following arguments specify sources. Repeated calls for the same ``<target>`` append items in the order called. -Targets with :prop_tgt:`INTERFACE_SOURCES` may not be exported with the -:command:`export` or :command:`install(EXPORT)` commands. This limitation may be -lifted in a future version of CMake. - Arguments to ``target_sources`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 43ee219..e3bd57d 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -73,7 +73,8 @@ When cross compiling, the executable compiled in the first step usually cannot be run on the build host. The ``try_run`` command checks the :variable:`CMAKE_CROSSCOMPILING` variable to detect whether CMake is in cross-compiling mode. If that is the case, it will still try to compile -the executable, but it will not try to run the executable. Instead it +the executable, but it will not try to run the executable unless the +:variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable is set. Instead it will create cache variables which must be filled by the user or by presetting them in some CMake script file to the values the executable would have produced if it had been run on its actual target platform. diff --git a/Help/generator/Qbs.rst b/Help/generator/Qbs.rst new file mode 100644 index 0000000..e569b77 --- /dev/null +++ b/Help/generator/Qbs.rst @@ -0,0 +1,25 @@ +Qbs +--- + +Generates Qbs project files. + +Project files for Qbs will be created in the top directory and +in every subdirectory which features a CMakeLists.txt file containing +a PROJECT() call. Additionally a hierarchy of makefiles is generated +into the build tree. The appropriate make program can build the +project through the default make target. A "make install" target is +also provided. + +This "extra" generator may be specified as: + +``Qbs - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Qbs - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Qbs - Ninja`` + Generate with :generator:`Ninja`. + +``Qbs - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. 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..e4c5873 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,14 @@ 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. + ``-U <globbing_expr>`` Remove matching entries from CMake cache. @@ -35,7 +43,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..ae5e58e 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 ----------------- diff --git a/Help/manual/cmake-compile-features.7.rst b/Help/manual/cmake-compile-features.7.rst index 7a6c249..46a5afb 100644 --- a/Help/manual/cmake-compile-features.7.rst +++ b/Help/manual/cmake-compile-features.7.rst @@ -295,3 +295,17 @@ the feature-appropriate include directory add_executable(consumer_no consumer_no.cpp) target_link_libraries(consumer_no foo) + +Supported Compilers +=================== + +CMake is currently aware of the :prop_tgt:`language standards <CXX_STANDARD>` +and :prop_gbl:`compile features <CMAKE_CXX_KNOWN_FEATURES>` available from +the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>` as of the +versions specified for each: + +* ``AppleClang``: Apple Clang for Xcode versions 4.4 though 6.2. +* ``Clang``: Clang compiler versions 2.9 through 3.4. +* ``GNU``: GNU compiler versions 4.4 through 5.0. +* ``MSVC``: Microsoft Visual Studio versions 2010 through 2015. +* ``SunPro``: Oracle SolarisStudio version 12.4. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index e18250c..ab74140 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -28,34 +28,6 @@ Some implementations have a ``std::auto_ptr`` which can not be used as a return value from a function. ``std::auto_ptr`` may not be used. Use ``cmsys::auto_ptr`` instead. -Template Parameter Defaults ---------------------------- - -On ancient compilers, C++ template must use template parameters in function -arguments. If no parameter of that type is needed, the common workaround is -to add a defaulted pointer to the type to the templated function. However, -this does not work with other ancient compilers: - -.. code-block:: c++ - - template<typename PropertyType> - PropertyType getTypedProperty(cmTarget* tgt, const char* prop, - PropertyType* = 0) // Wrong - { - - } - -.. code-block:: c++ - - template<typename PropertyType> - PropertyType getTypedProperty(cmTarget* tgt, const char* prop, - PropertyType*) // Ok - { - - } - -and invoke it with the value ``0`` explicitly in all cases. - size_t ------ @@ -633,6 +605,7 @@ have a .cmake file in this directory NOT show up in the modules documentation, simply leave out the ``Help/module/<module-name>.rst`` file and the ``Help/manual/cmake-modules.7.rst`` toctree entry. +.. _`Find Modules`: Find Modules ------------ diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c47a7c4..189c3ef 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -40,10 +40,6 @@ otherwise expands to nothing. Available logical expressions are: -``$<0:...>`` - Empty string (ignores ``...``) -``$<1:...>`` - Content of ``...`` ``$<BOOL:...>`` ``1`` if the ``...`` is true, else ``0`` ``$<AND:?[,?]...>`` @@ -92,7 +88,47 @@ Available logical expressions are: increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on - compile features. + compile features and a list of supported compilers. +``$<COMPILE_LANGUAGE:lang>`` + ``1`` when the language used for compilation unit matches ``lang``, + otherwise ``0``. This expression used to specify compile options for + source files of a particular language in a target. For example, to specify + the use of the ``-fno-exceptions`` compile option (compiler id checks + elided): + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp) + target_compile_options(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:-fno-exceptions> + ) + + This generator expression has limited use because it is not possible to + use it with the Visual Studio generators. Portable buildsystems would + not use this expression, and would create separate libraries for each + source file language instead: + + .. code-block:: cmake + + add_library(myapp_c foo.c) + add_library(myapp_cxx foo.c) + target_compile_options(myapp_cxx PUBLIC -fno-exceptions) + add_executable(myapp main.cpp) + target_link_libraries(myapp myapp_c myapp_cxx) + + The ``Makefile`` and ``Ninja`` based generators can also use this + expression to specify compile-language specific compile definitions + and include directories: + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX> + ) + target_include_directories(myapp + PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> + ) Informational Expressions ========================= @@ -174,6 +210,10 @@ Available informational expressions are: ``$<INSTALL_PREFIX>`` Content of the install prefix when the target is exported via :command:`install(EXPORT)` and empty otherwise. +``$<COMPILE_LANGUAGE>`` + The compile language of source files when evaluating compile options. See + the unary version for notes about portability of this generator + expression. Output Expressions ================== @@ -197,6 +237,10 @@ where ``${prop}`` refers to a helper variable:: Available output expressions are: +``$<0:...>`` + Empty string (ignores ``...``) +``$<1:...>`` + Content of ``...`` ``$<JOIN:list,...>`` Joins the list with the content of ``...`` ``$<ANGLE-R>`` diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index bda7eef..6f76fb1 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,13 @@ one may launch CMake from any environment. /generator/Visual Studio 11 2012 /generator/Visual Studio 12 2013 /generator/Visual Studio 14 2015 + +Xcode Generator +^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + /generator/Xcode Extra Generators @@ -85,3 +109,4 @@ The following extra generators are known to CMake. /generator/KDevelop3 /generator/Kate /generator/Sublime Text 2 + /generator/Qbs 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 965eede..c9219d5 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -22,6 +22,7 @@ All Modules /module/CheckCXXSourceCompiles /module/CheckCXXSourceRuns /module/CheckCXXSymbolExists + /module/CheckFortranCompilerFlag /module/CheckFortranFunctionExists /module/CheckFortranSourceCompiles /module/CheckFunctionExists @@ -211,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..aff696d 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -114,3 +114,7 @@ All Policies /policy/CMP0054 /policy/CMP0055 /policy/CMP0056 + /policy/CMP0057 + /policy/CMP0058 + /policy/CMP0059 + /policy/CMP0060 diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 25f989f..02d164b 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 @@ -243,6 +250,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 +278,8 @@ Properties on Tests /prop_test/WILL_FAIL /prop_test/WORKING_DIRECTORY +.. _`Source File Properties`: + Properties on Source Files ========================== @@ -297,10 +309,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 +329,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..63f704d 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 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index da41bbb..b2f7e9d 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -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..dd3bcfb 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -194,6 +194,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 diff --git a/Help/module/CheckFortranCompilerFlag.rst b/Help/module/CheckFortranCompilerFlag.rst new file mode 100644 index 0000000..58bf6ec --- /dev/null +++ b/Help/module/CheckFortranCompilerFlag.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckFortranCompilerFlag.cmake diff --git a/Help/module/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/CMP0057.rst b/Help/policy/CMP0057.rst new file mode 100644 index 0000000..5cf0784 --- /dev/null +++ b/Help/policy/CMP0057.rst @@ -0,0 +1,21 @@ +CMP0057 +------- + +Disallow multiple ``MAIN_DEPENDENCY`` specifications for the same file. + +CMake 3.3 and above no longer allow the same input file to be used +as a ``MAIN_DEPENDENCY`` in more than one custom command. + +Listing the same input file more than once in this context has not been +supported by earlier versions either and would lead to build time issues +but was not diagnosed. + +The ``OLD`` behavior for this policy is to allow using the same input file +in a ``MAIN_DEPENDENCY`` specfication more than once. +The ``NEW`` behavior is to disallow using the same input file in a +``MAIN_DEPENDENCY`` specification more than once. + +This policy was introduced in CMake version 3.3. +CMake version |release| warns when the policy is not set and uses +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. diff --git a/Help/policy/CMP0058.rst b/Help/policy/CMP0058.rst new file mode 100644 index 0000000..0f20383 --- /dev/null +++ b/Help/policy/CMP0058.rst @@ -0,0 +1,108 @@ +CMP0058 +------- + +Ninja requires custom command byproducts to be explicit. + +When an intermediate file generated during the build is consumed +by an expensive operation or a large tree of dependents, one may +reduce the work needed for an incremental rebuild by updating the +file timestamp only when its content changes. With this approach +the generation rule must have a separate output file that is always +updated with a new timestamp that is newer than any dependencies of +the rule so that the build tool re-runs the rule only when the input +changes. We refer to the separate output file as a rule's *witness* +and the generated file as a rule's *byproduct*. + +Byproducts may not be listed as outputs because their timestamps are +allowed to be older than the inputs. No build tools (like ``make``) +that existed when CMake was designed have a way to express byproducts. +Therefore CMake versions prior to 3.2 had no way to specify them. +Projects typically left byproducts undeclared in the rules that +generate them. For example: + +.. code-block:: cmake + + add_custom_command( + OUTPUT witness.txt + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + byproduct.txt # timestamp may not change + COMMAND ${CMAKE_COMMAND} -E touch witness.txt + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + ) + add_custom_target(Provider DEPENDS witness.txt) + add_custom_command( + OUTPUT generated.c + COMMAND expensive-task -i byproduct.txt -o generated.c + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt + ) + add_library(Consumer generated.c) + add_dependencies(Consumer Provider) + +This works well for all generators except :generator:`Ninja`. +The Ninja build tool sees a rule listing ``byproduct.txt`` +as a dependency and no rule listing it as an output. Ninja then +complains that there is no way to satisfy the dependency and +stops building even though there are order-only dependencies +that ensure ``byproduct.txt`` will exist before its consumers +need it. See discussion of this problem in `Ninja Issue 760`_ +for further details on why Ninja works this way. + +.. _`Ninja Issue 760`: https://github.com/martine/ninja/issues/760 + +Instead of leaving byproducts undeclared in the rules that generate +them, Ninja expects byproducts to be listed along with other outputs. +Such rules may be marked with a ``restat`` option that tells Ninja +to check the timestamps of outputs after the rules run. This +prevents byproducts whose timestamps do not change from causing +their dependents to re-build unnecessarily. + +Since the above approach does not tell CMake what custom command +generates ``byproduct.txt``, the Ninja generator does not have +enough information to add the byproduct as an output of any rule. +CMake 2.8.12 and above work around this problem and allow projects +using the above approach to build by generating ``phony`` build +rules to tell Ninja to tolerate such missing files. However, this +workaround prevents Ninja from diagnosing a dependency that is +really missing. It also works poorly in in-source builds where +every custom command dependency, even on source files, needs to +be treated this way because CMake does not have enough information +to know which files are generated as byproducts of custom commands. + +CMake 3.2 introduced the ``BYPRODUCTS`` option to the +:command:`add_custom_command` and :command:`add_custom_target` +commands. This option allows byproducts to be specified explicitly: + +.. code-block:: cmake + + add_custom_command( + OUTPUT witness.txt + BYPRODUCTS byproduct.txt # explicit byproduct specification + COMMAND ${CMAKE_COMMAND} -E copy_if_different + ${CMAKE_CURRENT_SOURCE_DIR}/input.txt + byproduct.txt # timestamp may not change + ... + +The ``BYPRODUCTS`` option is used by the :generator:`Ninja` generator +to list byproducts among the outputs of the custom commands that +generate them, and is ignored by other generators. + +CMake 3.3 and above prefer to require projects to specify custom +command byproducts explicitly so that it can avoid using the +``phony`` rule workaround altogether. Policy ``CMP0058`` was +introduced to provide compatibility with existing projects that +still need the workaround. + +This policy has no effect on generators other than :generator:`Ninja`. +The ``OLD`` behavior for this policy is to generate Ninja ``phony`` +rules for unknown dependencies in the build tree. The ``NEW`` +behavior for this policy is to not generate these and instead +require projects to specify custom command ``BYPRODUCTS`` explicitly. + +This policy was introduced in CMake version 3.3. +CMake version |release| warns when it sees unknown dependencies in +out-of-source build trees if the policy is not set and then uses +``OLD`` behavior. Use the :command:`cmake_policy` command to set +the policy to ``OLD`` or ``NEW`` explicitly. The policy setting +must be in scope at the end of the top-level ``CMakeLists.txt`` +file of the project and has global effect. diff --git a/Help/policy/CMP0059.rst b/Help/policy/CMP0059.rst new file mode 100644 index 0000000..e40f450 --- /dev/null +++ b/Help/policy/CMP0059.rst @@ -0,0 +1,17 @@ +CMP0059 +------- + +Don't treat ``DEFINITIONS`` as a built-in directory property. + +CMake 3.3 and above no longer make a list of definitions available through +the :prop_dir:`DEFINITIONS` directory property. The +:prop_dir:`COMPILE_DEFINITIONS` directory property may be used instead. + +The ``OLD`` behavior for this policy is to provide the list of flags given +so far to the :command:`add_definitions` command. The ``NEW`` behavior is +to behave as a normal user-defined directory property. + +This policy was introduced in CMake version 3.3. +CMake version |release| warns when the policy is not set and uses +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. diff --git a/Help/policy/CMP0060.rst b/Help/policy/CMP0060.rst new file mode 100644 index 0000000..cc37b1b --- /dev/null +++ b/Help/policy/CMP0060.rst @@ -0,0 +1,63 @@ +CMP0060 +------- + +Link libraries by full path even in implicit directories. + +Policy :policy:`CMP0003` was introduced with the intention of always +linking library files by full path when a full path is given to the +:command:`target_link_libraries` command. However, on some platforms +(e.g. HP-UX) the compiler front-end adds alternative library search paths +for the current architecture (e.g. ``/usr/lib/<arch>`` has alternatives +to libraries in ``/usr/lib`` for the current architecture). +On such platforms the :command:`find_library` may find a library such as +``/usr/lib/libfoo.so`` that does not belong to the current architecture. + +Prior to policy :policy:`CMP0003` projects would still build in such +cases because the incorrect library path would be converted to ``-lfoo`` +on the link line and the linker would find the proper library in the +arch-specific search path provided by the compiler front-end implicitly. +At the time we chose to remain compatible with such projects by always +converting library files found in implicit link directories to ``-lfoo`` +flags to ask the linker to search for them. This approach allowed existing +projects to continue to build while still linking to libraries outside +implicit link directories via full path (such as those in the build tree). + +CMake does allow projects to override this behavior by using an +:ref:`IMPORTED library target <Imported Targets>` with its +:prop_tgt:`IMPORTED_LOCATION` property set to the desired full path to +a library file. In fact, many :ref:`Find Modules` are learning to provide +:ref:`Imported Targets` instead of just the traditional ``Foo_LIBRARIES`` +variable listing library files. However, this makes the link line +generated for a library found by a Find Module depend on whether it +is linked through an imported target or not, which is inconsistent. +Furthermore, this behavior has been a source of confusion because the +generated link line for a library file depends on its location. It is +also problematic for projects trying to link statically because flags +like ``-Wl,-Bstatic -lfoo -Wl,-Bdynamic`` may be used to help the linker +select ``libfoo.a`` instead of ``libfoo.so`` but then leak dynamic linking +to following libraries. (See the :prop_tgt:`LINK_SEARCH_END_STATIC` +target property for a solution typically used for that problem.) + +When the special case for libraries in implicit link directories was first +introduced the list of implicit link directories was simply hard-coded +(e.g. ``/lib``, ``/usr/lib``, and a few others). Since that time, CMake +has learned to detect the implicit link directories used by the compiler +front-end. If necessary, the :command:`find_library` command could be +taught to use this information to help find libraries of the proper +architecture. + +For these reasons, CMake 3.3 and above prefer to drop the special case +and link libraries by full path even when they are in implicit link +directories. Policy ``CMP0060`` provides compatibility for existing +projects. + +The OLD behavior for this policy is to ask the linker to search for +libraries whose full paths are known to be in implicit link directories. +The NEW behavior for this policy is to link libraries by full path even +if they are in implicit link directories. + +This policy was introduced in CMake version 3.3. Unlike most policies, +CMake version |release| does *not* warn by default when this policy +is not set and simply uses OLD behavior. See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. diff --git a/Help/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/COMPILE_FEATURES.rst b/Help/prop_tgt/COMPILE_FEATURES.rst index 225ffee..195215e 100644 --- a/Help/prop_tgt/COMPILE_FEATURES.rst +++ b/Help/prop_tgt/COMPILE_FEATURES.rst @@ -9,4 +9,4 @@ in the :variable:`CMAKE_CXX_COMPILE_FEATURES` variable. Contents of ``COMPILE_FEATURES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-compile-features(7)` manual -for information on compile features. +for information on compile features and a list of supported compilers. diff --git a/Help/prop_tgt/COMPILE_OPTIONS.rst b/Help/prop_tgt/COMPILE_OPTIONS.rst index 27cbec1..36d786a 100644 --- a/Help/prop_tgt/COMPILE_OPTIONS.rst +++ b/Help/prop_tgt/COMPILE_OPTIONS.rst @@ -3,12 +3,13 @@ COMPILE_OPTIONS List of options to pass to the compiler. -This property specifies the list of options specified so far for this -property. +This property holds a :ref:`;-list <CMake Language Lists>` of options +specified so far for its target. Use the :command:`target_compile_options` +command to append more options. This property is intialized by the :prop_dir:`COMPILE_OPTIONS` directory -property, which is used by the generators to set the options for the -compiler. +property when a target is created, and is used by the generators to set +the options for the compiler. Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual diff --git a/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst new file mode 100644 index 0000000..3ef8e03 --- /dev/null +++ b/Help/prop_tgt/CROSSCOMPILING_EMULATOR.rst @@ -0,0 +1,6 @@ +CROSSCOMPILING_EMULATOR +----------------------- + +Use the given emulator to run executables created when crosscompiling. This +command will be added as a prefix to :command:`add_test` test commands for +built target system executables. diff --git a/Help/prop_tgt/CXX_EXTENSIONS.rst b/Help/prop_tgt/CXX_EXTENSIONS.rst index 67c5cb0..0f547e2 100644 --- a/Help/prop_tgt/CXX_EXTENSIONS.rst +++ b/Help/prop_tgt/CXX_EXTENSIONS.rst @@ -9,7 +9,7 @@ as ``-std=gnu++11`` instead of ``-std=c++11`` to the compile line. This property is ``ON`` by default. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_CXX_EXTENSIONS` variable if it is set when a target diff --git a/Help/prop_tgt/CXX_STANDARD.rst b/Help/prop_tgt/CXX_STANDARD.rst index 65b30ec..edc9ba5 100644 --- a/Help/prop_tgt/CXX_STANDARD.rst +++ b/Help/prop_tgt/CXX_STANDARD.rst @@ -24,7 +24,7 @@ flag will not result in an error or warning, but will instead add the with the :prop_tgt:`CXX_STANDARD_REQUIRED` target property. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_CXX_STANDARD` variable if it is set when a target diff --git a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst index 4e24e5e..697d7f6 100644 --- a/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/CXX_STANDARD_REQUIRED.rst @@ -11,7 +11,7 @@ not available. For compilers that have no notion of a standard level, such as MSVC, this has no effect. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_CXX_STANDARD_REQUIRED` variable if it is set when a diff --git a/Help/prop_tgt/C_EXTENSIONS.rst b/Help/prop_tgt/C_EXTENSIONS.rst index dc48cc6..fce67f4 100644 --- a/Help/prop_tgt/C_EXTENSIONS.rst +++ b/Help/prop_tgt/C_EXTENSIONS.rst @@ -9,7 +9,7 @@ as ``-std=gnu11`` instead of ``-std=c11`` to the compile line. This property is ``ON`` by default. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_C_EXTENSIONS` variable if it is set when a target diff --git a/Help/prop_tgt/C_STANDARD.rst b/Help/prop_tgt/C_STANDARD.rst index 3aa74af..5e36821 100644 --- a/Help/prop_tgt/C_STANDARD.rst +++ b/Help/prop_tgt/C_STANDARD.rst @@ -24,7 +24,7 @@ flag will not result in an error or warning, but will instead add the be controlled with the :prop_tgt:`C_STANDARD_REQUIRED` target property. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_C_STANDARD` variable if it is set when a target diff --git a/Help/prop_tgt/C_STANDARD_REQUIRED.rst b/Help/prop_tgt/C_STANDARD_REQUIRED.rst index 743d568..acfad98 100644 --- a/Help/prop_tgt/C_STANDARD_REQUIRED.rst +++ b/Help/prop_tgt/C_STANDARD_REQUIRED.rst @@ -11,7 +11,7 @@ not available. For compilers that have no notion of a standard level, such as MSVC, this has no effect. See the :manual:`cmake-compile-features(7)` manual for information on -compile features. +compile features and a list of supported compilers. This property is initialized by the value of the :variable:`CMAKE_C_STANDARD_REQUIRED` variable if it is set when a diff --git a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst index 8dfec5f..31b594f 100644 --- a/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst +++ b/Help/prop_tgt/INTERFACE_COMPILE_FEATURES.rst @@ -9,4 +9,4 @@ INTERFACE_COMPILE_FEATURES .. include:: INTERFACE_BUILD_PROPERTY.txt See the :manual:`cmake-compile-features(7)` manual for information on compile -features. +features and a list of supported compilers. diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index 1cfd7a8..b1c40b2 100644 --- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -22,5 +22,8 @@ installation prefix. For example: $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib ) +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index 55b7b8d..832d12b 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst @@ -17,5 +17,8 @@ with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem properties. +Creating Relocatable Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES`` .. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_SOURCES.rst b/Help/prop_tgt/INTERFACE_SOURCES.rst index 696ee95..a224b68 100644 --- a/Help/prop_tgt/INTERFACE_SOURCES.rst +++ b/Help/prop_tgt/INTERFACE_SOURCES.rst @@ -12,10 +12,6 @@ When target dependencies are specified using :command:`target_link_libraries`, CMake will read this property from all target dependencies to determine the sources of the consumer. -Targets with ``INTERFACE_SOURCES`` may not be exported with the -:command:`export` or :command:`install(EXPORT)` commands. This limitation may be -lifted in a future version of CMake. - Contents of ``INTERFACE_SOURCES`` may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. See the :manual:`cmake-buildsystem(7)` diff --git a/Help/prop_tgt/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/XCODE_ATTRIBUTE_an-attribute.rst b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst index de98c37..7e00ac4 100644 --- a/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst +++ b/Help/prop_tgt/XCODE_ATTRIBUTE_an-attribute.rst @@ -8,3 +8,9 @@ the generated Xcode project. Ignored on other generators. See the :variable:`CMAKE_XCODE_ATTRIBUTE_<an-attribute>` variable to set attributes on all targets in a directory tree. + +Contents of ``XCODE_ATTRIBUTE_<an-attribute>`` may use +"generator expressions" with the syntax ``$<...>``. See the +:manual:`cmake-generator-expressions(7)` manual for available +expressions. See the :manual:`cmake-buildsystem(7)` manual +for more on defining buildsystem properties. diff --git a/Help/prop_tgt/XCTEST.rst b/Help/prop_tgt/XCTEST.rst new file mode 100644 index 0000000..eb47e60 --- /dev/null +++ b/Help/prop_tgt/XCTEST.rst @@ -0,0 +1,13 @@ +XCTEST +------ + +This target is a XCTest CFBundle on the Mac. + +This property will usually get set via the :command:`xctest_add_bundle` +macro in :module:`FindXCTest` module. + +If a module library target has this property set to true it will be +built as a CFBundle when built on the Mac. It will have the directory +structure required for a CFBundle. + +This property depends on :prop_tgt:`BUNDLE` to be effective. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/ExternalData-recursive-match.rst b/Help/release/dev/ExternalData-recursive-match.rst new file mode 100644 index 0000000..4d8c789 --- /dev/null +++ b/Help/release/dev/ExternalData-recursive-match.rst @@ -0,0 +1,7 @@ +ExternalData-recursive-match +---------------------------- + +* The :module:`ExternalData` module learned a new ``RECURSE:`` + option in ``DATA{}`` references specifying directories. + This allows an entire directory tree of associated files + to be matched. diff --git a/Help/release/dev/ExternalData-url-algo-map.rst b/Help/release/dev/ExternalData-url-algo-map.rst new file mode 100644 index 0000000..baf661f --- /dev/null +++ b/Help/release/dev/ExternalData-url-algo-map.rst @@ -0,0 +1,8 @@ +ExternalData-url-algo-map +------------------------- + +* The :module:`ExternalData` module learned a new URL template + placeholder ``%(algo:<key>)`` to allow custom mapping from + algorithm name to URL component through configuration of new + :variable:`ExternalData_URL_ALGO_<algo>_<key>` variables. + This allows more flexibility in remote URLs. diff --git a/Help/release/dev/ExternalProject-byproducts-tokens.rst b/Help/release/dev/ExternalProject-byproducts-tokens.rst new file mode 100644 index 0000000..20b4dd4 --- /dev/null +++ b/Help/release/dev/ExternalProject-byproducts-tokens.rst @@ -0,0 +1,5 @@ +ExternalProject-byproducts-tokens +--------------------------------- + +* The :module:`ExternalProject` module learned to replace tokens + like ``<BINARY_DIR>`` in the ``BYPRODUCTS`` of each step. diff --git a/Help/release/dev/FindBoost-per-config-libraries.rst b/Help/release/dev/FindBoost-per-config-libraries.rst new file mode 100644 index 0000000..e6ef70f --- /dev/null +++ b/Help/release/dev/FindBoost-per-config-libraries.rst @@ -0,0 +1,5 @@ +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/FindCUDA-StaticRuntime.rst b/Help/release/dev/FindCUDA-StaticRuntime.rst new file mode 100644 index 0000000..112596c --- /dev/null +++ b/Help/release/dev/FindCUDA-StaticRuntime.rst @@ -0,0 +1,7 @@ +FindCUDA-StaticRuntime +---------------------- + +* The :module:`FindCUDA` module now defaults to using the static + CUDA runtime library if it is available. A new + ``CUDA_USE_STATIC_CUDA_RUNTIME`` option is offered to control + this behavior. diff --git a/Help/release/dev/FindMatlab-rewrite.rst b/Help/release/dev/FindMatlab-rewrite.rst new file mode 100644 index 0000000..07727b8 --- /dev/null +++ b/Help/release/dev/FindMatlab-rewrite.rst @@ -0,0 +1,7 @@ +FindMatlab-rewrite +------------------ + +* The :module:`FindMatlab` module was completely rewritten. It learned + about versions and components and to find Matlab in a more precise and + multiplatform way. The module now offers APIs to create mex extensions, + documentation, and unit tests. diff --git a/Help/release/dev/InstallRequiredSystemLibraries-COMPONENT.rst b/Help/release/dev/InstallRequiredSystemLibraries-COMPONENT.rst new file mode 100644 index 0000000..e6ebc2d --- /dev/null +++ b/Help/release/dev/InstallRequiredSystemLibraries-COMPONENT.rst @@ -0,0 +1,6 @@ +InstallRequiredSystemLibraries-COMPONENT +---------------------------------------- + +* The :module:`InstallRequiredSystemLibraries` module learned a new + ``CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT`` option to specify the + installation component. diff --git a/Help/release/dev/UseSWIG-no-MAIN_DEPENDENCY.rst b/Help/release/dev/UseSWIG-no-MAIN_DEPENDENCY.rst new file mode 100644 index 0000000..5311cf1 --- /dev/null +++ b/Help/release/dev/UseSWIG-no-MAIN_DEPENDENCY.rst @@ -0,0 +1,9 @@ +UseSWIG-no-MAIN_DEPENDENCY +-------------------------- + +* The :module:`UseSWIG` module ``SWIG_ADD_MODULE`` macro no + longer attaches the swig invocation custom command to the + ``.i`` source file in IDE projects. This is because only + one custom command can be safely attached to a given source + file, and adding multiple modules with the same ``.i`` file + for different languages requires more than one such command. diff --git a/Help/release/dev/add-CheckFortranCompilerFlag.rst b/Help/release/dev/add-CheckFortranCompilerFlag.rst new file mode 100644 index 0000000..718b53e --- /dev/null +++ b/Help/release/dev/add-CheckFortranCompilerFlag.rst @@ -0,0 +1,6 @@ +add-CheckFortranCompilerFlag +---------------------------- + +* The :module:`CheckFortranCompilerFlag` module was introduced + to check ``Fortran`` compiler flags, much like the + :module:`CheckCCompilerFlag` module already does for ``C``. diff --git a/Help/release/dev/add-extra-qbs-generator.rst b/Help/release/dev/add-extra-qbs-generator.rst new file mode 100644 index 0000000..edb441f --- /dev/null +++ b/Help/release/dev/add-extra-qbs-generator.rst @@ -0,0 +1,6 @@ +add-extra-qbs-geneator +---------------------- + +* It is now possible to generate :generator:`Qbs` project files + for use with QtCreator IDE, matching make tool must be used + to build the project through the generated makefiles. diff --git a/Help/release/dev/add_dependencies-INTERFACE-libraries.rst b/Help/release/dev/add_dependencies-INTERFACE-libraries.rst new file mode 100644 index 0000000..dfac2af --- /dev/null +++ b/Help/release/dev/add_dependencies-INTERFACE-libraries.rst @@ -0,0 +1,7 @@ +add_dependencies-INTERFACE-libraries +------------------------------------ + +* The :command:`add_dependencies` command learned to allow dependencies + to be added to :ref:`interface libraries <Interface Libraries>`. + Dependencies added to an interface library are followed transitively + in its place since the target itself does not build. diff --git a/Help/release/dev/compiler-version-Fortran.rst b/Help/release/dev/compiler-version-Fortran.rst new file mode 100644 index 0000000..e10b206 --- /dev/null +++ b/Help/release/dev/compiler-version-Fortran.rst @@ -0,0 +1,6 @@ +compiler-version-Fortran +------------------------ + +* The version of some Fortran compilers is now detected and stored in the + :variable:`CMAKE_Fortran_COMPILER_VERSION <CMAKE_<LANG>_COMPILER_VERSION>` + variable. diff --git a/Help/release/dev/cpack-rpm-basic-symlink-handling.rst b/Help/release/dev/cpack-rpm-basic-symlink-handling.rst new file mode 100644 index 0000000..3af4cf1 --- /dev/null +++ b/Help/release/dev/cpack-rpm-basic-symlink-handling.rst @@ -0,0 +1,6 @@ +cpack-rpm-basic-symlink-handling +-------------------------------- + +* The :module:`CPackRPM` module learned to package symbolic links + more cleanly and now supports directory symlinks with recent + ``rpmbuild`` versions. diff --git a/Help/release/dev/ctest-repeat-until-fail.rst b/Help/release/dev/ctest-repeat-until-fail.rst new file mode 100644 index 0000000..8a679c6 --- /dev/null +++ b/Help/release/dev/ctest-repeat-until-fail.rst @@ -0,0 +1,5 @@ +ctest-repeat-until-fail +----------------------- + +* The :manual:`ctest(1)` tool learned a new ``--repeat-until-fail <n>`` + option to help find sporadic test failures. diff --git a/Help/release/dev/emulator-property.rst b/Help/release/dev/emulator-property.rst new file mode 100644 index 0000000..1bc2f2d --- /dev/null +++ b/Help/release/dev/emulator-property.rst @@ -0,0 +1,7 @@ +emulator-property +----------------- + +* A :prop_tgt:`CROSSCOMPILING_EMULATOR` target property and supporting + :variable:`CMAKE_CROSSCOMPILING_EMULATOR` variable were introduced + to allow target platform binaries to run on the host during cross + compiling. diff --git a/Help/release/dev/export-interface-source-files.rst b/Help/release/dev/export-interface-source-files.rst new file mode 100644 index 0000000..00dcd25 --- /dev/null +++ b/Help/release/dev/export-interface-source-files.rst @@ -0,0 +1,6 @@ +export-interface-source-files +----------------------------- + +* It is now possible to export targets which populate the + :prop_tgt:`INTERFACE_SOURCES` target property using the + :command:`install(EXPORT)` and :command:`export()` commands. diff --git a/Help/release/dev/file-globbing-directory-listing.rst b/Help/release/dev/file-globbing-directory-listing.rst new file mode 100644 index 0000000..c4d7ba5 --- /dev/null +++ b/Help/release/dev/file-globbing-directory-listing.rst @@ -0,0 +1,6 @@ +file-globbing-directory-listing +------------------------------- + +* The :command:`file(GLOB)` and :command:`file(GLOB_RECURSE)` commands + learned a new ``LIST_DIRECTORIES <bool>`` option to specify whether + the glob result should include directories. diff --git a/Help/release/dev/find-command-prefix-from-PATH.rst b/Help/release/dev/find-command-prefix-from-PATH.rst new file mode 100644 index 0000000..f9aae2a --- /dev/null +++ b/Help/release/dev/find-command-prefix-from-PATH.rst @@ -0,0 +1,6 @@ +find-command-prefix-from-PATH +----------------------------- + +* The :command:`find_library`, :command:`find_path`, and :command:`find_file` + commands now search in installation prefixes derived from the ``PATH`` + environment variable. diff --git a/Help/release/dev/gcov-module-coverage-exclude.rst b/Help/release/dev/gcov-module-coverage-exclude.rst new file mode 100644 index 0000000..ee4ebae --- /dev/null +++ b/Help/release/dev/gcov-module-coverage-exclude.rst @@ -0,0 +1,6 @@ +gcov-module-coverage-exclude +---------------------------- + +* The :module:`CTestCoverageCollectGCOV` module learned to support + the same ``CTEST_CUSTOM_COVERAGE_EXCLUDE`` option as the + :command:`ctest_coverage` command. diff --git a/Help/release/dev/install-DESTINATION-genex.rst b/Help/release/dev/install-DESTINATION-genex.rst new file mode 100644 index 0000000..4c4bbed --- /dev/null +++ b/Help/release/dev/install-DESTINATION-genex.rst @@ -0,0 +1,5 @@ +install-DESTINATION-genex +------------------------- + +* The :command:`install(TARGETS)` command learned to support + generator expressions in the ``DESTINATION`` value. diff --git a/Help/release/dev/link-implicit-libs-full-path.rst b/Help/release/dev/link-implicit-libs-full-path.rst new file mode 100644 index 0000000..7ed7245 --- /dev/null +++ b/Help/release/dev/link-implicit-libs-full-path.rst @@ -0,0 +1,6 @@ +link-implicit-libs-full-path +---------------------------- + +* Linking to library files by a full path in an implicit linker search + directory (e.g. ``/usr/lib/libfoo.a``) no longer asks the linker to + search for the library (e.g. ``-lfoo``). See policy :policy:`CMP0060`. diff --git a/Help/release/dev/main_dependency_diagnostic.rst b/Help/release/dev/main_dependency_diagnostic.rst new file mode 100644 index 0000000..13486ef --- /dev/null +++ b/Help/release/dev/main_dependency_diagnostic.rst @@ -0,0 +1,6 @@ +main_dependency_diagnostic +-------------------------- + +* Listing the same input file as a MAIN_DEPENDENCY of a custom command + can lead to broken build time behavior. This is now diagnosed. + See policy :policy:`CMP0057`. diff --git a/Help/release/dev/makefile-DELETE_ON_ERROR.rst b/Help/release/dev/makefile-DELETE_ON_ERROR.rst new file mode 100644 index 0000000..c7c45fd --- /dev/null +++ b/Help/release/dev/makefile-DELETE_ON_ERROR.rst @@ -0,0 +1,7 @@ +makefile-DELETE_ON_ERROR +------------------------ + +* The Makefile generators now add ``.DELETE_ON_ERROR`` to the + makefiles that contain the actual build rules for files on disk. + This tells GNU make to remove rule outputs when their recipe + modifies an output but fails. diff --git a/Help/release/dev/makefile-progress-improvements.rst b/Help/release/dev/makefile-progress-improvements.rst new file mode 100644 index 0000000..9cc9706 --- /dev/null +++ b/Help/release/dev/makefile-progress-improvements.rst @@ -0,0 +1,7 @@ +makefile-progress-improvements +------------------------------ + +* With Makefile generators, the build-time progress output has been improved. + It no longer mixes progress and build rule messages during parallel builds. + The link rule messages now have progress and are displayed as bold green + instead of bold red (since red is often associated with an error message). diff --git a/Help/release/dev/mingw-compile-features.rst b/Help/release/dev/mingw-compile-features.rst new file mode 100644 index 0000000..e2ed30b --- /dev/null +++ b/Help/release/dev/mingw-compile-features.rst @@ -0,0 +1,6 @@ +mingw-compile-features +---------------------- + +* The :manual:`Compile Features <cmake-compile-features(7)>` functionality + is now aware of features supported by GNU compilers on Windows, versions + 4.4 through 5.0. diff --git a/Help/release/dev/mingw-no-find_library-dll.rst b/Help/release/dev/mingw-no-find_library-dll.rst new file mode 100644 index 0000000..1b0c19b --- /dev/null +++ b/Help/release/dev/mingw-no-find_library-dll.rst @@ -0,0 +1,8 @@ +mingw-no-find_library-dll +------------------------- + +* When building with GNU tools on Windows (MinGW tools), the + :command:`find_library` command will no longer consider + ``.dll`` files to be linkable libraries. All dynamic link + libraries are expected to provide separate ``.dll.a`` or + ``.lib`` import libraries. diff --git a/Help/release/dev/ninja-require-byproducts.rst b/Help/release/dev/ninja-require-byproducts.rst new file mode 100644 index 0000000..ccde4bc --- /dev/null +++ b/Help/release/dev/ninja-require-byproducts.rst @@ -0,0 +1,9 @@ +ninja-require-byproducts +------------------------ + +* The :generator:`Ninja` generator now requires that calls to the + :command:`add_custom_command` and :command:`add_custom_target` + commands use the ``BYPRODUCTS`` option to explicitly specify any + files generated by the custom commands that are not listed as + outputs (perhaps because their timestamps are allowed to be older + than the inputs). See policy :policy:`CMP0058`. diff --git a/Help/release/dev/remove-DEFINITIONS-directory-property.rst b/Help/release/dev/remove-DEFINITIONS-directory-property.rst new file mode 100644 index 0000000..d8e50f0 --- /dev/null +++ b/Help/release/dev/remove-DEFINITIONS-directory-property.rst @@ -0,0 +1,6 @@ +remove-DEFINITIONS-property +--------------------------- + +* The :command:`add_definitions()` command no longer causes a + :prop_dir:`DEFINITIONS` directory property to be populated. See policy + :policy:`CMP0059`. diff --git a/Help/release/dev/rpm_package_architecture.rst b/Help/release/dev/rpm_package_architecture.rst new file mode 100644 index 0000000..5bec51d --- /dev/null +++ b/Help/release/dev/rpm_package_architecture.rst @@ -0,0 +1,6 @@ +rpm_package_architecture +------------------------ + +* The :module:`CPackRPM` module learned a new + :variable:`CPACK_RPM_<component>_PACKAGE_ARCHITECTURE` variable + to specify a component-specific package architecture. diff --git a/Help/release/dev/tar-write-format.rst b/Help/release/dev/tar-write-format.rst new file mode 100644 index 0000000..004df21 --- /dev/null +++ b/Help/release/dev/tar-write-format.rst @@ -0,0 +1,6 @@ +tar-write-format +---------------- + +* The :manual:`cmake(1)` ``-E tar`` command learned a new + ``--format<format>`` option to specify the archive format to + be written. diff --git a/Help/release/dev/target-language-genex.rst b/Help/release/dev/target-language-genex.rst new file mode 100644 index 0000000..ed4cb5e --- /dev/null +++ b/Help/release/dev/target-language-genex.rst @@ -0,0 +1,9 @@ +target-language-genex +--------------------- + +* A new ``COMPILE_LANGUAGE`` generator expression was introduced to + allow specification of compile options for target files based on the + :prop_sf:`LANGUAGE` of each source file. Due to limitations of the + underlying native build tools, this feature has varying support across + generators. See the :manual:`cmake-generator-expressions(7)` manual + for details. diff --git a/Help/release/dev/vs-xaml.rst b/Help/release/dev/vs-xaml.rst new file mode 100644 index 0000000..575899f --- /dev/null +++ b/Help/release/dev/vs-xaml.rst @@ -0,0 +1,6 @@ +vs-xaml +------- + +* The :ref:`Visual Studio Generators` learned to support ``.xaml`` + source files and automatically associate them with corresponding + ``.h`` and ``.cpp`` sources. diff --git a/Help/release/dev/vs7-OutputDirectory.rst b/Help/release/dev/vs7-OutputDirectory.rst new file mode 100644 index 0000000..2725d0c --- /dev/null +++ b/Help/release/dev/vs7-OutputDirectory.rst @@ -0,0 +1,10 @@ +vs7-OutputDirectory +------------------- + +* The :variable:`CMAKE_CFG_INTDIR` variable value for Visual Studio + 7, 8, and 9 is now ``$(ConfigurationName)`` instead of ``$(OutDir)``. + This should have no effect on the intended use cases of the variable. + +* With Visual Studio 7, 8, and 9 generators the value of the ``$(OutDir)`` + placeholder no longer evaluates to the configuration name. Projects + should use ``$(ConfigurationName)`` for that instead. diff --git a/Help/release/dev/wix-shortcut-properties.rst b/Help/release/dev/wix-shortcut-properties.rst new file mode 100644 index 0000000..bdd6485 --- /dev/null +++ b/Help/release/dev/wix-shortcut-properties.rst @@ -0,0 +1,9 @@ +wix-shortcut-properties +----------------------- + +* The CPack WIX generator learned the new + :prop_inst:`CPACK_START_MENU_SHORTCUTS`, + :prop_inst:`CPACK_DESKTOP_SHORTCUTS` and + :prop_inst:`CPACK_STARTUP_SHORTCUTS` installed file properties which can + be used to install shorcuts in the Start Menu, on the Desktop and + in the Startup Folder respectively. diff --git a/Help/release/dev/xcode-attribute-genex.rst b/Help/release/dev/xcode-attribute-genex.rst new file mode 100644 index 0000000..3fd5b1c --- /dev/null +++ b/Help/release/dev/xcode-attribute-genex.rst @@ -0,0 +1,5 @@ +xcode-attribute-genex +--------------------- + +* The :prop_tgt:`XCODE_ATTRIBUTE_<an-attribute>` target property learned + to support generator expressions. diff --git a/Help/release/dev/xcode-xctest.rst b/Help/release/dev/xcode-xctest.rst new file mode 100644 index 0000000..7a2f07b --- /dev/null +++ b/Help/release/dev/xcode-xctest.rst @@ -0,0 +1,6 @@ +xcode-xctest +------------ + +* On OS X, CMake learned to create XCTest bundles to test Frameworks + and App Bundles within Xcode. The :module:`FindXCTest` module + provides convenience functions to handle :prop_tgt:`XCTEST` bundles. diff --git a/Help/release/index.rst b/Help/release/index.rst index a058bc1..45d0a69 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,6 +5,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_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_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 |