diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 01c415a929..232d0a9e39 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -64,6 +64,67 @@ 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. +Object Libraries +^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_library( OBJECT ...) + +Creates an :ref:`Object Library `. 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 ``$`` as a source, where ``objlib`` is the +object library name. For example: + +.. code-block:: cmake + + add_library(... $ ...) + add_executable(... $ ...) + +will include objlib's object files in a library and an executable +along with those compiled from their own sources. Object libraries +may contain only sources that compile, header files, and other files +that would not affect linking of a normal library (e.g. ``.txt``). +They may contain custom commands generating such sources, but not +``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build +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 +``$``. + +Interface Libraries +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: cmake + + add_library( INTERFACE [IMPORTED [GLOBAL]]) + +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: + +* :command:`set_property`, +* :command:`target_link_libraries(INTERFACE)`, +* :command:`target_link_options(INTERFACE)`, +* :command:`target_include_directories(INTERFACE)`, +* :command:`target_compile_options(INTERFACE)`, +* :command:`target_compile_definitions(INTERFACE)`, and +* :command:`target_sources(INTERFACE)`, + +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 ^^^^^^^^^^^^^^^^^^ @@ -100,35 +161,6 @@ 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 -^^^^^^^^^^^^^^^^ - -.. code-block:: cmake - - add_library( OBJECT ...) - -Creates an :ref:`Object Library `. 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 ``$`` as a source, where ``objlib`` is the -object library name. For example: - -.. code-block:: cmake - - add_library(... $ ...) - add_executable(... $ ...) - -will include objlib's object files in a library and an executable -along with those compiled from their own sources. Object libraries -may contain only sources that compile, header files, and other files -that would not affect linking of a normal library (e.g. ``.txt``). -They may contain custom commands generating such sources, but not -``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Some native build -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 ^^^^^^^^^^^^^^^ @@ -153,35 +185,3 @@ 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 -^^^^^^^^^^^^^^^^^^^ - -.. code-block:: cmake - - add_library( INTERFACE [IMPORTED [GLOBAL]]) - -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: - -* :command:`set_property`, -* :command:`target_link_libraries(INTERFACE)`, -* :command:`target_link_options(INTERFACE)`, -* :command:`target_include_directories(INTERFACE)`, -* :command:`target_compile_options(INTERFACE)`, -* :command:`target_compile_definitions(INTERFACE)`, and -* :command:`target_sources(INTERFACE)`, - -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`.