From 4054534cc63009652f2fa54f962b1b4fd318de4b Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 12 Jun 2014 13:25:53 -0400 Subject: Help: Mention INTERFACE_SOURCES as settable for INTERFACE libs The add_library(INTERFACE) and Interface Libraries documentation list all the INTERFACE_* properties and target_* commands that can be used to define the interface. Add INTERFACE_SOURCES and target_sources() to these lists for completeness. --- Help/command/add_library.rst | 5 +++-- Help/manual/cmake-buildsystem.7.rst | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index e93ef53..746d524 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -124,8 +124,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. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index fdd1be4..e4b58c0 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -786,11 +786,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. -- cgit v0.12 From 50dca47106a17fe9a4a929243fd12f84d4f95e79 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 12 Jun 2014 13:40:34 -0400 Subject: Help: Organize Binary Targets section of cmake-buildsystem.7 Add a subsection for Binary Executables just before Binary Library Types. Divide the library section into Normal Libraries and Object Libraries. --- Help/manual/cmake-buildsystem.7.rst | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index e4b58c0..a7402f7 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -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 ` +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 ` -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 ========================================== -- cgit v0.12 From d8319f0fc99fb628cbe33c3cc9169c2bd3a97f40 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 12 Jun 2014 13:54:27 -0400 Subject: Help: Update style guide to use section headers for command signatures In order to be able to link to specific command signatures we need to use a section header instead of a horizontal separator. --- Help/manual/cmake-developer.7.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 9851c12..cd979c9 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -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 + ^^^^^^^^^^^^^^^^ :: -- cgit v0.12 From a81531817ef26f4e23933274c2317fd698336c04 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 12 Jun 2014 13:57:37 -0400 Subject: Help: Organize add_library command documentation Add a section for each library type signature. Add a table of contents at the top for the html builder. --- Help/command/add_library.rst | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 746d524..18d8fe3 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -1,8 +1,15 @@ add_library ----------- +.. only:: html + + .. contents:: + Add a library to the project using the specified source files. +Normal Libraries +^^^^^^^^^^^^^^^^ + :: add_library( [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,7 +73,8 @@ variant :prop_tgt:`IMPORTED_LOCATION_`) which specifies the location of the main library file on disk. See documentation of the ``IMPORTED_*`` and ``INTERFACE_*`` properties for more information. --------------------------------------------------------------------------- +Object Libraries +^^^^^^^^^^^^^^^^ :: @@ -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 ``$``. --------------------------------------------------------------------------- +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 +^^^^^^^^^^^^^^^^^^^ :: -- cgit v0.12 From 20f5460288eea238aa6c5d4257df90d7d32f9dae Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 12 Jun 2014 13:59:13 -0400 Subject: Help: Link to Object Library docs from add_library --- Help/command/add_library.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 18d8fe3..f19b5c0 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -80,8 +80,8 @@ Object Libraries add_library( OBJECT ...) -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 `. 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 -- cgit v0.12