Help: Mark up the buildsystem commands documentation
Cross-link to the cmake-buildsystem manual.
This commit is contained in:
Stephen Kelly
Brad King
parent
a683262a72
commit
ba4c2fa8fd
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
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
|
||||
``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.
|
||||
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 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.
|
||||
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 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_library command can also create IMPORTED library targets using
|
||||
this signature:
|
||||
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.
|
||||
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.
|
||||
|
||||
The signature
|
||||
--------------------------------------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
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`` :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`.
|
||||
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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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.
|
||||
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
|
||||
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.)
|
||||
: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 "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>:
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
|
||||
|
||||
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 ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
|
||||
the link dependencies and the link interface in one command.
|
||||
|
||||
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
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue