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() 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              │                          │ MiB [1]                    │
45              ├──────────────────────────┼────────────────────────────┤
46AVAILABLE_VIRTUAL_MEMORY  │ Available  virtual  memory │
47              │                          │ in MiB [1]                 │
48              ├──────────────────────────┼────────────────────────────┤
49TOTAL_PHYSICAL_MEMORY     │ Total physical  memory  in │
50              │                          │ MiB [1]                    │
51              ├──────────────────────────┼────────────────────────────┤
52AVAILABLE_PHYSICAL_MEMORY │ Available  physical memory │
53              │                          │ in MiB [1]                 │
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 processor  supports │
64              │                          │ Ext. MMX instructions      │
65              └──────────────────────────┴────────────────────────────┘
66
67HAS_SSE                   │ One  if processor supports │
68              │                          │ SSE instructions           │
69              ├──────────────────────────┼────────────────────────────┤
70HAS_SSE2                  │ One if processor  supports │
71              │                          │ SSE2 instructions          │
72              ├──────────────────────────┼────────────────────────────┤
73HAS_SSE_FP                │ One  if processor supports │
74              │                          │ SSE FP instructions        │
75              ├──────────────────────────┼────────────────────────────┤
76HAS_SSE_MMX               │ One if processor  supports │
77              │                          │ SSE MMX instructions       │
78              ├──────────────────────────┼────────────────────────────┤
79HAS_AMD_3DNOW             │ One  if processor supports │
80              │                          │ 3DNow instructions         │
81              ├──────────────────────────┼────────────────────────────┤
82HAS_AMD_3DNOW_PLUS        │ One if processor  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

FOOTNOTES

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

PROJECT COMMANDS

