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.
Since commit 4391913133 (Add INTERFACE libraries to generated
buildsystem if they have SOURCES, 2020-07-20, v3.19.0-rc1~346^2~1) the
"Eigen" example in the `cmake-buildsystem(7)` manual is supposed to show
a header-only library in which the headers are attached as sources to be
edited in IDEs. This was accidentally broken by commit 4b25a0d512
(Help/manual: Update header-only library example, 2022-04-22,
v3.24.0-rc1~220^2) when updating the example to use a `FILE_SET`.
Fixes: #24319
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`.
Add additional information to the cmake-buildsystem manual:
* Add link to "Generator Expressions" in a place which demonstrates a
generator expression without linking to what they are.
* Update "diagnostic message" for "Compatible Interface Properties" to
contain an example of the message sent.
* Add information about the macOS FRAMEWORK_VERSION and how "A" is the
conventional value to use.
INTERFACE libraries were created with the intention of collecting usage
requirements for use by other targets via `target_link_libraries`.
Therefore they were not allowed to have SOURCES and were not included in
the generated buildsystem. In practice, this has become limiting:
* Header-only libraries do have sources, they just do not compile.
Developers should be able to edit those sources (the header files)
in their IDE.
* Header-only libraries may need to generate some of their header
files via custom commands.
Some projects work around these limitations by pairing each interface
library with an `add_custom_target` that makes the header files and
custom commands appear in the generated buildsystem and in IDEs.
Lift such limitations by allowing INTERFACE libraries to have SOURCES.
For those with sources, add a corresponding build target to the
generated buildsystem.
Fixes: #19145
Previously we disallowed use of arbitrary properties on INTERFACE
libraries. The goal was to future-proof projects using them by not
allowing properties to be set that may affect their future inclusion in
the generated buildsystem. In order to prepare to actually include
INTERFACE libraries in the generated buildsystem, drop the filter and
allow arbitrary properties to be set.
Issue: #19145
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
Since commit v3.11.0-rc1~433^2~2 (Teach target_* commands to set
INTERFACE properties of IMPORTED targets, 2017-09-18) it is now possible
to use the customary `target_*` commands for adjusting the settings of
an IMPORTED target. Update documentation accordingly.
The change in commit v3.8.0-rc1~276^2 (Allow NO_SYSTEM_FROM_IMPORTED on
imported INTERFACE libraries, 2016-11-21) was incorrect. The property
is not meant to be set on imported targets at all. It is meant to be
set on their consumers that compile sources. Since INTERFACE libraries
have no sources to compile, the property is not needed on them.
Revert most of that change. Unfortunately we must still tolerate
project code setting NO_SYSTEM_FROM_IMPORTED on INTERFACE libraries
because they were allowed by CMake 3.8 and 3.9.
Issue: #17348
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>
Previously the `TARGET_OBJECTS` generator expression was limited
only to use in a buildsystem context so that Xcode's placeholders
in object file paths can be evaluated. Lift this restriction so
that the expression can at least be used in most settings.
Co-Author: Brad King <brad.king@kitware.com>
Imported INTERFACE libraries can specify include directories via
`INTERFACE_INCLUDE_DIRECTORIES` so the default behavior of treating them
as system include directories applies. Allow users to turn this off by
setting `NO_SYSTEM_FROM_IMPORTED` on such targets.
Closes: #16443
This property was added by commit 09cda9d5 (Allow imported INTERFACE
libraries to specify a link library name, 2016-11-03) and is in the
implementation's whitelist. Add it to the documentation too.
The COMPATIBLE_INTERFACE_NUMBER_MAX example now sets
INTERFACE_CONTAINER_SIZE_REQUIRED on lib1Version2 and lib1Version3.
Previously set it on lib1Version2 twice and never on lib1Version3.
CMake assumes that a SHARED library compiled on Windows will export a LIB file.
This is not actually the case on Visual C++ if the library does not export any
symbols, and causes incremental builds to break if the user specifies SHARED
anyway. (Users should use MODULE libraries instead.)
Add sections to the cmake-buildsystem(7) manual and cross-reference
them with relevant variables and target properties. This avoids
duplicating the information and allows it to be more detailed.
Re-organize the content added to the cmake-packages(7) manual by
* commit v3.0.0-rc1~184^2 (Help: Document export(EXPORT) in the
cmake-packages manual, 2013-12-23),
* commit v3.0.0-rc1~154^2~1 (Help: Add notes about relocatability
of config-file packages, 2014-01-07), and
* commit v3.2.0-rc1~345^2 (Help: Warn that paths should not be used
in INTERFACE_ build properties, 2014-11-22).
These commits broke the natural flow of the original manual and made
wording after the new content make less sense. Move the content into
new subsections to restore the flow of the original manual and to
make explicitly the purpose of the new content.
Shorten the relocatable usage requirement "warnings". Refer to the
new cmake-packages(7) manual subsection to reduce duplication. Also
clarify the distinction between paths to library dependencies and
paths to their header files.
Fix cmTarget::GetSourceFiles to set EvaluateForBuildsystem on the
$<TARGET_PROPERTY:...,INTERFACE_SOURCES> generator expression so that
the $<TARGET_OBJECTS> generator expression is allowed within an
INTERFACE_SOURCES value.
Extend the InterfaceLibrary test to cover this case. Extend the
RunCMake.TargetObjects test to cover failure of $<TARGET_OBJECTS>
when used through $<TARGET_PROPERTY:...,INTERFACE_SOURCES> in a
non-buildsystem context.
The add_library(INTERFACE) and Interface Libraries documentation
list all the INTERFACE_* properties and target_* commands that
can be used to define the interface. Add INTERFACE_SOURCES
and target_sources() to these lists for completeness.
