|
1 .\" Man page generated from reStructuredText. |
|
2 . |
|
3 .TH "CMAKE-DEVELOPER" "7" "October 14, 2015" "3.3.2" "CMake" |
|
4 .SH NAME |
|
5 cmake-developer \- CMake Developer 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 This manual is intended for reference by developers modifying the CMake |
|
36 source tree itself. |
|
37 .SH PERMITTED C++ SUBSET |
|
38 .sp |
|
39 CMake is required to build with ancient C++ compilers and standard library |
|
40 implementations. Some common C++ constructs may not be used in CMake in order |
|
41 to build with such toolchains. |
|
42 .SS std::auto_ptr |
|
43 .sp |
|
44 Some implementations have a \fBstd::auto_ptr\fP which can not be used as a |
|
45 return value from a function. \fBstd::auto_ptr\fP may not be used. Use |
|
46 \fBcmsys::auto_ptr\fP instead. |
|
47 .SS size_t |
|
48 .sp |
|
49 Various implementations have differing implementation of \fBsize_t\fP\&. When |
|
50 assigning the result of \fB\&.size()\fP on a container for example, the result |
|
51 should be assigned to \fBsize_t\fP not to \fBstd::size_t\fP, \fBunsigned int\fP or |
|
52 similar types. |
|
53 .SH ADDING COMPILE FEATURES |
|
54 .sp |
|
55 CMake reports an error if a compiler whose features are known does not report |
|
56 support for a particular requested feature. A compiler is considered to have |
|
57 known features if it reports support for at least one feature. |
|
58 .sp |
|
59 When adding a new compile feature to CMake, it is therefore necessary to list |
|
60 support for the feature for all CompilerIds which already have one or more |
|
61 feature supported, if the new feature is available for any version of the |
|
62 compiler. |
|
63 .sp |
|
64 When adding the first supported feature to a particular CompilerId, it is |
|
65 necessary to list support for all features known to cmake (See |
|
66 \fBCMAKE_C_COMPILE_FEATURES\fP and |
|
67 \fBCMAKE_CXX_COMPILE_FEATURES\fP as appropriate), where available for |
|
68 the compiler. Furthermore, set \fBCMAKE_<LANG>_STANDARD_DEFAULT\fP to the |
|
69 default language standard level the compiler uses, or to the empty string |
|
70 if the compiler has no notion of standard levels (such as \fBMSVC\fP). |
|
71 .sp |
|
72 It is sensible to record the features for the most recent version of a |
|
73 particular CompilerId first, and then work backwards. It is sensible to |
|
74 try to create a continuous range of versions of feature releases of the |
|
75 compiler. Gaps in the range indicate incorrect features recorded for |
|
76 intermediate releases. |
|
77 .sp |
|
78 Generally, features are made available for a particular version if the |
|
79 compiler vendor documents availability of the feature with that |
|
80 version. Note that sometimes partially implemented features appear to |
|
81 be functional in previous releases (such as \fBcxx_constexpr\fP in GNU 4.6, |
|
82 though availability is documented in GNU 4.7), and sometimes compiler vendors |
|
83 document availability of features, though supporting infrastructure is |
|
84 not available (such as \fB__has_feature(cxx_generic_lambdas)\fP indicating |
|
85 non\-availability in Clang 3.4, though it is documented as available, and |
|
86 fixed in Clang 3.5). Similar cases for other compilers and versions |
|
87 need to be investigated when extending CMake to support them. |
|
88 .sp |
|
89 When a vendor releases a new version of a known compiler which supports |
|
90 a previously unsupported feature, and there are already known features for |
|
91 that compiler, the feature should be listed as supported in CMake for |
|
92 that version of the compiler as soon as reasonably possible. |
|
93 .sp |
|
94 Standard\-specific/compiler\-specific variables such |
|
95 \fBCMAKE_CXX98_COMPILE_FEATURES\fP are deliberately not documented. They |
|
96 only exist for the compiler\-specific implementation of adding the \fB\-std\fP |
|
97 compile flag for compilers which need that. |
|
98 .SH HELP |
|
99 .sp |
|
100 The \fBHelp\fP directory contains CMake help manual source files. |
|
101 They are written using the \fI\%reStructuredText\fP markup syntax and |
|
102 processed by \fI\%Sphinx\fP to generate the CMake help manuals. |
|
103 .SS Markup Constructs |
|
104 .sp |
|
105 In addition to using Sphinx to generate the CMake help manuals, we |
|
106 also use a C++\-implemented document processor to print documents for |
|
107 the \fB\-\-help\-*\fP command\-line help options. It supports a subset of |
|
108 reStructuredText markup. When authoring or modifying documents, |
|
109 please verify that the command\-line help looks good in addition to the |
|
110 Sphinx\-generated html and man pages. |
|
111 .sp |
|
112 The command\-line help processor supports the following constructs |
|
113 defined by reStructuredText, Sphinx, and a CMake extension to Sphinx. |
|
114 .INDENT 0.0 |
|
115 .TP |
|
116 .B CMake Domain directives |
|
117 Directives defined in the \fI\%CMake Domain\fP for defining CMake |
|
118 documentation objects are printed in command\-line help output as |
|
119 if the lines were normal paragraph text with interpretation. |
|
120 .TP |
|
121 .B CMake Domain interpreted text roles |
|
122 Interpreted text roles defined in the \fI\%CMake Domain\fP for |
|
123 cross\-referencing CMake documentation objects are replaced by their |
|
124 link text in command\-line help output. Other roles are printed |
|
125 literally and not processed. |
|
126 .TP |
|
127 .B \fBcode\-block\fP directive |
|
128 Add a literal code block without interpretation. The command\-line |
|
129 help processor prints the block content without the leading directive |
|
130 line and with common indentation replaced by one space. |
|
131 .TP |
|
132 .B \fBinclude\fP directive |
|
133 Include another document source file. The command\-line help |
|
134 processor prints the included document inline with the referencing |
|
135 document. |
|
136 .TP |
|
137 .B literal block after \fB::\fP |
|
138 A paragraph ending in \fB::\fP followed by a blank line treats |
|
139 the following indented block as literal text without interpretation. |
|
140 The command\-line help processor prints the \fB::\fP literally and |
|
141 prints the block content with common indentation replaced by one |
|
142 space. |
|
143 .TP |
|
144 .B \fBnote\fP directive |
|
145 Call out a side note. The command\-line help processor prints the |
|
146 block content as if the lines were normal paragraph text with |
|
147 interpretation. |
|
148 .TP |
|
149 .B \fBparsed\-literal\fP directive |
|
150 Add a literal block with markup interpretation. The command\-line |
|
151 help processor prints the block content without the leading |
|
152 directive line and with common indentation replaced by one space. |
|
153 .TP |
|
154 .B \fBproductionlist\fP directive |
|
155 Render context\-free grammar productions. The command\-line help |
|
156 processor prints the block content as if the lines were normal |
|
157 paragraph text with interpretation. |
|
158 .TP |
|
159 .B \fBreplace\fP directive |
|
160 Define a \fB|substitution|\fP replacement. |
|
161 The command\-line help processor requires a substitution replacement |
|
162 to be defined before it is referenced. |
|
163 .TP |
|
164 .B \fB|substitution|\fP reference |
|
165 Reference a substitution replacement previously defined by |
|
166 the \fBreplace\fP directive. The command\-line help processor |
|
167 performs the substitution and replaces all newlines in the |
|
168 replacement text with spaces. |
|
169 .TP |
|
170 .B \fBtoctree\fP directive |
|
171 Include other document sources in the Table\-of\-Contents |
|
172 document tree. The command\-line help processor prints |
|
173 the referenced documents inline as part of the referencing |
|
174 document. |
|
175 .UNINDENT |
|
176 .sp |
|
177 Inline markup constructs not listed above are printed literally in the |
|
178 command\-line help output. We prefer to use inline markup constructs that |
|
179 look correct in source form, so avoid use of \e\-escapes in favor of inline |
|
180 literals when possible. |
|
181 .sp |
|
182 Explicit markup blocks not matching directives listed above are removed from |
|
183 command\-line help output. Do not use them, except for plain \fB\&..\fP comments |
|
184 that are removed by Sphinx too. |
|
185 .sp |
|
186 Note that nested indentation of blocks is not recognized by the |
|
187 command\-line help processor. Therefore: |
|
188 .INDENT 0.0 |
|
189 .IP \(bu 2 |
|
190 Explicit markup blocks are recognized only when not indented |
|
191 inside other blocks. |
|
192 .IP \(bu 2 |
|
193 Literal blocks after paragraphs ending in \fB::\fP but not |
|
194 at the top indentation level may consume all indented lines |
|
195 following them. |
|
196 .UNINDENT |
|
197 .sp |
|
198 Try to avoid these cases in practice. |
|
199 .SS CMake Domain |
|
200 .sp |
|
201 CMake adds a \fI\%Sphinx Domain\fP called \fBcmake\fP, also called the |
|
202 "CMake Domain". It defines several "object" types for CMake |
|
203 documentation: |
|
204 .INDENT 0.0 |
|
205 .TP |
|
206 .B \fBcommand\fP |
|
207 A CMake language command. |
|
208 .TP |
|
209 .B \fBgenerator\fP |
|
210 A CMake native build system generator. |
|
211 See the \fBcmake(1)\fP command\-line tool\(aqs \fB\-G\fP option. |
|
212 .TP |
|
213 .B \fBmanual\fP |
|
214 A CMake manual page, like this \fI\%cmake\-developer(7)\fP manual. |
|
215 .TP |
|
216 .B \fBmodule\fP |
|
217 A CMake module. |
|
218 See the \fBcmake\-modules(7)\fP manual |
|
219 and the \fBinclude()\fP command. |
|
220 .TP |
|
221 .B \fBpolicy\fP |
|
222 A CMake policy. |
|
223 See the \fBcmake\-policies(7)\fP manual |
|
224 and the \fBcmake_policy()\fP command. |
|
225 .TP |
|
226 .B \fBprop_cache, prop_dir, prop_gbl, prop_sf, prop_inst, prop_test, prop_tgt\fP |
|
227 A CMake cache, directory, global, source file, installed file, test, |
|
228 or target property, respectively. See the \fBcmake\-properties(7)\fP |
|
229 manual and the \fBset_property()\fP command. |
|
230 .TP |
|
231 .B \fBvariable\fP |
|
232 A CMake language variable. |
|
233 See the \fBcmake\-variables(7)\fP manual |
|
234 and the \fBset()\fP command. |
|
235 .UNINDENT |
|
236 .sp |
|
237 Documentation objects in the CMake Domain come from two sources. |
|
238 First, the CMake extension to Sphinx transforms every document named |
|
239 with the form \fBHelp/<type>/<file\-name>.rst\fP to a domain object with |
|
240 type \fB<type>\fP\&. The object name is extracted from the document title, |
|
241 which is expected to be of the form: |
|
242 .INDENT 0.0 |
|
243 .INDENT 3.5 |
|
244 .sp |
|
245 .nf |
|
246 .ft C |
|
247 <object\-name> |
|
248 \-\-\-\-\-\-\-\-\-\-\-\-\- |
|
249 .ft P |
|
250 .fi |
|
251 .UNINDENT |
|
252 .UNINDENT |
|
253 .sp |
|
254 and to appear at or near the top of the \fB\&.rst\fP file before any other |
|
255 lines starting in a letter, digit, or \fB<\fP\&. If no such title appears |
|
256 literally in the \fB\&.rst\fP file, the object name is the \fB<file\-name>\fP\&. |
|
257 If a title does appear, it is expected that \fB<file\-name>\fP is equal |
|
258 to \fB<object\-name>\fP with any \fB<\fP and \fB>\fP characters removed. |
|
259 .sp |
|
260 Second, the CMake Domain provides directives to define objects inside |
|
261 other documents: |
|
262 .INDENT 0.0 |
|
263 .INDENT 3.5 |
|
264 .sp |
|
265 .nf |
|
266 .ft C |
|
267 \&.. command:: <command\-name> |
|
268 |
|
269 This indented block documents <command\-name>. |
|
270 |
|
271 \&.. variable:: <variable\-name> |
|
272 |
|
273 This indented block documents <variable\-name>. |
|
274 .ft P |
|
275 .fi |
|
276 .UNINDENT |
|
277 .UNINDENT |
|
278 .sp |
|
279 Object types for which no directive is available must be defined using |
|
280 the first approach above. |
|
281 .SS Cross\-References |
|
282 .sp |
|
283 Sphinx uses reStructuredText interpreted text roles to provide |
|
284 cross\-reference syntax. The \fI\%CMake Domain\fP provides for each |
|
285 domain object type a role of the same name to cross\-reference it. |
|
286 CMake Domain roles are inline markup of the forms: |
|
287 .INDENT 0.0 |
|
288 .INDENT 3.5 |
|
289 .sp |
|
290 .nf |
|
291 .ft C |
|
292 :type:\(ganame\(ga |
|
293 :type:\(gatext <name>\(ga |
|
294 .ft P |
|
295 .fi |
|
296 .UNINDENT |
|
297 .UNINDENT |
|
298 .sp |
|
299 where \fBtype\fP is the domain object type and \fBname\fP is the |
|
300 domain object name. In the first form the link text will be |
|
301 \fBname\fP (or \fBname()\fP if the type is \fBcommand\fP) and in |
|
302 the second form the link text will be the explicit \fBtext\fP\&. |
|
303 For example, the code: |
|
304 .INDENT 0.0 |
|
305 .INDENT 3.5 |
|
306 .sp |
|
307 .nf |
|
308 .ft C |
|
309 * The :command:\(galist\(ga command. |
|
310 * The :command:\(galist(APPEND)\(ga sub\-command. |
|
311 * The :command:\(galist() command <list>\(ga. |
|
312 * The :command:\(galist(APPEND) sub\-command <list>\(ga. |
|
313 * The :variable:\(gaCMAKE_VERSION\(ga variable. |
|
314 * The :prop_tgt:\(gaOUTPUT_NAME_<CONFIG>\(ga target property. |
|
315 .ft P |
|
316 .fi |
|
317 .UNINDENT |
|
318 .UNINDENT |
|
319 .sp |
|
320 produces: |
|
321 .INDENT 0.0 |
|
322 .IP \(bu 2 |
|
323 The \fBlist()\fP command. |
|
324 .IP \(bu 2 |
|
325 The \fBlist(APPEND)\fP sub\-command. |
|
326 .IP \(bu 2 |
|
327 The \fBlist() command\fP\&. |
|
328 .IP \(bu 2 |
|
329 The \fBlist(APPEND) sub\-command\fP\&. |
|
330 .IP \(bu 2 |
|
331 The \fBCMAKE_VERSION\fP variable. |
|
332 .IP \(bu 2 |
|
333 The \fBOUTPUT_NAME_<CONFIG>\fP target property. |
|
334 .UNINDENT |
|
335 .sp |
|
336 Note that CMake Domain roles differ from Sphinx and reStructuredText |
|
337 convention in that the form \fBa<b>\fP, without a space preceding \fB<\fP, |
|
338 is interpreted as a name instead of link text with an explicit target. |
|
339 This is necessary because we use \fB<placeholders>\fP frequently in |
|
340 object names like \fBOUTPUT_NAME_<CONFIG>\fP\&. The form \fBa <b>\fP, |
|
341 with a space preceding \fB<\fP, is still interpreted as a link text |
|
342 with an explicit target. |
|
343 .SS Style |
|
344 .SS Style: Section Headers |
|
345 .sp |
|
346 When marking section titles, make the section decoration line as long as |
|
347 the title text. Use only a line below the title, not above. For |
|
348 example: |
|
349 .INDENT 0.0 |
|
350 .INDENT 3.5 |
|
351 .sp |
|
352 .nf |
|
353 .ft C |
|
354 Title Text |
|
355 \-\-\-\-\-\-\-\-\-\- |
|
356 .ft P |
|
357 .fi |
|
358 .UNINDENT |
|
359 .UNINDENT |
|
360 .sp |
|
361 Capitalize the first letter of each non\-minor word in the title. |
|
362 .sp |
|
363 The section header underline character hierarchy is |
|
364 .INDENT 0.0 |
|
365 .IP \(bu 2 |
|
366 \fB#\fP: Manual group (part) in the master document |
|
367 .IP \(bu 2 |
|
368 \fB*\fP: Manual (chapter) title |
|
369 .IP \(bu 2 |
|
370 \fB=\fP: Section within a manual |
|
371 .IP \(bu 2 |
|
372 \fB\-\fP: Subsection or \fI\%CMake Domain\fP object document title |
|
373 .IP \(bu 2 |
|
374 \fB^\fP: Subsubsection or \fI\%CMake Domain\fP object document section |
|
375 .IP \(bu 2 |
|
376 \fB"\fP: Paragraph or \fI\%CMake Domain\fP object document subsection |
|
377 .UNINDENT |
|
378 .SS Style: Whitespace |
|
379 .sp |
|
380 Use two spaces for indentation. Use two spaces between sentences in |
|
381 prose. |
|
382 .SS Style: Line Length |
|
383 .sp |
|
384 Prefer to restrict the width of lines to 75\-80 columns. This is not a |
|
385 hard restriction, but writing new paragraphs wrapped at 75 columns |
|
386 allows space for adding minor content without significant re\-wrapping of |
|
387 content. |
|
388 .SS Style: Prose |
|
389 .sp |
|
390 Use American English spellings in prose. |
|
391 .SS Style: Starting Literal Blocks |
|
392 .sp |
|
393 Prefer to mark the start of literal blocks with \fB::\fP at the end of |
|
394 the preceding paragraph. In cases where the following block gets |
|
395 a \fBcode\-block\fP marker, put a single \fB:\fP at the end of the preceding |
|
396 paragraph. |
|
397 .SS Style: CMake Command Signatures |
|
398 .sp |
|
399 Command signatures should be marked up as plain literal blocks, not as |
|
400 cmake \fBcode\-blocks\fP\&. |
|
401 .sp |
|
402 Signatures are separated from preceding content by a section header. |
|
403 That is, use: |
|
404 .INDENT 0.0 |
|
405 .INDENT 3.5 |
|
406 .sp |
|
407 .nf |
|
408 .ft C |
|
409 \&... preceding paragraph. |
|
410 |
|
411 Normal Libraries |
|
412 ^^^^^^^^^^^^^^^^ |
|
413 |
|
414 :: |
|
415 |
|
416 add_library(<lib> ...) |
|
417 |
|
418 This signature is used for ... |
|
419 .ft P |
|
420 .fi |
|
421 .UNINDENT |
|
422 .UNINDENT |
|
423 .sp |
|
424 Signatures of commands should wrap optional parts with square brackets, |
|
425 and should mark list of optional arguments with an ellipsis (\fB\&...\fP). |
|
426 Elements of the signature which are specified by the user should be |
|
427 specified with angle brackets, and may be referred to in prose using |
|
428 \fBinline\-literal\fP syntax. |
|
429 .SS Style: Boolean Constants |
|
430 .sp |
|
431 Use "\fBOFF\fP" and "\fBON\fP" for boolean values which can be modified by |
|
432 the user, such as \fBPOSITION_INDEPENDENT_CODE\fP\&. Such properties |
|
433 may be "enabled" and "disabled". Use "\fBTrue\fP" and "\fBFalse\fP" for |
|
434 inherent values which can\(aqt be modified after being set, such as the |
|
435 \fBIMPORTED\fP property of a build target. |
|
436 .SS Style: Inline Literals |
|
437 .sp |
|
438 Mark up references to keywords in signatures, file names, and other |
|
439 technical terms with \fBinline\-literal\fP syntax, for example: |
|
440 .INDENT 0.0 |
|
441 .INDENT 3.5 |
|
442 .sp |
|
443 .nf |
|
444 .ft C |
|
445 If \(ga\(gaWIN32\(ga\(ga is used with :command:\(gaadd_executable\(ga, the |
|
446 :prop_tgt:\(gaWIN32_EXECUTABLE\(ga target property is enabled. That command |
|
447 creates the file \(ga\(ga<name>.exe\(ga\(ga on Windows. |
|
448 .ft P |
|
449 .fi |
|
450 .UNINDENT |
|
451 .UNINDENT |
|
452 .SS Style: Cross\-References |
|
453 .sp |
|
454 Mark up linkable references as links, including repeats. |
|
455 An alternative, which is used by wikipedia |
|
456 (\fI\%http://en.wikipedia.org/wiki/WP:REPEATLINK\fP), |
|
457 is to link to a reference only once per article. That style is not used |
|
458 in CMake documentation. |
|
459 .SS Style: Referencing CMake Concepts |
|
460 .sp |
|
461 If referring to a concept which corresponds to a property, and that |
|
462 concept is described in a high\-level manual, prefer to link to the |
|
463 manual section instead of the property. For example: |
|
464 .INDENT 0.0 |
|
465 .INDENT 3.5 |
|
466 .sp |
|
467 .nf |
|
468 .ft C |
|
469 This command creates an :ref:\(gaImported Target <Imported Targets>\(ga. |
|
470 .ft P |
|
471 .fi |
|
472 .UNINDENT |
|
473 .UNINDENT |
|
474 .sp |
|
475 instead of: |
|
476 .INDENT 0.0 |
|
477 .INDENT 3.5 |
|
478 .sp |
|
479 .nf |
|
480 .ft C |
|
481 This command creates an :prop_tgt:\(gaIMPORTED\(ga target. |
|
482 .ft P |
|
483 .fi |
|
484 .UNINDENT |
|
485 .UNINDENT |
|
486 .sp |
|
487 The latter should be used only when referring specifically to the |
|
488 property. |
|
489 .sp |
|
490 References to manual sections are not automatically created by creating |
|
491 a section, but code such as: |
|
492 .INDENT 0.0 |
|
493 .INDENT 3.5 |
|
494 .sp |
|
495 .nf |
|
496 .ft C |
|
497 \&.. _\(gaImported Targets\(ga: |
|
498 .ft P |
|
499 .fi |
|
500 .UNINDENT |
|
501 .UNINDENT |
|
502 .sp |
|
503 creates a suitable anchor. Use an anchor name which matches the name |
|
504 of the corresponding section. Refer to the anchor using a |
|
505 cross\-reference with specified text. |
|
506 .sp |
|
507 Imported Targets need the \fBIMPORTED\fP term marked up with care in |
|
508 particular because the term may refer to a command keyword |
|
509 (\fBIMPORTED\fP), a target property (\fBIMPORTED\fP), or a |
|
510 concept (Imported Targets). |
|
511 .sp |
|
512 Where a property, command or variable is related conceptually to others, |
|
513 by for example, being related to the buildsystem description, generator |
|
514 expressions or Qt, each relevant property, command or variable should |
|
515 link to the primary manual, which provides high\-level information. Only |
|
516 particular information relating to the command should be in the |
|
517 documentation of the command. |
|
518 .SS Style: Referencing CMake Domain Objects |
|
519 .sp |
|
520 When referring to \fI\%CMake Domain\fP objects such as properties, variables, |
|
521 commands etc, prefer to link to the target object and follow that with |
|
522 the type of object it is. For example: |
|
523 .INDENT 0.0 |
|
524 .INDENT 3.5 |
|
525 .sp |
|
526 .nf |
|
527 .ft C |
|
528 Set the :prop_tgt:\(gaAUTOMOC\(ga target property to \(ga\(gaON\(ga\(ga. |
|
529 .ft P |
|
530 .fi |
|
531 .UNINDENT |
|
532 .UNINDENT |
|
533 .sp |
|
534 Instead of |
|
535 .INDENT 0.0 |
|
536 .INDENT 3.5 |
|
537 .sp |
|
538 .nf |
|
539 .ft C |
|
540 Set the target property :prop_tgt:\(gaAUTOMOC\(ga to \(ga\(gaON\(ga\(ga. |
|
541 .ft P |
|
542 .fi |
|
543 .UNINDENT |
|
544 .UNINDENT |
|
545 .sp |
|
546 The \fBpolicy\fP directive is an exception, and the type us usually |
|
547 referred to before the link: |
|
548 .INDENT 0.0 |
|
549 .INDENT 3.5 |
|
550 .sp |
|
551 .nf |
|
552 .ft C |
|
553 If policy :prop_tgt:\(gaCMP0022\(ga is set to \(ga\(gaNEW\(ga\(ga the behavior is ... |
|
554 .ft P |
|
555 .fi |
|
556 .UNINDENT |
|
557 .UNINDENT |
|
558 .sp |
|
559 However, markup self\-references with \fBinline\-literal\fP syntax. |
|
560 For example, within the \fBadd_executable()\fP command |
|
561 documentation, use |
|
562 .INDENT 0.0 |
|
563 .INDENT 3.5 |
|
564 .sp |
|
565 .nf |
|
566 .ft C |
|
567 \(ga\(gaadd_executable\(ga\(ga |
|
568 .ft P |
|
569 .fi |
|
570 .UNINDENT |
|
571 .UNINDENT |
|
572 .sp |
|
573 not |
|
574 .INDENT 0.0 |
|
575 .INDENT 3.5 |
|
576 .sp |
|
577 .nf |
|
578 .ft C |
|
579 :command:\(gaadd_executable\(ga |
|
580 .ft P |
|
581 .fi |
|
582 .UNINDENT |
|
583 .UNINDENT |
|
584 .sp |
|
585 which is used elsewhere. |
|
586 .SH MODULES |
|
587 .sp |
|
588 The \fBModules\fP directory contains CMake\-language \fB\&.cmake\fP module files. |
|
589 .SS Module Documentation |
|
590 .sp |
|
591 To document CMake module \fBModules/<module\-name>.cmake\fP, modify |
|
592 \fBHelp/manual/cmake\-modules.7.rst\fP to reference the module in the |
|
593 \fBtoctree\fP directive, in sorted order, as: |
|
594 .INDENT 0.0 |
|
595 .INDENT 3.5 |
|
596 .sp |
|
597 .nf |
|
598 .ft C |
|
599 /module/<module\-name> |
|
600 .ft P |
|
601 .fi |
|
602 .UNINDENT |
|
603 .UNINDENT |
|
604 .sp |
|
605 Then add the module document file \fBHelp/module/<module\-name>.rst\fP |
|
606 containing just the line: |
|
607 .INDENT 0.0 |
|
608 .INDENT 3.5 |
|
609 .sp |
|
610 .nf |
|
611 .ft C |
|
612 \&.. cmake\-module:: ../../Modules/<module\-name>.cmake |
|
613 .ft P |
|
614 .fi |
|
615 .UNINDENT |
|
616 .UNINDENT |
|
617 .sp |
|
618 The \fBcmake\-module\fP directive will scan the module file to extract |
|
619 reStructuredText markup from comment blocks that start in \fB\&.rst:\fP\&. |
|
620 Add to the top of \fBModules/<module\-name>.cmake\fP a |
|
621 Line Comment block of the form: |
|
622 .INDENT 0.0 |
|
623 .INDENT 3.5 |
|
624 .sp |
|
625 .nf |
|
626 .ft C |
|
627 #.rst: |
|
628 # <module\-name> |
|
629 # \-\-\-\-\-\-\-\-\-\-\-\-\- |
|
630 # |
|
631 # <reStructuredText documentation of module> |
|
632 .ft P |
|
633 .fi |
|
634 .UNINDENT |
|
635 .UNINDENT |
|
636 .sp |
|
637 or a Bracket Comment of the form: |
|
638 .INDENT 0.0 |
|
639 .INDENT 3.5 |
|
640 .sp |
|
641 .nf |
|
642 .ft C |
|
643 #[[.rst: |
|
644 <module\-name> |
|
645 \-\-\-\-\-\-\-\-\-\-\-\-\- |
|
646 |
|
647 <reStructuredText documentation of module> |
|
648 #]] |
|
649 .ft P |
|
650 .fi |
|
651 .UNINDENT |
|
652 .UNINDENT |
|
653 .sp |
|
654 Any number of \fB=\fP may be used in the opening and closing brackets |
|
655 as long as they match. Content on the line containing the closing |
|
656 bracket is excluded if and only if the line starts in \fB#\fP\&. |
|
657 .sp |
|
658 Additional such \fB\&.rst:\fP comments may appear anywhere in the module file. |
|
659 All such comments must start with \fB#\fP in the first column. |
|
660 .sp |
|
661 For example, a \fBModules/Findxxx.cmake\fP module may contain: |
|
662 .INDENT 0.0 |
|
663 .INDENT 3.5 |
|
664 .sp |
|
665 .nf |
|
666 .ft C |
|
667 #.rst: |
|
668 # FindXxx |
|
669 # \-\-\-\-\-\-\- |
|
670 # |
|
671 # This is a cool module. |
|
672 # This module does really cool stuff. |
|
673 # It can do even more than you think. |
|
674 # |
|
675 # It even needs two paragraphs to tell you about it. |
|
676 # And it defines the following variables: |
|
677 # |
|
678 # * VAR_COOL: this is great isn\(aqt it? |
|
679 # * VAR_REALLY_COOL: cool right? |
|
680 |
|
681 <code> |
|
682 |
|
683 #[========================================[.rst: |
|
684 \&.. command:: xxx_do_something |
|
685 |
|
686 This command does something for Xxx:: |
|
687 |
|
688 xxx_do_something(some arguments) |
|
689 #]========================================] |
|
690 macro(xxx_do_something) |
|
691 <code> |
|
692 endmacro() |
|
693 .ft P |
|
694 .fi |
|
695 .UNINDENT |
|
696 .UNINDENT |
|
697 .sp |
|
698 After the top documentation block, leave a \fIBLANK\fP line, and then add a |
|
699 copyright and licence notice block like this one (change only the year |
|
700 range and name) |
|
701 .INDENT 0.0 |
|
702 .INDENT 3.5 |
|
703 .sp |
|
704 .nf |
|
705 .ft C |
|
706 #============================================================================= |
|
707 # Copyright 2009\-2011 Your Name |
|
708 # |
|
709 # Distributed under the OSI\-approved BSD License (the "License"); |
|
710 # see accompanying file Copyright.txt for details. |
|
711 # |
|
712 # This software is distributed WITHOUT ANY WARRANTY; without even the |
|
713 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
|
714 # See the License for more information. |
|
715 #============================================================================= |
|
716 # (To distribute this file outside of CMake, substitute the full |
|
717 # License text for the above reference.) |
|
718 .ft P |
|
719 .fi |
|
720 .UNINDENT |
|
721 .UNINDENT |
|
722 .sp |
|
723 Test the documentation formatting by running |
|
724 \fBcmake \-\-help\-module <module\-name>\fP, and also by enabling the |
|
725 \fBSPHINX_HTML\fP and \fBSPHINX_MAN\fP options to build the documentation. |
|
726 Edit the comments until generated documentation looks satisfactory. To |
|
727 have a .cmake file in this directory NOT show up in the modules |
|
728 documentation, simply leave out the \fBHelp/module/<module\-name>.rst\fP |
|
729 file and the \fBHelp/manual/cmake\-modules.7.rst\fP toctree entry. |
|
730 .SS Find Modules |
|
731 .sp |
|
732 A "find module" is a \fBModules/Find<package>.cmake\fP file to be loaded |
|
733 by the \fBfind_package()\fP command when invoked for \fB<package>\fP\&. |
|
734 .sp |
|
735 The primary task of a find module is to determine whether a package |
|
736 exists on the system, set the \fB<package>_FOUND\fP variable to reflect |
|
737 this and provide any variables, macros and imported targets required to |
|
738 use the package. A find module is useful in cases where an upstream |
|
739 library does not provide a |
|
740 config file package\&. |
|
741 .sp |
|
742 The traditional approach is to use variables for everything, including |
|
743 libraries and executables: see the \fI\%Standard Variable Names\fP section |
|
744 below. This is what most of the existing find modules provided by CMake |
|
745 do. |
|
746 .sp |
|
747 The more modern approach is to behave as much like |
|
748 config file packages files as possible, by |
|
749 providing imported target\&. This has the advantage |
|
750 of propagating Target Usage Requirements to consumers. |
|
751 .sp |
|
752 In either case (or even when providing both variables and imported |
|
753 targets), find modules should provide backwards compatibility with old |
|
754 versions that had the same name. |
|
755 .sp |
|
756 A FindFoo.cmake module will typically be loaded by the command: |
|
757 .INDENT 0.0 |
|
758 .INDENT 3.5 |
|
759 .sp |
|
760 .nf |
|
761 .ft C |
|
762 find_package(Foo [major[.minor[.patch[.tweak]]]] |
|
763 [EXACT] [QUIET] [REQUIRED] |
|
764 [[COMPONENTS] [components...]] |
|
765 [OPTIONAL_COMPONENTS components...] |
|
766 [NO_POLICY_SCOPE]) |
|
767 .ft P |
|
768 .fi |
|
769 .UNINDENT |
|
770 .UNINDENT |
|
771 .sp |
|
772 See the \fBfind_package()\fP documentation for details on what |
|
773 variables are set for the find module. Most of these are dealt with by |
|
774 using \fBFindPackageHandleStandardArgs\fP\&. |
|
775 .sp |
|
776 Briefly, the module should only locate versions of the package |
|
777 compatible with the requested version, as described by the |
|
778 \fBFoo_FIND_VERSION\fP family of variables. If \fBFoo_FIND_QUIETLY\fP is |
|
779 set to true, it should avoid printing messages, including anything |
|
780 complaining about the package not being found. If \fBFoo_FIND_REQUIRED\fP |
|
781 is set to true, the module should issue a \fBFATAL_ERROR\fP if the package |
|
782 cannot be found. If neither are set to true, it should print a |
|
783 non\-fatal message if it cannot find the package. |
|
784 .sp |
|
785 Packages that find multiple semi\-independent parts (like bundles of |
|
786 libraries) should search for the components listed in |
|
787 \fBFoo_FIND_COMPONENTS\fP if it is set , and only set \fBFoo_FOUND\fP to |
|
788 true if for each searched\-for component \fB<c>\fP that was not found, |
|
789 \fBFoo_FIND_REQUIRED_<c>\fP is not set to true. The \fBHANDLE_COMPONENTS\fP |
|
790 argument of \fBfind_package_handle_standard_args()\fP can be used to |
|
791 implement this. |
|
792 .sp |
|
793 If \fBFoo_FIND_COMPONENTS\fP is not set, which modules are searched for |
|
794 and required is up to the find module, but should be documented. |
|
795 .sp |
|
796 For internal implementation, it is a generally accepted convention that |
|
797 variables starting with underscore are for temporary use only. |
|
798 .sp |
|
799 Like all modules, find modules should be properly documented. To add a |
|
800 module to the CMake documentation, follow the steps in the \fI\%Module |
|
801 Documentation\fP section above. |
|
802 .SS Standard Variable Names |
|
803 .sp |
|
804 For a \fBFindXxx.cmake\fP module that takes the approach of setting |
|
805 variables (either instead of or in addition to creating imported |
|
806 targets), the following variable names should be used to keep things |
|
807 consistent between find modules. Note that all variables start with |
|
808 \fBXxx_\fP to make sure they do not interfere with other find modules; the |
|
809 same consideration applies to macros, functions and imported targets. |
|
810 .INDENT 0.0 |
|
811 .TP |
|
812 .B \fBXxx_INCLUDE_DIRS\fP |
|
813 The final set of include directories listed in one variable for use by |
|
814 client code. This should not be a cache entry. |
|
815 .TP |
|
816 .B \fBXxx_LIBRARIES\fP |
|
817 The libraries to link against to use Xxx. These should include full |
|
818 paths. This should not be a cache entry. |
|
819 .TP |
|
820 .B \fBXxx_DEFINITIONS\fP |
|
821 Definitions to use when compiling code that uses Xxx. This really |
|
822 shouldn\(aqt include options such as \fB\-DHAS_JPEG\fP that a client |
|
823 source\-code file uses to decide whether to \fB#include <jpeg.h>\fP |
|
824 .TP |
|
825 .B \fBXxx_EXECUTABLE\fP |
|
826 Where to find the Xxx tool. |
|
827 .TP |
|
828 .B \fBXxx_Yyy_EXECUTABLE\fP |
|
829 Where to find the Yyy tool that comes with Xxx. |
|
830 .TP |
|
831 .B \fBXxx_LIBRARY_DIRS\fP |
|
832 Optionally, the final set of library directories listed in one |
|
833 variable for use by client code. This should not be a cache entry. |
|
834 .TP |
|
835 .B \fBXxx_ROOT_DIR\fP |
|
836 Where to find the base directory of Xxx. |
|
837 .TP |
|
838 .B \fBXxx_VERSION_Yy\fP |
|
839 Expect Version Yy if true. Make sure at most one of these is ever true. |
|
840 .TP |
|
841 .B \fBXxx_WRAP_Yy\fP |
|
842 If False, do not try to use the relevant CMake wrapping command. |
|
843 .TP |
|
844 .B \fBXxx_Yy_FOUND\fP |
|
845 If False, optional Yy part of Xxx sytem is not available. |
|
846 .TP |
|
847 .B \fBXxx_FOUND\fP |
|
848 Set to false, or undefined, if we haven\(aqt found, or don\(aqt want to use |
|
849 Xxx. |
|
850 .TP |
|
851 .B \fBXxx_NOT_FOUND_MESSAGE\fP |
|
852 Should be set by config\-files in the case that it has set |
|
853 \fBXxx_FOUND\fP to FALSE. The contained message will be printed by the |
|
854 \fBfind_package()\fP command and by |
|
855 \fBfind_package_handle_standard_args()\fP to inform the user about the |
|
856 problem. |
|
857 .TP |
|
858 .B \fBXxx_RUNTIME_LIBRARY_DIRS\fP |
|
859 Optionally, the runtime library search path for use when running an |
|
860 executable linked to shared libraries. The list should be used by |
|
861 user code to create the \fBPATH\fP on windows or \fBLD_LIBRARY_PATH\fP on |
|
862 UNIX. This should not be a cache entry. |
|
863 .TP |
|
864 .B \fBXxx_VERSION\fP |
|
865 The full version string of the package found, if any. Note that many |
|
866 existing modules provide \fBXxx_VERSION_STRING\fP instead. |
|
867 .TP |
|
868 .B \fBXxx_VERSION_MAJOR\fP |
|
869 The major version of the package found, if any. |
|
870 .TP |
|
871 .B \fBXxx_VERSION_MINOR\fP |
|
872 The minor version of the package found, if any. |
|
873 .TP |
|
874 .B \fBXxx_VERSION_PATCH\fP |
|
875 The patch version of the package found, if any. |
|
876 .UNINDENT |
|
877 .sp |
|
878 The following names should not usually be used in CMakeLists.txt files, but |
|
879 are typically cache variables for users to edit and control the |
|
880 behaviour of find modules (like entering the path to a library manually) |
|
881 .INDENT 0.0 |
|
882 .TP |
|
883 .B \fBXxx_LIBRARY\fP |
|
884 The path of the Xxx library (as used with \fBfind_library()\fP, for |
|
885 example). |
|
886 .TP |
|
887 .B \fBXxx_Yy_LIBRARY\fP |
|
888 The path of the Yy library that is part of the Xxx system. It may or |
|
889 may not be required to use Xxx. |
|
890 .TP |
|
891 .B \fBXxx_INCLUDE_DIR\fP |
|
892 Where to find headers for using the Xxx library. |
|
893 .TP |
|
894 .B \fBXxx_Yy_INCLUDE_DIR\fP |
|
895 Where to find headers for using the Yy library of the Xxx system. |
|
896 .UNINDENT |
|
897 .sp |
|
898 To prevent users being overwhelmed with settings to configure, try to |
|
899 keep as many options as possible out of the cache, leaving at least one |
|
900 option which can be used to disable use of the module, or locate a |
|
901 not\-found library (e.g. \fBXxx_ROOT_DIR\fP). For the same reason, mark |
|
902 most cache options as advanced. For packages which provide both debug |
|
903 and release binaries, it is common to create cache variables with a |
|
904 \fB_LIBRARY_<CONFIG>\fP suffix, such as \fBFoo_LIBRARY_RELEASE\fP and |
|
905 \fBFoo_LIBRARY_DEBUG\fP\&. |
|
906 .sp |
|
907 While these are the standard variable names, you should provide |
|
908 backwards compatibility for any old names that were actually in use. |
|
909 Make sure you comment them as deprecated, so that no\-one starts using |
|
910 them. |
|
911 .SS A Sample Find Module |
|
912 .sp |
|
913 We will describe how to create a simple find module for a library |
|
914 \fBFoo\fP\&. |
|
915 .sp |
|
916 The first thing that is needed is documentation. CMake\(aqs documentation |
|
917 system requires you to start the file with a documentation marker and |
|
918 the name of the module. You should follow this with a simple statement |
|
919 of what the module does. |
|
920 .INDENT 0.0 |
|
921 .INDENT 3.5 |
|
922 .sp |
|
923 .nf |
|
924 .ft C |
|
925 #.rst: |
|
926 # FindFoo |
|
927 # \-\-\-\-\-\-\- |
|
928 # |
|
929 # Finds the Foo library |
|
930 # |
|
931 .ft P |
|
932 .fi |
|
933 .UNINDENT |
|
934 .UNINDENT |
|
935 .sp |
|
936 More description may be required for some packages. If there are |
|
937 caveats or other details users of the module should be aware of, you can |
|
938 add further paragraphs below this. Then you need to document what |
|
939 variables and imported targets are set by the module, such as |
|
940 .INDENT 0.0 |
|
941 .INDENT 3.5 |
|
942 .sp |
|
943 .nf |
|
944 .ft C |
|
945 # This will define the following variables:: |
|
946 # |
|
947 # Foo_FOUND \- True if the system has the Foo library |
|
948 # Foo_VERSION \- The version of the Foo library which was found |
|
949 # |
|
950 # and the following imported targets:: |
|
951 # |
|
952 # Foo::Foo \- The Foo library |
|
953 .ft P |
|
954 .fi |
|
955 .UNINDENT |
|
956 .UNINDENT |
|
957 .sp |
|
958 If the package provides any macros, they should be listed here, but can |
|
959 be documented where they are defined. See the \fI\%Module |
|
960 Documentation\fP section above for more details. |
|
961 .sp |
|
962 After the documentation, leave a blank line, and then add a copyright and |
|
963 licence notice block |
|
964 .INDENT 0.0 |
|
965 .INDENT 3.5 |
|
966 .sp |
|
967 .nf |
|
968 .ft C |
|
969 #============================================================================= |
|
970 # Copyright 2009\-2011 Your Name |
|
971 # |
|
972 # Distributed under the OSI\-approved BSD License (the "License"); |
|
973 # see accompanying file Copyright.txt for details. |
|
974 # |
|
975 # This software is distributed WITHOUT ANY WARRANTY; without even the |
|
976 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
|
977 # See the License for more information. |
|
978 #============================================================================= |
|
979 # (To distribute this file outside of CMake, substitute the full |
|
980 # License text for the above reference.) |
|
981 .ft P |
|
982 .fi |
|
983 .UNINDENT |
|
984 .UNINDENT |
|
985 .sp |
|
986 Now the actual libraries and so on have to be found. The code here will |
|
987 obviously vary from module to module (dealing with that, after all, is the |
|
988 point of find modules), but there tends to be a common pattern for libraries. |
|
989 .sp |
|
990 First, we try to use \fBpkg\-config\fP to find the library. Note that we |
|
991 cannot rely on this, as it may not be available, but it provides a good |
|
992 starting point. |
|
993 .INDENT 0.0 |
|
994 .INDENT 3.5 |
|
995 .sp |
|
996 .nf |
|
997 .ft C |
|
998 find_package(PkgConfig) |
|
999 pkg_check_modules(PC_Foo QUIET Foo) |
|
1000 .ft P |
|
1001 .fi |
|
1002 .UNINDENT |
|
1003 .UNINDENT |
|
1004 .sp |
|
1005 This should define some variables starting \fBPC_Foo_\fP that contain the |
|
1006 information from the \fBFoo.pc\fP file. |
|
1007 .sp |
|
1008 Now we need to find the libraries and include files; we use the |
|
1009 information from \fBpkg\-config\fP to provide hints to CMake about where to |
|
1010 look. |
|
1011 .INDENT 0.0 |
|
1012 .INDENT 3.5 |
|
1013 .sp |
|
1014 .nf |
|
1015 .ft C |
|
1016 find_path(Foo_INCLUDE_DIR |
|
1017 NAMES foo.h |
|
1018 PATHS ${PC_Foo_INCLUDE_DIRS} |
|
1019 PATH_SUFFIXES Foo |
|
1020 ) |
|
1021 find_library(Foo_LIBRARY |
|
1022 NAMES foo |
|
1023 PATHS ${PC_Foo_LIBRARY_DIRS} |
|
1024 ) |
|
1025 .ft P |
|
1026 .fi |
|
1027 .UNINDENT |
|
1028 .UNINDENT |
|
1029 .sp |
|
1030 If you have a good way of getting the version (from a header file, for |
|
1031 example), you can use that information to set \fBFoo_VERSION\fP (although |
|
1032 note that find modules have traditionally used \fBFoo_VERSION_STRING\fP, |
|
1033 so you may want to set both). Otherwise, attempt to use the information |
|
1034 from \fBpkg\-config\fP |
|
1035 .INDENT 0.0 |
|
1036 .INDENT 3.5 |
|
1037 .sp |
|
1038 .nf |
|
1039 .ft C |
|
1040 set(Foo_VERSION ${PC_Foo_VERSION}) |
|
1041 .ft P |
|
1042 .fi |
|
1043 .UNINDENT |
|
1044 .UNINDENT |
|
1045 .sp |
|
1046 Now we can use \fBFindPackageHandleStandardArgs\fP to do most of the |
|
1047 rest of the work for us |
|
1048 .INDENT 0.0 |
|
1049 .INDENT 3.5 |
|
1050 .sp |
|
1051 .nf |
|
1052 .ft C |
|
1053 include(FindPackageHandleStandardArgs) |
|
1054 find_package_handle_standard_args(Foo |
|
1055 FOUND_VAR Foo_FOUND |
|
1056 REQUIRED_VARS |
|
1057 Foo_LIBRARY |
|
1058 Foo_INCLUDE_DIR |
|
1059 VERSION_VAR Foo_VERSION |
|
1060 ) |
|
1061 .ft P |
|
1062 .fi |
|
1063 .UNINDENT |
|
1064 .UNINDENT |
|
1065 .sp |
|
1066 This will check that the \fBREQUIRED_VARS\fP contain values (that do not |
|
1067 end in \fB\-NOTFOUND\fP) and set \fBFoo_FOUND\fP appropriately. It will also |
|
1068 cache those values. If \fBFoo_VERSION\fP is set, and a required version |
|
1069 was passed to \fBfind_package()\fP, it will check the requested version |
|
1070 against the one in \fBFoo_VERSION\fP\&. It will also print messages as |
|
1071 appropriate; note that if the package was found, it will print the |
|
1072 contents of the first required variable to indicate where it was found. |
|
1073 .sp |
|
1074 At this point, we have to provide a way for users of the find module to |
|
1075 link to the library or libraries that were found. There are two |
|
1076 approaches, as discussed in the \fI\%Find Modules\fP section above. The |
|
1077 traditional variable approach looks like |
|
1078 .INDENT 0.0 |
|
1079 .INDENT 3.5 |
|
1080 .sp |
|
1081 .nf |
|
1082 .ft C |
|
1083 if(Foo_FOUND) |
|
1084 set(Foo_LIBRARIES ${Foo_LIBRARY}) |
|
1085 set(Foo_INCLUDE_DIRS ${Foo_INCLUDE_DIR}) |
|
1086 set(Foo_DEFINITIONS ${PC_Foo_CFLAGS_OTHER}) |
|
1087 endif() |
|
1088 .ft P |
|
1089 .fi |
|
1090 .UNINDENT |
|
1091 .UNINDENT |
|
1092 .sp |
|
1093 If more than one library was found, all of them should be included in |
|
1094 these variables (see the \fI\%Standard Variable Names\fP section for more |
|
1095 information). |
|
1096 .sp |
|
1097 When providing imported targets, these should be namespaced (hence the |
|
1098 \fBFoo::\fP prefix); CMake will recognize that values passed to |
|
1099 \fBtarget_link_libraries()\fP that contain \fB::\fP in their name are |
|
1100 supposed to be imported targets (rather than just library names), and |
|
1101 will produce appropriate diagnostic messages if that target does not |
|
1102 exist (see policy \fBCMP0028\fP). |
|
1103 .INDENT 0.0 |
|
1104 .INDENT 3.5 |
|
1105 .sp |
|
1106 .nf |
|
1107 .ft C |
|
1108 if(Foo_FOUND AND NOT TARGET Foo::Foo) |
|
1109 add_library(Foo::Foo UNKNOWN IMPORTED) |
|
1110 set_target_properties(Foo::Foo PROPERTIES |
|
1111 IMPORTED_LOCATION "${Foo_LIBRARY}" |
|
1112 INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" |
|
1113 INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" |
|
1114 ) |
|
1115 endif() |
|
1116 .ft P |
|
1117 .fi |
|
1118 .UNINDENT |
|
1119 .UNINDENT |
|
1120 .sp |
|
1121 One thing to note about this is that the \fBINTERFACE_INCLUDE_DIRECTORIES\fP and |
|
1122 similar properties should only contain information about the target itself, and |
|
1123 not any of its dependencies. Instead, those dependencies should also be |
|
1124 targets, and CMake should be told that they are dependencies of this target. |
|
1125 CMake will then combine all the necessary information automatically. |
|
1126 .sp |
|
1127 The type of the \fBIMPORTED\fP target created in the |
|
1128 \fBadd_library()\fP command can always be specified as \fBUNKNOWN\fP |
|
1129 type. This simplifies the code in cases where static or shared variants may |
|
1130 be found, and CMake will determine the type by inspecting the files. |
|
1131 .sp |
|
1132 If the library is available with multiple configurations, the |
|
1133 \fBIMPORTED_CONFIGURATIONS\fP target property should also be |
|
1134 populated: |
|
1135 .INDENT 0.0 |
|
1136 .INDENT 3.5 |
|
1137 .sp |
|
1138 .nf |
|
1139 .ft C |
|
1140 if(Foo_FOUND) |
|
1141 if (NOT TARGET Foo::Foo) |
|
1142 add_library(Foo::Foo UNKNOWN IMPORTED) |
|
1143 endif() |
|
1144 if (Foo_LIBRARY_RELEASE) |
|
1145 set_property(TARGET Foo::Foo APPEND PROPERTY |
|
1146 IMPORTED_CONFIGURATIONS RELEASE |
|
1147 ) |
|
1148 set_target_properties(Foo::Foo PROPERTIES |
|
1149 IMPORTED_LOCATION_RELEASE "${Foo_LIBRARY_RELEASE}" |
|
1150 ) |
|
1151 endif() |
|
1152 if (Foo_LIBRARY_DEBUG) |
|
1153 set_property(TARGET Foo::Foo APPEND PROPERTY |
|
1154 IMPORTED_CONFIGURATIONS DEBUG |
|
1155 ) |
|
1156 set_target_properties(Foo::Foo PROPERTIES |
|
1157 IMPORTED_LOCATION_DEBUG "${Foo_LIBRARY_DEBUG}" |
|
1158 ) |
|
1159 endif() |
|
1160 set_target_properties(Foo::Foo PROPERTIES |
|
1161 INTERFACE_COMPILE_OPTIONS "${PC_Foo_CFLAGS_OTHER}" |
|
1162 INTERFACE_INCLUDE_DIRECTORIES "${Foo_INCLUDE_DIR}" |
|
1163 ) |
|
1164 endif() |
|
1165 .ft P |
|
1166 .fi |
|
1167 .UNINDENT |
|
1168 .UNINDENT |
|
1169 .sp |
|
1170 The \fBRELEASE\fP variant should be listed first in the property |
|
1171 so that that variant is chosen if the user uses a configuration which is |
|
1172 not an exact match for any listed \fBIMPORTED_CONFIGURATIONS\fP\&. |
|
1173 .sp |
|
1174 Most of the cache variables should be hidden in the \fBccmake\fP interface unless |
|
1175 the user explicitly asks to edit them. |
|
1176 .INDENT 0.0 |
|
1177 .INDENT 3.5 |
|
1178 .sp |
|
1179 .nf |
|
1180 .ft C |
|
1181 mark_as_advanced( |
|
1182 Foo_INCLUDE_DIR |
|
1183 Foo_LIBRARY |
|
1184 ) |
|
1185 .ft P |
|
1186 .fi |
|
1187 .UNINDENT |
|
1188 .UNINDENT |
|
1189 .sp |
|
1190 If this module replaces an older version, you should set compatibility variables |
|
1191 to cause the least disruption possible. |
|
1192 .INDENT 0.0 |
|
1193 .INDENT 3.5 |
|
1194 .sp |
|
1195 .nf |
|
1196 .ft C |
|
1197 # compatibility variables |
|
1198 set(Foo_VERSION_STRING ${Foo_VERSION}) |
|
1199 .ft P |
|
1200 .fi |
|
1201 .UNINDENT |
|
1202 .UNINDENT |
|
1203 .SH COPYRIGHT |
|
1204 2000-2015 Kitware, Inc. |
|
1205 .\" Generated by docutils manpage writer. |
|
1206 . |