diff options
Diffstat (limited to 'Help')
29 files changed, 363 insertions, 82 deletions
diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst index b83edaf..6659005 100644 --- a/Help/command/build_command.rst +++ b/Help/command/build_command.rst @@ -14,7 +14,7 @@ This is mainly intended for internal use by the :module:`CTest` module. Sets the given ``<variable>`` to a command-line string of the form:: - <cmake> --build . [--config <config>] [--target <target>] [-- -i] + <cmake> --build . [--config <config>] [--target <target>...] [-- -i] where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line tool, and ``<config>`` and ``<target>`` are the values provided to the diff --git a/Help/command/cmake_parse_arguments.rst b/Help/command/cmake_parse_arguments.rst index c8327e2..196d90f 100644 --- a/Help/command/cmake_parse_arguments.rst +++ b/Help/command/cmake_parse_arguments.rst @@ -59,6 +59,11 @@ All remaining arguments are collected in a variable where recognized. This can be checked afterwards to see whether your macro was called with unrecognized parameters. +``<one_value_keywords>`` and ``<multi_value_keywords>`` that where given no +values at all are collected in a variable ``<prefix>_KEYWORDS_MISSING_VALUES`` +that will be undefined if all keywords received values. This can be checked +to see if there where keywords without any values given. + As an example here a ``my_install()`` macro, which takes similar arguments as the real :command:`install` command: @@ -77,7 +82,7 @@ Assume ``my_install()`` has been called like this: .. code-block:: cmake - my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) + my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS) After the ``cmake_parse_arguments`` call the macro will have set or undefined the following variables:: @@ -89,6 +94,8 @@ the following variables:: MY_INSTALL_TARGETS = "foo;bar" MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL" + MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS" + # No value for "CONFIGURATIONS" given You can then continue and process these variables. @@ -97,5 +104,6 @@ one_value_keyword another recognized keyword follows, this is interpreted as the beginning of the new option. E.g. ``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in ``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL`` -is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and -``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``. +is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty (but added +to ``MY_INSTALL_KEYWORDS_MISSING_VALUES``) and ``MY_INSTALL_OPTIONAL`` will +therefore be set to ``TRUE``. diff --git a/Help/command/install.rst b/Help/command/install.rst index a0e8c37..a4cee71 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -9,11 +9,11 @@ Synopsis .. parsed-literal:: install(`TARGETS`_ <target>... [...]) - install({`FILES`_ | `PROGRAMS`_} <file>... [DESTINATION <dir>] [...]) - install(`DIRECTORY`_ <dir>... [DESTINATION <dir>] [...]) + install({`FILES`_ | `PROGRAMS`_} <file>... [...]) + install(`DIRECTORY`_ <dir>... [...]) install(`SCRIPT`_ <file> [...]) install(`CODE`_ <code> [...]) - install(`EXPORT`_ <export-name> DESTINATION <dir> [...]) + install(`EXPORT`_ <export-name> [...]) Introduction ^^^^^^^^^^^^ @@ -99,6 +99,7 @@ Windows platforms are unaffected. Installing Targets ^^^^^^^^^^^^^^^^^^ +.. _`install(TARGETS)`: .. _TARGETS: .. code-block:: cmake @@ -172,11 +173,20 @@ installation properties apply to all target types. If only one is given then only targets of that type will be installed (which can be used to install just a DLL or just an import library.) -For some target types, the ``DESTINATION`` argument is optional. If no -``DESTINATION`` argument is specified for these target types, the destination -will default to either the appropriate variable from :module:`GNUInstallDirs` -(if it is defined) or a built-in default (if the variable is not defined.) These -defaults are outlined below: +For regular executables, static libraries and shared libraries, the +``DESTINATION`` argument is not required. For these target types, when +``DESTINATION`` is omitted, a default destination will be taken from the +appropriate variable from :module:`GNUInstallDirs`, or set to a built-in +default value if that variable is not defined. The same is true for the +public and private headers associated with the installed targets through the +:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties. +A destination must always be provided for module libraries, Apple bundles and +frameworks. A destination can be omitted for interface and object libraries, +but they are handled differently (see the discussion of this topic toward the +end of this section). + +The following table shows the target types with their associated variables and +built-in defaults that apply when no destination is given: ================== =============================== ====================== Target Type GNUInstallDirs Variable Built-In Default @@ -188,12 +198,28 @@ defaults are outlined below: ``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` ================== =============================== ====================== -To make your package compliant with distribution filesystem layout policies, it -is not recommended that you specify a ``DESTINATION`` for a target unless it -must be installed in a nonstandard location. That way, package maintainers can -control the install destination by setting the appropriate cache variables. In -any case, it is recommended that you use the :module:`GNUInstallDirs` variables -in your ``DESTINATION`` arguments whenever possible. +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. + +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows a static library +being installed to the default destination provided by +:module:`GNUInstallDirs`, but with its headers installed to a project-specific +subdirectory that follows the above recommendation: + +.. code-block:: cmake + + add_library(mylib STATIC ...) + set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h) + include(GNUInstallDirs) + install(TARGETS mylib + PUBLIC_HEADER + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) In addition to the common options listed above, each target can accept the following additional arguments: @@ -218,11 +244,9 @@ the following additional arguments: install(TARGETS mylib LIBRARY - DESTINATION lib COMPONENT Libraries NAMELINK_COMPONENT Development PUBLIC_HEADER - DESTINATION include COMPONENT Development ) @@ -265,18 +289,20 @@ the following additional arguments: is not recommended to use ``NAMELINK_SKIP`` in conjunction with ``NAMELINK_COMPONENT``. -The ``install(TARGETS)`` command can also accept the following options at the +The `install(TARGETS)`_ command can also accept the following options at the top level: ``EXPORT`` This option associates the installed target files with an export called ``<export-name>``. It must appear before any target options. To actually - install the export file itself, call ``install(EXPORT)``, documented below. + install the export file itself, call `install(EXPORT)`_, documented below. + See documentation of the :prop_tgt:`EXPORT_NAME` target property to change + the name of the exported target. ``INCLUDES DESTINATION`` This option specifies a list of directories which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the - ``<targets>`` when exported by the :command:`install(EXPORT)` command. If a + ``<targets>`` when exported by the `install(EXPORT)`_ command. If a relative path is specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. @@ -310,7 +336,7 @@ targets that link to the object libraries in their implementation. Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property set to ``TRUE`` has undefined behavior. -:command:`install(TARGETS)` can install targets that were created in +`install(TARGETS)`_ can install targets that were created in other directories. When using such cross-directory install rules, running ``make install`` (or similar) from a subdirectory will not guarantee that targets from other directories are up-to-date. You can use @@ -318,19 +344,22 @@ targets from other directories are up-to-date. You can use to ensure that such out-of-directory targets are built before the subdirectory-specific install rules are run. -The install destination given to the target install ``DESTINATION`` may +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. Installing Files ^^^^^^^^^^^^^^^^ +.. _`install(FILES)`: +.. _`install(PROGRAMS)`: .. _FILES: .. _PROGRAMS: .. code-block:: cmake - install(<FILES|PROGRAMS> files... [DESTINATION <dir> | TYPE <type>] + install(<FILES|PROGRAMS> files... + TYPE <type> | DESTINATION <dir> [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT <component>] @@ -354,12 +383,14 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use However, if any item begins in a generator expression it must evaluate to a full path. -Instead of specifying ``DESTINATION``, you may specify a generic file type -via the ``TYPE`` argument as listed below. If a type is selected and no -destination is specified, the destination will default to either the -appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a -built-in default (if the variable is not defined.) These defaults are outlined -below: +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files being +installed. A destination will then be set automatically by taking the +corresponding variable from :module:`GNUInstallDirs`, or by using a +built-in default if that variable is not defined. See the table below for +the supported file types and their corresponding variables and built-in +defaults. Projects can provide a ``DESTINATION`` argument instead of a +file type if they wish to explicitly define the install destination. ======================= ================================== ========================= ``TYPE`` Argument GNUInstallDirs Variable Built-In Default @@ -379,7 +410,9 @@ below: ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ======================= ================================== ========================= -It is an error to use ``TYPE`` and ``DESTINATION`` arguments together. +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with @@ -387,26 +420,34 @@ a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use ``DATA`` instead. -To make your package compliant with distribution filesystem layout policies, it -is recommended that you specify one of the above generic file types, rather than -a ``DESTINATION`` argument, unless the files must be installed in a nonstandard -location. That way, package maintainers can control the install destination by -setting the appropriate cache variables. In any case, it is recommended that you -use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments -whenever possible. +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows how to follow +this advice while installing headers to a project-specific subdirectory: -The install destination given to the files install ``DESTINATION`` may +.. code-block:: cmake + + include(GNUInstallDirs) + install(FILES mylib.h + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) + +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. Installing Directories ^^^^^^^^^^^^^^^^^^^^^^ +.. _`install(DIRECTORY)`: .. _DIRECTORY: .. code-block:: cmake - install(DIRECTORY dirs... [DESTINATION <dir> | TYPE <type>] + install(DIRECTORY dirs... + TYPE <type> | DESTINATION <dir> [FILE_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS permissions...] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] @@ -477,12 +518,15 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the file permissions, the scripts will be given specific permissions, and any ``CVS`` directories will be excluded. -Instead of specifying ``DESTINATION``, you may specify a generic file type -via the ``TYPE`` argument as listed below. If a type is selected and no -destination is specified, the destination will default to either the -appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a -built-in default (if the variable is not defined.) These defaults are outlined -below: +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files within the +listed directories being installed. A destination will then be set +automatically by taking the corresponding variable from +:module:`GNUInstallDirs`, or by using a built-in default if that variable +is not defined. See the table below for the supported file types and their +corresponding variables and built-in defaults. Projects can provide a +``DESTINATION`` argument instead of a file type if they wish to explicitly +define the install destination. ======================= ================================== ========================= ``TYPE`` Argument GNUInstallDirs Variable Built-In Default @@ -502,30 +546,28 @@ below: ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ======================= ================================== ========================= -It is an error to use ``TYPE`` and ``DESTINATION`` arguments together. - Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use ``DATA`` instead. -To make your package compliant with distribution filesystem layout policies, it -is recommended that you specify one of the above generic file types, rather than -a ``DESTINATION`` argument, unless the files must be installed in a nonstandard -location. That way, package maintainers can control the install destination by -setting the appropriate cache variables. In any case, it is recommended that you -use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments -whenever possible. +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. -The list of ``dirs...`` given to ``DIRECTORY`` and the install destination -given to the directory install ``DESTINATION`` may use "generator expressions" +The list of ``dirs...`` given to ``DIRECTORY`` and an install destination +given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. Custom Installation Logic ^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _`install(CODE)`: +.. _`install(SCRIPT)`: .. _CODE: .. _SCRIPT: @@ -555,6 +597,7 @@ name, not the file's contents). See the Installing Exports ^^^^^^^^^^^^^^^^^^ +.. _`install(EXPORT)`: .. _EXPORT: .. code-block:: cmake @@ -571,7 +614,7 @@ Installing Exports The ``EXPORT`` form generates and installs a CMake file containing code to import targets from the installation tree into another project. Target installations are associated with the export ``<export-name>`` -using the ``EXPORT`` option of the ``install(TARGETS)`` signature +using the ``EXPORT`` option of the `install(TARGETS)`_ signature documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to the target names as they are written to the import file. By default the generated file will be called ``<export-name>.cmake`` but the ``FILE`` diff --git a/Help/command/list.rst b/Help/command/list.rst index bfcdf34..4444af7 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -21,6 +21,9 @@ Synopsis list(`APPEND`_ <list> [<element>...]) list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>) list(`INSERT`_ <list> <index> [<element>...]) + list(`POP_BACK`_ <list> [<out-var>...]) + list(`POP_FRONT`_ <list> [<out-var>...]) + list(`PREPEND`_ <list> [<element>...]) list(`REMOVE_ITEM`_ <list> <value>...) list(`REMOVE_AT`_ <list> <index>...) list(`REMOVE_DUPLICATES`_ <list>) @@ -33,8 +36,9 @@ Synopsis Introduction ^^^^^^^^^^^^ -The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``, -``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create +The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``PREPEND``, +``POP_BACK``, ``POP_FRONT``, ``REMOVE_AT``, ``REMOVE_ITEM``, +``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create new values for the list within the current CMake variable scope. Similar to the :command:`set` command, the LIST command creates new variable values in the current scope, even if the list itself is actually defined in a parent @@ -142,6 +146,34 @@ For more information on regular expressions see also the Inserts elements to the list to the specified location. +.. _POP_BACK: + +.. code-block:: cmake + + list(POP_BACK <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the last element's value to the given variable and removes it, +up to the last variable name given. + +.. _POP_FRONT: + +.. code-block:: cmake + + list(POP_FRONT <list> [<out-var>...]) + +If no variable name is given, removes exactly one element. Otherwise, +assign the first element's value to the given variable and removes it, +up to the last variable name given. + +.. _PREPEND: + +.. code-block:: cmake + + list(PREPEND <list> [<element> ...]) + +Insert elements to the 0th position in the list. + .. _REMOVE_ITEM: .. code-block:: cmake @@ -164,7 +196,8 @@ Removes items at given indices from the list. list(REMOVE_DUPLICATES <list>) -Removes duplicated items in the list. +Removes duplicated items in the list. The relative order of items is preserved, +but if duplicates are encountered, only the first instance is preserved. .. _TRANSFORM: diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index 71430c7..d893ac5 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -3,9 +3,7 @@ Xcode Generate Xcode project files. -This supports Xcode 3.0 and above. Support for Xcode versions prior -to Xcode 5 is deprecated and will be dropped in a future version of -CMake. +This supports Xcode 5.0 and above. Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 409b5b1..9470d6c 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.15 +================================= + +.. toctree:: + :maxdepth: 1 + + CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089> + Policies Introduced by CMake 3.14 ================================= diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index ef86412..16c3460 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -334,6 +334,7 @@ Properties on Targets /prop_tgt/VS_IOT_STARTUP_TASK /prop_tgt/VS_KEYWORD /prop_tgt/VS_MOBILE_EXTENSIONS_VERSION + /prop_tgt/VS_NO_SOLUTION_DEPLOY /prop_tgt/VS_SCC_AUXPATH /prop_tgt/VS_SCC_LOCALPATH /prop_tgt/VS_SCC_PROJECTNAME diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index d214e4a..ba44b7f 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -556,6 +556,54 @@ command is sufficient: cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS +Variable :variable:`CMAKE_OSX_ARCHITECTURES` can be used to set architectures +for both device and simulator. Variable :variable:`CMAKE_OSX_DEPLOYMENT_TARGET` +can be used to set an iOS/tvOS/watchOS deployment target. + +Next configuration will install fat 5 architectures iOS library +and add the ``-miphoneos-version-min=9.3``/``-mios-simulator-version-min=9.3`` +flags to the compiler: + +.. code-block:: console + + $ cmake -S. -B_builds -GXcode \ + -DCMAKE_SYSTEM_NAME=iOS \ + "-DCMAKE_OSX_ARCHITECTURES=armv7;armv7s;arm64;i386;x86_64" \ + -DCMAKE_OSX_DEPLOYMENT_TARGET=9.3 \ + -DCMAKE_INSTALL_PREFIX=`pwd`/_install \ + -DCMAKE_XCODE_ATTRIBUTE_ONLY_ACTIVE_ARCH=NO \ + -DCMAKE_IOS_INSTALL_COMBINED=YES + +Example: + +.. code-block:: cmake + + # CMakeLists.txt + cmake_minimum_required(VERSION 3.14) + project(foo) + add_library(foo foo.cpp) + install(TARGETS foo DESTINATION lib) + +Install: + +.. code-block:: console + + $ cmake --build _builds --config Release --target install + +Check library: + +.. code-block:: console + + $ lipo -info _install/lib/libfoo.a + Architectures in the fat file: _install/lib/libfoo.a are: i386 armv7 armv7s x86_64 arm64 + +.. code-block:: console + + $ otool -l _install/lib/libfoo.a | grep -A2 LC_VERSION_MIN_IPHONEOS + cmd LC_VERSION_MIN_IPHONEOS + cmdsize 16 + version 9.3 + Code Signing ^^^^^^^^^^^^ @@ -592,4 +640,14 @@ Please note that checks made during configuration were performed against the configure-time SDK and might not hold true for other SDKs. Commands like :command:`find_package`, :command:`find_library`, etc. store and use details only for the configured SDK/platform, so they can be problematic -if wanting to switch between device and simulator builds. +if wanting to switch between device and simulator builds. You can follow +the next rules to make device + simulator configuration work: + +- Use explicit ``-l`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-lz")`` + +- Use explicit ``-framework`` linker flag, + e.g. ``target_link_libraries(foo PUBLIC "-framework CoreFoundation")`` + +- Use :command:`find_package` only for libraries installed with + :variable:`CMAKE_IOS_INSTALL_COMBINED` feature diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 52628c8..6bb30cb 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -259,6 +259,7 @@ Variables that Describe the System /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN /variable/GHS-MULTI + /variable/IOS /variable/MINGW /variable/MSVC /variable/MSVC10 diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index f3b81ec..e9a08b5 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -276,8 +276,8 @@ following options: The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set, specifies a default parallel level when this option is not given. -``--target <tgt>`` - Build ``<tgt>`` instead of default targets. May only be specified once. +``--target <tgt>...`` + Build ``<tgt>`` instead of default targets. May be specified multiple times. ``--config <cfg>`` For multi-configuration tools, choose configuration ``<cfg>``. diff --git a/Help/policy/CMP0089.rst b/Help/policy/CMP0089.rst new file mode 100644 index 0000000..e549e0c --- /dev/null +++ b/Help/policy/CMP0089.rst @@ -0,0 +1,30 @@ +CMP0089 +------- + +Compiler id for IBM Clang-based XL compilers is now ``XLClang``. + +CMake 3.15 and above recognize that IBM's Clang-based XL compilers +that define ``__ibmxl__`` are a new front-end distinct from ``xlc`` +with a different command line and set of capabilities. +CMake now prefers to present this to projects by setting the +:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``XLClang`` instead +of ``XL``. However, existing projects may assume the compiler id for +Clang-based XL is just ``XL`` as it was in CMake versions prior to 3.15. +Therefore this policy determines for Clang-based XL compilers which +compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID` +variable after language ``<LANG>`` is enabled by the :command:`project` +or :command:`enable_language` command. The policy must be set prior +to the invocation of either command. + +The OLD behavior for this policy is to use compiler id ``XL``. The +NEW behavior for this policy is to use compiler id ``XLClang``. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. +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_CMP0089 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/prop_sf/OBJECT_OUTPUTS.rst b/Help/prop_sf/OBJECT_OUTPUTS.rst index 6a28553..1ce4866 100644 --- a/Help/prop_sf/OBJECT_OUTPUTS.rst +++ b/Help/prop_sf/OBJECT_OUTPUTS.rst @@ -1,9 +1,9 @@ OBJECT_OUTPUTS -------------- -Additional outputs for a Makefile rule. +Additional outputs for a Ninja or Makefile rule. Additional outputs created by compilation of this source file. If any of these outputs is missing the object will be recompiled. This is -supported only on Makefile generators and will be ignored on other -generators. +supported only on the Ninja and Makefile generators and will be ignored on +other generators. diff --git a/Help/prop_tgt/EXPORT_NAME.rst b/Help/prop_tgt/EXPORT_NAME.rst index 1b4247c..043c57a 100644 --- a/Help/prop_tgt/EXPORT_NAME.rst +++ b/Help/prop_tgt/EXPORT_NAME.rst @@ -3,6 +3,6 @@ EXPORT_NAME Exported name for target files. -This sets the name for the IMPORTED target generated when it this -target is is exported. If not set, the logical target name is used by -default. +This sets the name for the IMPORTED target generated by the +:command:`install(EXPORT)` and :command:`export` commands. +If not set, the logical target name is used by default. diff --git a/Help/prop_tgt/VS_NO_SOLUTION_DEPLOY.rst b/Help/prop_tgt/VS_NO_SOLUTION_DEPLOY.rst new file mode 100644 index 0000000..ffcbde5 --- /dev/null +++ b/Help/prop_tgt/VS_NO_SOLUTION_DEPLOY.rst @@ -0,0 +1,46 @@ +VS_NO_SOLUTION_DEPLOY +--------------------- + +Specify that the target should not be marked for deployment to a Windows CE +or Windows Phone device in the generated Visual Studio solution. + +Be default, all EXE and shared library (DLL) targets are marked to deploy to +the target device in the generated Visual Studio solution. + +Generator expressions are supported. + +There are reasons one might want to exclude a target / generated project from +deployment: + +- The library or executable may not be necessary in the primary deploy/debug + scenario, and excluding from deployment saves time in the + develop/download/debug cycle. +- There may be insufficient space on the target device to accommodate all of + the build products. +- Visual Studio 2013 requires a target device IP address be entered for each + target marked for deployment. For large numbers of targets, this can be + tedious. + NOTE: Visual Studio *will* deploy all project dependencies of a project + tagged for deployment to the IP address configured for that project even + if those dependencies are not tagged for deployment. + + +Example 1 +^^^^^^^^^ + +This shows setting the variable for the target foo. + +.. code-block:: cmake + + add_library(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY ON) + +Example 2 +^^^^^^^^^ + +This shows setting the variable for the Release configuration only. + +.. code-block:: cmake + + add_library(foo SHARED foo.cpp) + set_property(TARGET foo PROPERTY VS_NO_SOLUTION_DEPLOY "$<CONFIG:Release>") 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/FindCups-imported-target.rst b/Help/release/dev/FindCups-imported-target.rst new file mode 100644 index 0000000..0fd9178 --- /dev/null +++ b/Help/release/dev/FindCups-imported-target.rst @@ -0,0 +1,4 @@ +FindCups-imported-target +------------------------ + +* The :module:`FindCups` module now provides imported targets. diff --git a/Help/release/dev/add-xlclang.rst b/Help/release/dev/add-xlclang.rst new file mode 100644 index 0000000..77ff938 --- /dev/null +++ b/Help/release/dev/add-xlclang.rst @@ -0,0 +1,5 @@ +add-xlclang +----------- + +* IBM Clang-based XL compilers that define ``__ibmxl__`` now use the + compiler id ``XLClang`` instead of ``XL``. See policy :policy:`CMP0089`. diff --git a/Help/release/dev/cmake-build-multiply-targets.rst b/Help/release/dev/cmake-build-multiply-targets.rst new file mode 100644 index 0000000..1275ca3 --- /dev/null +++ b/Help/release/dev/cmake-build-multiply-targets.rst @@ -0,0 +1,5 @@ +cmake-build-multiply-targets +---------------------------- + +* The :manual:`cmake(1)` ``--build`` tool ``--target`` parameter gained support for + multiple targets, e.g. ``cmake --build . --target Library1 Library2``. diff --git a/Help/release/dev/cmake_parse_arguments-keywords_missing_values.rst b/Help/release/dev/cmake_parse_arguments-keywords_missing_values.rst new file mode 100644 index 0000000..c7fe96b --- /dev/null +++ b/Help/release/dev/cmake_parse_arguments-keywords_missing_values.rst @@ -0,0 +1,6 @@ +cmake_parse_arguments-keywords_missing_values +--------------------------------------------- + +* The :command:`cmake_parse_arguments` command gained an additional + ``<prefix>_KEYWORDS_MISSING_VALUES`` output variable to report + keyword arguments that were given by the caller with no values. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst new file mode 100644 index 0000000..b94f4b7 --- /dev/null +++ b/Help/release/dev/deprecate-policy-old.rst @@ -0,0 +1,8 @@ +deprecate-policy-old +-------------------- + +* An explicit deprecation diagnostic was added for policy ``CMP0066`` + (``CMP0065`` and below were already deprecated). + The :manual:`cmake-policies(7)` manual explains that the OLD behaviors + of all policies are deprecated and that projects should port to the + NEW behaviors. diff --git a/Help/release/dev/list-prepend-and-pop-subcommands.rst b/Help/release/dev/list-prepend-and-pop-subcommands.rst new file mode 100644 index 0000000..16b14f1 --- /dev/null +++ b/Help/release/dev/list-prepend-and-pop-subcommands.rst @@ -0,0 +1,4 @@ +list-prepend-and-pop-subcommands +-------------------------------- + +* :command:`list` learned new sub-commands ``PREPEND``, ``POP_FRONT`` and ``POP_BACK``. diff --git a/Help/release/dev/require-xcode-5.rst b/Help/release/dev/require-xcode-5.rst new file mode 100644 index 0000000..6cfe96a --- /dev/null +++ b/Help/release/dev/require-xcode-5.rst @@ -0,0 +1,4 @@ +require-xcode-5 +--------------- + +* The :generator:`Xcode` generator now requires at least Xcode 5. diff --git a/Help/release/dev/vs-wince-no-deploy.rst b/Help/release/dev/vs-wince-no-deploy.rst new file mode 100644 index 0000000..6c18d895 --- /dev/null +++ b/Help/release/dev/vs-wince-no-deploy.rst @@ -0,0 +1,6 @@ +vs_wince_no_deploy +------------------ + +* A :prop_tgt:`VS_NO_SOLUTION_DEPLOY` target property was added to + tell :ref:`Visual Studio Generators` whether to deploy an artifact + to the WinCE or Windows Phone target device. diff --git a/Help/release/index.rst b/Help/release/index.rst index 4fcd4ca..2318e03 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,6 +7,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_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 5323880..2bb3979 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -24,7 +24,6 @@ include: HP = Hewlett-Packard Compiler (hp.com) IAR = IAR Systems (iar.com) Intel = Intel Compiler (intel.com) - MIPSpro = SGI MIPSpro (sgi.com) MSVC = Microsoft Visual Studio (microsoft.com) NVIDIA = NVIDIA CUDA Compiler (nvidia.com) OpenWatcom = Open Watcom (openwatcom.org) diff --git a/Help/variable/CMAKE_MACOSX_BUNDLE.rst b/Help/variable/CMAKE_MACOSX_BUNDLE.rst index 0badaf0..43ddff5 100644 --- a/Help/variable/CMAKE_MACOSX_BUNDLE.rst +++ b/Help/variable/CMAKE_MACOSX_BUNDLE.rst @@ -5,3 +5,6 @@ Default value for :prop_tgt:`MACOSX_BUNDLE` of targets. This variable is used to initialize the :prop_tgt:`MACOSX_BUNDLE` property on all the targets. See that target property for additional information. + +This variable is set to ``ON`` by default if :variable:`CMAKE_SYSTEM_NAME` +equals to :ref:`iOS, tvOS or watchOS <Cross Compiling for iOS, tvOS, or watchOS>`. diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst index 4f5a50f..56df2df 100644 --- a/Help/variable/CMAKE_MAKE_PROGRAM.rst +++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst @@ -19,15 +19,11 @@ to configure the project: This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache so that it may be edited by the user. -* The :generator:`Xcode` generator sets this to ``xcodebuild`` (or possibly an - otherwise undocumented ``cmakexbuild`` wrapper implementing some - workarounds). +* The :generator:`Xcode` generator sets this to ``xcodebuild``. This generator prefers to lookup the build tool at build time rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache - ahead of time. This is because ``xcodebuild`` is easy to find, - the ``cmakexbuild`` wrapper is needed only for older Xcode versions, - and the path to ``cmakexbuild`` may be outdated if CMake itself moves. + ahead of time. This is because ``xcodebuild`` is easy to find. For compatibility with versions of CMake prior to 3.2, if a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to diff --git a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst index d179728..fc52e7b 100644 --- a/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst +++ b/Help/variable/CMAKE_POLICY_WARNING_CMPNNNN.rst @@ -21,6 +21,8 @@ warn by default: policy :policy:`CMP0067`. * ``CMAKE_POLICY_WARNING_CMP0082`` controls the warning for policy :policy:`CMP0082`. +* ``CMAKE_POLICY_WARNING_CMP0089`` controls the warning for + policy :policy:`CMP0089`. This variable should not be set by a project in CMake code. Project developers running CMake may set this variable in their cache to diff --git a/Help/variable/IOS.rst b/Help/variable/IOS.rst new file mode 100644 index 0000000..e5cc3f6 --- /dev/null +++ b/Help/variable/IOS.rst @@ -0,0 +1,4 @@ +IOS +--- + +Set to ``1`` when the target system (:variable:`CMAKE_SYSTEM_NAME`) is ``iOS``. |