kolan/CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'update-buildsystem-docs'

Browse Source 
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
This commit is contained in:
Brad King 2014-02-06 16:19:02 -05:00 committed by CMake Topic Stage
commit 6abdc6c16a
43 changed files with 803 additions and 474 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
Help/command/add_compile_options.rst
View File

@ -9,9 +9,14 @@ Adds options to the compilation of source files.
Adds options to the compiler command line for sources in the current 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 directory and below. This command can be used to add any options, but
alternative commands exist to add preprocessor definitions or include alternative commands exist to add preprocessor definitions
directories. See documentation of the directory and target (:command:`target_compile_definitions` and :command:`add_definitions`) or
COMPILE_OPTIONS properties for details. Arguments to include directories (:command:`target_include_directories` and
add_compile_options may use "generator expressions" with the syntax :command:`include_directories`). See documentation of the
"$<...>". See the :manual:`cmake-generator-expressions(7)` manual for :prop_tgt:`directory <COMPILE_OPTIONS>` and
available expressions. :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.

2
Help/command/add_custom_command.rst
View File

@ -113,7 +113,7 @@ dependency that would cause the custom command to re-run whenever the
executable is recompiled. executable is recompiled.
Arguments to COMMAND may use "generator expressions" with the syntax 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. available expressions.
Note that tgt is not added as a dependency of the target this Note that tgt is not added as a dependency of the target this

24
Help/command/add_definitions.rst
View File

@ -7,13 +7,21 @@ Adds -D define flags to the compilation of source files.
add_definitions(-DFOO -DBAR ...) 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 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 beginning in -D or /D that look like preprocessor definitions are
automatically added to the COMPILE_DEFINITIONS property for the automatically added to the :prop_dir:`COMPILE_DEFINITIONS` directory
current directory. Definitions with non-trivial values may be left in property for the current directory. Definitions with non-trivial values
the set of flags instead of being converted for reasons of backwards may be left in the set of flags instead of being converted for reasons of
compatibility. See documentation of the directory, target, and source backwards compatibility. See documentation of the
file COMPILE_DEFINITIONS properties for details on adding preprocessor :prop_dir:`directory <COMPILE_DEFINITIONS>`,
definitions to specific scopes and configurations. :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.

82
Help/command/add_executable.rst
View File

@ -7,67 +7,71 @@ Add an executable to the project using the specified source files.
add_executable(<name> [WIN32] [MACOSX_BUNDLE] add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL] [EXCLUDE_FROM_ALL]
source1 source2 ... sourceN) source1 [source2 ...])
Adds an executable target called <name> to be built from the source Adds an executable target called ``<name>`` to be built from the source
files listed in the command invocation. The <name> corresponds to the files listed in the command invocation. The ``<name>`` corresponds to the
logical target name and must be globally unique within a project. The logical target name and must be globally unique within a project. The
actual file name of the executable built is constructed based on actual file name of the executable built is constructed based on
conventions of the native platform (such as <name>.exe or just conventions of the native platform (such as ``<name>.exe`` or just
<name>). ``<name>``.
By default the executable file will be created in the build tree By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the directory corresponding to the source tree directory in which the
command was invoked. See documentation of the command was invoked. See documentation of the
RUNTIME_OUTPUT_DIRECTORY target property to change this location. See :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target property to change this
documentation of the OUTPUT_NAME target property to change the <name> location. See documentation of the :prop_tgt:`OUTPUT_NAME` target property
part of the final file name. to change the ``<name>`` part of the final file name.
If WIN32 is given the property WIN32_EXECUTABLE will be set on the If ``WIN32`` is given the property :prop_tgt:`WIN32_EXECUTABLE` will be
target created. See documentation of that target property for set on the target created. See documentation of that target property for
details. details.
If MACOSX_BUNDLE is given the corresponding property will be set on If ``MACOSX_BUNDLE`` is given the corresponding property will be set on
the created target. See documentation of the MACOSX_BUNDLE target the created target. See documentation of the :prop_tgt:`MACOSX_BUNDLE`
property for details. target property for details.
If EXCLUDE_FROM_ALL is given the corresponding property will be set on If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the EXCLUDE_FROM_ALL target the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
property for details. target property for details.
The add_executable command can also create IMPORTED executable targets See the :manual:`cmake-buildsystem(7)` manual for more on defining
using this signature: buildsystem properties.
--------------------------------------------------------------------------
:: ::
add_executable(<name> IMPORTED [GLOBAL]) add_executable(<name> IMPORTED [GLOBAL])
An IMPORTED executable target references an executable file located An :ref:`IMPORTED executable target <Imported Targets>` references an
outside the project. No rules are generated to build it. The target executable file located outside the project. No rules are generated to
name has scope in the directory in which it is created and below, but build it, and the :prop_tgt:`IMPORTED` target property is ``True``. The
the GLOBAL option extends visibility. It may be referenced like any target name has scope in the directory in which it is created and below, but
target built within the project. IMPORTED executables are useful for the ``GLOBAL`` option extends visibility. It may be referenced like any
convenient reference from commands like add_custom_command. Details target built within the project. ``IMPORTED`` executables are useful
about the imported executable are specified by setting properties 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 whose names begin in ``IMPORTED_``. The most important such property is
IMPORTED_LOCATION (and its per-configuration version :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration version
IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the location of
executable file on disk. See documentation of the IMPORTED_* the main executable file on disk. See documentation of the ``IMPORTED_*``
properties for more information. properties for more information.
The signature --------------------------------------------------------------------------
:: ::
add_executable(<name> ALIAS <target>) add_executable(<name> ALIAS <target>)
creates an alias, such that <name> can be used to refer to <target> in Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
subsequent commands. The <name> does not appear in the generated be used to refer to ``<target>`` in subsequent commands. The ``<name>``
buildsystem as a make target. The <target> may not be an IMPORTED does not appear in the generated buildsystem as a make target. The
target or an ALIAS. Alias targets can be used as linkable targets, ``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an
targets to read properties from, executables for custom commands and ``ALIAS``. ``ALIAS`` targets can be used as targets to read properties
custom targets. They can also be tested for existance with the from, executables for custom commands and custom targets. They can also be
regular if(TARGET) subcommand. The <name> may not be used to modify tested for existance with the regular :command:`if(TARGET)` subcommand.
properties of <target>, that is, it may not be used as the operand of The ``<name>`` may not be used to modify properties of ``<target>``, that
set_property, set_target_properties, target_link_libraries etc. An is, it may not be used as the operand of :command:`set_property`,
ALIAS target may not be installed of exported. :command:`set_target_properties`, :command:`target_link_libraries` etc.
An ``ALIAS`` target may not be installed or exported.

155
Help/command/add_library.rst
View File

@ -7,73 +7,76 @@ Add a library to the project using the specified source files.
add_library(<name> [STATIC | SHARED | MODULE] add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL] [EXCLUDE_FROM_ALL]
source1 source2 ... sourceN) source1 [source2 ...])
Adds a library target called <name> to be built from the source files Adds a library target called ``<name>`` to be built from the source files
listed in the command invocation. The <name> corresponds to the listed in the command invocation. The ``<name>`` corresponds to the
logical target name and must be globally unique within a project. The logical target name and must be globally unique within a project. The
actual file name of the library built is constructed based on actual file name of the library built is constructed based on
conventions of the native platform (such as lib<name>.a or conventions of the native platform (such as ``lib<name>.a`` or
<name>.lib). ``<name>.lib``).
STATIC, SHARED, or MODULE may be given to specify the type of library ``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
to be created. STATIC libraries are archives of object files for use library to be created. ``STATIC`` libraries are archives of object files
when linking other targets. SHARED libraries are linked dynamically for use when linking other targets. ``SHARED`` libraries are linked
and loaded at runtime. MODULE libraries are plugins that are not dynamically and loaded at runtime. ``MODULE`` libraries are plugins that
linked into other targets but may be loaded dynamically at runtime are not linked into other targets but may be loaded dynamically at runtime
using dlopen-like functionality. If no type is given explicitly the using dlopen-like functionality. If no type is given explicitly the
type is STATIC or SHARED based on whether the current value of 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 variable :variable:`BUILD_SHARED_LIBS` is ``ON``. For ``SHARED`` and
the POSITION_INDEPENDENT_CODE target property is set to TRUE ``MODULE`` libraries the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
automatically. property is set to ``ON`` automatically.
By default the library file will be created in the build tree By default the library file will be created in the build tree directory
directory corresponding to the source tree directory in which the corresponding to the source tree directory in which thecommand was
command was invoked. See documentation of the invoked. See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`, and
RUNTIME_OUTPUT_DIRECTORY target properties to change this location. :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` target properties to change this
See documentation of the OUTPUT_NAME target property to change the location. See documentation of the :prop_tgt:`OUTPUT_NAME` target
<name> part of the final file name. property to change the ``<name>`` part of the final file name.
If EXCLUDE_FROM_ALL is given the corresponding property will be set on If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the EXCLUDE_FROM_ALL target the created target. See documentation of the :prop_tgt:`EXCLUDE_FROM_ALL`
property for details. target property for details.
The add_library command can also create IMPORTED library targets using See the :manual:`cmake-buildsystem(7)` manual for more on defining buildsystem
this signature: properties.
--------------------------------------------------------------------------
:: ::
add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
[GLOBAL]) [GLOBAL])
An IMPORTED library target references a library file located outside An :ref:`IMPORTED library target <Imported Targets>` references a library
the project. No rules are generated to build it. The target name has file located outside the project. No rules are generated to build it, and
scope in the directory in which it is created and below, but the the :prop_tgt:`IMPORTED` target property is ``True``. The target name has
GLOBAL option extends visibility. It may be referenced like any scope in the directory in which it is created and below, but the ``GLOBAL``
target built within the project. IMPORTED libraries are useful for option extends visibility. It may be referenced like any target built
convenient reference from commands like target_link_libraries. within the project. ``IMPORTED`` libraries are useful for convenient
Details about the imported library are specified by setting properties reference from commands like :command:`target_link_libraries`. Details
whose names begin in ``IMPORTED_``. The most important such property is about the imported library are specified by setting properties whose names
IMPORTED_LOCATION (and its per-configuration version begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such
IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main property is :prop_tgt:`IMPORTED_LOCATION` (and its per-configuration
library file on disk. See documentation of the IMPORTED_* properties variant :prop_tgt:`IMPORTED_LOCATION_<CONFIG>`) which specifies the
for more information. 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>...) 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 source files but does not archive or link their object files into a
library. Instead other targets created by add_library or library. Instead other targets created by :command:`add_library` or
add_executable may reference the objects using an expression of the :command:`add_executable` may reference the objects using an expression of the
form $<TARGET_OBJECTS:objlib> as a source, where "objlib" is the form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the
object library name. For example: object library name. For example:
:: .. code-block:: cmake
add_library(... $<TARGET_OBJECTS:objlib> ...) add_library(... $<TARGET_OBJECTS:objlib> ...)
add_executable(... $<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 along with those compiled from their own sources. Object libraries
may contain only sources (and headers) that compile to object files. may contain only sources (and headers) that compile to object files.
They may contain custom commands generating such sources, but not They may contain custom commands generating such sources, but not
PRE_BUILD, PRE_LINK, or POST_BUILD commands. Object libraries cannot ``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries
be imported, exported, installed, or linked. Some native build cannot be imported, exported, installed, or linked. Some native build
systems may not like targets that have only object files, so consider systems may not like targets that have only object files, so consider
adding at least one real source file to any target that references 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>) add_library(<name> ALIAS <target>)
creates an alias, such that <name> can be used to refer to <target> in Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
subsequent commands. The <name> does not appear in the generated used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
buildsystem as a make target. The <target> may not be an IMPORTED not appear in the generatedbuildsystem as a make target. The ``<target>``
target or an ALIAS. Alias targets can be used as linkable targets, may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
targets to read properties from. They can also be tested for ``ALIAS`` targets can be used as linkable targets and as targets to
existance with the regular if(TARGET) subcommand. The <name> may not read properties from. They can also be tested for existance with the
be used to modify properties of <target>, that is, it may not be used regular :command:`if(TARGET)` subcommand. The ``<name>`` may not be used
as the operand of set_property, set_target_properties, to modify properties of ``<target>``, that is, it may not be used as the
target_link_libraries etc. An ALIAS target may not be installed of operand of :command:`set_property`, :command:`set_target_properties`,
exported. :command:`target_link_libraries` etc. An ``ALIAS`` target may not be
installed or exported.
The signature --------------------------------------------------------------------------
:: ::
add_library(<name> INTERFACE [IMPORTED [GLOBAL]]) add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
creates an interface target. An interface target does not directly Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE``
create build output, though it may have properties set on it and it library target does not directly create build output, though it may
may be installed, exported and imported. Typically the INTERFACE_* have properties set on it and it may be installed, exported and
properties are populated on the interface target using the imported. Typically the ``INTERFACE_*`` properties are populated on
:command:`set_property`, :command:`target_link_libraries`, the interface target using the :command:`set_property`,
:command:`target_include_directories` :command:`target_link_libraries(INTERFACE)`,
and :command:`target_compile_defintions` commands, and then it is used as an :command:`target_include_directories(INTERFACE)`,
argument to :command:`target_link_libraries` like any other target. :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 An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be
signature. An :prop_tgt:`IMPORTED` library target references a library defined created with this signature. An ``IMPORTED`` library target references a
outside the project. The target name has scope in the directory in which it is library defined outside the project. The target name has scope in the
created and below, but the ``GLOBAL`` option extends visibility. It may be directory in which it is created and below, but the ``GLOBAL`` option
referenced like any target built within the project. :prop_tgt:`IMPORTED` extends visibility. It may be referenced like any target built within
libraries are useful for convenient reference from commands like the project. ``IMPORTED`` libraries are useful for convenient reference
:command:`target_link_libraries`. from commands like :command:`target_link_libraries`.

