Felix Geyer
8 years ago
parent
b4903bcd04
commit
18330eafcd
@ -0,0 +1,30 @@
|
|||||||
|
---
|
||||||
|
Checks: "-*,\
|
||||||
|
misc-*,\
|
||||||
|
-misc-incorrect-roundings,\
|
||||||
|
-misc-macro-parentheses,\
|
||||||
|
-misc-misplaced-widening-cast,\
|
||||||
|
-misc-static-assert,\
|
||||||
|
modernize-make-shared,\
|
||||||
|
modernize-make-unique,\
|
||||||
|
modernize-redundant-void-arg,\
|
||||||
|
modernize-use-bool-literals,\
|
||||||
|
modernize-use-nullptr,\
|
||||||
|
modernize-use-override,\
|
||||||
|
performance-*,\
|
||||||
|
-performance-inefficient-string-concatenation,\
|
||||||
|
readability-*,\
|
||||||
|
-readability-function-size,\
|
||||||
|
-readability-identifier-naming,\
|
||||||
|
-readability-implicit-bool-cast,\
|
||||||
|
-readability-inconsistent-declaration-parameter-name,\
|
||||||
|
-readability-named-parameter,\
|
||||||
|
-readability-redundant-declaration,\
|
||||||
|
-readability-redundant-member-init,\
|
||||||
|
-readability-simplify-boolean-expr,\
|
||||||
|
"
|
||||||
|
HeaderFilterRegex: 'Source/cm[^/]*\.(h|hxx|cxx)$'
|
||||||
|
CheckOptions:
|
||||||
|
- key: modernize-use-nullptr.NullMacros
|
||||||
|
value: 'CM_NULLPTR'
|
||||||
|
...
|
||||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -0,0 +1,49 @@
|
|||||||
|
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
|
||||||
|
|
||||||
|
Developer Documentation
|
||||||
|
=======================
|
||||||
|
|
||||||
|
CMake developer documentation is provided by the following documents:
|
||||||
|
|
||||||
|
* The `CMake Source Code Guide`_.
|
||||||
|
|
||||||
|
.. _`CMake Source Code Guide`: source.rst
|
||||||
|
|
||||||
|
Maintainer Documentation
|
||||||
|
========================
|
||||||
|
|
||||||
|
CMake maintainer documentation is provided by the following documents:
|
||||||
|
|
||||||
|
* The `CMake Maintainer Guide`_.
|
||||||
|
|
||||||
|
.. _`CMake Maintainer Guide`: maint.rst
|
||||||
@ -0,0 +1,171 @@
|
|||||||
|
CMake Maintainer Guide
|
||||||
|
**********************
|
||||||
|
|
||||||
|
The following is a guide to CMake maintenance processes.
|
||||||
|
See documentation on `CMake Development`_ for more information.
|
||||||
|
|
||||||
|
.. _`CMake Development`: README.rst
|
||||||
|
|
||||||
|
.. contents:: Maintainer Processes:
|
||||||
|
|
||||||
|
Branch a New Release
|
||||||
|
====================
|
||||||
|
|
||||||
|
This section covers how to start a new ``release`` branch for a major or
|
||||||
|
minor version bump (patch releases remain on their existing branch).
|
||||||
|
|
||||||
|
In the following we use the placeholder ``$ver`` to represent the
|
||||||
|
version number of the new release with the form ``$major.$minor``,
|
||||||
|
and ``$prev`` to represent the version number of the prior release.
|
||||||
|
|
||||||
|
Review Prior Release
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Review the history around the prior release branch:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
git log --graph --boundary \
|
||||||
|
^$(git rev-list --grep="Merge topic 'doc-.*-relnotes'" -n 1 master)~1 \
|
||||||
|
$(git rev-list --grep="Begin post-.* development" -n 1 master) \
|
||||||
|
$(git tag --list *-rc1| tail -1)
|
||||||
|
|
||||||
|
Consolidate Release Notes
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Starting from a clean work tree on ``master``, create a topic branch to
|
||||||
|
use for consolidating the release notes:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
git checkout -b doc-$ver-relnotes
|
||||||
|
|
||||||
|
Run the `consolidate-relnotes.bash`_ script:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
Utilities/Release/consolidate-relnotes.bash $ver $prev
|
||||||
|
|
||||||
|
.. _`consolidate-relnotes.bash`: ../../Utilities/Release/consolidate-relnotes.bash
|
||||||
|
|
||||||
|
This moves notes from the ``Help/release/dev/*.rst`` files into a versioned
|
||||||
|
``Help/release/$ver.rst`` file and updates ``Help/release/index.rst`` to
|
||||||
|
link to the new document. Commit the changes with a message such as::
|
||||||
|
|
||||||
|
Help: Consolidate $ver release notes
|
||||||
|
|
||||||
|
Run the `Utilities/Release/consolidate-relnotes.bash` script to move
|
||||||
|
notes from `Help/release/dev/*` into `Help/release/$ver.rst`.
|
||||||
|
|
||||||
|
Manually edit ``Help/release/$ver.rst`` to add section headers, organize
|
||||||
|
the notes, and revise wording. Then commit with a message such as::
|
||||||
|
|
||||||
|
Help: Organize and revise $ver release notes
|
||||||
|
|
||||||
|
Add section headers similar to the $prev release notes and move each
|
||||||
|
individual bullet into an appropriate section. Revise a few bullets.
|
||||||
|
|
||||||
|
Open a merge request with the ``doc-$ver-relnotes`` branch for review
|
||||||
|
and integration. Further steps may proceed after this has been merged
|
||||||
|
to ``master``.
|
||||||
|
|
||||||
|
Update 'release' Branch
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Starting from a clean work tree on ``master``, create a new ``release-$ver``
|
||||||
|
branch locally:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
git checkout -b release-$ver origin/master
|
||||||
|
|
||||||
|
Remove the development branch release note infrastructure:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
git rm Help/release/dev/0-sample-topic.rst
|
||||||
|
sed -i '/^\.\. include:: dev.txt/ {N;d}' Help/release/index.rst
|
||||||
|
|
||||||
|
Commit with a message such as::
|
||||||
|
|
||||||
|
Help: Drop development topic notes to prepare release
|
||||||
|
|
||||||
|
Release versions do not have the development topic section of
|
||||||
|
the CMake Release Notes index page.
|
||||||
|
|
||||||
|
Update ``Source/CMakeVersion.cmake`` to set the version to
|
||||||
|
``$major.$minor.0-rc1``:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
# CMake version number components.
|
||||||
|
set(CMake_VERSION_MAJOR $major)
|
||||||
|
set(CMake_VERSION_MINOR $minor)
|
||||||
|
set(CMake_VERSION_PATCH 0)
|
||||||
|
set(CMake_VERSION_RC 1)
|
||||||
|
|
||||||
|
Update ``Utilities/Release/upload_release.cmake``:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
set(VERSION $ver)
|
||||||
|
|
||||||
|
Update uses of ``DEVEL_CMAKE_VERSION`` in the source tree to mention the
|
||||||
|
actual version number:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
$EDITOR $(git grep -l DEVEL_CMAKE_VERSION)
|
||||||
|
|
||||||
|
Commit with a message such as::
|
||||||
|
|
||||||
|
CMake $major.$minor.0-rc1 version update
|
||||||
|
|
||||||
|
Merge the ``release-$ver`` branch to ``master``:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
git checkout master
|
||||||
|
git pull
|
||||||
|
git merge --no-ff release-$ver
|
||||||
|
|
||||||
|
Begin post-release development by restoring the development branch release
|
||||||
|
note infrastructure and the version date from ``origin/master``:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
git checkout origin/master -- \
|
||||||
|
Source/CMakeVersion.cmake Help/release/dev/0-sample-topic.rst
|
||||||
|
sed -i $'/^Releases/ i\\\n.. include:: dev.txt\\\n' Help/release/index.rst
|
||||||
|
|
||||||
|
Update ``Source/CMakeVersion.cmake`` to set the version to
|
||||||
|
``$major.$minor.$date``:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
# CMake version number components.
|
||||||
|
set(CMake_VERSION_MAJOR $major)
|
||||||
|
set(CMake_VERSION_MINOR $minor)
|
||||||
|
set(CMake_VERSION_PATCH $date)
|
||||||
|
#set(CMake_VERSION_RC 1)
|
||||||
|
|
||||||
|
Commit with a message such as::
|
||||||
|
|
||||||
|
Begin post-$ver development
|
||||||
|
|
||||||
|
Push the update to the ``master`` and ``release`` branches:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
git push --atomic origin master release-$ver:release
|
||||||
|
|
||||||
|
Announce 'release' Branch
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
Send email to the ``cmake-developers@cmake.org`` mailing list (perhaps
|
||||||
|
in reply to a release preparation thread) announcing that post-release
|
||||||
|
development is open::
|
||||||
|
|
||||||
|
I've branched 'release' for $ver. The repository is now open for
|
||||||
|
post-$ver development. Please rebase open merge requests on 'master'
|
||||||
|
before staging or merging.
|
||||||
@ -0,0 +1,350 @@
|
|||||||
|
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``, ``vs<year>``,
|
||||||
|
or ``lint-iwyu-tidy``
|
||||||
|
|
||||||
|
The special ``lint-<tools>`` generator name is a builder that builds
|
||||||
|
CMake using lint tools but does not run the test suite (so the actual
|
||||||
|
generator does not matter).
|
||||||
|
|
||||||
|
.. _`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.
|
||||||
|
This is useful to remove a MR from the topic stage when one is not ready
|
||||||
|
to push an update to the MR topic branch. It is unnecessary to explicitly
|
||||||
|
unstage just before or after pushing an update because the push will cause
|
||||||
|
the MR to be unstaged automatically.
|
||||||
|
|
||||||
|
* 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.
|
||||||
@ -0,0 +1,60 @@
|
|||||||
|
CMake Source Code Guide
|
||||||
|
***********************
|
||||||
|
|
||||||
|
The following is a guide to the CMake source code for developers.
|
||||||
|
See documentation on `CMake Development`_ for more information.
|
||||||
|
|
||||||
|
.. _`CMake Development`: README.rst
|
||||||
|
|
||||||
|
C++ Code Style
|
||||||
|
==============
|
||||||
|
|
||||||
|
We use `clang-format`_ version **3.8** to define our style for C++ code in
|
||||||
|
the CMake source tree. See the `.clang-format`_ configuration file for our
|
||||||
|
style settings. Use the `Utilities/Scripts/clang-format.bash`_ script to
|
||||||
|
format source code. It automatically runs ``clang-format`` on the set of
|
||||||
|
source files for which we enforce style. The script also has options to
|
||||||
|
format only a subset of files, such as those that are locally modified.
|
||||||
|
|
||||||
|
.. _`clang-format`: http://clang.llvm.org/docs/ClangFormat.html
|
||||||
|
.. _`.clang-format`: ../../.clang-format
|
||||||
|
.. _`Utilities/Scripts/clang-format.bash`: ../../Utilities/Scripts/clang-format.bash
|
||||||
|
|
||||||
|
C++ Subset Permitted
|
||||||
|
====================
|
||||||
|
|
||||||
|
CMake supports compiling as C++98 in addition to C++11 and C++14.
|
||||||
|
In order to support building on older toolchains some constructs
|
||||||
|
need to be handled with care:
|
||||||
|
|
||||||
|
* Use ``CM_AUTO_PTR`` instead of ``std::auto_ptr``.
|
||||||
|
|
||||||
|
The ``std::auto_ptr`` template is deprecated in C++11. We want to use it
|
||||||
|
so we can build on C++98 compilers but we do not want to turn off compiler
|
||||||
|
warnings about deprecated interfaces in general. Use the ``CM_AUTO_PTR``
|
||||||
|
macro instead.
|
||||||
|
|
||||||
|
* Use ``CM_EQ_DELETE;`` instead of ``= delete;``.
|
||||||
|
|
||||||
|
Defining functions as *deleted* is not supported in C++98. Using
|
||||||
|
``CM_EQ_DELETE`` will delete the functions if the compiler supports it and
|
||||||
|
give them no implementation otherwise. Calling such a function will lead
|
||||||
|
to compiler errors if the compiler supports *deleted* functions and linker
|
||||||
|
errors otherwise.
|
||||||
|
|
||||||
|
* Use ``CM_DISABLE_COPY(Class)`` to mark classes as non-copyable.
|
||||||
|
|
||||||
|
The ``CM_DISABLE_COPY`` macro should be used in the private section of a
|
||||||
|
class to make sure that attempts to copy or assign an instance of the class
|
||||||
|
lead to compiler errors even if the compiler does not support *deleted*
|
||||||
|
functions. As a guideline, all polymorphic classes should be made
|
||||||
|
non-copyable in order to avoid slicing. Classes that are composed of or
|
||||||
|
derived from non-copyable classes must also be made non-copyable explicitly
|
||||||
|
with ``CM_DISABLE_COPY``.
|
||||||
|
|
||||||
|
* Use ``size_t`` instead of ``std::size_t``.
|
||||||
|
|
||||||
|
Various implementations have differing implementation of ``size_t``.
|
||||||
|
When assigning the result of ``.size()`` on a container for example,
|
||||||
|
the result should be assigned to ``size_t`` not to ``std::size_t``,
|
||||||
|
``unsigned int`` or similar types.
|
||||||
@ -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.
|
||||||
@ -1,10 +1,6 @@
|
|||||||
Visual Studio 7 .NET 2003
|
Visual Studio 7 .NET 2003
|
||||||
-------------------------
|
-------------------------
|
||||||
|
|
||||||
Deprecated. Generates Visual Studio .NET 2003 project files.
|
Removed. This once generated Visual Studio .NET 2003 project files, but
|
||||||
|
the generator has been removed since CMake 3.9. It is still possible to
|
||||||
.. note::
|
build with VS 7.1 tools using the :generator:`NMake Makefiles` generator.
|
||||||
This generator is deprecated and will be removed
|
|
||||||
in a future version of CMake. It will still be
|
|
||||||
possible to build with VS 7.1 tools using the
|
|
||||||
:generator:`NMake Makefiles` generator.
|
|
||||||
|
|||||||
@ -0,0 +1 @@
|
|||||||
|
.. cmake-module:: ../../Modules/CPackArchive.cmake
|
||||||
@ -0,0 +1 @@
|
|||||||
|
.. cmake-module:: ../../Modules/CheckIPOSupported.cmake
|
||||||
@ -0,0 +1 @@
|
|||||||
|
.. cmake-module:: ../../Modules/GoogleTest.cmake
|
||||||
@ -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
|
||||||
@ -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)
|
||||||
@ -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.
|
||||||
@ -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`.
|
||||||
@ -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`.
|
||||||
@ -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.
|
||||||
@ -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`.
|
||||||
@ -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.
|
||||||
@ -0,0 +1,17 @@
|
|||||||
|
AUTOGEN_BUILD_DIR
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
Directory where :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and :prop_tgt:`AUTORCC`
|
||||||
|
generate files for the target.
|
||||||
|
|
||||||
|
The directory is created on demand and automatically added to the
|
||||||
|
:prop_dir:`ADDITIONAL_MAKE_CLEAN_FILES`.
|
||||||
|
|
||||||
|
When unset or empty the directory ``<dir>/<target-name>_autogen`` is used where
|
||||||
|
``<dir>`` is :variable:`CMAKE_CURRENT_BINARY_DIR` and ``<target-name>``
|
||||||
|
is :prop_tgt:`NAME`.
|
||||||
|
|
||||||
|
By default :prop_tgt:`AUTOGEN_BUILD_DIR` is unset.
|
||||||
|
|
||||||
|
See the :manual:`cmake-qt(7)` manual for more information on using CMake
|
||||||
|
with Qt.
|
||||||
@ -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]*\"([^\"]+)\""
|
||||||
|
)
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -1,11 +1,15 @@
|
|||||||
BUILD_WITH_INSTALL_RPATH
|
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
|
This property is initialized by the value of the
|
||||||
target in the build tree with the INSTALL_RPATH. This takes
|
:variable:`CMAKE_BUILD_WITH_INSTALL_RPATH` variable if it is set when a target
|
||||||
precedence over SKIP_BUILD_RPATH and avoids the need for relinking
|
is created.
|
||||||
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
|
If policy :policy:`CMP0068` is not ``NEW``, this property also controls use of
|
||||||
created.
|
: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.
|
||||||
|
|||||||
@ -0,0 +1,12 @@
|
|||||||
|
CUDA_PTX_COMPILATION
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
Compile CUDA sources to ``.ptx`` files instead of ``.obj`` files
|
||||||
|
within :ref:`Object Libraries`.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
add_library(myptx OBJECT a.cu b.cu)
|
||||||
|
set_property(TARGET myptx PROPERTY CUDA_PTX_COMPILATION ON)
|
||||||
@ -0,0 +1,15 @@
|
|||||||
|
CUDA_RESOLVE_DEVICE_SYMBOLS
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
CUDA only: Enables device linking for the specific static library target
|
||||||
|
|
||||||
|
If set this will enable device linking on this static library target. Normally
|
||||||
|
device linking is deferred until a shared library or executable is generated,
|
||||||
|
allowing for multiple static libraries to resolve device symbols at the same
|
||||||
|
time.
|
||||||
|
|
||||||
|
For instance:
|
||||||
|
|
||||||
|
.. code-block:: cmake
|
||||||
|
|
||||||
|
set_property(TARGET mystaticlib PROPERTY CUDA_RESOLVE_DEVICE_SYMBOLS ON)
|
||||||
@ -0,0 +1,11 @@
|
|||||||
|
IMPORTED_OBJECTS
|
||||||
|
----------------
|
||||||
|
|
||||||
|
:ref:`;-list <CMake Language Lists>` of absolute paths to the object
|
||||||
|
files on disk for an :ref:`imported <Imported targets>`
|
||||||
|
:ref:`object library <object libraries>`.
|
||||||
|
|
||||||
|
Ignored for non-imported targets.
|
||||||
|
|
||||||
|
Projects may skip ``IMPORTED_OBJECTS`` if the configuration-specific
|
||||||
|
property :prop_tgt:`IMPORTED_OBJECTS_<CONFIG>` is set instead.
|
||||||
@ -0,0 +1,7 @@
|
|||||||
|
IMPORTED_OBJECTS_<CONFIG>
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
<CONFIG>-specific version of :prop_tgt:`IMPORTED_OBJECTS` property.
|
||||||
|
|
||||||
|
Configuration names correspond to those provided by the project from
|
||||||
|
which the target is imported.
|
||||||
@ -0,0 +1,328 @@
|
|||||||
|
CMake 3.9 Release Notes
|
||||||
|
***********************
|
||||||
|
|
||||||
|
.. only:: html
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
Changes made since CMake 3.8 include the following.
|
||||||
|
|
||||||
|
New Features
|
||||||
|
============
|
||||||
|
|
||||||
|
Languages
|
||||||
|
---------
|
||||||
|
|
||||||
|
* ``CUDA`` is now supported by the :ref:`Visual Studio Generators`
|
||||||
|
for VS 2010 and above. This complements the existing support by the
|
||||||
|
:ref:`Makefile Generators` and the :generator:`Ninja` generator.
|
||||||
|
CUDA 8.0.61 or higher is recommended due to known bugs in the VS
|
||||||
|
integration by earlier versions.
|
||||||
|
|
||||||
|
* CMake is now aware of the :prop_tgt:`C++ standards <CXX_STANDARD>` and
|
||||||
|
:prop_tgt:`C standards <C_STANDARD>` and their associated meta-features for
|
||||||
|
the following :variable:`compiler ids <CMAKE_<LANG>_COMPILER_ID>`: ``Cray``,
|
||||||
|
``PGI``, and ``XL``.
|
||||||
|
|
||||||
|
Generators
|
||||||
|
----------
|
||||||
|
|
||||||
|
* :ref:`Visual Studio Generators` for VS 2010 and above learned to support
|
||||||
|
the ``ASM_NASM`` language when ``nasm`` is installed.
|
||||||
|
|
||||||
|
* The :generator:`Xcode` generator learned to create Xcode schema files.
|
||||||
|
This is an experimental feature and can be activated by setting the
|
||||||
|
:variable:`CMAKE_XCODE_GENERATE_SCHEME` variable to a ``TRUE`` value.
|
||||||
|
|
||||||
|
* The :generator:`Xcode` generator now supports Xcode 9.
|
||||||
|
|
||||||
|
Commands
|
||||||
|
--------
|
||||||
|
|
||||||
|
* The :command:`add_library` command ``IMPORTED`` option learned to support
|
||||||
|
:ref:`Object Libraries`.
|
||||||
|
|
||||||
|
* All ``find_`` commands now have a ``PACKAGE_ROOT`` search path group that
|
||||||
|
is first in the search heuristics. If a ``find_`` command is called from
|
||||||
|
inside a find module, then the CMake variable and environment variable named
|
||||||
|
``<PackageName>_ROOT`` are used as prefixes and are the first set of paths
|
||||||
|
to be searched.
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
* The :command:`install(TARGETS)` command learned a new ``OBJECTS`` option to
|
||||||
|
specify where to install :ref:`Object Libraries`.
|
||||||
|
|
||||||
|
* The :command:`install(EXPORT)` command learned how to export
|
||||||
|
:ref:`Object Libraries`.
|
||||||
|
|
||||||
|
* The :command:`project` command learned an optional ``DESCRIPTION``
|
||||||
|
parameter to set the :variable:`PROJECT_DESCRIPTION` variable.
|
||||||
|
|
||||||
|
* The :command:`separate_arguments` command gained a ``NATIVE_COMMAND`` mode
|
||||||
|
that performs argument separation depending on the host operating system.
|
||||||
|
|
||||||
|
Variables
|
||||||
|
---------
|
||||||
|
|
||||||
|
* A :variable:`CMAKE_ANDROID_NDK_DEPRECATED_HEADERS` variable was added
|
||||||
|
for use when :ref:`Cross Compiling for Android with the NDK` to request
|
||||||
|
use of the deprecated headers even when unified headers are available.
|
||||||
|
The default is now to use unified headers if available.
|
||||||
|
|
||||||
|
* A :variable:`CMAKE_AUTOMOC_DEPEND_FILTERS` variable was introduced to
|
||||||
|
allow :variable:`CMAKE_AUTOMOC` to extract additional dependency file names
|
||||||
|
for ``moc`` from the contents of source files.
|
||||||
|
|
||||||
|
* A :variable:`CMAKE_AUTOUIC_SEARCH_PATHS` variable was introduced to
|
||||||
|
allow :variable:`CMAKE_AUTOUIC` to search for ``foo.ui`` in more
|
||||||
|
places than the vicinity of the file including ``ui_foo.h``.
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
* A :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable was added to
|
||||||
|
initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all
|
||||||
|
targets.
|
||||||
|
|
||||||
|
* 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``.
|
||||||
|
|
||||||
|
* The :variable:`CMAKE_SYSROOT_COMPILE` and :variable:`CMAKE_SYSROOT_LINK`
|
||||||
|
variables were added to use separate sysroots for compiling and linking.
|
||||||
|
|
||||||
|
Properties
|
||||||
|
----------
|
||||||
|
|
||||||
|
* A new :prop_tgt:`AUTOGEN_BUILD_DIR` target property was introduced to set
|
||||||
|
a custom output directory for :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC`,
|
||||||
|
and :prop_tgt:`AUTORCC`.
|
||||||
|
|
||||||
|
* A new :prop_tgt:`AUTOMOC_DEPEND_FILTERS` target property was introduced to
|
||||||
|
allow :prop_tgt:`AUTOMOC` to extract additional dependency file names
|
||||||
|
for ``moc`` from the contents of source files.
|
||||||
|
|
||||||
|
* A new :prop_tgt:`AUTOUIC_SEARCH_PATHS` target property was introduced to
|
||||||
|
allow :prop_tgt:`AUTOUIC` to search for ``foo.ui`` in more
|
||||||
|
places than the vicinity of the file including ``ui_foo.h``.
|
||||||
|
|
||||||
|
* 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`.
|
||||||
|
|
||||||
|
* 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``.
|
||||||
|
|
||||||
|
* A :prop_tgt:`CUDA_PTX_COMPILATION` target property was added to
|
||||||
|
:ref:`Object Libraries` to support compiling to ``.ptx`` files
|
||||||
|
instead of host object files.
|
||||||
|
|
||||||
|
* 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`).
|
||||||
|
|
||||||
|
* 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`.
|
||||||
|
|
||||||
|
* 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``).
|
||||||
|
|
||||||
|
Modules
|
||||||
|
-------
|
||||||
|
|
||||||
|
* A :module:`CheckIPOSupported` module was added to help projects
|
||||||
|
check whether interprocedural optimization (IPO) is supported by
|
||||||
|
the current toolchain and CMake version.
|
||||||
|
|
||||||
|
* The :module:`CMakeFindDependencyMacro` module ``find_dependency`` macro
|
||||||
|
now forwards all arguments to the underlying :command:`find_package`
|
||||||
|
call. Existing uses will continue to function as before, but callers can
|
||||||
|
now access the full suite of arguments that ``find_package`` accepts.
|
||||||
|
|
||||||
|
* The :module:`FeatureSummary` module :command:`feature_summary` command now
|
||||||
|
accepts the new ``DEFAULT_DESCRIPTION`` option that will print the default
|
||||||
|
title for the selected package type.
|
||||||
|
|
||||||
|
* The :module:`FeatureSummary` module gained a new
|
||||||
|
:variable:`FeatureSummary_<TYPE>_DESCRIPTION` variable that 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.
|
||||||
|
|
||||||
|
* The :module:`FindDoxygen` module learned to control Doxygen behavior using
|
||||||
|
CMake variables and generate documentation via the newly added
|
||||||
|
:command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``)
|
||||||
|
is automatically generated and doxygen is run as part of a custom target.
|
||||||
|
Additional components can be specified to find optional tools: ``dot``,
|
||||||
|
``mscgen`` and ``dia``.
|
||||||
|
|
||||||
|
* The :module:`FindMPI` module now provides imported targets.
|
||||||
|
|
||||||
|
* The :module:`FindProtobuf` module :command:`protobuf_generate_cpp`
|
||||||
|
command gained an ``EXPORT_MACRO`` option to specify the name of
|
||||||
|
a DLL export markup macro.
|
||||||
|
|
||||||
|
* The :module:`FindProtobuf` module now supports usage of static libraries
|
||||||
|
for Unix via a new ``Protobuf_USE_STATIC_LIBS`` input variable.
|
||||||
|
|
||||||
|
* The :module:`FindProtobuf` module now provides imported targets
|
||||||
|
when the libraries are found.
|
||||||
|
|
||||||
|
* A new :module:`GoogleTest` module was added to provide the
|
||||||
|
:command:`gtest_add_tests` function independently of the :module:`FindGTest`
|
||||||
|
module. The function was also updated to support keyword arguments, with
|
||||||
|
functionality expanded to allow a test name prefix and suffix to be
|
||||||
|
specified, the dependency on the source files to be optional and the list of
|
||||||
|
discovered test cases to be returned to the caller.
|
||||||
|
|
||||||
|
CTest
|
||||||
|
-----
|
||||||
|
|
||||||
|
* The :command:`ctest_submit` command gained a ``HTTPHEADER`` option
|
||||||
|
to specify custom headers to send during submission.
|
||||||
|
|
||||||
|
* The :manual:`ctest(1)` executable gained new options which allow the
|
||||||
|
developer to disable automatically adding tests to the test set to satisfy
|
||||||
|
fixture dependencies. ``-FS`` prevents adding setup tests for fixtures
|
||||||
|
matching the provided regular expression, ``-FC`` prevents adding cleanup
|
||||||
|
tests for matching fixtures and ``-FA`` prevents adding any test for matching
|
||||||
|
fixtures.
|
||||||
|
|
||||||
|
* A :prop_test:`DISABLED` test property was added to mark tests that
|
||||||
|
are configured but explicitly disabled so they do not run.
|
||||||
|
|
||||||
|
CPack
|
||||||
|
-----
|
||||||
|
|
||||||
|
* The :module:`CPackArchive` module learned to modify the filename
|
||||||
|
per-component. See the :variable:`CPACK_ARCHIVE_FILE_NAME` variable and
|
||||||
|
its per-component version :variable:`CPACK_ARCHIVE_<component>_FILE_NAME`.
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
* The :module:`CPackIFW` module :command:`cpack_ifw_configure_component` and
|
||||||
|
:command:`cpack_ifw_configure_component_group` commands gained
|
||||||
|
internationalization support for ``DISPLAY_NAME`` and ``DESCRIPTION``
|
||||||
|
options.
|
||||||
|
|
||||||
|
* The :module:`CPackIFW` module learned the new hint :variable:`CPACK_IFW_ROOT`
|
||||||
|
variable for finding the QtIFW tool suite installed in a non-standard place.
|
||||||
|
|
||||||
|
* The :module:`CPackProductBuild` module gained a new
|
||||||
|
:variable:`CPACK_PRODUCTBUILD_RESOURCES_DIR` variable to
|
||||||
|
specify resources to be copied into the ``Resources``
|
||||||
|
directory.
|
||||||
|
|
||||||
|
* The :module:`CPackRPM` module learned to modify the ``debuginfo`` package
|
||||||
|
name. See the :variable:`CPACK_RPM_DEBUGINFO_FILE_NAME` variable.
|
||||||
|
|
||||||
|
* The :module:`CPackWIX` module patching system now has the ability to set
|
||||||
|
additional attributes. This can be done by specifying attributes with
|
||||||
|
the ``CPackWiXFragment`` XML tag after the ``Id`` attribute.
|
||||||
|
See the :variable:`CPACK_WIX_PATCH_FILE` variable.
|
||||||
|
|
||||||
|
* 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``.
|
||||||
|
|
||||||
|
Other
|
||||||
|
-----
|
||||||
|
|
||||||
|
* Interprocedural optimization (IPO) is now supported for GNU and Clang
|
||||||
|
compilers using link time optimization (LTO) flags. See the
|
||||||
|
:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property and
|
||||||
|
:module:`CheckIPOSupported` module.
|
||||||
|
|
||||||
|
* The ``TARGET_OBJECTS``
|
||||||
|
:manual:`generator expression <cmake-generator-expressions(7)>`
|
||||||
|
is now supported by the :command:`add_custom_command` and
|
||||||
|
:command:`file(GENERATE)` commands.
|
||||||
|
|
||||||
|
* 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>``.
|
||||||
|
The new expressions are helpful to query Bundle locations independent of
|
||||||
|
the different Bundle types and layouts on macOS and iOS.
|
||||||
|
|
||||||
|
Deprecated and Removed Features
|
||||||
|
===============================
|
||||||
|
|
||||||
|
* An explicit deprecation diagnostic was added for policies ``CMP0036``
|
||||||
|
and below. The :manual:`cmake-policies(7)` manual explains that the
|
||||||
|
OLD behaviors of all policies are deprecated and that projects should
|
||||||
|
always port to the NEW behaviors as soon as possible.
|
||||||
|
|
||||||
|
* The :generator:`Visual Studio 8 2005` generator is now deprecated
|
||||||
|
and will be removed in a future version of CMake.
|
||||||
|
|
||||||
|
* The :generator:`Visual Studio 7 .NET 2003` generator has been removed.
|
||||||
|
|
||||||
|
* The :generator:`Xcode` generator dropped support for Xcode versions
|
||||||
|
older than 3.
|
||||||
|
|
||||||
|
* The :module:`FindDoxygen` module has deprecated several variables.
|
||||||
|
|
||||||
|
* 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.
|
||||||
|
|
||||||
|
Other Changes
|
||||||
|
=============
|
||||||
|
|
||||||
|
* When using :prop_tgt:`AUTOMOC`, CMake now 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 search for the respective header file
|
||||||
|
now looks in the :prop_tgt:`INCLUDE_DIRECTORIES` of the target as well.
|
||||||
|
|
||||||
|
* When running tests, CTest learned to treat skipped tests (using the
|
||||||
|
:prop_test:`SKIP_RETURN_CODE` property) the same as tests with the new
|
||||||
|
:prop_test:`DISABLED` property. Due to this change, CTest will not indicate
|
||||||
|
failure when all tests are either skipped or pass.
|
||||||
|
|
||||||
|
* The :generator:`Ninja` generator has loosened the dependencies of object
|
||||||
|
compilation. Object compilation now depends only on custom targets
|
||||||
|
and custom commands associated with libraries on which the object's target
|
||||||
|
depends and no longer depends on the libraries themselves. Source files
|
||||||
|
in dependent targets may now compile without waiting for their targets'
|
||||||
|
dependencies to link.
|
||||||
|
|
||||||
|
* On macOS, the default application bundle ``Info.plist`` file now enables
|
||||||
|
Hi-DPI support.
|
||||||
|
|
||||||
|
* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH`
|
||||||
|
no longer affect the ``install_name`` field. See policy :policy:`CMP0068`.
|
||||||
|
|
||||||
|
* The :generator:`Visual Studio 14 2015` generator has been taught about
|
||||||
|
a change to the ``v140`` toolset made by a VS 2015 update. VS changed
|
||||||
|
the set of values it understands for the ``GenerateDebugInformation``
|
||||||
|
linker setting that produces the ``-DEBUG`` linker flag variants.
|
||||||
@ -0,0 +1,9 @@
|
|||||||
|
CMAKE_ANDROID_NDK_DEPRECATED_HEADERS
|
||||||
|
------------------------------------
|
||||||
|
|
||||||
|
When :ref:`Cross Compiling for Android with the NDK`, this variable
|
||||||
|
may be set to specify whether to use the deprecated per-api-level
|
||||||
|
headers instead of the unified headers.
|
||||||
|
|
||||||
|
If not specified, the default will be *false* if using a NDK version
|
||||||
|
that provides the unified headers and *true* otherwise.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -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.
|
||||||
@ -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`
|
||||||
@ -1,15 +1,50 @@
|
|||||||
CMAKE_GENERATOR_TOOLSET
|
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
|
Some CMake generators support a toolset specification to tell the
|
||||||
build system to choose a compiler. If the user specifies a toolset
|
native build system how to choose a compiler. If the user specifies
|
||||||
name (e.g. via the :manual:`cmake(1)` ``-T`` option) the value will be
|
a toolset (e.g. via the :manual:`cmake(1)` ``-T`` option) the value
|
||||||
available in this variable.
|
will be available in this variable.
|
||||||
|
|
||||||
The value of this variable should never be modified by project code.
|
The value of this variable should never be modified by project code.
|
||||||
A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
|
A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
|
||||||
variable may initialize ``CMAKE_GENERATOR_TOOLSET``. Once a given
|
variable may initialize ``CMAKE_GENERATOR_TOOLSET``. Once a given
|
||||||
build tree has been initialized with a particular value for this
|
build tree has been initialized with a particular value for this
|
||||||
variable, changing the value has undefined behavior.
|
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.
|
||||||
|
|||||||
@ -1,6 +1,6 @@
|
|||||||
CMAKE_HOST_WIN32
|
CMAKE_HOST_WIN32
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
``True`` on Windows systems, including Win64.
|
``True`` if the host system is running Windows, including Windows 64-bit and MSYS.
|
||||||
|
|
||||||
Set to ``true`` when the host system is Windows and on Cygwin.
|
Set to ``false`` on Cygwin.
|
||||||
|
|||||||
@ -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.
|
||||||
@ -0,0 +1,8 @@
|
|||||||
|
CMAKE_INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
|
||||||
|
-------------------------------------------
|
||||||
|
|
||||||
|
Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>` of targets.
|
||||||
|
|
||||||
|
This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_<CONFIG>`
|
||||||
|
property on all the targets. See that target property for additional
|
||||||
|
information.
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue