In a per-component installation the generated installation scripts
are invoked once for each component.
Per default custom installation script code added by install(CODE|SCRIPT)
only runs for one specific component in this context.
The new ALL_COMPONENTS option allows custom script code to be run once
for each component being installed.
`.. versionchanged` directive might be more appropriate when
documentation refers to previous CMake version, old behavior
or a policy, and there's no new parameter or a variable involved.
Issue: #19715
This change ony concerns directives that appear in the document body.
The guidelines for inserting version directives:
* Baseline version is CMake 3.0, i.e. directives start at 3.1.
* Always use `.. versionadded::` directive, avoid ad-hoc version
references. Exception: policy pages.
* For new command signatures, put `versionadded` on a separate line
after the signature.
* For a group of new signatures in a new document section,
a single version note at the beginning of the section is sufficient.
* For new options, put `versionadded` on a separate line before
option description.
* If all the option descriptions in the list are short one-liners,
it's fine to put `versionadded` on the same line as the description.
* If multiple option descriptions in close proximity would have
the same ..versionadded directive, consider adding a single
directive after the list, mentioning all added options.
* For compact value lists and sub-option lists, put a single
`versionadded` directive after the list mentioning all additions.
* When a change is described in a single paragraph, put
`versionadded` into that paragraph.
* When only part of the paragraph has changed, separate the changed
part if it doesn't break the flow. Otherwise, write a follow-up
clarification paragraph and apply version directive to that.
* When multiple version directives are close by, order earlier
additions before later additions.
* Indent related lists and code blocks to include them in the scope
of `versionadded` directive.
Issue: #19715
On AIX, plugins meant to be loaded into executables via `dlopen` must be
linked with access to a list of symbols exported from the executable in
order to use them (when not using runtime linking). The AIX linker
supports specifying this list as an "import file" passed on the command
line either via the `-bI:...` option or (with a leading `#! .` line) as
a normal input file like any other library file.
The linker import file plays the same role on AIX as import libraries do
on Windows. Teach CMake to enable its import library abstraction on AIX
for executables with the `ENABLE_EXPORTS` target property set. Teach
our internal `ExportImportList` script to optionally generate a leading
`#! .` line at the top of the generated export/import list. Update our
rule for linking an executable with exports to generate a public-facing
"import library" implemented as an AIX linker import file.
With this approach, our existing infrastructure for handling import
libraries on Windows will now work for AIX linker import files too:
* Plugins that link to their executable's symbols will be automatically
linked using the import file on the command line.
* The executable's import file will be (optionally) installed and
exported for use in linking externally-built plugins.
This will allow executables and their plugins to build even if we later
turn off runtime linking.
Issue: #19163
Revert commit v3.13.0-rc1~441^2 (install: Teach CODE,SCRIPT modes to
evaluate generator expressions, 2018-05-29). Unfortunately it has
been found to break existing code in a real project, e.g.
install(CODE [[
message("$<FOOBAR>")
]])
Address this regression by reverting support for the 3.13 release
series. Support can be restored later with a policy for compatibility.
Issue: #15785Fixes: #18435
Previously, `install(TARGETS)` would only accept targets created in the same
directory scope. Relax this restriction by searching the global scope when
determining whether or not a target exists.
Fixes: #14444
Summarize the command signatures in one block at the top of the
documentation as is typical in Unix command-line tool manuals.
Make the mode keywords links to the corresponding full signature
and documentation.
Issue: #17948
The "undefined behavior" that the install(EXPORT) command warned about
was simply the possibility of build errors (or other errors) if the
referenced targets aren't installed. As long as the referenced targets
are installed, this won't be an issue.
This file, which is currently undocumented, is useful for external
packaging programs that wish to install only a single component at a
time. This change adds documentation for the file.
`install(EXPORT_ANDROID_MK)` is its own mode, not an option to the
normal `install(EXPORT)` mode.
While at it, also fix the prose in our documented example to match
the code.
Fixes: #17891
Teach the `install` and `export` commands to support installing and
exporting `OBJECT` libraries without their object files. Transform
them to `INTERFACE` libraries in such cases.
For `install(TARGETS)`, activate this when no destination for the object
files is specified. For `export`, activate this only under Xcode with
multiple architectures when we have no well-defined object file
locations to give to clients.
Some are user facing.
Found using
codespell -q 3 --skip="./Utilities" -I .cmake-whitelist.txt`
whereby the whitelist contained:
ans
dum
helpfull
emmited
emmitted
buil
iff
isnt
nto
ot
pathes
substract
te
todays
upto
whitespaces
Teach install() and export() to handle the actual object files.
Disallow this on Xcode with multiple architectures because it
still cannot be cleanly supported there.
Co-Author: Brad King <brad.king@kitware.com>
Add options to the `install()` and `export()` commands to export the
targets we build into Android.mk files that reference them as prebuilt
libraries with associated usage requirements (compile definitions,
include directories, link libraries). This will allow CMake-built
projects to be imported into projects using the Android NDK build
system.
Closes: #15562
The option does not actually participate in argument groups like the
others because it does not actually install anything. Fix the order
in the documentation accordingly.
Reported-by: Daniel Wirtz <daniel.wirtz@simtech.uni-stuttgart.de>
Let us take an example of a project that has some tests in a component
that need to be installed into a dedicated test package. The user
expectation is that the result could be achieved by typing the
following:
make
make tests
make install
DESTDIR=/testpkgs make install-tests
However this results in test components in the default installation as
well as the testpkg.
Add an EXCLUDE_FROM_ALL option to the install() command to tell it that
the installation rule should not be included unless its component is
explicitly specified for installation.