2
Help/command/add_test.rst
View File

@ -35,7 +35,7 @@ a WORKING_DIRECTORY option is given then the test will be executed in
the given directory. the given directory.
Arguments after COMMAND may use "generator expressions" with the syntax 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. available expressions.
Note that tgt is not added as a dependency of the target this Note that tgt is not added as a dependency of the target this

33
Help/command/include_directories.rst
View File

@ -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 Add the given directories to those the compiler uses to search for
include files. Relative paths are interpreted as relative to the include files. Relative paths are interpreted as relative to the
current source directory. current source directory.
The include directories are added to the directory property The include directories are added to the :prop_dir:`INCLUDE_DIRECTORIES`
INCLUDE_DIRECTORIES for the current CMakeLists file. They are also directory property for the current ``CMakeLists`` file. They are also
added to the target property INCLUDE_DIRECTORIES for each target in added to the :prop_tgt:`INCLUDE_DIRECTORIES` target property for each
the current CMakeLists file. The target property values are the ones target in the current ``CMakeLists`` file. The target property values
used by the generators. 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 directories. This default behavior can be changed by setting
:variable:`CMAKE_INCLUDE_DIRECTORIES_BEFORE` to ON. By using AFTER or BEFORE :variable:`CMAKE_INCLUDE_DIRECTORIES_BEFORE` to ``ON``. By using
explicitly, you can select between appending and prepending, ``AFTER`` or ``BEFORE`` explicitly, you can select between appending and
independent of the default. prepending, independent of the default.
If the SYSTEM option is given, the compiler will be told the If the ``SYSTEM`` option is given, the compiler will be told the
directories are meant as system include directories on some platforms directories are meant as system include directories on some platforms.
(signalling this setting might achieve effects such as the compiler Signalling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being 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.

32
Help/command/target_compile_definitions.rst
View File

@ -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...] ...]) [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specify compile definitions to use when compiling a given target. The Specify compile definitions to use when compiling a given <target. The
named <target> must have been created by a command such as named ``<target>`` must have been created by a command such as
add_executable or add_library and must not be an IMPORTED target. The :command:`add_executable` or :command:`add_library` and must not be an
INTERFACE, PUBLIC and PRIVATE keywords are required to specify the :ref:`Imported Target <Imported Targets>`.
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.
Arguments to target_compile_definitions may use "generator expressions" with The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
the syntax "$<...>". See the :manual:`cmake-generator-expressions(7)` manual specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
for available expressions. 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.

40
Help/command/target_compile_options.rst
View File

@ -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...] ...]) [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specify compile options to use when compiling a given target. The Specify compile options to use when compiling a given target. The
named <target> must have been created by a command such as named ``<target>`` must have been created by a command such as
add_executable or add_library and must not be an IMPORTED target. If :command:`add_executable` or :command:`add_library` and must not be an
BEFORE is specified, the content will be prepended to the property :prop_tgt:`IMPORTED Target`. If ``BEFORE`` is specified, the content will
instead of being appended. be prepended to the property instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the This command can be used to add any options, but
scope of the following arguments. PRIVATE and PUBLIC items will alternative commands exist to add preprocessor definitions
populate the COMPILE_OPTIONS property of <target>. PUBLIC and (:command:`target_compile_definitions` and :command:`add_definitions`) or
INTERFACE items will populate the INTERFACE_COMPILE_OPTIONS property include directories (:command:`target_include_directories` and
of <target>. The following arguments specify compile options. :command:`include_directories`). See documentation of the
Repeated calls for the same <target> append items in the order called. :prop_tgt:`directory <COMPILE_OPTIONS>` and
:prop_tgt:` target <COMPILE_OPTIONS>` ``COMPILE_OPTIONS`` properties.
Arguments to target_compile_options may use "generator expressions" The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
with the syntax "$<...>". specify the scope of the following arguments. ``PRIVATE`` and ``PUBLIC``
See the :manual:`cmake-generator-expressions(7)` manual for available items will populate the :prop_tgt:`COMPILE_OPTIONS` property of
expressions. ``<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.

45
Help/command/target_include_directories.rst
View File

@ -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...] ...]) [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
Specify include directories or targets to use when compiling a given Specify include directories or targets to use when compiling a given
target. The named <target> must have been created by a command such 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. 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. instead of being appended.
The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
scope of the following arguments. PRIVATE and PUBLIC items will the scope of the following arguments. ``PRIVATE`` and ``PUBLIC`` items will
populate the INCLUDE_DIRECTORIES property of <target>. PUBLIC and populate the :prop_tgt:`INCLUDE_DIRECTORIES` property of ``<target>``.
INTERFACE items will populate the INTERFACE_INCLUDE_DIRECTORIES ``PUBLIC`` and ``INTERFACE`` items will populate the
property of <target>. The following arguments specify include :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
directories. Specified include directories may be absolute paths or property of ``<target>``. The following arguments specify include
relative paths. Repeated calls for the same <target> append items in directories.
the order called.If SYSTEM is specified, the compiler will be told the
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 directories are meant as system include directories on some platforms
(signalling this setting might achieve effects such as the compiler (signalling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being skipping warnings, or these fixed-install system files not being
considered in dependency calculations - see compiler docs). If SYSTEM considered in dependency calculations - see compiler docs). If ``SYSTEM``
is used together with PUBLIC or INTERFACE, the is used together with ``PUBLIC`` or ``INTERFACE``, the
INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target property will be populated :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
with the specified directories. populated with the specified directories.
Arguments to target_include_directories may use "generator Arguments to ``target_include_directories`` may use "generator expressions"
expressions" with the syntax "$<...>". with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
See the :manual:`cmake-generator-expressions(7)` manual for available manual for available expressions. See the :manual:`cmake-buildsystem(7)`
expressions. manual for more on defining buildsystem properties.

175
Help/command/target_link_libraries.rst
View File

@ -9,60 +9,49 @@ Link a target to given libraries.
[[debug|optimized|general] <item>] ...) [[debug|optimized|general] <item>] ...)
Specify libraries or flags to use when linking a given target. The Specify libraries or flags to use when linking a given target. The
named <target> must have been created in the current directory by a named ``<target>`` must have been created in the current directory by a
command such as add_executable or add_library. The remaining command such as :command:`add_executable` or :command:`add_library`. The
arguments specify library names or flags. Repeated calls for the same remaining arguments specify library names or flags. Repeated calls for
<target> append items in the order called. the same ``<target>`` append items in the order called.
If a library name matches that of another target in the project a If a library name matches that of another target in the project a
dependency will automatically be added in the build system to make dependency will automatically be added in the build system to make sure
sure the library being linked is up-to-date before the target links. the library being linked is up-to-date before the target links. Item names
Item names starting with '-', but not '-l' or '-framework', are starting with ``-``, but not ``-l`` or ``-framework``, are treated as
treated as linker flags. 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 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 the Debug configuration (or to configurations named in the
DEBUG_CONFIGURATIONS global property if it is set). The "optimized" :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set). The
keyword corresponds to all other configurations. The "general" ``optimized`` keyword corresponds to all other configurations. The
keyword corresponds to all configurations, and is purely optional ``general`` keyword corresponds to all configurations, and is purely
(assumed if omitted). Higher granularity may be achieved for optional (assumed if omitted). Higher granularity may be achieved for
per-configuration rules by creating and linking to IMPORTED library per-configuration rules by creating and linking to
targets. See the IMPORTED mode of the add_library command for more :ref:`IMPORTED library targets <Imported Targets>`.
information.
Library dependencies are transitive by default with this signature. Library dependencies are transitive by default with this signature.
When this target is linked into another target then the libraries When this target is linked into another target then the libraries
linked to this target will appear on the link line for the other linked to this target will appear on the link line for the other
target too. This transitive "link interface" is stored in the target too. This transitive "link interface" is stored in the
INTERFACE_LINK_LIBRARIES target property when policy CMP0022 is set to :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property and may be overridden
NEW and may be overridden by setting the property directly. by setting the property directly. When :policy:`CMP0022` is not set to
(When CMP0022 is not set to NEW, transitive linking is builtin but may ``NEW``, transitive linking is built in but may be overridden by the
be overridden by the LINK_INTERFACE_LIBRARIES property. Calls to other :prop_tgt:`LINK_INTERFACE_LIBRARIES` property. Calls to other signatures
signatures of this command may set the property making any libraries of this command may set the property making any libraries linked
linked exclusively by this signature private.) exclusively by this signature private.
CMake will also propagate "usage requirements" from linked library CMake will also propagate :ref:`usage requirements <Target Usage Requirements>`
targets. Usage requirements affect compilation of sources in the from linked library targets. Usage requirements of dependencies affect
<target>. They are specified by properties defined on linked targets. compilation of sources in the ``<target>``.
During generation of the build system, CMake integrates usage
requirement property values with the corresponding build properties
for <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> ...
[<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...]) [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
the link dependencies and the link interface in one command. specify both the link dependencies and the link interface in one command.
Libraries and targets following PUBLIC are linked to, and are made Libraries and targets following ``PUBLIC`` are linked to, and are made
part of the link interface. Libraries and targets following PRIVATE part of the link interface. Libraries and targets following ``PRIVATE``
are linked to, but are not made part of the link interface. Libraries are linked to, but are not made part of the link interface. Libraries
following INTERFACE are appended to the link interface and are not following ``INTERFACE`` are appended to the link interface and are not
used for linking <target>. used for linking ``<target>``.
--------------------------------------------------------------------------
:: ::
target_link_libraries(<target> LINK_INTERFACE_LIBRARIES target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
[[debug|optimized|general] <lib>] ...) [[debug|optimized|general] <lib>] ...)
The LINK_INTERFACE_LIBRARIES mode appends the libraries to the The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
INTERFACE_LINK_LIBRARIES target property instead of using them for :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
linking. If policy CMP0022 is not NEW, then this mode also appends for linking. If policy :policy:`CMP0022` is not ``NEW``, then this mode
libraries to the LINK_INTERFACE_LIBRARIES and its per-configuration also appends libraries to the :prop_tgt:`LINK_INTERFACE_LIBRARIES` and its
equivalent. This signature is for compatibility only. Prefer the per-configuration equivalent.
INTERFACE mode instead. Libraries specified as "debug" are wrapped in
a generator expression to correspond to debug builds. If policy This signature is for compatibility only. Prefer the ``INTERFACE`` mode
CMP0022 is not NEW, the libraries are also appended to the instead.
LINK_INTERFACE_LIBRARIES_DEBUG property (or to the properties
corresponding to configurations listed in the DEBUG_CONFIGURATIONS Libraries specified as ``debug`` are wrapped in a generator expression to
global property if it is set). Libraries specified as "optimized" are correspond to debug builds. If policy :policy:`CMP0022` is
appended to the INTERFACE_LINK_LIBRARIES property. If policy CMP0022 not ``NEW``, the libraries are also appended to the
is not NEW, they are also appended to the LINK_INTERFACE_LIBRARIES :prop_tgt:`LINK_INTERFACE_LIBRARIES_DEBUG <LINK_INTERFACE_LIBRARIES_<CONFIG>>`
property. Libraries specified as "general" (or without any keyword) property (or to the properties corresponding to configurations listed in
are treated as if specified for both "debug" and "optimized". 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> [<LINK_PRIVATE|LINK_PUBLIC>
[[debug|optimized|general] <lib>] ...]) [[debug|optimized|general] <lib>] ...])
The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
link dependencies and the link interface in one command. This the link dependencies and the link interface in one command.
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 This signature is for compatibility only. Prefer the ``PUBLIC`` or
case of mutually-dependent STATIC libraries CMake allows the graph to ``PRIVATE`` keywords instead.
contain cycles (strongly connected components). When another target
links to one of the libraries CMake repeats the entire connected
component. For example, the code
:: 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(A STATIC a.c)
add_library(B STATIC b.c) add_library(B STATIC b.c)
@ -132,15 +134,16 @@ component. For example, the code
add_executable(main main.c) add_executable(main main.c)
target_link_libraries(main A) target_link_libraries(main A)
links 'main' to 'A B A B'. (While one repetition is usually links ``main`` to ``A B A B``. While one repetition is usually
sufficient, pathological object file and symbol arrangements can sufficient, pathological object file and symbol arrangements can require
require more. One may handle such cases by manually repeating the more. One may handle such cases by manually repeating the component in
component in the last target_link_libraries call. However, if two the last ``target_link_libraries`` call. However, if two archives are
archives are really so interdependent they should probably be combined really so interdependent they should probably be combined into a single
into a single archive.) archive.
Arguments to target_link_libraries may use "generator expressions" Arguments to target_link_libraries may use "generator expressions"
with the syntax "$<...>". Note however, that 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 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.

37
Help/manual/cmake-buildsystem.7.rst
View File

@ -171,11 +171,14 @@ can be enabled to add the corresponding directories to the
targets in multiple different directories convenient through use of the targets in multiple different directories convenient through use of the
:command:`target_link_libraries` command. :command:`target_link_libraries` command.
.. _`Target Usage Requirements`:
Transitive Usage Requirements Transitive Usage Requirements
----------------------------- -----------------------------
The usage requirements of a target can transitively propagate to dependents. The usage requirements of a target can transitively propagate to dependents.
The :command:`target_link_libraries` command also has ``PRIVATE``, The :command:`target_link_libraries` command has ``PRIVATE``,
``INTERFACE`` and ``PUBLIC`` keywords to control the propagation. ``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
.. code-block:: cmake .. code-block:: cmake
@ -218,6 +221,26 @@ each keyword:
PRIVATE serialization PRIVATE serialization
) )
Usage requirements are propagated by reading the ``INTERFACE_`` variants
of target properties from dependencies and appending the values to the
non-``INTERFACE_`` variants of the operand. For example, the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of dependencies is read and
appended to the :prop_tgt:`INCLUDE_DIRECTORIES` of the operand. In cases
where order is relevant and maintained, and the order resulting from the
:command:`target_link_libraries` calls does not allow correct compilation,
use of an appropriate command to set the property directly may update the
order.
For example, if the linked libraries for a target must be specified
in the order ``lib1`` ``lib2`` ``lib3`` , but the include directories must
be specified in the order ``lib3`` ``lib1`` ``lib2``:
.. code-block:: cmake
target_link_libraries(myExe lib1 lib2 lib3)
target_include_directories(myExe
PRIVATE $<TARGET_PROPERTY:INTERFACE_INCLUDE_DIRECTORIES:lib3>)
.. _`Compatible Interface Properties`: .. _`Compatible Interface Properties`:
Compatible Interface Properties Compatible Interface Properties
@ -357,6 +380,10 @@ calculate the numeric minimum value for a property from dependencies.
Each calculated "compatible" property value may be read in the consumer at Each calculated "compatible" property value may be read in the consumer at
generate-time using generator expressions. generate-time using generator expressions.
Note that for each dependee, the set of properties specified in each
compatible interface property must not intersect with the set specified in
any of the other properties.
Property Origin Debugging Property Origin Debugging
------------------------- -------------------------
@ -634,13 +661,15 @@ target at a time. The commands :command:`add_definitions`,
a similar function, but operate at directory scope instead of target a similar function, but operate at directory scope instead of target
scope for convenience. scope for convenience.
Psuedo Targets Pseudo Targets
============== ==============
Some target types do not represent outputs of the buildsystem, but only inputs Some target types do not represent outputs of the buildsystem, but only inputs
such as external dependencies, aliases or other non-build artifacts. Pseudo such as external dependencies, aliases or other non-build artifacts. Pseudo
targets are not represented in the generated buildsystem. targets are not represented in the generated buildsystem.
.. _`Imported Targets`:
Imported Targets Imported Targets
---------------- ----------------
@ -677,6 +706,8 @@ accessible globally in the buildsystem.
See the :manual:`cmake-packages(7)` manual for more on creating packages See the :manual:`cmake-packages(7)` manual for more on creating packages
with :prop_tgt:`IMPORTED` targets. with :prop_tgt:`IMPORTED` targets.
.. _`Alias Targets`:
Alias Targets Alias Targets
------------- -------------
@ -718,6 +749,8 @@ property from it:
message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.") message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
endif() endif()
.. _`Interface Libraries`:
Interface Libraries Interface Libraries
------------------- -------------------

171
Help/manual/cmake-developer.7.rst
View File

@ -249,8 +249,7 @@ literal block after ``::``
the following indented block as literal text without interpretation. the following indented block as literal text without interpretation.
The command-line help processor prints the ``::`` literally and The command-line help processor prints the ``::`` literally and
prints the block content with common indentation replaced by one prints the block content with common indentation replaced by one
space. We prefer the ``::`` to appear at the end of a paragraph space.
line instead of as its own line.
``note`` directive ``note`` directive
Call out a side note. The command-line help processor prints the Call out a side note. The command-line help processor prints the
@ -418,6 +417,172 @@ object names like ``OUTPUT_NAME_<CONFIG>``. The form ``a <b>``,
with a space preceding ``<``, is still interpreted as a link text with a space preceding ``<``, is still interpreted as a link text
with an explicit target. with an explicit target.
Style
-----
1)
Command signatures should be marked up as plain literal blocks, not as
cmake ``code-blocks``.
2)
Signatures are separated from preceding content by a horizontal
line. That is, use:
.. code-block:: rst
... preceding paragraph.
---------------------------------------------------------------------
::
add_library(<lib> ...)
This signature is used for ...
3)
Use "``OFF``" and "``ON``" for boolean values which can be modified by
the user, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`. Such properties
may be "enabled" and "disabled". Use "``True``" and "``False``" for
inherent values which can't be modified after being set, such as the
:prop_tgt:`IMPORTED` property of a build target.
4)
Use two spaces for indentation. Use two spaces between sentences in
prose.
5)
Prefer to mark the start of literal blocks with ``::`` at the end of
the preceding paragraph. In cases where the following block gets
a ``code-block`` marker, put a single ``:`` at the end of the preceding
paragraph.
6)
Prefer to restrict the width of lines to 75-80 columns. This is not a
hard restriction, but writing new paragraphs wrapped at 75 columns
allows space for adding minor content without significant re-wrapping of
content.
7)
Mark up self-references with ``inline-literal`` syntax. For example,
within the add_executable command documentation, use
.. code-block:: rst
``add_executable``
not
.. code-block:: rst
:command:`add_executable`
which is used elsewhere.
8)
Mark up all other linkable references as links, including repeats. An
alternative, which is used by wikipedia (`<http://en.wikipedia.org/wiki/WP:REPEATLINK>`_),
is to link to a reference only once per article. That style is not used
in CMake documentation.
9)
Mark up references to keywords in signatures, file names, and other
technical terms with ``inline-literl`` syntax, for example:
.. code-block:: rst
If ``WIN32`` is used with :command:`add_executable`, the
:prop_tgt:`WIN32_EXECUTABLE` target property is enabled. That command
creates the file ``<name>.exe`` on Windows.
10)
If referring to a concept which corresponds to a property, and that
concept is described in a high-level manual, prefer to link to the
manual section instead of the property. For example:
.. code-block:: rst
This command creates an :ref:`Imported Target <Imported Targets>`.
instead of:
.. code-block:: rst
This command creates an :prop_tgt:`IMPORTED` target.
The latter should be used only when referring specifically to the
property.
References to manual sections are not automatically created by creating
a section, but code such as:
.. code-block:: rst
.. _`Imported Targets`:
creates a suitable anchor. Use an anchor name which matches the name
of the corresponding section. Refer to the anchor using a
cross-reference with specified text.
Imported Targets need the ``IMPORTED`` term marked up with care in
particular because the term may refer to a command keyword
(``IMPORTED``), a target property (:prop_tgt:`IMPORTED`), or a
concept (:ref:`Imported Targets`).
11)
Where a property, command or variable is related conceptually to others,
by for example, being related to the buildsystem description, generator
expressions or Qt, each relevant property, command or variable should
link to the primary manual, which provides high-level information. Only
particular information relating to the command should be in the
documentation of the command.
12)
When marking section titles, make the section decoration line as long as
the title text. Use only a line below the title, not above. For
example:
.. code-block:: rst
Title Text
----------
Capitalize the first letter of each non-minor word in the title.
13)
When referring to properties, variables, commands etc, prefer to link
to the target object and follow that with the type of object it is.
For example:
.. code-block:: rst
Set the :prop_tgt:`AUTOMOC` target property to ``ON``.
Instead of
.. code-block:: rst
Set the target property :prop_tgt:`AUTOMOC` to ``ON``.
The ``policy`` directive is an exception, and the type us usually
referred to before the link:
.. code-block:: rst
If policy :prop_tgt:`CMP0022` is set to ``NEW`` the behavior is ...
14)
Signatures of commands should wrap optional parts with square brackets,
and should mark list of optional arguments with an ellipsis (``...``).
Elements of the signature which are specified by the user should be
specified with angle brackets, and may be referred to in prose using
``inline-literal`` syntax.
15)
Use American English spellings in prose.
Modules Modules
======= =======
@ -703,7 +868,7 @@ If the package provides Xxx_INCLUDE_DIRS and Xxx_LIBRARIES variables, the
include dirs and libraries for all components which were requested and which include dirs and libraries for all components which were requested and which
have been found should be added to those two variables. have been found should be added to those two variables.
To get this behaviour you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS() To get this behavior you can use the FIND_PACKAGE_HANDLE_STANDARD_ARGS()
macro, as an example see FindJPEG.cmake. macro, as an example see FindJPEG.cmake.
For internal implementation, it's a generally accepted convention that For internal implementation, it's a generally accepted convention that

8
Help/manual/cmake-policies.7.rst
View File

