Merge topic 'buildsystem-doc-updates'
20f54602Help: Link to Object Library docs from add_librarya8153181Help: Organize add_library command documentationd8319f0fHelp: Update style guide to use section headers for command signatures50dca471Help: Organize Binary Targets section of cmake-buildsystem.74054534cHelp: Mention INTERFACE_SOURCES as settable for INTERFACE libs
This commit is contained in:
Brad King
CMake Topic Stage
commit
38befe3998
|
|
@ -1,8 +1,15 @@
|
|||
add_library
|
||||
-----------
|
||||
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
Add a library to the project using the specified source files.
|
||||
|
||||
Normal Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
add_library(<name> [STATIC | SHARED | MODULE]
|
||||
|
|
@ -44,7 +51,8 @@ the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
|||
manual for available expressions. See the :manual:`cmake-buildsystem(7)`
|
||||
manual for more on defining buildsystem properties.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
Imported Libraries
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -65,14 +73,15 @@ 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.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
Object Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
add_library(<name> OBJECT <src>...)
|
||||
|
||||
Creates a special "object library" target. An object library compiles
|
||||
source files but does not archive or link their object files into a
|
||||
Creates an :ref:`Object Library <Object Libraries>`. An object library
|
||||
compiles source files but does not archive or link their object files into a
|
||||
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
|
||||
|
|
@ -93,7 +102,8 @@ 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>``.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
Alias Libraries
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -111,7 +121,8 @@ 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
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -124,8 +135,9 @@ 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
|
||||
:command:`target_compile_options(INTERFACE)`,
|
||||
:command:`target_compile_definitions(INTERFACE)`,
|
||||
and :command:`target_sources(INTERFACE)` commands, and then it
|
||||
is used as an argument to :command:`target_link_libraries` like any other
|
||||
target.
|
||||
|
||||
|
|
|
|||
|
|
@ -19,8 +19,8 @@ and the rules for regeneration in response to change.
|
|||
Binary Targets
|
||||
==============
|
||||
|
||||
Executables and libraries are defined using the :command:`add_library`
|
||||
and :command:`add_executable` commands. The resulting binary files have
|
||||
Executables and libraries are defined using the :command:`add_executable`
|
||||
and :command:`add_library` commands. The resulting binary files have
|
||||
appropriate prefixes, suffixes and extensions for the platform targeted.
|
||||
Dependencies between binary targets are expressed using the
|
||||
:command:`target_link_libraries` command:
|
||||
|
|
@ -37,9 +37,28 @@ is defined as an executable formed by compiling and linking ``zipapp.cpp``.
|
|||
When linking the ``zipapp`` executable, the ``archive`` static library is
|
||||
linked in.
|
||||
|
||||
Binary Executables
|
||||
------------------
|
||||
|
||||
The :command:`add_executable` command defines an executable target:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
add_executable(mytool mytool.cpp)
|
||||
|
||||
Commands such as :command:`add_custom_command`, which generates rules to be
|
||||
run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
|
||||
target as a ``COMMAND`` executable. The buildsystem rules will ensure that
|
||||
the executable is built before attempting to run the command.
|
||||
|
||||
Binary Library Types
|
||||
--------------------
|
||||
|
||||
.. _`Normal Libraries`:
|
||||
|
||||
Normal Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
By default, the :command:`add_library` command defines a static library,
|
||||
unless a type is specified. A type may be specified when using the command:
|
||||
|
||||
|
|
@ -66,6 +85,11 @@ It is a type which is loaded as a plugin using runtime techniques.
|
|||
|
||||
add_library(archive MODULE 7z.cpp)
|
||||
|
||||
.. _`Object Libraries`:
|
||||
|
||||
Object Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``OBJECT`` library type is also not linked to. It defines a non-archival
|
||||
collection of object files resulting from compiling the given source files.
|
||||
The object files collection can be used as source inputs to other targets:
|
||||
|
|
@ -83,11 +107,6 @@ they may not be installed, exported, or used in the right hand side of
|
|||
:command:`target_link_libraries`. They also may not be used as the ``TARGET``
|
||||
in a use of the :command:`add_custom_command(TARGET)` command signature.
|
||||
|
||||
Commands such as :command:`add_custom_command`, which generates rules to be
|
||||
run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
|
||||
target as a ``COMMAND`` executable. The buildsystem rules will ensure that
|
||||
the executable is built before attempting to run the command.
|
||||
|
||||
Build Specification and Usage Requirements
|
||||
==========================================
|
||||
|
||||
|
|
@ -786,11 +805,12 @@ It may specify usage requirements such as
|
|||
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
|
||||
:prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
|
||||
:prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
|
||||
:prop_tgt:`INTERFACE_SOURCES`,
|
||||
:prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
|
||||
Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
|
||||
:command:`target_compile_definitions`, :command:`target_compile_options`,
|
||||
and :command:`target_link_libraries` commands may be used with ``INTERFACE``
|
||||
libraries.
|
||||
:command:`target_sources`, and :command:`target_link_libraries` commands
|
||||
may be used with ``INTERFACE`` libraries.
|
||||
|
||||
A primary use-case for ``INTERFACE`` libraries is header-only libraries.
|
||||
|
||||
|
|
|
|||
|
|
@ -521,14 +521,15 @@ Style: CMake Command Signatures
|
|||
Command signatures should be marked up as plain literal blocks, not as
|
||||
cmake ``code-blocks``.
|
||||
|
||||
Signatures are separated from preceding content by a horizontal
|
||||
line. That is, use:
|
||||
Signatures are separated from preceding content by a section header.
|
||||
That is, use:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
... preceding paragraph.
|
||||
|
||||
---------------------------------------------------------------------
|
||||
Normal Libraries
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue