Moved documentation of file(GET_RUNTIME_DEPENDENCIES ...) from
the 'Reading' section to a separate section at the bottom of
the page. Because it is a very long text, and because this
signature is quite different from all the others in the
'Reading' section.
Re-organize the section to explicitly describe target-specific
commands, build properties, and usage requirement properties.
Add builtin transitive properties that have been created since
the document was first written.
a61c9afdf8 add_library: Reject shared libraries on platforms that do not support them
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !9347
The note regarding commands superseded by install() somehow wound
up nested under the install(EXPORT) signature, when it has nothing
to do with install(EXPORT). Move it to the top level, immediately
before the Examples section.
6ba2bbc0f3 Help: Restructure and improve LINKER_TYPE docs
c39bc6e412 Help: CMAKE_<LANG>_USING_LINKER_<TYPE> can be a list of flags
1c7ccefd83 Help: Add custom linker example for CMAKE_<LANG>_USING_LINKER_<TYPE>
aecea7b28b Help: Grammar, typos and wording improvements for linker variables
5b21897c6e Help: Remove stray formatting for try_compile() LINKER_LANGUAGE keyword
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9362
Specifically, the various CMAKE_PROJECT_...INCLUDE... variables can
now take a list of things, and those things can be module names
too, not just file names.
Under job server integration, added by commit 80fe56c481 (ctest: Add
support for running under a make job server on POSIX systems,
2023-11-15, v3.29.0-rc1~324^2), use a very high default so that
parallelism is effectively limited only by available job server tokens.
Otherwise, choose a default limit based on the number of processors.
Also allow passing `0` to specify unbounded parallelism.
Fixes: #25739
Add a section to the `define_property()` documentation which
details the behavior when attempting to redefine an existing
property. (The command is silently ignored.)
Provide an example using `get_property()` to examine a property
definition created with `define_property()`.
Add tests to cover these cases:
* run as regular CMake module, in NORMAL_MODE (expected to fail);
* run as CMake script in SCRIPT_MODE (expected to exit with given code);
* run as CMake script that `include()`-s another script with EXIT subcommand;
* run as CMake script which EVAL-uates EXIT subcommand via
`cmake_language(EVAL CODE "<cmake code>")`.
Fixes: #23162
Since ff6234509e (Help: Clarify behavior of INHERITED properties, 2018-03-21),
the docs for some get_..._property() commands incorrectly describe
the behavior for inherited properties. When a property is not set, even
in a parent scope, the returned result from the get_..._property()
command is the same whether the property is inherited or not.
The docs incorrectly stated that an empty string would be returned
for inherited properties in such cases.
Property-related commands used a mix of <VAR>, <var>, or
<variable> to specify the variable to store the result in. The <VAR>
form is particularly confusing, since being uppercase it looks more
like a keyword. Use <variable> consistently across all the commands
so that the behavior is clear.
The cmake.vim file is generated by scanning for keyword-like
strings in the docs. Update the corresponding wrong entry
there too directly for now, which will fix the wrong entry until
the next full regeneration of the file.
Fixes: #25503
e831eef933 Help: Note case where IMPORTED_IMPLIB isn't needed for (xc)frameworks
01735badee Help: XCFrameworks and stubs are supported on all Apple, not just macOS
6ac50df591 Help: Add missing versionadded directives for IMPORTED_IMPLIB
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9058
e831eef933 Help: Note case where IMPORTED_IMPLIB isn't needed for (xc)frameworks
01735badee Help: XCFrameworks and stubs are supported on all Apple, not just macOS
6ac50df591 Help: Add missing versionadded directives for IMPORTED_IMPLIB
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9058
This allows individual signatures to be cross-referenced from elsewhere.
It also associates with each signature its main documentation via
indentation.
This allows individual signatures to be cross-referenced from elsewhere.
It also associates with each signature its main documentation via
indentation.
This signature was added by commit 4391913133 (Add INTERFACE libraries
to generated buildsystem if they have SOURCES, 2020-07-20,
v3.19.0-rc1~346^2~1) with incorrect documentation.
Previously the documented signature as:
add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
which is incorrect. CMake would recognize `EXCLUDE_FROM_ALL` as a source
file and report an error that it doesn't exists.
The correct signature is:
add_library(<name> INTERFACE [EXCLUDE_FROM_ALL] [<source>...])
which places `EXCLUDE_FROM_ALL` in the same position used by the
documentation of other signatures.
Fixes: #25463
bb7a0497ef cmTransformDepfile: warn when a depfile is not written to
c22c473bde Tests/Ninja*/CustomCommandDepfile: check that deps are in the database
b0177003e1 cmGlobalNinjaGenerator: tell `ninja` to actually read the depfile
45eff9145e cmAddCustomCommandCommand: use `cmStrCat`
c6445c615b Tests/RunCMake/Ninja: fix subdir prefix check
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !8911
But only do so if the depfile is not specified as an output of the
command. Otherwise the command will out-of-date itself as `ninja`
deletes depfiles that it incorporates into the database and a missing
output will cause the command to run again.
8f9f371668 try_compile: Add support for using ALIAS targets
9f8aa94192 Add missing `OUTPUT` in ExportImport test
Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !8877
In commit 8d7e80cf3d (find_* commands: add control over Windows registry
views, 2022-04-16, v3.24.0-rc1~201^2) this indentation was used for the
other find commands but was left out for `find_package`.
This requires knowing when a generated header is public, which we can
model using file sets. Add policy CMP0154 to treat generated sources
as private by default in targets with file sets. Generated public
headers can be specified in public file sets.
Fixes: #24959
Issue: #15555
Since commit ffc06c1239 (Teach find_(library|file|path) to get prefixes
from PATH, 2015-02-18, v3.3.0-rc1~430^2) we search in `<prefix>/include`
and `<prefix>/lib` directories for prefixes with `bin` directories in
the `PATH` environment variable. The motivation was to search the
installation prefixes of MSYS and MinGW development environments
automatically.
This behavior can search undesired prefixes that happen to be in the
`PATH` for unrelated reasons. It was reverted for non-Windows hosts
within a year by commit b30b32a493 (Drop find_(library|file|path)
prefixes from PATH on non-Windows, 2016-05-09, v3.6.0-rc1~82^2) but was
kept on Windows hosts to support its motivating use case. However,
similar problems have since been observed on Windows. For example,
commit 955d6245c1 (MSVC: Revert "Teach find_library to consider the
'libfoo.a' naming convention", 2022-11-28, v3.25.1~6^2) was primarily
due to undesired discovery of libraries in `PATH`-derived prefixes.
Since commit 5e5132e1b1 (MinGW: Search for packages in standard MSYSTEM
environment prefixes, 2023-09-11) we search MSYS and MinGW environments'
prefixes explicitly, so `PATH`-derived prefixes are no longer needed for
the original motivating use case.
Fixes: #24216
Document the deprecation warnings added by commit 5845c218d7 (Deprecate
compatibility with CMake versions older than 2.8.12, 2020-06-12,
v3.19.0-rc1~629^2) and commit 3a4791548d (Deprecate compatibility with
CMake versions older than 3.5, 2023-02-09, v3.27.0-rc1~508^2).
Fixes: #25196
be53c75852 cmExperimental: recycle the C++ modules API UUID
deb1c3cbd5 cmCoreTryCompile: forward module-related binutils variables
b768d293c5 cmCoreTryCompile: use the source type context for source files
93993c7ad4 cmArgumentParser: support storing a context value with parsing
c9ca5f6326 cmCoreTryCompile: parse `SOURCES_TYPE` argument
07551f35de cmCoreTryCompile: use `target_sources` for `try_compile` targets
aad9033b56 cmExperimental: support forwarding associated variables to `try_compile`
f6cf433256 cmExperimental: only forward C++ module support to non-ABI checks
...
Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Merge-request: !8639
Revise the signature and description to explicitly distinguish the
initial group of artifact options from later groups that apply to
a specific kind.
Issue: #25144Fixes: #16362
After switching to the signature directive we no longer need
per-signature sections. Group all the signatures in one section. Add a
table of contents since it is no longer redundant with the synopsis.
Revert commit f09fda97d8 (Help: improve install() documentation of
argument ordering, 2018-01-08, v3.11.0-rc1~126^2). Although the
example it added is correct, its explanation is misleading.
Revert it to make room for an alternative.
Issue: #25144
Issue: #16362
2b99e64413 set_test_properties: link to the test properties in the documentation
b11e8afbfa ctest: export test labels to junit xml
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !8635
Previously REAL_PATH would collapse paths before resolving any symlinks
so if `..` crossed a symlink the output from `REAL_PATH` would be wrong.
It looked like REAL_PATH did this by mistake since it was a side-effect
of ensuring we had an absolute path before resolving symlinks.
Suggest the `CMAKE_MAP_IMPORTED_CONFIG_<CONFIG>` variable for mapping
configurations of dependent projects to configurations exported by these
commands.
Issue: #25096
e588d29eaf Help: add_custom_command(TARGET) does not support USES_TERMINAL
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: William Jones <william.luke.jones@gmail.com>
Merge-request: !8602
e588d29eaf Help: add_custom_command(TARGET) does not support USES_TERMINAL
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: William Jones <william.luke.jones@gmail.com>
Merge-request: !8602
In commit b787be2714 (Help: Update supported languages in project and
enable_language, 2023-01-20, v3.26.0-rc1~53^2) the relevant paragraph
was accidentally moved to the `enable_language` command documentation.
Fixes: #25016
Projects can use the new command to request file API replies for the current
run. No query files are generated, the query is tracked internally. Replies are
created in the file system at generation time in the usual way.
Fixes: #24951
The configure_file(...) and string(CONFIGURE ...) functions also
substitutes variables of the form: $CACHE{VAR} and $ENV{VAR}.
Therefore add this information to the help documentation so that this
behavior is described to users
The documentation of the find-commands was pointing to the
cmake variables CMAKE_PREFIX_PATH, CMAKE_INCLUDE_PATH etc.
also in the section for environment variables. Now they point
to the documentation for the respective environment variables.
In commit fa45594407 (file(GET_RUNTIME_DEPENDENCIES): Preserve casing
for Windows PE binaries, 2023-03-06) we neglected to update associated
documentation.
Also call out possible exposure of an existing cache entry of the same
name, as we have for the `unset` command since commit 1a0f1a25a4 (Help:
Clarify the unset command, 2018-08-17, v3.13.0-rc1~199^2).
Issue: #24633
Convert `file` command to use new `signature` directive. Use '<HASH>'
rather than 'HASH' for relevant signature targets, as this is arguably
more correct, results in less need to specify explicit targets, but
still produces '#hash' as the HTML anchor.
Although actual textual changes to `file` are fairly minimal, large
portions of the content have been re-indented and in many cases,
re-flowed. Some tabular content in literal text blocks has also been
converted to actual tables.
Convert documentation of the `list` and `set` commands to use new
`signature` directive. Use new `cref` role in the `list` introduction so
that the subcommands there are links rather than just text. Turn
references into `string` subcommands into actual links. Reformat some
prose as definition lists.
Some servers have allow-lists for HTTP UserAgent for example.
CMake project devs would benefit from this hint about setting
authorization tokens and HTTP User Agent.
Extend commit eb35d8884b (find_package: Use PackageName_ROOT variables
as search prefixes, 2018-03-15, v3.12.0-rc1~349^2) to also check
upper-case `<PACKAGENAME>_ROOT` variables. Add policy `CMP0144` to
enable the behavior in a compatible way.
Fixes: #24403
Add CMake variable `CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY` to enable
option `DEPENDS_EXPLICIT_ONLY` on all uses of `add_custom_command`.
Fixes: #17097
* enable_testing must be called to enable testing
* can only set properties on tests created in same directory
* WILL_FAIL still fails on segfault and similar
* compact wording
Add option `DEPENDS_EXPLICIT_ONLY` to `add_custom_command` to indicate
that implicit dependencies coming from users of the output are not
needed, and only consider dependencies explicitly specified in the
custom command.
Fixes: #17097
e7f7bff4f5 Kate: improve the way the VCS-specific files are searched
96389b4cd3 Kate: add support for hg and fossil
4c32623f5f Help: fix typo in docs for set_property()
9a7612d2d0 Kate: make it possible to force a mode for the "files" entry
8a7aa2642b Help: add documentation for Kate-related variable
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Merge-request: !8154