@ -15,15 +15,15 @@ across multiple releases. When a new policy is introduced, newer CMake
versions will begin to warn about the backward compatible behavior. It versions will begin to warn about the backward compatible behavior. It
is possible to disable the warning by explicitly requesting the OLD, or is possible to disable the warning by explicitly requesting the OLD, or
backward compatible behavior using the :command:`cmake_policy` command. backward compatible behavior using the :command:`cmake_policy` command.
It is also possible to request NEW, or non-backward compatible behavior It is also possible to request ``NEW``, or non-backward compatible behavior
for a policy, also avoiding the warning. Each policy can also be set to for a policy, also avoiding the warning. Each policy can also be set to
either NEW or OLD behavior explicitly on the command line with the either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
:variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable. :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
The :command:`cmake_minimum_required` command does more than report an The :command:`cmake_minimum_required` command does more than report an
error if a too-old version of CMake is used to build a project. It error if a too-old version of CMake is used to build a project. It
also sets all policies introduced in that CMake version or earlier to also sets all policies introduced in that CMake version or earlier to
NEW behavior. To manage policies without increasing the minimum required ``NEW`` behavior. To manage policies without increasing the minimum required
CMake version, the :command:`if(POLICY)` command may be used: CMake version, the :command:`if(POLICY)` command may be used:
.. code-block:: cmake .. code-block:: cmake
@ -32,7 +32,7 @@ CMake version, the :command:`if(POLICY)` command may be used:
cmake_policy(SET CMP0990 NEW) cmake_policy(SET CMP0990 NEW)
endif() endif()
This has the effect of using the NEW behavior with newer CMake releases which This has the effect of using the ``NEW`` behavior with newer CMake releases which
users may be using and not issuing a compatibility warning. users may be using and not issuing a compatibility warning.
The setting of a policy is confined in some cases to not propagate to the The setting of a policy is confined in some cases to not propagate to the

24
Help/prop_dir/COMPILE_DEFINITIONS.rst
View File

