Help: Mark up the buildsystem commands documentation

Cross-link to the cmake-buildsystem manual.

1 files changed, 87 insertions, 80 deletions

diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index 2d69c89..0944269 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -7,73 +7,76 @@ Add a library to the project using the specified source files.
 
   add_library(<name> [STATIC | SHARED | MODULE]
               [EXCLUDE_FROM_ALL]
-              source1 source2 ... sourceN)
+              source1 [source2 ...])
 
-Adds a library target called <name> to be built from the source files
-listed in the command invocation.  The <name> corresponds to the
+Adds a library target called ``<name>`` to be built from the source files
+listed in the command invocation.  The ``<name>`` corresponds to the
 logical target name and must be globally unique within a project.  The
 actual file name of the library built is constructed based on
-conventions of the native platform (such as lib<name>.a or
-<name>.lib).
-
-STATIC, SHARED, or MODULE may be given to specify the type of library
-to be created.  STATIC libraries are archives of object files for use
-when linking other targets.  SHARED libraries are linked dynamically
-and loaded at runtime.  MODULE libraries are plugins that are not
-linked into other targets but may be loaded dynamically at runtime
+conventions of the native platform (such as ``lib<name>.a`` or
+``<name>.lib``).
+
+``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
+library to be created.  ``STATIC`` libraries are archives of object files
+for use when linking other targets.  ``SHARED`` libraries are linked
+dynamically and loaded at runtime.  ``MODULE`` libraries are plugins that
+are not linked into other targets but may be loaded dynamically at runtime
 using dlopen-like functionality.  If no type is given explicitly the
-type is STATIC or SHARED based on whether the current value of the
-variable BUILD_SHARED_LIBS is true.  For SHARED and MODULE libraries
-the POSITION_INDEPENDENT_CODE target property is set to TRUE
-automatically.
-
-By default the library file will be created in the build tree
-directory corresponding to the source tree directory in which the
-command was invoked.  See documentation of the
-ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and
-RUNTIME_OUTPUT_DIRECTORY target properties to change this location.
-See documentation of the OUTPUT_NAME target property to change the
-<name> part of the final file name.
-
-If EXCLUDE_FROM_ALL is given the corresponding property will be set on
-the created target.  See documentation of the EXCLUDE_FROM_ALL target
-property for details.
-
-The add_library command can also create IMPORTED library targets using
-this signature:
+type is ``STATIC`` or ``SHARED`` based on whether the current value of the
+variable :variable:`BUILD_SHARED_LIBS` is ``ON``.  For ``SHARED`` and
+``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
+property is set to ``ON`` automatically.
+
+By default the library file will be created in the build tree directory
+corresponding to the source tree directory in which thecommand was
+invoked.  See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
+:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
+:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this
+location.  See documentation of the :prop_tgt:`OUTPUT_NAME` target
+property to change the ``<name>`` part of the final file name.
+
+If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
+the created target.  See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
+target property for details.
+
+See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem
+properties.
+
+--------------------------------------------------------------------------
 
 ::
 
   add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
               [GLOBAL])
 
