diff options
Diffstat (limited to 'Help')
95 files changed, 695 insertions, 478 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index db4d6fc..465e567 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -26,8 +26,8 @@ Synopsis file(`MAKE_DIRECTORY`_ [<dir>...]) file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) file(`SIZE`_ <filename> <out-var>) - file(`READ_SYMLINK`_ <filename> <out-var>) - file(`CREATE_LINK`_ <file> <new-file> [...]) + file(`READ_SYMLINK`_ <linkname> <out-var>) + file(`CREATE_LINK`_ <original> <linkname> [...]) `Path Conversion`_ file(`RELATIVE_PATH`_ <out-var> <directory> <file>) @@ -350,22 +350,22 @@ pointing to a file and is readable. .. code-block:: cmake - file(READ_SYMLINK <filename> <variable>) + file(READ_SYMLINK <linkname> <variable>) -Read the symlink at ``<filename>`` and put the result in ``<variable>``. -Requires that ``<filename>`` is a valid path pointing to a symlink. If -``<filename>`` does not exist, or is not a symlink, an error is thrown. +This subcommand queries the symlink ``<linkname>`` and stores the path it +points to in the result ``<variable>``. If ``<linkname>`` does not exist or +is not a symlink, CMake issues a fatal error. Note that this command returns the raw symlink path and does not resolve -relative symlinks. If you want to resolve the relative symlink yourself, you -could do something like this: +a relative path. The following is an example of how to ensure that an +absolute path is obtained: .. code-block:: cmake - set(filename "/path/to/foo.sym") - file(READ_SYMLINK "${filename}" result) + set(linkname "/path/to/foo.sym") + file(READ_SYMLINK "${linkname}" result) if(NOT IS_ABSOLUTE "${result}") - get_filename_component(dir "${filename}" DIRECTORY) + get_filename_component(dir "${linkname}" DIRECTORY) set(result "${dir}/${result}") endif() @@ -373,23 +373,23 @@ could do something like this: .. code-block:: cmake - file(CREATE_LINK <file> <new-file> + file(CREATE_LINK <original> <linkname> [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) -Create a link to ``<file>`` at ``<new-file>``. +Create a link ``<linkname>`` that points to ``<original>``. +It will be a hard link by default, but providing the ``SYMBOLIC`` option +results in a symbolic link instead. Hard links require that ``original`` +exists and is a file, not a directory. If ``<linkname>`` already exists, +it will be overwritten. -It is a hard link by default. This can be changed to symbolic links by -using ``SYMBOLIC``. The original file needs to exist for hard links. - -The ``<result>`` variable, if specified, gets the status of the operation. -It is set to ``0`` in case of success. Otherwise, it contains the error -generated. In case of failures, if ``RESULT`` is not specified, a fatal error -is emitted. +The ``<result>`` variable, if specified, receives the status of the operation. +It is set to ``0`` upon success or an error message otherwise. If ``RESULT`` +is not specified and the operation fails, a fatal error is emitted. Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if -creating the link fails. - -Overwrites the ``<new-file>`` if it exists. +creating the link fails. It can be useful for handling situations such as +``<original>`` and ``<linkname>`` being on different drives or mount points, +which would make them unable to support a hard link. Path Conversion ^^^^^^^^^^^^^^^ diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 3e3c9c3..9bbf877 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -15,12 +15,13 @@ Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of: NAME = File name without directory EXT = File name longest extension (.b.c from d/a.b.c) NAME_WE = File name without directory or longest extension + LAST_EXT = File name last extension (.c from d/a.b.c) + NAME_WLE = File name without directory or last extension PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11) Paths are returned with forward slashes and have no trailing slashes. -The longest file extension is always considered. If the optional -``CACHE`` argument is specified, the result variable is added to the -cache. +If the optional ``CACHE`` argument is specified, the result variable is +added to the cache. .. code-block:: cmake diff --git a/Help/command/if.rst b/Help/command/if.rst index a682c83..a48a0fa 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -23,7 +23,7 @@ Otherwise, optional ``elseif`` blocks are processed in the same way. Finally, if no ``condition`` is true, ``commands`` in the optional ``else`` block are executed. -Per legacy, the :command:`else` and :command:`elseif` commands admit +Per legacy, the :command:`else` and :command:`endif` commands admit an optional ``<condition>`` argument. If used, it must be a verbatim repeat of the argument of the opening diff --git a/Help/command/set.rst b/Help/command/set.rst index dd5ea13..c0e02e2 100644 --- a/Help/command/set.rst +++ b/Help/command/set.rst @@ -86,7 +86,7 @@ Set Environment Variable .. code-block:: cmake - set(ENV{<variable>} <value>...) + set(ENV{<variable>} [<value>]) Sets an :manual:`Environment Variable <cmake-env-variables(7)>` to the given value. @@ -95,3 +95,10 @@ Subsequent calls of ``$ENV{<variable>}`` will return this new value. This command affects only the current CMake process, not the process from which CMake was called, nor the system environment at large, nor the environment of subsequent build or test processes. + +If no argument is given after ``ENV{<variable>}`` or if ``<value>`` is +an empty string, then this command will clear any existing value of the +environment variable. + +Arguments after ``<value>`` are ignored. If extra arguments are found, +then an author warning is issued. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index 77f42a1..ca8fc77 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -12,12 +12,12 @@ Try Compiling Whole Projects .. code-block:: cmake - try_compile(RESULT_VAR <bindir> <srcdir> + try_compile(<resultVar> <bindir> <srcdir> <projectName> [<targetName>] [CMAKE_FLAGS <flags>...] [OUTPUT_VARIABLE <var>]) Try building a project. The success or failure of the ``try_compile``, -i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``RESULT_VAR``. +i.e. ``TRUE`` or ``FALSE`` respectively, is returned in ``<resultVar>``. In this form, ``<srcdir>`` should contain a complete CMake project with a ``CMakeLists.txt`` file and all sources. The ``<bindir>`` and ``<srcdir>`` @@ -30,7 +30,7 @@ Try Compiling Source Files .. code-block:: cmake - try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...> + try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] @@ -42,13 +42,19 @@ Try Compiling Source Files [<LANG>_EXTENSIONS <bool>] ) -Try building an executable from one or more source files. The success or -failure of the ``try_compile``, i.e. ``TRUE`` or ``FALSE`` respectively, is -returned in ``RESULT_VAR``. +Try building an executable or static library from one or more source files +(which one is determined by the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` +variable). The success or failure of the ``try_compile``, i.e. ``TRUE`` or +``FALSE`` respectively, is returned in ``<resultVar>``. -In this form the user need only supply one or more source files that include a -definition for ``main``. CMake will create a ``CMakeLists.txt`` file to build -the source(s) as an executable that looks something like this: +In this form, one or more source files must be provided. If +:variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is unset or is set to ``EXECUTABLE``, +the sources must include a definition for ``main`` and CMake will create a +``CMakeLists.txt`` file to build the source(s) as an executable. +If :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` is set to ``STATIC_LIBRARY``, +a static library will be built instead and no definition for ``main`` is +required. For an executable, the generated ``CMakeLists.txt`` file would +contain something like the following: .. code-block:: cmake @@ -73,7 +79,7 @@ The options are: in the generated test project. ``COPY_FILE <fileName>`` - Copy the linked executable to the given ``<fileName>``. + Copy the built executable or static library to the given ``<fileName>``. ``COPY_FILE_ERROR <var>`` Use after ``COPY_FILE`` to capture into variable ``<var>`` any error @@ -88,12 +94,12 @@ The options are: given to the ``CMAKE_FLAGS`` option will be ignored. ``LINK_OPTIONS <options>...`` - Specify link step options to pass to :command:`target_link_options` or - to :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated - project, depending of the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. + Specify link step options to pass to :command:`target_link_options` or to + set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated + project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable. ``OUTPUT_VARIABLE <var>`` - Store the output from the build process the given variable. + Store the output from the build process in the given variable. ``<LANG>_STANDARD <std>`` Specify the :prop_tgt:`C_STANDARD`, :prop_tgt:`CXX_STANDARD`, @@ -114,7 +120,7 @@ passed to ``cmake`` to avoid this clean. However, multiple sequential ``try_compile`` operations reuse this single output directory. If you use ``--debug-trycompile``, you can only debug one ``try_compile`` call at a time. The recommended procedure is to protect all ``try_compile`` calls in your -project by ``if(NOT DEFINED RESULT_VAR)`` logic, configure with cmake +project by ``if(NOT DEFINED <resultVar>)`` logic, configure with cmake all the way through once, then delete the cache entry associated with the try_compile call of interest, and then re-run cmake again with ``--debug-trycompile``. @@ -139,8 +145,8 @@ behavior at link time, the ``check_pie_supported()`` command from the :module:`CheckPIESupported` module must be called before using the :command:`try_compile` command. -The current settings of :policy:`CMP0065` and :policy:`CMP0083` are set in the -generated project. +The current settings of :policy:`CMP0065` and :policy:`CMP0083` are propagated +through to the generated test project. Set the :variable:`CMAKE_TRY_COMPILE_CONFIGURATION` variable to choose a build configuration. @@ -150,7 +156,9 @@ the type of target used for the source file signature. Set the :variable:`CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` variable to specify variables that must be propagated into the test project. This variable is -meant for use only in toolchain files. +meant for use only in toolchain files and is only honored by the +``try_compile()`` command for the source files form, not when given a whole +project. If :policy:`CMP0067` is set to ``NEW``, or any of the ``<LANG>_STANDARD``, ``<LANG>_STANDARD_REQUIRED``, or ``<LANG>_EXTENSIONS`` options are used, diff --git a/Help/command/try_run.rst b/Help/command/try_run.rst index 137402f..d401ebe 100644 --- a/Help/command/try_run.rst +++ b/Help/command/try_run.rst @@ -12,8 +12,8 @@ Try Compiling and Running Source Files .. code-block:: cmake - try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR - bindir srcfile [CMAKE_FLAGS <flags>...] + try_run(<runResultVar> <compileResultVar> + <bindir> <srcfile> [CMAKE_FLAGS <flags>...] [COMPILE_DEFINITIONS <defs>...] [LINK_OPTIONS <options>...] [LINK_LIBRARIES <libs>...] @@ -23,9 +23,9 @@ Try Compiling and Running Source Files [ARGS <args>...]) Try compiling a ``<srcfile>``. Returns ``TRUE`` or ``FALSE`` for success -or failure in ``COMPILE_RESULT_VAR``. If the compile succeeded, runs the -executable and returns its exit code in ``RUN_RESULT_VAR``. If the -executable was built, but failed to run, then ``RUN_RESULT_VAR`` will be +or failure in ``<compileResultVar>``. If the compile succeeded, runs the +executable and returns its exit code in ``<runResultVar>``. If the +executable was built, but failed to run, then ``<runResultVar>`` will be set to ``FAILED_TO_RUN``. See the :command:`try_compile` command for information on how the test project is constructed to build the source file. @@ -85,10 +85,10 @@ 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. These cache entries are: -``<RUN_RESULT_VAR>`` +``<runResultVar>`` Exit code if the executable were to be run on the target platform. -``<RUN_RESULT_VAR>__TRYRUN_OUTPUT`` +``<runResultVar>__TRYRUN_OUTPUT`` Output from stdout and stderr if the executable were to be run on the target platform. This is created only if the ``RUN_OUTPUT_VARIABLE`` or ``OUTPUT_VARIABLE`` option was used. diff --git a/Help/dev/review.rst b/Help/dev/review.rst index 0c4eded..1d664c4 100644 --- a/Help/dev/review.rst +++ b/Help/dev/review.rst @@ -238,12 +238,10 @@ Referencing Commits in Commit Messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The preferred form for references to other commits is -``commit <commit> (<subject>, <date>)``, where: +``commit <shorthash> (<subject>, <date>)``, where: -* ``<commit>``: - If available, a tag-relative name of the commit produced by - ``git describe --contains <commit-ish>``. Otherwise, the first - 8-10 characters of the commit ``<hash>``. +* ``<shorthash>``: + The abbreviated hash of the commit. * ``<subject>``: The first line of the commit message. @@ -252,6 +250,17 @@ The preferred form for references to other commits is The author date of the commit, in its original time zone, formatted as ``CCYY-MM-DD``. ``git-log(1)`` shows the original time zone by default. +This may be generated with +``git show -s --date=short --pretty="format:%h (%s, %ad)" <commit>``. + +If the commit is a fix for the mentioned commit, consider using a ``Fixes:`` +trailer in the commit message with the specified format. This trailer should +not be word-wrapped. Note that if there is also an issue for what is being +fixed, it is preferrable to link to the issue instead. + +If relevant, add the first release tag of CMake containing the commit after +the ``<date>``, i.e., ``commit <shorthash> (<subject>, <date>, <tag>)``. + Alternatively, the full commit ``<hash>`` may be used. Revising Commit Messages diff --git a/Help/dev/source.rst b/Help/dev/source.rst index 6697d38..47baff4 100644 --- a/Help/dev/source.rst +++ b/Help/dev/source.rst @@ -30,16 +30,6 @@ building on older toolchains some constructs need to be handled with care: The ``std::auto_ptr`` template is deprecated in C++11. Use ``std::unique_ptr``. -* Use ``CM_DISABLE_COPY(Class)`` to mark classes as non-copyable. - - The ``CM_DISABLE_COPY`` macro should be used in the private section of a - class to make sure that attempts to copy or assign an instance of the class - lead to compiler errors even if the compiler does not support *deleted* - functions. As a guideline, all polymorphic classes should be made - non-copyable in order to avoid slicing. Classes that are composed of or - derived from non-copyable classes must also be made non-copyable explicitly - with ``CM_DISABLE_COPY``. - Source Tree Layout ================== diff --git a/Help/envvar/CMAKE_NO_VERBOSE.rst b/Help/envvar/CMAKE_NO_VERBOSE.rst new file mode 100644 index 0000000..149efbd --- /dev/null +++ b/Help/envvar/CMAKE_NO_VERBOSE.rst @@ -0,0 +1,8 @@ +CMAKE_NO_VERBOSE +---------------- + +Disables verbose output from CMake when :envvar:`VERBOSE` environment variable +is set. + +Only your build tool of choice will still print verbose output when you start +to actually build your project. diff --git a/Help/envvar/VERBOSE.rst b/Help/envvar/VERBOSE.rst new file mode 100644 index 0000000..2d775a5 --- /dev/null +++ b/Help/envvar/VERBOSE.rst @@ -0,0 +1,10 @@ +VERBOSE +------- + +Activates verbose output from CMake and your build tools of choice when +you start to actually build your project. + +Note that any given value is ignored. It's just checked for existence. + +See also :ref:`Build Tool Mode <Build Tool Mode>` and +:envvar:`CMAKE_NO_VERBOSE` environment variable diff --git a/Help/generator/Green Hills MULTI.rst b/Help/generator/Green Hills MULTI.rst index bfe671f..e474682 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -59,6 +59,7 @@ Customizations are available through the following cache variables: The following properties are available: * :prop_tgt:`GHS_INTEGRITY_APP` +* :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` .. note:: This generator is deemed experimental as of CMake |release| diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt index 5d13e77..4eb900f 100644 --- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -1,6 +1,7 @@ For each toolset that comes with this version of Visual Studio, there are variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts -(independent of the architecture they target). By default Visual Studio -chooses the 32-bit variant even on a 64-bit host. One may request use of the -64-bit host tools by adding a ``host=x64`` option to the toolset specification. +(independent of the architecture they target). +|VS_TOOLSET_HOST_ARCH_DEFAULT| +One may explicitly request use of either the 32-bit or 64-bit host tools +by adding either ``host=x86`` or ``host=x64`` to the toolset specification. See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst index d342c53..fb8e021 100644 --- a/Help/generator/Visual Studio 12 2013.rst +++ b/Help/generator/Visual Studio 12 2013.rst @@ -42,4 +42,7 @@ The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst index 106b7c5..7383f7a 100644 --- a/Help/generator/Visual Studio 14 2015.rst +++ b/Help/generator/Visual Studio 14 2015.rst @@ -39,4 +39,7 @@ The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst index 52c1fa0..7e6f0fb 100644 --- a/Help/generator/Visual Studio 15 2017.rst +++ b/Help/generator/Visual Studio 15 2017.rst @@ -56,4 +56,7 @@ The ``v141`` toolset that comes with Visual Studio 15 2017 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 32-bit variant even on a 64-bit host. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst index 6f2bc56..b456554 100644 --- a/Help/generator/Visual Studio 16 2019.rst +++ b/Help/generator/Visual Studio 16 2019.rst @@ -46,4 +46,8 @@ The ``v142`` toolset that comes with Visual Studio 16 2019 is selected by default. The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps via the :manual:`cmake(1)` ``-T`` option, to specify another toolset. +.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace:: + By default this generator uses the 64-bit variant on x64 hosts and + the 32-bit variant otherwise. + .. include:: VS_TOOLSET_HOST_ARCH.txt diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst index 968c26a..71430c7 100644 --- a/Help/generator/Xcode.rst +++ b/Help/generator/Xcode.rst @@ -3,7 +3,9 @@ Xcode Generate Xcode project files. -This supports Xcode 3.0 and above. +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. Toolset Selection ^^^^^^^^^^^^^^^^^ diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst index edf80f4..c433412 100644 --- a/Help/manual/cmake-env-variables.7.rst +++ b/Help/manual/cmake-env-variables.7.rst @@ -24,11 +24,13 @@ Environment Variables that Control the Build /envvar/CMAKE_BUILD_PARALLEL_LEVEL /envvar/CMAKE_CONFIG_TYPE /envvar/CMAKE_MSVCIDE_RUN_PATH + /envvar/CMAKE_NO_VERBOSE /envvar/CMAKE_OSX_ARCHITECTURES /envvar/DESTDIR /envvar/LDFLAGS /envvar/MACOSX_DEPLOYMENT_TARGET /envvar/PackageName_ROOT + /envvar/VERBOSE Environment Variables for Languages =================================== diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst index 9322e33..856aa2f 100644 --- a/Help/manual/cmake-gui.1.rst +++ b/Help/manual/cmake-gui.1.rst @@ -10,6 +10,7 @@ Synopsis cmake-gui [<options>] cmake-gui [<options>] {<path-to-source> | <path-to-existing-build>} + cmake-gui [<options>] -S <path-to-source> -B <path-to-build> Description =========== @@ -27,6 +28,14 @@ native tool on their platform. Options ======= +``-S <path-to-source>`` + Path to root directory of the CMake project to build. + +``-B <path-to-build>`` + Path to directory which CMake will use as the root of build directory. + + If the directory doesn't already exist CMake will make it. + .. include:: OPTIONS_HELP.txt See Also diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index e1de134..4366c0d 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -195,6 +195,7 @@ Properties on Targets /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME /prop_tgt/GHS_INTEGRITY_APP + /prop_tgt/GHS_NO_SOURCE_GROUP_FILE /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst index 8554e87..d214e4a 100644 --- a/Help/manual/cmake-toolchains.7.rst +++ b/Help/manual/cmake-toolchains.7.rst @@ -522,3 +522,74 @@ See also target properties: * :prop_tgt:`ANDROID_SECURE_PROPS_PATH` * :prop_tgt:`ANDROID_SKIP_ANT_STEP` * :prop_tgt:`ANDROID_STL_TYPE` + +.. _`Cross Compiling for iOS, tvOS, or watchOS`: + +Cross Compiling for iOS, tvOS, or watchOS +----------------------------------------- + +For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode` +generator is recommended. The :generator:`Unix Makefiles` or +:generator:`Ninja` generators can also be used, but they require the +project to handle more areas like target CPU selection and code signing. + +Any of the three systems can be targetted by setting the +:variable:`CMAKE_SYSTEM_NAME` variable to a value from the table below. +By default, the latest Device SDK is chosen. As for all Apple platforms, +a different SDK (e.g. a simulator) can be selected by setting the +:variable:`CMAKE_OSX_SYSROOT` variable, although this should rarely be +necessary (see :ref:`Switching Between Device and Simulator` below). +A list of available SDKs can be obtained by running ``xcodebuild -showsdks``. + +======= ================= ==================== ================ +OS CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK +======= ================= ==================== ================ +iOS iOS iphoneos iphonesimulator +tvOS tvOS appletvos appletvsimulator +watchOS watchOS watchos watchsimulator +======= ================= ==================== ================ + +For example, to create a CMake configuration for iOS, the following +command is sufficient: + +.. code-block:: console + + cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS + +Code Signing +^^^^^^^^^^^^ + +Some build artifacts for the embedded Apple platforms require mandatory +code signing. If the :generator:`Xcode` generator is being used and +code signing is required or desired, the developmemt team ID can be +specified via the ``CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM`` CMake variable. +This team ID will then be included in the generated Xcode project. +By default, CMake avoids the need for code signing during the internal +configuration phase (i.e compiler ID and feature detection). + +.. _`Switching Between Device and Simulator`: + +Switching Between Device and Simulator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When configuring for any of the embedded platforms, one can target either +real devices or the simulator. Both have their own separate SDK, but CMake +only supports specifying a single SDK for the configuration phase. This +means the developer must select one or the other at configuration time. +When using the :generator:`Xcode` generator, this is less of a limitation +because Xcode still allows you to build for either a device or a simulator, +even though configuration was only performed for one of the two. From +within the Xcode IDE, builds are performed for the selected "destination" +platform. When building from the command line, the desired sdk can be +specified directly by passing a ``-sdk`` option to the underlying build +tool (``xcodebuild``). For example: + +.. code-block:: console + + $ cmake --build ... -- -sdk iphonesimulator + +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. diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index de4ce3d..83c88a5 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -55,7 +55,6 @@ Variables that Provide Information /variable/CMAKE_GENERATOR_INSTANCE /variable/CMAKE_GENERATOR_PLATFORM /variable/CMAKE_GENERATOR_TOOLSET - /variable/CMAKE_HOME_DIRECTORY /variable/CMAKE_IMPORT_LIBRARY_PREFIX /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE @@ -103,7 +102,6 @@ Variables that Provide Information /variable/CMAKE_VERBOSE_MAKEFILE /variable/CMAKE_VERSION /variable/CMAKE_VS_DEVENV_COMMAND - /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION /variable/CMAKE_VS_MSBUILD_COMMAND /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME @@ -192,7 +190,6 @@ Variables that Change Behavior /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MODULE_PATH - /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_POLICY_DEFAULT_CMPNNNN /variable/CMAKE_POLICY_WARNING_CMPNNNN /variable/CMAKE_PREFIX_PATH @@ -276,6 +273,7 @@ Variables that Describe the System /variable/MSVC_IDE /variable/MSVC_TOOLSET_VERSION /variable/MSVC_VERSION + /variable/MSYS /variable/UNIX /variable/WIN32 /variable/WINCE @@ -347,6 +345,7 @@ Variables that Control the Build /variable/CMAKE_FOLDER /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY + /variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE /variable/CMAKE_GLOBAL_AUTOGEN_TARGET /variable/CMAKE_GLOBAL_AUTOGEN_TARGET_NAME /variable/CMAKE_GLOBAL_AUTORCC_TARGET @@ -451,7 +450,6 @@ Variables for Languages /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG - /variable/CMAKE_INTERNAL_PLATFORM_ABI /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_MACHINE /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_PREFIX /variable/CMAKE_LANG_ANDROID_TOOLCHAIN_SUFFIX @@ -459,15 +457,12 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH /variable/CMAKE_LANG_COMPILER - /variable/CMAKE_LANG_COMPILER_ABI - /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED /variable/CMAKE_LANG_COMPILER_PREDEFINES_COMMAND /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION - /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE @@ -496,7 +491,6 @@ Variables for Languages /variable/CMAKE_LANG_LINKER_WRAPPER_FLAG_SEP /variable/CMAKE_LANG_LINK_EXECUTABLE /variable/CMAKE_LANG_OUTPUT_EXTENSION - /variable/CMAKE_LANG_PLATFORM_ID /variable/CMAKE_LANG_SIMULATE_ID /variable/CMAKE_LANG_SIMULATE_VERSION /variable/CMAKE_LANG_SIZEOF_DATA_PTR @@ -608,3 +602,23 @@ Variable Expansion Operators /variable/CACHE /variable/ENV + +Internal Variables +================== + +CMake has many internal variables. Most of them are undocumented. +Some of them, however, were at some point described as normal +variables, and therefore may be encountered in legacy code. They +are subject to change, and not recommended for use in project code. + +.. toctree:: + :maxdepth: 1 + + /variable/CMAKE_HOME_DIRECTORY + /variable/CMAKE_INTERNAL_PLATFORM_ABI + /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_ARCHITECTURE_ID + /variable/CMAKE_LANG_COMPILER_VERSION_INTERNAL + /variable/CMAKE_LANG_PLATFORM_ID + /variable/CMAKE_NOT_USING_CONFIG_FLAGS + /variable/CMAKE_VS_INTEL_Fortran_PROJECT_VERSION diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 915e0d4..f3b81ec 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -289,6 +289,14 @@ following options: ``--use-stderr`` Ignored. Behavior is default in CMake >= 3.0. +``-v, --verbose`` + Enable verbose output - if supported - including the build commands to be + executed. + + This option can be omitted if :envvar:`VERBOSE` environment variable or + :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set. + + ``--`` Pass remaining options to the native tool. @@ -373,9 +381,10 @@ Available commands are: ``chdir <dir> <cmd> [<arg>...]`` Change the current working directory and run a command. -``compare_files <file1> <file2>`` +``compare_files [--ignore-eol] <file1> <file2>`` Check if ``<file1>`` is same as ``<file2>``. If files are the same, - then returns 0, if not it returns 1. + then returns 0, if not it returns 1. The ``--ignore-eol`` option + implies line-wise comparison and ignores LF/CRLF differences. ``copy <file>... <destination>`` Copy files to ``<destination>`` (either file or directory). diff --git a/Help/policy/CMP0083.rst b/Help/policy/CMP0083.rst index b26d6c8..32acf1f 100644 --- a/Help/policy/CMP0083.rst +++ b/Help/policy/CMP0083.rst @@ -23,9 +23,10 @@ which it is used, it is the project's responsibility to use the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property for executables will be honored at link time. -This policy was introduced in CMake version 3.14. 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. +This policy was introduced in CMake version 3.14. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does not warn when this policy is +not set and simply uses ``OLD`` behavior. .. include:: DEPRECATED.txt diff --git a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst index 127d79f..ef74ae2 100644 --- a/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst +++ b/Help/prop_tgt/CUDA_RESOLVE_DEVICE_SYMBOLS.rst @@ -1,12 +1,18 @@ CUDA_RESOLVE_DEVICE_SYMBOLS --------------------------- -CUDA only: Enables device linking for the specific static library target +CUDA only: Enables device linking for the specific library target -If set this will enable device linking on this static library target. Normally +If set this will enable device linking on the library target. Normally device linking is deferred until a shared library or executable is generated, allowing for multiple static libraries to resolve device symbols at the same -time. +time when they are used by a shared library or executable. + +By default static library targets have this property is disabled, +while shared, module, and executable targets have this property enabled. + +Note that device linking is not supported for :ref:`Object Libraries`. + For instance: diff --git a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst index e7457e1..0eee297 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -6,8 +6,16 @@ Exclude the target from the all target. A property on a target that indicates if the target is excluded from the default build target. If it is not, then with a Makefile for example typing make will cause this target to be built. The same -concept applies to the default build of other generators. Installing -a target with EXCLUDE_FROM_ALL set to true has undefined behavior. +concept applies to the default build of other generators. + +With ``EXCLUDE_FROM_ALL`` set to false or not set at all, the target +will be brought up to date as part of doing a ``make install`` or its +equivalent for the CMake generator being used. If a target has +``EXCLUDE_FROM_ALL`` set to true, then any attempt to install that +target has undefined behavior. Note that such a target can still safely +be listed in an :command:`install(TARGETS)` command as long as the install +components the target belongs to are not part of the set of components +that anything tries to install. This property is enabled by default for targets that are created in directories that have :prop_dir:`EXCLUDE_FROM_ALL` set to ``TRUE``. diff --git a/Help/prop_tgt/GHS_NO_SOURCE_GROUP_FILE.rst b/Help/prop_tgt/GHS_NO_SOURCE_GROUP_FILE.rst new file mode 100644 index 0000000..11ce0b22 --- /dev/null +++ b/Help/prop_tgt/GHS_NO_SOURCE_GROUP_FILE.rst @@ -0,0 +1,13 @@ +GHS_NO_SOURCE_GROUP_FILE +------------------------ + +``ON`` / ``OFF`` boolean to control if the project file for a target should +be one single file or multiple files. + +The default behavior or when the property is ``OFF`` is to generate a project +file for the target and then a sub-project file for each source group. + +When this property is ``ON`` or if :variable:`CMAKE_GHS_NO_SOURCE_GROUP_FILE` +is ``ON`` then only a single project file is generated for the target. + +Supported on :generator:`Green Hills MULTI`. diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst new file mode 100644 index 0000000..0246071 --- /dev/null +++ b/Help/release/3.14.rst @@ -0,0 +1,381 @@ +CMake 3.14 Release Notes +************************ + +.. only:: html + + .. contents:: + +Changes made since CMake 3.13 include the following. + +New Features +============ + +Generators +---------- + +* The :generator:`Visual Studio 16 2019` generator was added. This is + experimental and based on "Visual Studio 2019 Preview 2" because this + version of VS has not been released. + + The VS 2019 generator differs from generators for earlier versions + in that it does not provide variants that specify the target platform + in the generator name. Instead :variable:`CMAKE_GENERATOR_PLATFORM` + must be used, e.g. through the ``-A`` command-line option. Furthermore, + the default target platform (architecture) is now based on the *host* + platform. The VS host toolset selection is now based on the host + architecture as well. + +* The :generator:`Green Hills MULTI` generator has been updated: + + * Now supports :ref:`Object Libraries`. + + * Now warns on unsupported project types such as shared libraries. + + * Now generates a top-level ``<PROJECT-NAME>.top.gpj`` for each directory + calling the :command:`project` command. The top-level project file + ``default.gpj`` is no longer created. + + * Now honors target renaming and destination output control properties + such as :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`OUTPUT_NAME`. + This also fixes support for installation rules generated by + :command:`install`. + + * Now honors source file properties :prop_sf:`INCLUDE_DIRECTORIES`, + :prop_sf:`COMPILE_DEFINITIONS`, and :prop_sf:`COMPILE_OPTIONS`. + + * Now supports Dynamic Download Integrity Applications which did not include + Integrate Files via :prop_tgt:`GHS_INTEGRITY_APP` and setting a target + link flag of ``-dynamic``. + + * The contents of project files now sorts sources groups and files by name. + Set the :prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` target property to ``ON`` to + generate a single project file for the target instead of a project file for + each source group. Set the :variable:`CMAKE_GHS_NO_SOURCE_GROUP_FILE` + variable to enable this for all targets. + +File-Based API +-------------- + +* A file-based api for clients to get semantic buildsystem information + has been added. See the :manual:`cmake-file-api(7)` manual. + This is intended to replace the :manual:`cmake-server(7)` mode for IDEs. + +Platforms +--------- + +* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS` + using simple toolchain files. + +Command-Line +------------ + +* The :manual:`cmake(1)` :ref:`Build Tool Mode <Build Tool Mode>` + (``cmake --build``) gained ``--verbose`` and ``-v`` options to + specify verbose build output. Some generators such as Xcode don't + support this option currently. + +* The :manual:`cmake(1)` ``-E compare_files`` command learned a new + ``--ignore-eol`` option to specify that end-of-line differences + (e.g. LF vs CRLF) should be ignored when comparing files. + +* The :manual:`cmake-gui(1)` dialog gained new ``-S`` and ``-B`` arguments to + explicitly specify source and build directories. + +Commands +-------- + +* The :command:`file` command learned a new sub-command, ``CREATE_LINK``, + which can be used to create hard or symbolic links. + +* The :command:`file` command learned a new sub-command, ``READ_SYMLINK``, + which can be used to determine the path that a symlink points to. + +* The :command:`file` command gained a ``SIZE`` mode to get the size + of a file on disk. + +* The :command:`find_package` command learned to optionally resolve + symbolic links in the paths to package configuration files. + See the :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable. + +* The :command:`get_filename_component` command gained new + ``LAST_EXT`` and ``NAME_WLE`` variants to work with the + extension after the last ``.`` in the name. + +* The :command:`if` command gained support for checking if cache variables + are defined with the ``DEFINED CACHE{VAR}`` syntax. + +* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands + learned to support generator expressions. See policy :policy:`CMP0087`. + +* The :command:`install(TARGETS)` command learned how to install to an + appropriate default directory for a given target type, based on + variables from the :module:`GNUInstallDirs` module and built-in defaults, + in lieu of a ``DESTINATION`` argument. + +* The :command:`install(FILES)` and :command:`install(DIRECTORY)` commands + learned a new set of parameters for installing files as a file type, + setting the destination based on the appropriate variables from + :module:`GNUInstallDirs` and built-in defaults, in lieu of a + ``DESTINATION`` argument. + +* The :command:`list` operations ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, + ``SORT``, ``REVERSE``, and ``FILTER`` all now accept a non-existent variable + as the list since these operations on empty lists is also the empty list. + +* The :command:`list` operation ``REMOVE_AT`` now indicates that the given + indices are invalid for a non-existent variable or empty list. + +* The :command:`try_compile` and :command:`try_run` commands gained a new + ``LINK_OPTIONS`` option. + +Variables +--------- + +* A :variable:`CMAKE_BUILD_RPATH_USE_ORIGIN` variable and corresponding + :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property were added to + enable use of relative runtime paths (RPATHs). This helps achieving + relocatable and reproducible builds that are invariant of the build + directory. + +Properties +---------- + +* A :prop_gbl:`CMAKE_ROLE` global property was added to allow scripts to + determine whether they're running in project mode, script mode, + find-package mode, CTest, or CPack. + +* The :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` target property is now supported + on shared library, module library, and executable targets. Previously it was + only honored on static libraries. + +* The :prop_tgt:`EXCLUDE_FROM_ALL` target property was created to override + the setting of its directory. A target will now be built as part of "all" + if its :prop_tgt:`EXCLUDE_FROM_ALL` property is set to ``OFF``, even if its + containing directory is marked as :prop_dir:`EXCLUDE_FROM_ALL`. + +* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the + support of :manual:`generator expressions <cmake-generator-expressions(7)>`. + +Modules +------- + +* The family of modules to check capabilities (like + :module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``. + +* A :module:`CheckFortranSourceRuns` module was added to provide a + :command:`check_fortran_source_runs` command to check if a Fortran + source snippet compiles and runs. + +* The :module:`CMakePackageConfigHelpers` module's + :command:`write_basic_package_version_file` command gained a new + ``ARCH_INDEPENDENT`` option for supporting architecture-independent + packages. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + gained ``LOG_PATCH`` to optionally log the patch step. + +* The :module:`ExternalProject` module :command:`ExternalProject_Add` command + learned to apply ``SOURCE_SUBDIR`` when ``BUILD_IN_SOURCE`` is also used. + The ``BUILD_COMMAND`` is run in the given ``SOURCE_SUBDIR`` of the + ``SOURCE_DIR``. + +* The :module:`FetchContent` module gained a new + :command:`FetchContent_MakeAvailable` command. It accepts a list of + dependency names, which it then iterates over, populating and adding + each one to the main build using the canonical pattern. This + significantly reduces the amount of boilerplate needed in a project. + +* The :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison`` + with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory. + See policy :policy:`CMP0088`. + +* The :module:`FindCURL` module gained support for requesting + protocols as package components. + +* The :module:`FindFontconfig` module was added to find `fontconfig`_. + +* The :module:`FindGDAL` module now provides imported targets. + +* The :module:`FindGIF` module now provides imported targets. + +* The :module:`FindGit` module now provides an imported target for the + Git executable. + +* The :module:`FindIce` module learned to find ``slice2confluence`` + and ``slice2matlab``. + +* The :module:`FindLibinput` module was added to find `libinput`_. + +* The :module:`FindLibLZMA` module now provides imported targets. + +* The :module:`FindMatlab` module gained new options ``R2017b`` and + ``R2018a`` to specify the MEX API version to use; these options + mirror the new options to the ``mex`` command in MATLAB R2018a. + The option ``MX_LIBRARY`` is no longer needed. + +* A :module:`FindOctave` module was added to find GNU octave. + +* The :module:`FindPostgreSQL` module now provides imported targets. + +* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` + modules gained support for ``NumPy`` component. + +* The :module:`FindPython2`, :module:`FindPython3`, and :module:`FindPython` + modules now support running in script mode by skipping the creation of + imported targets and helper functions. + +* The :module:`FindSQLite3` module was added to find the SQLite v3.x library. + +* The :module:`FindX11` had the following variables renamed in order to match + their library names rather than header names. The old variables are provided + for compatibility: + + - ``X11_Xxf86misc_INCLUDE_PATH`` instead of ``X11_xf86misc_INCLUDE_PATH`` + - ``X11_Xxf86misc_LIB`` instead of ``X11_xf86misc_LIB`` + - ``X11_Xxf86misc_FOUND`` instead of ``X11_xf86misc_FOUND`` + - ``X11_Xxf86vm_INCLUDE_PATH`` instead of ``X11_xf86vmode_INCLUDE_PATH`` + - ``X11_Xxf86vm_LIB`` instead of ``X11_xf86vmode_LIB`` + - ``X11_Xxf86vm_FOUND`` instead of ``X11_xf86vmode_FOUND`` + - ``X11_xkbfile_INCLUDE_PATH`` instead of ``X11_Xkbfile_INCLUDE_PATH`` + - ``X11_xkbfile_LIB`` instead of ``X11_Xkbfile_LIB`` + - ``X11_xkbfile_FOUND`` instead of ``X11_Xkbfile_FOUND`` + - ``X11_Xtst_INCLUDE_PATH`` instead of ``X11_XTest_INCLUDE_PATH`` + - ``X11_Xtst_LIB`` instead of ``X11_XTest_LIB`` + - ``X11_Xtst_FOUND`` instead of ``X11_XTest_FOUND`` + - ``X11_Xss_INCLUDE_PATH`` instead of ``X11_Xscreensaver_INCLUDE_PATH`` + - ``X11_Xss_LIB`` instead of ``X11_Xscreensaver_LIB`` + - ``X11_Xss_FOUND`` instead of ``X11_Xscreensaver_FOUND`` + + The following variables are deprecated completely since they were + essentially duplicates: + + - ``X11_Xinput_INCLUDE_PATH`` (use ``X11_Xi_INCLUDE_PATH``) + - ``X11_Xinput_LIB`` (use ``X11_Xi_LIB``) + - ``X11_Xinput_FOUND`` (use ``X11_Xi_FOUND``) + +* The :module:`FindX11` now provides ``X11_Xext_INCLUDE_PATH``. + +* The :module:`FindX11` now provides imported targets. + +* The :module:`UseSWIG` module learned to pass ``-module <module_name>`` to + the ``SWIG`` compiler if the file property ``SWIG_MODULE_NAME`` is defined. + See policy :policy:`CMP0086`. + +* The :module:`UseSWIG` module gained an option to specify + ``SWIG`` source file extensions. + +.. _`fontconfig`: https://www.freedesktop.org/wiki/Software/fontconfig/ +.. _`libinput`: https://www.freedesktop.org/wiki/Software/libinput/ + +Generator Expressions +--------------------- + +* The ``$<Fortran_COMPILER_ID:...>`` and ``$<Fortran_COMPILER_VERSION:...>`` + :manual:`generator expressions <cmake-generator-expressions(7)>` were added. + +* The ``$<IN_LIST:...>`` generator expression now correctly handles an + empty argument. See :policy:`CMP0085` for details. + +Autogen +------- + +* The :prop_tgt:`AUTOMOC_EXECUTABLE`, :prop_tgt:`AUTORCC_EXECUTABLE`, and + :prop_tgt:`AUTOUIC_EXECUTABLE` target properties were added. They all + take a path to an executable and force automoc/autorcc/autouic to use + this executable. + + Setting these will also prevent the configure time testing for these + executables. This is mainly useful when you build these tools yourself. + +* The new variables :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`, + :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`, + :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` and + :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME` control the generation + of global ``autogen`` and ``autorcc`` targets. + +* A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and + :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or + disable forwarding of the origin target dependencies to the corresponding + ``_autogen`` target. + +CTest +----- + +* :manual:`ctest(1)` gained a ``--show-only=json-v1`` option to show the + list of tests in a machine-readable JSON format. + See the :ref:`Show as JSON Object Model` section of the manual. + +* The :command:`ctest_submit` command learned a new ``Done`` part that can be used + to inform CDash that a build is complete and that no more parts will be uploaded. + +* CTest learned to accept the dashboard server submission URL from a single + variable. See the ``SubmitURL`` setting in :manual:`ctest(1)`, + the :variable:`CTEST_SUBMIT_URL` variable, and the ``SUBMIT_URL`` + argument of the :command:`ctest_submit` command. + +Deprecated and Removed Features +=============================== + +* An explicit deprecation diagnostic was added for policies ``CMP0064`` + and ``CMP0065`` (``CMP0063`` 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. + +* The :generator:`Xcode` generator deprecated support for Xcode + versions prior to Xcode 5. Support for those will be dropped in a + future version of CMake. + +* The :module:`FindQt` module is no longer used by the :command:`find_package` + command as a find module. This allows the Qt Project upstream to optionally + provide its own ``QtConfig.cmake`` package configuration file and have + applications use it via ``find_package(Qt)`` rather than + ``find_package(Qt CONFIG)``. See policy :policy:`CMP0084`. + +* Support for running CMake on Windows XP and Windows Vista has been dropped. + The precompiled Windows binaries provided on ``cmake.org`` now require + Windows 7 or higher. + +* CTest no longer supports submissions via ``ftp``, ``scp``, ``cp``, and + ``xmlrpc``. CDash is the only maintained testing dashboard for CTest, + and it only supports submissions over ``http`` and ``https``. + +Other Changes +============= + +* Object library linking has been fixed to propagate private link libraries + of object libraries to consuming targets. + +* Install rules under :command:`add_subdirectory` now interleave with those in + the calling directory. See policy :policy:`CMP0082` for details. + +* CMake now imposes a maximum recursion limit to prevent a stack overflow on + scripts that recurse infinitely. The limit can be adjusted at runtime with + :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH`. + +* When using cppcheck via the :variable:`CMAKE_<LANG>_CPPCHECK` variable + or :prop_tgt:`<LANG>_CPPCHECK` property, the build will now fail if + ``cppcheck`` returns non-zero as configured by its command-line options. + +* Required link options to manage Position Independent Executable are now + added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. The project is + responsible for using the :module:`CheckPIESupported` module to check for + ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` + target property will be honored at link time for executables. This behavior + is controlled by policy :policy:`CMP0083`. + +* :ref:`Visual Studio Generators` for VS 2010 and above learned + to support the ``VS_DEBUGGER_*`` properties on targets created + via :command:`add_custom_target`. + +* The :module:`CPack` module no longer defaults to the ``paxr`` value in the + :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` variable, because ``dpkg`` has + never supported the PAX tar format. The ``paxr`` value will be mapped + to ``gnutar`` and a deprecation message emitted. + +* CMake no longer issues a warning if a target listed in an + :command:`install(TARGETS)` command has its :prop_tgt:`EXCLUDE_FROM_ALL` + property set to true. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst deleted file mode 100644 index e4cc01e..0000000 --- a/Help/release/dev/0-sample-topic.rst +++ /dev/null @@ -1,7 +0,0 @@ -0-sample-topic --------------- - -* This is a sample release note for the change in a topic. - Developers should add similar notes for each topic branch - making a noteworthy change. Each document should be named - and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/EXCLUDE_FROM_ALL.rst b/Help/release/dev/EXCLUDE_FROM_ALL.rst deleted file mode 100644 index 519ac42..0000000 --- a/Help/release/dev/EXCLUDE_FROM_ALL.rst +++ /dev/null @@ -1,7 +0,0 @@ -EXCLUDE_FROM_ALL ----------------- - -* A target's :prop_tgt:`EXCLUDE_FROM_ALL` property can now override the - setting of its directory. A target will now be built as part of "all" - if its :prop_tgt:`EXCLUDE_FROM_ALL` property is set to ``OFF``, even if its - containing directory is marked as :prop_dir:`EXCLUDE_FROM_ALL`. diff --git a/Help/release/dev/ExternalProject-log-options.rst b/Help/release/dev/ExternalProject-log-options.rst deleted file mode 100644 index 88bc799..0000000 --- a/Help/release/dev/ExternalProject-log-options.rst +++ /dev/null @@ -1,8 +0,0 @@ -ExternalProject-log-options ---------------------------- - -* The :module:`ExternalProject` module :command:`ExternalProject_Add` command - gained ``LOG_DIR`` and ``LOG_MERGED_STDOUTERR`` options to control logging. - -* The :module:`ExternalProject` module :command:`ExternalProject_Add` command - gained ``LOG_PATCH`` to optionally log the patch step. diff --git a/Help/release/dev/ExternalProject-non-cmake-source-subdir.rst b/Help/release/dev/ExternalProject-non-cmake-source-subdir.rst deleted file mode 100644 index 29fe2ad..0000000 --- a/Help/release/dev/ExternalProject-non-cmake-source-subdir.rst +++ /dev/null @@ -1,7 +0,0 @@ -ExternalProject-non-cmake-source-subdir ---------------------------------------- - -* The :module:`ExternalProject` module's ``ExternalProject_Add`` command - learned to apply ``SOURCE_SUBDIR`` when ``BUILD_IN_SOURCE`` is also used. - The ``BUILD_COMMAND`` is run in the given ``SOURCE_SUBDIR`` of the - ``SOURCE_DIR``. diff --git a/Help/release/dev/FindCURL-components.rst b/Help/release/dev/FindCURL-components.rst deleted file mode 100644 index 9c50ede..0000000 --- a/Help/release/dev/FindCURL-components.rst +++ /dev/null @@ -1,5 +0,0 @@ -FindCURL-components -------------------- - -* The :module:`FindCURL` module gained support for requesting - protocols as package components. diff --git a/Help/release/dev/FindGDAL-target.rst b/Help/release/dev/FindGDAL-target.rst deleted file mode 100644 index b121a72..0000000 --- a/Help/release/dev/FindGDAL-target.rst +++ /dev/null @@ -1,4 +0,0 @@ -FindGDAL-target ---------------- - -* The :module:`FindGDAL` module now provides an imported target. diff --git a/Help/release/dev/FindGIF-modernize.rst b/Help/release/dev/FindGIF-modernize.rst deleted file mode 100644 index 3bb4821..0000000 --- a/Help/release/dev/FindGIF-modernize.rst +++ /dev/null @@ -1,4 +0,0 @@ -FindGIF-modernize ------------------ - -* The :module:`FindGIF` module now provides imported targets. diff --git a/Help/release/dev/FindICE-more-exe.rst b/Help/release/dev/FindICE-more-exe.rst deleted file mode 100644 index fa18a88..0000000 --- a/Help/release/dev/FindICE-more-exe.rst +++ /dev/null @@ -1,5 +0,0 @@ -FindICE-more-exe ----------------- - -* The :module:`FindIce` module learned to find - ``slice2confluence`` and ``slice2matlab``. diff --git a/Help/release/dev/FindLibLZMA-target.rst b/Help/release/dev/FindLibLZMA-target.rst deleted file mode 100644 index a13c45f..0000000 --- a/Help/release/dev/FindLibLZMA-target.rst +++ /dev/null @@ -1,4 +0,0 @@ -FindLibLZMA-target ------------------- - -* The :module:`FindLibLZMA` module now provides an imported target. diff --git a/Help/release/dev/FindMatlab-2018a-API.rst b/Help/release/dev/FindMatlab-2018a-API.rst deleted file mode 100644 index 1063411..0000000 --- a/Help/release/dev/FindMatlab-2018a-API.rst +++ /dev/null @@ -1,7 +0,0 @@ -FindMatlab-2018a-API --------------------- - -* The :module:`FindMatlab` module gained new options ``R2017b`` and - ``R2018a`` to specify the MEX API version to use; these options - mirror the new options to the ``mex`` command in MATLAB R2018a. - The option ``MX_LIBRARY`` is no longer needed. diff --git a/Help/release/dev/FindOctave.rst b/Help/release/dev/FindOctave.rst deleted file mode 100644 index fe3b242..0000000 --- a/Help/release/dev/FindOctave.rst +++ /dev/null @@ -1,4 +0,0 @@ -FindOctave ----------- - -* A :module:`FindOctave` module was added to find GNU octave. diff --git a/Help/release/dev/FindPostgreSQL-target.rst b/Help/release/dev/FindPostgreSQL-target.rst deleted file mode 100644 index 84f8d1a..0000000 --- a/Help/release/dev/FindPostgreSQL-target.rst +++ /dev/null @@ -1,4 +0,0 @@ -FindPostgreSQL-target ---------------------- - -* The :module:`FindPostgreSQL` module now provides an imported target. diff --git a/Help/release/dev/FindPython-NumPy-component.rst b/Help/release/dev/FindPython-NumPy-component.rst deleted file mode 100644 index 5ea6cfb..0000000 --- a/Help/release/dev/FindPython-NumPy-component.rst +++ /dev/null @@ -1,5 +0,0 @@ -FindPython-NumPy-component --------------------------- - -* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` - modules gained support for ``NumPy`` component. diff --git a/Help/release/dev/FindSQLite3-module.rst b/Help/release/dev/FindSQLite3-module.rst deleted file mode 100644 index 733a4d3..0000000 --- a/Help/release/dev/FindSQLite3-module.rst +++ /dev/null @@ -1,4 +0,0 @@ -FindSQLite3-module ------------------- - -* The :module:`FindSQLite3` module was added to find the SQLite v3.x library. diff --git a/Help/release/dev/FindX11-imported-targets.rst b/Help/release/dev/FindX11-imported-targets.rst deleted file mode 100644 index 4df753d..0000000 --- a/Help/release/dev/FindX11-imported-targets.rst +++ /dev/null @@ -1,32 +0,0 @@ -FindX11-imported-targets ------------------------- - -* The :module:`FindX11` had the following variables renamed in order to match - their library names rather than header names. The old variables are provided - for compatibility: - - - ``X11_Xxf86misc_INCLUDE_PATH`` instead of ``X11_xf86misc_INCLUDE_PATH`` - - ``X11_Xxf86misc_LIB`` instead of ``X11_xf86misc_LIB`` - - ``X11_Xxf86misc_FOUND`` instead of ``X11_xf86misc_FOUND`` - - ``X11_Xxf86vm_INCLUDE_PATH`` instead of ``X11_xf86vmode_INCLUDE_PATH`` - - ``X11_Xxf86vm_LIB`` instead of ``X11_xf86vmode_LIB`` - - ``X11_Xxf86vm_FOUND`` instead of ``X11_xf86vmode_FOUND`` - - ``X11_xkbfile_INCLUDE_PATH`` instead of ``X11_Xkbfile_INCLUDE_PATH`` - - ``X11_xkbfile_LIB`` instead of ``X11_Xkbfile_LIB`` - - ``X11_xkbfile_FOUND`` instead of ``X11_Xkbfile_FOUND`` - - ``X11_Xtst_INCLUDE_PATH`` instead of ``X11_XTest_INCLUDE_PATH`` - - ``X11_Xtst_LIB`` instead of ``X11_XTest_LIB`` - - ``X11_Xtst_FOUND`` instead of ``X11_XTest_FOUND`` - - ``X11_Xss_INCLUDE_PATH`` instead of ``X11_Xscreensaver_INCLUDE_PATH`` - - ``X11_Xss_LIB`` instead of ``X11_Xscreensaver_LIB`` - - ``X11_Xss_FOUND`` instead of ``X11_Xscreensaver_FOUND`` - - The following variables are deprecated completely since they were - essentially duplicates: - - - ``X11_Xinput_INCLUDE_PATH`` (use ``X11_Xi_INCLUDE_PATH``) - - ``X11_Xinput_LIB`` (use ``X11_Xi_LIB``) - - ``X11_Xinput_FOUND`` (use ``X11_Xi_FOUND``) - -* The :module:`FindX11` now provides ``X11_Xext_INCLUDE_PATH``. -* The :module:`FindX11` now provides imported targets. diff --git a/Help/release/dev/INTERFACE_POSITION_INDEPENDENT_CODE.rst b/Help/release/dev/INTERFACE_POSITION_INDEPENDENT_CODE.rst deleted file mode 100644 index 7732ff6..0000000 --- a/Help/release/dev/INTERFACE_POSITION_INDEPENDENT_CODE.rst +++ /dev/null @@ -1,5 +0,0 @@ -INTERFACE_POSITION_INDEPENDENT_CODE ------------------------------------ - -* :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` target property gains the - support of :manual:`generator expressions <cmake-generator-expressions(7)>`. diff --git a/Help/release/dev/UseSWIG-CMP0086.rst b/Help/release/dev/UseSWIG-CMP0086.rst deleted file mode 100644 index d6fd0d1..0000000 --- a/Help/release/dev/UseSWIG-CMP0086.rst +++ /dev/null @@ -1,6 +0,0 @@ -UseSWIG-CMP0086 ---------------- - -* The :module:`UseSWIG` module passes option ``-module <module_name>`` to - ``SWIG`` compiler if the file property ``SWIG_MODULE_NAME`` is defined. - See policy :policy:`CMP0086`. diff --git a/Help/release/dev/UseSWIG-source-file-ext.rst b/Help/release/dev/UseSWIG-source-file-ext.rst deleted file mode 100644 index 5d11dc6..0000000 --- a/Help/release/dev/UseSWIG-source-file-ext.rst +++ /dev/null @@ -1,5 +0,0 @@ -UseSWIG-source-file-ext ------------------------ - -* The :module:`UseSWIG` module gains capability to specify - ``SWIG`` source file extensions. diff --git a/Help/release/dev/autogen-origin-depends.rst b/Help/release/dev/autogen-origin-depends.rst deleted file mode 100644 index 7310487..0000000 --- a/Help/release/dev/autogen-origin-depends.rst +++ /dev/null @@ -1,7 +0,0 @@ -autogen-origin-depends ----------------------- - -* A new :variable:`CMAKE_AUTOGEN_ORIGIN_DEPENDS` variable and - :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS` target property may be set to enable or - disable forwarding of the origin target dependencies to the corresponding - ``_autogen`` target. diff --git a/Help/release/dev/autogen_executables.rst b/Help/release/dev/autogen_executables.rst deleted file mode 100644 index 5e967ea..0000000 --- a/Help/release/dev/autogen_executables.rst +++ /dev/null @@ -1,9 +0,0 @@ -AUTO*_EXECUTABLE ----------------- - -* The :prop_tgt:`AUTOMOC_EXECUTABLE`, :prop_tgt:`AUTORCC_EXECUTABLE` and - :prop_tgt:`AUTOUIC_EXECUTABLE` target properties all take a path to an - executable and force automoc/autorcc/autouic to use this executable. - - Setting these will also prevent the configure time testing for these - executables. This is mainly useful when you build these tools yourself. diff --git a/Help/release/dev/autogen_global_target.rst b/Help/release/dev/autogen_global_target.rst deleted file mode 100644 index d555395..0000000 --- a/Help/release/dev/autogen_global_target.rst +++ /dev/null @@ -1,8 +0,0 @@ -autogen_global_target ---------------------- - -* The new variables :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET`, - :variable:`CMAKE_GLOBAL_AUTOGEN_TARGET_NAME`, - :variable:`CMAKE_GLOBAL_AUTORCC_TARGET` and - :variable:`CMAKE_GLOBAL_AUTORCC_TARGET_NAME` control the generation - of global ``autogen`` and ``autorcc`` targets. diff --git a/Help/release/dev/better-empty-list-behavior.rst b/Help/release/dev/better-empty-list-behavior.rst deleted file mode 100644 index cd864f4..0000000 --- a/Help/release/dev/better-empty-list-behavior.rst +++ /dev/null @@ -1,9 +0,0 @@ -better-empty-list-behavior --------------------------- - -* The :command:`list` operations ``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, - ``SORT``, ``REVERSE``, and ``FILTER`` all now accept a non-existent variable - as the list since these operations on empty lists is also the empty list. - -* The :command:`list` operation ``REMOVE_AT`` now indicates that the given - indices are invalid for a non-existent variable or empty list. diff --git a/Help/release/dev/bison_target_policy.rst b/Help/release/dev/bison_target_policy.rst deleted file mode 100644 index 3240318..0000000 --- a/Help/release/dev/bison_target_policy.rst +++ /dev/null @@ -1,6 +0,0 @@ -bison_target_policy -------------------- - -* The :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison`` - with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory. - See policy :policy:`CMP0088`. diff --git a/Help/release/dev/check-fortran-run.rst b/Help/release/dev/check-fortran-run.rst deleted file mode 100644 index b5f6558..0000000 --- a/Help/release/dev/check-fortran-run.rst +++ /dev/null @@ -1,6 +0,0 @@ -check-fortran-run ------------------ - -* A :module:`CheckFortranSourceRuns` module was added to provide a - :command:`check_fortran_source_runs` command to check if a Fortran - source snippet compiles and runs. diff --git a/Help/release/dev/check-functions-LINK_OPTIONS.rst b/Help/release/dev/check-functions-LINK_OPTIONS.rst deleted file mode 100644 index a6bfed2..0000000 --- a/Help/release/dev/check-functions-LINK_OPTIONS.rst +++ /dev/null @@ -1,5 +0,0 @@ -check-functions-LINK_OPTIONS ----------------------------- - -* The family of modules to check capabilities (like - :module:`CheckCSourceCompiles`) gain capability to manage ``LINK_OPTIONS``. diff --git a/Help/release/dev/cmake_role-global-property.rst b/Help/release/dev/cmake_role-global-property.rst deleted file mode 100644 index 7b1fa0b..0000000 --- a/Help/release/dev/cmake_role-global-property.rst +++ /dev/null @@ -1,6 +0,0 @@ -cmake_role-global-property --------------------------- - -* A new global property, :prop_gbl:`CMAKE_ROLE`, was added to allow scripts to - determine whether they're running in project mode, script mode, find-package - mode, CTest, or CPack. diff --git a/Help/release/dev/cpack-deb-tar-format.rst b/Help/release/dev/cpack-deb-tar-format.rst deleted file mode 100644 index 9296ec6..0000000 --- a/Help/release/dev/cpack-deb-tar-format.rst +++ /dev/null @@ -1,7 +0,0 @@ -cpack-deb-tar-format --------------------- - -* The :module:`CPack` module no longer defaults to the ``paxr`` value in the - :variable:`CPACK_DEBIAN_ARCHIVE_TYPE` variable, because ``dpkg`` has - never supported the PAX tar format. The ``paxr`` value will be mapped - to ``gnutar`` and a deprecation message emitted. diff --git a/Help/release/dev/cppcheck-exit-code.rst b/Help/release/dev/cppcheck-exit-code.rst deleted file mode 100644 index d66c762..0000000 --- a/Help/release/dev/cppcheck-exit-code.rst +++ /dev/null @@ -1,6 +0,0 @@ -cppcheck-exit-code ------------------- - -* When using cppcheck via the :variable:`CMAKE_<LANG>_CPPCHECK` variable - or :prop_tgt:`<LANG>_CPPCHECK` property, the build will now fail if - ``cppcheck`` returns non-zero as configured by its command-line options. diff --git a/Help/release/dev/ctest-done.rst b/Help/release/dev/ctest-done.rst deleted file mode 100644 index 9ec0e24..0000000 --- a/Help/release/dev/ctest-done.rst +++ /dev/null @@ -1,5 +0,0 @@ -ctest-done ----------- - -* The :command:`ctest_submit` command learned a new ``Done`` part that can be used - to inform CDash that a build is complete and that no more parts will be uploaded. diff --git a/Help/release/dev/ctest-show-only-json-v1.rst b/Help/release/dev/ctest-show-only-json-v1.rst deleted file mode 100644 index f593e7e..0000000 --- a/Help/release/dev/ctest-show-only-json-v1.rst +++ /dev/null @@ -1,6 +0,0 @@ -ctest-show-only-json-v1 ------------------------ - -* :manual:`ctest(1)` gained a ``--show-only=json-v1`` option to show the - list of tests in a machine-readable JSON format. - See the :ref:`Show as JSON Object Model` section of the manual. diff --git a/Help/release/dev/ctest-submit-url.rst b/Help/release/dev/ctest-submit-url.rst deleted file mode 100644 index f848877..0000000 --- a/Help/release/dev/ctest-submit-url.rst +++ /dev/null @@ -1,7 +0,0 @@ -ctest-submit-url ----------------- - -* CTest learned to accept the dashboard server submission URL from a single - variable. See the ``SubmitURL`` setting in :manual:`ctest(1)`, - the :variable:`CTEST_SUBMIT_URL` variable, and the ``SUBMIT_URL`` - argument of the :command:`ctest_submit` command. diff --git a/Help/release/dev/deprecate-findqt.rst b/Help/release/dev/deprecate-findqt.rst deleted file mode 100644 index 4171c65..0000000 --- a/Help/release/dev/deprecate-findqt.rst +++ /dev/null @@ -1,8 +0,0 @@ -deprecate-findqt ----------------- - -* The :module:`FindQt` module is no longer used by the :command:`find_package` - command as a find module. This allows the Qt Project upstream to optionally - provide its own ``QtConfig.cmake`` package configuration file and have - applications use it via ``find_package(Qt)`` rather than - ``find_package(Qt CONFIG)``. See policy :policy:`CMP0084`. diff --git a/Help/release/dev/deprecate-policy-old.rst b/Help/release/dev/deprecate-policy-old.rst deleted file mode 100644 index 2c99780..0000000 --- a/Help/release/dev/deprecate-policy-old.rst +++ /dev/null @@ -1,8 +0,0 @@ -deprecate-policy-old --------------------- - -* An explicit deprecation diagnostic was added for policies ``CMP0064`` - and ``CMP0065`` (``CMP0063`` 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/file-read_symlink.rst b/Help/release/dev/file-read_symlink.rst deleted file mode 100644 index 718802e..0000000 --- a/Help/release/dev/file-read_symlink.rst +++ /dev/null @@ -1,5 +0,0 @@ -file-read_symlink ------------------ - -* The :command:`file` command learned a new sub-command, ``READ_SYMLINK``, - which can be used to determine the path that a symlink points to. diff --git a/Help/release/dev/file-size.rst b/Help/release/dev/file-size.rst deleted file mode 100644 index 4f0e196..0000000 --- a/Help/release/dev/file-size.rst +++ /dev/null @@ -1,5 +0,0 @@ -file-size ---------- - -* The :command:`file` command gained a ``SIZE`` mode to get the size - of a file on disk. diff --git a/Help/release/dev/fileapi.rst b/Help/release/dev/fileapi.rst deleted file mode 100644 index c3f03ef..0000000 --- a/Help/release/dev/fileapi.rst +++ /dev/null @@ -1,5 +0,0 @@ -fileapi -------- - -* A file-based api for clients to get semantic buildsystem information - has been added. See the :manual:`cmake-file-api(7)` manual. diff --git a/Help/release/dev/find-package-resolve-symlinks.rst b/Help/release/dev/find-package-resolve-symlinks.rst deleted file mode 100644 index 7adb9fe..0000000 --- a/Help/release/dev/find-package-resolve-symlinks.rst +++ /dev/null @@ -1,6 +0,0 @@ -find-package-resolve-symlinks ------------------------------ - -* The :command:`find_package` command learned to optionally resolve - symbolic links in the paths to package configuration files. - See the :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` variable. diff --git a/Help/release/dev/find_fontconfig.rst b/Help/release/dev/find_fontconfig.rst deleted file mode 100644 index 4ae18c9..0000000 --- a/Help/release/dev/find_fontconfig.rst +++ /dev/null @@ -1,6 +0,0 @@ -find_fontconfig ---------------- - -* The :module:`FindFontconfig` module was added to find `fontconfig`_. - -.. _`fontconfig`: https://www.freedesktop.org/wiki/Software/fontconfig/ diff --git a/Help/release/dev/find_libinput.rst b/Help/release/dev/find_libinput.rst deleted file mode 100644 index ebb9e7a..0000000 --- a/Help/release/dev/find_libinput.rst +++ /dev/null @@ -1,6 +0,0 @@ -find_libinput -------------- - -* The :module:`FindLibinput` module was added to find `libinput`_. - -.. _`libinput`: https://www.freedesktop.org/wiki/Software/libinput/ diff --git a/Help/release/dev/findgit-imported-target.rst b/Help/release/dev/findgit-imported-target.rst deleted file mode 100644 index cabbae5..0000000 --- a/Help/release/dev/findgit-imported-target.rst +++ /dev/null @@ -1,5 +0,0 @@ -findgit-imported-target ------------------------ - -* The :module:`FindGit` module now provides an ``IMPORTED`` target for the Git - executable. diff --git a/Help/release/dev/findpython-script.rst b/Help/release/dev/findpython-script.rst deleted file mode 100644 index 5de1ebf..0000000 --- a/Help/release/dev/findpython-script.rst +++ /dev/null @@ -1,6 +0,0 @@ -findpython-script ------------------ - -* The :module:`FindPython2`, :module:`FindPython3`, and :module:`FindPython` - modules now support running in script mode by skipping the creation of - imported targets and helper functions. diff --git a/Help/release/dev/fortran-compiler-id.rst b/Help/release/dev/fortran-compiler-id.rst deleted file mode 100644 index 1ea3bf9..0000000 --- a/Help/release/dev/fortran-compiler-id.rst +++ /dev/null @@ -1,5 +0,0 @@ -Fortran_COMPILER_ID -------------------- - -* The ``$<Fortran_COMPILER_ID:...>`` and ``$<Fortran_COMPILER_VERSION:...>`` - :manual:`generator expressions <cmake-generator-expressions(7)>` were added. diff --git a/Help/release/dev/genex-in_list-empty-args.rst b/Help/release/dev/genex-in_list-empty-args.rst deleted file mode 100644 index ec1c6c0..0000000 --- a/Help/release/dev/genex-in_list-empty-args.rst +++ /dev/null @@ -1,5 +0,0 @@ -genex-in_list-empty-args ------------------------- - -* The $<IN_LIST:...> generator expression now correctly handles an empty - argument. See :policy:`CMP0085` for details. diff --git a/Help/release/dev/if-supports-cache-defined.rst b/Help/release/dev/if-supports-cache-defined.rst deleted file mode 100644 index 1e700c0..0000000 --- a/Help/release/dev/if-supports-cache-defined.rst +++ /dev/null @@ -1,5 +0,0 @@ -if-supports-cache-defined -------------------------- - -* The :command:`if` command gained support for checking if cache variables - are defined with the ``DEFINED CACHE{VAR}`` syntax. diff --git a/Help/release/dev/install-code-script-genex.rst b/Help/release/dev/install-code-script-genex.rst deleted file mode 100644 index a28a466..0000000 --- a/Help/release/dev/install-code-script-genex.rst +++ /dev/null @@ -1,5 +0,0 @@ -install-code-script-genex -------------------------- - -* The :command:`install(CODE)` and :command:`install(SCRIPT)` commands - learned to support generator expressions. See policy :policy:`CMP0087`. diff --git a/Help/release/dev/install-defaults.rst b/Help/release/dev/install-defaults.rst deleted file mode 100644 index 4f31b7e..0000000 --- a/Help/release/dev/install-defaults.rst +++ /dev/null @@ -1,12 +0,0 @@ -install-defaults ----------------- - -* The ``TARGETS`` variant of the :command:`install` command learned how to - install to an appropriate default directory for a given target type, based - on variables from the :module:`GNUInstallDirs` module and built-in defaults, - in lieu of a ``DESTINATION`` argument. -* The ``FILES`` and ``DIRECTORY`` variants of the :command:`install` command - learned a new set of parameters for installing files as a file type, setting - the destination based on the appropriate variables from - :module:`GNUInstallDirs` and built-in defaults, in lieu of a ``DESTINATION`` - argument. diff --git a/Help/release/dev/install-subdirectory-order.rst b/Help/release/dev/install-subdirectory-order.rst deleted file mode 100644 index c52e617..0000000 --- a/Help/release/dev/install-subdirectory-order.rst +++ /dev/null @@ -1,5 +0,0 @@ -install-subdirectory-order --------------------------- - -* Install rules under :command:`add_subdirectory` now interleave with those in - the calling directory. See policy :policy:`CMP0082` for details. diff --git a/Help/release/dev/link-option-PIE.rst b/Help/release/dev/link-option-PIE.rst deleted file mode 100644 index 872343c..0000000 --- a/Help/release/dev/link-option-PIE.rst +++ /dev/null @@ -1,9 +0,0 @@ -link-option-PIE ---------------- - -* Required link options to manage Position Independent Executable are now - added when :prop_tgt:`POSITION_INDEPENDENT_CODE` is set. The project is - responsible for using the :module:`CheckPIESupported` module to check for - ``PIE`` support to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` - target property will be honored at link time for executables. This behavior - is controlled by policy :policy:`CMP0083`. diff --git a/Help/release/dev/max-recursion-depth.rst b/Help/release/dev/max-recursion-depth.rst deleted file mode 100644 index 3d9c781..0000000 --- a/Help/release/dev/max-recursion-depth.rst +++ /dev/null @@ -1,6 +0,0 @@ -max-recursion-depth -------------------- - -* CMake now imposes a maximum recursion limit to prevent a stack overflow on - scripts that recurse infinitely. The limit can be adjusted at runtime with - :variable:`CMAKE_MAXIMUM_RECURSION_DEPTH`. diff --git a/Help/release/dev/object-library-link.rst b/Help/release/dev/object-library-link.rst deleted file mode 100644 index 990d915..0000000 --- a/Help/release/dev/object-library-link.rst +++ /dev/null @@ -1,5 +0,0 @@ -object-library-link -------------------- - -* Object library linking has been fixed to propagate transitive link - dependencies of object libraries to consuming targets. diff --git a/Help/release/dev/rel-win7.rst b/Help/release/dev/rel-win7.rst deleted file mode 100644 index f7a745c..0000000 --- a/Help/release/dev/rel-win7.rst +++ /dev/null @@ -1,6 +0,0 @@ -rel-win7 --------- - -* Support for running CMake on Windows XP and Windows Vista has been dropped. - The precompiled Windows binaries provided on ``cmake.org`` now require - Windows 7 or higher. diff --git a/Help/release/dev/relative-rpath.rst b/Help/release/dev/relative-rpath.rst deleted file mode 100644 index 5c62b10..0000000 --- a/Help/release/dev/relative-rpath.rst +++ /dev/null @@ -1,8 +0,0 @@ -relative-rpath --------------- - -* A :variable:`CMAKE_BUILD_RPATH_USE_ORIGIN` variable and corresponding - :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property were added to - enable use of relative runtime paths (RPATHs). This helps achieving - relocatable and reproducible builds that are invariant of the build - directory. diff --git a/Help/release/dev/submit-method.rst b/Help/release/dev/submit-method.rst deleted file mode 100644 index 38f0b92..0000000 --- a/Help/release/dev/submit-method.rst +++ /dev/null @@ -1,6 +0,0 @@ -submit-method -------------- - -* CTest no longer supports submissions via ``ftp``, ``scp``, ``cp``, and - ``xmlrpc``. CDash is the only maintained testing dashboard for CTest, - and it only supports submissions over ``http`` and ``https``. diff --git a/Help/release/dev/try_compile-LINK_OPTIONS.rst b/Help/release/dev/try_compile-LINK_OPTIONS.rst deleted file mode 100644 index 1db485b..0000000 --- a/Help/release/dev/try_compile-LINK_OPTIONS.rst +++ /dev/null @@ -1,5 +0,0 @@ -try_compile-LINK_OPTIONS ------------------------- - -* The commands :command:`try_compile` and :command:`try_run` gain new - option ``LINK_OPTIONS``. diff --git a/Help/release/dev/vs-debug-utility-targets.rst b/Help/release/dev/vs-debug-utility-targets.rst deleted file mode 100644 index 02e5262..0000000 --- a/Help/release/dev/vs-debug-utility-targets.rst +++ /dev/null @@ -1,6 +0,0 @@ -vs-debug-utility-targets ------------------------- - -* :ref:`Visual Studio Generators` for VS 2010 and above learned - to support the ``VS_DEBUGGER_*`` properties on targets created - via :command:`add_custom_target`. diff --git a/Help/release/dev/vs2019.rst b/Help/release/dev/vs2019.rst deleted file mode 100644 index 1ffdeec..0000000 --- a/Help/release/dev/vs2019.rst +++ /dev/null @@ -1,13 +0,0 @@ -vs2019 ------- - -* The :generator:`Visual Studio 16 2019` generator was added. This is - experimental and based on "Visual Studio 2019 Preview 1.1" because this - version of VS has not been released. - - The VS 2019 generator differs from generators for earlier versions - in that it does not provide variants that specify the target platform - in the generator name. Instead :variable:`CMAKE_GENERATOR_PLATFORM` - must be used, e.g. through the ``-A`` command-line option. Furthermore, - the default target platform (architecture) is now based on the *host* - platform. diff --git a/Help/release/index.rst b/Help/release/index.rst index 7ef3a8e..4fcd4ca 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -7,14 +7,13 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. -.. include:: dev.txt - Releases ======== .. toctree:: :maxdepth: 1 + 3.14 <3.14> 3.13 <3.13> 3.12 <3.12> 3.11 <3.11> diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index e9bc28b..e77f211 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -44,8 +44,8 @@ Supported pairs are: and above with the CUDA toolkit VS integration installed. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable. -``host=x64`` - Request use of the native ``x64`` toolchain on ``x64`` hosts. +``host=<arch>`` + Specify the host tools architecture as ``x64`` or ``x86``. Supported by VS 2013 and above. See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE` variable. diff --git a/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst b/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst new file mode 100644 index 0000000..b6768a1 --- /dev/null +++ b/Help/variable/CMAKE_GHS_NO_SOURCE_GROUP_FILE.rst @@ -0,0 +1,6 @@ +CMAKE_GHS_NO_SOURCE_GROUP_FILE +------------------------------ + +``ON`` / ``OFF`` boolean to control if the project file for a target should +be one single file or multiple files. Refer to +:prop_tgt:`GHS_NO_SOURCE_GROUP_FILE` for further details. diff --git a/Help/variable/CMAKE_HOME_DIRECTORY.rst b/Help/variable/CMAKE_HOME_DIRECTORY.rst index fdc5d81..b03d956 100644 --- a/Help/variable/CMAKE_HOME_DIRECTORY.rst +++ b/Help/variable/CMAKE_HOME_DIRECTORY.rst @@ -1,6 +1,9 @@ CMAKE_HOME_DIRECTORY -------------------- -Path to top of source tree. +Path to top of source tree. Same as :variable:`CMAKE_SOURCE_DIR`. -This is the path to the top level of the source tree. +This is an internal cache entry used to locate the source directory +when loading a ``CMakeCache.txt`` from a build tree. It should not +be used in project code. The variable :variable:`CMAKE_SOURCE_DIR` +has the same value and should be preferred. diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 033e81c..5323880 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -17,6 +17,7 @@ include: Clang = LLVM Clang (clang.llvm.org) Cray = Cray Compiler (cray.com) Embarcadero, Borland = Embarcadero (embarcadero.com) + Flang = Flang LLVM Fortran Compiler G95 = G95 Fortran (g95.org) GNU = GNU Compiler Collection (gcc.gnu.org) GHS = Green Hills Software (www.ghs.com) @@ -28,7 +29,6 @@ include: NVIDIA = NVIDIA CUDA Compiler (nvidia.com) OpenWatcom = Open Watcom (openwatcom.org) PGI = The Portland Group (pgroup.com) - Flang = Flang Fortran Compiler PathScale = PathScale (pathscale.com) SDCC = Small Device C Compiler (sdcc.sourceforge.net) SunPro = Oracle Solaris Studio (oracle.com) diff --git a/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst index be89f85..16fcc03 100644 --- a/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_LIBRARY.rst @@ -4,4 +4,5 @@ CMAKE_<LANG>_CREATE_SHARED_LIBRARY Rule variable to create a shared library. This is a rule variable that tells CMake how to create a shared -library for the language ``<LANG>``. +library for the language ``<LANG>``. This rule variable is a ``;`` delimited +list of commands to run to perform the linking step. diff --git a/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst index ae5f69d..807229d 100644 --- a/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst +++ b/Help/variable/CMAKE_LANG_CREATE_SHARED_MODULE.rst @@ -4,4 +4,5 @@ CMAKE_<LANG>_CREATE_SHARED_MODULE Rule variable to create a shared module. This is a rule variable that tells CMake how to create a shared -library for the language ``<LANG>``. +library for the language ``<LANG>``. This rule variable is a ``;`` delimited +list of commands to run. diff --git a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst index cc80851..e361fd9 100644 --- a/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst +++ b/Help/variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES.rst @@ -6,4 +6,9 @@ Directories implicitly searched by the compiler for header files. CMake does not explicitly specify these directories on compiler command lines for language ``<LANG>``. This prevents system include directories from being treated as user include directories on some -compilers. +compilers, which is important for ``C``, ``CXX``, and ``CUDA`` to +avoid overriding standard library headers. + +This value is not used for ``Fortran`` because it has no standard +library headers and some compilers do not search their implicit +include directories for module ``.mod`` files. diff --git a/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst index 50121e2..b4a74eb 100644 --- a/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst +++ b/Help/variable/CMAKE_Swift_LANGUAGE_VERSION.rst @@ -1,5 +1,9 @@ CMAKE_Swift_LANGUAGE_VERSION ---------------------------- -Set to the Swift language version number. If not set, the legacy "2.3" -version is assumed. +Set to the Swift language version number. If not set, the oldest legacy +version known to be available in the host Xcode version is assumed: + +* Swift ``4.0`` for Xcode 10.2 and above. +* Swift ``3.0`` for Xcode 8.3 and above. +* Swift ``2.3`` for Xcode 8.2 and below. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst index 9b59c52..99ac90d 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst @@ -3,8 +3,8 @@ CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE Visual Studio preferred tool architecture. -The :ref:`Visual Studio Generators` for VS 2013 and above support optional -selection of a 64-bit toolchain on 64-bit hosts by specifying a ``host=x64`` -value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. CMake provides -the selected toolchain architecture preference in this variable (either -``x64`` or empty). +The :ref:`Visual Studio Generators` for VS 2013 and above support using +either the 32-bit or 64-bit host toolchains by specifying a ``host=x86`` +or ``host=x64`` value in the :variable:`CMAKE_GENERATOR_TOOLSET` option. +CMake provides the selected toolchain architecture preference in this +variable (``x86``, ``x64``, or empty). diff --git a/Help/variable/MSYS.rst b/Help/variable/MSYS.rst new file mode 100644 index 0000000..25ddc7f --- /dev/null +++ b/Help/variable/MSYS.rst @@ -0,0 +1,4 @@ +MSYS +---- + +``True`` when using the :generator:`MSYS Makefiles` generator. |