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

NAME

6         ctest - Testing driver provided by CMake.
7
8

USAGE

10         ctest [options]
11
12

DESCRIPTION

14       The  "ctest" executable is the CMake test driver program.  CMake-gener‐
15       ated build trees created for projects that use the  ENABLE_TESTING  and
16       ADD_TEST  commands  have  testing  support.   This program will run the
17       tests and report results.
18
19

OPTIONS

21       -C <cfg>, --build-config <cfg>
22              Choose configuration to test.
23
24              Some CMake-generated build trees can have multiple build config‐
25              urations  in  the same tree.  This option can be used to specify
26              which one should be tested.  Example configurations are  "Debug"
27              and "Release".
28
29
30       -V,--verbose
31              Enable verbose output from tests.
32
33              Test  output is normally suppressed and only summary information
34              is displayed.  This option will show all test output.
35
36
37       -VV,--extra-verbose
38              Enable more verbose output from tests.
39
40              Test output is normally suppressed and only summary  information
41              is displayed.  This option will show even more test output.
42
43
44       --debug
45              Displaying more verbose internals of CTest.
46
47              This  feature  will  result  in a large number of output that is
48              mostly useful for debugging dashboard problems.
49
50
51       --output-on-failure
52              Output anything outputted by the test program if the test should
53              fail.   This  option can also be enabled by setting the environ‐
54              ment variable CTEST_OUTPUT_ON_FAILURE
55
56
57       -F     Enable failover.
58
59              This option allows ctest to resume a test set execution that was
60              previously  interrupted.   If  no  interruption occurred, the -F
61              option will have no effect.
62
63
64       -j <jobs>, --parallel <jobs>
65              Run the tests in parallel using thegiven number of jobs.
66
67              This option tells ctest to run the tests in parallel using given
68              number  of  jobs.   This  option  can also be set by setting the
69              environment variable CTEST_PARALLEL_LEVEL.
70
71
72       -Q,--quiet
73              Make ctest quiet.
74
75              This option will suppress all the output. The  output  log  file
76              will  still  be  generated  if  the  --output-log  is specified.
77              Options such as  --verbose,  --extra-verbose,  and  --debug  are
78              ignored if --quiet is specified.
79
80
81       -O <file>, --output-log <file>
82              Output to log file
83
84              This option tells ctest to write all its output to a log file.
85
86
87       -N,--show-only
88              Disable actual execution of tests.
89
90              This  option tells ctest to list the tests that would be run but
91              not actually run them.  Useful in conjunction with the -R and -E
92              options.
93
94
95       -L <regex>, --label-regex <regex>
96              Run tests with labels matching regular expression.
97
98              This option tells ctest to run only the tests whose labels match
99              the given regular expression.
100
101
102       -R <regex>, --tests-regex <regex>
103              Run tests matching regular expression.
104
105              This option tells ctest to run only the tests whose names  match
106              the given regular expression.
107
108
109       -E <regex>, --exclude-regex <regex>
110              Exclude tests matching regular expression.
111
112              This  option  tells ctest to NOT run the tests whose names match
113              the given regular expression.
114
115
116       -LE <regex>, --label-exclude <regex>
117              Exclude tests with labels matching regular expression.
118
119              This option tells ctest to NOT run the tests whose labels  match
120              the given regular expression.
121
122
123       -D <dashboard>, --dashboard <dashboard>
124              Execute dashboard test
125
126              This  option  tells  ctest to act as a Dart client and perform a
127              dashboard test. All tests are <Mode><Test>, where  Mode  can  be
128              Experimental,  Nightly,  and  Continuous, and Test can be Start,
129              Update, Configure, Build, Test, Coverage, and Submit.
130
131
132       -D <var>:<type>=<value>
133              Define a variable for script mode
134
135              Pass in variable values on the command line. Use in  conjunction
136              with  -S  to pass variable values to a dashboard script. Parsing
137              -D arguments as variable values is only attempted if  the  value
138              following -D does not match any of the known dashboard types.
139
140
141       -M <model>, --test-model <model>
142              Sets the model for a dashboard
143
144              This  option tells ctest to act as a Dart client where the Test‐
145              Model can be Experimental, Nightly, and Continuous. Combining -M
146              and -T is similar to -D
147
148
149       -T <action>, --test-action <action>
150              Sets the dashboard action to perform
151
152              This option tells ctest to act as a Dart client and perform some
153              action such as start, build, test etc. Combining -M  and  -T  is
154              similar to -D
155
156
157       --track <track>
158              Specify the track to submit dashboard to
159
160              Submit  dashboard  to specified track instead of default one. By
161              default, the dashboard is submitted to Nightly, Experimental, or
162              Continuous  track,  but by specifying this option, the track can
163              be arbitrary.
164
165
166       -S <script>, --script <script>
167              Execute a dashboard for a configuration
168
169              This option tells ctest to load in a configuration script  which
170              sets a number of parameters such as the binary and source direc‐
171              tories. Then ctest will do what is required to create and run  a
172              dashboard.  This  option  basically sets up a dashboard and then
173              runs ctest -D with the appropriate options.
174
175
176       -SP <script>, --script-new-process <script>
177              Execute a dashboard for a configuration
178
179              This option does the same operations as -S but it will  do  them
180              in  a  separate process. This is primarily useful in cases where
181              the script may modify the environment and you do  not  want  the
182              modified environment to impact other -S scripts.
183
184
185       -A <file>, --add-notes <file>
186              Add a notes file with submission
187
188              This  option tells ctest to include a notes file when submitting
189              dashboard.
190
191
192       -I [Start,End,Stride,test#,test#|Test file], --tests-information
193              Run a specific number of tests by number.
194
195              This option causes ctest to run tests starting at number  Start,
196              ending at number End, and incrementing by Stride. Any additional
197              numbers after Stride are  considered  individual  test  numbers.
198              Start,  End,or  stride  can  be empty.  Optionally a file can be
199              given that contains the same syntax as the command line.
200
201
202       -U, --union
203              Take the Union of -I and -R
204
205              When both -R and -I are specified by default the intersection of
206              tests  are  run.  By  specifying  -U  the  union of tests is run
207              instead.
208
209
210       --max-width <width>
211              Set the max width for a test name to output
212
213              Set the maximum width for each test name to show in the  output.
214              This  allows  the user to widen the output to avoid clipping the
215              test name which can be very annoying.
216
217
218       --interactive-debug-mode [0|1]
219              Set the interactive mode to 0 or 1.
220
221              This option causes ctest to run tests in either  an  interactive
222              mode  or  a  non-interactive mode. On Windows this means that in
223              non-interactive mode,  all  system  debug  pop  up  windows  are
224              blocked.  In dashboard mode (Experimental, Nightly, Continuous),
225              the default is non-interactive.  When just running tests not for
226              a  dashboard  the  default  is  to  allow popups and interactive
227              debugging.
228
229
230       --no-label-summary
231              Disable timing summary information for labels.
232
233              This option tells ctest not to  print  summary  information  for
234              each label associated with the tests run. If there are no labels
235              on the tests, nothing extra is printed.
236
237
238       --build-and-test
239              Configure, build and run a test.
240
241              This option tells ctest to configure (i.e. run cmake on), build,
242              and  or  execute  a  test.  The  configure  and  test  steps are
243              optional. The arguments to this command line are the source  and
244              binary  directories.  By  default  this  will  run  CMake on the
245              Source/Bin directories specified unless --build-nocmake is spec‐
246              ified.  Both  --build-makeprogram  and --build-generator MUST be
247              provided to use --build-and-test. If --test-command is specified
248              then that will be run after the build is complete. Other options
249              that  affect  this  mode  are  --build-target   --build-nocmake,
250              --build-run-dir,       --build-two-config,      --build-exe-dir,
251              --build-project,--build-noclean, --build-options
252
253
254       --build-target
255              Specify a specific target to build.
256
257              This option goes with the --build-and-test option, if  left  out
258              the all target is built.
259
260
261       --build-nocmake
262              Run the build without running cmake first.
263
264              Skip the cmake step.
265
266
267       --build-run-dir
268              Specify directory to run programs from.
269
270              Directory where programs will be after it has been compiled.
271
272
273       --build-two-config
274              Run CMake twice
275
276
277       --build-exe-dir
278              Specify the directory for the executable.
279
280
281       --build-generator
282              Specify the generator to use.
283
284
285       --build-generator-toolset
286              Specify the generator-specific toolset.
287
288
289       --build-project
290              Specify the name of the project to build.
291
292
293       --build-makeprogram
294              Specify the make program to use.
295
296
297       --build-noclean
298              Skip the make clean step.
299
300
301       --build-config-sample
302              A sample executable to use to determine the configuration
303
304              A  sample  executable to use to determine the configuration that
305              should be used. e.g. Debug/Release/etc
306
307
308       --build-options
309              Add extra options to the build step.
310
311              This option must be  the  last  option  with  the  exception  of
312              --test-command
313
314
315       --test-command
316              The test to run with the --build-and-test option.
317
318
319       --test-timeout
320              The time limit in seconds, internal use only.
321
322
323       --tomorrow-tag
324              Nightly or experimental starts with next day tag.
325
326              This is useful if the build will not finish in one day.
327
328
329       --ctest-config
330              The  configuration file used to initialize CTest state when sub‐
331              mitting dashboards.
332
333              This option tells CTest to  use  different  initialization  file
334              instead of CTestConfiguration.tcl. This way multiple initializa‐
335              tion files can be used for example to submit to  multiple  dash‐
336              boards.
337
338
339       --overwrite
340              Overwrite CTest configuration option.
341
342              By  default  ctest uses configuration options from configuration
343              file. This option will overwrite the configuration option.
344
345
346       --extra-submit <file>[;<file>]
347              Submit extra files to the dashboard.
348
349              This option will submit extra files to the dashboard.
350
351
352       --force-new-ctest-process
353              Run child CTest instances as new processes
354
355              By default CTest will run child CTest instances within the  same
356              process.  If  this  behavior  is not desired, this argument will
357              enforce new processes for child CTest processes.
358
359
360       --schedule-random
361              Use a random order for scheduling tests
362
363              This option will run the tests in a random order. It is commonly
364              used to detect implicit dependencies in a test suite.
365
366
367       --submit-index
368              Submit individual dashboard tests with specific index
369
370              This  option  allows  performing  the same CTest action (such as
371              test) multiple times and submit all stages to the same dashboard
372              (Dart2 required). Each execution requires different index.
373
374
375       --timeout <seconds>
376              Set a global timeout on all tests.
377
378              This  option  will set a global timeout on all tests that do not
379              already have a timeout set on them.
380
381
382       --stop-time <time>
383              Set a time at which all tests should stop running.
384
385              Set a real time of day at which all tests should timeout.  Exam‐
386              ple:  7:00:00 -0400. Any time format understood by the curl date
387              parser is accepted. Local time is  assumed  if  no  timezone  is
388              specified.
389
390
391       --http1.0
392              Submit using HTTP 1.0.
393
394              This  option will force CTest to use HTTP 1.0 to submit files to
395              the dashboard, instead of HTTP 1.1.
396
397
398       --no-compress-output
399              Do not compress test output when submitting.
400
401              This flag will turn off automatic compression  of  test  output.
402              Use  this  to  maintain  compatibility  with an older version of
403              CDash which doesn't support compressed test output.
404
405
406       --print-labels
407              Print all available test labels.
408
409              This option will not run any tests, it  will  simply  print  the
410              list of all labels associated with the test set.
411
412
413       --help-command <cmd> [<file>]
414              Show help for a single command and exit.
415
416              Prints  the  help  for the command to stdout or to the specified
417              file.
418
419
420       --help-command-list [<file>]
421              List available commands and exit.
422
423              Prints the list of all available listfile commands to stdout  or
424              the specified file.
425
426
427       --help-commands [<file>]
428              Print help for all commands and exit.
429
430              Prints  the  help for all commands to stdout or to the specified
431              file.
432
433
434       --copyright [file]
435              Print the CMake copyright and exit.
436
437              If a file is specified, the copyright is written into it.
438
439
440       --help,-help,-usage,-h,-H,/?
441              Print usage information and exit.
442
443              Usage  describes  the  basic  command  line  interface  and  its
444              options.
445
446
447       --help-full [file]
448              Print full help and exit.
449
450              Full  help  displays  most  of the documentation provided by the
451              UNIX man page.  It is provided for use  on  non-UNIX  platforms,
452              but  is  also convenient if the man page is not installed.  If a
453              file is specified, the help is written into it.
454
455
456       --help-html [file]
457              Print full help in HTML format.
458
459              This option is used by CMake authors to help produce web  pages.
460              If a file is specified, the help is written into it.
461
462
463       --help-man [file]
464              Print full help as a UNIX man page and exit.
465
466              This  option is used by the cmake build to generate the UNIX man
467              page.  If a file is specified, the help is written into it.
468
469
470       --version,-version,/V [file]
471              Show program name/version banner and exit.
472
473              If a file is specified, the version is written into it.
474
475

GENERATORS

477       The following generators are available on this platform:
478
479

COMMANDS

481       break  Break from an enclosing foreach or while loop.
482
483                break()
484
485              Breaks from an enclosing foreach loop or while loop
486
487
488       build_name
489              Deprecated.   Use  ${CMAKE_SYSTEM}   and   ${CMAKE_CXX_COMPILER}
490              instead.
491
492                build_name(variable)
493
494              Sets  the  specified variable to a string representing the plat‐
495              form and compiler settings.   These  values  are  now  available
496              through the CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
497
498
499       cmake_host_system_information
500              Query host system specific information.
501
502                cmake_host_system_information(RESULT <variable> QUERY <key> ...)
503
504              Queries  system  information  of  the host system on which cmake
505              runs. One or more <key> can be provided to select  the  informa‐
506              tion  to  be  queried.  The  list of queried values is stored in
507              <variable>.
508
509
510              <key> can be one of the following values:
511
512
513                NUMBER_OF_LOGICAL_CORES   = Number of logical cores.
514                NUMBER_OF_PHYSICAL_CORES  = Number of physical cores.
515                HOSTNAME                  = Hostname.
516                FQDN                      = Fully qualified domain name.
517                TOTAL_VIRTUAL_MEMORY      = Total virtual memory in megabytes.
518                AVAILABLE_VIRTUAL_MEMORY  = Available virtual memory in megabytes.
519                TOTAL_PHYSICAL_MEMORY     = Total physical memory in megabytes.
520                AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
521
522
523       cmake_minimum_required
524              Set the minimum required version of cmake for a project.
525
526                cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
527                                       [FATAL_ERROR])
528
529              If the current version of CMake is lower than that  required  it
530              will  stop  processing  the project and report an error.  When a
531              version higher than 2.4  is  specified  the  command  implicitly
532              invokes
533
534
535                cmake_policy(VERSION major[.minor[.patch[.tweak]]])
536
537              which  sets the cmake policy version level to the version speci‐
538              fied.  When version 2.4 or lower is given the command implicitly
539              invokes
540
541
542                cmake_policy(VERSION 2.4)
543
544              which enables compatibility features for CMake 2.4 and lower.
545
546
547              The  FATAL_ERROR option is accepted but ignored by CMake 2.6 and
548              higher.  It should be specified so CMake versions 2.4 and  lower
549              fail with an error instead of just a warning.
550
551
552       cmake_policy
553              Manage CMake Policy settings.
554
555              As  CMake  evolves  it is sometimes necessary to change existing
556              behavior in order to fix  bugs  or  improve  implementations  of
557              existing  features.   The  CMake Policy mechanism is designed to
558              help keep existing projects building as new  versions  of  CMake
559              introduce  changes  in  behavior.   Each  new policy (behavioral
560              change) is given an identifier of  the  form  "CMP<NNNN>"  where
561              "<NNNN>"  is  an  integer  index.  Documentation associated with
562              each policy describes the OLD and NEW behavior  and  the  reason
563              the  policy  was  introduced.   Projects  may set each policy to
564              select the desired behavior.  When CMake  needs  to  know  which
565              behavior  to  use  it  checks  for  a  setting  specified by the
566              project.  If no setting is available the OLD behavior is assumed
567              and a warning is produced requesting that the policy be set.
568
569
570              The  cmake_policy  command is used to set policies to OLD or NEW
571              behavior.  While setting policies individually is supported,  we
572              encourage projects to set policies based on CMake versions.
573
574
575                cmake_policy(VERSION major.minor[.patch[.tweak]])
576
577              Specify  that  the  current  CMake  list file is written for the
578              given version of CMake.  All policies introduced in  the  speci‐
579              fied  version  or  earlier will be set to use NEW behavior.  All
580              policies introduced after the specified version  will  be  unset
581              (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
582              This effectively requests behavior preferred as of a given CMake
583              version  and  tells newer CMake versions to warn about their new
584              policies.  The policy version specified must be at least 2.4  or
585              the command will report an error.  In order to get compatibility
586              features supporting versions earlier than 2.4 see  documentation
587              of policy CMP0001.
588
589
590                cmake_policy(SET CMP<NNNN> NEW)
591                cmake_policy(SET CMP<NNNN> OLD)
592
593              Tell  CMake  to  use the OLD or NEW behavior for a given policy.
594              Projects depending on the old behavior of  a  given  policy  may
595              silence  a  policy  warning  by setting the policy state to OLD.
596              Alternatively one may fix the  project  to  work  with  the  new
597              behavior and set the policy state to NEW.
598
599
600                cmake_policy(GET CMP<NNNN> <variable>)
601
602              Check whether a given policy is set to OLD or NEW behavior.  The
603              output variable value will be "OLD" or "NEW" if  the  policy  is
604              set, and empty otherwise.
605
606
607              CMake  keeps  policy settings on a stack, so changes made by the
608              cmake_policy command affect only the top of the  stack.   A  new
609              entry on the policy stack is managed automatically for each sub‐
610              directory to protect its parents and siblings.  CMake also  man‐
611              ages  a new entry for scripts loaded by include() and find_pack‐
612              age() commands except  when  invoked  with  the  NO_POLICY_SCOPE
613              option (see also policy CMP0011).  The cmake_policy command pro‐
614              vides an interface to manage custom entries on the policy stack:
615
616
617                cmake_policy(PUSH)
618                cmake_policy(POP)
619
620              Each PUSH must have a matching POP to erase any  changes.   This
621              is useful to make temporary changes to policy settings.
622
623
624              Functions  and  macros record policy settings when they are cre‐
625              ated and use the pre-record policies when they are invoked.   If
626              the  function or macro implementation sets policies, the changes
627              automatically propagate up through callers until they reach  the
628              closest nested policy stack entry.
629
630
631       configure_file
632              Copy a file to another location and modify its contents.
633
634                configure_file(<input> <output>
635                               [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
636                               [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
637
638              Copies  a file <input> to file <output> and substitutes variable
639              values referenced in the file content.  If <input> is a relative
640              path  it  is evaluated with respect to the current source direc‐
641              tory.  The <input> must be a file, not a directory.  If <output>
642              is  a  relative path it is evaluated with respect to the current
643              binary directory.  If <output> names an existing  directory  the
644              input file is placed in that directory with its original name.
645
646
647              If  the  <input>  file  is modified the build system will re-run
648              CMake to re-configure the file and  generate  the  build  system
649              again.
650
651
652              This command replaces any variables in the input file referenced
653              as ${VAR} or @VAR@ with their values as determined by CMake.  If
654              a variable is not defined, it will be replaced with nothing.  If
655              COPYONLY is specified, then  no  variable  expansion  will  take
656              place.   If  ESCAPE_QUOTES  is  specified  then  any substituted
657              quotes will be C-style escaped.  The  file  will  be  configured
658              with  the  current values of CMake variables. If @ONLY is speci‐
659              fied, only variables of the form  @VAR@  will  be  replaced  and
660              ${VAR}  will be ignored.  This is useful for configuring scripts
661              that use ${VAR}.
662
663
664              Input file lines of the form  "#cmakedefine  VAR  ..."  will  be
665              replaced  with  either  "#define  VAR ..." or "/* #undef VAR */"
666              depending on whether VAR is set in CMake to any value  not  con‐
667              sidered a false constant by the if() command. (Content of "...",
668              if any, is processed as above.) Input file  lines  of  the  form
669              "#cmakedefine01  VAR"  will be replaced with either "#define VAR
670              1" or "#define VAR 0" similarly.
671
672
673              With NEWLINE_STYLE the line ending could be adjusted:
674
675
676                  'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
677
678              COPYONLY must not be used with NEWLINE_STYLE.
679
680
681
682       ctest_build
683              Build the project.
684
685                ctest_build([BUILD build_dir] [TARGET target] [RETURN_VALUE res]
686                            [APPEND][NUMBER_ERRORS val] [NUMBER_WARNINGS val])
687
688              Builds  the  given  build  directory  and  stores   results   in
689              Build.xml.  If  no  BUILD  is  given, the CTEST_BINARY_DIRECTORY
690              variable is used.
691
692
693              The TARGET variable can be used to specify a build  target.   If
694              none is specified, the "all" target will be built.
695
696
697              The  RETURN_VALUE  option specifies a variable in which to store
698              the return value of the native build tool. The NUMBER_ERRORS and
699              NUMBER_WARNINGS  options specify variables in which to store the
700              number of build errors and warnings detected.
701
702
703              The APPEND option marks results for append to  those  previously
704              submitted  to  a  dashboard  server  since the last ctest_start.
705              Append semantics are defined by the dashboard server in use.
706
707
708       ctest_configure
709              Configure the project build tree.
710
711                ctest_configure([BUILD build_dir] [SOURCE source_dir] [APPEND]
712                                [OPTIONS options] [RETURN_VALUE res])
713
714              Configures the given build directory and stores results in  Con‐
715              figure.xml.  If  no  BUILD  is given, the CTEST_BINARY_DIRECTORY
716              variable is used. If no SOURCE is given, the CTEST_SOURCE_DIREC‐
717              TORY  variable  is  used. The OPTIONS argument specifies command
718              line  arguments  to  pass  to  the   configuration   tool.   The
719              RETURN_VALUE  option  specifies a variable in which to store the
720              return value of the native build tool.
721
722
723              The APPEND option marks results for append to  those  previously
724              submitted  to  a  dashboard  server  since the last ctest_start.
725              Append semantics are defined by the dashboard server in use.
726
727
728       ctest_coverage
729              Collect coverage tool results.
730
731                ctest_coverage([BUILD build_dir] [RETURN_VALUE res] [APPEND]
732                               [LABELS label1 [label2 [...]]])
733
734              Perform the coverage of the given  build  directory  and  stores
735              results  in Coverage.xml. The second argument is a variable that
736              will hold value.
737
738
739              The LABELS option filters the coverage report  to  include  only
740              source files labeled with at least one of the labels specified.
741
742
743              The  APPEND  option marks results for append to those previously
744              submitted to a dashboard  server  since  the  last  ctest_start.
745              Append semantics are defined by the dashboard server in use.
746
747
748       ctest_empty_binary_directory
749              empties the binary directory
750
751                ctest_empty_binary_directory( directory )
752
753              Removes  a  binary  directory.  This  command  will perform some
754              checks prior to deleting the directory in an  attempt  to  avoid
755              malicious or accidental directory deletion.
756
757
758       ctest_memcheck
759              Run tests with a dynamic analysis tool.
760
761                ctest_memcheck([BUILD build_dir] [RETURN_VALUE res] [APPEND]
762                           [START start number] [END end number]
763                           [STRIDE stride number] [EXCLUDE exclude regex ]
764                           [INCLUDE include regex]
765                           [EXCLUDE_LABEL exclude regex]
766                           [INCLUDE_LABEL label regex]
767                           [PARALLEL_LEVEL level] )
768
769              Tests  the  given  build  directory  and  stores results in Mem‐
770              Check.xml. The second argument is  a  variable  that  will  hold
771              value.  Optionally,  you  can  specify  the starting test number
772              START, the ending test number END, the number of tests  to  skip
773              between  each test STRIDE, a regular expression for tests to run
774              INCLUDE, or a regular expression for tests not to  run  EXCLUDE.
775              EXCLUDE_LABEL  and  INCLUDE_LABEL  are  regular  expressions for
776              tests to be included or excluded by  the  test  property  LABEL.
777              PARALLEL_LEVEL  should  be set to a positive number representing
778              the number of tests to be run in parallel.
779
780
781              The APPEND option marks results for append to  those  previously
782              submitted  to  a  dashboard  server  since the last ctest_start.
783              Append semantics are defined by the dashboard server in use.
784
785
786       ctest_read_custom_files
787              read CTestCustom files.
788
789                ctest_read_custom_files( directory ... )
790
791              Read all the CTestCustom.ctest or CTestCustom.cmake  files  from
792              the given directory.
793
794
795       ctest_run_script
796              runs a ctest -S script
797
798                ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
799                            script_file_name2 ... [RETURN_VALUE var])
800
801              Runs  a script or scripts much like if it was run from ctest -S.
802              If no argument is provided then the current script is run  using
803              the  current settings of the variables. If NEW_PROCESS is speci‐
804              fied then each script will  be  run  in  a  separate  process.If
805              RETURN_VALUE  is  specified  the return value of the last script
806              run will be put into var.
807
808
809       ctest_sleep
810              sleeps for some amount of time
811
812                ctest_sleep(<seconds>)
813
814              Sleep for given number of seconds.
815
816
817                ctest_sleep(<time1> <duration> <time2>)
818
819              Sleep for t=(time1 + duration - time2) seconds if t > 0.
820
821
822       ctest_start
823              Starts the testing for a given model
824
825                ctest_start(Model [TRACK <track>] [APPEND] [source [binary]])
826
827              Starts the testing for a given  model.  The  command  should  be
828              called  after  the  binary  directory  is  initialized.  If  the
829              'source' and 'binary' directory are not specified, it reads  the
830              CTEST_SOURCE_DIRECTORY  and CTEST_BINARY_DIRECTORY. If the track
831              is specified, the submissions will go to the specified track. If
832              APPEND  is used, the existing TAG is used rather than creating a
833              new one based on the current time stamp.
834
835
836       ctest_submit
837              Submit results to a dashboard server.
838
839                ctest_submit([PARTS ...] [FILES ...] [RETRY_COUNT count]                [RETRY_DELAY delay][RETURN_VALUE res])
840
841              By default all available parts are  submitted  if  no  PARTS  or
842              FILES  are  specified.  The PARTS option lists a subset of parts
843              to be submitted.  Valid part names are:
844
845
846                Start      = nothing
847                Update     = ctest_update results, in Update.xml
848                Configure  = ctest_configure results, in Configure.xml
849                Build      = ctest_build results, in Build.xml
850                Test       = ctest_test results, in Test.xml
851                Coverage   = ctest_coverage results, in Coverage.xml
852                MemCheck   = ctest_memcheck results, in DynamicAnalysis.xml
853                Notes      = Files listed by CTEST_NOTES_FILES, in Notes.xml
854                ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
855                Submit     = nothing
856
857              The FILES option explicitly lists specific files to  be  submit‐
858              ted.  Each individual file must exist at the time of the call.
859
860
861              The  RETRY_DELAY  option  specifies  how long in seconds to wait
862              after a timed-out submission before attempting to re-submit.
863
864
865              The RETRY_COUNT option specifies  how  many  times  to  retry  a
866              timed-out submission.
867
868
869
870       ctest_test
871              Run tests in the project build tree.
872
873                ctest_test([BUILD build_dir] [APPEND]
874                           [START start number] [END end number]
875                           [STRIDE stride number] [EXCLUDE exclude regex ]
876                           [INCLUDE include regex] [RETURN_VALUE res]
877                           [EXCLUDE_LABEL exclude regex]
878                           [INCLUDE_LABEL label regex]
879                           [PARALLEL_LEVEL level]
880                           [SCHEDULE_RANDOM on]
881                           [STOP_TIME time of day])
882
883              Tests  the given build directory and stores results in Test.xml.
884              The second argument is a variable that will hold value.  Option‐
885              ally, you can specify the starting test number START, the ending
886              test number END, the number of tests to skip between  each  test
887              STRIDE, a regular expression for tests to run INCLUDE, or a reg‐
888              ular expression for tests to not run EXCLUDE. EXCLUDE_LABEL  and
889              INCLUDE_LABEL  are regular expression for test to be included or
890              excluded by the test property LABEL.  PARALLEL_LEVEL  should  be
891              set  to a positive number representing the number of tests to be
892              run in parallel. SCHEDULE_RANDOM will launch tests in  a  random
893              order,  and  is typically used to detect implicit test dependen‐
894              cies. STOP_TIME is the time of day at which the tests should all
895              stop running.
896
897
898              The  APPEND  option marks results for append to those previously
899              submitted to a dashboard  server  since  the  last  ctest_start.
900              Append semantics are defined by the dashboard server in use.
901
902
903       ctest_update
904              Update the work tree from version control.
905
906                ctest_update([SOURCE source] [RETURN_VALUE res])
907
908              Updates  the  given  source  directory  and  stores  results  in
909              Update.xml. If no SOURCE is  given,  the  CTEST_SOURCE_DIRECTORY
910              variable  is  used. The RETURN_VALUE option specifies a variable
911              in which to store the result,  which  is  the  number  of  files
912              updated or -1 on error.
913
914
915       ctest_upload
916              Upload files to a dashboard server.
917
918                ctest_upload(FILES ...)
919
920              Pass  a list of files to be sent along with the build results to
921              the dashboard server.
922
923
924
925       else   Starts the else portion of an if block.
926
927                else(expression)
928
929              See the if command.
930
931
932       elseif Starts the elseif portion of an if block.
933
934                elseif(expression)
935
936              See the if command.
937
938
939       endforeach
940              Ends a list of commands in a FOREACH block.
941
942                endforeach(expression)
943
944              See the FOREACH command.
945
946
947       endfunction
948              Ends a list of commands in a function block.
949
950                endfunction(expression)
951
952              See the function command.
953
954
955       endif  Ends a list of commands in an if block.
956
957                endif(expression)
958
959              See the if command.
960
961
962       endmacro
963              Ends a list of commands in a macro block.
964
965                endmacro(expression)
966
967              See the macro command.
968
969
970       endwhile
971              Ends a list of commands in a while block.
972
973                endwhile(expression)
974
975              See the while command.
976
977
978       exec_program
979              Deprecated.  Use the execute_process() command instead.
980
981              Run an executable program during the processing  of  the  CMake‐
982              List.txt file.
983
984
985                exec_program(Executable [directory in which to run]
986                             [ARGS <arguments to executable>]
987                             [OUTPUT_VARIABLE <var>]
988                             [RETURN_VALUE <var>])
989
990              The  executable  is  run  in the optionally specified directory.
991              The executable can include arguments if it is double quoted, but
992              it  is better to use the optional ARGS argument to specify argu‐
993              ments to the program.   This is because cmake will then be  able
994              to  escape  spaces in the executable path.  An optional argument
995              OUTPUT_VARIABLE specifies a variable in which to store the  out‐
996              put.  To  capture  the  return value of the execution, provide a
997              RETURN_VALUE. If OUTPUT_VARIABLE is specified,  then  no  output
998              will go to the stdout/stderr of the console running cmake.
999
1000
1001
1002       execute_process
1003              Execute one or more child processes.
1004
1005                execute_process(COMMAND <cmd1> [args1...]]
1006                                [COMMAND <cmd2> [args2...] [...]]
1007                                [WORKING_DIRECTORY <directory>]
1008                                [TIMEOUT <seconds>]
1009                                [RESULT_VARIABLE <variable>]
1010                                [OUTPUT_VARIABLE <variable>]
1011                                [ERROR_VARIABLE <variable>]
1012                                [INPUT_FILE <file>]
1013                                [OUTPUT_FILE <file>]
1014                                [ERROR_FILE <file>]
1015                                [OUTPUT_QUIET]
1016                                [ERROR_QUIET]
1017                                [OUTPUT_STRIP_TRAILING_WHITESPACE]
1018                                [ERROR_STRIP_TRAILING_WHITESPACE])
1019
1020              Runs  the  given sequence of one or more commands with the stan‐
1021              dard output of each process piped to the standard input  of  the
1022              next.   A  single standard error pipe is used for all processes.
1023              If WORKING_DIRECTORY is given the named directory will be set as
1024              the  current working directory of the child processes.  If TIME‐
1025              OUT is given the child processes will be terminated if  they  do
1026              not  finish  in  the  specified number of seconds (fractions are
1027              allowed).  If RESULT_VARIABLE is given the variable will be  set
1028              to contain the result of running the processes.  This will be an
1029              integer return code from the last child or a  string  describing
1030              an  error  condition.   If OUTPUT_VARIABLE or ERROR_VARIABLE are
1031              given the variable named will be set with the  contents  of  the
1032              standard  output  and standard error pipes respectively.  If the
1033              same variable is named for  both  pipes  their  output  will  be
1034              merged  in  the  order produced.  If INPUT_FILE, OUTPUT_FILE, or
1035              ERROR_FILE is given the file named will be attached to the stan‐
1036              dard  input  of  the  first process, standard output of the last
1037              process, or standard error of all  processes  respectively.   If
1038              OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
1039              standard error results will be quietly ignored.   If  more  than
1040              one  OUTPUT_*  or  ERROR_* option is given for the same pipe the
1041              precedence is not specified.  If no OUTPUT_* or ERROR_*  options
1042              are given the output will be shared with the corresponding pipes
1043              of the CMake process itself.
1044
1045
1046              The execute_process command is a newer more powerful version  of
1047              exec_program,  but the old command has been kept for compatibil‐
1048              ity.
1049
1050
1051       file   File manipulation command.
1052
1053                file(WRITE filename "message to write"... )
1054                file(APPEND filename "message to write"... )
1055                file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
1056                file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
1057                file(STRINGS filename variable [LIMIT_COUNT num]
1058                     [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
1059                     [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
1060                     [NEWLINE_CONSUME] [REGEX regex]
1061                     [NO_HEX_CONVERSION])
1062                file(GLOB variable [RELATIVE path] [globbing expressions]...)
1063                file(GLOB_RECURSE variable [RELATIVE path]
1064                     [FOLLOW_SYMLINKS] [globbing expressions]...)
1065                file(RENAME <oldname> <newname>)
1066                file(REMOVE [file1 ...])
1067                file(REMOVE_RECURSE [file1 ...])
1068                file(MAKE_DIRECTORY [directory1 directory2 ...])
1069                file(RELATIVE_PATH variable directory file)
1070                file(TO_CMAKE_PATH path result)
1071                file(TO_NATIVE_PATH path result)
1072                file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
1073                     [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
1074                     [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
1075                     [TLS_VERIFY on|off] [TLS_CAINFO file])
1076                file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
1077                     [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
1078                file(TIMESTAMP filename variable [<format string>] [UTC])
1079                file(GENERATE OUTPUT output_file
1080                     <INPUT input_file|CONTENT input_content>
1081                     [CONDITION expression])
1082
1083              WRITE will write a message into a  file  called  'filename'.  It
1084              overwrites  the  file if it already exists, and creates the file
1085              if it does not exist. (If the file is a build input, use config‐
1086              ure_file to update the file only when its content changes.)
1087
1088
1089              APPEND will write a message into a file same as WRITE, except it
1090              will append it to the end of the file
1091
1092
1093              READ will read the content of a file and store it into the vari‐
1094              able. It will start at the given offset and read up to numBytes.
1095              If the argument HEX is given, the binary data will be  converted
1096              to  hexadecimal  representation  and  this will be stored in the
1097              variable.
1098
1099
1100              MD5, SHA1, SHA224, SHA256, SHA384, and  SHA512  will  compute  a
1101              cryptographic hash of the content of a file.
1102
1103
1104              STRINGS will parse a list of ASCII strings from a file and store
1105              it in a variable. Binary data in the file are ignored.  Carriage
1106              return  (CR) characters are ignored. It works also for Intel Hex
1107              and Motorola S-record files, which are  automatically  converted
1108              to   binary   format  when  reading  them.  Disable  this  using
1109              NO_HEX_CONVERSION.
1110
1111
1112              LIMIT_COUNT sets  the  maximum  number  of  strings  to  return.
1113              LIMIT_INPUT  sets  the  maximum number of bytes to read from the
1114              input file. LIMIT_OUTPUT sets the maximum  number  of  bytes  to
1115              store  in  the  output variable. LENGTH_MINIMUM sets the minimum
1116              length of a string  to  return.  Shorter  strings  are  ignored.
1117              LENGTH_MAXIMUM  sets  the  maximum length of a string to return.
1118              Longer strings are split into strings no longer than the maximum
1119              length.  NEWLINE_CONSUME  allows  newlines  to  be  included  in
1120              strings instead of terminating them.
1121
1122
1123              REGEX specifies a regular expression that a string must match to
1124              be returned. Typical usage
1125
1126
1127                file(STRINGS myfile.txt myfile)
1128
1129              stores  a  list in the variable "myfile" in which each item is a
1130              line from the input file.
1131
1132
1133              GLOB will generate a list of all files that match  the  globbing
1134              expressions and store it into the variable. Globbing expressions
1135              are similar to regular expressions, but much simpler.  If  RELA‐
1136              TIVE  flag  is  specified for an expression, the results will be
1137              returned as a relative path to the given path.  (We do not  rec‐
1138              ommend  using  GLOB  to collect a list of source files from your
1139              source tree.  If no CMakeLists.txt file changes when a source is
1140              added  or  removed  then  the generated build system cannot know
1141              when to ask CMake to regenerate.)
1142
1143
1144              Examples of globbing expressions include:
1145
1146
1147                 *.cxx      - match all files with extension cxx
1148                 *.vt?      - match all files with extension vta,...,vtz
1149                 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1150
1151              GLOB_RECURSE will generate a list similar to the  regular  GLOB,
1152              except  it  will  traverse all the subdirectories of the matched
1153              directory and match the files. Subdirectories that are  symlinks
1154              are  only  traversed if FOLLOW_SYMLINKS is given or cmake policy
1155              CMP0009 is not set to NEW. See cmake --help-policy  CMP0009  for
1156              more information.
1157
1158
1159              Examples of recursive globbing include:
1160
1161
1162                 /dir/*.py  - match all python files in /dir and subdirectories
1163
1164              MAKE_DIRECTORY  will create the given directories, also if their
1165              parent directories don't exist yet
1166
1167
1168              RENAME moves a file or directory within a filesystem,  replacing
1169              the destination atomically.
1170
1171
1172              REMOVE will remove the given files, also in subdirectories
1173
1174
1175              REMOVE_RECURSE will remove the given files and directories, also
1176              non-empty directories
1177
1178
1179              RELATIVE_PATH will determine relative path from directory to the
1180              given file.
1181
1182
1183              TO_CMAKE_PATH  will  convert  path  into a cmake style path with
1184              unix /.  The input can be a single path or a  system  path  like
1185              "$ENV{PATH}".   Note  the  double  quotes  around  the  ENV call
1186              TO_CMAKE_PATH only takes  one argument. This command  will  also
1187              convert  the native list delimiters for a list of paths like the
1188              PATH environment variable.
1189
1190
1191              TO_NATIVE_PATH works just like TO_CMAKE_PATH, but  will  convert
1192              from   a  cmake style path into the native path style \ for win‐
1193              dows and / for UNIX.
1194
1195
1196              DOWNLOAD will download the given URL to the given file.  If  LOG
1197              var  is  specified  a log of the download will be put in var. If
1198              STATUS var is specified the status of the operation will be  put
1199              in  var. The status is returned in a list of length 2. The first
1200              element is the numeric return value for the operation,  and  the
1201              second  element  is  a  string  value for the error. A 0 numeric
1202              error means no error in the operation. If TIMEOUT time is speci‐
1203              fied, the operation will timeout after time seconds, time should
1204              be specified as an integer. The INACTIVITY_TIMEOUT specifies  an
1205              integer  number  of seconds of inactivity after which the opera‐
1206              tion should terminate. If EXPECTED_HASH ALGO=value is specified,
1207              the operation will verify that the downloaded file's actual hash
1208              matches the expected value, where ALGO  is  one  of  MD5,  SHA1,
1209              SHA224,  SHA256,  SHA384,  or SHA512.  If it does not match, the
1210              operation fails with an error. ("EXPECTED_MD5 sum" is short-hand
1211              for  "EXPECTED_HASH  MD5=sum".)  If  SHOW_PROGRESS is specified,
1212              progress information will be printed as  status  messages  until
1213              the  operation  is  complete. For https URLs CMake must be built
1214              with OpenSSL.  TLS/SSL certificates are not checked by  default.
1215              Set   TLS_VERIFY   to   ON  to  check  certificates  and/or  use
1216              EXPECTED_HASH to verify downloaded content.  Set  TLS_CAINFO  to
1217              specify  a  custom  Certificate  Authority  file.  If either TLS
1218              option is not given CMake will check variables  CMAKE_TLS_VERIFY
1219              and CMAKE_TLS_CAINFO, respectively.
1220
1221
1222              UPLOAD  will  upload the given file to the given URL. If LOG var
1223              is specified a log of the upload will be put in var.  If  STATUS
1224              var is specified the status of the operation will be put in var.
1225              The status is returned in a list of length 2. The first  element
1226              is  the  numeric  return value for the operation, and the second
1227              element is a string value for the error. A 0 numeric error means
1228              no  error  in  the  operation. If TIMEOUT time is specified, the
1229              operation will timeout after time seconds, time should be speci‐
1230              fied  as an integer. The INACTIVITY_TIMEOUT specifies an integer
1231              number of seconds of inactivity after which the operation should
1232              terminate.  If  SHOW_PROGRESS is specified, progress information
1233              will be printed as status messages until the operation  is  com‐
1234              plete.
1235
1236
1237              TIMESTAMP will write a string representation of the modification
1238              time of filename to variable.
1239
1240
1241              Should the command be unable to obtain a timestamp variable will
1242              be set to the empty string "".
1243
1244
1245              See  documentation  of the string TIMESTAMP sub-command for more
1246              details.
1247
1248
1249              The file() command also provides COPY and INSTALL signatures:
1250
1251
1252                file(<COPY|INSTALL> files... DESTINATION <dir>
1253                     [FILE_PERMISSIONS permissions...]
1254                     [DIRECTORY_PERMISSIONS permissions...]
1255                     [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1256                     [FILES_MATCHING]
1257                     [[PATTERN <pattern> | REGEX <regex>]
1258                      [EXCLUDE] [PERMISSIONS permissions...]] [...])
1259
1260              The COPY signature copies files, directories, and symlinks to  a
1261              destination  folder.   Relative  input  paths are evaluated with
1262              respect to the current source directory, and a relative destina‐
1263              tion  is  evaluated with respect to the current build directory.
1264              Copying preserves input file timestamps,  and  optimizes  out  a
1265              file  if  it  exists at the destination with the same timestamp.
1266              Copying preserves input permissions unless explicit  permissions
1267              or  NO_SOURCE_PERMISSIONS  are given (default is USE_SOURCE_PER‐
1268              MISSIONS).  See the install(DIRECTORY) command for documentation
1269              of permissions, PATTERN, REGEX, and EXCLUDE options.
1270
1271
1272              The INSTALL signature differs slightly from COPY: it prints sta‐
1273              tus messages, and NO_SOURCE_PERMISSIONS is  default.   Installa‐
1274              tion  scripts generated by the install() command use this signa‐
1275              ture (with some undocumented options for internal use).
1276
1277
1278              GENERATE will  write  an  <output_file>  with  content  from  an
1279              <input_file>,  or from <input_content>.  The output is generated
1280              conditionally based on the content of the <condition>.  The file
1281              is written at CMake generate-time and the input may contain gen‐
1282              erator  expressions.    The   <condition>,   <output_file>   and
1283              <input_file>  may also contain generator expressions.  The <con‐
1284              dition> must evaluate to either '0' or '1'.   The  <output_file>
1285              must  evaluate  to  a  unique  name among all configurations and
1286              among all invocations of file(GENERATE).
1287
1288
1289       find_file
1290              Find the full path to a file.
1291
1292                 find_file(<VAR> name1 [path1 path2 ...])
1293
1294              This is the short-hand signature for the command that is  suffi‐
1295              cient  in  many  cases.  It is the same as find_file(<VAR> name1
1296              [PATHS path1 path2 ...])
1297
1298
1299                 find_file(
1300                           <VAR>
1301                           name | NAMES name1 [name2 ...]
1302                           [HINTS path1 [path2 ... ENV var]]
1303                           [PATHS path1 [path2 ... ENV var]]
1304                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
1305                           [DOC "cache documentation string"]
1306                           [NO_DEFAULT_PATH]
1307                           [NO_CMAKE_ENVIRONMENT_PATH]
1308                           [NO_CMAKE_PATH]
1309                           [NO_SYSTEM_ENVIRONMENT_PATH]
1310                           [NO_CMAKE_SYSTEM_PATH]
1311                           [CMAKE_FIND_ROOT_PATH_BOTH |
1312                            ONLY_CMAKE_FIND_ROOT_PATH |
1313                            NO_CMAKE_FIND_ROOT_PATH]
1314                          )
1315
1316              This command is used to find a full path to named file. A  cache
1317              entry named by <VAR> is created to store the result of this com‐
1318              mand.  If the full path to a file is found the result is  stored
1319              in  the  variable and the search will not be repeated unless the
1320              variable is cleared.  If nothing is found, the  result  will  be
1321              <VAR>-NOTFOUND,  and the search will be attempted again the next
1322              time find_file is invoked with the same variable.  The  name  of
1323              the full path to a file that is searched for is specified by the
1324              names listed after the NAMES argument.   Additional search loca‐
1325              tions  can be specified after the PATHS argument.  If ENV var is
1326              found in the HINTS or PATHS section the environment variable var
1327              will be read and converted from a system environment variable to
1328              a cmake style list of paths.  For example ENV PATH  would  be  a
1329              way  to  list  the  system path variable. The argument after DOC
1330              will  be  used  for  the  documentation  string  in  the  cache.
1331              PATH_SUFFIXES specifies additional subdirectories to check below
1332              each search path.
1333
1334
1335              If NO_DEFAULT_PATH is specified, then no  additional  paths  are
1336              added  to  the  search. If NO_DEFAULT_PATH is not specified, the
1337              search process is as follows:
1338
1339
1340              1. Search paths specified  in  cmake-specific  cache  variables.
1341              These  are  intended  to  be  used  on  the  command line with a
1342              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
1343
1344
1345                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1346                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1347                 CMAKE_INCLUDE_PATH
1348                 CMAKE_FRAMEWORK_PATH
1349
1350              2. Search paths specified in  cmake-specific  environment  vari‐
1351              ables.  These are intended to be set in the user's shell config‐
1352              uration.  This can be skipped  if  NO_CMAKE_ENVIRONMENT_PATH  is
1353              passed.
1354
1355
1356                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1357                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1358                 CMAKE_INCLUDE_PATH
1359                 CMAKE_FRAMEWORK_PATH
1360
1361              3. Search the paths specified by the HINTS option.  These should
1362              be paths computed by system introspection, such as a  hint  pro‐
1363              vided by the location of another item already found.  Hard-coded
1364              guesses should be specified with the PATHS option.
1365
1366
1367              4. Search the standard system environment variables. This can be
1368              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1369
1370
1371                 PATH
1372                 INCLUDE
1373
1374              5.  Search cmake variables defined in the Platform files for the
1375              current system.  This can be skipped if NO_CMAKE_SYSTEM_PATH  is
1376              passed.
1377
1378
1379                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1380                 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1381                 CMAKE_SYSTEM_INCLUDE_PATH
1382                 CMAKE_SYSTEM_FRAMEWORK_PATH
1383
1384              6.  Search  the  paths  specified  by the PATHS option or in the
1385              short-hand  version  of  the  command.   These   are   typically
1386              hard-coded guesses.
1387
1388
1389              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1390              able    CMAKE_FIND_FRAMEWORK can be set to empty or one  of  the
1391              following:
1392
1393
1394                 "FIRST"  - Try to find frameworks before standard
1395                            libraries or headers. This is the default on Darwin.
1396                 "LAST"   - Try to find frameworks after standard
1397                            libraries or headers.
1398                 "ONLY"   - Only try to find frameworks.
1399                 "NEVER" - Never try to find frameworks.
1400
1401              On  Darwin  or  systems supporting OS X Application Bundles, the
1402              cmake variable CMAKE_FIND_APPBUNDLE can be set to empty  or  one
1403              of the following:
1404
1405
1406                 "FIRST"  - Try to find application bundles before standard
1407                            programs. This is the default on Darwin.
1408                 "LAST"   - Try to find application bundles after standard
1409                            programs.
1410                 "ONLY"   - Only try to find application bundles.
1411                 "NEVER" - Never try to find application bundles.
1412
1413              The  CMake  variable  CMAKE_FIND_ROOT_PATH specifies one or more
1414              directories to be prepended to  all  other  search  directories.
1415              This  effectively "re-roots" the entire search under given loca‐
1416              tions. By default it is empty.  It  is  especially  useful  when
1417              cross-compiling  to  point  to  the root directory of the target
1418              environment and CMake will search there too. By default at first
1419              the  directories  listed  in  CMAKE_FIND_ROOT_PATH  and then the
1420              non-rooted directories will be searched.  The  default  behavior
1421              can  be  adjusted  by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1422              This behavior can be manually overridden on a per-call basis. By
1423              using  CMAKE_FIND_ROOT_PATH_BOTH  the  search  order  will be as
1424              described  above.  If  NO_CMAKE_FIND_ROOT_PATH  is   used   then
1425              CMAKE_FIND_ROOT_PATH      will      not      be     used.     If
1426              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1427              tories will be searched.
1428
1429
1430              The  default  search  order  is  designed to be most-specific to
1431              least-specific for common use cases.  Projects may override  the
1432              order by simply calling the command multiple times and using the
1433              NO_* options:
1434
1435
1436                 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1437                 find_file(<VAR> NAMES name)
1438
1439              Once one of the calls succeeds the result variable will  be  set
1440              and stored in the cache so that no call will search again.
1441
1442
1443       find_library
1444              Find a library.
1445
1446                 find_library(<VAR> name1 [path1 path2 ...])
1447
1448              This  is the short-hand signature for the command that is suffi‐
1449              cient in many cases.  It is the same as find_library(<VAR> name1
1450              [PATHS path1 path2 ...])
1451
1452
1453                 find_library(
1454                           <VAR>
1455                           name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1456                           [HINTS path1 [path2 ... ENV var]]
1457                           [PATHS path1 [path2 ... ENV var]]
1458                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
1459                           [DOC "cache documentation string"]
1460                           [NO_DEFAULT_PATH]
1461                           [NO_CMAKE_ENVIRONMENT_PATH]
1462                           [NO_CMAKE_PATH]
1463                           [NO_SYSTEM_ENVIRONMENT_PATH]
1464                           [NO_CMAKE_SYSTEM_PATH]
1465                           [CMAKE_FIND_ROOT_PATH_BOTH |
1466                            ONLY_CMAKE_FIND_ROOT_PATH |
1467                            NO_CMAKE_FIND_ROOT_PATH]
1468                          )
1469
1470              This  command  is used to find a library. A cache entry named by
1471              <VAR> is created to store the result of this  command.   If  the
1472              library  is  found  the result is stored in the variable and the
1473              search will not be repeated unless the variable is cleared.   If
1474              nothing  is  found,  the  result will be <VAR>-NOTFOUND, and the
1475              search will be attempted again the  next  time  find_library  is
1476              invoked with the same variable.  The name of the library that is
1477              searched for is specified by the names listed  after  the  NAMES
1478              argument.    Additional  search locations can be specified after
1479              the PATHS argument.  If ENV var is found in the HINTS  or  PATHS
1480              section  the environment variable var will be read and converted
1481              from a system environment variable to  a  cmake  style  list  of
1482              paths.   For  example ENV PATH would be a way to list the system
1483              path variable. The argument after DOC will be used for the docu‐
1484              mentation  string  in  the cache.  PATH_SUFFIXES specifies addi‐
1485              tional subdirectories to check below each search path.
1486
1487
1488              If NO_DEFAULT_PATH is specified, then no  additional  paths  are
1489              added  to  the  search. If NO_DEFAULT_PATH is not specified, the
1490              search process is as follows:
1491
1492
1493              1. Search paths specified  in  cmake-specific  cache  variables.
1494              These  are  intended  to  be  used  on  the  command line with a
1495              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
1496
1497
1498                 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1499                 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1500                 CMAKE_LIBRARY_PATH
1501                 CMAKE_FRAMEWORK_PATH
1502
1503              2. Search paths specified in  cmake-specific  environment  vari‐
1504              ables.  These are intended to be set in the user's shell config‐
1505              uration.  This can be skipped  if  NO_CMAKE_ENVIRONMENT_PATH  is
1506              passed.
1507
1508
1509                 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1510                 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1511                 CMAKE_LIBRARY_PATH
1512                 CMAKE_FRAMEWORK_PATH
1513
1514              3. Search the paths specified by the HINTS option.  These should
1515              be paths computed by system introspection, such as a  hint  pro‐
1516              vided by the location of another item already found.  Hard-coded
1517              guesses should be specified with the PATHS option.
1518
1519
1520              4. Search the standard system environment variables. This can be
1521              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1522
1523
1524                 PATH
1525                 LIB
1526
1527              5.  Search cmake variables defined in the Platform files for the
1528              current system.  This can be skipped if NO_CMAKE_SYSTEM_PATH  is
1529              passed.
1530
1531
1532                 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1533                 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1534                 CMAKE_SYSTEM_LIBRARY_PATH
1535                 CMAKE_SYSTEM_FRAMEWORK_PATH
1536
1537              6.  Search  the  paths  specified  by the PATHS option or in the
1538              short-hand  version  of  the  command.   These   are   typically
1539              hard-coded guesses.
1540
1541
1542              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1543              able    CMAKE_FIND_FRAMEWORK can be set to empty or one  of  the
1544              following:
1545
1546
1547                 "FIRST"  - Try to find frameworks before standard
1548                            libraries or headers. This is the default on Darwin.
1549                 "LAST"   - Try to find frameworks after standard
1550                            libraries or headers.
1551                 "ONLY"   - Only try to find frameworks.
1552                 "NEVER" - Never try to find frameworks.
1553
1554              On  Darwin  or  systems supporting OS X Application Bundles, the
1555              cmake variable CMAKE_FIND_APPBUNDLE can be set to empty  or  one
1556              of the following:
1557
1558
1559                 "FIRST"  - Try to find application bundles before standard
1560                            programs. This is the default on Darwin.
1561                 "LAST"   - Try to find application bundles after standard
1562                            programs.
1563                 "ONLY"   - Only try to find application bundles.
1564                 "NEVER" - Never try to find application bundles.
1565
1566              The  CMake  variable  CMAKE_FIND_ROOT_PATH specifies one or more
1567              directories to be prepended to  all  other  search  directories.
1568              This  effectively "re-roots" the entire search under given loca‐
1569              tions. By default it is empty.  It  is  especially  useful  when
1570              cross-compiling  to  point  to  the root directory of the target
1571              environment and CMake will search there too. By default at first
1572              the  directories  listed  in  CMAKE_FIND_ROOT_PATH  and then the
1573              non-rooted directories will be searched.  The  default  behavior
1574              can  be  adjusted  by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
1575              This behavior can be manually overridden on a per-call basis. By
1576              using  CMAKE_FIND_ROOT_PATH_BOTH  the  search  order  will be as
1577              described  above.  If  NO_CMAKE_FIND_ROOT_PATH  is   used   then
1578              CMAKE_FIND_ROOT_PATH      will      not      be     used.     If
1579              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1580              tories will be searched.
1581
1582
1583              The  default  search  order  is  designed to be most-specific to
1584              least-specific for common use cases.  Projects may override  the
1585              order by simply calling the command multiple times and using the
1586              NO_* options:
1587
1588
1589                 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1590                 find_library(<VAR> NAMES name)
1591
1592              Once one of the calls succeeds the result variable will  be  set
1593              and stored in the cache so that no call will search again.
1594
1595
1596              When  more than one value is given to the NAMES option this com‐
1597              mand by default will consider one name  at  a  time  and  search
1598              every  directory  for  it.   The NAMES_PER_DIR option tells this
1599              command to consider one directory at a time and search  for  all
1600              names in it.
1601
1602
1603              If the library found is a framework, then VAR will be set to the
1604              full path to the framework <fullPath>/A.framework. When  a  full
1605              path  to  a  framework  is  used  as a library, CMake will use a
1606              -framework A, and a -F<fullPath> to link the  framework  to  the
1607              target.
1608
1609
1610              If  the  global property FIND_LIBRARY_USE_LIB64_PATHS is set all
1611              search paths will be tested as normal, with "64/" appended,  and
1612              with all matches of "lib/" replaced with "lib64/". This property
1613              is automatically set for the platforms that are known to need it
1614              if  at  least one of the languages supported by the PROJECT com‐
1615              mand is enabled.
1616
1617
1618       find_package
1619              Load settings for an external project.
1620
1621                find_package(<package> [version] [EXACT] [QUIET] [MODULE]
1622                             [REQUIRED] [[COMPONENTS] [components...]]
1623                             [OPTIONAL_COMPONENTS components...]
1624                             [NO_POLICY_SCOPE])
1625
1626              Finds and loads  settings  from  an  external  project.   <pack‐
1627              age>_FOUND  will  be  set  to  indicate  whether the package was
1628              found.  When the package is found  package-specific  information
1629              is provided through variables and imported targets documented by
1630              the package itself.  The QUIET option disables messages  if  the
1631              package  cannot be found.  The MODULE option disables the second
1632              signature documented below.  The REQUIRED option stops  process‐
1633              ing with an error message if the package cannot be found.
1634
1635
1636              A  package-specific  list  of  required components may be listed
1637              after the COMPONENTS option (or after  the  REQUIRED  option  if
1638              present).   Additional  optional  components may be listed after
1639              OPTIONAL_COMPONENTS.  Available components and  their  influence
1640              on  whether  a  package is considered to be found are defined by
1641              the target package.
1642
1643
1644              The [version] argument requests a version with which the package
1645              found       should       be      compatible      (format      is
1646              major[.minor[.patch[.tweak]]]).  The EXACT option requests  that
1647              the  version  be matched exactly.  If no [version] and/or compo‐
1648              nent list is given to a recursive invocation inside a  find-mod‐
1649              ule,  the  corresponding  arguments  are forwarded automatically
1650              from the outer call (including the EXACT  flag  for  [version]).
1651              Version support is currently provided only on a package-by-pack‐
1652              age basis (details below).
1653
1654
1655              User code should generally look for  packages  using  the  above
1656              simple  signature.   The remainder of this command documentation
1657              specifies the full command signature and details of  the  search
1658              process.  Project maintainers wishing to provide a package to be
1659              found by this command are encouraged to read on.
1660
1661
1662              The command has two modes by which  it  searches  for  packages:
1663              "Module"  mode and "Config" mode.  Module mode is available when
1664              the command is invoked with the above reduced signature.   CMake
1665              searches   for   a  file  called  "Find<package>.cmake"  in  the
1666              CMAKE_MODULE_PATH followed by the CMake  installation.   If  the
1667              file is found, it is read and processed by CMake.  It is respon‐
1668              sible for finding the package, checking the version, and produc‐
1669              ing  any  needed messages.  Many find-modules provide limited or
1670              no support for versioning; check the module  documentation.   If
1671              no  module  is found and the MODULE option is not given the com‐
1672              mand proceeds to Config mode.
1673
1674
1675              The complete Config mode command signature is:
1676
1677
1678                find_package(<package> [version] [EXACT] [QUIET]
1679                             [REQUIRED] [[COMPONENTS] [components...]]
1680                             [CONFIG|NO_MODULE]
1681                             [NO_POLICY_SCOPE]
1682                             [NAMES name1 [name2 ...]]
1683                             [CONFIGS config1 [config2 ...]]
1684                             [HINTS path1 [path2 ... ]]
1685                             [PATHS path1 [path2 ... ]]
1686                             [PATH_SUFFIXES suffix1 [suffix2 ...]]
1687                             [NO_DEFAULT_PATH]
1688                             [NO_CMAKE_ENVIRONMENT_PATH]
1689                             [NO_CMAKE_PATH]
1690                             [NO_SYSTEM_ENVIRONMENT_PATH]
1691                             [NO_CMAKE_PACKAGE_REGISTRY]
1692                             [NO_CMAKE_BUILDS_PATH]
1693                             [NO_CMAKE_SYSTEM_PATH]
1694                             [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1695                             [CMAKE_FIND_ROOT_PATH_BOTH |
1696                              ONLY_CMAKE_FIND_ROOT_PATH |
1697                              NO_CMAKE_FIND_ROOT_PATH])
1698
1699              The CONFIG option may be used to skip Module mode explicitly and
1700              switch  to  Config  mode.   It is synonymous to using NO_MODULE.
1701              Config mode is also implied by use of options not  specified  in
1702              the reduced signature.
1703
1704
1705              Config  mode attempts to locate a configuration file provided by
1706              the package to be found.  A cache entry called <package>_DIR  is
1707              created  to  hold the directory containing the file.  By default
1708              the command searches for a package with the name <package>.   If
1709              the  NAMES  option  is  given  the  names  following it are used
1710              instead of <package>.  The command searches for  a  file  called
1711              "<name>Config.cmake"   or  "<lower-case-name>-config.cmake"  for
1712              each name specified.  A replacement set of  possible  configura‐
1713              tion  file  names  may  be  given using the CONFIGS option.  The
1714              search procedure is specified below.  Once found, the configura‐
1715              tion  file  is  read  and processed by CMake.  Since the file is
1716              provided by the package it already knows the location of package
1717              contents.   The full path to the configuration file is stored in
1718              the cmake variable <package>_CONFIG.
1719
1720
1721              All configuration files which  have  been  considered  by  CMake
1722              while  searching  for  an  installation  of  the package with an
1723              appropriate version are stored  in  the  cmake  variable  <pack‐
1724              age>_CONSIDERED_CONFIGS,   the  associated  versions  in  <pack‐
1725              age>_CONSIDERED_VERSIONS.
1726
1727
1728              If the package configuration file cannot  be  found  CMake  will
1729              generate  an error describing the problem unless the QUIET argu‐
1730              ment is specified.  If REQUIRED is specified and the package  is
1731              not  found  a  fatal  error  is generated and the configure step
1732              stops executing.  If <package>_DIR has been set to  a  directory
1733              not  containing  a  configuration  file CMake will ignore it and
1734              search from scratch.
1735
1736
1737              When the [version] argument is given Config mode will only  find
1738              a  version  of  the  package  that claims compatibility with the
1739              requested version (format is major[.minor[.patch[.tweak]]]).  If
1740              the EXACT option is given only a version of the package claiming
1741              an exact match of the requested version  may  be  found.   CMake
1742              does  not  establish  any  convention for the meaning of version
1743              numbers.  Package version numbers are checked by "version" files
1744              provided  by  the  packages themselves.  For a candidate package
1745              configuration file "<config-file>.cmake" the corresponding  ver‐
1746              sion  file  is  located  next  to  it  and  named  either "<con‐
1747              fig-file>-version.cmake" or "<config-file>Version.cmake".  If no
1748              such  version  file  is available then the configuration file is
1749              assumed to not be compatible  with  any  requested  version.   A
1750              basic  version file containing generic version matching code can
1751              be created using the  macro  write_basic_package_version_file(),
1752              see  its documentation for more details.  When a version file is
1753              found it is loaded to check the requested version  number.   The
1754              version  file is loaded in a nested scope in which the following
1755              variables have been defined:
1756
1757
1758                PACKAGE_FIND_NAME          = the <package> name
1759                PACKAGE_FIND_VERSION       = full requested version string
1760                PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
1761                PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
1762                PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
1763                PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
1764                PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
1765
1766              The version file checks whether it satisfies the requested  ver‐
1767              sion and sets these variables:
1768
1769
1770                PACKAGE_VERSION            = full provided version string
1771                PACKAGE_VERSION_EXACT      = true if version is exact match
1772                PACKAGE_VERSION_COMPATIBLE = true if version is compatible
1773                PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
1774
1775              These  variables  are  checked  by  the  find_package command to
1776              determine whether the configuration file provides an  acceptable
1777              version.   They  are  not  available after the find_package call
1778              returns.  If the version is acceptable the  following  variables
1779              are set:
1780
1781
1782                <package>_VERSION       = full provided version string
1783                <package>_VERSION_MAJOR = major version if provided, else 0
1784                <package>_VERSION_MINOR = minor version if provided, else 0
1785                <package>_VERSION_PATCH = patch version if provided, else 0
1786                <package>_VERSION_TWEAK = tweak version if provided, else 0
1787                <package>_VERSION_COUNT = number of version components, 0 to 4
1788
1789              and  the  corresponding  package  configuration  file is loaded.
1790              When multiple package configuration files  are  available  whose
1791              version  files claim compatibility with the version requested it
1792              is unspecified which one is  chosen.   No  attempt  is  made  to
1793              choose a highest or closest version number.
1794
1795
1796              Config  mode  provides  an elaborate interface and search proce‐
1797              dure.  Much of the interface is provided  for  completeness  and
1798              for  use internally by find-modules loaded by Module mode.  Most
1799              user code should simply call
1800
1801
1802                find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1803
1804              in order to find a package.  Package maintainers providing CMake
1805              package  configuration  files are encouraged to name and install
1806              them such that the procedure outlined below will find them with‐
1807              out requiring use of additional options.
1808
1809
1810              CMake constructs a set of possible installation prefixes for the
1811              package.  Under each prefix several directories are searched for
1812              a  configuration  file.   The  tables below show the directories
1813              searched.  Each entry is meant for installation trees  following
1814              Windows (W), UNIX (U), or Apple (A) conventions.
1815
1816
1817                <prefix>/                                               (W)
1818                <prefix>/(cmake|CMake)/                                 (W)
1819                <prefix>/<name>*/                                       (W)
1820                <prefix>/<name>*/(cmake|CMake)/                         (W)
1821                <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/          (U)
1822                <prefix>/(lib/<arch>|lib|share)/<name>*/                (U)
1823                <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (U)
1824
1825              On  systems  supporting  OS X Frameworks and Application Bundles
1826              the following directories are searched for frameworks or bundles
1827              containing a configuration file:
1828
1829
1830                <prefix>/<name>.framework/Resources/                    (A)
1831                <prefix>/<name>.framework/Resources/CMake/              (A)
1832                <prefix>/<name>.framework/Versions/*/Resources/         (A)
1833                <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
1834                <prefix>/<name>.app/Contents/Resources/                 (A)
1835                <prefix>/<name>.app/Contents/Resources/CMake/           (A)
1836
1837              In  all cases the <name> is treated as case-insensitive and cor‐
1838              responds to any of the names specified (<package> or names given
1839              by    NAMES).     Paths   with   lib/<arch>   are   enabled   if
1840              CMAKE_LIBRARY_ARCHITECTURE is set.  If PATH_SUFFIXES  is  speci‐
1841              fied  the  suffixes  are  appended  to each (W) or (U) directory
1842              entry one-by-one.
1843
1844
1845              This set of directories is intended to work in cooperation  with
1846              projects  that provide configuration files in their installation
1847              trees.  Directories above  marked  with  (W)  are  intended  for
1848              installations  on  Windows where the prefix may point at the top
1849              of an application's installation directory.  Those  marked  with
1850              (U)  are  intended for installations on UNIX platforms where the
1851              prefix is shared by multiple packages.  This is merely a conven‐
1852              tion,  so  all (W) and (U) directories are still searched on all
1853              platforms.  Directories marked with (A) are intended for instal‐
1854              lations    on    Apple    platforms.     The   cmake   variables
1855              CMAKE_FIND_FRAMEWORK  and  CMAKE_FIND_APPBUNDLE  determine   the
1856              order of preference as specified below.
1857
1858
1859              The  set  of installation prefixes is constructed using the fol‐
1860              lowing steps.  If NO_DEFAULT_PATH is specified all NO_*  options
1861              are enabled.
1862
1863
1864              1.  Search  paths  specified  in cmake-specific cache variables.
1865              These are intended to  be  used  on  the  command  line  with  a
1866              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
1867
1868
1869                 CMAKE_PREFIX_PATH
1870                 CMAKE_FRAMEWORK_PATH
1871                 CMAKE_APPBUNDLE_PATH
1872
1873              2.  Search  paths  specified in cmake-specific environment vari‐
1874              ables.  These are intended to be set in the user's shell config‐
1875              uration.   This  can  be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1876              passed.
1877
1878
1879                 <package>_DIR
1880                 CMAKE_PREFIX_PATH
1881                 CMAKE_FRAMEWORK_PATH
1882                 CMAKE_APPBUNDLE_PATH
1883
1884              3. Search paths specified by the HINTS option.  These should  be
1885              paths  computed by system introspection, such as a hint provided
1886              by the location  of  another  item  already  found.   Hard-coded
1887              guesses should be specified with the PATHS option.
1888
1889
1890              4. Search the standard system environment variables. This can be
1891              skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed.   Path  entries
1892              ending in "/bin" or "/sbin" are automatically converted to their
1893              parent directories.
1894
1895
1896                 PATH
1897
1898              5. Search project build trees recently  configured  in  a  CMake
1899              GUI.  This can be skipped if NO_CMAKE_BUILDS_PATH is passed.  It
1900              is intended for the case when a user is building multiple depen‐
1901              dent projects one after another.
1902
1903
1904              6. Search paths stored in the CMake user package registry.  This
1905              can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed.  On  Win‐
1906              dows a <package> may appear under registry key
1907
1908
1909                HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
1910
1911              as  a  REG_SZ  value,  with  arbitrary  name, that specifies the
1912              directory containing the package configuration  file.   On  UNIX
1913              platforms a <package> may appear under the directory
1914
1915
1916                ~/.cmake/packages/<package>
1917
1918              as  a  file,  with  arbitrary  name, whose content specifies the
1919              directory containing the package configuration  file.   See  the
1920              export(PACKAGE)  command to create user package registry entries
1921              for project build trees.
1922
1923
1924              7. Search cmake variables defined in the Platform files for  the
1925              current  system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is
1926              passed.
1927
1928
1929                 CMAKE_SYSTEM_PREFIX_PATH
1930                 CMAKE_SYSTEM_FRAMEWORK_PATH
1931                 CMAKE_SYSTEM_APPBUNDLE_PATH
1932
1933              8. Search paths stored in the  CMake  system  package  registry.
1934              This  can  be  skipped  if  NO_CMAKE_SYSTEM_PACKAGE_REGISTRY  is
1935              passed.  On Windows a <package> may appear under registry key
1936
1937
1938                HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
1939
1940              as a REG_SZ value,  with  arbitrary  name,  that  specifies  the
1941              directory  containing  the package configuration file.  There is
1942              no system package registry on non-Windows platforms.
1943
1944
1945              9. Search paths specified by the PATHS option.  These are  typi‐
1946              cally hard-coded guesses.
1947
1948
1949              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1950              able    CMAKE_FIND_FRAMEWORK can be set to empty or one  of  the
1951              following:
1952
1953
1954                 "FIRST"  - Try to find frameworks before standard
1955                            libraries or headers. This is the default on Darwin.
1956                 "LAST"   - Try to find frameworks after standard
1957                            libraries or headers.
1958                 "ONLY"   - Only try to find frameworks.
1959                 "NEVER" - Never try to find frameworks.
1960
1961              On  Darwin  or  systems supporting OS X Application Bundles, the
1962              cmake variable CMAKE_FIND_APPBUNDLE can be set to empty  or  one
1963              of the following:
1964
1965
1966                 "FIRST"  - Try to find application bundles before standard
1967                            programs. This is the default on Darwin.
1968                 "LAST"   - Try to find application bundles after standard
1969                            programs.
1970                 "ONLY"   - Only try to find application bundles.
1971                 "NEVER" - Never try to find application bundles.
1972
1973              The  CMake  variable  CMAKE_FIND_ROOT_PATH specifies one or more
1974              directories to be prepended to  all  other  search  directories.
1975              This  effectively "re-roots" the entire search under given loca‐
1976              tions. By default it is empty.  It  is  especially  useful  when
1977              cross-compiling  to  point  to  the root directory of the target
1978              environment and CMake will search there too. By default at first
1979              the  directories  listed  in  CMAKE_FIND_ROOT_PATH  and then the
1980              non-rooted directories will be searched.  The  default  behavior
1981              can  be  adjusted  by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
1982              This behavior can be manually overridden on a per-call basis. By
1983              using  CMAKE_FIND_ROOT_PATH_BOTH  the  search  order  will be as
1984              described  above.  If  NO_CMAKE_FIND_ROOT_PATH  is   used   then
1985              CMAKE_FIND_ROOT_PATH      will      not      be     used.     If
1986              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1987              tories will be searched.
1988
1989
1990              The  default  search  order  is  designed to be most-specific to
1991              least-specific for common use cases.  Projects may override  the
1992              order by simply calling the command multiple times and using the
1993              NO_* options:
1994
1995
1996                 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
1997                 find_package(<package>)
1998
1999              Once one of the calls succeeds the result variable will  be  set
2000              and stored in the cache so that no call will search again.
2001
2002
2003              Every  non-REQUIRED  find_package() call can be disabled by set‐
2004              ting the variable CMAKE_DISABLE_FIND_PACKAGE_<package> to  TRUE.
2005              See  the documentation for the CMAKE_DISABLE_FIND_PACKAGE_<pack‐
2006              age> variable for more information.
2007
2008
2009              When  loading  a  find  module  or  package  configuration  file
2010              find_package  defines variables to provide information about the
2011              call arguments (and restores their original state before return‐
2012              ing):
2013
2014
2015               <package>_FIND_REQUIRED      = true if REQUIRED option was given
2016               <package>_FIND_QUIETLY       = true if QUIET option was given
2017               <package>_FIND_VERSION       = full requested version string
2018               <package>_FIND_VERSION_MAJOR = major version if requested, else 0
2019               <package>_FIND_VERSION_MINOR = minor version if requested, else 0
2020               <package>_FIND_VERSION_PATCH = patch version if requested, else 0
2021               <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0
2022               <package>_FIND_VERSION_COUNT = number of version components, 0 to 4
2023               <package>_FIND_VERSION_EXACT = true if EXACT option was given
2024               <package>_FIND_COMPONENTS    = list of requested components
2025               <package>_FIND_REQUIRED_<c>  = true if component <c> is required
2026                                              false if component <c> is optional
2027
2028              In  Module  mode  the loaded find module is responsible to honor
2029              the request detailed by these variables; see the find module for
2030              details.   In  Config mode find_package handles REQUIRED, QUIET,
2031              and version options automatically but leaves it to  the  package
2032              configuration  file  to  handle  components  in a way that makes
2033              sense for the package.  The package configuration file  may  set
2034              <package>_FOUND  to  false  to  tell find_package that component
2035              requirements are not satisfied.
2036
2037
2038              See the cmake_policy() command documentation for  discussion  of
2039              the NO_POLICY_SCOPE option.
2040
2041
2042       find_path
2043              Find the directory containing a file.
2044
2045                 find_path(<VAR> name1 [path1 path2 ...])
2046
2047              This  is the short-hand signature for the command that is suffi‐
2048              cient in many cases.  It is the same  as  find_path(<VAR>  name1
2049              [PATHS path1 path2 ...])
2050
2051
2052                 find_path(
2053                           <VAR>
2054                           name | NAMES name1 [name2 ...]
2055                           [HINTS path1 [path2 ... ENV var]]
2056                           [PATHS path1 [path2 ... ENV var]]
2057                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
2058                           [DOC "cache documentation string"]
2059                           [NO_DEFAULT_PATH]
2060                           [NO_CMAKE_ENVIRONMENT_PATH]
2061                           [NO_CMAKE_PATH]
2062                           [NO_SYSTEM_ENVIRONMENT_PATH]
2063                           [NO_CMAKE_SYSTEM_PATH]
2064                           [CMAKE_FIND_ROOT_PATH_BOTH |
2065                            ONLY_CMAKE_FIND_ROOT_PATH |
2066                            NO_CMAKE_FIND_ROOT_PATH]
2067                          )
2068
2069              This  command  is  used to find a directory containing the named
2070              file. A cache entry named by  <VAR>  is  created  to  store  the
2071              result of this command.  If the file in a directory is found the
2072              result is stored in the variable and  the  search  will  not  be
2073              repeated  unless  the variable is cleared.  If nothing is found,
2074              the result will  be  <VAR>-NOTFOUND,  and  the  search  will  be
2075              attempted again the next time find_path is invoked with the same
2076              variable.  The name of the file in a directory that is  searched
2077              for  is  specified by the names listed after the NAMES argument.
2078              Additional search locations can be  specified  after  the  PATHS
2079              argument.  If ENV var is found in the HINTS or PATHS section the
2080              environment variable var will be read and converted from a  sys‐
2081              tem  environment  variable  to a cmake style list of paths.  For
2082              example ENV PATH would be a way to list the  system  path  vari‐
2083              able.  The argument after DOC will be used for the documentation
2084              string in the cache.  PATH_SUFFIXES specifies additional  subdi‐
2085              rectories to check below each search path.
2086
2087
2088              If  NO_DEFAULT_PATH  is  specified, then no additional paths are
2089              added to the search. If NO_DEFAULT_PATH is  not  specified,  the
2090              search process is as follows:
2091
2092
2093              1.  Search  paths  specified  in cmake-specific cache variables.
2094              These are intended to  be  used  on  the  command  line  with  a
2095              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
2096
2097
2098                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2099                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2100                 CMAKE_INCLUDE_PATH
2101                 CMAKE_FRAMEWORK_PATH
2102
2103              2.  Search  paths  specified in cmake-specific environment vari‐
2104              ables.  These are intended to be set in the user's shell config‐
2105              uration.   This  can  be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2106              passed.
2107
2108
2109                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2110                 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2111                 CMAKE_INCLUDE_PATH
2112                 CMAKE_FRAMEWORK_PATH
2113
2114              3. Search the paths specified by the HINTS option.  These should
2115              be  paths  computed by system introspection, such as a hint pro‐
2116              vided by the location of another item already found.  Hard-coded
2117              guesses should be specified with the PATHS option.
2118
2119
2120              4. Search the standard system environment variables. This can be
2121              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2122
2123
2124                 PATH
2125                 INCLUDE
2126
2127              5. Search cmake variables defined in the Platform files for  the
2128              current  system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is
2129              passed.
2130
2131
2132                 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2133                 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2134                 CMAKE_SYSTEM_INCLUDE_PATH
2135                 CMAKE_SYSTEM_FRAMEWORK_PATH
2136
2137              6. Search the paths specified by the  PATHS  option  or  in  the
2138              short-hand   version   of  the  command.   These  are  typically
2139              hard-coded guesses.
2140
2141
2142              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2143              able     CMAKE_FIND_FRAMEWORK  can be set to empty or one of the
2144              following:
2145
2146
2147                 "FIRST"  - Try to find frameworks before standard
2148                            libraries or headers. This is the default on Darwin.
2149                 "LAST"   - Try to find frameworks after standard
2150                            libraries or headers.
2151                 "ONLY"   - Only try to find frameworks.
2152                 "NEVER" - Never try to find frameworks.
2153
2154              On Darwin or systems supporting OS X  Application  Bundles,  the
2155              cmake  variable  CMAKE_FIND_APPBUNDLE can be set to empty or one
2156              of the following:
2157
2158
2159                 "FIRST"  - Try to find application bundles before standard
2160                            programs. This is the default on Darwin.
2161                 "LAST"   - Try to find application bundles after standard
2162                            programs.
2163                 "ONLY"   - Only try to find application bundles.
2164                 "NEVER" - Never try to find application bundles.
2165
2166              The CMake variable CMAKE_FIND_ROOT_PATH specifies  one  or  more
2167              directories  to  be  prepended  to all other search directories.
2168              This effectively "re-roots" the entire search under given  loca‐
2169              tions.  By  default  it  is  empty. It is especially useful when
2170              cross-compiling to point to the root  directory  of  the  target
2171              environment and CMake will search there too. By default at first
2172              the directories listed  in  CMAKE_FIND_ROOT_PATH  and  then  the
2173              non-rooted  directories  will  be searched. The default behavior
2174              can be adjusted  by  setting  CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2175              This behavior can be manually overridden on a per-call basis. By
2176              using CMAKE_FIND_ROOT_PATH_BOTH the  search  order  will  be  as
2177              described   above.   If  NO_CMAKE_FIND_ROOT_PATH  is  used  then
2178              CMAKE_FIND_ROOT_PATH     will     not      be      used.      If
2179              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2180              tories will be searched.
2181
2182
2183              The default search order is  designed  to  be  most-specific  to
2184              least-specific  for common use cases.  Projects may override the
2185              order by simply calling the command multiple times and using the
2186              NO_* options:
2187
2188
2189                 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2190                 find_path(<VAR> NAMES name)
2191
2192              Once  one  of the calls succeeds the result variable will be set
2193              and stored in the cache so that no call will search again.
2194
2195
2196              When searching for frameworks,  if  the  file  is  specified  as
2197              A/b.h, then the framework search will look for A.framework/Head‐
2198              ers/b.h. If that is found the path will be set to  the  path  to
2199              the  framework. CMake will convert this to the correct -F option
2200              to include the file.
2201
2202
2203       find_program
2204              Find an executable program.
2205
2206                 find_program(<VAR> name1 [path1 path2 ...])
2207
2208              This is the short-hand signature for the command that is  suffi‐
2209              cient in many cases.  It is the same as find_program(<VAR> name1
2210              [PATHS path1 path2 ...])
2211
2212
2213                 find_program(
2214                           <VAR>
2215                           name | NAMES name1 [name2 ...]
2216                           [HINTS path1 [path2 ... ENV var]]
2217                           [PATHS path1 [path2 ... ENV var]]
2218                           [PATH_SUFFIXES suffix1 [suffix2 ...]]
2219                           [DOC "cache documentation string"]
2220                           [NO_DEFAULT_PATH]
2221                           [NO_CMAKE_ENVIRONMENT_PATH]
2222                           [NO_CMAKE_PATH]
2223                           [NO_SYSTEM_ENVIRONMENT_PATH]
2224                           [NO_CMAKE_SYSTEM_PATH]
2225                           [CMAKE_FIND_ROOT_PATH_BOTH |
2226                            ONLY_CMAKE_FIND_ROOT_PATH |
2227                            NO_CMAKE_FIND_ROOT_PATH]
2228                          )
2229
2230              This command is used to find a program. A cache entry  named  by
2231              <VAR>  is  created  to store the result of this command.  If the
2232              program is found the result is stored in the  variable  and  the
2233              search  will not be repeated unless the variable is cleared.  If
2234              nothing is found, the result will  be  <VAR>-NOTFOUND,  and  the
2235              search  will  be  attempted  again the next time find_program is
2236              invoked with the same variable.  The name of the program that is
2237              searched  for  is  specified by the names listed after the NAMES
2238              argument.   Additional search locations can be  specified  after
2239              the  PATHS  argument.  If ENV var is found in the HINTS or PATHS
2240              section the environment variable var will be read and  converted
2241              from  a  system  environment  variable  to a cmake style list of
2242              paths.  For example ENV PATH would be a way to list  the  system
2243              path variable. The argument after DOC will be used for the docu‐
2244              mentation string in the cache.   PATH_SUFFIXES  specifies  addi‐
2245              tional subdirectories to check below each search path.
2246
2247
2248              If  NO_DEFAULT_PATH  is  specified, then no additional paths are
2249              added to the search. If NO_DEFAULT_PATH is  not  specified,  the
2250              search process is as follows:
2251
2252
2253              1.  Search  paths  specified  in cmake-specific cache variables.
2254              These are intended to  be  used  on  the  command  line  with  a
2255              -DVAR=value.  This can be skipped if NO_CMAKE_PATH is passed.
2256
2257
2258                 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2259                 CMAKE_PROGRAM_PATH
2260                 CMAKE_APPBUNDLE_PATH
2261
2262              2.  Search  paths  specified in cmake-specific environment vari‐
2263              ables.  These are intended to be set in the user's shell config‐
2264              uration.   This  can  be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2265              passed.
2266
2267
2268                 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2269                 CMAKE_PROGRAM_PATH
2270                 CMAKE_APPBUNDLE_PATH
2271
2272              3. Search the paths specified by the HINTS option.  These should
2273              be  paths  computed by system introspection, such as a hint pro‐
2274              vided by the location of another item already found.  Hard-coded
2275              guesses should be specified with the PATHS option.
2276
2277
2278              4. Search the standard system environment variables. This can be
2279              skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2280
2281
2282                 PATH
2283
2284
2285              5. Search cmake variables defined in the Platform files for  the
2286              current  system.  This can be skipped if NO_CMAKE_SYSTEM_PATH is
2287              passed.
2288
2289
2290                 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2291                 CMAKE_SYSTEM_PROGRAM_PATH
2292                 CMAKE_SYSTEM_APPBUNDLE_PATH
2293
2294              6. Search the paths specified by the  PATHS  option  or  in  the
2295              short-hand   version   of  the  command.   These  are  typically
2296              hard-coded guesses.
2297
2298
2299              On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2300              able     CMAKE_FIND_FRAMEWORK  can be set to empty or one of the
2301              following:
2302
2303
2304                 "FIRST"  - Try to find frameworks before standard
2305                            libraries or headers. This is the default on Darwin.
2306                 "LAST"   - Try to find frameworks after standard
2307                            libraries or headers.
2308                 "ONLY"   - Only try to find frameworks.
2309                 "NEVER" - Never try to find frameworks.
2310
2311              On Darwin or systems supporting OS X  Application  Bundles,  the
2312              cmake  variable  CMAKE_FIND_APPBUNDLE can be set to empty or one
2313              of the following:
2314
2315
2316                 "FIRST"  - Try to find application bundles before standard
2317                            programs. This is the default on Darwin.
2318                 "LAST"   - Try to find application bundles after standard
2319                            programs.
2320                 "ONLY"   - Only try to find application bundles.
2321                 "NEVER" - Never try to find application bundles.
2322
2323              The CMake variable CMAKE_FIND_ROOT_PATH specifies  one  or  more
2324              directories  to  be  prepended  to all other search directories.
2325              This effectively "re-roots" the entire search under given  loca‐
2326              tions.  By  default  it  is  empty. It is especially useful when
2327              cross-compiling to point to the root  directory  of  the  target
2328              environment and CMake will search there too. By default at first
2329              the directories listed  in  CMAKE_FIND_ROOT_PATH  and  then  the
2330              non-rooted  directories  will  be searched. The default behavior
2331              can be adjusted  by  setting  CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
2332              This behavior can be manually overridden on a per-call basis. By
2333              using CMAKE_FIND_ROOT_PATH_BOTH the  search  order  will  be  as
2334              described   above.   If  NO_CMAKE_FIND_ROOT_PATH  is  used  then
2335              CMAKE_FIND_ROOT_PATH     will     not      be      used.      If
2336              ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2337              tories will be searched.
2338
2339
2340              The default search order is  designed  to  be  most-specific  to
2341              least-specific  for common use cases.  Projects may override the
2342              order by simply calling the command multiple times and using the
2343              NO_* options:
2344
2345
2346                 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2347                 find_program(<VAR> NAMES name)
2348
2349              Once  one  of the calls succeeds the result variable will be set
2350              and stored in the cache so that no call will search again.
2351
2352
2353       foreach
2354              Evaluate a group of commands for each value in a list.
2355
2356                foreach(loop_var arg1 arg2 ...)
2357                  COMMAND1(ARGS ...)
2358                  COMMAND2(ARGS ...)
2359                  ...
2360                endforeach(loop_var)
2361
2362              All commands between foreach and  the  matching  endforeach  are
2363              recorded  without  being invoked.  Once the endforeach is evalu‐
2364              ated, the recorded list of commands is  invoked  once  for  each
2365              argument  listed  in  the original foreach command.  Before each
2366              iteration of the loop "${loop_var}" will be set  as  a  variable
2367              with the current value in the list.
2368
2369
2370                foreach(loop_var RANGE total)
2371                foreach(loop_var RANGE start stop [step])
2372
2373              Foreach  can  also  iterate  over  a generated range of numbers.
2374              There are three types of this iteration:
2375
2376
2377              * When specifying single number, the range will have elements  0
2378              to "total".
2379
2380
2381              * When specifying two numbers, the range will have elements from
2382              the first number to the second number.
2383
2384
2385              * The third optional number is the  increment  used  to  iterate
2386              from the first number to the second number.
2387
2388
2389                foreach(loop_var IN [LISTS [list1 [...]]]
2390                                    [ITEMS [item1 [...]]])
2391
2392              Iterates  over  a precise list of items.  The LISTS option names
2393              list-valued variables to be traversed, including empty  elements
2394              (an  empty string is a zero-length list).  The ITEMS option ends
2395              argument parsing and includes all arguments following it in  the
2396              iteration.
2397
2398
2399       function
2400              Start recording a function for later invocation as a command.
2401
2402                function(<name> [arg1 [arg2 [arg3 ...]]])
2403                  COMMAND1(ARGS ...)
2404                  COMMAND2(ARGS ...)
2405                  ...
2406                endfunction(<name>)
2407
2408              Define  a  function named <name> that takes arguments named arg1
2409              arg2 arg3 (...).  Commands listed after function, but before the
2410              matching  endfunction,  are  not  invoked  until the function is
2411              invoked.  When it is invoked, the commands recorded in the func‐
2412              tion are first modified by replacing formal parameters (${arg1})
2413              with the arguments passed, and then invoked as normal  commands.
2414              In  addition to referencing the formal parameters you can refer‐
2415              ence the variable ARGC which will be set to the number of  argu‐
2416              ments  passed into the function as well as ARGV0 ARGV1 ARGV2 ...
2417              which will have the actual values of the  arguments  passed  in.
2418              This  facilitates  creating  functions  with optional arguments.
2419              Additionally ARGV holds the list of all arguments given  to  the
2420              function  and  ARGN  holds  the  list of arguments past the last
2421              expected argument.
2422
2423
2424              A function opens a new  scope:  see  set(var  PARENT_SCOPE)  for
2425              details.
2426
2427
2428              See the cmake_policy() command documentation for the behavior of
2429              policies inside functions.
2430
2431
2432       get_cmake_property
2433              Get a property of the CMake instance.
2434
2435                get_cmake_property(VAR property)
2436
2437              Get a property from the CMake instance.  The value of the  prop‐
2438              erty  is  stored  in  the  variable VAR.  If the property is not
2439              found, VAR will be set to "NOTFOUND".  Some supported properties
2440              include:  VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and COM‐
2441              PONENTS.
2442
2443
2444              See also the more general get_property() command.
2445
2446
2447       get_directory_property
2448              Get a property of DIRECTORY scope.
2449
2450                get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2451
2452              Store a property of directory scope in the named  variable.   If
2453              the  property  is not defined the empty-string is returned.  The
2454              DIRECTORY argument specifies another  directory  from  which  to
2455              retrieve  the property value.  The specified directory must have
2456              already been traversed by CMake.
2457
2458
2459                get_directory_property(<variable> [DIRECTORY <dir>]
2460                                       DEFINITION <var-name>)
2461
2462              Get a variable definition from a directory.  This form is useful
2463              to get a variable definition from another directory.
2464
2465
2466              See also the more general get_property() command.
2467
2468
2469       get_filename_component
2470              Get a specific component of a full filename.
2471
2472                get_filename_component(<VAR> <FileName> <COMP> [CACHE])
2473
2474              Set <VAR> to a component of <FileName>, where <COMP> is one of:
2475
2476
2477               DIRECTORY = Directory without file name
2478               NAME      = File name without directory
2479               EXT       = File name longest extension (.b.c from d/a.b.c)
2480               NAME_WE   = File name without directory or longest extension
2481               ABSOLUTE  = Full path to file
2482               REALPATH  = Full path to existing file with symlinks resolved
2483               PATH      = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2484
2485              Paths  are  returned  with  forward slashes and have no trailing
2486              slahes. The longest file extension is always considered. If  the
2487              optional  CACHE  argument  is  specified, the result variable is
2488              added to the cache.
2489
2490
2491                get_filename_component(<VAR> FileName
2492                                       PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2493                                       [CACHE])
2494
2495              The program in FileName will be found in the system search  path
2496              or  left  as  a full path.  If PROGRAM_ARGS is present with PRO‐
2497              GRAM, then any command-line arguments present  in  the  FileName
2498              string  are split from the program name and stored in <ARG_VAR>.
2499              This is used to separate a program name from its arguments in  a
2500              command line string.
2501
2502
2503       get_property
2504              Get a property.
2505
2506                get_property(<variable>
2507                             <GLOBAL             |
2508                              DIRECTORY [dir]    |
2509                              TARGET    <target> |
2510                              SOURCE    <source> |
2511                              TEST      <test>   |
2512                              CACHE     <entry>  |
2513                              VARIABLE>
2514                             PROPERTY <name>
2515                             [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2516
2517              Get one property from one object in a scope.  The first argument
2518              specifies the variable in which to store the result.  The second
2519              argument  determines  the  scope from which to get the property.
2520              It must be one of the following:
2521
2522
2523              GLOBAL scope is unique and does not accept a name.
2524
2525
2526              DIRECTORY scope defaults to the current  directory  but  another
2527              directory  (already  processed by CMake) may be named by full or
2528              relative path.
2529
2530
2531              TARGET scope must name one existing target.
2532
2533
2534              SOURCE scope must name one source file.
2535
2536
2537              TEST scope must name one existing test.
2538
2539
2540              CACHE scope must name one cache entry.
2541
2542
2543              VARIABLE scope is unique and does not accept a name.
2544
2545
2546              The required PROPERTY option is immediately followed by the name
2547              of  the  property  to  get.  If the property is not set an empty
2548              value is returned.  If the SET option is given the  variable  is
2549              set  to a boolean value indicating whether the property has been
2550              set.  If the DEFINED option is given the variable is  set  to  a
2551              boolean  value  indicating whether the property has been defined
2552              such as with define_property.  If  BRIEF_DOCS  or  FULL_DOCS  is
2553              given then the variable is set to a string containing documenta‐
2554              tion for the requested property.  If documentation is  requested
2555              for a property that has not been defined NOTFOUND is returned.
2556
2557
2558       if     Conditionally execute a group of commands.
2559
2560                if(expression)
2561                  # then section.
2562                  COMMAND1(ARGS ...)
2563                  COMMAND2(ARGS ...)
2564                  ...
2565                elseif(expression2)
2566                  # elseif section.
2567                  COMMAND1(ARGS ...)
2568                  COMMAND2(ARGS ...)
2569                  ...
2570                else(expression)
2571                  # else section.
2572                  COMMAND1(ARGS ...)
2573                  COMMAND2(ARGS ...)
2574                  ...
2575                endif(expression)
2576
2577              Evaluates the given expression.  If the result is true, the com‐
2578              mands in the THEN section are invoked.  Otherwise, the  commands
2579              in  the  else section are invoked.  The elseif and else sections
2580              are optional. You may have multiple elseif  clauses.  Note  that
2581              the  expression  in  the else and endif clause is optional. Long
2582              expressions can be used and there  is  a  traditional  order  of
2583              precedence.  Parenthetical  expressions are evaluated first fol‐
2584              lowed by unary operators such as EXISTS, COMMAND,  and  DEFINED.
2585              Then  any  EQUAL,  LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
2586              MATCHES will be evaluated. Then NOT operators and  finally  AND,
2587              OR operators will be evaluated. Possible expressions are:
2588
2589
2590                if(<constant>)
2591
2592              True  if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2593              ber.  False if the constant is 0, OFF,  NO,  FALSE,  N,  IGNORE,
2594              NOTFOUND,  '', or ends in the suffix '-NOTFOUND'.  Named boolean
2595              constants are case-insensitive.  If the argument is not  one  of
2596              these constants, it is treated as a variable:
2597
2598
2599                if(<variable>)
2600
2601              True  if  the variable is defined to a value that is not a false
2602              constant.  False otherwise.  (Note macro arguments are not vari‐
2603              ables.)
2604
2605
2606                if(NOT <expression>)
2607
2608              True if the expression is not true.
2609
2610
2611                if(<expr1> AND <expr2>)
2612
2613              True if both expressions would be considered true individually.
2614
2615
2616                if(<expr1> OR <expr2>)
2617
2618              True if either expression would be considered true individually.
2619
2620
2621                if(COMMAND command-name)
2622
2623              True  if the given name is a command, macro or function that can
2624              be invoked.
2625
2626
2627                if(POLICY policy-id)
2628
2629              True if the given name  is  an  existing  policy  (of  the  form
2630              CMP<NNNN>).
2631
2632
2633                if(TARGET target-name)
2634
2635              True if the given name is an existing target, built or imported.
2636
2637
2638                if(EXISTS file-name)
2639                if(EXISTS directory-name)
2640
2641              True  if  the  named  file  or  directory  exists.   Behavior is
2642              well-defined only for full paths.
2643
2644
2645                if(file1 IS_NEWER_THAN file2)
2646
2647              True if file1 is newer than file2 or if one  of  the  two  files
2648              doesn't  exist. Behavior is well-defined only for full paths. If
2649              the file time stamps are exactly the same, an IS_NEWER_THAN com‐
2650              parison  returns  true,  so  that any dependent build operations
2651              will occur in the event of a tie.  This  includes  the  case  of
2652              passing the same file name for both file1 and file2.
2653
2654
2655                if(IS_DIRECTORY directory-name)
2656
2657              True if the given name is a directory.  Behavior is well-defined
2658              only for full paths.
2659
2660
2661                if(IS_SYMLINK file-name)
2662
2663              True if  the  given  name  is  a  symbolic  link.   Behavior  is
2664              well-defined only for full paths.
2665
2666
2667                if(IS_ABSOLUTE path)
2668
2669              True if the given path is an absolute path.
2670
2671
2672                if(<variable|string> MATCHES regex)
2673
2674              True  if  the given string or variable's value matches the given
2675              regular expression.
2676
2677
2678                if(<variable|string> LESS <variable|string>)
2679                if(<variable|string> GREATER <variable|string>)
2680                if(<variable|string> EQUAL <variable|string>)
2681
2682              True if the given string or variable's value is a  valid  number
2683              and the inequality or equality is true.
2684
2685
2686                if(<variable|string> STRLESS <variable|string>)
2687                if(<variable|string> STRGREATER <variable|string>)
2688                if(<variable|string> STREQUAL <variable|string>)
2689
2690              True  if  the  given string or variable's value is lexicographi‐
2691              cally less (or greater, or equal) than the string or variable on
2692              the right.
2693
2694
2695                if(<variable|string> VERSION_LESS <variable|string>)
2696                if(<variable|string> VERSION_EQUAL <variable|string>)
2697                if(<variable|string> VERSION_GREATER <variable|string>)
2698
2699              Component-wise integer version number comparison (version format
2700              is major[.minor[.patch[.tweak]]]).
2701
2702
2703                if(DEFINED <variable>)
2704
2705              True if the given variable is defined. It does not matter if the
2706              variable is true or false just if it has been set.
2707
2708
2709                if((expression) AND (expression OR (expression)))
2710
2711              The  expressions  inside the parenthesis are evaluated first and
2712              then the remaining expression is evaluated as  in  the  previous
2713              examples.  Where  there are nested parenthesis the innermost are
2714              evaluated as part of evaluating  the  expression  that  contains
2715              them.
2716
2717
2718              The  if  command was written very early in CMake's history, pre‐
2719              dating the ${} variable evaluation syntax, and  for  convenience
2720              evaluates variables named by its arguments as shown in the above
2721              signatures.  Note  that  normal  variable  evaluation  with  ${}
2722              applies  before  the  if  command  even  receives the arguments.
2723              Therefore code like
2724
2725
2726                set(var1 OFF)
2727                set(var2 "var1")
2728                if(${var2})
2729
2730              appears to the if command as
2731
2732
2733                if(var1)
2734
2735              and is evaluated according to the if(<variable>) case documented
2736              above.  The result is OFF which is false.  However, if we remove
2737              the ${} from the example then the command sees
2738
2739
2740                if(var2)
2741
2742              which is true because var2 is defined to "var1" which is  not  a
2743              false constant.
2744
2745
2746              Automatic  evaluation  applies  in  the other cases whenever the
2747              above-documented signature accepts <variable|string>:
2748
2749
2750              1) The left hand argument to MATCHES is first checked to see  if
2751              it  is  a  defined variable, if so the variable's value is used,
2752              otherwise the original value is used.
2753
2754
2755              2) If the left hand argument to MATCHES is  missing  it  returns
2756              false without error
2757
2758
2759              3)  Both left and right hand arguments to LESS GREATER EQUAL are
2760              independently tested to see if they are defined variables, if so
2761              their  defined  values  are used otherwise the original value is
2762              used.
2763
2764
2765              4) Both left and right hand arguments to STRLESS  STREQUAL  STR‐
2766              GREATER  are  independently  tested  to  see if they are defined
2767              variables, if so their defined values  are  used  otherwise  the
2768              original value is used.
2769
2770
2771              5)  Both  left  and  right  hand argumemnts to VERSION_LESS VER‐
2772              SION_EQUAL VERSION_GREATER are independently tested  to  see  if
2773              they  are defined variables, if so their defined values are used
2774              otherwise the original value is used.
2775
2776
2777              6) The right hand argument to NOT is tested to see if  it  is  a
2778              boolean  constant,  if  so  the  value  is used, otherwise it is
2779              assumed to be a variable and it is dereferenced.
2780
2781
2782              7) The left and right hand arguments to AND OR are independently
2783              tested to see if they are boolean constants, if so they are used
2784              as such, otherwise they are assumed  to  be  variables  and  are
2785              dereferenced.
2786
2787
2788
2789       include
2790              Load and run CMake code from a file or module.
2791
2792                include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
2793                                      [NO_POLICY_SCOPE])
2794
2795              Load and run CMake code from the file given.  Variable reads and
2796              writes access the scope of the  caller  (dynamic  scoping).   If
2797              OPTIONAL  is  present,  then no error is raised if the file does
2798              not exist.  If RESULT_VARIABLE is given the variable will be set
2799              to  the  full filename which has been included or NOTFOUND if it
2800              failed.
2801
2802
2803              If a module is specified instead of a file, the file  with  name
2804              <modulename>.cmake  is searched first in CMAKE_MODULE_PATH, then
2805              in the CMake module directory. There is one exception  to  this:
2806              if the file which calls include() is located itself in the CMake
2807              module directory, then  first  the  CMake  module  directory  is
2808              searched  and  CMAKE_MODULE_PATH  afterwards.  See  also  policy
2809              CMP0017.
2810
2811
2812              See the cmake_policy() command documentation for  discussion  of
2813              the NO_POLICY_SCOPE option.
2814
2815
2816       list   List operations.
2817
2818                list(LENGTH <list> <output variable>)
2819                list(GET <list> <element index> [<element index> ...]
2820                     <output variable>)
2821                list(APPEND <list> <element> [<element> ...])
2822                list(FIND <list> <value> <output variable>)
2823                list(INSERT <list> <element_index> <element> [<element> ...])
2824                list(REMOVE_ITEM <list> <value> [<value> ...])
2825                list(REMOVE_AT <list> <index> [<index> ...])
2826                list(REMOVE_DUPLICATES <list>)
2827                list(REVERSE <list>)
2828                list(SORT <list>)
2829
2830              LENGTH will return a given list's length.
2831
2832
2833              GET  will  return list of elements specified by indices from the
2834              list.
2835
2836
2837              APPEND will append elements to the list.
2838
2839
2840              FIND will return the index of the element specified in the  list
2841              or -1 if it wasn't found.
2842
2843
2844              INSERT  will  insert elements to the list to the specified loca‐
2845              tion.
2846
2847
2848              REMOVE_AT and REMOVE_ITEM will remove items from the  list.  The
2849              difference  is  that  REMOVE_ITEM  will  remove the given items,
2850              while REMOVE_AT will remove the items at the given indices.
2851
2852
2853              REMOVE_DUPLICATES will remove duplicated items in the list.
2854
2855
2856              REVERSE reverses the contents of the list in-place.
2857
2858
2859              SORT sorts the list in-place alphabetically.
2860
2861
2862              The list subcommands  APPEND,  INSERT,  REMOVE_AT,  REMOVE_ITEM,
2863              REMOVE_DUPLICATES,  REVERSE  and  SORT may create new values for
2864              the list within the current CMake variable scope. Similar to the
2865              SET command, the LIST command creates new variable values in the
2866              current scope, even if the list itself is actually defined in  a
2867              parent  scope.  To  propagate  the  results  of these operations
2868              upwards, use SET with PARENT_SCOPE, SET with CACHE INTERNAL,  or
2869              some other means of value propagation.
2870
2871
2872              NOTES:  A  list  in  cmake is a ; separated group of strings. To
2873              create a list the set command can be used. For example,  set(var
2874              a  b c d e)  creates a list with a;b;c;d;e, and set(var "a b c d
2875              e") creates a string or a list with one item in it.
2876
2877
2878              When specifying  index  values,  if  <element  index>  is  0  or
2879              greater,  it  is  indexed from the beginning of the list, with 0
2880              representing the first list element. If <element index> is -1 or
2881              lesser,  it  is indexed from the end of the list, with -1 repre‐
2882              senting the last list element. Be  careful  when  counting  with
2883              negative  indices: they do not start from 0. -0 is equivalent to
2884              0, the first list element.
2885
2886
2887
2888       macro  Start recording a macro for later invocation as a command.
2889
2890                macro(<name> [arg1 [arg2 [arg3 ...]]])
2891                  COMMAND1(ARGS ...)
2892                  COMMAND2(ARGS ...)
2893                  ...
2894                endmacro(<name>)
2895
2896              Define a macro named <name> that takes arguments named arg1 arg2
2897              arg3  (...).  Commands listed after macro, but before the match‐
2898              ing endmacro, are not invoked until the macro is invoked.   When
2899              it is invoked, the commands recorded in the macro are first mod‐
2900              ified by replacing formal parameters (${arg1})  with  the  argu‐
2901              ments  passed,  and then invoked as normal commands. In addition
2902              to referencing the formal parameters you can reference the  val‐
2903              ues  ${ARGC} which will be set to the number of arguments passed
2904              into the function as well  as  ${ARGV0}  ${ARGV1}  ${ARGV2}  ...
2905              which  will  have  the actual values of the arguments passed in.
2906              This facilitates creating macros with optional arguments.  Addi‐
2907              tionally  ${ARGV}  holds  the list of all arguments given to the
2908              macro and ${ARGN} holds the list  of  arguments  past  the  last
2909              expected  argument. Note that the parameters to a macro and val‐
2910              ues such as ARGN are not variables in  the  usual  CMake  sense.
2911              They  are string replacements much like the C preprocessor would
2912              do with a macro. If you want true CMake variables and/or  better
2913              CMake scope control you should look at the function command.
2914
2915
2916              See the cmake_policy() command documentation for the behavior of
2917              policies inside macros.
2918
2919
2920       make_directory
2921              Deprecated. Use the file(MAKE_DIRECTORY ) command instead.
2922
2923                make_directory(directory)
2924
2925              Creates the specified directory.  Full paths  should  be  given.
2926              Any  parent  directories that do not exist will also be created.
2927              Use with care.
2928
2929
2930       mark_as_advanced
2931              Mark cmake cached variables as advanced.
2932
2933                mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
2934
2935              Mark the named cached variables as advanced.  An advanced  vari‐
2936              able  will  not be displayed in any of the cmake GUIs unless the
2937              show advanced option is on.  If  CLEAR  is  the  first  argument
2938              advanced  variables are changed back to unadvanced.  If FORCE is
2939              the first argument, then the variable is made advanced.  If nei‐
2940              ther  FORCE nor CLEAR is specified, new values will be marked as
2941              advanced,   but    if    the    variable    already    has    an
2942              advanced/non-advanced state, it will not be changed.
2943
2944
2945              It does nothing in script mode.
2946
2947
2948       math   Mathematical expressions.
2949
2950                math(EXPR <output variable> <math expression>)
2951
2952              EXPR evaluates mathematical expression and returns result in the
2953              output variable. Example mathematical expression is '5 * ( 10  +
2954              13  )'.   Supported operators are + - * / % | & ^ ~ << >> * / %.
2955              They have the same meaning  as they do in C code.
2956
2957
2958       message
2959              Display a message to the user.
2960
2961                message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
2962                        "message to display" ...)
2963
2964              The optional keyword determines the type of message:
2965
2966
2967                (none)         = Important information
2968                STATUS         = Incidental information
2969                WARNING        = CMake Warning, continue processing
2970                AUTHOR_WARNING = CMake Warning (dev), continue processing
2971                SEND_ERROR     = CMake Error, continue processing,
2972                                              but skip generation
2973                FATAL_ERROR    = CMake Error, stop processing and generation
2974
2975              The CMake command-line tool displays STATUS messages  on  stdout
2976              and  all  other message types on stderr.  The CMake GUI displays
2977              all messages in its log area.  The interactive  dialogs  (ccmake
2978              and  CMakeSetup)  show STATUS messages one at a time on a status
2979              line and other messages in interactive pop-up boxes.
2980
2981
2982              CMake Warning and Error message text  displays  using  a  simple
2983              markup language.  Non-indented text is formatted in line-wrapped
2984              paragraphs delimited by newlines.  Indented text  is  considered
2985              pre-formatted.
2986
2987
2988       option Provides an option that the user can optionally select.
2989
2990                option(<option_variable> "help string describing option"
2991                       [initial value])
2992
2993              Provide  an  option  for the user to select as ON or OFF.  If no
2994              initial value is provided, OFF is used.
2995
2996
2997              If you have options that depend on the values of other  options,
2998              see the module help for CMakeDependentOption.
2999
3000
3001       remove Deprecated. Use the list(REMOVE_ITEM ) command instead.
3002
3003                remove(VAR VALUE VALUE ...)
3004
3005              Removes  VALUE from the variable VAR.  This is typically used to
3006              remove entries from a vector (e.g.  semicolon  separated  list).
3007              VALUE is expanded.
3008
3009
3010       return Return from a file, directory or function.
3011
3012                return()
3013
3014              Returns from a file, directory or function. When this command is
3015              encountered in an included file  (via  include()  or  find_pack‐
3016              age()),  it  causes  processing  of the current file to stop and
3017              control is returned to the including file. If it is  encountered
3018              in  a  file which is not included by another file, e.g. a CMake‐
3019              Lists.txt, control is returned to the parent directory if  there
3020              is  one.  If return is called in a function, control is returned
3021              to the caller of the function. Note that a macro is not a  func‐
3022              tion and does not handle return like a function does.
3023
3024
3025       separate_arguments
3026              Parse space-separated arguments into a semicolon-separated list.
3027
3028                separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
3029
3030              Parses a unix- or windows-style command-line string "<args>" and
3031              stores a semicolon-separated list of  the  arguments  in  <var>.
3032              The entire command line must be given in one "<args>" argument.
3033
3034
3035              The  UNIX_COMMAND  mode  separates  arguments by unquoted white‐
3036              space.  It recognizes both single-quote and double-quote  pairs.
3037              A  backslash escapes the next literal character (\" is "); there
3038              are no special escapes (\n is just n).
3039
3040
3041              The WINDOWS_COMMAND mode parses a windows command-line using the
3042              same  syntax  the  runtime  library  uses  to  construct argv at
3043              startup.  It separates arguments by whitespace that is not  dou‐
3044              ble-quoted.   Backslashes  are  literal unless they precede dou‐
3045              ble-quotes.  See the MSDN article "Parsing C Command-Line  Argu‐
3046              ments" for details.
3047
3048
3049                separate_arguments(VARIABLE)
3050
3051              Convert  the  value  of VARIABLE to a semi-colon separated list.
3052              All spaces are replaced with ';'.  This  helps  with  generating
3053              command lines.
3054
3055
3056       set    Set a CMake, cache or environment variable to a given value.
3057
3058                set(<variable> <value>
3059                    [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
3060
3061              Within  CMake  sets <variable> to the value <value>.  <value> is
3062              expanded before <variable> is set to it.  Normally, set will set
3063              a  regular  CMake variable. If CACHE is present, then the <vari‐
3064              able> is put in the cache instead, unless it is already  in  the
3065              cache.  See  section 'Variable types in CMake' below for details
3066              of regular and cache variables and their interactions. If  CACHE
3067              is  used, <type> and <docstring> are required. <type> is used by
3068              the CMake GUI to choose a widget with  which  the  user  sets  a
3069              value. The value for <type> may be one of
3070
3071
3072                FILEPATH = File chooser dialog.
3073                PATH     = Directory chooser dialog.
3074                STRING   = Arbitrary string.
3075                BOOL     = Boolean ON/OFF checkbox.
3076                INTERNAL = No GUI entry (used for persistent variables).
3077
3078              If <type> is INTERNAL, the cache variable is marked as internal,
3079              and will not be shown to the user in tools like cmake-gui.  This
3080              is  intended  for  values that should be persisted in the cache,
3081              but which users should not  normally  change.  INTERNAL  implies
3082              FORCE.
3083
3084
3085              Normally, set(...CACHE...) creates cache variables, but does not
3086              modify them. If FORCE is specified, the value of the cache vari‐
3087              able  is set, even if the variable is already in the cache. This
3088              should normally be avoided, as it will remove any changes to the
3089              cache variable's value by the user.
3090
3091
3092              If  PARENT_SCOPE  is  present,  the  variable will be set in the
3093              scope above the current scope. Each new  directory  or  function
3094              creates  a new scope. This command will set the value of a vari‐
3095              able into the parent directory or calling function (whichever is
3096              applicable to the case at hand). PARENT_SCOPE cannot be combined
3097              with CACHE.
3098
3099
3100              If <value> is not specified then the variable is removed instead
3101              of set.  See also: the unset() command.
3102
3103
3104                set(<variable> <value1> ... <valueN>)
3105
3106              In  this case <variable> is set to a semicolon separated list of
3107              values.
3108
3109
3110              <variable> can be an environment variable such as:
3111
3112
3113                set( ENV{PATH} /home/martink )
3114
3115              in which case the environment variable will be set.
3116
3117
3118              *** Variable types in CMake ***
3119
3120
3121              In CMake there are two types of variables: normal variables  and
3122              cache variables. Normal variables are meant for the internal use
3123              of the script (just like  variables  in  most  programming  lan‐
3124              guages);  they  are not persisted across CMake runs. Cache vari‐
3125              ables (unless set with INTERNAL) are mostly intended for config‐
3126              uration settings where the first CMake run determines a suitable
3127              default value, which the user can then override, by editing  the
3128              cache  with  tools  such as ccmake or cmake-gui. Cache variables
3129              are stored in the CMake cache file,  and  are  persisted  across
3130              CMake runs.
3131
3132
3133              Both  types  can  exist  at the same time with the same name but
3134              different values. When ${FOO} is evaluated,  CMake  first  looks
3135              for  a normal variable 'FOO' in scope and uses it if set. If and
3136              only if no normal variable exists then  it  falls  back  to  the
3137              cache variable 'FOO'.
3138
3139
3140              Some examples:
3141
3142
3143              The  code 'set(FOO "x")' sets the normal variable 'FOO'. It does
3144              not touch the cache, but it will hide any existing  cache  value
3145              'FOO'.
3146
3147
3148              The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
3149              ignoring any normal variable of the same name. If  'FOO'  is  in
3150              the  cache then nothing happens to either the normal variable or
3151              the cache variable. If 'FOO' is not in the  cache,  then  it  is
3152              added to the cache.
3153
3154
3155              Finally,  whenever  a  cache  variable is added or modified by a
3156              command, CMake also *removes* the normal variable  of  the  same
3157              name  from  the  current  scope so that an immediately following
3158              evaluation of it will expose the newly cached value.
3159
3160
3161              Normally projects should avoid using normal and cache  variables
3162              of  the  same  name,  as this interaction can be hard to follow.
3163              However, in some situations it can be useful. One example  (used
3164              by some projects):
3165
3166
3167              A project has a subproject in its source tree. The child project
3168              has its own CMakeLists.txt, which is included  from  the  parent
3169              CMakeLists.txt  using add_subdirectory(). Now, if the parent and
3170              the child project provide the same option (for  example  a  com‐
3171              piler  option),  the  parent  gets  the  first  chance  to add a
3172              user-editable option to the cache.  Normally,  the  child  would
3173              then use the same value that the parent uses. However, it may be
3174              necessary to hard-code the value for the child project's  option
3175              while still allowing the user to edit the value used by the par‐
3176              ent project. The parent project can achieve this simply by  set‐
3177              ting  a  normal  variable  with the same name as the option in a
3178              scope sufficient to hide the option's cache  variable  from  the
3179              child completely. The parent has already set the cache variable,
3180              so the child's set(...CACHE...) will do nothing, and  evaluating
3181              the option variable will use the value from the normal variable,
3182              which hides the cache variable.
3183
3184
3185       set_directory_properties
3186              Set a property of the directory.
3187
3188                set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
3189
3190              Set a property for the current directory and subdirectories.  If
3191              the property is not found, CMake will report an error. The prop‐
3192              erties    include:    INCLUDE_DIRECTORIES,     LINK_DIRECTORIES,
3193              INCLUDE_REGULAR_EXPRESSION,   and   ADDITIONAL_MAKE_CLEAN_FILES.
3194              ADDITIONAL_MAKE_CLEAN_FILES is a list  of  files  that  will  be
3195              cleaned as a part of "make clean" stage.
3196
3197
3198       set_property
3199              Set a named property in a given scope.
3200
3201                set_property(<GLOBAL                            |
3202                              DIRECTORY [dir]                   |
3203                              TARGET    [target1 [target2 ...]] |
3204                              SOURCE    [src1 [src2 ...]]       |
3205                              TEST      [test1 [test2 ...]]     |
3206                              CACHE     [entry1 [entry2 ...]]>
3207                             [APPEND] [APPEND_STRING]
3208                             PROPERTY <name> [value1 [value2 ...]])
3209
3210              Set  one property on zero or more objects of a scope.  The first
3211              argument determines the scope in which the property is set.   It
3212              must be one of the following:
3213
3214
3215              GLOBAL scope is unique and does not accept a name.
3216
3217
3218              DIRECTORY  scope  defaults  to the current directory but another
3219              directory (already processed by CMake) may be named by  full  or
3220              relative path.
3221
3222
3223              TARGET scope may name zero or more existing targets.
3224
3225
3226              SOURCE  scope  may  name  zero  or more source files.  Note that
3227              source file properties are visible only to targets added in  the
3228              same directory (CMakeLists.txt).
3229
3230
3231              TEST scope may name zero or more existing tests.
3232
3233
3234              CACHE scope must name zero or more cache existing entries.
3235
3236
3237              The required PROPERTY option is immediately followed by the name
3238              of the property to set.  Remaining arguments are used to compose
3239              the  property  value  in the form of a semicolon-separated list.
3240              If the APPEND option is given the list is appended to any exist‐
3241              ing  property  value.If  the  APPEND_STRING  option is given the
3242              string is append to any existing property value as string,  i.e.
3243              it results in a longer string and not a list of strings.
3244
3245
3246       site_name
3247              Set the given variable to the name of the computer.
3248
3249                site_name(variable)
3250
3251
3252       string String operations.
3253
3254                string(REGEX MATCH <regular_expression>
3255                       <output variable> <input> [<input>...])
3256                string(REGEX MATCHALL <regular_expression>
3257                       <output variable> <input> [<input>...])
3258                string(REGEX REPLACE <regular_expression>
3259                       <replace_expression> <output variable>
3260                       <input> [<input>...])
3261                string(REPLACE <match_string>
3262                       <replace_string> <output variable>
3263                       <input> [<input>...])
3264                string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
3265                       <output variable> <input>)
3266                string(COMPARE EQUAL <string1> <string2> <output variable>)
3267                string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
3268                string(COMPARE LESS <string1> <string2> <output variable>)
3269                string(COMPARE GREATER <string1> <string2> <output variable>)
3270                string(ASCII <number> [<number> ...] <output variable>)
3271                string(CONFIGURE <string1> <output variable>
3272                       [@ONLY] [ESCAPE_QUOTES])
3273                string(TOUPPER <string1> <output variable>)
3274                string(TOLOWER <string1> <output variable>)
3275                string(LENGTH <string> <output variable>)
3276                string(SUBSTRING <string> <begin> <length> <output variable>)
3277                string(STRIP <string> <output variable>)
3278                string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
3279                       [RANDOM_SEED <seed>] <output variable>)
3280                string(FIND <string> <substring> <output variable> [REVERSE])
3281                string(TIMESTAMP <output variable> [<format string>] [UTC])
3282                string(MAKE_C_IDENTIFIER <input string> <output variable>)
3283
3284              REGEX MATCH will match the regular expression once and store the
3285              match in the output variable.
3286
3287
3288              REGEX MATCHALL will match the regular expression as  many  times
3289              as  possible  and  store the matches in the output variable as a
3290              list.
3291
3292
3293              REGEX REPLACE will match the regular expression as many times as
3294              possible and substitute the replacement expression for the match
3295              in the output.  The replace expression may refer to paren-delim‐
3296              ited  subexpressions  of  the match using \1, \2, ..., \9.  Note
3297              that two backslashes (\\1) are required in CMake code to  get  a
3298              backslash through argument parsing.
3299
3300
3301              REPLACE  will  replace  all  occurrences  of match_string in the
3302              input with replace_string and store the result in the output.
3303
3304
3305              MD5, SHA1, SHA224, SHA256, SHA384, and  SHA512  will  compute  a
3306              cryptographic hash of the input string.
3307
3308
3309              COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
3310              store true or false in the output variable.
3311
3312
3313              ASCII will convert all numbers into corresponding ASCII  charac‐
3314              ters.
3315
3316
3317              CONFIGURE will transform a string like CONFIGURE_FILE transforms
3318              a file.
3319
3320
3321              TOUPPER/TOLOWER will convert string to upper/lower characters.
3322
3323
3324              LENGTH will return a given string's length.
3325
3326
3327              SUBSTRING will return a substring of a given string.  If  length
3328              is  -1  the  remainder  of  the string starting at begin will be
3329              returned.
3330
3331
3332              STRIP will return a substring of a given string with leading and
3333              trailing spaces removed.
3334
3335
3336              RANDOM will return a random string of given length consisting of
3337              characters from the given alphabet. Default length is 5  charac‐
3338              ters  and  default  alphabet  is all numbers and upper and lower
3339              case letters.  If an integer RANDOM_SEED  is  given,  its  value
3340              will be used to seed the random number generator.
3341
3342
3343              FIND  will  return  the  position  where the given substring was
3344              found in the supplied string. If the REVERSE flag was used,  the
3345              command  will  search for the position of the last occurrence of
3346              the specified substring.
3347
3348
3349              The following characters have special meaning in regular expres‐
3350              sions:
3351
3352
3353                 ^         Matches at beginning of input
3354                 $         Matches at end of input
3355                 .         Matches any single character
3356                 [ ]       Matches any character(s) inside the brackets
3357                 [^ ]      Matches any character(s) not inside the brackets
3358                  -        Inside brackets, specifies an inclusive range between
3359                           characters on either side e.g. [a-f] is [abcdef]
3360                           To match a literal - using brackets, make it the first
3361                           or the last character e.g. [+*/-] matches basic
3362                           mathematical operators.
3363                 *         Matches preceding pattern zero or more times
3364                 +         Matches preceding pattern one or more times
3365                 ?         Matches preceding pattern zero or once only
3366                 |         Matches a pattern on either side of the |
3367                 ()        Saves a matched subexpression, which can be referenced
3368                           in the REGEX REPLACE operation. Additionally it is saved
3369                           by all regular expression-related commands, including
3370                           e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
3371
3372              *,  +  and  ?  have  higher precedence than concatenation. | has
3373              lower precedence than concatenation. This means that the regular
3374              expression "^ab+d$" matches "abbd" but not "ababd", and the reg‐
3375              ular expression "^(ab|cd)$" matches "ab" but not "abd".
3376
3377
3378              TIMESTAMP will write a string representation of the current date
3379              and/or time to the output variable.
3380
3381
3382              Should  the  command  be unable to obtain a timestamp the output
3383              variable will be set to the empty string "".
3384
3385
3386              The optional UTC flag requests the current date/time representa‐
3387              tion to be in Coordinated Universal Time (UTC) rather than local
3388              time.
3389
3390
3391              The optional <format string> may contain  the  following  format
3392              specifiers:
3393
3394
3395                 %d        The day of the current month (01-31).
3396                 %H        The hour on a 24-hour clock (00-23).
3397                 %I        The hour on a 12-hour clock (01-12).
3398                 %j        The day of the current year (001-366).
3399                 %m        The month of the current year (01-12).
3400                 %M        The minute of the current hour (00-59).
3401                 %S        The second of the current minute.
3402                           60 represents a leap second. (00-60)
3403                 %U        The week number of the current year (00-53).
3404                 %w        The day of the current week. 0 is Sunday. (0-6)
3405                 %y        The last two digits of the current year (00-99)
3406                 %Y        The current year.
3407
3408              Unknown format specifiers will be ignored and copied to the out‐
3409              put as-is.
3410
3411
3412              If no explicit <format string> is given it will default to:
3413
3414
3415                 %Y-%m-%dT%H:%M:%S    for local time.
3416                 %Y-%m-%dT%H:%M:%SZ   for UTC.
3417
3418              MAKE_C_IDENTIFIER will write a string which can be  used  as  an
3419              identifier in C.
3420
3421
3422       unset  Unset a variable, cache variable, or environment variable.
3423
3424                unset(<variable> [CACHE])
3425
3426              Removes  the  specified variable causing it to become undefined.
3427              If CACHE is present then the variable is removed from the  cache
3428              instead of the current scope.
3429
3430
3431              <variable> can be an environment variable such as:
3432
3433
3434                unset(ENV{LD_LIBRARY_PATH})
3435
3436              in  which  case  the  variable  will be removed from the current
3437              environment.
3438
3439
3440       use_mangled_mesa
3441              Copy mesa headers for use in combination with system GL.
3442
3443                use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
3444
3445              The path to mesa includes, should contain gl_mangle.h.  The mesa
3446              headers  are  copied  to  the  specified output directory.  This
3447              allows mangled mesa headers to  override  other  GL  headers  by
3448              being added to the include directory path earlier.
3449
3450
3451       variable_watch
3452              Watch the CMake variable for change.
3453
3454                variable_watch(<variable name> [<command to execute>])
3455
3456              If  the  specified variable changes, the message will be printed
3457              about the variable being changed. If the command  is  specified,
3458              the  command will be executed. The command will receive the fol‐
3459              lowing arguments: COMMAND(<variable> <access>  <value>  <current
3460              list file> <stack>)
3461
3462
3463       while  Evaluate a group of commands while a condition is true
3464
3465                while(condition)
3466                  COMMAND1(ARGS ...)
3467                  COMMAND2(ARGS ...)
3468                  ...
3469                endwhile(condition)
3470
3471              All  commands  between  while  and  the  matching  endwhile  are
3472              recorded without being invoked.  Once the endwhile is evaluated,
3473              the  recorded  list of commands is invoked as long as the condi‐
3474              tion is true. The condition is evaluated using the same logic as
3475              the if command.
3476
3477
3478       write_file
3479              Deprecated. Use the file(WRITE ) command instead.
3480
3481                write_file(filename "message to write"... [APPEND])
3482
3483              The  first  argument is the file name, the rest of the arguments
3484              are messages to write. If the argument APPEND is specified, then
3485              the message will be appended.
3486
3487
3488              NOTE  1:  file(WRITE ... and file(APPEND ... do exactly the same
3489              as this one but add some more functionality.
3490
3491
3492              NOTE 2: When using write_file the produced file cannot  be  used
3493              as  an  input to CMake (CONFIGURE_FILE, source file ...) because
3494              it will lead to an infinite loop. Use configure_file if you want
3495              to generate input files to CMake.
3496
3497

PROPERTIES

3499         CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
3500
3501
3502       This  is the documentation for the properties supported by CMake. Prop‐
3503       erties can have different scopes. They can  either  be  assigned  to  a
3504       source  file,  a directory, a target or globally to CMake. By modifying
3505       the values of properties the behaviour of the build system can be  cus‐
3506       tomized.
3507
3508

COMPATIBILITY COMMANDS

3510         CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.
3511
3512
3513       This  is the documentation for now obsolete listfile commands from pre‐
3514       vious CMake versions, which are still supported for compatibility  rea‐
3515       sons.  You  should  instead  use the newer, faster and shinier new com‐
3516       mands. ;-)
3517
3518

MODULES

3521       Copyright 2000-2012 Kitware, Inc., Insight  Software  Consortium.   All
3522       rights reserved.
3523
3524
3525       Redistribution and use in source and binary forms, with or without mod‐
3526       ification, are permitted provided that  the  following  conditions  are
3527       met:
3528
3529
3530       Redistributions  of source code must retain the above copyright notice,
3531       this list of conditions and the following disclaimer.
3532
3533
3534       Redistributions in binary  form  must  reproduce  the  above  copyright
3535       notice,  this  list  of  conditions and the following disclaimer in the
3536       documentation and/or other materials provided with the distribution.
3537
3538
3539       Neither the names of Kitware, Inc., the  Insight  Software  Consortium,
3540       nor  the  names of their contributors may be used to endorse or promote
3541       products derived from this software without specific prior written per‐
3542       mission.
3543
3544
3545       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
3546       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT  NOT  LIMITED
3547       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
3548       ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER  OR
3549       CONTRIBUTORS  BE  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
3550       EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,  BUT  NOT  LIMITED  TO,
3551       PROCUREMENT  OF  SUBSTITUTE  GOODS  OR  SERVICES; LOSS OF USE, DATA, OR
3552       PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY  OF
3553       LIABILITY,  WHETHER  IN  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
3554       NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT  OF  THE  USE  OF  THIS
3555       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3556
3557

SEE ALSO

3559       cmake(1), ccmake(1)
3560
3561
3562       The following resources are available to get help using CMake:
3563
3564
3565       Home Page
3566              http://www.cmake.org
3567
3568              The primary starting point for learning about CMake.
3569
3570
3571       Frequently Asked Questions
3572              http://www.cmake.org/Wiki/CMake_FAQ
3573
3574              A  Wiki is provided containing answers to frequently asked ques‐
3575              tions.
3576
3577
3578       Online Documentation
3579              http://www.cmake.org/HTML/Documentation.html
3580
3581              Links to available documentation may be found on this web page.
3582
3583
3584       Mailing List
3585              http://www.cmake.org/HTML/MailingLists.html
3586
3587              For help and discussion about using cmake,  a  mailing  list  is
3588              provided  at  cmake@cmake.org.  The list is member-post-only but
3589              one may sign up on the CMake web page.  Please  first  read  the
3590              full  documentation at http://www.cmake.org before posting ques‐
3591              tions to the list.
3592
3593

AUTHOR

3595       This manual page was generated by the "--help-man" option.
3596
3597
3598
3599
3600ctest 2.8.12.2                 October 15, 2014                       ctest(1)
Impressum