-An IMPORTED library target references a library file located outside
-the project.  No rules are generated to build it.  The target name has
-scope in the directory in which it is created and below, but the
-GLOBAL option extends visibility.  It may be referenced like any
-target built within the project.  IMPORTED libraries are useful for
-convenient reference from commands like target_link_libraries.
-Details about the imported library are specified by setting properties
-whose names begin in ``IMPORTED_``.  The most important such property is
-IMPORTED_LOCATION (and its per-configuration version
-IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main
-library file on disk.  See documentation of the IMPORTED_* properties
-for more information.
-
-The signature
+An :ref:`IMPORTED library target <Imported Targets>` references a library
+file located outside the project.  No rules are generated to build it, and
+the :prop_tgt:`IMPORTED` target property is ``True``.  The target name has
+scope in the directory in which it is created and below, but the ``GLOBAL``
+option extends visibility.  It may be referenced like any target built
+within the project.  ``IMPORTED`` libraries are useful for convenient
+reference from commands like :command:`target_link_libraries`.  Details
+about the imported library are specified by setting properties whose names
+begin in ``IMPORTED_`` and ``INTERFACE_``.  The most important such
+property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
+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.
+
+--------------------------------------------------------------------------
 
 ::
 
   add_library(<name> OBJECT <src>...)
 
-creates a special "object library" target.  An object library compiles
+Creates a special "object library" target.  An object library compiles
 source files but does not archive or link their object files into a
-library.  Instead other targets created by add_library or
-add_executable may reference the objects using an expression of the
-form $<TARGET_OBJECTS:objlib> as a source, where "objlib" is the
+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
 object library name.  For example:
 
-::
+.. code-block:: cmake
 
   add_library(... $<TARGET_OBJECTS:objlib> ...)
   add_executable(... $<TARGET_OBJECTS:objlib> ...)
@@ -82,48 +85,52 @@ will include objlib's object files in a library and an executable
 along with those compiled from their own sources.  Object libraries
 may contain only sources (and headers) that compile to object files.
 They may contain custom commands generating such sources, but not
-PRE_BUILD, PRE_LINK, or POST_BUILD commands.  Object libraries cannot
-be imported, exported, installed, or linked.  Some native build
+``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands.  Object libraries
+cannot be imported, exported, installed, or linked.  Some native build
 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>.
+``$<TARGET_OBJECTS:objlib>``.
 
-The signature
+--------------------------------------------------------------------------
 
 ::
 
   add_library(<name> ALIAS <target>)
 
-creates an alias, such that <name> can be used to refer to <target> in
-subsequent commands.  The <name> does not appear in the generated
-buildsystem as a make target.  The <target> may not be an IMPORTED
-target or an ALIAS.  Alias targets can be used as linkable targets,
-targets to read properties from.  They can also be tested for
-existance with the regular if(TARGET) subcommand.  The <name> may not
-be used to modify properties of <target>, that is, it may not be used
-as the operand of set_property, set_target_properties,
-target_link_libraries etc.  An ALIAS target may not be installed of
-exported.
+Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
+used to refer to ``<target>`` in subsequent commands.  The ``<name>`` does
+not appear in the generatedbuildsystem as a make target.  The ``<target>``
+may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
+``ALIAS`` targets can be used as linkable targets and as targets to
+read properties from.  They can also be tested for existance with the
+regular :command:`if(TARGET)` subcommand.  The ``<name>`` may not be used
+to modify properties of ``<target>``, that is, it may not be used as the
+operand of :command:`set_property`, :command:`set_target_properties`,
+:command:`target_link_libraries` etc.  An ``ALIAS`` target may not be
+installed or exported.
 
-The signature
+--------------------------------------------------------------------------
 
 ::
 
   add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
 
-creates an interface target.  An interface target does not directly
-create build output, though it may have properties set on it and it
-may be installed, exported and imported.  Typically the INTERFACE_*
-properties are populated on the interface target using the
-:command:`set_property`, :command:`target_link_libraries`,
-:command:`target_include_directories`
-and :command:`target_compile_defintions` commands, and then it is used as an
-argument to :command:`target_link_libraries` like any other target.
-
-An ``INTERFACE`` :prop_tgt:`IMPORTED` target may also be created with this
-signature.  An :prop_tgt:`IMPORTED` library target references a library defined
-outside the project.  The target name has scope in the directory in which it is
-created and below, but the ``GLOBAL`` option extends visibility.  It may be
-referenced like any target built within the project.  :prop_tgt:`IMPORTED`
-libraries are useful for convenient reference from commands like
-:command:`target_link_libraries`.
+Creates an :ref:`Interface Library <Interface Libraries>`.  An ``INTERFACE``
+library target does not directly create build output, though it may
+have properties set on it and it may be installed, exported and
+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)`
+and :command:`target_compile_definitions(INTERFACE)` commands, and then it
+is used as an argument to :command:`target_link_libraries` like any other
+target.
+
+An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be
+created with this signature.  An ``IMPORTED`` library target references a
+library defined outside the project.  The target name has scope in the
+directory in which it is created and below, but the ``GLOBAL`` option
+extends visibility.  It may be referenced like any target built within
+the project.  ``IMPORTED`` libraries are useful for convenient reference
+from commands like :command:`target_link_libraries`.