diff options
| -rw-r--r-- | Help/command/add_compile_options.rst | 17 | ||||
| -rw-r--r-- | Help/command/add_definitions.rst | 24 | ||||
| -rw-r--r-- | Help/command/add_executable.rst | 82 | ||||
| -rw-r--r-- | Help/command/add_library.rst | 167 | ||||
| -rw-r--r-- | Help/command/include_directories.rst | 33 | ||||
| -rw-r--r-- | Help/command/target_compile_definitions.rst | 32 | ||||
| -rw-r--r-- | Help/command/target_compile_options.rst | 40 | ||||
| -rw-r--r-- | Help/command/target_include_directories.rst | 47 | ||||
| -rw-r--r-- | Help/command/target_link_libraries.rst | 175 |
9 files changed, 334 insertions, 283 deletions
diff --git a/Help/command/add_compile_options.rst b/Help/command/add_compile_options.rst index 49b38a2..5d71e11 100644 --- a/Help/command/add_compile_options.rst +++ b/Help/command/add_compile_options.rst @@ -9,9 +9,14 @@ Adds options to the compilation of source files. Adds options to the compiler command line for sources in the current directory and below. This command can be used to add any options, but -alternative commands exist to add preprocessor definitions or include -directories. See documentation of the directory and target -COMPILE_OPTIONS properties for details. Arguments to -add_compile_options may use "generator expressions" with the syntax -``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for -available expressions. +alternative commands exist to add preprocessor definitions +(:command:`target_compile_definitions` and :command:`add_definitions`) or +include directories (:command:`target_include_directories` and +:command:`include_directories`). See documentation of the +:prop_tgt:`directory <COMPILE_OPTIONS>` and +:prop_tgt:` target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. + +Arguments to ``add_compile_options`` may use "generator expressions" with +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. diff --git a/Help/command/add_definitions.rst b/Help/command/add_definitions.rst index 4c72752..a9a6bf5 100644 --- a/Help/command/add_definitions.rst +++ b/Help/command/add_definitions.rst @@ -7,13 +7,21 @@ Adds -D define flags to the compilation of source files. add_definitions(-DFOO -DBAR ...) -Adds flags to the compiler command line for sources in the current +Adds definitions to the compiler command line for sources in the current directory and below. This command can be used to add any flags, but -it was originally intended to add preprocessor definitions. Flags +it is intended to add preprocessor definitions. Flags beginning in -D or /D that look like preprocessor definitions are -automatically added to the COMPILE_DEFINITIONS property for the -current directory. Definitions with non-trivial values may be left in -the set of flags instead of being converted for reasons of backwards -compatibility. See documentation of the directory, target, and source -file COMPILE_DEFINITIONS properties for details on adding preprocessor -definitions to specific scopes and configurations. +automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory +property for the current directory. Definitions with non-trivial values +may be left in the set of flags instead of being converted for reasons of +backwards compatibility. See documentation of the +:prop_dir:`directory <COMPILE_DEFINITIONS>`, +:prop_tgt:`target <COMPILE_DEFINITIONS>`, +:prop_sf:`source file <COMPILE_DEFINITIONS>` ``COMPILE_DEFINITIONS`` +properties for details on adding preprocessor definitions to specific +scopes and configurations. + +Arguments to ``add_definitions`` may use "generator expressions" with +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. diff --git a/Help/command/add_executable.rst b/Help/command/add_executable.rst index d6fd929..231eeed 100644 --- a/Help/command/add_executable.rst +++ b/Help/command/add_executable.rst @@ -7,67 +7,71 @@ Add an executable to the project using the specified source files. add_executable(<name> [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] - source1 source2 ... sourceN) + source1 [source2 ...]) -Adds an executable target called <name> to be built from the source -files listed in the command invocation. The <name> corresponds to the +Adds an executable target called ``<name>`` to be built from the source +files listed in the command invocation. The ``<name>`` corresponds to the logical target name and must be globally unique within a project. The actual file name of the executable built is constructed based on -conventions of the native platform (such as <name>.exe or just -<name>). +conventions of the native platform (such as ``<name>.exe`` or just +``<name>``. By default the executable file will be created in the build tree directory corresponding to the source tree directory in which the command was invoked. See documentation of the -RUNTIME_OUTPUT_DIRECTORY target property to change this location. See -documentation of the OUTPUT_NAME target property to change the <name> -part of the final file name. +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property to change this +location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property +to change the ``<name>`` part of the final file name. -If WIN32 is given the property WIN32_EXECUTABLE will be set on the -target created. See documentation of that target property for +If ``WIN32`` is given the property :prop_tgt:`WIN32_EXECUTABLE` will be +set on the target created. See documentation of that target property for details. -If MACOSX_BUNDLE is given the corresponding property will be set on -the created target. See documentation of the MACOSX_BUNDLE target -property for details. +If ``MACOSX_BUNDLE`` is given the corresponding property will be set on +the created target. See documentation of the :prop_tgt:`MACOSX_BUNDLE` +target property for details. -If EXCLUDE_FROM_ALL is given the corresponding property will be set on -the created target. See documentation of the EXCLUDE_FROM_ALL target -property for details. +If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on +the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` +target property for details. -The add_executable command can also create IMPORTED executable targets -using this signature: +See the :manual:`cmake-buildsystem(7)` manual for more on defining +buildsystem properties. + +-------------------------------------------------------------------------- :: add_executable(<name> IMPORTED [GLOBAL]) -An IMPORTED executable target references an executable file located -outside the project. No rules are generated to build it. 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 executables are useful for -convenient reference from commands like add_custom_command. Details -about the imported executable are specified by setting properties +An :ref:`IMPORTED executable target <Imported Targets>` references an +executable 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`` executables are useful +for convenient reference from commands like :command:`add_custom_command`. +Details about the imported executable are specified by setting properties whose names begin in ``IMPORTED_``. The most important such property is -IMPORTED_LOCATION (and its per-configuration version -IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main -executable file on disk. See documentation of the IMPORTED_* +:prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version +:prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the location of +the main executable file on disk. See documentation of the ``IMPORTED_*`` properties for more information. -The signature +-------------------------------------------------------------------------- :: add_executable(<name> ALIAS <target>) -creates an alias, such that <name> can be used to refer to <target> in -subsequent commands. The <name> does not appear in the generated -buildsystem as a make target. The <target> may not be an IMPORTED -target or an ALIAS. Alias targets can be used as linkable targets, -targets to read properties from, executables for custom commands and -custom targets. They can also be tested for existance with the -regular if(TARGET) subcommand. The <name> may not be used to modify -properties of <target>, that is, it may not be used as the operand of -set_property, set_target_properties, target_link_libraries etc. An -ALIAS target may not be installed of exported. +Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can +be used to refer to ``<target>`` in subsequent commands. The ``<name>`` +does not appear in the generated buildsystem as a make target. The +``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an +``ALIAS``. ``ALIAS`` targets can be used as targets to read properties +from, executables for custom commands and custom targets. They can also be +tested for existance with the regular :command:`if(TARGET)` subcommand. +The ``<name>`` may not be used to modify properties of ``<target>``, 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. diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst index 2d69c89..0944269 100644 --- a/Help/command/add_library.rst +++ b/Help/command/add_library.rst @@ -7,73 +7,76 @@ Add a library to the project using the specified source files. add_library(<name> [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] - source1 source2 ... sourceN) + source1 [source2 ...]) -Adds a library target called <name> to be built from the source files -listed in the command invocation. The <name> corresponds to the +Adds a library target called ``<name>`` to be built from the source files +listed in the command invocation. The ``<name>`` corresponds to the logical target name and must be globally unique within a project. The actual file name of the library built is constructed based on -conventions of the native platform (such as lib<name>.a or -<name>.lib). - -STATIC, SHARED, or MODULE may be given to specify the type of library -to be created. STATIC libraries are archives of object files for use -when linking other targets. SHARED libraries are linked dynamically -and loaded at runtime. MODULE libraries are plugins that are not -linked into other targets but may be loaded dynamically at runtime +conventions of the native platform (such as ``lib<name>.a`` or +``<name>.lib``). + +``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of +library to be created. ``STATIC`` libraries are archives of object files +for use when linking other targets. ``SHARED`` libraries are linked +dynamically and loaded at runtime. ``MODULE`` libraries are plugins that +are not linked into other targets but may be loaded dynamically at runtime using dlopen-like functionality. If no type is given explicitly the -type is STATIC or SHARED based on whether the current value of the -variable BUILD_SHARED_LIBS is true. For SHARED and MODULE libraries -the POSITION_INDEPENDENT_CODE target property is set to TRUE -automatically. - -By default the library file will be created in the build tree -directory corresponding to the source tree directory in which the -command was invoked. See documentation of the -ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and -RUNTIME_OUTPUT_DIRECTORY target properties to change this location. -See documentation of the OUTPUT_NAME target property to change the -<name> part of the final file name. - -If EXCLUDE_FROM_ALL is given the corresponding property will be set on -the created target. See documentation of the EXCLUDE_FROM_ALL target -property for details. - -The add_library command can also create IMPORTED library targets using -this signature: +type is ``STATIC`` or ``SHARED`` based on whether the current value of the +variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and +``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target +property is set to ``ON`` automatically. + +By default the library file will be created in the build tree directory +corresponding to the source tree directory in which thecommand was +invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`, +:prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and +:prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this +location. See documentation of the :prop_tgt:`OUTPUT_NAME` target +property to change the ``<name>`` part of the final file name. + +If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on +the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL` +target property for details. + +See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem +properties. + +-------------------------------------------------------------------------- :: add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED [GLOBAL]) -An IMPORTED library target references a library file located outside -the project. No rules are generated to build it. 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 target_link_libraries. -Details about the imported library are specified by setting properties -whose names begin in ``IMPORTED_``. The most important such property is -IMPORTED_LOCATION (and its per-configuration version -IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main -library file on disk. See documentation of the IMPORTED_* properties -for more information. - -The signature +An :ref:`IMPORTED library target <Imported Targets>` 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 such +property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration +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. + +-------------------------------------------------------------------------- :: add_library(<name> OBJECT <src>...) -creates a special "object library" target. An object library compiles +Creates a special "object library" target. An object library compiles source files but does not archive or link their object files into a -library. Instead other targets created by add_library or -add_executable may reference the objects using an expression of the -form $<TARGET_OBJECTS:objlib> as a source, where "objlib" is the +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 object library name. For example: -:: +.. code-block:: cmake add_library(... $<TARGET_OBJECTS:objlib> ...) add_executable(... $<TARGET_OBJECTS:objlib> ...) @@ -82,48 +85,52 @@ 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 (and headers) that compile to object files. They may contain custom commands generating such sources, but not -PRE_BUILD, PRE_LINK, or POST_BUILD commands. Object libraries cannot -be imported, exported, installed, or linked. Some native build +``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries +cannot be imported, exported, installed, or linked. Some native build 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>. +``$<TARGET_OBJECTS:objlib>``. -The signature +-------------------------------------------------------------------------- :: add_library(<name> ALIAS <target>) -creates an alias, such that <name> can be used to refer to <target> in -subsequent commands. The <name> does not appear in the generated -buildsystem as a make target. The <target> may not be an IMPORTED -target or an ALIAS. Alias targets can be used as linkable targets, -targets to read properties from. They can also be tested for -existance with the regular if(TARGET) subcommand. The <name> may not -be used to modify properties of <target>, that is, it may not be used -as the operand of set_property, set_target_properties, -target_link_libraries etc. An ALIAS target may not be installed of -exported. +Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be +used to refer to ``<target>`` in subsequent commands. The ``<name>`` does +not appear in the generatedbuildsystem as a make target. The ``<target>`` +may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``. +``ALIAS`` targets can be used as linkable targets and as targets to +read properties from. They can also be tested for existance with the +regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used +to modify properties of ``<target>``, 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. -The signature +-------------------------------------------------------------------------- :: add_library(<name> INTERFACE [IMPORTED [GLOBAL]]) -creates an interface target. An interface 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 -:command:`set_property`, :command:`target_link_libraries`, -:command:`target_include_directories` -and :command:`target_compile_defintions` commands, and then it is used as an -argument to :command:`target_link_libraries` like any other target. - -An ``INTERFACE`` :prop_tgt:`IMPORTED` target may also be created with this -signature. An :prop_tgt:`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. :prop_tgt:`IMPORTED` -libraries are useful for convenient reference from commands like -:command:`target_link_libraries`. +Creates an :ref:`Interface Library <Interface Libraries>`. 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 :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 +is used as an argument to :command:`target_link_libraries` like any other +target. + +An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` 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`. diff --git a/Help/command/include_directories.rst b/Help/command/include_directories.rst index 3e0c7a0..f694934 100644 --- a/Help/command/include_directories.rst +++ b/Help/command/include_directories.rst @@ -5,26 +5,31 @@ Add include directories to the build. :: - include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...) + include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...]) Add the given directories to those the compiler uses to search for include files. Relative paths are interpreted as relative to the current source directory. -The include directories are added to the directory property -INCLUDE_DIRECTORIES for the current CMakeLists file. They are also -added to the target property INCLUDE_DIRECTORIES for each target in -the current CMakeLists file. The target property values are the ones -used by the generators. +The include directories are added to the :prop_dir:`INCLUDE_DIRECTORIES` +directory property for the current ``CMakeLists`` file. They are also +added to the :prop_tgt:`INCLUDE_DIRECTORIES` target property for each +target in the current ``CMakeLists`` file. The target property values +are the ones used by the generators. -By default the directories are appended onto the current list of +By default the directories specified are appended onto the current list of directories. This default behavior can be changed by setting -:variable:`CMAKE_INCLUDE_DIRECTORIES_BEFORE` to ON. By using AFTER or BEFORE -explicitly, you can select between appending and prepending, -independent of the default. +:variable:`CMAKE_INCLUDE_DIRECTORIES_BEFORE` to ``ON``. By using +``AFTER`` or ``BEFORE`` explicitly, you can select between appending and +prepending, independent of the default. -If the SYSTEM option is given, the compiler will be told the -directories are meant as system include directories on some platforms -(signalling this setting might achieve effects such as the compiler +If the ``SYSTEM`` option is given, the compiler will be told the +directories are meant as system include directories on some platforms. +Signalling this setting might achieve effects such as the compiler skipping warnings, or these fixed-install system files not being -considered in dependency calculations - see compiler docs). +considered in dependency calculations - see compiler docs. + +Arguments to ``include_directories`` may use "generator expressions" with +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. diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst index d32cc18..3c9fe87 100644 --- a/Help/command/target_compile_definitions.rst +++ b/Help/command/target_compile_definitions.rst @@ -5,20 +5,24 @@ Add compile definitions to a target. :: - target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...] + target_compile_definitions(<target> + <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) -Specify compile definitions to use when compiling a given target. The -named <target> must have been created by a command such as -add_executable or add_library and must not be an IMPORTED target. The -INTERFACE, PUBLIC and PRIVATE keywords are required to specify the -scope of the following arguments. PRIVATE and PUBLIC items will -populate the COMPILE_DEFINITIONS property of <target>. PUBLIC and -INTERFACE items will populate the INTERFACE_COMPILE_DEFINITIONS -property of <target>. The following arguments specify compile -definitions. Repeated calls for the same <target> append items in the -order called. +Specify compile definitions to use when compiling a given <target. The +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:ref:`Imported Target <Imported Targets>`. -Arguments to target_compile_definitions may use "generator expressions" with -the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual -for available expressions. +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`COMPILE_DEFINITIONS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``. The +following arguments specify compile definitions. Repeated calls for the +same ``<target>`` append items in the order called. + +Arguments to ``target_compile_definitions`` may use "generator expressions" +with 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. diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst index 3870abf..0fdeba6 100644 --- a/Help/command/target_compile_options.rst +++ b/Help/command/target_compile_options.rst @@ -5,23 +5,33 @@ Add compile options to a target. :: - target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] + target_compile_options(<target> [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) Specify compile options to use when compiling a given target. The -named <target> must have been created by a command such as -add_executable or add_library and must not be an IMPORTED target. If -BEFORE is specified, the content will be prepended to the property -instead of being appended. +named ``<target>`` must have been created by a command such as +:command:`add_executable` or :command:`add_library` and must not be an +:prop_tgt:`IMPORTED Target`. If ``BEFORE`` is specified, the content will +be prepended to the property instead of being appended. -The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the -scope of the following arguments. PRIVATE and PUBLIC items will -populate the COMPILE_OPTIONS property of <target>. PUBLIC and -INTERFACE items will populate the INTERFACE_COMPILE_OPTIONS property -of <target>. The following arguments specify compile options. -Repeated calls for the same <target> append items in the order called. +This command can be used to add any options, but +alternative commands exist to add preprocessor definitions +(:command:`target_compile_definitions` and :command:`add_definitions`) or +include directories (:command:`target_include_directories` and +:command:`include_directories`). See documentation of the +:prop_tgt:`directory <COMPILE_OPTIONS>` and +:prop_tgt:` target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties. -Arguments to target_compile_options may use "generator expressions" -with the syntax ``$<...>``. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to +specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` +items will populate the :prop_tgt:`COMPILE_OPTIONS` property of +``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``. The +following arguments specify compile options. Repeated calls for the same +``<target>`` append items in the order called. + +Arguments to ``target_compile_options`` may use "generator expressions" +with 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. diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index 2fd7d7f..75f917d 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -5,33 +5,38 @@ Add include directories to a target. :: - target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...] + target_include_directories(<target> [SYSTEM] [BEFORE] + <INTERFACE|PUBLIC|PRIVATE> [items1...] [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...]) Specify include directories or targets to use when compiling a given -target. The named <target> must have been created by a command such -as add_executable or add_library and must not be an IMPORTED target. +target. The named ``<target>`` must have been created by a command such +as :command:`add_executable` or :command:`add_library` and must not be an +:prop_tgt:`IMPORTED` target. -If BEFORE is specified, the content will be prepended to the property +If ``BEFORE`` is specified, the content will be prepended to the property instead of being appended. -The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the -scope of the following arguments. PRIVATE and PUBLIC items will -populate the INCLUDE_DIRECTORIES property of <target>. PUBLIC and -INTERFACE items will populate the INTERFACE_INCLUDE_DIRECTORIES -property of <target>. The following arguments specify include -directories. Specified include directories may be absolute paths or -relative paths. Repeated calls for the same <target> append items in -the order called.If SYSTEM is specified, the compiler will be told the +The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify +the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will +populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``. +``PUBLIC`` and ``INTERFACE`` items will populate the +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` +property of ``<target>``. The following arguments specify include +directories. + +Specified include directories may be absolute paths or relative paths. +Repeated calls for the same <target> append items in the order called. If +``SYSTEM`` is specified, the compiler will be told the directories are meant as system include directories on some platforms (signalling this setting might achieve effects such as the compiler skipping warnings, or these fixed-install system files not being -considered in dependency calculations - see compiler docs). If SYSTEM -is used together with PUBLIC or INTERFACE, the -INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target property will be populated -with the specified directories. - -Arguments to target_include_directories may use "generator -expressions" with the syntax ``$<...>``. -See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. +considered in dependency calculations - see compiler docs). If ``SYSTEM`` +is used together with ``PUBLIC`` or ``INTERFACE``, the +:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be +populated with the specified directories. + +Arguments to ``target_include_directories`` may use "generator expressions" +with 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. diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index eaecf21..bced169 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -9,60 +9,49 @@ Link a target to given libraries. [[debug|optimized|general] <item>] ...) Specify libraries or flags to use when linking a given target. The -named <target> must have been created in the current directory by a -command such as add_executable or add_library. The remaining -arguments specify library names or flags. Repeated calls for the same -<target> append items in the order called. +named ``<target>`` must have been created in the current directory by a +command such as :command:`add_executable` or :command:`add_library`. The +remaining arguments specify library names or flags. Repeated calls for +the same ``<target>`` append items in the order called. If a library name matches that of another target in the project a -dependency will automatically be added in the build system to make -sure the library being linked is up-to-date before the target links. -Item names starting with '-', but not '-l' or '-framework', are -treated as linker flags. +dependency will automatically be added in the build system to make sure +the library being linked is up-to-date before the target links. Item names +starting with ``-``, but not ``-l`` or ``-framework``, are treated as +linker flags. -A "debug", "optimized", or "general" keyword indicates that the +A ``debug``, ``optimized``, or ``general`` keyword indicates that the library immediately following it is to be used only for the -corresponding build configuration. The "debug" keyword corresponds to +corresponding build configuration. The ``debug`` keyword corresponds to the Debug configuration (or to configurations named in the -DEBUG_CONFIGURATIONS global property if it is set). The "optimized" -keyword corresponds to all other configurations. The "general" -keyword corresponds to all configurations, and is purely optional -(assumed if omitted). Higher granularity may be achieved for -per-configuration rules by creating and linking to IMPORTED library -targets. See the IMPORTED mode of the add_library command for more -information. +:prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). The +``optimized`` keyword corresponds to all other configurations. The +``general`` keyword corresponds to all configurations, and is purely +optional (assumed if omitted). Higher granularity may be achieved for +per-configuration rules by creating and linking to +:ref:`IMPORTED library targets <Imported Targets>`. Library dependencies are transitive by default with this signature. When this target is linked into another target then the libraries linked to this target will appear on the link line for the other target too. This transitive "link interface" is stored in the -INTERFACE_LINK_LIBRARIES target property when policy CMP0022 is set to -NEW and may be overridden by setting the property directly. -(When CMP0022 is not set to NEW, transitive linking is builtin but may -be overridden by the LINK_INTERFACE_LIBRARIES property. Calls to other -signatures of this command may set the property making any libraries -linked exclusively by this signature private.) - -CMake will also propagate "usage requirements" from linked library -targets. Usage requirements affect compilation of sources in the -<target>. They are specified by properties defined on linked targets. -During generation of the build system, CMake integrates usage -requirement property values with the corresponding build properties -for <target>: - -:: - - INTERFACE_COMPILE_DEFINITONS: Appends to COMPILE_DEFINITONS - INTERFACE_INCLUDE_DIRECTORIES: Appends to INCLUDE_DIRECTORIES - INTERFACE_POSITION_INDEPENDENT_CODE: Sets POSITION_INDEPENDENT_CODE - or checked for consistency with existing value +:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden +by setting the property directly. When :policy:`CMP0022` is not set to +``NEW``, transitive linking is built in but may be overridden by the +:prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Calls to other signatures +of this command may set the property making any libraries linked +exclusively by this signature private. +CMake will also propagate :ref:`usage requirements <Target Usage Requirements>` +from linked library targets. Usage requirements of dependencies affect +compilation of sources in the ``<target>``. +If an ``<item>`` is a library in a Mac OX framework, the ``Headers`` +directory of the framework will also be processed as a +:ref:`usage requirement <Target Usage Requirements>`. This has the same +effect as passing the framework directory as an include directory. -If an <item> is a library in a Mac OX framework, the Headers directory -of the framework will also be processed as a "usage requirement". -This has the same effect as passing the framework directory as an -include directory. +-------------------------------------------------------------------------- :: @@ -70,34 +59,44 @@ include directory. <PRIVATE|PUBLIC|INTERFACE> <lib> ... [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...]) -The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both -the link dependencies and the link interface in one command. -Libraries and targets following PUBLIC are linked to, and are made -part of the link interface. Libraries and targets following PRIVATE +The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to +specify both the link dependencies and the link interface in one command. +Libraries and targets following ``PUBLIC`` are linked to, and are made +part of the link interface. Libraries and targets following ``PRIVATE`` are linked to, but are not made part of the link interface. Libraries -following INTERFACE are appended to the link interface and are not -used for linking <target>. +following ``INTERFACE`` are appended to the link interface and are not +used for linking ``<target>``. + +-------------------------------------------------------------------------- :: target_link_libraries(<target> LINK_INTERFACE_LIBRARIES [[debug|optimized|general] <lib>] ...) -The LINK_INTERFACE_LIBRARIES mode appends the libraries to the -INTERFACE_LINK_LIBRARIES target property instead of using them for -linking. If policy CMP0022 is not NEW, then this mode also appends -libraries to the LINK_INTERFACE_LIBRARIES and its per-configuration -equivalent. This signature is for compatibility only. Prefer the -INTERFACE mode instead. Libraries specified as "debug" are wrapped in -a generator expression to correspond to debug builds. If policy -CMP0022 is not NEW, the libraries are also appended to the -LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties -corresponding to configurations listed in the DEBUG_CONFIGURATIONS -global property if it is set). Libraries specified as "optimized" are -appended to the INTERFACE_LINK_LIBRARIES property. If policy CMP0022 -is not NEW, they are also appended to the LINK_INTERFACE_LIBRARIES -property. Libraries specified as "general" (or without any keyword) -are treated as if specified for both "debug" and "optimized". +The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them +for linking. If policy :policy:`CMP0022` is not ``NEW``, then this mode +also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its +per-configuration equivalent. + +This signature is for compatibility only. Prefer the ``INTERFACE`` mode +instead. + +Libraries specified as ``debug`` are wrapped in a generator expression to +correspond to debug builds. If policy :policy:`CMP0022` is +not ``NEW``, the libraries are also appended to the +:prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>` +property (or to the properties corresponding to configurations listed in +the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). +Libraries specified as ``optimized`` are appended to the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` property. If policy :policy:`CMP0022` +is not ``NEW``, they are also appended to the +:prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Libraries specified as +``general`` (or without any keyword) are treated as if specified for both +``debug`` and ``optimized``. + +-------------------------------------------------------------------------- :: @@ -107,23 +106,26 @@ are treated as if specified for both "debug" and "optimized". [<LINK_PRIVATE|LINK_PUBLIC> [[debug|optimized|general] <lib>] ...]) -The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the -link dependencies and the link interface in one command. This -signature is for compatibility only. Prefer the PUBLIC or PRIVATE -keywords instead. Libraries and targets following LINK_PUBLIC are -linked to, and are made part of the INTERFACE_LINK_LIBRARIES. If -policy CMP0022 is not NEW, they are also made part of the -LINK_INTERFACE_LIBRARIES. Libraries and targets following -LINK_PRIVATE are linked to, but are not made part of the -INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES). - -The library dependency graph is normally acyclic (a DAG), but in the -case of mutually-dependent STATIC libraries CMake allows the graph to -contain cycles (strongly connected components). When another target -links to one of the libraries CMake repeats the entire connected -component. For example, the code +The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both +the link dependencies and the link interface in one command. -:: +This signature is for compatibility only. Prefer the ``PUBLIC`` or +``PRIVATE`` keywords instead. + +Libraries and targets following ``LINK_PUBLIC`` are linked to, and are +made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`. If policy +:policy:`CMP0022` is not ``NEW``, they are also made part of the +:prop_tgt:`LINK_INTERFACE_LIBRARIES`. Libraries and targets following +``LINK_PRIVATE`` are linked to, but are not made part of the +:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`). + +The library dependency graph is normally acyclic (a DAG), but in the case +of mutually-dependent ``STATIC`` libraries CMake allows the graph to +contain cycles (strongly connected components). When another target links +to one of the libraries, CMake repeats the entire connected component. +For example, the code + +.. code-block:: cmake add_library(A STATIC a.c) add_library(B STATIC b.c) @@ -132,15 +134,16 @@ component. For example, the code add_executable(main main.c) target_link_libraries(main A) -links 'main' to 'A B A B'. (While one repetition is usually -sufficient, pathological object file and symbol arrangements can -require more. One may handle such cases by manually repeating the -component in the last target_link_libraries call. However, if two -archives are really so interdependent they should probably be combined -into a single archive.) +links ``main`` to ``A B A B``. While one repetition is usually +sufficient, pathological object file and symbol arrangements can require +more. One may handle such cases by manually repeating the component in +the last ``target_link_libraries`` call. However, if two archives are +really so interdependent they should probably be combined into a single +archive. Arguments to target_link_libraries may use "generator expressions" with the syntax ``$<...>``. Note however, that generator expressions -will not be used in OLD handling of CMP0003 or CMP0004. +will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`. See the :manual:`cmake-generator-expressions(7)` manual for available -expressions. +expressions. See the :manual:`cmake-buildsystem(7)` manual for more on +defining buildsystem properties. |