diff options
Diffstat (limited to 'Help')
51 files changed, 362 insertions, 75 deletions
diff --git a/Help/command/ctest_submit.rst b/Help/command/ctest_submit.rst index 426475c..fba03fd 100644 --- a/Help/command/ctest_submit.rst +++ b/Help/command/ctest_submit.rst @@ -6,6 +6,7 @@ Perform the :ref:`CTest Submit Step` as a :ref:`Dashboard Client`. :: ctest_submit([PARTS <part>...] [FILES <file>...] + [SUBMIT_URL <url>] [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] @@ -39,6 +40,10 @@ The options are: Specify an explicit list of specific files to be submitted. Each individual file must exist at the time of the call. +``SUBMIT_URL <url>`` + The ``http`` or ``https`` URL of the dashboard server to send the submission + to. If not given, the :variable:`CTEST_SUBMIT_URL` variable is used. + ``HTTPHEADER <HTTP-header>`` Specify HTTP header to be included in the request to CDash during submission. This suboption can be repeated several times. @@ -68,6 +73,7 @@ Submit to CDash Upload API :: ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>] + [SUBMIT_URL <url>] [HTTPHEADER <header>] [RETRY_COUNT <count>] [RETRY_DELAY <delay>] @@ -80,5 +86,5 @@ with a content hash of the file. If CDash does not already have the file, then it is uploaded. Along with the file, a CDash type string is specified to tell CDash which handler to use to process the data. -This signature accepts the ``HTTPHEADER``, ``RETRY_COUNT``, ``RETRY_DELAY``, -``RETURN_VALUE`` and ``QUIET`` options as described above. +This signature accepts the ``SUBMIT_URL``, ``HTTPHEADER``, ``RETRY_COUNT``, +``RETRY_DELAY``, ``RETURN_VALUE`` and ``QUIET`` options as described above. diff --git a/Help/command/file.rst b/Help/command/file.rst index 6e2a6dd..db4d6fc 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -27,6 +27,7 @@ Synopsis file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...]) file(`SIZE`_ <filename> <out-var>) file(`READ_SYMLINK`_ <filename> <out-var>) + file(`CREATE_LINK`_ <file> <new-file> [...]) `Path Conversion`_ file(`RELATIVE_PATH`_ <out-var> <directory> <file>) @@ -368,6 +369,28 @@ could do something like this: set(result "${dir}/${result}") endif() +.. _CREATE_LINK: + +.. code-block:: cmake + + file(CREATE_LINK <file> <new-file> + [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC]) + +Create a link to ``<file>`` at ``<new-file>``. + +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. + +Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if +creating the link fails. + +Overwrites the ``<new-file>`` if it exists. + Path Conversion ^^^^^^^^^^^^^^^ diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index cafef8c..54d5f68 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -354,6 +354,11 @@ enabled. .. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ORDER.txt +By default the value stored in the result variable will be the path at +which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` +variable may be set to ``TRUE`` before calling ``find_package`` in order +to resolve symbolic links and store the real path to the file. + Every non-REQUIRED ``find_package`` call can be disabled by setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. diff --git a/Help/command/get_filename_component.rst b/Help/command/get_filename_component.rst index 3e3c9c3..f55499a 100644 --- a/Help/command/get_filename_component.rst +++ b/Help/command/get_filename_component.rst @@ -15,6 +15,8 @@ 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 extention (.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. diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index cf9e06f..77f42a1 100644 --- a/Help/command/try_compile.rst +++ b/Help/command/try_compile.rst @@ -168,3 +168,6 @@ then the language standard variables are honored: Their values are used to set the corresponding target properties in the generated project (unless overridden by an explicit option). + +For the :generator:`Green Hills MULTI` generator the GHS toolset and target +system customization cache variables are also propagated into the test project. 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/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 1b4960d..bfe671f 100644 --- a/Help/generator/Green Hills MULTI.rst +++ b/Help/generator/Green Hills MULTI.rst @@ -3,49 +3,63 @@ Green Hills MULTI Generates Green Hills MULTI project files (experimental, work-in-progress). +The buildsystem has predetermined build-configuration settings that can be controlled +via the :variable:`CMAKE_BUILD_TYPE` variable. + Customizations that are used to pick toolset and target system: The ``-A <arch>`` can be supplied for setting the target architecture. ``<arch>`` usually is one of "arm", "ppc", "86", etcetera. If the target architecture is not specified then the default architecture of "arm" will be used. -The ``-T <toolset>`` can be supplied for setting the toolset to be used. -All toolsets are expected to be located at ``GHS_TOOLSET_ROOT``. -If the toolset is not specified then the latest toolset will be used. +The ``-T <toolset>`` option can be used to set the directory location of the toolset. +Both absolute and relative paths are valid. Relative paths use ``GHS_TOOLSET_ROOT`` +as the root. If the toolset is not specified then the latest toolset found in +``GHS_TOOLSET_ROOT`` will be used. + +Cache variables that are used for toolset and target system customization: * ``GHS_TARGET_PLATFORM`` -Default to ``integrity``. -Usual values are ``integrity``, ``threadx``, ``uvelosity``, -``velosity``, ``vxworks``, ``standalone``. + | Defaults to ``integrity``. + | Usual values are ``integrity``, ``threadx``, ``uvelosity``, ``velosity``, + ``vxworks``, ``standalone``. * ``GHS_PRIMARY_TARGET`` -Sets ``primaryTarget`` field in project file. -Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``. + | Sets ``primaryTarget`` entry in project file. + | Defaults to ``<arch>_<GHS_TARGET_PLATFORM>.tgt``. * ``GHS_TOOLSET_ROOT`` -Default to ``C:/ghs``. Root path for ``toolset``. + | Root path for ``toolset`` searches. + | Defaults to ``C:/ghs``. * ``GHS_OS_ROOT`` -Default to ``C:/ghs``. Root path for RTOS searches. + | Root path for RTOS searches. + | Defaults to ``C:/ghs``. * ``GHS_OS_DIR`` -Default to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if -a specific RTOS is to be used. + | Sets ``-os_dir`` entry in project file. + | Defaults to latest platform OS installation at ``GHS_OS_ROOT``. Set this value if + a specific RTOS is to be used. * ``GHS_BSP_NAME`` -Defaults to ``sim<arch>`` if not set by user. + | Sets ``-bsp`` entry in project file. + | Defaults to ``sim<arch>`` for ``integrity`` platforms. Customizations are available through the following cache variables: * ``GHS_CUSTOMIZATION`` * ``GHS_GPJ_MACROS`` +The following properties are available: + +* :prop_tgt:`GHS_INTEGRITY_APP` + .. note:: This generator is deemed experimental as of CMake |release| and is still a work in progress. Future versions of CMake 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/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-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 63e43e1..7f484a4 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -122,12 +122,19 @@ Variable Queries ``1`` if the CMake-id of the CXX compiler matches ``compiler_id``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID:compiler_id>`` + ``1`` if the CMake-id of the Fortran compiler matches ``compiler_id``, + otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION:version>`` ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<CXX_COMPILER_VERSION:version>`` ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<Fortran_COMPILER_VERSION:version>`` + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<TARGET_POLICY:policy>`` ``1`` if the ``policy`` was NEW when the 'head' target was created, else ``0``. If the ``policy`` was not set, the warning message for the policy @@ -339,12 +346,18 @@ Variable Queries ``$<CXX_COMPILER_ID>`` The CMake-id of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID>`` + The CMake-id of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION>`` The version of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<CXX_COMPILER_VERSION>`` The version of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<Fortran_COMPILER_VERSION>`` + The version of the Fortran compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<COMPILE_LANGUAGE>`` The compile language of source files when evaluating compile options. See :ref:`the related boolean expression 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 02aaf4a..e1de134 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -194,6 +194,7 @@ Properties on Targets /prop_tgt/FRAMEWORK /prop_tgt/FRAMEWORK_VERSION /prop_tgt/GENERATOR_FILE_NAME + /prop_tgt/GHS_INTEGRITY_APP /prop_tgt/GNUtoMS /prop_tgt/HAS_CXX /prop_tgt/IMPLICIT_DEPENDS_INCLUDE_TRANSFORM @@ -205,7 +206,6 @@ Properties on Targets /prop_tgt/IMPORTED_LIBNAME_CONFIG /prop_tgt/IMPORTED_LIBNAME /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG - /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES_CONFIG /prop_tgt/IMPORTED_LINK_DEPENDENT_LIBRARIES /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES_CONFIG /prop_tgt/IMPORTED_LINK_INTERFACE_LANGUAGES diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index e464b0c..de4ce3d 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -170,6 +170,7 @@ Variables that Change Behavior /variable/CMAKE_FIND_NO_INSTALL_PREFIX /variable/CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY /variable/CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY + /variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS /variable/CMAKE_FIND_PACKAGE_WARN_NO_MODULE /variable/CMAKE_FIND_ROOT_PATH /variable/CMAKE_FIND_ROOT_PATH_MODE_INCLUDE @@ -189,6 +190,7 @@ Variables that Change Behavior /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE /variable/CMAKE_MFC_FLAG + /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MODULE_PATH /variable/CMAKE_NOT_USING_CONFIG_FLAGS /variable/CMAKE_POLICY_DEFAULT_CMPNNNN @@ -482,11 +484,6 @@ Variables for Languages /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE - /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_IGNORE_EXTENSIONS /variable/CMAKE_LANG_IMPLICIT_INCLUDE_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES @@ -574,6 +571,7 @@ Variables for CTest /variable/CTEST_RUN_CURRENT_SCRIPT /variable/CTEST_SCP_COMMAND /variable/CTEST_SITE + /variable/CTEST_SUBMIT_URL /variable/CTEST_SOURCE_DIRECTORY /variable/CTEST_SVN_COMMAND /variable/CTEST_SVN_OPTIONS 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/manual/ctest.1.rst b/Help/manual/ctest.1.rst index 8490e3d..bcf75ac 100644 --- a/Help/manual/ctest.1.rst +++ b/Help/manual/ctest.1.rst @@ -1109,38 +1109,45 @@ Configuration settings include: * :module:`CTest` module variable: ``CTEST_CURL_OPTIONS`` ``DropLocation`` - The path on the dashboard server to send the submission. + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_LOCATION` * :module:`CTest` module variable: ``DROP_LOCATION`` if set, else ``CTEST_DROP_LOCATION`` ``DropMethod`` - Specify the method by which results should be submitted to the - dashboard server. The value may be ``http`` or ``https``. + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_METHOD` * :module:`CTest` module variable: ``DROP_METHOD`` if set, else ``CTEST_DROP_METHOD`` ``DropSite`` - The dashboard server name. + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE` * :module:`CTest` module variable: ``DROP_SITE`` if set, else ``CTEST_DROP_SITE`` ``DropSitePassword`` - The dashboard server login password, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_PASSWORD` * :module:`CTest` module variable: ``DROP_SITE_PASSWORD`` if set, else ``CTEST_DROP_SITE_PASWORD`` ``DropSiteUser`` - The dashboard server login user name, if any - (for ``ftp``, ``http``, and ``https``). + Legacy option. When ``SubmitURL`` is not set, it is constructed from + ``DropMethod``, ``DropSiteUser``, ``DropSitePassword``, ``DropSite``, and + ``DropLocation``. * `CTest Script`_ variable: :variable:`CTEST_DROP_SITE_USER` * :module:`CTest` module variable: ``DROP_SITE_USER`` if set, @@ -1166,6 +1173,14 @@ Configuration settings include: * :module:`CTest` module variable: ``SITE``, initialized by the :command:`site_name` command +``SubmitURL`` + The ``http`` or ``https`` URL of the dashboard server to send the submission + to. + + * `CTest Script`_ variable: :variable:`CTEST_SUBMIT_URL` + * :module:`CTest` module variable: ``SUBMIT_URL`` if set, + else ``CTEST_SUBMIT_URL`` + ``TriggerSite`` Legacy option. Not used. diff --git a/Help/prop_dir/EXCLUDE_FROM_ALL.rst b/Help/prop_dir/EXCLUDE_FROM_ALL.rst index 1aa24e4..9d3192c 100644 --- a/Help/prop_dir/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_dir/EXCLUDE_FROM_ALL.rst @@ -7,3 +7,9 @@ A property on a directory that indicates if its targets are excluded from the default build target. If it is not, then with a Makefile for example typing make will cause the targets to be built. The same concept applies to the default build of other generators. + +Targets inherit the :prop_tgt:`EXCLUDE_FROM_ALL` property from the directory +that they are created in. When a directory is excluded, all of its targets will +have :prop_tgt:`EXCLUDE_FROM_ALL` set to ``TRUE``. After creating such a target +you can change its :prop_tgt:`EXCLUDE_FROM_ALL` property to ``FALSE``. This +will cause the target to be included in the default build target. diff --git a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst index caa5741..e7457e1 100644 --- a/Help/prop_tgt/EXCLUDE_FROM_ALL.rst +++ b/Help/prop_tgt/EXCLUDE_FROM_ALL.rst @@ -8,3 +8,6 @@ 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. + +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_INTEGRITY_APP.rst b/Help/prop_tgt/GHS_INTEGRITY_APP.rst new file mode 100644 index 0000000..7643038 --- /dev/null +++ b/Help/prop_tgt/GHS_INTEGRITY_APP.rst @@ -0,0 +1,10 @@ +GHS_INTEGRITY_APP +----------------- + +``ON`` / ``OFF`` boolean to determine if an executable target should +be treated as an `Integrity Application`. + +If no value is set and if a `.int` file is added as a source file to the +executable target it will be treated as an `Integrity Application`. + +Supported on :generator:`Green Hills MULTI`. diff --git a/Help/release/3.13.rst b/Help/release/3.13.rst index 68e05c3..1c58550 100644 --- a/Help/release/3.13.rst +++ b/Help/release/3.13.rst @@ -252,3 +252,29 @@ Changes made since CMake 3.13.0 include the following. directories to the ``moc`` tool for :prop_tgt:`AUTOMOC`. This has been reverted due to regressing existing builds and will need further investigation before being re-introduced in a later release. + +3.13.3 +------ + +* The :generator:`Visual Studio 15 2017` generator has been fixed to work + when VS 2019 is installed. + +* CMake now checks that at least one of the source or binary directory + is specified when running CMake and issues an error if both are missing. + This has always been a documented requirement, but the implementation + previously accidentally accepted cases in which neither are specified + so long as some other argument is given, and silently used the current + working directory as the source and build tree. + +3.13.4 +------ + +* The error added by 3.13.3 in cases that neither a source or binary + directory is specified has been downgraded to a warning. While this + was never intended, documented, nor supported behavior, some projects + relied on it. The error has been downgraded to a warning for the + remainder of the 3.13.x release series to allow a transition period, + but it may become a fatal error again in a later release. Scripts + relying on the old behavior can be trivially fixed by specifying + the path to the source tree (even if just ``.``) explicitly and + continue to work with all versions of CMake. diff --git a/Help/release/dev/EXCLUDE_FROM_ALL.rst b/Help/release/dev/EXCLUDE_FROM_ALL.rst new file mode 100644 index 0000000..519ac42 --- /dev/null +++ b/Help/release/dev/EXCLUDE_FROM_ALL.rst @@ -0,0 +1,7 @@ +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-non-cmake-source-subdir.rst b/Help/release/dev/ExternalProject-non-cmake-source-subdir.rst new file mode 100644 index 0000000..29fe2ad --- /dev/null +++ b/Help/release/dev/ExternalProject-non-cmake-source-subdir.rst @@ -0,0 +1,7 @@ +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/FindPython-NumPy-component.rst b/Help/release/dev/FindPython-NumPy-component.rst new file mode 100644 index 0000000..5ea6cfb --- /dev/null +++ b/Help/release/dev/FindPython-NumPy-component.rst @@ -0,0 +1,5 @@ +FindPython-NumPy-component +-------------------------- + +* The :module:`FindPython`, :module:`FindPython2`, and :module:`FindPython3` + modules gained support for ``NumPy`` component. diff --git a/Help/release/dev/cmake-build-verbose.rst b/Help/release/dev/cmake-build-verbose.rst new file mode 100644 index 0000000..dee212e --- /dev/null +++ b/Help/release/dev/cmake-build-verbose.rst @@ -0,0 +1,6 @@ +cmake-build-verbose +------------------- + +* The :manual:`cmake(1)` :ref:`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. diff --git a/Help/release/dev/cmake-gui-s-b.rst b/Help/release/dev/cmake-gui-s-b.rst new file mode 100644 index 0000000..9447eb3 --- /dev/null +++ b/Help/release/dev/cmake-gui-s-b.rst @@ -0,0 +1,5 @@ +cmake-gui-s-b +------------- + +* The :manual:`cmake-gui(1)` dialog gained new ``-S`` and ``-B`` arguments to + explicitly specify source and build directories. diff --git a/Help/release/dev/compare_files-ignore-eol.rst b/Help/release/dev/compare_files-ignore-eol.rst new file mode 100644 index 0000000..bc32921 --- /dev/null +++ b/Help/release/dev/compare_files-ignore-eol.rst @@ -0,0 +1,6 @@ +compare_files-ignore-eol +------------------------ + +* 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. diff --git a/Help/release/dev/ctest-submit-url.rst b/Help/release/dev/ctest-submit-url.rst new file mode 100644 index 0000000..f848877 --- /dev/null +++ b/Help/release/dev/ctest-submit-url.rst @@ -0,0 +1,7 @@ +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/find-package-resolve-symlinks.rst b/Help/release/dev/find-package-resolve-symlinks.rst new file mode 100644 index 0000000..7adb9fe --- /dev/null +++ b/Help/release/dev/find-package-resolve-symlinks.rst @@ -0,0 +1,6 @@ +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/findgit-imported-target.rst b/Help/release/dev/findgit-imported-target.rst new file mode 100644 index 0000000..cabbae5 --- /dev/null +++ b/Help/release/dev/findgit-imported-target.rst @@ -0,0 +1,5 @@ +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 new file mode 100644 index 0000000..5de1ebf --- /dev/null +++ b/Help/release/dev/findpython-script.rst @@ -0,0 +1,6 @@ +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 new file mode 100644 index 0000000..1ea3bf9 --- /dev/null +++ b/Help/release/dev/fortran-compiler-id.rst @@ -0,0 +1,5 @@ +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/get_filename_component_last_ext.rst b/Help/release/dev/get_filename_component_last_ext.rst new file mode 100644 index 0000000..2487dbc --- /dev/null +++ b/Help/release/dev/get_filename_component_last_ext.rst @@ -0,0 +1,6 @@ +get_filename_component_last_ext +------------------------------- + +* 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. diff --git a/Help/release/dev/max-recursion-depth.rst b/Help/release/dev/max-recursion-depth.rst new file mode 100644 index 0000000..3d9c781 --- /dev/null +++ b/Help/release/dev/max-recursion-depth.rst @@ -0,0 +1,6 @@ +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/vs2019.rst b/Help/release/dev/vs2019.rst index 1ffdeec..ee9a2f2 100644 --- a/Help/release/dev/vs2019.rst +++ b/Help/release/dev/vs2019.rst @@ -2,7 +2,7 @@ vs2019 ------ * The :generator:`Visual Studio 16 2019` generator was added. This is - experimental and based on "Visual Studio 2019 Preview 1.1" because this + 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 @@ -10,4 +10,5 @@ vs2019 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. + platform. The VS host toolset selection is now based on the host + architecture as well. diff --git a/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst b/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst new file mode 100644 index 0000000..dfbde20 --- /dev/null +++ b/Help/variable/CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS.rst @@ -0,0 +1,10 @@ +CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS +----------------------------------- + +Set to ``TRUE`` to tell :command:`find_package` calls to resolve symbolic +links in the value of ``<PackageName>_DIR``. + +This is helpful in use cases where the package search path points at a +proxy directory in which symlinks to the real package locations appear. +This is not enabled by default because there are also common use cases +in which the symlinks should be preserved. 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_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst index 2264269..5323880 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst @@ -17,8 +17,10 @@ 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) HP = Hewlett-Packard Compiler (hp.com) IAR = IAR Systems (iar.com) Intel = Intel Compiler (intel.com) @@ -27,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_GHS_KERNEL_FLAGS_CONFIG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst deleted file mode 100644 index 8ed1c02..0000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_CONFIG.rst +++ /dev/null @@ -1,5 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG> --------------------------------------- - -GHS kernel flags for language ``<LANG>`` when building for the ``<CONFIG>`` -configuration. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst deleted file mode 100644 index 4fea67a..0000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG.rst +++ /dev/null @@ -1,5 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_DEBUG ------------------------------------ - -This variable is the ``Debug`` variant of the -:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst deleted file mode 100644 index 31f87f2..0000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL.rst +++ /dev/null @@ -1,5 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_MINSIZEREL ----------------------------------------- - -This variable is the ``MinSizeRel`` variant of the -:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst deleted file mode 100644 index 1acd198..0000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE.rst +++ /dev/null @@ -1,5 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELEASE -------------------------------------- - -This variable is the ``Release`` variant of the -:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst b/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst deleted file mode 100644 index ac1b6bc..0000000 --- a/Help/variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELWITHDEBINFO.rst +++ /dev/null @@ -1,5 +0,0 @@ -CMAKE_<LANG>_GHS_KERNEL_FLAGS_RELWITHDEBINFO --------------------------------------------- - -This variable is the ``RelWithDebInfo`` variant of the -:variable:`CMAKE_<LANG>_GHS_KERNEL_FLAGS_<CONFIG>` variable. diff --git a/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst new file mode 100644 index 0000000..7110b16 --- /dev/null +++ b/Help/variable/CMAKE_MAXIMUM_RECURSION_DEPTH.rst @@ -0,0 +1,33 @@ +CMAKE_MAXIMUM_RECURSION_DEPTH +----------------------------- + +Maximum recursion depth for CMake scripts. It is intended to be set on the +command line with ``-DCMAKE_MAXIMUM_RECURSION_DEPTH=<x>``, or within +``CMakeLists.txt`` by projects that require a large recursion depth. Projects +that set this variable should provide the user with a way to override it. For +example: + +.. code-block:: cmake + + # About to perform deeply recursive actions + if(NOT CMAKE_MAXIMUM_RECURSION_DEPTH) + set(CMAKE_MAXIMUM_RECURSION_DEPTH 2000) + endif() + +If it is not set, or is set to a non-integer value, a sensible default limit is +used. If the recursion limit is reached, the script terminates immediately with +a fatal error. + +Calling any of the following commands increases the recursion depth: + +* :command:`include` +* :command:`find_package` +* :command:`add_subdirectory` +* :command:`try_compile` +* :command:`ctest_read_custom_files` +* :command:`ctest_run_script` (unless ``NEW_PROCESS`` is specified) +* User-defined :command:`function`'s and :command:`macro`'s (note that + :command:`function` and :command:`macro` themselves don't increase recursion + depth) +* Reading or writing variables that are being watched by a + :command:`variable_watch` 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/CTEST_SUBMIT_URL.rst b/Help/variable/CTEST_SUBMIT_URL.rst new file mode 100644 index 0000000..7d84da4 --- /dev/null +++ b/Help/variable/CTEST_SUBMIT_URL.rst @@ -0,0 +1,5 @@ +CTEST_SUBMIT_URL +---------------- + +Specify the CTest ``SubmitURL`` setting +in a :manual:`ctest(1)` dashboard client script. diff --git a/Help/variable/GHS-MULTI.rst b/Help/variable/GHS-MULTI.rst index 0f91be8..fe3b17e 100644 --- a/Help/variable/GHS-MULTI.rst +++ b/Help/variable/GHS-MULTI.rst @@ -1,4 +1,4 @@ GHS-MULTI --------- -True when using Green Hills MULTI +``True`` when using :generator:`Green Hills MULTI` generator. |