@ -3,18 +3,30 @@ COMPILE_DEFINITIONS
Preprocessor definitions for compiling a directory's sources. Preprocessor definitions for compiling a directory's sources.
The COMPILE_DEFINITIONS property may be set to a semicolon-separated This property specifies the list of options given so far to the
list of preprocessor definitions using the syntax VAR or VAR=value. :command:`add_definitions` command.
The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated
list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``.
Function-style definitions are not supported. CMake will Function-style definitions are not supported. CMake will
automatically escape the value correctly for the native build system automatically escape the value correctly for the native build system
(note that CMake language syntax may require escapes to specify some (note that CMake language syntax may require escapes to specify some
values). This property may be set on a per-configuration basis using values).
the name COMPILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case
name (ex. "COMPILE_DEFINITIONS_DEBUG"). This property will be This property will be initialized in each directory by its value in the
initialized in each directory by its value in the directory's parent. directory's parent.
CMake will automatically drop some definitions that are not supported CMake will automatically drop some definitions that are not supported
by the native build tool. The VS6 IDE does not support definition by the native build tool. The VS6 IDE does not support definition
values with spaces (but NMake does). values with spaces (but NMake does).
.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt
Contents of ``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.
The corresponding :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` property may
be set to specify per-configuration definitions. Generator expressions
should be preferred instead of setting the alternative property.

11
Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst
View File

@ -3,6 +3,15 @@ COMPILE_DEFINITIONS_<CONFIG>
Per-configuration preprocessor definitions in a directory. Per-configuration preprocessor definitions in a directory.
This is the configuration-specific version of COMPILE_DEFINITIONS. This is the configuration-specific version of :prop_dir:`COMPILE_DEFINITIONS`
where ``<CONFIG>`` is an upper-case name (ex. ``COMPILE_DEFINITIONS_DEBUG``).
This property will be initialized in each directory by its value in This property will be initialized in each directory by its value in
the directory's parent. the directory's parent.
Contents of ``COMPILE_DEFINITIONS_<CONFIG>`` 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.
Generator expressions should be preferred instead of setting this property.

16
Help/prop_dir/COMPILE_OPTIONS.rst
View File

@ -3,12 +3,14 @@ COMPILE_OPTIONS
List of options to pass to the compiler. List of options to pass to the compiler.
This property specifies the list of directories given so far for this This property specifies the list of options given so far to the
property. This property exists on directories and targets. :command:`add_compile_options` command.
The target property values are used by the generators to set the This property is used to populate the :prop_tgt:`COMPILE_OPTIONS` target
options for the compiler. property, which is used by the generators to set the options for the
compiler.
Contents of COMPILE_OPTIONS may use "generator expressions" with the syntax Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
"$<...>". See the :manual:`cmake-generator-expressions(7)` manual for syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual
available expressions. for available expressions. See the :manual:`cmake-buildsystem(7)` manual
for more on defining buildsystem properties.

28
Help/prop_dir/INCLUDE_DIRECTORIES.rst
View File

@ -4,15 +4,23 @@ INCLUDE_DIRECTORIES
List of preprocessor include file search directories. List of preprocessor include file search directories.
This property specifies the list of directories given so far to the This property specifies the list of directories given so far to the
include_directories command. This property exists on directories and :command:`include_directories` command.
targets. In addition to accepting values from the include_directories
command, values may be set directly on any directory or any target This property is used to populate the :prop_tgt:`INCLUDE_DIRECTORIES`
using the set_property command. A target gets its initial value for target property, which is used by the generators to set the include
this property from the value of the directory property. A directory directories for the compiler.
gets its initial value from its parent directory if it has one. Both
directory and target property values are adjusted by calls to the In addition to accepting values from that command, values may be set
include_directories command. directly on any directory using the :command:`set_property` command. A
directory gets its initial value from its parent directory if it has one.
The intial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property
comes from the value of this property. Both directory and target property
values are adjusted by calls to the :command:`include_directories` command.
The target property values are used by the generators to set the The target property values are used by the generators to set the
include paths for the compiler. See also the include_directories include paths for the compiler.
command.
Contents of ``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.

4
Help/prop_tgt/ALIASED_TARGET.rst
View File

@ -3,5 +3,5 @@ ALIASED_TARGET
Name of target aliased by this target. Name of target aliased by this target.
If this is an ALIAS target, this property contains the name of the If this is an :ref:`Alias Target <Alias Targets>`, this property contains
target aliased. the name of the target aliased.

5
Help/prop_tgt/AUTOGEN_TARGET_DEPENDS.rst
View File

@ -3,7 +3,7 @@ AUTOGEN_TARGET_DEPENDS
Target dependencies of the corresponding ``_automoc`` target. Target dependencies of the corresponding ``_automoc`` target.
Targets which have their :prop_tgt:`AUTOMOC` target set to ``TRUE`` have a Targets which have their :prop_tgt:`AUTOMOC` target ``ON`` have a
corresponding ``_automoc`` target which is used to autogenerate generate moc corresponding ``_automoc`` target which is used to autogenerate generate moc
files. As this ``_automoc`` target is created at generate-time, it is not files. As this ``_automoc`` target is created at generate-time, it is not
possible to define dependencies of it, such as to create inputs for the ``moc`` possible to define dependencies of it, such as to create inputs for the ``moc``
@ -12,3 +12,6 @@ executable.
The ``AUTOGEN_TARGET_DEPENDS`` target property can be set instead to a list of The ``AUTOGEN_TARGET_DEPENDS`` target property can be set instead to a list of
dependencies for the ``_automoc`` target. The buildsystem will be generated to dependencies for the ``_automoc`` target. The buildsystem will be generated to
depend on its contents. depend on its contents.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

13
Help/prop_tgt/AUTOMOC.rst
View File

@ -6,7 +6,7 @@ Should the target be processed with automoc (for Qt projects).
AUTOMOC is a boolean specifying whether CMake will handle the Qt ``moc`` AUTOMOC is a boolean specifying whether CMake will handle the Qt ``moc``
preprocessor automatically, i.e. without having to use the preprocessor automatically, i.e. without having to use the
:module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are :module:`QT4_WRAP_CPP() <FindQt4>` or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5 are
supported. When this property is set to ``TRUE``, CMake will scan the supported. When this property is set ``ON``, CMake will scan the
source files at build time and invoke moc accordingly. If an ``#include`` source files at build time and invoke moc accordingly. If an ``#include``
statement like ``#include "moc_foo.cpp"`` is found, the ``Q_OBJECT`` class statement like ``#include "moc_foo.cpp"`` is found, the ``Q_OBJECT`` class
declaration is expected in the header, and ``moc`` is run on the header declaration is expected in the header, and ``moc`` is run on the header
@ -20,15 +20,18 @@ for ``Q_OBJECT`` macros, and if found, ``moc`` is also executed on those files.
The resulting moc files, which are not included as shown above in any The resulting moc files, which are not included as shown above in any
of the source files are included in a generated of the source files are included in a generated
``<targetname>_automoc.cpp`` file, which is compiled as part of the ``<targetname>_automoc.cpp`` file, which is compiled as part of the
target. This property is initialized by the value of the variable target. This property is initialized by the value of the
:variable:`CMAKE_AUTOMOC` if it is set when a target is created. :variable:`CMAKE_AUTOMOC` variable if it is set when a target is created.
Additional command line options for moc can be set via the Additional command line options for moc can be set via the
:prop_tgt:`AUTOMOC_MOC_OPTIONS` property. :prop_tgt:`AUTOMOC_MOC_OPTIONS` property.
By setting the :variable:`CMAKE_AUTOMOC_RELAXED_MODE` variable to ``TRUE`` the By enabling the :variable:`CMAKE_AUTOMOC_RELAXED_MODE` variable the
rules for searching the files which will be processed by moc can be relaxed. rules for searching the files which will be processed by moc can be relaxed.
See the documentation for this variable for more details. See the documentation for this variable for more details.
The global property :prop_gbl:`AUTOMOC_TARGETS_FOLDER` can be used to group the The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the
automoc targets together in an IDE, e.g. in MSVS. automoc targets together in an IDE, e.g. in MSVS.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

13
Help/prop_tgt/AUTOMOC_MOC_OPTIONS.rst
View File

@ -3,10 +3,13 @@ AUTOMOC_MOC_OPTIONS
Additional options for moc when using :prop_tgt:`AUTOMOC` Additional options for moc when using :prop_tgt:`AUTOMOC`
This property is only used if the :prop_tgt:`AUTOMOC` property is set to ``TRUE`` This property is only used if the :prop_tgt:`AUTOMOC` property is ``ON``
for this target. In this case, it holds additional command line options for this target. In this case, it holds additional command line
which will be used when ``moc`` is executed during the build, i.e. it is options which will be used when ``moc`` is executed during the build, i.e.
equivalent to the optional ``OPTIONS`` argument of the :module:`qt4_wrap_cpp() <FindQt4>` it is equivalent to the optional ``OPTIONS`` argument of the
macro. :module:`qt4_wrap_cpp() <FindQt4>` macro.
By default it is empty. By default it is empty.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

14
Help/prop_tgt/AUTORCC.rst
View File

@ -1,4 +1,3 @@
AUTORCC AUTORCC
------- -------
@ -6,10 +5,10 @@ Should the target be processed with autorcc (for Qt projects).
``AUTORCC`` is a boolean specifying whether CMake will handle ``AUTORCC`` is a boolean specifying whether CMake will handle
the Qt ``rcc`` code generator automatically, i.e. without having to use the Qt ``rcc`` code generator automatically, i.e. without having to use
the :module:`QT4_ADD_RESOURCES() <FindQt4>` or QT5_ADD_RESOURCES() macro. the :module:`QT4_ADD_RESOURCES() <FindQt4>` or ``QT5_ADD_RESOURCES()``
Currently Qt4 and Qt5 are supported. macro. Currently Qt4 and Qt5 are supported.
When this property is set to ``TRUE``, CMake will handle ``.qrc`` files added When this property is ``ON``, CMake will handle ``.qrc`` files added
as target sources at build time and invoke ``rcc`` accordingly. as target sources at build time and invoke ``rcc`` accordingly.
This property is initialized by the value of the :variable:`CMAKE_AUTORCC` This property is initialized by the value of the :variable:`CMAKE_AUTORCC`
variable if it is set when a target is created. variable if it is set when a target is created.
@ -17,5 +16,8 @@ variable if it is set when a target is created.
Additional command line options for rcc can be set via the Additional command line options for rcc can be set via the
:prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file. :prop_sf:`AUTORCC_OPTIONS` source file property on the ``.qrc`` file.
The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group
autouic targets together in an IDE, e.g. in MSVS. the autorcc targets together in an IDE, e.g. in MSVS.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

16
Help/prop_tgt/AUTORCC_OPTIONS.rst
View File

@ -3,15 +3,19 @@ AUTORCC_OPTIONS
Additional options for ``rcc`` when using :prop_tgt:`AUTORCC` Additional options for ``rcc`` when using :prop_tgt:`AUTORCC`
This property holds additional command line options This property holds additional command line options which will be used
which will be used when ``rcc`` is executed during the build via :prop_tgt:`AUTORCC`, when ``rcc`` is executed during the build via :prop_tgt:`AUTORCC`,
i.e. it is equivalent to the optional ``OPTIONS`` argument of the i.e. it is equivalent to the optional ``OPTIONS`` argument of the
:module:`qt4_add_resources() <FindQt4>` macro. :module:`qt4_add_resources() <FindQt4>` macro.
By default it is empty. By default it is empty.
This property is initialized by the value of the variable This property is initialized by the value of the
:variable:`CMAKE_AUTORCC` if it is set when a target is created. :variable:`CMAKE_AUTORCC_OPTIONS` variable if it is set when a target is
created.
The options set on the target may be overridden by :prop_sf:`AUTORCC_OPTIONS` set The options set on the target may be overridden by :prop_sf:`AUTORCC_OPTIONS`
on the ``.qrc`` source file. set on the ``.qrc`` source file.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

18
Help/prop_tgt/AUTOUIC.rst
View File

@ -5,18 +5,20 @@ Should the target be processed with autouic (for Qt projects).
``AUTOUIC`` is a boolean specifying whether CMake will handle ``AUTOUIC`` is a boolean specifying whether CMake will handle
the Qt ``uic`` code generator automatically, i.e. without having to use the Qt ``uic`` code generator automatically, i.e. without having to use
the :module:`QT4_WRAP_UI() <FindQt4>` or QT5_WRAP_UI() macro. Currently Qt4 the :module:`QT4_WRAP_UI() <FindQt4>` or ``QT5_WRAP_UI()`` macro. Currently
and Qt5 are supported. Qt4 and Qt5 are supported.
When this property is set to ``TRUE``, CMake will scan the source files When this property is ``ON``, CMake will scan the source files at build time
at build time and invoke ``uic`` accordingly. and invoke ``uic`` accordingly. If an ``#include`` statement like
If an ``#include`` statement like ``#include "ui_foo.h"`` is found in ``#include "ui_foo.h"`` is found in ``foo.cpp``, a ``foo.ui`` file is
``foo.cpp``, a ``foo.ui`` file is expected next to ``foo.cpp``, and ``uic`` is expected next to ``foo.cpp``, and ``uic`` is run on the ``foo.ui`` file.
run on the ``foo.ui`` file.
This property is initialized by the value of the :variable:`CMAKE_AUTOUIC` This property is initialized by the value of the :variable:`CMAKE_AUTOUIC`
variable if it is set when a target is created. variable if it is set when a target is created.
Additional command line options for uic can be set via the Additional command line options for ``uic`` can be set via the
:prop_sf:`AUTOUIC_OPTIONS` source file property on the ``foo.ui`` file. :prop_sf:`AUTOUIC_OPTIONS` source file property on the ``foo.ui`` file.
The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the The global property :prop_gbl:`AUTOGEN_TARGETS_FOLDER` can be used to group the
autouic targets together in an IDE, e.g. in MSVS. autouic targets together in an IDE, e.g. in MSVS.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

20
Help/prop_tgt/AUTOUIC_OPTIONS.rst
View File

@ -3,19 +3,23 @@ AUTOUIC_OPTIONS
Additional options for uic when using :prop_tgt:`AUTOUIC` Additional options for uic when using :prop_tgt:`AUTOUIC`
This property holds additional command line options This property holds additional command line options which will be used when
which will be used when ``uic`` is executed during the build via :prop_tgt:`AUTOUIC`, ``uic`` is executed during the build via :prop_tgt:`AUTOUIC`, i.e. it is
i.e. it is equivalent to the optional ``OPTIONS`` argument of the equivalent to the optional ``OPTIONS`` argument of the
:module:`qt4_wrap_ui() <FindQt4>` macro. :module:`qt4_wrap_ui() <FindQt4>` macro.
By default it is empty. By default it is empty.
This property is initialized by the value of the variable This property is initialized by the value of the
:variable:`CMAKE_AUTOUIC` if it is set when a target is created. :variable:`CMAKE_AUTOUIC_OPTIONS` variable if it is set when a target is
created.
The options set on the target may be overridden by :prop_sf:`AUTOUIC_OPTIONS` set The options set on the target may be overridden by :prop_sf:`AUTOUIC_OPTIONS`
on the ``.ui`` source file. set on the ``.ui`` source file.
This property may use "generator expressions" with the syntax "$<...>". This property may use "generator expressions" with the syntax ``$<...>``.
See the :manual:`cmake-generator-expressions(7)` manual for available See the :manual:`cmake-generator-expressions(7)` manual for available
expressions. expressions.
See the :manual:`cmake-qt(7)` manual for more information on using CMake
with Qt.

29
Help/prop_tgt/COMPATIBLE_INTERFACE_BOOL.rst
View File

@ -3,17 +3,18 @@ COMPATIBLE_INTERFACE_BOOL
Properties which must be compatible with their link interface Properties which must be compatible with their link interface
The COMPATIBLE_INTERFACE_BOOL property may contain a list of The ``COMPATIBLE_INTERFACE_BOOL`` property may contain a list of
propertiesfor this target which must be consistent when evaluated as a properties for this target which must be consistent when evaluated as a
boolean in the INTERFACE of all linked dependees. For example, if a boolean with the ``INTERFACE`` variant of the property in all linked
property "FOO" appears in the list, then for each dependee, the dependees. For example, if a property ``FOO`` appears in the list, then
"INTERFACE_FOO" property content in all of its dependencies must be for each dependee, the ``INTERFACE_FOO`` property content in all of its
consistent with each other, and with the "FOO" property in the dependencies must be consistent with each other, and with the ``FOO``
depender. Consistency in this sense has the meaning that if the property in the depender.
property is set, then it must have the same boolean value as all
others, and if the property is not set, then it is ignored. Note that Consistency in this sense has the meaning that if the property is set,
for each dependee, the set of properties from this property must not then it must have the same boolean value as all others, and if the
intersect with the set of properties from the property is not set, then it is ignored.
:prop_tgt:`COMPATIBLE_INTERFACE_STRING`,
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` or Note that for each dependee, the set of properties specified in this
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` property. property must not intersect with the set specified in any of the other
:ref:`Compatible Interface Properties`.

25
Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MAX.rst
View File

@ -3,15 +3,16 @@ COMPATIBLE_INTERFACE_NUMBER_MAX
Properties whose maximum value from the link interface will be used. Properties whose maximum value from the link interface will be used.
The COMPATIBLE_INTERFACE_NUMBER_MAX property may contain a list of The ``COMPATIBLE_INTERFACE_NUMBER_MAX`` property may contain a list of
properties for this target whose maximum value may be read at generate time properties for this target whose maximum value may be read at generate
when evaluated in the INTERFACE of all linked dependees. For example, if a time when evaluated in the ``INTERFACE`` variant of the property in all
property "FOO" appears in the list, then for each dependee, the linked dependees. For example, if a property ``FOO`` appears in the list,
"INTERFACE_FOO" property content in all of its dependencies will be compared then for each dependee, the ``INTERFACE_FOO`` property content in all of
with each other and with the "FOO" property in the depender. When reading its dependencies will be compared with each other and with the ``FOO``
the FOO property at generate time, the maximum value will be returned. property in the depender. When reading the ``FOO`` property at generate
If the property is not set, then it is ignored. Note that for each time, the maximum value will be returned. If the property is not set,
dependee, the set of properties from this property must not intersect then it is ignored.
with the set of properties from the :prop_tgt:`COMPATIBLE_INTERFACE_BOOL`,
:prop_tgt:`COMPATIBLE_INTERFACE_STRING` or Note that for each dependee, the set of properties specified in this
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` property. property must not intersect with the set specified in any of the other
:ref:`Compatible Interface Properties`.

