1CMAKE-COMMANDS(7)                    CMake                   CMAKE-COMMANDS(7)
2
3
4

NAME

6       cmake-commands - CMake Language Command Reference
7

SCRIPTING COMMANDS

9       These commands are always available.
10
11   break
12       Break from an enclosing foreach or while loop.
13
14          break()
15
16       Breaks from an enclosing foreach loop or while loop
17
18       See also the continue() command.
19
20   cmake_host_system_information
21       Query host system specific information.
22
23          cmake_host_system_information(RESULT <variable> QUERY <key> ...)
24
25       Queries system information of the host system on which cmake runs.  One
26       or more <key> can be provided to select the information to be  queried.
27       The list of queried values is stored in <variable>.
28
29       <key> can be one of the following values:
30
31              ┌──────────────────────────┬────────────────────────────┐
32              │Key                       │ Description                │
33              ├──────────────────────────┼────────────────────────────┤
34NUMBER_OF_LOGICAL_CORES   │ Number of logical cores    │
35              ├──────────────────────────┼────────────────────────────┤
36NUMBER_OF_PHYSICAL_CORES  │ Number of physical cores   │
37              ├──────────────────────────┼────────────────────────────┤
38HOSTNAME                  │ Hostname                   │
39              ├──────────────────────────┼────────────────────────────┤
40FQDN                      │ Fully   qualified   domain │
41              │                          │ name                       │
42              ├──────────────────────────┼────────────────────────────┤
43TOTAL_VIRTUAL_MEMORY      │ Total  virtual  memory  in │
44              │                          │ megabytes                  │
45              ├──────────────────────────┼────────────────────────────┤
46AVAILABLE_VIRTUAL_MEMORY  │ Available  virtual  memory │
47              │                          │ in megabytes               │
48              ├──────────────────────────┼────────────────────────────┤
49TOTAL_PHYSICAL_MEMORY     │ Total physical  memory  in │
50              │                          │ megabytes                  │
51              ├──────────────────────────┼────────────────────────────┤
52AVAILABLE_PHYSICAL_MEMORY │ Available  physical memory │
53              │                          │ in megabytes               │
54              ├──────────────────────────┼────────────────────────────┤
55IS_64BIT                  │ One if processor is 64Bit  │
56              ├──────────────────────────┼────────────────────────────┤
57HAS_FPU                   │ One   if   processor   has │
58              │                          │ floating point unit        │
59              ├──────────────────────────┼────────────────────────────┤
60HAS_MMX                   │ One  if processor supports │
61              │                          │ MMX instructions           │
62              ├──────────────────────────┼────────────────────────────┤
63HAS_MMX_PLUS              │ One if porcessor  supports │
64              │                          │ Ext. MMX instructions      │
65              └──────────────────────────┴────────────────────────────┘
66
67HAS_SSE                   │ One  if porcessor supports │
68              │                          │ SSE instructions           │
69              ├──────────────────────────┼────────────────────────────┤
70HAS_SSE2                  │ One if porcessor  supports │
71              │                          │ SSE2 instructions          │
72              ├──────────────────────────┼────────────────────────────┤
73HAS_SSE_FP                │ One  if porcessor supports │
74              │                          │ SSE FP instructions        │
75              ├──────────────────────────┼────────────────────────────┤
76HAS_SSE_MMX               │ One if porcessor  supports │
77              │                          │ SSE MMX instructions       │
78              ├──────────────────────────┼────────────────────────────┤
79HAS_AMD_3DNOW             │ One  if porcessor supports │
80              │                          │ 3DNow instructions         │
81              ├──────────────────────────┼────────────────────────────┤
82HAS_AMD_3DNOW_PLUS        │ One if porcessor  supports │
83              │                          │ 3DNow+ instructions        │
84              ├──────────────────────────┼────────────────────────────┤
85HAS_IA64                  │ One if IA64 processor emu‐ │
86              │                          │ lating x86                 │
87              ├──────────────────────────┼────────────────────────────┤
88HAS_SERIAL_NUMBER         │ One   if   processor   has │
89              │                          │ serial number              │
90              ├──────────────────────────┼────────────────────────────┤
91PROCESSOR_SERIAL_NUMBER   │ Processor serial number    │
92              ├──────────────────────────┼────────────────────────────┤
93PROCESSOR_NAME            │ Human  readable  processor │
94              │                          │ name                       │
95              ├──────────────────────────┼────────────────────────────┤
96PROCESSOR_DESCRIPTION     │ Human readable  full  pro‐ │
97              │                          │ cessor description         │
98              ├──────────────────────────┼────────────────────────────┤
99OS_NAME                   │ See CMAKE_HOST_SYSTEM_NAME 
100              ├──────────────────────────┼────────────────────────────┤
101OS_RELEASE                │ The  OS  sub-type  e.g. on │
102              │                          │ Windows Professional       
103              ├──────────────────────────┼────────────────────────────┤
104OS_VERSION                │ The OS build ID            │
105              ├──────────────────────────┼────────────────────────────┤
106OS_PLATFORM               │ See CMAKE_HOST_SYSTEM_PRO‐ 
107              │                          │ CESSOR                     
108              └──────────────────────────┴────────────────────────────┘
109
110   cmake_minimum_required
111       Set  the  minimum  required  version  of cmake for a project and update
112       Policy Settings to match the version given:
113
114          cmake_minimum_required(VERSION major.minor[.patch[.tweak]]
115                                 [FATAL_ERROR])
116
117       If the current version of CMake is lower than  that  required  it  will
118       stop processing the project and report an error.
119
120       The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
121       It should be specified so CMake versions 2.4 and  lower  fail  with  an
122       error instead of just a warning.
123
124       NOTE:
125          Call  the  cmake_minimum_required()  command at the beginning of the
126          top-level CMakeLists.txt file even before calling the project() com‐
127          mand.   It  is  important  to  establish version and policy settings
128          before invoking other commands whose behavior they may affect.   See
129          also policy CMP0000.
130
131          Calling  cmake_minimum_required()  inside  a  function() limits some
132          effects to the function scope when invoked.  Such calls  should  not
133          be made with the intention of having global effects.
134
135   Policy Settings
136       The  cmake_minimum_required(VERSION)  command  implicitly  invokes  the
137       cmake_policy(VERSION) command to specify that the current project  code
138       is  written for the given version of CMake.  All policies introduced in
139       the specified version or earlier will be set to use NEW behavior.   All
140       policies  introduced  after  the specified version will be unset.  This
141       effectively requests behavior preferred as of a given CMake version and
142       tells newer CMake versions to warn about their new policies.
143
144       When  a  version  higher  than  2.4 is specified the command implicitly
145       invokes:
146
147          cmake_policy(VERSION major[.minor[.patch[.tweak]]])
148
149       which sets the cmake policy version level  to  the  version  specified.
150       When version 2.4 or lower is given the command implicitly invokes:
151
152          cmake_policy(VERSION 2.4)
153
154       which enables compatibility features for CMake 2.4 and lower.
155
156   cmake_parse_arguments
157       cmake_parse_arguments is intended to be used in macros or functions for
158       parsing the arguments given to that macro or  function.   It  processes
159       the  arguments  and defines a set of variables which hold the values of
160       the respective options.
161
162          cmake_parse_arguments(<prefix> <options> <one_value_keywords>
163                                <multi_value_keywords> args...)
164
165          cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
166                                <multi_value_keywords>)
167
168       The first signature reads processes arguments passed  in  the  args....
169       This may be used in either a macro() or a function().
170
171       The PARSE_ARGV signature is only for use in a function() body.  In this
172       case the arguments that are parsed come from the ARGV# variables of the
173       calling function.  The parsing starts with the Nth argument, where N is
174       an unsigned integer.  This allows for the values to have special  char‐
175       acters like ; in them.
176
177       The  <options>  argument contains all options for the respective macro,
178       i.e.  keywords which can be used when calling  the  macro  without  any
179       value  following, like e.g.  the OPTIONAL keyword of the install() com‐
180       mand.
181
182       The <one_value_keywords> argument contains all keywords for this  macro
183       which  are  followed by one value, like e.g. DESTINATION keyword of the
184       install() command.
185
186       The <multi_value_keywords> argument  contains  all  keywords  for  this
187       macro  which can be followed by more than one value, like e.g. the TAR‐
188       GETS or FILES keywords of the install() command.
189
190       NOTE:
191          All keywords shall be unique. I.e. every keyword shall only be spec‐
192          ified    once   in   either   <options>,   <one_value_keywords>   or
193          <multi_value_keywords>. A warning will be emitted if  uniqueness  is
194          violated.
195
196       When done, cmake_parse_arguments will consider for each of the keywords
197       listed in <options>, <one_value_keywords> and <multi_value_keywords>  a
198       variable composed of the given <prefix> followed by "_" and the name of
199       the respective keyword.  These variables will then hold the  respective
200       value  from  the argument list or be undefined if the associated option
201       could not be found.  For the <options> keywords, these will  always  be
202       defined,  to  TRUE or FALSE, whether the option is in the argument list
203       or not.
204
205       All  remaining  arguments   are   collected   in   a   variable   <pre‐
206       fix>_UNPARSED_ARGUMENTS  that  will  be undefined if all argument where
207       recognized. This can be checked afterwards to see  whether  your  macro
208       was called with unrecognized parameters.
209
210       As  an example here a my_install() macro, which takes similar arguments
211       as the real install() command:
212
213          macro(my_install)
214              set(options OPTIONAL FAST)
215              set(oneValueArgs DESTINATION RENAME)
216              set(multiValueArgs TARGETS CONFIGURATIONS)
217              cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
218                                    "${multiValueArgs}" ${ARGN} )
219
220              # ...
221
222       Assume my_install() has been called like this:
223
224          my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
225
226       After the cmake_parse_arguments call the macro will have set  or  unde‐
227       fined the following variables:
228
229          MY_INSTALL_OPTIONAL = TRUE
230          MY_INSTALL_FAST = FALSE # was not used in call to my_install
231          MY_INSTALL_DESTINATION = "bin"
232          MY_INSTALL_RENAME <UNDEFINED> # was not used
233          MY_INSTALL_TARGETS = "foo;bar"
234          MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
235          MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
236
237       You can then continue and process these variables.
238
239       Keywords   terminate  lists  of  values,  e.g.   if  directly  after  a
240       one_value_keyword another recognized keyword follows,  this  is  inter‐
241       preted  as  the  beginning of the new option.  E.g.  my_install(TARGETS
242       foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
243       "OPTIONAL",  but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
244       will be empty and MY_INSTALL_OPTIONAL will therefore be set to TRUE.
245
246   cmake_policy
247       Manage CMake Policy settings.  See  the  cmake-policies(7)  manual  for
248       defined policies.
249
250       As  CMake evolves it is sometimes necessary to change existing behavior
251       in order to fix bugs or improve implementations of  existing  features.
252       The  CMake  Policy mechanism is designed to help keep existing projects
253       building as new versions of CMake introduce changes in behavior.   Each
254       new  policy  (behavioral  change)  is  given  an identifier of the form
255       CMP<NNNN> where <NNNN> is an integer index.   Documentation  associated
256       with  each policy describes the OLD and NEW behavior and the reason the
257       policy was introduced.  Projects may set  each  policy  to  select  the
258       desired  behavior.   When  CMake needs to know which behavior to use it
259       checks for a setting specified by the project.  If no setting is avail‐
260       able  the  OLD behavior is assumed and a warning is produced requesting
261       that the policy be set.
262
263   Setting Policies by CMake Version
264       The cmake_policy command is used to set policies to OLD or  NEW  behav‐
265       ior.   While  setting  policies individually is supported, we encourage
266       projects to set policies based on CMake versions:
267
268          cmake_policy(VERSION major.minor[.patch[.tweak]])
269
270       Specify that the current CMake code is written for the given version of
271       CMake.   All  policies  introduced  in the specified version or earlier
272       will be set to use NEW behavior.  All  policies  introduced  after  the
273       specified    version    will    be   unset   (unless   the   CMAKE_POL‐
274       ICY_DEFAULT_CMP<NNNN>  variable  sets  a  default).   This  effectively
275       requests behavior preferred as of a given CMake version and tells newer
276       CMake versions to warn about their new policies.   The  policy  version
277       specified must be at least 2.4 or the command will report an error.
278
279       Note  that the cmake_minimum_required(VERSION) command implicitly calls
280       cmake_policy(VERSION) too.
281
282   Setting Policies Explicitly
283          cmake_policy(SET CMP<NNNN> NEW)
284          cmake_policy(SET CMP<NNNN> OLD)
285
286       Tell CMake to use the OLD or NEW behavior for a given policy.  Projects
287       depending  on  the  old behavior of a given policy may silence a policy
288       warning by setting the policy state to OLD.  Alternatively one may  fix
289       the  project  to work with the new behavior and set the policy state to
290       NEW.
291
292       NOTE:
293          The OLD behavior of a policy is deprecated by definition and may  be
294          removed in a future version of CMake.
295
296   Checking Policy Settings
297          cmake_policy(GET CMP<NNNN> <variable>)
298
299       Check whether a given policy is set to OLD or NEW behavior.  The output
300       <variable> value will be OLD or NEW if the policy  is  set,  and  empty
301       otherwise.
302
303   CMake Policy Stack
304       CMake  keeps  policy  settings  on  a  stack,  so  changes  made by the
305       cmake_policy command affect only the top of the stack.  A new entry  on
306       the policy stack is managed automatically for each subdirectory to pro‐
307       tect its parents and siblings.  CMake also  manages  a  new  entry  for
308       scripts  loaded  by  include()  and find_package() commands except when
309       invoked with the NO_POLICY_SCOPE option (see also policy CMP0011).  The
310       cmake_policy  command provides an interface to manage custom entries on
311       the policy stack:
312
313          cmake_policy(PUSH)
314          cmake_policy(POP)
315
316       Each PUSH must have a matching POP to erase any changes.  This is  use‐
317       ful  to  make  temporary  changes  to  policy  settings.   Calls to the
318       cmake_minimum_required(VERSION), cmake_policy(VERSION),  or  cmake_pol‐
319       icy(SET) commands influence only the current top of the policy stack.
320
321       Commands  created  by the function() and macro() commands record policy
322       settings when they are created and use  the  pre-record  policies  when
323       they  are  invoked.  If the function or macro implementation sets poli‐
324       cies, the changes automatically propagate up through callers until they
325       reach the closest nested policy stack entry.
326
327   configure_file
328       Copy a file to another location and modify its contents.
329
330          configure_file(<input> <output>
331                         [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
332                         [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
333
334       Copies  an  <input>  file  to an <output> file and substitutes variable
335       values referenced as @VAR@ or ${VAR} in the input file  content.   Each
336       variable reference will be replaced with the current value of the vari‐
337       able, or the empty string if the variable is not defined.  Furthermore,
338       input lines of the form:
339
340          #cmakedefine VAR ...
341
342       will be replaced with either:
343
344          #define VAR ...
345
346       or:
347
348          /* #undef VAR */
349
350       depending  on whether VAR is set in CMake to any value not considered a
351       false constant by the if() command.  The “…” content on the line  after
352       the  variable name, if any, is processed as above.  Input file lines of
353       the form #cmakedefine01 VAR will be replaced with either #define VAR  1
354       or  #define  VAR  0 similarly.  The result lines (with the exception of
355       the #undef comments) can be indented using spaces and/or  tabs  between
356       the # character and the cmakedefine or cmakedefine01 words. This white‐
357       space indentation will be preserved in the output lines:
358
359          #  cmakedefine VAR
360          #  cmakedefine01 VAR
361
362       will be replaced, if VAR is defined, with:
363
364          #  define VAR
365          #  define VAR 1
366
367       If the input file is modified the build system  will  re-run  CMake  to
368       re-configure  the file and generate the build system again.  The gener‐
369       ated file is modified and its timestamp  updated  on  subsequent  cmake
370       runs only if its content is changed.
371
372       The arguments are:
373
374       <input>
375              Path to the input file.  A relative path is treated with respect
376              to the value of CMAKE_CURRENT_SOURCE_DIR.  The input  path  must
377              be a file, not a directory.
378
379       <output>
380              Path  to  the  output  file  or  directory.   A relative path is
381              treated with respect to the value  of  CMAKE_CURRENT_BINARY_DIR.
382              If  the  path  names  an  existing  directory the output file is
383              placed in that directory with the same file name  as  the  input
384              file.
385
386       COPYONLY
387              Copy the file without replacing any variable references or other
388              content.  This option may not be used with NEWLINE_STYLE.
389
390       ESCAPE_QUOTES
391              Escape any substituted quotes with backslashes (C-style).
392
393       @ONLY  Restrict variable replacement to references of the  form  @VAR@.
394              This is useful for configuring scripts that use ${VAR} syntax.
395
396       NEWLINE_STYLE <style>
397              Specify  the newline style for the output file.  Specify UNIX or
398              LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
399              lines.  This option may not be used with COPYONLY.
400
401   Example
402       Consider a source tree containing a foo.h.in file:
403
404          #cmakedefine FOO_ENABLE
405          #cmakedefine FOO_STRING "@FOO_STRING@"
406
407       An  adjacent  CMakeLists.txt  may  use  configure_file to configure the
408       header:
409
410          option(FOO_ENABLE "Enable Foo" ON)
411          if(FOO_ENABLE)
412            set(FOO_STRING "foo")
413          endif()
414          configure_file(foo.h.in foo.h @ONLY)
415
416       This creates a foo.h in  the  build  directory  corresponding  to  this
417       source  directory.  If the FOO_ENABLE option is on, the configured file
418       will contain:
419
420          #define FOO_ENABLE
421          #define FOO_STRING "foo"
422
423       Otherwise it will contain:
424
425          /* #undef FOO_ENABLE */
426          /* #undef FOO_STRING */
427
428       One may then use the include_directories() command to specify the  out‐
429       put directory as an include directory:
430
431          include_directories(${CMAKE_CURRENT_BINARY_DIR})
432
433       so that sources may include the header as #include <foo.h>.
434
435   continue
436       Continue to the top of enclosing foreach or while loop.
437
438          continue()
439
440       The continue command allows a cmake script to abort the rest of a block
441       in a foreach() or while() loop, and start at the top of the next itera‐
442       tion.  See also the break() command.
443
444   elseif
445       Starts the elseif portion of an if block.
446
447          elseif(expression)
448
449       See the if() command.
450
451   else
452       Starts the else portion of an if block.
453
454          else(expression)
455
456       See the if() command.
457
458   endforeach
459       Ends a list of commands in a foreach block.
460
461          endforeach(expression)
462
463       See the foreach() command.
464
465   endfunction
466       Ends a list of commands in a function block.
467
468          endfunction(expression)
469
470       See the function() command.
471
472   endif
473       Ends a list of commands in an if block.
474
475          endif(expression)
476
477       See the if() command.
478
479   endmacro
480       Ends a list of commands in a macro block.
481
482          endmacro(expression)
483
484       See the macro() command.
485
486   endwhile
487       Ends a list of commands in a while block.
488
489          endwhile(expression)
490
491       See the while() command.
492
493   execute_process
494       Execute one or more child processes.
495
496          execute_process(COMMAND <cmd1> [args1...]]
497                          [COMMAND <cmd2> [args2...] [...]]
498                          [WORKING_DIRECTORY <directory>]
499                          [TIMEOUT <seconds>]
500                          [RESULT_VARIABLE <variable>]
501                          [RESULTS_VARIABLE <variable>]
502                          [OUTPUT_VARIABLE <variable>]
503                          [ERROR_VARIABLE <variable>]
504                          [INPUT_FILE <file>]
505                          [OUTPUT_FILE <file>]
506                          [ERROR_FILE <file>]
507                          [OUTPUT_QUIET]
508                          [ERROR_QUIET]
509                          [OUTPUT_STRIP_TRAILING_WHITESPACE]
510                          [ERROR_STRIP_TRAILING_WHITESPACE]
511                          [ENCODING <name>])
512
513       Runs  the  given  sequence of one or more commands in parallel with the
514       standard output of each process piped to  the  standard  input  of  the
515       next.  A single standard error pipe is used for all processes.
516
517       Options:
518
519       COMMAND
520              A child process command line.
521
522              CMake  executes  the  child  process using operating system APIs
523              directly.  All  arguments  are  passed  VERBATIM  to  the  child
524              process.  No intermediate shell is used, so shell operators such
525              as > are treated as normal arguments.  (Use  the  INPUT_*,  OUT‐
526              PUT_*,  and  ERROR_*  options  to  redirect  stdin,  stdout, and
527              stderr.)
528
529              If a sequential execution of multiple commands is required,  use
530              multiple execute_process() calls with a single COMMAND argument.
531
532       WORKING_DIRECTORY
533              The named directory will be set as the current working directory
534              of the child processes.
535
536       TIMEOUT
537              The child processes will be terminated if they do not finish  in
538              the specified number of seconds (fractions are allowed).
539
540       RESULT_VARIABLE
541              The  variable  will  be  set to contain the result of last child
542              process.  This will be an integer  return  code  from  the  last
543              child or a string describing an error condition.
544
545       RESULTS_VARIABLE <variable>
546              The  variable will be set to contain the result of all processes
547              as a ;-list, in order of  the  given  COMMAND  arguments.   Each
548              entry  will  be  an  integer  return code from the corresponding
549              child or a string describing an error condition.
550
551       OUTPUT_VARIABLE, ERROR_VARIABLE
552              The variable named will be set with the contents of the standard
553              output  and  standard  error  pipes,  respectively.  If the same
554              variable is named for both pipes their output will be merged  in
555              the order produced.
556
557       INPUT_FILE, OUTPUT_FILE, ERROR_FILE
558              The  file  named  will  be attached to the standard input of the
559              first process, standard output of the last process, or  standard
560              error of all processes, respectively.  If the same file is named
561              for both output and error then it will be used for both.
562
563       OUTPUT_QUIET, ERROR_QUIET
564              The standard output or standard error results  will  be  quietly
565              ignored.
566
567       ENCODING <name>
568              On  Windows, the encoding that is used to decode output from the
569              process.  Ignored on other platforms.  Valid encoding names are:
570
571              NONE   Perform no decoding.  This assumes that the process  out‐
572                     put is encoded in the same way as CMake’s internal encod‐
573                     ing (UTF-8).  This is the default.
574
575              AUTO   Use the current active  console’s  codepage  or  if  that
576                     isn’t available then use ANSI.
577
578              ANSI   Use the ANSI codepage.
579
580              OEM    Use the original equipment manufacturer (OEM) code page.
581
582              UTF8 or UTF-8
583                     Use  the UTF-8 codepage. Prior to CMake 3.11.0, only UTF8
584                     was accepted for this encoding. In  CMake  3.11.0,  UTF-8
585                     was  added for consistency with the UTF-8 RFC naming con‐
586                     vention.
587
588       If more than one OUTPUT_* or ERROR_* option is given for the same  pipe
589       the precedence is not specified.  If no OUTPUT_* or ERROR_* options are
590       given the output will be shared with the  corresponding  pipes  of  the
591       CMake process itself.
592
593       The  execute_process()  command  is  a  newer  more powerful version of
594       exec_program(), but the old command has been  kept  for  compatibility.
595       Both  commands run while CMake is processing the project prior to build
596       system generation.  Use add_custom_target() and add_custom_command() to
597       create custom commands that run at build time.
598
599   file
600       File manipulation command.
601
602
603                                        ----
604
605
606
607          file(WRITE <filename> <content>...)
608          file(APPEND <filename> <content>...)
609
610       Write  <content>  into  a file called <filename>.  If the file does not
611       exist, it will be created.  If the file already exists, WRITE mode will
612       overwrite  it  and APPEND mode will append to the end.  Any directories
613       in the path specified by <filename> that do not exist will be created.
614
615       If the file is a build  input,  use  the  configure_file()  command  to
616       update the file only when its content changes.
617
618
619                                        ----
620
621
622
623          file(READ <filename> <variable>
624               [OFFSET <offset>] [LIMIT <max-in>] [HEX])
625
626       Read  content  from  a  file called <filename> and store it in a <vari‐
627       able>.  Optionally start from the  given  <offset>  and  read  at  most
628       <max-in>  bytes.  The HEX option causes data to be converted to a hexa‐
629       decimal representation (useful for binary data).
630
631
632                                        ----
633
634
635
636          file(STRINGS <filename> <variable> [<options>...])
637
638       Parse a list of ASCII strings from <filename> and store  it  in  <vari‐
639       able>.   Binary data in the file are ignored.  Carriage return (\r, CR)
640       characters are ignored.  The options are:
641
642       LENGTH_MAXIMUM <max-len>
643              Consider only strings of at most a given length.
644
645       LENGTH_MINIMUM <min-len>
646              Consider only strings of at least a given length.
647
648       LIMIT_COUNT <max-num>
649              Limit the number of distinct strings to be extracted.
650
651       LIMIT_INPUT <max-in>
652              Limit the number of input bytes to read from the file.
653
654       LIMIT_OUTPUT <max-out>
655              Limit the number of total bytes to store in the <variable>.
656
657       NEWLINE_CONSUME
658              Treat newline characters (\n, LF)  as  part  of  string  content
659              instead of terminating at them.
660
661       NO_HEX_CONVERSION
662              Intel  Hex  and  Motorola  S-record files are automatically con‐
663              verted to binary while reading unless this option is given.
664
665       REGEX <regex>
666              Consider only strings that match the given regular expression.
667
668       ENCODING <encoding-type>
669              Consider strings  of  a  given  encoding.   Currently  supported
670              encodings  are:  UTF-8,  UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.
671              If the ENCODING option is not provided and the file has  a  Byte
672              Order Mark, the ENCODING option will be defaulted to respect the
673              Byte Order Mark.
674
675       For example, the code
676
677          file(STRINGS myfile.txt myfile)
678
679       stores a list in the variable myfile in which each item is a line  from
680       the input file.
681
682
683                                        ----
684
685
686
687          file(<HASH> <filename> <variable>)
688
689       Compute  a cryptographic hash of the content of <filename> and store it
690       in a <variable>.  The supported <HASH> algorithm names are those listed
691       by the string(<HASH>) command.
692
693
694                                        ----
695
696
697
698          file(GLOB <variable>
699               [LIST_DIRECTORIES true|false] [RELATIVE <path>]
700               [<globbing-expressions>...])
701          file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
702               [LIST_DIRECTORIES true|false] [RELATIVE <path>]
703               [<globbing-expressions>...])
704
705       Generate  a  list  of  files  that match the <globbing-expressions> and
706       store it into the <variable>.  Globbing expressions are similar to reg‐
707       ular expressions, but much simpler.  If RELATIVE flag is specified, the
708       results will be returned as relative paths  to  the  given  path.   The
709       results will be ordered lexicographically.
710
711       By  default  GLOB lists directories - directories are omitted in result
712       if LIST_DIRECTORIES is set to false.
713
714       NOTE:
715          We do not recommend using GLOB to collect a  list  of  source  files
716          from  your  source  tree.   If no CMakeLists.txt file changes when a
717          source is added or removed then the generated  build  system  cannot
718          know when to ask CMake to regenerate.
719
720       Examples of globbing expressions include:
721
722          *.cxx      - match all files with extension cxx
723          *.vt?      - match all files with extension vta,...,vtz
724          f[3-5].txt - match files f3.txt, f4.txt, f5.txt
725
726       The  GLOB_RECURSE  mode  will  traverse  all  the subdirectories of the
727       matched directory and match the files.  Subdirectories  that  are  sym‐
728       links  are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
729       is not set to NEW.
730
731       By default GLOB_RECURSE omits directories from result  list  -  setting
732       LIST_DIRECTORIES  to  true  adds  directories  to result list.  If FOL‐
733       LOW_SYMLINKS is given  or  policy  CMP0009  is  not  set  to  OLD  then
734       LIST_DIRECTORIES treats symlinks as directories.
735
736       Examples of recursive globbing include:
737
738          /dir/*.py  - match all python files in /dir and subdirectories
739
740
741                                        ----
742
743
744
745          file(RENAME <oldname> <newname>)
746
747       Move  a  file  or directory within a filesystem from <oldname> to <new‐
748       name>, replacing the destination atomically.
749
750
751                                        ----
752
753
754
755          file(REMOVE [<files>...])
756          file(REMOVE_RECURSE [<files>...])
757
758       Remove the given files.  The REMOVE_RECURSE mode will remove the  given
759       files  and directories, also non-empty directories. No error is emitted
760       if a given file does not exist.
761
762
763                                        ----
764
765
766
767          file(MAKE_DIRECTORY [<directories>...])
768
769       Create the given directories and their parents as needed.
770
771
772                                        ----
773
774
775
776          file(RELATIVE_PATH <variable> <directory> <file>)
777
778       Compute the relative path from a <directory> to a <file> and  store  it
779       in the <variable>.
780
781
782                                        ----
783
784
785
786          file(TO_CMAKE_PATH "<path>" <variable>)
787          file(TO_NATIVE_PATH "<path>" <variable>)
788
789       The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
790       with forward-slashes (/).  The input can be a single path or  a  system
791       search  path  like  $ENV{PATH}.   A  search path will be converted to a
792       cmake-style list separated by ; characters.
793
794       The TO_NATIVE_PATH mode converts a cmake-style  <path>  into  a  native
795       path with platform-specific slashes (\ on Windows and / elsewhere).
796
797       Always  use double quotes around the <path> to be sure it is treated as
798       a single argument to this command.
799
800
801                                        ----
802
803
804
805          file(DOWNLOAD <url> <file> [<options>...])
806          file(UPLOAD   <file> <url> [<options>...])
807
808       The DOWNLOAD mode downloads the given <url> to  a  local  <file>.   The
809       UPLOAD mode uploads a local <file> to a given <url>.
810
811       Options to both DOWNLOAD and UPLOAD are:
812
813       INACTIVITY_TIMEOUT <seconds>
814              Terminate the operation after a period of inactivity.
815
816       LOG <variable>
817              Store a human-readable log of the operation in a variable.
818
819       SHOW_PROGRESS
820              Print  progress  information as status messages until the opera‐
821              tion is complete.
822
823       STATUS <variable>
824              Store the resulting status of the operation in a variable.   The
825              status  is a ; separated list of length 2.  The first element is
826              the numeric return value for the operation, and the second  ele‐
827              ment  is  a string value for the error.  A 0 numeric error means
828              no error in the operation.
829
830       TIMEOUT <seconds>
831              Terminate the operation after a given total time has elapsed.
832
833       USERPWD <username>:<password>
834              Set username and password for operation.
835
836       HTTPHEADER <HTTP-header>
837              HTTP header for operation. Suboption  can  be  repeated  several
838              times.
839
840       NETRC <level>
841              Specify whether the .netrc file is to be used for operation.  If
842              this option is not specified, the value of the CMAKE_NETRC vari‐
843              able will be used instead.  Valid levels are:
844
845              IGNORED
846                     The .netrc file is ignored.  This is the default.
847
848              OPTIONAL
849                     The  .netrc  file is optional, and information in the URL
850                     is preferred.  The file will be  scanned  to  find  which
851                     ever information is not specified in the URL.
852
853              REQUIRED
854                     The  .netrc  file is required, and information in the URL
855                     is ignored.
856
857       NETRC_FILE <file>
858              Specify an alternative .netrc file  to  the  one  in  your  home
859              directory,  if  the NETRC level is OPTIONAL or REQUIRED. If this
860              option is not specified, the value of the CMAKE_NETRC_FILE vari‐
861              able will be used instead.
862
863       If neither NETRC option is given CMake will check variables CMAKE_NETRC
864       and CMAKE_NETRC_FILE, respectively.
865
866       Additional options to DOWNLOAD are:
867
868       EXPECTED_HASH ALGO=<value>
869          Verify that the downloaded content hash matches the expected  value,
870          where  ALGO  is one of the algorithms supported by file(<HASH>).  If
871          it does not match, the operation fails with an error.
872
873       EXPECTED_MD5 <value>
874              Historical short-hand for EXPECTED_HASH MD5=<value>.
875
876       TLS_VERIFY <ON|OFF>
877              Specify whether to verify the server  certificate  for  https://
878              URLs.  The default is to not verify.
879
880       TLS_CAINFO <file>
881              Specify a custom Certificate Authority file for https:// URLs.
882
883       For  https://  URLs  CMake must be built with OpenSSL support.  TLS/SSL
884       certificates are not checked by default.  Set TLS_VERIFY to ON to check
885       certificates and/or use EXPECTED_HASH to verify downloaded content.  If
886       neither TLS option is given CMake will check variables CMAKE_TLS_VERIFY
887       and CMAKE_TLS_CAINFO, respectively.
888
889
890                                        ----
891
892
893
894          file(TIMESTAMP <filename> <variable> [<format>] [UTC])
895
896       Compute  a string representation of the modification time of <filename>
897       and store it in <variable>.  Should the command be unable to  obtain  a
898       timestamp variable will be set to the empty string (“”).
899
900       See the string(TIMESTAMP) command for documentation of the <format> and
901       UTC options.
902
903
904                                        ----
905
906
907
908          file(GENERATE OUTPUT output-file
909               <INPUT input-file|CONTENT content>
910               [CONDITION expression])
911
912       Generate an output file for each build configuration supported  by  the
913       current CMake Generator.  Evaluate generator expressions from the input
914       content to produce the output content.  The options are:
915
916       CONDITION <condition>
917              Generate the output file for a particular configuration only  if
918              the  condition  is  true.   The  condition must be either 0 or 1
919              after evaluating generator expressions.
920
921       CONTENT <content>
922              Use the content given explicitly as input.
923
924       INPUT <input-file>
925              Use the content from a given file as input.  A relative path  is
926              treated  with  respect to the value of CMAKE_CURRENT_SOURCE_DIR.
927              See policy CMP0070.
928
929       OUTPUT <output-file>
930              Specify the output file name to generate.  Use generator expres‐
931              sions such as $<CONFIG> to specify a configuration-specific out‐
932              put file name.  Multiple configurations may  generate  the  same
933              output  file only if the generated content is identical.  Other‐
934              wise, the <output-file> must evaluate to an unique name for each
935              configuration.   A  relative  path  (after  evaluating generator
936              expressions) is treated with respect to the value of  CMAKE_CUR‐
937              RENT_BINARY_DIR.  See policy CMP0070.
938
939       Exactly  one  CONTENT or INPUT option must be given.  A specific OUTPUT
940       file may be named by at most one invocation of file(GENERATE).   Gener‐
941       ated files are modified and their timestamp updated on subsequent cmake
942       runs only if their content is changed.
943
944       Note also that file(GENERATE) does not create the output file until the
945       generation  phase.  The output file will not yet have been written when
946       the file(GENERATE) command returns, it is written only after processing
947       all of a project’s CMakeLists.txt files.
948
949
950                                        ----
951
952
953
954          file(<COPY|INSTALL> <files>... DESTINATION <dir>
955               [FILE_PERMISSIONS <permissions>...]
956               [DIRECTORY_PERMISSIONS <permissions>...]
957               [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
958               [FILES_MATCHING]
959               [[PATTERN <pattern> | REGEX <regex>]
960                [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
961
962       The  COPY signature copies files, directories, and symlinks to a desti‐
963       nation folder.  Relative input paths are evaluated with respect to  the
964       current  source directory, and a relative destination is evaluated with
965       respect to the current build directory.  Copying preserves  input  file
966       timestamps,  and  optimizes  out a file if it exists at the destination
967       with the same timestamp.  Copying preserves  input  permissions  unless
968       explicit  permissions  or  NO_SOURCE_PERMISSIONS  are given (default is
969       USE_SOURCE_PERMISSIONS).
970
971       See the install(DIRECTORY) command for  documentation  of  permissions,
972       FILES_MATCHING,  PATTERN, REGEX, and EXCLUDE options.  Copying directo‐
973       ries preserves the structure of their content even if options are  used
974       to select a subset of files.
975
976       The INSTALL signature differs slightly from COPY: it prints status mes‐
977       sages   (subject   to   the   CMAKE_INSTALL_MESSAGE   variable),    and
978       NO_SOURCE_PERMISSIONS  is  default.   Installation scripts generated by
979       the install()  command  use  this  signature  (with  some  undocumented
980       options for internal use).
981
982
983                                        ----
984
985
986
987          file(LOCK <path> [DIRECTORY] [RELEASE]
988               [GUARD <FUNCTION|FILE|PROCESS>]
989               [RESULT_VARIABLE <variable>]
990               [TIMEOUT <seconds>])
991
992       Lock a file specified by <path> if no DIRECTORY option present and file
993       <path>/cmake.lock otherwise. File will be locked for scope  defined  by
994       GUARD  option (default value is PROCESS). RELEASE option can be used to
995       unlock file explicitly. If option TIMEOUT is not specified  CMake  will
996       wait  until lock succeed or until fatal error occurs. If TIMEOUT is set
997       to 0 lock will be tried once and result will be  reported  immediately.
998       If  TIMEOUT  is not 0 CMake will try to lock file for the period speci‐
999       fied by <seconds> value. Any errors will be  interpreted  as  fatal  if
1000       there  is no RESULT_VARIABLE option. Otherwise result will be stored in
1001       <variable> and will be 0 on success or error message on failure.
1002
1003       Note that lock is advisory - there is no guarantee that other processes
1004       will  respect  this  lock,  i.e.  lock  synchronize  two  or more CMake
1005       instances sharing some modifiable resources. Similar logic  applied  to
1006       DIRECTORY  option - locking parent directory doesn’t prevent other LOCK
1007       commands to lock any child directory or file.
1008
1009       Trying to lock file twice is not allowed.  Any intermediate directories
1010       and  file  itself will be created if they not exist.  GUARD and TIMEOUT
1011       options ignored on RELEASE operation.
1012
1013   find_file
1014       A short-hand signature is:
1015
1016          find_file (<VAR> name1 [path1 path2 ...])
1017
1018       The general signature is:
1019
1020          find_file (
1021                    <VAR>
1022                    name | NAMES name1 [name2 ...]
1023                    [HINTS path1 [path2 ... ENV var]]
1024                    [PATHS path1 [path2 ... ENV var]]
1025                    [PATH_SUFFIXES suffix1 [suffix2 ...]]
1026                    [DOC "cache documentation string"]
1027                    [NO_DEFAULT_PATH]
1028                    [NO_CMAKE_PATH]
1029                    [NO_CMAKE_ENVIRONMENT_PATH]
1030                    [NO_SYSTEM_ENVIRONMENT_PATH]
1031                    [NO_CMAKE_SYSTEM_PATH]
1032                    [CMAKE_FIND_ROOT_PATH_BOTH |
1033                     ONLY_CMAKE_FIND_ROOT_PATH |
1034                     NO_CMAKE_FIND_ROOT_PATH]
1035                   )
1036
1037       This command is used to find a full path to named file.  A cache  entry
1038       named  by <VAR> is created to store the result of this command.  If the
1039       full path to a file is found the result is stored in the  variable  and
1040       the  search  will  not  be repeated unless the variable is cleared.  If
1041       nothing is found, the result will be  <VAR>-NOTFOUND,  and  the  search
1042       will  be  attempted  again  the next time find_file is invoked with the
1043       same variable.
1044
1045       Options include:
1046
1047       NAMES  Specify one or more possible names for the full path to a file.
1048
1049              When using this to specify names with and without a version suf‐
1050              fix,  we recommend specifying the unversioned name first so that
1051              locally-built packages can be found  before  those  provided  by
1052              distributions.
1053
1054       HINTS, PATHS
1055              Specify  directories  to search in addition to the default loca‐
1056              tions.  The ENV var sub-option reads paths from a  system  envi‐
1057              ronment variable.
1058
1059       PATH_SUFFIXES
1060              Specify  additional subdirectories to check below each directory
1061              location otherwise considered.
1062
1063       DOC    Specify the documentation string for the <VAR> cache entry.
1064
1065       If NO_DEFAULT_PATH is specified, then no additional paths are added  to
1066       the search.  If NO_DEFAULT_PATH is not specified, the search process is
1067       as follows:
1068
1069       1. Search paths specified in cmake-specific cache variables.  These are
1070          intended  to  be  used  on the command line with a -DVAR=value.  The
1071          values  are  interpreted  as  ;-lists.   This  can  be  skipped   if
1072          NO_CMAKE_PATH is passed.
1073
1074          · <prefix>/include/<arch>  if CMAKE_LIBRARY_ARCHITECTURE is set, and
1075            <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1076
1077          · CMAKE_INCLUDE_PATH
1078
1079          · CMAKE_FRAMEWORK_PATH
1080
1081       2. Search paths  specified  in  cmake-specific  environment  variables.
1082          These  are intended to be set in the user’s shell configuration, and
1083          therefore use the host’s native path separator (; on Windows  and  :
1084          on  UNIX).   This  can  be  skipped  if NO_CMAKE_ENVIRONMENT_PATH is
1085          passed.
1086
1087          · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set,  and
1088            <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1089
1090          · CMAKE_INCLUDE_PATH
1091
1092          · CMAKE_FRAMEWORK_PATH
1093
1094       3. Search  the  paths  specified  by the HINTS option.  These should be
1095          paths computed by system introspection, such as a hint  provided  by
1096          the  location  of  another  item  already found.  Hard-coded guesses
1097          should be specified with the PATHS option.
1098
1099       4. Search the standard  system  environment  variables.   This  can  be
1100          skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1101
1102          · Directories in INCLUDE.  On Windows hosts: <prefix>/include/<arch>
1103            if CMAKE_LIBRARY_ARCHITECTURE is  set,  and  <prefix>/include  for
1104            each  <prefix>/[s]bin  in  PATH,  and  <entry>/include  for  other
1105            entries in PATH, and the directories in PATH itself.
1106
1107       5. Search cmake variables defined in the Platform files for the current
1108          system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1109
1110          · <prefix>/include/<arch>  if CMAKE_LIBRARY_ARCHITECTURE is set, and
1111            <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1112
1113          · CMAKE_SYSTEM_INCLUDE_PATH
1114
1115          · CMAKE_SYSTEM_FRAMEWORK_PATH
1116
1117       6. Search the paths specified by the PATHS option or in the  short-hand
1118          version of the command.  These are typically hard-coded guesses.
1119
1120       On  OS  X  the  CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1121       determine the order of preference between  Apple-style  and  unix-style
1122       package components.
1123
1124       The  CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1125       ries to be prepended to all other search directories.  This effectively
1126       “re-roots”  the  entire  search under given locations.  Paths which are
1127       descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1128       ing,  because  that  variable  is always a path on the host system.  By
1129       default the CMAKE_FIND_ROOT_PATH is empty.
1130
1131       The CMAKE_SYSROOT variable can also be  used  to  specify  exactly  one
1132       directory  to  use  as  a prefix.  Setting CMAKE_SYSROOT also has other
1133       effects.  See the documentation for that variable for more.
1134
1135       These variables are especially useful when cross-compiling to point  to
1136       the  root  directory  of  the  target environment and CMake will search
1137       there  too.   By  default  at   first   the   directories   listed   in
1138       CMAKE_FIND_ROOT_PATH  are searched, then the CMAKE_SYSROOT directory is
1139       searched, and then the non-rooted directories will  be  searched.   The
1140       default      behavior      can      be      adjusted     by     setting
1141       CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.  This behavior can be manually over‐
1142       ridden on a per-call basis using options:
1143
1144       CMAKE_FIND_ROOT_PATH_BOTH
1145              Search in the order described above.
1146
1147       NO_CMAKE_FIND_ROOT_PATH
1148              Do not use the CMAKE_FIND_ROOT_PATH variable.
1149
1150       ONLY_CMAKE_FIND_ROOT_PATH
1151              Search  only  the  re-rooted  directories  and directories below
1152              CMAKE_STAGING_PREFIX.
1153
1154       The default search order is designed to be most-specific to  least-spe‐
1155       cific  for common use cases.  Projects may override the order by simply
1156       calling the command multiple times and using the NO_* options:
1157
1158          find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1159          find_file (<VAR> NAMES name)
1160
1161       Once one of the calls succeeds the result  variable  will  be  set  and
1162       stored in the cache so that no call will search again.
1163
1164   find_library
1165       A short-hand signature is:
1166
1167          find_library (<VAR> name1 [path1 path2 ...])
1168
1169       The general signature is:
1170
1171          find_library (
1172                    <VAR>
1173                    name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1174                    [HINTS path1 [path2 ... ENV var]]
1175                    [PATHS path1 [path2 ... ENV var]]
1176                    [PATH_SUFFIXES suffix1 [suffix2 ...]]
1177                    [DOC "cache documentation string"]
1178                    [NO_DEFAULT_PATH]
1179                    [NO_CMAKE_PATH]
1180                    [NO_CMAKE_ENVIRONMENT_PATH]
1181                    [NO_SYSTEM_ENVIRONMENT_PATH]
1182                    [NO_CMAKE_SYSTEM_PATH]
1183                    [CMAKE_FIND_ROOT_PATH_BOTH |
1184                     ONLY_CMAKE_FIND_ROOT_PATH |
1185                     NO_CMAKE_FIND_ROOT_PATH]
1186                   )
1187
1188       This  command  is used to find a library.  A cache entry named by <VAR>
1189       is created to store the result of this  command.   If  the  library  is
1190       found  the  result is stored in the variable and the search will not be
1191       repeated unless the variable is cleared.   If  nothing  is  found,  the
1192       result  will  be <VAR>-NOTFOUND, and the search will be attempted again
1193       the next time find_library is invoked with the same variable.
1194
1195       Options include:
1196
1197       NAMES  Specify one or more possible names for the library.
1198
1199              When using this to specify names with and without a version suf‐
1200              fix,  we recommend specifying the unversioned name first so that
1201              locally-built packages can be found  before  those  provided  by
1202              distributions.
1203
1204       HINTS, PATHS
1205              Specify  directories  to search in addition to the default loca‐
1206              tions.  The ENV var sub-option reads paths from a  system  envi‐
1207              ronment variable.
1208
1209       PATH_SUFFIXES
1210              Specify  additional subdirectories to check below each directory
1211              location otherwise considered.
1212
1213       DOC    Specify the documentation string for the <VAR> cache entry.
1214
1215       If NO_DEFAULT_PATH is specified, then no additional paths are added  to
1216       the search.  If NO_DEFAULT_PATH is not specified, the search process is
1217       as follows:
1218
1219       1. Search paths specified in cmake-specific cache variables.  These are
1220          intended  to  be  used  on the command line with a -DVAR=value.  The
1221          values  are  interpreted  as  ;-lists.   This  can  be  skipped   if
1222          NO_CMAKE_PATH is passed.
1223
1224          · <prefix>/lib/<arch>  if  CMAKE_LIBRARY_ARCHITECTURE  is  set,  and
1225            <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1226
1227          · CMAKE_LIBRARY_PATH
1228
1229          · CMAKE_FRAMEWORK_PATH
1230
1231       2. Search paths  specified  in  cmake-specific  environment  variables.
1232          These  are intended to be set in the user’s shell configuration, and
1233          therefore use the host’s native path separator (; on Windows  and  :
1234          on  UNIX).   This  can  be  skipped  if NO_CMAKE_ENVIRONMENT_PATH is
1235          passed.
1236
1237          · <prefix>/lib/<arch>  if  CMAKE_LIBRARY_ARCHITECTURE  is  set,  and
1238            <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1239
1240          · CMAKE_LIBRARY_PATH
1241
1242          · CMAKE_FRAMEWORK_PATH
1243
1244       3. Search  the  paths  specified  by the HINTS option.  These should be
1245          paths computed by system introspection, such as a hint  provided  by
1246          the  location  of  another  item  already found.  Hard-coded guesses
1247          should be specified with the PATHS option.
1248
1249       4. Search the standard  system  environment  variables.   This  can  be
1250          skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1251
1252          · Directories  in  LIB.   On  Windows  hosts: <prefix>/lib/<arch> if
1253            CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <pre‐
1254            fix>/[s]bin  in  PATH,  and <entry>/lib for other entries in PATH,
1255            and the directories in PATH itself.
1256
1257       5. Search cmake variables defined in the Platform files for the current
1258          system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1259
1260          · <prefix>/lib/<arch>  if  CMAKE_LIBRARY_ARCHITECTURE  is  set,  and
1261            <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1262
1263          · CMAKE_SYSTEM_LIBRARY_PATH
1264
1265          · CMAKE_SYSTEM_FRAMEWORK_PATH
1266
1267       6. Search the paths specified by the PATHS option or in the  short-hand
1268          version of the command.  These are typically hard-coded guesses.
1269
1270       On  OS  X  the  CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1271       determine the order of preference between  Apple-style  and  unix-style
1272       package components.
1273
1274       The  CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1275       ries to be prepended to all other search directories.  This effectively
1276       “re-roots”  the  entire  search under given locations.  Paths which are
1277       descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1278       ing,  because  that  variable  is always a path on the host system.  By
1279       default the CMAKE_FIND_ROOT_PATH is empty.
1280
1281       The CMAKE_SYSROOT variable can also be  used  to  specify  exactly  one
1282       directory  to  use  as  a prefix.  Setting CMAKE_SYSROOT also has other
1283       effects.  See the documentation for that variable for more.
1284
1285       These variables are especially useful when cross-compiling to point  to
1286       the  root  directory  of  the  target environment and CMake will search
1287       there  too.   By  default  at   first   the   directories   listed   in
1288       CMAKE_FIND_ROOT_PATH  are searched, then the CMAKE_SYSROOT directory is
1289       searched, and then the non-rooted directories will  be  searched.   The
1290       default      behavior      can      be      adjusted     by     setting
1291       CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.  This behavior can be manually over‐
1292       ridden on a per-call basis using options:
1293
1294       CMAKE_FIND_ROOT_PATH_BOTH
1295              Search in the order described above.
1296
1297       NO_CMAKE_FIND_ROOT_PATH
1298              Do not use the CMAKE_FIND_ROOT_PATH variable.
1299
1300       ONLY_CMAKE_FIND_ROOT_PATH
1301              Search  only  the  re-rooted  directories  and directories below
1302              CMAKE_STAGING_PREFIX.
1303
1304       The default search order is designed to be most-specific to  least-spe‐
1305       cific  for common use cases.  Projects may override the order by simply
1306       calling the command multiple times and using the NO_* options:
1307
1308          find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1309          find_library (<VAR> NAMES name)
1310
1311       Once one of the calls succeeds the result  variable  will  be  set  and
1312       stored in the cache so that no call will search again.
1313
1314       When  more  than one value is given to the NAMES option this command by
1315       default will consider one name at a time and search every directory for
1316       it.  The NAMES_PER_DIR option tells this command to consider one direc‐
1317       tory at a time and search for all names in it.
1318
1319       Each library name given to the NAMES option is first  considered  as  a
1320       library  file  name and then considered with platform-specific prefixes
1321       (e.g. lib) and suffixes (e.g. .so).  Therefore one may specify  library
1322       file  names  such  as  libfoo.a  directly.   This can be used to locate
1323       static libraries on UNIX-like systems.
1324
1325       If the library found is a framework, then <VAR> will be set to the full
1326       path  to  the  framework <fullPath>/A.framework.  When a full path to a
1327       framework is used as a library, CMake will use a -framework  A,  and  a
1328       -F<fullPath> to link the framework to the target.
1329
1330       If  the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
1331       paths will be tested as normal, with the suffix appended, and with  all
1332       matches  of  lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
1333       FIX}/.   This  variable  overrides  the   FIND_LIBRARY_USE_LIB32_PATHS,
1334       FIND_LIBRARY_USE_LIBX32_PATHS,  and FIND_LIBRARY_USE_LIB64_PATHS global
1335       properties.
1336
1337       If the FIND_LIBRARY_USE_LIB32_PATHS global property is set  all  search
1338       paths will be tested as normal, with 32/ appended, and with all matches
1339       of lib/ replaced with lib32/.  This property is automatically  set  for
1340       the  platforms  that  are  known to need it if at least one of the lan‐
1341       guages supported by the project() command is enabled.
1342
1343       If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all  search
1344       paths  will  be  tested  as  normal,  with  x32/ appended, and with all
1345       matches of lib/ replaced with libx32/.  This property is  automatically
1346       set  for the platforms that are known to need it if at least one of the
1347       languages supported by the project() command is enabled.
1348
1349       If the FIND_LIBRARY_USE_LIB64_PATHS global property is set  all  search
1350       paths will be tested as normal, with 64/ appended, and with all matches
1351       of lib/ replaced with lib64/.  This property is automatically  set  for
1352       the  platforms  that  are  known to need it if at least one of the lan‐
1353       guages supported by the project() command is enabled.
1354
1355   find_package
1356       Load settings for an external project.
1357
1358          find_package(<package> [version] [EXACT] [QUIET] [MODULE]
1359                       [REQUIRED] [[COMPONENTS] [components...]]
1360                       [OPTIONAL_COMPONENTS components...]
1361                       [NO_POLICY_SCOPE])
1362
1363       Finds and loads settings from  an  external  project.   <package>_FOUND
1364       will  be set to indicate whether the package was found.  When the pack‐
1365       age is found package-specific information is provided through variables
1366       and  Imported  Targets  documented  by  the  package itself.  The QUIET
1367       option disables messages if the package cannot be  found.   The  MODULE
1368       option  disables  the  second signature documented below.  The REQUIRED
1369       option stops processing with an error message if the package cannot  be
1370       found.
1371
1372       A  package-specific list of required components may be listed after the
1373       COMPONENTS option (or after the REQUIRED  option  if  present).   Addi‐
1374       tional  optional  components  may  be listed after OPTIONAL_COMPONENTS.
1375       Available components and their influence on whether a package  is  con‐
1376       sidered to be found are defined by the target package.
1377
1378       The  [version] argument requests a version with which the package found
1379       should be compatible (format  is  major[.minor[.patch[.tweak]]]).   The
1380       EXACT option requests that the version be matched exactly.  If no [ver‐
1381       sion] and/or component list is given to a recursive invocation inside a
1382       find-module,  the  corresponding  arguments are forwarded automatically
1383       from the outer call (including the EXACT flag for [version]).   Version
1384       support  is  currently  provided  only  on  a  package-by-package basis
1385       (details below).
1386
1387       User code should generally look for packages  using  the  above  simple
1388       signature.   The  remainder of this command documentation specifies the
1389       full command signature and details  of  the  search  process.   Project
1390       maintainers  wishing  to  provide a package to be found by this command
1391       are encouraged to read on.
1392
1393       The command has two modes by which it searches for  packages:  “Module”
1394       mode  and  “Config” mode.  Module mode is available when the command is
1395       invoked with the above reduced signature.  CMake searches  for  a  file
1396       called  Find<package>.cmake  in  the  CMAKE_MODULE_PATH followed by the
1397       CMake installation.  If the file is found, it is read and processed  by
1398       CMake.   It  is  responsible for finding the package, checking the ver‐
1399       sion, and producing any needed  messages.   Many  find-modules  provide
1400       limited  or  no support for versioning; check the module documentation.
1401       If no module is found and the MODULE option is not  given  the  command
1402       proceeds to Config mode.
1403
1404       The complete Config mode command signature is:
1405
1406          find_package(<package> [version] [EXACT] [QUIET]
1407                       [REQUIRED] [[COMPONENTS] [components...]]
1408                       [CONFIG|NO_MODULE]
1409                       [NO_POLICY_SCOPE]
1410                       [NAMES name1 [name2 ...]]
1411                       [CONFIGS config1 [config2 ...]]
1412                       [HINTS path1 [path2 ... ]]
1413                       [PATHS path1 [path2 ... ]]
1414                       [PATH_SUFFIXES suffix1 [suffix2 ...]]
1415                       [NO_DEFAULT_PATH]
1416                       [NO_CMAKE_PATH]
1417                       [NO_CMAKE_ENVIRONMENT_PATH]
1418                       [NO_SYSTEM_ENVIRONMENT_PATH]
1419                       [NO_CMAKE_PACKAGE_REGISTRY]
1420                       [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
1421                       [NO_CMAKE_SYSTEM_PATH]
1422                       [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1423                       [CMAKE_FIND_ROOT_PATH_BOTH |
1424                        ONLY_CMAKE_FIND_ROOT_PATH |
1425                        NO_CMAKE_FIND_ROOT_PATH])
1426
1427       The CONFIG option may be used to skip Module mode explicitly and switch
1428       to Config mode.  It is synonymous to using NO_MODULE.  Config  mode  is
1429       also implied by use of options not specified in the reduced signature.
1430
1431       Config  mode  attempts  to  locate a configuration file provided by the
1432       package to be found.  A cache entry called <package>_DIR is created  to
1433       hold  the  directory  containing  the  file.   By  default  the command
1434       searches for a package with the name <package>.  If the NAMES option is
1435       given  the  names following it are used instead of <package>.  The com‐
1436       mand   searches   for   a    file    called    <name>Config.cmake    or
1437       <lower-case-name>-config.cmake  for each name specified.  A replacement
1438       set of possible configuration file names may be given using the CONFIGS
1439       option.  The search procedure is specified below.  Once found, the con‐
1440       figuration file is read and processed by CMake.  Since the file is pro‐
1441       vided by the package it already knows the location of package contents.
1442       The full path to the configuration file is stored in the cmake variable
1443       <package>_CONFIG.
1444
1445       All  configuration  files  which  have  been  considered by CMake while
1446       searching for an installation of the package with an  appropriate  ver‐
1447       sion are stored in the cmake variable <package>_CONSIDERED_CONFIGS, the
1448       associated versions in <package>_CONSIDERED_VERSIONS.
1449
1450       If the package configuration file cannot be found CMake  will  generate
1451       an error describing the problem unless the QUIET argument is specified.
1452       If REQUIRED is specified and the package is not found a fatal error  is
1453       generated and the configure step stops executing.  If <package>_DIR has
1454       been set to a directory not containing a configuration file CMake  will
1455       ignore it and search from scratch.
1456
1457       When  the [version] argument is given Config mode will only find a ver‐
1458       sion of the package that claims compatibility with the  requested  ver‐
1459       sion (format is major[.minor[.patch[.tweak]]]).  If the EXACT option is
1460       given only a version of the package claiming  an  exact  match  of  the
1461       requested  version  may be found.  CMake does not establish any conven‐
1462       tion for the meaning of version numbers.  Package version  numbers  are
1463       checked  by “version” files provided by the packages themselves.  For a
1464       candidate package configuration  file  <config-file>.cmake  the  corre‐
1465       sponding  version  file  is  located  next to it and named either <con‐
1466       fig-file>-version.cmake or <config-file>Version.cmake.  If no such ver‐
1467       sion file is available then the configuration file is assumed to not be
1468       compatible with any requested version.  A basic version file containing
1469       generic version matching code can be created using the CMakePackageCon‐
1470       figHelpers module.  When a version file is found it is loaded to  check
1471       the  requested  version number.  The version file is loaded in a nested
1472       scope in which the following variables have been defined:
1473
1474       PACKAGE_FIND_NAME
1475              the <package> name
1476
1477       PACKAGE_FIND_VERSION
1478              full requested version string
1479
1480       PACKAGE_FIND_VERSION_MAJOR
1481              major version if requested, else 0
1482
1483       PACKAGE_FIND_VERSION_MINOR
1484              minor version if requested, else 0
1485
1486       PACKAGE_FIND_VERSION_PATCH
1487              patch version if requested, else 0
1488
1489       PACKAGE_FIND_VERSION_TWEAK
1490              tweak version if requested, else 0
1491
1492       PACKAGE_FIND_VERSION_COUNT
1493              number of version components, 0 to 4
1494
1495       The version file checks whether it satisfies the requested version  and
1496       sets these variables:
1497
1498       PACKAGE_VERSION
1499              full provided version string
1500
1501       PACKAGE_VERSION_EXACT
1502              true if version is exact match
1503
1504       PACKAGE_VERSION_COMPATIBLE
1505              true if version is compatible
1506
1507       PACKAGE_VERSION_UNSUITABLE
1508              true if unsuitable as any version
1509
1510       These  variables  are  checked by the find_package command to determine
1511       whether the configuration file provides an  acceptable  version.   They
1512       are  not available after the find_package call returns.  If the version
1513       is acceptable the following variables are set:
1514
1515       <package>_VERSION
1516              full provided version string
1517
1518       <package>_VERSION_MAJOR
1519              major version if provided, else 0
1520
1521       <package>_VERSION_MINOR
1522              minor version if provided, else 0
1523
1524       <package>_VERSION_PATCH
1525              patch version if provided, else 0
1526
1527       <package>_VERSION_TWEAK
1528              tweak version if provided, else 0
1529
1530       <package>_VERSION_COUNT
1531              number of version components, 0 to 4
1532
1533       and the corresponding package configuration file is loaded.  When  mul‐
1534       tiple  package  configuration  files  are available whose version files
1535       claim compatibility with the version requested it is unspecified  which
1536       one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
1537       no attempt is made to choose a highest or closest version number.
1538
1539       To control the order in which find_package checks for compatibility use
1540       the  two  variables  CMAKE_FIND_PACKAGE_SORT_ORDER and CMAKE_FIND_PACK‐
1541       AGE_SORT_DIRECTION.  For instance in order to select the  highest  ver‐
1542       sion one can set:
1543
1544          SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
1545          SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
1546
1547       before calling find_package.
1548
1549       Config mode provides an elaborate interface and search procedure.  Much
1550       of the interface is provided for completeness and for use internally by
1551       find-modules loaded by Module mode.  Most user code should simply call:
1552
1553          find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1554
1555       in  order to find a package.  Package maintainers providing CMake pack‐
1556       age configuration files are encouraged to name and  install  them  such
1557       that  the procedure outlined below will find them without requiring use
1558       of additional options.
1559
1560       CMake constructs a set of possible installation prefixes for the  pack‐
1561       age.  Under each prefix several directories are searched for a configu‐
1562       ration file.  The tables below show  the  directories  searched.   Each
1563       entry  is meant for installation trees following Windows (W), UNIX (U),
1564       or Apple (A) conventions:
1565
1566          <prefix>/                                                       (W)
1567          <prefix>/(cmake|CMake)/                                         (W)
1568          <prefix>/<name>*/                                               (W)
1569          <prefix>/<name>*/(cmake|CMake)/                                 (W)
1570          <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/                  (U)
1571          <prefix>/(lib/<arch>|lib|share)/<name>*/                        (U)
1572          <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/          (U)
1573          <prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/          (W/U)
1574          <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/                (W/U)
1575          <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (W/U)
1576
1577       On systems supporting OS X Frameworks and Application Bundles the  fol‐
1578       lowing  directories are searched for frameworks or bundles containing a
1579       configuration file:
1580
1581          <prefix>/<name>.framework/Resources/                    (A)
1582          <prefix>/<name>.framework/Resources/CMake/              (A)
1583          <prefix>/<name>.framework/Versions/*/Resources/         (A)
1584          <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
1585          <prefix>/<name>.app/Contents/Resources/                 (A)
1586          <prefix>/<name>.app/Contents/Resources/CMake/           (A)
1587
1588       In all cases the <name> is treated as case-insensitive and  corresponds
1589       to  any  of  the  names  specified (<package> or names given by NAMES).
1590       Paths with lib/<arch> are  enabled  if  the  CMAKE_LIBRARY_ARCHITECTURE
1591       variable  is  set.   If  PATH_SUFFIXES  is  specified  the suffixes are
1592       appended to each (W) or (U) directory entry one-by-one.
1593
1594       This set of  directories  is  intended  to  work  in  cooperation  with
1595       projects  that provide configuration files in their installation trees.
1596       Directories above marked with (W) are  intended  for  installations  on
1597       Windows  where  the  prefix  may  point  at the top of an application’s
1598       installation directory.  Those marked with (U) are intended for instal‐
1599       lations  on UNIX platforms where the prefix is shared by multiple pack‐
1600       ages.  This is merely a convention, so all (W) and (U) directories  are
1601       still  searched  on  all  platforms.   Directories  marked with (A) are
1602       intended for installations on Apple platforms.   The  CMAKE_FIND_FRAME‐
1603       WORK  and CMAKE_FIND_APPBUNDLE variables determine the order of prefer‐
1604       ence.
1605
1606       The set of installation prefixes is  constructed  using  the  following
1607       steps.  If NO_DEFAULT_PATH is specified all NO_* options are enabled.
1608
1609       1. Search paths specified in cmake-specific cache variables.  These are
1610          intended to be used on the command line  with  a  -DVAR=value.   The
1611          values   are  interpreted  as  ;-lists.   This  can  be  skipped  if
1612          NO_CMAKE_PATH is passed:
1613
1614             CMAKE_PREFIX_PATH
1615             CMAKE_FRAMEWORK_PATH
1616             CMAKE_APPBUNDLE_PATH
1617
1618       2. Search paths  specified  in  cmake-specific  environment  variables.
1619          These  are intended to be set in the user’s shell configuration, and
1620          therefore use the host’s native path separator (; on Windows  and  :
1621          on  UNIX).   This  can  be  skipped  if NO_CMAKE_ENVIRONMENT_PATH is
1622          passed:
1623
1624             <package>_DIR
1625             CMAKE_PREFIX_PATH
1626             CMAKE_FRAMEWORK_PATH
1627             CMAKE_APPBUNDLE_PATH
1628
1629       3. Search paths specified by the HINTS option.  These should  be  paths
1630          computed  by  system  introspection,  such as a hint provided by the
1631          location of another item already found.  Hard-coded  guesses  should
1632          be specified with the PATHS option.
1633
1634       4. Search  the  standard  system  environment  variables.   This can be
1635          skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed.  Path entries  end‐
1636          ing  in  /bin  or  /sbin are automatically converted to their parent
1637          directories:
1638
1639             PATH
1640
1641       5. Search paths stored in the CMake User Package Registry.  This can be
1642          skipped  if  NO_CMAKE_PACKAGE_REGISTRY  is  passed or by setting the
1643          CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.  See the cmake-pack‐
1644          ages(7) manual for details on the user package registry.
1645
1646       6. Search cmake variables defined in the Platform files for the current
1647          system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is passed:
1648
1649             CMAKE_SYSTEM_PREFIX_PATH
1650             CMAKE_SYSTEM_FRAMEWORK_PATH
1651             CMAKE_SYSTEM_APPBUNDLE_PATH
1652
1653       7. Search paths stored in the CMake System Package Registry.  This  can
1654          be  skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
1655          ting the CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to TRUE.  See
1656          the  cmake-packages(7) manual for details on the system package reg‐
1657          istry.
1658
1659       8. Search paths specified by the PATHS  option.   These  are  typically
1660          hard-coded guesses.
1661
1662       The  CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1663       ries to be prepended to all other search directories.  This effectively
1664       “re-roots”  the  entire  search under given locations.  Paths which are
1665       descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1666       ing,  because  that  variable  is always a path on the host system.  By
1667       default the CMAKE_FIND_ROOT_PATH is empty.
1668
1669       The CMAKE_SYSROOT variable can also be  used  to  specify  exactly  one
1670       directory  to  use  as  a prefix.  Setting CMAKE_SYSROOT also has other
1671       effects.  See the documentation for that variable for more.
1672
1673       These variables are especially useful when cross-compiling to point  to
1674       the  root  directory  of  the  target environment and CMake will search
1675       there  too.   By  default  at   first   the   directories   listed   in
1676       CMAKE_FIND_ROOT_PATH  are searched, then the CMAKE_SYSROOT directory is
1677       searched, and then the non-rooted directories will  be  searched.   The
1678       default      behavior      can      be      adjusted     by     setting
1679       CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.  This behavior can be manually over‐
1680       ridden on a per-call basis using options:
1681
1682       CMAKE_FIND_ROOT_PATH_BOTH
1683              Search in the order described above.
1684
1685       NO_CMAKE_FIND_ROOT_PATH
1686              Do not use the CMAKE_FIND_ROOT_PATH variable.
1687
1688       ONLY_CMAKE_FIND_ROOT_PATH
1689              Search  only  the  re-rooted  directories  and directories below
1690              CMAKE_STAGING_PREFIX.
1691
1692       The default search order is designed to be most-specific to  least-spe‐
1693       cific  for common use cases.  Projects may override the order by simply
1694       calling the command multiple times and using the NO_* options:
1695
1696          find_package (<package> PATHS paths... NO_DEFAULT_PATH)
1697          find_package (<package>)
1698
1699       Once one of the calls succeeds the result  variable  will  be  set  and
1700       stored in the cache so that no call will search again.
1701
1702       Every  non-REQUIRED  find_package  call  can be disabled by setting the
1703       CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE.
1704
1705       When loading a find module or package configuration  file  find_package
1706       defines  variables to provide information about the call arguments (and
1707       restores their original state before returning):
1708
1709       CMAKE_FIND_PACKAGE_NAME
1710              the <package> name which is searched for
1711
1712       <package>_FIND_REQUIRED
1713              true if REQUIRED option was given
1714
1715       <package>_FIND_QUIETLY
1716              true if QUIET option was given
1717
1718       <package>_FIND_VERSION
1719              full requested version string
1720
1721       <package>_FIND_VERSION_MAJOR
1722              major version if requested, else 0
1723
1724       <package>_FIND_VERSION_MINOR
1725              minor version if requested, else 0
1726
1727       <package>_FIND_VERSION_PATCH
1728              patch version if requested, else 0
1729
1730       <package>_FIND_VERSION_TWEAK
1731              tweak version if requested, else 0
1732
1733       <package>_FIND_VERSION_COUNT
1734              number of version components, 0 to 4
1735
1736       <package>_FIND_VERSION_EXACT
1737              true if EXACT option was given
1738
1739       <package>_FIND_COMPONENTS
1740              list of requested components
1741
1742       <package>_FIND_REQUIRED_<c>
1743              true if component <c> is required, false  if  component  <c>  is
1744              optional
1745
1746       In  Module  mode  the  loaded  find  module is responsible to honor the
1747       request detailed by these variables; see the find module  for  details.
1748       In  Config  mode  find_package  handles  REQUIRED, QUIET, and [version]
1749       options automatically but leaves it to the package  configuration  file
1750       to  handle  components  in a way that makes sense for the package.  The
1751       package configuration file may set <package>_FOUND  to  false  to  tell
1752       find_package that component requirements are not satisfied.
1753
1754       See  the  cmake_policy()  command  documentation  for discussion of the
1755       NO_POLICY_SCOPE option.
1756
1757   find_path
1758       A short-hand signature is:
1759
1760          find_path (<VAR> name1 [path1 path2 ...])
1761
1762       The general signature is:
1763
1764          find_path (
1765                    <VAR>
1766                    name | NAMES name1 [name2 ...]
1767                    [HINTS path1 [path2 ... ENV var]]
1768                    [PATHS path1 [path2 ... ENV var]]
1769                    [PATH_SUFFIXES suffix1 [suffix2 ...]]
1770                    [DOC "cache documentation string"]
1771                    [NO_DEFAULT_PATH]
1772                    [NO_CMAKE_PATH]
1773                    [NO_CMAKE_ENVIRONMENT_PATH]
1774                    [NO_SYSTEM_ENVIRONMENT_PATH]
1775                    [NO_CMAKE_SYSTEM_PATH]
1776                    [CMAKE_FIND_ROOT_PATH_BOTH |
1777                     ONLY_CMAKE_FIND_ROOT_PATH |
1778                     NO_CMAKE_FIND_ROOT_PATH]
1779                   )
1780
1781       This command is used to find a directory containing the named file.   A
1782       cache  entry named by <VAR> is created to store the result of this com‐
1783       mand.  If the file in a directory is found the result is stored in  the
1784       variable  and  the  search  will not be repeated unless the variable is
1785       cleared.  If nothing is found, the result will be  <VAR>-NOTFOUND,  and
1786       the  search  will be attempted again the next time find_path is invoked
1787       with the same variable.
1788
1789       Options include:
1790
1791       NAMES  Specify one or more possible names for the file in a directory.
1792
1793              When using this to specify names with and without a version suf‐
1794              fix,  we recommend specifying the unversioned name first so that
1795              locally-built packages can be found  before  those  provided  by
1796              distributions.
1797
1798       HINTS, PATHS
1799              Specify  directories  to search in addition to the default loca‐
1800              tions.  The ENV var sub-option reads paths from a  system  envi‐
1801              ronment variable.
1802
1803       PATH_SUFFIXES
1804              Specify  additional subdirectories to check below each directory
1805              location otherwise considered.
1806
1807       DOC    Specify the documentation string for the <VAR> cache entry.
1808
1809       If NO_DEFAULT_PATH is specified, then no additional paths are added  to
1810       the search.  If NO_DEFAULT_PATH is not specified, the search process is
1811       as follows:
1812
1813       1. Search paths specified in cmake-specific cache variables.  These are
1814          intended  to  be  used  on the command line with a -DVAR=value.  The
1815          values  are  interpreted  as  ;-lists.   This  can  be  skipped   if
1816          NO_CMAKE_PATH is passed.
1817
1818          · <prefix>/include/<arch>  if CMAKE_LIBRARY_ARCHITECTURE is set, and
1819            <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1820
1821          · CMAKE_INCLUDE_PATH
1822
1823          · CMAKE_FRAMEWORK_PATH
1824
1825       2. Search paths  specified  in  cmake-specific  environment  variables.
1826          These  are intended to be set in the user’s shell configuration, and
1827          therefore use the host’s native path separator (; on Windows  and  :
1828          on  UNIX).   This  can  be  skipped  if NO_CMAKE_ENVIRONMENT_PATH is
1829          passed.
1830
1831          · <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set,  and
1832            <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1833
1834          · CMAKE_INCLUDE_PATH
1835
1836          · CMAKE_FRAMEWORK_PATH
1837
1838       3. Search  the  paths  specified  by the HINTS option.  These should be
1839          paths computed by system introspection, such as a hint  provided  by
1840          the  location  of  another  item  already found.  Hard-coded guesses
1841          should be specified with the PATHS option.
1842
1843       4. Search the standard  system  environment  variables.   This  can  be
1844          skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1845
1846          · Directories in INCLUDE.  On Windows hosts: <prefix>/include/<arch>
1847            if CMAKE_LIBRARY_ARCHITECTURE is  set,  and  <prefix>/include  for
1848            each  <prefix>/[s]bin  in  PATH,  and  <entry>/include  for  other
1849            entries in PATH, and the directories in PATH itself.
1850
1851       5. Search cmake variables defined in the Platform files for the current
1852          system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
1853
1854          · <prefix>/include/<arch>  if CMAKE_LIBRARY_ARCHITECTURE is set, and
1855            <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1856
1857          · CMAKE_SYSTEM_INCLUDE_PATH
1858
1859          · CMAKE_SYSTEM_FRAMEWORK_PATH
1860
1861       6. Search the paths specified by the PATHS option or in the  short-hand
1862          version of the command.  These are typically hard-coded guesses.
1863
1864       On  OS  X  the  CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
1865       determine the order of preference between  Apple-style  and  unix-style
1866       package components.
1867
1868       The  CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
1869       ries to be prepended to all other search directories.  This effectively
1870       “re-roots”  the  entire  search under given locations.  Paths which are
1871       descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
1872       ing,  because  that  variable  is always a path on the host system.  By
1873       default the CMAKE_FIND_ROOT_PATH is empty.
1874
1875       The CMAKE_SYSROOT variable can also be  used  to  specify  exactly  one
1876       directory  to  use  as  a prefix.  Setting CMAKE_SYSROOT also has other
1877       effects.  See the documentation for that variable for more.
1878
1879       These variables are especially useful when cross-compiling to point  to
1880       the  root  directory  of  the  target environment and CMake will search
1881       there  too.   By  default  at   first   the   directories   listed   in
1882       CMAKE_FIND_ROOT_PATH  are searched, then the CMAKE_SYSROOT directory is
1883       searched, and then the non-rooted directories will  be  searched.   The
1884       default      behavior      can      be      adjusted     by     setting
1885       CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.  This behavior can be manually over‐
1886       ridden on a per-call basis using options:
1887
1888       CMAKE_FIND_ROOT_PATH_BOTH
1889              Search in the order described above.
1890
1891       NO_CMAKE_FIND_ROOT_PATH
1892              Do not use the CMAKE_FIND_ROOT_PATH variable.
1893
1894       ONLY_CMAKE_FIND_ROOT_PATH
1895              Search  only  the  re-rooted  directories  and directories below
1896              CMAKE_STAGING_PREFIX.
1897
1898       The default search order is designed to be most-specific to  least-spe‐
1899       cific  for common use cases.  Projects may override the order by simply
1900       calling the command multiple times and using the NO_* options:
1901
1902          find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1903          find_path (<VAR> NAMES name)
1904
1905       Once one of the calls succeeds the result  variable  will  be  set  and
1906       stored in the cache so that no call will search again.
1907
1908       When  searching for frameworks, if the file is specified as A/b.h, then
1909       the framework search will look for A.framework/Headers/b.h.  If that is
1910       found  the  path  will be set to the path to the framework.  CMake will
1911       convert this to the correct -F option to include the file.
1912
1913   find_program
1914       A short-hand signature is:
1915
1916          find_program (<VAR> name1 [path1 path2 ...])
1917
1918       The general signature is:
1919
1920          find_program (
1921                    <VAR>
1922                    name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1923                    [HINTS path1 [path2 ... ENV var]]
1924                    [PATHS path1 [path2 ... ENV var]]
1925                    [PATH_SUFFIXES suffix1 [suffix2 ...]]
1926                    [DOC "cache documentation string"]
1927                    [NO_DEFAULT_PATH]
1928                    [NO_CMAKE_PATH]
1929                    [NO_CMAKE_ENVIRONMENT_PATH]
1930                    [NO_SYSTEM_ENVIRONMENT_PATH]
1931                    [NO_CMAKE_SYSTEM_PATH]
1932                    [CMAKE_FIND_ROOT_PATH_BOTH |
1933                     ONLY_CMAKE_FIND_ROOT_PATH |
1934                     NO_CMAKE_FIND_ROOT_PATH]
1935                   )
1936
1937       This command is used to find a program.  A cache entry named  by  <VAR>
1938       is  created  to  store  the  result of this command.  If the program is
1939       found the result is stored in the variable and the search will  not  be
1940       repeated  unless  the  variable  is  cleared.  If nothing is found, the
1941       result will be <VAR>-NOTFOUND, and the search will be  attempted  again
1942       the next time find_program is invoked with the same variable.
1943
1944       Options include:
1945
1946       NAMES  Specify one or more possible names for the program.
1947
1948              When using this to specify names with and without a version suf‐
1949              fix, we recommend specifying the unversioned name first so  that
1950              locally-built  packages  can  be  found before those provided by
1951              distributions.
1952
1953       HINTS, PATHS
1954              Specify directories to search in addition to the  default  loca‐
1955              tions.   The  ENV var sub-option reads paths from a system envi‐
1956              ronment variable.
1957
1958       PATH_SUFFIXES
1959              Specify additional subdirectories to check below each  directory
1960              location otherwise considered.
1961
1962       DOC    Specify the documentation string for the <VAR> cache entry.
1963
1964       If  NO_DEFAULT_PATH is specified, then no additional paths are added to
1965       the search.  If NO_DEFAULT_PATH is not specified, the search process is
1966       as follows:
1967
1968       1. Search paths specified in cmake-specific cache variables.  These are
1969          intended to be used on the command line  with  a  -DVAR=value.   The
1970          values   are  interpreted  as  ;-lists.   This  can  be  skipped  if
1971          NO_CMAKE_PATH is passed.
1972
1973          · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
1974
1975          · CMAKE_PROGRAM_PATH
1976
1977          · CMAKE_APPBUNDLE_PATH
1978
1979       2. Search paths  specified  in  cmake-specific  environment  variables.
1980          These  are intended to be set in the user’s shell configuration, and
1981          therefore use the host’s native path separator (; on Windows  and  :
1982          on  UNIX).   This  can  be  skipped  if NO_CMAKE_ENVIRONMENT_PATH is
1983          passed.
1984
1985          · <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
1986
1987          · CMAKE_PROGRAM_PATH
1988
1989          · CMAKE_APPBUNDLE_PATH
1990
1991       3. Search the paths specified by the HINTS  option.   These  should  be
1992          paths  computed  by system introspection, such as a hint provided by
1993          the location of another  item  already  found.   Hard-coded  guesses
1994          should be specified with the PATHS option.
1995
1996       4. Search  the  standard  system  environment  variables.   This can be
1997          skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1998
1999          · PATH
2000
2001       5. Search cmake variables defined in the Platform files for the current
2002          system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is passed.
2003
2004          · <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2005
2006          · CMAKE_SYSTEM_PROGRAM_PATH
2007
2008          · CMAKE_SYSTEM_APPBUNDLE_PATH
2009
2010       6. Search  the paths specified by the PATHS option or in the short-hand
2011          version of the command.  These are typically hard-coded guesses.
2012
2013       On OS X the  CMAKE_FIND_FRAMEWORK  and  CMAKE_FIND_APPBUNDLE  variables
2014       determine  the  order  of preference between Apple-style and unix-style
2015       package components.
2016
2017       The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more  directo‐
2018       ries to be prepended to all other search directories.  This effectively
2019       “re-roots” the entire search under given locations.   Paths  which  are
2020       descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
2021       ing, because that variable is always a path on  the  host  system.   By
2022       default the CMAKE_FIND_ROOT_PATH is empty.
2023
2024       The  CMAKE_SYSROOT  variable  can  also  be used to specify exactly one
2025       directory to use as a prefix.  Setting  CMAKE_SYSROOT  also  has  other
2026       effects.  See the documentation for that variable for more.
2027
2028       These  variables are especially useful when cross-compiling to point to
2029       the root directory of the target  environment  and  CMake  will  search
2030       there   too.    By   default   at   first  the  directories  listed  in
2031       CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory  is
2032       searched,  and  then  the non-rooted directories will be searched.  The
2033       default     behavior     can      be      adjusted      by      setting
2034       CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.  This behavior can be manually over‐
2035       ridden on a per-call basis using options:
2036
2037       CMAKE_FIND_ROOT_PATH_BOTH
2038              Search in the order described above.
2039
2040       NO_CMAKE_FIND_ROOT_PATH
2041              Do not use the CMAKE_FIND_ROOT_PATH variable.
2042
2043       ONLY_CMAKE_FIND_ROOT_PATH
2044              Search only the  re-rooted  directories  and  directories  below
2045              CMAKE_STAGING_PREFIX.
2046
2047       The  default search order is designed to be most-specific to least-spe‐
2048       cific for common use cases.  Projects may override the order by  simply
2049       calling the command multiple times and using the NO_* options:
2050
2051          find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2052          find_program (<VAR> NAMES name)
2053
2054       Once  one  of  the  calls  succeeds the result variable will be set and
2055       stored in the cache so that no call will search again.
2056
2057       When more than one value is given to the NAMES option this  command  by
2058       default will consider one name at a time and search every directory for
2059       it.  The NAMES_PER_DIR option tells this command to consider one direc‐
2060       tory at a time and search for all names in it.
2061
2062   foreach
2063       Evaluate a group of commands for each value in a list.
2064
2065          foreach(loop_var arg1 arg2 ...)
2066            COMMAND1(ARGS ...)
2067            COMMAND2(ARGS ...)
2068            ...
2069          endforeach(loop_var)
2070
2071       All  commands  between foreach and the matching endforeach are recorded
2072       without being invoked.  Once the endforeach is evaluated, the  recorded
2073       list of commands is invoked once for each argument listed in the origi‐
2074       nal foreach command.  Before each iteration  of  the  loop  ${loop_var}
2075       will be set as a variable with the current value in the list.
2076
2077          foreach(loop_var RANGE total)
2078          foreach(loop_var RANGE start stop [step])
2079
2080       Foreach  can also iterate over a generated range of numbers.  There are
2081       three types of this iteration:
2082
2083       · When specifying single number, the range will have elements [0, …  to
2084         “total”] (inclusive).
2085
2086       · When  specifying  two  numbers, the range will have elements from the
2087         first number to the second number (inclusive).
2088
2089       · The third optional number is the increment used to iterate  from  the
2090         first number to the second number (inclusive).
2091
2092          foreach(loop_var IN [LISTS [list1 [...]]]
2093                              [ITEMS [item1 [...]]])
2094
2095       Iterates  over  a  precise  list  of  items.   The  LISTS  option names
2096       list-valued variables to be traversed,  including  empty  elements  (an
2097       empty  string  is  a  zero-length list).  (Note macro arguments are not
2098       variables.)  The ITEMS option ends argument parsing  and  includes  all
2099       arguments following it in the iteration.
2100
2101   function
2102       Start recording a function for later invocation as a command:
2103
2104          function(<name> [arg1 [arg2 [arg3 ...]]])
2105            COMMAND1(ARGS ...)
2106            COMMAND2(ARGS ...)
2107            ...
2108          endfunction(<name>)
2109
2110       Define  a  function named <name> that takes arguments named arg1, arg2,
2111       arg3, (…).  Commands listed after function,  but  before  the  matching
2112       endfunction(),  are not invoked until the function is invoked.  When it
2113       is invoked, the commands recorded in the function are first modified by
2114       replacing  formal  parameters  (${arg1}) with the arguments passed, and
2115       then invoked as normal commands.  In addition to referencing the formal
2116       parameters you can reference the ARGC variable which will be set to the
2117       number of arguments passed into the function as well as  ARGV0,  ARGV1,
2118       ARGV2, …  which will have the actual values of the arguments passed in.
2119       This facilitates creating functions with optional arguments.  Addition‐
2120       ally  ARGV  holds  the  list of all arguments given to the function and
2121       ARGN holds the list of arguments past the last expected argument.  Ref‐
2122       erencing to ARGV# arguments beyond ARGC have undefined behavior. Check‐
2123       ing that ARGC is greater than # is the only way to  ensure  that  ARGV#
2124       was passed to the function as an extra argument.
2125
2126       A function opens a new scope: see set(var PARENT_SCOPE) for details.
2127
2128       See  the cmake_policy() command documentation for the behavior of poli‐
2129       cies inside functions.
2130
2131   get_cmake_property
2132       Get a global property of the CMake instance.
2133
2134          get_cmake_property(VAR property)
2135
2136       Get a global property from the CMake instance.  The value of the  prop‐
2137       erty  is stored in the variable VAR.  If the property is not found, VAR
2138       will be  set to “NOTFOUND”.  See  the  cmake-properties(7)  manual  for
2139       available properties.
2140
2141       See also the get_property() command GLOBAL option.
2142
2143       In addition to global properties, this command (for historical reasons)
2144       also supports the VARIABLES and MACROS directory properties.   It  also
2145       supports a special COMPONENTS global property that lists the components
2146       given to the install() command.
2147
2148   get_directory_property
2149       Get a property of DIRECTORY scope.
2150
2151          get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2152
2153       Store a property of directory scope in  the  named  variable.   If  the
2154       property  is  not  defined the empty-string is returned.  The DIRECTORY
2155       argument specifies another directory from which to retrieve  the  prop‐
2156       erty  value.   The specified directory must have already been traversed
2157       by CMake.
2158
2159          get_directory_property(<variable> [DIRECTORY <dir>]
2160                                 DEFINITION <var-name>)
2161
2162       Get a variable definition from a directory.  This form is useful to get
2163       a variable definition from another directory.
2164
2165       See also the more general get_property() command.
2166
2167   get_filename_component
2168       Get a specific component of a full filename.
2169
2170
2171                                        ----
2172
2173
2174
2175          get_filename_component(<VAR> <FileName> <COMP> [CACHE])
2176
2177       Set <VAR> to a component of <FileName>, where <COMP> is one of:
2178
2179          DIRECTORY = Directory without file name
2180          NAME      = File name without directory
2181          EXT       = File name longest extension (.b.c from d/a.b.c)
2182          NAME_WE   = File name without directory or longest extension
2183          PATH      = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2184
2185       Paths  are  returned with forward slashes and have no trailing slashes.
2186       The longest file extension is always considered.  If the optional CACHE
2187       argument is specified, the result variable is added to the cache.
2188
2189
2190                                        ----
2191
2192
2193
2194          get_filename_component(<VAR> <FileName>
2195                                 <COMP> [BASE_DIR <BASE_DIR>]
2196                                 [CACHE])
2197
2198       Set <VAR> to the absolute path of <FileName>, where <COMP> is one of:
2199
2200          ABSOLUTE  = Full path to file
2201          REALPATH  = Full path to existing file with symlinks resolved
2202
2203       If the provided <FileName> is a relative path, it is evaluated relative
2204       to the given base directory <BASE_DIR>.  If no base directory  is  pro‐
2205       vided, the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
2206
2207       Paths  are  returned  with forward slashes and have no trailing slahes.
2208       If the optional CACHE argument is specified,  the  result  variable  is
2209       added to the cache.
2210
2211
2212                                        ----
2213
2214
2215
2216          get_filename_component(<VAR> <FileName>
2217                                 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2218                                 [CACHE])
2219
2220       The  program  in  <FileName> will be found in the system search path or
2221       left as a full path.  If PROGRAM_ARGS is present with PROGRAM, then any
2222       command-line  arguments present in the <FileName> string are split from
2223       the program name and stored in <ARG_VAR>.  This is used to  separate  a
2224       program name from its arguments in a command line string.
2225
2226   get_property
2227       Get a property.
2228
2229          get_property(<variable>
2230                       <GLOBAL             |
2231                        DIRECTORY [dir]    |
2232                        TARGET    <target> |
2233                        SOURCE    <source> |
2234                        INSTALL   <file>   |
2235                        TEST      <test>   |
2236                        CACHE     <entry>  |
2237                        VARIABLE>
2238                       PROPERTY <name>
2239                       [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2240
2241       Get one property from one object in a scope.  The first argument speci‐
2242       fies the variable in which to store the result.   The  second  argument
2243       determines the scope from which to get the property.  It must be one of
2244       the following:
2245
2246       GLOBAL Scope is unique and does not accept a name.
2247
2248       DIRECTORY
2249              Scope defaults to the current directory  but  another  directory
2250              (already  processed  by  CMake) may be named by full or relative
2251              path.
2252
2253       TARGET Scope must name one existing target.
2254
2255       SOURCE Scope must name one source file.
2256
2257       INSTALL
2258              Scope must name one installed file path.
2259
2260       TEST   Scope must name one existing test.
2261
2262       CACHE  Scope must name one cache entry.
2263
2264       VARIABLE
2265              Scope is unique and does not accept a name.
2266
2267       The required PROPERTY option is immediately followed by the name of the
2268       property  to  get.   If  the  property  is  not  set  an empty value is
2269       returned.  If the SET option is given the variable is set to a  boolean
2270       value  indicating  whether  the  property has been set.  If the DEFINED
2271       option is given the variable is  set  to  a  boolean  value  indicating
2272       whether  the  property  has  been defined such as with the define_prop‐
2273       erty() command.  If BRIEF_DOCS or FULL_DOCS is given then the  variable
2274       is set to a string containing documentation for the requested property.
2275       If documentation is requested for a property that has not been  defined
2276       NOTFOUND is returned.
2277
2278   if
2279       Conditionally execute a group of commands.
2280
2281          if(expression)
2282            # then section.
2283            COMMAND1(ARGS ...)
2284            COMMAND2(ARGS ...)
2285            #...
2286          elseif(expression2)
2287            # elseif section.
2288            COMMAND1(ARGS ...)
2289            COMMAND2(ARGS ...)
2290            #...
2291          else(expression)
2292            # else section.
2293            COMMAND1(ARGS ...)
2294            COMMAND2(ARGS ...)
2295            #...
2296          endif(expression)
2297
2298       Evaluates the given expression.  If the result is true, the commands in
2299       the THEN section are invoked.  Otherwise, the commands in the else sec‐
2300       tion  are invoked.  The elseif and else sections are optional.  You may
2301       have multiple elseif clauses.  Note that the expression in the else and
2302       endif  clause is optional.  Long expressions can be used and there is a
2303       traditional order of precedence.  Parenthetical expressions are  evalu‐
2304       ated  first  followed  by  unary  tests  such  as  EXISTS, COMMAND, and
2305       DEFINED.  Then any  binary  tests  such  as  EQUAL,  LESS,  LESS_EQUAL,
2306       GREATER,  GREATER_EQUAL,  STREQUAL, STRLESS, STRLESS_EQUAL, STRGREATER,
2307       STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS, VERSION_LESS_EQUAL, VER‐
2308       SION_GREATER,  VERSION_GREATER_EQUAL,  and  MATCHES  will be evaluated.
2309       Then boolean NOT operators and finally boolean AND and then  OR  opera‐
2310       tors will be evaluated.
2311
2312       Possible expressions are:
2313
2314       if(<constant>)
2315              True  if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2316              ber.  False if the constant is 0, OFF,  NO,  FALSE,  N,  IGNORE,
2317              NOTFOUND,  the  empty  string,  or ends in the suffix -NOTFOUND.
2318              Named boolean constants are case-insensitive.  If  the  argument
2319              is not one of these specific constants, it is treated as a vari‐
2320              able or string and the following signature is used.
2321
2322       if(<variable|string>)
2323              True if given a variable that is defined to a value that is  not
2324              a  false  constant.  False otherwise.  (Note macro arguments are
2325              not variables.)
2326
2327       if(NOT <expression>)
2328              True if the expression is not true.
2329
2330       if(<expr1> AND <expr2>)
2331              True if both expressions would be considered true individually.
2332
2333       if(<expr1> OR <expr2>)
2334              True if either expression would be considered true individually.
2335
2336       if(COMMAND command-name)
2337              True if the given name is a command, macro or function that  can
2338              be invoked.
2339
2340       if(POLICY policy-id)
2341              True  if  the  given  name  is  an  existing policy (of the form
2342              CMP<NNNN>).
2343
2344       if(TARGET target-name)
2345              True if the given name is an existing logical target  name  cre‐
2346              ated  by  a  call  to  the  add_executable(),  add_library(), or
2347              add_custom_target() command that has already  been  invoked  (in
2348              any directory).
2349
2350       if(TEST test-name)
2351              True  if  the given name is an existing test name created by the
2352              add_test() command.
2353
2354       if(EXISTS path-to-file-or-directory)
2355              True if  the  named  file  or  directory  exists.   Behavior  is
2356              well-defined only for full paths.
2357
2358       if(file1 IS_NEWER_THAN file2)
2359              True  if  file1  is  newer than file2 or if one of the two files
2360              doesn’t exist.  Behavior is well-defined only  for  full  paths.
2361              If  the  file time stamps are exactly the same, an IS_NEWER_THAN
2362              comparison returns true, so that any dependent build  operations
2363              will  occur  in  the  event of a tie.  This includes the case of
2364              passing the same file name for both file1 and file2.
2365
2366       if(IS_DIRECTORY path-to-directory)
2367              True if the given name is a directory.  Behavior is well-defined
2368              only for full paths.
2369
2370       if(IS_SYMLINK file-name)
2371              True  if  the  given  name  is  a  symbolic  link.   Behavior is
2372              well-defined only for full paths.
2373
2374       if(IS_ABSOLUTE path)
2375              True if the given path is an absolute path.
2376
2377       if(<variable|string> MATCHES regex)
2378              True if the given string or variable’s value matches  the  given
2379              regular  expression.   See Regex Specification for regex format.
2380              () groups are captured in CMAKE_MATCH_<n> variables.
2381
2382       if(<variable|string> LESS <variable|string>)
2383              True if the given string or variable’s value is a  valid  number
2384              and less than that on the right.
2385
2386       if(<variable|string> GREATER <variable|string>)
2387              True  if  the given string or variable’s value is a valid number
2388              and greater than that on the right.
2389
2390       if(<variable|string> EQUAL <variable|string>)
2391              True if the given string or variable’s value is a  valid  number
2392              and equal to that on the right.
2393
2394       if(<variable|string> LESS_EQUAL <variable|string>)
2395              True  if  the given string or variable’s value is a valid number
2396              and less than or equal to that on the right.
2397
2398       if(<variable|string> GREATER_EQUAL <variable|string>)
2399              True if the given string or variable’s value is a  valid  number
2400              and greater than or equal to that on the right.
2401
2402       if(<variable|string> STRLESS <variable|string>)
2403              True  if  the  given string or variable’s value is lexicographi‐
2404              cally less than the string or variable on the right.
2405
2406       if(<variable|string> STRGREATER <variable|string>)
2407              True if the given string or variable’s  value  is  lexicographi‐
2408              cally greater than the string or variable on the right.
2409
2410       if(<variable|string> STREQUAL <variable|string>)
2411              True  if  the  given string or variable’s value is lexicographi‐
2412              cally equal to the string or variable on the right.
2413
2414       if(<variable|string> STRLESS_EQUAL <variable|string>)
2415              True if the given string or variable’s  value  is  lexicographi‐
2416              cally less than or equal to the string or variable on the right.
2417
2418       if(<variable|string> STRGREATER_EQUAL <variable|string>)
2419              True  if  the  given string or variable’s value is lexicographi‐
2420              cally greater than or equal to the string  or  variable  on  the
2421              right.
2422
2423       if(<variable|string> VERSION_LESS <variable|string>)
2424              Component-wise integer version number comparison (version format
2425              is major[.minor[.patch[.tweak]]]).
2426
2427       if(<variable|string> VERSION_GREATER <variable|string>)
2428              Component-wise integer version number comparison (version format
2429              is major[.minor[.patch[.tweak]]]).
2430
2431       if(<variable|string> VERSION_EQUAL <variable|string>)
2432              Component-wise integer version number comparison (version format
2433              is major[.minor[.patch[.tweak]]]).
2434
2435       if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
2436              Component-wise integer version number comparison (version format
2437              is major[.minor[.patch[.tweak]]]).
2438
2439       if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
2440              Component-wise integer version number comparison (version format
2441              is major[.minor[.patch[.tweak]]]).
2442
2443       if(<variable|string> IN_LIST <variable>)
2444              True if the given element is contained in the named  list  vari‐
2445              able.
2446
2447       if(DEFINED <variable>)
2448              True  if  the  given variable is defined.  It does not matter if
2449              the variable is true or false just if it has  been  set.   (Note
2450              macro arguments are not variables.)
2451
2452       if((expression) AND (expression OR (expression)))
2453              The  expressions  inside the parenthesis are evaluated first and
2454              then the remaining expression is evaluated as  in  the  previous
2455              examples.   Where there are nested parenthesis the innermost are
2456              evaluated as part of evaluating  the  expression  that  contains
2457              them.
2458
2459       The if command was written very early in CMake’s history, predating the
2460       ${} variable evaluation syntax, and for convenience evaluates variables
2461       named  by  its  arguments  as shown in the above signatures.  Note that
2462       normal variable evaluation with ${} applies before the if command  even
2463       receives the arguments.  Therefore code like:
2464
2465          set(var1 OFF)
2466          set(var2 "var1")
2467          if(${var2})
2468
2469       appears to the if command as:
2470
2471          if(var1)
2472
2473       and is evaluated according to the if(<variable>) case documented above.
2474       The result is OFF which is false.  However, if we remove the  ${}  from
2475       the example then the command sees:
2476
2477          if(var2)
2478
2479       which  is  true  because var2 is defined to “var1” which is not a false
2480       constant.
2481
2482       Automatic evaluation applies in the other cases whenever the above-doc‐
2483       umented signature accepts <variable|string>:
2484
2485       · The  left hand argument to MATCHES is first checked to see if it is a
2486         defined variable, if so the variable’s value is used,  otherwise  the
2487         original value is used.
2488
2489       · If  the  left  hand  argument  to MATCHES is missing it returns false
2490         without error
2491
2492       · Both  left  and  right  hand  arguments  to  LESS,  GREATER,   EQUAL,
2493         LESS_EQUAL,  and  GREATER_EQUAL,  are  independently tested to see if
2494         they are defined variables, if so their defined values are used  oth‐
2495         erwise the original value is used.
2496
2497       · Both  left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
2498         STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested  to  see
2499         if  they  are  defined variables, if so their defined values are used
2500         otherwise the original value is used.
2501
2502       · Both left and right hand arguments to VERSION_LESS,  VERSION_GREATER,
2503         VERSION_EQUAL,   VERSION_LESS_EQUAL,  and  VERSION_GREATER_EQUAL  are
2504         independently tested to see if they  are  defined  variables,  if  so
2505         their defined values are used otherwise the original value is used.
2506
2507       · The  right  hand  argument to NOT is tested to see if it is a boolean
2508         constant, if so the value is used, otherwise it is assumed  to  be  a
2509         variable and it is dereferenced.
2510
2511       · The  left  and  right  hand arguments to AND and OR are independently
2512         tested to see if they are boolean constants, if so they are  used  as
2513         such,  otherwise  they  are  assumed to be variables and are derefer‐
2514         enced.
2515
2516       To prevent ambiguity, potential variable or keyword names can be speci‐
2517       fied in a Quoted Argument or a Bracket Argument.  A quoted or bracketed
2518       variable or keyword will be interpreted as a string  and  not  derefer‐
2519       enced or interpreted.  See policy CMP0054.
2520
2521   include
2522       Load and run CMake code from a file or module.
2523
2524          include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
2525                                [NO_POLICY_SCOPE])
2526
2527       Load and run CMake code from the file given.  Variable reads and writes
2528       access the scope of the  caller  (dynamic  scoping).   If  OPTIONAL  is
2529       present,  then  no  error  is  raised  if  the file does not exist.  If
2530       RESULT_VARIABLE is given the variable will be set to the full  filename
2531       which has been included or NOTFOUND if it failed.
2532
2533       If a module is specified instead of a file, the file with name <module‐
2534       name>.cmake is searched first in CMAKE_MODULE_PATH, then in  the  CMake
2535       module  directory.   There  is one exception to this: if the file which
2536       calls include() is located itself in the CMake  builtin  module  direc‐
2537       tory,  then  first  the  CMake builtin module directory is searched and
2538       CMAKE_MODULE_PATH afterwards.  See also policy CMP0017.
2539
2540       See the cmake_policy() command  documentation  for  discussion  of  the
2541       NO_POLICY_SCOPE option.
2542
2543   include_guard
2544       Provides  an  include  guard  for the file currently being processed by
2545       CMake.
2546
2547          include_guard([DIRECTORY|GLOBAL])
2548
2549       Sets up an include guard for the current CMake file (see the CMAKE_CUR‐
2550       RENT_LIST_FILE variable documentation).
2551
2552       CMake  will  end  its processing of the current file at the location of
2553       the include_guard() command if the current file has already  been  pro‐
2554       cessed  for the applicable scope (see below). This provides functional‐
2555       ity similar to the include guards commonly used in source headers or to
2556       the #pragma once directive. If the current file has been processed pre‐
2557       viously for the applicable scope, the effect is as though return()  had
2558       been  called.  Do  not  call  this command from inside a function being
2559       defined within the current file.
2560
2561       An optional argument specifying the scope of the guard may be provided.
2562       Possible values for the option are:
2563
2564       DIRECTORY
2565              The  include  guard  applies  within  the  current directory and
2566              below. The file will only be included once within this directory
2567              scope,  but may be included again by other files outside of this
2568              directory (i.e. a parent  directory  or  another  directory  not
2569              pulled  in  by  add_subdirectory() or include() from the current
2570              file or its children).
2571
2572       GLOBAL The include guard applies globally to the whole build. The  cur‐
2573              rent file will only be included once regardless of the scope.
2574
2575       If  no arguments given, include_guard has the same scope as a variable,
2576       meaning that the include guard effect is isolated by  the  most  recent
2577       function  scope or current directory if no inner function scopes exist.
2578       In this case the command behavior is the same as:
2579
2580          if(__CURRENT_FILE_VAR__)
2581            return()
2582          endif()
2583          set(__CURRENT_FILE_VAR__ TRUE)
2584
2585   list
2586       List operations.
2587
2588          list(LENGTH <list> <output variable>)
2589          list(GET <list> <element index> [<element index> ...]
2590               <output variable>)
2591          list(APPEND <list> [<element> ...])
2592          list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
2593          list(FIND <list> <value> <output variable>)
2594          list(INSERT <list> <element_index> <element> [<element> ...])
2595          list(REMOVE_ITEM <list> <value> [<value> ...])
2596          list(REMOVE_AT <list> <index> [<index> ...])
2597          list(REMOVE_DUPLICATES <list>)
2598          list(REVERSE <list>)
2599          list(SORT <list>)
2600
2601       LENGTH will return a given list’s length.
2602
2603       GET will return list of elements specified by indices from the list.
2604
2605       APPEND will append elements to the list.
2606
2607       FILTER will include or remove items from the list that match the mode’s
2608       pattern.   In REGEX mode, items will be matched against the given regu‐
2609       lar expression.  For more information on regular expressions  see  also
2610       the string() command.
2611
2612       FIND  will  return the index of the element specified in the list or -1
2613       if it wasn’t found.
2614
2615       INSERT will insert elements to the list to the specified location.
2616
2617       REMOVE_AT and REMOVE_ITEM will remove items from the list.  The differ‐
2618       ence  is  that REMOVE_ITEM will remove the given items, while REMOVE_AT
2619       will remove the items at the given indices.
2620
2621       REMOVE_DUPLICATES will remove duplicated items in the list.
2622
2623       REVERSE reverses the contents of the list in-place.
2624
2625       SORT sorts the list in-place alphabetically.
2626
2627       The list subcommands APPEND, INSERT,  FILTER,  REMOVE_AT,  REMOVE_ITEM,
2628       REMOVE_DUPLICATES,  REVERSE and SORT may create new values for the list
2629       within the current CMake variable scope.  Similar to the set() command,
2630       the LIST command creates new variable values in the current scope, even
2631       if the list itself is actually defined in a parent scope.  To propagate
2632       the  results  of these operations upwards, use set() with PARENT_SCOPE,
2633       set() with CACHE INTERNAL, or some other means of value propagation.
2634
2635       NOTES: A list in cmake is a ; separated group of strings.  To create  a
2636       list the set command can be used.  For example, set(var a b c d e) cre‐
2637       ates a list with a;b;c;d;e, and set(var "a b c d e") creates  a  string
2638       or  a  list  with one item in it.   (Note macro arguments are not vari‐
2639       ables, and therefore cannot be used in LIST commands.)
2640
2641       When specifying index values, if <element index> is 0 or greater, it is
2642       indexed  from  the beginning of the list, with 0 representing the first
2643       list element.  If <element index> is -1 or lesser, it is  indexed  from
2644       the  end  of  the list, with -1 representing the last list element.  Be
2645       careful when counting with negative indices: they do not start from  0.
2646       -0 is equivalent to 0, the first list element.
2647
2648   macro
2649       Start recording a macro for later invocation as a command:
2650
2651          macro(<name> [arg1 [arg2 [arg3 ...]]])
2652            COMMAND1(ARGS ...)
2653            COMMAND2(ARGS ...)
2654            ...
2655          endmacro(<name>)
2656
2657       Define  a  macro  named  <name>  that takes arguments named arg1, arg2,
2658       arg3, (…).  Commands listed after macro, but before the  matching  end‐
2659       macro(),  are  not  invoked  until  the  macro  is invoked.  When it is
2660       invoked, the commands recorded in  the  macro  are  first  modified  by
2661       replacing  formal  parameters  (${arg1}) with the arguments passed, and
2662       then invoked as normal commands.  In addition to referencing the formal
2663       parameters  you  can  reference the values ${ARGC} which will be set to
2664       the number of arguments passed into the function as well  as  ${ARGV0},
2665       ${ARGV1},  ${ARGV2},  …  which will have the actual values of the argu‐
2666       ments passed in.  This facilitates creating macros with optional  argu‐
2667       ments.   Additionally  ${ARGV} holds the list of all arguments given to
2668       the macro and ${ARGN}  holds  the  list  of  arguments  past  the  last
2669       expected  argument.   Referencing  to ${ARGV#} arguments beyond ${ARGC}
2670       have undefined behavior. Checking that ${ARGC} is greater than # is the
2671       only way to ensure that ${ARGV#} was passed to the function as an extra
2672       argument.
2673
2674       See the cmake_policy() command documentation for the behavior of  poli‐
2675       cies inside macros.
2676
2677   Macro Argument Caveats
2678       Note  that  the  parameters  to a macro and values such as ARGN are not
2679       variables in the usual CMake sense.  They are string replacements  much
2680       like  the C preprocessor would do with a macro.  Therefore you will NOT
2681       be able to use commands like:
2682
2683          if(ARGV1) # ARGV1 is not a variable
2684          if(DEFINED ARGV2) # ARGV2 is not a variable
2685          if(ARGC GREATER 2) # ARGC is not a variable
2686          foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
2687
2688       In the first case, you can use if(${ARGV1}).  In the second  and  third
2689       case, the proper way to check if an optional variable was passed to the
2690       macro is to use if(${ARGC} GREATER 2).  In the last case, you  can  use
2691       foreach(loop_var  ${ARGN})  but this will skip empty arguments.  If you
2692       need to include them, you can use:
2693
2694          set(list_var "${ARGN}")
2695          foreach(loop_var IN LISTS list_var)
2696
2697       Note that if you have a variable with the same name in the  scope  from
2698       which the macro is called, using unreferenced names will use the exist‐
2699       ing variable instead of the arguments. For example:
2700
2701          macro(_BAR)
2702            foreach(arg IN LISTS ARGN)
2703              [...]
2704            endforeach()
2705          endmacro()
2706
2707          function(_FOO)
2708            _bar(x y z)
2709          endfunction()
2710
2711          _foo(a b c)
2712
2713       Will loop over a;b;c and not over x;y;z as one might be expecting.   If
2714       you  want  true  CMake  variables and/or better CMake scope control you
2715       should look at the function command.
2716
2717   mark_as_advanced
2718       Mark cmake cached variables as advanced.
2719
2720          mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...])
2721
2722       Mark the named cached variables as advanced.  An advanced variable will
2723       not  be  displayed  in  any  of the cmake GUIs unless the show advanced
2724       option is on.  If CLEAR is the first argument  advanced  variables  are
2725       changed  back  to unadvanced.  If FORCE is the first argument, then the
2726       variable is made advanced.  If neither FORCE nor  CLEAR  is  specified,
2727       new  values will be marked as advanced, but if the variable already has
2728       an advanced/non-advanced state, it will not be changed.
2729
2730       It does nothing in script mode.
2731
2732   math
2733       Mathematical expressions.
2734
2735          math(EXPR <output-variable> <math-expression>)
2736
2737       EXPR evaluates mathematical expression and returns result in the output
2738       variable.  Example mathematical expression is 5 * (10 + 13).  Supported
2739       operators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...).  They  have
2740       the same meaning as they do in C code.
2741
2742   message
2743       Display a message to the user.
2744
2745          message([<mode>] "message to display" ...)
2746
2747       The optional <mode> keyword determines the type of message:
2748
2749          (none)         = Important information
2750          STATUS         = Incidental information
2751          WARNING        = CMake Warning, continue processing
2752          AUTHOR_WARNING = CMake Warning (dev), continue processing
2753          SEND_ERROR     = CMake Error, continue processing,
2754                                        but skip generation
2755          FATAL_ERROR    = CMake Error, stop processing and generation
2756          DEPRECATION    = CMake Deprecation Error or Warning if variable
2757                           CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED
2758                           is enabled, respectively, else no message.
2759
2760       The  CMake command-line tool displays STATUS messages on stdout and all
2761       other message types on stderr.  The CMake GUI displays all messages  in
2762       its  log  area.   The  interactive dialogs (ccmake and CMakeSetup) show
2763       STATUS messages one at a time on a status line and  other  messages  in
2764       interactive pop-up boxes.
2765
2766       CMake  Warning  and  Error  message text displays using a simple markup
2767       language.  Non-indented text is formatted  in  line-wrapped  paragraphs
2768       delimited by newlines.  Indented text is considered pre-formatted.
2769
2770   option
2771       Provides an option that the user can optionally select.
2772
2773          option(<option_variable> "help string describing option"
2774                 [initial value])
2775
2776       Provide  an  option for the user to select as ON or OFF.  If no initial
2777       value is provided, OFF is used.
2778
2779       If you have options that depend on the values of other options, see the
2780       module help for CMakeDependentOption.
2781
2782   return
2783       Return from a file, directory or function.
2784
2785          return()
2786
2787       Returns  from  a  file,  directory  or  function.  When this command is
2788       encountered in an included file (via include() or  find_package()),  it
2789       causes  processing  of the current file to stop and control is returned
2790       to the including file.  If it is encountered in a  file  which  is  not
2791       included  by  another file, e.g.  a CMakeLists.txt, control is returned
2792       to the parent directory if there is one.  If  return  is  called  in  a
2793       function, control is returned to the caller of the function.  Note that
2794       a macro is not a function and does not handle return  like  a  function
2795       does.
2796
2797   separate_arguments
2798       Parse space-separated arguments into a semicolon-separated list.
2799
2800          separate_arguments(<var> <NATIVE|UNIX|WINDOWS>_COMMAND "<args>")
2801
2802       Parses a UNIX- or Windows-style command-line string “<args>” and stores
2803       a semicolon-separated list of the arguments in <var>.  The entire  com‐
2804       mand line must be given in one “<args>” argument.
2805
2806       The  UNIX_COMMAND  mode separates arguments by unquoted whitespace.  It
2807       recognizes both  single-quote  and  double-quote  pairs.   A  backslash
2808       escapes  the  next  literal  character  (\" is "); there are no special
2809       escapes (\n is just n).
2810
2811       The WINDOWS_COMMAND mode parses a Windows command-line using  the  same
2812       syntax the runtime library uses to construct argv at startup.  It sepa‐
2813       rates arguments by whitespace that is not  double-quoted.   Backslashes
2814       are  literal  unless  they precede double-quotes.  See the MSDN article
2815       Parsing C Command-Line Arguments for details.
2816
2817       The NATIVE_COMMAND mode parses a Windows command-line if the host  sys‐
2818       tem is Windows, and a UNIX command-line otherwise.
2819
2820          separate_arguments(<var>)
2821
2822       Convert  the value of <var> to a semi-colon separated list.  All spaces
2823       are replaced with ‘;’.  This helps with generating command lines.
2824
2825   set_directory_properties
2826       Set a property of the directory.
2827
2828          set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
2829
2830       Set a property for the current directory and subdirectories. See Direc‐
2831       tory Properties for the list of properties known to CMake.
2832
2833   set_property
2834       Set a named property in a given scope.
2835
2836          set_property(<GLOBAL                            |
2837                        DIRECTORY [dir]                   |
2838                        TARGET    [target1 [target2 ...]] |
2839                        SOURCE    [src1 [src2 ...]]       |
2840                        INSTALL   [file1 [file2 ...]]     |
2841                        TEST      [test1 [test2 ...]]     |
2842                        CACHE     [entry1 [entry2 ...]]>
2843                       [APPEND] [APPEND_STRING]
2844                       PROPERTY <name> [value1 [value2 ...]])
2845
2846       Set  one  property on zero or more objects of a scope.  The first argu‐
2847       ment determines the scope in which the property is set.  It must be one
2848       of the following:
2849
2850       GLOBAL Scope is unique and does not accept a name.
2851
2852       DIRECTORY
2853              Scope  defaults  to  the current directory but another directory
2854              (already processed by CMake) may be named by  full  or  relative
2855              path.
2856
2857       TARGET Scope may name zero or more existing targets.
2858
2859       SOURCE Scope may name zero or more source files.  Note that source file
2860              properties are visible only to targets added in the same  direc‐
2861              tory (CMakeLists.txt).
2862
2863       INSTALL
2864              Scope  may  name  zero  or more installed file paths.  These are
2865              made available to CPack to influence deployment.
2866
2867              Both the property key and value may use  generator  expressions.
2868              Specific properties may apply to installed files and/or directo‐
2869              ries.
2870
2871              Path components have to be separated by forward slashes, must be
2872              normalized and are case sensitive.
2873
2874              To reference the installation prefix itself with a relative path
2875              use “.”.
2876
2877              Currently installed file properties are only defined for the WIX
2878              generator where the given paths are relative to the installation
2879              prefix.
2880
2881       TEST   Scope may name zero or more existing tests.
2882
2883       CACHE  Scope must name zero or more cache existing entries.
2884
2885       The required PROPERTY option is immediately followed by the name of the
2886       property  to set.  Remaining arguments are used to compose the property
2887       value in the form of a semicolon-separated list.  If the APPEND  option
2888       is  given  the list is appended to any existing property value.  If the
2889       APPEND_STRING option is given the string  is  append  to  any  existing
2890       property value as string, i.e.  it results in a longer string and not a
2891       list of strings.
2892
2893       See the cmake-properties(7) manual for a list  of  properties  in  each
2894       scope.
2895
2896   set
2897       Set a normal, cache, or environment variable to a given value.  See the
2898       cmake-language(7) variables documentation for the scopes  and  interac‐
2899       tion of normal variables and cache entries.
2900
2901       Signatures of this command that specify a <value>... placeholder expect
2902       zero or more arguments.  Multiple arguments will be joined as a  ;-list
2903       to form the actual variable value to be set.  Zero arguments will cause
2904       normal variables to be unset.  See the unset() command to  unset  vari‐
2905       ables explicitly.
2906
2907   Set Normal Variable
2908          set(<variable> <value>... [PARENT_SCOPE])
2909
2910       Set the given <variable> in the current function or directory scope.
2911
2912       If  the  PARENT_SCOPE  option  is given the variable will be set in the
2913       scope above the current scope.  Each new directory or function  creates
2914       a  new  scope.   This command will set the value of a variable into the
2915       parent directory or calling function (whichever is  applicable  to  the
2916       case  at  hand).  The  previous state of the variable’s value stays the
2917       same in the current scope (e.g., if it  was  undefined  before,  it  is
2918       still undefined and if it had a value, it is still that value).
2919
2920   Set Cache Entry
2921          set(<variable> <value>... CACHE <type> <docstring> [FORCE])
2922
2923       Set  the given cache <variable> (cache entry).  Since cache entries are
2924       meant to provide user-settable values this does not overwrite  existing
2925       cache  entries  by default.  Use the FORCE option to overwrite existing
2926       entries.
2927
2928       The <type> must be specified as one of:
2929
2930       BOOL   Boolean ON/OFF value.  cmake-gui(1) offers a checkbox.
2931
2932       FILEPATH
2933              Path to a file on disk.  cmake-gui(1) offers a file dialog.
2934
2935       PATH   Path to a directory on disk.  cmake-gui(1) offers a file dialog.
2936
2937       STRING A line of text.  cmake-gui(1) offers a text field or a drop-down
2938              selection if the STRINGS cache entry property is set.
2939
2940       INTERNAL
2941              A  line  of  text.  cmake-gui(1) does not show internal entries.
2942              They may be used to store variables  persistently  across  runs.
2943              Use of this type implies FORCE.
2944
2945       The  <docstring>  must be specified as a line of text providing a quick
2946       summary of the option for presentation to cmake-gui(1) users.
2947
2948       If the cache entry does not exist prior to the call or the FORCE option
2949       is given then the cache entry will be set to the given value.  Further‐
2950       more, any normal variable binding in the current scope will be  removed
2951       to  expose  the newly cached value to any immediately following evalua‐
2952       tion.
2953
2954       It is possible for the cache entry to exist prior to the call but  have
2955       no  type  set  if it was created on the cmake(1) command line by a user
2956       through the -D<var>=<value> option without specifying a type.  In  this
2957       case  the set command will add the type.  Furthermore, if the <type> is
2958       PATH or FILEPATH and the <value> provided on the command line is a rel‐
2959       ative path, then the set command will treat the path as relative to the
2960       current working directory and convert it to an absolute path.
2961
2962   Set Environment Variable
2963          set(ENV{<variable>} <value>...)
2964
2965       Set the current process environment <variable> to the given value.
2966
2967   site_name
2968       Set the given variable to the name of the computer.
2969
2970          site_name(variable)
2971
2972   string
2973       String operations.
2974
2975   Search and Replace
2976   FIND
2977          string(FIND <string> <substring> <output variable> [REVERSE])
2978
2979       Return the position where the given substring was found in the supplied
2980       string.   If the REVERSE flag was used, the command will search for the
2981       position of the last occurrence of the  specified  substring.   If  the
2982       substring is not found, a position of -1 is returned.
2983
2984   REPLACE
2985          string(REPLACE <match_string>
2986                 <replace_string> <output variable>
2987                 <input> [<input>...])
2988
2989       Replace   all   occurrences   of   match_string   in   the  input  with
2990       replace_string and store the result in the output.
2991
2992   Regular Expressions
2993   REGEX MATCH
2994          string(REGEX MATCH <regular_expression>
2995                 <output variable> <input> [<input>...])
2996
2997       Match the regular expression once and store the  match  in  the  output
2998       variable.  All <input> arguments are concatenated before matching.
2999
3000   REGEX MATCHALL
3001          string(REGEX MATCHALL <regular_expression>
3002                 <output variable> <input> [<input>...])
3003
3004       Match  the  regular  expression as many times as possible and store the
3005       matches in the output variable as a list.  All  <input>  arguments  are
3006       concatenated before matching.
3007
3008   REGEX REPLACE
3009          string(REGEX REPLACE <regular_expression>
3010                 <replace_expression> <output variable>
3011                 <input> [<input>...])
3012
3013       Match  the  regular expression as many times as possible and substitute
3014       the replacement expression for the match in the  output.   All  <input>
3015       arguments are concatenated before matching.
3016
3017       The  replace  expression may refer to paren-delimited subexpressions of
3018       the match using \1, \2, …, \9.  Note that  two  backslashes  (\\1)  are
3019       required in CMake code to get a backslash through argument parsing.
3020
3021   Regex Specification
3022       The following characters have special meaning in regular expressions:
3023
3024       ^      Matches at beginning of input
3025
3026       $      Matches at end of input
3027
3028       .      Matches any single character
3029
3030       [ ]    Matches any character(s) inside the brackets
3031
3032       [^ ]   Matches any character(s) not inside the brackets
3033
3034       -      Inside brackets, specifies an inclusive range between characters
3035              on either side e.g. [a-f] is [abcdef] To match a literal - using
3036              brackets,  make  it  the first or the last character e.g. [+*/-]
3037              matches basic mathematical operators.
3038
3039       *      Matches preceding pattern zero or more times
3040
3041       +      Matches preceding pattern one or more times
3042
3043       ?      Matches preceding pattern zero or once only
3044
3045       |      Matches a pattern on either side of the |
3046
3047       ()     Saves a matched subexpression, which can be  referenced  in  the
3048              REGEX REPLACE operation. Additionally it is saved by all regular
3049              expression-related commands, including e.g. if(MATCHES), in  the
3050              variables CMAKE_MATCH_<n> for <n> 0..9.
3051
3052       *,  +  and  ?  have  higher precedence than concatenation.  | has lower
3053       precedence than concatenation.  This means that the regular  expression
3054       ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
3055       matches ab but not abd.
3056
3057   Manipulation
3058   APPEND
3059          string(APPEND <string variable> [<input>...])
3060
3061       Append all the input arguments to the string.
3062
3063   PREPEND
3064          string(PREPEND <string variable> [<input>...])
3065
3066       Prepend all the input arguments to the string.
3067
3068   CONCAT
3069          string(CONCAT <output variable> [<input>...])
3070
3071       Concatenate all the input arguments together and store  the  result  in
3072       the named output variable.
3073
3074   TOLOWER
3075          string(TOLOWER <string1> <output variable>)
3076
3077       Convert string to lower characters.
3078
3079   TOUPPER
3080          string(TOUPPER <string1> <output variable>)
3081
3082       Convert string to upper characters.
3083
3084   LENGTH
3085          string(LENGTH <string> <output variable>)
3086
3087       Store in an output variable a given string’s length.
3088
3089   SUBSTRING
3090          string(SUBSTRING <string> <begin> <length> <output variable>)
3091
3092       Store  in  an output variable a substring of a given string.  If length
3093       is -1 the remainder of the string starting at begin will  be  returned.
3094       If string is shorter than length then end of string is used instead.
3095
3096       NOTE:
3097          CMake 3.1 and below reported an error if length pointed past the end
3098          of string.
3099
3100   STRIP
3101          string(STRIP <string> <output variable>)
3102
3103       Store in an output variable a substring of a given string with  leading
3104       and trailing spaces removed.
3105
3106   GENEX_STRIP
3107          string(GENEX_STRIP <input string> <output variable>)
3108
3109       Strip  any  generator  expressions  from the input string and store the
3110       result in the output variable.
3111
3112   Comparison
3113          string(COMPARE LESS <string1> <string2> <output variable>)
3114          string(COMPARE GREATER <string1> <string2> <output variable>)
3115          string(COMPARE EQUAL <string1> <string2> <output variable>)
3116          string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
3117          string(COMPARE LESS_EQUAL <string1> <string2> <output variable>)
3118          string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>)
3119
3120       Compare the strings and store true or false in the output variable.
3121
3122   Hashing
3123          string(<HASH> <output variable> <input>)
3124
3125       Compute a cryptographic hash of the input string.  The supported <HASH>
3126       algorithm names are:
3127
3128       MD5    Message-Digest Algorithm 5, RFC 1321.
3129
3130       SHA1   US Secure Hash Algorithm 1, RFC 3174.
3131
3132       SHA224 US Secure Hash Algorithms, RFC 4634.
3133
3134       SHA256 US Secure Hash Algorithms, RFC 4634.
3135
3136       SHA384 US Secure Hash Algorithms, RFC 4634.
3137
3138       SHA512 US Secure Hash Algorithms, RFC 4634.
3139
3140       SHA3_224
3141              Keccak SHA-3.
3142
3143       SHA3_256
3144              Keccak SHA-3.
3145
3146       SHA3_384
3147              Keccak SHA-3.
3148
3149       SHA3_512
3150              Keccak SHA-3.
3151
3152   Generation
3153   ASCII
3154          string(ASCII <number> [<number> ...] <output variable>)
3155
3156       Convert all numbers into corresponding ASCII characters.
3157
3158   CONFIGURE
3159          string(CONFIGURE <string1> <output variable>
3160                 [@ONLY] [ESCAPE_QUOTES])
3161
3162       Transform a string like configure_file() transforms a file.
3163
3164   RANDOM
3165          string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
3166                 [RANDOM_SEED <seed>] <output variable>)
3167
3168       Return  a  random  string of given length consisting of characters from
3169       the given alphabet.  Default length is 5 characters and default  alpha‐
3170       bet  is  all  numbers  and upper and lower case letters.  If an integer
3171       RANDOM_SEED is given, its value will be used to seed the random  number
3172       generator.
3173
3174   TIMESTAMP
3175          string(TIMESTAMP <output variable> [<format string>] [UTC])
3176
3177       Write  a  string  representation of the current date and/or time to the
3178       output variable.
3179
3180       Should the command be unable to obtain a timestamp the output  variable
3181       will be set to the empty string “”.
3182
3183       The  optional UTC flag requests the current date/time representation to
3184       be in Coordinated Universal Time (UTC) rather than local time.
3185
3186       The optional <format string> may contain the  following  format  speci‐
3187       fiers:
3188
3189          %%        A literal percent sign (%).
3190          %d        The day of the current month (01-31).
3191          %H        The hour on a 24-hour clock (00-23).
3192          %I        The hour on a 12-hour clock (01-12).
3193          %j        The day of the current year (001-366).
3194          %m        The month of the current year (01-12).
3195          %b        Abbreviated month name (e.g. Oct).
3196          %B        Full month name (e.g. October).
3197          %M        The minute of the current hour (00-59).
3198          %s        Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
3199          %S        The second of the current minute.
3200                    60 represents a leap second. (00-60)
3201          %U        The week number of the current year (00-53).
3202          %w        The day of the current week. 0 is Sunday. (0-6)
3203          %a        Abbreviated weekday name (e.g. Fri).
3204          %A        Full weekday name (e.g. Friday).
3205          %y        The last two digits of the current year (00-99)
3206          %Y        The current year.
3207
3208       Unknown  format  specifiers  will  be  ignored and copied to the output
3209       as-is.
3210
3211       If no explicit <format string> is given it will default to:
3212
3213          %Y-%m-%dT%H:%M:%S    for local time.
3214          %Y-%m-%dT%H:%M:%SZ   for UTC.
3215
3216          string(MAKE_C_IDENTIFIER <input string> <output variable>)
3217
3218       Write a string which can be used as an identifier in C.
3219
3220       NOTE:
3221          If the SOURCE_DATE_EPOCH environment variable is set, its value will
3222          be     used     instead     of     the     current     time.     See
3223          https://reproducible-builds.org/specs/source-date-epoch/         for
3224          details.
3225
3226   UUID
3227          string(UUID <output variable> NAMESPACE <namespace> NAME <name>
3228                 TYPE <MD5|SHA1> [UPPER])
3229
3230       Create  a  univerally unique identifier (aka GUID) as per RFC4122 based
3231       on the hash of the combined values of <namespace> (which itself has  to
3232       be  a  valid  UUID)  and  <name>.  The hash algorithm can be either MD5
3233       (Version 3 UUID) or SHA1 (Version 5  UUID).   A  UUID  has  the  format
3234       xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  where  each  x represents a lower
3235       case hexadecimal character.  Where required an uppercase representation
3236       can be requested with the optional UPPER flag.
3237
3238   unset
3239       Unset a variable, cache variable, or environment variable.
3240
3241          unset(<variable> [CACHE | PARENT_SCOPE])
3242
3243       Removes  the  specified  variable  causing  it to become undefined.  If
3244       CACHE is present then the variable is removed from the cache instead of
3245       the current scope.
3246
3247       If  PARENT_SCOPE is present then the variable is removed from the scope
3248       above the current scope.  See the same option in the set() command  for
3249       further details.
3250
3251       <variable> can be an environment variable such as:
3252
3253          unset(ENV{LD_LIBRARY_PATH})
3254
3255       in  which  case  the variable will be removed from the current environ‐
3256       ment.
3257
3258   variable_watch
3259       Watch the CMake variable for change.
3260
3261          variable_watch(<variable name> [<command to execute>])
3262
3263       If the specified variable changes, the message will  be  printed  about
3264       the  variable  being changed.  If the command is specified, the command
3265       will be executed.  The command will receive  the  following  arguments:
3266       COMMAND(<variable> <access> <value> <current list file> <stack>)
3267
3268   while
3269       Evaluate a group of commands while a condition is true
3270
3271          while(condition)
3272            COMMAND1(ARGS ...)
3273            COMMAND2(ARGS ...)
3274            ...
3275          endwhile(condition)
3276
3277       All  commands  between  while  and the matching endwhile() are recorded
3278       without being invoked.  Once the endwhile() is evaluated, the  recorded
3279       list of commands is invoked as long as the condition is true.  The con‐
3280       dition is evaluated using the same logic as the if() command.
3281

