From 99b1e85f07c67a4737c06be52b501b3a10f476b8 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 31 Jul 2020 11:35:46 -0400 Subject: Help: Consolidate add_library documentation on IMPORTED libraries 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 --- Help/command/add_library.rst | 66 +++++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 232d0a9..2615db9 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -98,7 +98,7 @@ Interface Libraries .. code-block:: cmake - add_library( INTERFACE [IMPORTED [GLOBAL]]) + add_library( INTERFACE) Creates an :ref:`Interface Library `. An ``INTERFACE`` library target does not directly create build output, though it may @@ -117,50 +117,52 @@ the interface target using the commands: and then it is used as an argument to :command:`target_link_libraries` like any other target. -An ``INTERFACE`` :ref:`Imported Target ` 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`. - Imported Libraries ^^^^^^^^^^^^^^^^^^ .. code-block:: cmake - add_library( IMPORTED - [GLOBAL]) + add_library( IMPORTED [GLOBAL]) -An :ref:`IMPORTED library target ` 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_``. +Creates an :ref:`IMPORTED library target ` called ````. +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 properties are: +The ```` must be one of: -* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration - variant :prop_tgt:`IMPORTED_LOCATION_`) which specifies the +``STATIC``, ``SHARED``, ``MODULE``, ``UNKNOWN`` + References a library file located outside the project. The + :prop_tgt:`IMPORTED_LOCATION` target property (or its per-configuration + variant :prop_tgt:`IMPORTED_LOCATION_`) specifies the location of the main library file on disk. -* :prop_tgt:`IMPORTED_OBJECTS` (and :prop_tgt:`IMPORTED_OBJECTS_`) - for object libraries, specifies the locations of object files on disk. -* :prop_tgt:`PUBLIC_HEADER` files to be installed during :command:`install` invocation + Additional usage requirements may be specified in ``INTERFACE_*`` properties. + + An ``UNKNOWN`` library type is typically only used in the implementation of + :ref:`Find Modules`. It allows the path to an imported library (often found + using the :command:`find_library` command) to be used without having to know + what type of library it is. This is especially useful on Windows where a + static library and a DLL's import library both have the same file extension. + +``OBJECT`` + References a set of object files located outside the project. + The :prop_tgt:`IMPORTED_OBJECTS` target property (or its per-configuration + variant :prop_tgt:`IMPORTED_OBJECTS_`) specifies the locations of + object files on disk. + Additional usage requirements may be specified in ``INTERFACE_*`` properties. + +``INTERFACE`` + Does not reference any library or object files on disk, but may + specify usage requirements in ``INTERFACE_*`` properties. See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. -An ``UNKNOWN`` library type is typically only used in the implementation of -:ref:`Find Modules`. It allows the path to an imported library (often found -using the :command:`find_library` command) to be used without having to know -what type of library it is. This is especially useful on Windows where a -static library and a DLL's import library both have the same file extension. - Alias Libraries ^^^^^^^^^^^^^^^ -- cgit v0.12