GitLab

This was added in Git 2.25 (13 Jan 2020).

This enables cross-reference syntax for CMake generator expressions:

    :genex:`SOME_GENEX`
    :genex:`$<SOME_GENEX>`
    :genex:`$<SOME_GENEX:...>`

and definition of CMake generator expressions via a directive:

    .. genex:: SOME_GENEX
    .. genex:: $<SOME_GENEX>
    .. genex:: $<SOME_GENEX:...>

It also adds generator expressions defined by the directive and by
`Help/genex/SOME_GENEX.rst` documents to the index.

This was accidentally left out of commit 2a2829cc (Help: Add new
section for CPack generators, 2018-06-15, v3.13.0-rc1~394^2~3).

This was accidentally left out of commit 8acf46ca (Utilities/Sphinx:
Add role and directive for 'envvar' in CMake domain, 2018-04-19,
v3.12.0-rc1~200^2~1).

Optionally enable this infrastructure through an undocumented
`CMAKE_EXPERIMENTAL_CXX_MODULE_DYNDEP` variable.  Currently this is
experimental and intended for use by compiler writers to implement their
scanning tools.  Warn as such when the feature is activated.  Later when
compilers provide the needed scanning tools we can enable this variable
from our corresponding compiler information modules.  It is never meant
to be set by project code.

When enabled, generate a build graph similar to what we use for Fortran
module dependencies.  There are some differences needed because we can
scan dependencies without explicit preprocessing, and can directly
compile the original source afterward.

Co-Author: Ben Boeckel <ben.boeckel@kitware.com>

Initialize it with placeholder content.  This document will serve to
contain documentation for experimental features that are under
development and not yet included in official documentation.

Using `git describe --contains` is the preferred way to reference a
commit relative to a tag.

Jean-Christophe Fillion-Robin authored Jul 21, 2020 and Brad King committed Jul 22, 2020

See https://github.com/codespell-project/codespell#readme

The following command was used:

```
codespell -q6 --skip="\
.git,\
*.json,\
./Copyright.txt,\
./Help/command/foreach.rst,\
./Help/prop_test/REQUIRED_FILES.rst,\
./Help/variable/CTEST_COVERAGE_COMMAND.rst,\
./Modules/CMakeCheckCompilerFlagCommonPatterns.cmake,\
./Modules/CMakeRCInformation.cmake,\
./Modules/Internal/CPack/NSIS.template.in,\
./Modules/FindMatlab.cmake,\
./Modules/MatlabTestsRedirect.cmake,\
./Modules/Platform/Windows-Clang.cmake,\
./Modules/Platform/Windows-Intel-Fortran.cmake,\
./Modules/Platform/Windows-MSVC.cmake,\
./Source/CMakeVersion.cmake,\
./Source/cmConvertMSBuildXMLToJSON.py,\
./Source/cmCreateTestSourceList.cxx,\
./Source/cmGlobalVisualStudio10Generator.cxx,\
./Source/cmExportBuildFileGenerator.cxx,\
./Source/cmExportInstallAndroidMKGenerator.cxx,\
./Source/cmExportInstallFileGenerator.cxx,\
./Source/cmExportSet.cxx,\
./Source/cmExportTryCompileFileGenerator.cxx,\
./Source/cmFindPacka...

Brad King authored Jun 12, 2020 and Craig Scott committed Jun 13, 2020

Document steps for deprecating old policy settings and future-proofing
export files generated by `install(EXPORT)`.

We have replaced use of `buildbot` with GitLab CI.  Update the
relevant section of our review process documentation.

GitLab now uses a `/-/` component between the `group/project` part of
the URL and the `{issues,merge_requests,tree}` part so that it can
support `group/subgroup/project` with arbitrary depth.

Fixes: #20666

Marc Chevrier authored Mar 12, 2020 and Craig Scott committed Mar 14, 2020

We now offer many C++14, C++17, C++20, and custom extensions to the C++
standard library that are available even when compiling as C++11.

This was accidentally left out of commit 49f5b6f7 (Help: Document the
expire and external discussion resolve states, 2019-05-26,
v3.15.0-rc1~35^2).

Replace the post-release development announcement to the mailing list
with a post to the appropriate category on `discourse.cmake.org`.

Revert the change from commit 7b354baa (CMakeVersion: Set
CMake_VERSION_RC to 0 even in non-rc versions, 2019-07-25) and instead
define a `0` value in `CMake_VERSION_RC` to mean `-rc0`.  This
distinguishes release branch versions prior to the first release
candidate from the first release candidate itself.  It also makes room
for a dedicated "CMake $major.$minor.0-rc1" release commit for `-rc1` as
we have for later release candidates and final releases.

The logic that uses this value already ignores any "false" value, so `0`
is just as good as not being set at all.  Using `0` for this role makes
the version components look more symmetric and reduces the number of
edits needed when creating releases.

Our practice of closing MRs temporarily while discussion
takes place in a separate issue isn't always well understood
by MR authors. Expiring a MR seems to be better understood,
but making it clear that it is also a temporary state is helpful.

Read the version from `Source/CMakeVersion.cmake` instead of repeating it.

The logic is that the describe output is readily available using `git
tag --contains` locally. In addition, for a hypothetical commit which
landed in both v3.9.4 and v3.10.1, there is no "better" tag to refer to.
since v3.10.0's relation to such a commit is unclear either way.

Also mention that a `Fixes` trailer is preferred if the mention is just
to indicate a commit which introduced an error rather than writing a
complete sentence about it.

Remove this content from the `cmake-developer(7)` manual because it
is relevant only to developers working on CMake itself.  Move it to
a guide in the developer documentation.

We now use `std::size_t` in several places and it is fully supported by
C++11 compilers.  Drop the recommendation to prefer plain `size_t`.

The Maintain Current Release instructions previously assumed that
the topic branch had been merged to master. Add text to make this
explicit in the instructions as an initial verification step.

The previous instructions also made no mention of the commit
message for the merge to the release branch. This needs to include
a footer that mentions the merge request number for tracking
purposes.

Update `.clang-format` with configuration to make the 6.0 format as
close as possible to what 3.8 produced before.  Then revise the style:

* Indent preprocessor directives (a feature new since 3.8)
* Add a newline and indentation before inheritance `:` and `,`

Rename the Git attribute identifying the format to include the
clang-format version number: `format.clang-format-6.0`.  This will aid
external infrastructure in knowing what version of the tool to run.