Merge topic 'buildsystem-doc-updates'

20f54602 Help: Link to Object Library docs from add_library
a8153181 Help: Organize add_library command documentation
d8319f0f Help: Update style guide to use section headers for command signatures
50dca471 Help: Organize Binary Targets section of cmake-buildsystem.7
4054534c Help: Mention INTERFACE_SOURCES as settable for INTERFACE libs

Help/command/add_library.rst

@@ -1,8 +1,15 @@
 add_library
 -----------
 
+.. only:: html
+
+   .. contents::
+
 Add a library to the project using the specified source files.
 
+Normal Libraries
+^^^^^^^^^^^^^^^^
+
 ::
 
   add_library(<name> [STATIC | SHARED | MODULE]
@@ -44,7 +51,8 @@ the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
---------------------------------------------------------------------------
+Imported Libraries
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -65,14 +73,15 @@ variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
 location of the main library file on disk.  See documentation of the
 ``IMPORTED_*`` and ``INTERFACE_*`` properties for more information.
 
---------------------------------------------------------------------------
+Object Libraries
+^^^^^^^^^^^^^^^^
 
 ::
 
   add_library(<name> OBJECT <src>...)
 
-Creates a special "object library" target.  An object library compiles
+Creates an :ref:`Object Library <Object Libraries>`.  An object library
-source files but does not archive or link their object files into a
+compiles source files but does not archive or link their object files into a
 library.  Instead other targets created by :command:`add_library` or
 :command:`add_executable` may reference the objects using an expression of the
 form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the
@@ -93,7 +102,8 @@ systems may not like targets that have only object files, so consider
 adding at least one real source file to any target that references
 ``$<TARGET_OBJECTS:objlib>``.
 
---------------------------------------------------------------------------
+Alias Libraries
+^^^^^^^^^^^^^^^
 
 ::
 
@@ -111,7 +121,8 @@ operand of :command:`set_property`, :command:`set_target_properties`,
 :command:`target_link_libraries` etc.  An ``ALIAS`` target may not be
 installed or exported.
 
---------------------------------------------------------------------------
+Interface Libraries
+^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -124,8 +135,9 @@ imported. Typically the ``INTERFACE_*`` properties are populated on
 the interface target using the :command:`set_property`,
 :command:`target_link_libraries(INTERFACE)`,
 :command:`target_include_directories(INTERFACE)`,
-:command:`target_compile_options(INTERFACE)`
+:command:`target_compile_options(INTERFACE)`,
-and :command:`target_compile_definitions(INTERFACE)` commands, and then it
+:command:`target_compile_definitions(INTERFACE)`,
+and :command:`target_sources(INTERFACE)` commands, and then it
 is used as an argument to :command:`target_link_libraries` like any other
 target.
 

Help/manual/cmake-buildsystem.7.rst

@@ -19,8 +19,8 @@ and the rules for regeneration in response to change.
 Binary Targets
 ==============
 
-Executables and libraries are defined using the :command:`add_library`
+Executables and libraries are defined using the :command:`add_executable`
-and :command:`add_executable` commands.  The resulting binary files have
+and :command:`add_library` commands.  The resulting binary files have
 appropriate prefixes, suffixes and extensions for the platform targeted.
 Dependencies between binary targets are expressed using the
 :command:`target_link_libraries` command:
@@ -37,9 +37,28 @@ is defined as an executable formed by compiling and linking ``zipapp.cpp``.
 When linking the ``zipapp`` executable, the ``archive`` static library is
 linked in.
 
+Binary Executables
+------------------
+
+The :command:`add_executable` command defines an executable target:
+
+.. code-block:: cmake
+
+  add_executable(mytool mytool.cpp)
+
+Commands such as :command:`add_custom_command`, which generates rules to be
+run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
+target as a ``COMMAND`` executable.  The buildsystem rules will ensure that
+the executable is built before attempting to run the command.
+
 Binary Library Types
 --------------------
 
+.. _`Normal Libraries`:
+
+Normal Libraries
+^^^^^^^^^^^^^^^^
+
 By default, the :command:`add_library` command defines a static library,
 unless a type is specified.  A type may be specified when using the command:
 
@@ -66,6 +85,11 @@ It is a type which is loaded as a plugin using runtime techniques.
 
   add_library(archive MODULE 7z.cpp)
 
+.. _`Object Libraries`:
+
+Object Libraries
+^^^^^^^^^^^^^^^^
+
 The ``OBJECT`` library type is also not linked to. It defines a non-archival
 collection of object files resulting from compiling the given source files.
 The object files collection can be used as source inputs to other targets:
@@ -83,11 +107,6 @@ they may not be installed, exported, or used in the right hand side of
 :command:`target_link_libraries`.  They also may not be used as the ``TARGET``
 in a use of the :command:`add_custom_command(TARGET)` command signature.
 
-Commands such as :command:`add_custom_command`, which generates rules to be
-run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
-target as a ``COMMAND`` executable.  The buildsystem rules will ensure that
-the executable is built before attempting to run the command.
-
 Build Specification and Usage Requirements
 ==========================================
 
@@ -786,11 +805,12 @@ It may specify usage requirements such as
 :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
 :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
 :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
+:prop_tgt:`INTERFACE_SOURCES`,
 :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
 Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
 :command:`target_compile_definitions`, :command:`target_compile_options`,
-and :command:`target_link_libraries` commands may be used with ``INTERFACE``
+:command:`target_sources`, and :command:`target_link_libraries` commands
-libraries.
+may be used with ``INTERFACE`` libraries.
 
 A primary use-case for ``INTERFACE`` libraries is header-only libraries.
 

Help/manual/cmake-developer.7.rst

@@ -521,14 +521,15 @@ Style: CMake Command Signatures
 Command signatures should be marked up as plain literal blocks, not as
 cmake ``code-blocks``.
 
-Signatures are separated from preceding content by a horizontal
+Signatures are separated from preceding content by a section header.
-line. That is, use:
+That is, use:
 
 .. code-block:: rst
 
   ... preceding paragraph.
 
-  ---------------------------------------------------------------------
+  Normal Libraries
+  ^^^^^^^^^^^^^^^^
 
   ::