Add INTERFACE libraries to generated buildsystem if they have SOURCES

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

1 files changed, 29 insertions, 2 deletions

diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index ed8447e..f7e6792 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -118,8 +118,35 @@ target using the commands:
 and then it is used as an argument to :command:`target_link_libraries`
 like any other target.
 
-An interface library has no source files itself and is not included
-as a target in the generated buildsystem.
+An interface library created with the above signature has no source files
+itself and is not included as a target in the generated buildsystem.
+
+Since CMake 3.19, an interface library target may be created with
+source files:
+
+.. code-block:: cmake
+
+  add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
+
+Source files may be listed directly in the ``add_library`` call or added
+later by calls to :command:`target_sources` with the ``PRIVATE`` or
+``PUBLIC`` keywords.
+
+If an interface library has source files (i.e. the :prop_tgt:`SOURCES`
+target property is set), it will appear in the generated buildsystem
+as a build target much like a target defined by the
+:command:`add_custom_target` command.  It does not compile any sources,
+but does contain build rules for custom commands created by the
+:command:`add_custom_command` command.
+
+.. note::
+  In most command signatures where the ``INTERFACE`` keyword appears,
+  the items listed after it only become part of that target's usage
+  requirements and are not part of the target's own settings.  However,
+  in this signature of ``add_library``, the ``INTERFACE`` keyword refers
+  to the library type only.  Sources listed after it in the ``add_library``
+  call are ``PRIVATE`` to the interface library and do not appear in its
+  :prop_tgt:`INTERFACE_SOURCES` target property.
 
 Imported Libraries
 ^^^^^^^^^^^^^^^^^^