1cmakecommands(1)            General Commands Manual           cmakecommands(1)
2
3
4

NAME

6       cmakecommands - Reference of available CMake commands.
7
8

COMMANDS

10       add_compile_options
11              Adds options to the compilation of source files.
12
13                add_compile_options(<option> ...)
14
15              Adds  options  to  the  compiler command line for sources in the
16              current directory and below.  This command can be  used  to  add
17              any  options, but alternative commands exist to add preprocessor
18              definitions or include directories.  See  documentation  of  the
19              directory  and  target  COMPILE_OPTIONS  properties for details.
20              Arguments to add_compile_options may use "generator expressions"
21              with  the  syntax "$<...>".  Generator expressions are evaluated
22              during build system generation to produce  information  specific
23              to each build configuration.  Valid expressions are:
24
25
26                $<0:...>                  = empty string (ignores "...")
27                $<1:...>                  = content of "..."
28                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
29                $<CONFIGURATION>          = configuration name
30                $<BOOL:...>               = '1' if the '...' is true, else '0'
31                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
32                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
33                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
34                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
35                $<JOIN:list,...>          = joins the list with the content of "..."
36                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
37                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
38                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
39                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
40                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
41                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
42                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
43                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
44                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
45                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
46                $<C_COMPILER_VERSION>     = The version of the C compiler used.
47                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
48                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
49                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
50                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
51                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
52                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
53
54              where  "tgt"  is  the name of a target.  Target file expressions
55              produce a full path, but _DIR and _NAME versions can produce the
56              directory and file name components:
57
58
59                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
60                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
61                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
62
63
64
65
66                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
67
68              Note  that  tgt  is not added as a dependency of the target this
69              expression is evaluated on.
70
71
72                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
73                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
74
75              Boolean expressions:
76
77
78                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
79                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
80                $<NOT:?>                  = '0' if '?' is '1', else '1'
81
82              where '?' is always either '0' or '1'.
83
84
85              Expressions with an implicit 'this' target:
86
87
88                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
89
90
91       add_custom_command
92              Add a custom build rule to the generated build system.
93
94              There are two main signatures for add_custom_command  The  first
95              signature is for adding a custom command to produce an output.
96
97
98                add_custom_command(OUTPUT output1 [output2 ...]
99                                   COMMAND command1 [ARGS] [args1...]
100                                   [COMMAND command2 [ARGS] [args2...] ...]
101                                   [MAIN_DEPENDENCY depend]
102                                   [DEPENDS [depends...]]
103                                   [IMPLICIT_DEPENDS <lang1> depend1
104                                                    [<lang2> depend2] ...]
105                                   [WORKING_DIRECTORY dir]
106                                   [COMMENT comment] [VERBATIM] [APPEND])
107
108              This  defines a command to generate specified OUTPUT file(s).  A
109              target created in the same directory (CMakeLists.txt file)  that
110              specifies  any  output of the custom command as a source file is
111              given a rule to generate the file using  the  command  at  build
112              time.   Do not list the output in more than one independent tar‐
113              get that may build in parallel or the two instances of the  rule
114              may conflict (instead use add_custom_target to drive the command
115              and make the other targets depend on that one).   If  an  output
116              name  is  a relative path it will be interpreted relative to the
117              build tree directory corresponding to the current source  direc‐
118              tory.  Note  that  MAIN_DEPENDENCY is completely optional and is
119              used as a suggestion to visual studio about where  to  hang  the
120              custom  command.  In makefile terms this creates a new target in
121              the following form:
122
123
124                OUTPUT: MAIN_DEPENDENCY DEPENDS
125                        COMMAND
126
127              If more than one command is specified they will be  executed  in
128              order.  The optional ARGS argument is for backward compatibility
129              and will be ignored.
130
131
132              The second signature adds a custom command to a target such as a
133              library  or  executable. This is useful for performing an opera‐
134              tion before or after building the target.  The  command  becomes
135              part  of the target and will only execute when the target itself
136              is built.  If the target is already built, the command will  not
137              execute.
138
139
140                add_custom_command(TARGET target
141                                   PRE_BUILD | PRE_LINK | POST_BUILD
142                                   COMMAND command1 [ARGS] [args1...]
143                                   [COMMAND command2 [ARGS] [args2...] ...]
144                                   [WORKING_DIRECTORY dir]
145                                   [COMMENT comment] [VERBATIM])
146
147              This defines a new command that will be associated with building
148              the specified target. When the command will happen is determined
149              by which of the following is specified:
150
151
152                PRE_BUILD - run before all other dependencies
153                PRE_LINK - run after other dependencies
154                POST_BUILD - run after the target has been built
155
156              Note  that the PRE_BUILD option is only supported on Visual Stu‐
157              dio 7 or later. For  all  other  generators  PRE_BUILD  will  be
158              treated as PRE_LINK.
159
160
161              If  WORKING_DIRECTORY  is specified the command will be executed
162              in the directory given. If it is a  relative  path  it  will  be
163              interpreted  relative  to the build tree directory corresponding
164              to the current source directory. If COMMENT is  set,  the  value
165              will  be displayed as a message before the commands are executed
166              at build time. If APPEND is specified the  COMMAND  and  DEPENDS
167              option  values  are appended to the custom command for the first
168              output specified. There must have already been a  previous  call
169              to  this  command  with  the  same  output.  The  COMMENT, WORK‐
170              ING_DIRECTORY, and MAIN_DEPENDENCY options are currently ignored
171              when APPEND is given, but may be used in the future.
172
173
174              If  VERBATIM is given then all arguments to the commands will be
175              escaped properly for the build tool so that the invoked  command
176              receives  each  argument  unchanged.   Note  that  one  level of
177              escapes is still used by the  CMake  language  processor  before
178              add_custom_command  even  sees the arguments. Use of VERBATIM is
179              recommended as it enables correct behavior. When VERBATIM is not
180              given the behavior is platform specific because there is no pro‐
181              tection of tool-specific special characters.
182
183
184              If the output of the custom command is not actually created as a
185              file   on   disk   it   should   be   marked  as  SYMBOLIC  with
186              SET_SOURCE_FILES_PROPERTIES.
187
188
189              The IMPLICIT_DEPENDS option requests scanning of implicit depen‐
190              dencies of an input file.  The language given specifies the pro‐
191              gramming language whose corresponding dependency scanner  should
192              be  used.   Currently  only C and CXX language scanners are sup‐
193              ported. The language has to be specified for every file  in  the
194              IMPLICIT_DEPENDS list. Dependencies discovered from the scanning
195              are added to those of the custom command at  build  time.   Note
196              that the IMPLICIT_DEPENDS option is currently supported only for
197              Makefile generators and will be ignored by other generators.
198
199
200              If COMMAND specifies an executable target (created  by  ADD_EXE‐
201              CUTABLE)  it  will  automatically be replaced by the location of
202              the executable created  at  build  time.   Additionally  a  tar‐
203              get-level dependency will be added so that the executable target
204              will be built before any target using this custom command.  How‐
205              ever  this does NOT add a file-level dependency that would cause
206              the custom command to re-run whenever the executable  is  recom‐
207              piled.
208
209
210              Arguments  to  COMMAND  may use "generator expressions" with the
211              syntax "$<...>".  Generator  expressions  are  evaluated  during
212              build  system generation to produce information specific to each
213              build configuration.  Valid expressions are:
214
215
216                $<0:...>                  = empty string (ignores "...")
217                $<1:...>                  = content of "..."
218                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
219                $<CONFIGURATION>          = configuration name
220                $<BOOL:...>               = '1' if the '...' is true, else '0'
221                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
222                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
223                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
224                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
225                $<JOIN:list,...>          = joins the list with the content of "..."
226                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
227                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
228                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
229                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
230                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
231                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
232                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
233                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
234                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
235                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
236                $<C_COMPILER_VERSION>     = The version of the C compiler used.
237                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
238                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
239                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
240                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
241                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
242                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
243
244              where "tgt" is the name of a target.   Target  file  expressions
245              produce a full path, but _DIR and _NAME versions can produce the
246              directory and file name components:
247
248
249                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
250                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
251                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
252
253
254
255
256                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
257
258              Note that tgt is not added as a dependency of  the  target  this
259              expression is evaluated on.
260
261
262                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
263                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
264
265              Boolean expressions:
266
267
268                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
269                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
270                $<NOT:?>                  = '0' if '?' is '1', else '1'
271
272              where '?' is always either '0' or '1'.
273
274
275              Expressions with an implicit 'this' target:
276
277
278                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
279
280              References  to  target names in generator expressions imply tar‐
281              get-level dependencies, but NOT file-level  dependencies.   List
282              target names with the DEPENDS option to add file dependencies.
283
284
285              The DEPENDS option specifies files on which the command depends.
286              If any dependency is an OUTPUT of another custom command in  the
287              same  directory (CMakeLists.txt file) CMake automatically brings
288              the other custom command into the target in which  this  command
289              is  built.   If  DEPENDS  is  not specified the command will run
290              whenever the OUTPUT is missing; if the command does not actually
291              create  the  OUTPUT  then  the rule will always run.  If DEPENDS
292              specifies any target  (created  by  an  ADD_*  command)  a  tar‐
293              get-level dependency is created to make sure the target is built
294              before any target using this custom command.   Additionally,  if
295              the  target  is an executable or library a file-level dependency
296              is created to cause the custom command to  re-run  whenever  the
297              target is recompiled.
298
299
300
301       add_custom_target
302              Add a target with no output so it will always be built.
303
304                add_custom_target(Name [ALL] [command1 [args1...]]
305                                  [COMMAND command2 [args2...] ...]
306                                  [DEPENDS depend depend depend ... ]
307                                  [WORKING_DIRECTORY dir]
308                                  [COMMENT comment] [VERBATIM]
309                                  [SOURCES src1 [src2...]])
310
311              Adds  a  target with the given name that executes the given com‐
312              mands. The target has no output file and  is  ALWAYS  CONSIDERED
313              OUT  OF  DATE even if the commands try to create a file with the
314              name of the target. Use ADD_CUSTOM_COMMAND to  generate  a  file
315              with dependencies. By default nothing depends on the custom tar‐
316              get. Use ADD_DEPENDENCIES to add dependencies to or  from  other
317              targets.  If  the ALL option is specified it indicates that this
318              target should be added to the default build target  so  that  it
319              will  be  run every time (the command cannot be called ALL). The
320              command and arguments are optional and if not specified an empty
321              target  will  be  created. If WORKING_DIRECTORY is set, then the
322              command will be run in that directory. If it is a relative  path
323              it will be interpreted relative to the build tree directory cor‐
324              responding to the current source directory. If COMMENT  is  set,
325              the value will be displayed as a message before the commands are
326              executed at build time. Dependencies  listed  with  the  DEPENDS
327              argument may reference files and outputs of custom commands cre‐
328              ated with add_custom_command() in  the  same  directory  (CMake‐
329              Lists.txt file).
330
331
332              If  VERBATIM is given then all arguments to the commands will be
333              escaped properly for the build tool so that the invoked  command
334              receives  each  argument  unchanged.   Note  that  one  level of
335              escapes is still used by the  CMake  language  processor  before
336              add_custom_target  even  sees  the arguments. Use of VERBATIM is
337              recommended as it enables correct behavior. When VERBATIM is not
338              given the behavior is platform specific because there is no pro‐
339              tection of tool-specific special characters.
340
341
342              The SOURCES option  specifies  additional  source  files  to  be
343              included  in  the custom target.  Specified source files will be
344              added to IDE project files for convenience in  editing  even  if
345              they have not build rules.
346
347
348       add_definitions
349              Adds -D define flags to the compilation of source files.
350
351                add_definitions(-DFOO -DBAR ...)
352
353              Adds  flags to the compiler command line for sources in the cur‐
354              rent directory and below.  This command can be used to  add  any
355              flags,  but it was originally intended to add preprocessor defi‐
356              nitions.  Flags beginning in -D or /D that look like  preproces‐
357              sor  definitions  are automatically added to the COMPILE_DEFINI‐
358              TIONS property for  the  current  directory.   Definitions  with
359              non-trivial  values  may  be left in the set of flags instead of
360              being converted for reasons  of  backwards  compatibility.   See
361              documentation  of  the  directory,  target, and source file COM‐
362              PILE_DEFINITIONS properties for details on  adding  preprocessor
363              definitions to specific scopes and configurations.
364
365
366       add_dependencies
367              Add a dependency between top-level targets.
368
369                add_dependencies(target-name depend-target1
370                                 depend-target2 ...)
371
372              Make  a  top-level  target depend on other top-level targets.  A
373              top-level target is one created by ADD_EXECUTABLE,  ADD_LIBRARY,
374              or ADD_CUSTOM_TARGET.  Adding dependencies with this command can
375              be used to make sure one target is built before another  target.
376              Dependencies  added  to  an IMPORTED target are followed transi‐
377              tively in its place since the target itself does not build.  See
378              the  DEPENDS  option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND
379              for adding file-level dependencies in  custom  rules.   See  the
380              OBJECT_DEPENDS  option  in  SET_SOURCE_FILES_PROPERTIES  to  add
381              file-level dependencies to object files.
382
383
384       add_executable
385              Add an executable to the  project  using  the  specified  source
386              files.
387
388                add_executable(<name> [WIN32] [MACOSX_BUNDLE]
389                               [EXCLUDE_FROM_ALL]
390                               source1 source2 ... sourceN)
391
392              Adds  an  executable  target  called <name> to be built from the
393              source files listed in the command invocation.  The <name>  cor‐
394              responds  to the logical target name and must be globally unique
395              within a project.  The actual file name of the executable  built
396              is constructed based on conventions of the native platform (such
397              as <name>.exe or just <name>).
398
399
400              By default the executable file will be created in the build tree
401              directory  corresponding  to  the source tree directory in which
402              the command was invoked.  See documentation of the  RUNTIME_OUT‐
403              PUT_DIRECTORY target property to change this location.  See doc‐
404              umentation of the OUTPUT_NAME  target  property  to  change  the
405              <name> part of the final file name.
406
407
408              If  WIN32  is given the property WIN32_EXECUTABLE will be set on
409              the target created.  See documentation of that  target  property
410              for details.
411
412
413              If MACOSX_BUNDLE is given the corresponding property will be set
414              on the created target.  See documentation of  the  MACOSX_BUNDLE
415              target property for details.
416
417
418              If  EXCLUDE_FROM_ALL is given the corresponding property will be
419              set  on  the  created  target.    See   documentation   of   the
420              EXCLUDE_FROM_ALL target property for details.
421
422
423              The  add_executable  command can also create IMPORTED executable
424              targets using this signature:
425
426
427                add_executable(<name> IMPORTED [GLOBAL])
428
429              An IMPORTED executable  target  references  an  executable  file
430              located  outside  the  project.  No rules are generated to build
431              it.  The target name has scope in the directory in which  it  is
432              created and below, but the GLOBAL option extends visibility.  It
433              may be referenced like any  target  built  within  the  project.
434              IMPORTED  executables  are  useful for convenient reference from
435              commands like add_custom_command.  Details  about  the  imported
436              executable are specified by setting properties whose names begin
437              in  "IMPORTED_".   The   most   important   such   property   is
438              IMPORTED_LOCATION    (and    its    per-configuration    version
439              IMPORTED_LOCATION_<CONFIG>) which specifies the location of  the
440              main   executable  file  on  disk.   See  documentation  of  the
441              IMPORTED_* properties for more information.
442
443
444              The signature
445
446
447                add_executable(<name> ALIAS <target>)
448
449              creates an alias, such that <name> can be used to refer to <tar‐
450              get>  in subsequent commands.  The <name> does not appear in the
451              generated buildsystem as a make target.  The <target> may not be
452              an  IMPORTED  target  or an ALIAS.  Alias targets can be used as
453              linkable targets, targets to read properties  from,  executables
454              for custom commands and custom targets.  They can also be tested
455              for existance  with  the  regular  if(TARGET)  subcommand.   The
456              <name>  may  not  be used to modify properties of <target>, that
457              is, it may not be used as the operand of set_property,  set_tar‐
458              get_properties,  target_link_libraries etc.  An ALIAS target may
459              not be installed of exported.
460
461
462       add_library
463              Add a library to the project using the specified source files.
464
465                add_library(<name> [STATIC | SHARED | MODULE]
466                            [EXCLUDE_FROM_ALL]
467                            source1 source2 ... sourceN)
468
469              Adds a library target called <name> to be built from the  source
470              files  listed in the command invocation.  The <name> corresponds
471              to the logical target name and must be globally unique within  a
472              project.   The  actual  file  name  of the library built is con‐
473              structed based on conventions of the native  platform  (such  as
474              lib<name>.a or <name>.lib).
475
476
477              STATIC,  SHARED,  or  MODULE may be given to specify the type of
478              library to be created.  STATIC libraries are archives of  object
479              files  for use when linking other targets.  SHARED libraries are
480              linked dynamically and loaded at runtime.  MODULE libraries  are
481              plugins that are not linked into other targets but may be loaded
482              dynamically at runtime using dlopen-like functionality.   If  no
483              type  is  given explicitly the type is STATIC or SHARED based on
484              whether the current value of the variable  BUILD_SHARED_LIBS  is
485              true.   For  SHARED  and  MODULE libraries the POSITION_INDEPEN‐
486              DENT_CODE target property is set to TRUE automatically.
487
488
489              By default the library file will be created in  the  build  tree
490              directory  corresponding  to  the source tree directory in which
491              the command was invoked.  See documentation of the  ARCHIVE_OUT‐
492              PUT_DIRECTORY,    LIBRARY_OUTPUT_DIRECTORY,   and   RUNTIME_OUT‐
493              PUT_DIRECTORY target properties to change  this  location.   See
494              documentation  of  the OUTPUT_NAME target property to change the
495              <name> part of the final file name.
496
497
498              If EXCLUDE_FROM_ALL is given the corresponding property will  be
499              set   on   the   created   target.   See  documentation  of  the
500              EXCLUDE_FROM_ALL target property for details.
501
502
503              The add_library command can also create IMPORTED library targets
504              using this signature:
505
506
507                add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
508                            [GLOBAL])
509
510              An  IMPORTED  library  target  references a library file located
511              outside the project.  No rules are generated to build  it.   The
512              target  name  has  scope in the directory in which it is created
513              and below, but the GLOBAL option extends visibility.  It may  be
514              referenced  like  any target built within the project.  IMPORTED
515              libraries are useful for convenient reference from commands like
516              target_link_libraries.   Details  about the imported library are
517              specified  by  setting   properties   whose   names   begin   in
518              "IMPORTED_".  The most important such property is IMPORTED_LOCA‐
519              TION (and its per-configuration version  IMPORTED_LOCATION_<CON‐
520              FIG>)  which  specifies the location of the main library file on
521              disk.  See documentation of the IMPORTED_* properties  for  more
522              information.
523
524
525              The signature
526
527
528                add_library(<name> OBJECT <src>...)
529
530              creates  a  special  "object library" target.  An object library
531              compiles source files but does not archive or link their  object
532              files   into  a  library.   Instead  other  targets  created  by
533              add_library or add_executable may reference the objects using an
534              expression  of  the  form  $<TARGET_OBJECTS:objlib> as a source,
535              where "objlib" is the object library name.  For example:
536
537
538                add_library(... $<TARGET_OBJECTS:objlib> ...)
539                add_executable(... $<TARGET_OBJECTS:objlib> ...)
540
541              will include objlib's object files in  a  library  and  an  exe‐
542              cutable  along  with  those  compiled  from  their  own sources.
543              Object libraries may contain only  sources  (and  headers)  that
544              compile  to object files.  They may contain custom commands gen‐
545              erating such sources, but not PRE_BUILD, PRE_LINK, or POST_BUILD
546              commands.    Object  libraries  cannot  be  imported,  exported,
547              installed, or linked.  Some native build systems  may  not  like
548              targets that have only object files, so consider adding at least
549              one real source  file  to  any  target  that  references  $<TAR‐
550              GET_OBJECTS:objlib>.
551
552
553              The signature
554
555
556                add_library(<name> ALIAS <target>)
557
558              creates an alias, such that <name> can be used to refer to <tar‐
559              get> in subsequent commands.  The <name> does not appear in  the
560              generated buildsystem as a make target.  The <target> may not be
561              an IMPORTED target or an ALIAS.  Alias targets can  be  used  as
562              linkable  targets,  targets  to  read properties from.  They can
563              also be tested for existance with the regular if(TARGET) subcom‐
564              mand.   The <name> may not be used to modify properties of <tar‐
565              get>, that is, it may not be used as the  operand  of  set_prop‐
566              erty,   set_target_properties,  target_link_libraries  etc.   An
567              ALIAS target may not be installed of exported.
568
569
570       add_subdirectory
571              Add a subdirectory to the build.
572
573                add_subdirectory(source_dir [binary_dir]
574                                 [EXCLUDE_FROM_ALL])
575
576              Add a subdirectory to the build. The  source_dir  specifies  the
577              directory  in which the source CMakeLists.txt and code files are
578              located. If it is a relative path  it  will  be  evaluated  with
579              respect to the current directory (the typical usage), but it may
580              also be an absolute path. The binary_dir specifies the directory
581              in  which to place the output files. If it is a relative path it
582              will be evaluated with respect to the current output  directory,
583              but it may also be an absolute path. If binary_dir is not speci‐
584              fied, the value of source_dir,  before  expanding  any  relative
585              path,  will be used (the typical usage). The CMakeLists.txt file
586              in the specified source directory will be processed  immediately
587              by  CMake  before processing in the current input file continues
588              beyond this command.
589
590
591              If the EXCLUDE_FROM_ALL argument is provided then targets in the
592              subdirectory  will not be included in the ALL target of the par‐
593              ent directory by default, and will be excluded from IDE  project
594              files.  Users must explicitly build targets in the subdirectory.
595              This is meant for use when the subdirectory contains a  separate
596              part  of the project that is useful but not necessary, such as a
597              set of examples.  Typically the subdirectory should contain  its
598              own  project()  command  invocation  so that a full build system
599              will be generated in the subdirectory (such as a VS IDE solution
600              file).   Note  that  inter-target  dependencies  supercede  this
601              exclusion.  If a target built by the parent project depends on a
602              target in the subdirectory, the dependee target will be included
603              in the parent project build system to satisfy the dependency.
604
605
606       add_test
607              Add a test to the project with the specified arguments.
608
609                add_test(testname Exename arg1 arg2 ... )
610
611              If the ENABLE_TESTING command has been run, this command adds  a
612              test  target to the current directory. If ENABLE_TESTING has not
613              been run, this command does nothing.  The tests are run  by  the
614              testing  subsystem by executing Exename with the specified argu‐
615              ments.  Exename can  be  either  an  executable  built  by  this
616              project  or  an arbitrary executable on the system (like tclsh).
617              The test will be run with the current working directory  set  to
618              the  CMakeList.txt  files  corresponding directory in the binary
619              tree.
620
621
622
623
624
625                add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]]
626                         [WORKING_DIRECTORY dir]
627                         COMMAND <command> [arg1 [arg2 ...]])
628
629              Add a test called <name>.  The test name may not contain spaces,
630              quotes, or other characters special in CMake syntax.  If COMMAND
631              specifies an executable target (created  by  add_executable)  it
632              will automatically be replaced by the location of the executable
633              created at build time.  If a CONFIGURATIONS option is given then
634              the  test  will  be  executed only when testing under one of the
635              named configurations.  If a WORKING_DIRECTORY  option  is  given
636              then the test will be executed in the given directory.
637
638
639              Arguments after COMMAND may use "generator expressions" with the
640              syntax "$<...>".  Generator  expressions  are  evaluated  during
641              build  system generation to produce information specific to each
642              build configuration.  Valid expressions are:
643
644
645                $<0:...>                  = empty string (ignores "...")
646                $<1:...>                  = content of "..."
647                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
648                $<CONFIGURATION>          = configuration name
649                $<BOOL:...>               = '1' if the '...' is true, else '0'
650                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
651                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
652                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
653                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
654                $<JOIN:list,...>          = joins the list with the content of "..."
655                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
656                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
657                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
658                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
659                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
660                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
661                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
662                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
663                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
664                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
665                $<C_COMPILER_VERSION>     = The version of the C compiler used.
666                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
667                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
668                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
669                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
670                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
671                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
672
673              where "tgt" is the name of a target.   Target  file  expressions
674              produce a full path, but _DIR and _NAME versions can produce the
675              directory and file name components:
676
677
678                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
679                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
680                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
681
682
683
684
685                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
686
687              Note that tgt is not added as a dependency of  the  target  this
688              expression is evaluated on.
689
690
691                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
692                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
693
694              Boolean expressions:
695
696
697                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
698                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
699                $<NOT:?>                  = '0' if '?' is '1', else '1'
700
701              where '?' is always either '0' or '1'.
702
703
704              Example usage:
705
706
707                add_test(NAME mytest
708                         COMMAND testDriver --config $<CONFIGURATION>
709                                            --exe $<TARGET_FILE:myexe>)
710
711              This  creates  a  test  "mytest" whose command runs a testDriver
712              tool passing the configuration name and the  full  path  to  the
713              executable file produced by target "myexe".
714
715
716       aux_source_directory
717              Find all source files in a directory.
718
719                aux_source_directory(<dir> <variable>)
720
721              Collects  the  names  of  all  the source files in the specified
722              directory and stores the list in the <variable> provided.   This
723              command  is  intended  to  be used by projects that use explicit
724              template instantiation.  Template  instantiation  files  can  be
725              stored in a "Templates" subdirectory and collected automatically
726              using this command to avoid manually listing all instantiations.
727
728
729              It is tempting to use this command to avoid writing the list  of
730              source  files  for  a  library or executable target.  While this
731              seems to work, there is no way for CMake  to  generate  a  build
732              system  that  knows when a new source file has been added.  Nor‐
733              mally the generated build system knows when it  needs  to  rerun
734              CMake  because  the CMakeLists.txt file is modified to add a new
735              source.  When the source is just added to the directory  without
736              modifying  this  file, one would have to manually rerun CMake to
737              generate a build system incorporating the new file.
738
739
740       break  Break from an enclosing foreach or while loop.
741
742                break()
743
744              Breaks from an enclosing foreach loop or while loop
745
746
747       build_command
748              Get the command line to build this project.
749
750                build_command(<variable>
751                              [CONFIGURATION <config>]
752                              [PROJECT_NAME <projname>]
753                              [TARGET <target>])
754
755              Sets the given <variable> to a  string  containing  the  command
756              line  for  building  one  configuration of a target in a project
757              using the build tool appropriate for the  current  CMAKE_GENERA‐
758              TOR.
759
760
761              If  CONFIGURATION is omitted, CMake chooses a reasonable default
762              value  for  multi-configuration  generators.   CONFIGURATION  is
763              ignored for single-configuration generators.
764
765
766              If  PROJECT_NAME  is  omitted,  the  resulting command line will
767              build the top level PROJECT in the current build tree.
768
769
770              If TARGET is omitted, the  resulting  command  line  will  build
771              everything, effectively using build target 'all' or 'ALL_BUILD'.
772
773
774                build_command(<cachevariable> <makecommand>)
775
776              This  second  signature  is  deprecated, but still available for
777              backwards compatibility. Use the first signature instead.
778
779
780              Sets the given <cachevariable> to a string containing  the  com‐
781              mand to build this project from the root of the build tree using
782              the build tool given by <makecommand>.  <makecommand> should  be
783              the  full  path  to msdev, devenv, nmake, make or one of the end
784              user build tools.
785
786
787       cmake_host_system_information
788              Query host system specific information.
789
790                cmake_host_system_information(RESULT <variable> QUERY <key> ...)
791
792              Queries system information of the host  system  on  which  cmake
793              runs.  One  or more <key> can be provided to select the informa‐
794              tion to be queried. The list of  queried  values  is  stored  in
795              <variable>.
796
797
798              <key> can be one of the following values:
799
800
801                NUMBER_OF_LOGICAL_CORES   = Number of logical cores.
802                NUMBER_OF_PHYSICAL_CORES  = Number of physical cores.
803                HOSTNAME                  = Hostname.
804                FQDN                      = Fully qualified domain name.
805                TOTAL_VIRTUAL_MEMORY      = Total virtual memory in megabytes.
806                AVAILABLE_VIRTUAL_MEMORY  = Available virtual memory in megabytes.
807                TOTAL_PHYSICAL_MEMORY     = Total physical memory in megabytes.
808                AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
809
810
811       cmake_minimum_required
812              Set the minimum required version of cmake for a project.
813
814                cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
815                                       [FATAL_ERROR])
816
817              If  the  current version of CMake is lower than that required it
818              will stop processing the project and report an  error.   When  a
819              version  higher  than  2.4  is  specified the command implicitly
820              invokes
821
822
823                cmake_policy(VERSION major[.minor[.patch[.tweak]]])
824
825              which sets the cmake policy version level to the version  speci‐
826              fied.  When version 2.4 or lower is given the command implicitly
827              invokes
828
829
830                cmake_policy(VERSION 2.4)
831
832              which enables compatibility features for CMake 2.4 and lower.
833
834
835              The FATAL_ERROR option is accepted but ignored by CMake 2.6  and
836              higher.   It should be specified so CMake versions 2.4 and lower
837              fail with an error instead of just a warning.
838
839
840       cmake_policy
841              Manage CMake Policy settings.
842
843              As CMake evolves it is sometimes necessary  to  change  existing
844              behavior  in  order  to  fix  bugs or improve implementations of
845              existing features.  The CMake Policy mechanism  is  designed  to
846              help  keep  existing  projects building as new versions of CMake
847              introduce changes in  behavior.   Each  new  policy  (behavioral
848              change)  is  given  an  identifier of the form "CMP<NNNN>" where
849              "<NNNN>" is an integer  index.   Documentation  associated  with
850              each  policy  describes  the OLD and NEW behavior and the reason
851              the policy was introduced.  Projects  may  set  each  policy  to
852              select  the  desired  behavior.   When CMake needs to know which
853              behavior to use  it  checks  for  a  setting  specified  by  the
854              project.  If no setting is available the OLD behavior is assumed
855              and a warning is produced requesting that the policy be set.
856
857
858              The cmake_policy command is used to set policies to OLD  or  NEW
859              behavior.   While setting policies individually is supported, we
860              encourage projects to set policies based on CMake versions.
861
862
863                cmake_policy(VERSION major.minor[.patch[.tweak]])
864
865              Specify that the current CMake list  file  is  written  for  the
866              given  version  of CMake.  All policies introduced in the speci‐
867              fied version or earlier will be set to use  NEW  behavior.   All
868              policies  introduced  after  the specified version will be unset
869              (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
870              This effectively requests behavior preferred as of a given CMake
871              version and tells newer CMake versions to warn about  their  new
872              policies.   The policy version specified must be at least 2.4 or
873              the command will report an error.  In order to get compatibility
874              features  supporting versions earlier than 2.4 see documentation
875              of policy CMP0001.
876
877
878                cmake_policy(SET CMP<NNNN> NEW)
879                cmake_policy(SET CMP<NNNN> OLD)
880
881              Tell CMake to use the OLD or NEW behavior for  a  given  policy.
882              Projects  depending  on  the  old behavior of a given policy may
883              silence a policy warning by setting the  policy  state  to  OLD.
884              Alternatively  one  may  fix  the  project  to work with the new
885              behavior and set the policy state to NEW.
886
887
888                cmake_policy(GET CMP<NNNN> <variable>)
889
890              Check whether a given policy is set to OLD or NEW behavior.  The
891              output  variable  value  will be "OLD" or "NEW" if the policy is
892              set, and empty otherwise.
893
894
895              CMake keeps policy settings on a stack, so changes made  by  the
896              cmake_policy  command  affect  only the top of the stack.  A new
897              entry on the policy stack is managed automatically for each sub‐
898              directory  to protect its parents and siblings.  CMake also man‐
899              ages a new entry for scripts loaded by include() and  find_pack‐
900              age()  commands  except  when  invoked  with the NO_POLICY_SCOPE
901              option (see also policy CMP0011).  The cmake_policy command pro‐
902              vides an interface to manage custom entries on the policy stack:
903
904
905                cmake_policy(PUSH)
906                cmake_policy(POP)
907
908              Each  PUSH  must have a matching POP to erase any changes.  This
909              is useful to make temporary changes to policy settings.
910
911
912              Functions and macros record policy settings when they  are  cre‐
913              ated  and use the pre-record policies when they are invoked.  If
914              the function or macro implementation sets policies, the  changes
915              automatically  propagate up through callers until they reach the
916              closest nested policy stack entry.
917
918
919       configure_file
920              Copy a file to another location and modify its contents.
921
922                configure_file(<input> <output>
923                               [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
924                               [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
925
926              Copies a file <input> to file <output> and substitutes  variable
927              values referenced in the file content.  If <input> is a relative
928              path it is evaluated with respect to the current  source  direc‐
929              tory.  The <input> must be a file, not a directory.  If <output>
930              is a relative path it is evaluated with respect to  the  current
931              binary  directory.   If <output> names an existing directory the
932              input file is placed in that directory with its original name.
933
934
935              If the <input> file is modified the  build  system  will  re-run
936              CMake  to  re-configure  the  file and generate the build system
937              again.
938
939
940              This command replaces any variables in the input file referenced
941              as ${VAR} or @VAR@ with their values as determined by CMake.  If
942              a variable is not defined, it will be replaced with nothing.  If
943              COPYONLY  is  specified,  then  no  variable expansion will take
944              place.  If  ESCAPE_QUOTES  is  specified  then  any  substituted
945              quotes  will  be  C-style  escaped.  The file will be configured
946              with the current values of CMake variables. If @ONLY  is  speci‐
947              fied,  only  variables  of  the  form @VAR@ will be replaced and
948              ${VAR} will be ignored.  This is useful for configuring  scripts
949              that use ${VAR}.
950
951
952              Input  file  lines  of  the  form "#cmakedefine VAR ..." will be
953              replaced with either "#define VAR ..." or  "/*  #undef  VAR  */"
954              depending  on  whether VAR is set in CMake to any value not con‐
955              sidered a false constant by the if() command. (Content of "...",
956              if  any,  is  processed  as above.) Input file lines of the form
957              "#cmakedefine01 VAR" will be replaced with either  "#define  VAR
958              1" or "#define VAR 0" similarly.
959
960
961              With NEWLINE_STYLE the line ending could be adjusted:
962
963
964                  'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
965
966              COPYONLY must not be used with NEWLINE_STYLE.
967
968
969
970       create_test_sourcelist
971              Create a test driver and source list for building test programs.
972
973                create_test_sourcelist(sourceListName driverName
974                                       test1 test2 test3
975                                       EXTRA_INCLUDE include.h
976                                       FUNCTION function)
977
978              A  test driver is a program that links together many small tests
979              into a single executable.  This is useful when  building  static
980              executables  with  large  libraries to shrink the total required
981              size.  The list of source files needed to build the test  driver
982              will  be  in sourceListName.  DriverName is the name of the test
983              driver program.  The rest of the arguments consist of a list  of
984              test source files, can be semicolon separated.  Each test source
985              file should have a function in it that is the same name  as  the
986              file  with  no  extension  (foo.cxx  should  have  int  foo(int,
987              char*[]);) DriverName will be able to call each of the tests  by
988              name  on  the  command line. If EXTRA_INCLUDE is specified, then
989              the next argument is included into the generated file. If  FUNC‐
990              TION is specified, then the next argument is taken as a function
991              name that is passed a pointer to ac and av.  This can be used to
992              add  extra command line processing to each test. The cmake vari‐
993              able CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set  to  have  code
994              that  will be placed directly before calling the test main func‐
995              tion.   CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have  code
996              that  will  be  placed  directly after the call to the test main
997              function.
998
999
1000       define_property
1001              Define and document custom properties.
1002
1003                define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
1004                                 TEST | VARIABLE | CACHED_VARIABLE>
1005                                 PROPERTY <name> [INHERITED]
1006                                 BRIEF_DOCS <brief-doc> [docs...]
1007                                 FULL_DOCS <full-doc> [docs...])
1008
1009              Define one property in a scope for use with the set_property and
1010              get_property  commands.   This  is primarily useful to associate
1011              documentation with property names that may be retrieved with the
1012              get_property command.  The first argument determines the kind of
1013              scope in which the property should be used.  It must be  one  of
1014              the following:
1015
1016
1017                GLOBAL    = associated with the global namespace
1018                DIRECTORY = associated with one directory
1019                TARGET    = associated with one target
1020                SOURCE    = associated with one source file
1021                TEST      = associated with a test named with add_test
1022                VARIABLE  = documents a CMake language variable
1023                CACHED_VARIABLE = documents a CMake cache variable
1024
1025              Note  that  unlike set_property and get_property no actual scope
1026              needs to be given; only the kind of scope is important.
1027
1028
1029              The required PROPERTY option is immediately followed by the name
1030              of the property being defined.
1031
1032
1033              If the INHERITED option then the get_property command will chain
1034              up to the next higher scope when the requested property  is  not
1035              set  in  the scope given to the command.  DIRECTORY scope chains
1036              to GLOBAL.  TARGET, SOURCE, and TEST chain to DIRECTORY.
1037
1038
1039              The BRIEF_DOCS and FULL_DOCS options are followed by strings  to
1040              be associated with the property as its brief and full documenta‐
1041              tion.  Corresponding options to the  get_property  command  will
1042              retrieve the documentation.
1043
1044
1045       else   Starts the else portion of an if block.
1046
1047                else(expression)
1048
1049              See the if command.
1050
1051
1052       elseif Starts the elseif portion of an if block.
1053
1054                elseif(expression)
1055
1056              See the if command.
1057
1058
1059       enable_language
1060              Enable a language (CXX/C/Fortran/etc)
1061
1062                enable_language(<lang> [OPTIONAL] )
1063
1064              This  command  enables  support for the named language in CMake.
1065              This is the same as the project command but does not create  any
1066              of  the extra variables that are created by the project command.
1067              Example languages are CXX, C, Fortran.
1068
1069
1070              This command must be called in file scope,  not  in  a  function
1071              call.   Furthermore,  it must be called in the highest directory
1072              common to all targets using the named language directly for com‐
1073              piling  sources  or indirectly through link dependencies.  It is
1074              simplest to enable all needed languages in the top-level  direc‐
1075              tory of a project.
1076
1077
1078              The  OPTIONAL keyword is a placeholder for future implementation
1079              and does not currently work.
1080
1081
1082       enable_testing
1083              Enable testing for current directory and below.
1084
1085                enable_testing()
1086
1087              Enables testing for this directory  and  below.   See  also  the
1088              add_test  command.   Note that ctest expects to find a test file
1089              in the build directory root.  Therefore, this command should  be
1090              in the source directory root.
1091
1092
1093       endforeach
1094              Ends a list of commands in a FOREACH block.
1095
1096                endforeach(expression)
1097
1098              See the FOREACH command.
1099
1100
1101       endfunction
1102              Ends a list of commands in a function block.
1103
1104                endfunction(expression)
1105
1106              See the function command.
1107
1108
1109       endif  Ends a list of commands in an if block.
1110
1111                endif(expression)
1112
1113              See the if command.
1114
1115
1116       endmacro
1117              Ends a list of commands in a macro block.
1118
1119                endmacro(expression)
1120
1121              See the macro command.
1122
1123
1124       endwhile
1125              Ends a list of commands in a while block.
1126
1127                endwhile(expression)
1128
1129              See the while command.
1130
1131
1132       execute_process
1133              Execute one or more child processes.
1134
1135                execute_process(COMMAND <cmd1> [args1...]]
1136                                [COMMAND <cmd2> [args2...] [...]]
1137                                [WORKING_DIRECTORY <directory>]
1138                                [TIMEOUT <seconds>]
1139                                [RESULT_VARIABLE <variable>]
1140                                [OUTPUT_VARIABLE <variable>]
1141                                [ERROR_VARIABLE <variable>]
1142                                [INPUT_FILE <file>]
1143                                [OUTPUT_FILE <file>]
1144                                [ERROR_FILE <file>]
1145                                [OUTPUT_QUIET]
1146                                [ERROR_QUIET]
1147                                [OUTPUT_STRIP_TRAILING_WHITESPACE]
1148                                [ERROR_STRIP_TRAILING_WHITESPACE])
1149
1150              Runs  the  given sequence of one or more commands with the stan‐
1151              dard output of each process piped to the standard input  of  the
1152              next.   A  single standard error pipe is used for all processes.
1153              If WORKING_DIRECTORY is given the named directory will be set as
1154              the  current working directory of the child processes.  If TIME‐
1155              OUT is given the child processes will be terminated if  they  do
1156              not  finish  in  the  specified number of seconds (fractions are
1157              allowed).  If RESULT_VARIABLE is given the variable will be  set
1158              to contain the result of running the processes.  This will be an
1159              integer return code from the last child or a  string  describing
1160              an  error  condition.   If OUTPUT_VARIABLE or ERROR_VARIABLE are
1161              given the variable named will be set with the  contents  of  the
1162              standard  output  and standard error pipes respectively.  If the
1163              same variable is named for  both  pipes  their  output  will  be
1164              merged  in  the  order produced.  If INPUT_FILE, OUTPUT_FILE, or
1165              ERROR_FILE is given the file named will be attached to the stan‐
1166              dard  input  of  the  first process, standard output of the last
1167              process, or standard error of all  processes  respectively.   If
1168              OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
1169              standard error results will be quietly ignored.   If  more  than
1170              one  OUTPUT_*  or  ERROR_* option is given for the same pipe the
1171              precedence is not specified.  If no OUTPUT_* or ERROR_*  options
1172              are given the output will be shared with the corresponding pipes
1173              of the CMake process itself.
1174
1175
1176              The execute_process command is a newer more powerful version  of
1177              exec_program,  but the old command has been kept for compatibil‐
1178              ity.
1179
1180
1181       export Export targets from the build tree for use by outside projects.
1182
1183                export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
1184                       [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
1185
1186              Create a  file  <filename>  that  may  be  included  by  outside
1187              projects  to  import  targets  from  the current project's build
1188              tree.  This is useful during cross-compiling  to  build  utility
1189              executables that can run on the host platform in one project and
1190              then import them into another project  being  compiled  for  the
1191              target  platform.   If the NAMESPACE option is given the <names‐
1192              pace> string will be prepended to all target  names  written  to
1193              the file.  If the APPEND option is given the generated code will
1194              be  appended  to  the  file  instead  of  overwriting  it.   The
1195              EXPORT_LINK_INTERFACE_LIBRARIES  keyword, if present, causes the
1196              contents  of  the  properties  matching  (IMPORTED_)?LINK_INTER‐
1197              FACE_LIBRARIES(_<CONFIG>)?  to  be exported, when policy CMP0022
1198              is NEW.  If a library target is included in  the  export  but  a
1199              target to which it links is not included the behavior is unspec‐
1200              ified.
1201
1202
1203              The file created by this command is specific to the  build  tree
1204              and  should never be installed.  See the install(EXPORT) command
1205              to export targets from an installation tree.
1206
1207
1208              Do not set properties that affect the location of a target after
1209              passing  it  to  this  command.   These include properties whose
1210              names    match    "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIREC‐
1211              TORY)(_<CONFIG>)?", "(IMPLIB_)?(PREFIX|SUFFIX)", or "LINKER_LAN‐
1212              GUAGE".  Failure to follow this rule is not diagnosed and leaves
1213              the location of the target undefined.
1214
1215
1216                export(PACKAGE <name>)
1217
1218              Store the current build directory in the CMake user package reg‐
1219              istry for package <name>.  The find_package command may consider
1220              the  directory  while  searching for package <name>.  This helps
1221              dependent projects find and  use  a  package  from  the  current
1222              project's  build tree without help from the user.  Note that the
1223              entry in the package registry that this  command  creates  works
1224              only   in   conjunction   with   a  package  configuration  file
1225              (<name>Config.cmake) that works with the build tree.
1226
1227
1228       file   File manipulation command.
1229
1230                file(WRITE filename "message to write"... )
1231                file(APPEND filename "message to write"... )
1232                file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
1233                file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
1234                file(STRINGS filename variable [LIMIT_COUNT num]
1235                     [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
1236                     [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
1237                     [NEWLINE_CONSUME] [REGEX regex]
1238                     [NO_HEX_CONVERSION])
1239                file(GLOB variable [RELATIVE path] [globbing expressions]...)
1240                file(GLOB_RECURSE variable [RELATIVE path]
1241                     [FOLLOW_SYMLINKS] [globbing expressions]...)
1242                file(RENAME <oldname> <newname>)
1243                file(REMOVE [file1 ...])
1244                file(REMOVE_RECURSE [file1 ...])
1245                file(MAKE_DIRECTORY [directory1 directory2 ...])
1246                file(RELATIVE_PATH variable directory file)
1247                file(TO_CMAKE_PATH path result)
1248                file(TO_NATIVE_PATH path result)
1249                file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
1250                     [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
1251                     [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
1252                     [TLS_VERIFY on|off] [TLS_CAINFO file])
1253                file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
1254                     [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
1255                file(TIMESTAMP filename variable [<format string>] [UTC])
1256                file(GENERATE OUTPUT output_file
1257                     <INPUT input_file|CONTENT input_content>
1258                     [CONDITION expression])
1259
1260              WRITE will write a message into a  file  called  'filename'.  It
1261              overwrites  the  file if it already exists, and creates the file
1262              if it does not exist. (If the file is a build input, use config‐
1263              ure_file to update the file only when its content changes.)
1264
1265
1266              APPEND will write a message into a file same as WRITE, except it
1267              will append it to the end of the file
1268
1269
1270              READ will read the content of a file and store it into the vari‐
1271              able. It will start at the given offset and read up to numBytes.
1272              If the argument HEX is given, the binary data will be  converted
1273              to  hexadecimal  representation  and  this will be stored in the
1274              variable.
1275
1276
1277              MD5, SHA1, SHA224, SHA256, SHA384, and  SHA512  will  compute  a
1278              cryptographic hash of the content of a file.
1279
1280
1281              STRINGS will parse a list of ASCII strings from a file and store
1282              it in a variable. Binary data in the file are ignored.  Carriage
1283              return  (CR) characters are ignored. It works also for Intel Hex
1284              and Motorola S-record files, which are  automatically  converted
1285              to   binary   format  when  reading  them.  Disable  this  using
1286              NO_HEX_CONVERSION.
1287
1288
1289              LIMIT_COUNT sets  the  maximum  number  of  strings  to  return.
1290              LIMIT_INPUT  sets  the  maximum number of bytes to read from the
1291              input file. LIMIT_OUTPUT sets the maximum  number  of  bytes  to
1292              store  in  the  output variable. LENGTH_MINIMUM sets the minimum
1293              length of a string  to  return.  Shorter  strings  are  ignored.
1294              LENGTH_MAXIMUM  sets  the  maximum length of a string to return.
1295              Longer strings are split into strings no longer than the maximum
1296              length.  NEWLINE_CONSUME  allows  newlines  to  be  included  in
1297              strings instead of terminating them.
1298
1299
1300              REGEX specifies a regular expression that a string must match to
1301              be returned. Typical usage
1302
1303
1304                file(STRINGS myfile.txt myfile)
1305
1306              stores  a  list in the variable "myfile" in which each item is a
1307              line from the input file.
1308
1309
1310              GLOB will generate a list of all files that match  the  globbing
1311              expressions and store it into the variable. Globbing expressions
1312              are similar to regular expressions, but much simpler.  If  RELA‐
1313              TIVE  flag  is  specified for an expression, the results will be
1314              returned as a relative path to the given path.  (We do not  rec‐
1315              ommend  using  GLOB  to collect a list of source files from your
1316              source tree.  If no CMakeLists.txt file changes when a source is
1317              added  or  removed  then  the generated build system cannot know
1318              when to ask CMake to regenerate.)
1319
1320
1321              Examples of globbing expressions include:
1322
1323
1324                 *.cxx      - match all files with extension cxx
1325                 *.vt?      - match all files with extension vta,...,vtz
1326                 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1327
1328              GLOB_RECURSE will generate a list similar to the  regular  GLOB,
1329              except  it  will  traverse all the subdirectories of the matched
1330              directory and match the files. Subdirectories that are  symlinks
1331              are  only  traversed if FOLLOW_SYMLINKS is given or cmake policy
1332              CMP0009 is not set to NEW. See cmake --help-policy  CMP0009  for
1333              more information.
1334
1335
1336              Examples of recursive globbing include:
1337
1338
1339                 /dir/*.py  - match all python files in /dir and subdirectories
1340
1341              MAKE_DIRECTORY  will create the given directories, also if their
1342              parent directories don't exist yet
1343
1344
1345              RENAME moves a file or directory within a filesystem,  replacing
1346              the destination atomically.
1347
1348
1349              REMOVE will remove the given files, also in subdirectories
1350
1351
1352              REMOVE_RECURSE will remove the given files and directories, also
1353              non-empty directories
1354
1355
1356              RELATIVE_PATH will determine relative path from directory to the
1357              given file.
1358
1359
1360              TO_CMAKE_PATH  will  convert  path  into a cmake style path with
1361              unix /.  The input can be a single path or a  system  path  like
1362              "$ENV{PATH}".   Note  the  double  quotes  around  the  ENV call
1363              TO_CMAKE_PATH only takes  one argument. This command  will  also
1364              convert  the native list delimiters for a list of paths like the
1365              PATH environment variable.
1366
1367
1368              TO_NATIVE_PATH works just like TO_CMAKE_PATH, but  will  convert
1369              from   a  cmake style path into the native path style \ for win‐
1370              dows and / for UNIX.
1371
1372
1373              DOWNLOAD will download the given URL to the given file.  If  LOG
1374              var  is  specified  a log of the download will be put in var. If
1375              STATUS var is specified the status of the operation will be  put
1376              in  var. The status is returned in a list of length 2. The first
1377              element is the numeric return value for the operation,  and  the
1378              second  element  is  a  string  value for the error. A 0 numeric
1379              error means no error in the operation. If TIMEOUT time is speci‐
1380              fied, the operation will timeout after time seconds, time should
1381              be specified as an integer. The INACTIVITY_TIMEOUT specifies  an
1382              integer  number  of seconds of inactivity after which the opera‐
1383              tion should terminate. If EXPECTED_HASH ALGO=value is specified,
1384              the operation will verify that the downloaded file's actual hash
1385              matches the expected value, where ALGO  is  one  of  MD5,  SHA1,
1386              SHA224,  SHA256,  SHA384,  or SHA512.  If it does not match, the
1387              operation fails with an error. ("EXPECTED_MD5 sum" is short-hand
1388              for  "EXPECTED_HASH  MD5=sum".)  If  SHOW_PROGRESS is specified,
1389              progress information will be printed as  status  messages  until
1390              the  operation  is  complete. For https URLs CMake must be built
1391              with OpenSSL.  TLS/SSL certificates are not checked by  default.
1392              Set   TLS_VERIFY   to   ON  to  check  certificates  and/or  use
1393              EXPECTED_HASH to verify downloaded content.  Set  TLS_CAINFO  to
1394              specify  a  custom  Certificate  Authority  file.  If either TLS
1395              option is not given CMake will check variables  CMAKE_TLS_VERIFY
1396              and CMAKE_TLS_CAINFO, respectively.
1397
1398
1399              UPLOAD  will  upload the given file to the given URL. If LOG var
1400              is specified a log of the upload will be put in var.  If  STATUS
1401              var is specified the status of the operation will be put in var.
1402              The status is returned in a list of length 2. The first  element
1403              is  the  numeric  return value for the operation, and the second
1404              element is a string value for the error. A 0 numeric error means
1405              no  error  in  the  operation. If TIMEOUT time is specified, the
1406              operation will timeout after time seconds, time should be speci‐
1407              fied  as an integer. The INACTIVITY_TIMEOUT specifies an integer
1408              number of seconds of inactivity after which the operation should
1409              terminate.  If  SHOW_PROGRESS is specified, progress information
1410              will be printed as status messages until the operation  is  com‐
1411              plete.
1412
1413
1414              TIMESTAMP will write a string representation of the modification
1415              time of filename to variable.
1416
1417
1418              Should the command be unable to obtain a timestamp variable will
1419              be set to the empty string "".
1420
1421
1422              See  documentation  of the string TIMESTAMP sub-command for more
1423              details.
1424
1425
1426              The file() command also provides COPY and INSTALL signatures:
1427
1428
1429                file(<COPY|INSTALL> files... DESTINATION <dir>
1430                     [FILE_PERMISSIONS permissions...]
1431                     [DIRECTORY_PERMISSIONS permissions...]
1432                     [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1433                     [FILES_MATCHING]
1434                     [[PATTERN <pattern> | REGEX <regex>]
1435                      [EXCLUDE] [PERMISSIONS permissions...]] [...])
1436
1437              The COPY signature copies files, directories, and symlinks to  a
1438              destination  folder.   Relative  input  paths are evaluated with
1439              respect to the current source directory, and a relative destina‐
1440              tion  is  evaluated with respect to the current build directory.
1441              Copying preserves input file timestamps,  and  optimizes  out  a
1442              file  if  it  exists at the destination with the same timestamp.
1443              Copying preserves input permissions unless explicit  permissions
1444              or  NO_SOURCE_PERMISSIONS  are given (default is USE_SOURCE_PER‐
1445              MISSIONS).  See the install(DIRECTORY) command for documentation
1446              of permissions, PATTERN, REGEX, and EXCLUDE options.
1447
1448
1449              The INSTALL signature differs slightly from COPY: it prints sta‐
1450              tus messages, and NO_SOURCE_PERMISSIONS is  default.   Installa‐
1451              tion  scripts generated by the install() command use this signa‐
1452              ture (with some undocumented options for internal use).
1453
1454
1455              GENERATE will  write  an  <output_file>  with  content  from  an
1456              <input_file>,  or from <input_content>.  The output is generated
1457              conditionally based on the content of the <condition>.  The file
1458              is written at CMake generate-time and the input may contain gen‐
1459              erator  expressions.    The   <condition>,   <output_file>   and
1460              <input_file>  may also contain generator expressions.  The <con‐
1461              dition> must evaluate to either '0' or '1'.   The  <output_file>
1462              must  evaluate  to  a  unique  name among all configurations and
1463              among all invocations of file(GENERATE).
1464
1465
1466       find_file
1467              Find the full path to a file.
1468
1469                 find_file(<VAR> name1 [path1 path2 ...])
1470
1471              This is the short-hand signature for the command that is  suffi‐
1472              cient  in  many  cases.  It is the same as find_file(<VAR> name1
1473              [PATHS path1 path2 ...])
1474
1475
1476                 find_file(
1477                           <VAR>
1478                           name | NAMES name1 [name2 ...]
1479                           [HINTS path1 [path2 ... ENV var]]
1480                           [PATHS path1 [path2 ... ENV var]]
1481                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
1482                           [DOC "cache documentation string"]
1483                           [NO_DEFAULT_PATH]
1484                           [NO_CMAKE_ENVIRONMENT_PATH]
1485                           [NO_CMAKE_PATH]
1486                           [NO_SYSTEM_ENVIRONMENT_PATH]
1487                           [NO_CMAKE_SYSTEM_PATH]
1488                           [CMAKE_FIND_ROOT_PATH_BOTH |
1489                            ONLY_CMAKE_FIND_ROOT_PATH |
1490                            NO_CMAKE_FIND_ROOT_PATH]
1491                          )
1492
1493              This command is used to find a full path to named file. A  cache
1494              entry named by <VAR> is created to store the result of this com‐
1495              mand.  If the full path to a file is found the result is  stored
1496              in  the  variable and the search will not be repeated unless the
1497              variable is cleared.  If nothing is found, the  result  will  be
1498              <VAR>-NOTFOUND,  and the search will be attempted again the next
1499              time find_file is invoked with the same variable.  The  name  of
1500              the full path to a file that is searched for is specified by the
1501              names listed after the NAMES argument.   Additional search loca‐
1502              tions  can be specified after the PATHS argument.  If ENV var is
1503              found in the HINTS or PATHS section the environment variable var
1504              will be read and converted from a system environment variable to
1505              a cmake style list of paths.  For example ENV PATH  would  be  a
1506              way  to  list  the  system path variable. The argument after DOC
1507              will  be  used  for  the  documentation  string  in  the  cache.
1508              PATH_SUFFIXES specifies additional subdirectories to check below
1509              each search path.
1510
1511
1512              If NO_DEFAULT_PATH is specified, then no  additional  paths  are
1513              added  to  the  search. If NO_DEFAULT_PATH is not specified, the
1514              search process is as follows:
1515
1516
1517              1. Search paths specified  in  cmake-specific  cache  variables.
1518              These  are  intended  to  be  used  on  the  command line with a
1519              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
1520
1521
1522                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1523                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1524                 CMAKE_INCLUDE_PATH
1525                 CMAKE_FRAMEWORK_PATH
1526
1527              2. Search paths specified in  cmake-specific  environment  vari‐
1528              ables.  These are intended to be set in the user's shell config‐
1529              uration.  This can be skipped  if  NO_CMAKE_ENVIRONMENT_PATH  is
1530              passed.
1531
1532
1533                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1534                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1535                 CMAKE_INCLUDE_PATH
1536                 CMAKE_FRAMEWORK_PATH
1537
1538              3. Search the paths specified by the HINTS option.  These should
1539              be paths computed by system introspection, such as a  hint  pro‐
1540              vided by the location of another item already found.  Hard-coded
1541              guesses should be specified with the PATHS option.
1542
1543
1544              4. Search the standard system environment variables. This can be
1545              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1546
1547
1548                 PATH
1549                 INCLUDE
1550
1551              5.  Search cmake variables defined in the Platform files for the
1552              current system.  This can be skipped if NO_CMAKE_SYSTEM_PATH  is
1553              passed.
1554
1555
1556                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1557                 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1558                 CMAKE_SYSTEM_INCLUDE_PATH
1559                 CMAKE_SYSTEM_FRAMEWORK_PATH
1560
1561              6.  Search  the  paths  specified  by the PATHS option or in the
1562              short-hand  version  of  the  command.   These   are   typically
1563              hard-coded guesses.
1564
1565
1566              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1567              able    CMAKE_FIND_FRAMEWORK can be set to empty or one  of  the
1568              following:
1569
1570
1571                 "FIRST"  - Try to find frameworks before standard
1572                            libraries or headers. This is the default on Darwin.
1573                 "LAST"   - Try to find frameworks after standard
1574                            libraries or headers.
1575                 "ONLY"   - Only try to find frameworks.
1576                 "NEVER" - Never try to find frameworks.
1577
1578              On  Darwin  or  systems supporting OS X Application Bundles, the
1579              cmake variable CMAKE_FIND_APPBUNDLE can be set to empty  or  one
1580              of the following:
1581
1582
1583                 "FIRST"  - Try to find application bundles before standard
1584                            programs. This is the default on Darwin.
1585                 "LAST"   - Try to find application bundles after standard
1586                            programs.
1587                 "ONLY"   - Only try to find application bundles.
1588                 "NEVER" - Never try to find application bundles.
1589
1590              The  CMake  variable  CMAKE_FIND_ROOT_PATH specifies one or more
1591              directories to be prepended to  all  other  search  directories.
1592              This  effectively "re-roots" the entire search under given loca‐
1593              tions. By default it is empty.  It  is  especially  useful  when
1594              cross-compiling  to  point  to  the root directory of the target
1595              environment and CMake will search there too. By default at first
1596              the  directories  listed  in  CMAKE_FIND_ROOT_PATH  and then the
1597              non-rooted directories will be searched.  The  default  behavior
1598              can  be  adjusted  by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1599              This behavior can be manually overridden on a per-call basis. By
1600              using  CMAKE_FIND_ROOT_PATH_BOTH  the  search  order  will be as
1601              described  above.  If  NO_CMAKE_FIND_ROOT_PATH  is   used   then
1602              CMAKE_FIND_ROOT_PATH      will      not      be     used.     If
1603              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1604              tories will be searched.
1605
1606
1607              The  default  search  order  is  designed to be most-specific to
1608              least-specific for common use cases.  Projects may override  the
1609              order by simply calling the command multiple times and using the
1610              NO_* options:
1611
1612
1613                 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1614                 find_file(<VAR> NAMES name)
1615
1616              Once one of the calls succeeds the result variable will  be  set
1617              and stored in the cache so that no call will search again.
1618
1619
1620       find_library
1621              Find a library.
1622
1623                 find_library(<VAR> name1 [path1 path2 ...])
1624
1625              This  is the short-hand signature for the command that is suffi‐
1626              cient in many cases.  It is the same as find_library(<VAR> name1
1627              [PATHS path1 path2 ...])
1628
1629
1630                 find_library(
1631                           <VAR>
1632                           name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1633                           [HINTS path1 [path2 ... ENV var]]
1634                           [PATHS path1 [path2 ... ENV var]]
1635                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
1636                           [DOC "cache documentation string"]
1637                           [NO_DEFAULT_PATH]
1638                           [NO_CMAKE_ENVIRONMENT_PATH]
1639                           [NO_CMAKE_PATH]
1640                           [NO_SYSTEM_ENVIRONMENT_PATH]
1641                           [NO_CMAKE_SYSTEM_PATH]
1642                           [CMAKE_FIND_ROOT_PATH_BOTH |
1643                            ONLY_CMAKE_FIND_ROOT_PATH |
1644                            NO_CMAKE_FIND_ROOT_PATH]
1645                          )
1646
1647              This  command  is used to find a library. A cache entry named by
1648              <VAR> is created to store the result of this  command.   If  the
1649              library  is  found  the result is stored in the variable and the
1650              search will not be repeated unless the variable is cleared.   If
1651              nothing  is  found,  the  result will be <VAR>-NOTFOUND, and the
1652              search will be attempted again the  next  time  find_library  is
1653              invoked with the same variable.  The name of the library that is
1654              searched for is specified by the names listed  after  the  NAMES
1655              argument.    Additional  search locations can be specified after
1656              the PATHS argument.  If ENV var is found in the HINTS  or  PATHS
1657              section  the environment variable var will be read and converted
1658              from a system environment variable to  a  cmake  style  list  of
1659              paths.   For  example ENV PATH would be a way to list the system
1660              path variable. The argument after DOC will be used for the docu‐
1661              mentation  string  in  the cache.  PATH_SUFFIXES specifies addi‐
1662              tional subdirectories to check below each search path.
1663
1664
1665              If NO_DEFAULT_PATH is specified, then no  additional  paths  are
1666              added  to  the  search. If NO_DEFAULT_PATH is not specified, the
1667              search process is as follows:
1668
1669
1670              1. Search paths specified  in  cmake-specific  cache  variables.
1671              These  are  intended  to  be  used  on  the  command line with a
1672              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
1673
1674
1675                 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1676                 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1677                 CMAKE_LIBRARY_PATH
1678                 CMAKE_FRAMEWORK_PATH
1679
1680              2. Search paths specified in  cmake-specific  environment  vari‐
1681              ables.  These are intended to be set in the user's shell config‐
1682              uration.  This can be skipped  if  NO_CMAKE_ENVIRONMENT_PATH  is
1683              passed.
1684
1685
1686                 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1687                 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1688                 CMAKE_LIBRARY_PATH
1689                 CMAKE_FRAMEWORK_PATH
1690
1691              3. Search the paths specified by the HINTS option.  These should
1692              be paths computed by system introspection, such as a  hint  pro‐
1693              vided by the location of another item already found.  Hard-coded
1694              guesses should be specified with the PATHS option.
1695
1696
1697              4. Search the standard system environment variables. This can be
1698              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1699
1700
1701                 PATH
1702                 LIB
1703
1704              5.  Search cmake variables defined in the Platform files for the
1705              current system.  This can be skipped if NO_CMAKE_SYSTEM_PATH  is
1706              passed.
1707
1708
1709                 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1710                 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1711                 CMAKE_SYSTEM_LIBRARY_PATH
1712                 CMAKE_SYSTEM_FRAMEWORK_PATH
1713
1714              6.  Search  the  paths  specified  by the PATHS option or in the
1715              short-hand  version  of  the  command.   These   are   typically
1716              hard-coded guesses.
1717
1718
1719              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1720              able    CMAKE_FIND_FRAMEWORK can be set to empty or one  of  the
1721              following:
1722
1723
1724                 "FIRST"  - Try to find frameworks before standard
1725                            libraries or headers. This is the default on Darwin.
1726                 "LAST"   - Try to find frameworks after standard
1727                            libraries or headers.
1728                 "ONLY"   - Only try to find frameworks.
1729                 "NEVER" - Never try to find frameworks.
1730
1731              On  Darwin  or  systems supporting OS X Application Bundles, the
1732              cmake variable CMAKE_FIND_APPBUNDLE can be set to empty  or  one
1733              of the following:
1734
1735
1736                 "FIRST"  - Try to find application bundles before standard
1737                            programs. This is the default on Darwin.
1738                 "LAST"   - Try to find application bundles after standard
1739                            programs.
1740                 "ONLY"   - Only try to find application bundles.
1741                 "NEVER" - Never try to find application bundles.
1742
1743              The  CMake  variable  CMAKE_FIND_ROOT_PATH specifies one or more
1744              directories to be prepended to  all  other  search  directories.
1745              This  effectively "re-roots" the entire search under given loca‐
1746              tions. By default it is empty.  It  is  especially  useful  when
1747              cross-compiling  to  point  to  the root directory of the target
1748              environment and CMake will search there too. By default at first
1749              the  directories  listed  in  CMAKE_FIND_ROOT_PATH  and then the
1750              non-rooted directories will be searched.  The  default  behavior
1751              can  be  adjusted  by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
1752              This behavior can be manually overridden on a per-call basis. By
1753              using  CMAKE_FIND_ROOT_PATH_BOTH  the  search  order  will be as
1754              described  above.  If  NO_CMAKE_FIND_ROOT_PATH  is   used   then
1755              CMAKE_FIND_ROOT_PATH      will      not      be     used.     If
1756              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1757              tories will be searched.
1758
1759
1760              The  default  search  order  is  designed to be most-specific to
1761              least-specific for common use cases.  Projects may override  the
1762              order by simply calling the command multiple times and using the
1763              NO_* options:
1764
1765
1766                 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1767                 find_library(<VAR> NAMES name)
1768
1769              Once one of the calls succeeds the result variable will  be  set
1770              and stored in the cache so that no call will search again.
1771
1772
1773              When  more than one value is given to the NAMES option this com‐
1774              mand by default will consider one name  at  a  time  and  search
1775              every  directory  for  it.   The NAMES_PER_DIR option tells this
1776              command to consider one directory at a time and search  for  all
1777              names in it.
1778
1779
1780              If the library found is a framework, then VAR will be set to the
1781              full path to the framework <fullPath>/A.framework. When  a  full
1782              path  to  a  framework  is  used  as a library, CMake will use a
1783              -framework A, and a -F<fullPath> to link the  framework  to  the
1784              target.
1785
1786
1787              If  the  global property FIND_LIBRARY_USE_LIB64_PATHS is set all
1788              search paths will be tested as normal, with "64/" appended,  and
1789              with all matches of "lib/" replaced with "lib64/". This property
1790              is automatically set for the platforms that are known to need it
1791              if  at  least one of the languages supported by the PROJECT com‐
1792              mand is enabled.
1793
1794
1795       find_package
1796              Load settings for an external project.
1797
1798                find_package(<package> [version] [EXACT] [QUIET] [MODULE]
1799                             [REQUIRED] [[COMPONENTS] [components...]]
1800                             [OPTIONAL_COMPONENTS components...]
1801                             [NO_POLICY_SCOPE])
1802
1803              Finds and loads  settings  from  an  external  project.   <pack‐
1804              age>_FOUND  will  be  set  to  indicate  whether the package was
1805              found.  When the package is found  package-specific  information
1806              is provided through variables and imported targets documented by
1807              the package itself.  The QUIET option disables messages  if  the
1808              package  cannot be found.  The MODULE option disables the second
1809              signature documented below.  The REQUIRED option stops  process‐
1810              ing with an error message if the package cannot be found.
1811
1812
1813              A  package-specific  list  of  required components may be listed
1814              after the COMPONENTS option (or after  the  REQUIRED  option  if
1815              present).   Additional  optional  components may be listed after
1816              OPTIONAL_COMPONENTS.  Available components and  their  influence
1817              on  whether  a  package is considered to be found are defined by
1818              the target package.
1819
1820
1821              The [version] argument requests a version with which the package
1822              found       should       be      compatible      (format      is
1823              major[.minor[.patch[.tweak]]]).  The EXACT option requests  that
1824              the  version  be matched exactly.  If no [version] and/or compo‐
1825              nent list is given to a recursive invocation inside a  find-mod‐
1826              ule,  the  corresponding  arguments  are forwarded automatically
1827              from the outer call (including the EXACT  flag  for  [version]).
1828              Version support is currently provided only on a package-by-pack‐
1829              age basis (details below).
1830
1831
1832              User code should generally look for  packages  using  the  above
1833              simple  signature.   The remainder of this command documentation
1834              specifies the full command signature and details of  the  search
1835              process.  Project maintainers wishing to provide a package to be
1836              found by this command are encouraged to read on.
1837
1838
1839              The command has two modes by which  it  searches  for  packages:
1840              "Module"  mode and "Config" mode.  Module mode is available when
1841              the command is invoked with the above reduced signature.   CMake
1842              searches   for   a  file  called  "Find<package>.cmake"  in  the
1843              CMAKE_MODULE_PATH followed by the CMake  installation.   If  the
1844              file is found, it is read and processed by CMake.  It is respon‐
1845              sible for finding the package, checking the version, and produc‐
1846              ing  any  needed messages.  Many find-modules provide limited or
1847              no support for versioning; check the module  documentation.   If
1848              no  module  is found and the MODULE option is not given the com‐
1849              mand proceeds to Config mode.
1850
1851
1852              The complete Config mode command signature is:
1853
1854
1855                find_package(<package> [version] [EXACT] [QUIET]
1856                             [REQUIRED] [[COMPONENTS] [components...]]
1857                             [CONFIG|NO_MODULE]
1858                             [NO_POLICY_SCOPE]
1859                             [NAMES name1 [name2 ...]]
1860                             [CONFIGS config1 [config2 ...]]
1861                             [HINTS path1 [path2 ... ]]
1862                             [PATHS path1 [path2 ... ]]
1863                             [PATH_SUFFIXES suffix1 [suffix2 ...]]
1864                             [NO_DEFAULT_PATH]
1865                             [NO_CMAKE_ENVIRONMENT_PATH]
1866                             [NO_CMAKE_PATH]
1867                             [NO_SYSTEM_ENVIRONMENT_PATH]
1868                             [NO_CMAKE_PACKAGE_REGISTRY]
1869                             [NO_CMAKE_BUILDS_PATH]
1870                             [NO_CMAKE_SYSTEM_PATH]
1871                             [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1872                             [CMAKE_FIND_ROOT_PATH_BOTH |
1873                              ONLY_CMAKE_FIND_ROOT_PATH |
1874                              NO_CMAKE_FIND_ROOT_PATH])
1875
1876              The CONFIG option may be used to skip Module mode explicitly and
1877              switch  to  Config  mode.   It is synonymous to using NO_MODULE.
1878              Config mode is also implied by use of options not  specified  in
1879              the reduced signature.
1880
1881
1882              Config  mode attempts to locate a configuration file provided by
1883              the package to be found.  A cache entry called <package>_DIR  is
1884              created  to  hold the directory containing the file.  By default
1885              the command searches for a package with the name <package>.   If
1886              the  NAMES  option  is  given  the  names  following it are used
1887              instead of <package>.  The command searches for  a  file  called
1888              "<name>Config.cmake"   or  "<lower-case-name>-config.cmake"  for
1889              each name specified.  A replacement set of  possible  configura‐
1890              tion  file  names  may  be  given using the CONFIGS option.  The
1891              search procedure is specified below.  Once found, the configura‐
1892              tion  file  is  read  and processed by CMake.  Since the file is
1893              provided by the package it already knows the location of package
1894              contents.   The full path to the configuration file is stored in
1895              the cmake variable <package>_CONFIG.
1896
1897
1898              All configuration files which  have  been  considered  by  CMake
1899              while  searching  for  an  installation  of  the package with an
1900              appropriate version are stored  in  the  cmake  variable  <pack‐
1901              age>_CONSIDERED_CONFIGS,   the  associated  versions  in  <pack‐
1902              age>_CONSIDERED_VERSIONS.
1903
1904
1905              If the package configuration file cannot  be  found  CMake  will
1906              generate  an error describing the problem unless the QUIET argu‐
1907              ment is specified.  If REQUIRED is specified and the package  is
1908              not  found  a  fatal  error  is generated and the configure step
1909              stops executing.  If <package>_DIR has been set to  a  directory
1910              not  containing  a  configuration  file CMake will ignore it and
1911              search from scratch.
1912
1913
1914              When the [version] argument is given Config mode will only  find
1915              a  version  of  the  package  that claims compatibility with the
1916              requested version (format is major[.minor[.patch[.tweak]]]).  If
1917              the EXACT option is given only a version of the package claiming
1918              an exact match of the requested version  may  be  found.   CMake
1919              does  not  establish  any  convention for the meaning of version
1920              numbers.  Package version numbers are checked by "version" files
1921              provided  by  the  packages themselves.  For a candidate package
1922              configuration file "<config-file>.cmake" the corresponding  ver‐
1923              sion  file  is  located  next  to  it  and  named  either "<con‐
1924              fig-file>-version.cmake" or "<config-file>Version.cmake".  If no
1925              such  version  file  is available then the configuration file is
1926              assumed to not be compatible  with  any  requested  version.   A
1927              basic  version file containing generic version matching code can
1928              be created using the  macro  write_basic_package_version_file(),
1929              see  its documentation for more details.  When a version file is
1930              found it is loaded to check the requested version  number.   The
1931              version  file is loaded in a nested scope in which the following
1932              variables have been defined:
1933
1934
1935                PACKAGE_FIND_NAME          = the <package> name
1936                PACKAGE_FIND_VERSION       = full requested version string
1937                PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
1938                PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
1939                PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
1940                PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
1941                PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
1942
1943              The version file checks whether it satisfies the requested  ver‐
1944              sion and sets these variables:
1945
1946
1947                PACKAGE_VERSION            = full provided version string
1948                PACKAGE_VERSION_EXACT      = true if version is exact match
1949                PACKAGE_VERSION_COMPATIBLE = true if version is compatible
1950                PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
1951
1952              These  variables  are  checked  by  the  find_package command to
1953              determine whether the configuration file provides an  acceptable
1954              version.   They  are  not  available after the find_package call
1955              returns.  If the version is acceptable the  following  variables
1956              are set:
1957
1958
1959                <package>_VERSION       = full provided version string
1960                <package>_VERSION_MAJOR = major version if provided, else 0
1961                <package>_VERSION_MINOR = minor version if provided, else 0
1962                <package>_VERSION_PATCH = patch version if provided, else 0
1963                <package>_VERSION_TWEAK = tweak version if provided, else 0
1964                <package>_VERSION_COUNT = number of version components, 0 to 4
1965
1966              and  the  corresponding  package  configuration  file is loaded.
1967              When multiple package configuration files  are  available  whose
1968              version  files claim compatibility with the version requested it
1969              is unspecified which one is  chosen.   No  attempt  is  made  to
1970              choose a highest or closest version number.
1971
1972
1973              Config  mode  provides  an elaborate interface and search proce‐
1974              dure.  Much of the interface is provided  for  completeness  and
1975              for  use internally by find-modules loaded by Module mode.  Most
1976              user code should simply call
1977
1978
1979                find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1980
1981              in order to find a package.  Package maintainers providing CMake
1982              package  configuration  files are encouraged to name and install
1983              them such that the procedure outlined below will find them with‐
1984              out requiring use of additional options.
1985
1986
1987              CMake constructs a set of possible installation prefixes for the
1988              package.  Under each prefix several directories are searched for
1989              a  configuration  file.   The  tables below show the directories
1990              searched.  Each entry is meant for installation trees  following
1991              Windows (W), UNIX (U), or Apple (A) conventions.
1992
1993
1994                <prefix>/                                               (W)
1995                <prefix>/(cmake|CMake)/                                 (W)
1996                <prefix>/<name>*/                                       (W)
1997                <prefix>/<name>*/(cmake|CMake)/                         (W)
1998                <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/          (U)
1999                <prefix>/(lib/<arch>|lib|share)/<name>*/                (U)
2000                <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (U)
2001
2002              On  systems  supporting  OS X Frameworks and Application Bundles
2003              the following directories are searched for frameworks or bundles
2004              containing a configuration file:
2005
2006
2007                <prefix>/<name>.framework/Resources/                    (A)
2008                <prefix>/<name>.framework/Resources/CMake/              (A)
2009                <prefix>/<name>.framework/Versions/*/Resources/         (A)
2010                <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
2011                <prefix>/<name>.app/Contents/Resources/                 (A)
2012                <prefix>/<name>.app/Contents/Resources/CMake/           (A)
2013
2014              In  all cases the <name> is treated as case-insensitive and cor‐
2015              responds to any of the names specified (<package> or names given
2016              by    NAMES).     Paths   with   lib/<arch>   are   enabled   if
2017              CMAKE_LIBRARY_ARCHITECTURE is set.  If PATH_SUFFIXES  is  speci‐
2018              fied  the  suffixes  are  appended  to each (W) or (U) directory
2019              entry one-by-one.
2020
2021
2022              This set of directories is intended to work in cooperation  with
2023              projects  that provide configuration files in their installation
2024              trees.  Directories above  marked  with  (W)  are  intended  for
2025              installations  on  Windows where the prefix may point at the top
2026              of an application's installation directory.  Those  marked  with
2027              (U)  are  intended for installations on UNIX platforms where the
2028              prefix is shared by multiple packages.  This is merely a conven‐
2029              tion,  so  all (W) and (U) directories are still searched on all
2030              platforms.  Directories marked with (A) are intended for instal‐
2031              lations    on    Apple    platforms.     The   cmake   variables
2032              CMAKE_FIND_FRAMEWORK  and  CMAKE_FIND_APPBUNDLE  determine   the
2033              order of preference as specified below.
2034
2035
2036              The  set  of installation prefixes is constructed using the fol‐
2037              lowing steps.  If NO_DEFAULT_PATH is specified all NO_*  options
2038              are enabled.
2039
2040
2041              1.  Search  paths  specified  in cmake-specific cache variables.
2042              These are intended to  be  used  on  the  command  line  with  a
2043              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
2044
2045
2046                 CMAKE_PREFIX_PATH
2047                 CMAKE_FRAMEWORK_PATH
2048                 CMAKE_APPBUNDLE_PATH
2049
2050              2.  Search  paths  specified in cmake-specific environment vari‐
2051              ables.  These are intended to be set in the user's shell config‐
2052              uration.   This  can  be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2053              passed.
2054
2055
2056                 <package>_DIR
2057                 CMAKE_PREFIX_PATH
2058                 CMAKE_FRAMEWORK_PATH
2059                 CMAKE_APPBUNDLE_PATH
2060
2061              3. Search paths specified by the HINTS option.  These should  be
2062              paths  computed by system introspection, such as a hint provided
2063              by the location  of  another  item  already  found.   Hard-coded
2064              guesses should be specified with the PATHS option.
2065
2066
2067              4. Search the standard system environment variables. This can be
2068              skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed.   Path  entries
2069              ending in "/bin" or "/sbin" are automatically converted to their
2070              parent directories.
2071
2072
2073                 PATH
2074
2075              5. Search project build trees recently  configured  in  a  CMake
2076              GUI.  This can be skipped if NO_CMAKE_BUILDS_PATH is passed.  It
2077              is intended for the case when a user is building multiple depen‐
2078              dent projects one after another.
2079
2080
2081              6. Search paths stored in the CMake user package registry.  This
2082              can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed.  On  Win‐
2083              dows a <package> may appear under registry key
2084
2085
2086                HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
2087
2088              as  a  REG_SZ  value,  with  arbitrary  name, that specifies the
2089              directory containing the package configuration  file.   On  UNIX
2090              platforms a <package> may appear under the directory
2091
2092
2093                ~/.cmake/packages/<package>
2094
2095              as  a  file,  with  arbitrary  name, whose content specifies the
2096              directory containing the package configuration  file.   See  the
2097              export(PACKAGE)  command to create user package registry entries
2098              for project build trees.
2099
2100
2101              7. Search cmake variables defined in the Platform files for  the
2102              current  system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is
2103              passed.
2104
2105
2106                 CMAKE_SYSTEM_PREFIX_PATH
2107                 CMAKE_SYSTEM_FRAMEWORK_PATH
2108                 CMAKE_SYSTEM_APPBUNDLE_PATH
2109
2110              8. Search paths stored in the  CMake  system  package  registry.
2111              This  can  be  skipped  if  NO_CMAKE_SYSTEM_PACKAGE_REGISTRY  is
2112              passed.  On Windows a <package> may appear under registry key
2113
2114
2115                HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
2116
2117              as a REG_SZ value,  with  arbitrary  name,  that  specifies  the
2118              directory  containing  the package configuration file.  There is
2119              no system package registry on non-Windows platforms.
2120
2121
2122              9. Search paths specified by the PATHS option.  These are  typi‐
2123              cally hard-coded guesses.
2124
2125
2126              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2127              able    CMAKE_FIND_FRAMEWORK can be set to empty or one  of  the
2128              following:
2129
2130
2131                 "FIRST"  - Try to find frameworks before standard
2132                            libraries or headers. This is the default on Darwin.
2133                 "LAST"   - Try to find frameworks after standard
2134                            libraries or headers.
2135                 "ONLY"   - Only try to find frameworks.
2136                 "NEVER" - Never try to find frameworks.
2137
2138              On  Darwin  or  systems supporting OS X Application Bundles, the
2139              cmake variable CMAKE_FIND_APPBUNDLE can be set to empty  or  one
2140              of the following:
2141
2142
2143                 "FIRST"  - Try to find application bundles before standard
2144                            programs. This is the default on Darwin.
2145                 "LAST"   - Try to find application bundles after standard
2146                            programs.
2147                 "ONLY"   - Only try to find application bundles.
2148                 "NEVER" - Never try to find application bundles.
2149
2150              The  CMake  variable  CMAKE_FIND_ROOT_PATH specifies one or more
2151              directories to be prepended to  all  other  search  directories.
2152              This  effectively "re-roots" the entire search under given loca‐
2153              tions. By default it is empty.  It  is  especially  useful  when
2154              cross-compiling  to  point  to  the root directory of the target
2155              environment and CMake will search there too. By default at first
2156              the  directories  listed  in  CMAKE_FIND_ROOT_PATH  and then the
2157              non-rooted directories will be searched.  The  default  behavior
2158              can  be  adjusted  by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
2159              This behavior can be manually overridden on a per-call basis. By
2160              using  CMAKE_FIND_ROOT_PATH_BOTH  the  search  order  will be as
2161              described  above.  If  NO_CMAKE_FIND_ROOT_PATH  is   used   then
2162              CMAKE_FIND_ROOT_PATH      will      not      be     used.     If
2163              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2164              tories will be searched.
2165
2166
2167              The  default  search  order  is  designed to be most-specific to
2168              least-specific for common use cases.  Projects may override  the
2169              order by simply calling the command multiple times and using the
2170              NO_* options:
2171
2172
2173                 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
2174                 find_package(<package>)
2175
2176              Once one of the calls succeeds the result variable will  be  set
2177              and stored in the cache so that no call will search again.
2178
2179
2180              Every  non-REQUIRED  find_package() call can be disabled by set‐
2181              ting the variable CMAKE_DISABLE_FIND_PACKAGE_<package> to  TRUE.
2182              See  the documentation for the CMAKE_DISABLE_FIND_PACKAGE_<pack‐
2183              age> variable for more information.
2184
2185
2186              When  loading  a  find  module  or  package  configuration  file
2187              find_package  defines variables to provide information about the
2188              call arguments (and restores their original state before return‐
2189              ing):
2190
2191
2192               <package>_FIND_REQUIRED      = true if REQUIRED option was given
2193               <package>_FIND_QUIETLY       = true if QUIET option was given
2194               <package>_FIND_VERSION       = full requested version string
2195               <package>_FIND_VERSION_MAJOR = major version if requested, else 0
2196               <package>_FIND_VERSION_MINOR = minor version if requested, else 0
2197               <package>_FIND_VERSION_PATCH = patch version if requested, else 0
2198               <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0
2199               <package>_FIND_VERSION_COUNT = number of version components, 0 to 4
2200               <package>_FIND_VERSION_EXACT = true if EXACT option was given
2201               <package>_FIND_COMPONENTS    = list of requested components
2202               <package>_FIND_REQUIRED_<c>  = true if component <c> is required
2203                                              false if component <c> is optional
2204
2205              In  Module  mode  the loaded find module is responsible to honor
2206              the request detailed by these variables; see the find module for
2207              details.   In  Config mode find_package handles REQUIRED, QUIET,
2208              and version options automatically but leaves it to  the  package
2209              configuration  file  to  handle  components  in a way that makes
2210              sense for the package.  The package configuration file  may  set
2211              <package>_FOUND  to  false  to  tell find_package that component
2212              requirements are not satisfied.
2213
2214
2215              See the cmake_policy() command documentation for  discussion  of
2216              the NO_POLICY_SCOPE option.
2217
2218
2219       find_path
2220              Find the directory containing a file.
2221
2222                 find_path(<VAR> name1 [path1 path2 ...])
2223
2224              This  is the short-hand signature for the command that is suffi‐
2225              cient in many cases.  It is the same  as  find_path(<VAR>  name1
2226              [PATHS path1 path2 ...])
2227
2228
2229                 find_path(
2230                           <VAR>
2231                           name | NAMES name1 [name2 ...]
2232                           [HINTS path1 [path2 ... ENV var]]
2233                           [PATHS path1 [path2 ... ENV var]]
2234                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
2235                           [DOC "cache documentation string"]
2236                           [NO_DEFAULT_PATH]
2237                           [NO_CMAKE_ENVIRONMENT_PATH]
2238                           [NO_CMAKE_PATH]
2239                           [NO_SYSTEM_ENVIRONMENT_PATH]
2240                           [NO_CMAKE_SYSTEM_PATH]
2241                           [CMAKE_FIND_ROOT_PATH_BOTH |
2242                            ONLY_CMAKE_FIND_ROOT_PATH |
2243                            NO_CMAKE_FIND_ROOT_PATH]
2244                          )
2245
2246              This  command  is  used to find a directory containing the named
2247              file. A cache entry named by  <VAR>  is  created  to  store  the
2248              result of this command.  If the file in a directory is found the
2249              result is stored in the variable and  the  search  will  not  be
2250              repeated  unless  the variable is cleared.  If nothing is found,
2251              the result will  be  <VAR>-NOTFOUND,  and  the  search  will  be
2252              attempted again the next time find_path is invoked with the same
2253              variable.  The name of the file in a directory that is  searched
2254              for  is  specified by the names listed after the NAMES argument.
2255              Additional search locations can be  specified  after  the  PATHS
2256              argument.  If ENV var is found in the HINTS or PATHS section the
2257              environment variable var will be read and converted from a  sys‐
2258              tem  environment  variable  to a cmake style list of paths.  For
2259              example ENV PATH would be a way to list the  system  path  vari‐
2260              able.  The argument after DOC will be used for the documentation
2261              string in the cache.  PATH_SUFFIXES specifies additional  subdi‐
2262              rectories to check below each search path.
2263
2264
2265              If  NO_DEFAULT_PATH  is  specified, then no additional paths are
2266              added to the search. If NO_DEFAULT_PATH is  not  specified,  the
2267              search process is as follows:
2268
2269
2270              1.  Search  paths  specified  in cmake-specific cache variables.
2271              These are intended to  be  used  on  the  command  line  with  a
2272              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
2273
2274
2275                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2276                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2277                 CMAKE_INCLUDE_PATH
2278                 CMAKE_FRAMEWORK_PATH
2279
2280              2.  Search  paths  specified in cmake-specific environment vari‐
2281              ables.  These are intended to be set in the user's shell config‐
2282              uration.   This  can  be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2283              passed.
2284
2285
2286                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2287                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2288                 CMAKE_INCLUDE_PATH
2289                 CMAKE_FRAMEWORK_PATH
2290
2291              3. Search the paths specified by the HINTS option.  These should
2292              be  paths  computed by system introspection, such as a hint pro‐
2293              vided by the location of another item already found.  Hard-coded
2294              guesses should be specified with the PATHS option.
2295
2296
2297              4. Search the standard system environment variables. This can be
2298              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2299
2300
2301                 PATH
2302                 INCLUDE
2303
2304              5. Search cmake variables defined in the Platform files for  the
2305              current  system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is
2306              passed.
2307
2308
2309                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2310                 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2311                 CMAKE_SYSTEM_INCLUDE_PATH
2312                 CMAKE_SYSTEM_FRAMEWORK_PATH
2313
2314              6. Search the paths specified by the  PATHS  option  or  in  the
2315              short-hand   version   of  the  command.   These  are  typically
2316              hard-coded guesses.
2317
2318
2319              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2320              able     CMAKE_FIND_FRAMEWORK  can be set to empty or one of the
2321              following:
2322
2323
2324                 "FIRST"  - Try to find frameworks before standard
2325                            libraries or headers. This is the default on Darwin.
2326                 "LAST"   - Try to find frameworks after standard
2327                            libraries or headers.
2328                 "ONLY"   - Only try to find frameworks.
2329                 "NEVER" - Never try to find frameworks.
2330
2331              On Darwin or systems supporting OS X  Application  Bundles,  the
2332              cmake  variable  CMAKE_FIND_APPBUNDLE can be set to empty or one
2333              of the following:
2334
2335
2336                 "FIRST"  - Try to find application bundles before standard
2337                            programs. This is the default on Darwin.
2338                 "LAST"   - Try to find application bundles after standard
2339                            programs.
2340                 "ONLY"   - Only try to find application bundles.
2341                 "NEVER" - Never try to find application bundles.
2342
2343              The CMake variable CMAKE_FIND_ROOT_PATH specifies  one  or  more
2344              directories  to  be  prepended  to all other search directories.
2345              This effectively "re-roots" the entire search under given  loca‐
2346              tions.  By  default  it  is  empty. It is especially useful when
2347              cross-compiling to point to the root  directory  of  the  target
2348              environment and CMake will search there too. By default at first
2349              the directories listed  in  CMAKE_FIND_ROOT_PATH  and  then  the
2350              non-rooted  directories  will  be searched. The default behavior
2351              can be adjusted  by  setting  CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2352              This behavior can be manually overridden on a per-call basis. By
2353              using CMAKE_FIND_ROOT_PATH_BOTH the  search  order  will  be  as
2354              described   above.   If  NO_CMAKE_FIND_ROOT_PATH  is  used  then
2355              CMAKE_FIND_ROOT_PATH     will     not      be      used.      If
2356              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2357              tories will be searched.
2358
2359
2360              The default search order is  designed  to  be  most-specific  to
2361              least-specific  for common use cases.  Projects may override the
2362              order by simply calling the command multiple times and using the
2363              NO_* options:
2364
2365
2366                 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2367                 find_path(<VAR> NAMES name)
2368
2369              Once  one  of the calls succeeds the result variable will be set
2370              and stored in the cache so that no call will search again.
2371
2372
2373              When searching for frameworks,  if  the  file  is  specified  as
2374              A/b.h, then the framework search will look for A.framework/Head‐
2375              ers/b.h. If that is found the path will be set to  the  path  to
2376              the  framework. CMake will convert this to the correct -F option
2377              to include the file.
2378
2379
2380       find_program
2381              Find an executable program.
2382
2383                 find_program(<VAR> name1 [path1 path2 ...])
2384
2385              This is the short-hand signature for the command that is  suffi‐
2386              cient in many cases.  It is the same as find_program(<VAR> name1
2387              [PATHS path1 path2 ...])
2388
2389
2390                 find_program(
2391                           <VAR>
2392                           name | NAMES name1 [name2 ...]
2393                           [HINTS path1 [path2 ... ENV var]]
2394                           [PATHS path1 [path2 ... ENV var]]
2395                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
2396                           [DOC "cache documentation string"]
2397                           [NO_DEFAULT_PATH]
2398                           [NO_CMAKE_ENVIRONMENT_PATH]
2399                           [NO_CMAKE_PATH]
2400                           [NO_SYSTEM_ENVIRONMENT_PATH]
2401                           [NO_CMAKE_SYSTEM_PATH]
2402                           [CMAKE_FIND_ROOT_PATH_BOTH |
2403                            ONLY_CMAKE_FIND_ROOT_PATH |
2404                            NO_CMAKE_FIND_ROOT_PATH]
2405                          )
2406
2407              This command is used to find a program. A cache entry  named  by
2408              <VAR>  is  created  to store the result of this command.  If the
2409              program is found the result is stored in the  variable  and  the
2410              search  will not be repeated unless the variable is cleared.  If
2411              nothing is found, the result will  be  <VAR>-NOTFOUND,  and  the
2412              search  will  be  attempted  again the next time find_program is
2413              invoked with the same variable.  The name of the program that is
2414              searched  for  is  specified by the names listed after the NAMES
2415              argument.   Additional search locations can be  specified  after
2416              the  PATHS  argument.  If ENV var is found in the HINTS or PATHS
2417              section the environment variable var will be read and  converted
2418              from  a  system  environment  variable  to a cmake style list of
2419              paths.  For example ENV PATH would be a way to list  the  system
2420              path variable. The argument after DOC will be used for the docu‐
2421              mentation string in the cache.   PATH_SUFFIXES  specifies  addi‐
2422              tional subdirectories to check below each search path.
2423
2424
2425              If  NO_DEFAULT_PATH  is  specified, then no additional paths are
2426              added to the search. If NO_DEFAULT_PATH is  not  specified,  the
2427              search process is as follows:
2428
2429
2430              1.  Search  paths  specified  in cmake-specific cache variables.
2431              These are intended to  be  used  on  the  command  line  with  a
2432              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
2433
2434
2435                 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2436                 CMAKE_PROGRAM_PATH
2437                 CMAKE_APPBUNDLE_PATH
2438
2439              2.  Search  paths  specified in cmake-specific environment vari‐
2440              ables.  These are intended to be set in the user's shell config‐
2441              uration.   This  can  be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2442              passed.
2443
2444
2445                 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2446                 CMAKE_PROGRAM_PATH
2447                 CMAKE_APPBUNDLE_PATH
2448
2449              3. Search the paths specified by the HINTS option.  These should
2450              be  paths  computed by system introspection, such as a hint pro‐
2451              vided by the location of another item already found.  Hard-coded
2452              guesses should be specified with the PATHS option.
2453
2454
2455              4. Search the standard system environment variables. This can be
2456              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2457
2458
2459                 PATH
2460
2461
2462              5. Search cmake variables defined in the Platform files for  the
2463              current  system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is
2464              passed.
2465
2466
2467                 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2468                 CMAKE_SYSTEM_PROGRAM_PATH
2469                 CMAKE_SYSTEM_APPBUNDLE_PATH
2470
2471              6. Search the paths specified by the  PATHS  option  or  in  the
2472              short-hand   version   of  the  command.   These  are  typically
2473              hard-coded guesses.
2474
2475
2476              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2477              able     CMAKE_FIND_FRAMEWORK  can be set to empty or one of the
2478              following:
2479
2480
2481                 "FIRST"  - Try to find frameworks before standard
2482                            libraries or headers. This is the default on Darwin.
2483                 "LAST"   - Try to find frameworks after standard
2484                            libraries or headers.
2485                 "ONLY"   - Only try to find frameworks.
2486                 "NEVER" - Never try to find frameworks.
2487
2488              On Darwin or systems supporting OS X  Application  Bundles,  the
2489              cmake  variable  CMAKE_FIND_APPBUNDLE can be set to empty or one
2490              of the following:
2491
2492
2493                 "FIRST"  - Try to find application bundles before standard
2494                            programs. This is the default on Darwin.
2495                 "LAST"   - Try to find application bundles after standard
2496                            programs.
2497                 "ONLY"   - Only try to find application bundles.
2498                 "NEVER" - Never try to find application bundles.
2499
2500              The CMake variable CMAKE_FIND_ROOT_PATH specifies  one  or  more
2501              directories  to  be  prepended  to all other search directories.
2502              This effectively "re-roots" the entire search under given  loca‐
2503              tions.  By  default  it  is  empty. It is especially useful when
2504              cross-compiling to point to the root  directory  of  the  target
2505              environment and CMake will search there too. By default at first
2506              the directories listed  in  CMAKE_FIND_ROOT_PATH  and  then  the
2507              non-rooted  directories  will  be searched. The default behavior
2508              can be adjusted  by  setting  CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
2509              This behavior can be manually overridden on a per-call basis. By
2510              using CMAKE_FIND_ROOT_PATH_BOTH the  search  order  will  be  as
2511              described   above.   If  NO_CMAKE_FIND_ROOT_PATH  is  used  then
2512              CMAKE_FIND_ROOT_PATH     will     not      be      used.      If
2513              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2514              tories will be searched.
2515
2516
2517              The default search order is  designed  to  be  most-specific  to
2518              least-specific  for common use cases.  Projects may override the
2519              order by simply calling the command multiple times and using the
2520              NO_* options:
2521
2522
2523                 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2524                 find_program(<VAR> NAMES name)
2525
2526              Once  one  of the calls succeeds the result variable will be set
2527              and stored in the cache so that no call will search again.
2528
2529
2530       fltk_wrap_ui
2531              Create FLTK user interfaces Wrappers.
2532
2533                fltk_wrap_ui(resultingLibraryName source1
2534                             source2 ... sourceN )
2535
2536              Produce .h and .cxx files for all the .fl and .fld files listed.
2537              The  resulting  .h  and  .cxx  files will be added to a variable
2538              named resultingLibraryName_FLTK_UI_SRCS which should be added to
2539              your library.
2540
2541
2542       foreach
2543              Evaluate a group of commands for each value in a list.
2544
2545                foreach(loop_var arg1 arg2 ...)
2546                  COMMAND1(ARGS ...)
2547                  COMMAND2(ARGS ...)
2548                  ...
2549                endforeach(loop_var)
2550
2551              All  commands  between  foreach  and the matching endforeach are
2552              recorded without being invoked.  Once the endforeach  is  evalu‐
2553              ated,  the  recorded  list  of commands is invoked once for each
2554              argument listed in the original foreach  command.   Before  each
2555              iteration  of  the  loop "${loop_var}" will be set as a variable
2556              with the current value in the list.
2557
2558
2559                foreach(loop_var RANGE total)
2560                foreach(loop_var RANGE start stop [step])
2561
2562              Foreach can also iterate over  a  generated  range  of  numbers.
2563              There are three types of this iteration:
2564
2565
2566              *  When specifying single number, the range will have elements 0
2567              to "total".
2568
2569
2570              * When specifying two numbers, the range will have elements from
2571              the first number to the second number.
2572
2573
2574              *  The  third  optional  number is the increment used to iterate
2575              from the first number to the second number.
2576
2577
2578                foreach(loop_var IN [LISTS [list1 [...]]]
2579                                    [ITEMS [item1 [...]]])
2580
2581              Iterates over a precise list of items.  The LISTS  option  names
2582              list-valued  variables to be traversed, including empty elements
2583              (an empty string is a zero-length list).  The ITEMS option  ends
2584              argument  parsing and includes all arguments following it in the
2585              iteration.
2586
2587
2588       function
2589              Start recording a function for later invocation as a command.
2590
2591                function(<name> [arg1 [arg2 [arg3 ...]]])
2592                  COMMAND1(ARGS ...)
2593                  COMMAND2(ARGS ...)
2594                  ...
2595                endfunction(<name>)
2596
2597              Define a function named <name> that takes arguments  named  arg1
2598              arg2 arg3 (...).  Commands listed after function, but before the
2599              matching endfunction, are not  invoked  until  the  function  is
2600              invoked.  When it is invoked, the commands recorded in the func‐
2601              tion are first modified by replacing formal parameters (${arg1})
2602              with  the arguments passed, and then invoked as normal commands.
2603              In addition to referencing the formal parameters you can  refer‐
2604              ence  the variable ARGC which will be set to the number of argu‐
2605              ments passed into the function as well as ARGV0 ARGV1 ARGV2  ...
2606              which  will  have  the actual values of the arguments passed in.
2607              This facilitates creating  functions  with  optional  arguments.
2608              Additionally  ARGV  holds the list of all arguments given to the
2609              function and ARGN holds the list  of  arguments  past  the  last
2610              expected argument.
2611
2612
2613              A  function  opens  a  new  scope: see set(var PARENT_SCOPE) for
2614              details.
2615
2616
2617              See the cmake_policy() command documentation for the behavior of
2618              policies inside functions.
2619
2620
2621       get_cmake_property
2622              Get a property of the CMake instance.
2623
2624                get_cmake_property(VAR property)
2625
2626              Get  a property from the CMake instance.  The value of the prop‐
2627              erty is stored in the variable VAR.   If  the  property  is  not
2628              found, VAR will be set to "NOTFOUND".  Some supported properties
2629              include: VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and  COM‐
2630              PONENTS.
2631
2632
2633              See also the more general get_property() command.
2634
2635
2636       get_directory_property
2637              Get a property of DIRECTORY scope.
2638
2639                get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2640
2641              Store  a  property of directory scope in the named variable.  If
2642              the property is not defined the empty-string is  returned.   The
2643              DIRECTORY  argument  specifies  another  directory from which to
2644              retrieve the property value.  The specified directory must  have
2645              already been traversed by CMake.
2646
2647
2648                get_directory_property(<variable> [DIRECTORY <dir>]
2649                                       DEFINITION <var-name>)
2650
2651              Get a variable definition from a directory.  This form is useful
2652              to get a variable definition from another directory.
2653
2654
2655              See also the more general get_property() command.
2656
2657
2658       get_filename_component
2659              Get a specific component of a full filename.
2660
2661                get_filename_component(<VAR> <FileName> <COMP> [CACHE])
2662
2663              Set <VAR> to a component of <FileName>, where <COMP> is one of:
2664
2665
2666               DIRECTORY = Directory without file name
2667               NAME      = File name without directory
2668               EXT       = File name longest extension (.b.c from d/a.b.c)
2669               NAME_WE   = File name without directory or longest extension
2670               ABSOLUTE  = Full path to file
2671               REALPATH  = Full path to existing file with symlinks resolved
2672               PATH      = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2673
2674              Paths are returned with forward slashes  and  have  no  trailing
2675              slahes.  The longest file extension is always considered. If the
2676              optional CACHE argument is specified,  the  result  variable  is
2677              added to the cache.
2678
2679
2680                get_filename_component(<VAR> FileName
2681                                       PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2682                                       [CACHE])
2683
2684              The  program in FileName will be found in the system search path
2685              or left as a full path.  If PROGRAM_ARGS is  present  with  PRO‐
2686              GRAM,  then  any  command-line arguments present in the FileName
2687              string are split from the program name and stored in  <ARG_VAR>.
2688              This  is used to separate a program name from its arguments in a
2689              command line string.
2690
2691
2692       get_property
2693              Get a property.
2694
2695                get_property(<variable>
2696                             <GLOBAL             |
2697                              DIRECTORY [dir]    |
2698                              TARGET    <target> |
2699                              SOURCE    <source> |
2700                              TEST      <test>   |
2701                              CACHE     <entry>  |
2702                              VARIABLE>
2703                             PROPERTY <name>
2704                             [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2705
2706              Get one property from one object in a scope.  The first argument
2707              specifies the variable in which to store the result.  The second
2708              argument determines the scope from which to  get  the  property.
2709              It must be one of the following:
2710
2711
2712              GLOBAL scope is unique and does not accept a name.
2713
2714
2715              DIRECTORY  scope  defaults  to the current directory but another
2716              directory (already processed by CMake) may be named by  full  or
2717              relative path.
2718
2719
2720              TARGET scope must name one existing target.
2721
2722
2723              SOURCE scope must name one source file.
2724
2725
2726              TEST scope must name one existing test.
2727
2728
2729              CACHE scope must name one cache entry.
2730
2731
2732              VARIABLE scope is unique and does not accept a name.
2733
2734
2735              The required PROPERTY option is immediately followed by the name
2736              of the property to get.  If the property is  not  set  an  empty
2737              value  is  returned.  If the SET option is given the variable is
2738              set to a boolean value indicating whether the property has  been
2739              set.   If  the  DEFINED option is given the variable is set to a
2740              boolean value indicating whether the property has  been  defined
2741              such  as  with  define_property.  If  BRIEF_DOCS or FULL_DOCS is
2742              given then the variable is set to a string containing documenta‐
2743              tion  for the requested property.  If documentation is requested
2744              for a property that has not been defined NOTFOUND is returned.
2745
2746
2747       get_source_file_property
2748              Get a property for a source file.
2749
2750                get_source_file_property(VAR file property)
2751
2752              Get a property from a source file.  The value of the property is
2753              stored  in  the variable VAR.  If the property is not found, VAR
2754              will be set to "NOTFOUND".  Use  set_source_files_properties  to
2755              set property values.  Source file properties usually control how
2756              the file is built. One property that is always there is LOCATION
2757
2758
2759              See also the more general get_property() command.
2760
2761
2762       get_target_property
2763              Get a property from a target.
2764
2765                get_target_property(VAR target property)
2766
2767              Get a property from a target.   The value  of  the  property  is
2768              stored  in  the variable VAR.  If the property is not found, VAR
2769              will be set to "NOTFOUND".   Use  set_target_properties  to  set
2770              property  values.   Properties are usually used to control how a
2771              target is built, but some query the target instead.   This  com‐
2772              mand  can get properties for any target so far created. The tar‐
2773              gets do not need to be in the current CMakeLists.txt file.
2774
2775
2776              See also the more general get_property() command.
2777
2778
2779       get_test_property
2780              Get a property of the test.
2781
2782                get_test_property(test property VAR)
2783
2784              Get a property from the Test.  The  value  of  the  property  is
2785              stored  in  the variable VAR.  If the property is not found, VAR
2786              will be set to "NOTFOUND". For a list of standard properties you
2787              can type cmake --help-property-list
2788
2789
2790              See also the more general get_property() command.
2791
2792
2793       if     Conditionally execute a group of commands.
2794
2795                if(expression)
2796                  # then section.
2797                  COMMAND1(ARGS ...)
2798                  COMMAND2(ARGS ...)
2799                  ...
2800                elseif(expression2)
2801                  # elseif section.
2802                  COMMAND1(ARGS ...)
2803                  COMMAND2(ARGS ...)
2804                  ...
2805                else(expression)
2806                  # else section.
2807                  COMMAND1(ARGS ...)
2808                  COMMAND2(ARGS ...)
2809                  ...
2810                endif(expression)
2811
2812              Evaluates the given expression.  If the result is true, the com‐
2813              mands in the THEN section are invoked.  Otherwise, the  commands
2814              in  the  else section are invoked.  The elseif and else sections
2815              are optional. You may have multiple elseif  clauses.  Note  that
2816              the  expression  in  the else and endif clause is optional. Long
2817              expressions can be used and there  is  a  traditional  order  of
2818              precedence.  Parenthetical  expressions are evaluated first fol‐
2819              lowed by unary operators such as EXISTS, COMMAND,  and  DEFINED.
2820              Then  any  EQUAL,  LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
2821              MATCHES will be evaluated. Then NOT operators and  finally  AND,
2822              OR operators will be evaluated. Possible expressions are:
2823
2824
2825                if(<constant>)
2826
2827              True  if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2828              ber.  False if the constant is 0, OFF,  NO,  FALSE,  N,  IGNORE,
2829              NOTFOUND,  '', or ends in the suffix '-NOTFOUND'.  Named boolean
2830              constants are case-insensitive.  If the argument is not  one  of
2831              these constants, it is treated as a variable:
2832
2833
2834                if(<variable>)
2835
2836              True  if  the variable is defined to a value that is not a false
2837              constant.  False otherwise.  (Note macro arguments are not vari‐
2838              ables.)
2839
2840
2841                if(NOT <expression>)
2842
2843              True if the expression is not true.
2844
2845
2846                if(<expr1> AND <expr2>)
2847
2848              True if both expressions would be considered true individually.
2849
2850
2851                if(<expr1> OR <expr2>)
2852
2853              True if either expression would be considered true individually.
2854
2855
2856                if(COMMAND command-name)
2857
2858              True  if the given name is a command, macro or function that can
2859              be invoked.
2860
2861
2862                if(POLICY policy-id)
2863
2864              True if the given name  is  an  existing  policy  (of  the  form
2865              CMP<NNNN>).
2866
2867
2868                if(TARGET target-name)
2869
2870              True if the given name is an existing target, built or imported.
2871
2872
2873                if(EXISTS file-name)
2874                if(EXISTS directory-name)
2875
2876              True  if  the  named  file  or  directory  exists.   Behavior is
2877              well-defined only for full paths.
2878
2879
2880                if(file1 IS_NEWER_THAN file2)
2881
2882              True if file1 is newer than file2 or if one  of  the  two  files
2883              doesn't  exist. Behavior is well-defined only for full paths. If
2884              the file time stamps are exactly the same, an IS_NEWER_THAN com‐
2885              parison  returns  true,  so  that any dependent build operations
2886              will occur in the event of a tie.  This  includes  the  case  of
2887              passing the same file name for both file1 and file2.
2888
2889
2890                if(IS_DIRECTORY directory-name)
2891
2892              True if the given name is a directory.  Behavior is well-defined
2893              only for full paths.
2894
2895
2896                if(IS_SYMLINK file-name)
2897
2898              True if  the  given  name  is  a  symbolic  link.   Behavior  is
2899              well-defined only for full paths.
2900
2901
2902                if(IS_ABSOLUTE path)
2903
2904              True if the given path is an absolute path.
2905
2906
2907                if(<variable|string> MATCHES regex)
2908
2909              True  if  the given string or variable's value matches the given
2910              regular expression.
2911
2912
2913                if(<variable|string> LESS <variable|string>)
2914                if(<variable|string> GREATER <variable|string>)
2915                if(<variable|string> EQUAL <variable|string>)
2916
2917              True if the given string or variable's value is a  valid  number
2918              and the inequality or equality is true.
2919
2920
2921                if(<variable|string> STRLESS <variable|string>)
2922                if(<variable|string> STRGREATER <variable|string>)
2923                if(<variable|string> STREQUAL <variable|string>)
2924
2925              True  if  the  given string or variable's value is lexicographi‐
2926              cally less (or greater, or equal) than the string or variable on
2927              the right.
2928
2929
2930                if(<variable|string> VERSION_LESS <variable|string>)
2931                if(<variable|string> VERSION_EQUAL <variable|string>)
2932                if(<variable|string> VERSION_GREATER <variable|string>)
2933
2934              Component-wise integer version number comparison (version format
2935              is major[.minor[.patch[.tweak]]]).
2936
2937
2938                if(DEFINED <variable>)
2939
2940              True if the given variable is defined. It does not matter if the
2941              variable is true or false just if it has been set.
2942
2943
2944                if((expression) AND (expression OR (expression)))
2945
2946              The  expressions  inside the parenthesis are evaluated first and
2947              then the remaining expression is evaluated as  in  the  previous
2948              examples.  Where  there are nested parenthesis the innermost are
2949              evaluated as part of evaluating  the  expression  that  contains
2950              them.
2951
2952
2953              The  if  command was written very early in CMake's history, pre‐
2954              dating the ${} variable evaluation syntax, and  for  convenience
2955              evaluates variables named by its arguments as shown in the above
2956              signatures.  Note  that  normal  variable  evaluation  with  ${}
2957              applies  before  the  if  command  even  receives the arguments.
2958              Therefore code like
2959
2960
2961                set(var1 OFF)
2962                set(var2 "var1")
2963                if(${var2})
2964
2965              appears to the if command as
2966
2967
2968                if(var1)
2969
2970              and is evaluated according to the if(<variable>) case documented
2971              above.  The result is OFF which is false.  However, if we remove
2972              the ${} from the example then the command sees
2973
2974
2975                if(var2)
2976
2977              which is true because var2 is defined to "var1" which is  not  a
2978              false constant.
2979
2980
2981              Automatic  evaluation  applies  in  the other cases whenever the
2982              above-documented signature accepts <variable|string>:
2983
2984
2985              1) The left hand argument to MATCHES is first checked to see  if
2986              it  is  a  defined variable, if so the variable's value is used,
2987              otherwise the original value is used.
2988
2989
2990              2) If the left hand argument to MATCHES is  missing  it  returns
2991              false without error
2992
2993
2994              3)  Both left and right hand arguments to LESS GREATER EQUAL are
2995              independently tested to see if they are defined variables, if so
2996              their  defined  values  are used otherwise the original value is
2997              used.
2998
2999
3000              4) Both left and right hand arguments to STRLESS  STREQUAL  STR‐
3001              GREATER  are  independently  tested  to  see if they are defined
3002              variables, if so their defined values  are  used  otherwise  the
3003              original value is used.
3004
3005
3006              5)  Both  left  and  right  hand argumemnts to VERSION_LESS VER‐
3007              SION_EQUAL VERSION_GREATER are independently tested  to  see  if
3008              they  are defined variables, if so their defined values are used
3009              otherwise the original value is used.
3010
3011
3012              6) The right hand argument to NOT is tested to see if  it  is  a
3013              boolean  constant,  if  so  the  value  is used, otherwise it is
3014              assumed to be a variable and it is dereferenced.
3015
3016
3017              7) The left and right hand arguments to AND OR are independently
3018              tested to see if they are boolean constants, if so they are used
3019              as such, otherwise they are assumed  to  be  variables  and  are
3020              dereferenced.
3021
3022
3023
3024       include
3025              Load and run CMake code from a file or module.
3026
3027                include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
3028                                      [NO_POLICY_SCOPE])
3029
3030              Load and run CMake code from the file given.  Variable reads and
3031              writes access the scope of the  caller  (dynamic  scoping).   If
3032              OPTIONAL  is  present,  then no error is raised if the file does
3033              not exist.  If RESULT_VARIABLE is given the variable will be set
3034              to  the  full filename which has been included or NOTFOUND if it
3035              failed.
3036
3037
3038              If a module is specified instead of a file, the file  with  name
3039              <modulename>.cmake  is searched first in CMAKE_MODULE_PATH, then
3040              in the CMake module directory. There is one exception  to  this:
3041              if the file which calls include() is located itself in the CMake
3042              module directory, then  first  the  CMake  module  directory  is
3043              searched  and  CMAKE_MODULE_PATH  afterwards.  See  also  policy
3044              CMP0017.
3045
3046
3047              See the cmake_policy() command documentation for  discussion  of
3048              the NO_POLICY_SCOPE option.
3049
3050
3051       include_directories
3052              Add include directories to the build.
3053
3054                include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)
3055
3056              Add  the  given directories to those the compiler uses to search
3057              for include files.  Relative paths are interpreted  as  relative
3058              to the current source directory.
3059
3060
3061              The  include  directories  are  added  to the directory property
3062              INCLUDE_DIRECTORIES for the current CMakeLists  file.  They  are
3063              also  added  to the target property INCLUDE_DIRECTORIES for each
3064              target in the current CMakeLists file. The target property  val‐
3065              ues are the ones used by the generators.
3066
3067
3068              By default the directories are appended onto the current list of
3069              directories. This default behavior can  be  changed  by  setting
3070              CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
3071              explicitly, you can select  between  appending  and  prepending,
3072              independent of the default.
3073
3074
3075              If  the  SYSTEM  option  is given, the compiler will be told the
3076              directories are meant as  system  include  directories  on  some
3077              platforms (signalling this setting might achieve effects such as
3078              the compiler skipping warnings, or  these  fixed-install  system
3079              files not being considered in dependency calculations - see com‐
3080              piler docs).
3081
3082
3083       include_external_msproject
3084              Include an external Microsoft project file in a workspace.
3085
3086                include_external_msproject(projectname location
3087                                           [TYPE projectTypeGUID]
3088                                           [GUID projectGUID]
3089                                           [PLATFORM platformName]
3090                                           dep1 dep2 ...)
3091
3092              Includes  an  external  Microsoft  project  in   the   generated
3093              workspace  file.  Currently does nothing on UNIX. This will cre‐
3094              ate a target named [projectname].   This  can  be  used  in  the
3095              add_dependencies  command  to make things depend on the external
3096              project.
3097
3098
3099              TYPE, GUID and PLATFORM are optional parameters that  allow  one
3100              to specify the type of project, id (GUID) of the project and the
3101              name of the  target  platform.   This  is  useful  for  projects
3102              requiring  values  other  than  the default (e.g. WIX projects).
3103              These options are not supported by the Visual Studio  6  genera‐
3104              tor.
3105
3106
3107       include_regular_expression
3108              Set the regular expression used for dependency checking.
3109
3110                include_regular_expression(regex_match [regex_complain])
3111
3112              Set  the  regular expressions used in dependency checking.  Only
3113              files matching regex_match will be traced as dependencies.  Only
3114              files  matching  regex_complain  will  generate warnings if they
3115              cannot be found (standard header paths are not  searched).   The
3116              defaults are:
3117
3118
3119                regex_match    = "^.*$" (match everything)
3120                regex_complain = "^$" (match empty string only)
3121
3122
3123       install
3124              Specify rules to run at install time.
3125
3126              This  command generates installation rules for a project.  Rules
3127              specified by calls to this command within a source directory are
3128              executed  in order during installation.  The order across direc‐
3129              tories is not defined.
3130
3131
3132              There are multiple signatures for this command.   Some  of  them
3133              define  installation  properties for files and targets.  Proper‐
3134              ties common to multiple signatures are covered here but they are
3135              valid only for signatures that specify them.
3136
3137
3138              DESTINATION  arguments  specify the directory on disk to which a
3139              file will be installed.  If a full path (with a leading slash or
3140              drive  letter) is given it is used directly.  If a relative path
3141              is  given  it  is  interpreted  relative   to   the   value   of
3142              CMAKE_INSTALL_PREFIX.  The  prefix  can  be relocated at install
3143              time using DESTDIR mechanism explained in the CMAKE_INSTALL_PRE‐
3144              FIX variable documentation.
3145
3146
3147              PERMISSIONS  arguments  specify permissions for installed files.
3148              Valid permissions are  OWNER_READ,  OWNER_WRITE,  OWNER_EXECUTE,
3149              GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
3150              WORLD_EXECUTE, SETUID, and SETGID.  Permissions that do not make
3151              sense on certain platforms are ignored on those platforms.
3152
3153
3154              The CONFIGURATIONS argument specifies a list of build configura‐
3155              tions for which the install rule applies (Debug, Release, etc.).
3156
3157
3158              The COMPONENT argument specifies an installation component  name
3159              with  which the install rule is associated, such as "runtime" or
3160              "development".   During  component-specific  installation   only
3161              install  rules  associated with the given component name will be
3162              executed.   During  a  full  installation  all  components   are
3163              installed.  If  COMPONENT  is  not  provided a default component
3164              "Unspecified" is created. The default component name may be con‐
3165              trolled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME variable.
3166
3167
3168              The  RENAME argument specifies a name for an installed file that
3169              may be different from the original file.   Renaming  is  allowed
3170              only when a single file is installed by the command.
3171
3172
3173              The  OPTIONAL  argument specifies that it is not an error if the
3174              file to be installed does not exist.
3175
3176
3177              The TARGETS signature:
3178
3179
3180                install(TARGETS targets... [EXPORT <export-name>]
3181                        [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
3182                          PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
3183                         [DESTINATION <dir>]
3184                         [INCLUDES DESTINATION [<dir> ...]]
3185                         [PERMISSIONS permissions...]
3186                         [CONFIGURATIONS [Debug|Release|...]]
3187                         [COMPONENT <component>]
3188                         [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
3189                        ] [...])
3190
3191              The TARGETS form specifies rules for installing targets  from  a
3192              project.   There  are  five  kinds  of  target files that may be
3193              installed: ARCHIVE, LIBRARY,  RUNTIME,  FRAMEWORK,  and  BUNDLE.
3194              Executables  are  treated  as RUNTIME targets, except that those
3195              marked with the MACOSX_BUNDLE property  are  treated  as  BUNDLE
3196              targets  on OS X. Static libraries are always treated as ARCHIVE
3197              targets. Module libraries are always treated as LIBRARY targets.
3198              For  non-DLL  platforms  shared libraries are treated as LIBRARY
3199              targets, except that those marked with  the  FRAMEWORK  property
3200              are treated as FRAMEWORK targets on OS X.  For DLL platforms the
3201              DLL part of a shared library is treated as a RUNTIME target  and
3202              the  corresponding  import library is treated as an ARCHIVE tar‐
3203              get. All Windows-based systems including Cygwin  are  DLL  plat‐
3204              forms.  The  ARCHIVE,  LIBRARY, RUNTIME, and FRAMEWORK arguments
3205              change the type of target to  which  the  subsequent  properties
3206              apply.   If  none  is given the installation properties apply to
3207              all target types.  If only one is given  then  only  targets  of
3208              that type will be installed (which can be used to install just a
3209              DLL or just an import library).The INCLUDES  DESTINATION  speci‐
3210              fies  a  list  of  directories which will be added to the INTER‐
3211              FACE_INCLUDE_DIRECTORIES  of  the  <targets>  when  exported  by
3212              install(EXPORT).  If a relative path is specified, it is treated
3213              as relative to the $<INSTALL_PREFIX>.
3214
3215
3216              The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments  cause
3217              subsequent  properties  to  be applied to installing a FRAMEWORK
3218              shared library target's associated files on non-Apple platforms.
3219              Rules  defined by these arguments are ignored on Apple platforms
3220              because the associated files are installed into the  appropriate
3221              locations inside the framework folder.  See documentation of the
3222              PRIVATE_HEADER, PUBLIC_HEADER, and  RESOURCE  target  properties
3223              for details.
3224
3225
3226              Either  NAMELINK_ONLY  or  NAMELINK_SKIP  may  be specified as a
3227              LIBRARY option.  On some platforms a  versioned  shared  library
3228              has a symbolic link such as
3229
3230
3231                lib<name>.so -> lib<name>.so.1
3232
3233              where   "lib<name>.so.1"  is  the  soname  of  the  library  and
3234              "lib<name>.so" is a "namelink"  allowing  linkers  to  find  the
3235              library  when given "-l<name>".  The NAMELINK_ONLY option causes
3236              installation of only the  namelink  when  a  library  target  is
3237              installed.   The  NAMELINK_SKIP  option  causes  installation of
3238              library files other than the namelink when a library  target  is
3239              installed.   When  neither  option  is  given  both portions are
3240              installed.  On platforms where versioned shared libraries do not
3241              have   namelinks   or  when  a  library  is  not  versioned  the
3242              NAMELINK_SKIP option installs the library and the  NAMELINK_ONLY
3243              option  installs  nothing.  See the VERSION and SOVERSION target
3244              properties for details on creating versioned shared libraries.
3245
3246
3247              One or more groups of properties may be specified  in  a  single
3248              call  to  the  TARGETS  form  of  this command.  A target may be
3249              installed more than once to different locations.  Consider hypo‐
3250              thetical targets "myExe", "mySharedLib", and "myStaticLib".  The
3251              code
3252
3253
3254                  install(TARGETS myExe mySharedLib myStaticLib
3255                          RUNTIME DESTINATION bin
3256                          LIBRARY DESTINATION lib
3257                          ARCHIVE DESTINATION lib/static)
3258                  install(TARGETS mySharedLib DESTINATION /some/full/path)
3259
3260              will install myExe to  <prefix>/bin  and  myStaticLib  to  <pre‐
3261              fix>/lib/static.   On  non-DLL  platforms  mySharedLib  will  be
3262              installed to <prefix>/lib and /some/full/path.  On DLL platforms
3263              the  mySharedLib  DLL  will  be  installed  to  <prefix>/bin and
3264              /some/full/path and its import  library  will  be  installed  to
3265              <prefix>/lib/static and /some/full/path.
3266
3267
3268              The  EXPORT option associates the installed target files with an
3269              export called <export-name>.  It must appear before any RUNTIME,
3270              LIBRARY,  or  ARCHIVE  options.   To actually install the export
3271              file itself, call install(EXPORT).   See  documentation  of  the
3272              install(EXPORT ...) signature below for details.
3273
3274
3275              Installing  a target with EXCLUDE_FROM_ALL set to true has unde‐
3276              fined behavior.
3277
3278
3279              The FILES signature:
3280
3281
3282                install(FILES files... DESTINATION <dir>
3283                        [PERMISSIONS permissions...]
3284                        [CONFIGURATIONS [Debug|Release|...]]
3285                        [COMPONENT <component>]
3286                        [RENAME <name>] [OPTIONAL])
3287
3288              The FILES form  specifies  rules  for  installing  files  for  a
3289              project.   File  names  given  as relative paths are interpreted
3290              with respect to the current source directory.   Files  installed
3291              by  this  form  are  by  default  given permissions OWNER_WRITE,
3292              OWNER_READ, GROUP_READ, and WORLD_READ if no  PERMISSIONS  argu‐
3293              ment is given.
3294
3295
3296              The PROGRAMS signature:
3297
3298
3299                install(PROGRAMS files... DESTINATION <dir>
3300                        [PERMISSIONS permissions...]
3301                        [CONFIGURATIONS [Debug|Release|...]]
3302                        [COMPONENT <component>]
3303                        [RENAME <name>] [OPTIONAL])
3304
3305              The PROGRAMS form is identical to the FILES form except that the
3306              default  permissions  for  the  installed  file   also   include
3307              OWNER_EXECUTE,  GROUP_EXECUTE,  and WORLD_EXECUTE.  This form is
3308              intended to install programs that are not targets, such as shell
3309              scripts.   Use  the TARGETS form to install targets built within
3310              the project.
3311
3312
3313              The DIRECTORY signature:
3314
3315
3316                install(DIRECTORY dirs... DESTINATION <dir>
3317                        [FILE_PERMISSIONS permissions...]
3318                        [DIRECTORY_PERMISSIONS permissions...]
3319                        [USE_SOURCE_PERMISSIONS] [OPTIONAL]
3320                        [CONFIGURATIONS [Debug|Release|...]]
3321                        [COMPONENT <component>] [FILES_MATCHING]
3322                        [[PATTERN <pattern> | REGEX <regex>]
3323                         [EXCLUDE] [PERMISSIONS permissions...]] [...])
3324
3325              The DIRECTORY form installs contents of one or more  directories
3326              to  a given destination.  The directory structure is copied ver‐
3327              batim to the destination.  The last component of each  directory
3328              name  is  appended  to  the destination directory but a trailing
3329              slash may be used to avoid this because it leaves the last  com‐
3330              ponent  empty.   Directory  names  given  as  relative paths are
3331              interpreted with respect to the current source directory.  If no
3332              input  directory  names are given the destination directory will
3333              be created but nothing will be installed into it.  The FILE_PER‐
3334              MISSIONS  and  DIRECTORY_PERMISSIONS options specify permissions
3335              given  to  files  and  directories  in  the   destination.    If
3336              USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not,
3337              file permissions will be copied from the source directory struc‐
3338              ture.   If  no permissions are specified files will be given the
3339              default permissions specified in the FILES form of the  command,
3340              and the directories will be given the default permissions speci‐
3341              fied in the PROGRAMS form of the command.
3342
3343
3344              Installation of directories may be controlled with  fine  granu‐
3345              larity  using  the  PATTERN  or  REGEX  options.   These "match"
3346              options specify a globbing  pattern  or  regular  expression  to
3347              match directories or files encountered within input directories.
3348              They may be used to apply certain options (see below) to a  sub‐
3349              set  of the files and directories encountered.  The full path to
3350              each input file or directory (with forward slashes)  is  matched
3351              against the expression.  A PATTERN will match only complete file
3352              names: the portion of the full path matching  the  pattern  must
3353              occur at the end of the file name and be preceded by a slash.  A
3354              REGEX will match any portion of the full path but it may use '/'
3355              and  '$' to simulate the PATTERN behavior.  By default all files
3356              and directories are installed whether or not they  are  matched.
3357              The  FILES_MATCHING  option  may be given before the first match
3358              option to disable installation of files  (but  not  directories)
3359              not matched by any expression.  For example, the code
3360
3361
3362                install(DIRECTORY src/ DESTINATION include/myproj
3363                        FILES_MATCHING PATTERN "*.h")
3364
3365              will extract and install header files from a source tree.
3366
3367
3368              Some  options  may  follow a PATTERN or REGEX expression and are
3369              applied only to files or directories matching them.  The EXCLUDE
3370              option will skip the matched file or directory.  The PERMISSIONS
3371              option overrides the permissions setting for the matched file or
3372              directory.  For example the code
3373
3374
3375                install(DIRECTORY icons scripts/ DESTINATION share/myproj
3376                        PATTERN "CVS" EXCLUDE
3377                        PATTERN "scripts/*"
3378                        PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
3379                                    GROUP_EXECUTE GROUP_READ)
3380
3381              will  install  the icons directory to share/myproj/icons and the
3382              scripts directory to share/myproj.  The icons will  get  default
3383              file  permissions,  the  scripts  will be given specific permis‐
3384              sions, and any CVS directories will be excluded.
3385
3386
3387              The SCRIPT and CODE signature:
3388
3389
3390                install([[SCRIPT <file>] [CODE <code>]] [...])
3391
3392              The SCRIPT form will invoke the given CMake script files  during
3393              installation.   If  the  script  file name is a relative path it
3394              will be interpreted with respect to the  current  source  direc‐
3395              tory.   The  CODE  form  will invoke the given CMake code during
3396              installation.  Code is specified as a single argument  inside  a
3397              double-quoted string. For example, the code
3398
3399
3400                install(CODE "MESSAGE(\"Sample install message.\")")
3401
3402              will print a message during installation.
3403
3404
3405              The EXPORT signature:
3406
3407
3408                install(EXPORT <export-name> DESTINATION <dir>
3409                        [NAMESPACE <namespace>] [FILE <name>.cmake]
3410                        [PERMISSIONS permissions...]
3411                        [CONFIGURATIONS [Debug|Release|...]]
3412                        [EXPORT_LINK_INTERFACE_LIBRARIES]
3413                        [COMPONENT <component>])
3414
3415              The  EXPORT  form generates and installs a CMake file containing
3416              code to import targets from the installation tree  into  another
3417              project.   Target  installations  are associated with the export
3418              <export-name> using the EXPORT  option  of  the  install(TARGETS
3419              ...)  signature  documented  above.   The  NAMESPACE option will
3420              prepend <namespace> to the target names as they are  written  to
3421              the  import  file.  By default the generated file will be called
3422              <export-name>.cmake but the FILE option may be used to specify a
3423              different  name.   The  value given to the FILE option must be a
3424              file name with the  ".cmake"  extension.   If  a  CONFIGURATIONS
3425              option is given then the file will only be installed when one of
3426              the named configurations is installed.  Additionally, the gener‐
3427              ated import file will reference only the matching target config‐
3428              urations.   The  EXPORT_LINK_INTERFACE_LIBRARIES   keyword,   if
3429              present,   causes   the  contents  of  the  properties  matching
3430              (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported,
3431              when  policy CMP0022 is NEW.  If a COMPONENT option is specified
3432              that does not match that given to the  targets  associated  with
3433              <export-name> the behavior is undefined.  If a library target is
3434              included in the export but a target to which  it  links  is  not
3435              included the behavior is unspecified.
3436
3437
3438              The  EXPORT  form is useful to help outside projects use targets
3439              built and installed by the current project.   For  example,  the
3440              code
3441
3442
3443                install(TARGETS myexe EXPORT myproj DESTINATION bin)
3444                install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
3445
3446              will  install  the  executable myexe to <prefix>/bin and code to
3447              import it in the  file  "<prefix>/lib/myproj/myproj.cmake".   An
3448              outside  project may load this file with the include command and
3449              reference the myexe executable from the installation tree  using
3450              the imported target name mp_myexe as if the target were built in
3451              its own tree.
3452
3453
3454              NOTE: This command supercedes the  INSTALL_TARGETS  command  and
3455              the      target      properties      PRE_INSTALL_SCRIPT      and
3456              POST_INSTALL_SCRIPT.  It also replaces the FILES  forms  of  the
3457              INSTALL_FILES  and  INSTALL_PROGRAMS  commands.   The processing
3458              order of these install rules  relative  to  those  generated  by
3459              INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS commands is
3460              not defined.
3461
3462
3463
3464       link_directories
3465              Specify directories in which the linker will look for libraries.
3466
3467                link_directories(directory1 directory2 ...)
3468
3469              Specify  the  paths  in  which  the  linker  should  search  for
3470              libraries.  The command will apply only to targets created after
3471              it is called. Relative paths given to this  command  are  inter‐
3472              preted as relative to the current source directory, see CMP0015.
3473
3474
3475              Note  that  this command is rarely necessary.  Library locations
3476              returned  by  find_package()  and  find_library()  are  absolute
3477              paths.   Pass  these absolute library file paths directly to the
3478              target_link_libraries() command.  CMake will ensure  the  linker
3479              finds them.
3480
3481
3482       list   List operations.
3483
3484                list(LENGTH <list> <output variable>)
3485                list(GET <list> <element index> [<element index> ...]
3486                     <output variable>)
3487                list(APPEND <list> <element> [<element> ...])
3488                list(FIND <list> <value> <output variable>)
3489                list(INSERT <list> <element_index> <element> [<element> ...])
3490                list(REMOVE_ITEM <list> <value> [<value> ...])
3491                list(REMOVE_AT <list> <index> [<index> ...])
3492                list(REMOVE_DUPLICATES <list>)
3493                list(REVERSE <list>)
3494                list(SORT <list>)
3495
3496              LENGTH will return a given list's length.
3497
3498
3499              GET  will  return list of elements specified by indices from the
3500              list.
3501
3502
3503              APPEND will append elements to the list.
3504
3505
3506              FIND will return the index of the element specified in the  list
3507              or -1 if it wasn't found.
3508
3509
3510              INSERT  will  insert elements to the list to the specified loca‐
3511              tion.
3512
3513
3514              REMOVE_AT and REMOVE_ITEM will remove items from the  list.  The
3515              difference  is  that  REMOVE_ITEM  will  remove the given items,
3516              while REMOVE_AT will remove the items at the given indices.
3517
3518
3519              REMOVE_DUPLICATES will remove duplicated items in the list.
3520
3521
3522              REVERSE reverses the contents of the list in-place.
3523
3524
3525              SORT sorts the list in-place alphabetically.
3526
3527
3528              The list subcommands  APPEND,  INSERT,  REMOVE_AT,  REMOVE_ITEM,
3529              REMOVE_DUPLICATES,  REVERSE  and  SORT may create new values for
3530              the list within the current CMake variable scope. Similar to the
3531              SET command, the LIST command creates new variable values in the
3532              current scope, even if the list itself is actually defined in  a
3533              parent  scope.  To  propagate  the  results  of these operations
3534              upwards, use SET with PARENT_SCOPE, SET with CACHE INTERNAL,  or
3535              some other means of value propagation.
3536
3537
3538              NOTES:  A  list  in  cmake is a ; separated group of strings. To
3539              create a list the set command can be used. For example,  set(var
3540              a  b c d e)  creates a list with a;b;c;d;e, and set(var "a b c d
3541              e") creates a string or a list with one item in it.
3542
3543
3544              When specifying  index  values,  if  <element  index>  is  0  or
3545              greater,  it  is  indexed from the beginning of the list, with 0
3546              representing the first list element. If <element index> is -1 or
3547              lesser,  it  is indexed from the end of the list, with -1 repre‐
3548              senting the last list element. Be  careful  when  counting  with
3549              negative  indices: they do not start from 0. -0 is equivalent to
3550              0, the first list element.
3551
3552
3553
3554       load_cache
3555              Load in the values from another project's CMake cache.
3556
3557                load_cache(pathToCacheFile READ_WITH_PREFIX
3558                           prefix entry1...)
3559
3560              Read the cache and store the requested entries in variables with
3561              their  name prefixed with the given prefix.  This only reads the
3562              values, and does not  create  entries  in  the  local  project's
3563              cache.
3564
3565
3566                load_cache(pathToCacheFile [EXCLUDE entry1...]
3567                           [INCLUDE_INTERNALS entry1...])
3568
3569              Load  in  the  values  from  another cache and store them in the
3570              local project's cache as internal entries.  This is useful for a
3571              project  that  depends  on  another project built in a different
3572              tree.  EXCLUDE option can be used to provide a list  of  entries
3573              to be excluded.  INCLUDE_INTERNALS can be used to provide a list
3574              of internal entries  to  be  included.   Normally,  no  internal
3575              entries  are  brought  in.   Use  of this form of the command is
3576              strongly discouraged, but it is provided for  backward  compati‐
3577              bility.
3578
3579
3580       load_command
3581              Load a command into a running CMake.
3582
3583                load_command(COMMAND_NAME <loc1> [loc2 ...])
3584
3585              The  given  locations  are  searched for a library whose name is
3586              cmCOMMAND_NAME.  If found, it is loaded as a module and the com‐
3587              mand  is added to the set of available CMake commands.  Usually,
3588              TRY_COMPILE is used before this command to compile  the  module.
3589              If the command is successfully loaded a variable named
3590
3591
3592                CMAKE_LOADED_COMMAND_<COMMAND_NAME>
3593
3594              will  be  set  to  the  full path of the module that was loaded.
3595              Otherwise the variable will not be set.
3596
3597
3598       macro  Start recording a macro for later invocation as a command.
3599
3600                macro(<name> [arg1 [arg2 [arg3 ...]]])
3601                  COMMAND1(ARGS ...)
3602                  COMMAND2(ARGS ...)
3603                  ...
3604                endmacro(<name>)
3605
3606              Define a macro named <name> that takes arguments named arg1 arg2
3607              arg3  (...).  Commands listed after macro, but before the match‐
3608              ing endmacro, are not invoked until the macro is invoked.   When
3609              it is invoked, the commands recorded in the macro are first mod‐
3610              ified by replacing formal parameters (${arg1})  with  the  argu‐
3611              ments  passed,  and then invoked as normal commands. In addition
3612              to referencing the formal parameters you can reference the  val‐
3613              ues  ${ARGC} which will be set to the number of arguments passed
3614              into the function as well  as  ${ARGV0}  ${ARGV1}  ${ARGV2}  ...
3615              which  will  have  the actual values of the arguments passed in.
3616              This facilitates creating macros with optional arguments.  Addi‐
3617              tionally  ${ARGV}  holds  the list of all arguments given to the
3618              macro and ${ARGN} holds the list  of  arguments  past  the  last
3619              expected  argument. Note that the parameters to a macro and val‐
3620              ues such as ARGN are not variables in  the  usual  CMake  sense.
3621              They  are string replacements much like the C preprocessor would
3622              do with a macro. If you want true CMake variables and/or  better
3623              CMake scope control you should look at the function command.
3624
3625
3626              See the cmake_policy() command documentation for the behavior of
3627              policies inside macros.
3628
3629
3630       mark_as_advanced
3631              Mark cmake cached variables as advanced.
3632
3633                mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
3634
3635              Mark the named cached variables as advanced.  An advanced  vari‐
3636              able  will  not be displayed in any of the cmake GUIs unless the
3637              show advanced option is on.  If  CLEAR  is  the  first  argument
3638              advanced  variables are changed back to unadvanced.  If FORCE is
3639              the first argument, then the variable is made advanced.  If nei‐
3640              ther  FORCE nor CLEAR is specified, new values will be marked as
3641              advanced,   but    if    the    variable    already    has    an
3642              advanced/non-advanced state, it will not be changed.
3643
3644
3645              It does nothing in script mode.
3646
3647
3648       math   Mathematical expressions.
3649
3650                math(EXPR <output variable> <math expression>)
3651
3652              EXPR evaluates mathematical expression and returns result in the
3653              output variable. Example mathematical expression is '5 * ( 10  +
3654              13  )'.   Supported operators are + - * / % | & ^ ~ << >> * / %.
3655              They have the same meaning  as they do in C code.
3656
3657
3658       message
3659              Display a message to the user.
3660
3661                message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
3662                        "message to display" ...)
3663
3664              The optional keyword determines the type of message:
3665
3666
3667                (none)         = Important information
3668                STATUS         = Incidental information
3669                WARNING        = CMake Warning, continue processing
3670                AUTHOR_WARNING = CMake Warning (dev), continue processing
3671                SEND_ERROR     = CMake Error, continue processing,
3672                                              but skip generation
3673                FATAL_ERROR    = CMake Error, stop processing and generation
3674
3675              The CMake command-line tool displays STATUS messages  on  stdout
3676              and  all  other message types on stderr.  The CMake GUI displays
3677              all messages in its log area.  The interactive  dialogs  (ccmake
3678              and  CMakeSetup)  show STATUS messages one at a time on a status
3679              line and other messages in interactive pop-up boxes.
3680
3681
3682              CMake Warning and Error message text  displays  using  a  simple
3683              markup language.  Non-indented text is formatted in line-wrapped
3684              paragraphs delimited by newlines.  Indented text  is  considered
3685              pre-formatted.
3686
3687
3688       option Provides an option that the user can optionally select.
3689
3690                option(<option_variable> "help string describing option"
3691                       [initial value])
3692
3693              Provide  an  option  for the user to select as ON or OFF.  If no
3694              initial value is provided, OFF is used.
3695
3696
3697              If you have options that depend on the values of other  options,
3698              see the module help for CMakeDependentOption.
3699
3700
3701       project
3702              Set a name for the entire project.
3703
3704                project(<projectname> [languageName1 languageName2 ... ] )
3705
3706              Sets  the name of the project.  Additionally this sets the vari‐
3707              ables <projectName>_BINARY_DIR and  <projectName>_SOURCE_DIR  to
3708              the respective values.
3709
3710
3711              Optionally  you  can  specify  which languages your project sup‐
3712              ports.  Example languages are CXX (i.e. C++), C,  Fortran,  etc.
3713              By default C and CXX are enabled.  E.g. if you do not have a C++
3714              compiler, you can disable the check for it by explicitly listing
3715              the languages you want to support, e.g. C.  By using the special
3716              language "NONE" all checks for any language can be disabled.  If
3717              a  variable  exists  called CMAKE_PROJECT_<projectName>_INCLUDE,
3718              the file pointed to by that variable will  be  included  as  the
3719              last step of the project command.
3720
3721
3722              The  top-level  CMakeLists.txt file for a project must contain a
3723              literal, direct call  to  the  project()  command;  loading  one
3724              through  the  include()  command  is not sufficient.  If no such
3725              call exists CMake will  implicitly  add  one  to  the  top  that
3726              enables the default languages (C and CXX).
3727
3728
3729       qt_wrap_cpp
3730              Create Qt Wrappers.
3731
3732                qt_wrap_cpp(resultingLibraryName DestName
3733                            SourceLists ...)
3734
3735              Produce   moc   files  for  all  the  .h  files  listed  in  the
3736              SourceLists.  The moc files will be added to the  library  using
3737              the DestName source list.
3738
3739
3740       qt_wrap_ui
3741              Create Qt user interfaces Wrappers.
3742
3743                qt_wrap_ui(resultingLibraryName HeadersDestName
3744                           SourcesDestName SourceLists ...)
3745
3746              Produce  .h  and  .cxx files for all the .ui files listed in the
3747              SourceLists.  The .h files will be added to  the  library  using
3748              the HeadersDestNamesource list.  The .cxx files will be added to
3749              the library using the SourcesDestNamesource list.
3750
3751
3752       remove_definitions
3753              Removes -D define flags added by add_definitions.
3754
3755                remove_definitions(-DFOO -DBAR ...)
3756
3757              Removes flags (added by add_definitions) from the compiler  com‐
3758              mand line for sources in the current directory and below.
3759
3760
3761       return Return from a file, directory or function.
3762
3763                return()
3764
3765              Returns from a file, directory or function. When this command is
3766              encountered in an included file  (via  include()  or  find_pack‐
3767              age()),  it  causes  processing  of the current file to stop and
3768              control is returned to the including file. If it is  encountered
3769              in  a  file which is not included by another file, e.g. a CMake‐
3770              Lists.txt, control is returned to the parent directory if  there
3771              is  one.  If return is called in a function, control is returned
3772              to the caller of the function. Note that a macro is not a  func‐
3773              tion and does not handle return like a function does.
3774
3775
3776       separate_arguments
3777              Parse space-separated arguments into a semicolon-separated list.
3778
3779                separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
3780
3781              Parses a unix- or windows-style command-line string "<args>" and
3782              stores a semicolon-separated list of  the  arguments  in  <var>.
3783              The entire command line must be given in one "<args>" argument.
3784
3785
3786              The  UNIX_COMMAND  mode  separates  arguments by unquoted white‐
3787              space.  It recognizes both single-quote and double-quote  pairs.
3788              A  backslash escapes the next literal character (\" is "); there
3789              are no special escapes (\n is just n).
3790
3791
3792              The WINDOWS_COMMAND mode parses a windows command-line using the
3793              same  syntax  the  runtime  library  uses  to  construct argv at
3794              startup.  It separates arguments by whitespace that is not  dou‐
3795              ble-quoted.   Backslashes  are  literal unless they precede dou‐
3796              ble-quotes.  See the MSDN article "Parsing C Command-Line  Argu‐
3797              ments" for details.
3798
3799
3800                separate_arguments(VARIABLE)
3801
3802              Convert  the  value  of VARIABLE to a semi-colon separated list.
3803              All spaces are replaced with ';'.  This  helps  with  generating
3804              command lines.
3805
3806
3807       set    Set a CMake, cache or environment variable to a given value.
3808
3809                set(<variable> <value>
3810                    [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
3811
3812              Within  CMake  sets <variable> to the value <value>.  <value> is
3813              expanded before <variable> is set to it.  Normally, set will set
3814              a  regular  CMake variable. If CACHE is present, then the <vari‐
3815              able> is put in the cache instead, unless it is already  in  the
3816              cache.  See  section 'Variable types in CMake' below for details
3817              of regular and cache variables and their interactions. If  CACHE
3818              is  used, <type> and <docstring> are required. <type> is used by
3819              the CMake GUI to choose a widget with  which  the  user  sets  a
3820              value. The value for <type> may be one of
3821
3822
3823                FILEPATH = File chooser dialog.
3824                PATH     = Directory chooser dialog.
3825                STRING   = Arbitrary string.
3826                BOOL     = Boolean ON/OFF checkbox.
3827                INTERNAL = No GUI entry (used for persistent variables).
3828
3829              If <type> is INTERNAL, the cache variable is marked as internal,
3830              and will not be shown to the user in tools like cmake-gui.  This
3831              is  intended  for  values that should be persisted in the cache,
3832              but which users should not  normally  change.  INTERNAL  implies
3833              FORCE.
3834
3835
3836              Normally, set(...CACHE...) creates cache variables, but does not
3837              modify them. If FORCE is specified, the value of the cache vari‐
3838              able  is set, even if the variable is already in the cache. This
3839              should normally be avoided, as it will remove any changes to the
3840              cache variable's value by the user.
3841
3842
3843              If  PARENT_SCOPE  is  present,  the  variable will be set in the
3844              scope above the current scope. Each new  directory  or  function
3845              creates  a new scope. This command will set the value of a vari‐
3846              able into the parent directory or calling function (whichever is
3847              applicable to the case at hand). PARENT_SCOPE cannot be combined
3848              with CACHE.
3849
3850
3851              If <value> is not specified then the variable is removed instead
3852              of set.  See also: the unset() command.
3853
3854
3855                set(<variable> <value1> ... <valueN>)
3856
3857              In  this case <variable> is set to a semicolon separated list of
3858              values.
3859
3860
3861              <variable> can be an environment variable such as:
3862
3863
3864                set( ENV{PATH} /home/martink )
3865
3866              in which case the environment variable will be set.
3867
3868
3869              *** Variable types in CMake ***
3870
3871
3872              In CMake there are two types of variables: normal variables  and
3873              cache variables. Normal variables are meant for the internal use
3874              of the script (just like  variables  in  most  programming  lan‐
3875              guages);  they  are not persisted across CMake runs. Cache vari‐
3876              ables (unless set with INTERNAL) are mostly intended for config‐
3877              uration settings where the first CMake run determines a suitable
3878              default value, which the user can then override, by editing  the
3879              cache  with  tools  such as ccmake or cmake-gui. Cache variables
3880              are stored in the CMake cache file,  and  are  persisted  across
3881              CMake runs.
3882
3883
3884              Both  types  can  exist  at the same time with the same name but
3885              different values. When ${FOO} is evaluated,  CMake  first  looks
3886              for  a normal variable 'FOO' in scope and uses it if set. If and
3887              only if no normal variable exists then  it  falls  back  to  the
3888              cache variable 'FOO'.
3889
3890
3891              Some examples:
3892
3893
3894              The  code 'set(FOO "x")' sets the normal variable 'FOO'. It does
3895              not touch the cache, but it will hide any existing  cache  value
3896              'FOO'.
3897
3898
3899              The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
3900              ignoring any normal variable of the same name. If  'FOO'  is  in
3901              the  cache then nothing happens to either the normal variable or
3902              the cache variable. If 'FOO' is not in the  cache,  then  it  is
3903              added to the cache.
3904
3905
3906              Finally,  whenever  a  cache  variable is added or modified by a
3907              command, CMake also *removes* the normal variable  of  the  same
3908              name  from  the  current  scope so that an immediately following
3909              evaluation of it will expose the newly cached value.
3910
3911
3912              Normally projects should avoid using normal and cache  variables
3913              of  the  same  name,  as this interaction can be hard to follow.
3914              However, in some situations it can be useful. One example  (used
3915              by some projects):
3916
3917
3918              A project has a subproject in its source tree. The child project
3919              has its own CMakeLists.txt, which is included  from  the  parent
3920              CMakeLists.txt  using add_subdirectory(). Now, if the parent and
3921              the child project provide the same option (for  example  a  com‐
3922              piler  option),  the  parent  gets  the  first  chance  to add a
3923              user-editable option to the cache.  Normally,  the  child  would
3924              then use the same value that the parent uses. However, it may be
3925              necessary to hard-code the value for the child project's  option
3926              while still allowing the user to edit the value used by the par‐
3927              ent project. The parent project can achieve this simply by  set‐
3928              ting  a  normal  variable  with the same name as the option in a
3929              scope sufficient to hide the option's cache  variable  from  the
3930              child completely. The parent has already set the cache variable,
3931              so the child's set(...CACHE...) will do nothing, and  evaluating
3932              the option variable will use the value from the normal variable,
3933              which hides the cache variable.
3934
3935
3936       set_directory_properties
3937              Set a property of the directory.
3938
3939                set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
3940
3941              Set a property for the current directory and subdirectories.  If
3942              the property is not found, CMake will report an error. The prop‐
3943              erties    include:    INCLUDE_DIRECTORIES,     LINK_DIRECTORIES,
3944              INCLUDE_REGULAR_EXPRESSION,   and   ADDITIONAL_MAKE_CLEAN_FILES.
3945              ADDITIONAL_MAKE_CLEAN_FILES is a list  of  files  that  will  be
3946              cleaned as a part of "make clean" stage.
3947
3948
3949       set_property
3950              Set a named property in a given scope.
3951
3952                set_property(<GLOBAL                            |
3953                              DIRECTORY [dir]                   |
3954                              TARGET    [target1 [target2 ...]] |
3955                              SOURCE    [src1 [src2 ...]]       |
3956                              TEST      [test1 [test2 ...]]     |
3957                              CACHE     [entry1 [entry2 ...]]>
3958                             [APPEND] [APPEND_STRING]
3959                             PROPERTY <name> [value1 [value2 ...]])
3960
3961              Set  one property on zero or more objects of a scope.  The first
3962              argument determines the scope in which the property is set.   It
3963              must be one of the following:
3964
3965
3966              GLOBAL scope is unique and does not accept a name.
3967
3968
3969              DIRECTORY  scope  defaults  to the current directory but another
3970              directory (already processed by CMake) may be named by  full  or
3971              relative path.
3972
3973
3974              TARGET scope may name zero or more existing targets.
3975
3976
3977              SOURCE  scope  may  name  zero  or more source files.  Note that
3978              source file properties are visible only to targets added in  the
3979              same directory (CMakeLists.txt).
3980
3981
3982              TEST scope may name zero or more existing tests.
3983
3984
3985              CACHE scope must name zero or more cache existing entries.
3986
3987
3988              The required PROPERTY option is immediately followed by the name
3989              of the property to set.  Remaining arguments are used to compose
3990              the  property  value  in the form of a semicolon-separated list.
3991              If the APPEND option is given the list is appended to any exist‐
3992              ing  property  value.If  the  APPEND_STRING  option is given the
3993              string is append to any existing property value as string,  i.e.
3994              it results in a longer string and not a list of strings.
3995
3996
3997       set_source_files_properties
3998              Source files can have properties that affect how they are built.
3999
4000                set_source_files_properties([file1 [file2 [...]]]
4001                                            PROPERTIES prop1 value1
4002                                            [prop2 value2 [...]])
4003
4004              Set  properties  associated  with source files using a key/value
4005              paired list.  See properties documentation for  those  known  to
4006              CMake.   Unrecognized properties are ignored.  Source file prop‐
4007              erties are visible only to targets added in the  same  directory
4008              (CMakeLists.txt).
4009
4010
4011       set_target_properties
4012              Targets can have properties that affect how they are built.
4013
4014                set_target_properties(target1 target2 ...
4015                                      PROPERTIES prop1 value1
4016                                      prop2 value2 ...)
4017
4018              Set  properties  on  a  target. The syntax for the command is to
4019              list all the files you want to change, and then provide the val‐
4020              ues  you  want to set next.  You can use any prop value pair you
4021              want and extract it later with the GET_TARGET_PROPERTY command.
4022
4023
4024              Properties that affect the name of a target's output file are as
4025              follows.   The PREFIX and SUFFIX properties override the default
4026              target name prefix (such as "lib") and suffix (such  as  ".so").
4027              IMPORT_PREFIX  and  IMPORT_SUFFIX  are the equivalent properties
4028              for the import  library  corresponding  to  a  DLL  (for  SHARED
4029              library  targets).   OUTPUT_NAME  sets the real name of a target
4030              when it is built and can be used to help create two  targets  of
4031              the  same  name even though CMake requires unique logical target
4032              names.  There is also a <CONFIG>_OUTPUT_NAME that  can  set  the
4033              output name on a per-configuration basis.  <CONFIG>_POSTFIX sets
4034              a postfix for the real name of the target when it is built under
4035              the  configuration  named  by  <CONFIG>  (in upper-case, such as
4036              "DEBUG_POSTFIX").  The value of  this  property  is  initialized
4037              when  the  target  is  created  to  the  value  of  the variable
4038              CMAKE_<CONFIG>_POSTFIX (except for  executable  targets  because
4039              earlier  CMake versions which did not use this variable for exe‐
4040              cutables).
4041
4042
4043              The LINK_FLAGS property can be used to add extra  flags  to  the
4044              link  step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
4045              figuration <CONFIG>, for example,  DEBUG,  RELEASE,  MINSIZEREL,
4046              RELWITHDEBINFO.  DEFINE_SYMBOL sets the name of the preprocessor
4047              symbol defined when compiling sources in a  shared  library.  If
4048              not  set  here then it is set to target_EXPORTS by default (with
4049              some substitutions if the target is not a valid  C  identifier).
4050              This  is  useful  for  headers  to  know  whether they are being
4051              included from inside their library or outside to properly  setup
4052              dllexport/dllimport decorations. The COMPILE_FLAGS property sets
4053              additional compiler flags used to build sources within the  tar‐
4054              get.   It may also be used to pass additional preprocessor defi‐
4055              nitions.
4056
4057
4058              The LINKER_LANGUAGE property is used to change the tool used  to
4059              link  an  executable  or  shared library. The default is set the
4060              language to match the files in the library. CXX and C are common
4061              values for this property.
4062
4063
4064              For  shared libraries VERSION and SOVERSION can be used to spec‐
4065              ify the build version and API version respectively. When  build‐
4066              ing  or installing appropriate symlinks are created if the plat‐
4067              form supports symlinks and the linker supports so-names. If only
4068              one of both is specified the missing is assumed to have the same
4069              version number. For executables VERSION can be used  to  specify
4070              the  build version. When building or installing appropriate sym‐
4071              links are created if the platform supports symlinks. For  shared
4072              libraries  and  executables  on Windows the VERSION attribute is
4073              parsed to extract a "major.minor" version number. These  numbers
4074              are used as the image version of the binary.
4075
4076
4077              There  are  a  few  properties  used  to  specify  RPATH  rules.
4078              INSTALL_RPATH is a semicolon-separated list specifying the rpath
4079              to  use  in  installed  targets (for platforms that support it).
4080              INSTALL_RPATH_USE_LINK_PATH is a boolean that  if  set  to  true
4081              will  append  directories  in the linker search path and outside
4082              the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a  boolean
4083              specifying  whether  to  skip  automatic  generation of an rpath
4084              allowing   the   target   to   run   from   the   build    tree.
4085              BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
4086              the target in the build tree with the INSTALL_RPATH.  This takes
4087              precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
4088              ing before installation.  INSTALL_NAME_DIR is a string  specify‐
4089              ing  the directory portion of the "install_name" field of shared
4090              libraries on Mac OSX to use in the installed targets.  When  the
4091              target    is    created    the    values    of   the   variables
4092              CMAKE_INSTALL_RPATH,          CMAKE_INSTALL_RPATH_USE_LINK_PATH,
4093              CMAKE_SKIP_BUILD_RPATH,    CMAKE_BUILD_WITH_INSTALL_RPATH,   and
4094              CMAKE_INSTALL_NAME_DIR are used to initialize these properties.
4095
4096
4097              PROJECT_LABEL can be used to change the name of the target in an
4098              IDE  like  visual  studio.   VS_KEYWORD can be set to change the
4099              visual studio keyword, for example Qt integration  works  better
4100              if this is set to Qt4VSv1.0.
4101
4102
4103              VS_SCC_PROJECTNAME,    VS_SCC_LOCALPATH,   VS_SCC_PROVIDER   and
4104              VS_SCC_AUXPATH can be set to  add  support  for  source  control
4105              bindings in a  Visual Studio project file.
4106
4107
4108              VS_GLOBAL_<variable>   can   be  set  to  add  a  Visual  Studio
4109              project-specific global variable. Qt integration works better if
4110              VS_GLOBAL_QtVersion  is  set  to  the  Qt  version FindQt4.cmake
4111              found. For example, "4.7.3"
4112
4113
4114              The PRE_INSTALL_SCRIPT and  POST_INSTALL_SCRIPT  properties  are
4115              the  old  way  to  specify CMake scripts to run before and after
4116              installing  a  target.   They  are  used  only  when   the   old
4117              INSTALL_TARGETS  command is used to install the target.  Use the
4118              INSTALL command instead.
4119
4120
4121              The EXCLUDE_FROM_DEFAULT_BUILD property is used  by  the  visual
4122              studio  generators.   If  it  is set to 1 the target will not be
4123              part of the default build when you select "Build Solution". This
4124              can   also   be   set   on   a   per-configuration  basis  using
4125              EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>.
4126
4127
4128       set_tests_properties
4129              Set a property of the tests.
4130
4131                set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
4132
4133              Set a property for the tests. If  the  property  is  not  found,
4134              CMake will report an error. The properties include:
4135
4136
4137              WILL_FAIL:  If  set to true, this will invert the pass/fail flag
4138              of the test.
4139
4140
4141              PASS_REGULAR_EXPRESSION: If set, the test output will be checked
4142              against  the  specified  regular expressions and at least one of
4143              the regular expressions has to match, otherwise  the  test  will
4144              fail.
4145
4146
4147                Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
4148
4149              FAIL_REGULAR_EXPRESSION: If set, if the output will match to one
4150              of specified regular expressions, the test will fail.
4151
4152
4153                Example: PASS_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
4154
4155              Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION  expect
4156              a list of regular expressions.
4157
4158
4159              TIMEOUT:  Setting this will limit the test runtime to the number
4160              of seconds specified.
4161
4162
4163
4164       site_name
4165              Set the given variable to the name of the computer.
4166
4167                site_name(variable)
4168
4169
4170       source_group
4171              Define a grouping for sources in the makefile.
4172
4173                source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])
4174
4175              Defines a group into which sources will  be  placed  in  project
4176              files.  This is mainly used to setup file tabs in Visual Studio.
4177              Any file whose name is listed or matches the regular  expression
4178              will  be  placed  in  this  group.   If  a file matches multiple
4179              groups, the LAST group that explicitly lists the  file  will  be
4180              favored,  if  any.   If  no group explicitly lists the file, the
4181              LAST group whose regular expression matches  the  file  will  be
4182              favored.
4183
4184
4185              The  name  of  the group may contain backslashes to specify sub‐
4186              groups:
4187
4188
4189                source_group(outer\\inner ...)
4190
4191              For backwards compatibility, this command also supports the for‐
4192              mat:
4193
4194
4195                source_group(name regex)
4196
4197
4198       string String operations.
4199
4200                string(REGEX MATCH <regular_expression>
4201                       <output variable> <input> [<input>...])
4202                string(REGEX MATCHALL <regular_expression>
4203                       <output variable> <input> [<input>...])
4204                string(REGEX REPLACE <regular_expression>
4205                       <replace_expression> <output variable>
4206                       <input> [<input>...])
4207                string(REPLACE <match_string>
4208                       <replace_string> <output variable>
4209                       <input> [<input>...])
4210                string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
4211                       <output variable> <input>)
4212                string(COMPARE EQUAL <string1> <string2> <output variable>)
4213                string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
4214                string(COMPARE LESS <string1> <string2> <output variable>)
4215                string(COMPARE GREATER <string1> <string2> <output variable>)
4216                string(ASCII <number> [<number> ...] <output variable>)
4217                string(CONFIGURE <string1> <output variable>
4218                       [@ONLY] [ESCAPE_QUOTES])
4219                string(TOUPPER <string1> <output variable>)
4220                string(TOLOWER <string1> <output variable>)
4221                string(LENGTH <string> <output variable>)
4222                string(SUBSTRING <string> <begin> <length> <output variable>)
4223                string(STRIP <string> <output variable>)
4224                string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
4225                       [RANDOM_SEED <seed>] <output variable>)
4226                string(FIND <string> <substring> <output variable> [REVERSE])
4227                string(TIMESTAMP <output variable> [<format string>] [UTC])
4228                string(MAKE_C_IDENTIFIER <input string> <output variable>)
4229
4230              REGEX MATCH will match the regular expression once and store the
4231              match in the output variable.
4232
4233
4234              REGEX MATCHALL will match the regular expression as  many  times
4235              as  possible  and  store the matches in the output variable as a
4236              list.
4237
4238
4239              REGEX REPLACE will match the regular expression as many times as
4240              possible and substitute the replacement expression for the match
4241              in the output.  The replace expression may refer to paren-delim‐
4242              ited  subexpressions  of  the match using \1, \2, ..., \9.  Note
4243              that two backslashes (\\1) are required in CMake code to  get  a
4244              backslash through argument parsing.
4245
4246
4247              REPLACE  will  replace  all  occurrences  of match_string in the
4248              input with replace_string and store the result in the output.
4249
4250
4251              MD5, SHA1, SHA224, SHA256, SHA384, and  SHA512  will  compute  a
4252              cryptographic hash of the input string.
4253
4254
4255              COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
4256              store true or false in the output variable.
4257
4258
4259              ASCII will convert all numbers into corresponding ASCII  charac‐
4260              ters.
4261
4262
4263              CONFIGURE will transform a string like CONFIGURE_FILE transforms
4264              a file.
4265
4266
4267              TOUPPER/TOLOWER will convert string to upper/lower characters.
4268
4269
4270              LENGTH will return a given string's length.
4271
4272
4273              SUBSTRING will return a substring of a given string.  If  length
4274              is  -1  the  remainder  of  the string starting at begin will be
4275              returned.
4276
4277
4278              STRIP will return a substring of a given string with leading and
4279              trailing spaces removed.
4280
4281
4282              RANDOM will return a random string of given length consisting of
4283              characters from the given alphabet. Default length is 5  charac‐
4284              ters  and  default  alphabet  is all numbers and upper and lower
4285              case letters.  If an integer RANDOM_SEED  is  given,  its  value
4286              will be used to seed the random number generator.
4287
4288
4289              FIND  will  return  the  position  where the given substring was
4290              found in the supplied string. If the REVERSE flag was used,  the
4291              command  will  search for the position of the last occurrence of
4292              the specified substring.
4293
4294
4295              The following characters have special meaning in regular expres‐
4296              sions:
4297
4298
4299                 ^         Matches at beginning of input
4300                 $         Matches at end of input
4301                 .         Matches any single character
4302                 [ ]       Matches any character(s) inside the brackets
4303                 [^ ]      Matches any character(s) not inside the brackets
4304                  -        Inside brackets, specifies an inclusive range between
4305                           characters on either side e.g. [a-f] is [abcdef]
4306                           To match a literal - using brackets, make it the first
4307                           or the last character e.g. [+*/-] matches basic
4308                           mathematical operators.
4309                 *         Matches preceding pattern zero or more times
4310                 +         Matches preceding pattern one or more times
4311                 ?         Matches preceding pattern zero or once only
4312                 |         Matches a pattern on either side of the |
4313                 ()        Saves a matched subexpression, which can be referenced
4314                           in the REGEX REPLACE operation. Additionally it is saved
4315                           by all regular expression-related commands, including
4316                           e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
4317
4318              *,  +  and  ?  have  higher precedence than concatenation. | has
4319              lower precedence than concatenation. This means that the regular
4320              expression "^ab+d$" matches "abbd" but not "ababd", and the reg‐
4321              ular expression "^(ab|cd)$" matches "ab" but not "abd".
4322
4323
4324              TIMESTAMP will write a string representation of the current date
4325              and/or time to the output variable.
4326
4327
4328              Should  the  command  be unable to obtain a timestamp the output
4329              variable will be set to the empty string "".
4330
4331
4332              The optional UTC flag requests the current date/time representa‐
4333              tion to be in Coordinated Universal Time (UTC) rather than local
4334              time.
4335
4336
4337              The optional <format string> may contain  the  following  format
4338              specifiers:
4339
4340
4341                 %d        The day of the current month (01-31).
4342                 %H        The hour on a 24-hour clock (00-23).
4343                 %I        The hour on a 12-hour clock (01-12).
4344                 %j        The day of the current year (001-366).
4345                 %m        The month of the current year (01-12).
4346                 %M        The minute of the current hour (00-59).
4347                 %S        The second of the current minute.
4348                           60 represents a leap second. (00-60)
4349                 %U        The week number of the current year (00-53).
4350                 %w        The day of the current week. 0 is Sunday. (0-6)
4351                 %y        The last two digits of the current year (00-99)
4352                 %Y        The current year.
4353
4354              Unknown format specifiers will be ignored and copied to the out‐
4355              put as-is.
4356
4357
4358              If no explicit <format string> is given it will default to:
4359
4360
4361                 %Y-%m-%dT%H:%M:%S    for local time.
4362                 %Y-%m-%dT%H:%M:%SZ   for UTC.
4363
4364              MAKE_C_IDENTIFIER will write a string which can be  used  as  an
4365              identifier in C.
4366
4367
4368       target_compile_definitions
4369              Add compile definitions to a target.
4370
4371                target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...]
4372                  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4373
4374              Specify  compile  definitions to use when compiling a given tar‐
4375              get.  The named <target> must have been  created  by  a  command
4376              such  as  add_executable  or  add_library  and  must  not  be an
4377              IMPORTED target.  The INTERFACE, PUBLIC and PRIVATE keywords are
4378              required  to specify the scope of the following arguments.  PRI‐
4379              VATE and PUBLIC  items  will  populate  the  COMPILE_DEFINITIONS
4380              property  of <target>.  PUBLIC and INTERFACE items will populate
4381              the INTERFACE_COMPILE_DEFINITIONS property  of  <target>.    The
4382              following arguments specify compile definitions.  Repeated calls
4383              for the same <target> append items in the order called.
4384
4385
4386              Arguments  to  target_compile_definitions  may  use   "generator
4387              expressions"  with  the  syntax "$<...>".  Generator expressions
4388              are evaluated during build system generation to produce informa‐
4389              tion  specific  to  each build configuration.  Valid expressions
4390              are:
4391
4392
4393                $<0:...>                  = empty string (ignores "...")
4394                $<1:...>                  = content of "..."
4395                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4396                $<CONFIGURATION>          = configuration name
4397                $<BOOL:...>               = '1' if the '...' is true, else '0'
4398                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4399                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4400                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4401                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4402                $<JOIN:list,...>          = joins the list with the content of "..."
4403                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4404                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4405                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4406                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4407                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4408                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4409                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4410                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4411                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4412                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4413                $<C_COMPILER_VERSION>     = The version of the C compiler used.
4414                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4415                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
4416                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4417                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
4418                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4419                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4420
4421              where "tgt" is the name of a target.   Target  file  expressions
4422              produce a full path, but _DIR and _NAME versions can produce the
4423              directory and file name components:
4424
4425
4426                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4427                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4428                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4429
4430
4431
4432
4433                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
4434
4435              Note that tgt is not added as a dependency of  the  target  this
4436              expression is evaluated on.
4437
4438
4439                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
4440                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4441
4442              Boolean expressions:
4443
4444
4445                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
4446                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
4447                $<NOT:?>                  = '0' if '?' is '1', else '1'
4448
4449              where '?' is always either '0' or '1'.
4450
4451
4452              Expressions with an implicit 'this' target:
4453
4454
4455                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
4456
4457
4458       target_compile_options
4459              Add compile options to a target.
4460
4461                target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
4462                  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4463
4464              Specify  compile  options  to use when compiling a given target.
4465              The named <target> must have been created by a command  such  as
4466              add_executable  or  add_library and must not be an IMPORTED tar‐
4467              get.  If BEFORE is specified, the content will be  prepended  to
4468              the property instead of being appended.
4469
4470
4471              The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
4472              ify the scope of the following arguments.   PRIVATE  and  PUBLIC
4473              items  will  populate  the COMPILE_OPTIONS property of <target>.
4474              PUBLIC and INTERFACE  items  will  populate  the  INTERFACE_COM‐
4475              PILE_OPTIONS  property  of  <target>.    The following arguments
4476              specify compile opitions.  Repeated calls for the same  <target>
4477              append items in the order called.
4478
4479
4480              Arguments  to  target_compile_options may use "generator expres‐
4481              sions" with the  syntax  "$<...>".   Generator  expressions  are
4482              evaluated  during build system generation to produce information
4483              specific to each build configuration.  Valid expressions are:
4484
4485
4486                $<0:...>                  = empty string (ignores "...")
4487                $<1:...>                  = content of "..."
4488                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4489                $<CONFIGURATION>          = configuration name
4490                $<BOOL:...>               = '1' if the '...' is true, else '0'
4491                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4492                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4493                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4494                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4495                $<JOIN:list,...>          = joins the list with the content of "..."
4496                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4497                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4498                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4499                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4500                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4501                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4502                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4503                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4504                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4505                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4506                $<C_COMPILER_VERSION>     = The version of the C compiler used.
4507                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4508                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
4509                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4510                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
4511                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4512                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4513
4514              where "tgt" is the name of a target.   Target  file  expressions
4515              produce a full path, but _DIR and _NAME versions can produce the
4516              directory and file name components:
4517
4518
4519                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4520                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4521                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4522
4523
4524
4525
4526                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
4527
4528              Note that tgt is not added as a dependency of  the  target  this
4529              expression is evaluated on.
4530
4531
4532                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
4533                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4534
4535              Boolean expressions:
4536
4537
4538                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
4539                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
4540                $<NOT:?>                  = '0' if '?' is '1', else '1'
4541
4542              where '?' is always either '0' or '1'.
4543
4544
4545              Expressions with an implicit 'this' target:
4546
4547
4548                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
4549
4550
4551       target_include_directories
4552              Add include directories to a target.
4553
4554                target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
4555                  [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4556
4557              Specify  include  directories or targets to use when compiling a
4558              given target.  The named <target> must have been  created  by  a
4559              command such as add_executable or add_library and must not be an
4560              IMPORTED target.
4561
4562
4563              If BEFORE is specified, the content will  be  prepended  to  the
4564              property instead of being appended.
4565
4566
4567              The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
4568              ify the scope of the following arguments.   PRIVATE  and  PUBLIC
4569              items  will  populate  the INCLUDE_DIRECTORIES property of <tar‐
4570              get>.  PUBLIC and  INTERFACE  items  will  populate  the  INTER‐
4571              FACE_INCLUDE_DIRECTORIES  property  of <target>.   The following
4572              arguments specify include directories.  Specified include direc‐
4573              tories  may be absolute paths or relative paths.  Repeated calls
4574              for the same <target> append items in the order called.If SYSTEM
4575              is  specified,  the  compiler  will  be told the directories are
4576              meant as system include  directories  on  some  platforms  (sig‐
4577              nalling  this setting might achieve effects such as the compiler
4578              skipping warnings, or these fixed-install system files not being
4579              considered  in dependency calculations - see compiler docs).  If
4580              SYSTEM is used together with PUBLIC  or  INTERFACE,  the  INTER‐
4581              FACE_SYSTEM_INCLUDE_DIRECTORIES  target  property  will be popu‐
4582              lated with the specified directories.
4583
4584
4585              Arguments  to  target_include_directories  may  use   "generator
4586              expressions"  with  the  syntax "$<...>".  Generator expressions
4587              are evaluated during build system generation to produce informa‐
4588              tion  specific  to  each build configuration.  Valid expressions
4589              are:
4590
4591
4592                $<0:...>                  = empty string (ignores "...")
4593                $<1:...>                  = content of "..."
4594                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4595                $<CONFIGURATION>          = configuration name
4596                $<BOOL:...>               = '1' if the '...' is true, else '0'
4597                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4598                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4599                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4600                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4601                $<JOIN:list,...>          = joins the list with the content of "..."
4602                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4603                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4604                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4605                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4606                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4607                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4608                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4609                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4610                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4611                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4612                $<C_COMPILER_VERSION>     = The version of the C compiler used.
4613                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4614                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
4615                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4616                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
4617                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4618                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4619
4620              where "tgt" is the name of a target.   Target  file  expressions
4621              produce a full path, but _DIR and _NAME versions can produce the
4622              directory and file name components:
4623
4624
4625                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4626                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4627                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4628
4629
4630
4631
4632                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
4633
4634              Note that tgt is not added as a dependency of  the  target  this
4635              expression is evaluated on.
4636
4637
4638                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
4639                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4640
4641              Boolean expressions:
4642
4643
4644                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
4645                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
4646                $<NOT:?>                  = '0' if '?' is '1', else '1'
4647
4648              where '?' is always either '0' or '1'.
4649
4650
4651              Expressions with an implicit 'this' target:
4652
4653
4654                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
4655
4656
4657       target_link_libraries
4658              Link a target to given libraries.
4659
4660                target_link_libraries(<target> [item1 [item2 [...]]]
4661                                      [[debug|optimized|general] <item>] ...)
4662
4663              Specify  libraries  or flags to use when linking a given target.
4664              The named <target> must have been created in the current  direc‐
4665              tory  by  a  command such as add_executable or add_library.  The
4666              remaining arguments specify library names  or  flags.   Repeated
4667              calls for the same <target> append items in the order called.
4668
4669
4670              If  a library name matches that of another target in the project
4671              a dependency will automatically be added in the build system  to
4672              make sure the library being linked is up-to-date before the tar‐
4673              get links.  Item names  starting  with  '-',  but  not  '-l'  or
4674              '-framework', are treated as linker flags.
4675
4676
4677              A  "debug", "optimized", or "general" keyword indicates that the
4678              library immediately following it is to be used only for the cor‐
4679              responding build configuration.  The "debug" keyword corresponds
4680              to the Debug configuration (or to configurations  named  in  the
4681              DEBUG_CONFIGURATIONS  global property if it is set).  The "opti‐
4682              mized" keyword corresponds to  all  other  configurations.   The
4683              "general"  keyword  corresponds  to  all  configurations, and is
4684              purely optional (assumed if omitted).  Higher granularity may be
4685              achieved  for per-configuration rules by creating and linking to
4686              IMPORTED  library  targets.   See  the  IMPORTED  mode  of   the
4687              add_library command for more information.
4688
4689
4690              Library  dependencies are transitive by default with this signa‐
4691              ture.  When this target is linked into another target  then  the
4692              libraries linked to this target will appear on the link line for
4693              the other target  too.   This  transitive  "link  interface"  is
4694              stored in the INTERFACE_LINK_LIBRARIES target property when pol‐
4695              icy CMP0022 is set to NEW and may be overridden by  setting  the
4696              property  directly.  (When CMP0022 is not set to NEW, transitive
4697              linking is builtin but may  be  overridden  by  the  LINK_INTER‐
4698              FACE_LIBRARIES property.  Calls to other signatures of this com‐
4699              mand may set the property making  any  libraries  linked  exclu‐
4700              sively by this signature private.)
4701
4702
4703              CMake  will  also  propagate  "usage  requirements"  from linked
4704              library  targets.   Usage  requirements  affect  compilation  of
4705              sources  in  the  <target>.   They  are  specified by properties
4706              defined on linked targets.  During generation of the build  sys‐
4707              tem, CMake integrates usage requirement property values with the
4708              corresponding build properties for <target>:
4709
4710
4711               INTERFACE_COMPILE_DEFINITONS: Appends to COMPILE_DEFINITONS
4712               INTERFACE_INCLUDE_DIRECTORIES: Appends to INCLUDE_DIRECTORIES
4713               INTERFACE_POSITION_INDEPENDENT_CODE: Sets POSITION_INDEPENDENT_CODE
4714                 or checked for consistency with existing value
4715
4716
4717
4718
4719              If an <item> is a library in a Mac  OX  framework,  the  Headers
4720              directory  of  the  framework will also be processed as a "usage
4721              requirement".  This has the same effect as passing the framework
4722              directory  as an include directory.  target_link_libraries(<tar‐
4723              get>
4724
4725
4726                                    <PRIVATE|PUBLIC|INTERFACE> <lib> ...
4727                                    [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
4728
4729              The PUBLIC, PRIVATE and INTERFACE keywords can be used to  spec‐
4730              ify  both  the  link  dependencies and the link interface in one
4731              command.  Libraries and targets following PUBLIC are linked  to,
4732              and  are made part of the link interface.  Libraries and targets
4733              following PRIVATE are linked to, but are not made  part  of  the
4734              link  interface.   Libraries following INTERFACE are appended to
4735              the link interface and are not used for linking <target>.
4736
4737
4738                target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
4739                                      [[debug|optimized|general] <lib>] ...)
4740
4741              The LINK_INTERFACE_LIBRARIES mode appends the libraries  to  the
4742              INTERFACE_LINK_LIBRARIES  target  property instead of using them
4743              for linking.  If policy CMP0022 is not NEW, then this mode  also
4744              appends   libraries  to  the  LINK_INTERFACE_LIBRARIES  and  its
4745              per-configuration equivalent.  This signature is for compatibil‐
4746              ity  only.  Prefer the INTERFACE mode instead.  Libraries speci‐
4747              fied as "debug" are wrapped in a generator expression to  corre‐
4748              spond  to  debug  builds.   If  policy  CMP0022  is not NEW, the
4749              libraries    are    also    appended    to    the    LINK_INTER‐
4750              FACE_LIBRARIES_DEBUG  property (or to the properties correspond‐
4751              ing to configurations listed in the DEBUG_CONFIGURATIONS  global
4752              property  if it is set).  Libraries specified as "optimized" are
4753              appended to the INTERFACE_LINK_LIBRARIES  property.   If  policy
4754              CMP0022  is  not  NEW, they are also appended to the LINK_INTER‐
4755              FACE_LIBRARIES property.  Libraries specified as  "general"  (or
4756              without  any  keyword)  are  treated  as  if  specified for both
4757              "debug" and "optimized".
4758
4759
4760                target_link_libraries(<target>
4761                                      <LINK_PRIVATE|LINK_PUBLIC>
4762                                        [[debug|optimized|general] <lib>] ...
4763                                      [<LINK_PRIVATE|LINK_PUBLIC>
4764                                        [[debug|optimized|general] <lib>] ...])
4765
4766              The LINK_PUBLIC and LINK_PRIVATE modes can be  used  to  specify
4767              both  the  link  dependencies and the link interface in one com‐
4768              mand.  This signature is for compatibility only. Prefer the PUB‐
4769              LIC  or PRIVATE keywords instead.  Libraries and targets follow‐
4770              ing LINK_PUBLIC are linked to, and are made part of  the  INTER‐
4771              FACE_LINK_LIBRARIES.   If  policy  CMP0022  is not NEW, they are
4772              also made part of the LINK_INTERFACE_LIBRARIES.   Libraries  and
4773              targets  following  LINK_PRIVATE are linked to, but are not made
4774              part   of   the   INTERFACE_LINK_LIBRARIES    (or    LINK_INTER‐
4775              FACE_LIBRARIES).
4776
4777
4778              The library dependency graph is normally acyclic (a DAG), but in
4779              the case of mutually-dependent STATIC libraries CMake allows the
4780              graph  to  contain cycles (strongly connected components).  When
4781              another target links to one of the libraries CMake  repeats  the
4782              entire connected component.  For example, the code
4783
4784
4785                add_library(A STATIC a.c)
4786                add_library(B STATIC b.c)
4787                target_link_libraries(A B)
4788                target_link_libraries(B A)
4789                add_executable(main main.c)
4790                target_link_libraries(main A)
4791
4792              links  'main'  to  'A  B A B'.  (While one repetition is usually
4793              sufficient, pathological object file and symbol arrangements can
4794              require  more.   One may handle such cases by manually repeating
4795              the component in the last target_link_libraries call.   However,
4796              if  two archives are really so interdependent they should proba‐
4797              bly be combined into a single archive.)
4798
4799
4800              Arguments to target_link_libraries may  use  "generator  expres‐
4801              sions"  with  the syntax "$<...>".  Note however, that generator
4802              expressions will not be used  in  OLD  handling  of  CMP0003  or
4803              CMP0004.
4804
4805
4806              Generator  expressions are evaluated during build system genera‐
4807              tion to produce information specific to  each  build  configura‐
4808              tion.  Valid expressions are:
4809
4810
4811                $<0:...>                  = empty string (ignores "...")
4812                $<1:...>                  = content of "..."
4813                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4814                $<CONFIGURATION>          = configuration name
4815                $<BOOL:...>               = '1' if the '...' is true, else '0'
4816                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4817                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4818                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4819                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4820                $<JOIN:list,...>          = joins the list with the content of "..."
4821                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4822                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4823                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4824                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4825                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4826                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4827                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4828                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4829                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4830                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4831                $<C_COMPILER_VERSION>     = The version of the C compiler used.
4832                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4833                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
4834                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4835                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
4836                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4837                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4838
4839              where  "tgt"  is  the name of a target.  Target file expressions
4840              produce a full path, but _DIR and _NAME versions can produce the
4841              directory and file name components:
4842
4843
4844                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4845                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4846                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4847
4848
4849
4850
4851                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
4852
4853              Note  that  tgt  is not added as a dependency of the target this
4854              expression is evaluated on.
4855
4856
4857                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
4858                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4859
4860              Boolean expressions:
4861
4862
4863                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
4864                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
4865                $<NOT:?>                  = '0' if '?' is '1', else '1'
4866
4867              where '?' is always either '0' or '1'.
4868
4869
4870              Expressions with an implicit 'this' target:
4871
4872
4873                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
4874
4875
4876       try_compile
4877              Try building some code.
4878
4879                try_compile(RESULT_VAR <bindir> <srcdir>
4880                            <projectName> [targetName] [CMAKE_FLAGS flags...]
4881                            [OUTPUT_VARIABLE <var>])
4882
4883              Try building a project.  In this form, srcdir should  contain  a
4884              complete  CMake  project  with  a  CMakeLists.txt  file  and all
4885              sources. The bindir and srcdir will not be  deleted  after  this
4886              command  is  run.  Specify targetName to build a specific target
4887              instead of the 'all' or 'ALL_BUILD' target.
4888
4889
4890                try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
4891                            [CMAKE_FLAGS flags...]
4892                            [COMPILE_DEFINITIONS flags...]
4893                            [LINK_LIBRARIES libs...]
4894                            [OUTPUT_VARIABLE <var>]
4895                            [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
4896
4897              Try building an executable from one or more  source  files.   In
4898              this  form  the  user  need only supply one or more source files
4899              that include a definition  for  'main'.   CMake  will  create  a
4900              CMakeLists.txt  file  to  build  the source(s) as an executable.
4901              Specify COPY_FILE to get a copy of the linked executable at  the
4902              given  fileName  and  optionally  COPY_FILE_ERROR to capture any
4903              error.
4904
4905
4906              In this version all files in bindir/CMakeFiles/CMakeTmp will  be
4907              cleaned  automatically. For debugging, --debug-trycompile can be
4908              passed to cmake to avoid this clean. However,  multiple  sequen‐
4909              tial  try_compile operations reuse this single output directory.
4910              If you use --debug-trycompile, you can only debug  one  try_com‐
4911              pile  call  at a time. The recommended procedure is to configure
4912              with cmake all the way through once, then delete the cache entry
4913              associated  with  the  try_compile  call  of  interest, and then
4914              re-run cmake again with --debug-trycompile.
4915
4916
4917              Some extra flags that can be included are,  INCLUDE_DIRECTORIES,
4918              LINK_DIRECTORIES,  and  LINK_LIBRARIES.  COMPILE_DEFINITIONS are
4919              -Ddefinition that will be passed to the compile line.
4920
4921
4922              The srcfile signature also  accepts  a  LINK_LIBRARIES  argument
4923              which  may contain a list of libraries or IMPORTED targets which
4924              will be linked to in the generated project.   If  LINK_LIBRARIES
4925              is   specified   as   a   parameter  to  try_compile,  then  any
4926              LINK_LIBRARIES passed as CMAKE_FLAGS will be ignored.
4927
4928
4929              try_compile creates a CMakeList.txt file on the fly  that  looks
4930              like this:
4931
4932
4933                add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
4934                include_directories(${INCLUDE_DIRECTORIES})
4935                link_directories(${LINK_DIRECTORIES})
4936                add_executable(cmTryCompileExec sources)
4937                target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
4938
4939              In  both  versions  of the command, if OUTPUT_VARIABLE is speci‐
4940              fied, then the output from the build process is  stored  in  the
4941              given  variable. The success or failure of the try_compile, i.e.
4942              TRUE  or  FALSE  respectively,  is   returned   in   RESULT_VAR.
4943              CMAKE_FLAGS  can  be  used to pass -DVAR:TYPE=VALUE flags to the
4944              cmake that is run during the build. Set variable  CMAKE_TRY_COM‐
4945              PILE_CONFIGURATION to choose a build configuration.
4946
4947
4948       try_run
4949              Try compiling and then running some code.
4950
4951                try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
4952                        bindir srcfile [CMAKE_FLAGS <Flags>]
4953                        [COMPILE_DEFINITIONS <flags>]
4954                        [COMPILE_OUTPUT_VARIABLE comp]
4955                        [RUN_OUTPUT_VARIABLE run]
4956                        [OUTPUT_VARIABLE var]
4957                        [ARGS <arg1> <arg2>...])
4958
4959              Try  compiling  a  srcfile.  Return TRUE or FALSE for success or
4960              failure in COMPILE_RESULT_VAR.  Then if the  compile  succeeded,
4961              run  the  executable and return its exit code in RUN_RESULT_VAR.
4962              If  the  executable  was  built,  but  failed   to   run,   then
4963              RUN_RESULT_VAR   will  be  set  to  FAILED_TO_RUN.  COMPILE_OUT‐
4964              PUT_VARIABLE specifies the variable where the  output  from  the
4965              compile  step  goes.  RUN_OUTPUT_VARIABLE specifies the variable
4966              where the output from the running executable goes.
4967
4968
4969              For compatibility reasons OUTPUT_VARIABLE  is  still  supported,
4970              which  gives  you  the output from the compile and run step com‐
4971              bined.
4972
4973
4974              Cross compiling issues
4975
4976
4977              When cross compiling, the executable compiled in the first  step
4978              usually  cannot  be  run on the build host. try_run() checks the
4979              CMAKE_CROSSCOMPILING variable to  detect  whether  CMake  is  in
4980              crosscompiling  mode.  If  that's the case, it will still try to
4981              compile the executable, but it will not  try  to  run  the  exe‐
4982              cutable.  Instead  it  will create cache variables which must be
4983              filled by the user or by presetting them in  some  CMake  script
4984              file  to the values the executable would have produced if it had
4985              been run on its actual  target  platform.  These  variables  are
4986              RUN_RESULT_VAR  (explanation  see above) and if RUN_OUTPUT_VARI‐
4987              ABLE (or OUTPUT_VARIABLE) was used, an additional cache variable
4988              RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This        is
4989              intended to hold stdout and stderr from the executable.
4990
4991
4992              In order to  make  cross  compiling  your  project  easier,  use
4993              try_run  only  if  really  required.  If  you  use  try_run, use
4994              RUN_OUTPUT_VARIABLE  (or   OUTPUT_VARIABLE)   only   if   really
4995              required.  Using them will require that when crosscompiling, the
4996              cache variables will have to be set manually to  the  output  of
4997              the  executable.  You can also "guard" the calls to try_run with
4998              if(CMAKE_CROSSCOMPILING) and provide an easy-to-preset  alterna‐
4999              tive for this case.
5000
5001
5002              Set  variable  CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
5003              configuration.
5004
5005
5006       unset  Unset a variable, cache variable, or environment variable.
5007
5008                unset(<variable> [CACHE])
5009
5010              Removes the specified variable causing it to  become  undefined.
5011              If  CACHE is present then the variable is removed from the cache
5012              instead of the current scope.
5013
5014
5015              <variable> can be an environment variable such as:
5016
5017
5018                unset(ENV{LD_LIBRARY_PATH})
5019
5020              in which case the variable will  be  removed  from  the  current
5021              environment.
5022
5023
5024       variable_watch
5025              Watch the CMake variable for change.
5026
5027                variable_watch(<variable name> [<command to execute>])
5028
5029              If  the  specified variable changes, the message will be printed
5030              about the variable being changed. If the command  is  specified,
5031              the  command will be executed. The command will receive the fol‐
5032              lowing arguments: COMMAND(<variable> <access>  <value>  <current
5033              list file> <stack>)
5034
5035
5036       while  Evaluate a group of commands while a condition is true
5037
5038                while(condition)
5039                  COMMAND1(ARGS ...)
5040                  COMMAND2(ARGS ...)
5041                  ...
5042                endwhile(condition)
5043
5044              All  commands  between  while  and  the  matching  endwhile  are
5045              recorded without being invoked.  Once the endwhile is evaluated,
5046              the  recorded  list of commands is invoked as long as the condi‐
5047              tion is true. The condition is evaluated using the same logic as
5048              the if command.
5049
5050
5052       Copyright  2000-2012  Kitware,  Inc., Insight Software Consortium.  All
5053       rights reserved.
5054
5055
5056       Redistribution and use in source and binary forms, with or without mod‐
5057       ification,  are  permitted  provided  that the following conditions are
5058       met:
5059
5060
5061       Redistributions of source code must retain the above copyright  notice,
5062       this list of conditions and the following disclaimer.
5063
5064
5065       Redistributions  in  binary  form  must  reproduce  the above copyright
5066       notice, this list of conditions and the  following  disclaimer  in  the
5067       documentation and/or other materials provided with the distribution.
5068
5069
5070       Neither  the  names  of Kitware, Inc., the Insight Software Consortium,
5071       nor the names of their contributors may be used to endorse  or  promote
5072       products derived from this software without specific prior written per‐
5073       mission.
5074
5075
5076       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
5077       IS"  AND  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
5078       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
5079       ULAR  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
5080       CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,  INCIDENTAL,  SPECIAL,
5081       EXEMPLARY,  OR  CONSEQUENTIAL  DAMAGES  (INCLUDING, BUT NOT LIMITED TO,
5082       PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;  LOSS  OF  USE,  DATA,  OR
5083       PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
5084       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,  OR  TORT  (INCLUDING
5085       NEGLIGENCE  OR  OTHERWISE)  ARISING  IN  ANY WAY OUT OF THE USE OF THIS
5086       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5087
5088

SEE ALSO

5090       The following resources are available to get help using CMake:
5091
5092
5093       Home Page
5094              http://www.cmake.org
5095
5096              The primary starting point for learning about CMake.
5097
5098
5099       Frequently Asked Questions
5100              http://www.cmake.org/Wiki/CMake_FAQ
5101
5102              A Wiki is provided containing answers to frequently asked  ques‐
5103              tions.
5104
5105
5106       Online Documentation
5107              http://www.cmake.org/HTML/Documentation.html
5108
5109              Links to available documentation may be found on this web page.
5110
5111
5112       Mailing List
5113              http://www.cmake.org/HTML/MailingLists.html
5114
5115              For  help  and  discussion  about using cmake, a mailing list is
5116              provided at cmake@cmake.org. The list  is  member-post-only  but
5117              one  may  sign  up  on the CMake web page. Please first read the
5118              full documentation at http://www.cmake.org before posting  ques‐
5119              tions to the list.
5120
5121
5122
5123
5124cmake 2.8.12.2                 November 05, 2016              cmakecommands(1)
Impressum