3844       These commands are available only in CMake projects.
3845
3846   add_compile_definitions
3847       Add preprocessor definitions to the compilation of source files.
3848
3849          add_compile_definitions(<definition> ...)
3850
3851       Adds  preprocessor definitions to the compiler command line for targets
3852       in the current directory and below (whether added before or after  this
3853       command is invoked). See documentation of the directory and target COM‐
3854       PILE_DEFINITIONS properties.
3855
3856       Definitions are specified using the syntax  VAR  or  VAR=value.   Func‐
3857       tion-style  definitions  are  not  supported.  CMake will automatically
3858       escape the value correctly for the native build system (note that CMake
3859       language syntax may require escapes to specify some values).
3860
3861       Arguments  to  add_compile_definitions  may use “generator expressions”
3862       with the syntax $<...>.  See the cmake-generator-expressions(7)  manual
3863       for  available  expressions.   See  the cmake-buildsystem(7) manual for
3864       more on defining buildsystem properties.
3865
3866   add_compile_options
3867       Add options to the compilation of source files.
3868
3869          add_compile_options(<option> ...)
3870
3871       Adds options to the COMPILE_OPTIONS directory property.  These  options
3872       are used when compiling targets from the current directory and below.
3873
3874   Arguments
3875       Arguments  to  add_compile_options may use “generator expressions” with
3876       the syntax $<...>.  See the cmake-generator-expressions(7)  manual  for
3877       available expressions.  See the cmake-buildsystem(7) manual for more on
3878       defining buildsystem properties.
3879
3880       The final set of compile or link options used  for  a  target  is  con‐
3881       structed  by accumulating options from the current target and the usage
3882       requirements of it dependencies.  The set of options  is  de-duplicated
3883       to  avoid  repetition.   While  beneficial  for individual options, the
3884       de-duplication step can break up option groups.  For example, -D A -D B
3885       becomes  -D  A  B.  One may specify a group of options using shell-like
3886       quoting along with a SHELL: prefix.  The SHELL: prefix is  dropped  and
3887       the  rest of the option string is parsed using the separate_arguments()
3888       UNIX_COMMAND mode.  For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
3889       -D B.
3890
3891   Example
3892       Since  different  compilers support different options, a typical use of
3893       this command is in a compiler-specific conditional clause:
3894
3895          if (MSVC)
3896              # warning level 4 and all warnings as errors
3897              add_compile_options(/W4 /WX)
3898          else()
3899              # lots of warnings and all warnings as errors
3900              add_compile_options(-Wall -Wextra -pedantic -Werror)
3901          endif()
3902
3903   See Also
3904       This command can be used to add any options. However, for  adding  pre‐
3905       processor  definitions and include directories it is recommended to use
3906       the more specific commands add_compile_definitions() and include_direc‐
3907       tories().
3908
3909       The command target_compile_options() adds target-specific options.
3910
3911   add_custom_command
3912       Add a custom build rule to the generated build system.
3913
3914       There are two main signatures for add_custom_command.
3915
3916   Generating Files
3917       The  first  signature is for adding a custom command to produce an out‐
3918       put:
3919
3920          add_custom_command(OUTPUT output1 [output2 ...]
3921                             COMMAND command1 [ARGS] [args1...]
3922                             [COMMAND command2 [ARGS] [args2...] ...]
3923                             [MAIN_DEPENDENCY depend]
3924                             [DEPENDS [depends...]]
3925                             [BYPRODUCTS [files...]]
3926                             [IMPLICIT_DEPENDS <lang1> depend1
3927                                              [<lang2> depend2] ...]
3928                             [WORKING_DIRECTORY dir]
3929                             [COMMENT comment]
3930                             [DEPFILE depfile]
3931                             [VERBATIM] [APPEND] [USES_TERMINAL]
3932                             [COMMAND_EXPAND_LISTS])
3933
3934       This defines a command to generate specified OUTPUT file(s).  A  target
3935       created  in the same directory (CMakeLists.txt file) that specifies any
3936       output of the custom command as a source file is given a rule to gener‐
3937       ate  the  file using the command at build time.  Do not list the output
3938       in more than one independent target that may build in parallel  or  the
3939       two instances of the rule may conflict (instead use the add_custom_tar‐
3940       get() command to drive the command and make the other targets depend on
3941       that  one).  In makefile terms this creates a new target in the follow‐
3942       ing form:
3943
3944          OUTPUT: MAIN_DEPENDENCY DEPENDS
3945                  COMMAND
3946
3947       The options are:
3948
3949       APPEND Append the COMMAND and DEPENDS option values to the custom  com‐
3950              mand  for  the  first output specified.  There must have already
3951              been a previous call to this command with the same output.   The
3952              COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are cur‐
3953              rently ignored when APPEND is given, but  may  be  used  in  the
3954              future.
3955
3956       BYPRODUCTS
3957              Specify  the  files the command is expected to produce but whose
3958              modification time may or may not be newer than the dependencies.
3959              If  a  byproduct  name is a relative path it will be interpreted
3960              relative to the build tree directory corresponding to  the  cur‐
3961              rent  source directory.  Each byproduct file will be marked with
3962              the GENERATED source file property automatically.
3963
3964              Explicit specification of byproducts is supported by  the  Ninja
3965              generator to tell the ninja build tool how to regenerate byprod‐
3966              ucts when they are missing.  It is also useful when other  build
3967              rules  (e.g.  custom  commands) depend on the byproducts.  Ninja
3968              requires a build rule for any generated file  on  which  another
3969              rule depends even if there are order-only dependencies to ensure
3970              the byproducts will be available before their dependents build.
3971
3972              The BYPRODUCTS option is ignored on non-Ninja generators  except
3973              to mark byproducts GENERATED.
3974
3975       COMMAND
3976              Specify  the  command-line(s) to execute at build time.  If more
3977              than one COMMAND is specified they will be  executed  in  order,
3978              but  not  necessarily  composed  into  a stateful shell or batch
3979              script.  (To run a full script, use the configure_file() command
3980              or  the  file(GENERATE) command to create it, and then specify a
3981              COMMAND to launch it.)  The optional ARGS argument is for  back‐
3982              ward compatibility and will be ignored.
3983
3984              If  COMMAND  specifies an executable target name (created by the
3985              add_executable() command) it will automatically be  replaced  by
3986              the  location  of  the executable created at build time. If set,
3987              the CROSSCOMPILING_EMULATOR executable target property will also
3988              be  prepended  to  the command to allow the executable to run on
3989              the host.  (Use the TARGET_FILE generator expression  to  refer‐
3990              ence  an  executable later in the command line.)  Additionally a
3991              target-level dependency will be added  so  that  the  executable
3992              target  will  be  built before any target using this custom com‐
3993              mand.  However this does NOT add a  file-level  dependency  that
3994              would cause the custom command to re-run whenever the executable
3995              is recompiled.
3996
3997              Arguments to COMMAND may use generator expressions.   References
3998              to  target  names  in  generator  expressions imply target-level
3999              dependencies, but  NOT  file-level  dependencies.   List  target
4000              names with the DEPENDS option to add file-level dependencies.
4001
4002       COMMENT
4003              Display  the  given  message before the commands are executed at
4004              build time.
4005
4006       DEPENDS
4007              Specify files on which the command depends.  If  any  dependency
4008              is  an  OUTPUT  of  another custom command in the same directory
4009              (CMakeLists.txt file) CMake automatically brings the other  cus‐
4010              tom  command into the target in which this command is built.  If
4011              DEPENDS is not specified the command will run whenever the  OUT‐
4012              PUT is missing; if the command does not actually create the OUT‐
4013              PUT then the rule will always run.   If  DEPENDS  specifies  any
4014              target (created by the add_custom_target(), add_executable(), or
4015              add_library() command) a target-level dependency is  created  to
4016              make  sure the target is built before any target using this cus‐
4017              tom command.  Additionally, if the target is  an  executable  or
4018              library  a  file-level dependency is created to cause the custom
4019              command to re-run whenever the target is recompiled.
4020
4021              Arguments to DEPENDS may use generator expressions.
4022
4023       COMMAND_EXPAND_LISTS
4024              Lists in COMMAND arguments will  be  expanded,  including  those
4025              created  with  generator expressions, allowing COMMAND arguments
4026              such as  ${CC}  "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4027              RIES>,;-I>" foo.cc to be properly expanded.
4028
4029       IMPLICIT_DEPENDS
4030              Request scanning of implicit dependencies of an input file.  The
4031              language given specifies the programming language  whose  corre‐
4032              sponding  dependency  scanner  should be used.  Currently only C
4033              and CXX language scanners are supported.  The language has to be
4034              specified  for  every file in the IMPLICIT_DEPENDS list.  Depen‐
4035              dencies discovered from the scanning are added to those  of  the
4036              custom  command  at  build time.  Note that the IMPLICIT_DEPENDS
4037              option is currently supported only for Makefile  generators  and
4038              will be ignored by other generators.
4039
4040       MAIN_DEPENDENCY
4041              Specify  the  primary input source file to the command.  This is
4042              treated just like any value given to the DEPENDS option but also
4043              suggests  to  Visual  Studio generators where to hang the custom
4044              command. Each source file may have at most one command  specify‐
4045              ing  it  as  its  main dependency. A compile command (i.e. for a
4046              library or an executable) counts as an implicit main  dependency
4047              which  gets  silently overwritten by a custom command specifica‐
4048              tion.
4049
4050       OUTPUT Specify the output files the command is expected to produce.  If
4051              an  output  name is a relative path it will be interpreted rela‐
4052              tive to the build tree directory corresponding  to  the  current
4053              source directory.  Each output file will be marked with the GEN‐
4054              ERATED source file property automatically.  If the output of the
4055              custom  command  is  not  actually  created as a file on disk it
4056              should be marked with the SYMBOLIC source file property.
4057
4058       USES_TERMINAL
4059              The command will be given direct access to the terminal if  pos‐
4060              sible.  With the Ninja generator, this places the command in the
4061              console pool.
4062
4063       VERBATIM
4064              All arguments to the commands will be escaped properly  for  the
4065              build  tool  so  that the invoked command receives each argument
4066              unchanged.  Note that one level of escapes is still used by  the
4067              CMake language processor before add_custom_command even sees the
4068              arguments.  Use of VERBATIM is recommended as it enables correct
4069              behavior.   When  VERBATIM is not given the behavior is platform
4070              specific because there is no protection of tool-specific special
4071              characters.
4072
4073       WORKING_DIRECTORY
4074              Execute  the  command  with the given current working directory.
4075              If it is a relative path it will be interpreted relative to  the
4076              build  tree directory corresponding to the current source direc‐
4077              tory.
4078
4079              Arguments to WORKING_DIRECTORY may use generator expressions.
4080
4081       DEPFILE
4082              Specify a .d depfile for the Ninja generator.  A .d  file  holds
4083              dependencies  usually  emitted  by  the  custom  command itself.
4084              Using DEPFILE with other generators than Ninja is an error.
4085
4086   Build Events
4087       The second signature adds a custom  command  to  a  target  such  as  a
4088       library  or  executable.   This  is  useful for performing an operation
4089       before or after building the target.  The command becomes part  of  the
4090       target  and  will only execute when the target itself is built.  If the
4091       target is already built, the command will not execute.
4092
4093          add_custom_command(TARGET <target>
4094                             PRE_BUILD | PRE_LINK | POST_BUILD
4095                             COMMAND command1 [ARGS] [args1...]
4096                             [COMMAND command2 [ARGS] [args2...] ...]
4097                             [BYPRODUCTS [files...]]
4098                             [WORKING_DIRECTORY dir]
4099                             [COMMENT comment]
4100                             [VERBATIM] [USES_TERMINAL])
4101
4102       This defines a new command that will be associated  with  building  the
4103       specified <target>.  The <target> must be defined in the current direc‐
4104       tory; targets defined in other directories may not be specified.
4105
4106       When the command will happen is determined by which of the following is
4107       specified:
4108
4109       PRE_BUILD
4110              On Visual Studio Generators, run before any other rules are exe‐
4111              cuted within the target.  On other generators, run  just  before
4112              PRE_LINK commands.
4113
4114       PRE_LINK
4115              Run  after  sources  have  been  compiled but before linking the
4116              binary or running the librarian or archiver  tool  of  a  static
4117              library.   This  is  not  defined  for  targets  created  by the
4118              add_custom_target() command.
4119
4120       POST_BUILD
4121              Run after all other rules within the target have been executed.
4122
4123       NOTE:
4124          Because generator expressions can be used in custom commands, it  is
4125          possible  to  define  COMMAND  lines  or whole custom commands which
4126          evaluate to empty strings for certain  configurations.   For  Visual
4127          Studio  2010  (and  newer)  generators these command lines or custom
4128          commands will be omitted  for  the  specific  configuration  and  no
4129          “empty-string-command” will be added.
4130
4131          This allows to add individual build events for every configuration.
4132
4133   add_custom_target
4134       Add a target with no output so it will always be built.
4135
4136          add_custom_target(Name [ALL] [command1 [args1...]]
4137                            [COMMAND command2 [args2...] ...]
4138                            [DEPENDS depend depend depend ... ]
4139                            [BYPRODUCTS [files...]]
4140                            [WORKING_DIRECTORY dir]
4141                            [COMMENT comment]
4142                            [VERBATIM] [USES_TERMINAL]
4143                            [COMMAND_EXPAND_LISTS]
4144                            [SOURCES src1 [src2...]])
4145
4146       Adds  a  target  with  the given name that executes the given commands.
4147       The target has no output file and is always considered out of date even
4148       if  the commands try to create a file with the name of the target.  Use
4149       the add_custom_command() command to generate a file with  dependencies.
4150       By default nothing depends on the custom target.  Use the add_dependen‐
4151       cies() command to add dependencies to or from other targets.
4152
4153       The options are:
4154
4155       ALL    Indicate that this target should be added to the  default  build
4156              target  so that it will be run every time (the command cannot be
4157              called ALL).
4158
4159       BYPRODUCTS
4160              Specify the files the command is expected to produce  but  whose
4161              modification  time  may  or  may  not  be  updated on subsequent
4162              builds.  If a byproduct name is  a  relative  path  it  will  be
4163              interpreted  relative  to the build tree directory corresponding
4164              to the current source directory.  Each byproduct  file  will  be
4165              marked with the GENERATED source file property automatically.
4166
4167              Explicit  specification  of byproducts is supported by the Ninja
4168              generator to tell the ninja build tool how to regenerate byprod‐
4169              ucts  when they are missing.  It is also useful when other build
4170              rules (e.g. custom commands) depend on  the  byproducts.   Ninja
4171              requires  a  build  rule for any generated file on which another
4172              rule depends even if there are order-only dependencies to ensure
4173              the byproducts will be available before their dependents build.
4174
4175              The  BYPRODUCTS option is ignored on non-Ninja generators except
4176              to mark byproducts GENERATED.
4177
4178       COMMAND
4179              Specify the command-line(s) to execute at build time.   If  more
4180              than  one  COMMAND  is specified they will be executed in order,
4181              but not necessarily composed into  a  stateful  shell  or  batch
4182              script.  (To run a full script, use the configure_file() command
4183              or the file(GENERATE) command to create it, and then  specify  a
4184              COMMAND to launch it.)
4185
4186              If  COMMAND  specifies an executable target name (created by the
4187              add_executable() command) it will automatically be  replaced  by
4188              the  location  of  the executable created at build time. If set,
4189              the CROSSCOMPILING_EMULATOR executable target property will also
4190              be  prepended  to  the command to allow the executable to run on
4191              the host.  Additionally a target-level dependency will be  added
4192              so  that  the executable target will be built before this custom
4193              target.
4194
4195              Arguments to COMMAND may use generator expressions.   References
4196              to  target  names  in  generator  expressions imply target-level
4197              dependencies.
4198
4199              The command and arguments are optional and if not  specified  an
4200              empty target will be created.
4201
4202       COMMENT
4203              Display  the  given  message before the commands are executed at
4204              build time.
4205
4206       DEPENDS
4207              Reference files and outputs  of  custom  commands  created  with
4208              add_custom_command() command calls in the same directory (CMake‐
4209              Lists.txt file).  They will be brought up to date when the  tar‐
4210              get is built.
4211
4212              Use  the add_dependencies() command to add dependencies on other
4213              targets.
4214
4215       COMMAND_EXPAND_LISTS
4216              Lists in COMMAND arguments will  be  expanded,  including  those
4217              created  with  generator expressions, allowing COMMAND arguments
4218              such as  ${CC}  "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
4219              RIES>,;-I>" foo.cc to be properly expanded.
4220
4221       SOURCES
4222              Specify  additional  source  files  to be included in the custom
4223              target.  Specified source files will be  added  to  IDE  project
4224              files  for  convenience  in  editing  even if they have no build
4225              rules.
4226
4227       VERBATIM
4228              All arguments to the commands will be escaped properly  for  the
4229              build  tool  so  that the invoked command receives each argument
4230              unchanged.  Note that one level of escapes is still used by  the
4231              CMake  language processor before add_custom_target even sees the
4232              arguments.  Use of VERBATIM is recommended as it enables correct
4233              behavior.   When  VERBATIM is not given the behavior is platform
4234              specific because there is no protection of tool-specific special
4235              characters.
4236
4237       USES_TERMINAL
4238              The  command will be given direct access to the terminal if pos‐
4239              sible.  With the Ninja generator, this places the command in the
4240              console pool.
4241
4242       WORKING_DIRECTORY
4243              Execute  the  command  with the given current working directory.
4244              If it is a relative path it will be interpreted relative to  the
4245              build  tree directory corresponding to the current source direc‐
4246              tory.
4247
4248              Arguments to WORKING_DIRECTORY may use generator expressions.
4249
4250   add_definitions
4251       Add -D define flags to the compilation of source files.
4252
4253          add_definitions(-DFOO -DBAR ...)
4254
4255       Adds definitions to the compiler command line for targets in  the  cur‐
4256       rent directory and below (whether added before or after this command is
4257       invoked).  This command can be  used  to  add  any  flags,  but  it  is
4258       intended to add preprocessor definitions.
4259
4260       NOTE:
4261          This command has been superseded by alternatives:
4262
4263          · Use add_compile_definitions() to add preprocessor definitions.
4264
4265          · Use include_directories() to add include directories.
4266
4267          · Use add_compile_options() to add other options.
4268
4269       Flags beginning in -D or /D that look like preprocessor definitions are
4270       automatically added to the COMPILE_DEFINITIONS directory  property  for
4271       the current directory.  Definitions with non-trivial values may be left
4272       in the set of flags instead of being converted for reasons of backwards
4273       compatibility.  See documentation of the directory, target, source file
4274       COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
4275       nitions to specific scopes and configurations.
4276
4277       See  the  cmake-buildsystem(7)  manual for more on defining buildsystem
4278       properties.
4279
4280   add_dependencies
4281       Add a dependency between top-level targets.
4282
4283          add_dependencies(<target> [<target-dependency>]...)
4284
4285       Makes a top-level <target> depend on other top-level targets to  ensure
4286       that  they  build before <target> does.  A top-level target is one cre‐
4287       ated by one of the add_executable(), add_library(), or  add_custom_tar‐
4288       get() commands (but not targets generated by CMake like install).
4289
4290       Dependencies  added  to  an imported target or an interface library are
4291       followed transitively in its place since the  target  itself  does  not
4292       build.
4293
4294       See  the DEPENDS option of add_custom_target() and add_custom_command()
4295       commands for adding file-level dependencies in custom rules.   See  the
4296       OBJECT_DEPENDS  source  file property to add file-level dependencies to
4297       object files.
4298
4299   add_executable
4300       Add an executable to the project using the specified source files.
4301
4302          add_executable(<name> [WIN32] [MACOSX_BUNDLE]
4303                         [EXCLUDE_FROM_ALL]
4304                         [source1] [source2 ...])
4305
4306       Adds an executable target called <name> to be  built  from  the  source
4307       files listed in the command invocation.  (The source files can be omit‐
4308       ted here if they are added later using target_sources().)   The  <name>
4309       corresponds  to  the  logical  target  name and must be globally unique
4310       within a project.  The actual file name of the executable built is con‐
4311       structed   based  on  conventions  of  the  native  platform  (such  as
4312       <name>.exe or just <name>).
4313
4314       By default the executable file will be created in the build tree direc‐
4315       tory  corresponding  to  the source tree directory in which the command
4316       was invoked.  See documentation of the RUNTIME_OUTPUT_DIRECTORY  target
4317       property to change this location.  See documentation of the OUTPUT_NAME
4318       target property to change the <name> part of the final file name.
4319
4320       If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
4321       get created.  See documentation of that target property for details.
4322
4323       If MACOSX_BUNDLE is given the corresponding property will be set on the
4324       created target.  See documentation of the MACOSX_BUNDLE target property
4325       for details.
4326
4327       If  EXCLUDE_FROM_ALL is given the corresponding property will be set on
4328       the created target.  See documentation of the  EXCLUDE_FROM_ALL  target
4329       property for details.
4330
4331       Source arguments to add_executable may use “generator expressions” with
4332       the syntax $<...>.  See the cmake-generator-expressions(7)  manual  for
4333       available expressions.  See the cmake-buildsystem(7) manual for more on
4334       defining buildsystem properties.
4335
4336       See also HEADER_FILE_ONLY on what to do if some  sources  are  pre-pro‐
4337       cessed, and you want to have the original sources reachable from within
4338       IDE.
4339
4340
4341                                        ----
4342
4343
4344
4345          add_executable(<name> IMPORTED [GLOBAL])
4346
4347       An IMPORTED executable target references  an  executable  file  located
4348       outside  the  project.   No  rules  are  generated to build it, and the
4349       IMPORTED target property is True.  The target name  has  scope  in  the
4350       directory  in  which  it  is  created  and below, but the GLOBAL option
4351       extends visibility.  It may be referenced like any target built  within
4352       the  project.  IMPORTED executables are useful for convenient reference
4353       from commands like add_custom_command().  Details  about  the  imported
4354       executable  are  specified  by  setting properties whose names begin in
4355       IMPORTED_.  The most important such property is IMPORTED_LOCATION  (and
4356       its  per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
4357       fies the location of the main executable file on disk.  See  documenta‐
4358       tion of the IMPORTED_* properties for more information.
4359
4360
4361                                        ----
4362
4363
4364
4365          add_executable(<name> ALIAS <target>)
4366
4367       Creates an Alias Target, such that <name> can be used to refer to <tar‐
4368       get> in subsequent commands.  The <name> does not appear in the  gener‐
4369       ated  buildsystem  as  a  make  target.   The  <target>  may  not  be a
4370       non-GLOBAL Imported Target or an ALIAS.  ALIAS targets can be  used  as
4371       targets  to  read  properties from, executables for custom commands and
4372       custom targets.  They can also be tested for existence with the regular
4373       if(TARGET) subcommand.  The <name> may not be used to modify properties
4374       of <target>, that is, it may not be used as the  operand  of  set_prop‐
4375       erty(), set_target_properties(), target_link_libraries() etc.  An ALIAS
4376       target may not be installed or exported.
4377
4378   add_library
4379       Add a library to the project using the specified source files.
4380
4381   Normal Libraries
4382          add_library(<name> [STATIC | SHARED | MODULE]
4383                      [EXCLUDE_FROM_ALL]
4384                      [source1] [source2 ...])
4385
4386       Adds a library target called <name> to be built from the  source  files
4387       listed  in  the  command  invocation.  (The source files can be omitted
4388       here if they are added later using target_sources().)  The <name>  cor‐
4389       responds  to the logical target name and must be globally unique within
4390       a project.  The actual file name of the library  built  is  constructed
4391       based  on  conventions  of  the native platform (such as lib<name>.a or
4392       <name>.lib).
4393
4394       STATIC, SHARED, or MODULE may be given to specify the type  of  library
4395       to  be  created.  STATIC libraries are archives of object files for use
4396       when linking other targets.  SHARED libraries  are  linked  dynamically
4397       and  loaded  at  runtime.   MODULE  libraries  are plugins that are not
4398       linked into other targets but may  be  loaded  dynamically  at  runtime
4399       using  dlopen-like  functionality.   If no type is given explicitly the
4400       type is STATIC or SHARED based on whether  the  current  value  of  the
4401       variable  BUILD_SHARED_LIBS is ON.  For SHARED and MODULE libraries the
4402       POSITION_INDEPENDENT_CODE target property is set to  ON  automatically.
4403       A  SHARED  or  STATIC  library  may be marked with the FRAMEWORK target
4404       property to create an macOS Framework.
4405
4406       If a library does not export any symbols, it must not be declared as  a
4407       SHARED  library.   For  example,  a  Windows  resource DLL or a managed
4408       C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
4409       library.  This is because CMake expects a SHARED library to always have
4410       an associated import library on Windows.
4411
4412       By default the library file will be created in the build tree directory
4413       corresponding  to  the  source  tree directory in which the command was
4414       invoked.    See   documentation   of   the    ARCHIVE_OUTPUT_DIRECTORY,
4415       LIBRARY_OUTPUT_DIRECTORY,  and  RUNTIME_OUTPUT_DIRECTORY target proper‐
4416       ties to change this location.  See  documentation  of  the  OUTPUT_NAME
4417       target property to change the <name> part of the final file name.
4418
4419       If  EXCLUDE_FROM_ALL is given the corresponding property will be set on
4420       the created target.  See documentation of the  EXCLUDE_FROM_ALL  target
4421       property for details.
4422
4423       Source  arguments  to  add_library may use “generator expressions” with
4424       the syntax $<...>.  See the cmake-generator-expressions(7)  manual  for
4425       available expressions.  See the cmake-buildsystem(7) manual for more on
4426       defining buildsystem properties.
4427
4428       See also HEADER_FILE_ONLY on what to do if some  sources  are  pre-pro‐
4429       cessed, and you want to have the original sources reachable from within
4430       IDE.
4431
4432   Imported Libraries
4433          add_library(<name> <SHARED|STATIC|MODULE|OBJECT|UNKNOWN> IMPORTED
4434                      [GLOBAL])
4435
4436       An IMPORTED library target references a library  file  located  outside
4437       the project.  No rules are generated to build it, and the IMPORTED tar‐
4438       get property is True.  The target name has scope in  the  directory  in
4439       which  it  is created and below, but the GLOBAL option extends visibil‐
4440       ity.  It may be referenced like any target built  within  the  project.
4441       IMPORTED  libraries  are  useful for convenient reference from commands
4442       like target_link_libraries().  Details about the imported  library  are
4443       specified  by  setting  properties  whose  names begin in IMPORTED_ and
4444       INTERFACE_.  The most important such property is IMPORTED_LOCATION (and
4445       its  per-configuration variant IMPORTED_LOCATION_<CONFIG>) which speci‐
4446       fies the location of the main library file on  disk.   Or,  for  object
4447       libraries,  IMPORTED_OBJECTS  (and IMPORTED_OBJECTS_<CONFIG>) specifies
4448       the locations of object  files  on  disk.   See  documentation  of  the
4449       IMPORTED_* and INTERFACE_* properties for more information.
4450
4451   Object Libraries
4452          add_library(<name> OBJECT <src>...)
4453
4454       Creates an Object Library.  An object library compiles source files but
4455       does not archive or link their object files into  a  library.   Instead
4456       other  targets  created by add_library() or add_executable() may refer‐
4457       ence  the  objects   using   an   expression   of   the   form   $<TAR‐
4458       GET_OBJECTS:objlib>  as  a  source,  where objlib is the object library
4459       name.  For example:
4460
4461          add_library(... $<TARGET_OBJECTS:objlib> ...)
4462          add_executable(... $<TARGET_OBJECTS:objlib> ...)
4463
4464       will include objlib’s object files in a library and an executable along
4465       with  those compiled from their own sources.  Object libraries may con‐
4466       tain only sources that compile, header  files,  and  other  files  that
4467       would  not  affect  linking  of a normal library (e.g. .txt).  They may
4468       contain custom commands generating such  sources,  but  not  PRE_BUILD,
4469       PRE_LINK,  or  POST_BUILD commands.  Some native build systems (such as
4470       Xcode) may not like targets that have only object  files,  so  consider
4471       adding  at  least  one  real  source file to any target that references
4472       $<TARGET_OBJECTS:objlib>.
4473
4474   Alias Libraries
4475          add_library(<name> ALIAS <target>)
4476
4477       Creates an Alias Target, such that <name> can be used to refer to <tar‐
4478       get>  in subsequent commands.  The <name> does not appear in the gener‐
4479       ated buildsystem  as  a  make  target.   The  <target>  may  not  be  a
4480       non-GLOBAL  Imported  Target or an ALIAS.  ALIAS targets can be used as
4481       linkable targets and as targets to read properties from.  They can also
4482       be  tested  for  existence with the regular if(TARGET) subcommand.  The
4483       <name> may not be used to modify properties of <target>,  that  is,  it
4484       may  not  be  used as the operand of set_property(), set_target_proper‐
4485       ties(), target_link_libraries()  etc.   An  ALIAS  target  may  not  be
4486       installed or exported.
4487
4488   Interface Libraries
4489          add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
4490
4491       Creates  an  Interface  Library.   An INTERFACE library target does not
4492       directly create build output, though it may have properties set  on  it
4493       and  it  may  be installed, exported and imported. Typically the INTER‐
4494       FACE_* properties are populated on the interface target using the  com‐
4495       mands:
4496
4497       · set_property(),
4498
4499       · target_link_libraries(INTERFACE),
4500
4501       · target_link_options(INTERFACE),
4502
4503       · target_include_directories(INTERFACE),
4504
4505       · target_compile_options(INTERFACE),
4506
4507       · target_compile_definitions(INTERFACE), and
4508
4509       · target_sources(INTERFACE),
4510
4511       and  then it is used as an argument to target_link_libraries() like any
4512       other target.
4513
4514       An INTERFACE Imported Target may also be created with  this  signature.
4515       An  IMPORTED  library  target  references a library defined outside the
4516       project.  The target name has scope in the directory  in  which  it  is
4517       created and below, but the GLOBAL option extends visibility.  It may be
4518       referenced  like  any  target  built  within  the  project.    IMPORTED
4519       libraries  are  useful for convenient reference from commands like tar‐
4520       get_link_libraries().
4521
4522   add_link_options
4523       Add options to the link of shared library, module and  executable  tar‐
4524       gets.
4525
4526          add_link_options(<option> ...)
4527
4528       Adds  options to the link step for targets in the current directory and
4529       below that are added after this command is invoked.  See  documentation
4530       of the directory and target LINK_OPTIONS properties.
4531
4532       This  command  can be used to add any options, but alternative commands
4533       exist to add libraries (target_link_libraries() or link_libraries()).
4534
4535       Arguments to add_link_options may use “generator expressions” with  the
4536       syntax  $<...>.   See  the  cmake-generator-expressions(7)  manual  for
4537       available expressions.  See the cmake-buildsystem(7) manual for more on
4538       defining buildsystem properties.
4539
4540       The  final  set  of  compile  or link options used for a target is con‐
4541       structed by accumulating options from the current target and the  usage
4542       requirements  of  it dependencies.  The set of options is de-duplicated
4543       to avoid repetition.  While  beneficial  for  individual  options,  the
4544       de-duplication step can break up option groups.  For example, -D A -D B
4545       becomes -D A B.  One may specify a group of  options  using  shell-like
4546       quoting  along  with a SHELL: prefix.  The SHELL: prefix is dropped and
4547       the rest of the option string is parsed using the  separate_arguments()
4548       UNIX_COMMAND mode.  For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
4549       -D B.
4550
4551       To pass options to the linker tool, each compiler  driver  has  is  own
4552       syntax.   The LINKER: prefix can be used to specify, in a portable way,
4553       options to pass to the linker tool. The LINKER: prefix is  replaced  by
4554       the  required  driver  option and the rest of the option string defines
4555       linker arguments using , as separator. These arguments will be  format‐
4556       ted    according    to    the    CMAKE_<LANG>_LINKER_WRAPPER_FLAG   and
4557       CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
4558
4559       For example, "LINKER:-z,defs" becomes -Xlinker  -z  -Xlinker  defs  for
4560       Clang and -Wl,-z,defs for GNU GCC.
4561
4562       The  LINKER: prefix can be specified as part of a SHELL: prefix expres‐
4563       sion.
4564
4565       The LINKER: prefix supports,  as  alternate  syntax,  specification  of
4566       arguments  using SHELL: prefix and space as separator. Previous example
4567       becomes "LINKER:SHELL:-z defs".
4568
4569       NOTE:
4570          Specifying SHELL: prefix elsewhere than  at  the  beginning  of  the
4571          LINKER: prefix is not supported.
4572
4573   add_subdirectory
4574       Add a subdirectory to the build.
4575
4576          add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])
4577
4578       Adds  a subdirectory to the build.  The source_dir specifies the direc‐
4579       tory in which the source CMakeLists.txt and code files are located.  If
4580       it  is a relative path it will be evaluated with respect to the current
4581       directory (the typical usage), but it may also  be  an  absolute  path.
4582       The  binary_dir  specifies  the  directory in which to place the output
4583       files.  If it is a relative path it will be evaluated with  respect  to
4584       the  current output directory, but it may also be an absolute path.  If
4585       binary_dir is not specified, the value of source_dir, before  expanding
4586       any  relative  path,  will  be  used  (the  typical usage).  The CMake‐
4587       Lists.txt file in the specified  source  directory  will  be  processed
4588       immediately  by  CMake before processing in the current input file con‐
4589       tinues beyond this command.
4590
4591       If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
4592       rectory  will not be included in the ALL target of the parent directory
4593       by default, and will be excluded from IDE project  files.   Users  must
4594       explicitly  build  targets  in the subdirectory.  This is meant for use
4595       when the subdirectory contains a separate part of the project  that  is
4596       useful  but  not  necessary,  such as a set of examples.  Typically the
4597       subdirectory should contain its own  project()  command  invocation  so
4598       that a full build system will be generated in the subdirectory (such as
4599       a VS IDE solution file).  Note that inter-target dependencies supersede
4600       this  exclusion.   If a target built by the parent project depends on a
4601       target in the subdirectory, the dependee target will be included in the
4602       parent project build system to satisfy the dependency.
4603
4604   add_test
4605       Add a test to the project to be run by ctest(1).
4606
4607          add_test(NAME <name> COMMAND <command> [<arg>...]
4608                   [CONFIGURATIONS <config>...]
4609                   [WORKING_DIRECTORY <dir>])
4610
4611       Adds  a  test  called  <name>.   The  test name may not contain spaces,
4612       quotes, or other characters special in CMake syntax.  The options are:
4613
4614       COMMAND
4615              Specify the test command-line.  If <command> specifies  an  exe‐
4616              cutable  target  (created by add_executable()) it will automati‐
4617              cally be replaced by the location of the executable  created  at
4618              build time.
4619
4620       CONFIGURATIONS
4621              Restrict execution of the test only to the named configurations.
4622
4623       WORKING_DIRECTORY
4624              Set  the  WORKING_DIRECTORY test property to specify the working
4625              directory in which to execute the test.  If  not  specified  the
4626              test  will  be run with the current working directory set to the
4627              build directory corresponding to the current source directory.
4628
4629       The given test command is expected to exit with  code  0  to  pass  and
4630       non-zero  to fail, or vice-versa if the WILL_FAIL test property is set.
4631       Any output written to stdout or stderr will be captured by ctest(1) but
4632       does not affect the pass/fail status unless the PASS_REGULAR_EXPRESSION
4633       or FAIL_REGULAR_EXPRESSION test property is used.
4634
4635       The COMMAND and WORKING_DIRECTORY options may  use  “generator  expres‐
4636       sions”  with the syntax $<...>.  See the cmake-generator-expressions(7)
4637       manual for available expressions.
4638
4639       Example usage:
4640
4641          add_test(NAME mytest
4642                   COMMAND testDriver --config $<CONFIGURATION>
4643                                      --exe $<TARGET_FILE:myexe>)
4644
4645       This creates a test mytest whose command runs a testDriver tool passing
4646       the  configuration  name  and the full path to the executable file pro‐
4647       duced by target myexe.
4648
4649       NOTE:
4650          CMake will generate tests only if the enable_testing()  command  has
4651          been  invoked.   The  CTest module invokes the command automatically
4652          when the BUILD_TESTING option is ON.
4653
4654
4655                                        ----
4656
4657
4658
4659          add_test(<name> <command> [<arg>...])
4660
4661       Add a test called <name> with the given command-line.  Unlike the above
4662       NAME  signature  no  transformation is performed on the command-line to
4663       support target names or generator expressions.
4664
4665   aux_source_directory
4666       Find all source files in a directory.
4667
4668          aux_source_directory(<dir> <variable>)
4669
4670       Collects the names of all the source files in the  specified  directory
4671       and  stores  the  list  in  the  <variable>  provided.  This command is
4672       intended to be used by projects that use explicit  template  instantia‐
4673       tion.  Template instantiation files can be stored in a “Templates” sub‐
4674       directory and collected automatically using this command to avoid manu‐
4675       ally listing all instantiations.
4676
4677       It  is tempting to use this command to avoid writing the list of source
4678       files for a library or executable target.  While this  seems  to  work,
4679       there  is no way for CMake to generate a build system that knows when a
4680       new source file has been added.  Normally the  generated  build  system
4681       knows  when  it needs to rerun CMake because the CMakeLists.txt file is
4682       modified to add a new source.  When the source is  just  added  to  the
4683       directory without modifying this file, one would have to manually rerun
4684       CMake to generate a build system incorporating the new file.
4685
4686   build_command
4687       Get a command line to  build  the  current  project.   This  is  mainly
4688       intended for internal use by the CTest module.
4689
4690          build_command(<variable>
4691                        [CONFIGURATION <config>]
4692                        [TARGET <target>]
4693                        [PROJECT_NAME <projname>] # legacy, causes warning
4694                       )
4695
4696       Sets the given <variable> to a command-line string of the form:
4697
4698          <cmake> --build . [--config <config>] [--target <target>] [-- -i]
4699
4700       where  <cmake>  is  the location of the cmake(1) command-line tool, and
4701       <config> and <target> are the values provided to the CONFIGURATION  and
4702       TARGET  options,  if any.  The trailing -- -i option is added for Make‐
4703       file Generators if policy CMP0061 is not set to NEW.
4704
4705       When invoked, this cmake --build command line will launch the  underly‐
4706       ing build system tool.
4707
4708          build_command(<cachevariable> <makecommand>)
4709
4710       This  second signature is deprecated, but still available for backwards
4711       compatibility.  Use the first signature instead.
4712
4713       It sets the given <cachevariable> to a command-line string as above but
4714       without  the  --target option.  The <makecommand> is ignored but should
4715       be the full path to devenv, nmake, make or one of the  end  user  build
4716       tools for legacy invocations.
4717
4718       NOTE:
4719          In  CMake versions prior to 3.0 this command returned a command line
4720          that directly invokes the native build tool for the current  genera‐
4721          tor.   Their implementation of the PROJECT_NAME option had no useful
4722          effects, so CMake now warns on use of the option.
4723
4724   create_test_sourcelist
4725       Create a test driver and source list for building test programs.
4726
4727          create_test_sourcelist(sourceListName driverName
4728                                 test1 test2 test3
4729                                 EXTRA_INCLUDE include.h
4730                                 FUNCTION function)
4731
4732       A test driver is a program that links together many small tests into  a
4733       single  executable.   This  is  useful when building static executables
4734       with large libraries to shrink the total required size.   The  list  of
4735       source files needed to build the test driver will be in sourceListName.
4736       driverName is the name of the test driver program.   The  rest  of  the
4737       arguments consist of a list of test source files, can be semicolon sep‐
4738       arated.  Each test source file should have a function in it that is the
4739       same  name  as  the  file  with  no  extension (foo.cxx should have int
4740       foo(int, char*[]);) driverName will be able to call each of  the  tests
4741       by  name  on the command line.  If EXTRA_INCLUDE is specified, then the
4742       next argument is included into the  generated  file.   If  FUNCTION  is
4743       specified,  then  the next argument is taken as a function name that is
4744       passed a pointer to ac and av.  This can be used to add  extra  command
4745       line  processing  to  each  test.  The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
4746       cmake variable can be set to have code that  will  be  placed  directly
4747       before calling the test main function.  CMAKE_TESTDRIVER_AFTER_TESTMAIN
4748       can be set to have code that will be placed directly after the call  to
4749       the test main function.
4750
4751   define_property
4752       Define and document custom properties.
4753
4754          define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
4755                           TEST | VARIABLE | CACHED_VARIABLE>
4756                           PROPERTY <name> [INHERITED]
4757                           BRIEF_DOCS <brief-doc> [docs...]
4758                           FULL_DOCS <full-doc> [docs...])
4759
4760       Defines  one  property  in  a scope for use with the set_property() and
4761       get_property() commands.  This is primarily useful to  associate  docu‐
4762       mentation  with property names that may be retrieved with the get_prop‐
4763       erty() command. The first argument determines  the  kind  of  scope  in
4764       which the property should be used.  It must be one of the following:
4765
4766          GLOBAL    = associated with the global namespace
4767          DIRECTORY = associated with one directory
4768          TARGET    = associated with one target
4769          SOURCE    = associated with one source file
4770          TEST      = associated with a test named with add_test
4771          VARIABLE  = documents a CMake language variable
4772          CACHED_VARIABLE = documents a CMake cache variable
4773
4774       Note  that  unlike  set_property()  and  get_property() no actual scope
4775       needs to be given; only the kind of scope is important.
4776
4777       The required PROPERTY option is immediately followed by the name of the
4778       property being defined.
4779
4780       If  the INHERITED option is given, then the get_property() command will
4781       chain up to the next higher scope when the requested  property  is  not
4782       set in the scope given to the command.
4783
4784       · DIRECTORY  scope  chains  to its parent directory’s scope, continuing
4785         the walk up parent directories until a directory has the property set
4786         or  there  are  no more parents.  If still not found at the top level
4787         directory, it chains to the GLOBAL scope.
4788
4789       · TARGET, SOURCE and TEST properties chain to DIRECTORY scope,  includ‐
4790         ing further chaining up the directories, etc. as needed.
4791
4792       Note  that  this  scope  chaining  behavior  only  applies  to calls to
4793       get_property(),    get_directory_property(),     get_target_property(),
4794       get_source_file_property() and get_test_property().  There is no inher‐
4795       iting  behavior  when  setting   properties,   so   using   APPEND   or
4796       APPEND_STRING  with the set_property() command will not consider inher‐
4797       ited values when working out the contents to append to.
4798
4799       The BRIEF_DOCS and FULL_DOCS options are  followed  by  strings  to  be
4800       associated with the property as its brief and full documentation.  Cor‐
4801       responding options to the get_property() command will retrieve the doc‐
4802       umentation.
4803
4804   enable_language
4805       Enable a language (CXX/C/Fortran/etc)
4806
4807          enable_language(<lang> [OPTIONAL] )
4808
4809       Enables  support  for the named language in CMake.  This is the same as
4810       the project() command but does not create any of  the  extra  variables
4811       that are created by the project command.  Example languages are CXX, C,
4812       CUDA, Fortran, and ASM.
4813
4814       If enabling ASM, enable it last so that CMake can check whether compil‐
4815       ers for other languages like C work for assembly too.
4816
4817       This  command  must  be  called  in file scope, not in a function call.
4818       Furthermore, it must be called in the highest directory common  to  all
4819       targets  using  the  named  language  directly for compiling sources or
4820       indirectly through link dependencies.  It is  simplest  to  enable  all
4821       needed languages in the top-level directory of a project.
4822
4823       The  OPTIONAL  keyword  is  a placeholder for future implementation and
4824       does not currently work. Instead you can use the  CheckLanguage  module
4825       to verify support before enabling.
4826
4827   enable_testing
4828       Enable testing for current directory and below.
4829
4830          enable_testing()
4831
4832       Enables  testing for this directory and below.  See also the add_test()
4833       command.  Note that ctest expects to find a  test  file  in  the  build
4834       directory root.  Therefore, this command should be in the source direc‐
4835       tory root.
4836
4837   export
4838       Export targets from the build tree for use by outside projects.
4839
4840          export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>])
4841
4842       Creates a file <filename> that may be included by outside  projects  to
4843       import  targets  from the current project’s build tree.  This is useful
4844       during cross-compiling to build utility executables that can run on the
4845       host  platform in one project and then import them into another project
4846       being compiled for the target platform.  If  the  NAMESPACE  option  is
4847       given  the  <namespace>  string  will  be prepended to all target names
4848       written to the file.
4849
4850       Target installations are associated with the export <export-name> using
4851       the EXPORT option of the install(TARGETS) command.
4852
4853       The  file  created  by  this  command is specific to the build tree and
4854       should never be installed.  See the install(EXPORT) command  to  export
4855       targets from an installation tree.
4856
4857       The properties set on the generated IMPORTED targets will have the same
4858       values as the final values of the input TARGETS.
4859
4860          export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
4861                 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
4862
4863       This signature is similar to the  EXPORT  signature,  but  targets  are
4864       listed  explicitly  rather  than  specified  as an export-name.  If the
4865       APPEND option is given the generated code will be appended to the  file
4866       instead  of  overwriting  it.  The EXPORT_LINK_INTERFACE_LIBRARIES key‐
4867       word, if present,  causes  the  contents  of  the  properties  matching
4868       (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?  to  be exported, when
4869       policy CMP0022 is NEW.  If a library target is included in  the  export
4870       but a target to which it links is not included the behavior is unspeci‐
4871       fied.
4872
4873       NOTE:
4874          Object Libraries under  Xcode  have  special  handling  if  multiple
4875          architectures  are  listed in CMAKE_OSX_ARCHITECTURES.  In this case
4876          they will be exported as Interface Libraries with  no  object  files
4877          available  to  clients.   This  is  sufficient to satisfy transitive
4878          usage  requirements  of  other  targets  that  link  to  the  object
4879          libraries in their implementation.
4880
4881          export(PACKAGE <PackageName>)
4882
4883       Store  the  current  build directory in the CMake user package registry
4884       for package <PackageName>.  The find_package command may  consider  the
4885       directory while searching for package <PackageName>.  This helps depen‐
4886       dent projects find and use a package from the current  project’s  build
4887       tree  without  help  from the user.  Note that the entry in the package
4888       registry that this command creates works only  in  conjunction  with  a
4889       package  configuration file (<PackageName>Config.cmake) that works with
4890       the build tree. In some cases, for example for packaging and for system
4891       wide  installations, it is not desirable to write the user package reg‐
4892       istry. If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable is enabled, the
4893       export(PACKAGE) command will do nothing.
4894
4895          export(TARGETS [target1 [target2 [...]]]  [ANDROID_MK <filename>])
4896
4897       This  signature  exports  cmake  built targets to the android ndk build
4898       system by creating an Android.mk file that references the prebuilt tar‐
4899       gets.  The  Android  NDK  supports  the use of prebuilt libraries, both
4900       static and shared.  This allows cmake  to  build  the  libraries  of  a
4901       project  and  make  them available to an ndk build system complete with
4902       transitive dependencies, include flags and defines required to use  the
4903       libraries.  The  signature takes a list of targets and puts them in the
4904       Android.mk file specified by the <filename> given. This  signature  can
4905       only  be  used  if policy CMP0022 is NEW for all targets given. A error
4906       will be issued if that policy is set to OLD for one of the targets.
4907
4908   fltk_wrap_ui
4909       Create FLTK user interfaces Wrappers.
4910
4911          fltk_wrap_ui(resultingLibraryName source1
4912                       source2 ... sourceN )
4913
4914       Produce .h and .cxx files for all the .fl and .fld files  listed.   The
4915       resulting  .h  and .cxx files will be added to a variable named result‐
4916       ingLibraryName_FLTK_UI_SRCS which should be added to your library.
4917
4918   get_source_file_property
4919       Get a property for a source file.
4920
4921          get_source_file_property(VAR file property)
4922
4923       Gets a property from a source file.   The  value  of  the  property  is
4924       stored  in  the variable VAR.  If the source property is not found, the
4925       behavior depends on whether it has been  defined  to  be  an  INHERITED
4926       property or not (see define_property()).  Non-inherited properties will
4927       set VAR to “NOTFOUND”, whereas inherited  properties  will  search  the
4928       relevant  parent  scope  as described for the define_property() command
4929       and if still unable to find the property, VAR will be set to  an  empty
4930       string.
4931
4932       Use  set_source_files_properties() to set property values.  Source file
4933       properties usually control how the file is built. One property that  is
4934       always there is LOCATION.
4935
4936       See also the more general get_property() command.
4937
4938   get_target_property
4939       Get a property from a target.
4940
4941          get_target_property(VAR target property)
4942
4943       Get  a  property from a target.  The value of the property is stored in
4944       the variable VAR.  If the target property is not  found,  the  behavior
4945       depends  on  whether it has been defined to be an INHERITED property or
4946       not (see define_property()).  Non-inherited properties will set VAR  to
4947       “NOTFOUND”,  whereas inherited properties will search the relevant par‐
4948       ent scope as described for the define_property() command and  if  still
4949       unable to find the property, VAR will be set to an empty string.
4950
4951       Use  set_target_properties() to set target property values.  Properties
4952       are usually used to control how a target is built, but some  query  the
4953       target  instead.  This command can get properties for any target so far
4954       created.  The targets do not need to be in the  current  CMakeLists.txt
4955       file.
4956
4957       See also the more general get_property() command.
4958
4959       See Target Properties for the list of properties known to CMake.
4960
4961   get_test_property
4962       Get a property of the test.
4963
4964          get_test_property(test property VAR)
4965
4966       Get  a  property from the test.  The value of the property is stored in
4967       the variable VAR.  If the test property  is  not  found,  the  behavior
4968       depends  on  whether it has been defined to be an INHERITED property or
4969       not (see define_property()).  Non-inherited properties will set VAR  to
4970       “NOTFOUND”,  whereas inherited properties will search the relevant par‐
4971       ent scope as described for the define_property() command and  if  still
4972       unable to find the property, VAR will be set to an empty string.
4973
4974       For  a  list  of  standard  properties  you can type cmake --help-prop‐
4975       erty-list.
4976
4977       See also the more general get_property() command.
4978
4979   include_directories
4980       Add include directories to the build.
4981
4982          include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
4983
4984       Add the given directories to those the  compiler  uses  to  search  for
4985       include  files.  Relative paths are interpreted as relative to the cur‐
4986       rent source directory.
4987
4988       The include directories are added to the INCLUDE_DIRECTORIES  directory
4989       property  for  the current CMakeLists file.  They are also added to the
4990       INCLUDE_DIRECTORIES target property for  each  target  in  the  current
4991       CMakeLists  file.   The target property values are the ones used by the
4992       generators.
4993
4994       By default the directories specified are appended onto the current list
4995       of  directories.   This  default  behavior  can  be  changed by setting
4996       CMAKE_INCLUDE_DIRECTORIES_BEFORE to  ON.   By  using  AFTER  or  BEFORE
4997       explicitly,  you  can select between appending and prepending, indepen‐
4998       dent of the default.
4999
5000       If the SYSTEM option is given, the compiler will be told  the  directo‐
5001       ries  are  meant as system include directories on some platforms.  Sig‐
5002       nalling this setting might achieve effects such as the  compiler  skip‐
5003       ping warnings, or these fixed-install system files not being considered
5004       in dependency calculations - see compiler docs.
5005
5006       Arguments to include_directories may use “generator  expressions”  with
5007       the  syntax  “$<…>”.  See the cmake-generator-expressions(7) manual for
5008       available expressions.  See the cmake-buildsystem(7) manual for more on
5009       defining buildsystem properties.
5010
5011       NOTE:
5012          Prefer  the  target_include_directories()  command  to  add  include
5013          directories to individual targets  and  optionally  propagate/export
5014          them to dependents.
5015
5016   include_external_msproject
5017       Include an external Microsoft project file in a workspace.
5018
5019          include_external_msproject(projectname location
5020                                     [TYPE projectTypeGUID]
5021                                     [GUID projectGUID]
5022                                     [PLATFORM platformName]
5023                                     dep1 dep2 ...)
5024
5025       Includes an external Microsoft project in the generated workspace file.
5026       Currently does nothing on UNIX.  This will create a target named  [pro‐
5027       jectname].   This can be used in the add_dependencies() command to make
5028       things depend on the external project.
5029
5030       TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
5031       ify  the  type of project, id (GUID) of the project and the name of the
5032       target platform.  This is useful for projects  requiring  values  other
5033       than the default (e.g.  WIX projects).
5034
5035       If the imported project has different configuration names than the cur‐
5036       rent project, set the MAP_IMPORTED_CONFIG_<CONFIG> target  property  to
5037       specify the mapping.
5038
5039   include_regular_expression
5040       Set the regular expression used for dependency checking.
5041
5042          include_regular_expression(regex_match [regex_complain])
5043
5044       Sets  the  regular expressions used in dependency checking.  Only files
5045       matching regex_match will be traced as dependencies.  Only files match‐
5046       ing  regex_complain  will  generate  warnings  if  they cannot be found
5047       (standard header paths are not searched).  The defaults are:
5048
5049          regex_match    = "^.*$" (match everything)
5050          regex_complain = "^$" (match empty string only)
5051
5052   install
5053       Specify rules to run at install time.
5054
5055   Synopsis
5056          install(TARGETS <target>... [...])
5057          install({FILES | PROGRAMS} <file>... [...])
5058          install(DIRECTORY <dir>... [...])
5059          install(SCRIPT <file> [...])
5060          install(CODE <code> [...])
5061          install(EXPORT <export-name> [...])
5062
5063   Introduction
5064       This command generates installation rules for a project.  Rules  speci‐
5065       fied by calls to this command within a source directory are executed in
5066       order  during  installation.   The  order  across  directories  is  not
5067       defined.
5068
5069       There  are  multiple  signatures for this command.  Some of them define
5070       installation options for files and targets.  Options common to multiple
5071       signatures are covered here but they are valid only for signatures that
5072       specify them.  The common options are:
5073
5074       DESTINATION
5075              Specify the directory on disk to which a file will be installed.
5076              If  a  full path (with a leading slash or drive letter) is given
5077              it is used directly.  If a relative path is given it  is  inter‐
5078              preted  relative  to the value of the CMAKE_INSTALL_PREFIX vari‐
5079              able.  The prefix can be relocated at  install  time  using  the
5080              DESTDIR mechanism explained in the CMAKE_INSTALL_PREFIX variable
5081              documentation.
5082
5083       PERMISSIONS
5084              Specify permissions for installed files.  Valid permissions  are
5085              OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
5086              GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,  WORLD_EXECUTE,  SETUID,
5087              and SETGID.  Permissions that do not make sense on certain plat‐
5088              forms are ignored on those platforms.
5089
5090       CONFIGURATIONS
5091              Specify a list of build configurations  for  which  the  install
5092              rule applies (Debug, Release, etc.). Note that the values speci‐
5093              fied for this option only apply to options listed AFTER the CON‐
5094              FIGURATIONS  option.  For example, to set separate install paths
5095              for the Debug and Release configurations, do the following:
5096
5097                 install(TARGETS target
5098                         CONFIGURATIONS Debug
5099                         RUNTIME DESTINATION Debug/bin)
5100                 install(TARGETS target
5101                         CONFIGURATIONS Release
5102                         RUNTIME DESTINATION Release/bin)
5103
5104              Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
5105
5106       COMPONENT
5107              Specify an installation component name with  which  the  install
5108              rule  is associated, such as “runtime” or “development”.  During
5109              component-specific installation only  install  rules  associated
5110              with  the  given component name will be executed.  During a full
5111              installation all components are  installed  unless  marked  with
5112              EXCLUDE_FROM_ALL.  If COMPONENT is not provided a default compo‐
5113              nent “Unspecified” is created.  The default component  name  may
5114              be   controlled  with  the  CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
5115              variable.
5116
5117       EXCLUDE_FROM_ALL
5118              Specify that the file is excluded from a full  installation  and
5119              only installed as part of a component-specific installation
5120
5121       RENAME Specify  a name for an installed file that may be different from
5122              the original file.  Renaming is allowed only when a single  file
5123              is installed by the command.
5124
5125       OPTIONAL
5126              Specify that it is not an error if the file to be installed does
5127              not exist.
5128
5129       Command signatures that install files may print messages during instal‐
5130       lation.   Use  the CMAKE_INSTALL_MESSAGE variable to control which mes‐
5131       sages are printed.
5132
5133       Many of the install() variants implicitly create the  directories  con‐
5134       taining the installed files. If CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMIS‐
5135       SIONS is set, these directories will be created  with  the  permissions
5136       specified. Otherwise, they will be created according to the uname rules
5137       on Unix-like platforms.  Windows platforms are unaffected.
5138
5139   Installing Targets
5140          install(TARGETS targets... [EXPORT <export-name>]
5141                  [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
5142                    PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
5143                   [DESTINATION <dir>]
5144                   [PERMISSIONS permissions...]
5145                   [CONFIGURATIONS [Debug|Release|...]]
5146                   [COMPONENT <component>]
5147                   [NAMELINK_COMPONENT <component>]
5148                   [OPTIONAL] [EXCLUDE_FROM_ALL]
5149                   [NAMELINK_ONLY|NAMELINK_SKIP]
5150                  ] [...]
5151                  [INCLUDES DESTINATION [<dir> ...]]
5152                  )
5153
5154       The TARGETS form specifies rules for installing targets from a project.
5155       There are several kinds of target files that may be installed:
5156
5157       ARCHIVE
5158              Static  libraries  are  treated as ARCHIVE targets, except those
5159              marked with the  FRAMEWORK  property  on  macOS  (see  FRAMEWORK
5160              below.)  For  DLL platforms (all Windows-based systems including
5161              Cygwin), the DLL import library is treated as an ARCHIVE target.
5162
5163       LIBRARY
5164              Module libraries are always treated as LIBRARY targets. For non-
5165              DLL  platforms  shared libraries are treated as LIBRARY targets,
5166              except those marked with the FRAMEWORK property  on  macOS  (see
5167              FRAMEWORK below.)
5168
5169       RUNTIME
5170              Executables  are treated as RUNTIME objects, except those marked
5171              with the MACOSX_BUNDLE property on  macOS  (see  BUNDLE  below.)
5172              For  DLL platforms (all Windows-based systems including Cygwin),
5173              the DLL part of a shared library is treated as a RUNTIME target.
5174
5175       OBJECTS
5176              Object libraries (a simple group of  object  files)  are  always
5177              treated as OBJECTS targets.
5178
5179       FRAMEWORK
5180              Both static and shared libraries marked with the FRAMEWORK prop‐
5181              erty are treated as FRAMEWORK targets on macOS.
5182
5183       BUNDLE Executables marked with the MACOSX_BUNDLE property  are  treated
5184              as BUNDLE targets on macOS.
5185
5186       PUBLIC_HEADER
5187              Any  PUBLIC_HEADER files associated with a library are installed
5188              in the destination specified by the  PUBLIC_HEADER  argument  on
5189              non-Apple  platforms. Rules defined by this argument are ignored
5190              for FRAMEWORK libraries on Apple platforms because  the  associ‐
5191              ated  files  are installed into the appropriate locations inside
5192              the framework folder. See PUBLIC_HEADER for details.
5193
5194       PRIVATE_HEADER
5195              Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See PRI‐
5196              VATE_HEADER for details.
5197
5198       RESOURCE
5199              Similar  to  PUBLIC_HEADER  and PRIVATE_HEADER, but for RESOURCE
5200              files. See RESOURCE for details.
5201
5202       For each of these arguments given, the arguments  following  them  only
5203       apply  to the target or file type specified in the argument. If none is
5204       given, the installation properties apply to all target types.  If  only
5205       one  is  given  then only targets of that type will be installed (which
5206       can be used to install just a DLL or just an import library.)
5207
5208       For regular executables, static libraries  and  shared  libraries,  the
5209       DESTINATION  argument  is  not  required.  For these target types, when
5210       DESTINATION is omitted, a default destination will be  taken  from  the
5211       appropriate  variable from GNUInstallDirs, or set to a built-in default
5212       value if that variable is not defined.  The same is true for the public
5213       and  private  headers associated with the installed targets through the
5214       PUBLIC_HEADER and PRIVATE_HEADER target properties.  A destination must
5215       always  be provided for module libraries, Apple bundles and frameworks.
5216       A destination can be omitted for interface and  object  libraries,  but
5217       they  are  handled differently (see the discussion of this topic toward
5218       the end of this section).
5219
5220       The following table shows the target types with their associated  vari‐
5221       ables and built-in defaults that apply when no destination is given:
5222
5223          ┌───────────────┬─────────────────────────────┬──────────────────┐
5224          │Target Type    │ GNUInstallDirs              │ Built-In Default │
5225          │               │ Variable                    │                  │
5226          ├───────────────┼─────────────────────────────┼──────────────────┤
5227RUNTIME        ${CMAKE_INSTALL_BINDIR}     bin              
5228          ├───────────────┼─────────────────────────────┼──────────────────┤
5229LIBRARY        ${CMAKE_INSTALL_LIBDIR}     lib              
5230          ├───────────────┼─────────────────────────────┼──────────────────┤
5231ARCHIVE        ${CMAKE_INSTALL_LIBDIR}     lib              
5232          ├───────────────┼─────────────────────────────┼──────────────────┤
5233PRIVATE_HEADER ${CMAKE_INSTALL_INCLUDEDIR} include          
5234          ├───────────────┼─────────────────────────────┼──────────────────┤
5235PUBLIC_HEADER  ${CMAKE_INSTALL_INCLUDEDIR} include          
5236          └───────────────┴─────────────────────────────┴──────────────────┘
5237
5238       Projects wishing to follow the common practice  of  installing  headers
5239       into a project-specific subdirectory will need to provide a destination
5240       rather than rely on the above.
5241
5242       To make packages compliant with distribution  filesystem  layout  poli‐
5243       cies,  if  projects  must specify a DESTINATION, it is recommended that
5244       they use a path that begins with the appropriate  GNUInstallDirs  vari‐
5245       able.   This allows package maintainers to control the install destina‐
5246       tion by setting the appropriate cache variables.  The following example
5247       shows  a static library being installed to the default destination pro‐
5248       vided  by  GNUInstallDirs,  but  with  its  headers  installed   to   a
5249       project-specific subdirectory that follows the above recommendation:
5250
5251          add_library(mylib STATIC ...)
5252          set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
5253          include(GNUInstallDirs)
5254          install(TARGETS mylib
5255                  PUBLIC_HEADER
5256                    DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
5257          )
5258
5259       In  addition to the common options listed above, each target can accept
5260       the following additional arguments:
5261
5262       NAMELINK_COMPONENT
5263              On some platforms a versioned shared library has a symbolic link
5264              such as:
5265
5266                 lib<name>.so -> lib<name>.so.1
5267
5268              where   lib<name>.so.1   is   the  soname  of  the  library  and
5269              lib<name>.so is  a  “namelink”  allowing  linkers  to  find  the
5270              library  when  given  -l<name>. The NAMELINK_COMPONENT option is
5271              similar to the COMPONENT option, but it changes the installation
5272              component  of  a shared library namelink if one is generated. If
5273              not specified, this defaults to the value of COMPONENT. It is an
5274              error to use this parameter outside of a LIBRARY block.
5275
5276              Consider the following example:
5277
5278                 install(TARGETS mylib
5279                         LIBRARY
5280                           COMPONENT Libraries
5281                           NAMELINK_COMPONENT Development
5282                         PUBLIC_HEADER
5283                           COMPONENT Development
5284                        )
5285
5286              In  this scenario, if you choose to install only the Development
5287              component, both the headers and namelink will be installed with‐
5288              out the library. (If you don’t also install the Libraries compo‐
5289              nent, the namelink will be a dangling symlink, and projects that
5290              link to the library will have build errors.) If you install only
5291              the Libraries component, only the  library  will  be  installed,
5292              without the headers and namelink.
5293
5294              This  option  is  typically  used for package managers that have
5295              separate runtime  and  development  packages.  For  example,  on
5296              Debian  systems,  the  library  is expected to be in the runtime
5297              package, and the headers and namelink are expected to be in  the
5298              development package.
5299
5300              See  the  VERSION and SOVERSION target properties for details on
5301              creating versioned shared libraries.
5302
5303       NAMELINK_ONLY
5304              This option causes the installation of only the namelink when  a
5305              library target is installed. On platforms where versioned shared
5306              libraries do not have namelinks or when a library  is  not  ver‐
5307              sioned,  the  NAMELINK_ONLY  option  installs  nothing. It is an
5308              error to use this parameter outside of a LIBRARY block.
5309
5310              When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
5311              NENT  may  be  used to specify the installation component of the
5312              namelink, but COMPONENT should generally be preferred.
5313
5314       NAMELINK_SKIP
5315              Similar to NAMELINK_ONLY, but it has  the  opposite  effect:  it
5316              causes the installation of library files other than the namelink
5317              when a library target is installed. When  neither  NAMELINK_ONLY
5318              or  NAMELINK_SKIP  are  given,  both  portions are installed. On
5319              platforms where versioned shared libraries do not have  symlinks
5320              or  when  a library is not versioned, NAMELINK_SKIP installs the
5321              library. It is an error to  use  this  parameter  outside  of  a
5322              LIBRARY block.
5323
5324              If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
5325              It is not recommended to use NAMELINK_SKIP in  conjunction  with
5326              NAMELINK_COMPONENT.
5327
5328       The  install(TARGETS)  command can also accept the following options at
5329       the top level:
5330
5331       EXPORT This option associates the installed target files with an export
5332              called <export-name>.  It must appear before any target options.
5333              To   actually   install   the   export   file    itself,    call
5334              install(EXPORT), documented below.
5335
5336       INCLUDES DESTINATION
5337              This  option specifies a list of directories which will be added
5338              to the  INTERFACE_INCLUDE_DIRECTORIES  target  property  of  the
5339              <targets>  when  exported  by  the install(EXPORT) command. If a
5340              relative path is specified, it is treated  as  relative  to  the
5341              $<INSTALL_PREFIX>.
5342
5343       One  or  more groups of properties may be specified in a single call to
5344       the TARGETS form of this command.  A target may be installed more  than
5345       once  to  different  locations.   Consider  hypothetical targets myExe,
5346       mySharedLib, and myStaticLib.  The code:
5347
5348          install(TARGETS myExe mySharedLib myStaticLib
5349                  RUNTIME DESTINATION bin
5350                  LIBRARY DESTINATION lib
5351                  ARCHIVE DESTINATION lib/static)
5352          install(TARGETS mySharedLib DESTINATION /some/full/path)
5353
5354       will  install  myExe  to  <prefix>/bin   and   myStaticLib   to   <pre‐
5355       fix>/lib/static.  On non-DLL platforms mySharedLib will be installed to
5356       <prefix>/lib and /some/full/path.  On DLL platforms the mySharedLib DLL
5357       will  be  installed  to <prefix>/bin and /some/full/path and its import
5358       library will be installed to <prefix>/lib/static and /some/full/path.
5359
5360       Interface Libraries may be listed among the targets to  install.   They
5361       install  no artifacts but will be included in an associated EXPORT.  If
5362       Object Libraries are listed but given no destination for  their  object
5363       files,  they  will  be exported as Interface Libraries.  This is suffi‐
5364       cient to satisfy transitive usage requirements of  other  targets  that
5365       link to the object libraries in their implementation.
5366
5367       Installing  a  target  with the EXCLUDE_FROM_ALL target property set to
5368       TRUE has undefined behavior.
5369
5370       install(TARGETS) can install targets that were created in other  direc‐
5371       tories.   When  using  such cross-directory install rules, running make
5372       install (or similar) from a subdirectory will not guarantee  that  tar‐
5373       gets   from  other  directories  are  up-to-date.   You  can  use  tar‐
5374       get_link_libraries()  or  add_dependencies()  to   ensure   that   such
5375       out-of-directory  targets  are  built  before the subdirectory-specific
5376       install rules are run.
5377
5378       An install destination given as a DESTINATION argument may use “genera‐
5379       tor  expressions”  with  the  syntax  $<...>.   See  the  cmake-genera‐
5380       tor-expressions(7) manual for available expressions.
5381
5382   Installing Files
5383          install(<FILES|PROGRAMS> files...
5384                  TYPE <type> | DESTINATION <dir>
5385                  [PERMISSIONS permissions...]
5386                  [CONFIGURATIONS [Debug|Release|...]]
5387                  [COMPONENT <component>]
5388                  [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
5389
5390       The FILES form specifies rules for  installing  files  for  a  project.
5391       File  names given as relative paths are interpreted with respect to the
5392       current source directory.  Files installed by this form are by  default
5393       given  permissions  OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
5394       if no PERMISSIONS argument is given.
5395
5396       The PROGRAMS form is identical  to  the  FILES  form  except  that  the
5397       default  permissions for the installed file also include OWNER_EXECUTE,
5398       GROUP_EXECUTE, and WORLD_EXECUTE.  This form  is  intended  to  install
5399       programs  that are not targets, such as shell scripts.  Use the TARGETS
5400       form to install targets built within the project.
5401
5402       The list of files... given to FILES  or  PROGRAMS  may  use  “generator
5403       expressions”  with  the syntax $<...>.  See the cmake-generator-expres‐
5404       sions(7) manual for available expressions.  However, if any item begins
5405       in a generator expression it must evaluate to a full path.
5406
5407       Either  a TYPE or a DESTINATION must be provided, but not both.  A TYPE
5408       argument specifies the generic file type of the files being  installed.
5409       A  destination will then be set automatically by taking the correspond‐
5410       ing variable from GNUInstallDirs, or by using  a  built-in  default  if
5411       that  variable  is  not defined.  See the table below for the supported
5412       file types and their corresponding  variables  and  built-in  defaults.
5413       Projects  can  provide a DESTINATION argument instead of a file type if
5414       they wish to explicitly define the install destination.
5415
5416         ┌──────────────┬─────────────────────────────┬─────────────────────┐
5417TYPE Argument │ GNUInstallDirs              │ Built-In Default    │
5418         │              │ Variable                    │                     │
5419         ├──────────────┼─────────────────────────────┼─────────────────────┤
5420BIN           ${CMAKE_INSTALL_BINDIR}     bin                 
5421         ├──────────────┼─────────────────────────────┼─────────────────────┤
5422SBIN          ${CMAKE_INSTALL_SBINDIR}    sbin                
5423         ├──────────────┼─────────────────────────────┼─────────────────────┤
5424LIB           ${CMAKE_INSTALL_LIBDIR}     lib                 
5425         ├──────────────┼─────────────────────────────┼─────────────────────┤
5426INCLUDE       ${CMAKE_INSTALL_INCLUDEDIR} include             
5427         ├──────────────┼─────────────────────────────┼─────────────────────┤
5428SYSCONF       ${CMAKE_INSTALL_SYSCONFDIR} etc                 
5429         ├──────────────┼─────────────────────────────┼─────────────────────┤
5430SHAREDSTATE   ${CMAKE_INSTALL_SHARESTATE‐ com                 
5431         │              │ DIR}                        │                     │
5432         ├──────────────┼─────────────────────────────┼─────────────────────┤
5433LOCALSTATE    ${CMAKE_INSTALL_LOCALSTATE‐ var                 
5434         │              │ DIR}                        │                     │
5435         ├──────────────┼─────────────────────────────┼─────────────────────┤
5436RUNSTATE      ${CMAKE_INSTALL_RUNSTATE‐   <LOCALSTATE         
5437         │              │ DIR}                        dir>/run            
5438         ├──────────────┼─────────────────────────────┼─────────────────────┤
5439DATA          ${CMAKE_INSTALL_DATADIR}    <DATAROOT dir>      
5440         ├──────────────┼─────────────────────────────┼─────────────────────┤
5441INFO          ${CMAKE_INSTALL_INFODIR}    <DATAROOT dir>/info 
5442         ├──────────────┼─────────────────────────────┼─────────────────────┤
5443LOCALE        ${CMAKE_INSTALL_LOCALEDIR}  <DATAROOT           
5444         │              │                             │ dir>/locale         
5445         ├──────────────┼─────────────────────────────┼─────────────────────┤
5446MAN           ${CMAKE_INSTALL_MANDIR}     <DATAROOT dir>/man  
5447         ├──────────────┼─────────────────────────────┼─────────────────────┤
5448DOC           ${CMAKE_INSTALL_DOCDIR}     <DATAROOT dir>/doc  
5449         └──────────────┴─────────────────────────────┴─────────────────────┘
5450
5451       Projects  wishing  to  follow the common practice of installing headers
5452       into a project-specific subdirectory will need to provide a destination
5453       rather than rely on the above.
5454
5455       Note  that some of the types’ built-in defaults use the DATAROOT direc‐
5456       tory as a prefix. The DATAROOT prefix is calculated  similarly  to  the
5457       types,  with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
5458       built-in default. You cannot use DATAROOT as a TYPE  parameter;  please
5459       use DATA instead.
5460
5461       To  make  packages  compliant with distribution filesystem layout poli‐
5462       cies, if projects must specify a DESTINATION, it  is  recommended  that
5463       they  use  a path that begins with the appropriate GNUInstallDirs vari‐
5464       able.  This allows package maintainers to control the install  destina‐
5465       tion by setting the appropriate cache variables.  The following example
5466       shows  how  to  follow  this  advice  while  installing  headers  to  a
5467       project-specific subdirectory:
5468
5469          include(GNUInstallDirs)
5470          install(FILES mylib.h
5471                  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
5472          )
5473
5474       An install destination given as a DESTINATION argument may use “genera‐
5475       tor  expressions”  with  the  syntax  $<...>.   See  the  cmake-genera‐
5476       tor-expressions(7) manual for available expressions.
5477
5478   Installing Directories
5479          install(DIRECTORY dirs...
5480                  TYPE <type> | DESTINATION <dir>
5481                  [FILE_PERMISSIONS permissions...]
5482                  [DIRECTORY_PERMISSIONS permissions...]
5483                  [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
5484                  [CONFIGURATIONS [Debug|Release|...]]
5485                  [COMPONENT <component>] [EXCLUDE_FROM_ALL]
5486                  [FILES_MATCHING]
5487                  [[PATTERN <pattern> | REGEX <regex>]
5488                   [EXCLUDE] [PERMISSIONS permissions...]] [...])
5489
5490       The  DIRECTORY  form  installs contents of one or more directories to a
5491       given destination.  The directory structure is copied verbatim  to  the
5492       destination.   The last component of each directory name is appended to
5493       the destination directory but a trailing slash may  be  used  to  avoid
5494       this because it leaves the last component empty.  Directory names given
5495       as relative paths are interpreted with respect to  the  current  source
5496       directory.   If  no  input  directory  names  are given the destination
5497       directory will be created but nothing will be installed into  it.   The
5498       FILE_PERMISSIONS  and DIRECTORY_PERMISSIONS options specify permissions
5499       given to files and directories in the destination.  If  USE_SOURCE_PER‐
5500       MISSIONS  is  specified  and  FILE_PERMISSIONS is not, file permissions
5501       will be copied from the source directory structure.  If no  permissions
5502       are  specified files will be given the default permissions specified in
5503       the FILES form of the command, and the directories will  be  given  the
5504       default permissions specified in the PROGRAMS form of the command.
5505
5506       The MESSAGE_NEVER option disables file installation status output.
5507
5508       Installation  of  directories  may  be controlled with fine granularity
5509       using the PATTERN or REGEX options.  These “match”  options  specify  a
5510       globbing  pattern  or  regular expression to match directories or files
5511       encountered within input directories.  They may be used to  apply  cer‐
5512       tain  options  (see  below)  to  a  subset of the files and directories
5513       encountered.  The full path to each input file or directory (with  for‐
5514       ward  slashes) is matched against the expression.  A PATTERN will match
5515       only complete file names: the portion of the  full  path  matching  the
5516       pattern  must  occur  at  the end of the file name and be preceded by a
5517       slash.  A REGEX will match any portion of the full path but it may  use
5518       /  and  $  to  simulate the PATTERN behavior.  By default all files and
5519       directories are  installed  whether  or  not  they  are  matched.   The
5520       FILES_MATCHING  option  may  be  given before the first match option to
5521       disable installation of files (but not directories) not matched by  any
5522       expression.  For example, the code
5523
5524          install(DIRECTORY src/ DESTINATION include/myproj
5525                  FILES_MATCHING PATTERN "*.h")
5526
5527       will extract and install header files from a source tree.
5528
5529       Some  options  may follow a PATTERN or REGEX expression and are applied
5530       only to files or directories matching them.  The  EXCLUDE  option  will
5531       skip  the  matched file or directory.  The PERMISSIONS option overrides
5532       the permissions setting for the matched file or directory.  For example
5533       the code
5534
5535          install(DIRECTORY icons scripts/ DESTINATION share/myproj
5536                  PATTERN "CVS" EXCLUDE
5537                  PATTERN "scripts/*"
5538                  PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
5539                              GROUP_EXECUTE GROUP_READ)
5540
5541       will  install the icons directory to share/myproj/icons and the scripts
5542       directory to share/myproj.  The icons will  get  default  file  permis‐
5543       sions,  the  scripts  will  be  given specific permissions, and any CVS
5544       directories will be excluded.
5545
5546       Either a TYPE or a DESTINATION must be provided, but not both.  A  TYPE
5547       argument specifies the generic file type of the files within the listed
5548       directories being installed.  A destination will then be set  automati‐
5549       cally  by  taking the corresponding variable from GNUInstallDirs, or by
5550       using a built-in default if that variable is not defined.  See the  ta‐
5551       ble  below  for  the supported file types and their corresponding vari‐
5552       ables and built-in defaults.  Projects can provide a DESTINATION  argu‐
5553       ment  instead  of  a  file  type  if they wish to explicitly define the
5554       install destination.
5555
5556         ┌──────────────┬─────────────────────────────┬─────────────────────┐
5557TYPE Argument │ GNUInstallDirs              │ Built-In Default    │
5558         │              │ Variable                    │                     │
5559         ├──────────────┼─────────────────────────────┼─────────────────────┤
5560BIN           ${CMAKE_INSTALL_BINDIR}     bin                 
5561         ├──────────────┼─────────────────────────────┼─────────────────────┤
5562SBIN          ${CMAKE_INSTALL_SBINDIR}    sbin                
5563         ├──────────────┼─────────────────────────────┼─────────────────────┤
5564LIB           ${CMAKE_INSTALL_LIBDIR}     lib                 
5565         ├──────────────┼─────────────────────────────┼─────────────────────┤
5566INCLUDE       ${CMAKE_INSTALL_INCLUDEDIR} include             
5567         ├──────────────┼─────────────────────────────┼─────────────────────┤
5568SYSCONF       ${CMAKE_INSTALL_SYSCONFDIR} etc                 
5569         ├──────────────┼─────────────────────────────┼─────────────────────┤
5570SHAREDSTATE   ${CMAKE_INSTALL_SHARESTATE‐ com                 
5571         │              │ DIR}                        │                     │
5572         ├──────────────┼─────────────────────────────┼─────────────────────┤
5573LOCALSTATE    ${CMAKE_INSTALL_LOCALSTATE‐ var                 
5574         │              │ DIR}                        │                     │
5575         ├──────────────┼─────────────────────────────┼─────────────────────┤
5576RUNSTATE      ${CMAKE_INSTALL_RUNSTATE‐   <LOCALSTATE         
5577         │              │ DIR}                        dir>/run            
5578         ├──────────────┼─────────────────────────────┼─────────────────────┤
5579DATA          ${CMAKE_INSTALL_DATADIR}    <DATAROOT dir>      
5580         ├──────────────┼─────────────────────────────┼─────────────────────┤
5581INFO          ${CMAKE_INSTALL_INFODIR}    <DATAROOT dir>/info 
5582         ├──────────────┼─────────────────────────────┼─────────────────────┤
5583LOCALE        ${CMAKE_INSTALL_LOCALEDIR}  <DATAROOT           
5584         │              │                             │ dir>/locale         
5585         ├──────────────┼─────────────────────────────┼─────────────────────┤
5586MAN           ${CMAKE_INSTALL_MANDIR}     <DATAROOT dir>/man  
5587         ├──────────────┼─────────────────────────────┼─────────────────────┤
5588DOC           ${CMAKE_INSTALL_DOCDIR}     <DATAROOT dir>/doc  
5589         └──────────────┴─────────────────────────────┴─────────────────────┘
5590
5591       Note  that some of the types’ built-in defaults use the DATAROOT direc‐
5592       tory as a prefix. The DATAROOT prefix is calculated  similarly  to  the
5593       types,  with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
5594       built-in default. You cannot use DATAROOT as a TYPE  parameter;  please
5595       use DATA instead.
5596
5597       To  make  packages  compliant with distribution filesystem layout poli‐
5598       cies, if projects must specify a DESTINATION, it  is  recommended  that
5599       they  use  a path that begins with the appropriate GNUInstallDirs vari‐
5600       able.  This allows package maintainers to control the install  destina‐
5601       tion by setting the appropriate cache variables.
5602
5603       The list of dirs... given to DIRECTORY and an install destination given
5604       as a DESTINATION argument may use “generator expressions” with the syn‐
5605       tax  $<...>.   See the cmake-generator-expressions(7) manual for avail‐
5606       able expressions.
5607
5608   Custom Installation Logic
5609          install([[SCRIPT <file>] [CODE <code>]]
5610                  [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
5611
5612       The SCRIPT form will invoke the given CMake script files during instal‐
5613       lation.   If  the script file name is a relative path it will be inter‐
5614       preted with respect to the current source  directory.   The  CODE  form
5615       will  invoke  the given CMake code during installation.  Code is speci‐
5616       fied as a single argument inside a double-quoted string.  For  example,
5617       the code
5618
5619          install(CODE "MESSAGE(\"Sample install message.\")")
5620
5621       will print a message during installation.
5622
5623       <file> or <code> may use “generator expressions” with the syntax $<...>
5624       (in the case of <file>, this refers to their use in the file name,  not
5625       the  file’s  contents).   See the cmake-generator-expressions(7) manual
5626       for available expressions.
5627
5628   Installing Exports
5629          install(EXPORT <export-name> DESTINATION <dir>
5630                  [NAMESPACE <namespace>] [[FILE <name>.cmake]|
5631                  [PERMISSIONS permissions...]
5632                  [CONFIGURATIONS [Debug|Release|...]]
5633                  [EXPORT_LINK_INTERFACE_LIBRARIES]
5634                  [COMPONENT <component>]
5635                  [EXCLUDE_FROM_ALL])
5636          install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
5637
5638       The EXPORT form generates and installs a CMake file containing code  to
5639       import targets from the installation tree into another project.  Target
5640       installations are associated with the export  <export-name>  using  the
5641       EXPORT  option of the install(TARGETS) signature documented above.  The
5642       NAMESPACE option will prepend <namespace> to the target names  as  they
5643       are  written to the import file.  By default the generated file will be
5644       called <export-name>.cmake but the FILE option may be used to specify a
5645       different name.  The value given to the FILE option must be a file name
5646       with the .cmake extension.  If a CONFIGURATIONS option  is  given  then
5647       the file will only be installed when one of the named configurations is
5648       installed.  Additionally, the generated import file will reference only
5649       the    matching    target   configurations.    The   EXPORT_LINK_INTER‐
5650       FACE_LIBRARIES keyword, if present, causes the contents of the  proper‐
5651       ties  matching  (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?  to be
5652       exported, when policy CMP0022 is NEW.
5653
5654       When a COMPONENT option is given,  the  listed  <component>  implicitly
5655       depends  on  all  components  mentioned in the export set. The exported
5656       <name>.cmake file will require each of the exported  components  to  be
5657       present in order for dependent projects to build properly. For example,
5658       a project may define components Runtime and  Development,  with  shared
5659       libraries  going  into  the  Runtime component and static libraries and
5660       headers going into the Development component. The export set would also
5661       typically  be  part  of  the Development component, but it would export
5662       targets from both the Runtime and  Development  components.  Therefore,
5663       the  Runtime  component  would  need to be installed if the Development
5664       component was installed, but not vice versa. If the Development  compo‐
5665       nent  was  installed  without the Runtime component, dependent projects
5666       that try to link against it would have build errors. Package  managers,
5667       such  as APT and RPM, typically handle this by listing the Runtime com‐
5668       ponent as a dependency of the  Development  component  in  the  package
5669       metadata,  ensuring that the library is always installed if the headers
5670       and CMake export file are present.
5671
5672       In addition to cmake language files, the EXPORT_ANDROID_MK  mode  maybe
5673       used  to  specify an export to the android ndk build system.  This mode
5674       accepts the same options as the normal export mode.   The  Android  NDK
5675       supports  the  use  of prebuilt libraries, both static and shared. This
5676       allows cmake to build the libraries of a project and make  them  avail‐
5677       able  to  an  ndk  build  system complete with transitive dependencies,
5678       include flags and defines required to use the libraries.
5679
5680       The EXPORT form is useful to help outside projects  use  targets  built
5681       and installed by the current project.  For example, the code
5682
5683          install(TARGETS myexe EXPORT myproj DESTINATION bin)
5684          install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
5685          install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)
5686
5687       will install the executable myexe to <prefix>/bin and code to import it
5688       in    the    file    <prefix>/lib/myproj/myproj.cmake     and     <pre‐
5689       fix>/share/ndk-modules/Android.mk.   An  outside  project may load this
5690       file with the include command and reference the myexe  executable  from
5691       the installation tree using the imported target name mp_myexe as if the
5692       target were built in its own tree.
5693
5694       NOTE:
5695          This  command  supercedes  the  install_targets()  command  and  the
5696          PRE_INSTALL_SCRIPT  and  POST_INSTALL_SCRIPT  target properties.  It
5697          also  replaces  the  FILES  forms   of   the   install_files()   and
5698          install_programs()  commands.  The processing order of these install
5699          rules   relative   to   those   generated   by    install_targets(),
5700          install_files(), and install_programs() commands is not defined.
5701
5702   Generated Installation Script
5703       The install() command generates a file, cmake_install.cmake, inside the
5704       build directory, which is used internally by the generated install tar‐
5705       get  and  by CPack. You can also invoke this script manually with cmake
5706       -P. This script accepts several variables:
5707
5708       COMPONENT
5709              Set this variable to install only a single  CPack  component  as
5710              opposed to all of them. For example, if you only want to install
5711              the Development component, run cmake -DCOMPONENT=Development  -P
5712              cmake_install.cmake.
5713
5714       BUILD_TYPE
5715              Set  this  variable  to change the build type if you are using a
5716              multi-config generator. For example, to install with  the  Debug
5717              configuration,      run      cmake     -DBUILD_TYPE=Debug     -P
5718              cmake_install.cmake.
5719
5720       DESTDIR
5721              This is an environment variable rather than a CMake variable. It
5722              allows  you  to  change the installation prefix on UNIX systems.
5723              See DESTDIR for details.
5724
5725   link_directories
5726       Add directories in which the linker will look for libraries.
5727
5728          link_directories([AFTER|BEFORE] directory1 [directory2 ...])
5729
5730       Adds the paths in which the linker should search for libraries.   Rela‐
5731       tive  paths  given  to  this command are interpreted as relative to the
5732       current source directory, see CMP0015.
5733
5734       The directories are added to the  LINK_DIRECTORIES  directory  property
5735       for the current CMakeLists.txt file, converting relative paths to abso‐
5736       lute as needed.  The command will apply only to targets  created  after
5737       it is called.
5738
5739       By default the directories specified are appended onto the current list
5740       of directories.  This  default  behavior  can  be  changed  by  setting
5741       CMAKE_LINK_DIRECTORIES_BEFORE  to ON.  By using AFTER or BEFORE explic‐
5742       itly, you can select between appending and prepending,  independent  of
5743       the default.
5744
5745       Arguments  to link_directories may use “generator expressions” with the
5746       syntax  “$<…>”.   See  the  cmake-generator-expressions(7)  manual  for
5747       available expressions.  See the cmake-buildsystem(7) manual for more on
5748       defining buildsystem properties.
5749
5750       NOTE:
5751          This command is rarely necessary and should be avoided  where  there
5752          are  other choices.  Prefer to pass full absolute paths to libraries
5753          where possible, since this ensures the correct library  will  always
5754          be linked.  The find_library() command provides the full path, which
5755          can generally be used directly in calls to  target_link_libraries().
5756          Situations where a library search path may be needed include:
5757
5758          · Project  generators  like  Xcode  where the user can switch target
5759            architecture at build time, but a full path to a library cannot be
5760            used  because  it only provides one architecture (i.e. it is not a
5761            universal binary).
5762
5763          · Libraries may themselves have other private  library  dependencies
5764            that expect to be found via RPATH mechanisms, but some linkers are
5765            not able to fully decode those paths (e.g. due to the presence  of
5766            things like $ORIGIN).
5767
5768          If  a  library  search path must be provided, prefer to localize the
5769          effect where possible by using the target_link_directories() command
5770          rather  than  link_directories().   The  target-specific command can
5771          also control how the search directories propagate to other dependent
5772          targets.
5773
5774   link_libraries
5775       Link libraries to all targets added later.
5776
5777          link_libraries([item1 [item2 [...]]]
5778                         [[debug|optimized|general] <item>] ...)
5779
5780       Specify  libraries  or  flags  to  use when linking any targets created
5781       later in the current directory or below by commands  such  as  add_exe‐
5782       cutable()  or  add_library().   See the target_link_libraries() command
5783       for meaning of arguments.
5784
5785       NOTE:
5786          The target_link_libraries() command  should  be  preferred  whenever
5787          possible.  Library dependencies are chained automatically, so direc‐
5788          tory-wide specification of link libraries is rarely needed.
5789
5790   load_cache
5791       Load in the values from another project’s CMake cache.
5792
5793          load_cache(pathToCacheFile READ_WITH_PREFIX prefix entry1...)
5794
5795       Reads the cache and store the requested entries in variables with their
5796       name  prefixed  with the given prefix.  This only reads the values, and
5797       does not create entries in the local project’s cache.
5798
5799          load_cache(pathToCacheFile [EXCLUDE entry1...]
5800                     [INCLUDE_INTERNALS entry1...])
5801
5802       Loads in the values from another cache and  store  them  in  the  local
5803       project’s cache as internal entries.  This is useful for a project that
5804       depends on another project built in a different tree.   EXCLUDE  option
5805       can   be   used   to   provide  a  list  of  entries  to  be  excluded.
5806       INCLUDE_INTERNALS can be used to provide a list of internal entries  to
5807       be  included.   Normally,  no  internal entries are brought in.  Use of
5808       this form of the command is strongly discouraged, but  it  is  provided
5809       for backward compatibility.
5810
5811   project
5812       Set the name of the project.
5813
5814   Synopsis
5815          project(<PROJECT-NAME> [<language-name>...])
5816          project(<PROJECT-NAME>
5817                  [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
5818                  [DESCRIPTION <project-description-string>]
5819                  [HOMEPAGE_URL <url-string>]
5820                  [LANGUAGES <language-name>...])
5821
5822       Sets   the  name  of  the  project,  and  stores  it  in  the  variable
5823       PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
5824       the project name in the variable CMAKE_PROJECT_NAME.
5825
5826       Also sets the variables
5827
5828       · PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
5829
5830       · PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
5831
5832       Further  variables  are  set by the optional arguments described in the
5833       following.  If any of these arguments is not used, then the correspond‐
5834       ing variables are set to the empty string.
5835
5836       If  the  variable CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE exists, the file
5837       pointed to by that variable will be included as the last  step  of  the
5838       project command.
5839
5840   Options
5841       The options are:
5842
5843       VERSION <version>
5844              Optional; may not be used unless policy CMP0048 is set to NEW.
5845
5846              Takes a <version> argument composed of non-negative integer com‐
5847              ponents, i.e.  <major>[.<minor>[.<patch>[.<tweak>]]],  and  sets
5848              the variables
5849
5850              · PROJECT_VERSION, <PROJECT-NAME>_VERSION
5851
5852              · PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
5853
5854              · PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
5855
5856              · PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
5857
5858              · PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
5859
5860              When  the  project() command is called from the top-level CMake‐
5861              Lists.txt, then the version  is  also  stored  in  the  variable
5862              CMAKE_PROJECT_VERSION.
5863
5864       DESCRIPTION <project-description-string>
5865              Optional.  Sets the variables
5866
5867              · PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
5868
5869              to  <project-description-string>.   It  is recommended that this
5870              description is a relatively short string, usually no more than a
5871              few words.
5872
5873              When  the  project() command is called from the top-level CMake‐
5874              Lists.txt, then the description is also stored in  the  variable
5875              CMAKE_PROJECT_DESCRIPTION.
5876
5877       HOMEPAGE_URL <url-string>
5878              Optional.  Sets the variables
5879
5880              · PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
5881
5882              to  <url-string>, which should be the canonical home URL for the
5883              project.
5884
5885              When the project() command is called from the  top-level  CMake‐
5886              Lists.txt,   then  the  URL  also  is  stored  in  the  variable
5887              CMAKE_PROJECT_HOMEPAGE_URL.
5888
5889       LANGUAGES <language-name>...
5890              Optional.  Can also be specified without LANGUAGES  keyword  per
5891              the first, short signature.
5892
5893              Selects  which  programming  languages  are  needed to build the
5894              project.  Supported languages include C, CXX (i.e.  C++),  CUDA,
5895              Fortran,  and  ASM.  By default C and CXX are enabled if no lan‐
5896              guage options are given.  Specify language NONE, or use the LAN‐
5897              GUAGES  keyword and list no languages, to skip enabling any lan‐
5898              guages.
5899
5900              If enabling ASM, list it last so that CMake  can  check  whether
5901              compilers for other languages like C work for assembly too.
5902
5903       The  variables  set  through  the VERSION, DESCRIPTION and HOMEPAGE_URL
5904       options are intended for use as default values in package metadata  and
5905       documentation.
5906
5907   Usage
5908       The top-level CMakeLists.txt file for a project must contain a literal,
5909       direct call to the project() command; loading one through the include()
5910       command  is  not sufficient.  If no such call exists CMake will implic‐
5911       itly add one to the top that enables the default languages (C and CXX).
5912
5913       NOTE:
5914          Call the cmake_minimum_required() command at the  beginning  of  the
5915          top-level CMakeLists.txt file even before calling the project() com‐
5916          mand.  It is important to  establish  version  and  policy  settings
5917          before  invoking other commands whose behavior they may affect.  See
5918          also policy CMP0000.
5919
5920   remove_definitions
5921       Remove -D define flags added by add_definitions().
5922
5923          remove_definitions(-DFOO -DBAR ...)
5924
5925       Removes flags (added by add_definitions()) from  the  compiler  command
5926       line for sources in the current directory and below.
5927
5928   set_source_files_properties
5929       Source files can have properties that affect how they are built.
5930
5931          set_source_files_properties([file1 [file2 [...]]]
5932                                      PROPERTIES prop1 value1
5933                                      [prop2 value2 [...]])
5934
5935       Sets  properties  associated with source files using a key/value paired
5936       list.
5937
5938       See also the set_property(SOURCE) command.
5939
5940       See Source File Properties for the list of properties known  to  CMake.
5941       Source  file  properties  are visible only to targets added in the same
5942       directory (CMakeLists.txt).
5943
5944   set_target_properties
5945       Targets can have properties that affect how they are built.
5946
5947          set_target_properties(target1 target2 ...
5948                                PROPERTIES prop1 value1
5949                                prop2 value2 ...)
5950
5951       Sets properties on targets.  The syntax for the command is to list  all
5952       the targets you want to change, and then provide the values you want to
5953       set next.  You can use any prop value pair  you  want  and  extract  it
5954       later with the get_property() or get_target_property() command.
5955
5956       See also the set_property(TARGET) command.
5957
5958       See Target Properties for the list of properties known to CMake.
5959
5960   set_tests_properties
5961       Set a property of the tests.
5962
5963          set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
5964
5965       Sets  a  property  for the tests.  If the test is not found, CMake will
5966       report an error.  Generator expressions will be expanded  the  same  as
5967       supported by the test’s add_test() call.
5968
5969       See also the set_property(TEST) command.
5970
5971       See Test Properties for the list of properties known to CMake.
5972
5973   source_group
5974       Define  a  grouping  for source files in IDE project generation.  There
5975       are two different signatures to create source groups.
5976
5977          source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
5978          source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
5979
5980       Defines a group into which sources will be  placed  in  project  files.
5981       This  is  intended  to  set up file tabs in Visual Studio.  The options
5982       are:
5983
5984       TREE   CMake will automatically detect, from <src> files paths,  source
5985              groups  it  needs  to create, to keep structure of source groups
5986              analogically to the actual files and  directories  structure  in
5987              the  project. Paths of <src> files will be cut to be relative to
5988              <root>.
5989
5990       PREFIX Source group and files located directly in <root> path, will  be
5991              placed in <prefix> source groups.
5992
5993       FILES  Any  source  file  specified  explicitly will be placed in group
5994              <name>.  Relative paths are interpreted with respect to the cur‐
5995              rent source directory.
5996
5997       REGULAR_EXPRESSION
5998              Any  source  file whose name matches the regular expression will
5999              be placed in group <name>.
6000
6001       If a source file matches multiple groups, the last group  that  explic‐
6002       itly  lists  the  file with FILES will be favored, if any.  If no group
6003       explicitly lists the file, the  last  group  whose  regular  expression
6004       matches the file will be favored.
6005
6006       The  <name>  of the group and <prefix> argument may contain backslashes
6007       to specify subgroups:
6008
6009          source_group(outer\\inner ...)
6010          source_group(TREE <root> PREFIX sources\\inc ...)
6011
6012       For backwards compatibility, the short-hand signature
6013
6014          source_group(<name> <regex>)
6015
6016       is equivalent to
6017
6018          source_group(<name> REGULAR_EXPRESSION <regex>)
6019
6020   target_compile_definitions
6021       Add compile definitions to a target.
6022
6023          target_compile_definitions(<target>
6024            <INTERFACE|PUBLIC|PRIVATE> [items1...]
6025            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6026
6027       Specifies compile definitions to use when compiling a  given  <target>.
6028       The named <target> must have been created by a command such as add_exe‐
6029       cutable() or add_library() and must not be an ALIAS target.
6030
6031       The INTERFACE, PUBLIC and PRIVATE keywords are required to specify  the
6032       scope  of the following arguments.  PRIVATE and PUBLIC items will popu‐
6033       late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
6034       items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
6035       get>.  (IMPORTED targets only support INTERFACE items.)  The  following
6036       arguments  specify  compile  definitions.   Repeated calls for the same
6037       <target> append items in the order called.
6038
6039       Arguments to target_compile_definitions may use “generator expressions”
6040       with  the syntax $<...>.  See the cmake-generator-expressions(7) manual
6041       for available expressions.  See  the  cmake-buildsystem(7)  manual  for
6042       more on defining buildsystem properties.
6043
6044       Any  leading  -D  on an item will be removed.  Empty items are ignored.
6045       For example, the following are all equivalent:
6046
6047          target_compile_definitions(foo PUBLIC FOO)
6048          target_compile_definitions(foo PUBLIC -DFOO)  # -D removed
6049          target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
6050          target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
6051
6052   target_compile_features
6053       Add expected compiler features to a target.
6054
6055          target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
6056
6057       Specifies compiler features required when compiling a given target.  If
6058       the  feature  is not listed in the CMAKE_C_COMPILE_FEATURES variable or
6059       CMAKE_CXX_COMPILE_FEATURES variable, then an error will be reported  by
6060       CMake.  If the use of the feature requires an additional compiler flag,
6061       such as -std=gnu++11, the flag will be added automatically.
6062
6063       The INTERFACE, PUBLIC and PRIVATE keywords are required to specify  the
6064       scope of the features.  PRIVATE and PUBLIC items will populate the COM‐
6065       PILE_FEATURES property of <target>.  PUBLIC and  INTERFACE  items  will
6066       populate   the   INTERFACE_COMPILE_FEATURES   property   of   <target>.
6067       (IMPORTED targets only support INTERFACE items.)   Repeated  calls  for
6068       the same <target> append items.
6069
6070       The named <target> must have been created by a command such as add_exe‐
6071       cutable() or add_library() and must not be an ALIAS target.
6072
6073       Arguments to target_compile_features may  use  “generator  expressions”
6074       with  the syntax $<...>.  See the cmake-generator-expressions(7) manual
6075       for available expressions.  See  the  cmake-compile-features(7)  manual
6076       for information on compile features and a list of supported compilers.
6077
6078   target_compile_options
6079       Add compile options to a target.
6080
6081          target_compile_options(<target> [BEFORE]
6082            <INTERFACE|PUBLIC|PRIVATE> [items1...]
6083            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6084
6085       Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
6086       properties. These options are used when compiling the  given  <target>,
6087       which  must  have been created by a command such as add_executable() or
6088       add_library() and must not be an ALIAS target.
6089
6090   Arguments
6091       If BEFORE is specified, the content will be prepended to  the  property
6092       instead of being appended.
6093
6094       The  INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6095       scope of the following arguments.  PRIVATE and PUBLIC items will  popu‐
6096       late  the  COMPILE_OPTIONS  property of <target>.  PUBLIC and INTERFACE
6097       items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
6098       (IMPORTED  targets  only support INTERFACE items.)  The following argu‐
6099       ments specify compile options.  Repeated calls for  the  same  <target>
6100       append items in the order called.
6101
6102       Arguments  to  target_compile_options  may  use “generator expressions”
6103       with the syntax $<...>. See the  cmake-generator-expressions(7)  manual
6104       for  available  expressions.   See  the cmake-buildsystem(7) manual for
6105       more on defining buildsystem properties.
6106
6107       The final set of compile or link options used  for  a  target  is  con‐
6108       structed  by accumulating options from the current target and the usage
6109       requirements of it dependencies.  The set of options  is  de-duplicated
6110       to  avoid  repetition.   While  beneficial  for individual options, the
6111       de-duplication step can break up option groups.  For example, -D A -D B
6112       becomes  -D  A  B.  One may specify a group of options using shell-like
6113       quoting along with a SHELL: prefix.  The SHELL: prefix is  dropped  and
6114       the  rest of the option string is parsed using the separate_arguments()
6115       UNIX_COMMAND mode.  For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6116       -D B.
6117
6118   See Also
6119       This  command  can be used to add any options. However, for adding pre‐
6120       processor definitions and include directories it is recommended to  use
6121       the   more  specific  commands  target_compile_definitions()  and  tar‐
6122       get_include_directories().
6123
6124       For  directory-wide   settings,   there   is   the   command   add_com‐
6125       pile_options().
6126
6127   target_include_directories
6128       Add include directories to a target.
6129
6130          target_include_directories(<target> [SYSTEM] [BEFORE]
6131            <INTERFACE|PUBLIC|PRIVATE> [items1...]
6132            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6133
6134       Specifies  include  directories  to  use when compiling a given target.
6135       The named <target> must have been created by a command such as add_exe‐
6136       cutable() or add_library() and must not be an ALIAS target.
6137
6138       If  BEFORE  is specified, the content will be prepended to the property
6139       instead of being appended.
6140
6141       The INTERFACE, PUBLIC and PRIVATE keywords are required to specify  the
6142       scope  of the following arguments.  PRIVATE and PUBLIC items will popu‐
6143       late the INCLUDE_DIRECTORIES property of <target>.  PUBLIC  and  INTER‐
6144       FACE  items will populate the INTERFACE_INCLUDE_DIRECTORIES property of
6145       <target>.  (IMPORTED targets only support INTERFACE items.)   The  fol‐
6146       lowing arguments specify include directories.
6147
6148       Specified  include directories may be absolute paths or relative paths.
6149       Repeated calls for the same <target> append items in the order  called.
6150       If  SYSTEM  is specified, the compiler will be told the directories are
6151       meant as system include directories on some platforms (signalling  this
6152       setting  might  achieve effects such as the compiler skipping warnings,
6153       or these fixed-install system files not being considered in  dependency
6154       calculations  -  see  compiler  docs).  If SYSTEM is used together with
6155       PUBLIC or INTERFACE,  the  INTERFACE_SYSTEM_INCLUDE_DIRECTORIES  target
6156       property will be populated with the specified directories.
6157
6158       Arguments to target_include_directories may use “generator expressions”
6159       with the syntax $<...>.  See the cmake-generator-expressions(7)  manual
6160       for  available  expressions.   See  the cmake-buildsystem(7) manual for
6161       more on defining buildsystem properties.
6162
6163       Include directories usage  requirements  commonly  differ  between  the
6164       build-tree    and    the   install-tree.    The   BUILD_INTERFACE   and
6165       INSTALL_INTERFACE generator expressions can be used to  describe  sepa‐
6166       rate  usage  requirements  based on the usage location.  Relative paths
6167       are allowed within the INSTALL_INTERFACE expression and are interpreted
6168       relative to the installation prefix.  For example:
6169
6170          target_include_directories(mylib PUBLIC
6171            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
6172            $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
6173          )
6174
6175   Creating Relocatable Packages
6176       Note  that it is not advisable to populate the INSTALL_INTERFACE of the
6177       INTERFACE_INCLUDE_DIRECTORIES of a target with absolute  paths  to  the
6178       include   directories  of  dependencies.   That  would  hard-code  into
6179       installed packages the include  directory  paths  for  dependencies  as
6180       found on the machine the package was made on.
6181
6182       The  INSTALL_INTERFACE  of  the  INTERFACE_INCLUDE_DIRECTORIES  is only
6183       suitable for specifying the required include  directories  for  headers
6184       provided  with  the target itself, not those provided by the transitive
6185       dependencies listed in its  INTERFACE_LINK_LIBRARIES  target  property.
6186       Those  dependencies should themselves be targets that specify their own
6187       header locations in INTERFACE_INCLUDE_DIRECTORIES.
6188
6189       See the Creating Relocatable Packages section of the  cmake-packages(7)
6190       manual for discussion of additional care that must be taken when speci‐
6191       fying usage requirements while creating packages for redistribution.
6192
6193   target_link_directories
6194       Add link directories to a target.
6195
6196          target_link_directories(<target> [BEFORE]
6197            <INTERFACE|PUBLIC|PRIVATE> [items1...]
6198            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6199
6200       Specifies the paths in which the linker  should  search  for  libraries
6201       when  linking a given target.  Each item can be an absolute or relative
6202       path, with the latter being interpreted  as  relative  to  the  current
6203       source directory.  These items will be added to the link command.
6204
6205       The named <target> must have been created by a command such as add_exe‐
6206       cutable() or add_library() and must not be an ALIAS target.
6207
6208       The INTERFACE, PUBLIC and PRIVATE keywords are required to specify  the
6209       scope  of  the  items  that follow them.  PRIVATE and PUBLIC items will
6210       populate the LINK_DIRECTORIES property of <target>.  PUBLIC and  INTER‐
6211       FACE  items  will  populate  the INTERFACE_LINK_DIRECTORIES property of
6212       <target> (IMPORTED targets only support INTERFACE  items).   Each  item
6213       specifies a link directory and will be converted to an absolute path if
6214       necessary before adding it to the relevant  property.   Repeated  calls
6215       for the same <target> append items in the order called.
6216
6217       If  BEFORE  is specified, the content will be prepended to the relevant
6218       property instead of being appended.
6219
6220       Arguments to target_link_directories may  use  “generator  expressions”
6221       with  the  syntax $<...>. See the cmake-generator-expressions(7) manual
6222       for available expressions.  See  the  cmake-buildsystem(7)  manual  for
6223       more on defining buildsystem properties.
6224
6225       NOTE:
6226          This  command  is rarely necessary and should be avoided where there
6227          are other choices.  Prefer to pass full absolute paths to  libraries
6228          where  possible,  since this ensures the correct library will always
6229          be linked.  The find_library() command provides the full path, which
6230          can  generally be used directly in calls to target_link_libraries().
6231          Situations where a library search path may be needed include:
6232
6233          · Project generators like Xcode where the  user  can  switch  target
6234            architecture at build time, but a full path to a library cannot be
6235            used because it only provides one architecture (i.e. it is  not  a
6236            universal binary).
6237
6238          · Libraries  may  themselves have other private library dependencies
6239            that expect to be found via RPATH mechanisms, but some linkers are
6240            not  able to fully decode those paths (e.g. due to the presence of
6241            things like $ORIGIN).
6242
6243   target_link_libraries
6244       Specify libraries or flags to use when linking a  given  target  and/or
6245       its dependents.  Usage requirements from linked library targets will be
6246       propagated.  Usage requirements of a target’s dependencies affect  com‐
6247       pilation of its own sources.
6248
6249   Overview
6250       This  command  has several signatures as detailed in subsections below.
6251       All of them have the general form
6252
6253          target_link_libraries(<target> ... <item>... ...)
6254
6255       The named <target> must have been created by a command such as add_exe‐
6256       cutable()  or add_library() and must not be an ALIAS target.  If policy
6257       CMP0079 is not set to NEW then the target must have been created in the
6258       current  directory.   Repeated calls for the same <target> append items
6259       in the order called.
6260
6261       Each <item> may be:
6262
6263       · A library target name: The generated link line  will  have  the  full
6264         path  to  the  linkable library file associated with the target.  The
6265         buildsystem will have a dependency to re-link <target> if the library
6266         file changes.
6267
6268         The  named target must be created by add_library() within the project
6269         or as an IMPORTED library.  If it is created within  the  project  an
6270         ordering  dependency  will automatically be added in the build system
6271         to make sure the named library target is up-to-date before the  <tar‐
6272         get> links.
6273
6274         If  an  imported  library  has the IMPORTED_NO_SONAME target property
6275         set, CMake may ask the linker to search for the  library  instead  of
6276         using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
6277
6278         The full path to the target’s artifact will be quoted/escaped for the
6279         shell automatically.
6280
6281       · A full path to a library file: The generated link line will  normally
6282         preserve  the  full  path  to  the  file. The buildsystem will have a
6283         dependency to re-link <target> if the library file changes.
6284
6285         There are some cases where CMake may ask the linker to search for the
6286         library  (e.g.  /usr/lib/libfoo.so  becomes  -lfoo),  such  as when a
6287         shared library is detected to  have  no  SONAME  field.   See  policy
6288         CMP0060 for discussion of another case.
6289
6290         If  the library file is in a Mac OSX framework, the Headers directory
6291         of the framework will also be processed as a usage requirement.  This
6292         has  the same effect as passing the framework directory as an include
6293         directory.
6294
6295         On Visual Studio Generators for VS 2010 and above, library files end‐
6296         ing in .targets will be treated as MSBuild targets files and imported
6297         into generated project files.  This is not supported by other genera‐
6298         tors.
6299
6300         The  full  path  to  the  library file will be quoted/escaped for the
6301         shell automatically.
6302
6303       · A plain library name: The generated link line will ask the linker  to
6304         search for the library (e.g. foo becomes -lfoo or foo.lib).
6305
6306         The  library  name/flag  is treated as a command-line string fragment
6307         and will be used with no extra quoting or escaping.
6308
6309       · A link flag: Item names starting with -, but not  -l  or  -framework,
6310         are  treated  as  linker flags.  Note that such flags will be treated
6311         like any other library link item for purposes of transitive dependen‐
6312         cies,  so  they  are  generally  safe to specify only as private link
6313         items that will not propagate to dependents.
6314
6315         Link flags specified here are inserted into the link command  in  the
6316         same  place as the link libraries. This might not be correct, depend‐
6317         ing on the linker. Use  the  LINK_OPTIONS  target  property  or  tar‐
6318         get_link_options()  command  to  add link flags explicitly. The flags
6319         will then be placed at the toolchain-defined  flag  position  in  the
6320         link command.
6321
6322         The  link  flag is treated as a command-line string fragment and will
6323         be used with no extra quoting or escaping.
6324
6325       · A generator expression: A $<...> generator expression may evaluate to
6326         any  of the above items or to a semicolon-separated list of them.  If
6327         the ... contains any ; characters, e.g. after evaluation of a ${list}
6328         variable,  be  sure  to use an explicitly quoted argument "$<...>" so
6329         that this command receives it as a single <item>.
6330
6331         Additionally, a generator expression may be used as a fragment of any
6332         of the above items, e.g. foo$<1:_d>.
6333
6334         Note  that  generator expressions will not be used in OLD handling of
6335         policy CMP0003 or policy CMP0004.
6336
6337       · A debug,  optimized,  or  general  keyword  immediately  followed  by
6338         another  <item>.  The item following such a keyword will be used only
6339         for the corresponding build configuration.  The debug keyword  corre‐
6340         sponds  to the Debug configuration (or to configurations named in the
6341         DEBUG_CONFIGURATIONS global property if it is  set).   The  optimized
6342         keyword corresponds to all other configurations.  The general keyword
6343         corresponds to all configurations, and is  purely  optional.   Higher
6344         granularity  may  be achieved for per-configuration rules by creating
6345         and linking to IMPORTED library targets.  These keywords  are  inter‐
6346         preted  immediately  by  this  command  and therefore have no special
6347         meaning when produced by a generator expression.
6348
6349       Items containing ::, such as Foo::Bar, are assumed to  be  IMPORTED  or
6350       ALIAS  library  target  names and will cause an error if no such target
6351       exists.  See policy CMP0028.
6352
6353       See the cmake-buildsystem(7) manual for more  on  defining  buildsystem
6354       properties.
6355
6356   Libraries for a Target and/or its Dependents
6357          target_link_libraries(<target>
6358                                <PRIVATE|PUBLIC|INTERFACE> <item>...
6359                               [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
6360
6361       The  PUBLIC, PRIVATE and INTERFACE keywords can be used to specify both
6362       the link dependencies and the link interface in one command.  Libraries
6363       and  targets  following  PUBLIC are linked to, and are made part of the
6364       link interface.  Libraries and targets following PRIVATE are linked to,
6365       but  are  not  made  part  of  the link interface.  Libraries following
6366       INTERFACE are appended to the link interface and are not used for link‐
6367       ing <target>.
6368
6369   Libraries for both a Target and its Dependents
6370          target_link_libraries(<target> <item>...)
6371
6372       Library  dependencies  are  transitive  by default with this signature.
6373       When this target is linked  into  another  target  then  the  libraries
6374       linked to this target will appear on the link line for the other target
6375       too.   This  transitive  “link  interface”  is  stored  in  the  INTER‐
6376       FACE_LINK_LIBRARIES  target  property  and may be overridden by setting
6377       the property directly.  When CMP0022 is  not  set  to  NEW,  transitive
6378       linking   is  built  in  but  may  be  overridden  by  the  LINK_INTER‐
6379       FACE_LIBRARIES property.  Calls to other signatures of this command may
6380       set the property making any libraries linked exclusively by this signa‐
6381       ture private.
6382
6383   Libraries for a Target and/or its Dependents (Legacy)
6384          target_link_libraries(<target>
6385                                <LINK_PRIVATE|LINK_PUBLIC> <lib>...
6386                               [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
6387
6388       The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both  the
6389       link dependencies and the link interface in one command.
6390
6391       This signature is for compatibility only.  Prefer the PUBLIC or PRIVATE
6392       keywords instead.
6393
6394       Libraries and targets following LINK_PUBLIC are linked to, and are made
6395       part  of  the  INTERFACE_LINK_LIBRARIES.  If policy CMP0022 is not NEW,
6396       they are also made part of the LINK_INTERFACE_LIBRARIES.  Libraries and
6397       targets  following LINK_PRIVATE are linked to, but are not made part of
6398       the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
6399
6400   Libraries for Dependents Only (Legacy)
6401          target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
6402
6403       The LINK_INTERFACE_LIBRARIES mode appends the libraries to  the  INTER‐
6404       FACE_LINK_LIBRARIES  target property instead of using them for linking.
6405       If policy CMP0022 is not NEW, then this mode also appends libraries  to
6406       the LINK_INTERFACE_LIBRARIES and its per-configuration equivalent.
6407
6408       This  signature  is  for compatibility only.  Prefer the INTERFACE mode
6409       instead.
6410
6411       Libraries specified as debug are wrapped in a generator  expression  to
6412       correspond  to  debug  builds.   If  policy  CMP0022  is  not  NEW, the
6413       libraries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
6414       erty  (or  to  the properties corresponding to configurations listed in
6415       the DEBUG_CONFIGURATIONS global property  if  it  is  set).   Libraries
6416       specified  as  optimized  are  appended to the INTERFACE_LINK_LIBRARIES
6417       property.  If policy CMP0022 is not NEW, they are also appended to  the
6418       LINK_INTERFACE_LIBRARIES  property.  Libraries specified as general (or
6419       without any keyword) are treated as if specified  for  both  debug  and
6420       optimized.
6421
6422   Linking Object Libraries
6423       Object  Libraries  may be used as the <target> (first) argument of tar‐
6424       get_link_libraries to specify dependencies of their  sources  on  other
6425       libraries.  For example, the code
6426
6427          add_library(A SHARED a.c)
6428          target_compile_definitions(A PUBLIC A)
6429
6430          add_library(obj OBJECT obj.c)
6431          target_compile_definitions(obj PUBLIC OBJ)
6432          target_link_libraries(obj PUBLIC A)
6433
6434       compiles  obj.c  with  -DA -DOBJ and establishes usage requirements for
6435       obj that propagate to its dependents.
6436
6437       Normal libraries and executables may link to Object  Libraries  to  get
6438       their  objects  and  usage requirements.  Continuing the above example,
6439       the code
6440
6441          add_library(B SHARED b.c)
6442          target_link_libraries(B PUBLIC obj)
6443
6444       compiles b.c with -DA -DOBJ, creates shared library B with object files
6445       from b.c and obj.c, and links B to A.  Furthermore, the code
6446
6447          add_executable(main main.c)
6448          target_link_libraries(main B)
6449
6450       compiles  main.c  with  -DA -DOBJ and links executable main to B and A.
6451       The object library’s usage  requirements  are  propagated  transitively
6452       through B, but its object files are not.
6453
6454       Object  Libraries  may  “link”  to  other object libraries to get usage
6455       requirements, but since they do not have a link step  nothing  is  done
6456       with their object files.  Continuing from the above example, the code:
6457
6458          add_library(obj2 OBJECT obj2.c)
6459          target_link_libraries(obj2 PUBLIC obj)
6460
6461          add_executable(main2 main2.c)
6462          target_link_libraries(main2 obj2)
6463
6464       compiles  obj2.c  with  -DA -DOBJ, creates executable main2 with object
6465       files from main2.c and obj2.c, and links main2 to A.
6466
6467       In other words, when Object  Libraries  appear  in  a  target’s  INTER‐
6468       FACE_LINK_LIBRARIES   property   they  will  be  treated  as  Interface
6469       Libraries, but when they appear in a target’s  LINK_LIBRARIES  property
6470       their object files will be included in the link too.
6471
6472   Cyclic Dependencies of Static Libraries
6473       The  library  dependency  graph is normally acyclic (a DAG), but in the
6474       case of mutually-dependent STATIC libraries CMake allows the  graph  to
6475       contain  cycles  (strongly  connected components).  When another target
6476       links to one of the libraries, CMake repeats the entire connected  com‐
6477       ponent.  For example, the code
6478
6479          add_library(A STATIC a.c)
6480          add_library(B STATIC b.c)
6481          target_link_libraries(A B)
6482          target_link_libraries(B A)
6483          add_executable(main main.c)
6484          target_link_libraries(main A)
6485
6486       links  main  to  A  B A B.  While one repetition is usually sufficient,
6487       pathological object file and symbol arrangements can require more.  One
6488       may  handle  such cases by using the LINK_INTERFACE_MULTIPLICITY target
6489       property or by manually  repeating  the  component  in  the  last  tar‐
6490       get_link_libraries call.  However, if two archives are really so inter‐
6491       dependent they should probably be combined into a single archive,  per‐
6492       haps by using Object Libraries.
6493
6494   Creating Relocatable Packages
6495       Note  that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
6496       of a target with absolute paths to dependencies.  That would  hard-code
6497       into  installed  packages  the  library  file paths for dependencies as
6498       found on the machine the package was made on.
6499
6500       See the Creating Relocatable Packages section of the  cmake-packages(7)
6501       manual for discussion of additional care that must be taken when speci‐
6502       fying usage requirements while creating packages for redistribution.
6503
6504   target_link_options
6505       Add link options to a target.
6506
6507          target_link_options(<target> [BEFORE]
6508            <INTERFACE|PUBLIC|PRIVATE> [items1...]
6509            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6510
6511       Specifies link options to use when linking a given target.   The  named
6512       <target>  must  have been created by a command such as add_executable()
6513       or add_library() and must not be an ALIAS target.
6514
6515       If BEFORE is specified, the content will be prepended to  the  property
6516       instead of being appended.
6517
6518       This  command  can be used to add any options, but alternative commands
6519       exist to add libraries (target_link_libraries() and  link_libraries()).
6520       See documentation of the directory and target LINK_OPTIONS properties.
6521
6522       The  INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
6523       scope of the following arguments.  PRIVATE and PUBLIC items will  popu‐
6524       late the LINK_OPTIONS property of <target>.  PUBLIC and INTERFACE items
6525       will  populate  the  INTERFACE_LINK_OPTIONS   property   of   <target>.
6526       (IMPORTED  targets  only support INTERFACE items.)  The following argu‐
6527       ments specify link options.   Repeated  calls  for  the  same  <target>
6528       append items in the order called.
6529
6530       Arguments  to  target_link_options may use “generator expressions” with
6531       the syntax $<...>. See the  cmake-generator-expressions(7)  manual  for
6532       available expressions.  See the cmake-buildsystem(7) manual for more on
6533       defining buildsystem properties.
6534
6535       The final set of compile or link options used  for  a  target  is  con‐
6536       structed  by accumulating options from the current target and the usage
6537       requirements of it dependencies.  The set of options  is  de-duplicated
6538       to  avoid  repetition.   While  beneficial  for individual options, the
6539       de-duplication step can break up option groups.  For example, -D A -D B
6540       becomes  -D  A  B.  One may specify a group of options using shell-like
6541       quoting along with a SHELL: prefix.  The SHELL: prefix is  dropped  and
6542       the  rest of the option string is parsed using the separate_arguments()
6543       UNIX_COMMAND mode.  For example, "SHELL:-D A" "SHELL:-D B" becomes -D A
6544       -D B.
6545
6546       To  pass  options  to  the linker tool, each compiler driver has is own
6547       syntax.  The LINKER: prefix can be used to specify, in a portable  way,
6548       options  to  pass to the linker tool. The LINKER: prefix is replaced by
6549       the required driver option and the rest of the  option  string  defines
6550       linker  arguments using , as separator. These arguments will be format‐
6551       ted   according    to    the    CMAKE_<LANG>_LINKER_WRAPPER_FLAG    and
6552       CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
6553
6554       For  example,  "LINKER:-z,defs"  becomes  -Xlinker -z -Xlinker defs for
6555       Clang and -Wl,-z,defs for GNU GCC.
6556
6557       The LINKER: prefix can be specified as part of a SHELL: prefix  expres‐
6558       sion.
6559
6560       The  LINKER:  prefix  supports,  as  alternate syntax, specification of
6561       arguments using SHELL: prefix and space as separator. Previous  example
6562       becomes "LINKER:SHELL:-z defs".
6563
6564       NOTE:
6565          Specifying  SHELL:  prefix  elsewhere  than  at the beginning of the
6566          LINKER: prefix is not supported.
6567
6568   target_sources
6569       Add sources to a target.
6570
6571          target_sources(<target>
6572            <INTERFACE|PUBLIC|PRIVATE> [items1...]
6573            [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
6574
6575       Specifies sources to use  when  compiling  a  given  target.   Relative
6576       source  file  paths  are  interpreted  as being relative to the current
6577       source directory (i.e. CMAKE_CURRENT_SOURCE_DIR).  The  named  <target>
6578       must  have  been  created  by  a  command  such  as add_executable() or
6579       add_library() and must not be an ALIAS target.
6580
6581       The INTERFACE, PUBLIC and PRIVATE keywords are required to specify  the
6582       scope  of the following arguments.  PRIVATE and PUBLIC items will popu‐
6583       late the SOURCES property of <target>.  PUBLIC and INTERFACE items will
6584       populate the INTERFACE_SOURCES property of <target>.  (IMPORTED targets
6585       only  support  INTERFACE  items.)   The  following  arguments   specify
6586       sources.   Repeated  calls  for  the  same <target> append items in the
6587       order called.
6588
6589       Arguments to target_sources may use “generator  expressions”  with  the
6590       syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
6591       able expressions.  See the  cmake-buildsystem(7)  manual  for  more  on
6592       defining buildsystem properties.
6593
6594       See  also the CMP0076 policy for older behavior related to the handling
6595       of relative source file paths.
6596
6597   try_compile
6598       Try building some code.
6599
6600   Try Compiling Whole Projects
6601          try_compile(<resultVar> <bindir> <srcdir>
6602                      <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
6603                      [OUTPUT_VARIABLE <var>])
6604
6605       Try building a project.  The success or  failure  of  the  try_compile,
6606       i.e. TRUE or FALSE respectively, is returned in <resultVar>.
6607
6608       In  this  form, <srcdir> should contain a complete CMake project with a
6609       CMakeLists.txt file and all sources.  The <bindir>  and  <srcdir>  will
6610       not  be  deleted  after  this  command is run.  Specify <targetName> to
6611       build a specific target instead of the all or  ALL_BUILD  target.   See
6612       below for the meaning of other options.
6613
6614   Try Compiling Source Files
6615          try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
6616                      [CMAKE_FLAGS <flags>...]
6617                      [COMPILE_DEFINITIONS <defs>...]
6618                      [LINK_OPTIONS <options>...]
6619                      [LINK_LIBRARIES <libs>...]
6620                      [OUTPUT_VARIABLE <var>]
6621                      [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
6622                      [<LANG>_STANDARD <std>]
6623                      [<LANG>_STANDARD_REQUIRED <bool>]
6624                      [<LANG>_EXTENSIONS <bool>]
6625                      )
6626
6627       Try  building  an  executable or static library from one or more source
6628       files (which one is  determined  by  the  CMAKE_TRY_COMPILE_TARGET_TYPE
6629       variable).   The  success  or  failure of the try_compile, i.e. TRUE or
6630       FALSE respectively, is returned in <resultVar>.
6631
6632       In  this  form,  one  or  more  source  files  must  be  provided.   If
6633       CMAKE_TRY_COMPILE_TARGET_TYPE  is  unset  or  is set to EXECUTABLE, the
6634       sources must include a definition for main  and  CMake  will  create  a
6635       CMakeLists.txt  file  to  build  the  source(s)  as  an executable.  If
6636       CMAKE_TRY_COMPILE_TARGET_TYPE  is  set  to  STATIC_LIBRARY,  a   static
6637       library  will  be built instead and no definition for main is required.
6638       For an executable, the  generated  CMakeLists.txt  file  would  contain
6639       something like the following:
6640
6641          add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
6642          include_directories(${INCLUDE_DIRECTORIES})
6643          link_directories(${LINK_DIRECTORIES})
6644          add_executable(cmTryCompileExec <srcfile>...)
6645          target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
6646          target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
6647
6648       The options are:
6649
6650       CMAKE_FLAGS <flags>...
6651              Specify  flags  of the form -DVAR:TYPE=VALUE to be passed to the
6652              cmake command-line used to drive  the  test  build.   The  above
6653              example  shows  how  values  for  variables INCLUDE_DIRECTORIES,
6654              LINK_DIRECTORIES, and LINK_LIBRARIES are used.
6655
6656       COMPILE_DEFINITIONS <defs>...
6657              Specify -Ddefinition arguments to pass to  add_definitions()  in
6658              the generated test project.
6659
6660       COPY_FILE <fileName>
6661              Copy  the built executable or static library to the given <file‐
6662              Name>.
6663
6664       COPY_FILE_ERROR <var>
6665              Use after COPY_FILE to capture into  variable  <var>  any  error
6666              message encountered while trying to copy the file.
6667
6668       LINK_LIBRARIES <libs>...
6669              Specify  libraries  to  be linked in the generated project.  The
6670              list of libraries may refer to system libraries and to  Imported
6671              Targets from the calling project.
6672
6673              If  this  option  is  specified,  any -DLINK_LIBRARIES=... value
6674              given to the CMAKE_FLAGS option will be ignored.
6675
6676       LINK_OPTIONS <options>...
6677              Specify link step options to pass to target_link_options() or to
6678              set  the STATIC_LIBRARY_OPTIONS target property in the generated
6679              project, depending on  the  CMAKE_TRY_COMPILE_TARGET_TYPE  vari‐
6680              able.
6681
6682       OUTPUT_VARIABLE <var>
6683              Store the output from the build process in the given variable.
6684
6685       <LANG>_STANDARD <std>
6686              Specify  the  C_STANDARD,  CXX_STANDARD, or CUDA_STANDARD target
6687              property of the generated project.
6688
6689       <LANG>_STANDARD_REQUIRED <bool>
6690              Specify  the  C_STANDARD_REQUIRED,   CXX_STANDARD_REQUIRED,   or
6691              CUDA_STANDARD_REQUIRED target property of the generated project.
6692
6693       <LANG>_EXTENSIONS <bool>
6694              Specify  the  C_EXTENSIONS,  CXX_EXTENSIONS,  or CUDA_EXTENSIONS
6695              target property of the generated project.
6696
6697       In this version  all  files  in  <bindir>/CMakeFiles/CMakeTmp  will  be
6698       cleaned automatically.  For debugging, --debug-trycompile can be passed
6699       to cmake to avoid this clean.  However, multiple sequential try_compile
6700       operations   reuse   this   single   output   directory.   If  you  use
6701       --debug-trycompile, you can only debug one try_compile call at a  time.
6702       The  recommended  procedure is to protect all try_compile calls in your
6703       project by if(NOT DEFINED <resultVar>) logic, configure with cmake  all
6704       the  way  through once, then delete the cache entry associated with the
6705       try_compile  call  of  interest,  and  then  re-run  cmake  again  with
6706       --debug-trycompile.
6707
6708   Other Behavior Settings
6709       If set, the following variables are passed in to the generated try_com‐
6710       pile  CMakeLists.txt  to  initialize  compile  target  properties  with
6711       default values:
6712
6713       · CMAKE_ENABLE_EXPORTS
6714
6715       · CMAKE_LINK_SEARCH_START_STATIC
6716
6717       · CMAKE_LINK_SEARCH_END_STATIC
6718
6719       · CMAKE_POSITION_INDEPENDENT_CODE
6720
6721       If  CMP0056  is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
6722       well.
6723
6724       If CMP0083 is set to NEW, then in order to obtain correct  behavior  at
6725       link time, the check_pie_supported() command from the CheckPIESupported
6726       module must be called before using the try_compile() command.
6727
6728       The current settings of CMP0065 and CMP0083 are propagated  through  to
6729       the generated test project.
6730
6731       Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
6732       figuration.
6733
6734       Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to specify the  type  of
6735       target used for the source file signature.
6736
6737       Set  the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable to specify vari‐
6738       ables that must be propagated into the test project.  This variable  is
6739       meant  for  use  only  in  toolchain  files  and is only honored by the
6740       try_compile() command for the source files form, not when given a whole
6741       project.
6742
6743       If  CMP0067  is set to NEW, or any of the <LANG>_STANDARD, <LANG>_STAN‐
6744       DARD_REQUIRED, or <LANG>_EXTENSIONS options are used, then the language
6745       standard variables are honored:
6746
6747       · CMAKE_C_STANDARD
6748
6749       · CMAKE_C_STANDARD_REQUIRED
6750
6751       · CMAKE_C_EXTENSIONS
6752
6753       · CMAKE_CXX_STANDARD
6754
6755       · CMAKE_CXX_STANDARD_REQUIRED
6756
6757       · CMAKE_CXX_EXTENSIONS
6758
6759       · CMAKE_CUDA_STANDARD
6760
6761       · CMAKE_CUDA_STANDARD_REQUIRED
6762
6763       · CMAKE_CUDA_EXTENSIONS
6764
6765       Their values are used to set the corresponding target properties in the
6766       generated project (unless overridden by an explicit option).
6767
6768       For the Green Hills MULTI generator the GHS toolset and  target  system
6769       customization  cache  variables  are  also  propagated  into  the  test
6770       project.
6771
6772   try_run
6773       Try compiling and then running some code.
6774
6775   Try Compiling and Running Source Files
6776          try_run(<runResultVar> <compileResultVar>
6777                  <bindir> <srcfile> [CMAKE_FLAGS <flags>...]
6778                  [COMPILE_DEFINITIONS <defs>...]
6779                  [LINK_OPTIONS <options>...]
6780                  [LINK_LIBRARIES <libs>...]
6781                  [COMPILE_OUTPUT_VARIABLE <var>]
6782                  [RUN_OUTPUT_VARIABLE <var>]
6783                  [OUTPUT_VARIABLE <var>]
6784                  [ARGS <args>...])
6785
6786       Try compiling a <srcfile>.  Returns TRUE or FALSE for success or  fail‐
6787       ure  in  <compileResultVar>.   If  the compile succeeded, runs the exe‐
6788       cutable and returns its exit code in <runResultVar>.  If the executable
6789       was  built,  but  failed  to  run,  then  <runResultVar> will be set to
6790       FAILED_TO_RUN.  See the try_compile() command for  information  on  how
6791       the test project is constructed to build the source file.
6792
6793       The options are:
6794
6795       CMAKE_FLAGS <flags>...
6796              Specify  flags  of the form -DVAR:TYPE=VALUE to be passed to the
6797              cmake command-line used to drive the test build.  The example in
6798              try_compile()  shows  how  values for variables INCLUDE_DIRECTO‐
6799              RIES, LINK_DIRECTORIES, and LINK_LIBRARIES are used.
6800
6801       COMPILE_DEFINITIONS <defs>...
6802              Specify -Ddefinition arguments to pass to  add_definitions()  in
6803              the generated test project.
6804
6805       COMPILE_OUTPUT_VARIABLE <var>
6806              Report the compile step build output in a given variable.
6807
6808       LINK_LIBRARIES <libs>...
6809              Specify  libraries  to  be linked in the generated project.  The
6810              list of libraries may refer to system libraries and to  Imported
6811              Targets from the calling project.
6812
6813              If  this  option  is  specified,  any -DLINK_LIBRARIES=... value
6814              given to the CMAKE_FLAGS option will be ignored.
6815
6816       LINK_OPTIONS <options>...
6817              Specify link step options to pass  to  target_link_options()  in
6818              the generated project.
6819
6820       OUTPUT_VARIABLE <var>
6821              Report  the compile build output and the output from running the
6822              executable in the given variable.  This option exists for legacy
6823              reasons.  Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE
6824              instead.
6825
6826       RUN_OUTPUT_VARIABLE <var>
6827              Report the output from running the executable in a  given  vari‐
6828              able.
6829
6830   Other Behavior Settings
6831       Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
6832       figuration.
6833
6834   Behavior when Cross Compiling
6835       When cross compiling, the executable compiled in the first step usually
6836       cannot  be  run  on  the  build  host.   The try_run command checks the
6837       CMAKE_CROSSCOMPILING variable to detect whether CMake is in  cross-com‐
6838       piling  mode.   If  that  is the case, it will still try to compile the
6839       executable, but it will not  try  to  run  the  executable  unless  the
6840       CMAKE_CROSSCOMPILING_EMULATOR  variable is set.  Instead it will create
6841       cache variables which must be filled by the user or by presetting  them
6842       in  some CMake script file to the values the executable would have pro‐
6843       duced if it had been run on its actual target  platform.   These  cache
6844       entries are:
6845
6846       <runResultVar>
6847              Exit  code  if the executable were to be run on the target plat‐
6848              form.
6849
6850       <runResultVar>__TRYRUN_OUTPUT
6851              Output from stdout and stderr if the executable were to  be  run
6852              on  the  target  platform.  This is created only if the RUN_OUT‐
6853              PUT_VARIABLE or OUTPUT_VARIABLE option was used.
6854
6855       In order to make cross compiling your project easier, use try_run  only
6856       if really required.  If you use try_run, use the RUN_OUTPUT_VARIABLE or
6857       OUTPUT_VARIABLE options only  if  really  required.   Using  them  will
6858       require  that when cross-compiling, the cache variables will have to be
6859       set manually to the output of the executable.  You can also “guard” the
6860       calls  to  try_run with an if() block checking the CMAKE_CROSSCOMPILING
6861       variable and provide an easy-to-preset alternative for this case.
6862

CTEST COMMANDS

6864       These commands are available only in CTest scripts.
6865
6866   ctest_build
6867       Perform the CTest Build Step as a Dashboard Client.
6868
6869          ctest_build([BUILD <build-dir>] [APPEND]
6870                      [CONFIGURATION <config>]
6871                      [FLAGS <flags>]
6872                      [PROJECT_NAME <project-name>]
6873                      [TARGET <target-name>]
6874                      [NUMBER_ERRORS <num-err-var>]
6875                      [NUMBER_WARNINGS <num-warn-var>]
6876                      [RETURN_VALUE <result-var>]
6877                      [CAPTURE_CMAKE_ERROR <result-var>]
6878                      )
6879
6880       Build the project and store results in Build.xml  for  submission  with
6881       the ctest_submit() command.
6882
6883       The  CTEST_BUILD_COMMAND  variable may be set to explicitly specify the
6884       build command line.  Otherwise the build command line is computed auto‐
6885       matically based on the options given.
6886
6887       The options are:
6888
6889       BUILD <build-dir>
6890              Specify  the  top-level  build  directory.   If  not  given, the
6891              CTEST_BINARY_DIRECTORY variable is used.
6892
6893       APPEND Mark Build.xml for append to results previously submitted  to  a
6894              dashboard  server  since  the  last  ctest_start() call.  Append
6895              semantics are defined by the dashboard server in use.  This does
6896              not  cause  results  to be appended to a .xml file produced by a
6897              previous call to this command.
6898
6899       CONFIGURATION <config>
6900              Specify the build configuration (e.g. Debug).  If not  specified
6901              the  CTEST_BUILD_CONFIGURATION variable will be checked.  Other‐
6902              wise the -C <cfg> option given to the ctest(1) command  will  be
6903              used, if any.
6904
6905       FLAGS <flags>
6906              Pass  additional  arguments to the underlying build command.  If
6907              not specified the CTEST_BUILD_FLAGS variable  will  be  checked.
6908              This can, e.g., be used to trigger a parallel build using the -j
6909              option of make. See the ProcessorCount module for an example.
6910
6911       PROJECT_NAME <project-name>
6912              Ignored.  This was once used but is no longer needed.
6913
6914       TARGET <target-name>
6915              Specify the name of a target to build.   If  not  specified  the
6916              CTEST_BUILD_TARGET  variable  will  be  checked.   Otherwise the
6917              default target will be built.  This is the “all” target  (called
6918              ALL_BUILD in Visual Studio Generators).
6919
6920       NUMBER_ERRORS <num-err-var>
6921              Store the number of build errors detected in the given variable.
6922
6923       NUMBER_WARNINGS <num-warn-var>
6924              Store  the  number of build warnings detected in the given vari‐
6925              able.
6926
6927       RETURN_VALUE <result-var>
6928              Store the return value of the native build  tool  in  the  given
6929              variable.
6930
6931       CAPTURE_CMAKE_ERROR <result-var>
6932              Store  in  the  <result-var> variable -1 if there are any errors
6933              running the command and prevent ctest from returning non-zero if
6934              an error occurs.
6935
6936       QUIET  Suppress  any  CTest-specific  non-error  output that would have
6937              been printed to the console otherwise.  The summary of  warnings
6938              /  errors,  as  well as the output from the native build tool is
6939              unaffected by this option.
6940
6941   ctest_configure
6942       Perform the CTest Configure Step as a Dashboard Client.
6943
6944          ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
6945                          [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
6946                          [CAPTURE_CMAKE_ERROR <result-var>])
6947
6948       Configure the project build tree and record  results  in  Configure.xml
6949       for submission with the ctest_submit() command.
6950
6951       The options are:
6952
6953       BUILD <build-dir>
6954              Specify  the  top-level  build  directory.   If  not  given, the
6955              CTEST_BINARY_DIRECTORY variable is used.
6956
6957       SOURCE <source-dir>
6958              Specify   the   source   directory.    If   not    given,    the
6959              CTEST_SOURCE_DIRECTORY variable is used.
6960
6961       APPEND Mark Configure.xml for append to results previously submitted to
6962              a dashboard server since the last  ctest_start()  call.   Append
6963              semantics are defined by the dashboard server in use.  This does
6964              not cause results to be appended to a .xml file  produced  by  a
6965              previous call to this command.
6966
6967       OPTIONS <options>
6968              Specify  command-line  arguments  to  pass  to the configuration
6969              tool.
6970
6971       RETURN_VALUE <result-var>
6972              Store in the <result-var>  variable  the  return  value  of  the
6973              native configuration tool.
6974
6975       CAPTURE_CMAKE_ERROR <result-var>
6976              Store  in  the  <result-var> variable -1 if there are any errors
6977              running the command and prevent ctest from returning non-zero if
6978              an error occurs.
6979
6980       QUIET  Suppress  any  CTest-specific non-error messages that would have
6981              otherwise been printed to the console.  Output from the underly‐
6982              ing configure command is not affected.
6983
6984   ctest_coverage
6985       Perform the CTest Coverage Step as a Dashboard Client.
6986
6987          ctest_coverage([BUILD <build-dir>] [APPEND]
6988                         [LABELS <label>...]
6989                         [RETURN_VALUE <result-var>]
6990                         [CAPTURE_CMAKE_ERROR <result-var]
6991                         [QUIET]
6992                         )
6993
6994       Collect  coverage tool results and stores them in Coverage.xml for sub‐
6995       mission with the ctest_submit() command.
6996
6997       The options are:
6998
6999       BUILD <build-dir>
7000              Specify the  top-level  build  directory.   If  not  given,  the
7001              CTEST_BINARY_DIRECTORY variable is used.
7002
7003       APPEND Mark  Coverage.xml for append to results previously submitted to
7004              a dashboard server since the last  ctest_start()  call.   Append
7005              semantics are defined by the dashboard server in use.  This does
7006              not cause results to be appended to a .xml file  produced  by  a
7007              previous call to this command.
7008
7009       LABELS Filter  the coverage report to include only source files labeled
7010              with at least one of the labels specified.
7011
7012       RETURN_VALUE <result-var>
7013              Store in the <result-var> variable 0 if coverage tools ran with‐
7014              out error and non-zero otherwise.
7015
7016       CAPTURE_CMAKE_ERROR <result-var>
7017              Store  in  the  <result-var> variable -1 if there are any errors
7018              running the command and prevent ctest from returning non-zero if
7019              an error occurs.
7020
7021       QUIET  Suppress  any  CTest-specific  non-error  output that would have
7022              been printed to the console otherwise.  The  summary  indicating
7023              how  many  lines  of  code  were  covered  is unaffected by this
7024              option.
7025
7026   ctest_empty_binary_directory
7027       empties the binary directory
7028
7029          ctest_empty_binary_directory( directory )
7030
7031       Removes a binary directory.  This  command  will  perform  some  checks
7032       prior  to  deleting  the  directory in an attempt to avoid malicious or
7033       accidental directory deletion.
7034
7035   ctest_memcheck
7036       Perform the CTest MemCheck Step as a Dashboard Client.
7037
7038          ctest_memcheck([BUILD <build-dir>] [APPEND]
7039                         [START <start-number>]
7040                         [END <end-number>]
7041                         [STRIDE <stride-number>]
7042                         [EXCLUDE <exclude-regex>]
7043                         [INCLUDE <include-regex>]
7044                         [EXCLUDE_LABEL <label-exclude-regex>]
7045                         [INCLUDE_LABEL <label-include-regex>]
7046                         [EXCLUDE_FIXTURE <regex>]
7047                         [EXCLUDE_FIXTURE_SETUP <regex>]
7048                         [EXCLUDE_FIXTURE_CLEANUP <regex>]
7049                         [PARALLEL_LEVEL <level>]
7050                         [TEST_LOAD <threshold>]
7051                         [SCHEDULE_RANDOM <ON|OFF>]
7052                         [STOP_TIME <time-of-day>]
7053                         [RETURN_VALUE <result-var>]
7054                         [DEFECT_COUNT <defect-count-var>]
7055                         [QUIET]
7056                         )
7057
7058       Run tests with a dynamic  analysis  tool  and  store  results  in  Mem‐
7059       Check.xml for submission with the ctest_submit() command.
7060
7061       Most options are the same as those for the ctest_test() command.
7062
7063       The options unique to this command are:
7064
7065       DEFECT_COUNT <defect-count-var>
7066              Store in the <defect-count-var> the number of defects found.
7067
7068   ctest_read_custom_files
7069       read CTestCustom files.
7070
7071          ctest_read_custom_files( directory ... )
7072
7073       Read  all  the  CTestCustom.ctest  or  CTestCustom.cmake files from the
7074       given directory.
7075
7076       By default, invoking ctest(1) without a script will read  custom  files
7077       from the binary directory.
7078
7079   ctest_run_script
7080       runs a ctest -S script
7081
7082          ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
7083                      script_file_name2 ... [RETURN_VALUE var])
7084
7085       Runs  a script or scripts much like if it was run from ctest -S.  If no
7086       argument is provided then the current script is run using  the  current
7087       settings  of  the  variables.   If  NEW_PROCESS  is specified then each
7088       script will be run in a separate process.If RETURN_VALUE  is  specified
7089       the return value of the last script run will be put into var.
7090
7091   ctest_sleep
7092       sleeps for some amount of time
7093
7094          ctest_sleep(<seconds>)
7095
7096       Sleep for given number of seconds.
7097
7098          ctest_sleep(<time1> <duration> <time2>)
7099
7100       Sleep for t=(time1 + duration - time2) seconds if t > 0.
7101
7102   ctest_start
7103       Starts the testing for a given model
7104
7105          ctest_start(<model> [<source> [<binary>]] [TRACK <track>] [QUIET])
7106
7107          ctest_start([<model> [<source> [<binary>]]] [TRACK <track>] APPEND [QUIET])
7108
7109       Starts  the  testing  for  a given model.  The command should be called
7110       after the binary directory is initialized.
7111
7112       The parameters are as follows:
7113
7114       <model>
7115              Set the dashboard model. Must be one of  Experimental,  Continu‐
7116              ous,  or  Nightly.  This  parameter is required unless APPEND is
7117              specified.
7118
7119       <source>
7120              Set the  source  directory.  If  not  specified,  the  value  of
7121              CTEST_SOURCE_DIRECTORY is used instead.
7122
7123       <binary>
7124              Set  the  binary  directory.  If  not  specified,  the  value of
7125              CTEST_BINARY_DIRECTORY is used instead.
7126
7127       TRACK <track>
7128              If TRACK is used, the submissions will go to the specified track
7129              on  the  CDash server. If no TRACK is specified, the name of the
7130              model is used by default.
7131
7132       APPEND If APPEND is used, the existing TAG is used rather than creating
7133              a  new  one  based on the current time stamp. If you use APPEND,
7134              you can omit the <model> and TRACK <track>  parameters,  because
7135              they will be read from the generated TAG file. For example:
7136
7137                 ctest_start(Experimental TRACK TrackExperimental)
7138
7139              Later, in another ctest -S script:
7140
7141                 ctest_start(APPEND)
7142
7143              When  the  second  script runs ctest_start(APPEND), it will read
7144              the Experimental model and TrackExperimental track from the  TAG
7145              file  generated  by the first ctest_start() command. Please note
7146              that if you call ctest_start(APPEND)  and  specify  a  different
7147              model  or track than in the first ctest_start() command, a warn‐
7148              ing will be issued, and the new model and track will be used.
7149
7150       QUIET  If QUIET is used, CTest will  suppress  any  non-error  messages
7151              that it otherwise would have printed to the console.
7152
7153       The  parameters  for ctest_start() can be issued in any order, with the
7154       exception that <model>, <source>, and <binary> have to appear  in  that
7155       order  with  respect  to  each  other.  The following are all valid and
7156       equivalent:
7157
7158          ctest_start(Experimental path/to/source path/to/binary TRACK SomeTrack QUIET APPEND)
7159
7160          ctest_start(TRACK SomeTrack Experimental QUIET path/to/source APPEND path/to/binary)
7161
7162          ctest_start(APPEND QUIET Experimental path/to/source TRACK SomeTrack path/to/binary)
7163
7164       However, for the sake of readability, it is recommended that you  order
7165       your parameters in the order listed at the top of this page.
7166
7167       If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
7168       able) is set, its content is treated as command-line.  The  command  is
7169       invoked  with  the  current  working directory set to the parent of the
7170       source directory, even if the source directory  already  exists.   This
7171       can  be  used  to create the source tree from a version control reposi‐
7172       tory.
7173
7174   ctest_submit
7175       Perform the CTest Submit Step as a Dashboard Client.
7176
7177          ctest_submit([PARTS <part>...] [FILES <file>...]
7178                       [SUBMIT_URL <url>]
7179                       [HTTPHEADER <header>]
7180                       [RETRY_COUNT <count>]
7181                       [RETRY_DELAY <delay>]
7182                       [RETURN_VALUE <result-var>]
7183                       [CAPTURE_CMAKE_ERROR <result-var>]
7184                       [QUIET]
7185                       )
7186
7187       Submit results to a dashboard server.  By default all  available  parts
7188       are submitted.
7189
7190       The options are:
7191
7192       PARTS <part>...
7193              Specify a subset of parts to submit.  Valid part names are:
7194
7195                 Start      = nothing
7196                 Update     = ctest_update results, in Update.xml
7197                 Configure  = ctest_configure results, in Configure.xml
7198                 Build      = ctest_build results, in Build.xml
7199                 Test       = ctest_test results, in Test.xml
7200                 Coverage   = ctest_coverage results, in Coverage.xml
7201                 MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
7202                 Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
7203                 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
7204                 Upload     = Files prepared for upload by ctest_upload(), in Upload.xml
7205                 Submit     = nothing
7206                 Done       = Build is complete, in Done.xml
7207
7208       FILES <file>...
7209              Specify  an  explicit  list  of  specific files to be submitted.
7210              Each individual file must exist at the time of the call.
7211
7212       SUBMIT_URL <url>
7213              The http or https URL of the dashboard server to send  the  sub‐
7214              mission  to.   If  not  given,  the CTEST_SUBMIT_URL variable is
7215              used.
7216
7217       HTTPHEADER <HTTP-header>
7218              Specify HTTP header to be included in the request to CDash  dur‐
7219              ing submission.  This suboption can be repeated several times.
7220
7221       RETRY_COUNT <count>
7222              Specify how many times to retry a timed-out submission.
7223
7224       RETRY_DELAY <delay>
7225              Specify  how long (in seconds) to wait after a timed-out submis‐
7226              sion before attempting to re-submit.
7227
7228       RETURN_VALUE <result-var>
7229              Store in the <result-var> variable 0 for success and non-zero on
7230              failure.
7231
7232       CAPTURE_CMAKE_ERROR <result-var>
7233              Store  in  the  <result-var> variable -1 if there are any errors
7234              running the command and prevent ctest from returning non-zero if
7235              an error occurs.
7236
7237       QUIET  Suppress  all  non-error messages that would have otherwise been
7238              printed to the console.
7239
7240   Submit to CDash Upload API
7241          ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
7242                       [SUBMIT_URL <url>]
7243                       [HTTPHEADER <header>]
7244                       [RETRY_COUNT <count>]
7245                       [RETRY_DELAY <delay>]
7246                       [RETURN_VALUE <result-var>]
7247                       [QUIET])
7248
7249       This second signature is used to upload files to CDash  via  the  CDash
7250       file upload API. The API first sends a request to upload to CDash along
7251       with a content hash of the file. If CDash does  not  already  have  the
7252       file,  then it is uploaded. Along with the file, a CDash type string is
7253       specified to tell CDash which handler to use to process the data.
7254
7255       This  signature  accepts  the  SUBMIT_URL,   HTTPHEADER,   RETRY_COUNT,
7256       RETRY_DELAY, RETURN_VALUE and QUIET options as described above.
7257
7258   ctest_test
7259       Perform the CTest Test Step as a Dashboard Client.
7260
7261          ctest_test([BUILD <build-dir>] [APPEND]
7262                     [START <start-number>]
7263                     [END <end-number>]
7264                     [STRIDE <stride-number>]
7265                     [EXCLUDE <exclude-regex>]
7266                     [INCLUDE <include-regex>]
7267                     [EXCLUDE_LABEL <label-exclude-regex>]
7268                     [INCLUDE_LABEL <label-include-regex>]
7269                     [EXCLUDE_FIXTURE <regex>]
7270                     [EXCLUDE_FIXTURE_SETUP <regex>]
7271                     [EXCLUDE_FIXTURE_CLEANUP <regex>]
7272                     [PARALLEL_LEVEL <level>]
7273                     [TEST_LOAD <threshold>]
7274                     [SCHEDULE_RANDOM <ON|OFF>]
7275                     [STOP_TIME <time-of-day>]
7276                     [RETURN_VALUE <result-var>]
7277                     [CAPTURE_CMAKE_ERROR <result-var>]
7278                     [QUIET]
7279                     )
7280
7281       Run  tests  in the project build tree and store results in Test.xml for
7282       submission with the ctest_submit() command.
7283
7284       The options are:
7285
7286       BUILD <build-dir>
7287              Specify the  top-level  build  directory.   If  not  given,  the
7288              CTEST_BINARY_DIRECTORY variable is used.
7289
7290       APPEND Mark  Test.xml  for  append to results previously submitted to a
7291              dashboard server since  the  last  ctest_start()  call.   Append
7292              semantics are defined by the dashboard server in use.  This does
7293              not cause results to be appended to a .xml file  produced  by  a
7294              previous call to this command.
7295
7296       START <start-number>
7297              Specify the beginning of a range of test numbers.
7298
7299       END <end-number>
7300              Specify the end of a range of test numbers.
7301
7302       STRIDE <stride-number>
7303              Specify  the stride by which to step across a range of test num‐
7304              bers.
7305
7306       EXCLUDE <exclude-regex>
7307              Specify a regular expression matching test names to exclude.
7308
7309       INCLUDE <include-regex>
7310              Specify a regular expression matching  test  names  to  include.
7311              Tests not matching this expression are excluded.
7312
7313       EXCLUDE_LABEL <label-exclude-regex>
7314              Specify a regular expression matching test labels to exclude.
7315
7316       INCLUDE_LABEL <label-include-regex>
7317              Specify  a  regular  expression matching test labels to include.
7318              Tests not matching this expression are excluded.
7319
7320       EXCLUDE_FIXTURE <regex>
7321              If a test in the set of tests to be executed requires a particu‐
7322              lar  fixture,  that fixture’s setup and cleanup tests would nor‐
7323              mally be added to the test set automatically. This  option  pre‐
7324              vents  adding  setup  or cleanup tests for fixtures matching the
7325              <regex>. Note that  all  other  fixture  behavior  is  retained,
7326              including test dependencies and skipping tests that have fixture
7327              setup tests that fail.
7328
7329       EXCLUDE_FIXTURE_SETUP <regex>
7330              Same as EXCLUDE_FIXTURE except only  matching  setup  tests  are
7331              excluded.
7332
7333       EXCLUDE_FIXTURE_CLEANUP <regex>
7334              Same  as  EXCLUDE_FIXTURE except only matching cleanup tests are
7335              excluded.
7336
7337       PARALLEL_LEVEL <level>
7338              Specify a positive number representing the number of tests to be
7339              run in parallel.
7340
7341       TEST_LOAD <threshold>
7342              While  running  tests  in  parallel, try not to start tests when
7343              they may cause the CPU load to pass above a given threshold.  If
7344              not  specified the CTEST_TEST_LOAD variable will be checked, and
7345              then the --test-load command-line  argument  to  ctest(1).   See
7346              also the TestLoad setting in the CTest Test Step.
7347
7348       SCHEDULE_RANDOM <ON|OFF>
7349              Launch  tests in a random order.  This may be useful for detect‐
7350              ing implicit test dependencies.
7351
7352       STOP_TIME <time-of-day>
7353              Specify a time of day at which the tests should  all  stop  run‐
7354              ning.
7355
7356       RETURN_VALUE <result-var>
7357              Store in the <result-var> variable 0 if all tests passed.  Store
7358              non-zero if anything went wrong.
7359
7360       CAPTURE_CMAKE_ERROR <result-var>
7361              Store in the <result-var> variable -1 if there  are  any  errors
7362              running the command and prevent ctest from returning non-zero if
7363              an error occurs.
7364
7365       QUIET  Suppress any CTest-specific non-error messages that  would  have
7366              otherwise been printed to the console.  Output from the underly‐
7367              ing test command is not affected.  Summary  info  detailing  the
7368              percentage  of  passing  tests  is  also unaffected by the QUIET
7369              option.
7370
7371       See   also   the    CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE    and
7372       CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE variables.
7373
7374   ctest_update
7375       Perform the CTest Update Step as a Dashboard Client.
7376
7377          ctest_update([SOURCE <source-dir>]
7378                       [RETURN_VALUE <result-var>]
7379                       [CAPTURE_CMAKE_ERROR <result-var>]
7380                       [QUIET])
7381
7382       Update  the  source  tree  from  version  control and record results in
7383       Update.xml for submission with the ctest_submit() command.
7384
7385       The options are:
7386
7387       SOURCE <source-dir>
7388              Specify   the   source   directory.    If   not    given,    the
7389              CTEST_SOURCE_DIRECTORY variable is used.
7390
7391       RETURN_VALUE <result-var>
7392              Store  in  the <result-var> variable the number of files updated
7393              or -1 on error.
7394
7395       CAPTURE_CMAKE_ERROR <result-var>
7396              Store in the <result-var> variable -1 if there  are  any  errors
7397              running the command and prevent ctest from returning non-zero if
7398              an error occurs.
7399
7400       QUIET  Tell CTest to suppress most non-error  messages  that  it  would
7401              have  otherwise printed to the console.  CTest will still report
7402              the new revision of the repository  and  any  conflicting  files
7403              that were found.
7404
7405       The  update always follows the version control branch currently checked
7406       out in the source directory.  See the CTest Update  Step  documentation
7407       for more information.
7408
7409   ctest_upload
7410       Upload files to a dashboard server as a Dashboard Client.
7411
7412          ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
7413
7414       The options are:
7415
7416       FILES <file>...
7417              Specify  a list of files to be sent along with the build results
7418              to the dashboard server.
7419
7420       QUIET  Suppress any CTest-specific non-error  output  that  would  have
7421              been printed to the console otherwise.
7422
7423       CAPTURE_CMAKE_ERROR <result-var>
7424              Store  in  the  <result-var> variable -1 if there are any errors
7425              running the command and prevent ctest from returning non-zero if
7426              an error occurs.
7427

DEPRECATED COMMANDS

7429       These  commands  are deprecated and are only made available to maintain
7430       backward compatibility.  The documentation of each command  states  the
7431       CMake version in which it was deprecated.  Do not use these commands in
7432       new code.
7433
7434   build_name
7435       Disallowed since version 3.0.  See CMake Policy CMP0036.
7436
7437       Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
7438
7439          build_name(variable)
7440
7441       Sets the specified variable to a string representing the  platform  and
7442       compiler   settings.   These  values  are  now  available  through  the
7443       CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
7444
7445   exec_program
7446       Deprecated  since  version  3.0:  Use  the  execute_process()   command
7447       instead.
7448
7449
7450       Run  an  executable  program during the processing of the CMakeList.txt
7451       file.
7452
7453          exec_program(Executable [directory in which to run]
7454                       [ARGS <arguments to executable>]
7455                       [OUTPUT_VARIABLE <var>]
7456                       [RETURN_VALUE <var>])
7457
7458       The executable is run in the optionally specified directory.  The  exe‐
7459       cutable  can include arguments if it is double quoted, but it is better
7460       to use the optional ARGS argument to specify arguments to the  program.
7461       This  is  because  cmake will then be able to escape spaces in the exe‐
7462       cutable path.  An optional argument OUTPUT_VARIABLE specifies  a  vari‐
7463       able  in which to store the output.  To capture the return value of the
7464       execution, provide a RETURN_VALUE.  If  OUTPUT_VARIABLE  is  specified,
7465       then  no  output  will  go  to the stdout/stderr of the console running
7466       cmake.
7467
7468   export_library_dependencies
7469       Disallowed since version 3.0.  See CMake Policy CMP0033.
7470
7471       Use install(EXPORT) or export() command.
7472
7473       This  command  generates  an  old-style  library   dependencies   file.
7474       Projects  requiring CMake 2.6 or later should not use the command.  Use
7475       instead the install(EXPORT) command to  help  export  targets  from  an
7476       installation  tree  and  the  export() command to export targets from a
7477       build tree.
7478
7479       The old-style library dependencies file  does  not  take  into  account
7480       per-configuration  names  of  libraries or the LINK_INTERFACE_LIBRARIES
7481       target property.
7482
7483          export_library_dependencies(<file> [APPEND])
7484
7485       Create a file named <file> that can be included into a  CMake  listfile
7486       with  the  INCLUDE command.  The file will contain a number of SET com‐
7487       mands that will set all the variables  needed  for  library  dependency
7488       information.   This  should be the last command in the top level CMake‐
7489       Lists.txt file of the project.  If the APPEND option is specified,  the
7490       SET  commands  will  be appended to the given file instead of replacing
7491       it.
7492
7493   install_files
7494       Deprecated since version 3.0: Use the install(FILES) command instead.
7495
7496
7497       This command has been superceded by the install() command.  It is  pro‐
7498       vided  for  compatibility  with  older  CMake  code.  The FILES form is
7499       directly replaced by the FILES form of the install() command.  The reg‐
7500       exp  form  can  be  expressed  more  clearly using the GLOB form of the
7501       file() command.
7502
7503          install_files(<dir> extension file file ...)
7504
7505       Create rules to install the listed files with the given extension  into
7506       the given directory.  Only files existing in the current source tree or
7507       its corresponding location in the binary tree may be listed.  If a file
7508       specified  already  has  an  extension,  that extension will be removed
7509       first.  This is useful for providing lists  of  source  files  such  as
7510       foo.cxx when you want the corresponding foo.h to be installed.  A typi‐
7511       cal extension is ‘.h’.
7512
7513          install_files(<dir> regexp)
7514
7515       Any files in the  current  source  directory  that  match  the  regular
7516       expression will be installed.
7517
7518          install_files(<dir> FILES file file ...)
7519
7520       Any  files  listed after the FILES keyword will be installed explicitly
7521       from the names given.  Full paths are allowed in this form.
7522
7523       The directory <dir> is relative to the installation  prefix,  which  is
7524       stored in the variable CMAKE_INSTALL_PREFIX.
7525
7526   install_programs
7527       Deprecated   since  version  3.0:  Use  the  install(PROGRAMS)  command
7528       instead.
7529
7530
7531       This command has been superceded by the install() command.  It is  pro‐
7532       vided  for  compatibility  with  older  CMake  code.  The FILES form is
7533       directly replaced by the PROGRAMS form of the install()  command.   The
7534       regexp  form  can  be expressed more clearly using the GLOB form of the
7535       file() command.
7536
7537          install_programs(<dir> file1 file2 [file3 ...])
7538          install_programs(<dir> FILES file1 [file2 ...])
7539
7540       Create rules to install the listed programs into the  given  directory.
7541       Use  the  FILES argument to guarantee that the file list version of the
7542       command will be used even when there is only one argument.
7543
7544          install_programs(<dir> regexp)
7545
7546       In the second form any program in the  current  source  directory  that
7547       matches the regular expression will be installed.
7548
7549       This  command  is  intended  to  install programs that are not built by
7550       cmake, such as shell scripts.  See the TARGETS form  of  the  install()
7551       command to create installation rules for targets built by cmake.
7552
7553       The  directory  <dir>  is relative to the installation prefix, which is
7554       stored in the variable CMAKE_INSTALL_PREFIX.
7555
7556   install_targets
7557       Deprecated since version 3.0: Use the install(TARGETS) command instead.
7558
7559
7560       This command has been superceded by the install() command.  It is  pro‐
7561       vided for compatibility with older CMake code.
7562
7563          install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
7564
7565       Create  rules  to  install the listed targets into the given directory.
7566       The directory <dir> is relative to the installation  prefix,  which  is
7567       stored  in  the variable CMAKE_INSTALL_PREFIX.  If RUNTIME_DIRECTORY is
7568       specified, then on systems with special runtime  files  (Windows  DLL),
7569       the files will be copied to that directory.
7570
7571   load_command
7572       Disallowed since version 3.0.  See CMake Policy CMP0031.
7573
7574       Load a command into a running CMake.
7575
7576          load_command(COMMAND_NAME <loc1> [loc2 ...])
7577
7578       The  given  locations  are  searched for a library whose name is cmCOM‐
7579       MAND_NAME.  If found, it is loaded as a module and the command is added
7580       to the set of available CMake commands.  Usually, try_compile() is used
7581       before this command to compile the module.  If the command is  success‐
7582       fully loaded a variable named
7583
7584          CMAKE_LOADED_COMMAND_<COMMAND_NAME>
7585
7586       will  be set to the full path of the module that was loaded.  Otherwise
7587       the variable will not be set.
7588
7589   make_directory
7590       Deprecated since version  3.0:  Use  the  file(MAKE_DIRECTORY)  command
7591       instead.
7592
7593
7594          make_directory(directory)
7595
7596       Creates the specified directory.  Full paths should be given.  Any par‐
7597       ent directories that do not exist will also be created.  Use with care.
7598
7599   output_required_files
7600       Disallowed since version 3.0.  See CMake Policy CMP0032.
7601
7602       Approximate C preprocessor dependency scanning.
7603
7604       This command exists only because ancient CMake  versions  provided  it.
7605       CMake  handles  preprocessor  dependency scanning automatically using a
7606       more advanced scanner.
7607
7608          output_required_files(srcfile outputfile)
7609
7610       Outputs a list of all the source files that are required by the  speci‐
7611       fied  srcfile.   This list is written into outputfile.  This is similar
7612       to writing out the dependencies for srcfile except that it  jumps  from
7613       .h files into .cxx, .c and .cpp files if possible.
7614
7615   qt_wrap_cpp
7616       Deprecated  since  version  3.14:  This command was originally added to
7617       support Qt 3 before the add_custom_command() command  was  sufficiently
7618       mature.   The  FindQt4  module provides the qt4_wrap_cpp() macro, which
7619       should be used instead for Qt 4 projects.  For projects using Qt  5  or
7620       later,  use  the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
7621       vides qt5_wrap_cpp()).
7622
7623
7624       Manually create Qt Wrappers.
7625
7626          qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
7627
7628       Produces moc files for all the .h files listed in the SourceLists.  The
7629       moc files will be added to the library using the DestName source list.
7630
7631       Consider  updating  the  project  to  use  the  AUTOMOC target property
7632       instead for a more automated way of invoking the moc tool.
7633
7634   qt_wrap_ui
7635       Deprecated since version 3.14: This command  was  originally  added  to
7636       support  Qt  3 before the add_custom_command() command was sufficiently
7637       mature.  The FindQt4 module provides  the  qt4_wrap_ui()  macro,  which
7638       should  be  used instead for Qt 4 projects.  For projects using Qt 5 or
7639       later, use the equivalent macro provided by Qt itself (e.g. Qt  5  pro‐
7640       vides qt5_wrap_ui()).
7641
7642
7643       Manually create Qt user interfaces Wrappers.
7644
7645          qt_wrap_ui(resultingLibraryName HeadersDestName
7646                     SourcesDestName SourceLists ...)
7647
7648       Produces  .h  and  .cxx  files  for  all  the  .ui  files listed in the
7649       SourceLists.  The .h files will be added to the library using the Head‐
7650       ersDestNamesource  list.   The  .cxx files will be added to the library
7651       using the SourcesDestNamesource list.
7652
7653       Consider updating the  project  to  use  the  AUTOUIC  target  property
7654       instead for a more automated way of invoking the uic tool.
7655
7656   remove
7657       Deprecated   since  version  3.0:  Use  the  list(REMOVE_ITEM)  command
7658       instead.
7659
7660
7661          remove(VAR VALUE VALUE ...)
7662
7663       Removes VALUE from the variable VAR.  This is typically used to  remove
7664       entries  from  a  vector  (e.g.   semicolon  separated list).  VALUE is
7665       expanded.
7666
7667   subdir_depends
7668       Disallowed since version 3.0.  See CMake Policy CMP0029.
7669
7670       Does nothing.
7671
7672          subdir_depends(subdir dep1 dep2 ...)
7673
7674       Does not do anything.  This command used to help projects order  paral‐
7675       lel builds correctly.  This functionality is now automatic.
7676
7677   subdirs
7678       Deprecated  since  version  3.0:  Use  the  add_subdirectory()  command
7679       instead.
7680
7681
7682       Add a list of subdirectories to the build.
7683
7684          subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
7685                  [PREORDER] )
7686
7687       Add a list of subdirectories to the build.  The add_subdirectory() com‐
7688       mand  should  be  used  instead  of subdirs although subdirs will still
7689       work.  This will cause any CMakeLists.txt files in the sub  directories
7690       to  be processed by CMake.  Any directories after the PREORDER flag are
7691       traversed first by makefile builds, the PREORDER flag has no effect  on
7692       IDE  projects.   Any directories after the EXCLUDE_FROM_ALL marker will
7693       not be included in the top level makefile or  project  file.   This  is
7694       useful for having CMake create makefiles or projects for a set of exam‐
7695       ples in a project.  You would  want  CMake  to  generate  makefiles  or
7696       project  files for all the examples at the same time, but you would not
7697       want them to show up in the top level project or  be  built  each  time
7698       make is run from the top.
7699
7700   use_mangled_mesa
7701       Disallowed since version 3.0.  See CMake Policy CMP0030.
7702
7703       Copy mesa headers for use in combination with system GL.
7704
7705          use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
7706
7707       The  path to mesa includes, should contain gl_mangle.h.  The mesa head‐
7708       ers are copied to the specified output directory.  This allows  mangled
7709       mesa headers to override other GL headers by being added to the include
7710       directory path earlier.
7711
7712   utility_source
7713       Disallowed since version 3.0.  See CMake Policy CMP0034.
7714
7715       Specify the source tree of a third-party utility.
7716
7717          utility_source(cache_entry executable_name
7718                         path_to_source [file1 file2 ...])
7719
7720       When a third-party utility’s source is included  in  the  distribution,
7721       this command specifies its location and name.  The cache entry will not
7722       be set unless the path_to_source and all listed  files  exist.   It  is
7723       assumed that the source tree of the utility will have been built before
7724       it is needed.
7725
7726       When cross compiling CMake will print a warning if  a  utility_source()
7727       command  is executed, because in many cases it is used to build an exe‐
7728       cutable which is executed later on.  This doesn’t work when cross  com‐
7729       piling, since the executable can run only on their target platform.  So
7730       in this case the cache entry has to be adjusted manually so  it  points
7731       to an executable which is runnable on the build host.
7732
7733   variable_requires
7734       Disallowed since version 3.0.  See CMake Policy CMP0035.
7735
7736       Use the if() command instead.
7737
7738       Assert satisfaction of an option’s required variables.
7739
7740          variable_requires(TEST_VARIABLE RESULT_VARIABLE
7741                            REQUIRED_VARIABLE1
7742                            REQUIRED_VARIABLE2 ...)
7743
7744       The  first  argument  (TEST_VARIABLE) is the name of the variable to be
7745       tested, if that variable is false nothing else is done.  If  TEST_VARI‐
7746       ABLE  is  true,  then the next argument (RESULT_VARIABLE) is a variable
7747       that is set to true if all the required variables are set.  The rest of
7748       the arguments are variables that must be true or not set to NOTFOUND to
7749       avoid an error.  If any are not true, an error is reported.
7750
7751   write_file
7752       Deprecated since version 3.0: Use the file(WRITE) command instead.
7753
7754
7755          write_file(filename "message to write"... [APPEND])
7756
7757       The first argument is the file name, the rest of the arguments are mes‐
7758       sages  to write.  If the argument APPEND is specified, then the message
7759       will be appended.
7760
7761       NOTE 1: file(WRITE)  and file(APPEND)  do exactly the same as this  one
7762       but add some more functionality.
7763
7764       NOTE  2:  When  using write_file the produced file cannot be used as an
7765       input to CMake (CONFIGURE_FILE, source file …) because it will lead  to
7766       an  infinite  loop.  Use configure_file() if you want to generate input
7767       files to CMake.
7768
7770       2000-2019 Kitware, Inc. and Contributors
7771
7772
7773
7774
77753.14.5                           Jun 01, 2019                CMAKE-COMMANDS(7)
Impressum