PROJECT COMMANDS

3283       These commands are available only in CMake projects.
3284
3285   add_compile_options
3286       Adds options to the compilation of source files.
3287
3288          add_compile_options(<option> ...)
3289
3290       Adds options to the compiler command line for targets  in  the  current
3291       directory  and below that are added after this command is invoked.  See
3292       documentation of the directory and target COMPILE_OPTIONS properties.
3293
3294       This command can be used to add any options, but  alternative  commands
3295       exist to add preprocessor definitions (target_compile_definitions() and
3296       add_definitions()) or include directories (target_include_directories()
3297       and include_directories()).
3298
3299       Arguments  to  add_compile_options may use “generator expressions” with
3300       the syntax $<...>.  See the cmake-generator-expressions(7)  manual  for
3301       available expressions.  See the cmake-buildsystem(7) manual for more on
3302       defining buildsystem properties.
3303
3304   add_custom_command
3305       Add a custom build rule to the generated build system.
3306
3307       There are two main signatures for add_custom_command.
3308
3309   Generating Files
3310       The first signature is for adding a custom command to produce  an  out‐
3311       put:
3312
3313          add_custom_command(OUTPUT output1 [output2 ...]
3314                             COMMAND command1 [ARGS] [args1...]
3315                             [COMMAND command2 [ARGS] [args2...] ...]
3316                             [MAIN_DEPENDENCY depend]
3317                             [DEPENDS [depends...]]
3318                             [BYPRODUCTS [files...]]
3319                             [IMPLICIT_DEPENDS <lang1> depend1
3320                                              [<lang2> depend2] ...]
3321                             [WORKING_DIRECTORY dir]
3322                             [COMMENT comment]
3323                             [DEPFILE depfile]
3324                             [VERBATIM] [APPEND] [USES_TERMINAL]
3325                             [COMMAND_EXPAND_LISTS])
3326
3327       This  defines a command to generate specified OUTPUT file(s).  A target
3328       created in the same directory (CMakeLists.txt file) that specifies  any
3329       output of the custom command as a source file is given a rule to gener‐
3330       ate the file using the command at build time.  Do not list  the  output
3331       in  more  than one independent target that may build in parallel or the
3332       two instances of the rule may conflict (instead use the add_custom_tar‐
3333       get() command to drive the command and make the other targets depend on
3334       that one).  In makefile terms this creates a new target in the  follow‐
3335       ing form:
3336
3337          OUTPUT: MAIN_DEPENDENCY DEPENDS
3338                  COMMAND
3339
3340       The options are:
3341
3342       APPEND Append  the COMMAND and DEPENDS option values to the custom com‐
3343              mand for the first output specified.  There  must  have  already
3344              been  a previous call to this command with the same output.  The
3345              COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are cur‐
3346              rently  ignored  when  APPEND  is  given, but may be used in the
3347              future.
3348
3349       BYPRODUCTS
3350              Specify the files the command is expected to produce  but  whose
3351              modification time may or may not be newer than the dependencies.
3352              If a byproduct name is a relative path it  will  be  interpreted
3353              relative  to  the build tree directory corresponding to the cur‐
3354              rent source directory.  Each byproduct file will be marked  with
3355              the GENERATED source file property automatically.
3356
3357              Explicit  specification  of byproducts is supported by the Ninja
3358              generator to tell the ninja build tool how to regenerate byprod‐
3359              ucts  when they are missing.  It is also useful when other build
3360              rules (e.g. custom commands) depend on  the  byproducts.   Ninja
3361              requires  a  build  rule for any generated file on which another
3362              rule depends even if there are order-only dependencies to ensure
3363              the byproducts will be available before their dependents build.
3364
3365              The  BYPRODUCTS option is ignored on non-Ninja generators except
3366              to mark byproducts GENERATED.
3367
3368       COMMAND
3369              Specify the command-line(s) to execute at build time.   If  more
3370              than  one  COMMAND  is specified they will be executed in order,
3371              but not necessarily composed into  a  stateful  shell  or  batch
3372              script.  (To run a full script, use the configure_file() command
3373              or the file(GENERATE) command to create it, and then  specify  a
3374              COMMAND  to launch it.)  The optional ARGS argument is for back‐
3375              ward compatibility and will be ignored.
3376
3377              If COMMAND specifies an executable target name (created  by  the
3378              add_executable()  command)  it will automatically be replaced by
3379              the location of the executable created at build  time.  If  set,
3380              the CROSSCOMPILING_EMULATOR executable target property will also
3381              be prepended to the command to allow the executable  to  run  on
3382              the  host.   (Use the TARGET_FILE generator expression to refer‐
3383              ence an executable later in the command line.)   Additionally  a
3384              target-level  dependency  will  be  added so that the executable
3385              target will be built before any target using  this  custom  com‐
3386              mand.   However  this  does NOT add a file-level dependency that
3387              would cause the custom command to re-run whenever the executable
3388              is recompiled.
3389
3390              Arguments  to COMMAND may use generator expressions.  References
3391              to target names  in  generator  expressions  imply  target-level
3392              dependencies,  but  NOT  file-level  dependencies.   List target
3393              names with the DEPENDS option to add file-level dependencies.
3394
3395       COMMENT
3396              Display the given message before the commands  are  executed  at
3397              build time.
3398
3399       DEPENDS
3400              Specify  files  on which the command depends.  If any dependency
3401              is an OUTPUT of another custom command  in  the  same  directory
3402              (CMakeLists.txt  file) CMake automatically brings the other cus‐
3403              tom command into the target in which this command is built.   If
3404              DEPENDS  is not specified the command will run whenever the OUT‐
3405              PUT is missing; if the command does not actually create the OUT‐
3406              PUT  then  the  rule  will always run.  If DEPENDS specifies any
3407              target (created by the add_custom_target(), add_executable(), or
3408              add_library()  command)  a target-level dependency is created to
3409              make sure the target is built before any target using this  cus‐
3410              tom  command.   Additionally,  if the target is an executable or
3411              library a file-level dependency is created to cause  the  custom
3412              command to re-run whenever the target is recompiled.
3413
3414              Arguments to DEPENDS may use generator expressions.
3415
3416       COMMAND_EXPAND_LISTS
3417              Lists  in  COMMAND  arguments  will be expanded, including those
3418              created with generator expressions, allowing  COMMAND  arguments
3419              such  as  ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
3420              RIES>,;-I>" foo.cc to be properly expanded.
3421
3422       IMPLICIT_DEPENDS
3423              Request scanning of implicit dependencies of an input file.  The
3424              language  given  specifies the programming language whose corre‐
3425              sponding dependency scanner should be used.   Currently  only  C
3426              and CXX language scanners are supported.  The language has to be
3427              specified for every file in the IMPLICIT_DEPENDS  list.   Depen‐
3428              dencies  discovered  from the scanning are added to those of the
3429              custom command at build time.  Note  that  the  IMPLICIT_DEPENDS
3430              option  is  currently supported only for Makefile generators and
3431              will be ignored by other generators.
3432
3433       MAIN_DEPENDENCY
3434              Specify the primary input source file to the command.   This  is
3435              treated just like any value given to the DEPENDS option but also
3436              suggests to Visual Studio generators where to  hang  the  custom
3437              command.  Each source file may have at most one command specify‐
3438              ing it as its main dependency. A compile  command  (i.e.  for  a
3439              library  or an executable) counts as an implicit main dependency
3440              which gets silently overwritten by a custom  command  specifica‐
3441              tion.
3442
3443       OUTPUT Specify the output files the command is expected to produce.  If
3444              an output name is a relative path it will be  interpreted  rela‐
3445              tive  to  the  build tree directory corresponding to the current
3446              source directory.  Each output file will be marked with the GEN‐
3447              ERATED source file property automatically.  If the output of the
3448              custom command is not actually created as  a  file  on  disk  it
3449              should be marked with the SYMBOLIC source file property.
3450
3451       USES_TERMINAL
3452              The  command will be given direct access to the terminal if pos‐
3453              sible.  With the Ninja generator, this places the command in the
3454              console pool.
3455
3456       VERBATIM
3457              All  arguments  to the commands will be escaped properly for the
3458              build tool so that the invoked command  receives  each  argument
3459              unchanged.   Note that one level of escapes is still used by the
3460              CMake language processor before add_custom_command even sees the
3461              arguments.  Use of VERBATIM is recommended as it enables correct
3462              behavior.  When VERBATIM is not given the behavior  is  platform
3463              specific because there is no protection of tool-specific special
3464              characters.
3465
3466       WORKING_DIRECTORY
3467              Execute the command with the given  current  working  directory.
3468              If  it is a relative path it will be interpreted relative to the
3469              build tree directory corresponding to the current source  direc‐
3470              tory.
3471
3472       DEPFILE
3473              Specify  a  .d depfile for the Ninja generator.  A .d file holds
3474              dependencies usually  emitted  by  the  custom  command  itself.
3475              Using DEPFILE with other generators than Ninja is an error.
3476
3477   Build Events
3478       The  second  signature  adds  a  custom  command  to a target such as a
3479       library or executable.  This is  useful  for  performing  an  operation
3480       before  or  after building the target.  The command becomes part of the
3481       target and will only execute when the target itself is built.   If  the
3482       target is already built, the command will not execute.
3483
3484          add_custom_command(TARGET <target>
3485                             PRE_BUILD | PRE_LINK | POST_BUILD
3486                             COMMAND command1 [ARGS] [args1...]
3487                             [COMMAND command2 [ARGS] [args2...] ...]
3488                             [BYPRODUCTS [files...]]
3489                             [WORKING_DIRECTORY dir]
3490                             [COMMENT comment]
3491                             [VERBATIM] [USES_TERMINAL])
3492
3493       This  defines  a  new command that will be associated with building the
3494       specified <target>.  The <target> must be defined in the current direc‐
3495       tory; targets defined in other directories may not be specified.
3496
3497       When the command will happen is determined by which of the following is
3498       specified:
3499
3500       PRE_BUILD
3501              Run before any other rules are executed within the target.  This
3502              is  supported  only  on Visual Studio 8 or later.  For all other
3503              generators PRE_BUILD will be treated as PRE_LINK.
3504
3505       PRE_LINK
3506              Run after sources have been  compiled  but  before  linking  the
3507              binary  or  running  the  librarian or archiver tool of a static
3508              library.  This  is  not  defined  for  targets  created  by  the
3509              add_custom_target() command.
3510
3511       POST_BUILD
3512              Run after all other rules within the target have been executed.
3513
3514       NOTE:
3515          Because  generator expressions can be used in custom commands, it is
3516          possible to define COMMAND lines  or  whole  custom  commands  which
3517          evaluate  to  empty  strings for certain configurations.  For Visual
3518          Studio 2010 (and newer) generators these  command  lines  or  custom
3519          commands  will  be  omitted  for  the  specific configuration and no
3520          “empty-string-command” will be added.
3521
3522          This allows to add individual build events for every configuration.
3523
3524   add_custom_target
3525       Add a target with no output so it will always be built.
3526
3527          add_custom_target(Name [ALL] [command1 [args1...]]
3528                            [COMMAND command2 [args2...] ...]
3529                            [DEPENDS depend depend depend ... ]
3530                            [BYPRODUCTS [files...]]
3531                            [WORKING_DIRECTORY dir]
3532                            [COMMENT comment]
3533                            [VERBATIM] [USES_TERMINAL]
3534                            [COMMAND_EXPAND_LISTS]
3535                            [SOURCES src1 [src2...]])
3536
3537       Adds a target with the given name that  executes  the  given  commands.
3538       The target has no output file and is always considered out of date even
3539       if the commands try to create a file with the name of the target.   Use
3540       the  add_custom_command() command to generate a file with dependencies.
3541       By default nothing depends on the custom target.  Use the add_dependen‐
3542       cies() command to add dependencies to or from other targets.
3543
3544       The options are:
3545
3546       ALL    Indicate  that  this target should be added to the default build
3547              target so that it will be run every time (the command cannot  be
3548              called ALL).
3549
3550       BYPRODUCTS
3551              Specify  the  files the command is expected to produce but whose
3552              modification time may  or  may  not  be  updated  on  subsequent
3553              builds.   If  a  byproduct  name  is  a relative path it will be
3554              interpreted relative to the build tree  directory  corresponding
3555              to  the  current  source directory.  Each byproduct file will be
3556              marked with the GENERATED source file property automatically.
3557
3558              Explicit specification of byproducts is supported by  the  Ninja
3559              generator to tell the ninja build tool how to regenerate byprod‐
3560              ucts when they are missing.  It is also useful when other  build
3561              rules  (e.g.  custom  commands) depend on the byproducts.  Ninja
3562              requires a build rule for any generated file  on  which  another
3563              rule depends even if there are order-only dependencies to ensure
3564              the byproducts will be available before their dependents build.
3565
3566              The BYPRODUCTS option is ignored on non-Ninja generators  except
3567              to mark byproducts GENERATED.
3568
3569       COMMAND
3570              Specify  the  command-line(s) to execute at build time.  If more
3571              than one COMMAND is specified they will be  executed  in  order,
3572              but  not  necessarily  composed  into  a stateful shell or batch
3573              script.  (To run a full script, use the configure_file() command
3574              or  the  file(GENERATE) command to create it, and then specify a
3575              COMMAND to launch it.)
3576
3577              If COMMAND specifies an executable target name (created  by  the
3578              add_executable()  command)  it will automatically be replaced by
3579              the location of the executable created at build  time.  If  set,
3580              the CROSSCOMPILING_EMULATOR executable target property will also
3581              be prepended to the command to allow the executable  to  run  on
3582              the  host.  Additionally a target-level dependency will be added
3583              so that the executable target will be built before  this  custom
3584              target.
3585
3586              Arguments  to COMMAND may use generator expressions.  References
3587              to target names  in  generator  expressions  imply  target-level
3588              dependencies.
3589
3590              The  command  and arguments are optional and if not specified an
3591              empty target will be created.
3592
3593       COMMENT
3594              Display the given message before the commands  are  executed  at
3595              build time.
3596
3597       DEPENDS
3598              Reference  files  and  outputs  of  custom commands created with
3599              add_custom_command() command calls in the same directory (CMake‐
3600              Lists.txt  file).  They will be brought up to date when the tar‐
3601              get is built.
3602
3603              Use the add_dependencies() command to add dependencies on  other
3604              targets.
3605
3606       COMMAND_EXPAND_LISTS
3607              Lists  in  COMMAND  arguments  will be expanded, including those
3608              created with generator expressions, allowing  COMMAND  arguments
3609              such  as  ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
3610              RIES>,;-I>" foo.cc to be properly expanded.
3611
3612       SOURCES
3613              Specify additional source files to be  included  in  the  custom
3614              target.   Specified  source  files  will be added to IDE project
3615              files for convenience in editing even  if  they  have  no  build
3616              rules.
3617
3618       VERBATIM
3619              All  arguments  to the commands will be escaped properly for the
3620              build tool so that the invoked command  receives  each  argument
3621              unchanged.   Note that one level of escapes is still used by the
3622              CMake language processor before add_custom_target even sees  the
3623              arguments.  Use of VERBATIM is recommended as it enables correct
3624              behavior.  When VERBATIM is not given the behavior  is  platform
3625              specific because there is no protection of tool-specific special
3626              characters.
3627
3628       USES_TERMINAL
3629              The command will be given direct access to the terminal if  pos‐
3630              sible.  With the Ninja generator, this places the command in the
3631              console pool.
3632
3633       WORKING_DIRECTORY
3634              Execute the command with the given  current  working  directory.
3635              If  it is a relative path it will be interpreted relative to the
3636              build tree directory corresponding to the current source  direc‐
3637              tory.
3638
3639   add_definitions
3640       Adds -D define flags to the compilation of source files.
3641
3642          add_definitions(-DFOO -DBAR ...)
3643
3644       Adds  definitions  to the compiler command line for targets in the cur‐
3645       rent directory and below (whether added before or after this command is
3646       invoked).   This  command  can  be  used  to  add  any flags, but it is
3647       intended to add preprocessor definitions (see the add_compile_options()
3648       command  to  add  other  flags).  Flags beginning in -D or /D that look
3649       like preprocessor definitions  are  automatically  added  to  the  COM‐
3650       PILE_DEFINITIONS directory property for the current directory.  Defini‐
3651       tions with non-trivial values may be left in the set of  flags  instead
3652       of  being  converted for reasons of backwards compatibility.  See docu‐
3653       mentation of the directory,  target,  source  file  COMPILE_DEFINITIONS
3654       properties  for  details on adding preprocessor definitions to specific
3655       scopes and configurations.
3656
3657       See the cmake-buildsystem(7) manual for more  on  defining  buildsystem
3658       properties.
3659
3660   add_dependencies
3661       Add a dependency between top-level targets.
3662
3663          add_dependencies(<target> [<target-dependency>]...)
3664
3665       Make  a  top-level <target> depend on other top-level targets to ensure
3666       that they build before <target> does.  A top-level target is  one  cre‐
3667       ated  by one of the add_executable(), add_library(), or add_custom_tar‐
3668       get() commands (but not targets generated by CMake like install).
3669
3670       Dependencies added to an imported target or an  interface  library  are
3671       followed  transitively  in  its  place since the target itself does not
3672       build.
3673
3674       See the DEPENDS option of add_custom_target() and  add_custom_command()
3675       commands  for  adding file-level dependencies in custom rules.  See the
3676       OBJECT_DEPENDS source file property to add file-level  dependencies  to
3677       object files.
3678
3679   add_executable
3680       Add an executable to the project using the specified source files.
3681
3682          add_executable(<name> [WIN32] [MACOSX_BUNDLE]
3683                         [EXCLUDE_FROM_ALL]
3684                         [source1] [source2 ...])
3685
3686       Adds  an  executable  target  called <name> to be built from the source
3687       files listed in the command invocation.  (The source files can be omit‐
3688       ted  here  if they are added later using target_sources().)  The <name>
3689       corresponds to the logical target name  and  must  be  globally  unique
3690       within a project.  The actual file name of the executable built is con‐
3691       structed  based  on  conventions  of  the  native  platform  (such   as
3692       <name>.exe or just <name>).
3693
3694       By default the executable file will be created in the build tree direc‐
3695       tory corresponding to the source tree directory in  which  the  command
3696       was  invoked.  See documentation of the RUNTIME_OUTPUT_DIRECTORY target
3697       property to change this location.  See documentation of the OUTPUT_NAME
3698       target property to change the <name> part of the final file name.
3699
3700       If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
3701       get created.  See documentation of that target property for details.
3702
3703       If MACOSX_BUNDLE is given the corresponding property will be set on the
3704       created target.  See documentation of the MACOSX_BUNDLE target property
3705       for details.
3706
3707       If EXCLUDE_FROM_ALL is given the corresponding property will be set  on
3708       the  created  target.  See documentation of the EXCLUDE_FROM_ALL target
3709       property for details.
3710
3711       Source arguments to add_executable may use “generator expressions” with
3712       the  syntax  $<...>.  See the cmake-generator-expressions(7) manual for
3713       available expressions.  See the cmake-buildsystem(7) manual for more on
3714       defining buildsystem properties.
3715
3716       See  also  HEADER_FILE_ONLY  on what to do if some sources are pre-pro‐
3717       cessed, and you want to have the original sources reachable from within
3718       IDE.
3719
3720
3721                                        ----
3722
3723
3724
3725          add_executable(<name> IMPORTED [GLOBAL])
3726
3727       An  IMPORTED  executable  target  references an executable file located
3728       outside the project.  No rules are  generated  to  build  it,  and  the
3729       IMPORTED  target  property  is  True.  The target name has scope in the
3730       directory in which it is created  and  below,  but  the  GLOBAL  option
3731       extends  visibility.  It may be referenced like any target built within
3732       the project.  IMPORTED executables are useful for convenient  reference
3733       from  commands  like  add_custom_command().  Details about the imported
3734       executable are specified by setting properties  whose  names  begin  in
3735       IMPORTED_.   The most important such property is IMPORTED_LOCATION (and
3736       its per-configuration version IMPORTED_LOCATION_<CONFIG>) which  speci‐
3737       fies  the location of the main executable file on disk.  See documenta‐
3738       tion of the IMPORTED_* properties for more information.
3739
3740
3741                                        ----
3742
3743
3744
3745          add_executable(<name> ALIAS <target>)
3746
3747       Creates an Alias Target, such that <name> can be used to refer to <tar‐
3748       get>  in subsequent commands.  The <name> does not appear in the gener‐
3749       ated buildsystem  as  a  make  target.   The  <target>  may  not  be  a
3750       non-GLOBAL  Imported  Target or an ALIAS.  ALIAS targets can be used as
3751       targets to read properties from, executables for  custom  commands  and
3752       custom targets.  They can also be tested for existence with the regular
3753       if(TARGET) subcommand.  The <name> may not be used to modify properties
3754       of  <target>,  that  is, it may not be used as the operand of set_prop‐
3755       erty(), set_target_properties(), target_link_libraries() etc.  An ALIAS
3756       target may not be installed or exported.
3757
3758   add_library
3759       Add a library to the project using the specified source files.
3760
3761   Normal Libraries
3762          add_library(<name> [STATIC | SHARED | MODULE]
3763                      [EXCLUDE_FROM_ALL]
3764                      [source1] [source2 ...])
3765
3766       Adds  a  library target called <name> to be built from the source files
3767       listed in the command invocation.  (The source  files  can  be  omitted
3768       here  if they are added later using target_sources().)  The <name> cor‐
3769       responds to the logical target name and must be globally unique  within
3770       a  project.   The  actual file name of the library built is constructed
3771       based on conventions of the native platform  (such  as  lib<name>.a  or
3772       <name>.lib).
3773
3774       STATIC,  SHARED,  or MODULE may be given to specify the type of library
3775       to be created.  STATIC libraries are archives of object files  for  use
3776       when  linking  other  targets.  SHARED libraries are linked dynamically
3777       and loaded at runtime.  MODULE  libraries  are  plugins  that  are  not
3778       linked  into  other  targets  but  may be loaded dynamically at runtime
3779       using dlopen-like functionality.  If no type is  given  explicitly  the
3780       type  is  STATIC  or  SHARED  based on whether the current value of the
3781       variable BUILD_SHARED_LIBS is ON.  For SHARED and MODULE libraries  the
3782       POSITION_INDEPENDENT_CODE  target  property is set to ON automatically.
3783       A SHARED or STATIC library may be  marked  with  the  FRAMEWORK  target
3784       property to create an OS X Framework.
3785
3786       If  a library does not export any symbols, it must not be declared as a
3787       SHARED library.  For example, a  Windows  resource  DLL  or  a  managed
3788       C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
3789       library.  This is because CMake expects a SHARED library to always have
3790       an associated import library on Windows.
3791
3792       By default the library file will be created in the build tree directory
3793       corresponding to the source tree directory in  which  the  command  was
3794       invoked.     See   documentation   of   the   ARCHIVE_OUTPUT_DIRECTORY,
3795       LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY  target  proper‐
3796       ties  to  change  this  location.  See documentation of the OUTPUT_NAME
3797       target property to change the <name> part of the final file name.
3798
3799       If EXCLUDE_FROM_ALL is given the corresponding property will be set  on
3800       the  created  target.  See documentation of the EXCLUDE_FROM_ALL target
3801       property for details.
3802
3803       Source arguments to add_library may use  “generator  expressions”  with
3804       the  syntax  $<...>.  See the cmake-generator-expressions(7) manual for
3805       available expressions.  See the cmake-buildsystem(7) manual for more on
3806       defining buildsystem properties.
3807
3808       See  also  HEADER_FILE_ONLY  on what to do if some sources are pre-pro‐
3809       cessed, and you want to have the original sources reachable from within
3810       IDE.
3811
3812   Imported Libraries
3813          add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
3814                      [GLOBAL])
3815
3816       An  IMPORTED  library  target references a library file located outside
3817       the project.  No rules are generated to build it, and the IMPORTED tar‐
3818       get  property  is  True.  The target name has scope in the directory in
3819       which it is created and below, but the GLOBAL option  extends  visibil‐
3820       ity.   It  may  be referenced like any target built within the project.
3821       IMPORTED libraries are useful for convenient  reference  from  commands
3822       like  target_link_libraries().   Details about the imported library are
3823       specified by setting properties whose  names  begin  in  IMPORTED_  and
3824       INTERFACE_.  The most important such property is IMPORTED_LOCATION (and
3825       its per-configuration variant IMPORTED_LOCATION_<CONFIG>) which  speci‐
3826       fies  the location of the main library file on disk.  See documentation
3827       of the IMPORTED_* and INTERFACE_* properties for more information.
3828
3829   Object Libraries
3830          add_library(<name> OBJECT <src>...)
3831
3832       Creates an Object Library.  An object library compiles source files but
3833       does  not  archive  or link their object files into a library.  Instead
3834       other targets created by add_library() or add_executable()  may  refer‐
3835       ence   the   objects   using   an   expression   of   the  form  $<TAR‐
3836       GET_OBJECTS:objlib> as a source, where objlib  is  the  object  library
3837       name.  For example:
3838
3839          add_library(... $<TARGET_OBJECTS:objlib> ...)
3840          add_executable(... $<TARGET_OBJECTS:objlib> ...)
3841
3842       will include objlib’s object files in a library and an executable along
3843       with those compiled from their own sources.  Object libraries may  con‐
3844       tain  only  sources  that  compile,  header files, and other files that
3845       would not affect linking of a normal library  (e.g.  .txt).   They  may
3846       contain  custom  commands  generating  such sources, but not PRE_BUILD,
3847       PRE_LINK, or POST_BUILD commands.  Object libraries cannot  be  linked.
3848       Some  native  build  systems  (such as Xcode) may not like targets that
3849       have only object files, so consider adding at  least  one  real  source
3850       file to any target that references $<TARGET_OBJECTS:objlib>.
3851
3852   Alias Libraries
3853          add_library(<name> ALIAS <target>)
3854
3855       Creates an Alias Target, such that <name> can be used to refer to <tar‐
3856       get> in subsequent commands.  The <name> does not appear in the  gener‐
3857       ated  buildsystem  as  a  make  target.   The  <target>  may  not  be a
3858       non-GLOBAL Imported Target or an ALIAS.  ALIAS targets can be  used  as
3859       linkable targets and as targets to read properties from.  They can also
3860       be tested for existence with the regular  if(TARGET)  subcommand.   The
3861       <name>  may  not  be used to modify properties of <target>, that is, it
3862       may not be used as the operand  of  set_property(),  set_target_proper‐
3863       ties(),  target_link_libraries()  etc.   An  ALIAS  target  may  not be
3864       installed or exported.
3865
3866   Interface Libraries
3867          add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
3868
3869       Creates an Interface Library.  An INTERFACE  library  target  does  not
3870       directly  create  build output, though it may have properties set on it
3871       and it may be installed, exported and imported.  Typically  the  INTER‐
3872       FACE_*  properties are populated on the interface target using the com‐
3873       mands:
3874
3875       · set_property(),
3876
3877       · target_link_libraries(INTERFACE),
3878
3879       · target_include_directories(INTERFACE),
3880
3881       · target_compile_options(INTERFACE),
3882
3883       · target_compile_definitions(INTERFACE), and
3884
3885       · target_sources(INTERFACE),
3886
3887       and then it is used as an argument to target_link_libraries() like  any
3888       other target.
3889
3890       An  INTERFACE  Imported Target may also be created with this signature.
3891       An IMPORTED library target references a  library  defined  outside  the
3892       project.   The  target  name  has scope in the directory in which it is
3893       created and below, but the GLOBAL option extends visibility.  It may be
3894       referenced   like  any  target  built  within  the  project.   IMPORTED
3895       libraries are useful for convenient reference from commands  like  tar‐
3896       get_link_libraries().
3897
3898   add_subdirectory
3899       Add a subdirectory to the build.
3900
3901          add_subdirectory(source_dir [binary_dir]
3902                           [EXCLUDE_FROM_ALL])
3903
3904       Add  a  subdirectory to the build.  The source_dir specifies the direc‐
3905       tory in which the source CMakeLists.txt and code files are located.  If
3906       it  is a relative path it will be evaluated with respect to the current
3907       directory (the typical usage), but it may also  be  an  absolute  path.
3908       The  binary_dir  specifies  the  directory in which to place the output
3909       files.  If it is a relative path it will be evaluated with  respect  to
3910       the  current output directory, but it may also be an absolute path.  If
3911       binary_dir is not specified, the value of source_dir, before  expanding
3912       any  relative  path,  will  be  used  (the  typical usage).  The CMake‐
3913       Lists.txt file in the specified  source  directory  will  be  processed
3914       immediately  by  CMake before processing in the current input file con‐
3915       tinues beyond this command.
3916
3917       If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
3918       rectory  will not be included in the ALL target of the parent directory
3919       by default, and will be excluded from IDE project  files.   Users  must
3920       explicitly  build  targets  in the subdirectory.  This is meant for use
3921       when the subdirectory contains a separate part of the project  that  is
3922       useful  but  not  necessary,  such as a set of examples.  Typically the
3923       subdirectory should contain its own  project()  command  invocation  so
3924       that a full build system will be generated in the subdirectory (such as
3925       a VS IDE solution file).  Note that inter-target dependencies supersede
3926       this  exclusion.   If a target built by the parent project depends on a
3927       target in the subdirectory, the dependee target will be included in the
3928       parent project build system to satisfy the dependency.
3929
3930   add_test
3931       Add a test to the project to be run by ctest(1).
3932
3933          add_test(NAME <name> COMMAND <command> [<arg>...]
3934                   [CONFIGURATIONS <config>...]
3935                   [WORKING_DIRECTORY <dir>])
3936
3937       Add  a  test  called  <name>.   The  test  name may not contain spaces,
3938       quotes, or other characters special in CMake syntax.  The options are:
3939
3940       COMMAND
3941              Specify the test command-line.  If <command> specifies  an  exe‐
3942              cutable  target  (created by add_executable()) it will automati‐
3943              cally be replaced by the location of the executable  created  at
3944              build time.
3945
3946       CONFIGURATIONS
3947              Restrict execution of the test only to the named configurations.
3948
3949       WORKING_DIRECTORY
3950              Set  the  WORKING_DIRECTORY test property to specify the working
3951              directory in which to execute the test.  If  not  specified  the
3952              test  will  be run with the current working directory set to the
3953              build directory corresponding to the current source directory.
3954
3955       The given test command is expected to exit with  code  0  to  pass  and
3956       non-zero  to fail, or vice-versa if the WILL_FAIL test property is set.
3957       Any output written to stdout or stderr will be captured by ctest(1) but
3958       does not affect the pass/fail status unless the PASS_REGULAR_EXPRESSION
3959       or FAIL_REGULAR_EXPRESSION test property is used.
3960
3961       The COMMAND and WORKING_DIRECTORY options may  use  “generator  expres‐
3962       sions”  with the syntax $<...>.  See the cmake-generator-expressions(7)
3963       manual for available expressions.
3964
3965       Example usage:
3966
3967          add_test(NAME mytest
3968                   COMMAND testDriver --config $<CONFIGURATION>
3969                                      --exe $<TARGET_FILE:myexe>)
3970
3971       This creates a test mytest whose command runs a testDriver tool passing
3972       the  configuration  name  and the full path to the executable file pro‐
3973       duced by target myexe.
3974
3975       NOTE:
3976          CMake will generate tests only if the enable_testing()  command  has
3977          been  invoked.   The  CTest module invokes the command automatically
3978          when the BUILD_TESTING option is ON.
3979
3980
3981                                        ----
3982
3983
3984
3985          add_test(<name> <command> [<arg>...])
3986
3987       Add a test called <name> with the given command-line.  Unlike the above
3988       NAME  signature  no  transformation is performed on the command-line to
3989       support target names or generator expressions.
3990
3991   aux_source_directory
3992       Find all source files in a directory.
3993
3994          aux_source_directory(<dir> <variable>)
3995
3996       Collects the names of all the source files in the  specified  directory
3997       and  stores  the  list  in  the  <variable>  provided.  This command is
3998       intended to be used by projects that use explicit  template  instantia‐
3999       tion.  Template instantiation files can be stored in a “Templates” sub‐
4000       directory and collected automatically using this command to avoid manu‐
4001       ally listing all instantiations.
4002
4003       It  is tempting to use this command to avoid writing the list of source
4004       files for a library or executable target.  While this  seems  to  work,
4005       there  is no way for CMake to generate a build system that knows when a
4006       new source file has been added.  Normally the  generated  build  system
4007       knows  when  it needs to rerun CMake because the CMakeLists.txt file is
4008       modified to add a new source.  When the source is  just  added  to  the
4009       directory without modifying this file, one would have to manually rerun
4010       CMake to generate a build system incorporating the new file.
4011
4012   build_command
4013       Get a command line to  build  the  current  project.   This  is  mainly
4014       intended for internal use by the CTest module.
4015
4016          build_command(<variable>
4017                        [CONFIGURATION <config>]
4018                        [TARGET <target>]
4019                        [PROJECT_NAME <projname>] # legacy, causes warning
4020                       )
4021
4022       Sets the given <variable> to a command-line string of the form:
4023
4024          <cmake> --build . [--config <config>] [--target <target>] [-- -i]
4025
4026       where  <cmake>  is  the location of the cmake(1) command-line tool, and
4027       <config> and <target> are the values provided to the CONFIGURATION  and
4028       TARGET  options,  if any.  The trailing -- -i option is added for Make‐
4029       file Generators if policy CMP0061 is not set to NEW.
4030
4031       When invoked, this cmake --build command line will launch the  underly‐
4032       ing build system tool.
4033
4034          build_command(<cachevariable> <makecommand>)
4035
4036       This  second signature is deprecated, but still available for backwards
4037       compatibility.  Use the first signature instead.
4038
4039       It sets the given <cachevariable> to a command-line string as above but
4040       without  the  --target option.  The <makecommand> is ignored but should
4041       be the full path to devenv, nmake, make or one of the  end  user  build
4042       tools for legacy invocations.
4043
4044       NOTE:
4045          In  CMake versions prior to 3.0 this command returned a command line
4046          that directly invokes the native build tool for the current  genera‐
4047          tor.   Their implementation of the PROJECT_NAME option had no useful
4048          effects, so CMake now warns on use of the option.
4049
4050   create_test_sourcelist
4051       Create a test driver and source list for building test programs.
4052
4053          create_test_sourcelist(sourceListName driverName
4054                                 test1 test2 test3
4055                                 EXTRA_INCLUDE include.h
4056                                 FUNCTION function)
4057
4058       A test driver is a program that links together many small tests into  a
4059       single  executable.   This  is  useful when building static executables
4060       with large libraries to shrink the total required size.   The  list  of
4061       source files needed to build the test driver will be in sourceListName.
4062       driverName is the name of the test driver program.   The  rest  of  the
4063       arguments consist of a list of test source files, can be semicolon sep‐
4064       arated.  Each test source file should have a function in it that is the
4065       same  name  as  the  file  with  no  extension (foo.cxx should have int
4066       foo(int, char*[]);) driverName will be able to call each of  the  tests
4067       by  name  on the command line.  If EXTRA_INCLUDE is specified, then the
4068       next argument is included into the  generated  file.   If  FUNCTION  is
4069       specified,  then  the next argument is taken as a function name that is
4070       passed a pointer to ac and av.  This can be used to add  extra  command
4071       line  processing  to  each  test.  The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
4072       cmake variable can be set to have code that  will  be  placed  directly
4073       before calling the test main function.  CMAKE_TESTDRIVER_AFTER_TESTMAIN
4074       can be set to have code that will be placed directly after the call  to
4075       the test main function.
4076
4077   define_property
4078       Define and document custom properties.
4079
4080          define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
4081                           TEST | VARIABLE | CACHED_VARIABLE>
4082                           PROPERTY <name> [INHERITED]
4083                           BRIEF_DOCS <brief-doc> [docs...]
4084                           FULL_DOCS <full-doc> [docs...])
4085
4086       Define  one  property  in  a  scope for use with the set_property() and
4087       get_property() commands.  This is primarily useful to  associate  docu‐
4088       mentation  with property names that may be retrieved with the get_prop‐
4089       erty() command. The first argument determines  the  kind  of  scope  in
4090       which the property should be used.  It must be one of the following:
4091
4092          GLOBAL    = associated with the global namespace
4093          DIRECTORY = associated with one directory
4094          TARGET    = associated with one target
4095          SOURCE    = associated with one source file
4096          TEST      = associated with a test named with add_test
4097          VARIABLE  = documents a CMake language variable
4098          CACHED_VARIABLE = documents a CMake cache variable
4099
4100       Note  that  unlike  set_property()  and  get_property() no actual scope
4101       needs to be given; only the kind of scope is important.
4102
4103       The required PROPERTY option is immediately followed by the name of the
4104       property being defined.
4105
4106       If  the  INHERITED option then the get_property() command will chain up
4107       to the next higher scope when the requested property is not set in  the
4108       scope  given  to the command. DIRECTORY scope chains to GLOBAL. TARGET,
4109       SOURCE, and TEST chain to DIRECTORY.
4110
4111       The BRIEF_DOCS and FULL_DOCS options are  followed  by  strings  to  be
4112       associated with the property as its brief and full documentation.  Cor‐
4113       responding options to the get_property() command will retrieve the doc‐
4114       umentation.
4115
4116   enable_language
4117       Enable a language (CXX/C/Fortran/etc)
4118
4119          enable_language(<lang> [OPTIONAL] )
4120
4121       This  command enables support for the named language in CMake.  This is
4122       the same as the project command but does not create any  of  the  extra
4123       variables  that  are created by the project command.  Example languages
4124       are CXX, C, CUDA, Fortran, and ASM.
4125
4126       If enabling ASM, enable it last so that CMake can check whether compil‐
4127       ers for other languages like C work for assembly too.
4128
4129       This  command  must  be  called  in file scope, not in a function call.
4130       Furthermore, it must be called in the highest directory common  to  all
4131       targets  using  the  named  language  directly for compiling sources or
4132       indirectly through link dependencies.  It is  simplest  to  enable  all
4133       needed languages in the top-level directory of a project.
4134
4135       The  OPTIONAL  keyword  is  a placeholder for future implementation and
4136       does not currently work. Instead you can use the  CheckLanguage  module
4137       to verify support before enabling.
4138
4139   enable_testing
4140       Enable testing for current directory and below.
4141
4142          enable_testing()
4143
4144       Enables  testing for this directory and below.  See also the add_test()
4145       command.  Note that ctest expects to find a  test  file  in  the  build
4146       directory root.  Therefore, this command should be in the source direc‐
4147       tory root.
4148
4149   export
4150       Export targets from the build tree for use by outside projects.
4151
4152          export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
4153
4154       Create a file <filename> that may be included by  outside  projects  to
4155       import  targets  from the current project’s build tree.  This is useful
4156       during cross-compiling to build utility executables that can run on the
4157       host  platform in one project and then import them into another project
4158       being compiled for the target platform.  If  the  NAMESPACE  option  is
4159       given  the  <namespace>  string  will  be prepended to all target names
4160       written to the file.
4161
4162       Target installations are associated with the export <export-name> using
4163       the EXPORT option of the install(TARGETS) command.
4164
4165       The  file  created  by  this  command is specific to the build tree and
4166       should never be installed.  See the install(EXPORT) command  to  export
4167       targets from an installation tree.
4168
4169       The properties set on the generated IMPORTED targets will have the same
4170       values as the final values of the input TARGETS.
4171
4172          export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
4173                 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
4174
4175       This signature is similar to the  EXPORT  signature,  but  targets  are
4176       listed  explicitly  rather  than  specified  as an export-name.  If the
4177       APPEND option is given the generated code will be appended to the  file
4178       instead  of  overwriting  it.  The EXPORT_LINK_INTERFACE_LIBRARIES key‐
4179       word, if present,  causes  the  contents  of  the  properties  matching
4180       (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?  to  be exported, when
4181       policy CMP0022 is NEW.  If a library target is included in  the  export
4182       but a target to which it links is not included the behavior is unspeci‐
4183       fied.
4184
4185          export(PACKAGE <name>)
4186
4187       Store the current build directory in the CMake  user  package  registry
4188       for  package  <name>.  The find_package command may consider the direc‐
4189       tory while searching for package <name>.  This helps dependent projects
4190       find  and  use  a package from the current project’s build tree without
4191       help from the user.  Note that the entry in the package  registry  that
4192       this  command creates works only in conjunction with a package configu‐
4193       ration file (<name>Config.cmake) that works with  the  build  tree.  In
4194       some  cases,  for  example  for packaging and for system wide installa‐
4195       tions, it is not desirable to write the user package registry.  If  the
4196       CMAKE_EXPORT_NO_PACKAGE_REGISTRY  variable is enabled, the export(PACK‐
4197       AGE) command will do nothing.
4198
4199          export(TARGETS [target1 [target2 [...]]]  [ANDROID_MK <filename>])
4200
4201       This signature exports cmake built targets to  the  android  ndk  build
4202       system by creating an Android.mk file that references the prebuilt tar‐
4203       gets. The Android NDK supports the  use  of  prebuilt  libraries,  both
4204       static  and  shared.   This  allows  cmake  to build the libraries of a
4205       project and make them available to an ndk build  system  complete  with
4206       transitive  dependencies, include flags and defines required to use the
4207       libraries. The signature takes a list of targets and puts them  in  the
4208       Android.mk  file  specified by the <filename> given. This signature can
4209       only be used if policy CMP0022 is NEW for all targets  given.  A  error
4210       will be issued if that policy is set to OLD for one of the targets.
4211
4212   fltk_wrap_ui
4213       Create FLTK user interfaces Wrappers.
4214
4215          fltk_wrap_ui(resultingLibraryName source1
4216                       source2 ... sourceN )
4217
4218       Produce  .h  and .cxx files for all the .fl and .fld files listed.  The
4219       resulting .h and .cxx files will be added to a variable  named  result‐
4220       ingLibraryName_FLTK_UI_SRCS which should be added to your library.
4221
4222   get_source_file_property
4223       Get a property for a source file.
4224
4225          get_source_file_property(VAR file property)
4226
4227       Get a property from a source file.  The value of the property is stored
4228       in the variable VAR.  If the property is not found, VAR will be set  to
4229       “NOTFOUND”.   Use set_source_files_properties() to set property values.
4230       Source file properties usually control how the file is built. One prop‐
4231       erty that is always there is LOCATION
4232
4233       See also the more general get_property() command.
4234
4235   get_target_property
4236       Get a property from a target.
4237
4238          get_target_property(VAR target property)
4239
4240       Get  a  property from a target.  The value of the property is stored in
4241       the variable VAR.  If the property is not found, VAR  will  be  set  to
4242       “NOTFOUND”.  Use set_target_properties() to set property values.  Prop‐
4243       erties are usually used to control how a  target  is  built,  but  some
4244       query the target instead.  This command can get properties for any tar‐
4245       get so far created.  The targets do not  need  to  be  in  the  current
4246       CMakeLists.txt file.
4247
4248       See also the more general get_property() command.
4249
4250   get_test_property
4251       Get a property of the test.
4252
4253          get_test_property(test property VAR)
4254
4255       Get  a  property from the test.  The value of the property is stored in
4256       the variable VAR.  If the test or property is not found,  VAR  will  be
4257       set  to  “NOTFOUND”.   For  a  list of standard properties you can type
4258       cmake --help-property-list.
4259
4260       See also the more general get_property() command.
4261
4262   include_directories
4263       Add include directories to the build.
4264
4265          include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
4266
4267       Add the given directories to those the  compiler  uses  to  search  for
4268       include  files.  Relative paths are interpreted as relative to the cur‐
4269       rent source directory.
4270
4271       The include directories are added to the INCLUDE_DIRECTORIES  directory
4272       property  for  the current CMakeLists file.  They are also added to the
4273       INCLUDE_DIRECTORIES target property for  each  target  in  the  current
4274       CMakeLists  file.   The target property values are the ones used by the
4275       generators.
4276
4277       By default the directories specified are appended onto the current list
4278       of  directories.   This  default  behavior  can  be  changed by setting
4279       CMAKE_INCLUDE_DIRECTORIES_BEFORE to  ON.   By  using  AFTER  or  BEFORE
4280       explicitly,  you  can select between appending and prepending, indepen‐
4281       dent of the default.
4282
4283       If the SYSTEM option is given, the compiler will be told  the  directo‐
4284       ries  are  meant as system include directories on some platforms.  Sig‐
4285       nalling this setting might achieve effects such as the  compiler  skip‐
4286       ping warnings, or these fixed-install system files not being considered
4287       in dependency calculations - see compiler docs.
4288
4289       Arguments to include_directories may use “generator  expressions”  with
4290       the  syntax  “$<…>”.  See the cmake-generator-expressions(7) manual for
4291       available expressions.  See the cmake-buildsystem(7) manual for more on
4292       defining buildsystem properties.
4293
4294   include_external_msproject
4295       Include an external Microsoft project file in a workspace.
4296
4297          include_external_msproject(projectname location
4298                                     [TYPE projectTypeGUID]
4299                                     [GUID projectGUID]
4300                                     [PLATFORM platformName]
4301                                     dep1 dep2 ...)
4302
4303       Includes an external Microsoft project in the generated workspace file.
4304       Currently does nothing on UNIX.  This will create a target named  [pro‐
4305       jectname].   This can be used in the add_dependencies() command to make
4306       things depend on the external project.
4307
4308       TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
4309       ify  the  type of project, id (GUID) of the project and the name of the
4310       target platform.  This is useful for projects  requiring  values  other
4311       than the default (e.g.  WIX projects).
4312
4313       If the imported project has different configuration names than the cur‐
4314       rent project, set the MAP_IMPORTED_CONFIG_<CONFIG> target  property  to
4315       specify the mapping.
4316
4317   include_regular_expression
4318       Set the regular expression used for dependency checking.
4319
4320          include_regular_expression(regex_match [regex_complain])
4321
4322       Set  the  regular  expressions used in dependency checking.  Only files
4323       matching regex_match will be traced as dependencies.  Only files match‐
4324       ing  regex_complain  will  generate  warnings  if  they cannot be found
4325       (standard header paths are not searched).  The defaults are:
4326
4327          regex_match    = "^.*$" (match everything)
4328          regex_complain = "^$" (match empty string only)
4329
4330   install
4331       Specify rules to run at install time.
4332
4333   Introduction
4334       This command generates installation rules for a project.  Rules  speci‐
4335       fied by calls to this command within a source directory are executed in
4336       order  during  installation.   The  order  across  directories  is  not
4337       defined.
4338
4339       There  are  multiple  signatures for this command.  Some of them define
4340       installation options for files and targets.  Options common to multiple
4341       signatures are covered here but they are valid only for signatures that
4342       specify them.  The common options are:
4343
4344       DESTINATION
4345              Specify the directory on disk to which a file will be installed.
4346              If  a  full path (with a leading slash or drive letter) is given
4347              it is used directly.  If a relative path is given it  is  inter‐
4348              preted  relative  to the value of the CMAKE_INSTALL_PREFIX vari‐
4349              able.  The prefix can be relocated at  install  time  using  the
4350              DESTDIR mechanism explained in the CMAKE_INSTALL_PREFIX variable
4351              documentation.
4352
4353       PERMISSIONS
4354              Specify permissions for installed files.  Valid permissions  are
4355              OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
4356              GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,  WORLD_EXECUTE,  SETUID,
4357              and SETGID.  Permissions that do not make sense on certain plat‐
4358              forms are ignored on those platforms.
4359
4360       CONFIGURATIONS
4361              Specify a list of build configurations  for  which  the  install
4362              rule applies (Debug, Release, etc.). Note that the values speci‐
4363              fied for this option only apply to options listed AFTER the CON‐
4364              FIGURATIONS  option.  For example, to set separate install paths
4365              for the Debug and Release configurations, do the following:
4366
4367                 install(TARGETS target
4368                         CONFIGURATIONS Debug
4369                         RUNTIME DESTINATION Debug/bin)
4370                 install(TARGETS target
4371                         CONFIGURATIONS Release
4372                         RUNTIME DESTINATION Release/bin)
4373
4374              Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
4375
4376       COMPONENT
4377              Specify an installation component name with  which  the  install
4378              rule  is associated, such as “runtime” or “development”.  During
4379              component-specific installation only  install  rules  associated
4380              with  the  given component name will be executed.  During a full
4381              installation all components are  installed  unless  marked  with
4382              EXCLUDE_FROM_ALL.  If COMPONENT is not provided a default compo‐
4383              nent “Unspecified” is created.  The default component  name  may
4384              be   controlled  with  the  CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
4385              variable.
4386
4387       EXCLUDE_FROM_ALL
4388              Specify that the file is excluded from a full  installation  and
4389              only installed as part of a component-specific installation
4390
4391       RENAME Specify  a name for an installed file that may be different from
4392              the original file.  Renaming is allowed only when a single  file
4393              is installed by the command.
4394
4395       OPTIONAL
4396              Specify that it is not an error if the file to be installed does
4397              not exist.
4398
4399       Command signatures that install files may print messages during instal‐
4400       lation.   Use  the CMAKE_INSTALL_MESSAGE variable to control which mes‐
4401       sages are printed.
4402
4403   Installing Targets
4404          install(TARGETS targets... [EXPORT <export-name>]
4405                  [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
4406                    PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
4407                   [DESTINATION <dir>]
4408                   [PERMISSIONS permissions...]
4409                   [CONFIGURATIONS [Debug|Release|...]]
4410                   [COMPONENT <component>]
4411                   [OPTIONAL] [EXCLUDE_FROM_ALL]
4412                   [NAMELINK_ONLY|NAMELINK_SKIP]
4413                  ] [...]
4414                  [INCLUDES DESTINATION [<dir> ...]]
4415                  )
4416
4417       The TARGETS form specifies rules for installing targets from a project.
4418       There  are  six  kinds  of target files that may be installed: ARCHIVE,
4419       LIBRARY, RUNTIME,  OBJECTS,  FRAMEWORK,  and  BUNDLE.  Executables  are
4420       treated   as  RUNTIME  targets,  except  that  those  marked  with  the
4421       MACOSX_BUNDLE property are treated as BUNDLE targets on OS  X.   Static
4422       libraries are treated as ARCHIVE targets, except that those marked with
4423       the FRAMEWORK property are treated as FRAMEWORK targets on OS X.   Mod‐
4424       ule libraries are always treated as LIBRARY targets.  For non-DLL plat‐
4425       forms shared libraries are treated  as  LIBRARY  targets,  except  that
4426       those  marked with the FRAMEWORK property are treated as FRAMEWORK tar‐
4427       gets on OS X.  For DLL platforms the DLL part of a  shared  library  is
4428       treated  as  a  RUNTIME  target and the corresponding import library is
4429       treated as an ARCHIVE target.  All Windows-based systems including Cyg‐
4430       win  are  DLL platforms. Object libraries are always treated as OBJECTS
4431       targets.  The ARCHIVE, LIBRARY, RUNTIME, OBJECTS, and  FRAMEWORK  argu‐
4432       ments  change  the  type  of  target to which the subsequent properties
4433       apply. If none is given the installation properties apply to all target
4434       types.   If  only  one  is given then only targets of that type will be
4435       installed (which can be used to install just a DLL or  just  an  import
4436       library).
4437
4438       The  PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause subse‐
4439       quent properties to be applied to installing a FRAMEWORK shared library
4440       target’s  associated  files  on  non-Apple platforms.  Rules defined by
4441       these arguments are ignored on Apple platforms because  the  associated
4442       files are installed into the appropriate locations inside the framework
4443       folder.  See documentation of the  PRIVATE_HEADER,  PUBLIC_HEADER,  and
4444       RESOURCE target properties for details.
4445
4446       Either  NAMELINK_ONLY  or  NAMELINK_SKIP  may be specified as a LIBRARY
4447       option.  On some platforms a versioned shared library  has  a  symbolic
4448       link such as:
4449
4450          lib<name>.so -> lib<name>.so.1
4451
4452       where lib<name>.so.1 is the soname of the library and lib<name>.so is a
4453       “namelink” allowing linkers to find the library  when  given  -l<name>.
4454       The  NAMELINK_ONLY option causes installation of only the namelink when
4455       a library target is installed.  The NAMELINK_SKIP option causes instal‐
4456       lation  of  library files other than the namelink when a library target
4457       is  installed.   When  neither  option  is  given  both  portions   are
4458       installed.   On  platforms where versioned shared libraries do not have
4459       namelinks or when a library is not versioned the  NAMELINK_SKIP  option
4460       installs  the  library  and  the NAMELINK_ONLY option installs nothing.
4461       See the VERSION and SOVERSION target properties for details on creating
4462       versioned shared libraries.
4463
4464       The  INCLUDES DESTINATION specifies a list of directories which will be
4465       added to the INTERFACE_INCLUDE_DIRECTORIES target property of the <tar‐
4466       gets> when exported by the install(EXPORT) command.  If a relative path
4467       is specified, it is treated as relative to the $<INSTALL_PREFIX>.  This
4468       is independent of the rest of the argument groups and does not actually
4469       install anything.
4470
4471       One or more groups of properties may be specified in a single  call  to
4472       the  TARGETS form of this command.  A target may be installed more than
4473       once to different  locations.   Consider  hypothetical  targets  myExe,
4474       mySharedLib, and myStaticLib.  The code:
4475
4476          install(TARGETS myExe mySharedLib myStaticLib
4477                  RUNTIME DESTINATION bin
4478                  LIBRARY DESTINATION lib
4479                  ARCHIVE DESTINATION lib/static)
4480          install(TARGETS mySharedLib DESTINATION /some/full/path)
4481
4482       will   install   myExe   to   <prefix>/bin  and  myStaticLib  to  <pre‐
4483       fix>/lib/static.  On non-DLL platforms mySharedLib will be installed to
4484       <prefix>/lib and /some/full/path.  On DLL platforms the mySharedLib DLL
4485       will be installed to <prefix>/bin and /some/full/path  and  its  import
4486       library will be installed to <prefix>/lib/static and /some/full/path.
4487
4488       The  EXPORT option associates the installed target files with an export
4489       called <export-name>.  It must appear before any RUNTIME, LIBRARY,  AR‐
4490       CHIVE, or OBJECTS options.  To actually install the export file itself,
4491       call install(EXPORT), documented below.
4492
4493       Installing a target with the EXCLUDE_FROM_ALL target  property  set  to
4494       TRUE has undefined behavior.
4495
4496       The install destination given to the target install DESTINATION may use
4497       “generator expressions” with the syntax $<...>.  See the  cmake-genera‐
4498       tor-expressions(7) manual for available expressions.
4499
4500   Installing Files
4501          install(<FILES|PROGRAMS> files... DESTINATION <dir>
4502                  [PERMISSIONS permissions...]
4503                  [CONFIGURATIONS [Debug|Release|...]]
4504                  [COMPONENT <component>]
4505                  [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
4506
4507       The  FILES  form  specifies  rules  for installing files for a project.
4508       File names given as relative paths are interpreted with respect to  the
4509       current  source directory.  Files installed by this form are by default
4510       given permissions OWNER_WRITE, OWNER_READ, GROUP_READ,  and  WORLD_READ
4511       if no PERMISSIONS argument is given.
4512
4513       The  PROGRAMS  form  is  identical  to  the  FILES form except that the
4514       default permissions for the installed file also include  OWNER_EXECUTE,
4515       GROUP_EXECUTE,  and  WORLD_EXECUTE.   This  form is intended to install
4516       programs that are not targets, such as shell scripts.  Use the  TARGETS
4517       form to install targets built within the project.
4518
4519       The  list  of  files...  given  to FILES or PROGRAMS may use “generator
4520       expressions” with the syntax $<...>.  See  the  cmake-generator-expres‐
4521       sions(7) manual for available expressions.  However, if any item begins
4522       in a generator expression it must evaluate to a full path.
4523
4524       The install destination given to the files install DESTINATION may  use
4525       “generator  expressions” with the syntax $<...>.  See the cmake-genera‐
4526       tor-expressions(7) manual for available expressions.
4527
4528   Installing Directories
4529          install(DIRECTORY dirs... DESTINATION <dir>
4530                  [FILE_PERMISSIONS permissions...]
4531                  [DIRECTORY_PERMISSIONS permissions...]
4532                  [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
4533                  [CONFIGURATIONS [Debug|Release|...]]
4534                  [COMPONENT <component>] [EXCLUDE_FROM_ALL]
4535                  [FILES_MATCHING]
4536                  [[PATTERN <pattern> | REGEX <regex>]
4537                   [EXCLUDE] [PERMISSIONS permissions...]] [...])
4538
4539       The DIRECTORY form installs contents of one or more  directories  to  a
4540       given  destination.   The directory structure is copied verbatim to the
4541       destination.  The last component of each directory name is appended  to
4542       the  destination  directory  but  a trailing slash may be used to avoid
4543       this because it leaves the last component empty.  Directory names given
4544       as  relative  paths  are interpreted with respect to the current source
4545       directory.  If no input  directory  names  are  given  the  destination
4546       directory  will  be created but nothing will be installed into it.  The
4547       FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify  permissions
4548       given  to files and directories in the destination.  If USE_SOURCE_PER‐
4549       MISSIONS is specified and FILE_PERMISSIONS  is  not,  file  permissions
4550       will  be copied from the source directory structure.  If no permissions
4551       are specified files will be given the default permissions specified  in
4552       the  FILES  form  of the command, and the directories will be given the
4553       default permissions specified in the PROGRAMS form of the command.
4554
4555       The MESSAGE_NEVER option disables file installation status output.
4556
4557       Installation of directories may be  controlled  with  fine  granularity
4558       using  the  PATTERN  or REGEX options.  These “match” options specify a
4559       globbing pattern or regular expression to match  directories  or  files
4560       encountered  within  input directories.  They may be used to apply cer‐
4561       tain options (see below) to a  subset  of  the  files  and  directories
4562       encountered.   The full path to each input file or directory (with for‐
4563       ward slashes) is matched against the expression.  A PATTERN will  match
4564       only  complete  file  names:  the portion of the full path matching the
4565       pattern must occur at the end of the file name and  be  preceded  by  a
4566       slash.   A REGEX will match any portion of the full path but it may use
4567       / and $ to simulate the PATTERN behavior.  By  default  all  files  and
4568       directories  are  installed  whether  or  not  they  are  matched.  The
4569       FILES_MATCHING option may be given before the  first  match  option  to
4570       disable  installation of files (but not directories) not matched by any
4571       expression.  For example, the code
4572
4573          install(DIRECTORY src/ DESTINATION include/myproj
4574                  FILES_MATCHING PATTERN "*.h")
4575
4576       will extract and install header files from a source tree.
4577
4578       Some options may follow a PATTERN or REGEX expression and  are  applied
4579       only  to  files  or directories matching them.  The EXCLUDE option will
4580       skip the matched file or directory.  The PERMISSIONS  option  overrides
4581       the permissions setting for the matched file or directory.  For example
4582       the code
4583
4584          install(DIRECTORY icons scripts/ DESTINATION share/myproj
4585                  PATTERN "CVS" EXCLUDE
4586                  PATTERN "scripts/*"
4587                  PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
4588                              GROUP_EXECUTE GROUP_READ)
4589
4590       will install the icons directory to share/myproj/icons and the  scripts
4591       directory  to  share/myproj.   The  icons will get default file permis‐
4592       sions, the scripts will be given  specific  permissions,  and  any  CVS
4593       directories will be excluded.
4594
4595       The  list  of  dirs...  given  to DIRECTORY and the install destination
4596       given to the directory install DESTINATION may use  “generator  expres‐
4597       sions”  with the syntax $<...>.  See the cmake-generator-expressions(7)
4598       manual for available expressions.
4599
4600   Custom Installation Logic
4601          install([[SCRIPT <file>] [CODE <code>]]
4602                  [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
4603
4604       The SCRIPT form will invoke the given CMake script files during instal‐
4605       lation.   If  the script file name is a relative path it will be inter‐
4606       preted with respect to the current source  directory.   The  CODE  form
4607       will  invoke  the given CMake code during installation.  Code is speci‐
4608       fied as a single argument inside a double-quoted string.  For  example,
4609       the code
4610
4611          install(CODE "MESSAGE(\"Sample install message.\")")
4612
4613       will print a message during installation.
4614
4615   Installing Exports
4616          install(EXPORT <export-name> DESTINATION <dir>
4617                  [NAMESPACE <namespace>] [[FILE <name>.cmake]|
4618                  [EXPORT_ANDROID_MK <name>.mk]]
4619                  [PERMISSIONS permissions...]
4620                  [CONFIGURATIONS [Debug|Release|...]]
4621                  [EXPORT_LINK_INTERFACE_LIBRARIES]
4622                  [COMPONENT <component>]
4623                  [EXCLUDE_FROM_ALL])
4624
4625       The  EXPORT form generates and installs a CMake file containing code to
4626       import targets from the installation tree into another project.  Target
4627       installations  are  associated  with the export <export-name> using the
4628       EXPORT option of the install(TARGETS) signature documented above.   The
4629       NAMESPACE  option  will prepend <namespace> to the target names as they
4630       are written to the import file.  By default the generated file will  be
4631       called <export-name>.cmake but the FILE option may be used to specify a
4632       different name.  The value given to the FILE option must be a file name
4633       with  the  .cmake  extension.  If a CONFIGURATIONS option is given then
4634       the file will only be installed when one of the named configurations is
4635       installed.  Additionally, the generated import file will reference only
4636       the   matching   target   configurations.     The    EXPORT_LINK_INTER‐
4637       FACE_LIBRARIES  keyword, if present, causes the contents of the proper‐
4638       ties matching  (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?  to  be
4639       exported,  when policy CMP0022 is NEW.  If a COMPONENT option is speci‐
4640       fied that does not match that given  to  the  targets  associated  with
4641       <export-name>  the  behavior  is  undefined.   If  a  library target is
4642       included in the export but a target to which it links is  not  included
4643       the behavior is unspecified.
4644
4645       In addition to cmake language files, the EXPORT_ANDROID_MK option maybe
4646       used to specify an export to the android ndk build system.  The Android
4647       NDK  supports  the  use  of prebuilt libraries, both static and shared.
4648       This allows cmake to build the libraries of a  project  and  make  them
4649       available to an ndk build system complete with transitive dependencies,
4650       include flags and defines required to use the libraries.
4651
4652       The EXPORT form is useful to help outside projects  use  targets  built
4653       and installed by the current project.  For example, the code
4654
4655          install(TARGETS myexe EXPORT myproj DESTINATION bin)
4656          install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
4657          install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)
4658
4659       will install the executable myexe to <prefix>/bin and code to import it
4660       in    the    file    <prefix>/lib/myproj/myproj.cmake     and     <pre‐
4661       fix>/lib/share/ndk-modules/Android.mk.   An  outside  project  may load
4662       this file with the include command and reference the  myexe  executable
4663       from  the  installation tree using the imported target name mp_myexe as
4664       if the target were built in its own tree.
4665
4666       NOTE:
4667          This  command  supercedes  the  install_targets()  command  and  the
4668          PRE_INSTALL_SCRIPT  and  POST_INSTALL_SCRIPT  target properties.  It
4669          also  replaces  the  FILES  forms   of   the   install_files()   and
4670          install_programs()  commands.  The processing order of these install
4671          rules   relative   to   those   generated   by    install_targets(),
4672          install_files(), and install_programs() commands is not defined.
4673
4674   link_directories
4675       Specify directories in which the linker will look for libraries.
4676
4677          link_directories(directory1 directory2 ...)
4678
4679       Specify the paths in which the linker should search for libraries.  The
4680       command will apply only to targets created after it is  called.   Rela‐
4681       tive  paths  given  to  this command are interpreted as relative to the
4682       current source directory, see CMP0015.
4683
4684       Note that this command is rarely necessary.  Library locations returned
4685       by  find_package()  and  find_library()  are absolute paths. Pass these
4686       absolute library file paths  directly  to  the  target_link_libraries()
4687       command.  CMake will ensure the linker finds them.
4688
4689   link_libraries
4690       Link libraries to all targets added later.
4691
4692          link_libraries([item1 [item2 [...]]]
4693                         [[debug|optimized|general] <item>] ...)
4694
4695       Specify  libraries  or  flags  to  use when linking any targets created
4696       later in the current directory or below by commands  such  as  add_exe‐
4697       cutable()  or  add_library().   See the target_link_libraries() command
4698       for meaning of arguments.
4699
4700       NOTE:
4701          The target_link_libraries() command  should  be  preferred  whenever
4702          possible.  Library dependencies are chained automatically, so direc‐
4703          tory-wide specification of link libraries is rarely needed.
4704
4705   load_cache
4706       Load in the values from another project’s CMake cache.
4707
4708          load_cache(pathToCacheFile READ_WITH_PREFIX
4709                     prefix entry1...)
4710
4711       Read the cache and store the requested entries in variables with  their
4712       name  prefixed  with the given prefix.  This only reads the values, and
4713       does not create entries in the local project’s cache.
4714
4715          load_cache(pathToCacheFile [EXCLUDE entry1...]
4716                     [INCLUDE_INTERNALS entry1...])
4717
4718       Load in the values from another cache  and  store  them  in  the  local
4719       project’s cache as internal entries.  This is useful for a project that
4720       depends on another project built in a different tree.   EXCLUDE  option
4721       can   be   used   to   provide  a  list  of  entries  to  be  excluded.
4722       INCLUDE_INTERNALS can be used to provide a list of internal entries  to
4723       be  included.   Normally,  no  internal entries are brought in.  Use of
4724       this form of the command is strongly discouraged, but  it  is  provided
4725       for backward compatibility.
4726
4727   project
4728       Set a name, version, and enable languages for the entire project.
4729
4730          project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
4731          project(<PROJECT-NAME>
4732                  [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
4733                  [DESCRIPTION <project-description-string>]
4734                  [LANGUAGES <language-name>...])
4735
4736       Sets  the  name  of the project and stores the name in the PROJECT_NAME
4737       variable.  Additionally this sets variables
4738
4739       · PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
4740
4741       · PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
4742
4743       If VERSION is specified, given components must  be  non-negative  inte‐
4744       gers.   If  VERSION  is not specified, the default version is the empty
4745       string.  The VERSION option may not be used unless  policy  CMP0048  is
4746       set to NEW.
4747
4748       The  project()  command stores the version number and its components in
4749       variables
4750
4751       · PROJECT_VERSION, <PROJECT-NAME>_VERSION
4752
4753       · PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
4754
4755       · PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
4756
4757       · PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
4758
4759       · PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK
4760
4761       Variables corresponding to unspecified versions are set  to  the  empty
4762       string (if policy CMP0048 is set to NEW).
4763
4764       If  optional  DESCRIPTION is given, then additional PROJECT_DESCRIPTION
4765       variable will be set to its argument. The argument  must  be  a  string
4766       with short description of the project (only a few words).
4767
4768       Optionally  you  can  specify  which  languages  your project supports.
4769       Example languages include C, CXX (i.e.  C++), CUDA, Fortran,  and  ASM.
4770       By  default  C  and  CXX  are enabled if no language options are given.
4771       Specify language NONE, or use the LANGUAGES keyword and  list  no  lan‐
4772       guages, to skip enabling any languages.
4773
4774       If enabling ASM, list it last so that CMake can check whether compilers
4775       for other languages like C work for assembly too.
4776
4777       If a variable exists called  CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,  the
4778       file  pointed  to by that variable will be included as the last step of
4779       the project command.
4780
4781       The top-level CMakeLists.txt file for a project must contain a literal,
4782       direct call to the project() command; loading one through the include()
4783       command is not sufficient.  If no such call exists CMake  will  implic‐
4784       itly add one to the top that enables the default languages (C and CXX).
4785
4786       NOTE:
4787          Call  the  cmake_minimum_required()  command at the beginning of the
4788          top-level CMakeLists.txt file even before calling the project() com‐
4789          mand.   It  is  important  to  establish version and policy settings
4790          before invoking other commands whose behavior they may affect.   See
4791          also policy CMP0000.
4792
4793   qt_wrap_cpp
4794       Create Qt Wrappers.
4795
4796          qt_wrap_cpp(resultingLibraryName DestName
4797                      SourceLists ...)
4798
4799       Produce  moc files for all the .h files listed in the SourceLists.  The
4800       moc files will be added to the library using the DestName source list.
4801
4802   qt_wrap_ui
4803       Create Qt user interfaces Wrappers.
4804
4805          qt_wrap_ui(resultingLibraryName HeadersDestName
4806                     SourcesDestName SourceLists ...)
4807
4808       Produce .h and  .cxx  files  for  all  the  .ui  files  listed  in  the
4809       SourceLists.  The .h files will be added to the library using the Head‐
4810       ersDestNamesource list.  The .cxx files will be added  to  the  library
4811       using the SourcesDestNamesource list.
4812
4813   remove_definitions
4814       Removes -D define flags added by add_definitions().
4815
4816          remove_definitions(-DFOO -DBAR ...)
4817
4818       Removes  flags  (added  by add_definitions()) from the compiler command
4819       line for sources in the current directory and below.
4820
4821   set_source_files_properties
4822       Source files can have properties that affect how they are built.
4823
4824          set_source_files_properties([file1 [file2 [...]]]
4825                                      PROPERTIES prop1 value1
4826                                      [prop2 value2 [...]])
4827
4828       Set properties associated with source files using  a  key/value  paired
4829       list.   See  Source File Properties for the list of properties known to
4830       CMake.  Source file properties are visible only to targets added in the
4831       same directory (CMakeLists.txt).
4832
4833   set_target_properties
4834       Targets can have properties that affect how they are built.
4835
4836          set_target_properties(target1 target2 ...
4837                                PROPERTIES prop1 value1
4838                                prop2 value2 ...)
4839
4840       Set  properties on a target.  The syntax for the command is to list all
4841       the files you want to change, and then provide the values you  want  to
4842       set  next.   You  can  use  any prop value pair you want and extract it
4843       later with the get_property() or get_target_property() command.
4844
4845       See Target Properties for the list of properties known to CMake.
4846
4847   set_tests_properties
4848       Set a property of the tests.
4849
4850          set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
4851
4852       Set a property for the tests.  If the test is  not  found,  CMake  will
4853       report  an  error.   Generator expressions will be expanded the same as
4854       supported by the test’s add_test() call.  See Test Properties  for  the
4855       list of properties known to CMake.
4856
4857   source_group
4858       Define  a  grouping  for source files in IDE project generation.  There
4859       are two different signatures to create source groups.
4860
4861          source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
4862          source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
4863
4864       Defines a group into which sources will be  placed  in  project  files.
4865       This  is  intended  to  set up file tabs in Visual Studio.  The options
4866       are:
4867
4868       TREE   CMake will automatically detect, from <src> files paths,  source
4869              groups  it  needs  to create, to keep structure of source groups
4870              analogically to the actual files and  directories  structure  in
4871              the  project. Paths of <src> files will be cut to be relative to
4872              <root>.
4873
4874       PREFIX Source group and files located directly in <root> path, will  be
4875              placed in <prefix> source groups.
4876
4877       FILES  Any  source  file  specified  explicitly will be placed in group
4878              <name>.  Relative paths are interpreted with respect to the cur‐
4879              rent source directory.
4880
4881       REGULAR_EXPRESSION
4882              Any  source  file whose name matches the regular expression will
4883              be placed in group <name>.
4884
4885       If a source file matches multiple groups, the last group  that  explic‐
4886       itly  lists  the  file with FILES will be favored, if any.  If no group
4887       explicitly lists the file, the  last  group  whose  regular  expression
4888       matches the file will be favored.
4889
4890       The  <name>  of the group and <prefix> argument may contain backslashes
4891       to specify subgroups:
4892
4893          source_group(outer\\inner ...)
4894          source_group(TREE <root> PREFIX sources\\inc ...)
4895
4896       For backwards compatibility, the short-hand signature
4897
4898          source_group(<name> <regex>)
4899
4900       is equivalent to
4901
4902          source_group(<name> REGULAR_EXPRESSION <regex>)
4903
4904   target_compile_definitions
4905       Add compile definitions to a target.
4906
4907          target_compile_definitions(<target>
4908            <INTERFACE|PUBLIC|PRIVATE> [items1...]
4909            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4910
4911       Specify compile definitions to use when  compiling  a  given  <target>.
4912       The named <target> must have been created by a command such as add_exe‐
4913       cutable() or add_library() and must not be an ALIAS target.
4914
4915       The INTERFACE, PUBLIC and PRIVATE keywords are required to specify  the
4916       scope  of the following arguments.  PRIVATE and PUBLIC items will popu‐
4917       late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
4918       items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
4919       get>.  (IMPORTED targets only support INTERFACE items.)  The  following
4920       arguments  specify  compile  definitions.   Repeated calls for the same
4921       <target> append items in the order called.
4922
4923       Arguments to target_compile_definitions may use “generator expressions”
4924       with  the syntax $<...>.  See the cmake-generator-expressions(7) manual
4925       for available expressions.  See  the  cmake-buildsystem(7)  manual  for
4926       more on defining buildsystem properties.
4927
4928   target_compile_features
4929       Add expected compiler features to a target.
4930
4931          target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
4932
4933       Specify  compiler  features required when compiling a given target.  If
4934       the feature is not listed in the CMAKE_C_COMPILE_FEATURES  variable  or
4935       CMAKE_CXX_COMPILE_FEATURES  variable, then an error will be reported by
4936       CMake.  If the use of the feature requires an additional compiler flag,
4937       such as -std=gnu++11, the flag will be added automatically.
4938
4939       The  INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
4940       scope of the features.  PRIVATE and PUBLIC items will populate the COM‐
4941       PILE_FEATURES  property  of  <target>.  PUBLIC and INTERFACE items will
4942       populate   the   INTERFACE_COMPILE_FEATURES   property   of   <target>.
4943       (IMPORTED  targets  only  support INTERFACE items.)  Repeated calls for
4944       the same <target> append items.
4945
4946       The named <target> must have been created by a command such as add_exe‐
4947       cutable() or add_library() and must not be an ALIAS target.
4948
4949       Arguments  to  target_compile_features  may use “generator expressions”
4950       with the syntax $<...>.  See the cmake-generator-expressions(7)  manual
4951       for  available  expressions.   See the cmake-compile-features(7) manual
4952       for information on compile features and a list of supported compilers.
4953
4954   target_compile_options
4955       Add compile options to a target.
4956
4957          target_compile_options(<target> [BEFORE]
4958            <INTERFACE|PUBLIC|PRIVATE> [items1...]
4959            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4960
4961       Specify compile options to use when  compiling  a  given  target.   The
4962       named  <target>  must  have  been created by a command such as add_exe‐
4963       cutable() or add_library() and must not be an ALIAS target.
4964
4965       If BEFORE is specified, the content will be prepended to  the  property
4966       instead of being appended.
4967
4968       This  command  can be used to add any options, but alternative commands
4969       exist to add preprocessor definitions (target_compile_definitions() and
4970       add_definitions()) or include directories (target_include_directories()
4971       and include_directories()).  See documentation  of  the  directory  and
4972       target COMPILE_OPTIONS properties.
4973
4974       The  INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
4975       scope of the following arguments.  PRIVATE and PUBLIC items will  popu‐
4976       late  the  COMPILE_OPTIONS  property of <target>.  PUBLIC and INTERFACE
4977       items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
4978       (IMPORTED  targets  only support INTERFACE items.)  The following argu‐
4979       ments specify compile options.  Repeated calls for  the  same  <target>
4980       append items in the order called.
4981
4982       Arguments  to  target_compile_options  may  use “generator expressions”
4983       with the syntax $<...>. See the  cmake-generator-expressions(7)  manual
4984       for  available  expressions.   See  the cmake-buildsystem(7) manual for
4985       more on defining buildsystem properties.
4986
4987   target_include_directories
4988       Add include directories to a target.
4989
4990          target_include_directories(<target> [SYSTEM] [BEFORE]
4991            <INTERFACE|PUBLIC|PRIVATE> [items1...]
4992            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4993
4994       Specify include directories to use when compiling a given target.   The
4995       named  <target>  must  have  been created by a command such as add_exe‐
4996       cutable() or add_library() and must not be an ALIAS target.
4997
4998       If BEFORE is specified, the content will be prepended to  the  property
4999       instead of being appended.
5000
5001       The  INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
5002       scope of the following arguments.  PRIVATE and PUBLIC items will  popu‐
5003       late  the  INCLUDE_DIRECTORIES property of <target>.  PUBLIC and INTER‐
5004       FACE items will populate the INTERFACE_INCLUDE_DIRECTORIES property  of
5005       <target>.   (IMPORTED  targets only support INTERFACE items.)  The fol‐
5006       lowing arguments specify include directories.
5007
5008       Specified include directories may be absolute paths or relative  paths.
5009       Repeated  calls for the same <target> append items in the order called.
5010       If SYSTEM is specified, the compiler will be told the  directories  are
5011       meant  as system include directories on some platforms (signalling this
5012       setting might achieve effects such as the compiler  skipping  warnings,
5013       or  these fixed-install system files not being considered in dependency
5014       calculations - see compiler docs).  If SYSTEM  is  used  together  with
5015       PUBLIC  or  INTERFACE,  the INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target
5016       property will be populated with the specified directories.
5017
5018       Arguments to target_include_directories may use “generator expressions”
5019       with  the syntax $<...>.  See the cmake-generator-expressions(7) manual
5020       for available expressions.  See  the  cmake-buildsystem(7)  manual  for
5021       more on defining buildsystem properties.
5022
5023       Include  directories  usage  requirements  commonly  differ between the
5024       build-tree   and   the   install-tree.    The    BUILD_INTERFACE    and
5025       INSTALL_INTERFACE  generator  expressions can be used to describe sepa‐
5026       rate usage requirements based on the usage  location.   Relative  paths
5027       are allowed within the INSTALL_INTERFACE expression and are interpreted
5028       relative to the installation prefix.  For example:
5029
5030          target_include_directories(mylib PUBLIC
5031            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
5032            $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
5033          )
5034
5035   Creating Relocatable Packages
5036       Note that it is not advisable to populate the INSTALL_INTERFACE of  the
5037       INTERFACE_INCLUDE_DIRECTORIES  of  a  target with absolute paths to the
5038       include  directories  of  dependencies.   That  would  hard-code   into
5039       installed  packages  the  include  directory  paths for dependencies as
5040       found on the machine the package was made on.
5041
5042       The INSTALL_INTERFACE  of  the  INTERFACE_INCLUDE_DIRECTORIES  is  only
5043       suitable  for  specifying  the required include directories for headers
5044       provided with the target itself, not those provided by  the  transitive
5045       dependencies  listed  in  its INTERFACE_LINK_LIBRARIES target property.
5046       Those dependencies should themselves be targets that specify their  own
5047       header locations in INTERFACE_INCLUDE_DIRECTORIES.
5048
5049       See  the Creating Relocatable Packages section of the cmake-packages(7)
5050       manual for discussion of additional care that must be taken when speci‐
5051       fying usage requirements while creating packages for redistribution.
5052
5053   target_link_libraries
5054       Specify  libraries  or  flags to use when linking a given target and/or
5055       its dependents.  Usage requirements from linked library targets will be
5056       propagated.   Usage requirements of a target’s dependencies affect com‐
5057       pilation of its own sources.
5058
5059   Overview
5060       This command has several signatures as detailed in  subsections  below.
5061       All of them have the general form:
5062
5063          target_link_libraries(<target> ... <item>... ...)
5064
5065       The named <target> must have been created in the current directory by a
5066       command such as add_executable() or add_library() and must  not  be  an
5067       ALIAS target.  Repeated calls for the same <target> append items in the
5068       order called.  Each <item> may be:
5069
5070       · A library target name: The generated link line  will  have  the  full
5071         path  to  the  linkable library file associated with the target.  The
5072         buildsystem will have a dependency to re-link <target> if the library
5073         file changes.
5074
5075         The  named target must be created by add_library() within the project
5076         or as an IMPORTED library.  If it is created within  the  project  an
5077         ordering  dependency  will automatically be added in the build system
5078         to make sure the named library target is up-to-date before the  <tar‐
5079         get> links.
5080
5081         If  an  imported  library  has the IMPORTED_NO_SONAME target property
5082         set, CMake may ask the linker to search for the  library  instead  of
5083         using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
5084
5085       · A  full path to a library file: The generated link line will normally
5086         preserve the full path to the  file.  The  buildsystem  will  have  a
5087         dependency to re-link <target> if the library file changes.
5088
5089         There are some cases where CMake may ask the linker to search for the
5090         library (e.g. /usr/lib/libfoo.so  becomes  -lfoo),  such  as  when  a
5091         shared  library  is  detected  to  have  no SONAME field.  See policy
5092         CMP0060 for discussion of another case.
5093
5094         If the library file is in a Mac OSX framework, the Headers  directory
5095         of the framework will also be processed as a usage requirement.  This
5096         has the same effect as passing the framework directory as an  include
5097         directory.
5098
5099         On Visual Studio Generators for VS 2010 and above, library files end‐
5100         ing in .targets will be treated as MSBuild targets files and imported
5101         into generated project files.  This is not supported by other genera‐
5102         tors.
5103
5104       · A plain library name: The generated link line will ask the linker  to
5105         search for the library (e.g. foo becomes -lfoo or foo.lib).
5106
5107       · A  link  flag:  Item names starting with -, but not -l or -framework,
5108         are treated as linker flags.  Note that such flags  will  be  treated
5109         like any other library link item for purposes of transitive dependen‐
5110         cies, so they are generally safe to  specify  only  as  private  link
5111         items that will not propagate to dependents.
5112
5113         Link  flags  specified here are inserted into the link command in the
5114         same place as the link libraries. This might not be correct,  depend‐
5115         ing  on  the  linker.  Use the LINK_FLAGS target property to add link
5116         flags  explicitly.  The  flags   will   then   be   placed   at   the
5117         toolchain-defined flag position in the link command.
5118
5119       · A  debug,  optimized,  or  general  keyword  immediately  followed by
5120         another <item>.  The item following such a keyword will be used  only
5121         for  the corresponding build configuration.  The debug keyword corre‐
5122         sponds to the Debug configuration (or to configurations named in  the
5123         DEBUG_CONFIGURATIONS  global  property  if it is set).  The optimized
5124         keyword corresponds to all other configurations.  The general keyword
5125         corresponds  to  all  configurations, and is purely optional.  Higher
5126         granularity may be achieved for per-configuration rules  by  creating
5127         and linking to IMPORTED library targets.
5128
5129       Items  containing  ::,  such as Foo::Bar, are assumed to be IMPORTED or
5130       ALIAS library target names and will cause an error if  no  such  target
5131       exists.  See policy CMP0028.
5132
5133       Arguments to target_link_libraries may use “generator expressions” with
5134       the syntax $<...>.  Note however, that generator expressions  will  not
5135       be  used  in OLD handling of CMP0003 or CMP0004.  See the cmake-genera‐
5136       tor-expressions(7)  manual  for   available   expressions.    See   the
5137       cmake-buildsystem(7)  manual  for  more on defining buildsystem proper‐
5138       ties.
5139
5140   Libraries for a Target and/or its Dependents
5141          target_link_libraries(<target>
5142                                <PRIVATE|PUBLIC|INTERFACE> <item>...
5143                               [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
5144
5145       The PUBLIC, PRIVATE and INTERFACE keywords can be used to specify  both
5146       the link dependencies and the link interface in one command.  Libraries
5147       and targets following PUBLIC are linked to, and are made  part  of  the
5148       link interface.  Libraries and targets following PRIVATE are linked to,
5149       but are not made part  of  the  link  interface.   Libraries  following
5150       INTERFACE are appended to the link interface and are not used for link‐
5151       ing <target>.
5152
5153   Libraries for both a Target and its Dependents
5154          target_link_libraries(<target> <item>...)
5155
5156       Library dependencies are transitive by  default  with  this  signature.
5157       When  this  target  is  linked  into  another target then the libraries
5158       linked to this target will appear on the link line for the other target
5159       too.   This  transitive  “link  interface”  is  stored  in  the  INTER‐
5160       FACE_LINK_LIBRARIES target property and may be  overridden  by  setting
5161       the  property  directly.   When  CMP0022  is not set to NEW, transitive
5162       linking  is  built  in  but  may  be  overridden  by  the   LINK_INTER‐
5163       FACE_LIBRARIES property.  Calls to other signatures of this command may
5164       set the property making any libraries linked exclusively by this signa‐
5165       ture private.
5166
5167   Libraries for a Target and/or its Dependents (Legacy)
5168          target_link_libraries(<target>
5169                                <LINK_PRIVATE|LINK_PUBLIC> <lib>...
5170                               [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
5171
5172       The  LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
5173       link dependencies and the link interface in one command.
5174
5175       This signature is for compatibility only.  Prefer the PUBLIC or PRIVATE
5176       keywords instead.
5177
5178       Libraries and targets following LINK_PUBLIC are linked to, and are made
5179       part of the INTERFACE_LINK_LIBRARIES.  If policy CMP0022  is  not  NEW,
5180       they are also made part of the LINK_INTERFACE_LIBRARIES.  Libraries and
5181       targets following LINK_PRIVATE are linked to, but are not made part  of
5182       the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
5183
5184   Libraries for Dependents Only (Legacy)
5185          target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
5186
5187       The  LINK_INTERFACE_LIBRARIES  mode appends the libraries to the INTER‐
5188       FACE_LINK_LIBRARIES target property instead of using them for  linking.
5189       If  policy CMP0022 is not NEW, then this mode also appends libraries to
5190       the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
5191
5192       This signature is for compatibility only.  Prefer  the  INTERFACE  mode
5193       instead.
5194
5195       Libraries  specified  as debug are wrapped in a generator expression to
5196       correspond to  debug  builds.   If  policy  CMP0022  is  not  NEW,  the
5197       libraries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
5198       erty (or to the properties corresponding to  configurations  listed  in
5199       the  DEBUG_CONFIGURATIONS  global  property  if  it is set).  Libraries
5200       specified as optimized are  appended  to  the  INTERFACE_LINK_LIBRARIES
5201       property.   If policy CMP0022 is not NEW, they are also appended to the
5202       LINK_INTERFACE_LIBRARIES property.  Libraries specified as general  (or
5203       without  any  keyword)  are  treated as if specified for both debug and
5204       optimized.
5205
5206   Cyclic Dependencies of Static Libraries
5207       The library dependency graph is normally acyclic (a DAG),  but  in  the
5208       case  of  mutually-dependent STATIC libraries CMake allows the graph to
5209       contain cycles (strongly connected components).   When  another  target
5210       links  to one of the libraries, CMake repeats the entire connected com‐
5211       ponent.  For example, the code
5212
5213          add_library(A STATIC a.c)
5214          add_library(B STATIC b.c)
5215          target_link_libraries(A B)
5216          target_link_libraries(B A)
5217          add_executable(main main.c)
5218          target_link_libraries(main A)
5219
5220       links main to A B A B.  While one  repetition  is  usually  sufficient,
5221       pathological object file and symbol arrangements can require more.  One
5222       may handle such cases by using the  LINK_INTERFACE_MULTIPLICITY  target
5223       property  or  by  manually  repeating  the  component  in the last tar‐
5224       get_link_libraries call.  However, if two archives are really so inter‐
5225       dependent  they should probably be combined into a single archive, per‐
5226       haps by using Object Libraries.
5227
5228   Creating Relocatable Packages
5229       Note that it is not advisable to populate the  INTERFACE_LINK_LIBRARIES
5230       of  a target with absolute paths to dependencies.  That would hard-code
5231       into installed packages the library  file  paths  for  dependencies  as
5232       found on the machine the package was made on.
5233
5234       See  the Creating Relocatable Packages section of the cmake-packages(7)
5235       manual for discussion of additional care that must be taken when speci‐
5236       fying usage requirements while creating packages for redistribution.
5237
5238   target_sources
5239       Add sources to a target.
5240
5241          target_sources(<target>
5242            <INTERFACE|PUBLIC|PRIVATE> [items1...]
5243            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
5244
5245       Specify  sources to use when compiling a given target.  The named <tar‐
5246       get> must have been created by a command such  as  add_executable()  or
5247       add_library() and must not be an ALIAS target.
5248
5249       The  INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
5250       scope of the following arguments.  PRIVATE and PUBLIC items will  popu‐
5251       late the SOURCES property of <target>.  PUBLIC and INTERFACE items will
5252       populate the INTERFACE_SOURCES property of <target>.  (IMPORTED targets
5253       only   support  INTERFACE  items.)   The  following  arguments  specify
5254       sources.  Repeated calls for the same  <target>  append  items  in  the
5255       order called.
5256
5257       Arguments  to  target_sources  may use “generator expressions” with the
5258       syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
5259       able  expressions.   See  the  cmake-buildsystem(7)  manual for more on
5260       defining buildsystem properties.
5261
5262   try_compile
5263       Try building some code.
5264
5265   Try Compiling Whole Projects
5266          try_compile(RESULT_VAR <bindir> <srcdir>
5267                      <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
5268                      [OUTPUT_VARIABLE <var>])
5269
5270       Try building a project.  The success or  failure  of  the  try_compile,
5271       i.e. TRUE or FALSE respectively, is returned in RESULT_VAR.
5272
5273       In  this  form, <srcdir> should contain a complete CMake project with a
5274       CMakeLists.txt file and all sources.  The <bindir>  and  <srcdir>  will
5275       not  be  deleted  after  this  command is run.  Specify <targetName> to
5276       build a specific target instead of the all or  ALL_BUILD  target.   See
5277       below for the meaning of other options.
5278
5279   Try Compiling Source Files
5280          try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
5281                      [CMAKE_FLAGS <flags>...]
5282                      [COMPILE_DEFINITIONS <defs>...]
5283                      [LINK_LIBRARIES <libs>...]
5284                      [OUTPUT_VARIABLE <var>]
5285                      [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
5286                      [<LANG>_STANDARD <std>]
5287                      [<LANG>_STANDARD_REQUIRED <bool>]
5288                      [<LANG>_EXTENSIONS <bool>]
5289                      )
5290
5291       Try  building an executable from one or more source files.  The success
5292       or failure of the try_compile, i.e.  TRUE  or  FALSE  respectively,  is
5293       returned in RESULT_VAR.
5294
5295       In  this  form  the user need only supply one or more source files that
5296       include a definition for main.  CMake will create a CMakeLists.txt file
5297       to build the source(s) as an executable that looks something like this:
5298
5299          add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
5300          include_directories(${INCLUDE_DIRECTORIES})
5301          link_directories(${LINK_DIRECTORIES})
5302          add_executable(cmTryCompileExec <srcfile>...)
5303          target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
5304
5305       The options are:
5306
5307       CMAKE_FLAGS <flags>...
5308              Specify  flags  of the form -DVAR:TYPE=VALUE to be passed to the
5309              cmake command-line used to drive  the  test  build.   The  above
5310              example  shows  how  values  for  variables INCLUDE_DIRECTORIES,
5311              LINK_DIRECTORIES, and LINK_LIBRARIES are used.
5312
5313       COMPILE_DEFINITIONS <defs>...
5314              Specify -Ddefinition arguments to pass to add_definitions in the
5315              generated test project.
5316
5317       COPY_FILE <fileName>
5318              Copy the linked executable to the given <fileName>.
5319
5320       COPY_FILE_ERROR <var>
5321              Use  after  COPY_FILE  to  capture into variable <var> any error
5322              message encountered while trying to copy the file.
5323
5324       LINK_LIBRARIES <libs>...
5325              Specify libraries to be linked in the  generated  project.   The
5326              list  of libraries may refer to system libraries and to Imported
5327              Targets from the calling project.
5328
5329              If this option  is  specified,  any  -DLINK_LIBRARIES=...  value
5330              given to the CMAKE_FLAGS option will be ignored.
5331
5332       OUTPUT_VARIABLE <var>
5333              Store the output from the build process the given variable.
5334
5335       <LANG>_STANDARD <std>
5336              Specify  the  C_STANDARD,  CXX_STANDARD, or CUDA_STANDARD target
5337              property of the generated project.
5338
5339       <LANG>_STANDARD_REQUIRED <bool>
5340              Specify  the  C_STANDARD_REQUIRED,   CXX_STANDARD_REQUIRED,   or
5341              CUDA_STANDARD_REQUIRED target property of the generated project.
5342
5343       <LANG>_EXTENSIONS <bool>
5344              Specify  the  C_EXTENSIONS,  CXX_EXTENSIONS,  or CUDA_EXTENSIONS
5345              target property of the generated project.
5346
5347       In this version  all  files  in  <bindir>/CMakeFiles/CMakeTmp  will  be
5348       cleaned automatically.  For debugging, --debug-trycompile can be passed
5349       to cmake to avoid this clean.  However, multiple sequential try_compile
5350       operations   reuse   this   single   output   directory.   If  you  use
5351       --debug-trycompile, you can only debug one try_compile call at a  time.
5352       The  recommended  procedure is to protect all try_compile calls in your
5353       project by if(NOT DEFINED RESULT_VAR) logic, configure with  cmake  all
5354       the  way  through once, then delete the cache entry associated with the
5355       try_compile  call  of  interest,  and  then  re-run  cmake  again  with
5356       --debug-trycompile.
5357
5358   Other Behavior Settings
5359       If set, the following variables are passed in to the generated try_com‐
5360       pile  CMakeLists.txt  to  initialize  compile  target  properties  with
5361       default values:
5362
5363       · CMAKE_ENABLE_EXPORTS
5364
5365       · CMAKE_LINK_SEARCH_START_STATIC
5366
5367       · CMAKE_LINK_SEARCH_END_STATIC
5368
5369       · CMAKE_POSITION_INDEPENDENT_CODE
5370
5371       If  CMP0056  is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
5372       well.
5373
5374       The current setting of CMP0065 is set in the generated project.
5375
5376       Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
5377       figuration.
5378
5379       Set  the  CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify the type of
5380       target used for the source file signature.
5381
5382       Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify  vari‐
5383       ables  that must be propagated into the test project.  This variable is
5384       meant for use only in toolchain files.
5385
5386       If CMP0067 is set to NEW, or any of the  <LANG>_STANDARD,  <LANG>_STAN‐
5387       DARD_REQUIRED, or <LANG>_EXTENSIONS options are used, then the language
5388       standard variables are honored:
5389
5390       · CMAKE_C_STANDARD
5391
5392       · CMAKE_C_STANDARD_REQUIRED
5393
5394       · CMAKE_C_EXTENSIONS
5395
5396       · CMAKE_CXX_STANDARD
5397
5398       · CMAKE_CXX_STANDARD_REQUIRED
5399
5400       · CMAKE_CXX_EXTENSIONS
5401
5402       · CMAKE_CUDA_STANDARD
5403
5404       · CMAKE_CUDA_STANDARD_REQUIRED
5405
5406       · CMAKE_CUDA_EXTENSIONS
5407
5408       Their values are used to set the corresponding target properties in the
5409       generated project (unless overridden by an explicit option).
5410
5411   try_run
5412       Try compiling and then running some code.
5413
5414   Try Compiling and Running Source Files
5415          try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
5416                  bindir srcfile [CMAKE_FLAGS <flags>...]
5417                  [COMPILE_DEFINITIONS <defs>...]
5418                  [LINK_LIBRARIES <libs>...]
5419                  [COMPILE_OUTPUT_VARIABLE <var>]
5420                  [RUN_OUTPUT_VARIABLE <var>]
5421                  [OUTPUT_VARIABLE <var>]
5422                  [ARGS <args>...])
5423
5424       Try  compiling a <srcfile>.  Returns TRUE or FALSE for success or fail‐
5425       ure in COMPILE_RESULT_VAR.  If the compile  succeeded,  runs  the  exe‐
5426       cutable and returns its exit code in RUN_RESULT_VAR.  If the executable
5427       was built, but failed to  run,  then  RUN_RESULT_VAR  will  be  set  to
5428       FAILED_TO_RUN.   See  the  try_compile() command for information on how
5429       the test project is constructed to build the source file.
5430
5431       The options are:
5432
5433       CMAKE_FLAGS <flags>...
5434              Specify flags of the form -DVAR:TYPE=VALUE to be passed  to  the
5435              cmake command-line used to drive the test build.  The example in
5436              try_compile() shows how values  for  variables  INCLUDE_DIRECTO‐
5437              RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
5438
5439       COMPILE_DEFINITIONS <defs>...
5440              Specify -Ddefinition arguments to pass to add_definitions in the
5441              generated test project.
5442
5443       COMPILE_OUTPUT_VARIABLE <var>
5444              Report the compile step build output in a given variable.
5445
5446       LINK_LIBRARIES <libs>...
5447              Specify libraries to be linked in the  generated  project.   The
5448              list  of libraries may refer to system libraries and to Imported
5449              Targets from the calling project.
5450
5451              If this option  is  specified,  any  -DLINK_LIBRARIES=...  value
5452              given to the CMAKE_FLAGS option will be ignored.
5453
5454       OUTPUT_VARIABLE <var>
5455              Report  the compile build output and the output from running the
5456              executable in the given variable.  This option exists for legacy
5457              reasons.  Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
5458              instead.
5459
5460       RUN_OUTPUT_VARIABLE <var>
5461              Report the output from running the executable in a  given  vari‐
5462              able.
5463
5464   Other Behavior Settings
5465       Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
5466       figuration.
5467
5468   Behavior when Cross Compiling
5469       When cross compiling, the executable compiled in the first step usually
5470       cannot  be  run  on  the  build  host.   The try_run command checks the
5471       CMAKE_CROSSCOMPILING variable to detect whether CMake is in  cross-com‐
5472       piling  mode.   If  that  is the case, it will still try to compile the
5473       executable, but it will not  try  to  run  the  executable  unless  the
5474       CMAKE_CROSSCOMPILING_EMULATOR  variable is set.  Instead it will create
5475       cache variables which must be filled by the user or by presetting  them
5476       in  some CMake script file to the values the executable would have pro‐
5477       duced if it had been run on its actual target  platform.   These  cache
5478       entries are:
5479
5480       <RUN_RESULT_VAR>
5481              Exit  code  if the executable were to be run on the target plat‐
5482              form.
5483
5484       <RUN_RESULT_VAR>__TRYRUN_OUTPUT
5485              Output from stdout and stderr if the executable were to  be  run
5486              on  the  target  platform.  This is created only if the RUN_OUT‐
5487              PUT_VARIABLE or OUTPUT_VARIABLE option was used.
5488
5489       In order to make cross compiling your project easier, use try_run  only
5490       if really required.  If you use try_run, use the RUN_OUTPUT_VARIABLE or
5491       OUTPUT_VARIABLE options only  if  really  required.   Using  them  will
5492       require  that when cross-compiling, the cache variables will have to be
5493       set manually to the output of the executable.  You can also “guard” the
5494       calls  to  try_run with an if() block checking the CMAKE_CROSSCOMPILING
5495       variable and provide an easy-to-preset alternative for this case.
5496

CTEST COMMANDS

5498       These commands are available only in CTest scripts.
5499
5500   ctest_build
5501       Perform the CTest Build Step as a Dashboard Client.
5502
5503          ctest_build([BUILD <build-dir>] [APPEND]
5504                      [CONFIGURATION <config>]
5505                      [FLAGS <flags>]
5506                      [PROJECT_NAME <project-name>]
5507                      [TARGET <target-name>]
5508                      [NUMBER_ERRORS <num-err-var>]
5509                      [NUMBER_WARNINGS <num-warn-var>]
5510                      [RETURN_VALUE <result-var>]
5511                      [CAPTURE_CMAKE_ERROR <result-var>]
5512                      )
5513
5514       Build the project and store results in Build.xml  for  submission  with
5515       the ctest_submit() command.
5516
5517       The  CTEST_BUILD_COMMAND  variable may be set to explicitly specify the
5518       build command line.  Otherwise the build command line is computed auto‐
5519       matically based on the options given.
5520
5521       The options are:
5522
5523       BUILD <build-dir>
5524              Specify  the  top-level  build  directory.   If  not  given, the
5525              CTEST_BINARY_DIRECTORY variable is used.
5526
5527       APPEND Mark Build.xml for append to results previously submitted  to  a
5528              dashboard  server  since  the  last  ctest_start() call.  Append
5529              semantics are defined by the dashboard server in use.  This does
5530              not  cause  results  to be appended to a .xml file produced by a
5531              previous call to this command.
5532
5533       CONFIGURATION <config>
5534              Specify the build configuration (e.g. Debug).  If not  specified
5535              the  CTEST_BUILD_CONFIGURATION variable will be checked.  Other‐
5536              wise the -C <cfg> option given to the ctest(1) command  will  be
5537              used, if any.
5538
5539       FLAGS <flags>
5540              Pass  additional  arguments to the underlying build command.  If
5541              not specified the CTEST_BUILD_FLAGS variable  will  be  checked.
5542              This can, e.g., be used to trigger a parallel build using the -j
5543              option of make. See the ProcessorCount module for an example.
5544
5545       PROJECT_NAME <project-name>
5546              Set the name of the project to build.  This should correspond to
5547              the  top-level  call to the project() command.  If not specified
5548              the CTEST_PROJECT_NAME variable will be checked.
5549
5550       TARGET <target-name>
5551              Specify the name of a target to build.   If  not  specified  the
5552              CTEST_BUILD_TARGET  variable  will  be  checked.   Otherwise the
5553              default target will be built.  This is the “all” target  (called
5554              ALL_BUILD in Visual Studio Generators).
5555
5556       NUMBER_ERRORS <num-err-var>
5557              Store the number of build errors detected in the given variable.
5558
5559       NUMBER_WARNINGS <num-warn-var>
5560              Store  the  number of build warnings detected in the given vari‐
5561              able.
5562
5563       RETURN_VALUE <result-var>
5564              Store the return value of the native build  tool  in  the  given
5565              variable.
5566
5567       CAPTURE_CMAKE_ERROR <result-var>
5568              Store  in  the  <result-var> variable -1 if there are any errors
5569              running the command and prevent ctest from returning non-zero if
5570              an error occurs.
5571
5572       QUIET  Suppress  any  CTest-specific  non-error  output that would have
5573              been printed to the console otherwise.  The summary of  warnings
5574              /  errors,  as  well as the output from the native build tool is
5575              unaffected by this option.
5576
5577   ctest_configure
5578       Perform the CTest Configure Step as a Dashboard Client.
5579
5580          ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
5581                          [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
5582                          [CAPTURE_CMAKE_ERROR <result-var>])
5583
5584       Configure the project build tree and record  results  in  Configure.xml
5585       for submission with the ctest_submit() command.
5586
5587       The options are:
5588
5589       BUILD <build-dir>
5590              Specify  the  top-level  build  directory.   If  not  given, the
5591              CTEST_BINARY_DIRECTORY variable is used.
5592
5593       SOURCE <source-dir>
5594              Specify   the   source   directory.    If   not    given,    the
5595              CTEST_SOURCE_DIRECTORY variable is used.
5596
5597       APPEND Mark Configure.xml for append to results previously submitted to
5598              a dashboard server since the last  ctest_start()  call.   Append
5599              semantics are defined by the dashboard server in use.  This does
5600              not cause results to be appended to a .xml file  produced  by  a
5601              previous call to this command.
5602
5603       OPTIONS <options>
5604              Specify  command-line  arguments  to  pass  to the configuration
5605              tool.
5606
5607       RETURN_VALUE <result-var>
5608              Store in the <result-var>  variable  the  return  value  of  the
5609              native configuration tool.
5610
5611       CAPTURE_CMAKE_ERROR <result-var>
5612              Store  in  the  <result-var> variable -1 if there are any errors
5613              running the command and prevent ctest from returning non-zero if
5614              an error occurs.
5615
5616       QUIET  Suppress  any  CTest-specific non-error messages that would have
5617              otherwise been printed to the console.  Output from the underly‐
5618              ing configure command is not affected.
5619
5620   ctest_coverage
5621       Perform the CTest Coverage Step as a Dashboard Client.
5622
5623          ctest_coverage([BUILD <build-dir>] [APPEND]
5624                         [LABELS <label>...]
5625                         [RETURN_VALUE <result-var>]
5626                         [CAPTURE_CMAKE_ERROR <result-var]
5627                         [QUIET]
5628                         )
5629
5630       Collect  coverage tool results and stores them in Coverage.xml for sub‐
5631       mission with the ctest_submit() command.
5632
5633       The options are:
5634
5635       BUILD <build-dir>
5636              Specify the  top-level  build  directory.   If  not  given,  the
5637              CTEST_BINARY_DIRECTORY variable is used.
5638
5639       APPEND Mark  Coverage.xml for append to results previously submitted to
5640              a dashboard server since the last  ctest_start()  call.   Append
5641              semantics are defined by the dashboard server in use.  This does
5642              not cause results to be appended to a .xml file  produced  by  a
5643              previous call to this command.
5644
5645       LABELS Filter  the coverage report to include only source files labeled
5646              with at least one of the labels specified.
5647
5648       RETURN_VALUE <result-var>
5649              Store in the <result-var> variable 0 if coverage tools ran with‐
5650              out error and non-zero otherwise.
5651
5652       CAPTURE_CMAKE_ERROR <result-var>
5653              Store  in  the  <result-var> variable -1 if there are any errors
5654              running the command and prevent ctest from returning non-zero if
5655              an error occurs.
5656
5657       QUIET  Suppress  any  CTest-specific  non-error  output that would have
5658              been printed to the console otherwise.  The  summary  indicating
5659              how  many  lines  of  code  were  covered  is unaffected by this
5660              option.
5661
5662   ctest_empty_binary_directory
5663       empties the binary directory
5664
5665          ctest_empty_binary_directory( directory )
5666
5667       Removes a binary directory.  This  command  will  perform  some  checks
5668       prior  to  deleting  the  directory in an attempt to avoid malicious or
5669       accidental directory deletion.
5670
5671   ctest_memcheck
5672       Perform the CTest MemCheck Step as a Dashboard Client.
5673
5674          ctest_memcheck([BUILD <build-dir>] [APPEND]
5675                         [START <start-number>]
5676                         [END <end-number>]
5677                         [STRIDE <stride-number>]
5678                         [EXCLUDE <exclude-regex>]
5679                         [INCLUDE <include-regex>]
5680                         [EXCLUDE_LABEL <label-exclude-regex>]
5681                         [INCLUDE_LABEL <label-include-regex>]
5682                         [EXCLUDE_FIXTURE <regex>]
5683                         [EXCLUDE_FIXTURE_SETUP <regex>]
5684                         [EXCLUDE_FIXTURE_CLEANUP <regex>]
5685                         [PARALLEL_LEVEL <level>]
5686                         [TEST_LOAD <threshold>]
5687                         [SCHEDULE_RANDOM <ON|OFF>]
5688                         [STOP_TIME <time-of-day>]
5689                         [RETURN_VALUE <result-var>]
5690                         [DEFECT_COUNT <defect-count-var>]
5691                         [QUIET]
5692                         )
5693
5694       Run tests with a dynamic  analysis  tool  and  store  results  in  Mem‐
5695       Check.xml for submission with the ctest_submit() command.
5696
5697       Most options are the same as those for the ctest_test() command.
5698
5699       The options unique to this command are:
5700
5701       DEFECT_COUNT <defect-count-var>
5702              Store in the <defect-count-var> the number of defects found.
5703
5704   ctest_read_custom_files
5705       read CTestCustom files.
5706
5707          ctest_read_custom_files( directory ... )
5708
5709       Read  all  the  CTestCustom.ctest  or  CTestCustom.cmake files from the
5710       given directory.
5711
5712       By default, invoking ctest(1) without a script will read  custom  files
5713       from the binary directory.
5714
5715   ctest_run_script
5716       runs a ctest -S script
5717
5718          ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
5719                      script_file_name2 ... [RETURN_VALUE var])
5720
5721       Runs  a script or scripts much like if it was run from ctest -S.  If no
5722       argument is provided then the current script is run using  the  current
5723       settings  of  the  variables.   If  NEW_PROCESS  is specified then each
5724       script will be run in a separate process.If RETURN_VALUE  is  specified
5725       the return value of the last script run will be put into var.
5726
5727   ctest_sleep
5728       sleeps for some amount of time
5729
5730          ctest_sleep(<seconds>)
5731
5732       Sleep for given number of seconds.
5733
5734          ctest_sleep(<time1> <duration> <time2>)
5735
5736       Sleep for t=(time1 + duration - time2) seconds if t > 0.
5737
5738   ctest_start
5739       Starts the testing for a given model
5740
5741          ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET])
5742
5743       Starts  the  testing  for  a given model.  The command should be called
5744       after the  binary  directory  is  initialized.   If  the  ‘source’  and
5745       ‘binary’  directory are not specified, it reads the CTEST_SOURCE_DIREC‐
5746       TORY and CTEST_BINARY_DIRECTORY.  If the track is specified,  the  sub‐
5747       missions will go to the specified track.  If APPEND is used, the exist‐
5748       ing TAG is used rather than creating a new one  based  on  the  current
5749       time  stamp.   If QUIET is used, CTest will suppress any non-error mes‐
5750       sages that it otherwise would have printed to the console.
5751
5752       If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
5753       able)  is  set, its content is treated as command-line.  The command is
5754       invoked with the current working directory set to  the  parent  of  the
5755       source  directory,  even  if the source directory already exists.  This
5756       can be used to create the source tree from a  version  control  reposi‐
5757       tory.
5758
5759   ctest_submit
5760       Perform the CTest Submit Step as a Dashboard Client.
5761
5762          ctest_submit([PARTS <part>...] [FILES <file>...]
5763                       [HTTPHEADER <header>]
5764                       [RETRY_COUNT <count>]
5765                       [RETRY_DELAY <delay>]
5766                       [RETURN_VALUE <result-var>]
5767                       [QUIET]
5768                       )
5769
5770       Submit  results  to a dashboard server.  By default all available parts
5771       are submitted.
5772
5773       The options are:
5774
5775       PARTS <part>...
5776              Specify a subset of parts to submit.  Valid part names are:
5777
5778                 Start      = nothing
5779                 Update     = ctest_update results, in Update.xml
5780                 Configure  = ctest_configure results, in Configure.xml
5781                 Build      = ctest_build results, in Build.xml
5782                 Test       = ctest_test results, in Test.xml
5783                 Coverage   = ctest_coverage results, in Coverage.xml
5784                 MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
5785                 Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
5786                 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
5787                 Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
5788                 Submit     = nothing
5789
5790       FILES <file>...
5791              Specify an explicit list of  specific  files  to  be  submitted.
5792              Each individual file must exist at the time of the call.
5793
5794       HTTPHEADER <HTTP-header>
5795              Specify  HTTP header to be included in the request to CDash dur‐
5796              ing submission.  This suboption can be repeated several times.
5797
5798       RETRY_COUNT <count>
5799              Specify how many times to retry a timed-out submission.
5800
5801       RETRY_DELAY <delay>
5802              Specify how long (in seconds) to wait after a timed-out  submis‐
5803              sion before attempting to re-submit.
5804
5805       RETURN_VALUE <result-var>
5806              Store in the <result-var> variable 0 for success and non-zero on
5807              failure.
5808
5809       QUIET  Suppress all non-error messages that would have  otherwise  been
5810              printed to the console.
5811
5812   Submit to CDash Upload API
5813          ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
5814                       [HTTPHEADER <header>]
5815                       [RETRY_COUNT <count>]
5816                       [RETRY_DELAY <delay>]
5817                       [QUIET])
5818
5819       This  second  signature  is used to upload files to CDash via the CDash
5820       file upload API. The api first sends a request to upload to CDash along
5821       with  a  content  hash  of the file. If CDash does not already have the
5822       file, then it is uploaded. Along with the file, a CDash type string  is
5823       specified to tell CDash which handler to use to process the data.
5824
5825       This  signature  accepts  the HTTPHEADER, RETRY_COUNT, RETRY_DELAY, and
5826       QUIET options as described above.
5827
5828   ctest_test
5829       Perform the CTest Test Step as a Dashboard Client.
5830
5831          ctest_test([BUILD <build-dir>] [APPEND]
5832                     [START <start-number>]
5833                     [END <end-number>]
5834                     [STRIDE <stride-number>]
5835                     [EXCLUDE <exclude-regex>]
5836                     [INCLUDE <include-regex>]
5837                     [EXCLUDE_LABEL <label-exclude-regex>]
5838                     [INCLUDE_LABEL <label-include-regex>]
5839                     [EXCLUDE_FIXTURE <regex>]
5840                     [EXCLUDE_FIXTURE_SETUP <regex>]
5841                     [EXCLUDE_FIXTURE_CLEANUP <regex>]
5842                     [PARALLEL_LEVEL <level>]
5843                     [TEST_LOAD <threshold>]
5844                     [SCHEDULE_RANDOM <ON|OFF>]
5845                     [STOP_TIME <time-of-day>]
5846                     [RETURN_VALUE <result-var>]
5847                     [CAPTURE_CMAKE_ERROR <result-var>]
5848                     [QUIET]
5849                     )
5850
5851       Run tests in the project build tree and store results in  Test.xml  for
5852       submission with the ctest_submit() command.
5853
5854       The options are:
5855
5856       BUILD <build-dir>
5857              Specify  the  top-level  build  directory.   If  not  given, the
5858              CTEST_BINARY_DIRECTORY variable is used.
5859
5860       APPEND Mark Test.xml for append to results previously  submitted  to  a
5861              dashboard  server  since  the  last  ctest_start() call.  Append
5862              semantics are defined by the dashboard server in use.  This does
5863              not  cause  results  to be appended to a .xml file produced by a
5864              previous call to this command.
5865
5866       START <start-number>
5867              Specify the beginning of a range of test numbers.
5868
5869       END <end-number>
5870              Specify the end of a range of test numbers.
5871
5872       STRIDE <stride-number>
5873              Specify the stride by which to step across a range of test  num‐
5874              bers.
5875
5876       EXCLUDE <exclude-regex>
5877              Specify a regular expression matching test names to exclude.
5878
5879       INCLUDE <include-regex>
5880              Specify  a  regular  expression  matching test names to include.
5881              Tests not matching this expression are excluded.
5882
5883       EXCLUDE_LABEL <label-exclude-regex>
5884              Specify a regular expression matching test labels to exclude.
5885
5886       INCLUDE_LABEL <label-include-regex>
5887              Specify a regular expression matching test  labels  to  include.
5888              Tests not matching this expression are excluded.
5889
5890       EXCLUDE_FIXTURE <regex>
5891              If a test in the set of tests to be executed requires a particu‐
5892              lar fixture, that fixture’s setup and cleanup tests  would  nor‐
5893              mally  be  added to the test set automatically. This option pre‐
5894              vents adding setup or cleanup tests for  fixtures  matching  the
5895              <regex>.  Note  that  all  other  fixture  behavior is retained,
5896              including test dependencies and skipping tests that have fixture
5897              setup tests that fail.
5898
5899       EXCLUDE_FIXTURE_SETUP <regex>
5900              Same  as  EXCLUDE_FIXTURE  except  only matching setup tests are
5901              excluded.
5902
5903       EXCLUDE_FIXTURE_CLEANUP <regex>
5904              Same as EXCLUDE_FIXTURE except only matching cleanup  tests  are
5905              excluded.
5906
5907       PARALLEL_LEVEL <level>
5908              Specify a positive number representing the number of tests to be
5909              run in parallel.
5910
5911       TEST_LOAD <threshold>
5912              While running tests in parallel, try not  to  start  tests  when
5913              they may cause the CPU load to pass above a given threshold.  If
5914              not specified the CTEST_TEST_LOAD variable will be checked,  and
5915              then  the  --test-load  command-line  argument to ctest(1).  See
5916              also the TestLoad setting in the CTest Test Step.
5917
5918       SCHEDULE_RANDOM <ON|OFF>
5919              Launch tests in a random order.  This may be useful for  detect‐
5920              ing implicit test dependencies.
5921
5922       STOP_TIME <time-of-day>
5923              Specify  a  time  of day at which the tests should all stop run‐
5924              ning.
5925
5926       RETURN_VALUE <result-var>
5927              Store in the <result-var> variable 0 if all tests passed.  Store
5928              non-zero if anything went wrong.
5929
5930       CAPTURE_CMAKE_ERROR <result-var>
5931              Store  in  the  <result-var> variable -1 if there are any errors
5932              running the command and prevent ctest from returning non-zero if
5933              an error occurs.
5934
5935       QUIET  Suppress  any  CTest-specific non-error messages that would have
5936              otherwise been printed to the console.  Output from the underly‐
5937              ing  test  command  is not affected.  Summary info detailing the
5938              percentage of passing tests is  also  unaffected  by  the  QUIET
5939              option.
5940
5941       See    also    the   CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE   and
5942       CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
5943
5944   ctest_update
5945       Perform the CTest Update Step as a Dashboard Client.
5946
5947          ctest_update([SOURCE <source-dir>] [RETURN_VALUE <result-var>] [QUIET])
5948
5949       Update the source tree from  version  control  and  record  results  in
5950       Update.xml for submission with the ctest_submit() command.
5951
5952       The options are:
5953
5954       SOURCE <source-dir>
5955              Specify    the    source   directory.    If   not   given,   the
5956              CTEST_SOURCE_DIRECTORY variable is used.
5957
5958       RETURN_VALUE <result-var>
5959              Store in the <result-var> variable the number of  files  updated
5960              or -1 on error.
5961
5962       QUIET  Tell  CTest  to  suppress  most non-error messages that it would
5963              have otherwise printed to the console.  CTest will still  report
5964              the  new  revision  of  the repository and any conflicting files
5965              that were found.
5966
5967       The update always follows the version control branch currently  checked
5968       out  in  the source directory.  See the CTest Update Step documentation
5969       for more information.
5970
5971   ctest_upload
5972       Upload files to a dashboard server as a Dashboard Client.
5973
5974          ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
5975
5976       The options are:
5977
5978       FILES <file>...
5979              Specify a list of files to be sent along with the build  results
5980              to the dashboard server.
5981
5982       QUIET  Suppress  any  CTest-specific  non-error  output that would have
5983              been printed to the console otherwise.
5984
5985       CAPTURE_CMAKE_ERROR <result-var>
5986              Store in the <result-var> variable -1 if there  are  any  errors
5987              running the command and prevent ctest from returning non-zero if
5988              an error occurs.
5989

DEPRECATED COMMANDS

5991       These commands are available only for compatibility with older versions
5992       of CMake.  Do not use them in new code.
5993
5994   build_name
5995       Disallowed.  See CMake Policy CMP0036.
5996
5997       Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
5998
5999          build_name(variable)
6000
6001       Sets  the  specified variable to a string representing the platform and
6002       compiler  settings.   These  values  are  now  available  through   the
6003       CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
6004
6005   exec_program
6006       Deprecated.  Use the execute_process() command instead.
6007
6008       Run  an  executable  program during the processing of the CMakeList.txt
6009       file.
6010
6011          exec_program(Executable [directory in which to run]
6012                       [ARGS <arguments to executable>]
6013                       [OUTPUT_VARIABLE <var>]
6014                       [RETURN_VALUE <var>])
6015
6016       The executable is run in the optionally specified directory.  The  exe‐
6017       cutable  can include arguments if it is double quoted, but it is better
6018       to use the optional ARGS argument to specify arguments to the  program.
6019       This  is  because  cmake will then be able to escape spaces in the exe‐
6020       cutable path.  An optional argument OUTPUT_VARIABLE specifies  a  vari‐
6021       able  in which to store the output.  To capture the return value of the
6022       execution, provide a RETURN_VALUE.  If  OUTPUT_VARIABLE  is  specified,
6023       then  no  output  will  go  to the stdout/stderr of the console running
6024       cmake.
6025
6026   export_library_dependencies
6027       Disallowed.  See CMake Policy CMP0033.
6028
6029       Use install(EXPORT) or export() command.
6030
6031       This  command  generates  an  old-style  library   dependencies   file.
6032       Projects  requiring CMake 2.6 or later should not use the command.  Use
6033       instead the install(EXPORT) command to  help  export  targets  from  an
6034       installation  tree  and  the  export() command to export targets from a
6035       build tree.
6036
6037       The old-style library dependencies file  does  not  take  into  account
6038       per-configuration  names  of  libraries or the LINK_INTERFACE_LIBRARIES
6039       target property.
6040
6041          export_library_dependencies(<file> [APPEND])
6042
6043       Create a file named <file> that can be included into a  CMake  listfile
6044       with  the  INCLUDE command.  The file will contain a number of SET com‐
6045       mands that will set all the variables  needed  for  library  dependency
6046       information.   This  should be the last command in the top level CMake‐
6047       Lists.txt file of the project.  If the APPEND option is specified,  the
6048       SET  commands  will  be appended to the given file instead of replacing
6049       it.
6050
6051   install_files
6052       Deprecated.  Use the install(FILES) command instead.
6053
6054       This command has been superceded by the install() command.  It is  pro‐
6055       vided  for  compatibility  with  older  CMake  code.  The FILES form is
6056       directly replaced by the FILES form of the install() command.  The reg‐
6057       exp  form  can  be  expressed  more  clearly using the GLOB form of the
6058       file() command.
6059
6060          install_files(<dir> extension file file ...)
6061
6062       Create rules to install the listed files with the given extension  into
6063       the given directory.  Only files existing in the current source tree or
6064       its corresponding location in the binary tree may be listed.  If a file
6065       specified  already  has  an  extension,  that extension will be removed
6066       first.  This is useful for providing lists  of  source  files  such  as
6067       foo.cxx when you want the corresponding foo.h to be installed.  A typi‐
6068       cal extension is ‘.h’.
6069
6070          install_files(<dir> regexp)
6071
6072       Any files in the  current  source  directory  that  match  the  regular
6073       expression will be installed.
6074
6075          install_files(<dir> FILES file file ...)
6076
6077       Any  files  listed after the FILES keyword will be installed explicitly
6078       from the names given.  Full paths are allowed in this form.
6079
6080       The directory <dir> is relative to the installation  prefix,  which  is
6081       stored in the variable CMAKE_INSTALL_PREFIX.
6082
6083   install_programs
6084       Deprecated. Use the install(PROGRAMS) command instead.
6085
6086       This  command has been superceded by the install() command.  It is pro‐
6087       vided for compatibility with older  CMake  code.   The  FILES  form  is
6088       directly  replaced  by the PROGRAMS form of the install() command.  The
6089       regexp form can be expressed more clearly using the GLOB  form  of  the
6090       file() command.
6091
6092          install_programs(<dir> file1 file2 [file3 ...])
6093          install_programs(<dir> FILES file1 [file2 ...])
6094
6095       Create  rules  to install the listed programs into the given directory.
6096       Use the FILES argument to guarantee that the file list version  of  the
6097       command will be used even when there is only one argument.
6098
6099          install_programs(<dir> regexp)
6100
6101       In  the  second  form  any program in the current source directory that
6102       matches the regular expression will be installed.
6103
6104       This command is intended to install programs  that  are  not  built  by
6105       cmake,  such  as  shell scripts.  See the TARGETS form of the install()
6106       command to create installation rules for targets built by cmake.
6107
6108       The directory <dir> is relative to the installation  prefix,  which  is
6109       stored in the variable CMAKE_INSTALL_PREFIX.
6110
6111   install_targets
6112       Deprecated. Use the install(TARGETS) command instead.
6113
6114       This  command has been superceded by the install() command.  It is pro‐
6115       vided for compatibility with older CMake code.
6116
6117          install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
6118
6119       Create rules to install the listed targets into  the  given  directory.
6120       The  directory  <dir>  is relative to the installation prefix, which is
6121       stored in the variable CMAKE_INSTALL_PREFIX.  If  RUNTIME_DIRECTORY  is
6122       specified,  then  on  systems with special runtime files (Windows DLL),
6123       the files will be copied to that directory.
6124
6125   load_command
6126       Disallowed.  See CMake Policy CMP0031.
6127
6128       Load a command into a running CMake.
6129
6130          load_command(COMMAND_NAME <loc1> [loc2 ...])
6131
6132       The given locations are searched for a library  whose  name  is  cmCOM‐
6133       MAND_NAME.  If found, it is loaded as a module and the command is added
6134       to the set of available CMake commands.  Usually, try_compile() is used
6135       before  this command to compile the module.  If the command is success‐
6136       fully loaded a variable named
6137
6138          CMAKE_LOADED_COMMAND_<COMMAND_NAME>
6139
6140       will be set to the full path of the module that was loaded.   Otherwise
6141       the variable will not be set.
6142
6143   make_directory
6144       Deprecated. Use the file(MAKE_DIRECTORY) command instead.
6145
6146          make_directory(directory)
6147
6148       Creates the specified directory.  Full paths should be given.  Any par‐
6149       ent directories that do not exist will also be created.  Use with care.
6150
6151   output_required_files
6152       Disallowed.  See CMake Policy CMP0032.
6153
6154       Approximate C preprocessor dependency scanning.
6155
6156       This command exists only because ancient CMake  versions  provided  it.
6157       CMake  handles  preprocessor  dependency scanning automatically using a
6158       more advanced scanner.
6159
6160          output_required_files(srcfile outputfile)
6161
6162       Outputs a list of all the source files that are required by the  speci‐
6163       fied  srcfile.   This list is written into outputfile.  This is similar
6164       to writing out the dependencies for srcfile except that it  jumps  from
6165       .h files into .cxx, .c and .cpp files if possible.
6166
6167   remove
6168       Deprecated. Use the list(REMOVE_ITEM) command instead.
6169
6170          remove(VAR VALUE VALUE ...)
6171
6172       Removes  VALUE from the variable VAR.  This is typically used to remove
6173       entries from a vector  (e.g.   semicolon  separated  list).   VALUE  is
6174       expanded.
6175
6176   subdir_depends
6177       Disallowed.  See CMake Policy CMP0029.
6178
6179       Does nothing.
6180
6181          subdir_depends(subdir dep1 dep2 ...)
6182
6183       Does  not do anything.  This command used to help projects order paral‐
6184       lel builds correctly.  This functionality is now automatic.
6185
6186   subdirs
6187       Deprecated. Use the add_subdirectory() command instead.
6188
6189       Add a list of subdirectories to the build.
6190
6191          subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
6192                  [PREORDER] )
6193
6194       Add a list of subdirectories to the build.  The add_subdirectory() com‐
6195       mand  should  be  used  instead  of subdirs although subdirs will still
6196       work.  This will cause any CMakeLists.txt files in the sub  directories
6197       to  be processed by CMake.  Any directories after the PREORDER flag are
6198       traversed first by makefile builds, the PREORDER flag has no effect  on
6199       IDE  projects.   Any directories after the EXCLUDE_FROM_ALL marker will
6200       not be included in the top level makefile or  project  file.   This  is
6201       useful for having CMake create makefiles or projects for a set of exam‐
6202       ples in a project.  You would  want  CMake  to  generate  makefiles  or
6203       project  files for all the examples at the same time, but you would not
6204       want them to show up in the top level project or  be  built  each  time
6205       make is run from the top.
6206
6207   use_mangled_mesa
6208       Disallowed.  See CMake Policy CMP0030.
6209
6210       Copy mesa headers for use in combination with system GL.
6211
6212          use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
6213
6214       The  path to mesa includes, should contain gl_mangle.h.  The mesa head‐
6215       ers are copied to the specified output directory.  This allows  mangled
6216       mesa headers to override other GL headers by being added to the include
6217       directory path earlier.
6218
6219   utility_source
6220       Disallowed.  See CMake Policy CMP0034.
6221
6222       Specify the source tree of a third-party utility.
6223
6224          utility_source(cache_entry executable_name
6225                         path_to_source [file1 file2 ...])
6226
6227       When a third-party utility’s source is included  in  the  distribution,
6228       this command specifies its location and name.  The cache entry will not
6229       be set unless the path_to_source and all listed  files  exist.   It  is
6230       assumed that the source tree of the utility will have been built before
6231       it is needed.
6232
6233       When cross compiling CMake will print a warning if  a  utility_source()
6234       command  is executed, because in many cases it is used to build an exe‐
6235       cutable which is executed later on.  This doesn’t work when cross  com‐
6236       piling, since the executable can run only on their target platform.  So
6237       in this case the cache entry has to be adjusted manually so  it  points
6238       to an executable which is runnable on the build host.
6239
6240   variable_requires
6241       Disallowed.  See CMake Policy CMP0035.
6242
6243       Use the if() command instead.
6244
6245       Assert satisfaction of an option’s required variables.
6246
6247          variable_requires(TEST_VARIABLE RESULT_VARIABLE
6248                            REQUIRED_VARIABLE1
6249                            REQUIRED_VARIABLE2 ...)
6250
6251       The  first  argument  (TEST_VARIABLE) is the name of the variable to be
6252       tested, if that variable is false nothing else is done.  If  TEST_VARI‐
6253       ABLE  is  true,  then the next argument (RESULT_VARIABLE) is a variable
6254       that is set to true if all the required variables are set.  The rest of
6255       the arguments are variables that must be true or not set to NOTFOUND to
6256       avoid an error.  If any are not true, an error is reported.
6257
6258   write_file
6259       Deprecated. Use the file(WRITE) command instead.
6260
6261          write_file(filename "message to write"... [APPEND])
6262
6263       The first argument is the file name, the rest of the arguments are mes‐
6264       sages  to write.  If the argument APPEND is specified, then the message
6265       will be appended.
6266
6267       NOTE 1: file(WRITE)  and file(APPEND)  do exactly the same as this  one
6268       but add some more functionality.
6269
6270       NOTE  2:  When  using write_file the produced file cannot be used as an
6271       input to CMake (CONFIGURE_FILE, source file …) because it will lead  to
6272       an  infinite  loop.  Use configure_file() if you want to generate input
6273       files to CMake.
6274
6276       2000-2018 Kitware, Inc. and Contributors
6277
6278
6279
6280
62813.11.4                           May 13, 2019                CMAKE-COMMANDS(7)
Impressum