As part of the general restructuring, also move the notes of a more
introductory nature out of what was the "String-Valued Generator
Expressions" section and up to the dedicated Introduction. This gives
the reader a bit more of a foundation before they get to the heavier
detail of the reference section.
This involves moving the Debugging section up to just after the
introduction. The content of that section is unchanged.
The reference section then follows, and since it is a dedicated
section, all existing sections thereunder were demoted one level.
Move the note about deviating from the usual CMake docs convention
of using angle brackets around placeholders out of the Introduction
and to the start of the reference section. No placeholders are used
before that point, so that content no longer belongs in the introduction.
Apply some minor wording cleanup to the content in the Introduction
that remained.
These changes restructure the docs to improve readability and flow,
correct grammar and typos, and fix errors and inconsistencies in
some of the examples.
Fixes: #23684
The new sub-command writes a string representation of the
current log level to the output variable given to the
sub-command.
Given that the log-level might be set either via the --log-level
command line option or via the CMAKE_MESSAGE_LOG_LEVEL
cache / regular variables, the priority for each of the log level
sources is as follows, with the first one being the highest:
1) --log-level
2) CMAKE_MESSAGE_LOG_LEVEL regular variable
3) CMAKE_MESSAGE_LOG_LEVEL cache variable
4) default log level (STATUS)
Fixes: #23572
Extend the change from commit b764c7c273 (VS: Add property to turn off
Visual Studio compile batching, 2022-02-07, v3.24.0-rc1~710^2) by
adding a variable to initialize the property on every target.
Issue: #23179Fixes: #23639
07bc3b07ec gitlab-ci: test C++ modules using GCC
1b2270aa4e ci: add a Docker image to test out C++ modules with GCC
8c5a53096a Tests/RunCMake/CXXModules: add module-using examples
4151547e2f cmGlobalNinjaGenerator: use `cmModuleMapper` implementation
b43bdaff3c cmCxxModuleMapper: implement support for GCC's module map format
02d0f0e752 cmCxxModuleMapper: add source to handle module mapper contents
a046a45aad cmGlobalNinjaGenerator: add a TODO for header units
386465bf83 cmTarget: add support for C++ module fileset types
...
Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !7369
C++ modules have two variants which are of importance to CMake:
- `CXX_MODULES`: interface modules (those using `export module M;`,
`export module M:part;`, or `module M:internal_part;`)
- `CXX_MODULE_HEADER_UNITS`: importable header units
Creating C++ modules or partitions are *not* supported in any other
source listing. This is because the source files must be installed (so
their scope matters), but not part of usage requirements (what it means
for a module source to be injected into a consumer is not clear at this
moment). Due to the way `FILE_SET` works with scopes, they are a perfect
fit as long as `INTERFACE` is not allowed (which it is not).
Forward `CMAKE_<LANG>_FLAGS` and `CMAKE_<LANG>_FLAGS_DEBUG` from the
calling project into the test project. The set of flags may affect the
availability of IPO support. Since this may change the result of the
check for existing projects, add a policy for compatibility.
This was discovered after commit 5fcadc481e (MSVC: Default to -ZI
instead of /Zi for x86 and x64, 2022-05-24) introduced policy CMP0138 to
switch our default for MSVC's debug info flag. The `-ZI` flag is
incompatible with the `-GL` flag used for IPO, so CMP0138 was reverted
pending future work on an alternative solution. Re-use the CMP0138
policy number for this change to CheckIPOSupported instead.
Fixes: #23607
Revert commit 5fcadc481e (MSVC: Default to -ZI instead of /Zi for x86
and x64, 2022-05-24). The `-ZI` flag is incompatible with the `-GL`
flag used for IPO, and so is not an unconditionally better default.
Revert the change pending future design of a first-class setting for
MSVC debug info format that can be automatically reconciled with IPO
settings.
That commit introduced policy CMP0138, but we already have later policy
numbers used too. Leave placeholder text to avoid policy renumbering.
Issue: #23607, #10189
Add a new property, INTERFACE_HEADER_SETS_TO_VERIFY, which contains
a list of header sets that should be verified by
VERIFY_INTERFACE_HEADER_SETS.
Fixes: #23522
In commit 8d7e80cf3d (find_* commands: add control over Windows registry
views, 2022-04-16) we added documentation that is repeated by multiple
find commands. Move it to a dedicated manual section to avoid duplication.
Add policy CMP0137 to propagate both our builtin variables and those
listed by `CMAKE_TRY_COMPILE_PLATFORM_VARIABLES` to `try_compile`
whole-project builds.
Inspired-by: Alexander Neumann <Alexander.Neumann@hamburg.de>
Fixes: #23219
Add `COMPILE_WARNING_AS_ERROR` target property and supporting
`CMAKE_COMPILE_WARNING_AS_ERROR` variable.
`COMPILE_WARNING_AS_ERROR` is initialized by
`CMAKE_COMPILE_WARNING_AS_ERROR`. It is a boolean variable. If it is
true, it expands to a different flag depending on the compiler such that
any warnings at compile will be treated as errors.
Supports compiler ids that I could find a relevant flag for.
Add a `CMAKE_WATCOM_RUNTIME_LIBRARY` variable to control the
runtime library selection. Add policy CMP0136 to switch to
in place of the old hard-coded default flags.
Fixes: #23178
a693da21f3 Help: from command:if, link to environment variables
ab2bdbaf31 Help: Cross-reference ENV operator from cmake-language(7) manual
ee4e728a69 Help: From Environment Variables section, link to cmake -E env etc
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7239
Add the option to keep the current filestamps when extracting an
archive in ExternalProject_Add.
Enabling this option makes the behavior consistent with how
ExternalProject_Add is used when checking out code from revision
control instead of an archive.
Fixes: #22746
Allow FetchContent_MakeAvailable() to try a call to
find_package() first, or redirect a find_package() call to
FetchContent_MakeAvailable(). The user can set variables
to control which of these are allowed or tried by default.
Fixes: #21687
The `TARGET_BUNDLE_DIR` and `TARGET_BUNDLE_CONTENT_DIR` generator
expressions produce absolute paths. Show them in the examples.
Suggested-by: Ben Leadbetter <ben.leadbetter@native-instruments.com>
b760828d3f CPack/DMG: Do not use CPACK_RESOURCE_FILE_LICENSE for SLA by default
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !7176
Since macOS 12.0 deprecated the tools needed to attach a SLA to a
`.dmg`, we should no longer do this by default. Add a policy to
change the default to off.
Fixes: #22978
When running CMake for the first time in a build tree, for some
generators CMake would set compiler environment variables
like CC, CXX, etc. when the corresponding language is enabled.
That behavior was never documented and can result in different
behavior between the first and subsequent runs. Add a policy
to no longer set those environment variables.
Fixes: #21378
9f1471739d cmake: Add --fresh option to clear the cache and start from scratch
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !7099
Previously we always used content guarded by `$<LINK_ONLY:...>`
in `LINK_LIBRARIES`, even when evaluating for non-linking usage
requirements. Add a policy to honor `LINK_ONLY` in `LINK_LIBRARIES`
the same way we already do in `INTERFACE_LINK_LIBRARIES`.
Similar to GNU tar add a --touch option to the tar extract command to
skip extracting the timestamps from the files in the archive
effectively touching them as if they were just created.
Issue: #22746
Revert commit f3ad061858 (Add usage requirements to update direct link
dependencies, 2022-01-12, v3.23.0-rc1~44^2) and the property storage
updates in its predecessor commit 193a999cd5 (cmTarget: Add
INTERFACE_LINK_LIBRARIES_DIRECT{,_EXCLUDE} backtrace storage,
2022-01-06, v3.23.0-rc1~44^2~1) from the 3.23 release branch.
After initial experience using the feature in practice, additional
design considerations have been raised for discussion in the original
issue. To avoid rushing this for the 3.23 series, we've decided to
revert the feature for now so it can be revised for a future release.
Issue: #22496
Although passing multiple source paths was never documented, it was not
diagnosed by CMake 3.22 and below. In CMake 3.23 we now diagnose extra
paths and warn. Document this change and add a release note.
Issue: #23334
8abd714176 Help: Clarify that ENVIRONMENT test properties take ;-separated lists
02cf404ace Help: Add advice for dealing with semicolons in lists
c4117d9116 ExternalProject: Document that LIST_SEPARATOR works for CMAKE_ARGS too
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !7066
Allow find package to promote scope of imported targets by specifying
an argument to `find_package` or by specifying a CMake variable.
* Add support for CMAKE_GLOBAL_IMPORT_SCOPE variable
* Add support for GLOBAL argument to find_package
Additionally add testing for above features.
fbda79f39d Help: Document explicitly that 'cxx_std_##' features may not add a flag
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: antmak <antmak.pub@gmail.com>
Merge-request: !7043
Add `--test-output-truncation` to `ctest`. This option can be used to
customize which part of the test output is being truncated. Currently
supported values are `tail`, `middle` and `head`.
Also add equivalent `CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION` variable.
Fixes: #23206
9fb1dff070 LINK_LIBRARY: Add features for library support on Apple
93a153bc7f Genx-LINK_LIBRARY: simplify framework features definitions
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7029
Encourage placing preset includes near the beginning of a preset
file and ensure the example shows that usage. Move the prose
discussing includes to its own section to improve discoverability
and break up paragraphs to make each main point harder to miss.
Also clarify ${sourceDir} to remove any ambiguity with regard to
its meaning in included files.
Issue: #23214
To be more consistent between genex and variables as well as
the forecomming LINK_GROUP genex, rename variable *_LINK_USING_<FEATURE>*
in *_LINK_LIBRARY_USING_<FEATURE>*
d92469e572 Help: Clarify how package resolve mode is intended to be used
f320a31087 cmake --build: prioritize --resolve-package-references over preset
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6984
This variable was added by commit 42f74df6d4 (Add basic Android platform
module, 2014-06-06, v3.1.0-rc1~416^2), but was not previously documented.
Fixes: #23227
Always using `_supported_components` causes conflicts when transitive
dependencies also set this variable, e.g., because the developers
followed these code samples.
An even more general approach could be to set
`_${CMAKE_FIND_PACKAGE_NAME}_supported_components` instead, but such a
change should then be applied to other variables for consistency.
Fixes: #23112
After !6954 got merged, it has become easier for tools to get
full stack-traces for runtime traces of a CMake program. The trace
information already included in the JSON objects (line number, source
file path) allows tools that display these stack traces to print the
CMake source code associated to them. However, CMake commands may
spawn multiple lines, and the JSON information associated to a trace
only contains the line in which the command started, but not the one
in which it ended. If tools want to print stack traces along the
relevant source code, and they want to print the whole command
associated to the stack frame, they will have to implement their own
CMake language parser to know where the command ends.
In order to simplify the life of those who want to write tooling for
CMake, this commit adds a `line_end` field to the json-v1 trace
format. If a given command spans multiple lines, the `line_end` field
will contain the line of the last line spanned by the command (that of
the closing parenthesis associated to the command).
To enable the management of incompatible $<LINK_LIBRARY> declarations,
add LINK_LIBRARY_OVERRIDE and LINK_LIBRARY_OVERRIDE_<LIBRARY> target
properties.
This generator expression offers the capability, for the link step, to
decorate libraries with prefix/suffix flags and/or adding any specific flag for each
library.
Fixes: #22812, #18751, #20078, #22703
Tools using the json-v1 format might want to trace stack frames across
different `CMakeLists.txt` files, in order to, for example, provide
stacktraces that span from the top-level `CMakeLists.txt` in a
project. One would think that `frame` lets you do that, but it
doesn't, because it tells you the depth of the stack within the
current `CMakeLists.txt`, so it gets reset across calls to
`add_subdirectory`.
The solution involves adding a field with a "global frame". This value
gets incremented on calls to `add_subdirectory`, which makes it easier
for tools to reconstruct "global stacktraces".
I considered changing the current "frame" value, but I didn't because
it would be a breaking change. I cannot think of any use-case where
"frame" is more useful to "global-frame", but maybe I'm missing
something.
Implements a -- delimiter, that indicates the end of options (starting
with a dash -) of a command and separates them from the subsequent
operands (positional arguments).
The following commands are affected:
- env: Implemented the -- delimiter.
- cat: The -- delimiter was already kind of considered, but its
occurence did not stop the options parsing.
- rm: Here the command already implemented the -- delimiter as
specified, but it was not documented.
Fixes#22970
Mention that system include directories are searched after normal
include directories.
Document that `IMPORTED_NO_SYSTEM` and `NO_SYSTEM_FROM_IMPORTED`
do not affect `INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`.
f3ad061858 Add usage requirements to update direct link dependencies
193a999cd5 cmTarget: Add INTERFACE_LINK_LIBRARIES_DIRECT{,_EXCLUDE} backtrace storage
22d5427aa6 cmGeneratorTarget: Add LookupLinkItem option to consider own target name
f3d2eab36a cmGeneratorTarget: Fix link interface caching of partial results
d75ab9d066 cmGeneratorTarget: Clarify CMP0022 logic in ComputeLinkInterfaceLibraries
f3e9e03fe0 cmGeneratorTarget: Simplify CMP0022 warning check
216aa14997 cmGeneratorTarget: Return early from ExpandLinkItems with no items
1bc98371d1 Tests: Remove unnecessary policy setting from ObjectLibrary test
...
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6886
Link line construction starts with `LINK_LIBRARIES` and appends
dependencies from the transitive closure of `INTERFACE_LINK_LIBRARIES`.
Only the entries of `LINK_LIBRARIES` are considered direct link
dependencies. In some advanced use cases, particularly involving static
libraries and static plugins, usage requirements need to update the list
of direct link dependencies. This may mean adding new items, removing
existing items, or both.
Add target properties to encode these usage requirements:
* INTERFACE_LINK_LIBRARIES_DIRECT
* INTERFACE_LINK_LIBRARIES_DIRECT_EXCLUDE
Fixes: #22496
0c2d234bc9 CMakePresets: Allow files included from CMakePresets.json to be anywhere
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Gerhard Olsson <gerhard.nospam@gmail.com>
Merge-request: !6867
There are some valid use cases for allowing these files to be outside
the project directory. Relax the restriction, and include a strong
warning in the documentation.
These probably should not have been documented as public variables
to begin with. But since they have been documented for a long time,
we can't just remove them from the docs. Move them to the internal
section instead to make it clearer that they are not intended to be used
directly by projects.
0eea32a376 VS: Add DOTNET_SDK property to generate SDK-style C# projects
a450cc9533 VS: Set ResolveNugetPackages to false for ALL_BUILD and ZERO_CHECK
fa76e5d194 cmVisualStudio10TargetGenerator: Factor out helper for classic MSBuild project
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6634
Changes in cmVisualStudio10TargetGenerator::Generate to write .Net
SDK-style project for VS generators VS 19 and above. Also adds
documentation and tests.
Issue: #20227
Optionally verify that items in `LINK_LIBRARIES` and
`INTERFACE_LINK_LIBRARIES` that can be target names are actually target
names. Add a `LINK_LIBRARIES_ONLY_TARGETS` target property and
corresponding `CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable to enable
this new check.
Fixes: #22858
Add a `--debug-find-pkg=` option to debug find calls for specific
packages.
Add a `--debug-find-var=` option to debug find calls for specific
return variables.
Fixes: #21880
250acbb099 Help: Improve cross-referencing of test LABELS and related features
a77bdefa3e Help: Add missing version details for Additional Test Measurements
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6726
Add fields to the VS generator to select a target framework.
Migrate the existing default for VS 12 .NET CF for Windows CE.
Report the values in `CMAKE_VS_*` variables and use them for
the CSharp compiler id project too.
Issue: #22849
This generator expression does not report the locations of `.dll`
files on imported targets with the `UNKNWON` type, since their
`IMPORTED_LOCATION` refers to the import library and not the DLL.
Fixes: #22845
Explain that this represents the compiler's default and mustn't be modified
by the user. Clarify when it's used as the default.
Additionally:
* Add a reference to it in cmake-compile-features in text explaining the
feature.
* Add explanations for the default initialization by
`CMAKE_<LANG>_EXTENSIONS_DEFAULT` to all `<LANG>_EXTENSIONS` pages and
references to CMP0128.
* Slightly reduce the wordiness of the default initialization explanations by
removing an unnecessary "it is".
Fixes#22828.
Due to MCST LCC compiler identification is now changed to LCC,
there should be a way for old projects to still identify it as GNU,
as it was before.
This commits adds the policy:
CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU.
This policy controls such a behavior.
OLD behaivior is to treat LCC as GNU, NEW is to treat is as LCC.
Added XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE variable which
sets the scheme property value for "GPU Frame Capture" in the Options section by setting the Xcode project variable "enableGPUFrameCaptureMode".
Example values are "Metal" (1) and "Disabled" (3).
XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE is initialized by the property CMAKE_XCODE_SCHEME_ENABLE_GPU_FRAME_CAPTURE_MODE.
Implements: #22700
Add an `IMPORTED_NO_SYSTEM` target property to specify this. When
enabled, do not treat the `INTERFACE_INCLUDE_DIRECTORIES` of an imported
target as `SYSTEM` include directories.
This is similar to the existing `NO_SYSTEM_FROM_IMPORTED` property, but
works from the consumed target rather than the consumer.
Fixes: #17364
1851aa49be FetchContent: Pass through networking-related CMAKE_... variables
96937438b7 Help: Clean up how TLS and NETRC variables are discussed
2a82bd85b6 Help: Add documentation for CMAKE_TLS_CAINFO
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6589
The changes are part of CMP0128.
When the standard level is unset:
* Flags are added if extension mode doesn't match the compiler's default.
Previously logic only worked if LANG_EXTENSIONS was ON. Fixes#22224.
* The full flag is used. Previously CMAKE_LANG_EXTENSION_COMPILE_OPTION was
used. This was only supported for IAR.
Otherwise:
* Avoid adding flags if not necessary per the detected compiler defaults.
* Fixed check for when the requested standard is older. It now matches the
nearby comments.
I reworded the fallback comment as its logic was a bit difficult to wrap my
head around.
Add generic documentation to improve the discoverability of language-specific
ones and to make it possible to refer to them generically from other language
generic documentation.
b8d10c27d1 Help: Restructure build type docs and clarify case sensitivity
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Ben Boeckel <ben.boeckel@kitware.com>
Merge-request: !6516
An new environment variable 'CMAKE_INSTALL_MODE' is introduced,
which can be used to ask CMake to create symbolic links
instead of copying files during a file(INSTALL ...).
The operation is at the file level only, directory trees are
still created using actual directories, not links.
Signed-off-by: Felix Lelchuk <felix.lelchuk@gmx.de>
