From 716e76be3e3fa8a646fd1d5fc2240aecd91365d8 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 31 Jul 2020 11:22:28 -0400 Subject: Help: Re-order add_library sections Put all the sections that create in-project targets first, and move Imported Libraries and Alias Libraries at the end. --- Help/command/add_library.rst | 122 +++++++++++++++++++++---------------------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 01c415a..232d0a9 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -64,42 +64,6 @@ See also :prop_sf:`HEADER_FILE_ONLY` on what to do if some sources are pre-processed, and you want to have the original sources reachable from within IDE. -Imported Libraries -^^^^^^^^^^^^^^^^^^ - -.. code-block:: cmake - - 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_``. - -The most important properties are: - -* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration - variant :prop_tgt:`IMPORTED_LOCATION_`) which 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 - -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. - Object Libraries ^^^^^^^^^^^^^^^^ @@ -129,31 +93,6 @@ systems (such as Xcode) may not like targets that have only object files, so consider adding at least one real source file to any target that references ``$``. -Alias Libraries -^^^^^^^^^^^^^^^ - -.. code-block:: cmake - - add_library( ALIAS ) - -Creates an :ref:`Alias Target `, such that ```` can be -used to refer to ```` in subsequent commands. The ```` does -not appear in the generated buildsystem as a make target. The ```` -may not be an ``ALIAS``. - -An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target ` -has scope in the directory in which the alias is created and below. -The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the -alias is global or not. - -``ALIAS`` targets can be used as linkable targets and as targets to -read properties from. They can also be tested for existence with the -regular :command:`if(TARGET)` subcommand. The ```` may not be used -to modify properties of ````, 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. - Interface Libraries ^^^^^^^^^^^^^^^^^^^ @@ -185,3 +124,64 @@ 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]) + +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_``. + +The most important properties are: + +* :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration + variant :prop_tgt:`IMPORTED_LOCATION_`) which 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 + +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 +^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_library( ALIAS ) + +Creates an :ref:`Alias Target `, such that ```` can be +used to refer to ```` in subsequent commands. The ```` does +not appear in the generated buildsystem as a make target. The ```` +may not be an ``ALIAS``. + +An ``ALIAS`` to a non-``GLOBAL`` :ref:`Imported Target ` +has scope in the directory in which the alias is created and below. +The :prop_tgt:`ALIAS_GLOBAL` target property can be used to check if the +alias is global or not. + +``ALIAS`` targets can be used as linkable targets and as targets to +read properties from. They can also be tested for existence with the +regular :command:`if(TARGET)` subcommand. The ```` may not be used +to modify properties of ````, 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. -- cgit v0.12