25
Help/prop_tgt/COMPATIBLE_INTERFACE_NUMBER_MIN.rst
View File

@ -3,15 +3,16 @@ COMPATIBLE_INTERFACE_NUMBER_MIN
Properties whose maximum value from the link interface will be used. Properties whose maximum value from the link interface will be used.
The COMPATIBLE_INTERFACE_NUMBER_MIN property may contain a list of The ``COMPATIBLE_INTERFACE_NUMBER_MIN`` property may contain a list of
properties for this target whose minimum value may be read at generate time properties for this target whose minimum value may be read at generate
when evaluated in the INTERFACE of all linked dependees. For example, if a time when evaluated in the ``INTERFACE`` variant of the property of all
property "FOO" appears in the list, then for each dependee, the linked dependees. For example, if a
"INTERFACE_FOO" property content in all of its dependencies will be compared property ``FOO`` appears in the list, then for each dependee, the
with each other and with the "FOO" property in the depender. When reading ``INTERFACE_FOO`` property content in all of its dependencies will be
the FOO property at generate time, the minimum value will be returned. compared with each other and with the ``FOO`` property in the depender.
If the property is not set, then it is ignored. Note that for each When reading the ``FOO`` property at generate time, the minimum value
dependee, the set of properties from this property must not intersect will be returned. If the property is not set, then it is ignored.
with the set of properties from the :prop_tgt:`COMPATIBLE_INTERFACE_BOOL`,
:prop_tgt:`COMPATIBLE_INTERFACE_STRING` or Note that for each dependee, the set of properties specified in this
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` property. property must not intersect with the set specified in any of the other
:ref:`Compatible Interface Properties`.

20
Help/prop_tgt/COMPATIBLE_INTERFACE_STRING.rst
View File

@ -3,14 +3,14 @@ COMPATIBLE_INTERFACE_STRING
Properties which must be string-compatible with their link interface Properties which must be string-compatible with their link interface
The COMPATIBLE_INTERFACE_STRING property may contain a list of The ``COMPATIBLE_INTERFACE_STRING`` property may contain a list of
properties for this target which must be the same when evaluated as a properties for this target which must be the same when evaluated as a
string in the INTERFACE of all linked dependees. For example, if a string in the ``INTERFACE`` variant of the property all linked dependees.
property "FOO" appears in the list, then for each dependee, the For example, if a property ``FOO`` appears in the list, then for each
"INTERFACE_FOO" property content in all of its dependencies must be dependee, the ``INTERFACE_FOO`` property content in all of its
equal with each other, and with the "FOO" property in the depender. dependencies must be equal with each other, and with the ``FOO`` property
If the property is not set, then it is ignored. Note that for each in the depender. If the property is not set, then it is ignored.
dependee, the set of properties from this property must not intersect
with the set of properties from the :prop_tgt:`COMPATIBLE_INTERFACE_BOOL`, Note that for each dependee, the set of properties specified in this
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` or property must not intersect with the set specified in any of the other
:prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` property. :ref:`Compatible Interface Properties`.

21
Help/prop_tgt/COMPILE_DEFINITIONS.rst
View File

@ -3,21 +3,24 @@ COMPILE_DEFINITIONS
Preprocessor definitions for compiling a target's sources. Preprocessor definitions for compiling a target's sources.
The COMPILE_DEFINITIONS property may be set to a semicolon-separated The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated
list of preprocessor definitions using the syntax VAR or VAR=value. list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``.
Function-style definitions are not supported. CMake will Function-style definitions are not supported. CMake will
automatically escape the value correctly for the native build system automatically escape the value correctly for the native build system
(note that CMake language syntax may require escapes to specify some (note that CMake language syntax may require escapes to specify some
values). This property may be set on a per-configuration basis using values).
the name COMPILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case
name (ex. "COMPILE_DEFINITIONS_DEBUG").
CMake will automatically drop some definitions that are not supported CMake will automatically drop some definitions that are not supported
by the native build tool. The VS6 IDE does not support definition by the native build tool. The VS6 IDE does not support definition
values with spaces (but NMake does). values with spaces (but NMake does).
Contents of COMPILE_DEFINITIONS may use "generator expressions" with the
syntax "$<...>". See the :manual:`cmake-generator-expressions(7)` manual
for available expressions.
.. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt
Contents of ``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.
The corresponding :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` property may
be set to specify per-configuration definitions. Generator expressions
should be preferred instead of setting the alternative property.

10
Help/prop_tgt/COMPILE_DEFINITIONS_CONFIG.rst
View File

@ -3,4 +3,12 @@ COMPILE_DEFINITIONS_<CONFIG>
Per-configuration preprocessor definitions on a target. Per-configuration preprocessor definitions on a target.
This is the configuration-specific version of COMPILE_DEFINITIONS. This is the configuration-specific version of :prop_tgt:`COMPILE_DEFINITIONS`
where ``<CONFIG>`` is an upper-case name (ex. ``COMPILE_DEFINITIONS_DEBUG``).
Contents of ``COMPILE_DEFINITIONS_<CONFIG>`` 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.
Generator expressions should be preferred instead of setting this property.

14
Help/prop_tgt/COMPILE_OPTIONS.rst
View File

@ -4,11 +4,13 @@ COMPILE_OPTIONS
List of options to pass to the compiler. List of options to pass to the compiler.
This property specifies the list of options specified so far for this This property specifies the list of options specified so far for this
property. This property exists on directories and targets. property.
The target property values are used by the generators to set the This property is intialized by the :prop_dir:`COMPILE_OPTIONS` directory
options for the compiler. property, which is used by the generators to set the options for the
compiler.
Contents of COMPILE_OPTIONS may use "generator expressions" with the Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
syntax "$<...>". See the :manual:`cmake-generator-expressions(7)` manual for syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual
available expressions. for available expressions. See the :manual:`cmake-buildsystem(7)` manual
for more on defining buildsystem properties.

6
Help/prop_tgt/IMPORTED.rst
View File

@ -3,6 +3,6 @@ IMPORTED
Read-only indication of whether a target is IMPORTED. Read-only indication of whether a target is IMPORTED.
The boolean value of this property is true for targets created with The boolean value of this property is ``True`` for targets created with
the IMPORTED option to add_executable or add_library. It is false for the IMPORTED option to :command:`add_executable` or :command:`add_library`.
targets built within the project. It is ``False`` for targets built within the project.

25
Help/prop_tgt/INCLUDE_DIRECTORIES.rst
View File

@ -4,22 +4,21 @@ INCLUDE_DIRECTORIES
List of preprocessor include file search directories. List of preprocessor include file search directories.
This property specifies the list of directories given so far to the This property specifies the list of directories given so far to the
include_directories command. This property exists on directories and :command:`target_include_directories` command. In addition to accepting
targets. In addition to accepting values from the :command:`include_directories` values from that command, values may be set directly on any
command, values may be set directly on any directory or any target target using the :command:`set_property` command. A target gets its
using the :command:`set_property` command. A target gets its initial value for initial value for this property from the value of the
this property from the value of the directory property. A directory :prop_dir:`INCLUDE_DIRECTORIES` directory property. Both directory and
gets its initial value from its parent directory if it has one. Both target property values are adjusted by calls to the
directory and target property values are adjusted by calls to the
:command:`include_directories` command. :command:`include_directories` command.
The target property values are used by the generators to set the The value of this property is used by the generators to set the include
include paths for the compiler. See also the :command:`include_directories` paths for the compiler.
and :command:`target_include_directories` commands.
Relative paths should not be added to this property directly. Use one of Relative paths should not be added to this property directly. Use one of
the commands above instead to handle relative paths. the commands above instead to handle relative paths.
Contents of INCLUDE_DIRECTORIES may use "generator expressions" with the Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with
syntax "$<...>". See the :manual:`cmake-generator-expressions(7)` manual for the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
available expressions. manual for available expressions. See the :manual:`cmake-buildsystem(7)`
manual for more on defining buildsystem properties.

12
Help/prop_tgt/INTERFACE_COMPILE_DEFINITIONS.rst
View File

@ -5,9 +5,11 @@ List of public compile definitions for a library.
Targets may populate this property to publish the compile definitions Targets may populate this property to publish the compile definitions
required to compile against the headers for the target. Consuming required to compile against the headers for the target. Consuming
targets can add entries to their own COMPILE_DEFINITIONS property such targets can add entries to their own :prop_tgt:`COMPILE_DEFINITIONS`
as $<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS> to use the property such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS>``
compile definitions specified in the interface of 'foo'. to use the compile definitions specified in the interface of ``foo``.
This property also supports generator expressions. See the Contents of ``INTERFACE_COMPILE_DEFINITIONS`` may use "generator expressions"
:manual:`cmake-generator-expressions(7)` manual for available 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.

12
Help/prop_tgt/INTERFACE_COMPILE_OPTIONS.rst
View File

@ -5,9 +5,11 @@ List of interface options to pass to the compiler.
Targets may populate this property to publish the compile options Targets may populate this property to publish the compile options
required to compile against the headers for the target. Consuming required to compile against the headers for the target. Consuming
targets can add entries to their own COMPILE_OPTIONS property such as targets can add entries to their own :prop_tgt:`COMPILE_OPTIONS` property
$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS> to use the compile such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS>`` to use the
options specified in the interface of 'foo'. compile options specified in the interface of ``foo``.
This property also supports generator expressions. See the Contents of ``INTERFACE_COMPILE_OPTIONS`` may use "generator expressions"
:manual:`cmake-generator-expressions(7)` manual for available 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.

12
Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst
View File

@ -5,9 +5,11 @@ List of public include directories for a library.
Targets may populate this property to publish the include directories Targets may populate this property to publish the include directories
required to compile against the headers for the target. Consuming required to compile against the headers for the target. Consuming
targets can add entries to their own INCLUDE_DIRECTORIES property such targets can add entries to their own :prop_tgt:`INCLUDE_DIRECTORIES`
as $<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES> to use the property such as ``$<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES>``
include directories specified in the interface of 'foo'. to use the include directories specified in the interface of ``foo``.
This property also supports generator expressions. See the Contents of ``INTERFACE_INCLUDE_DIRECTORIES`` may use "generator expressions"
:manual:`cmake-generator-expressions(7)` manual for available 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.

11
Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
View File

@ -7,8 +7,11 @@ This property contains the list of transitive link dependencies. When
the target is linked into another target the libraries listed (and the target is linked into another target the libraries listed (and
recursively their link interface libraries) will be provided to the recursively their link interface libraries) will be provided to the
other target also. This property is overridden by the other target also. This property is overridden by the
LINK_INTERFACE_LIBRARIES or LINK_INTERFACE_LIBRARIES_<CONFIG> property :prop_tgt:`LINK_INTERFACE_LIBRARIES` or
if policy CMP0022 is OLD or unset. :prop_tgt:`LINK_INTERFACE_LIBRARIES_<CONFIG>` property if policy
:policy:`CMP0022` is ``OLD`` or unset.
This property also supports generator expressions. See the Contents of ``INTERFACE_LINK_LIBRARIES`` may use "generator expressions"
:manual:`cmake-generator-expressions(7)` manual for available 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.

19
Help/prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE.rst
View File

@ -3,13 +3,14 @@ INTERFACE_POSITION_INDEPENDENT_CODE
Whether consumers need to create a position-independent target Whether consumers need to create a position-independent target
The INTERFACE_POSITION_INDEPENDENT_CODE property informs consumers of The ``INTERFACE_POSITION_INDEPENDENT_CODE`` property informs consumers of
this target whether they must set their POSITION_INDEPENDENT_CODE this target whether they must set their
property to ON. If this property is set to ON, then the :prop_tgt:`POSITION_INDEPENDENT_CODE` property to ``ON``. If this
POSITION_INDEPENDENT_CODE property on all consumers will be set to ON. property is set to ``ON``, then the :prop_tgt:`POSITION_INDEPENDENT_CODE`
Similarly, if this property is set to OFF, then the property on all consumers will be set to ``ON``. Similarly, if this
POSITION_INDEPENDENT_CODE property on all consumers will be set to property is set to ``OFF``, then the :prop_tgt:`POSITION_INDEPENDENT_CODE`
OFF. If this property is undefined, then consumers will determine property on all consumers will be set to ``OFF``. If this property is
their POSITION_INDEPENDENT_CODE property by other means. Consumers undefined, then consumers will determine their
:prop_tgt:`POSITION_INDEPENDENT_CODE` property by other means. Consumers
must ensure that the targets that they link to have a consistent must ensure that the targets that they link to have a consistent
requirement for their INTERFACE_POSITION_INDEPENDENT_CODE property. requirement for their ``INTERFACE_POSITION_INDEPENDENT_CODE`` property.

5
Help/prop_tgt/INTERFACE_SYSTEM_INCLUDE_DIRECTORIES.rst
View File

@ -8,5 +8,8 @@ which contain system headers, and therefore should not result in
compiler warnings. Consuming targets will then mark the same include compiler warnings. Consuming targets will then mark the same include
directories as system headers. directories as system headers.
This property also supports generator expressions. See the Contents of ``INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`` may use "generator
expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions. :manual:`cmake-generator-expressions(7)` manual for available expressions.
See the :manual:`cmake-buildsystem(7)` manual for more on defining
buildsystem properties.

16
Help/prop_tgt/LINK_LIBRARIES.rst
View File

@ -5,13 +5,13 @@ List of direct link dependencies.
This property specifies the list of libraries or targets which will be This property specifies the list of libraries or targets which will be
used for linking. In addition to accepting values from the used for linking. In addition to accepting values from the
target_link_libraries command, values may be set directly on any :command:`target_link_libraries` command, values may be set directly on
target using the set_property command. any target using the :command:`set_property` command.
The target property values are used by the generators to set the link The value of this property is used by the generators to set the link
libraries for the compiler. See also the target_link_libraries libraries for the compiler.
command.
Contents of LINK_LIBRARIES may use "generator expressions" with the syntax Contents of ``LINK_LIBRARIES`` may use "generator expressions" with the
"$<...>". See the :manual:`cmake-generator-expressions(7)` manual for syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual
available expressions. for available expressions. See the :manual:`cmake-buildsystem(7)` manual
for more on defining buildsystem properties.

10
Help/prop_tgt/POSITION_INDEPENDENT_CODE.rst
View File

@ -3,9 +3,9 @@ POSITION_INDEPENDENT_CODE
Whether to create a position-independent target Whether to create a position-independent target
The POSITION_INDEPENDENT_CODE property determines whether position The ``POSITION_INDEPENDENT_CODE`` property determines whether position
independent executables or shared libraries will be created. This independent executables or shared libraries will be created. This
property is true by default for SHARED and MODULE library targets and property is ``True`` by default for ``SHARED`` and ``MODULE`` library
false otherwise. This property is initialized by the value of the targets and ``False`` otherwise. This property is initialized by the value
variable CMAKE_POSITION_INDEPENDENT_CODE if it is set when a target is of the :variable:`CMAKE_POSITION_INDEPENDENT_CODE` variable if it is set
created. when a target is created.