|
1 .\" Man page generated from reStructuredText. |
|
2 . |
|
3 .TH "CMAKE-BUILDSYSTEM" "7" "October 14, 2015" "3.3.2" "CMake" |
|
4 .SH NAME |
|
5 cmake-buildsystem \- CMake Buildsystem Reference |
|
6 . |
|
7 .nr rst2man-indent-level 0 |
|
8 . |
|
9 .de1 rstReportMargin |
|
10 \\$1 \\n[an-margin] |
|
11 level \\n[rst2man-indent-level] |
|
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] |
|
13 - |
|
14 \\n[rst2man-indent0] |
|
15 \\n[rst2man-indent1] |
|
16 \\n[rst2man-indent2] |
|
17 .. |
|
18 .de1 INDENT |
|
19 .\" .rstReportMargin pre: |
|
20 . RS \\$1 |
|
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] |
|
22 . nr rst2man-indent-level +1 |
|
23 .\" .rstReportMargin post: |
|
24 .. |
|
25 .de UNINDENT |
|
26 . RE |
|
27 .\" indent \\n[an-margin] |
|
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] |
|
29 .nr rst2man-indent-level -1 |
|
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] |
|
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u |
|
32 .. |
|
33 .SH INTRODUCTION |
|
34 .sp |
|
35 A CMake\-based buildsystem is organized as a set of high\-level logical |
|
36 targets. Each target corresponds to an executable or library, or |
|
37 is a custom target containing custom commands. Dependencies between the |
|
38 targets are expressed in the buildsystem to determine the build order |
|
39 and the rules for regeneration in response to change. |
|
40 .SH BINARY TARGETS |
|
41 .sp |
|
42 Executables and libraries are defined using the \fBadd_executable()\fP |
|
43 and \fBadd_library()\fP commands. The resulting binary files have |
|
44 appropriate prefixes, suffixes and extensions for the platform targeted. |
|
45 Dependencies between binary targets are expressed using the |
|
46 \fBtarget_link_libraries()\fP command: |
|
47 .INDENT 0.0 |
|
48 .INDENT 3.5 |
|
49 .sp |
|
50 .nf |
|
51 .ft C |
|
52 add_library(archive archive.cpp zip.cpp lzma.cpp) |
|
53 add_executable(zipapp zipapp.cpp) |
|
54 target_link_libraries(zipapp archive) |
|
55 .ft P |
|
56 .fi |
|
57 .UNINDENT |
|
58 .UNINDENT |
|
59 .sp |
|
60 \fBarchive\fP is defined as a static library \-\- an archive containing objects |
|
61 compiled from \fBarchive.cpp\fP, \fBzip.cpp\fP, and \fBlzma.cpp\fP\&. \fBzipapp\fP |
|
62 is defined as an executable formed by compiling and linking \fBzipapp.cpp\fP\&. |
|
63 When linking the \fBzipapp\fP executable, the \fBarchive\fP static library is |
|
64 linked in. |
|
65 .SS Binary Executables |
|
66 .sp |
|
67 The \fBadd_executable()\fP command defines an executable target: |
|
68 .INDENT 0.0 |
|
69 .INDENT 3.5 |
|
70 .sp |
|
71 .nf |
|
72 .ft C |
|
73 add_executable(mytool mytool.cpp) |
|
74 .ft P |
|
75 .fi |
|
76 .UNINDENT |
|
77 .UNINDENT |
|
78 .sp |
|
79 Commands such as \fBadd_custom_command()\fP, which generates rules to be |
|
80 run at build time can transparently use an \fBEXECUTABLE\fP |
|
81 target as a \fBCOMMAND\fP executable. The buildsystem rules will ensure that |
|
82 the executable is built before attempting to run the command. |
|
83 .SS Binary Library Types |
|
84 .SS Normal Libraries |
|
85 .sp |
|
86 By default, the \fBadd_library()\fP command defines a static library, |
|
87 unless a type is specified. A type may be specified when using the command: |
|
88 .INDENT 0.0 |
|
89 .INDENT 3.5 |
|
90 .sp |
|
91 .nf |
|
92 .ft C |
|
93 add_library(archive SHARED archive.cpp zip.cpp lzma.cpp) |
|
94 .ft P |
|
95 .fi |
|
96 .UNINDENT |
|
97 .UNINDENT |
|
98 .INDENT 0.0 |
|
99 .INDENT 3.5 |
|
100 .sp |
|
101 .nf |
|
102 .ft C |
|
103 add_library(archive STATIC archive.cpp zip.cpp lzma.cpp) |
|
104 .ft P |
|
105 .fi |
|
106 .UNINDENT |
|
107 .UNINDENT |
|
108 .sp |
|
109 The \fBBUILD_SHARED_LIBS\fP variable may be enabled to change the |
|
110 behavior of \fBadd_library()\fP to build shared libraries by default. |
|
111 .sp |
|
112 In the context of the buildsystem definition as a whole, it is largely |
|
113 irrelevant whether particular libraries are \fBSHARED\fP or \fBSTATIC\fP \-\- |
|
114 the commands, dependency specifications and other APIs work similarly |
|
115 regardless of the library type. The \fBMODULE\fP library type is |
|
116 dissimilar in that it is generally not linked to \-\- it is not used in |
|
117 the right\-hand\-side of the \fBtarget_link_libraries()\fP command. |
|
118 It is a type which is loaded as a plugin using runtime techniques. |
|
119 .INDENT 0.0 |
|
120 .INDENT 3.5 |
|
121 .sp |
|
122 .nf |
|
123 .ft C |
|
124 add_library(archive MODULE 7z.cpp) |
|
125 .ft P |
|
126 .fi |
|
127 .UNINDENT |
|
128 .UNINDENT |
|
129 .SS Object Libraries |
|
130 .sp |
|
131 The \fBOBJECT\fP library type is also not linked to. It defines a non\-archival |
|
132 collection of object files resulting from compiling the given source files. |
|
133 The object files collection can be used as source inputs to other targets: |
|
134 .INDENT 0.0 |
|
135 .INDENT 3.5 |
|
136 .sp |
|
137 .nf |
|
138 .ft C |
|
139 add_library(archive OBJECT archive.cpp zip.cpp lzma.cpp) |
|
140 |
|
141 add_library(archiveExtras STATIC $<TARGET_OBJECTS:archive> extras.cpp) |
|
142 |
|
143 add_executable(test_exe $<TARGET_OBJECTS:archive> test.cpp) |
|
144 .ft P |
|
145 .fi |
|
146 .UNINDENT |
|
147 .UNINDENT |
|
148 .sp |
|
149 \fBOBJECT\fP libraries may only be used locally as sources in a buildsystem \-\- |
|
150 they may not be installed, exported, or used in the right hand side of |
|
151 \fBtarget_link_libraries()\fP\&. They also may not be used as the \fBTARGET\fP |
|
152 in a use of the \fBadd_custom_command(TARGET)\fP command signature. |
|
153 .sp |
|
154 Although object libraries may not be named directly in calls to |
|
155 the \fBtarget_link_libraries()\fP command, they can be "linked" |
|
156 indirectly by using an \fI\%Interface Library\fP |
|
157 whose \fBINTERFACE_SOURCES\fP target property is set to name |
|
158 \fB$<TARGET_OBJECTS:objlib>\fP\&. |
|
159 .SH BUILD SPECIFICATION AND USAGE REQUIREMENTS |
|
160 .sp |
|
161 The \fBtarget_include_directories()\fP, \fBtarget_compile_definitions()\fP |
|
162 and \fBtarget_compile_options()\fP commands specify the build specifications |
|
163 and the usage requirements of binary targets. The commands populate the |
|
164 \fBINCLUDE_DIRECTORIES\fP, \fBCOMPILE_DEFINITIONS\fP and |
|
165 \fBCOMPILE_OPTIONS\fP target properties respectively, and/or the |
|
166 \fBINTERFACE_INCLUDE_DIRECTORIES\fP, \fBINTERFACE_COMPILE_DEFINITIONS\fP |
|
167 and \fBINTERFACE_COMPILE_OPTIONS\fP target properties. |
|
168 .sp |
|
169 Each of the commands has a \fBPRIVATE\fP, \fBPUBLIC\fP and \fBINTERFACE\fP mode. The |
|
170 \fBPRIVATE\fP mode populates only the non\-\fBINTERFACE_\fP variant of the target |
|
171 property and the \fBINTERFACE\fP mode populates only the \fBINTERFACE_\fP variants. |
|
172 The \fBPUBLIC\fP mode populates both variants of the repective target property. |
|
173 Each command may be invoked with multiple uses of each keyword: |
|
174 .INDENT 0.0 |
|
175 .INDENT 3.5 |
|
176 .sp |
|
177 .nf |
|
178 .ft C |
|
179 target_compile_definitions(archive |
|
180 PRIVATE BUILDING_WITH_LZMA |
|
181 INTERFACE USING_ARCHIVE_LIB |
|
182 ) |
|
183 .ft P |
|
184 .fi |
|
185 .UNINDENT |
|
186 .UNINDENT |
|
187 .sp |
|
188 Note that usage requirements are not designed as a way to make downstreams |
|
189 use particular \fBCOMPILE_OPTIONS\fP or |
|
190 \fBCOMPILE_DEFINITIONS\fP etc for convenience only. The contents of |
|
191 the properties must be \fBrequirements\fP, not merely recommendations or |
|
192 convenience. |
|
193 .sp |
|
194 See the Creating Relocatable Packages section of the |
|
195 \fBcmake\-packages(7)\fP manual for discussion of additional care |
|
196 that must be taken when specifying usage requirements while creating |
|
197 packages for redistribution. |
|
198 .SS Target Properties |
|
199 .sp |
|
200 The contents of the \fBINCLUDE_DIRECTORIES\fP, |
|
201 \fBCOMPILE_DEFINITIONS\fP and \fBCOMPILE_OPTIONS\fP target |
|
202 properties are used appropriately when compiling the source files of a |
|
203 binary target. |
|
204 .sp |
|
205 Entries in the \fBINCLUDE_DIRECTORIES\fP are added to the compile line |
|
206 with \fB\-I\fP or \fB\-isystem\fP prefixes and in the order of appearance in the |
|
207 property value. |
|
208 .sp |
|
209 Entries in the \fBCOMPILE_DEFINITIONS\fP are prefixed with \fB\-D\fP or |
|
210 \fB/D\fP and added to the compile line in an unspecified order. The |
|
211 \fBDEFINE_SYMBOL\fP target property is also added as a compile |
|
212 definition as a special convenience case for \fBSHARED\fP and \fBMODULE\fP |
|
213 library targets. |
|
214 .sp |
|
215 Entries in the \fBCOMPILE_OPTIONS\fP are escaped for the shell and added |
|
216 in the order of appearance in the property value. Several compile options have |
|
217 special separate handling, such as \fBPOSITION_INDEPENDENT_CODE\fP\&. |
|
218 .sp |
|
219 The contents of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP, |
|
220 \fBINTERFACE_COMPILE_DEFINITIONS\fP and |
|
221 \fBINTERFACE_COMPILE_OPTIONS\fP target properties are |
|
222 \fIUsage Requirements\fP \-\- they specify content which consumers |
|
223 must use to correctly compile and link with the target they appear on. |
|
224 For any binary target, the contents of each \fBINTERFACE_\fP property on |
|
225 each target specified in a \fBtarget_link_libraries()\fP command is |
|
226 consumed: |
|
227 .INDENT 0.0 |
|
228 .INDENT 3.5 |
|
229 .sp |
|
230 .nf |
|
231 .ft C |
|
232 set(srcs archive.cpp zip.cpp) |
|
233 if (LZMA_FOUND) |
|
234 list(APPEND srcs lzma.cpp) |
|
235 endif() |
|
236 add_library(archive SHARED ${srcs}) |
|
237 if (LZMA_FOUND) |
|
238 # The archive library sources are compiled with \-DBUILDING_WITH_LZMA |
|
239 target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA) |
|
240 endif() |
|
241 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB) |
|
242 |
|
243 add_executable(consumer) |
|
244 # Link consumer to archive and consume its usage requirements. The consumer |
|
245 # executable sources are compiled with \-DUSING_ARCHIVE_LIB. |
|
246 target_link_libraries(consumer archive) |
|
247 .ft P |
|
248 .fi |
|
249 .UNINDENT |
|
250 .UNINDENT |
|
251 .sp |
|
252 Because it is common to require that the source directory and corresponding |
|
253 build directory are added to the \fBINCLUDE_DIRECTORIES\fP, the |
|
254 \fBCMAKE_INCLUDE_CURRENT_DIR\fP variable can be enabled to conveniently |
|
255 add the corresponding directories to the \fBINCLUDE_DIRECTORIES\fP of |
|
256 all targets. The variable \fBCMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE\fP |
|
257 can be enabled to add the corresponding directories to the |
|
258 \fBINTERFACE_INCLUDE_DIRECTORIES\fP of all targets. This makes use of |
|
259 targets in multiple different directories convenient through use of the |
|
260 \fBtarget_link_libraries()\fP command. |
|
261 .SS Transitive Usage Requirements |
|
262 .sp |
|
263 The usage requirements of a target can transitively propagate to dependents. |
|
264 The \fBtarget_link_libraries()\fP command has \fBPRIVATE\fP, |
|
265 \fBINTERFACE\fP and \fBPUBLIC\fP keywords to control the propagation. |
|
266 .INDENT 0.0 |
|
267 .INDENT 3.5 |
|
268 .sp |
|
269 .nf |
|
270 .ft C |
|
271 add_library(archive archive.cpp) |
|
272 target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB) |
|
273 |
|
274 add_library(serialization serialization.cpp) |
|
275 target_compile_definitions(serialization INTERFACE USING_SERIALIZATION_LIB) |
|
276 |
|
277 add_library(archiveExtras extras.cpp) |
|
278 target_link_libraries(archiveExtras PUBLIC archive) |
|
279 target_link_libraries(archiveExtras PRIVATE serialization) |
|
280 # archiveExtras is compiled with \-DUSING_ARCHIVE_LIB |
|
281 # and \-DUSING_SERIALIZATION_LIB |
|
282 |
|
283 add_executable(consumer consumer.cpp) |
|
284 # consumer is compiled with \-DUSING_ARCHIVE_LIB |
|
285 target_link_libraries(consumer archiveExtras) |
|
286 .ft P |
|
287 .fi |
|
288 .UNINDENT |
|
289 .UNINDENT |
|
290 .sp |
|
291 Because \fBarchive\fP is a \fBPUBLIC\fP dependency of \fBarchiveExtras\fP, the |
|
292 usage requirements of it are propagated to \fBconsumer\fP too. Because |
|
293 \fBserialization\fP is a \fBPRIVATE\fP dependency of \fBarchive\fP, the usage |
|
294 requirements of it are not propagated to \fBconsumer\fP\&. |
|
295 .sp |
|
296 Generally, a dependency should be specified in a use of |
|
297 \fBtarget_link_libraries()\fP with the \fBPRIVATE\fP keyword if it is used by |
|
298 only the implementation of a library, and not in the header files. If a |
|
299 dependency is additionally used in the header files of a library (e.g. for |
|
300 class inheritance), then it should be specified as a \fBPUBLIC\fP dependency. |
|
301 A dependency which is not used by the implementation of a library, but only by |
|
302 its headers should be specified as an \fBINTERFACE\fP dependency. The |
|
303 \fBtarget_link_libraries()\fP command may be invoked with multiple uses of |
|
304 each keyword: |
|
305 .INDENT 0.0 |
|
306 .INDENT 3.5 |
|
307 .sp |
|
308 .nf |
|
309 .ft C |
|
310 target_link_libraries(archiveExtras |
|
311 PUBLIC archive |
|
312 PRIVATE serialization |
|
313 ) |
|
314 .ft P |
|
315 .fi |
|
316 .UNINDENT |
|
317 .UNINDENT |
|
318 .sp |
|
319 Usage requirements are propagated by reading the \fBINTERFACE_\fP variants |
|
320 of target properties from dependencies and appending the values to the |
|
321 non\-\fBINTERFACE_\fP variants of the operand. For example, the |
|
322 \fBINTERFACE_INCLUDE_DIRECTORIES\fP of dependencies is read and |
|
323 appended to the \fBINCLUDE_DIRECTORIES\fP of the operand. In cases |
|
324 where order is relevant and maintained, and the order resulting from the |
|
325 \fBtarget_link_libraries()\fP calls does not allow correct compilation, |
|
326 use of an appropriate command to set the property directly may update the |
|
327 order. |
|
328 .sp |
|
329 For example, if the linked libraries for a target must be specified |
|
330 in the order \fBlib1\fP \fBlib2\fP \fBlib3\fP , but the include directories must |
|
331 be specified in the order \fBlib3\fP \fBlib1\fP \fBlib2\fP: |
|
332 .INDENT 0.0 |
|
333 .INDENT 3.5 |
|
334 .sp |
|
335 .nf |
|
336 .ft C |
|
337 target_link_libraries(myExe lib1 lib2 lib3) |
|
338 target_include_directories(myExe |
|
339 PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>) |
|
340 .ft P |
|
341 .fi |
|
342 .UNINDENT |
|
343 .UNINDENT |
|
344 .sp |
|
345 Note that care must be taken when specifying usage requirements for targets |
|
346 which will be exported for installation using the \fBinstall(EXPORT)\fP |
|
347 command. See Creating Packages for more. |
|
348 .SS Compatible Interface Properties |
|
349 .sp |
|
350 Some target properties are required to be compatible between a target and |
|
351 the interface of each dependency. For example, the |
|
352 \fBPOSITION_INDEPENDENT_CODE\fP target property may specify a |
|
353 boolean value of whether a target should be compiled as |
|
354 position\-independent\-code, which has platform\-specific consequences. |
|
355 A target may also specify the usage requirement |
|
356 \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP to communicate that |
|
357 consumers must be compiled as position\-independent\-code. |
|
358 .INDENT 0.0 |
|
359 .INDENT 3.5 |
|
360 .sp |
|
361 .nf |
|
362 .ft C |
|
363 add_executable(exe1 exe1.cpp) |
|
364 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE ON) |
|
365 |
|
366 add_library(lib1 SHARED lib1.cpp) |
|
367 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) |
|
368 |
|
369 add_executable(exe2 exe2.cpp) |
|
370 target_link_libraries(exe2 lib1) |
|
371 .ft P |
|
372 .fi |
|
373 .UNINDENT |
|
374 .UNINDENT |
|
375 .sp |
|
376 Here, both \fBexe1\fP and \fBexe2\fP will be compiled as position\-independent\-code. |
|
377 \fBlib1\fP will also be compiled as position\-independent\-code because that is the |
|
378 default setting for \fBSHARED\fP libraries. If dependencies have conflicting, |
|
379 non\-compatible requirements \fBcmake(1)\fP issues a diagnostic: |
|
380 .INDENT 0.0 |
|
381 .INDENT 3.5 |
|
382 .sp |
|
383 .nf |
|
384 .ft C |
|
385 add_library(lib1 SHARED lib1.cpp) |
|
386 set_property(TARGET lib1 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) |
|
387 |
|
388 add_library(lib2 SHARED lib2.cpp) |
|
389 set_property(TARGET lib2 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF) |
|
390 |
|
391 add_executable(exe1 exe1.cpp) |
|
392 target_link_libraries(exe1 lib1) |
|
393 set_property(TARGET exe1 PROPERTY POSITION_INDEPENDENT_CODE OFF) |
|
394 |
|
395 add_executable(exe2 exe2.cpp) |
|
396 target_link_libraries(exe2 lib1 lib2) |
|
397 .ft P |
|
398 .fi |
|
399 .UNINDENT |
|
400 .UNINDENT |
|
401 .sp |
|
402 The \fBlib1\fP requirement \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP is not |
|
403 "compatible" with the \fBPOSITION_INDEPENDENT_CODE\fP property of the \fBexe1\fP |
|
404 target. The library requires that consumers are built as |
|
405 position\-independent\-code, while the executable specifies to not built as |
|
406 position\-independent\-code, so a diagnostic is issued. |
|
407 .sp |
|
408 The \fBlib1\fP and \fBlib2\fP requirements are not "compatible". One of them |
|
409 requires that consumers are built as position\-independent\-code, while |
|
410 the other requires that consumers are not built as position\-independent\-code. |
|
411 Because \fBexe2\fP links to both and they are in conflict, a diagnostic is |
|
412 issued. |
|
413 .sp |
|
414 To be "compatible", the \fBPOSITION_INDEPENDENT_CODE\fP property, |
|
415 if set must be either the same, in a boolean sense, as the |
|
416 \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP property of all transitively |
|
417 specified dependencies on which that property is set. |
|
418 .sp |
|
419 This property of "compatible interface requirement" may be extended to other |
|
420 properties by specifying the property in the content of the |
|
421 \fBCOMPATIBLE_INTERFACE_BOOL\fP target property. Each specified property |
|
422 must be compatible between the consuming target and the corresponding property |
|
423 with an \fBINTERFACE_\fP prefix from each dependency: |
|
424 .INDENT 0.0 |
|
425 .INDENT 3.5 |
|
426 .sp |
|
427 .nf |
|
428 .ft C |
|
429 add_library(lib1Version2 SHARED lib1_v2.cpp) |
|
430 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CUSTOM_PROP ON) |
|
431 set_property(TARGET lib1Version2 APPEND PROPERTY |
|
432 COMPATIBLE_INTERFACE_BOOL CUSTOM_PROP |
|
433 ) |
|
434 |
|
435 add_library(lib1Version3 SHARED lib1_v3.cpp) |
|
436 set_property(TARGET lib1Version3 PROPERTY INTERFACE_CUSTOM_PROP OFF) |
|
437 |
|
438 add_executable(exe1 exe1.cpp) |
|
439 target_link_libraries(exe1 lib1Version2) # CUSTOM_PROP will be ON |
|
440 |
|
441 add_executable(exe2 exe2.cpp) |
|
442 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic |
|
443 .ft P |
|
444 .fi |
|
445 .UNINDENT |
|
446 .UNINDENT |
|
447 .sp |
|
448 Non\-boolean properties may also participate in "compatible interface" |
|
449 computations. Properties specified in the |
|
450 \fBCOMPATIBLE_INTERFACE_STRING\fP |
|
451 property must be either unspecified or compare to the same string among |
|
452 all transitively specified dependencies. This can be useful to ensure |
|
453 that multiple incompatible versions of a library are not linked together |
|
454 through transitive requirements of a target: |
|
455 .INDENT 0.0 |
|
456 .INDENT 3.5 |
|
457 .sp |
|
458 .nf |
|
459 .ft C |
|
460 add_library(lib1Version2 SHARED lib1_v2.cpp) |
|
461 set_property(TARGET lib1Version2 PROPERTY INTERFACE_LIB_VERSION 2) |
|
462 set_property(TARGET lib1Version2 APPEND PROPERTY |
|
463 COMPATIBLE_INTERFACE_STRING LIB_VERSION |
|
464 ) |
|
465 |
|
466 add_library(lib1Version3 SHARED lib1_v3.cpp) |
|
467 set_property(TARGET lib1Version3 PROPERTY INTERFACE_LIB_VERSION 3) |
|
468 |
|
469 add_executable(exe1 exe1.cpp) |
|
470 target_link_libraries(exe1 lib1Version2) # LIB_VERSION will be "2" |
|
471 |
|
472 add_executable(exe2 exe2.cpp) |
|
473 target_link_libraries(exe2 lib1Version2 lib1Version3) # Diagnostic |
|
474 .ft P |
|
475 .fi |
|
476 .UNINDENT |
|
477 .UNINDENT |
|
478 .sp |
|
479 The \fBCOMPATIBLE_INTERFACE_NUMBER_MAX\fP target property specifies |
|
480 that content will be evaluated numerically and the maximum number among all |
|
481 specified will be calculated: |
|
482 .INDENT 0.0 |
|
483 .INDENT 3.5 |
|
484 .sp |
|
485 .nf |
|
486 .ft C |
|
487 add_library(lib1Version2 SHARED lib1_v2.cpp) |
|
488 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 200) |
|
489 set_property(TARGET lib1Version2 APPEND PROPERTY |
|
490 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED |
|
491 ) |
|
492 |
|
493 add_library(lib1Version3 SHARED lib1_v3.cpp) |
|
494 set_property(TARGET lib1Version2 PROPERTY INTERFACE_CONTAINER_SIZE_REQUIRED 1000) |
|
495 |
|
496 add_executable(exe1 exe1.cpp) |
|
497 # CONTAINER_SIZE_REQUIRED will be "200" |
|
498 target_link_libraries(exe1 lib1Version2) |
|
499 |
|
500 add_executable(exe2 exe2.cpp) |
|
501 # CONTAINER_SIZE_REQUIRED will be "1000" |
|
502 target_link_libraries(exe2 lib1Version2 lib1Version3) |
|
503 .ft P |
|
504 .fi |
|
505 .UNINDENT |
|
506 .UNINDENT |
|
507 .sp |
|
508 Similarly, the \fBCOMPATIBLE_INTERFACE_NUMBER_MIN\fP may be used to |
|
509 calculate the numeric minimum value for a property from dependencies. |
|
510 .sp |
|
511 Each calculated "compatible" property value may be read in the consumer at |
|
512 generate\-time using generator expressions. |
|
513 .sp |
|
514 Note that for each dependee, the set of properties specified in each |
|
515 compatible interface property must not intersect with the set specified in |
|
516 any of the other properties. |
|
517 .SS Property Origin Debugging |
|
518 .sp |
|
519 Because build specifications can be determined by dependencies, the lack of |
|
520 locality of code which creates a target and code which is responsible for |
|
521 setting build specifications may make the code more difficult to reason about. |
|
522 \fBcmake(1)\fP provides a debugging facility to print the origin of the |
|
523 contents of properties which may be determined by dependencies. The properties |
|
524 which can be debugged are listed in the |
|
525 \fBCMAKE_DEBUG_TARGET_PROPERTIES\fP variable documentation: |
|
526 .INDENT 0.0 |
|
527 .INDENT 3.5 |
|
528 .sp |
|
529 .nf |
|
530 .ft C |
|
531 set(CMAKE_DEBUG_TARGET_PROPERTIES |
|
532 INCLUDE_DIRECTORIES |
|
533 COMPILE_DEFINITIONS |
|
534 POSITION_INDEPENDENT_CODE |
|
535 CONTAINER_SIZE_REQUIRED |
|
536 LIB_VERSION |
|
537 ) |
|
538 add_executable(exe1 exe1.cpp) |
|
539 .ft P |
|
540 .fi |
|
541 .UNINDENT |
|
542 .UNINDENT |
|
543 .sp |
|
544 In the case of properties listed in \fBCOMPATIBLE_INTERFACE_BOOL\fP or |
|
545 \fBCOMPATIBLE_INTERFACE_STRING\fP, the debug output shows which target |
|
546 was responsible for setting the property, and which other dependencies also |
|
547 defined the property. In the case of |
|
548 \fBCOMPATIBLE_INTERFACE_NUMBER_MAX\fP and |
|
549 \fBCOMPATIBLE_INTERFACE_NUMBER_MIN\fP, the debug output shows the |
|
550 value of the property from each dependency, and whether the value determines |
|
551 the new extreme. |
|
552 .SS Build Specification with Generator Expressions |
|
553 .sp |
|
554 Build specifications may use |
|
555 \fBgenerator expressions\fP containing |
|
556 content which may be conditional or known only at generate\-time. For example, |
|
557 the calculated "compatible" value of a property may be read with the |
|
558 \fBTARGET_PROPERTY\fP expression: |
|
559 .INDENT 0.0 |
|
560 .INDENT 3.5 |
|
561 .sp |
|
562 .nf |
|
563 .ft C |
|
564 add_library(lib1Version2 SHARED lib1_v2.cpp) |
|
565 set_property(TARGET lib1Version2 PROPERTY |
|
566 INTERFACE_CONTAINER_SIZE_REQUIRED 200) |
|
567 set_property(TARGET lib1Version2 APPEND PROPERTY |
|
568 COMPATIBLE_INTERFACE_NUMBER_MAX CONTAINER_SIZE_REQUIRED |
|
569 ) |
|
570 |
|
571 add_executable(exe1 exe1.cpp) |
|
572 target_link_libraries(exe1 lib1Version2) |
|
573 target_compile_definitions(exe1 PRIVATE |
|
574 CONTAINER_SIZE=$<TARGET_PROPERTY:CONTAINER_SIZE_REQUIRED> |
|
575 ) |
|
576 .ft P |
|
577 .fi |
|
578 .UNINDENT |
|
579 .UNINDENT |
|
580 .sp |
|
581 In this case, the \fBexe1\fP source files will be compiled with |
|
582 \fB\-DCONTAINER_SIZE=200\fP\&. |
|
583 .sp |
|
584 Configuration determined build specifications may be conveniently set using |
|
585 the \fBCONFIG\fP generator expression. |
|
586 .INDENT 0.0 |
|
587 .INDENT 3.5 |
|
588 .sp |
|
589 .nf |
|
590 .ft C |
|
591 target_compile_definitions(exe1 PRIVATE |
|
592 $<$<CONFIG:Debug>:DEBUG_BUILD> |
|
593 ) |
|
594 .ft P |
|
595 .fi |
|
596 .UNINDENT |
|
597 .UNINDENT |
|
598 .sp |
|
599 The \fBCONFIG\fP parameter is compared case\-insensitively with the configuration |
|
600 being built. In the presence of \fBIMPORTED\fP targets, the content of |
|
601 \fBMAP_IMPORTED_CONFIG_DEBUG\fP is also |
|
602 accounted for by this expression. |
|
603 .sp |
|
604 Some buildsystems generated by \fBcmake(1)\fP have a predetermined |
|
605 build\-configuration set in the \fBCMAKE_BUILD_TYPE\fP variable. The |
|
606 buildsystem for the IDEs such as Visual Studio and Xcode are generated |
|
607 independent of the build\-configuration, and the actual build configuration |
|
608 is not known until build\-time. Therefore, code such as |
|
609 .INDENT 0.0 |
|
610 .INDENT 3.5 |
|
611 .sp |
|
612 .nf |
|
613 .ft C |
|
614 string(TOLOWER ${CMAKE_BUILD_TYPE} _type) |
|
615 if (_type STREQUAL debug) |
|
616 target_compile_definitions(exe1 PRIVATE DEBUG_BUILD) |
|
617 endif() |
|
618 .ft P |
|
619 .fi |
|
620 .UNINDENT |
|
621 .UNINDENT |
|
622 .sp |
|
623 may appear to work for \fBMakefile\fP based and \fBNinja\fP generators, but is not |
|
624 portable to IDE generators. Additionally, the \fBIMPORTED\fP |
|
625 configuration\-mappings are not accounted for with code like this, so it should |
|
626 be avoided. |
|
627 .sp |
|
628 The unary \fBTARGET_PROPERTY\fP generator expression and the \fBTARGET_POLICY\fP |
|
629 generator expression are evaluated with the consuming target context. This |
|
630 means that a usage requirement specification may be evaluated differently based |
|
631 on the consumer: |
|
632 .INDENT 0.0 |
|
633 .INDENT 3.5 |
|
634 .sp |
|
635 .nf |
|
636 .ft C |
|
637 add_library(lib1 lib1.cpp) |
|
638 target_compile_definitions(lib1 INTERFACE |
|
639 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:LIB1_WITH_EXE> |
|
640 $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,SHARED_LIBRARY>:LIB1_WITH_SHARED_LIB> |
|
641 $<$<TARGET_POLICY:CMP0041>:CONSUMER_CMP0041_NEW> |
|
642 ) |
|
643 |
|
644 add_executable(exe1 exe1.cpp) |
|
645 target_link_libraries(exe1 lib1) |
|
646 |
|
647 cmake_policy(SET CMP0041 NEW) |
|
648 |
|
649 add_library(shared_lib shared_lib.cpp) |
|
650 target_link_libraries(shared_lib lib1) |
|
651 .ft P |
|
652 .fi |
|
653 .UNINDENT |
|
654 .UNINDENT |
|
655 .sp |
|
656 The \fBexe1\fP executable will be compiled with \fB\-DLIB1_WITH_EXE\fP, while the |
|
657 \fBshared_lib\fP shared library will be compiled with \fB\-DLIB1_WITH_SHARED_LIB\fP |
|
658 and \fB\-DCONSUMER_CMP0041_NEW\fP, because policy \fBCMP0041\fP is |
|
659 \fBNEW\fP at the point where the \fBshared_lib\fP target is created. |
|
660 .sp |
|
661 The \fBBUILD_INTERFACE\fP expression wraps requirements which are only used when |
|
662 consumed from a target in the same buildsystem, or when consumed from a target |
|
663 exported to the build directory using the \fBexport()\fP command. The |
|
664 \fBINSTALL_INTERFACE\fP expression wraps requirements which are only used when |
|
665 consumed from a target which has been installed and exported with the |
|
666 \fBinstall(EXPORT)\fP command: |
|
667 .INDENT 0.0 |
|
668 .INDENT 3.5 |
|
669 .sp |
|
670 .nf |
|
671 .ft C |
|
672 add_library(ClimbingStats climbingstats.cpp) |
|
673 target_compile_definitions(ClimbingStats INTERFACE |
|
674 $<BUILD_INTERFACE:ClimbingStats_FROM_BUILD_LOCATION> |
|
675 $<INSTALL_INTERFACE:ClimbingStats_FROM_INSTALLED_LOCATION> |
|
676 ) |
|
677 install(TARGETS ClimbingStats EXPORT libExport ${InstallArgs}) |
|
678 install(EXPORT libExport NAMESPACE Upstream:: |
|
679 DESTINATION lib/cmake/ClimbingStats) |
|
680 export(EXPORT libExport NAMESPACE Upstream::) |
|
681 |
|
682 add_executable(exe1 exe1.cpp) |
|
683 target_link_libraries(exe1 ClimbingStats) |
|
684 .ft P |
|
685 .fi |
|
686 .UNINDENT |
|
687 .UNINDENT |
|
688 .sp |
|
689 In this case, the \fBexe1\fP executable will be compiled with |
|
690 \fB\-DClimbingStats_FROM_BUILD_LOCATION\fP\&. The exporting commands generate |
|
691 \fBIMPORTED\fP targets with either the \fBINSTALL_INTERFACE\fP or the |
|
692 \fBBUILD_INTERFACE\fP omitted, and the \fB*_INTERFACE\fP marker stripped away. |
|
693 A separate project consuming the \fBClimbingStats\fP package would contain: |
|
694 .INDENT 0.0 |
|
695 .INDENT 3.5 |
|
696 .sp |
|
697 .nf |
|
698 .ft C |
|
699 find_package(ClimbingStats REQUIRED) |
|
700 |
|
701 add_executable(Downstream main.cpp) |
|
702 target_link_libraries(Downstream Upstream::ClimbingStats) |
|
703 .ft P |
|
704 .fi |
|
705 .UNINDENT |
|
706 .UNINDENT |
|
707 .sp |
|
708 Depending on whether the \fBClimbingStats\fP package was used from the build |
|
709 location or the install location, the \fBDownstream\fP target would be compiled |
|
710 with either \fB\-DClimbingStats_FROM_BUILD_LOCATION\fP or |
|
711 \fB\-DClimbingStats_FROM_INSTALL_LOCATION\fP\&. For more about packages and |
|
712 exporting see the \fBcmake\-packages(7)\fP manual. |
|
713 .SS Include Directories and Usage Requirements |
|
714 .sp |
|
715 Include directories require some special consideration when specified as usage |
|
716 requirements and when used with generator expressions. The |
|
717 \fBtarget_include_directories()\fP command accepts both relative and |
|
718 absolute include directories: |
|
719 .INDENT 0.0 |
|
720 .INDENT 3.5 |
|
721 .sp |
|
722 .nf |
|
723 .ft C |
|
724 add_library(lib1 lib1.cpp) |
|
725 target_include_directories(lib1 PRIVATE |
|
726 /absolute/path |
|
727 relative/path |
|
728 ) |
|
729 .ft P |
|
730 .fi |
|
731 .UNINDENT |
|
732 .UNINDENT |
|
733 .sp |
|
734 Relative paths are interpreted relative to the source directory where the |
|
735 command appears. Relative paths are not allowed in the |
|
736 \fBINTERFACE_INCLUDE_DIRECTORIES\fP of \fBIMPORTED\fP targets. |
|
737 .sp |
|
738 In cases where a non\-trivial generator expression is used, the |
|
739 \fBINSTALL_PREFIX\fP expression may be used within the argument of an |
|
740 \fBINSTALL_INTERFACE\fP expression. It is a replacement marker which |
|
741 expands to the installation prefix when imported by a consuming project. |
|
742 .sp |
|
743 Include directories usage requirements commonly differ between the build\-tree |
|
744 and the install\-tree. The \fBBUILD_INTERFACE\fP and \fBINSTALL_INTERFACE\fP |
|
745 generator expressions can be used to describe separate usage requirements |
|
746 based on the usage location. Relative paths are allowed within the |
|
747 \fBINSTALL_INTERFACE\fP expression and are interpreted relative to the |
|
748 installation prefix. For example: |
|
749 .INDENT 0.0 |
|
750 .INDENT 3.5 |
|
751 .sp |
|
752 .nf |
|
753 .ft C |
|
754 add_library(ClimbingStats climbingstats.cpp) |
|
755 target_include_directories(ClimbingStats INTERFACE |
|
756 $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/generated> |
|
757 $<INSTALL_INTERFACE:/absolute/path> |
|
758 $<INSTALL_INTERFACE:relative/path> |
|
759 $<INSTALL_INTERFACE:$<INSTALL_PREFIX>/$<CONFIG>/generated> |
|
760 ) |
|
761 .ft P |
|
762 .fi |
|
763 .UNINDENT |
|
764 .UNINDENT |
|
765 .sp |
|
766 Two convenience APIs are provided relating to include directories usage |
|
767 requirements. The \fBCMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE\fP variable |
|
768 may be enabled, with an equivalent effect to: |
|
769 .INDENT 0.0 |
|
770 .INDENT 3.5 |
|
771 .sp |
|
772 .nf |
|
773 .ft C |
|
774 set_property(TARGET tgt APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES |
|
775 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}> |
|
776 ) |
|
777 .ft P |
|
778 .fi |
|
779 .UNINDENT |
|
780 .UNINDENT |
|
781 .sp |
|
782 for each target affected. The convenience for installed targets is |
|
783 an \fBINCLUDES DESTINATION\fP component with the \fBinstall(TARGETS)\fP |
|
784 command: |
|
785 .INDENT 0.0 |
|
786 .INDENT 3.5 |
|
787 .sp |
|
788 .nf |
|
789 .ft C |
|
790 install(TARGETS foo bar bat EXPORT tgts ${dest_args} |
|
791 INCLUDES DESTINATION include |
|
792 ) |
|
793 install(EXPORT tgts ${other_args}) |
|
794 install(FILES ${headers} DESTINATION include) |
|
795 .ft P |
|
796 .fi |
|
797 .UNINDENT |
|
798 .UNINDENT |
|
799 .sp |
|
800 This is equivalent to appending \fB${CMAKE_INSTALL_PREFIX}/include\fP to the |
|
801 \fBINTERFACE_INCLUDE_DIRECTORIES\fP of each of the installed |
|
802 \fBIMPORTED\fP targets when generated by \fBinstall(EXPORT)\fP\&. |
|
803 .sp |
|
804 When the \fBINTERFACE_INCLUDE_DIRECTORIES\fP of an |
|
805 \fI\%imported target\fP is consumed, the entries in the |
|
806 property are treated as \fBSYSTEM\fP include directories, as if they were |
|
807 listed in the \fBINTERFACE_SYSTEM_INCLUDE_DIRECTORIES\fP of the |
|
808 dependency. This can result in omission of compiler warnings for headers |
|
809 found in those directories. This behavior for \fI\%Imported Targets\fP may |
|
810 be controlled with the \fBNO_SYSTEM_FROM_IMPORTED\fP target property. |
|
811 .sp |
|
812 If a binary target is linked transitively to a Mac OX framework, the |
|
813 \fBHeaders\fP directory of the framework is also treated as a usage requirement. |
|
814 This has the same effect as passing the framework directory as an include |
|
815 directory. |
|
816 .SS Link Libraries and Generator Expressions |
|
817 .sp |
|
818 Like build specifications, \fBlink libraries\fP may be |
|
819 specified with generator expression conditions. However, as consumption of |
|
820 usage requirements is based on collection from linked dependencies, there is |
|
821 an additional limitation that the link dependencies must form a "directed |
|
822 acyclic graph". That is, if linking to a target is dependent on the value of |
|
823 a target property, that target property may not be dependent on the linked |
|
824 dependencies: |
|
825 .INDENT 0.0 |
|
826 .INDENT 3.5 |
|
827 .sp |
|
828 .nf |
|
829 .ft C |
|
830 add_library(lib1 lib1.cpp) |
|
831 add_library(lib2 lib2.cpp) |
|
832 target_link_libraries(lib1 PUBLIC |
|
833 $<$<TARGET_PROPERTY:POSITION_INDEPENDENT_CODE>:lib2> |
|
834 ) |
|
835 add_library(lib3 lib3.cpp) |
|
836 set_property(TARGET lib3 PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) |
|
837 |
|
838 add_executable(exe1 exe1.cpp) |
|
839 target_link_libraries(exe1 lib1 lib3) |
|
840 .ft P |
|
841 .fi |
|
842 .UNINDENT |
|
843 .UNINDENT |
|
844 .sp |
|
845 As the value of the \fBPOSITION_INDEPENDENT_CODE\fP property of |
|
846 the \fBexe1\fP target is dependent on the linked libraries (\fBlib3\fP), and the |
|
847 edge of linking \fBexe1\fP is determined by the same |
|
848 \fBPOSITION_INDEPENDENT_CODE\fP property, the dependency graph above |
|
849 contains a cycle. \fBcmake(1)\fP issues a diagnostic in this case. |
|
850 .SS Output Artifacts |
|
851 .sp |
|
852 The buildsystem targets created by the \fBadd_library()\fP and |
|
853 \fBadd_executable()\fP commands create rules to create binary outputs. |
|
854 The exact output location of the binaries can only be determined at |
|
855 generate\-time because it can depend on the build\-configuration and the |
|
856 link\-language of linked dependencies etc. \fBTARGET_FILE\fP, |
|
857 \fBTARGET_LINKER_FILE\fP and related expressions can be used to access the |
|
858 name and location of generated binaries. These expressions do not work |
|
859 for \fBOBJECT\fP libraries however, as there is no single file generated |
|
860 by such libraries which is relevant to the expressions. |
|
861 .sp |
|
862 There are three kinds of output artifacts that may be build by targets |
|
863 as detailed in the following sections. Their classification differs |
|
864 between DLL platforms and non\-DLL platforms. All Windows\-based |
|
865 systems including Cygwin are DLL platforms. |
|
866 .SS Runtime Output Artifacts |
|
867 .sp |
|
868 A \fIruntime\fP output artifact of a buildsystem target may be: |
|
869 .INDENT 0.0 |
|
870 .IP \(bu 2 |
|
871 The executable file (e.g. \fB\&.exe\fP) of an executable target |
|
872 created by the \fBadd_executable()\fP command. |
|
873 .IP \(bu 2 |
|
874 On DLL platforms: the executable file (e.g. \fB\&.dll\fP) of a shared |
|
875 library target created by the \fBadd_library()\fP command |
|
876 with the \fBSHARED\fP option. |
|
877 .UNINDENT |
|
878 .sp |
|
879 The \fBRUNTIME_OUTPUT_DIRECTORY\fP and \fBRUNTIME_OUTPUT_NAME\fP |
|
880 target properties may be used to control runtime output artifact locations |
|
881 and names in the build tree. |
|
882 .SS Library Output Artifacts |
|
883 .sp |
|
884 A \fIlibrary\fP output artifact of a buildsystem target may be: |
|
885 .INDENT 0.0 |
|
886 .IP \(bu 2 |
|
887 The loadable module file (e.g. \fB\&.dll\fP or \fB\&.so\fP) of a module |
|
888 library target created by the \fBadd_library()\fP command |
|
889 with the \fBMODULE\fP option. |
|
890 .IP \(bu 2 |
|
891 On non\-DLL platforms: the shared library file (e.g. \fB\&.so\fP or \fB\&.dylib\fP) |
|
892 of a shared shared library target created by the \fBadd_library()\fP |
|
893 command with the \fBSHARED\fP option. |
|
894 .UNINDENT |
|
895 .sp |
|
896 The \fBLIBRARY_OUTPUT_DIRECTORY\fP and \fBLIBRARY_OUTPUT_NAME\fP |
|
897 target properties may be used to control library output artifact locations |
|
898 and names in the build tree. |
|
899 .SS Archive Output Artifacts |
|
900 .sp |
|
901 An \fIarchive\fP output artifact of a buildsystem target may be: |
|
902 .INDENT 0.0 |
|
903 .IP \(bu 2 |
|
904 The static library file (e.g. \fB\&.lib\fP or \fB\&.a\fP) of a static |
|
905 library target created by the \fBadd_library()\fP command |
|
906 with the \fBSTATIC\fP option. |
|
907 .IP \(bu 2 |
|
908 On DLL platforms: the import library file (e.g. \fB\&.lib\fP) of a shared |
|
909 library target created by the \fBadd_library()\fP command |
|
910 with the \fBSHARED\fP option. |
|
911 .IP \(bu 2 |
|
912 On DLL platforms: the import library file (e.g. \fB\&.lib\fP) of an |
|
913 executable target created by the \fBadd_executable()\fP command |
|
914 when its \fBENABLE_EXPORTS\fP target property is set. |
|
915 .UNINDENT |
|
916 .sp |
|
917 The \fBARCHIVE_OUTPUT_DIRECTORY\fP and \fBARCHIVE_OUTPUT_NAME\fP |
|
918 target properties may be used to control archive output artifact locations |
|
919 and names in the build tree. |
|
920 .SS Directory\-Scoped Commands |
|
921 .sp |
|
922 The \fBtarget_include_directories()\fP, |
|
923 \fBtarget_compile_definitions()\fP and |
|
924 \fBtarget_compile_options()\fP commands have an effect on only one |
|
925 target at a time. The commands \fBadd_definitions()\fP, |
|
926 \fBadd_compile_options()\fP and \fBinclude_directories()\fP have |
|
927 a similar function, but operate at directory scope instead of target |
|
928 scope for convenience. |
|
929 .SH PSEUDO TARGETS |
|
930 .sp |
|
931 Some target types do not represent outputs of the buildsystem, but only inputs |
|
932 such as external dependencies, aliases or other non\-build artifacts. Pseudo |
|
933 targets are not represented in the generated buildsystem. |
|
934 .SS Imported Targets |
|
935 .sp |
|
936 An \fBIMPORTED\fP target represents a pre\-existing dependency. Usually |
|
937 such targets are defined by an upstream package and should be treated as |
|
938 immutable. It is not possible to use an \fBIMPORTED\fP target in the |
|
939 left\-hand\-side of the \fBtarget_compile_definitions()\fP, |
|
940 \fBtarget_include_directories()\fP, \fBtarget_compile_options()\fP or |
|
941 \fBtarget_link_libraries()\fP commands, as that would be an attempt to |
|
942 modify it. \fBIMPORTED\fP targets are designed to be used only in the |
|
943 right\-hand\-side of those commands. |
|
944 .sp |
|
945 \fBIMPORTED\fP targets may have the same usage requirement properties |
|
946 populated as binary targets, such as |
|
947 \fBINTERFACE_INCLUDE_DIRECTORIES\fP, |
|
948 \fBINTERFACE_COMPILE_DEFINITIONS\fP, |
|
949 \fBINTERFACE_COMPILE_OPTIONS\fP, |
|
950 \fBINTERFACE_LINK_LIBRARIES\fP, and |
|
951 \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP\&. |
|
952 .sp |
|
953 The \fBLOCATION\fP may also be read from an IMPORTED target, though there |
|
954 is rarely reason to do so. Commands such as \fBadd_custom_command()\fP can |
|
955 transparently use an \fBIMPORTED\fP \fBEXECUTABLE\fP target |
|
956 as a \fBCOMMAND\fP executable. |
|
957 .sp |
|
958 The scope of the definition of an \fBIMPORTED\fP target is the directory |
|
959 where it was defined. It may be accessed and used from subdirectories, but |
|
960 not from parent directories or sibling directories. The scope is similar to |
|
961 the scope of a cmake variable. |
|
962 .sp |
|
963 It is also possible to define a \fBGLOBAL\fP \fBIMPORTED\fP target which is |
|
964 accessible globally in the buildsystem. |
|
965 .sp |
|
966 See the \fBcmake\-packages(7)\fP manual for more on creating packages |
|
967 with \fBIMPORTED\fP targets. |
|
968 .SS Alias Targets |
|
969 .sp |
|
970 An \fBALIAS\fP target is a name which may be used interchangably with |
|
971 a binary target name in read\-only contexts. A primary use\-case for \fBALIAS\fP |
|
972 targets is for example or unit test executables accompanying a library, which |
|
973 may be part of the same buildsystem or built separately based on user |
|
974 configuration. |
|
975 .INDENT 0.0 |
|
976 .INDENT 3.5 |
|
977 .sp |
|
978 .nf |
|
979 .ft C |
|
980 add_library(lib1 lib1.cpp) |
|
981 install(TARGETS lib1 EXPORT lib1Export ${dest_args}) |
|
982 install(EXPORT lib1Export NAMESPACE Upstream:: ${other_args}) |
|
983 |
|
984 add_library(Upstream::lib1 ALIAS lib1) |
|
985 .ft P |
|
986 .fi |
|
987 .UNINDENT |
|
988 .UNINDENT |
|
989 .sp |
|
990 In another directory, we can link unconditionally to the \fBUpstream::lib1\fP |
|
991 target, which may be an \fBIMPORTED\fP target from a package, or an |
|
992 \fBALIAS\fP target if built as part of the same buildsystem. |
|
993 .INDENT 0.0 |
|
994 .INDENT 3.5 |
|
995 .sp |
|
996 .nf |
|
997 .ft C |
|
998 if (NOT TARGET Upstream::lib1) |
|
999 find_package(lib1 REQUIRED) |
|
1000 endif() |
|
1001 add_executable(exe1 exe1.cpp) |
|
1002 target_link_libraries(exe1 Upstream::lib1) |
|
1003 .ft P |
|
1004 .fi |
|
1005 .UNINDENT |
|
1006 .UNINDENT |
|
1007 .sp |
|
1008 \fBALIAS\fP targets are not mutable, installable or exportable. They are |
|
1009 entirely local to the buildsystem description. A name can be tested for |
|
1010 whether it is an \fBALIAS\fP name by reading the \fBALIASED_TARGET\fP |
|
1011 property from it: |
|
1012 .INDENT 0.0 |
|
1013 .INDENT 3.5 |
|
1014 .sp |
|
1015 .nf |
|
1016 .ft C |
|
1017 get_target_property(_aliased Upstream::lib1 ALIASED_TARGET) |
|
1018 if(_aliased) |
|
1019 message(STATUS "The name Upstream::lib1 is an ALIAS for ${_aliased}.") |
|
1020 endif() |
|
1021 .ft P |
|
1022 .fi |
|
1023 .UNINDENT |
|
1024 .UNINDENT |
|
1025 .SS Interface Libraries |
|
1026 .sp |
|
1027 An \fBINTERFACE\fP target has no \fBLOCATION\fP and is mutable, but is |
|
1028 otherwise similar to an \fBIMPORTED\fP target. |
|
1029 .sp |
|
1030 It may specify usage requirements such as |
|
1031 \fBINTERFACE_INCLUDE_DIRECTORIES\fP, |
|
1032 \fBINTERFACE_COMPILE_DEFINITIONS\fP, |
|
1033 \fBINTERFACE_COMPILE_OPTIONS\fP, |
|
1034 \fBINTERFACE_LINK_LIBRARIES\fP, |
|
1035 \fBINTERFACE_SOURCES\fP, |
|
1036 and \fBINTERFACE_POSITION_INDEPENDENT_CODE\fP\&. |
|
1037 Only the \fBINTERFACE\fP modes of the \fBtarget_include_directories()\fP, |
|
1038 \fBtarget_compile_definitions()\fP, \fBtarget_compile_options()\fP, |
|
1039 \fBtarget_sources()\fP, and \fBtarget_link_libraries()\fP commands |
|
1040 may be used with \fBINTERFACE\fP libraries. |
|
1041 .sp |
|
1042 A primary use\-case for \fBINTERFACE\fP libraries is header\-only libraries. |
|
1043 .INDENT 0.0 |
|
1044 .INDENT 3.5 |
|
1045 .sp |
|
1046 .nf |
|
1047 .ft C |
|
1048 add_library(Eigen INTERFACE) |
|
1049 target_include_directories(Eigen INTERFACE |
|
1050 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> |
|
1051 $<INSTALL_INTERFACE:include/Eigen> |
|
1052 ) |
|
1053 |
|
1054 add_executable(exe1 exe1.cpp) |
|
1055 target_link_libraries(exe1 Eigen) |
|
1056 .ft P |
|
1057 .fi |
|
1058 .UNINDENT |
|
1059 .UNINDENT |
|
1060 .sp |
|
1061 Here, the usage requirements from the \fBEigen\fP target are consumed and used |
|
1062 when compiling, but it has no effect on linking. |
|
1063 .sp |
|
1064 Another use\-case is to employ an entirely target\-focussed design for usage |
|
1065 requirements: |
|
1066 .INDENT 0.0 |
|
1067 .INDENT 3.5 |
|
1068 .sp |
|
1069 .nf |
|
1070 .ft C |
|
1071 add_library(pic_on INTERFACE) |
|
1072 set_property(TARGET pic_on PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE ON) |
|
1073 add_library(pic_off INTERFACE) |
|
1074 set_property(TARGET pic_off PROPERTY INTERFACE_POSITION_INDEPENDENT_CODE OFF) |
|
1075 |
|
1076 add_library(enable_rtti INTERFACE) |
|
1077 target_compile_options(enable_rtti INTERFACE |
|
1078 $<$<OR:$<COMPILER_ID:GNU>,$<COMPILER_ID:Clang>>:\-rtti> |
|
1079 ) |
|
1080 |
|
1081 add_executable(exe1 exe1.cpp) |
|
1082 target_link_libraries(exe1 pic_on enable_rtti) |
|
1083 .ft P |
|
1084 .fi |
|
1085 .UNINDENT |
|
1086 .UNINDENT |
|
1087 .sp |
|
1088 This way, the build specification of \fBexe1\fP is expressed entirely as linked |
|
1089 targets, and the complexity of compiler\-specific flags is encapsulated in an |
|
1090 \fBINTERFACE\fP library target. |
|
1091 .sp |
|
1092 The properties permitted to be set on or read from an \fBINTERFACE\fP library |
|
1093 are: |
|
1094 .INDENT 0.0 |
|
1095 .IP \(bu 2 |
|
1096 Properties matching \fBINTERFACE_*\fP |
|
1097 .IP \(bu 2 |
|
1098 Built\-in properties matching \fBCOMPATIBLE_INTERFACE_*\fP |
|
1099 .IP \(bu 2 |
|
1100 \fBEXPORT_NAME\fP |
|
1101 .IP \(bu 2 |
|
1102 \fBIMPORTED\fP |
|
1103 .IP \(bu 2 |
|
1104 \fBNAME\fP |
|
1105 .IP \(bu 2 |
|
1106 Properties matching \fBMAP_IMPORTED_CONFIG_*\fP |
|
1107 .UNINDENT |
|
1108 .sp |
|
1109 \fBINTERFACE\fP libraries may be installed and exported. Any content they refer |
|
1110 to must be installed separately: |
|
1111 .INDENT 0.0 |
|
1112 .INDENT 3.5 |
|
1113 .sp |
|
1114 .nf |
|
1115 .ft C |
|
1116 add_library(Eigen INTERFACE) |
|
1117 target_include_directories(Eigen INTERFACE |
|
1118 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src> |
|
1119 $<INSTALL_INTERFACE:include/Eigen> |
|
1120 ) |
|
1121 |
|
1122 install(TARGETS Eigen EXPORT eigenExport) |
|
1123 install(EXPORT eigenExport NAMESPACE Upstream:: |
|
1124 DESTINATION lib/cmake/Eigen |
|
1125 ) |
|
1126 install(FILES |
|
1127 ${CMAKE_CURRENT_SOURCE_DIR}/src/eigen.h |
|
1128 ${CMAKE_CURRENT_SOURCE_DIR}/src/vector.h |
|
1129 ${CMAKE_CURRENT_SOURCE_DIR}/src/matrix.h |
|
1130 DESTINATION include/Eigen |
|
1131 ) |
|
1132 .ft P |
|
1133 .fi |
|
1134 .UNINDENT |
|
1135 .UNINDENT |
|
1136 .SH COPYRIGHT |
|
1137 2000-2015 Kitware, Inc. |
|
1138 .\" Generated by docutils manpage writer. |
|
1139 . |