From cbb609072f00ee6aec3fdfb6e54ed2b3a747e840 Mon Sep 17 00:00:00 2001
From: Kyle Edwards <kyle.edwards@kitware.com>
Date: Thu, 19 Apr 2018 11:28:30 -0400
Subject: Help: clean up install(TARGETS) documentation
The documentation for install(TARGETS) has been rearranged so that
the options are presented as a list, for better readability and
maintenance.
---
Help/command/install.rst | 158 ++++++++++++++++++++++++++++-------------------
1 file changed, 96 insertions(+), 62 deletions(-)
diff --git a/Help/command/install.rst b/Help/command/install.rst
index b11b35a..1037edf 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -110,63 +110,102 @@ Installing Targets
)
The ``TARGETS`` form specifies rules for installing targets from a
-project. There are six kinds of target files that may be installed:
-``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``FRAMEWORK``, and
-``BUNDLE``. Executables are treated as ``RUNTIME`` targets, except that
-those marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE``
-targets on OS X. Static libraries are treated as ``ARCHIVE`` targets,
-except that those marked with the ``FRAMEWORK`` property are treated
-as ``FRAMEWORK`` targets on OS X.
-Module libraries are always treated as ``LIBRARY`` targets.
-For non-DLL platforms shared libraries are treated as ``LIBRARY``
-targets, except that those marked with the ``FRAMEWORK`` property are
-treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL
-part of a shared library is treated as a ``RUNTIME`` target and the
-corresponding import library is treated as an ``ARCHIVE`` target.
-All Windows-based systems including Cygwin are DLL platforms. Object
-libraries are always treated as ``OBJECTS`` targets.
-The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, and ``FRAMEWORK``
-arguments change the type of target to which the subsequent properties
-apply. If none is given the installation properties apply to all target
-types. If only one is given then only targets of that type will be
-installed (which can be used to install just a DLL or just an import
-library).
-
-The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments
-cause subsequent properties to be applied to installing a ``FRAMEWORK``
-shared library target's associated files on non-Apple platforms. Rules
-defined by these arguments are ignored on Apple platforms because the
-associated files are installed into the appropriate locations inside
-the framework folder. See documentation of the
-:prop_tgt:`PRIVATE_HEADER`, :prop_tgt:`PUBLIC_HEADER`, and
-:prop_tgt:`RESOURCE` target properties for details.
-
-Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a
-``LIBRARY`` option. On some platforms a versioned shared library
-has a symbolic link such as::
-
- lib<name>.so -> lib<name>.so.1
-
-where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so``
-is a "namelink" allowing linkers to find the library when given
-``-l<name>``. The ``NAMELINK_ONLY`` option causes installation of only the
-namelink when a library target is installed. The ``NAMELINK_SKIP`` option
-causes installation of library files other than the namelink when a
-library target is installed. When neither option is given both
-portions are installed. On platforms where versioned shared libraries
-do not have namelinks or when a library is not versioned the
-``NAMELINK_SKIP`` option installs the library and the ``NAMELINK_ONLY``
-option installs nothing. See the :prop_tgt:`VERSION` and
-:prop_tgt:`SOVERSION` target properties for details on creating versioned
-shared libraries.
-
-The ``INCLUDES DESTINATION`` specifies a list of directories
-which will be added to the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
-target property of the ``<targets>`` when exported by the
-:command:`install(EXPORT)` command. If a relative path is
-specified, it is treated as relative to the ``$<INSTALL_PREFIX>``.
-This is independent of the rest of the argument groups and does
-not actually install anything.
+project. There are several kinds of target files that may be installed:
+
+``ARCHIVE``
+ Static libraries are treated as ``ARCHIVE`` targets, except those
+ marked with the ``FRAMEWORK`` property on OS X (see ``FRAMEWORK``
+ below.) For DLL platforms (all Windows-based systems including
+ Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
+
+``LIBRARY``
+ Module libraries are always treated as ``LIBRARY`` targets. For non-
+ DLL platforms shared libraries are treated as ``LIBRARY`` targets,
+ except those marked with the ``FRAMEWORK`` property on OS X (see
+ ``FRAMEWORK`` below.)
+
+``RUNTIME``
+ Executables are treated as ``RUNTIME`` objects, except those marked
+ with the ``MACOSX_BUNDLE`` property on OS X (see ``BUNDLE`` below.)
+ For DLL platforms (all Windows-based systems including Cygwin), the
+ DLL part of a shared library is treated as a ``RUNTIME`` target.
+
+``OBJECTS``
+ Object libraries (a simple group of object files) are always treated
+ as ``OBJECTS`` targets.
+
+``FRAMEWORK``
+ Both static and shared libraries marked with the ``FRAMEWORK``
+ property are treated as ``FRAMEWORK`` targets on OS X.
+
+``BUNDLE``
+ Executables marked with the ``MACOSX_BUNDLE`` property are treated as
+ ``BUNDLE`` targets on OS X.
+
+``PUBLIC_HEADER``
+ Any ``PUBLIC_HEADER`` files associated with a library are installed in
+ the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple
+ platforms. Rules defined by this argument are ignored for ``FRAMEWORK``
+ libraries on Apple platforms because the associated files are installed
+ into the appropriate locations inside the framework folder. See
+ :prop_tgt:`PUBLIC_HEADER` for details.
+
+``PRIVATE_HEADER``
+ Similar to ``PUBLIC_HEADER``, but for ``PRIVATE_HEADER`` files. See
+ :prop_tgt:`PRIVATE_HEADER` for details.
+
+``RESOURCE``
+ Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for
+ ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details.
+
+For each of these arguments given, the arguments following them only apply
+to the target or file type specified in the argument. If none is given, the
+installation properties apply to all target types. If only one is given then
+only targets of that type will be installed (which can be used to install
+just a DLL or just an import library.)
+
+In addition to the common options listed above, each target can accept
+the following additional arguments:
+
+``NAMELINK_ONLY``
+ On some platforms a versioned shared library has a symbolic link such
+ as::
+
+ lib<name>.so -> lib<name>.so.1
+
+ where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so``
+ is a "namelink" allowing linkers to find the library when given
+ ``-l<name>``. The ``NAMELINK_ONLY`` option causes the installation of only
+ the namelink when a library target is installed. On platforms where
+ versioned shared libraries do not have namelinks or when a library is not
+ versioned, the ``NAMELINK_ONLY`` option installs nothing. It is an error to
+ use this parameter outside of a ``LIBRARY`` block. See the
+ :prop_tgt:`VERSION` and :prop_tgt:`SOVERSION` target properties for details
+ on creating versioned shared libraries.
+
+``NAMELINK_SKIP``
+ Similar to ``NAMELINK_ONLY``, but it has the opposite effect: it causes the
+ installation of library files other than the namelink when a library target
+ is installed. When neither ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` are given,
+ both portions are installed. On platforms where versioned shared libraries
+ do not have symlinks or when a library is not versioned, ``NAMELINK_SKIP``
+ installs the library. It is an error to use this parameter outside of a
+ ``LIBRARY`` block.
+
+The ``install(TARGETS)`` command can also accept the following options at the
+top level:
+
+``EXPORT``
+ This option associates the installed target files with an export called
+ ``<export-name>``. It must appear before any target options. To actually
+ install the export file itself, call ``install(EXPORT)``, documented below.
+
+``INCLUDES DESTINATION``
+ This option specifies a list of directories which will be added to the
+ :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
+ ``<targets>`` when exported by the :command:`install(EXPORT)` command. If a
+ relative path is specified, it is treated as relative to the
+ ``$<INSTALL_PREFIX>``.
One or more groups of properties may be specified in a single call to
the ``TARGETS`` form of this command. A target may be installed more than
@@ -188,11 +227,6 @@ the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and
``/some/full/path`` and its import library will be installed to
``<prefix>/lib/static`` and ``/some/full/path``.
-The ``EXPORT`` option associates the installed target files with an
-export called ``<export-name>``. It must appear before any ``RUNTIME``,
-``LIBRARY``, ``ARCHIVE``, or ``OBJECTS`` options. To actually install the
-export file itself, call ``install(EXPORT)``, documented below.
-
:ref:`Interface Libraries` may be listed among the targets to install.
They install no artifacts but will be included in an associated ``EXPORT``.
If :ref:`Object Libraries` are listed but given no destination for their
--
cgit v0.12