Re-organize the "Binary Targets" section of the manual to have a
dedicated subsection for each kind of binary target. Initialize each
subsection by documenting the object file and link semantics of the
corresponding target type.
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
If an INTERFACE library has HEADER_SETS, and its header sets contain
files generated by a custom command, the library needs to participate in
the buildsystem so that the files will be generated.
Fixes: #23422
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
When using `add_library` to create an `IMPORTED` library target, there
are a few target properties that are essential to correctly tell CMake
about the library file. We already cover `IMPORTED_LOCATION` and
`IMPORTED_IMPLIB`. Add `IMPORTED_SONAME` and `IMPORTED_NO_SONAME`,
which are important in certain cases.
Fixes: #22016
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
bafa9fe887 fileapi: Add INTERFACE libraries with SOURCES to codemodel-v2
4391913133 Add INTERFACE libraries to generated buildsystem if they have SOURCES
afb998704e Remove filtering of allowed INTERFACE library properties
e7edba2baf Makefiles: Use IsInBuildSystem in global generator target type checks
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5078
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
Move documentation on IMPORTED INTERFACE libraries to the main section
on Imported Libraries. Revise the section to clarify the different
kinds of imported libraries that can be created and what properties they
need.
Issue: #18975
The `add_library` and `add_executable` commands can now be called with
no source-files and won't generate a warning or error message, as long
as source-files will be added later via the `target_sources` command.
If during the generation step still no sources are associated with
targets created by such calls a useful error message will be generated
and generation fails.
Targets of type `INTERFACE_LIBRARY`, `UTILITY` or `GLOBAL_TARGET` are
excluded from this check because we do not need sources for these target
types during generation.
Fixes: #16872
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>
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.)
Loosen this restriction on OBJECT libraries to allow source files of any
name to be generated by custom commands or listed for reference in IDE
projects so long as they would not affect linking of a normal library.
Update the rejection message to be more specific about the looser
restriction.
Extend the ObjectLibrary test to cover a ".cmake" file generated by a
custom command in an OBJECT library.
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.
Remove use of UseObjectLibraries from Makefile and Ninja generators. It
is not needed now because those generators use GetExternalObjects
which already contains the objects from object libraries.
The VS10 generator calls both the UseObjectLibraries and the GetExternalObjects
methods. Ensure that duplicates are not created by skipping objects
from object libraries in handling of GetExternalObjects.
Similarly, fix VS6, VS7 and Xcode object handling by skipping
external objects from OBJECT_LIBRARY usage as appropriate.
The error message in the BadSourceExpression1 test is now reported
by the generator expression evaluator, so it has different text.
