cmake-buildsystem.7.rst 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989
  1. .. cmake-manual-description: CMake Buildsystem Reference
  2. cmake-buildsystem(7)
  3. ********************
  4. .. only:: html
  5. .. contents::
  6. Introduction
  7. ============
  8. A CMake-based buildsystem is organized as a set of high-level logical
  9. targets. Each target corresponds to an executable or library, or
  10. is a custom target containing custom commands. Dependencies between the
  11. targets are expressed in the buildsystem to determine the build order
  12. and the rules for regeneration in response to change.
  13. Binary Targets
  14. ==============
  15. Executables and libraries are defined using the :command:`add_executable`
  16. and :command:`add_library` commands. The resulting binary files have
  17. appropriate prefixes, suffixes and extensions for the platform targeted.
  18. Dependencies between binary targets are expressed using the
  19. :command:`target_link_libraries` command:
  20. .. code-block:: cmake
  21. add_library(archive archive.cpp zip.cpp lzma.cpp)
  22. add_executable(zipapp zipapp.cpp)
  23. target_link_libraries(zipapp archive)
  24. ``archive`` is defined as a static library -- an archive containing objects
  25. compiled from ``archive.cpp``, ``zip.cpp``, and ``lzma.cpp``. ``zipapp``
  26. is defined as an executable formed by compiling and linking ``zipapp.cpp``.
  27. When linking the ``zipapp`` executable, the ``archive`` static library is
  28. linked in.
  29. Binary Executables
  30. ------------------
  31. The :command:`add_executable` command defines an executable target:
  32. .. code-block:: cmake
  33. add_executable(mytool mytool.cpp)
  34. Commands such as :command:`add_custom_command`, which generates rules to be
  35. run at build time can transparently use an :prop_tgt:`EXECUTABLE <TYPE>`
  36. target as a ``COMMAND`` executable. The buildsystem rules will ensure that
  37. the executable is built before attempting to run the command.
  38. Binary Library Types
  39. --------------------
  40. .. _`Normal Libraries`:
  41. Normal Libraries
  42. ^^^^^^^^^^^^^^^^
  43. By default, the :command:`add_library` command defines a static library,
  44. unless a type is specified. A type may be specified when using the command:
  45. .. code-block:: cmake
  46. add_library(archive SHARED archive.cpp zip.cpp lzma.cpp)
  47. .. code-block:: cmake
  48. add_library(archive STATIC archive.cpp zip.cpp lzma.cpp)
  49. The :variable:`BUILD_SHARED_LIBS` variable may be enabled to change the
  50. behavior of :command:`add_library` to build shared libraries by default.
  51. In the context of the buildsystem definition as a whole, it is largely
  52. irrelevant whether particular libraries are ``SHARED`` or ``STATIC`` --
  53. the commands, dependency specifications and other APIs work similarly
  54. regardless of the library type. The ``MODULE`` library type is
  55. dissimilar in that it is generally not linked to -- it is not used in
  56. the right-hand-side of the :command:`target_link_libraries` command.
  57. It is a type which is loaded as a plugin using runtime techniques.
  58. If the library does not export any unmanaged symbols (e.g. Windows
  59. resource DLL, C++/CLI DLL), it is required that the library not be a
  60. ``SHARED`` library because CMake expects ``SHARED`` libraries to export
  61. at least one symbol.
  62. .. code-block:: cmake
  63. add_library(archive MODULE 7z.cpp)
  64. .. _`Apple Frameworks`:
  65. Apple Frameworks
  66. """"""""""""""""
  67. A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
  68. target property to create an OS X or iOS Framework Bundle.
  69. The ``MACOSX_FRAMEWORK_IDENTIFIER`` sets ``CFBundleIdentifier`` key
  70. and it uniquely identifies the bundle.
  71. .. code-block:: cmake
  72. add_library(MyFramework SHARED MyFramework.cpp)
  73. set_target_properties(MyFramework PROPERTIES
  74. FRAMEWORK TRUE
  75. FRAMEWORK_VERSION A
  76. MACOSX_FRAMEWORK_IDENTIFIER org.cmake.MyFramework
  77. )
  78. .. _`Object Libraries`:
  79. Object Libraries
  80. ^^^^^^^^^^^^^^^^
  81. The ``OBJECT`` library type is also not linked to. It defines a non-archival
  82. collection of object files resulting from compiling the given source files.
  83. The object files collection can be used as source inputs to other targets:
  84. .. code-block:: cmake
  85. add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp)
  86. add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp)
  87. add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp)
  88. ``OBJECT`` libraries may only be used locally as sources in a buildsystem --
  89. they may not be installed, exported, or used in the right hand side of
  90. :command:`target_link_libraries`. They also may not be used as the ``TARGET``
  91. in a use of the :command:`add_custom_command(TARGET)` command signature.
  92. Although object libraries may not be named directly in calls to
  93. the :command:`target_link_libraries` command, they can be "linked"
  94. indirectly by using an :ref:`Interface Library <Interface Libraries>`
  95. whose :prop_tgt:`INTERFACE_SOURCES` target property is set to name
  96. ``$<TARGET_OBJECTS:objlib>``.
  97. Build Specification and Usage Requirements
  98. ==========================================
  99. The :command:`target_include_directories`, :command:`target_compile_definitions`
  100. and :command:`target_compile_options` commands specify the build specifications
  101. and the usage requirements of binary targets. The commands populate the
  102. :prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and
  103. :prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the
  104. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
  105. and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
  106. Each of the commands has a ``PRIVATE``, ``PUBLIC`` and ``INTERFACE`` mode. The
  107. ``PRIVATE`` mode populates only the non-``INTERFACE_`` variant of the target
  108. property and the ``INTERFACE`` mode populates only the ``INTERFACE_`` variants.
  109. The ``PUBLIC`` mode populates both variants of the respective target property.
  110. Each command may be invoked with multiple uses of each keyword:
  111. .. code-block:: cmake
  112. target_compile_definitions(archive
  113. PRIVATE BUILDING_WITH_LZMA
  114. INTERFACE USING_ARCHIVE_LIB
  115. )
  116. Note that usage requirements are not designed as a way to make downstreams
  117. use particular :prop_tgt:`COMPILE_OPTIONS` or
  118. :prop_tgt:`COMPILE_DEFINITIONS` etc for convenience only. The contents of
  119. the properties must be **requirements**, not merely recommendations or
  120. convenience.
  121. See the :ref:`Creating Relocatable Packages` section of the
  122. :manual:`cmake-packages(7)` manual for discussion of additional care
  123. that must be taken when specifying usage requirements while creating
  124. packages for redistribution.
  125. Target Properties
  126. -----------------
  127. The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`,
  128. :prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target
  129. properties are used appropriately when compiling the source files of a
  130. binary target.
  131. Entries in the :prop_tgt:`INCLUDE_DIRECTORIES` are added to the compile line
  132. with ``-I`` or ``-isystem`` prefixes and in the order of appearance in the
  133. property value.
  134. Entries in the :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or
  135. ``/D`` and added to the compile line in an unspecified order. The
  136. :prop_tgt:`DEFINE_SYMBOL` target property is also added as a compile
  137. definition as a special convenience case for ``SHARED`` and ``MODULE``
  138. library targets.
  139. Entries in the :prop_tgt:`COMPILE_OPTIONS` are escaped for the shell and added
  140. in the order of appearance in the property value. Several compile options have
  141. special separate handling, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`.
  142. The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
  143. :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and
  144. :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties are
  145. *Usage Requirements* -- they specify content which consumers
  146. must use to correctly compile and link with the target they appear on.
  147. For any binary target, the contents of each ``INTERFACE_`` property on
  148. each target specified in a :command:`target_link_libraries` command is
  149. consumed:
  150. .. code-block:: cmake
  151. set(srcs archive.cpp zip.cpp)
  152. if (LZMA_FOUND)
  153. list(APPEND srcs lzma.cpp)
  154. endif()
  155. add_library(archive SHARED ${srcs})
  156. if (LZMA_FOUND)
  157. # The archive library sources are compiled with -DBUILDING_WITH_LZMA
  158. target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
  159. endif()
  160. target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
  161. add_executable(consumer)
  162. # Link consumer to archive and consume its usage requirements. The consumer
  163. # executable sources are compiled with -DUSING_ARCHIVE_LIB.
  164. target_link_libraries(consumer archive)
  165. Because it is common to require that the source directory and corresponding
  166. build directory are added to the :prop_tgt:`INCLUDE_DIRECTORIES`, the
  167. :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently
  168. add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of
  169. all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`
  170. can be enabled to add the corresponding directories to the
  171. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of
  172. targets in multiple different directories convenient through use of the
  173. :command:`target_link_libraries` command.
  174. .. _`Target Usage Requirements`:
  175. Transitive Usage Requirements
  176. -----------------------------
  177. The usage requirements of a target can transitively propagate to dependents.
  178. The :command:`target_link_libraries` command has ``PRIVATE``,
  179. ``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
  180. .. code-block:: cmake
  181. add_library(archive archive.cpp)
  182. target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
  183. add_library(serialization serialization.cpp)
  184. target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB)
  185. add_library(archiveExtras extras.cpp)
  186. target_link_libraries(archiveExtras PUBLIC archive)
  187. target_link_libraries(archiveExtras PRIVATE serialization)
  188. # archiveExtras is compiled with -DUSING_ARCHIVE_LIB
  189. # and -DUSING_SERIALIZATION_LIB
  190. add_executable(consumer consumer.cpp)
  191. # consumer is compiled with -DUSING_ARCHIVE_LIB
  192. target_link_libraries(consumer archiveExtras)
  193. Because ``archive`` is a ``PUBLIC`` dependency of ``archiveExtras``, the
  194. usage requirements of it are propagated to ``consumer`` too. Because
  195. ``serialization`` is a ``PRIVATE`` dependency of ``archive``, the usage
  196. requirements of it are not propagated to ``consumer``.
  197. Generally, a dependency should be specified in a use of
  198. :command:`target_link_libraries` with the ``PRIVATE`` keyword if it is used by
  199. only the implementation of a library, and not in the header files. If a
  200. dependency is additionally used in the header files of a library (e.g. for
  201. class inheritance), then it should be specified as a ``PUBLIC`` dependency.
  202. A dependency which is not used by the implementation of a library, but only by
  203. its headers should be specified as an ``INTERFACE`` dependency. The
  204. :command:`target_link_libraries` command may be invoked with multiple uses of
  205. each keyword:
  206. .. code-block:: cmake
  207. target_link_libraries(archiveExtras
  208. PUBLIC archive
  209. PRIVATE serialization
  210. )
  211. Usage requirements are propagated by reading the ``INTERFACE_`` variants
  212. of target properties from dependencies and appending the values to the
  213. non-``INTERFACE_`` variants of the operand. For example, the
  214. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of dependencies is read and
  215. appended to the :prop_tgt:`INCLUDE_DIRECTORIES` of the operand. In cases
  216. where order is relevant and maintained, and the order resulting from the
  217. :command:`target_link_libraries` calls does not allow correct compilation,
  218. use of an appropriate command to set the property directly may update the
  219. order.
  220. For example, if the linked libraries for a target must be specified
  221. in the order ``lib1`` ``lib2`` ``lib3`` , but the include directories must
  222. be specified in the order ``lib3`` ``lib1`` ``lib2``:
  223. .. code-block:: cmake
  224. target_link_libraries(myExe lib1 lib2 lib3)
  225. target_include_directories(myExe
  226. PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
  227. Note that care must be taken when specifying usage requirements for targets
  228. which will be exported for installation using the :command:`install(EXPORT)`
  229. command. See :ref:`Creating Packages` for more.
  230. .. _`Compatible Interface Properties`:
  231. Compatible Interface Properties
  232. -------------------------------
  233. Some target properties are required to be compatible between a target and
  234. the interface of each dependency. For example, the
  235. :prop_tgt:`POSITION_INDEPENDENT_CODE` target property may specify a
  236. boolean value of whether a target should be compiled as
  237. position-independent-code, which has platform-specific consequences.
  238. A target may also specify the usage requirement
  239. :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` to communicate that
  240. consumers must be compiled as position-independent-code.
  241. .. code-block:: cmake
  242. add_executable(exe1 exe1.cpp)
  243. set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON)
  244. add_library(lib1 SHARED lib1.cpp)
  245. set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
  246. add_executable(exe2 exe2.cpp)
  247. target_link_libraries(exe2 lib1)
  248. Here, both ``exe1`` and ``exe2`` will be compiled as position-independent-code.
  249. ``lib1`` will also be compiled as position-independent-code because that is the
  250. default setting for ``SHARED`` libraries. If dependencies have conflicting,
  251. non-compatible requirements :manual:`cmake(1)` issues a diagnostic:
  252. .. code-block:: cmake
  253. add_library(lib1 SHARED lib1.cpp)
  254. set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
  255. add_library(lib2 SHARED lib2.cpp)
  256. set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
  257. add_executable(exe1 exe1.cpp)
  258. target_link_libraries(exe1 lib1)
  259. set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF)
  260. add_executable(exe2 exe2.cpp)
  261. target_link_libraries(exe2 lib1 lib2)
  262. The ``lib1`` requirement ``INTERFACE_POSITION_INDEPENDENT_CODE`` is not
  263. "compatible" with the ``POSITION_INDEPENDENT_CODE`` property of the ``exe1``
  264. target. The library requires that consumers are built as
  265. position-independent-code, while the executable specifies to not built as
  266. position-independent-code, so a diagnostic is issued.
  267. The ``lib1`` and ``lib2`` requirements are not "compatible". One of them
  268. requires that consumers are built as position-independent-code, while
  269. the other requires that consumers are not built as position-independent-code.
  270. Because ``exe2`` links to both and they are in conflict, a diagnostic is
  271. issued.
  272. To be "compatible", the :prop_tgt:`POSITION_INDEPENDENT_CODE` property,
  273. if set must be either the same, in a boolean sense, as the
  274. :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE` property of all transitively
  275. specified dependencies on which that property is set.
  276. This property of "compatible interface requirement" may be extended to other
  277. properties by specifying the property in the content of the
  278. :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` target property. Each specified property
  279. must be compatible between the consuming target and the corresponding property
  280. with an ``INTERFACE_`` prefix from each dependency:
  281. .. code-block:: cmake
  282. add_library(lib1Version2 SHARED lib1_v2.cpp)
  283. set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON)
  284. set_property(TARGET lib1Version2 APPEND PROPERTY
  285. COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP
  286. )
  287. add_library(lib1Version3 SHARED lib1_v3.cpp)
  288. set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF)
  289. add_executable(exe1 exe1.cpp)
  290. target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON
  291. add_executable(exe2 exe2.cpp)
  292. target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
  293. Non-boolean properties may also participate in "compatible interface"
  294. computations. Properties specified in the
  295. :prop_tgt:`COMPATIBLE_INTERFACE_STRING`
  296. property must be either unspecified or compare to the same string among
  297. all transitively specified dependencies. This can be useful to ensure
  298. that multiple incompatible versions of a library are not linked together
  299. through transitive requirements of a target:
  300. .. code-block:: cmake
  301. add_library(lib1Version2 SHARED lib1_v2.cpp)
  302. set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2)
  303. set_property(TARGET lib1Version2 APPEND PROPERTY
  304. COMPATIBLE_INTERFACE_STRING LIB_VERSION
  305. )
  306. add_library(lib1Version3 SHARED lib1_v3.cpp)
  307. set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3)
  308. add_executable(exe1 exe1.cpp)
  309. target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2"
  310. add_executable(exe2 exe2.cpp)
  311. target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic
  312. The :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` target property specifies
  313. that content will be evaluated numerically and the maximum number among all
  314. specified will be calculated:
  315. .. code-block:: cmake
  316. add_library(lib1Version2 SHARED lib1_v2.cpp)
  317. set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200)
  318. set_property(TARGET lib1Version2 APPEND PROPERTY
  319. COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
  320. )
  321. add_library(lib1Version3 SHARED lib1_v3.cpp)
  322. set_property(TARGET lib1Version3 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000)
  323. add_executable(exe1 exe1.cpp)
  324. # CONTAINER_SIZE_REQUIRED will be "200"
  325. target_link_libraries(exe1 lib1Version2)
  326. add_executable(exe2 exe2.cpp)
  327. # CONTAINER_SIZE_REQUIRED will be "1000"
  328. target_link_libraries(exe2 lib1Version2 lib1Version3)
  329. Similarly, the :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN` may be used to
  330. calculate the numeric minimum value for a property from dependencies.
  331. Each calculated "compatible" property value may be read in the consumer at
  332. generate-time using generator expressions.
  333. Note that for each dependee, the set of properties specified in each
  334. compatible interface property must not intersect with the set specified in
  335. any of the other properties.
  336. Property Origin Debugging
  337. -------------------------
  338. Because build specifications can be determined by dependencies, the lack of
  339. locality of code which creates a target and code which is responsible for
  340. setting build specifications may make the code more difficult to reason about.
  341. :manual:`cmake(1)` provides a debugging facility to print the origin of the
  342. contents of properties which may be determined by dependencies. The properties
  343. which can be debugged are listed in the
  344. :variable:`CMAKE_DEBUG_TARGET_PROPERTIES` variable documentation:
  345. .. code-block:: cmake
  346. set(CMAKE_DEBUG_TARGET_PROPERTIES
  347. INCLUDE_DIRECTORIES
  348. COMPILE_DEFINITIONS
  349. POSITION_INDEPENDENT_CODE
  350. CONTAINER_SIZE_REQUIRED
  351. LIB_VERSION
  352. )
  353. add_executable(exe1 exe1.cpp)
  354. In the case of properties listed in :prop_tgt:`COMPATIBLE_INTERFACE_BOOL` or
  355. :prop_tgt:`COMPATIBLE_INTERFACE_STRING`, the debug output shows which target
  356. was responsible for setting the property, and which other dependencies also
  357. defined the property. In the case of
  358. :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MAX` and
  359. :prop_tgt:`COMPATIBLE_INTERFACE_NUMBER_MIN`, the debug output shows the
  360. value of the property from each dependency, and whether the value determines
  361. the new extreme.
  362. Build Specification with Generator Expressions
  363. ----------------------------------------------
  364. Build specifications may use
  365. :manual:`generator expressions <cmake-generator-expressions(7)>` containing
  366. content which may be conditional or known only at generate-time. For example,
  367. the calculated "compatible" value of a property may be read with the
  368. ``TARGET_PROPERTY`` expression:
  369. .. code-block:: cmake
  370. add_library(lib1Version2 SHARED lib1_v2.cpp)
  371. set_property(TARGET lib1Version2 PROPERTY
  372. INTERFACE_CONTAINER_SIZE_REQUIRED 200)
  373. set_property(TARGET lib1Version2 APPEND PROPERTY
  374. COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED
  375. )
  376. add_executable(exe1 exe1.cpp)
  377. target_link_libraries(exe1 lib1Version2)
  378. target_compile_definitions(exe1 PRIVATE
  379. CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED>
  380. )
  381. In this case, the ``exe1`` source files will be compiled with
  382. ``-DCONTAINER_SIZE=200``.
  383. Configuration determined build specifications may be conveniently set using
  384. the ``CONFIG`` generator expression.
  385. .. code-block:: cmake
  386. target_compile_definitions(exe1 PRIVATE
  387. $<$<CONFIG:Debug>:DEBUG_BUILD>
  388. )
  389. The ``CONFIG`` parameter is compared case-insensitively with the configuration
  390. being built. In the presence of :prop_tgt:`IMPORTED` targets, the content of
  391. :prop_tgt:`MAP_IMPORTED_CONFIG_DEBUG <MAP_IMPORTED_CONFIG_<CONFIG>>` is also
  392. accounted for by this expression.
  393. Some buildsystems generated by :manual:`cmake(1)` have a predetermined
  394. build-configuration set in the :variable:`CMAKE_BUILD_TYPE` variable. The
  395. buildsystem for the IDEs such as Visual Studio and Xcode are generated
  396. independent of the build-configuration, and the actual build configuration
  397. is not known until build-time. Therefore, code such as
  398. .. code-block:: cmake
  399. string(TOLOWER ${CMAKE_BUILD_TYPE} _type)
  400. if (_type STREQUAL debug)
  401. target_compile_definitions(exe1 PRIVATE DEBUG_BUILD)
  402. endif()
  403. may appear to work for ``Makefile`` based and ``Ninja`` generators, but is not
  404. portable to IDE generators. Additionally, the :prop_tgt:`IMPORTED`
  405. configuration-mappings are not accounted for with code like this, so it should
  406. be avoided.
  407. The unary ``TARGET_PROPERTY`` generator expression and the ``TARGET_POLICY``
  408. generator expression are evaluated with the consuming target context. This
  409. means that a usage requirement specification may be evaluated differently based
  410. on the consumer:
  411. .. code-block:: cmake
  412. add_library(lib1 lib1.cpp)
  413. target_compile_definitions(lib1 INTERFACE
  414. $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE>
  415. $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB>
  416. $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW>
  417. )
  418. add_executable(exe1 exe1.cpp)
  419. target_link_libraries(exe1 lib1)
  420. cmake_policy(SET CMP0041 NEW)
  421. add_library(shared_lib shared_lib.cpp)
  422. target_link_libraries(shared_lib lib1)
  423. The ``exe1`` executable will be compiled with ``-DLIB1_WITH_EXE``, while the
  424. ``shared_lib`` shared library will be compiled with ``-DLIB1_WITH_SHARED_LIB``
  425. and ``-DCONSUMER_CMP0041_NEW``, because policy :policy:`CMP0041` is
  426. ``NEW`` at the point where the ``shared_lib`` target is created.
  427. The ``BUILD_INTERFACE`` expression wraps requirements which are only used when
  428. consumed from a target in the same buildsystem, or when consumed from a target
  429. exported to the build directory using the :command:`export` command. The
  430. ``INSTALL_INTERFACE`` expression wraps requirements which are only used when
  431. consumed from a target which has been installed and exported with the
  432. :command:`install(EXPORT)` command:
  433. .. code-block:: cmake
  434. add_library(ClimbingStats climbingstats.cpp)
  435. target_compile_definitions(ClimbingStats INTERFACE
  436. $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION>
  437. $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION>
  438. )
  439. install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs})
  440. install(EXPORT libExport NAMESPACE Upstream::
  441. DESTINATION lib/cmake/ClimbingStats)
  442. export(EXPORT libExport NAMESPACE Upstream::)
  443. add_executable(exe1 exe1.cpp)
  444. target_link_libraries(exe1 ClimbingStats)
  445. In this case, the ``exe1`` executable will be compiled with
  446. ``-DClimbingStats_FROM_BUILD_LOCATION``. The exporting commands generate
  447. :prop_tgt:`IMPORTED` targets with either the ``INSTALL_INTERFACE`` or the
  448. ``BUILD_INTERFACE`` omitted, and the ``*_INTERFACE`` marker stripped away.
  449. A separate project consuming the ``ClimbingStats`` package would contain:
  450. .. code-block:: cmake
  451. find_package(ClimbingStats REQUIRED)
  452. add_executable(Downstream main.cpp)
  453. target_link_libraries(Downstream Upstream::ClimbingStats)
  454. Depending on whether the ``ClimbingStats`` package was used from the build
  455. location or the install location, the ``Downstream`` target would be compiled
  456. with either ``-DClimbingStats_FROM_BUILD_LOCATION`` or
  457. ``-DClimbingStats_FROM_INSTALL_LOCATION``. For more about packages and
  458. exporting see the :manual:`cmake-packages(7)` manual.
  459. .. _`Include Directories and Usage Requirements`:
  460. Include Directories and Usage Requirements
  461. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  462. Include directories require some special consideration when specified as usage
  463. requirements and when used with generator expressions. The
  464. :command:`target_include_directories` command accepts both relative and
  465. absolute include directories:
  466. .. code-block:: cmake
  467. add_library(lib1 lib1.cpp)
  468. target_include_directories(lib1 PRIVATE
  469. /absolute/path
  470. relative/path
  471. )
  472. Relative paths are interpreted relative to the source directory where the
  473. command appears. Relative paths are not allowed in the
  474. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of :prop_tgt:`IMPORTED` targets.
  475. In cases where a non-trivial generator expression is used, the
  476. ``INSTALL_PREFIX`` expression may be used within the argument of an
  477. ``INSTALL_INTERFACE`` expression. It is a replacement marker which
  478. expands to the installation prefix when imported by a consuming project.
  479. Include directories usage requirements commonly differ between the build-tree
  480. and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
  481. generator expressions can be used to describe separate usage requirements
  482. based on the usage location. Relative paths are allowed within the
  483. ``INSTALL_INTERFACE`` expression and are interpreted relative to the
  484. installation prefix. For example:
  485. .. code-block:: cmake
  486. add_library(ClimbingStats climbingstats.cpp)
  487. target_include_directories(ClimbingStats INTERFACE
  488. $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated>
  489. $<INSTALL_INTERFACE:/absolute/path>
  490. $<INSTALL_INTERFACE:relative/path>
  491. $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated>
  492. )
  493. Two convenience APIs are provided relating to include directories usage
  494. requirements. The :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable
  495. may be enabled, with an equivalent effect to:
  496. .. code-block:: cmake
  497. set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
  498. $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}>
  499. )
  500. for each target affected. The convenience for installed targets is
  501. an ``INCLUDES DESTINATION`` component with the :command:`install(TARGETS)`
  502. command:
  503. .. code-block:: cmake
  504. install(TARGETS foo bar bat EXPORT tgts ${dest_args}
  505. INCLUDES DESTINATION include
  506. )
  507. install(EXPORT tgts ${other_args})
  508. install(FILES ${headers} DESTINATION include)
  509. This is equivalent to appending ``${CMAKE_INSTALL_PREFIX}/include`` to the
  510. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of each of the installed
  511. :prop_tgt:`IMPORTED` targets when generated by :command:`install(EXPORT)`.
  512. When the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an
  513. :ref:`imported target <Imported targets>` is consumed, the entries in the
  514. property are treated as ``SYSTEM`` include directories, as if they were
  515. listed in the :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` of the
  516. dependency. This can result in omission of compiler warnings for headers
  517. found in those directories. This behavior for :ref:`imported targets` may
  518. be controlled with the :prop_tgt:`NO_SYSTEM_FROM_IMPORTED` target property.
  519. If a binary target is linked transitively to a Mac OX framework, the
  520. ``Headers`` directory of the framework is also treated as a usage requirement.
  521. This has the same effect as passing the framework directory as an include
  522. directory.
  523. Link Libraries and Generator Expressions
  524. ----------------------------------------
  525. Like build specifications, :prop_tgt:`link libraries <LINK_LIBRARIES>` may be
  526. specified with generator expression conditions. However, as consumption of
  527. usage requirements is based on collection from linked dependencies, there is
  528. an additional limitation that the link dependencies must form a "directed
  529. acyclic graph". That is, if linking to a target is dependent on the value of
  530. a target property, that target property may not be dependent on the linked
  531. dependencies:
  532. .. code-block:: cmake
  533. add_library(lib1 lib1.cpp)
  534. add_library(lib2 lib2.cpp)
  535. target_link_libraries(lib1 PUBLIC
  536. $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2>
  537. )
  538. add_library(lib3 lib3.cpp)
  539. set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
  540. add_executable(exe1 exe1.cpp)
  541. target_link_libraries(exe1 lib1 lib3)
  542. As the value of the :prop_tgt:`POSITION_INDEPENDENT_CODE` property of
  543. the ``exe1`` target is dependent on the linked libraries (``lib3``), and the
  544. edge of linking ``exe1`` is determined by the same
  545. :prop_tgt:`POSITION_INDEPENDENT_CODE` property, the dependency graph above
  546. contains a cycle. :manual:`cmake(1)` issues a diagnostic in this case.
  547. .. _`Output Artifacts`:
  548. Output Artifacts
  549. ----------------
  550. The buildsystem targets created by the :command:`add_library` and
  551. :command:`add_executable` commands create rules to create binary outputs.
  552. The exact output location of the binaries can only be determined at
  553. generate-time because it can depend on the build-configuration and the
  554. link-language of linked dependencies etc. ``TARGET_FILE``,
  555. ``TARGET_LINKER_FILE`` and related expressions can be used to access the
  556. name and location of generated binaries. These expressions do not work
  557. for ``OBJECT`` libraries however, as there is no single file generated
  558. by such libraries which is relevant to the expressions.
  559. There are three kinds of output artifacts that may be build by targets
  560. as detailed in the following sections. Their classification differs
  561. between DLL platforms and non-DLL platforms. All Windows-based
  562. systems including Cygwin are DLL platforms.
  563. .. _`Runtime Output Artifacts`:
  564. Runtime Output Artifacts
  565. ^^^^^^^^^^^^^^^^^^^^^^^^
  566. A *runtime* output artifact of a buildsystem target may be:
  567. * The executable file (e.g. ``.exe``) of an executable target
  568. created by the :command:`add_executable` command.
  569. * On DLL platforms: the executable file (e.g. ``.dll``) of a shared
  570. library target created by the :command:`add_library` command
  571. with the ``SHARED`` option.
  572. The :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and :prop_tgt:`RUNTIME_OUTPUT_NAME`
  573. target properties may be used to control runtime output artifact locations
  574. and names in the build tree.
  575. .. _`Library Output Artifacts`:
  576. Library Output Artifacts
  577. ^^^^^^^^^^^^^^^^^^^^^^^^
  578. A *library* output artifact of a buildsystem target may be:
  579. * The loadable module file (e.g. ``.dll`` or ``.so``) of a module
  580. library target created by the :command:`add_library` command
  581. with the ``MODULE`` option.
  582. * On non-DLL platforms: the shared library file (e.g. ``.so`` or ``.dylib``)
  583. of a shared shared library target created by the :command:`add_library`
  584. command with the ``SHARED`` option.
  585. The :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY` and :prop_tgt:`LIBRARY_OUTPUT_NAME`
  586. target properties may be used to control library output artifact locations
  587. and names in the build tree.
  588. .. _`Archive Output Artifacts`:
  589. Archive Output Artifacts
  590. ^^^^^^^^^^^^^^^^^^^^^^^^
  591. An *archive* output artifact of a buildsystem target may be:
  592. * The static library file (e.g. ``.lib`` or ``.a``) of a static
  593. library target created by the :command:`add_library` command
  594. with the ``STATIC`` option.
  595. * On DLL platforms: the import library file (e.g. ``.lib``) of a shared
  596. library target created by the :command:`add_library` command
  597. with the ``SHARED`` option. This file is only guaranteed to exist if
  598. the library exports at least one unmanaged symbol.
  599. * On DLL platforms: the import library file (e.g. ``.lib``) of an
  600. executable target created by the :command:`add_executable` command
  601. when its :prop_tgt:`ENABLE_EXPORTS` target property is set.
  602. The :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`
  603. target properties may be used to control archive output artifact locations
  604. and names in the build tree.
  605. Directory-Scoped Commands
  606. -------------------------
  607. The :command:`target_include_directories`,
  608. :command:`target_compile_definitions` and
  609. :command:`target_compile_options` commands have an effect on only one
  610. target at a time. The commands :command:`add_definitions`,
  611. :command:`add_compile_options` and :command:`include_directories` have
  612. a similar function, but operate at directory scope instead of target
  613. scope for convenience.
  614. Pseudo Targets
  615. ==============
  616. Some target types do not represent outputs of the buildsystem, but only inputs
  617. such as external dependencies, aliases or other non-build artifacts. Pseudo
  618. targets are not represented in the generated buildsystem.
  619. .. _`Imported Targets`:
  620. Imported Targets
  621. ----------------
  622. An :prop_tgt:`IMPORTED` target represents a pre-existing dependency. Usually
  623. such targets are defined by an upstream package and should be treated as
  624. immutable. It is not possible to use an :prop_tgt:`IMPORTED` target in the
  625. left-hand-side of the :command:`target_compile_definitions`,
  626. :command:`target_include_directories`, :command:`target_compile_options` or
  627. :command:`target_link_libraries` commands, as that would be an attempt to
  628. modify it. :prop_tgt:`IMPORTED` targets are designed to be used only in the
  629. right-hand-side of those commands.
  630. :prop_tgt:`IMPORTED` targets may have the same usage requirement properties
  631. populated as binary targets, such as
  632. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
  633. :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
  634. :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
  635. :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and
  636. :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
  637. The :prop_tgt:`LOCATION` may also be read from an IMPORTED target, though there
  638. is rarely reason to do so. Commands such as :command:`add_custom_command` can
  639. transparently use an :prop_tgt:`IMPORTED` :prop_tgt:`EXECUTABLE <TYPE>` target
  640. as a ``COMMAND`` executable.
  641. The scope of the definition of an :prop_tgt:`IMPORTED` target is the directory
  642. where it was defined. It may be accessed and used from subdirectories, but
  643. not from parent directories or sibling directories. The scope is similar to
  644. the scope of a cmake variable.
  645. It is also possible to define a ``GLOBAL`` :prop_tgt:`IMPORTED` target which is
  646. accessible globally in the buildsystem.
  647. See the :manual:`cmake-packages(7)` manual for more on creating packages
  648. with :prop_tgt:`IMPORTED` targets.
  649. .. _`Alias Targets`:
  650. Alias Targets
  651. -------------
  652. An ``ALIAS`` target is a name which may be used interchangably with
  653. a binary target name in read-only contexts. A primary use-case for ``ALIAS``
  654. targets is for example or unit test executables accompanying a library, which
  655. may be part of the same buildsystem or built separately based on user
  656. configuration.
  657. .. code-block:: cmake
  658. add_library(lib1 lib1.cpp)
  659. install(TARGETS lib1 EXPORT lib1Export ${dest_args})
  660. install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args})
  661. add_library(Upstream::lib1 ALIAS lib1)
  662. In another directory, we can link unconditionally to the ``Upstream::lib1``
  663. target, which may be an :prop_tgt:`IMPORTED` target from a package, or an
  664. ``ALIAS`` target if built as part of the same buildsystem.
  665. .. code-block:: cmake
  666. if (NOT TARGET Upstream::lib1)
  667. find_package(lib1 REQUIRED)
  668. endif()
  669. add_executable(exe1 exe1.cpp)
  670. target_link_libraries(exe1 Upstream::lib1)
  671. ``ALIAS`` targets are not mutable, installable or exportable. They are
  672. entirely local to the buildsystem description. A name can be tested for
  673. whether it is an ``ALIAS`` name by reading the :prop_tgt:`ALIASED_TARGET`
  674. property from it:
  675. .. code-block:: cmake
  676. get_target_property(_aliased Upstream::lib1 ALIASED_TARGET)
  677. if(_aliased)
  678. message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.")
  679. endif()
  680. .. _`Interface Libraries`:
  681. Interface Libraries
  682. -------------------
  683. An ``INTERFACE`` target has no :prop_tgt:`LOCATION` and is mutable, but is
  684. otherwise similar to an :prop_tgt:`IMPORTED` target.
  685. It may specify usage requirements such as
  686. :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
  687. :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`,
  688. :prop_tgt:`INTERFACE_COMPILE_OPTIONS`,
  689. :prop_tgt:`INTERFACE_LINK_LIBRARIES`,
  690. :prop_tgt:`INTERFACE_SOURCES`,
  691. and :prop_tgt:`INTERFACE_POSITION_INDEPENDENT_CODE`.
  692. Only the ``INTERFACE`` modes of the :command:`target_include_directories`,
  693. :command:`target_compile_definitions`, :command:`target_compile_options`,
  694. :command:`target_sources`, and :command:`target_link_libraries` commands
  695. may be used with ``INTERFACE`` libraries.
  696. A primary use-case for ``INTERFACE`` libraries is header-only libraries.
  697. .. code-block:: cmake
  698. add_library(Eigen INTERFACE)
  699. target_include_directories(Eigen INTERFACE
  700. $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
  701. $<INSTALL_INTERFACE:include/Eigen>
  702. )
  703. add_executable(exe1 exe1.cpp)
  704. target_link_libraries(exe1 Eigen)
  705. Here, the usage requirements from the ``Eigen`` target are consumed and used
  706. when compiling, but it has no effect on linking.
  707. Another use-case is to employ an entirely target-focussed design for usage
  708. requirements:
  709. .. code-block:: cmake
  710. add_library(pic_on INTERFACE)
  711. set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON)
  712. add_library(pic_off INTERFACE)
  713. set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF)
  714. add_library(enable_rtti INTERFACE)
  715. target_compile_options(enable_rtti INTERFACE
  716. $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:-rtti>
  717. )
  718. add_executable(exe1 exe1.cpp)
  719. target_link_libraries(exe1 pic_on enable_rtti)
  720. This way, the build specification of ``exe1`` is expressed entirely as linked
  721. targets, and the complexity of compiler-specific flags is encapsulated in an
  722. ``INTERFACE`` library target.
  723. The properties permitted to be set on or read from an ``INTERFACE`` library
  724. are:
  725. * Properties matching ``INTERFACE_*``
  726. * Built-in properties matching ``COMPATIBLE_INTERFACE_*``
  727. * ``EXPORT_NAME``
  728. * ``IMPORTED``
  729. * ``NAME``
  730. * Properties matching ``MAP_IMPORTED_CONFIG_*``
  731. ``INTERFACE`` libraries may be installed and exported. Any content they refer
  732. to must be installed separately:
  733. .. code-block:: cmake
  734. add_library(Eigen INTERFACE)
  735. target_include_directories(Eigen INTERFACE
  736. $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
  737. $<INSTALL_INTERFACE:include/Eigen>
  738. )
  739. install(TARGETS Eigen EXPORT eigenExport)
  740. install(EXPORT eigenExport NAMESPACE Upstream::
  741. DESTINATION lib/cmake/Eigen
  742. )
  743. install(FILES
  744. ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h
  745. ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h
  746. ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h
  747. DESTINATION include/Eigen
  748. )