Help/command/target_include_directories.rst

   1 target_include_directories
   2 --------------------------
   3
   4 Add include directories to a target.
   5
   6 .. code-block:: cmake
   7
   8   target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
   9     <INTERFACE|PUBLIC|PRIVATE> [items1...]
  10     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
  11
  12 Specifies include directories to use when compiling a given target.
  13 The named ``<target>`` must have been created by a command such
  14 as :command:`add_executable` or :command:`add_library` and must not be an
  15 :ref:`ALIAS target <Alias Targets>`.
  16
  17 By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending
  18 and prepending, independent of the default.
  19
  20 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
  21 the :ref:`scope <Target Usage Requirements>` of the following arguments.
  22 ``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES`
  23 property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
  24 :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.
  25 The following arguments specify include directories.
  26
  27 .. versionadded:: 3.11
  28   Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
  29
  30 Repeated calls for the same ``<target>`` append items in the order called.
  31
  32 If ``SYSTEM`` is specified, the compiler will be told the directories
  33 are meant as system include directories on some platforms.  This may
  34 have effects such as suppressing warnings or skipping the contained
  35 headers in dependency calculations (see compiler documentation).
  36 Additionally, system include directories are searched after normal
  37 include directories regardless of the order specified.
  38
  39 If ``SYSTEM`` is used together with ``PUBLIC`` or ``INTERFACE``, the
  40 :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` target property will be
  41 populated with the specified directories.
  42
  43 Arguments to ``target_include_directories`` may use "generator expressions"
  44 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
  45 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
  46 manual for more on defining buildsystem properties.
  47
  48 Specified include directories may be absolute paths or relative paths.
  49 A relative path will be interpreted as relative to the current source
  50 directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an
  51 absolute path before storing it in the associated target property.
  52 If the path starts with a generator expression, it will always be assumed
  53 to be an absolute path (with one exception noted below) and will be used
  54 unmodified.
  55
  56 Include directories usage requirements commonly differ between the build-tree
  57 and the install-tree.  The :genex:`BUILD_INTERFACE` and
  58 :genex:`INSTALL_INTERFACE` generator expressions can be used to describe
  59 separate usage requirements based on the usage location.  Relative paths
  60 are allowed within the :genex:`INSTALL_INTERFACE` expression and are
  61 interpreted as relative to the installation prefix.  Relative paths should not
  62 be used in :genex:`BUILD_INTERFACE` expressions because they will not be
  63 converted to absolute.  For example:
  64
  65 .. code-block:: cmake
  66
  67   target_include_directories(mylib PUBLIC
  68     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
  69     $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
  70   )
  71
  72 Creating Relocatable Packages
  73 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  74
  75 .. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
  76 .. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt