diff options
Diffstat (limited to 'Help')
84 files changed, 1356 insertions, 165 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst index 3e669c2..b2e4eea 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -304,6 +304,11 @@ Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific Generated files are modified on subsequent cmake runs only if their content is changed. +Note also that ``file(GENERATE)`` does not create the output file until the +generation phase. The output file will not yet have been written when the +``file(GENERATE)`` command returns, it is written only after processing all +of a project's ``CMakeLists.txt`` files. + ------------------------------------------------------------------------------ :: diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst index 1eb50f7..f774f17 100644 --- a/Help/command/find_library.rst +++ b/Help/command/find_library.rst @@ -49,6 +49,14 @@ path to the framework ``<fullPath>/A.framework``. When a full path to a framework is used as a library, CMake will use a ``-framework A``, and a ``-F<fullPath>`` to link the framework to the target. +If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all +search paths will be tested as normal, with the suffix appended, and with +all matches of ``lib/`` replaced with +``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``. This variable overrides +the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`, +:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`, +and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties. + If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set all search paths will be tested as normal, with ``32/`` appended, and with all matches of ``lib/`` replaced with ``lib32/``. This property is @@ -56,6 +64,13 @@ automatically set for the platforms that are known to need it if at least one of the languages supported by the :command:`project` command is enabled. +If the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property is set +all search paths will be tested as normal, with ``x32/`` appended, and +with all matches of ``lib/`` replaced with ``libx32/``. This property is +automatically set for the platforms that are known to need it if at +least one of the languages supported by the :command:`project` command +is enabled. + If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set all search paths will be tested as normal, with ``64/`` appended, and with all matches of ``lib/`` replaced with ``lib64/``. This property is diff --git a/Help/command/include_external_msproject.rst b/Help/command/include_external_msproject.rst index 18a2b50..335282a 100644 --- a/Help/command/include_external_msproject.rst +++ b/Help/command/include_external_msproject.rst @@ -20,3 +20,7 @@ command to make things depend on the external project. specify the type of project, id (GUID) of the project and the name of the target platform. This is useful for projects requiring values other than the default (e.g. WIX projects). + +If the imported project has different configuration names than the +current project, set the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` +target property to specify the mapping. diff --git a/Help/dev/README.rst b/Help/dev/README.rst new file mode 100644 index 0000000..0dc512a --- /dev/null +++ b/Help/dev/README.rst @@ -0,0 +1,31 @@ +CMake Development +***************** + +This directory contains documentation about development of CMake itself. +It is not part of the user documentation distributed with CMake. + +Contributor Instructions +======================== + +See `CONTRIBUTING.rst`_ for instructions to contribute changes. + +The process for contributing changes is the same whether or not one +has been invited to participate directly in upstream development. + +.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst + +Upstream Development +==================== + +CMake uses `Kitware's GitLab Instance`_ to manage development, review, and +integration of changes. The `CMake Repository`_ holds the integration +branches and tags. Upstream development processes are covered by the +following documents: + +* The `CMake Review Process`_ manages integration of changes. +* The `CMake Testing Process`_ drives integration testing. + +.. _`Kitware's GitLab Instance`: https://gitlab.kitware.com +.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake +.. _`CMake Review Process`: review.rst +.. _`CMake Testing Process`: testing.rst diff --git a/Help/dev/review.rst b/Help/dev/review.rst new file mode 100644 index 0000000..3db1f40 --- /dev/null +++ b/Help/dev/review.rst @@ -0,0 +1,341 @@ +CMake Review Process +******************** + +The following documents the process for reviewing and integrating changes. +See `CONTRIBUTING.rst`_ for instructions to contribute changes. +See documentation on `CMake Development`_ for more information. + +.. _`CONTRIBUTING.rst`: ../../CONTRIBUTING.rst +.. _`CMake Development`: README.rst + +.. contents:: The review process consists of the following steps: + +Merge Request +============= + +A user initiates the review process for a change by pushing a *topic +branch* to his or her own fork of the `CMake Repository`_ on GitLab and +creating a *merge request* ("MR"). The new MR will appear on the +`CMake Merge Requests Page`_. The rest of the review and integration +process is managed by the merge request page for the change. + +During the review process, the MR submitter should address review comments +or test failures by updating the MR with a (force-)push of the topic +branch. The update initiates a new round of review. + +We recommend that users enable the "Remove source branch when merge +request is accepted" option when creating the MR or by editing it. +This will cause the MR topic branch to be automatically removed from +the user's fork during the `Merge`_ step. + +.. _`CMake Merge Requests Page`: https://gitlab.kitware.com/cmake/cmake/merge_requests +.. _`CMake Repository`: https://gitlab.kitware.com/cmake/cmake + +Workflow Status +--------------- + +`CMake GitLab Project Developers`_ may set one of the following labels +in GitLab to track the state of a MR: + +* ``workflow:wip`` indicates that the MR needs additional updates from + the MR submitter before further review. Use this label after making + comments that require such updates. + +* ``workflow:in-review`` indicates that the MR awaits feedback from a + human reviewer or from `Topic Testing`_. Use this label after making + comments requesting such feedback. + +* ``workflow:nightly-testing`` indicates that the MR awaits results + of `Integration Testing`_. Use this label after making comments + requesting such staging. + +* ``workflow:expired`` indicates that the MR has been closed due + to a period of inactivity. See the `Expire`_ step. Use this label + after closing a MR for this reason. + +The workflow status labels are intended to be mutually exclusive, +so please remove any existing workflow label when adding one. + +.. _`CMake GitLab Project Developers`: https://gitlab.kitware.com/cmake/cmake/settings/members + +Robot Review +============ + +The "Kitware Robot" (``@kwrobot``) automatically performs basic checks on +the commits proposed in a MR. If all is well the robot silently reports +a successful "build" status to GitLab. Otherwise the robot posts a comment +with its diagnostics. **A topic may not be merged until the automatic +review succeeds.** + +Note that the MR submitter is expected to address the robot's comments by +*rewriting* the commits named by the robot's diagnostics (e.g., via +``git rebase -i``). This is because the robot checks each commit individually, +not the topic as a whole. This is done in order to ensure that commits in the +middle of a topic do not, for example, add a giant file which is then later +removed in the topic. + +Automatic Check +--------------- + +The automatic check is repeated whenever the topic branch is updated. +One may explicitly request a re-check by adding a comment with the +following command among the `comment trailing lines`_:: + + Do: check + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also run its checks again. + +Automatic Format +---------------- + +The automatic check will reject commits introducing source code not +formatted according to ``clang-format``. One may ask the robot to +automatically rewrite the MR topic branch with expected formatting +by adding a comment with the following command among the +`comment trailing lines`_:: + + Do: reformat + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also rewrite the MR topic branch and force-push an +updated version with every commit formatted as expected by the check. + +Human Review +============ + +Anyone is welcome to review merge requests and make comments! + +Please make comments directly on the MR page Discussion and Changes tabs +and not on individual commits. Comments on a commit may disappear +from the MR page if the commit is rewritten in response. + +Reviewers may add comments providing feedback or to acknowledge their +approval. Lines of specific forms will be extracted during the `merge`_ +step and included as trailing lines of the generated merge commit message. +Each review comment consists of up to two parts which must be specified +in the following order: `comment body`_, then `comment trailing lines`_. +Each part is optional, but they must be specified in this order. + +Comment Body +------------ + +The body of a comment may be free-form `GitLab Flavored Markdown`_. +See GitLab documentation on `Special GitLab References`_ to add links to +things like issues, commits, or other merge requests (even across projects). + +Additionally, a line in the comment body may start with one of the +following votes: + +* ``-1`` or ``:-1:`` indicates "the change is not ready for integration". + +* ``+1`` or ``:+1:`` indicates "I like the change". + This adds an ``Acked-by:`` trailer to the `merge`_ commit message. + +* ``+2`` indicates "the change is ready for integration". + This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message. + +* ``+3`` indicates "I have tested the change and verified it works". + This adds a ``Tested-by:`` trailer to the `merge`_ commit message. + +.. _`GitLab Flavored Markdown`: https://gitlab.kitware.com/help/user/markdown.md +.. _`Special GitLab References`: https://gitlab.kitware.com/help/user/markdown.md#special-gitlab-references + +Comment Trailing Lines +---------------------- + +Zero or more *trailing* lines in the last section of a comment may appear +with the form ``Key: Value``. The first such line should be separated +from a preceding `comment body`_ by a blank line. Any key-value pair(s) +may be specified for human reference. A few specific keys have meaning to +``@kwrobot`` as follows. + +Comment Trailer Votes +^^^^^^^^^^^^^^^^^^^^^ + +Among the `comment trailing lines`_ one may cast a vote using one of the +following pairs followed by nothing but whitespace before the end of the line: + +* ``Rejected-by: me`` indicates "the change is not ready for integration". +* ``Acked-by: me`` indicates "I like the change". + This adds an ``Acked-by:`` trailer to the `merge`_ commit message. +* ``Reviewed-by: me`` indicates "the change is ready for integration". + This adds a ``Reviewed-by:`` trailer to the `merge`_ commit message. +* ``Tested-by: me`` indicates "I have tested the change and verified it works". + This adds a ``Tested-by:`` trailer to the `merge`_ commit message. + +Each ``me`` reference may instead be an ``@username`` reference or a full +``Real Name <user@domain>`` reference to credit someone else for performing +the review. References to ``me`` and ``@username`` will automatically be +transformed into a real name and email address according to the user's +GitLab account profile. + +Comment Trailer Commands +^^^^^^^^^^^^^^^^^^^^^^^^ + +Among the `comment trailing lines`_ authorized users may issue special +commands to ``@kwrobot`` using the form ``Do: ...``: + +* ``Do: check`` explicitly re-runs the robot `Automatic Check`_. +* ``Do: reformat`` rewrites the MR topic for `Automatic Format`_. +* ``Do: test`` submits the MR for `Topic Testing`_. +* ``Do: stage`` submits the MR for `Integration Testing`_. +* ``Do: merge`` submits the MR for `Merge`_. + +See the corresponding sections for details on permissions and options +for each command. + +Topic Testing +============= + +CMake has a `buildbot`_ instance watching for merge requests to test. +`CMake GitLab Project Developers`_ may activate buildbot on a MR by +adding a comment with a command among the `comment trailing lines`_:: + + Do: test + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also inform buildbot about the request. The buildbot +user (``@buildbot``) will schedule builds and respond with a comment +linking to the `CMake CDash Page`_ with a filter for results associated +with the topic test request. If the MR topic branch is updated by a +push a new ``Do: test`` command is needed to activate testing again. + +The ``Do: test`` command accepts the following arguments: + +* ``--stop``: clear the list of commands for the merge request +* ``--clear``: clear previous commands before adding this command +* ``--regex-include <arg>`` or ``-i <arg>``: only build on builders + matching ``<arg>`` (a Python regular expression) +* ``--regex-exclude <arg>`` or ``-e <arg>``: exclude builds on builders + matching ``<arg>`` (a Python regular expression) + +Builder names follow the pattern ``project-host-os-buildtype-generator``: + +* ``project``: always ``cmake`` for CMake builds +* ``host``: the buildbot host +* ``os``: one of ``windows``, ``osx``, or ``linux`` +* ``buildtype``: ``release`` or ``debug`` +* ``generator``: ``ninja``, ``makefiles``, or ``vs<year>`` + +.. _`buildbot`: http://buildbot.net +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake + +Integration Testing +=================== + +The above `topic testing`_ tests the MR topic independent of other +merge requests and on only a few key platforms and configurations. +The `CMake Testing Process`_ also has a large number of machines +provided by Kitware and generous volunteers that cover nearly all +supported platforms, generators, and configurations. In order to +avoid overwhelming these resources, they do not test every MR +individually. Instead, these machines follow an *integration branch*, +run tests on a nightly basis (or continuously during the day), and +post to the `CMake CDash Page`_. Some follow ``master``. Most follow +a special integration branch, the *topic stage*. + +The topic stage is a special branch maintained by the "Kitware Robot" +(``@kwrobot``). It consists of the head of the MR target integration +branch (e.g. ``master``) branch followed by a sequence of merges each +integrating changes from an open MR that has been staged for integration +testing. Each time the target integration branch is updated the stage +is rebuilt automatically by merging the staged MR topics again. + +`CMake GitLab Project Developers`_ may stage a MR for integration testing +by adding a comment with a command among the `comment trailing lines`_:: + + Do: stage + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also attempt to add the MR topic branch to the topic +stage. If the MR cannot be added (e.g. due to conflicts) the robot will +post a comment explaining what went wrong. + +Once a MR has been added to the topic stage it will remain on the stage +until one of the following occurs: + +* The MR topic branch is updated by a push. + +* The MR target integration branch (e.g. ``master``) branch is updated + and the MR cannot be merged into the topic stage again due to conflicts. + +* A developer or the submitter posts an explicit ``Do: unstage`` command. + +* The MR is closed. + +* The MR is merged. + +Once a MR has been removed from the topic stage a new ``Do: stage`` +command is needed to stage it again. + +.. _`CMake Testing Process`: testing.rst + +Resolve +======= + +A MR may be resolved in one of the following ways. + +Merge +----- + +Once review has concluded that the MR topic is ready for integration, +`CMake GitLab Project Masters`_ may merge the topic by adding a comment +with a command among the `comment trailing lines`_:: + + Do: merge + +``@kwrobot`` will add an award emoji to the comment to indicate that it +was processed and also attempt to merge the MR topic branch to the MR +target integration branch (e.g. ``master``). If the MR cannot be merged +(e.g. due to conflicts) the robot will post a comment explaining what +went wrong. If the MR is merged the robot will also remove the source +branch from the user's fork if the corresponding MR option was checked. + +The robot automatically constructs a merge commit message of the following +form:: + + Merge topic 'mr-topic-branch-name' + + 00000000 commit message subject line (one line per commit) + + Acked-by: Kitware Robot <kwrobot@kitware.com> + Merge-request: !0000 + +Mention of the commit short sha1s and MR number helps GitLab link the +commits back to the merge request and indicates when they were merged. +The ``Acked-by:`` trailer shown indicates that `Robot Review`_ passed. +Additional ``Acked-by:``, ``Reviewed-by:``, and similar trailers may be +collected from `Human Review`_ comments that have been made since the +last time the MR topic branch was updated with a push. + +The ``Do: merge`` command accepts the following arguments: + +* ``-t <topic>``: substitute ``<topic>`` for the name of the MR topic + branch in the constructed merge commit message. + +Additionally, ``Do: merge`` extracts configuration from trailing lines +in the MR description: + +* ``Topic-rename: <topic>``: substitute ``<topic>`` for the name of + the MR topic branch in the constructed merge commit message. + The ``-t`` option overrides this. + +.. _`CMake GitLab Project Masters`: https://gitlab.kitware.com/cmake/cmake/settings/members + +Close +----- + +If review has concluded that the MR should not be integrated then it +may be closed through GitLab. + +Expire +------ + +If progress on a MR has stalled for a while, it may be closed with a +``workflow:expired`` label and a comment indicating that the MR has +been closed due to inactivity. + +Contributors are welcome to re-open an expired MR when they are ready +to continue work. Please re-open *before* pushing an update to the +MR topic branch to ensure GitLab will still act on the association. diff --git a/Help/dev/testing.rst b/Help/dev/testing.rst new file mode 100644 index 0000000..731930c --- /dev/null +++ b/Help/dev/testing.rst @@ -0,0 +1,42 @@ +CMake Testing Process +********************* + +The following documents the process for running integration testing builds. +See documentation on `CMake Development`_ for more information. + +.. _`CMake Development`: README.rst + +CMake Dashboard Scripts +======================= + +The *integration testing* step of the `CMake Review Process`_ uses a set of +testing machines that follow an integration branch on their own schedule to +drive testing and submit results to the `CMake CDash Page`_. Anyone is +welcome to provide testing machines in order to help keep support for their +platforms working. + +The `CMake Dashboard Scripts Repository`_ provides CTest scripts to drive +nightly, continous, and experimental testing of CMake. Use the following +commands to set up a new integration testing client: + +.. code-block:: console + + $ mkdir -p ~/Dashboards + $ cd ~/Dashboards + $ git clone https://gitlab.kitware.com/cmake/dashboard-scripts.git CMakeScripts + $ cd CMakeScripts + +The ``cmake_common.cmake`` script contains comments at the top with +instructions to set up a testing client. As it instructs, create a +CTest script with local settings and include ``cmake_common.cmake``. + +.. _`CMake Review Process`: review.rst +.. _`CMake CDash Page`: https://open.cdash.org/index.php?project=CMake +.. _`CMake Dashboard Scripts Repository`: https://gitlab.kitware.com/cmake/dashboard-scripts + +Nightly Start Time +------------------ + +The ``cmake_common.cmake`` script expects its includer to be run from a +nightly scheduled task (cron job). Schedule such tasks for sometime after +``1:00am UTC``, the time at which our nightly testing branches fast-forward. diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt index 58e9223..5d13e77 100644 --- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt +++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt @@ -2,9 +2,5 @@ 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 ``host=x64`` to the toolset specification: - -``host=x64`` - Select the 64-bit variant of the default toolset. -``<toolset>,host=x64`` - Select the 64-bit variant of the ``<toolset>`` toolset. +64-bit host tools by adding a ``host=x64`` option to the toolset specification. +See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt index 9b3f717..e8b87c9 100644 --- a/Help/manual/OPTIONS_BUILD.txt +++ b/Help/manual/OPTIONS_BUILD.txt @@ -48,31 +48,19 @@ build system. Possible generator names are specified in the :manual:`cmake-generators(7)` manual. -``-T <toolset-name>`` - Specify toolset name if supported by generator. +``-T <toolset-spec>`` + Toolset specification for the generator, if supported. - Some CMake generators support a toolset name to be given to the - native build system to choose a compiler. - See the :variable:`CMAKE_GENERATOR_TOOLSET` variable. - This is supported only on specific generators: - - * :ref:`Visual Studio Generators` for VS 2010 and above - * The :generator:`Xcode` generator for Xcode 3.0 and above - - See native build system documentation for allowed toolset names. + Some CMake generators support a toolset specification to tell + the native build system how to choose a compiler. See the + :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. ``-A <platform-name>`` Specify platform name if supported by generator. Some CMake generators support a platform name to be given to the native build system to choose a compiler or SDK. See the - :variable:`CMAKE_GENERATOR_PLATFORM` variable. - This is supported only on specific generators: - - * For :ref:`Visual Studio Generators` with VS 2005 and above this - specifies the target architecture. - - See native build system documentation for allowed platform names. + :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. ``-Wno-dev`` Suppress developer warnings. diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst index d0c2986..611c989 100644 --- a/Help/manual/cmake-commands.7.rst +++ b/Help/manual/cmake-commands.7.rst @@ -7,91 +7,103 @@ cmake-commands(7) .. contents:: -Normal Commands -=============== +Scripting Commands +================== -These commands may be used freely in CMake projects. +These commands are always available. .. toctree:: :maxdepth: 1 - /command/add_compile_options - /command/add_custom_command - /command/add_custom_target - /command/add_definitions - /command/add_dependencies - /command/add_executable - /command/add_library - /command/add_subdirectory - /command/add_test - /command/aux_source_directory /command/break - /command/build_command /command/cmake_host_system_information /command/cmake_minimum_required /command/cmake_parse_arguments /command/cmake_policy /command/configure_file /command/continue - /command/create_test_sourcelist - /command/define_property /command/elseif /command/else - /command/enable_language - /command/enable_testing /command/endforeach /command/endfunction /command/endif /command/endmacro /command/endwhile /command/execute_process - /command/export /command/file /command/find_file /command/find_library /command/find_package /command/find_path /command/find_program - /command/fltk_wrap_ui /command/foreach /command/function /command/get_cmake_property /command/get_directory_property /command/get_filename_component /command/get_property + /command/if + /command/include + /command/list + /command/macro + /command/mark_as_advanced + /command/math + /command/message + /command/option + /command/return + /command/separate_arguments + /command/set_directory_properties + /command/set_property + /command/set + /command/site_name + /command/string + /command/unset + /command/variable_watch + /command/while + +Project Commands +================ + +These commands are available only in CMake projects. + +.. toctree:: + :maxdepth: 1 + + /command/add_compile_options + /command/add_custom_command + /command/add_custom_target + /command/add_definitions + /command/add_dependencies + /command/add_executable + /command/add_library + /command/add_subdirectory + /command/add_test + /command/aux_source_directory + /command/build_command + /command/create_test_sourcelist + /command/define_property + /command/enable_language + /command/enable_testing + /command/export + /command/fltk_wrap_ui /command/get_source_file_property /command/get_target_property /command/get_test_property - /command/if /command/include_directories /command/include_external_msproject /command/include_regular_expression - /command/include /command/install /command/link_directories /command/link_libraries - /command/list /command/load_cache - /command/macro - /command/mark_as_advanced - /command/math - /command/message - /command/option /command/project /command/qt_wrap_cpp /command/qt_wrap_ui /command/remove_definitions - /command/return - /command/separate_arguments - /command/set_directory_properties - /command/set_property - /command/set /command/set_source_files_properties /command/set_target_properties /command/set_tests_properties - /command/site_name /command/source_group - /command/string /command/target_compile_definitions /command/target_compile_features /command/target_compile_options @@ -100,9 +112,30 @@ These commands may be used freely in CMake projects. /command/target_sources /command/try_compile /command/try_run - /command/unset - /command/variable_watch - /command/while + +.. _`CTest Commands`: + +CTest Commands +============== + +These commands are available only in CTest scripts. + +.. toctree:: + :maxdepth: 1 + + /command/ctest_build + /command/ctest_configure + /command/ctest_coverage + /command/ctest_empty_binary_directory + /command/ctest_memcheck + /command/ctest_read_custom_files + /command/ctest_run_script + /command/ctest_sleep + /command/ctest_start + /command/ctest_submit + /command/ctest_test + /command/ctest_update + /command/ctest_upload Deprecated Commands =================== @@ -129,27 +162,3 @@ versions of CMake. Do not use them in new code. /command/utility_source /command/variable_requires /command/write_file - -.. _`CTest Commands`: - -CTest Commands -============== - -These commands are available only in ctest scripts. - -.. toctree:: - :maxdepth: 1 - - /command/ctest_build - /command/ctest_configure - /command/ctest_coverage - /command/ctest_empty_binary_directory - /command/ctest_memcheck - /command/ctest_read_custom_files - /command/ctest_run_script - /command/ctest_sleep - /command/ctest_start - /command/ctest_submit - /command/ctest_test - /command/ctest_update - /command/ctest_upload diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 3a225ad..3eac45f 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -117,7 +117,7 @@ Available logical expressions are: .. code-block:: cmake add_library(myapp_c foo.c) - add_library(myapp_cxx foo.c) + add_library(myapp_cxx bar.cpp) target_compile_options(myapp_cxx PUBLIC -fno-exceptions) add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) @@ -205,6 +205,15 @@ Available informational expressions are: Name of the linker generated program database file (.pdb). ``$<TARGET_PDB_FILE_DIR:tgt>`` Directory of the linker generated program database file (.pdb). +``$<TARGET_BUNDLE_DIR:tgt>`` + Full path to the bundle directory (``my.app``, ``my.framework``, or + ``my.bundle``) where ``tgt`` is the name of a target. +``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` + Full path to the bundle content directory where ``tgt`` is the name of a + target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, + or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to + ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle + structure. ``$<TARGET_PROPERTY:tgt,prop>`` Value of the property ``prop`` on the target ``tgt``. diff --git a/Help/manual/cmake-modules.7.rst b/Help/manual/cmake-modules.7.rst index c478a1b..1e8342c 100644 --- a/Help/manual/cmake-modules.7.rst +++ b/Help/manual/cmake-modules.7.rst @@ -27,6 +27,7 @@ All Modules /module/CheckFortranFunctionExists /module/CheckFortranSourceCompiles /module/CheckFunctionExists + /module/CheckIPOSupported /module/CheckIncludeFileCXX /module/CheckIncludeFile /module/CheckIncludeFiles @@ -229,6 +230,7 @@ All Modules /module/GenerateExportHeader /module/GetPrerequisites /module/GNUInstallDirs + /module/GoogleTest /module/InstallRequiredSystemLibraries /module/MacroAddFileDependencies /module/ProcessorCount diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst index 3266958..7b85817 100644 --- a/Help/manual/cmake-policies.7.rst +++ b/Help/manual/cmake-policies.7.rst @@ -51,6 +51,15 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used to determine whether to report an error on use of deprecated macros or functions. +Policies Introduced by CMake 3.9 +================================ + +.. toctree:: + :maxdepth: 1 + + CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled. </policy/CMP0069> + CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068> + Policies Introduced by CMake 3.8 ================================ diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 0e3eb86..27c75dc 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -16,8 +16,11 @@ Properties of Global Scope :maxdepth: 1 /prop_gbl/ALLOW_DUPLICATE_CUSTOM_TARGETS + /prop_gbl/AUTOGEN_SOURCE_GROUP /prop_gbl/AUTOGEN_TARGETS_FOLDER + /prop_gbl/AUTOMOC_SOURCE_GROUP /prop_gbl/AUTOMOC_TARGETS_FOLDER + /prop_gbl/AUTORCC_SOURCE_GROUP /prop_gbl/CMAKE_C_KNOWN_FEATURES /prop_gbl/CMAKE_CXX_KNOWN_FEATURES /prop_gbl/DEBUG_CONFIGURATIONS @@ -26,7 +29,9 @@ Properties of Global Scope /prop_gbl/ENABLED_LANGUAGES /prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS /prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS + /prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS /prop_gbl/FIND_LIBRARY_USE_OPENBSD_VERSIONING + /prop_gbl/GENERATOR_IS_MULTI_CONFIG /prop_gbl/GLOBAL_DEPENDS_DEBUG_MODE /prop_gbl/GLOBAL_DEPENDS_NO_CYCLES /prop_gbl/IN_TRY_COMPILE @@ -115,14 +120,17 @@ Properties on Targets /prop_tgt/ARCHIVE_OUTPUT_NAME_CONFIG /prop_tgt/ARCHIVE_OUTPUT_NAME /prop_tgt/AUTOGEN_TARGET_DEPENDS + /prop_tgt/AUTOMOC_DEPEND_FILTERS /prop_tgt/AUTOMOC_MOC_OPTIONS /prop_tgt/AUTOMOC /prop_tgt/AUTOUIC /prop_tgt/AUTOUIC_OPTIONS + /prop_tgt/AUTOUIC_SEARCH_PATHS /prop_tgt/AUTORCC /prop_tgt/AUTORCC_OPTIONS /prop_tgt/BINARY_DIR /prop_tgt/BUILD_RPATH + /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR /prop_tgt/BUILD_WITH_INSTALL_RPATH /prop_tgt/BUNDLE_EXTENSION /prop_tgt/BUNDLE @@ -318,6 +326,7 @@ Properties on Tests /prop_test/ATTACHED_FILES /prop_test/COST /prop_test/DEPENDS + /prop_test/DISABLED /prop_test/ENVIRONMENT /prop_test/FAIL_REGULAR_EXPRESSION /prop_test/FIXTURES_CLEANUP diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst index 56d4ca7..3b95b05 100644 --- a/Help/manual/cmake-qt.7.rst +++ b/Help/manual/cmake-qt.7.rst @@ -63,26 +63,33 @@ If a ``Q_OBJECT`` or ``Q_GADGET`` macro is found in a header file, ``moc`` will be run on the file. The result will be put into a file named according to ``moc_<basename>.cpp``. If the macro is found in a C++ implementation file, the moc output will be put into a file named according to -``<basename>.moc``, following the Qt conventions. The ``moc file`` may be -included by the user in the C++ implementation file with a preprocessor -``#include``. If it is not so included, it will be added to a separate file -which is compiled into the target. +``<basename>.moc``, following the Qt conventions. The ``<basename>.moc`` must +be included by the user in the C++ implementation file with a preprocessor +``#include``. -The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and -:prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being -invoked for, and for the appropriate build configuration. - -The generated ``moc_*.cpp`` and ``*.moc`` files are placed in the +Included ``moc_*.cpp`` and ``*.moc`` files will be generated in the ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. (This differs from CMake 3.7 and below; see their documentation for details.) +Not included ``moc_<basename>.cpp`` files will be generated in custom +folders to avoid name collisions and included in a separate +``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/moc_compilation.cpp`` +file which is compiled into the target. + +The ``moc`` command line will consume the :prop_tgt:`COMPILE_DEFINITIONS` and +:prop_tgt:`INCLUDE_DIRECTORIES` target properties from the target it is being +invoked for, and for the appropriate build configuration. + The :prop_tgt:`AUTOMOC` target property may be pre-set for all following targets by setting the :variable:`CMAKE_AUTOMOC` variable. The :prop_tgt:`AUTOMOC_MOC_OPTIONS` target property may be populated to set options to pass to ``moc``. The :variable:`CMAKE_AUTOMOC_MOC_OPTIONS` variable may be populated to pre-set the options for all following targets. +Additional ``moc`` dependency file names can be extracted from source code +by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. + Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. @@ -97,7 +104,9 @@ be run, and to create rules to execute ``uic`` at the appropriate time. If a preprocessor ``#include`` directive is found which matches ``ui_<basename>.h``, and a ``<basename>.ui`` file exists, then ``uic`` will -be executed to generate the appropriate file. +be executed to generate the appropriate file. The ``<basename>.ui`` file is +searched for first in the vicinity of including file and afterwards in the +optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. The generated generated ``ui_*.h`` files are placed in the ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory which is diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 38444d1..c45574f 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -13,9 +13,9 @@ Variables that Provide Information .. toctree:: :maxdepth: 1 + /variable/CMAKE_AR /variable/CMAKE_ARGC /variable/CMAKE_ARGV0 - /variable/CMAKE_AR /variable/CMAKE_BINARY_DIR /variable/CMAKE_BUILD_TOOL /variable/CMAKE_CACHEFILE_DIR @@ -48,6 +48,8 @@ Variables that Provide Information /variable/CMAKE_IMPORT_LIBRARY_SUFFIX /variable/CMAKE_JOB_POOL_COMPILE /variable/CMAKE_JOB_POOL_LINK + /variable/CMAKE_LANG_COMPILER_AR + /variable/CMAKE_LANG_COMPILER_RANLIB /variable/CMAKE_LINK_LIBRARY_SUFFIX /variable/CMAKE_LINK_SEARCH_END_STATIC /variable/CMAKE_LINK_SEARCH_START_STATIC @@ -82,18 +84,20 @@ Variables that Provide Information /variable/CMAKE_VS_NsightTegra_VERSION /variable/CMAKE_VS_PLATFORM_NAME /variable/CMAKE_VS_PLATFORM_TOOLSET + /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION + /variable/CMAKE_XCODE_GENERATE_SCHEME /variable/CMAKE_XCODE_PLATFORM_TOOLSET - /variable/PROJECT_BINARY_DIR /variable/PROJECT-NAME_BINARY_DIR - /variable/PROJECT_NAME /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR /variable/PROJECT-NAME_VERSION_MINOR /variable/PROJECT-NAME_VERSION_PATCH /variable/PROJECT-NAME_VERSION_TWEAK + /variable/PROJECT_BINARY_DIR + /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION /variable/PROJECT_VERSION_MAJOR @@ -127,9 +131,9 @@ Variables that Change Behavior /variable/CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION /variable/CMAKE_EXPORT_COMPILE_COMMANDS /variable/CMAKE_EXPORT_NO_PACKAGE_REGISTRY - /variable/CMAKE_SYSROOT /variable/CMAKE_FIND_APPBUNDLE /variable/CMAKE_FIND_FRAMEWORK + /variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX /variable/CMAKE_FIND_LIBRARY_PREFIXES /variable/CMAKE_FIND_LIBRARY_SUFFIXES /variable/CMAKE_FIND_NO_INSTALL_PREFIX @@ -143,9 +147,9 @@ Variables that Change Behavior /variable/CMAKE_FIND_ROOT_PATH_MODE_PROGRAM /variable/CMAKE_FRAMEWORK_PATH /variable/CMAKE_IGNORE_PATH - /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INCLUDE_DIRECTORIES_BEFORE /variable/CMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE + /variable/CMAKE_INCLUDE_PATH /variable/CMAKE_INSTALL_DEFAULT_COMPONENT_NAME /variable/CMAKE_INSTALL_MESSAGE /variable/CMAKE_INSTALL_PREFIX @@ -163,6 +167,7 @@ Variables that Change Behavior /variable/CMAKE_STAGING_PREFIX /variable/CMAKE_SUBLIME_TEXT_2_ENV_SETTINGS /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE + /variable/CMAKE_SYSROOT /variable/CMAKE_SYSTEM_APPBUNDLE_PATH /variable/CMAKE_SYSTEM_FRAMEWORK_PATH /variable/CMAKE_SYSTEM_IGNORE_PATH @@ -187,23 +192,24 @@ Variables that Describe the System /variable/CMAKE_COMPILER_2005 /variable/CMAKE_HOST_APPLE /variable/CMAKE_HOST_SOLARIS + /variable/CMAKE_HOST_SYSTEM /variable/CMAKE_HOST_SYSTEM_NAME /variable/CMAKE_HOST_SYSTEM_PROCESSOR - /variable/CMAKE_HOST_SYSTEM /variable/CMAKE_HOST_SYSTEM_VERSION /variable/CMAKE_HOST_UNIX /variable/CMAKE_HOST_WIN32 - /variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX /variable/CMAKE_LIBRARY_ARCHITECTURE + /variable/CMAKE_LIBRARY_ARCHITECTURE_REGEX /variable/CMAKE_OBJECT_PATH_MAX + /variable/CMAKE_SYSTEM /variable/CMAKE_SYSTEM_NAME /variable/CMAKE_SYSTEM_PROCESSOR - /variable/CMAKE_SYSTEM /variable/CMAKE_SYSTEM_VERSION /variable/CYGWIN /variable/ENV /variable/GHS-MULTI /variable/MINGW + /variable/MSVC /variable/MSVC10 /variable/MSVC11 /variable/MSVC12 @@ -214,7 +220,6 @@ Variables that Describe the System /variable/MSVC80 /variable/MSVC90 /variable/MSVC_IDE - /variable/MSVC /variable/MSVC_VERSION /variable/UNIX /variable/WIN32 @@ -256,31 +261,35 @@ Variables that Control the Build /variable/CMAKE_ANDROID_STL_TYPE /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY /variable/CMAKE_ARCHIVE_OUTPUT_DIRECTORY_CONFIG - /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTOMOC + /variable/CMAKE_AUTOMOC_DEPEND_FILTERS + /variable/CMAKE_AUTOMOC_MOC_OPTIONS /variable/CMAKE_AUTORCC /variable/CMAKE_AUTORCC_OPTIONS /variable/CMAKE_AUTOUIC /variable/CMAKE_AUTOUIC_OPTIONS + /variable/CMAKE_AUTOUIC_SEARCH_PATHS /variable/CMAKE_BUILD_RPATH + /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR /variable/CMAKE_BUILD_WITH_INSTALL_RPATH /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG /variable/CMAKE_CONFIG_POSTFIX /variable/CMAKE_DEBUG_POSTFIX /variable/CMAKE_ENABLE_EXPORTS + /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG /variable/CMAKE_EXE_LINKER_FLAGS_CONFIG_INIT - /variable/CMAKE_EXE_LINKER_FLAGS /variable/CMAKE_EXE_LINKER_FLAGS_INIT /variable/CMAKE_Fortran_FORMAT /variable/CMAKE_Fortran_MODULE_DIRECTORY /variable/CMAKE_GNUtoMS - /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE /variable/CMAKE_INCLUDE_CURRENT_DIR + /variable/CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE /variable/CMAKE_INSTALL_NAME_DIR /variable/CMAKE_INSTALL_RPATH /variable/CMAKE_INSTALL_RPATH_USE_LINK_PATH + /variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION /variable/CMAKE_IOS_INSTALL_COMBINED /variable/CMAKE_LANG_CLANG_TIDY /variable/CMAKE_LANG_COMPILER_LAUNCHER @@ -299,9 +308,9 @@ Variables that Control the Build /variable/CMAKE_MACOSX_BUNDLE /variable/CMAKE_MACOSX_RPATH /variable/CMAKE_MAP_IMPORTED_CONFIG_CONFIG + /variable/CMAKE_MODULE_LINKER_FLAGS /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG /variable/CMAKE_MODULE_LINKER_FLAGS_CONFIG_INIT - /variable/CMAKE_MODULE_LINKER_FLAGS /variable/CMAKE_MODULE_LINKER_FLAGS_INIT /variable/CMAKE_NINJA_OUTPUT_PATH_PREFIX /variable/CMAKE_NO_BUILTIN_CHRPATH @@ -314,15 +323,15 @@ Variables that Control the Build /variable/CMAKE_POSITION_INDEPENDENT_CODE /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY /variable/CMAKE_RUNTIME_OUTPUT_DIRECTORY_CONFIG + /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG /variable/CMAKE_SHARED_LINKER_FLAGS_CONFIG_INIT - /variable/CMAKE_SHARED_LINKER_FLAGS /variable/CMAKE_SHARED_LINKER_FLAGS_INIT /variable/CMAKE_SKIP_BUILD_RPATH /variable/CMAKE_SKIP_INSTALL_RPATH + /variable/CMAKE_STATIC_LINKER_FLAGS /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG /variable/CMAKE_STATIC_LINKER_FLAGS_CONFIG_INIT - /variable/CMAKE_STATIC_LINKER_FLAGS /variable/CMAKE_STATIC_LINKER_FLAGS_INIT /variable/CMAKE_TRY_COMPILE_CONFIGURATION /variable/CMAKE_TRY_COMPILE_PLATFORM_VARIABLES @@ -331,8 +340,8 @@ Variables that Control the Build /variable/CMAKE_VISIBILITY_INLINES_HIDDEN /variable/CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD /variable/CMAKE_VS_INCLUDE_PACKAGE_TO_DEFAULT_BUILD - /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_WIN32_EXECUTABLE + /variable/CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS /variable/CMAKE_XCODE_ATTRIBUTE_an-attribute /variable/EXECUTABLE_OUTPUT_PATH /variable/LIBRARY_OUTPUT_PATH @@ -346,10 +355,6 @@ Variables for Languages /variable/CMAKE_COMPILER_IS_GNUCC /variable/CMAKE_COMPILER_IS_GNUCXX /variable/CMAKE_COMPILER_IS_GNUG77 - /variable/CMAKE_C_COMPILE_FEATURES - /variable/CMAKE_C_EXTENSIONS - /variable/CMAKE_C_STANDARD - /variable/CMAKE_C_STANDARD_REQUIRED /variable/CMAKE_CUDA_EXTENSIONS /variable/CMAKE_CUDA_STANDARD /variable/CMAKE_CUDA_STANDARD_REQUIRED @@ -358,6 +363,10 @@ Variables for Languages /variable/CMAKE_CXX_EXTENSIONS /variable/CMAKE_CXX_STANDARD /variable/CMAKE_CXX_STANDARD_REQUIRED + /variable/CMAKE_C_COMPILE_FEATURES + /variable/CMAKE_C_EXTENSIONS + /variable/CMAKE_C_STANDARD + /variable/CMAKE_C_STANDARD_REQUIRED /variable/CMAKE_Fortran_MODDIR_DEFAULT /variable/CMAKE_Fortran_MODDIR_FLAG /variable/CMAKE_Fortran_MODOUT_FLAG @@ -368,27 +377,27 @@ Variables for Languages /variable/CMAKE_LANG_ARCHIVE_APPEND /variable/CMAKE_LANG_ARCHIVE_CREATE /variable/CMAKE_LANG_ARCHIVE_FINISH - /variable/CMAKE_LANG_COMPILE_OBJECT + /variable/CMAKE_LANG_COMPILER /variable/CMAKE_LANG_COMPILER_ABI + /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_ID /variable/CMAKE_LANG_COMPILER_LOADED - /variable/CMAKE_LANG_COMPILER - /variable/CMAKE_LANG_COMPILER_EXTERNAL_TOOLCHAIN /variable/CMAKE_LANG_COMPILER_TARGET /variable/CMAKE_LANG_COMPILER_VERSION + /variable/CMAKE_LANG_COMPILE_OBJECT /variable/CMAKE_LANG_CREATE_SHARED_LIBRARY /variable/CMAKE_LANG_CREATE_SHARED_MODULE /variable/CMAKE_LANG_CREATE_STATIC_LIBRARY + /variable/CMAKE_LANG_FLAGS /variable/CMAKE_LANG_FLAGS_DEBUG /variable/CMAKE_LANG_FLAGS_DEBUG_INIT + /variable/CMAKE_LANG_FLAGS_INIT /variable/CMAKE_LANG_FLAGS_MINSIZEREL /variable/CMAKE_LANG_FLAGS_MINSIZEREL_INIT /variable/CMAKE_LANG_FLAGS_RELEASE /variable/CMAKE_LANG_FLAGS_RELEASE_INIT /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO /variable/CMAKE_LANG_FLAGS_RELWITHDEBINFO_INIT - /variable/CMAKE_LANG_FLAGS - /variable/CMAKE_LANG_FLAGS_INIT /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_DEBUG /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_MINSIZEREL /variable/CMAKE_LANG_GHS_KERNEL_FLAGS_RELEASE @@ -399,8 +408,8 @@ Variables for Languages /variable/CMAKE_LANG_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES /variable/CMAKE_LANG_IMPLICIT_LINK_LIBRARIES /variable/CMAKE_LANG_LIBRARY_ARCHITECTURE - /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_LINKER_PREFERENCE + /variable/CMAKE_LANG_LINKER_PREFERENCE_PROPAGATES /variable/CMAKE_LANG_LINK_EXECUTABLE /variable/CMAKE_LANG_OUTPUT_EXTENSION /variable/CMAKE_LANG_PLATFORM_ID diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 063aea1..b2e2828 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -263,8 +263,10 @@ Available commands are: 052f86c15bbde68af55c7f7b340ab639 file2.txt ``remove [-f] <file>...`` - Remove the file(s), use ``-f`` to force it. If a file does - not exist it will be silently ignored. + Remove the file(s). If any of the listed files already do not + exist, the command returns a non-zero exit code, but no message + is logged. The ``-f`` option changes the behavior to return a + zero exit code (i.e. success) in such situations instead. ``remove_directory <dir>`` Remove a directory and its contents. If a directory does @@ -315,6 +317,9 @@ The following ``cmake -E`` commands are available only on UNIX: ``create_symlink <old> <new>`` Create a symbolic link ``<new>`` naming ``<old>``. +.. note:: + Path to where ``<new>`` symbolic link will be created has to exist beforehand. + Windows-specific Command-Line Tools ----------------------------------- diff --git a/Help/module/CheckIPOSupported.rst b/Help/module/CheckIPOSupported.rst new file mode 100644 index 0000000..9c8a77b --- /dev/null +++ b/Help/module/CheckIPOSupported.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/CheckIPOSupported.cmake diff --git a/Help/module/GoogleTest.rst b/Help/module/GoogleTest.rst new file mode 100644 index 0000000..3d4cc97 --- /dev/null +++ b/Help/module/GoogleTest.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../Modules/GoogleTest.cmake diff --git a/Help/policy/CMP0068.rst b/Help/policy/CMP0068.rst new file mode 100644 index 0000000..978a6e3 --- /dev/null +++ b/Help/policy/CMP0068.rst @@ -0,0 +1,35 @@ +CMP0068 +------- + +``RPATH`` settings on macOS do not affect ``install_name``. + +CMake 3.9 and newer remove any effect the following settings may have on the +``install_name`` of a target on macOS: + +* :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property +* :prop_tgt:`SKIP_BUILD_RPATH` target property +* :variable:`CMAKE_SKIP_RPATH` variable +* :variable:`CMAKE_SKIP_INSTALL_RPATH` variable + +Previously, setting :prop_tgt:`BUILD_WITH_INSTALL_RPATH` had the effect of +setting both the ``install_name`` of a target to :prop_tgt:`INSTALL_NAME_DIR` +and the ``RPATH`` to :prop_tgt:`INSTALL_RPATH`. In CMake 3.9, it only affects +setting of ``RPATH``. However, if one wants :prop_tgt:`INSTALL_NAME_DIR` to +apply to the target in the build tree, one may set +:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`. + +If :prop_tgt:`SKIP_BUILD_RPATH`, :variable:`CMAKE_SKIP_RPATH` or +:variable:`CMAKE_SKIP_INSTALL_RPATH` were used to strip the directory portion +of the ``install_name`` of a target, one may set ``INSTALL_NAME_DIR=""`` +instead. + +The ``OLD`` behavior of this policy is to use the ``RPATH`` settings for +``install_name`` on macOS. The ``NEW`` behavior of this policy is to ignore +the ``RPATH`` settings for ``install_name`` on macOS. + +This policy was introduced in CMake version 3.9. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0069.rst b/Help/policy/CMP0069.rst new file mode 100644 index 0000000..b8f5d80 --- /dev/null +++ b/Help/policy/CMP0069.rst @@ -0,0 +1,92 @@ +CMP0069 +------- + +:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` is enforced when enabled. + +CMake 3.9 and newer prefer to add IPO flags whenever the +:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is enabled and +produce an error if flags are not known to CMake for the current compiler. +Since a given compiler may not support IPO flags in all environments in which +it is used, it is now the project's responsibility to use the +:module:`CheckIPOSupported` module to check for support before enabling the +:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property. This approach +allows a project to conditionally activate IPO when supported. It also +allows an end user to set the :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` +variable in an environment known to support IPO even if the project does +not enable the property. + +Since CMake 3.8 and lower only honored :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` +for the Intel compiler on Linux, some projects may unconditionally enable the +target property. Policy ``CMP0069`` provides compatibility with such projects. + +This policy takes effect whenever the IPO property is enabled. The ``OLD`` +behavior for this policy is to add IPO flags only for Intel compiler on Linux. +The ``NEW`` behavior for this policy is to add IPO flags for the current +compiler or produce an error if CMake does not know the flags. + +This policy was introduced in CMake version 3.9. CMake version +|release| warns when the policy is not set and uses ``OLD`` behavior. +Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` +explicitly. + +.. include:: DEPRECATED.txt + +Examples +^^^^^^^^ + +Behave like CMake 3.8 and do not apply any IPO flags except for Intel compiler +on Linux: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.8) + project(foo) + + # ... + + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) + +Use the :module:`CheckIPOSupported` module to detect whether IPO is +supported by the current compiler, environment, and CMake version. +Produce a fatal error if support is not available: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.9) # CMP0069 NEW + project(foo) + + include(CheckIPOSupport) + check_ipo_support() + + # ... + + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) + +Apply IPO flags only if compiler supports it: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.9) # CMP0069 NEW + project(foo) + + include(CheckIPOSupport) + + # ... + + check_ipo_support(RESULT result) + if(result) + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) + endif() + +Apply IPO flags without any checks. This may lead to build errors if IPO +is not supported by the compiler in the current environment. Produce an +error if CMake does not know IPO flags for the current compiler: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.9) # CMP0069 NEW + project(foo) + + # ... + + set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) diff --git a/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst new file mode 100644 index 0000000..d294eb1 --- /dev/null +++ b/Help/prop_gbl/AUTOGEN_SOURCE_GROUP.rst @@ -0,0 +1,15 @@ +AUTOGEN_SOURCE_GROUP +-------------------- + +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` and +:prop_tgt:`AUTORCC` generated files. + +Files generated by :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` are not always +known at configure time and therefore can't be passed to +:command:`source_group`. +:prop_gbl:`AUTOGEN_SOURCE_GROUP` an be used instead to generate or select +a source group for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` generated files. + +For :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTORCC` specific overrides see +:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` +respectively. diff --git a/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst index fae5626..0b747b2 100644 --- a/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst +++ b/Help/prop_gbl/AUTOGEN_TARGETS_FOLDER.rst @@ -1,8 +1,8 @@ AUTOGEN_TARGETS_FOLDER ---------------------- -Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added automatically by -CMake for targets for which :prop_tgt:`AUTOMOC` is enabled. +Name of :prop_tgt:`FOLDER` for ``*_autogen`` targets that are added +automatically by CMake for targets for which :prop_tgt:`AUTOMOC` is enabled. If not set, CMake uses the :prop_tgt:`FOLDER` property of the parent target as a default value for this property. See also the documentation for the diff --git a/Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst new file mode 100644 index 0000000..2455dc7 --- /dev/null +++ b/Help/prop_gbl/AUTOMOC_SOURCE_GROUP.rst @@ -0,0 +1,7 @@ +AUTOMOC_SOURCE_GROUP +-------------------- + +Name of the :command:`source_group` for :prop_tgt:`AUTOMOC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTOMOC`. diff --git a/Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst b/Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst new file mode 100644 index 0000000..65ea95b --- /dev/null +++ b/Help/prop_gbl/AUTORCC_SOURCE_GROUP.rst @@ -0,0 +1,7 @@ +AUTORCC_SOURCE_GROUP +-------------------- + +Name of the :command:`source_group` for :prop_tgt:`AUTORCC` generated files. + +When set this is used instead of :prop_gbl:`AUTOGEN_SOURCE_GROUP` for +files generated by :prop_tgt:`AUTORCC`. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst index ce18b65..8396026 100644 --- a/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB32_PATHS.rst @@ -8,3 +8,5 @@ Whether the :command:`find_library` command should automatically search :command:`find_library` command should automatically search the ``lib32`` variant of directories called ``lib`` in the search path when building 32-bit binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst index e52f8eb..ed343ba 100644 --- a/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIB64_PATHS.rst @@ -8,3 +8,5 @@ FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the :command:`find_library` command should automatically search the lib64 variant of directories called lib in the search path when building 64-bit binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst b/Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst new file mode 100644 index 0000000..b87b09b --- /dev/null +++ b/Help/prop_gbl/FIND_LIBRARY_USE_LIBX32_PATHS.rst @@ -0,0 +1,12 @@ +FIND_LIBRARY_USE_LIBX32_PATHS +----------------------------- + +Whether the :command:`find_library` command should automatically search +``libx32`` directories. + +``FIND_LIBRARY_USE_LIBX32_PATHS`` is a boolean specifying whether the +:command:`find_library` command should automatically search the ``libx32`` +variant of directories called ``lib`` in the search path when building +x32-abi binaries. + +See also the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable. diff --git a/Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst b/Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst new file mode 100644 index 0000000..b8ec8a6 --- /dev/null +++ b/Help/prop_gbl/GENERATOR_IS_MULTI_CONFIG.rst @@ -0,0 +1,9 @@ +GENERATOR_IS_MULTI_CONFIG +------------------------- + +Read-only property that is true on multi-configuration generators. + +True when using a multi-configuration generator +(such as :ref:`Visual Studio Generators` or :generator:`Xcode`). +Multi-config generators use :variable:`CMAKE_CONFIGURATION_TYPES` +as the set of configurations and ignore :variable:`CMAKE_BUILD_TYPE`. diff --git a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst index 69cdcb7..a064afa 100644 --- a/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst +++ b/Help/prop_sf/MACOSX_PACKAGE_LOCATION.rst @@ -21,3 +21,10 @@ extension is changed). See the :prop_tgt:`PUBLIC_HEADER`, :prop_tgt:`PRIVATE_HEADER`, and :prop_tgt:`RESOURCE` target properties for specifying files meant for ``Headers``, ``PrivateHeaders``, or ``Resources`` directories. + +If the specified location is equal to ``Resources``, the resulting location +will be the same as if the :prop_tgt:`RESOURCE` property had been used. If +the specified location is a sub-folder of ``Resources``, it will be placed +into the respective sub-folder. Note: For iOS Apple uses a flat bundle layout +where no ``Resources`` folder exist. Therefore CMake strips the ``Resources`` +folder name from the specified location. diff --git a/Help/prop_test/DISABLED.rst b/Help/prop_test/DISABLED.rst new file mode 100644 index 0000000..c18ae7f --- /dev/null +++ b/Help/prop_test/DISABLED.rst @@ -0,0 +1,15 @@ +DISABLED +-------- + +If set to true, the test will be skipped and its status will be 'Not Run'. A +DISABLED test will not be counted in the total number of tests and its +completion status will be reported to CDash as 'Disabled'. + +A DISABLED test does not participate in test fixture dependency resolution. +If a DISABLED test has fixture requirements defined in its +:prop_test:`FIXTURES_REQUIRED` property, it will not cause setup or cleanup +tests for those fixtures to be added to the test set. + +If a test with the :prop_test:`FIXTURES_SETUP` property set is DISABLED, the +fixture behavior will be as though that setup test was passing and any test +case requiring that fixture will still run. diff --git a/Help/prop_tgt/AUTOMOC.rst b/Help/prop_tgt/AUTOMOC.rst index b42643f..7e10fde 100644 --- a/Help/prop_tgt/AUTOMOC.rst +++ b/Help/prop_tgt/AUTOMOC.rst @@ -8,31 +8,41 @@ preprocessor automatically, i.e. without having to use the :module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are supported. -When this property is set ``ON``, CMake will scan the +When this property is set ``ON``, CMake will scan the header and source files at build time and invoke moc accordingly. -* If an ``#include`` statement like ``#include "moc_foo.cpp"`` is found, - the ``Q_OBJECT`` class declaration is expected in the header, and - ``moc`` is run on the header file. A ``moc_foo.cpp`` file will be - generated from the source's header into the - ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` - directory which is automatically added to the target's +* If an ``#include`` statement like ``#include "moc_<basename>.cpp"`` is found, + the ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in an otherwise empty + line of the ``<basename>.h(xx)`` header file. ``moc`` is run on the header file to + generate ``moc_<basename>.cpp`` in the + ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include`` directory + which is automatically added to the target's :prop_tgt:`INCLUDE_DIRECTORIES`. This allows the compiler to find the - included ``moc_foo.cpp`` file regardless of the location the original source. - However, if multiple source files in different directories do this then their - generated moc files would collide. In this case a diagnostic will be issued. - -* If an ``#include`` statement like ``#include "foo.moc"`` is found, - then a ``Q_OBJECT`` is expected in the current source file and ``moc`` - is run on the file itself. Additionally, header files with the same - base name (like ``foo.h``) or ``_p`` appended to the base name (like - ``foo_p.h``) are parsed for ``Q_OBJECT`` macros, and if found, ``moc`` - is also executed on those files. ``AUTOMOC`` checks multiple header - alternative extensions, such as ``hpp``, ``hxx`` etc when searching - for headers. The resulting moc files, which are not included as shown - above in any of the source files are included in a generated - ``moc_compilation.cpp`` file, which is compiled as part of the - target. + included ``moc_<basename>.cpp`` file regardless of the location the + original source. + +* If an ``#include`` statement like ``#include "<basename>.moc"`` is found, + then ``Q_OBJECT`` or ``Q_GADGET`` macros are expected in the current source + file and ``moc`` is run on the source file itself. + +* Header files that are not included by an ``#include "moc_<basename>.cpp"`` + statement are nonetheless scanned for ``Q_OBJECT`` or ``Q_GADGET`` macros. + The resulting ``moc_<basename>.cpp`` files are generated in custom + directories and automatically included in the generated + ``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/moc_compilation.cpp`` file, + which is compiled as part of the target. The custom directories help to + avoid name collisions for moc files with the same ``<basename>``. + +* Additionally, header files with the same base name as a source file, + (like ``<basename>.h``) or ``_p`` appended to the base name (like + ``<basename>_p.h``), are parsed for ``Q_OBJECT`` or ``Q_GADGET`` macros, + and if found, ``moc`` is also executed on those files. + +* ``AUTOMOC`` always checks multiple header alternative extensions, + such as ``hpp``, ``hxx``, etc. when searching for headers. + +* ``AUTOMOC`` looks for the ``Q_PLUGIN_METADATA`` macro and reruns the + ``moc`` when the file addressed by the ``FILE`` argument of the macro changes. This property is initialized by the value of the :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created. @@ -47,6 +57,12 @@ See the documentation for this variable for more details. The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the automoc targets together in an IDE, e.g. in MSVS. +The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group +files generated by :prop_tgt:`AUTOMOC` together in an IDE, e.g. in MSVS. + +Additional ``moc`` dependency file names can be extracted from source code +by using :prop_tgt:`AUTOMOC_DEPEND_FILTERS`. + Source C++ files can be excluded from :prop_tgt:`AUTOMOC` processing by enabling :prop_sf:`SKIP_AUTOMOC` or the broader :prop_sf:`SKIP_AUTOGEN`. diff --git a/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..810cbf4 --- /dev/null +++ b/Help/prop_tgt/AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,45 @@ +AUTOMOC_DEPEND_FILTERS +---------------------- + +Filter definitions used by :prop_tgt:`AUTOMOC` to extract file names from +source code as additional dependencies for the ``moc`` file. + +This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON`` +for this target. + +Filters are defined as ``KEYWORD;REGULAR_EXPRESSION`` pairs. First the file +content is searched for ``KEYWORD``. If it is found at least once, then file +names are extracted by successively searching for ``REGULAR_EXPRESSION`` and +taking the first match group. + +Consider a filter extracts the file name ``DEP`` from the content of a file +``FOO``. If ``DEP`` changes, then the ``moc`` file for ``FOO`` gets rebuilt. +The file ``DEP`` is searched for first in the vicinity +of ``FOO`` and afterwards in the target's :prop_tgt:`INCLUDE_DIRECTORIES`. + +By default :prop_tgt:`AUTOMOC_DEPEND_FILTERS` is initialized from +:variable:`CMAKE_AUTOMOC_DEPEND_FILTERS`, which is empty by default. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. + + +Example +------- + +Consider a file ``FOO.hpp`` holds a custom macro ``OBJ_JSON_FILE`` and we +want the ``moc`` file to depend on the macro`s file name argument:: + + class My_Class : public QObject + { + Q_OBJECT + OBJ_JSON_FILE ( "DEP.json" ) + ... + }; + +Then we might use :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` to +define a filter like this:: + + set(CMAKE_AUTOMOC_DEPEND_FILTERS + "OBJ_JSON_FILE" "[\n][ \t]*OBJ_JSON_FILE[ \t]*\\([ \t]*\"([^\"]+)\"" + ) diff --git a/Help/prop_tgt/AUTORCC.rst b/Help/prop_tgt/AUTORCC.rst index 1ad0895..c0f6a26 100644 --- a/Help/prop_tgt/AUTORCC.rst +++ b/Help/prop_tgt/AUTORCC.rst @@ -19,6 +19,9 @@ Additional command line options for rcc can be set via the The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the autorcc targets together in an IDE, e.g. in MSVS. +The global property :prop_gbl:`AUTOGEN_SOURCE_GROUP` can be used to group +files generated by :prop_tgt:`AUTORCC` together in an IDE, e.g. in MSVS. + When there are multiple ``.qrc`` files with the same name, CMake will generate unspecified unique names for ``rcc``. Therefore if ``Q_INIT_RESOURCE()`` or ``Q_CLEANUP_RESOURCE()`` need to be used the diff --git a/Help/prop_tgt/AUTOUIC.rst b/Help/prop_tgt/AUTOUIC.rst index fbf24c3..91d95e5 100644 --- a/Help/prop_tgt/AUTOUIC.rst +++ b/Help/prop_tgt/AUTOUIC.rst @@ -10,8 +10,13 @@ Qt4 and Qt5 are supported. When this property is ``ON``, CMake will scan the source files at build time and invoke ``uic`` accordingly. If an ``#include`` statement like -``#include "ui_foo.h"`` is found in ``foo.cpp``, a ``foo.ui`` file is -expected next to ``foo.cpp``, and ``uic`` is run on the ``foo.ui`` file. +``#include "ui_foo.h"`` is found in ``source.cpp``, a ``foo.ui`` file is +searched for first in the vicinity of ``source.cpp`` and afterwards in the +optional :prop_tgt:`AUTOUIC_SEARCH_PATHS` of the target. +``uic`` is run on the ``foo.ui`` file to generate ``ui_foo.h`` in the directory +``<CMAKE_CURRENT_BINARY_DIR>/<TARGETNAME>_autogen/include``, +which is added to the target's :prop_tgt:`INCLUDE_DIRECTORIES` automatically. + This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` variable if it is set when a target is created. diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst index dc3bee5..9fb042e 100644 --- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst +++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst @@ -1,7 +1,7 @@ AUTOUIC_OPTIONS --------------- -Additional options for uic when using :prop_tgt:`AUTOUIC` +Additional options for ``uic`` when using :prop_tgt:`AUTOUIC` This property holds additional command line options which will be used when ``uic`` is executed during the build via :prop_tgt:`AUTOUIC`, i.e. it is diff --git a/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 0000000..96d9f89 --- /dev/null +++ b/Help/prop_tgt/AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,12 @@ +AUTOUIC_SEARCH_PATHS +-------------------- + +Search path list used by :prop_tgt:`AUTOUIC` to find included +``.ui`` files. + +This property is initialized by the value of the +:variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable if it is set +when a target is created. Otherwise it is empty. + +See the :manual:`cmake-qt(7)` manual for more information on using CMake +with Qt. diff --git a/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..bbb9a24 --- /dev/null +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,13 @@ +BUILD_WITH_INSTALL_NAME_DIR +--------------------------- + +``BUILD_WITH_INSTALL_NAME_DIR`` is a boolean specifying whether the macOS +``install_name`` of a target in the build tree uses the directory given by +:prop_tgt:`INSTALL_NAME_DIR`. This setting only applies to targets on macOS. + +This property is initialized by the value of the variable +:variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` if it is set when a target is +created. + +If this property is not set and policy :policy:`CMP0068` is not ``NEW``, the +value of :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is used in its place. diff --git a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst index abcf28f..0244351 100644 --- a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst +++ b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst @@ -1,11 +1,15 @@ BUILD_WITH_INSTALL_RPATH ------------------------ -Should build tree targets have install tree rpaths. +``BUILD_WITH_INSTALL_RPATH`` is a boolean specifying whether to link the target +in the build tree with the :prop_tgt:`INSTALL_RPATH`. This takes precedence +over :prop_tgt:`SKIP_BUILD_RPATH` and avoids the need for relinking before +installation. -BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the -target in the build tree with the INSTALL_RPATH. This takes -precedence over SKIP_BUILD_RPATH and avoids the need for relinking -before installation. This property is initialized by the value of the -variable CMAKE_BUILD_WITH_INSTALL_RPATH if it is set when a target is -created. +This property is initialized by the value of the +:variable:`CMAKE_BUILD_WITH_INSTALL_RPATH` variable if it is set when a target +is created. + +If policy :policy:`CMP0068` is not ``NEW``, this property also controls use of +:prop_tgt:`INSTALL_NAME_DIR` in the build tree on macOS. Either way, the +:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property takes precedence. diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst index effa3b0..3f68c31 100644 --- a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst @@ -5,3 +5,7 @@ Enable interprocedural optimization for a target. If set to true, enables interprocedural optimizations if they are known to be supported by the compiler. + +This property is initialized by the +:variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable if it is set when a +target is created. diff --git a/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst index 4da855b..266ccf0 100644 --- a/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst +++ b/Help/prop_tgt/MAP_IMPORTED_CONFIG_CONFIG.rst @@ -23,3 +23,48 @@ is ignored for non-imported targets. This property is initialized by the value of the :variable:`CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable if it is set when a target is created. + +Example +^^^^^^^ + +For example creating imported C++ library ``foo``: + +.. code-block:: cmake + + add_library(foo STATIC IMPORTED) + +Use ``foo_debug`` path for ``Debug`` build type: + +.. code-block:: cmake + + set_property( + TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS DEBUG + ) + + set_target_properties(foo PROPERTIES + IMPORTED_LINK_INTERFACE_LANGUAGES_DEBUG "CXX" + IMPORTED_LOCATION_DEBUG "${foo_debug}" + ) + +Use ``foo_release`` path for ``Release`` build type: + +.. code-block:: cmake + + set_property( + TARGET foo APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE + ) + + set_target_properties(foo PROPERTIES + IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "CXX" + IMPORTED_LOCATION_RELEASE "${foo_release}" + ) + +Use ``Release`` version of library for ``MinSizeRel`` and ``RelWithDebInfo`` +build types: + +.. code-block:: cmake + + set_target_properties(foo PROPERTIES + MAP_IMPORTED_CONFIG_MINSIZEREL Release + MAP_IMPORTED_CONFIG_RELWITHDEBINFO Release + ) diff --git a/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst index 06c3e6d..86711bf 100644 --- a/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst +++ b/Help/prop_tgt/WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -14,6 +14,13 @@ be automatically exported and imported by callers. This simplifies porting projects to Windows by reducing the need for explicit ``dllexport`` markup, even in ``C++`` classes. +When this property is enabled, zero or more ``.def`` files may also be +specified as source files of the target. The exports named by these files +will be merged with those detected from the object files to generate a +single module definition file to be passed to the linker. This can be +used to export symbols from a ``.dll`` that are not in any of its object +files but are added by the linker from dependencies (e.g. ``msvcrt.lib``). + This property is initialized by the value of the :variable:`CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS` variable if it is set when a target is created. diff --git a/Help/release/dev/0-sample-topic.rst b/Help/release/dev/0-sample-topic.rst new file mode 100644 index 0000000..e4cc01e --- /dev/null +++ b/Help/release/dev/0-sample-topic.rst @@ -0,0 +1,7 @@ +0-sample-topic +-------------- + +* This is a sample release note for the change in a topic. + Developers should add similar notes for each topic branch + making a noteworthy change. Each document should be named + and titled to match the topic name to avoid merge conflicts. diff --git a/Help/release/dev/Autogen_depends.rst b/Help/release/dev/Autogen_depends.rst new file mode 100644 index 0000000..c774386 --- /dev/null +++ b/Help/release/dev/Autogen_depends.rst @@ -0,0 +1,10 @@ +AutoGen depends +--------------- + +* Variable :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` was introduced to + allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. + +* The new target property :prop_tgt:`AUTOMOC_DEPEND_FILTERS` was introduced to + allow :prop_tgt:`AUTOMOC` to extract additional dependency file names + for ``moc`` from the contents of source files. diff --git a/Help/release/dev/Autogen_json.rst b/Help/release/dev/Autogen_json.rst new file mode 100644 index 0000000..73bbdf1 --- /dev/null +++ b/Help/release/dev/Autogen_json.rst @@ -0,0 +1,10 @@ +AutoGen json +------------ + +* When using :prop_tgt:`AUTOMOC`, CMake scans for the presence of the + ``Q_PLUGIN_METADATA`` macro and reruns moc when the file from the + macro's ``FILE`` argument changes. + +* When :prop_tgt:`AUTOMOC` detects an include statement of the form + ``#include "moc_<basename>.cpp"`` the respective header file is searched + for in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well. diff --git a/Help/release/dev/Autogen_source_group.rst b/Help/release/dev/Autogen_source_group.rst new file mode 100644 index 0000000..60faa8c --- /dev/null +++ b/Help/release/dev/Autogen_source_group.rst @@ -0,0 +1,8 @@ +AutoGen source group +-------------------- + +* Global properties :prop_gbl:`AUTOGEN_SOURCE_GROUP`, + :prop_gbl:`AUTOMOC_SOURCE_GROUP` and + :prop_gbl:`AUTORCC_SOURCE_GROUP` were + introduced to allow files generated by :prop_tgt:`AUTOMOC` or + :prop_tgt:`AUTORCC` to be placed in a :command:`source_group`. diff --git a/Help/release/dev/Autogen_uic_paths.rst b/Help/release/dev/Autogen_uic_paths.rst new file mode 100644 index 0000000..0893194 --- /dev/null +++ b/Help/release/dev/Autogen_uic_paths.rst @@ -0,0 +1,10 @@ +AutoGen uic paths +----------------- + +* Variable :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` was introduced to + allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the ``ui_foo.h`` including file. + +* The new target property :prop_tgt:`AUTOUIC_SEARCH_PATHS` was introduced to + allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more + places than the vicinity of the ``ui_foo.h`` including file. diff --git a/Help/release/dev/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst b/Help/release/dev/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst new file mode 100644 index 0000000..fc4f733 --- /dev/null +++ b/Help/release/dev/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,6 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION +---------------------------------- + +* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to + initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all + targets. diff --git a/Help/release/dev/CheckIPOSupported.rst b/Help/release/dev/CheckIPOSupported.rst new file mode 100644 index 0000000..dbc84e6 --- /dev/null +++ b/Help/release/dev/CheckIPOSupported.rst @@ -0,0 +1,6 @@ +CheckIPOSupported +----------------- + +* A :module:`CheckIPOSupported` module was added to help projects + check whether interprocedural optimization (IPO) is supported by + the current toolchain and CMake version. diff --git a/Help/release/dev/ExtractGTestMacro.rst b/Help/release/dev/ExtractGTestMacro.rst new file mode 100644 index 0000000..574982c --- /dev/null +++ b/Help/release/dev/ExtractGTestMacro.rst @@ -0,0 +1,5 @@ +ExtractGTestMacro +----------------- + +* A new :module:`GoogleTest` module was added to provide the + ``gtest_add_tests`` macro independently of the :module:`FindGTest` module. diff --git a/Help/release/dev/FeatureSummary_description.rst b/Help/release/dev/FeatureSummary_description.rst new file mode 100644 index 0000000..c56e4ce --- /dev/null +++ b/Help/release/dev/FeatureSummary_description.rst @@ -0,0 +1,11 @@ +FeatureSummary_description +-------------------------- + +* The :command:`feature_summary` command in the :module:`FeatureSummary` module + accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default + title for the selected package type. + +* The global property :variable:`FeatureSummary_<TYPE>_DESCRIPTION` can be + defined for each ``<TYPE>`` to replace the type name with the specified string + whenever the package type is used in an output string by the + :module:`FeatureSummary` module. diff --git a/Help/release/dev/FindProtobuf-static-libs.rst b/Help/release/dev/FindProtobuf-static-libs.rst new file mode 100644 index 0000000..fcc0678 --- /dev/null +++ b/Help/release/dev/FindProtobuf-static-libs.rst @@ -0,0 +1,5 @@ +FindProtobuf-static-libs +------------------------ + +* The :module:`FindProtobuf` module now supports usage of static libraries + for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable. diff --git a/Help/release/dev/bundle-genex.rst b/Help/release/dev/bundle-genex.rst new file mode 100644 index 0000000..e79b84c --- /dev/null +++ b/Help/release/dev/bundle-genex.rst @@ -0,0 +1,12 @@ +bundle-genex +------------ + +* Two new informational generator expressions to retrieve Apple Bundle + directories have been added. The first one ``$<TARGET_BUNDLE_DIR:tgt>`` + outputs the full path to the Bundle directory, the other one + ``$<TARGET_BUNDLE_CONTENT_DIR:tgt>`` outputs the full path to the + ``Contents`` directory of macOS Bundles and App Bundles. For all other + bundle types and SDKs it is identical with ``$<TARGET_BUNDLE_DIR:tgt>``. + + Those new expressions are helpful to query Bundle locations independent of + the different Bundle types and layouts on macOS and iOS. diff --git a/Help/release/dev/cmake-xcode-schemes.rst b/Help/release/dev/cmake-xcode-schemes.rst new file mode 100644 index 0000000..81068ae --- /dev/null +++ b/Help/release/dev/cmake-xcode-schemes.rst @@ -0,0 +1,6 @@ +cmake-xcode-schemes +------------------- + +* The :generator:`Xcode` generator got the ability to create schema files. + This is still an experimental feature and can be activated by setting the + :variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value. diff --git a/Help/release/dev/compiler_archiving_tools.rst b/Help/release/dev/compiler_archiving_tools.rst new file mode 100644 index 0000000..de3471d --- /dev/null +++ b/Help/release/dev/compiler_archiving_tools.rst @@ -0,0 +1,8 @@ +compiler_archiving_tools +------------------------ + +* A :variable:`CMAKE_<LANG>_COMPILER_AR` variable was added to hold + the path to the GCC/Clang wrapper of ``ar``. + +* A :variable:`CMAKE_<LANG>_COMPILER_RANLIB` variable was added to hold + the path to the GCC/Clang wrapper of ``ranlib``. diff --git a/Help/release/dev/cpack-rpm-debuginfo-honor-package-filename.rst b/Help/release/dev/cpack-rpm-debuginfo-honor-package-filename.rst new file mode 100644 index 0000000..1c6eb2b --- /dev/null +++ b/Help/release/dev/cpack-rpm-debuginfo-honor-package-filename.rst @@ -0,0 +1,5 @@ +cpack-rpm-debuginfo-honor-package-filename +------------------------------------------ + +* The :module:`CPackRPM` module learned to modify debuginfo package name. + See :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable. diff --git a/Help/release/dev/ctest-disable-tests.rst b/Help/release/dev/ctest-disable-tests.rst new file mode 100644 index 0000000..9208f0c --- /dev/null +++ b/Help/release/dev/ctest-disable-tests.rst @@ -0,0 +1,5 @@ +ctest-disable-tests +------------------- + +* A :prop_test:`DISABLED` test property was added to mark tests that + are configured but explicitly disabled so they do not run. diff --git a/Help/release/dev/cuda-vs.rst b/Help/release/dev/cuda-vs.rst new file mode 100644 index 0000000..9170537 --- /dev/null +++ b/Help/release/dev/cuda-vs.rst @@ -0,0 +1,5 @@ +cuda-vs +------- + +* ``CUDA`` is now supported by the :ref:`Visual Studio Generators` + for VS 2010 and above. diff --git a/Help/release/dev/find_library-custom-lib-suffix.rst b/Help/release/dev/find_library-custom-lib-suffix.rst new file mode 100644 index 0000000..824b27e --- /dev/null +++ b/Help/release/dev/find_library-custom-lib-suffix.rst @@ -0,0 +1,6 @@ +find_library-custom-lib-suffix +------------------------------ + +* A :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable was added to + tell the :command:`find_library` command to search in a ``lib<suffix>`` + directory before each ``lib`` directory that would normally be searched. diff --git a/Help/release/dev/gcc-ipo.rst b/Help/release/dev/gcc-ipo.rst new file mode 100644 index 0000000..ebc5c0d --- /dev/null +++ b/Help/release/dev/gcc-ipo.rst @@ -0,0 +1,7 @@ +GCC IPO +------- + +* Interprocedural optimization (IPO) is now supported for GNU + compilers using link time optimization (LTO) flags. See the + :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and + :module:`CheckIPOSupported` module. diff --git a/Help/release/dev/include_external_msproject-map-config.rst b/Help/release/dev/include_external_msproject-map-config.rst new file mode 100644 index 0000000..d5f7a7f --- /dev/null +++ b/Help/release/dev/include_external_msproject-map-config.rst @@ -0,0 +1,6 @@ +include_external_msproject-map-config +------------------------------------- + +* The :command:`include_external_msproject` command learned to use + the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` target property + to map current configurations to the external configurations. diff --git a/Help/release/dev/install_name_policy.rst b/Help/release/dev/install_name_policy.rst new file mode 100644 index 0000000..7fe9a86 --- /dev/null +++ b/Help/release/dev/install_name_policy.rst @@ -0,0 +1,11 @@ +install_name_policy +------------------- + +* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding + :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to + control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property + value for binaries in the build tree. This is for macOS ``install_name`` + as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``. + +* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` + no longer affect the ``install_name`` field. See policy :policy:`CMP0068`. diff --git a/Help/release/dev/interprocedural_optimization_policy.rst b/Help/release/dev/interprocedural_optimization_policy.rst new file mode 100644 index 0000000..93a9d68 --- /dev/null +++ b/Help/release/dev/interprocedural_optimization_policy.rst @@ -0,0 +1,8 @@ +interprocedural_optimization_policy +----------------------------------- + +* The :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property is now enforced + when enabled. CMake will add IPO flags unconditionally or produce an error + if it does not know the flags for the current compiler. The project is now + responsible to use the :module:`CheckIPOSupported` module to check for IPO + support before enabling the target property. See policy :policy:`CMP0069`. diff --git a/Help/release/dev/module-def-and-WINDOWS_EXPORT_ALL_SYMBOLS.rst b/Help/release/dev/module-def-and-WINDOWS_EXPORT_ALL_SYMBOLS.rst new file mode 100644 index 0000000..dfa9ef1 --- /dev/null +++ b/Help/release/dev/module-def-and-WINDOWS_EXPORT_ALL_SYMBOLS.rst @@ -0,0 +1,8 @@ +module-def-and-WINDOWS_EXPORT_ALL_SYMBOLS +----------------------------------------- + +* The :prop_tgt:`WINDOWS_EXPORT_ALL_SYMBOLS` target property may now + be used in combination with explicit ``.def`` files in order to + export all symbols from the object files within a target plus + an explicit list of symbols that the linker finds in dependencies + (e.g. ``msvcrt.lib``). diff --git a/Help/release/dev/productbuild_component_plist.rst b/Help/release/dev/productbuild_component_plist.rst new file mode 100644 index 0000000..78d305c --- /dev/null +++ b/Help/release/dev/productbuild_component_plist.rst @@ -0,0 +1,7 @@ +productbuild_component_plist +---------------------------- + +* The :module:`CPackComponent` module :command:`cpack_add_component` command + gained a new ``PLIST <filename>`` option to specify the ``pkgbuild`` + ``--component-plist`` argument when using the + :module:`productbuild <CPackProductBuild>` generator. diff --git a/Help/release/dev/productbuild_resources.rst b/Help/release/dev/productbuild_resources.rst new file mode 100644 index 0000000..f381e63 --- /dev/null +++ b/Help/release/dev/productbuild_resources.rst @@ -0,0 +1,7 @@ +productbuild_resources +---------------------- + +* The :module:`CPackProductBuild` module gained a new + :variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to + specify resources to be copied into the ``Resources`` + directory. diff --git a/Help/release/dev/prop-is-multi-config.rst b/Help/release/dev/prop-is-multi-config.rst new file mode 100644 index 0000000..52de563 --- /dev/null +++ b/Help/release/dev/prop-is-multi-config.rst @@ -0,0 +1,6 @@ +prop-is-multi-config +-------------------- + +* A :prop_gbl:`GENERATOR_IS_MULTI_CONFIG` global property was + added to determine whether the current generator is a multi-configuration + generator (such as :ref:`Visual Studio Generators` or :generator:`Xcode`). diff --git a/Help/release/dev/update-curl.rst b/Help/release/dev/update-curl.rst new file mode 100644 index 0000000..852ad5a --- /dev/null +++ b/Help/release/dev/update-curl.rst @@ -0,0 +1,6 @@ +update-curl +----------- + +* The version of curl bundled with CMake no longer accepts URLs of the form + ``file://c:/...`` on Windows due to a change in upstream curl 7.52. Use + the form ``file:///c:/...`` instead to work on all versions. diff --git a/Help/release/dev/vs-nasm.rst b/Help/release/dev/vs-nasm.rst new file mode 100644 index 0000000..bb082a4 --- /dev/null +++ b/Help/release/dev/vs-nasm.rst @@ -0,0 +1,5 @@ +vs-nasm +------- + +* :ref:`Visual Studio Generators` for VS 2010 and above learned to support + the ``ASM_NASM`` language when ``nasm`` is installed. diff --git a/Help/release/dev/wix-custom-root-id.rst b/Help/release/dev/wix-custom-root-id.rst new file mode 100644 index 0000000..3e10fdd --- /dev/null +++ b/Help/release/dev/wix-custom-root-id.rst @@ -0,0 +1,7 @@ +wix-custom-root-id +------------------ + +* The CPack WIX generator implemented a new + :variable:`CPACK_WIX_ROOT_FOLDER_ID` variable which allows + using a custom root folder ID instead of the default + ``ProgramFilesFolder`` / ``ProgramFiles64Folder``. diff --git a/Help/release/dev/x32-abi.rst b/Help/release/dev/x32-abi.rst new file mode 100644 index 0000000..7571fac --- /dev/null +++ b/Help/release/dev/x32-abi.rst @@ -0,0 +1,6 @@ +x32-abi +------- + +* The :command:`find_library` command learned to search ``libx32`` paths + when the build targets the ``x32`` ABI. See the + :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property. diff --git a/Help/release/index.rst b/Help/release/index.rst index 8f0f252..292c9a8 100644 --- a/Help/release/index.rst +++ b/Help/release/index.rst @@ -5,6 +5,8 @@ CMake Release Notes This file should include the adjacent "dev.txt" file in development versions but not in release versions. +.. include:: dev.txt + Releases ======== diff --git a/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst new file mode 100644 index 0000000..5c3662d --- /dev/null +++ b/Help/variable/CMAKE_AUTOMOC_DEPEND_FILTERS.rst @@ -0,0 +1,12 @@ +CMAKE_AUTOMOC_DEPEND_FILTERS +---------------------------- + +Filter definitions used by :variable:`CMAKE_AUTOMOC` +to extract file names from source code as additional dependencies +for the ``moc`` file. + +This variable is used to initialize the :prop_tgt:`AUTOMOC_DEPEND_FILTERS` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst new file mode 100644 index 0000000..aa132bf --- /dev/null +++ b/Help/variable/CMAKE_AUTOUIC_SEARCH_PATHS.rst @@ -0,0 +1,11 @@ +CMAKE_AUTOUIC_SEARCH_PATHS +-------------------------- + +Search path list used by :variable:`CMAKE_AUTOUIC` to find included +``.ui`` files. + +This variable is used to initialize the :prop_tgt:`AUTOUIC_SEARCH_PATHS` +property on all the targets. See that target property for additional +information. + +By default it is empty. diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst new file mode 100644 index 0000000..30d5d3b --- /dev/null +++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst @@ -0,0 +1,7 @@ +CMAKE_BUILD_WITH_INSTALL_NAME_DIR +--------------------------------- + +Whether to use :prop_tgt:`INSTALL_NAME_DIR` on targets in the build tree. + +This variable is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` +property on all targets. diff --git a/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst new file mode 100644 index 0000000..ada8955 --- /dev/null +++ b/Help/variable/CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX.rst @@ -0,0 +1,12 @@ +CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX +------------------------------------ + +Specify a ``<suffix>`` to tell the :command:`find_library` command to +search in a ``lib<suffix>`` directory before each ``lib`` directory that +would normally be searched. + +This overrides the behavior of related global properties: + +* :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` +* :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` +* :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst index a5c284a..50412ff 100644 --- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst +++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst @@ -1,7 +1,7 @@ CMAKE_GENERATOR_PLATFORM ------------------------ -Generator-specific target platform name specified by user. +Generator-specific target platform specification provided by user. Some CMake generators support a target platform name to be given to the native build system to choose a compiler toolchain. @@ -13,3 +13,16 @@ A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` variable may initialize ``CMAKE_GENERATOR_PLATFORM``. Once a given build tree has been initialized with a particular value for this variable, changing the value has undefined behavior. + +Platform specification is supported only on specific generators: + +* For :ref:`Visual Studio Generators` with VS 2005 and above this + specifies the target architecture. + +See native build system documentation for allowed platform names. + +Visual Studio Platform Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +On :ref:`Visual Studio Generators` the selected platform name +is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable. diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst index 89abe54..11c37d7 100644 --- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst +++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst @@ -1,15 +1,50 @@ CMAKE_GENERATOR_TOOLSET ----------------------- -Native build system toolset name specified by user. +Native build system toolset specification provided by user. -Some CMake generators support a toolset name to be given to the native -build system to choose a compiler. If the user specifies a toolset -name (e.g. via the :manual:`cmake(1)` ``-T`` option) the value will be -available in this variable. +Some CMake generators support a toolset specification to tell the +native build system how to choose a compiler. If the user specifies +a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option) the value +will be available in this variable. The value of this variable should never be modified by project code. A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE` variable may initialize ``CMAKE_GENERATOR_TOOLSET``. Once a given build tree has been initialized with a particular value for this variable, changing the value has undefined behavior. + +Toolset specification is supported only on specific generators: + +* :ref:`Visual Studio Generators` for VS 2010 and above +* The :generator:`Xcode` generator for Xcode 3.0 and above + +See native build system documentation for allowed toolset names. + +Visual Studio Toolset Selection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The :ref:`Visual Studio Generators` support toolset specification +using one of these forms: + +* ``toolset`` +* ``toolset[,key=value]*`` +* ``key=value[,key=value]*`` + +The ``toolset`` specifies the toolset name. The selected toolset name +is provided in the :variable:`CMAKE_VS_PLATFORM_TOOLSET` variable. + +The ``key=value`` pairs form a comma-separated list of options to +specify generator-specific details of the toolset selection. +Supported pairs are: + +``cuda=<version>`` + Specify the CUDA toolkit version to use. Supported by VS 2010 + 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. + Supported by VS 2013 and above. + See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE` + variable. diff --git a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst new file mode 100644 index 0000000..b0cbb62 --- /dev/null +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst @@ -0,0 +1,8 @@ +CMAKE_INTERPROCEDURAL_OPTIMIZATION +---------------------------------- + +Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` of targets. + +This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` +property on all the targets. See that target property for additional +information. diff --git a/Help/variable/CMAKE_LANG_COMPILER_AR.rst b/Help/variable/CMAKE_LANG_COMPILER_AR.rst new file mode 100644 index 0000000..b83a1d4 --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_AR.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILER_AR +------------------------ + +A wrapper around ``ar`` adding the appropriate ``--plugin`` option for the +compiler. + +See also :variable:`CMAKE_AR`. diff --git a/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst new file mode 100644 index 0000000..945160b --- /dev/null +++ b/Help/variable/CMAKE_LANG_COMPILER_RANLIB.rst @@ -0,0 +1,7 @@ +CMAKE_<LANG>_COMPILER_RANLIB +---------------------------- + +A wrapper around ``ranlib`` adding the appropriate ``--plugin`` option for the +compiler. + +See also :variable:`CMAKE_RANLIB`. diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst index c6f8d41..a532743 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst @@ -5,3 +5,4 @@ Visual Studio target platform name. VS 8 and above allow project files to specify a target platform. CMake provides the name of the chosen platform in this variable. +See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst index 144a41d..ed2d3f3 100644 --- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst @@ -8,3 +8,5 @@ compiler toolchains. CMake may specify a toolset explicitly, such as ``v110`` for VS 11 or ``Windows7.1SDK`` for 64-bit support in VS 10 Express. CMake provides the name of the chosen toolset in this variable. + +See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details. diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst new file mode 100644 index 0000000..1604a76 --- /dev/null +++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA.rst @@ -0,0 +1,12 @@ +CMAKE_VS_PLATFORM_TOOLSET_CUDA +------------------------------ + +NVIDIA CUDA Toolkit version whose Visual Studio toolset to use. + +The :ref:`Visual Studio Generators` for VS 2010 and above support using +a CUDA toolset provided by a CUDA Toolkit. The toolset version number +may be specified by a field in :variable:`CMAKE_GENERATOR_TOOLSET` of +the form ``cuda=8.0``. If none is specified CMake will choose a default +version. CMake provides the selected CUDA toolset version in this variable. +The value may be empty if no CUDA Toolkit with Visual Studio integration +is installed. diff --git a/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst new file mode 100644 index 0000000..c9fcc92 --- /dev/null +++ b/Help/variable/CMAKE_XCODE_GENERATE_SCHEME.rst @@ -0,0 +1,11 @@ +CMAKE_XCODE_GENERATE_SCHEME +--------------------------- + +If enabled, the Xcode generator will generate schema files. Those are +are useful to invoke analyze, archive, build-for-testing and test +actions from the command line. + +.. note:: + + The Xcode Schema Generator is still experimental and subject to + change. |