From 1b0adeea819e82d19da190c47bab06e1f355cf8f Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 31 Jul 2020 10:31:25 -0400 Subject: Help: Clarify target_sources PRIVATE/PUBLIC/INTERFACE scopes --- Help/command/target_sources.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst index 856d869..653b8d7 100644 --- a/Help/command/target_sources.rst +++ b/Help/command/target_sources.rst @@ -11,19 +11,21 @@ Add sources to a target. [items1...] [ [items2...] ...]) -Specifies sources to use when compiling a given target. Relative -source file paths are interpreted as being relative to the current +Specifies sources to use when building a target and/or its dependents. +Relative source file paths are interpreted as being relative to the current source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`). The named ```` must have been created by a command such as :command:`add_executable` or :command:`add_library` and must not be an :ref:`ALIAS target `. The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to -specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +specify the scope of the items following them. ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`SOURCES` property of -````. ``PUBLIC`` and ``INTERFACE`` items will populate the -:prop_tgt:`INTERFACE_SOURCES` property of ````. -(:ref:`IMPORTED targets ` only support ``INTERFACE`` items.) +````, which are used when building the target itself. +``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_SOURCES` property of ````, which are used +when building dependents. (:ref:`IMPORTED targets ` +only support ``INTERFACE`` items because they are not build targets.) The following arguments specify sources. Repeated calls for the same ```` append items in the order called. -- cgit v0.12 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 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 From ee5b58f491829347049c242a9a4a0f2d696feb4c Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 31 Jul 2020 12:04:17 -0400 Subject: Help: State in add_library that INTERFACE libraries have no build targets --- Help/command/add_library.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 2615db9..ed8447e 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -100,11 +100,12 @@ Interface Libraries add_library( INTERFACE) -Creates an :ref:`Interface Library `. 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 commands: +Creates an :ref:`Interface Library `. +An ``INTERFACE`` library target does not compile sources and does +not produce a library artifact on disk. However, it may have +properties set on it and it may be installed and exported. +Typically, ``INTERFACE_*`` properties are populated on an interface +target using the commands: * :command:`set_property`, * :command:`target_link_libraries(INTERFACE)`, @@ -117,6 +118,9 @@ 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 library has no source files itself and is not included +as a target in the generated buildsystem. + Imported Libraries ^^^^^^^^^^^^^^^^^^ -- cgit v0.12