Commit 6abdc6c1 authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

Merge topic 'update-buildsystem-docs'

cc46b702 Help: Adjust the QtAutogen properties to the common style.
f371545d Help: Use ``True`` and ``False`` for IMPORTED values.
3879c847 Help: Document relation of properties to the rest of the buildsystem.
ba4c2fa8 Help: Mark up the buildsystem commands documentation
a683262a Help: Note that the compatible interface properties must not intersect.
fbe01bed Help: Specify how to order and modify transitively set property values.
645500b4 Help: Add hyperlink targets to some manual sections.
85a4fad7 Help: Use ``inline-literals`` to mark generator expressions.
a0fa0253 Help: Mark up references to NEW and OLD policy settings properly.
6c02e7f4 Help: Add a style guide.
91fbff88 Help: Fix typos
parents f5552818 cc46b702
......@@ -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.
......@@ -113,7 +113,7 @@ dependency that would cause the custom command to re-run whenever the
executable is recompiled.
Arguments to COMMAND may use "generator expressions" with the syntax
"$<...>". See the :manual:`cmake-generator-expressions(7)` manual for
``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for
available expressions.
Note that tgt is not added as a dependency of the target this
......
......@@ -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.
......@@ -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.
......@@ -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`.
......@@ -35,7 +35,7 @@ a WORKING_DIRECTORY option is given then the test will be executed in
the given directory.
Arguments after COMMAND may use "generator expressions" with the syntax
"$<...>". See the :manual:`cmake-generator-expressions(7)` manual for
``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for
available expressions.
Note that tgt is not added as a dependency of the target this
......
......@@ -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.
......@@ -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.
......@@ -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.
......@@ -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.
......@@ -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