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

NAME

6         cpack - Packaging driver provided by CMake.
7
8

USAGE

10         cpack -G <generator> [options]
11
12

DESCRIPTION

14       The "cpack" executable is the CMake packaging program.  CMake-generated
15       build trees created for projects that use the INSTALL_*  commands  have
16       packaging support.  This program will generate the package.
17
18
19       CMake  is  a  cross-platform  build system generator.  Projects specify
20       their build process with platform-independent CMake listfiles  included
21       in  each directory of a source tree with the name CMakeLists.txt. Users
22       build a project by using CMake to generate a build system for a  native
23       tool on their platform.
24
25

OPTIONS

27       -G <generator>
28              Use the specified generator to generate package.
29
30              CPack  may  support multiple native packaging systems on certain
31              platforms. A generator is responsible for generating input files
32              for particular system and invoking that systems. Possible gener‐
33              ator names are specified in the Generators section.
34
35
36       -C <Configuration>
37              Specify the project configuration
38
39              This option specifies the configuration  that  the  project  was
40              build with, for example 'Debug', 'Release'.
41
42
43       -D <var>=<value>
44              Set a CPack variable.
45
46              Set a variable that can be used by the generator.
47
48
49       --config <config file>
50              Specify the config file.
51
52              Specify the config file to use to create the package. By default
53              CPackConfig.cmake in the current directory will be used.
54
55
56       --verbose,-V
57              enable verbose output
58
59              Run cpack with verbose output.
60
61
62       --debug
63              enable debug output (for CPack developers)
64
65              Run cpack with debug output (for CPack developers).
66
67
68       -P <package name>
69              override/define CPACK_PACKAGE_NAME
70
71              If the package name is not  specified  on  cpack  commmand  line
72              thenCPack.cmake defines it as CMAKE_PROJECT_NAME
73
74
75       -R <package version>
76              override/define CPACK_PACKAGE_VERSION
77
78              If  version  is  not  specified  on  cpack  command  line thenC‐
79              Pack.cmake     defines      it      from      CPACK_PACKAGE_VER‐
80              SION_[MAJOR|MINOR|PATCH]look into CPack.cmake for detail
81
82
83       -B <package directory>
84              override/define CPACK_PACKAGE_DIRECTORY
85
86              The  directory  where CPack will be doing its packaging work.The
87              resulting package will be found there. Inside  this  directoryC‐
88              Pack  creates  '_CPack_Packages' sub-directory which is theCPack
89              temporary directory.
90
91
92       --vendor <vendor name>
93              override/define CPACK_PACKAGE_VENDOR
94
95              If vendor is not specified on  cpack  command  line  (or  inside
96              CMakeLists.txt) thenCPack.cmake defines it with a default value
97
98
99       --help-command cmd [file]
100              Print help for a single command and exit.
101
102              Full  documentation  specific to the given command is displayed.
103              If a file is specified, the documentation is  written  into  and
104              the  output  format is determined depending on the filename suf‐
105              fix. Supported are man page, HTML, DocBook and plain text.
106
107
108       --help-command-list [file]
109              List available commands and exit.
110
111              The list contains all commands for which help may be obtained by
112              using the --help-command argument followed by a command name. If
113              a file is specified, the documentation is written into  and  the
114              output  format  is  determined depending on the filename suffix.
115              Supported are man page, HTML, DocBook and plain text.
116
117
118       --help-commands [file]
119              Print help for all commands and exit.
120
121              Full documentation specific for  all  current  command  is  dis‐
122              played.If a file is specified, the documentation is written into
123              and the output format is determined depending  on  the  filename
124              suffix. Supported are man page, HTML, DocBook and plain text.
125
126
127       --help-variable var [file]
128              Print help for a single variable and exit.
129
130              Full  documentation  specific  to  the  given  variable  is dis‐
131              played.If a file is specified, the documentation is written into
132              and  the  output  format is determined depending on the filename
133              suffix. Supported are man page, HTML, DocBook and plain text.
134
135
136       --help-variable-list [file]
137              List documented variables and exit.
138
139              The list contains all variables for which help may  be  obtained
140              by  using  the  --help-variable  argument followed by a variable
141              name.  If a file is specified, the help is written into it.If  a
142              file  is  specified,  the  documentation is written into and the
143              output format is determined depending on  the  filename  suffix.
144              Supported are man page, HTML, DocBook and plain text.
145
146
147       --help-variables [file]
148              Print help for all variables and exit.
149
150              Full  documentation  for all variables is displayed.If a file is
151              specified, the documentation is written into and the output for‐
152              mat  is  determined  depending on the filename suffix. Supported
153              are man page, HTML, DocBook and plain text.
154
155
156       --copyright [file]
157              Print the CMake copyright and exit.
158
159              If a file is specified, the copyright is written into it.
160
161
162       --help,-help,-usage,-h,-H,/?
163              Print usage information and exit.
164
165              Usage  describes  the  basic  command  line  interface  and  its
166              options.
167
168
169       --help-full [file]
170              Print full help and exit.
171
172              Full  help  displays  most  of the documentation provided by the
173              UNIX man page.  It is provided for use  on  non-UNIX  platforms,
174              but  is  also convenient if the man page is not installed.  If a
175              file is specified, the help is written into it.
176
177
178       --help-html [file]
179              Print full help in HTML format.
180
181              This option is used by CMake authors to help produce web  pages.
182              If a file is specified, the help is written into it.
183
184
185       --help-man [file]
186              Print full help as a UNIX man page and exit.
187
188              This  option is used by the cmake build to generate the UNIX man
189              page.  If a file is specified, the help is written into it.
190
191
192       --version,-version,/V [file]
193              Show program name/version banner and exit.
194
195              If a file is specified, the version is written into it.
196
197

GENERATORS

199       DEB    Debian packages
200
201
202       NSIS   Null Soft Installer
203
204
205       NSIS64 Null Soft Installer (64-bit)
206
207
208       RPM    RPM packages
209
210
211       STGZ   Self extracting Tar GZip compression
212
213
214       TBZ2   Tar BZip2 compression
215
216
217       TGZ    Tar GZip compression
218
219
220       TZ     Tar Compress compression
221
222
223       ZIP    ZIP file format
224
225

COMMANDS

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

COMPATIBILITY COMMANDS

3146         CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.
3147
3148
3149       This is the documentation for now obsolete listfile commands from  pre‐
3150       vious  CMake versions, which are still supported for compatibility rea‐
3151       sons. You should instead use the newer, faster  and  shinier  new  com‐
3152       mands. ;-)
3153
3154

MODULES

PROPERTIES OF GLOBAL SCOPE

3157       ALLOW_DUPLICATE_CUSTOM_TARGETS
3158              Allow duplicate custom targets to be created.
3159
3160              Normally CMake requires that all targets built in a project have
3161              globally unique logical names (see  policy  CMP0002).   This  is
3162              necessary to generate meaningful project file names in Xcode and
3163              VS IDE generators.  It also allows the target names to be refer‐
3164              enced unambiguously.
3165
3166
3167              Makefile  generators  are capable of supporting duplicate custom
3168              target names.  For projects that care only about Makefile gener‐
3169              ators and do not wish to support Xcode or VS IDE generators, one
3170              may set this property to true to allow duplicate custom targets.
3171              The  property allows multiple add_custom_target command calls in
3172              different directories to specify the same target name.  However,
3173              setting this property will cause non-Makefile generators to pro‐
3174              duce an error and refuse to generate the project.
3175
3176
3177       AUTOMOC_TARGETS_FOLDER
3178              Name of FOLDER for *_automoc targets that  are  added  automati‐
3179              cally by CMake for targets for which AUTOMOC is enabled.
3180
3181              If  not set, CMake uses the FOLDER property of the parent target
3182              as a default value for this property. See also the documentation
3183              for the FOLDER target property and the AUTOMOC target property.
3184
3185
3186       DEBUG_CONFIGURATIONS
3187              Specify which configurations are for debugging.
3188
3189              The  value  must be a semi-colon separated list of configuration
3190              names.  Currently  this  property  is  used  only  by  the  tar‐
3191              get_link_libraries  command (see its documentation for details).
3192              Additional uses may be defined in the future.
3193
3194
3195              This property must be set at the top level of  the  project  and
3196              before  the  first target_link_libraries command invocation.  If
3197              any entry in the list does not match a valid  configuration  for
3198              the project the behavior is undefined.
3199
3200
3201       DISABLED_FEATURES
3202              List of features which are disabled during the CMake run.
3203
3204              List  of  features  which  are disabled during the CMake run. By
3205              default it contains the names of all  packages  which  were  not
3206              found.  This  is  determined  using  the <NAME>_FOUND variables.
3207              Packages which are searched QUIET are not listed. A project  can
3208              add  its own features to this list. This property is used by the
3209              macros in FeatureSummary.cmake.
3210
3211
3212       ENABLED_FEATURES
3213              List of features which are enabled during the CMake run.
3214
3215              List of features which are enabled  during  the  CMake  run.  By
3216              default  it contains the names of all packages which were found.
3217              This is determined using the  <NAME>_FOUND  variables.  Packages
3218              which  are  searched QUIET are not listed. A project can add its
3219              own features to this list. This property is used by  the  macros
3220              in FeatureSummary.cmake.
3221
3222
3223       ENABLED_LANGUAGES
3224              Read-only  property  that contains the list of currently enabled
3225              languages
3226
3227              Set to list of currently enabled languages.
3228
3229
3230       FIND_LIBRARY_USE_LIB64_PATHS
3231              Whether FIND_LIBRARY should automatically search lib64  directo‐
3232              ries.
3233
3234              FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the
3235              FIND_LIBRARY command should automatically search the lib64 vari‐
3236              ant  of  directories called lib in the search path when building
3237              64-bit binaries.
3238
3239
3240       FIND_LIBRARY_USE_OPENBSD_VERSIONING
3241              Whether FIND_LIBRARY should find OpenBSD-style shared libraries.
3242
3243              This property is a boolean specifying whether  the  FIND_LIBRARY
3244              command  should  find  shared  libraries with OpenBSD-style ver‐
3245              sioned extension: ".so.<major>.<minor>".  The property is set to
3246              true on OpenBSD and false on other platforms.
3247
3248
3249       GLOBAL_DEPENDS_DEBUG_MODE
3250              Enable global target dependency graph debug mode.
3251
3252              CMake  automatically analyzes the global inter-target dependency
3253              graph at the beginning of native build system generation.   This
3254              property causes it to display details of its analysis to stderr.
3255
3256
3257       GLOBAL_DEPENDS_NO_CYCLES
3258              Disallow global target dependency graph cycles.
3259
3260              CMake  automatically analyzes the global inter-target dependency
3261              graph at the beginning of native build  system  generation.   It
3262              reports  an  error if the dependency graph contains a cycle that
3263              does not consist of all STATIC library targets.   This  property
3264              tells CMake to disallow all cycles completely, even among static
3265              libraries.
3266
3267
3268       IN_TRY_COMPILE
3269              Read-only property that is true during a try-compile  configura‐
3270              tion.
3271
3272              True  when  building  a  project inside a TRY_COMPILE or TRY_RUN
3273              command.
3274
3275
3276       PACKAGES_FOUND
3277              List of packages which were found during the CMake run.
3278
3279              List of packages which were found during the CMake run.  Whether
3280              a  package  has  been found is determined using the <NAME>_FOUND
3281              variables.
3282
3283
3284       PACKAGES_NOT_FOUND
3285              List of packages which were not found during the CMake run.
3286
3287              List of packages which were not  found  during  the  CMake  run.
3288              Whether  a  package  has  been  found  is  determined  using the
3289              <NAME>_FOUND variables.
3290
3291
3292       PREDEFINED_TARGETS_FOLDER
3293              Name of FOLDER for  targets  that  are  added  automatically  by
3294              CMake.
3295
3296              If  not  set,  CMake  uses "CMakePredefinedTargets" as a default
3297              value for this property. Targets such as  INSTALL,  PACKAGE  and
3298              RUN_TESTS will be organized into this FOLDER. See also the docu‐
3299              mentation for the FOLDER target property.
3300
3301
3302       REPORT_UNDEFINED_PROPERTIES
3303              If set, report any undefined properties to this file.
3304
3305              If this property is set to a filename then when  CMake  runs  it
3306              will  report  any properties or variables that were accessed but
3307              not defined into the filename specified in this property.
3308
3309
3310       RULE_LAUNCH_COMPILE
3311              Specify a launcher for compile rules.
3312
3313              Makefile generators prefix  compiler  commands  with  the  given
3314              launcher  command  line.  This is intended to allow launchers to
3315              intercept build problems with  high  granularity.   Non-Makefile
3316              generators currently ignore this property.
3317
3318
3319       RULE_LAUNCH_CUSTOM
3320              Specify a launcher for custom rules.
3321
3322              Makefile  generators  prefix  custom  commands  with  the  given
3323              launcher command line.  This is intended to allow  launchers  to
3324              intercept  build  problems  with high granularity.  Non-Makefile
3325              generators currently ignore this property.
3326
3327
3328       RULE_LAUNCH_LINK
3329              Specify a launcher for link rules.
3330
3331              Makefile generators prefix link and archive  commands  with  the
3332              given  launcher command line.  This is intended to allow launch‐
3333              ers  to  intercept  build  problems   with   high   granularity.
3334              Non-Makefile generators currently ignore this property.
3335
3336
3337       RULE_MESSAGES
3338              Specify whether to report a message for each make rule.
3339
3340              This property specifies whether Makefile generators should add a
3341              progress message describing what each build rule does.   If  the
3342              property  is not set the default is ON.  Set the property to OFF
3343              to disable granular messages and report only as each target com‐
3344              pletes.   This is intended to allow scripted builds to avoid the
3345              build time cost of detailed reports.  If  a  CMAKE_RULE_MESSAGES
3346              cache entry exists its value initializes the value of this prop‐
3347              erty.  Non-Makefile generators currently ignore this property.
3348
3349
3350       TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
3351              Set if shared libraries may be named like archives.
3352
3353              On AIX shared libraries may be named "lib<name>.a".  This  prop‐
3354              erty is set to true on such platforms.
3355
3356
3357       TARGET_SUPPORTS_SHARED_LIBS
3358              Does the target platform support shared libraries.
3359
3360              TARGET_SUPPORTS_SHARED_LIBS  is a boolean specifying whether the
3361              target platform supports shared libraries. Basically all current
3362              general  general  purpose  OS  do  so, the exception are usually
3363              embedded systems with no or special OSs.
3364
3365
3366       USE_FOLDERS
3367              Use the FOLDER target property to organize targets into folders.
3368
3369              If not set, CMake treats this property as OFF by default.  CMake
3370              generators  that  are  capable of organizing into a hierarchy of
3371              folders use the values of the FOLDER  target  property  to  name
3372              those  folders. See also the documentation for the FOLDER target
3373              property.
3374
3375
3376       __CMAKE_DELETE_CACHE_CHANGE_VARS_
3377              Internal property
3378
3379              Used to detect compiler changes, Do not set.
3380
3381

PROPERTIES ON CACHE ENTRIES

3383       ADVANCED
3384              True if entry should be hidden by default in GUIs.
3385
3386              This is a boolean value indicating whether the entry is  consid‐
3387              ered   interesting   only   for   advanced  configuration.   The
3388              mark_as_advanced() command modifies this property.
3389
3390
3391       HELPSTRING
3392              Help associated with entry in GUIs.
3393
3394              This string summarizes the purpose of an entry to help users set
3395              it through a CMake GUI.
3396
3397
3398       MODIFIED
3399              Internal management property.  Do not set or get.
3400
3401              This  is  an  internal  cache entry property managed by CMake to
3402              track interactive user modification of entries.  Ignore it.
3403
3404
3405       STRINGS
3406              Enumerate possible STRING entry values for GUI selection.
3407
3408              For cache entries with type STRING, this  enumerates  a  set  of
3409              values.   CMake  GUIs may use this to provide a selection widget
3410              instead of a generic string entry field.   This  is  for  conve‐
3411              nience  only.  CMake does not enforce that the value matches one
3412              of those listed.
3413
3414
3415       TYPE   Widget type for entry in GUIs.
3416
3417              Cache entry values are always strings, but  CMake  GUIs  present
3418              widgets to help users set values.  The GUIs use this property as
3419              a hint to determine the widget type.  Valid TYPE values are:
3420
3421
3422                BOOL          = Boolean ON/OFF value.
3423                PATH          = Path to a directory.
3424                FILEPATH      = Path to a file.
3425                STRING        = Generic string value.
3426                INTERNAL      = Do not present in GUI at all.
3427                STATIC        = Value managed by CMake, do not change.
3428                UNINITIALIZED = Type not yet specified.
3429
3430              Generally the TYPE of a cache entry should be set by the command
3431              which creates it (set, option, find_library, etc.).
3432
3433
3434       VALUE  Value of a cache entry.
3435
3436              This  property  maps to the actual value of a cache entry.  Set‐
3437              ting this property always sets the value  without  checking,  so
3438              use with care.
3439
3440

PROPERTIES ON DIRECTORIES

3442       ADDITIONAL_MAKE_CLEAN_FILES
3443              Additional files to clean during the make clean stage.
3444
3445              A  list  of  files  that  will be cleaned as a part of the "make
3446              clean" stage.
3447
3448
3449       CACHE_VARIABLES
3450              List of cache variables available in the current directory.
3451
3452              This read-only property specifies the list of CMake cache  vari‐
3453              ables currently defined.  It is intended for debugging purposes.
3454
3455
3456       CLEAN_NO_CUSTOM
3457              Should the output of custom commands be left.
3458
3459              If  this  is  true  then the outputs of custom commands for this
3460              directory will not be removed during the "make clean" stage.
3461
3462
3463       COMPILE_DEFINITIONS
3464              Preprocessor definitions for compiling a directory's sources.
3465
3466              The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
3467              rated  list  of preprocessor definitions using the syntax VAR or
3468              VAR=value.  Function-style definitions are not supported.  CMake
3469              will  automatically  escape  the  value correctly for the native
3470              build system  (note  that  CMake  language  syntax  may  require
3471              escapes  to specify some values).  This property may be set on a
3472              per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
3473              FIG>  where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
3474              TIONS_DEBUG").  This property will be initialized in each direc‐
3475              tory by its value in the directory's parent.
3476
3477
3478              CMake will automatically drop some definitions that are not sup‐
3479              ported by the native build tool.  The VS6 IDE does  not  support
3480              definition values with spaces (but NMake does).
3481
3482
3483              Disclaimer: Most native build tools have poor support for escap‐
3484              ing certain values.  CMake has work-arounds for many  cases  but
3485              some  values  may  just not be possible to pass correctly.  If a
3486              value does not seem to be escaped correctly, do not  attempt  to
3487              work-around the problem by adding escape sequences to the value.
3488              Your work-around may break in a future version of CMake that has
3489              improved escape support.  Instead consider defining the macro in
3490              a (configured) header file.  Then report the limitation.   Known
3491              limitations include:
3492
3493
3494                #          - broken almost everywhere
3495                ;          - broken in VS IDE 7.0 and Borland Makefiles
3496                ,          - broken in VS IDE
3497                %          - broken in some cases in NMake
3498                & |        - broken in some cases on MinGW
3499                ^ < > \"   - broken in most Make tools on Windows
3500
3501              CMake does not reject these values outright because they do work
3502              in some cases.  Use with caution.
3503
3504
3505       COMPILE_DEFINITIONS_<CONFIG>
3506              Per-configuration preprocessor definitions in a directory.
3507
3508              This is the configuration-specific  version  of  COMPILE_DEFINI‐
3509              TIONS.   This  property will be initialized in each directory by
3510              its value in the directory's parent.
3511
3512
3513
3514       COMPILE_OPTIONS
3515              List of options to pass to the compiler.
3516
3517              This property specifies the list of directories given so far for
3518              this property.  This property exists on directories and targets.
3519
3520
3521              The target property values are used by the generators to set the
3522              options for the compiler.
3523
3524
3525              Contents of COMPILE_OPTIONS may use "generator expressions" with
3526              the syntax "$<...>".  Generator expressions are evaluated during
3527              build system generation to produce information specific to  each
3528              build configuration.  Valid expressions are:
3529
3530
3531                $<0:...>                  = empty string (ignores "...")
3532                $<1:...>                  = content of "..."
3533                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
3534                $<CONFIGURATION>          = configuration name
3535                $<BOOL:...>               = '1' if the '...' is true, else '0'
3536                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
3537                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
3538                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
3539                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
3540                $<JOIN:list,...>          = joins the list with the content of "..."
3541                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
3542                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
3543                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
3544                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
3545                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
3546                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
3547                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
3548                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
3549                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
3550                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
3551                $<C_COMPILER_VERSION>     = The version of the C compiler used.
3552                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
3553                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
3554                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
3555                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
3556                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
3557                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
3558
3559              where  "tgt"  is  the name of a target.  Target file expressions
3560              produce a full path, but _DIR and _NAME versions can produce the
3561              directory and file name components:
3562
3563
3564                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
3565                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
3566                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
3567
3568
3569
3570
3571                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
3572
3573              Note  that  tgt  is not added as a dependency of the target this
3574              expression is evaluated on.
3575
3576
3577                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
3578                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
3579
3580              Boolean expressions:
3581
3582
3583                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
3584                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
3585                $<NOT:?>                  = '0' if '?' is '1', else '1'
3586
3587              where '?' is always either '0' or '1'.
3588
3589
3590              Expressions with an implicit 'this' target:
3591
3592
3593                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
3594
3595
3596       DEFINITIONS
3597              For  CMake  2.4  compatibility  only.   Use  COMPILE_DEFINITIONS
3598              instead.
3599
3600              This read-only property specifies the list of flags given so far
3601              to the add_definitions command.  It is  intended  for  debugging
3602              purposes.  Use the COMPILE_DEFINITIONS instead.
3603
3604
3605       EXCLUDE_FROM_ALL
3606              Exclude the directory from the all target of its parent.
3607
3608              A  property  on  a  directory  that indicates if its targets are
3609              excluded from the default build target. If it is not, then  with
3610              a  Makefile for example typing make will cause the targets to be
3611              built. The same concept applies to the default  build  of  other
3612              generators.
3613
3614
3615       IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
3616              Specify  #include  line  transforms for dependencies in a direc‐
3617              tory.
3618
3619              This property specifies rules to transform  macro-like  #include
3620              lines  during  implicit  dependency scanning of C and C++ source
3621              files.  The list of rules must be semicolon-separated with  each
3622              entry  of the form "A_MACRO(%)=value-with-%" (the % must be lit‐
3623              eral).  During dependency scanning occurrences  of  A_MACRO(...)
3624              on  #include  lines will be replaced by the value given with the
3625              macro argument substituted for '%'.  For example, the entry
3626
3627
3628                MYDIR(%)=<mydir/%>
3629
3630              will convert lines of the form
3631
3632
3633                #include MYDIR(myheader.h)
3634
3635              to
3636
3637
3638                #include <mydir/myheader.h>
3639
3640              allowing the dependency to be followed.
3641
3642
3643              This property applies to sources in all targets within a  direc‐
3644              tory.   The  property  value is initialized in each directory by
3645              its value in the directory's parent.
3646
3647
3648       INCLUDE_DIRECTORIES
3649              List of preprocessor include file search directories.
3650
3651              This property specifies the list of directories given so far  to
3652              the include_directories command.  This property exists on direc‐
3653              tories and targets.  In addition to accepting  values  from  the
3654              include_directories  command,  values may be set directly on any
3655              directory or any target using the set_property command.  A  tar‐
3656              get  gets  its initial value for this property from the value of
3657              the directory property.  A directory gets its initial value from
3658              its  parent  directory if it has one.  Both directory and target
3659              property values are adjusted by calls to the include_directories
3660              command.
3661
3662
3663              The target property values are used by the generators to set the
3664              include paths for the compiler.  See also  the  include_directo‐
3665              ries command.
3666
3667
3668       INCLUDE_REGULAR_EXPRESSION
3669              Include file scanning regular expression.
3670
3671              This  read-only  property  specifies the regular expression used
3672              during dependency scanning to match include files that should be
3673              followed.  See the include_regular_expression command.
3674
3675
3676       INTERPROCEDURAL_OPTIMIZATION
3677              Enable interprocedural optimization for targets in a directory.
3678
3679              If  set  to  true, enables interprocedural optimizations if they
3680              are known to be supported by the compiler.
3681
3682
3683       INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
3684              Per-configuration interprocedural optimization for a directory.
3685
3686              This is a per-configuration version of INTERPROCEDURAL_OPTIMIZA‐
3687              TION.   If set, this property overrides the generic property for
3688              the named configuration.
3689
3690
3691       LINK_DIRECTORIES
3692              List of linker search directories.
3693
3694              This read-only property specifies the list of directories  given
3695              so  far  to  the  link_directories  command.  It is intended for
3696              debugging purposes.
3697
3698
3699       LISTFILE_STACK
3700              The current stack of listfiles being processed.
3701
3702              This property is mainly useful when trying to  debug  errors  in
3703              your  CMake  scripts.  It  returns a list of what list files are
3704              currently being processed, in order. So if one listfile does  an
3705              INCLUDE  command  then  that is effectively pushing the included
3706              listfile onto the stack.
3707
3708
3709       MACROS List of macro commands available in the current directory.
3710
3711              This read-only property specifies the list of CMake macros  cur‐
3712              rently defined.  It is intended for debugging purposes.  See the
3713              macro command.
3714
3715
3716       PARENT_DIRECTORY
3717              Source directory that added current subdirectory.
3718
3719              This read-only property  specifies  the  source  directory  that
3720              added  the  current  source  directory  as a subdirectory of the
3721              build.   In  the  top-level   directory   the   value   is   the
3722              empty-string.
3723
3724
3725       RULE_LAUNCH_COMPILE
3726              Specify a launcher for compile rules.
3727
3728              See  the  global  property  of  the same name for details.  This
3729              overrides the global property for a directory.
3730
3731
3732       RULE_LAUNCH_CUSTOM
3733              Specify a launcher for custom rules.
3734
3735              See the global property of the  same  name  for  details.   This
3736              overrides the global property for a directory.
3737
3738
3739       RULE_LAUNCH_LINK
3740              Specify a launcher for link rules.
3741
3742              See  the  global  property  of  the same name for details.  This
3743              overrides the global property for a directory.
3744
3745
3746       TEST_INCLUDE_FILE
3747              A cmake file that will be included when ctest is run.
3748
3749              If you specify TEST_INCLUDE_FILE, that file will be included and
3750              processed when ctest is run on the directory.
3751
3752
3753       VARIABLES
3754              List of variables defined in the current directory.
3755
3756              This  read-only  property  specifies the list of CMake variables
3757              currently defined.  It is intended for debugging purposes.
3758
3759
3760       VS_GLOBAL_SECTION_POST_<section>
3761              Specify a postSolution global section in Visual Studio.
3762
3763              Setting a property like this generates an entry of the following
3764              form in the solution file:
3765
3766
3767                GlobalSection(<section>) = postSolution
3768                  <contents based on property value>
3769                EndGlobalSection
3770
3771              The  property  must  be  set  to  a  semicolon-separated list of
3772              key=value pairs. Each such pair  will  be  transformed  into  an
3773              entry  in the solution global section. Whitespace around key and
3774              value is ignored. List elements which do not  contain  an  equal
3775              sign are skipped.
3776
3777
3778              This  property  only  works for Visual Studio 7 and above; it is
3779              ignored on other generators. The property only applies when  set
3780              on  a  directory  whose CMakeLists.txt contains a project() com‐
3781              mand.
3782
3783
3784              Note that CMake generates postSolution  sections  Extensibility‐
3785              Globals  and ExtensibilityAddIns by default. If you set the cor‐
3786              responding property, it will override the default  section.  For
3787              example,   setting   VS_GLOBAL_SECTION_POST_ExtensibilityGlobals
3788              will override the default contents of  the  ExtensibilityGlobals
3789              section, while keeping ExtensibilityAddIns on its default.
3790
3791
3792       VS_GLOBAL_SECTION_PRE_<section>
3793              Specify a preSolution global section in Visual Studio.
3794
3795              Setting a property like this generates an entry of the following
3796              form in the solution file:
3797
3798
3799                GlobalSection(<section>) = preSolution
3800                  <contents based on property value>
3801                EndGlobalSection
3802
3803              The property must  be  set  to  a  semicolon-separated  list  of
3804              key=value  pairs.  Each  such  pair  will be transformed into an
3805              entry in the solution global section. Whitespace around key  and
3806              value  is  ignored.  List elements which do not contain an equal
3807              sign are skipped.
3808
3809
3810              This property only works for Visual Studio 7 and  above;  it  is
3811              ignored  on other generators. The property only applies when set
3812              on a directory whose CMakeLists.txt contains  a  project()  com‐
3813              mand.
3814
3815

PROPERTIES ON SOURCE FILES

3817       ABSTRACT
3818              Is this source file an abstract class.
3819
3820              A  property  on  a source file that indicates if the source file
3821              represents a class that is abstract. This only makes  sense  for
3822              languages that have a notion of an abstract class and it is only
3823              used by some tools that wrap classes into other languages.
3824
3825
3826       COMPILE_DEFINITIONS
3827              Preprocessor definitions for compiling a source file.
3828
3829              The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
3830              rated  list  of preprocessor definitions using the syntax VAR or
3831              VAR=value.  Function-style definitions are not supported.  CMake
3832              will  automatically  escape  the  value correctly for the native
3833              build system  (note  that  CMake  language  syntax  may  require
3834              escapes  to specify some values).  This property may be set on a
3835              per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
3836              FIG>  where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
3837              TIONS_DEBUG").
3838
3839
3840              CMake will automatically drop some definitions that are not sup‐
3841              ported  by  the native build tool.  The VS6 IDE does not support
3842              definition values with spaces (but NMake does).  Xcode does  not
3843              support per-configuration definitions on source files.
3844
3845
3846              Disclaimer: Most native build tools have poor support for escap‐
3847              ing certain values.  CMake has work-arounds for many  cases  but
3848              some  values  may  just not be possible to pass correctly.  If a
3849              value does not seem to be escaped correctly, do not  attempt  to
3850              work-around the problem by adding escape sequences to the value.
3851              Your work-around may break in a future version of CMake that has
3852              improved escape support.  Instead consider defining the macro in
3853              a (configured) header file.  Then report the limitation.   Known
3854              limitations include:
3855
3856
3857                #          - broken almost everywhere
3858                ;          - broken in VS IDE 7.0 and Borland Makefiles
3859                ,          - broken in VS IDE
3860                %          - broken in some cases in NMake
3861                & |        - broken in some cases on MinGW
3862                ^ < > \"   - broken in most Make tools on Windows
3863
3864              CMake does not reject these values outright because they do work
3865              in some cases.  Use with caution.
3866
3867
3868       COMPILE_DEFINITIONS_<CONFIG>
3869              Per-configuration preprocessor definitions on a source file.
3870
3871              This is the configuration-specific  version  of  COMPILE_DEFINI‐
3872              TIONS.   Note  that  Xcode  does  not  support per-configuration
3873              source file flags so this property will be ignored by the  Xcode
3874              generator.
3875
3876
3877       COMPILE_FLAGS
3878              Additional flags to be added when compiling this source file.
3879
3880              These flags will be added to the list of compile flags when this
3881              source file builds.  Use COMPILE_DEFINITIONS to pass  additional
3882              preprocessor definitions.
3883
3884
3885       EXTERNAL_OBJECT
3886              If set to true then this is an object file.
3887
3888              If  this  property is set to true then the source file is really
3889              an object file and should not be compiled.   It  will  still  be
3890              linked into the target though.
3891
3892
3893       Fortran_FORMAT
3894              Set to FIXED or FREE to indicate the Fortran source layout.
3895
3896              This  property  tells  CMake whether a given Fortran source file
3897              uses fixed-format or free-format.  CMake will  pass  the  corre‐
3898              sponding  format  flag to the compiler.  Consider using the tar‐
3899              get-wide Fortran_FORMAT property if all source files in a target
3900              share the same format.
3901
3902
3903       GENERATED
3904              Is this source file generated as part of the build process.
3905
3906              If  a  source  file is generated by the build process CMake will
3907              handle it differently in terms of dependency checking etc.  Oth‐
3908              erwise having a non-existent source file could create problems.
3909
3910
3911       HEADER_FILE_ONLY
3912              Is this source file only a header file.
3913
3914              A property on a source file that indicates if the source file is
3915              a header file with no associated  implementation.  This  is  set
3916              automatically  based  on the file extension and is used by CMake
3917              to determine if certain dependency information  should  be  com‐
3918              puted.
3919
3920
3921       KEEP_EXTENSION
3922              Make the output file have the same extension as the source file.
3923
3924              If  this  property  is set then the file extension of the output
3925              file will be the same as that of the source file.  Normally  the
3926              output  file  extension is computed based on the language of the
3927              source file, for example .cxx will go to a .o extension.
3928
3929
3930       LABELS Specify a list of text labels associated with a source file.
3931
3932              This property has meaning only when the source file is listed in
3933              a  target whose LABELS property is also set.  No other semantics
3934              are currently specified.
3935
3936
3937       LANGUAGE
3938              What programming language is the file.
3939
3940              A property that can be set to indicate what programming language
3941              the  source file is. If it is not set the language is determined
3942              based on the file extension. Typical values are CXX C etc.  Set‐
3943              ting  this property for a file means this file will be compiled.
3944              Do not set this for headers or files that  should  not  be  com‐
3945              piled.
3946
3947
3948       LOCATION
3949              The full path to a source file.
3950
3951              A  read  only  property  on a SOURCE FILE that contains the full
3952              path to the source file.
3953
3954
3955       MACOSX_PACKAGE_LOCATION
3956              Place a source file inside a  Mac  OS  X  bundle,  CFBundle,  or
3957              framework.
3958
3959              Executable targets with the MACOSX_BUNDLE property set are built
3960              as Mac OS X application  bundles  on  Apple  platforms.   Shared
3961              library targets with the FRAMEWORK property set are built as Mac
3962              OS X frameworks on Apple platforms.  Module library targets with
3963              the  BUNDLE  property set are built as Mac OS X CFBundle bundles
3964              on Apple platforms.  Source files listed in the target with this
3965              property  set will be copied to a directory inside the bundle or
3966              framework content folder specified by the property  value.   For
3967              bundles the content folder is "<name>.app/Contents".  For frame‐
3968              works the  content  folder  is  "<name>.framework/Versions/<ver‐
3969              sion>".  For cfbundles the content folder is "<name>.bundle/Con‐
3970              tents"  (unless  the  extension  is  changed).   See  the   PUB‐
3971              LIC_HEADER,  PRIVATE_HEADER,  and RESOURCE target properties for
3972              specifying files meant for Headers, PrivateHeaders, or Resources
3973              directories.
3974
3975
3976       OBJECT_DEPENDS
3977              Additional files on which a compiled object file depends.
3978
3979              Specifies  a  semicolon-separated list of full-paths to files on
3980              which any object files compiled from this  source  file  depend.
3981              An  object  file will be recompiled if any of the named files is
3982              newer than it.
3983
3984
3985              This property need not be used to specify the  dependency  of  a
3986              source  file  on  a  generated  header  file  that  it includes.
3987              Although the property was originally introduced  for  this  pur‐
3988              pose,  it  is no longer necessary.  If the generated header file
3989              is created by a custom command in the same target as the  source
3990              file,  the  automatic dependency scanning process will recognize
3991              the dependency.  If the generated  header  file  is  created  by
3992              another  target,  an  inter-target  dependency should be created
3993              with the add_dependencies command (if one does not already exist
3994              due to linking relationships).
3995
3996
3997       OBJECT_OUTPUTS
3998              Additional outputs for a Makefile rule.
3999
4000              Additional  outputs  created by compilation of this source file.
4001              If any of these outputs is missing the  object  will  be  recom‐
4002              piled. This is supported only on Makefile generators and will be
4003              ignored on other generators.
4004
4005
4006       SYMBOLIC
4007              Is this just a name for a rule.
4008
4009              If SYMBOLIC (boolean) is set to true the build  system  will  be
4010              informed  that  the  source file is not actually created on disk
4011              but instead used as a symbolic name for a build rule.
4012
4013
4014       WRAP_EXCLUDE
4015              Exclude this source file from any code wrapping techniques.
4016
4017              Some packages can wrap source files into alternate languages  to
4018              provide  additional  functionality. For example, C++ code can be
4019              wrapped into Java or Python etc using SWIG etc. If  WRAP_EXCLUDE
4020              is  set  to  true  (1  etc) that indicates that this source file
4021              should not be wrapped.
4022
4023

PROPERTIES ON TARGETS

4025       <CONFIG>_OUTPUT_NAME
4026              Old per-configuration target file base name.
4027
4028              This is a configuration-specific version  of  OUTPUT_NAME.   Use
4029              OUTPUT_NAME_<CONFIG> instead.
4030
4031
4032       <CONFIG>_POSTFIX
4033              Postfix  to  append  to  the  target file name for configuration
4034              <CONFIG>.
4035
4036              When building with configuration  <CONFIG>  the  value  of  this
4037              property is appended to the target file name built on disk.  For
4038              non-executable targets, this  property  is  initialized  by  the
4039              value of the variable CMAKE_<CONFIG>_POSTFIX if it is set when a
4040              target is created.  This property is  ignored  on  the  Mac  for
4041              Frameworks and App Bundles.
4042
4043
4044       <LANG>_VISIBILITY_PRESET
4045              Value for symbol visibility compile flags
4046
4047              The   <LANG>_VISIBILITY_PRESET  property  determines  the  value
4048              passed in a visibility related compile option, such  as  -fvisi‐
4049              bility=  for  <LANG>.   This  property  only  has  an affect for
4050              libraries and executables with exports.  This property  is  ini‐
4051              tialized  by  the  value  of  the variable CMAKE_<LANG>_VISIBIL‐
4052              ITY_PRESET if it is set when a target is created.
4053
4054
4055       ALIASED_TARGET
4056              Name of target aliased by this target.
4057
4058              If this is an ALIAS target, this property contains the  name  of
4059              the target aliased.
4060
4061
4062       ARCHIVE_OUTPUT_DIRECTORY
4063              Output directory in which to build ARCHIVE target files.
4064
4065              This  property specifies the directory into which archive target
4066              files  should  be  built.  Multi-configuration  generators  (VS,
4067              Xcode)  append a per-configuration subdirectory to the specified
4068              directory.  There are three kinds of target files  that  may  be
4069              built:  archive,  library,  and runtime.  Executables are always
4070              treated as runtime targets. Static libraries are always  treated
4071              as  archive  targets.  Module  libraries  are  always treated as
4072              library targets. For  non-DLL  platforms  shared  libraries  are
4073              treated  as library targets. For DLL platforms the DLL part of a
4074              shared library is treated as a runtime  target  and  the  corre‐
4075              sponding  import  library  is  treated as an archive target. All
4076              Windows-based systems including Cygwin are DLL platforms.   This
4077              property  is  initialized by the value of the variable CMAKE_AR‐
4078              CHIVE_OUTPUT_DIRECTORY if it is set when a target is created.
4079
4080
4081       ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
4082              Per-configuration output directory for ARCHIVE target files.
4083
4084              This is a per-configuration version of ARCHIVE_OUTPUT_DIRECTORY,
4085              but  multi-configuration  generators (VS, Xcode) do NOT append a
4086              per-configuration subdirectory to the specified directory.  This
4087              property  is  initialized by the value of the variable CMAKE_AR‐
4088              CHIVE_OUTPUT_DIRECTORY_<CONFIG> if it is set when  a  target  is
4089              created.
4090
4091
4092       ARCHIVE_OUTPUT_NAME
4093              Output name for ARCHIVE target files.
4094
4095              This  property specifies the base name for archive target files.
4096              It overrides OUTPUT_NAME  and  OUTPUT_NAME_<CONFIG>  properties.
4097              There  are  three  kinds  of target files that may be built: ar‐
4098              chive, library, and runtime.  Executables are always treated  as
4099              runtime  targets. Static libraries are always treated as archive
4100              targets. Module libraries are always treated as library targets.
4101              For  non-DLL  platforms  shared libraries are treated as library
4102              targets. For DLL platforms the DLL part of a shared  library  is
4103              treated as a runtime target and the corresponding import library
4104              is treated as  an  archive  target.  All  Windows-based  systems
4105              including Cygwin are DLL platforms.
4106
4107
4108       ARCHIVE_OUTPUT_NAME_<CONFIG>
4109              Per-configuration output name for ARCHIVE target files.
4110
4111              This  is  the  configuration-specific  version  of  ARCHIVE_OUT‐
4112              PUT_NAME.
4113
4114
4115       AUTOMOC
4116              Should the target be processed with automoc (for Qt projects).
4117
4118              AUTOMOC is a boolean specifying whether CMake will handle the Qt
4119              moc  preprocessor  automatically, i.e. without having to use the
4120              QT4_WRAP_CPP() or QT5_WRAP_CPP() macro. Currently  Qt4  and  Qt5
4121              are  supported.   When  this property is set to TRUE, CMake will
4122              scan the source files at build time and invoke moc  accordingly.
4123              If  an  #include statement like #include "moc_foo.cpp" is found,
4124              the Q_OBJECT class declaration is expected in  the  header,  and
4125              moc  is  run  on  the header file. If an #include statement like
4126              #include "foo.moc" is found, then a Q_OBJECT is expected in  the
4127              current source file and moc is run on the file itself. Addition‐
4128              ally, all header files are parsed for Q_OBJECT  macros,  and  if
4129              found,  moc  is  also executed on those files. The resulting moc
4130              files, which are not included as  shown  above  in  any  of  the
4131              source  files  are  included  in  a generated <targetname>_auto‐
4132              moc.cpp file, which is compiled as part of the target.This prop‐
4133              erty  is  initialized by the value of the variable CMAKE_AUTOMOC
4134              if it is set when a target is created.
4135
4136
4137              Additional command line options for moc can be set via the AUTO‐
4138              MOC_MOC_OPTIONS property.
4139
4140
4141              By  setting  the CMAKE_AUTOMOC_RELAXED_MODE variable to TRUE the
4142              rules for searching the files which will be processed by moc can
4143              be  relaxed.  See  the  documentation for this variable for more
4144              details.
4145
4146
4147              The global property AUTOMOC_TARGETS_FOLDER can be used to  group
4148              the automoc targets together in an IDE, e.g. in MSVS.
4149
4150
4151       AUTOMOC_MOC_OPTIONS
4152              Additional  options  for moc when using automoc (see the AUTOMOC
4153              property)
4154
4155              This property is only used if the AUTOMOC  property  is  set  to
4156              TRUE  for this target. In this case, it holds additional command
4157              line options which will be used when moc is executed during  the
4158              build, i.e. it is equivalent to the optional OPTIONS argument of
4159              the qt4_wrap_cpp() macro.
4160
4161
4162              By default it is empty.
4163
4164
4165       BUILD_WITH_INSTALL_RPATH
4166              Should build tree targets have install tree rpaths.
4167
4168              BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
4169              the target in the build tree with the INSTALL_RPATH.  This takes
4170              precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
4171              ing  before  installation.   This property is initialized by the
4172              value of the variable CMAKE_BUILD_WITH_INSTALL_RPATH  if  it  is
4173              set when a target is created.
4174
4175
4176       BUNDLE This target is a CFBundle on the Mac.
4177
4178              If a module library target has this property set to true it will
4179              be built as a CFBundle when built on the mac. It will  have  the
4180              directory structure required for a CFBundle and will be suitable
4181              to be used for creating Browser  Plugins  or  other  application
4182              resources.
4183
4184
4185       BUNDLE_EXTENSION
4186              The file extension used to name a BUNDLE target on the Mac.
4187
4188              The  default  value  is  "bundle" - you can also use "plugin" or
4189              whatever file extension is required by the  host  app  for  your
4190              bundle.
4191
4192
4193       COMPATIBLE_INTERFACE_BOOL
4194              Properties which must be compatible with their link interface
4195
4196              The  COMPATIBLE_INTERFACE_BOOL  property  may  contain a list of
4197              propertiesfor this target which must be consistent  when  evalu‐
4198              ated as a boolean in the INTERFACE of all linked dependees.  For
4199              example, if a property "FOO" appears in the list, then for  each
4200              dependee,  the  "INTERFACE_FOO"  property  content in all of its
4201              dependencies must be consistent with each other,  and  with  the
4202              "FOO"  property  in the dependee.  Consistency in this sense has
4203              the meaning that if the property is set, then it must  have  the
4204              same  boolean  value  as  all others, and if the property is not
4205              set, then it is ignored.  Note that for each dependee,  the  set
4206              of properties from this property must not intersect with the set
4207              of properties from the COMPATIBLE_INTERFACE_STRING property.
4208
4209
4210       COMPATIBLE_INTERFACE_STRING
4211              Properties which  must  be  string-compatible  with  their  link
4212              interface
4213
4214              The  COMPATIBLE_INTERFACE_STRING  property may contain a list of
4215              properties for this target which must be the same when evaluated
4216              as a string in the INTERFACE of all linked dependees.  For exam‐
4217              ple, if a property "FOO" appears in  the  list,  then  for  each
4218              dependee,  the  "INTERFACE_FOO"  property  content in all of its
4219              dependencies must be equal with each other, and with  the  "FOO"
4220              property  in  the dependee.  If the property is not set, then it
4221              is ignored.  Note that for each dependee, the set of  properties
4222              from this property must not intersect with the set of properties
4223              from the COMPATIBLE_INTERFACE_BOOL property.
4224
4225
4226       COMPILE_DEFINITIONS
4227              Preprocessor definitions for compiling a target's sources.
4228
4229              The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
4230              rated  list  of preprocessor definitions using the syntax VAR or
4231              VAR=value.  Function-style definitions are not supported.  CMake
4232              will  automatically  escape  the  value correctly for the native
4233              build system  (note  that  CMake  language  syntax  may  require
4234              escapes  to specify some values).  This property may be set on a
4235              per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
4236              FIG>  where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
4237              TIONS_DEBUG").
4238
4239
4240              CMake will automatically drop some definitions that are not sup‐
4241              ported  by  the native build tool.  The VS6 IDE does not support
4242              definition values with spaces (but NMake does).
4243
4244
4245              Contents of COMPILE_DEFINITIONS may use "generator  expressions"
4246              with  the  syntax "$<...>".  Generator expressions are evaluated
4247              during build system generation to produce  information  specific
4248              to each build configuration.  Valid expressions are:
4249
4250
4251                $<0:...>                  = empty string (ignores "...")
4252                $<1:...>                  = content of "..."
4253                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4254                $<CONFIGURATION>          = configuration name
4255                $<BOOL:...>               = '1' if the '...' is true, else '0'
4256                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4257                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4258                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4259                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4260                $<JOIN:list,...>          = joins the list with the content of "..."
4261                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4262                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4263                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4264                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4265                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4266                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4267                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4268                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4269                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4270                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4271                $<C_COMPILER_VERSION>     = The version of the C compiler used.
4272                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4273                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
4274                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4275                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
4276                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4277                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4278
4279              where  "tgt"  is  the name of a target.  Target file expressions
4280              produce a full path, but _DIR and _NAME versions can produce the
4281              directory and file name components:
4282
4283
4284                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4285                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4286                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4287
4288
4289
4290
4291                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
4292
4293              Note  that  tgt  is not added as a dependency of the target this
4294              expression is evaluated on.
4295
4296
4297                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
4298                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4299
4300              Boolean expressions:
4301
4302
4303                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
4304                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
4305                $<NOT:?>                  = '0' if '?' is '1', else '1'
4306
4307              where '?' is always either '0' or '1'.
4308
4309
4310              Expressions with an implicit 'this' target:
4311
4312
4313                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
4314
4315              Disclaimer: Most native build tools have poor support for escap‐
4316              ing  certain  values.  CMake has work-arounds for many cases but
4317              some values may just not be possible to pass  correctly.   If  a
4318              value  does  not seem to be escaped correctly, do not attempt to
4319              work-around the problem by adding escape sequences to the value.
4320              Your work-around may break in a future version of CMake that has
4321              improved escape support.  Instead consider defining the macro in
4322              a  (configured) header file.  Then report the limitation.  Known
4323              limitations include:
4324
4325
4326                #          - broken almost everywhere
4327                ;          - broken in VS IDE 7.0 and Borland Makefiles
4328                ,          - broken in VS IDE
4329                %          - broken in some cases in NMake
4330                & |        - broken in some cases on MinGW
4331                ^ < > \"   - broken in most Make tools on Windows
4332
4333              CMake does not reject these values outright because they do work
4334              in some cases.  Use with caution.
4335
4336
4337       COMPILE_DEFINITIONS_<CONFIG>
4338              Per-configuration preprocessor definitions on a target.
4339
4340              This  is  the  configuration-specific version of COMPILE_DEFINI‐
4341              TIONS.
4342
4343
4344       COMPILE_FLAGS
4345              Additional flags to use when compiling this target's sources.
4346
4347              The COMPILE_FLAGS property sets additional compiler  flags  used
4348              to  build sources within the target.  Use COMPILE_DEFINITIONS to
4349              pass additional preprocessor definitions.
4350
4351
4352       COMPILE_OPTIONS
4353              List of options to pass to the compiler.
4354
4355              This property specifies the list of options specified so far for
4356              this property.  This property exists on directories and targets.
4357
4358
4359              The target property values are used by the generators to set the
4360              options for the compiler.
4361
4362
4363              Contents of COMPILE_OPTIONS may use "generator expressions" with
4364              the syntax "$<...>".  Generator expressions are evaluated during
4365              build system generation to produce information specific to  each
4366              build configuration.  Valid expressions are:
4367
4368
4369                $<0:...>                  = empty string (ignores "...")
4370                $<1:...>                  = content of "..."
4371                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4372                $<CONFIGURATION>          = configuration name
4373                $<BOOL:...>               = '1' if the '...' is true, else '0'
4374                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4375                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4376                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4377                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4378                $<JOIN:list,...>          = joins the list with the content of "..."
4379                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4380                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4381                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4382                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4383                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4384                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4385                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4386                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4387                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4388                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4389                $<C_COMPILER_VERSION>     = The version of the C compiler used.
4390                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4391                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
4392                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4393                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
4394                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4395                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4396
4397              where  "tgt"  is  the name of a target.  Target file expressions
4398              produce a full path, but _DIR and _NAME versions can produce the
4399              directory and file name components:
4400
4401
4402                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4403                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4404                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4405
4406
4407
4408
4409                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
4410
4411              Note  that  tgt  is not added as a dependency of the target this
4412              expression is evaluated on.
4413
4414
4415                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
4416                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4417
4418              Boolean expressions:
4419
4420
4421                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
4422                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
4423                $<NOT:?>                  = '0' if '?' is '1', else '1'
4424
4425              where '?' is always either '0' or '1'.
4426
4427
4428              Expressions with an implicit 'this' target:
4429
4430
4431                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
4432
4433
4434       DEBUG_POSTFIX
4435              See target property <CONFIG>_POSTFIX.
4436
4437              This property is  a  special  case  of  the  more-general  <CON‐
4438              FIG>_POSTFIX property for the DEBUG configuration.
4439
4440
4441       DEFINE_SYMBOL
4442              Define a symbol when compiling this target's sources.
4443
4444              DEFINE_SYMBOL  sets  the name of the preprocessor symbol defined
4445              when compiling sources in a shared library. If not set here then
4446              it  is set to target_EXPORTS by default (with some substitutions
4447              if the target is not a valid C identifier). This is  useful  for
4448              headers  to  know  whether  they  are being included from inside
4449              their library or outside to properly  setup  dllexport/dllimport
4450              decorations.
4451
4452
4453       ENABLE_EXPORTS
4454              Specify  whether an executable exports symbols for loadable mod‐
4455              ules.
4456
4457              Normally an executable does not export any symbols because it is
4458              the  final  program.  It is possible for an executable to export
4459              symbols to be used by loadable modules.  When this  property  is
4460              set to true CMake will allow other targets to "link" to the exe‐
4461              cutable with the TARGET_LINK_LIBRARIES command.   On  all  plat‐
4462              forms a target-level dependency on the executable is created for
4463              targets that link to it.  For DLL platforms  an  import  library
4464              will be created for the exported symbols and then used for link‐
4465              ing.  All Windows-based systems including Cygwin are  DLL  plat‐
4466              forms.   For  non-DLL  platforms  that require all symbols to be
4467              resolved at link time, such as Mac OS X, the module will  "link"
4468              to the executable using a flag like "-bundle_loader".  For other
4469              non-DLL platforms the link rule  is  simply  ignored  since  the
4470              dynamic  loader  will automatically bind symbols when the module
4471              is loaded.
4472
4473
4474       EXCLUDE_FROM_ALL
4475              Exclude the target from the all target.
4476
4477              A property on a target that indicates if the target is  excluded
4478              from  the  default build target. If it is not, then with a Make‐
4479              file for example typing make will cause this target to be built.
4480              The  same  concept applies to the default build of other genera‐
4481              tors. Installing a target with EXCLUDE_FROM_ALL set to true  has
4482              undefined behavior.
4483
4484
4485       EXCLUDE_FROM_DEFAULT_BUILD
4486              Exclude target from "Build Solution".
4487
4488              This  property  is  only  used by Visual Studio generators 7 and
4489              above. When set to TRUE, the target will not be built  when  you
4490              press "Build Solution".
4491
4492
4493       EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>
4494              Per-configuration  version of target exclusion from "Build Solu‐
4495              tion".
4496
4497              This    is     the     configuration-specific     version     of
4498              EXCLUDE_FROM_DEFAULT_BUILD.         If        the        generic
4499              EXCLUDE_FROM_DEFAULT_BUILD   is   also   set   on   a    target,
4500              EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes precedence in configu‐
4501              rations for which it has a value.
4502
4503
4504       EXPORT_NAME
4505              Exported name for target files.
4506
4507              This sets the name for the IMPORTED  target  generated  when  it
4508              this target is is exported.  If not set, the logical target name
4509              is used by default.
4510
4511
4512       EchoString
4513              A message to be displayed when the target is built.
4514
4515              A message to display on some generators (such as makefiles) when
4516              the target is built.
4517
4518
4519       FOLDER Set the folder name. Use to organize targets in an IDE.
4520
4521              Targets  with  no FOLDER property will appear as top level enti‐
4522              ties in IDEs like Visual Studio. Targets with  the  same  FOLDER
4523              property  value  will  appear  next to each other in a folder of
4524              that  name.  To  nest  folders,  use  FOLDER  values   such   as
4525              'GUI/Dialogs' with '/' characters separating folder levels.
4526
4527
4528       FRAMEWORK
4529              This target is a framework on the Mac.
4530
4531              If a shared library target has this property set to true it will
4532              be built as a framework when built on the mac. It will have  the
4533              directory  structure  required for a framework and will be suit‐
4534              able to be used with the -framework option
4535
4536
4537       Fortran_FORMAT
4538              Set to FIXED or FREE to indicate the Fortran source layout.
4539
4540              This property tells CMake whether the Fortran source files in  a
4541              target  use  fixed-format  or  free-format.  CMake will pass the
4542              corresponding format flag to the compiler.  Use the  source-spe‐
4543              cific Fortran_FORMAT property to change the format of a specific
4544              source file.  If the variable CMAKE_Fortran_FORMAT is set when a
4545              target is created its value is used to initialize this property.
4546
4547
4548       Fortran_MODULE_DIRECTORY
4549              Specify  output  directory  for  Fortran modules provided by the
4550              target.
4551
4552              If the target contains Fortran source files that provide modules
4553              and  the compiler supports a module output directory this speci‐
4554              fies the directory in which the modules will  be  placed.   When
4555              this property is not set the modules will be placed in the build
4556              directory corresponding to the target's  source  directory.   If
4557              the variable CMAKE_Fortran_MODULE_DIRECTORY is set when a target
4558              is created its value is used to initialize this property.
4559
4560
4561              Note that some compilers will automatically  search  the  module
4562              output  directory for modules USEd during compilation but others
4563              will not.  If your sources USE modules their  location  must  be
4564              specified by INCLUDE_DIRECTORIES regardless of this property.
4565
4566
4567       GENERATOR_FILE_NAME
4568              Generator's file for this target.
4569
4570              An  internal property used by some generators to record the name
4571              of the project or dsp file associated  with  this  target.  Note
4572              that  at  configure  time, this property is only set for targets
4573              created by include_external_msproject().
4574
4575
4576       GNUtoMS
4577              Convert GNU import library (.dll.a) to MS format (.lib).
4578
4579              When linking a shared library or executable that exports symbols
4580              using  GNU  tools  on  Windows  (MinGW/MSYS)  with Visual Studio
4581              installed convert the import library (.dll.a)  from  GNU  to  MS
4582              format  (.lib).   Both  import  libraries  will  be installed by
4583              install(TARGETS) and exported by install(EXPORT) and export() to
4584              be  linked  by  applications  with  either GNU- or MS-compatible
4585              tools.
4586
4587
4588              If the variable CMAKE_GNUtoMS is set when a  target  is  created
4589              its  value  is  used  to initialize this property.  The variable
4590              must be set prior to the first command that enables  a  language
4591              such  as  project()  or  enable_language().   CMake provides the
4592              variable as an option to the user automatically when configuring
4593              on Windows with GNU tools.
4594
4595
4596       HAS_CXX
4597              Link the target using the C++ linker tool (obsolete).
4598
4599              This  is  equivalent  to setting the LINKER_LANGUAGE property to
4600              CXX.  See that property's documentation for details.
4601
4602
4603       IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
4604              Specify #include line transforms for dependencies in a target.
4605
4606              This property specifies rules to transform  macro-like  #include
4607              lines  during  implicit  dependency scanning of C and C++ source
4608              files.  The list of rules must be semicolon-separated with  each
4609              entry  of the form "A_MACRO(%)=value-with-%" (the % must be lit‐
4610              eral).  During dependency scanning occurrences  of  A_MACRO(...)
4611              on  #include  lines will be replaced by the value given with the
4612              macro argument substituted for '%'.  For example, the entry
4613
4614
4615                MYDIR(%)=<mydir/%>
4616
4617              will convert lines of the form
4618
4619
4620                #include MYDIR(myheader.h)
4621
4622              to
4623
4624
4625                #include <mydir/myheader.h>
4626
4627              allowing the dependency to be followed.
4628
4629
4630              This property applies to sources in the target on  which  it  is
4631              set.
4632
4633
4634       IMPORTED
4635              Read-only indication of whether a target is IMPORTED.
4636
4637              The  boolean  value of this property is true for targets created
4638              with the IMPORTED option to add_executable or  add_library.   It
4639              is false for targets built within the project.
4640
4641
4642       IMPORTED_CONFIGURATIONS
4643              Configurations provided for an IMPORTED target.
4644
4645              Set  this  to  the  list of configuration names available for an
4646              IMPORTED target.  The names correspond to configurations defined
4647              in  the  project  from  which  the  target  is imported.  If the
4648              importing project uses a different  set  of  configurations  the
4649              names may be mapped using the MAP_IMPORTED_CONFIG_<CONFIG> prop‐
4650              erty.  Ignored for non-imported targets.
4651
4652
4653       IMPORTED_IMPLIB
4654              Full path to the import library for an IMPORTED target.
4655
4656              Set this to the location of the ".lib" part of  a  windows  DLL.
4657              Ignored for non-imported targets.
4658
4659
4660       IMPORTED_IMPLIB_<CONFIG>
4661              <CONFIG>-specific version of IMPORTED_IMPLIB property.
4662
4663              Configuration  names correspond to those provided by the project
4664              from which the target is imported.
4665
4666
4667       IMPORTED_LINK_DEPENDENT_LIBRARIES
4668              Dependent shared libraries of an imported shared library.
4669
4670              Shared libraries may be linked to other shared libraries as part
4671              of  their implementation.  On some platforms the linker searches
4672              for the dependent libraries of shared libraries they are includ‐
4673              ing  in  the  link.   Set this property to the list of dependent
4674              shared libraries of an imported library.   The  list  should  be
4675              disjoint  from  the  list  of  interface libraries in the INTER‐
4676              FACE_LINK_LIBRARIES property.  On platforms requiring  dependent
4677              shared  libraries  to be found at link time CMake uses this list
4678              to add appropriate files or paths  to  the  link  command  line.
4679              Ignored for non-imported targets.
4680
4681
4682       IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
4683              <CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES.
4684
4685              Configuration  names correspond to those provided by the project
4686              from which the target is imported.  If set, this  property  com‐
4687              pletely  overrides the generic property for the named configura‐
4688              tion.
4689
4690
4691       IMPORTED_LINK_INTERFACE_LANGUAGES
4692              Languages compiled into an IMPORTED static library.
4693
4694              Set this to the list of languages of source  files  compiled  to
4695              produce a STATIC IMPORTED library (such as "C" or "CXX").  CMake
4696              accounts for these languages when computing how to link a target
4697              to the imported library.  For example, when a C executable links
4698              to an imported C++ static library CMake chooses the  C++  linker
4699              to satisfy language runtime dependencies of the static library.
4700
4701
4702              This  property  is  ignored  for  targets  that  are  not STATIC
4703              libraries.  This property is ignored for non-imported targets.
4704
4705
4706       IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
4707              <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES.
4708
4709              Configuration names correspond to those provided by the  project
4710              from  which  the target is imported.  If set, this property com‐
4711              pletely overrides the generic property for the named  configura‐
4712              tion.
4713
4714
4715       IMPORTED_LINK_INTERFACE_LIBRARIES
4716              Transitive link interface of an IMPORTED target.
4717
4718              Set  this  to  the list of libraries whose interface is included
4719              when an IMPORTED library target is  linked  to  another  target.
4720              The  libraries will be included on the link line for the target.
4721              Unlike  the  LINK_INTERFACE_LIBRARIES  property,  this  property
4722              applies   to   all   imported  target  types,  including  STATIC
4723              libraries.  This property is ignored for non-imported targets.
4724
4725
4726              This property is ignored if the  target  also  has  a  non-empty
4727              INTERFACE_LINK_LIBRARIES property.
4728
4729
4730              This   property   is  deprecated.  Use  INTERFACE_LINK_LIBRARIES
4731              instead.
4732
4733
4734       IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
4735              <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES.
4736
4737              Configuration names correspond to those provided by the  project
4738              from  which  the target is imported.  If set, this property com‐
4739              pletely overrides the generic property for the named  configura‐
4740              tion.
4741
4742
4743              This  property  is  ignored  if  the target also has a non-empty
4744              INTERFACE_LINK_LIBRARIES property.
4745
4746
4747              This  property  is  deprecated.   Use   INTERFACE_LINK_LIBRARIES
4748              instead.
4749
4750
4751       IMPORTED_LINK_INTERFACE_MULTIPLICITY
4752              Repetition count for cycles of IMPORTED static libraries.
4753
4754              This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets.
4755
4756
4757       IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>
4758              <CONFIG>-specific  version of IMPORTED_LINK_INTERFACE_MULTIPLIC‐
4759              ITY.
4760
4761              If set, this property completely overrides the generic  property
4762              for the named configuration.
4763
4764
4765       IMPORTED_LOCATION
4766              Full path to the main file on disk for an IMPORTED target.
4767
4768              Set  this  to  the  location of an IMPORTED target file on disk.
4769              For executables this is the location  of  the  executable  file.
4770              For  bundles on OS X this is the location of the executable file
4771              inside Contents/MacOS under the application bundle folder.   For
4772              static libraries and modules this is the location of the library
4773              or module.  For shared libraries on non-DLL  platforms  this  is
4774              the location of the shared library.  For frameworks on OS X this
4775              is the location of the library  file  symlink  just  inside  the
4776              framework  folder.   For DLLs this is the location of the ".dll"
4777              part of the library.  For UNKNOWN libraries this is the location
4778              of the file to be linked.  Ignored for non-imported targets.
4779
4780
4781              Projects  may  skip  IMPORTED_LOCATION if the configuration-spe‐
4782              cific property IMPORTED_LOCATION_<CONFIG> is set.   To  get  the
4783              location of an imported target read one of the LOCATION or LOCA‐
4784              TION_<CONFIG> properties.
4785
4786
4787       IMPORTED_LOCATION_<CONFIG>
4788              <CONFIG>-specific version of IMPORTED_LOCATION property.
4789
4790              Configuration names correspond to those provided by the  project
4791              from which the target is imported.
4792
4793
4794       IMPORTED_NO_SONAME
4795              Specifies  that  an  IMPORTED shared library target has no "son‐
4796              ame".
4797
4798              Set this property to true for an imported  shared  library  file
4799              that  has  no  "soname"  field.  CMake may adjust generated link
4800              commands for some platforms to prevent the linker from using the
4801              path to the library in place of its missing soname.  Ignored for
4802              non-imported targets.
4803
4804
4805       IMPORTED_NO_SONAME_<CONFIG>
4806              <CONFIG>-specific version of IMPORTED_NO_SONAME property.
4807
4808              Configuration names correspond to those provided by the  project
4809              from which the target is imported.
4810
4811
4812       IMPORTED_SONAME
4813              The "soname" of an IMPORTED target of shared library type.
4814
4815              Set this to the "soname" embedded in an imported shared library.
4816              This is meaningful only on  platforms  supporting  the  feature.
4817              Ignored for non-imported targets.
4818
4819
4820       IMPORTED_SONAME_<CONFIG>
4821              <CONFIG>-specific version of IMPORTED_SONAME property.
4822
4823              Configuration  names correspond to those provided by the project
4824              from which the target is imported.
4825
4826
4827       IMPORT_PREFIX
4828              What comes before the import library name.
4829
4830              Similar to the target  property  PREFIX,  but  used  for  import
4831              libraries  (typically corresponding to a DLL) instead of regular
4832              libraries. A target property that can be  set  to  override  the
4833              prefix (such as "lib") on an import library name.
4834
4835
4836       IMPORT_SUFFIX
4837              What comes after the import library name.
4838
4839              Similar  to  the  target  property  SUFFIX,  but used for import
4840              libraries (typically corresponding to a DLL) instead of  regular
4841              libraries.  A  target  property  that can be set to override the
4842              suffix (such as ".lib") on an import library name.
4843
4844
4845       INCLUDE_DIRECTORIES
4846              List of preprocessor include file search directories.
4847
4848              This property specifies the list of directories given so far  to
4849              the  include_directories command. This property exists on direc‐
4850              tories and targets. In addition to  accepting  values  from  the
4851              include_directories  command,  values may be set directly on any
4852              directory or any target using the set_property command. A target
4853              gets  its  initial value for this property from the value of the
4854              directory property. A directory gets its initial value from  its
4855              parent  directory if it has one. Both directory and target prop‐
4856              erty values are adjusted by  calls  to  the  include_directories
4857              command.
4858
4859
4860              The target property values are used by the generators to set the
4861              include paths for the compiler.  See also  the  include_directo‐
4862              ries command.
4863
4864
4865              Contents  of INCLUDE_DIRECTORIES may use "generator expressions"
4866              with the syntax "$<...>".  Generator expressions  are  evaluated
4867              during  build  system generation to produce information specific
4868              to each build configuration.  Valid expressions are:
4869
4870
4871                $<0:...>                  = empty string (ignores "...")
4872                $<1:...>                  = content of "..."
4873                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4874                $<CONFIGURATION>          = configuration name
4875                $<BOOL:...>               = '1' if the '...' is true, else '0'
4876                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4877                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4878                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4879                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4880                $<JOIN:list,...>          = joins the list with the content of "..."
4881                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4882                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4883                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4884                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4885                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4886                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4887                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4888                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4889                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4890                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4891                $<C_COMPILER_VERSION>     = The version of the C compiler used.
4892                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4893                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
4894                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4895                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
4896                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4897                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4898
4899              where "tgt" is the name of a target.   Target  file  expressions
4900              produce a full path, but _DIR and _NAME versions can produce the
4901              directory and file name components:
4902
4903
4904                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4905                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4906                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4907
4908
4909
4910
4911                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
4912
4913              Note that tgt is not added as a dependency of  the  target  this
4914              expression is evaluated on.
4915
4916
4917                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
4918                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4919
4920              Boolean expressions:
4921
4922
4923                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
4924                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
4925                $<NOT:?>                  = '0' if '?' is '1', else '1'
4926
4927              where '?' is always either '0' or '1'.
4928
4929
4930              Expressions with an implicit 'this' target:
4931
4932
4933                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
4934
4935
4936       INSTALL_NAME_DIR
4937              Mac OSX directory name for installed targets.
4938
4939              INSTALL_NAME_DIR is a string specifying the directory portion of
4940              the "install_name" field of shared libraries on Mac OSX  to  use
4941              in the installed targets.
4942
4943
4944       INSTALL_RPATH
4945              The rpath to use for installed targets.
4946
4947              A  semicolon-separated  list  specifying  the  rpath  to  use in
4948              installed targets (for platforms that support it).   This  prop‐
4949              erty   is   initialized   by   the   value   of   the   variable
4950              CMAKE_INSTALL_RPATH if it is set when a target is created.
4951
4952
4953       INSTALL_RPATH_USE_LINK_PATH
4954              Add paths to linker search and installed rpath.
4955
4956              INSTALL_RPATH_USE_LINK_PATH is a boolean that  if  set  to  true
4957              will  append  directories  in the linker search path and outside
4958              the project to the INSTALL_RPATH.  This property is  initialized
4959              by  the  value of the variable CMAKE_INSTALL_RPATH_USE_LINK_PATH
4960              if it is set when a target is created.
4961
4962
4963       INTERFACE_COMPILE_DEFINITIONS
4964              List of public compile definitions for a library.
4965
4966              Targets may populate this property to publish the compile  defi‐
4967              nitions  required to compile against the headers for the target.
4968              Consuming targets can add entries to their  own  COMPILE_DEFINI‐
4969              TIONS   property  such  as  $<TARGET_PROPERTY:foo,INTERFACE_COM‐
4970              PILE_DEFINITIONS> to use the compile  definitions  specified  in
4971              the interface of 'foo'.
4972
4973
4974              Generator  expressions are evaluated during build system genera‐
4975              tion to produce information specific to  each  build  configura‐
4976              tion.  Valid expressions are:
4977
4978
4979                $<0:...>                  = empty string (ignores "...")
4980                $<1:...>                  = content of "..."
4981                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
4982                $<CONFIGURATION>          = configuration name
4983                $<BOOL:...>               = '1' if the '...' is true, else '0'
4984                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
4985                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
4986                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
4987                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
4988                $<JOIN:list,...>          = joins the list with the content of "..."
4989                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
4990                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4991                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4992                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
4993                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4994                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
4995                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4996                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
4997                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
4998                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
4999                $<C_COMPILER_VERSION>     = The version of the C compiler used.
5000                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5001                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
5002                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5003                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
5004                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5005                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5006
5007              where  "tgt"  is  the name of a target.  Target file expressions
5008              produce a full path, but _DIR and _NAME versions can produce the
5009              directory and file name components:
5010
5011
5012                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5013                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5014                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5015
5016
5017
5018
5019                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
5020
5021              Note  that  tgt  is not added as a dependency of the target this
5022              expression is evaluated on.
5023
5024
5025                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
5026                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5027
5028              Boolean expressions:
5029
5030
5031                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
5032                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
5033                $<NOT:?>                  = '0' if '?' is '1', else '1'
5034
5035              where '?' is always either '0' or '1'.
5036
5037
5038              Expressions with an implicit 'this' target:
5039
5040
5041                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
5042
5043
5044       INTERFACE_COMPILE_OPTIONS
5045              List of interface options to pass to the compiler.
5046
5047              Targets may  populate  this  property  to  publish  the  compile
5048              options  required to compile against the headers for the target.
5049              Consuming targets can add entries to their  own  COMPILE_OPTIONS
5050              property     such     as    $<TARGET_PROPERTY:foo,INTERFACE_COM‐
5051              PILE_OPTIONS> to use the compile options specified in the inter‐
5052              face of 'foo'.
5053
5054
5055              Generator  expressions are evaluated during build system genera‐
5056              tion to produce information specific to  each  build  configura‐
5057              tion.  Valid expressions are:
5058
5059
5060                $<0:...>                  = empty string (ignores "...")
5061                $<1:...>                  = content of "..."
5062                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
5063                $<CONFIGURATION>          = configuration name
5064                $<BOOL:...>               = '1' if the '...' is true, else '0'
5065                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
5066                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
5067                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
5068                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
5069                $<JOIN:list,...>          = joins the list with the content of "..."
5070                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
5071                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5072                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
5073                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
5074                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5075                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
5076                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5077                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
5078                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
5079                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
5080                $<C_COMPILER_VERSION>     = The version of the C compiler used.
5081                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5082                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
5083                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5084                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
5085                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5086                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5087
5088              where  "tgt"  is  the name of a target.  Target file expressions
5089              produce a full path, but _DIR and _NAME versions can produce the
5090              directory and file name components:
5091
5092
5093                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5094                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5095                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5096
5097
5098
5099
5100                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
5101
5102              Note  that  tgt  is not added as a dependency of the target this
5103              expression is evaluated on.
5104
5105
5106                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
5107                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5108
5109              Boolean expressions:
5110
5111
5112                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
5113                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
5114                $<NOT:?>                  = '0' if '?' is '1', else '1'
5115
5116              where '?' is always either '0' or '1'.
5117
5118
5119              Expressions with an implicit 'this' target:
5120
5121
5122                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
5123
5124
5125       INTERFACE_INCLUDE_DIRECTORIES
5126              List of public include directories for a library.
5127
5128              Targets may populate this property to publish the include direc‐
5129              tories  required  to compile against the headers for the target.
5130              Consuming targets can add entries to their own  INCLUDE_DIRECTO‐
5131              RIES     property     such    as    $<TARGET_PROPERTY:foo,INTER‐
5132              FACE_INCLUDE_DIRECTORIES> to use the include directories  speci‐
5133              fied in the interface of 'foo'.
5134
5135
5136              Generator  expressions are evaluated during build system genera‐
5137              tion to produce information specific to  each  build  configura‐
5138              tion.  Valid expressions are:
5139
5140
5141                $<0:...>                  = empty string (ignores "...")
5142                $<1:...>                  = content of "..."
5143                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
5144                $<CONFIGURATION>          = configuration name
5145                $<BOOL:...>               = '1' if the '...' is true, else '0'
5146                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
5147                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
5148                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
5149                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
5150                $<JOIN:list,...>          = joins the list with the content of "..."
5151                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
5152                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5153                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
5154                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
5155                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5156                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
5157                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5158                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
5159                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
5160                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
5161                $<C_COMPILER_VERSION>     = The version of the C compiler used.
5162                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5163                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
5164                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5165                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
5166                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5167                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5168
5169              where  "tgt"  is  the name of a target.  Target file expressions
5170              produce a full path, but _DIR and _NAME versions can produce the
5171              directory and file name components:
5172
5173
5174                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5175                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5176                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5177
5178
5179
5180
5181                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
5182
5183              Note  that  tgt  is not added as a dependency of the target this
5184              expression is evaluated on.
5185
5186
5187                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
5188                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5189
5190              Boolean expressions:
5191
5192
5193                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
5194                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
5195                $<NOT:?>                  = '0' if '?' is '1', else '1'
5196
5197              where '?' is always either '0' or '1'.
5198
5199
5200              Expressions with an implicit 'this' target:
5201
5202
5203                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
5204
5205
5206       INTERFACE_LINK_LIBRARIES
5207              List public interface libraries for a library.
5208
5209              This property contains the list of transitive link dependencies.
5210              When  the  target  is  linked  into another target the libraries
5211              listed (and recursively their link interface libraries) will  be
5212              provided  to the other target also.  This property is overridden
5213              by     the     LINK_INTERFACE_LIBRARIES      or      LINK_INTER‐
5214              FACE_LIBRARIES_<CONFIG>  property  if  policy  CMP0022 is OLD or
5215              unset.
5216
5217
5218
5219
5220
5221              Generator expressions are evaluated during build system  genera‐
5222              tion  to  produce  information specific to each build configura‐
5223              tion.  Valid expressions are:
5224
5225
5226                $<0:...>                  = empty string (ignores "...")
5227                $<1:...>                  = content of "..."
5228                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
5229                $<CONFIGURATION>          = configuration name
5230                $<BOOL:...>               = '1' if the '...' is true, else '0'
5231                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
5232                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
5233                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
5234                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
5235                $<JOIN:list,...>          = joins the list with the content of "..."
5236                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
5237                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5238                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
5239                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
5240                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5241                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
5242                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5243                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
5244                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
5245                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
5246                $<C_COMPILER_VERSION>     = The version of the C compiler used.
5247                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5248                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
5249                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5250                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
5251                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5252                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5253
5254              where "tgt" is the name of a target.   Target  file  expressions
5255              produce a full path, but _DIR and _NAME versions can produce the
5256              directory and file name components:
5257
5258
5259                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5260                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5261                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5262
5263
5264
5265
5266                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
5267
5268              Note that tgt is not added as a dependency of  the  target  this
5269              expression is evaluated on.
5270
5271
5272                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
5273                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5274
5275              Boolean expressions:
5276
5277
5278                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
5279                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
5280                $<NOT:?>                  = '0' if '?' is '1', else '1'
5281
5282              where '?' is always either '0' or '1'.
5283
5284
5285              Expressions with an implicit 'this' target:
5286
5287
5288                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
5289
5290
5291       INTERFACE_POSITION_INDEPENDENT_CODE
5292              Whether consumers need to create a position-independent target
5293
5294              The  INTERFACE_POSITION_INDEPENDENT_CODE  property  informs con‐
5295              sumers of this target whether they must set their POSITION_INDE‐
5296              PENDENT_CODE  property  to  ON.   If this property is set to ON,
5297              then the POSITION_INDEPENDENT_CODE  property  on  all  consumers
5298              will  be  set to ON.  Similarly, if this property is set to OFF,
5299              then the POSITION_INDEPENDENT_CODE  property  on  all  consumers
5300              will  be  set  to OFF.  If this property is undefined, then con‐
5301              sumers will determine their  POSITION_INDEPENDENT_CODE  property
5302              by  other  means.   Consumers  must ensure that the targets that
5303              they link to have a  consistent  requirement  for  their  INTER‐
5304              FACE_POSITION_INDEPENDENT_CODE property.
5305
5306
5307       INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
5308              List of public system include directories for a library.
5309
5310              Targets may populate this property to publish the include direc‐
5311              tories which contain system headers, and  therefore  should  not
5312              result  in  compiler warnings.  Consuming targets will then mark
5313              the same include directories as system headers.
5314
5315
5316              Generator expressions are evaluated during build system  genera‐
5317              tion  to  produce  information specific to each build configura‐
5318              tion.  Valid expressions are:
5319
5320
5321                $<0:...>                  = empty string (ignores "...")
5322                $<1:...>                  = content of "..."
5323                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
5324                $<CONFIGURATION>          = configuration name
5325                $<BOOL:...>               = '1' if the '...' is true, else '0'
5326                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
5327                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
5328                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
5329                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
5330                $<JOIN:list,...>          = joins the list with the content of "..."
5331                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
5332                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5333                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
5334                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
5335                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5336                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
5337                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5338                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
5339                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
5340                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
5341                $<C_COMPILER_VERSION>     = The version of the C compiler used.
5342                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5343                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
5344                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5345                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
5346                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5347                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5348
5349              where "tgt" is the name of a target.   Target  file  expressions
5350              produce a full path, but _DIR and _NAME versions can produce the
5351              directory and file name components:
5352
5353
5354                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5355                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5356                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5357
5358
5359
5360
5361                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
5362
5363              Note that tgt is not added as a dependency of  the  target  this
5364              expression is evaluated on.
5365
5366
5367                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
5368                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5369
5370              Boolean expressions:
5371
5372
5373                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
5374                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
5375                $<NOT:?>                  = '0' if '?' is '1', else '1'
5376
5377              where '?' is always either '0' or '1'.
5378
5379
5380              Expressions with an implicit 'this' target:
5381
5382
5383                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
5384
5385
5386       INTERPROCEDURAL_OPTIMIZATION
5387              Enable interprocedural optimization for a target.
5388
5389              If  set  to  true, enables interprocedural optimizations if they
5390              are known to be supported by the compiler.
5391
5392
5393       INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
5394              Per-configuration interprocedural optimization for a target.
5395
5396              This is a per-configuration version of INTERPROCEDURAL_OPTIMIZA‐
5397              TION.   If set, this property overrides the generic property for
5398              the named configuration.
5399
5400
5401       LABELS Specify a list of text labels associated with a target.
5402
5403              Target label semantics are currently unspecified.
5404
5405
5406       LIBRARY_OUTPUT_DIRECTORY
5407              Output directory in which to build LIBRARY target files.
5408
5409              This property specifies the directory into which library  target
5410              files  should  be  built.  Multi-configuration  generators  (VS,
5411              Xcode) append a per-configuration subdirectory to the  specified
5412              directory.   There  are  three kinds of target files that may be
5413              built: archive, library, and runtime.   Executables  are  always
5414              treated  as runtime targets. Static libraries are always treated
5415              as archive targets.  Module  libraries  are  always  treated  as
5416              library  targets.  For  non-DLL  platforms  shared libraries are
5417              treated as library targets. For DLL platforms the DLL part of  a
5418              shared  library  is  treated  as a runtime target and the corre‐
5419              sponding import library is treated as  an  archive  target.  All
5420              Windows-based  systems including Cygwin are DLL platforms.  This
5421              property  is  initialized  by  the   value   of   the   variable
5422              CMAKE_LIBRARY_OUTPUT_DIRECTORY  if  it  is  set when a target is
5423              created.
5424
5425
5426       LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
5427              Per-configuration output directory for LIBRARY target files.
5428
5429              This is a per-configuration version of LIBRARY_OUTPUT_DIRECTORY,
5430              but  multi-configuration  generators (VS, Xcode) do NOT append a
5431              per-configuration subdirectory to the specified directory.  This
5432              property   is   initialized   by   the  value  of  the  variable
5433              CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> if it is set when a tar‐
5434              get is created.
5435
5436
5437       LIBRARY_OUTPUT_NAME
5438              Output name for LIBRARY target files.
5439
5440              This  property specifies the base name for library target files.
5441              It overrides OUTPUT_NAME  and  OUTPUT_NAME_<CONFIG>  properties.
5442              There  are  three  kinds  of target files that may be built: ar‐
5443              chive, library, and runtime.  Executables are always treated  as
5444              runtime  targets. Static libraries are always treated as archive
5445              targets. Module libraries are always treated as library targets.
5446              For  non-DLL  platforms  shared libraries are treated as library
5447              targets. For DLL platforms the DLL part of a shared  library  is
5448              treated as a runtime target and the corresponding import library
5449              is treated as  an  archive  target.  All  Windows-based  systems
5450              including Cygwin are DLL platforms.
5451
5452
5453       LIBRARY_OUTPUT_NAME_<CONFIG>
5454              Per-configuration output name for LIBRARY target files.
5455
5456              This  is  the  configuration-specific  version  of  LIBRARY_OUT‐
5457              PUT_NAME.
5458
5459
5460       LINKER_LANGUAGE
5461              Specifies language whose compiler will invoke the linker.
5462
5463              For executables, shared libraries, and modules,  this  sets  the
5464              language  whose compiler is used to link the target (such as "C"
5465              or "CXX").  A typical value for an executable is the language of
5466              the  source  file  providing the program entry point (main).  If
5467              not set, the language with the highest linker  preference  value
5468              is  the default.  See documentation of CMAKE_<LANG>_LINKER_PREF‐
5469              ERENCE variables.
5470
5471
5472              If this property is not set by the user, it will  be  calculated
5473              at generate-time by CMake.
5474
5475
5476       LINK_DEPENDS
5477              Additional files on which a target binary depends for linking.
5478
5479              Specifies  a  semicolon-separated list of full-paths to files on
5480              which the link rule for this target depends.  The target  binary
5481              will be linked if any of the named files is newer than it.
5482
5483
5484              This  property  is  ignored  by  non-Makefile generators.  It is
5485              intended to specify dependencies on "linker scripts" for  custom
5486              Makefile link rules.
5487
5488
5489       LINK_DEPENDS_NO_SHARED
5490              Do not depend on linked shared library files.
5491
5492              Set  this  property  to true to tell CMake generators not to add
5493              file-level dependencies on the shared library  files  linked  by
5494              this  target.   Modification to the shared libraries will not be
5495              sufficient to re-link this target.  Logical target-level  depen‐
5496              dencies will not be affected so the linked shared libraries will
5497              still be brought up to date before this target is built.
5498
5499
5500              This property is  initialized  by  the  value  of  the  variable
5501              CMAKE_LINK_DEPENDS_NO_SHARED  if it is set when a target is cre‐
5502              ated.
5503
5504
5505       LINK_FLAGS
5506              Additional flags to use when linking this target.
5507
5508              The LINK_FLAGS property can be used to add extra  flags  to  the
5509              link  step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
5510              figuration <CONFIG>, for example,  DEBUG,  RELEASE,  MINSIZEREL,
5511              RELWITHDEBINFO.
5512
5513
5514       LINK_FLAGS_<CONFIG>
5515              Per-configuration linker flags for a target.
5516
5517              This is the configuration-specific version of LINK_FLAGS.
5518
5519
5520       LINK_INTERFACE_LIBRARIES
5521              List  public  interface  libraries  for a shared library or exe‐
5522              cutable.
5523
5524              By default linking to a shared library target transitively links
5525              to  targets  with  which  the library itself was linked.  For an
5526              executable with exports (see  the  ENABLE_EXPORTS  property)  no
5527              default  transitive  link  dependencies are used.  This property
5528              replaces  the  default  transitive  link  dependencies  with  an
5529              explicit  list.   When  the target is linked into another target
5530              the libraries  listed  (and  recursively  their  link  interface
5531              libraries)  will  be  provided to the other target also.  If the
5532              list is empty then  no  transitive  link  dependencies  will  be
5533              incorporated when this target is linked into another target even
5534              if the default set is non-empty.  This property  is  initialized
5535              by  the  value of the variable CMAKE_LINK_INTERFACE_LIBRARIES if
5536              it is set when a target is created.  This  property  is  ignored
5537              for STATIC libraries.
5538
5539
5540              This  property  is  overridden  by  the INTERFACE_LINK_LIBRARIES
5541              property if policy CMP0022 is NEW.
5542
5543
5544              This  property  is  deprecated.   Use   INTERFACE_LINK_LIBRARIES
5545              instead.
5546
5547
5548       LINK_INTERFACE_LIBRARIES_<CONFIG>
5549              Per-configuration  list of public interface libraries for a tar‐
5550              get.
5551
5552              This  is  the  configuration-specific  version  of   LINK_INTER‐
5553              FACE_LIBRARIES.   If set, this property completely overrides the
5554              generic property for the named configuration.
5555
5556
5557              This property  is  overridden  by  the  INTERFACE_LINK_LIBRARIES
5558              property if policy CMP0022 is NEW.
5559
5560
5561              This   property   is  deprecated.  Use  INTERFACE_LINK_LIBRARIES
5562              instead.
5563
5564
5565       LINK_INTERFACE_MULTIPLICITY
5566              Repetition count for STATIC libraries with cyclic dependencies.
5567
5568              When linking to a STATIC library target with cyclic dependencies
5569              the  linker may need to scan more than once through the archives
5570              in the strongly connected component  of  the  dependency  graph.
5571              CMake  by  default  constructs  the link line so that the linker
5572              will scan through the component at least twice.   This  property
5573              specifies  the  minimum number of scans if it is larger than the
5574              default.  CMake uses the largest value specified by  any  target
5575              in a component.
5576
5577
5578       LINK_INTERFACE_MULTIPLICITY_<CONFIG>
5579              Per-configuration   repetition   count   for  cycles  of  STATIC
5580              libraries.
5581
5582              This  is  the  configuration-specific  version  of   LINK_INTER‐
5583              FACE_MULTIPLICITY.   If  set, this property completely overrides
5584              the generic property for the named configuration.
5585
5586
5587       LINK_LIBRARIES
5588              List of direct link dependencies.
5589
5590              This property specifies the list of libraries or  targets  which
5591              will  be  used for linking. In addition to accepting values from
5592              the target_link_libraries command, values may be set directly on
5593              any target using the set_property command.
5594
5595
5596              The target property values are used by the generators to set the
5597              link  libraries  for  the   compiler.    See   also   the   tar‐
5598              get_link_libraries command.
5599
5600
5601              Contents  of LINK_LIBRARIES may use "generator expressions" with
5602              the syntax "$<...>".  Generator expressions are evaluated during
5603              build  system generation to produce information specific to each
5604              build configuration.  Valid expressions are:
5605
5606
5607                $<0:...>                  = empty string (ignores "...")
5608                $<1:...>                  = content of "..."
5609                $<CONFIG:cfg>             = '1' if config is "cfg", else '0'
5610                $<CONFIGURATION>          = configuration name
5611                $<BOOL:...>               = '1' if the '...' is true, else '0'
5612                $<STREQUAL:a,b>           = '1' if a is STREQUAL b, else '0'
5613                $<ANGLE-R>                = A literal '>'. Used to compare strings which contain a '>' for example.
5614                $<COMMA>                  = A literal ','. Used to compare strings which contain a ',' for example.
5615                $<SEMICOLON>              = A literal ';'. Used to prevent list expansion on an argument with ';'.
5616                $<JOIN:list,...>          = joins the list with the content of "..."
5617                $<TARGET_NAME:...>        = Marks ... as being the name of a target.  This is required if exporting targets to multiple dependent export sets.  The '...' must be a literal name of a target- it may not contain generator expressions.
5618                $<INSTALL_INTERFACE:...>  = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5619                $<BUILD_INTERFACE:...>    = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
5620                $<C_COMPILER_ID>          = The CMake-id of the C compiler used.
5621                $<C_COMPILER_ID:comp>     = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5622                $<CXX_COMPILER_ID>        = The CMake-id of the CXX compiler used.
5623                $<CXX_COMPILER_ID:comp>   = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5624                $<VERSION_GREATER:v1,v2>  = '1' if v1 is a version greater than v2, else '0'.
5625                $<VERSION_LESS:v1,v2>     = '1' if v1 is a version less than v2, else '0'.
5626                $<VERSION_EQUAL:v1,v2>    = '1' if v1 is the same version as v2, else '0'.
5627                $<C_COMPILER_VERSION>     = The version of the C compiler used.
5628                $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5629                $<CXX_COMPILER_VERSION>   = The version of the CXX compiler used.
5630                $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5631                $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)
5632                $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5633                $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5634
5635              where "tgt" is the name of a target.   Target  file  expressions
5636              produce a full path, but _DIR and _NAME versions can produce the
5637              directory and file name components:
5638
5639
5640                $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5641                $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5642                $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5643
5644
5645
5646
5647                $<TARGET_PROPERTY:tgt,prop>   = The value of the property prop on the target tgt.
5648
5649              Note that tgt is not added as a dependency of  the  target  this
5650              expression is evaluated on.
5651
5652
5653                $<TARGET_POLICY:pol>          = '1' if the policy was NEW when the 'head' target was created, else '0'.  If the policy was not set, the warning message for the policy will be emitted.  This generator expression only works for a subset of policies.
5654                $<INSTALL_PREFIX>         = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5655
5656              Boolean expressions:
5657
5658
5659                $<AND:?[,?]...>           = '1' if all '?' are '1', else '0'
5660                $<OR:?[,?]...>            = '0' if all '?' are '0', else '1'
5661                $<NOT:?>                  = '0' if '?' is '1', else '1'
5662
5663              where '?' is always either '0' or '1'.
5664
5665
5666              Expressions with an implicit 'this' target:
5667
5668
5669                $<TARGET_PROPERTY:prop>   = The value of the property prop on the target on which the generator expression is evaluated.
5670
5671
5672       LINK_SEARCH_END_STATIC
5673              End a link line such that static system libraries are used.
5674
5675              Some  linkers support switches such as -Bstatic and -Bdynamic to
5676              determine whether to use static or shared  libraries  for  -lXXX
5677              options.   CMake  uses  these  options  to set the link type for
5678              libraries whose full paths are not known or (in some cases)  are
5679              in implicit link directories for the platform.  By default CMake
5680              adds an option at the end of the library list (if necessary)  to
5681              set  the  linker  search  type  back to its starting type.  This
5682              property switches the  final  linker  search  type  to  -Bstatic
5683              regardless      of     how     it     started.      See     also
5684              LINK_SEARCH_START_STATIC.
5685
5686
5687       LINK_SEARCH_START_STATIC
5688              Assume the linker looks for static libraries by default.
5689
5690              Some linkers support switches such as -Bstatic and -Bdynamic  to
5691              determine  whether  to  use static or shared libraries for -lXXX
5692              options.  CMake uses these options to  set  the  link  type  for
5693              libraries  whose full paths are not known or (in some cases) are
5694              in implicit link directories for the platform.  By  default  the
5695              linker  search  type is assumed to be -Bdynamic at the beginning
5696              of the library list.  This property switches the  assumption  to
5697              -Bstatic.   It  is  intended  for use when linking an executable
5698              statically  (e.g.  with  the  GNU  -static  option).   See  also
5699              LINK_SEARCH_END_STATIC.
5700
5701
5702       LOCATION
5703              Read-only location of a target on disk.
5704
5705              For  an  imported  target,  this  read-only property returns the
5706              value of the LOCATION_<CONFIG> property for an unspecified  con‐
5707              figuration <CONFIG> provided by the target.
5708
5709
5710              For a non-imported target, this property is provided for compat‐
5711              ibility with CMake 2.4 and below.  It was meant to get the loca‐
5712              tion  of  an executable target's output file for use in add_cus‐
5713              tom_command.  The path may contain a build-system-specific  por‐
5714              tion  that is replaced at build time with the configuration get‐
5715              ting built (such as "$(ConfigurationName)" in VS). In CMake  2.6
5716              and  above  add_custom_command automatically recognizes a target
5717              name in its COMMAND and DEPENDS options and computes the  target
5718              location.   In  CMake  2.8.4 and above add_custom_command recog‐
5719              nizes generator expressions to refer to  target  locations  any‐
5720              where in the command.  Therefore this property is not needed for
5721              creating custom commands.
5722
5723
5724              Do not set properties that affect the location of a target after
5725              reading  this  property.   These  include properties whose names
5726              match  "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CON‐
5727              FIG>)?",   "(IMPLIB_)?(PREFIX|SUFFIX)",   or  "LINKER_LANGUAGE".
5728              Failure to follow this rule is  not  diagnosed  and  leaves  the
5729              location of the target undefined.
5730
5731
5732       LOCATION_<CONFIG>
5733              Read-only property providing a target location on disk.
5734
5735              A  read-only  property that indicates where a target's main file
5736              is located on disk for the configuration <CONFIG>.  The property
5737              is defined only for library and executable targets.  An imported
5738              target may provide a set of configurations different  from  that
5739              of  the  importing  project.   By  default  CMake  looks  for an
5740              exact-match but otherwise uses an arbitrary available configura‐
5741              tion.   Use  the  MAP_IMPORTED_CONFIG_<CONFIG>  property  to map
5742              imported configurations explicitly.
5743
5744
5745              Do not set properties that affect the location of a target after
5746              reading  this  property.   These  include properties whose names
5747              match  "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CON‐
5748              FIG>)?",   "(IMPLIB_)?(PREFIX|SUFFIX)",   or  "LINKER_LANGUAGE".
5749              Failure to follow this rule is  not  diagnosed  and  leaves  the
5750              location of the target undefined.
5751
5752
5753       MACOSX_BUNDLE
5754              Build an executable as an application bundle on Mac OS X.
5755
5756              When  this  property is set to true the executable when built on
5757              Mac OS X will be created as an application bundle.   This  makes
5758              it  a  GUI executable that can be launched from the Finder.  See
5759              the MACOSX_BUNDLE_INFO_PLIST  target  property  for  information
5760              about  creation  of the Info.plist file for the application bun‐
5761              dle.  This property is initialized by the value of the  variable
5762              CMAKE_MACOSX_BUNDLE if it is set when a target is created.
5763
5764
5765       MACOSX_BUNDLE_INFO_PLIST
5766              Specify a custom Info.plist template for a Mac OS X App Bundle.
5767
5768              An executable target with MACOSX_BUNDLE enabled will be built as
5769              an application bundle on Mac OS X.  By  default  its  Info.plist
5770              file  is  created by configuring a template called MacOSXBundle‐
5771              Info.plist.in located in the CMAKE_MODULE_PATH.   This  property
5772              specifies  an alternative template file name which may be a full
5773              path.
5774
5775
5776              The following target properties may be set to specify content to
5777              be configured into the file:
5778
5779
5780                MACOSX_BUNDLE_INFO_STRING
5781                MACOSX_BUNDLE_ICON_FILE
5782                MACOSX_BUNDLE_GUI_IDENTIFIER
5783                MACOSX_BUNDLE_LONG_VERSION_STRING
5784                MACOSX_BUNDLE_BUNDLE_NAME
5785                MACOSX_BUNDLE_SHORT_VERSION_STRING
5786                MACOSX_BUNDLE_BUNDLE_VERSION
5787                MACOSX_BUNDLE_COPYRIGHT
5788
5789              CMake  variables  of the same name may be set to affect all tar‐
5790              gets in a directory that do not have each specific property set.
5791              If  a  custom Info.plist is specified by this property it may of
5792              course hard-code all the settings instead of  using  the  target
5793              properties.
5794
5795
5796       MACOSX_FRAMEWORK_INFO_PLIST
5797              Specify a custom Info.plist template for a Mac OS X Framework.
5798
5799              A  library  target  with  FRAMEWORK  enabled  will be built as a
5800              framework on Mac OS X.  By default its Info.plist file  is  cre‐
5801              ated   by   configuring   a   template  called  MacOSXFramework‐
5802              Info.plist.in located in the CMAKE_MODULE_PATH.   This  property
5803              specifies  an alternative template file name which may be a full
5804              path.
5805
5806
5807              The following target properties may be set to specify content to
5808              be configured into the file:
5809
5810
5811                MACOSX_FRAMEWORK_ICON_FILE
5812                MACOSX_FRAMEWORK_IDENTIFIER
5813                MACOSX_FRAMEWORK_SHORT_VERSION_STRING
5814                MACOSX_FRAMEWORK_BUNDLE_VERSION
5815
5816              CMake  variables  of the same name may be set to affect all tar‐
5817              gets in a directory that do not have each specific property set.
5818              If  a  custom Info.plist is specified by this property it may of
5819              course hard-code all the settings instead of  using  the  target
5820              properties.
5821
5822
5823       MACOSX_RPATH
5824              Whether to use rpaths on Mac OS X.
5825
5826              When  this  property  is  set  to true, the directory portion of
5827              the"install_name" field of  shared  libraries  will  default  to
5828              "@rpath".Runtime  paths  will also be embedded in binaries using
5829              this target.This property is initialized by  the  value  of  the
5830              variable  CMAKE_MACOSX_RPATH  if it is set when a target is cre‐
5831              ated.
5832
5833
5834       MAP_IMPORTED_CONFIG_<CONFIG>
5835              Map from project configuration to IMPORTED  target's  configura‐
5836              tion.
5837
5838              Set  this  to  the  list of configurations of an imported target
5839              that may be used for the current project's  <CONFIG>  configura‐
5840              tion.  Targets imported from another project may not provide the
5841              same  set  of  configuration  names  available  in  the  current
5842              project.   Setting  this property tells CMake what imported con‐
5843              figurations are suitable for use when building the <CONFIG> con‐
5844              figuration.   The  first  configuration  in the list found to be
5845              provided by the imported target is selected.  If  this  property
5846              is  set  and  no matching configurations are available, then the
5847              imported target is considered to be not found.  This property is
5848              ignored for non-imported targets.
5849
5850
5851       NAME   Logical name for the target.
5852
5853              Read-only logical name for the target as used by CMake.
5854
5855
5856       NO_SONAME
5857              Whether to set "soname" when linking a shared library or module.
5858
5859              Enable  this  boolean  property if a generated shared library or
5860              module should not have "soname" set. Default is to set  "soname"
5861              on all shared libraries and modules as long as the platform sup‐
5862              ports it. Generally, use this property  only  for  leaf  private
5863              libraries  or  plugins. If you use it on normal shared libraries
5864              which other targets link against, on  some  platforms  a  linker
5865              will  insert  a  full  path to the library (as specified at link
5866              time) into the dynamic section of the dependent  binary.  There‐
5867              fore,  once  installed,  dynamic  loader  may eventually fail to
5868              locate the library for the binary.
5869
5870
5871       OSX_ARCHITECTURES
5872              Target specific architectures for OS X.
5873
5874              The OSX_ARCHITECTURES property sets the target binary  architec‐
5875              ture  for  targets on OS X.  This property is initialized by the
5876              value of the variable CMAKE_OSX_ARCHITECTURES if it is set  when
5877              a  target is created.  Use OSX_ARCHITECTURES_<CONFIG> to set the
5878              binary architectures on a per-configuration basis.  <CONFIG>  is
5879              an upper-case name (ex: "OSX_ARCHITECTURES_DEBUG").
5880
5881
5882       OSX_ARCHITECTURES_<CONFIG>
5883              Per-configuration OS X binary architectures for a target.
5884
5885              This   property   is   the   configuration-specific  version  of
5886              OSX_ARCHITECTURES.
5887
5888
5889       OUTPUT_NAME
5890              Output name for target files.
5891
5892              This sets the base name for output files  created  for  an  exe‐
5893              cutable  or library target.  If not set, the logical target name
5894              is used by default.
5895
5896
5897       OUTPUT_NAME_<CONFIG>
5898              Per-configuration target file base name.
5899
5900              This is the configuration-specific version of OUTPUT_NAME.
5901
5902
5903       PDB_NAME
5904              Output name for MS debug symbols .pdb file from linker.
5905
5906              Set the base name for debug symbols file  created  for  an  exe‐
5907              cutable  or shared library target.  If not set, the logical tar‐
5908              get name is used by default.
5909
5910
5911              This property is not implemented by the Visual Studio 6  genera‐
5912              tor.
5913
5914
5915       PDB_NAME_<CONFIG>
5916              Per-configuration name for MS debug symbols .pdb file.
5917
5918              This is the configuration-specific version of PDB_NAME.
5919
5920
5921              This  property is not implemented by the Visual Studio 6 genera‐
5922              tor.
5923
5924
5925       PDB_OUTPUT_DIRECTORY
5926              Output directory for MS debug symbols .pdb file from linker.
5927
5928              This property specifies the directory into which  the  MS  debug
5929              symbols will be placed by the linker.  This property is initial‐
5930              ized by the value of the variable CMAKE_PDB_OUTPUT_DIRECTORY  if
5931              it is set when a target is created.
5932
5933
5934              This  property is not implemented by the Visual Studio 6 genera‐
5935              tor.
5936
5937
5938       PDB_OUTPUT_DIRECTORY_<CONFIG>
5939              Per-configuration output directory for  MS  debug  symbols  .pdb
5940              files.
5941
5942              This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but
5943              multi-configuration generators  (VS,  Xcode)  do  NOT  append  a
5944              per-configuration  subdirectory to the specified directory. This
5945              property  is  initialized  by  the   value   of   the   variable
5946              CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG>  if  it is set when a target
5947              is created.
5948
5949
5950              This property is not implemented by the Visual Studio 6  genera‐
5951              tor.
5952
5953
5954       POSITION_INDEPENDENT_CODE
5955              Whether to create a position-independent target
5956
5957              The  POSITION_INDEPENDENT_CODE property determines whether posi‐
5958              tion independent executables or shared libraries  will  be  cre‐
5959              ated.   This  property  is true by default for SHARED and MODULE
5960              library targets and false otherwise.  This property is  initial‐
5961              ized  by  the  value  of  the  variable  CMAKE_POSITION_INDEPEN‐
5962              DENT_CODE if it is set when a target is created.
5963
5964
5965       POST_INSTALL_SCRIPT
5966              Deprecated install support.
5967
5968              The PRE_INSTALL_SCRIPT and  POST_INSTALL_SCRIPT  properties  are
5969              the  old  way  to  specify CMake scripts to run before and after
5970              installing  a  target.   They  are  used  only  when   the   old
5971              INSTALL_TARGETS  command is used to install the target.  Use the
5972              INSTALL command instead.
5973
5974
5975       PREFIX What comes before the library name.
5976
5977              A target property that can be set to override the  prefix  (such
5978              as "lib") on a library name.
5979
5980
5981       PRE_INSTALL_SCRIPT
5982              Deprecated install support.
5983
5984              The  PRE_INSTALL_SCRIPT  and  POST_INSTALL_SCRIPT properties are
5985              the old way to specify CMake scripts to  run  before  and  after
5986              installing   a   target.   They  are  used  only  when  the  old
5987              INSTALL_TARGETS command is used to install the target.  Use  the
5988              INSTALL command instead.
5989
5990
5991       PRIVATE_HEADER
5992              Specify  private header files in a FRAMEWORK shared library tar‐
5993              get.
5994
5995              Shared library targets marked with the FRAMEWORK property gener‐
5996              ate  frameworks  on  OS  X  and normal shared libraries on other
5997              platforms.  This property may be set to a list of  header  files
5998              to  be  placed in the PrivateHeaders directory inside the frame‐
5999              work folder.   On  non-Apple  platforms  these  headers  may  be
6000              installed  using  the  PRIVATE_HEADER option to the install(TAR‐
6001              GETS) command.
6002
6003
6004       PROJECT_LABEL
6005              Change the name of a target in an IDE.
6006
6007              Can be used to change the name of the target in an IDE like Vis‐
6008              ual Studio.
6009
6010
6011       PUBLIC_HEADER
6012              Specify  public  header files in a FRAMEWORK shared library tar‐
6013              get.
6014
6015              Shared library targets marked with the FRAMEWORK property gener‐
6016              ate  frameworks  on  OS  X  and normal shared libraries on other
6017              platforms.  This property may be set to a list of  header  files
6018              to  be  placed  in  the  Headers  directory inside the framework
6019              folder.  On non-Apple platforms these headers may  be  installed
6020              using the PUBLIC_HEADER option to the install(TARGETS) command.
6021
6022
6023       RESOURCE
6024              Specify resource files in a FRAMEWORK shared library target.
6025
6026              Shared library targets marked with the FRAMEWORK property gener‐
6027              ate frameworks on OS X and  normal  shared  libraries  on  other
6028              platforms.   This  property  may be set to a list of files to be
6029              placed in the Resources directory inside the  framework  folder.
6030              On  non-Apple  platforms  these files may be installed using the
6031              RESOURCE option to the install(TARGETS) command.
6032
6033
6034       RULE_LAUNCH_COMPILE
6035              Specify a launcher for compile rules.
6036
6037              See the global property of the  same  name  for  details.   This
6038              overrides the global and directory property for a target.
6039
6040
6041       RULE_LAUNCH_CUSTOM
6042              Specify a launcher for custom rules.
6043
6044              See  the  global  property  of  the same name for details.  This
6045              overrides the global and directory property for a target.
6046
6047
6048       RULE_LAUNCH_LINK
6049              Specify a launcher for link rules.
6050
6051              See the global property of the  same  name  for  details.   This
6052              overrides the global and directory property for a target.
6053
6054
6055       RUNTIME_OUTPUT_DIRECTORY
6056              Output directory in which to build RUNTIME target files.
6057
6058              This  property specifies the directory into which runtime target
6059              files  should  be  built.  Multi-configuration  generators  (VS,
6060              Xcode)  append a per-configuration subdirectory to the specified
6061              directory.  There are three kinds of target files  that  may  be
6062              built:  archive,  library,  and runtime.  Executables are always
6063              treated as runtime targets. Static libraries are always  treated
6064              as  archive  targets.  Module  libraries  are  always treated as
6065              library targets. For  non-DLL  platforms  shared  libraries  are
6066              treated  as library targets. For DLL platforms the DLL part of a
6067              shared library is treated as a runtime  target  and  the  corre‐
6068              sponding  import  library  is  treated as an archive target. All
6069              Windows-based systems including Cygwin are DLL platforms.   This
6070              property  is initialized by the value of the variable CMAKE_RUN‐
6071              TIME_OUTPUT_DIRECTORY if it is set when a target is created.
6072
6073
6074       RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
6075              Per-configuration output directory for RUNTIME target files.
6076
6077              This is a per-configuration version of RUNTIME_OUTPUT_DIRECTORY,
6078              but  multi-configuration  generators (VS, Xcode) do NOT append a
6079              per-configuration subdirectory to the specified directory.  This
6080              property  is initialized by the value of the variable CMAKE_RUN‐
6081              TIME_OUTPUT_DIRECTORY_<CONFIG> if it is set  when  a  target  is
6082              created.
6083
6084
6085       RUNTIME_OUTPUT_NAME
6086              Output name for RUNTIME target files.
6087
6088              This  property specifies the base name for runtime target files.
6089              It overrides OUTPUT_NAME  and  OUTPUT_NAME_<CONFIG>  properties.
6090              There  are  three  kinds  of target files that may be built: ar‐
6091              chive, library, and runtime.  Executables are always treated  as
6092              runtime  targets. Static libraries are always treated as archive
6093              targets. Module libraries are always treated as library targets.
6094              For  non-DLL  platforms  shared libraries are treated as library
6095              targets. For DLL platforms the DLL part of a shared  library  is
6096              treated as a runtime target and the corresponding import library
6097              is treated as  an  archive  target.  All  Windows-based  systems
6098              including Cygwin are DLL platforms.
6099
6100
6101       RUNTIME_OUTPUT_NAME_<CONFIG>
6102              Per-configuration output name for RUNTIME target files.
6103
6104              This  is  the  configuration-specific  version  of  RUNTIME_OUT‐
6105              PUT_NAME.
6106
6107
6108       SKIP_BUILD_RPATH
6109              Should rpaths be used for the build tree.
6110
6111              SKIP_BUILD_RPATH is a boolean specifying whether to  skip  auto‐
6112              matic generation of an rpath allowing the target to run from the
6113              build tree.  This property is initialized by the  value  of  the
6114              variable  CMAKE_SKIP_BUILD_RPATH  if  it is set when a target is
6115              created.
6116
6117
6118       SOURCES
6119              Source names specified for a target.
6120
6121              Read-only list of sources specified for  a  target.   The  names
6122              returned  are suitable for passing to the set_source_files_prop‐
6123              erties command.
6124
6125
6126       SOVERSION
6127              What version number is this target.
6128
6129              For shared libraries VERSION and SOVERSION can be used to  spec‐
6130              ify  the build version and API version respectively. When build‐
6131              ing or installing appropriate symlinks are created if the  plat‐
6132              form supports symlinks and the linker supports so-names. If only
6133              one of both is specified the missing is assumed to have the same
6134              version  number.  SOVERSION  is ignored if NO_SONAME property is
6135              set. For shared libraries and executables on Windows the VERSION
6136              attribute  is  parsed to extract a "major.minor" version number.
6137              These numbers are used as the image version of the binary.
6138
6139
6140       STATIC_LIBRARY_FLAGS
6141              Extra flags to use when linking static libraries.
6142
6143              Extra flags to use when linking a static library.
6144
6145
6146       STATIC_LIBRARY_FLAGS_<CONFIG>
6147              Per-configuration flags for creating a static library.
6148
6149              This    is     the     configuration-specific     version     of
6150              STATIC_LIBRARY_FLAGS.
6151
6152
6153       SUFFIX What comes after the target name.
6154
6155              A  target  property that can be set to override the suffix (such
6156              as ".so" or ".exe") on the name of a  library,  module  or  exe‐
6157              cutable.
6158
6159
6160       TYPE   The type of the target.
6161
6162              This  read-only  property  can  be  used to test the type of the
6163              given target. It will be one of STATIC_LIBRARY,  MODULE_LIBRARY,
6164              SHARED_LIBRARY, EXECUTABLE or one of the internal target types.
6165
6166
6167       VERSION
6168              What version number is this target.
6169
6170              For  shared libraries VERSION and SOVERSION can be used to spec‐
6171              ify the build version and API version respectively. When  build‐
6172              ing  or installing appropriate symlinks are created if the plat‐
6173              form supports symlinks and the linker supports so-names. If only
6174              one of both is specified the missing is assumed to have the same
6175              version number. For executables VERSION can be used  to  specify
6176              the  build version. When building or installing appropriate sym‐
6177              links are created if the platform supports symlinks. For  shared
6178              libraries  and  executables  on Windows the VERSION attribute is
6179              parsed to extract a "major.minor" version number. These  numbers
6180              are used as the image version of the binary.
6181
6182
6183       VISIBILITY_INLINES_HIDDEN
6184              Whether  to  add  a compile flag to hide symbols of inline func‐
6185              tions
6186
6187              The VISIBILITY_INLINES_HIDDEN property determines whether a flag
6188              for  hiding  symbols for inline functions. the value passed used
6189              in a visibility related compile option, such  as  -fvisibility=.
6190              This  property  only has an affect for libraries and executables
6191              with exports.  This property is initialized by the value of  the
6192              variable  CMAKE_VISIBILITY_INLINES_HIDDEN  if  it  is set when a
6193              target is created.
6194
6195
6196       VS_DOTNET_REFERENCES
6197              Visual Studio managed project .NET references
6198
6199              Adds one or more semicolon-delimited .NET references to a gener‐
6200              ated  Visual  Studio  project.  For example, "System;System.Win‐
6201              dows.Forms".
6202
6203
6204       VS_DOTNET_TARGET_FRAMEWORK_VERSION
6205              Specify the .NET target framework version.
6206
6207              Used to specify the .NET target framework version  for  C++/CLI.
6208              For example, "v4.5".
6209
6210
6211       VS_GLOBAL_<variable>
6212              Visual Studio project-specific global variable.
6213
6214              Tell  the  Visual  Studio  generator  to set the global variable
6215              '<variable>' to a given value in  the  generated  Visual  Studio
6216              project.  Ignored on other generators. Qt integration works bet‐
6217              ter if VS_GLOBAL_QtVersion is set to the  version  FindQt4.cmake
6218              found. For example, "4.7.3"
6219
6220
6221       VS_GLOBAL_KEYWORD
6222              Visual Studio project keyword.
6223
6224              Sets  the  "keyword"  attribute  for  a  generated Visual Studio
6225              project. Defaults to "Win32Proj". You may wish to override  this
6226              value  with "ManagedCProj", for example, in a Visual Studio man‐
6227              aged C++ unit test project.
6228
6229
6230       VS_GLOBAL_PROJECT_TYPES
6231              Visual Studio project type(s).
6232
6233              Can be set to one or more UUIDs recognized by Visual  Studio  to
6234              indicate the type of project. This value is copied verbatim into
6235              the generated project file. Example for a managed C++ unit test‐
6236              ing project:
6237
6238
6239               {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}
6240
6241              UUIDs are semicolon-delimited.
6242
6243
6244       VS_GLOBAL_ROOTNAMESPACE
6245              Visual Studio project root namespace.
6246
6247              Sets the "RootNamespace" attribute for a generated Visual Studio
6248              project.  The attribute will be generated only if this is set.
6249
6250
6251       VS_KEYWORD
6252              Visual Studio project keyword.
6253
6254              Can be set to change the visual studio keyword, for  example  Qt
6255              integration works better if this is set to Qt4VSv1.0.
6256
6257
6258       VS_SCC_AUXPATH
6259              Visual Studio Source Code Control Aux Path.
6260
6261              Can  be set to change the visual studio source code control aux‐
6262              path property.
6263
6264
6265       VS_SCC_LOCALPATH
6266              Visual Studio Source Code Control Local Path.
6267
6268              Can be set to change the visual studio source code control local
6269              path property.
6270
6271
6272       VS_SCC_PROJECTNAME
6273              Visual Studio Source Code Control Project.
6274
6275              Can  be  set  to  change  the  visual studio source code control
6276              project name property.
6277
6278
6279       VS_SCC_PROVIDER
6280              Visual Studio Source Code Control Provider.
6281
6282              Can be set to change  the  visual  studio  source  code  control
6283              provider property.
6284
6285
6286       VS_WINRT_EXTENSIONS
6287              Visual  Studio  project  C++/CX  language extensions for Windows
6288              Runtime
6289
6290              Can be set to enable C++/CX language extensions.
6291
6292
6293       VS_WINRT_REFERENCES
6294              Visual Studio project Windows Runtime Metadata references
6295
6296              Adds one or more semicolon-delimited WinRT references to a  gen‐
6297              erated   Visual   Studio  project.  For  example,  "Windows;Win‐
6298              dows.UI.Core".
6299
6300
6301       WIN32_EXECUTABLE
6302              Build an executable with a WinMain entry point on windows.
6303
6304              When this property is set to true the executable when linked  on
6305              Windows  will be created with a WinMain() entry point instead of
6306              just main().  This makes it a GUI executable instead of  a  con‐
6307              sole application.  See the CMAKE_MFC_FLAG variable documentation
6308              to configure use of MFC for WinMain executables.  This  property
6309              is  initialized  by  the  value of the variable CMAKE_WIN32_EXE‐
6310              CUTABLE if it is set when a target is created.
6311
6312
6313       XCODE_ATTRIBUTE_<an-attribute>
6314              Set Xcode target attributes directly.
6315
6316              Tell the Xcode generator to  set  '<an-attribute>'  to  a  given
6317              value  in the generated Xcode project.  Ignored on other genera‐
6318              tors.
6319
6320

PROPERTIES ON TESTS

6322       ATTACHED_FILES
6323              Attach a list of files to a dashboard submission.
6324
6325              Set this property to a list of files that will  be  encoded  and
6326              submitted to the dashboard as an addition to the test result.
6327
6328
6329       ATTACHED_FILES_ON_FAIL
6330              Attach  a  list  of  files to a dashboard submission if the test
6331              fails.
6332
6333              Same as ATTACHED_FILES, but these files will only be included if
6334              the test does not pass.
6335
6336
6337       COST   Set  this to a floating point value. Tests in a test set will be
6338              run in descending order of cost.
6339
6340              This property describes the cost of a test. You  can  explicitly
6341              set this value; tests with higher COST values will run first.
6342
6343
6344       DEPENDS
6345              Specifies  that this test should only be run after the specified
6346              list of tests.
6347
6348              Set this to a list of tests that must finish before this test is
6349              run.
6350
6351
6352       ENVIRONMENT
6353              Specify environment variables that should be defined for running
6354              a test.
6355
6356              If set to a list of environment variables and values of the form
6357              MYVAR=value  those  environment  variables will be defined while
6358              running the test. The environment is restored  to  its  previous
6359              state after the test is done.
6360
6361
6362       FAIL_REGULAR_EXPRESSION
6363              If  the  output  matches  this  regular expression the test will
6364              fail.
6365
6366              If set, if the output matches one of specified  regular  expres‐
6367              sions,  the  test will fail.For example: FAIL_REGULAR_EXPRESSION
6368              "[^a-z]Error;ERROR;Failed"
6369
6370
6371       LABELS Specify a list of text labels associated with a test.
6372
6373              The list is reported in dashboard submissions.
6374
6375
6376       MEASUREMENT
6377              Specify a CDASH measurement and value to be reported for a test.
6378
6379              If set to a name then that name will be reported to CDASH  as  a
6380              named  measurement  with  a  value  of 1. You may also specify a
6381              value by setting MEASUREMENT to "measurement=value".
6382
6383
6384       PASS_REGULAR_EXPRESSION
6385              The output must match this regular expression for  the  test  to
6386              pass.
6387
6388              If  set,  the  test output will be checked against the specified
6389              regular expressions and at least one of the regular  expressions
6390              has to match, otherwise the test will fail.
6391
6392
6393       PROCESSORS
6394              How many process slots this test requires
6395
6396              Denotes  the  number  of processors that this test will require.
6397              This is typically used for MPI tests, and should be used in con‐
6398              junction with the ctest_test PARALLEL_LEVEL option.
6399
6400
6401       REQUIRED_FILES
6402              List of files required to run the test.
6403
6404              If  set  to a list of files, the test will not be run unless all
6405              of the files exist.
6406
6407
6408       RESOURCE_LOCK
6409              Specify a list of resources that are locked by this test.
6410
6411              If multiple tests specify the same resource lock, they are guar‐
6412              anteed not to run concurrently.
6413
6414
6415       RUN_SERIAL
6416              Do not run this test in parallel with any other test.
6417
6418              Use  this  option  in  conjunction  with  the  ctest_test PARAL‐
6419              LEL_LEVEL option to specify that this test should not be run  in
6420              parallel with any other tests.
6421
6422
6423       TIMEOUT
6424              How many seconds to allow for this test.
6425
6426              This property if set will limit a test to not take more than the
6427              specified number of seconds to run. If it exceeds that the  test
6428              process  will  be  killed  and ctest will move to the next test.
6429              This setting takes precedence over CTEST_TESTING_TIMEOUT.
6430
6431
6432       WILL_FAIL
6433              If set to true, this will invert the pass/fail flag of the test.
6434
6435              This property can be used for tests that are  expected  to  fail
6436              and return a non zero return code.
6437
6438
6439       WORKING_DIRECTORY
6440              The directory from which the test executable will be called.
6441
6442              If this is not set it is called from the directory the test exe‐
6443              cutable is located in.
6444
6445

VARIABLES

6447       CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
6448              Ask CPack to error out as soon as a file with  absolute  INSTALL
6449              DESTINATION is encountered.
6450
6451              The  fatal  error  is  emitted  before  the  installation of the
6452              offending  file  takes  place.  Some  CPack   generators,   like
6453              NSIS,enforce this internally. This variable triggers the defini‐
6454              tion  ofCMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION  when  CPack
6455              runsVariables common to all CPack generators
6456
6457

VARIABLES THAT CHANGE BEHAVIOR

6459       BUILD_SHARED_LIBS
6460              Global  flag  to cause add_library to create shared libraries if
6461              on.
6462
6463              If present and true, this will cause all libraries to  be  built
6464              shared  unless  the  library  was  explicitly  added as a static
6465              library.  This variable is often added to projects as an  OPTION
6466              so  that each user of a project can decide if they want to build
6467              the project using shared or static libraries.
6468
6469
6470       CMAKE_ABSOLUTE_DESTINATION_FILES
6471              List of files which have been installed using  an ABSOLUTE  DES‐
6472              TINATION path.
6473
6474              This  variable is defined by CMake-generated cmake_install.cmake
6475              scripts. It can be used (read-only) by programs or scripts  that
6476              source those install scripts. This is used by some CPack genera‐
6477              tors (e.g. RPM).
6478
6479
6480       CMAKE_AUTOMOC_RELAXED_MODE
6481              Switch between strict and relaxed automoc mode.
6482
6483              By default, automoc behaves exactly as described in the documen‐
6484              tation  of  the  AUTOMOC  target property.  When set to TRUE, it
6485              accepts more input and tries to find the correct input file  for
6486              moc  even  if it differs from the documented behaviour.  In this
6487              mode it e.g. also checks whether a header file is intended to be
6488              processed by moc when a "foo.moc" file has been included.
6489
6490
6491              Relaxed mode has to be enabled for KDE4 compatibility.
6492
6493
6494       CMAKE_BACKWARDS_COMPATIBILITY
6495              Version of cmake required to build project
6496
6497              From  the  point of view of backwards compatibility, this speci‐
6498              fies what version of CMake should be supported. By default  this
6499              value  is  the version number of CMake that you are running. You
6500              can set this to an older version of CMake to support  deprecated
6501              commands  of  CMake  in  projects that were written to use older
6502              versions of CMake. This can be set by the user  or  set  at  the
6503              beginning of a CMakeLists file.
6504
6505
6506       CMAKE_BUILD_TYPE
6507              Specifies the build type on single-configuration generators.
6508
6509              This  statically  specifies what build type (configuration) will
6510              be built in this build tree. Possible values are  empty,  Debug,
6511              Release,  RelWithDebInfo  and MinSizeRel.  This variable is only
6512              meaningful to single-configuration generators (such as make  and
6513              Ninja) i.e. those which choose a single configuration when CMake
6514              runs to generate a build tree as opposed to  multi-configuration
6515              generators  which  offer  selection  of  the build configuration
6516              within the generated build environment.  There are many per-con‐
6517              fig   properties   and   variables   (usually   following  clean
6518              SOME_VAR_<CONFIG>     order      conventions),      such      as
6519              CMAKE_C_FLAGS_<CONFIG>,       specified       as      uppercase:
6520              CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL].     For
6521              example,  in  a build tree configured to build type Debug, CMake
6522              will see to having CMAKE_C_FLAGS_DEBUG settings get added to the
6523              CMAKE_C_FLAGS settings.  See also CMAKE_CONFIGURATION_TYPES.
6524
6525
6526       CMAKE_COLOR_MAKEFILE
6527              Enables color output when using the Makefile generator.
6528
6529              When  enabled, the generated Makefiles will produce colored out‐
6530              put.  Default is ON.
6531
6532
6533       CMAKE_CONFIGURATION_TYPES
6534              Specifies the available build types on multi-config generators.
6535
6536              This specifies what build types (configurations) will be  avail‐
6537              able  such as Debug, Release, RelWithDebInfo etc.  This has rea‐
6538              sonable defaults on most platforms, but can be extended to  pro‐
6539              vide  other  build types.  See also CMAKE_BUILD_TYPE for details
6540              of managing configuration data, and CMAKE_CFG_INTDIR.
6541
6542
6543       CMAKE_DEBUG_TARGET_PROPERTIES
6544              Enables tracing output for target properties.
6545
6546              This variable can be populated with a list of properties to gen‐
6547              erate  debug output for when evaluating target properties.  Cur‐
6548              rently it can only be used when evaluating the  INCLUDE_DIRECTO‐
6549              RIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS target properties.
6550              In that case, it outputs a backtrace for each entry in the  tar‐
6551              get property.  Default is unset.
6552
6553
6554       CMAKE_DISABLE_FIND_PACKAGE_<PackageName>
6555              Variable for disabling find_package() calls.
6556
6557              Every  non-REQUIRED find_package() call in a project can be dis‐
6558              abled by setting the variable CMAKE_DISABLE_FIND_PACKAGE_<Packa‐
6559              geName>  to TRUE. This can be used to build a project without an
6560              optional package, although that package is installed.
6561
6562
6563              This switch should be used during the initial CMake run.  Other‐
6564              wise  if  the package has already been found in a previous CMake
6565              run, the variables which have been  stored  in  the  cache  will
6566              still  be  there.   In that case it is recommended to remove the
6567              cache variables for this package from the cache using the  cache
6568              editor or cmake -U
6569
6570
6571       CMAKE_ERROR_DEPRECATED
6572              Whether to issue deprecation errors for macros and functions.
6573
6574              If TRUE, this can be used by macros and functions to issue fatal
6575              errors when deprecated macros or functions are used.  This vari‐
6576              able is FALSE by default.
6577
6578
6579       CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
6580              Ask  cmake_install.cmake  script  to error out as soon as a file
6581              with absolute INSTALL DESTINATION is encountered.
6582
6583              The fatal error  is  emitted  before  the  installation  of  the
6584              offending  file takes place. This variable is used by CMake-gen‐
6585              erated cmake_install.cmake scripts. If one sets this variable to
6586              ON  while  running  the  script, it may get fatal error messages
6587              from the script.
6588
6589
6590       CMAKE_FIND_LIBRARY_PREFIXES
6591              Prefixes to prepend when looking for libraries.
6592
6593              This specifies what prefixes to add to library  names  when  the
6594              find_library  command  looks for libraries. On UNIX systems this
6595              is typically lib, meaning that  when  trying  to  find  the  foo
6596              library it will look for libfoo.
6597
6598
6599       CMAKE_FIND_LIBRARY_SUFFIXES
6600              Suffixes to append when looking for libraries.
6601
6602              This  specifies  what  suffixes to add to library names when the
6603              find_library command looks for  libraries.  On  Windows  systems
6604              this  is  typically  .lib  and .dll, meaning that when trying to
6605              find the foo library it will look for foo.dll etc.
6606
6607
6608       CMAKE_FIND_PACKAGE_WARN_NO_MODULE
6609              Tell find_package to warn if called without an explicit mode.
6610
6611              If find_package is called without an explicit mode option  (MOD‐
6612              ULE,  CONFIG  or  NO_MODULE) and no Find<pkg>.cmake module is in
6613              CMAKE_MODULE_PATH then CMake implicitly assumes that the  caller
6614              intends to search for a package configuration file.  If no pack‐
6615              age configuration file is found then the wording of the  failure
6616              message  must  account  for  both  the  case that the package is
6617              really missing and the case that  the  project  has  a  bug  and
6618              failed  to  provide  the  intended  Find module.  If instead the
6619              caller specifies an explicit mode option then the  failure  mes‐
6620              sage can be more specific.
6621
6622
6623              Set CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE to tell find_pack‐
6624              age to warn when it implicitly assumes Config mode.  This  helps
6625              developers  enforce  use  of  an  explicit  mode in all calls to
6626              find_package within a project.
6627
6628
6629       CMAKE_IGNORE_PATH
6630              Path to be ignored by FIND_XXX() commands.
6631
6632              Specifies directories to be ignored by  searches  in  FIND_XXX()
6633              commands.   This  is useful in cross-compiled environments where
6634              some system directories contain incompatible but possibly  link‐
6635              able  libraries. For example, on cross-compiled cluster environ‐
6636              ments, this allows  a  user  to  ignore  directories  containing
6637              libraries  meant  for  the  front-end  machine that modules like
6638              FindX11 (and others) would normally search.  By default this  is
6639              empty;  it  is  intended  to  be  set by the project.  Note that
6640              CMAKE_IGNORE_PATH takes a list of directory names, NOT a list of
6641              prefixes.  If  you  want  to  ignore  paths under prefixes (bin,
6642              include, lib, etc.), you'll need  to  specify  them  explicitly.
6643              See       also       CMAKE_PREFIX_PATH,      CMAKE_LIBRARY_PATH,
6644              CMAKE_INCLUDE_PATH, CMAKE_PROGRAM_PATH.
6645
6646
6647       CMAKE_INCLUDE_PATH
6648              Path used for searching by FIND_FILE() and FIND_PATH().
6649
6650              Specifies a path which will be  used  both  by  FIND_FILE()  and
6651              FIND_PATH().  Both  commands  will  check  each of the contained
6652              directories for the existence of the  file  which  is  currently
6653              searched.  By  default  it is empty, it is intended to be set by
6654              the  project.  See  also  CMAKE_SYSTEM_INCLUDE_PATH,  CMAKE_PRE‐
6655              FIX_PATH.
6656
6657
6658       CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
6659              Default component used in install() commands.
6660
6661              If  an install() command is used without the COMPONENT argument,
6662              these files will be grouped into a default component.  The  name
6663              of  this default install component will be taken from this vari‐
6664              able.  It defaults to "Unspecified".
6665
6666
6667       CMAKE_INSTALL_PREFIX
6668              Install directory used by install.
6669
6670              If "make install" is invoked or INSTALL is built, this directory
6671              is   prepended  onto  all  install  directories.  This  variable
6672              defaults to /usr/local on UNIX and c:/Program Files on Windows.
6673
6674
6675              On UNIX one can use the DESTDIR mechanism in order  to  relocate
6676              the whole installation.  DESTDIR means DESTination DIRectory. It
6677              is commonly used by makefile users in order to install  software
6678              at non-default location.  It is usually invoked like this:
6679
6680
6681               make DESTDIR=/home/john install
6682
6683              which will install the concerned software using the installation
6684              prefix, e.g. "/usr/local" prepended with the DESTDIR value which
6685              finally gives "/home/john/usr/local".
6686
6687
6688              WARNING: DESTDIR may not be used on Windows because installation
6689              prefix usually contains  a  drive  letter  like  in  "C:/Program
6690              Files" which cannot be prepended with some other prefix.
6691
6692
6693              The  installation  prefix  is  also  added  to CMAKE_SYSTEM_PRE‐
6694              FIX_PATH  so  that  find_package,  find_program,   find_library,
6695              find_path,  and find_file will search the prefix for other soft‐
6696              ware.
6697
6698
6699       CMAKE_LIBRARY_PATH
6700              Path used for searching by FIND_LIBRARY().
6701
6702              Specifies  a  path  which  will  be  used   by   FIND_LIBRARY().
6703              FIND_LIBRARY()  will check each of the contained directories for
6704              the existence of the library which  is  currently  searched.  By
6705              default  it  is  empty, it is intended to be set by the project.
6706              See also CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_PREFIX_PATH.
6707
6708
6709       CMAKE_MFC_FLAG
6710              Tell cmake to use MFC for an executable or dll.
6711
6712              This can be set in a CMakeLists.txt file and will enable MFC  in
6713              the  application.   It  should  be  set  to 1 for the static MFC
6714              library, and 2 for the shared MFC library.  This is used in Vis‐
6715              ual  Studio  6 and 7 project files.   The CMakeSetup dialog used
6716              MFC and the CMakeLists.txt looks like this:
6717
6718
6719                add_definitions(-D_AFXDLL)
6720                set(CMAKE_MFC_FLAG 2)
6721                add_executable(CMakeSetup WIN32 ${SRCS})
6722
6723
6724       CMAKE_MODULE_PATH
6725              List of directories to search for CMake modules.
6726
6727              Commands like include() and find_package() search for  files  in
6728              directories  listed by this variable before checking the default
6729              modules that come with CMake.
6730
6731
6732       CMAKE_NOT_USING_CONFIG_FLAGS
6733              Skip _BUILD_TYPE flags if true.
6734
6735              This is an internal flag used by the generators in CMake to tell
6736              CMake to skip the _BUILD_TYPE flags.
6737
6738
6739       CMAKE_POLICY_DEFAULT_CMP<NNNN>
6740              Default  for  CMake  Policy  CMP<NNNN> when it is otherwise left
6741              unset.
6742
6743              Commands cmake_minimum_required(VERSION)  and  cmake_policy(VER‐
6744              SION)  by default leave policies introduced after the given ver‐
6745              sion unset.  Set CMAKE_POLICY_DEFAULT_CMP<NNNN> to OLD or NEW to
6746              specify  the  default  for policy CMP<NNNN>, where <NNNN> is the
6747              policy number.
6748
6749
6750              This variable should not be set by a project in CMake code;  use
6751              cmake_policy(SET)  instead.   Users  running  CMake may set this
6752              variable     in      the      cache      (e.g.      -DCMAKE_POL‐
6753              ICY_DEFAULT_CMP<NNNN>=<OLD|NEW>)  to  set a policy not otherwise
6754              set by the project.  Set to OLD to quiet a policy warning  while
6755              using  old  behavior  or to NEW to try building the project with
6756              new behavior.
6757
6758
6759       CMAKE_PREFIX_PATH
6760              Path used for searching by FIND_XXX(), with appropriate suffixes
6761              added.
6762
6763              Specifies  a path which will be used by the FIND_XXX() commands.
6764              It contains the  "base"  directories,  the  FIND_XXX()  commands
6765              append  appropriate  subdirectories  to the base directories. So
6766              FIND_PROGRAM() adds /bin to each of the directories in the path,
6767              FIND_LIBRARY()  appends  /lib  to  each  of the directories, and
6768              FIND_PATH() and FIND_FILE() append /include . By default  it  is
6769              empty,  it  is  intended  to  be  set  by  the project. See also
6770              CMAKE_SYSTEM_PREFIX_PATH,                    CMAKE_INCLUDE_PATH,
6771              CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH.
6772
6773
6774       CMAKE_PROGRAM_PATH
6775              Path used for searching by FIND_PROGRAM().
6776
6777              Specifies a path which will be used by FIND_PROGRAM(). FIND_PRO‐
6778              GRAM() will check each of  the  contained  directories  for  the
6779              existence of the program which is currently searched. By default
6780              it is empty, it is intended to be set by the project.  See  also
6781              CMAKE_SYSTEM_PROGRAM_PATH,  CMAKE_PREFIX_PATH.
6782
6783
6784       CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
6785              Don't make the install target depend on the all target.
6786
6787              By  default,  the  "install" target depends on the "all" target.
6788              This has the effect, that when  "make  install"  is  invoked  or
6789              INSTALL  is  built,  first  the  "all" target is built, then the
6790              installation starts.   If  CMAKE_SKIP_INSTALL_ALL_DEPENDENCY  is
6791              set to TRUE, this dependency is not created, so the installation
6792              process will start immediately,  independent  from  whether  the
6793              project has been completely built or not.
6794
6795
6796       CMAKE_SYSTEM_IGNORE_PATH
6797              Path to be ignored by FIND_XXX() commands.
6798
6799              Specifies  directories  to  be ignored by searches in FIND_XXX()
6800              commands.  This is useful in cross-compiled  environments  where
6801              some  system directories contain incompatible but possibly link‐
6802              able libraries. For example, on cross-compiled cluster  environ‐
6803              ments,  this  allows  a  user  to  ignore directories containing
6804              libraries meant for the  front-end  machine  that  modules  like
6805              FindX11  (and  others)  would  normally search.  By default this
6806              contains a list of directories containing incompatible  binaries
6807              for   the   host  system.   See  also  CMAKE_SYSTEM_PREFIX_PATH,
6808              CMAKE_SYSTEM_LIBRARY_PATH,    CMAKE_SYSTEM_INCLUDE_PATH,     and
6809              CMAKE_SYSTEM_PROGRAM_PATH.
6810
6811
6812       CMAKE_SYSTEM_INCLUDE_PATH
6813              Path used for searching by FIND_FILE() and FIND_PATH().
6814
6815              Specifies  a  path  which  will  be used both by FIND_FILE() and
6816              FIND_PATH(). Both commands will  check  each  of  the  contained
6817              directories  for  the  existence  of the file which is currently
6818              searched. By default it contains the  standard  directories  for
6819              the  current  system.  It  is NOT intended to be modified by the
6820              project, use CMAKE_INCLUDE_PATH for this.  See  also  CMAKE_SYS‐
6821              TEM_PREFIX_PATH.
6822
6823
6824       CMAKE_SYSTEM_LIBRARY_PATH
6825              Path used for searching by FIND_LIBRARY().
6826
6827              Specifies   a   path  which  will  be  used  by  FIND_LIBRARY().
6828              FIND_LIBRARY() will check each of the contained directories  for
6829              the  existence  of  the  library which is currently searched. By
6830              default it contains the standard  directories  for  the  current
6831              system.  It  is  NOT intended to be modified by the project, use
6832              CMAKE_LIBRARY_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH.
6833
6834
6835       CMAKE_SYSTEM_PREFIX_PATH
6836              Path used for searching by FIND_XXX(), with appropriate suffixes
6837              added.
6838
6839              Specifies  a path which will be used by the FIND_XXX() commands.
6840              It contains the  "base"  directories,  the  FIND_XXX()  commands
6841              append  appropriate  subdirectories  to the base directories. So
6842              FIND_PROGRAM() adds /bin to each of the directories in the path,
6843              FIND_LIBRARY()  appends  /lib  to  each  of the directories, and
6844              FIND_PATH() and FIND_FILE() append /include .  By  default  this
6845              contains the standard directories for the current system and the
6846              CMAKE_INSTALL_PREFIX.  It is NOT intended to be modified by  the
6847              project,  use  CMAKE_PREFIX_PATH  for  this. See also CMAKE_SYS‐
6848              TEM_INCLUDE_PATH,  CMAKE_SYSTEM_LIBRARY_PATH,  CMAKE_SYSTEM_PRO‐
6849              GRAM_PATH, and CMAKE_SYSTEM_IGNORE_PATH.
6850
6851
6852       CMAKE_SYSTEM_PROGRAM_PATH
6853              Path used for searching by FIND_PROGRAM().
6854
6855              Specifies a path which will be used by FIND_PROGRAM(). FIND_PRO‐
6856              GRAM() will check each of  the  contained  directories  for  the
6857              existence of the program which is currently searched. By default
6858              it contains the standard directories for the current system.  It
6859              is  NOT  intended  to be modified by the project, use CMAKE_PRO‐
6860              GRAM_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH.
6861
6862
6863       CMAKE_USER_MAKE_RULES_OVERRIDE
6864              Specify a CMake file that overrides platform information.
6865
6866              CMake loads the specified file while enabling support  for  each
6867              language  from  either  the  project() or enable_language() com‐
6868              mands.  It is loaded after CMake's builtin compiler and platform
6869              information  modules have been loaded but before the information
6870              is used.  The file may set  platform  information  variables  to
6871              override CMake's defaults.
6872
6873
6874              This  feature is intended for use only in overriding information
6875              variables that must be set before CMake builds  its  first  test
6876              project  to  check  that  the compiler for a language works.  It
6877              should not be used to  load  a  file  in  cases  that  a  normal
6878              include()  will work.  Use it only as a last resort for behavior
6879              that cannot be achieved any other way.  For example, one may set
6880              CMAKE_C_FLAGS_INIT  to change the default value used to initial‐
6881              ize CMAKE_C_FLAGS before it is cached.  The override file should
6882              NOT  be  used  to set anything that could be set after languages
6883              are enabled, such as variables like  CMAKE_RUNTIME_OUTPUT_DIREC‐
6884              TORY  that affect the placement of binaries.  Information set in
6885              the file will be used for try_compile and try_run builds too.
6886
6887
6888       CMAKE_WARN_DEPRECATED
6889              Whether to issue deprecation warnings for macros and functions.
6890
6891              If TRUE, this can be used by macros and functions to issue  dep‐
6892              recation warnings.  This variable is FALSE by default.
6893
6894
6895       CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
6896              Ask  cmake_install.cmake  script  to  warn each time a file with
6897              absolute INSTALL DESTINATION is encountered.
6898
6899              This variable is  used  by  CMake-generated  cmake_install.cmake
6900              scripts.  If  one  sets  this  variable  to ON while running the
6901              script, it may get warning messages from the script.
6902
6903

VARIABLES THAT DESCRIBE THE SYSTEM

6905       APPLE  True if running on Mac OS X.
6906
6907              Set to true on Mac OS X.
6908
6909
6910       BORLAND
6911              True if the Borland compiler is being used.
6912
6913              This is set to true if the Borland compiler is being used.
6914
6915
6916       CMAKE_CL_64
6917              Using the 64 bit compiler from Microsoft
6918
6919              Set to true when using the 64 bit cl compiler from Microsoft.
6920
6921
6922       CMAKE_COMPILER_2005
6923              Using the Visual Studio 2005 compiler from Microsoft
6924
6925              Set to true when using the Visual Studio 2005 compiler from  Mi‐
6926              crosoft.
6927
6928
6929       CMAKE_HOST_APPLE
6930              True for Apple OS X operating systems.
6931
6932              Set to true when the host system is Apple OS X.
6933
6934
6935       CMAKE_HOST_SYSTEM
6936              Name of system cmake is being run on.
6937
6938              The  same as CMAKE_SYSTEM but for the host system instead of the
6939              target system when cross compiling.
6940
6941
6942       CMAKE_HOST_SYSTEM_NAME
6943              Name of the OS CMake is running on.
6944
6945              The same as CMAKE_SYSTEM_NAME but for the host system instead of
6946              the target system when cross compiling.
6947
6948
6949       CMAKE_HOST_SYSTEM_PROCESSOR
6950              The name of the CPU CMake is running on.
6951
6952              The  same  as  CMAKE_SYSTEM_PROCESSOR  but  for  the host system
6953              instead of the target system when cross compiling.
6954
6955
6956       CMAKE_HOST_SYSTEM_VERSION
6957              OS version CMake is running on.
6958
6959              The same as CMAKE_SYSTEM_VERSION but for the host system instead
6960              of the target system when cross compiling.
6961
6962
6963       CMAKE_HOST_UNIX
6964              True for UNIX and UNIX like operating systems.
6965
6966              Set  to  true  when  the  host system is UNIX or UNIX like (i.e.
6967              APPLE and CYGWIN).
6968
6969
6970       CMAKE_HOST_WIN32
6971              True on windows systems, including win64.
6972
6973              Set to true when the host system is Windows and on Cygwin.
6974
6975
6976       CMAKE_LIBRARY_ARCHITECTURE
6977              Target architecture library directory name, if detected.
6978
6979              This  is  the  value  of  CMAKE_<lang>_LIBRARY_ARCHITECTURE   as
6980              detected for one of the enabled languages.
6981
6982
6983       CMAKE_LIBRARY_ARCHITECTURE_REGEX
6984              Regex  matching  possible  target architecture library directory
6985              names.
6986
6987              This is used to  detect  CMAKE_<lang>_LIBRARY_ARCHITECTURE  from
6988              the implicit linker search path by matching the <arch> name.
6989
6990
6991       CMAKE_OBJECT_PATH_MAX
6992              Maximum  object  file  full-path  length allowed by native build
6993              tools.
6994
6995              CMake computes for every source file an object file name that is
6996              unique  to the source file and deterministic with respect to the
6997              full path to the source file.  This allows multiple source files
6998              in  a  target  to  share  the same name if they lie in different
6999              directories without rebuilding when one  is  added  or  removed.
7000              However, it can produce long full paths in a few cases, so CMake
7001              shortens the path using a hashing scheme when the full  path  to
7002              an  object file exceeds a limit.  CMake has a built-in limit for
7003              each platform that is sufficient  for  common  tools,  but  some
7004              native  tools  may have a lower limit.  This variable may be set
7005              to specify the limit explicitly.  The value must be  an  integer
7006              no less than 128.
7007
7008
7009       CMAKE_SYSTEM
7010              Name of system cmake is compiling for.
7011
7012              This   variable   is  the  composite  of  CMAKE_SYSTEM_NAME  and
7013              CMAKE_SYSTEM_VERSION,       like        this        ${CMAKE_SYS‐
7014              TEM_NAME}-${CMAKE_SYSTEM_VERSION}.   If  CMAKE_SYSTEM_VERSION is
7015              not set, then CMAKE_SYSTEM is the same as CMAKE_SYSTEM_NAME.
7016
7017
7018       CMAKE_SYSTEM_NAME
7019              Name of the OS CMake is building for.
7020
7021              This is the name of the operating system on which CMake is  tar‐
7022              geting.    On systems that have the uname command, this variable
7023              is set to the output of uname -s.  Linux, Windows,   and  Darwin
7024              for  Mac  OS  X are the values found  on the big three operating
7025              systems.
7026
7027
7028       CMAKE_SYSTEM_PROCESSOR
7029              The name of the CPU CMake is building for.
7030
7031              On systems that support uname, this variable is set to the  out‐
7032              put  of uname -p, on windows it is set to the value of the envi‐
7033              ronment variable PROCESSOR_ARCHITECTURE
7034
7035
7036       CMAKE_SYSTEM_VERSION
7037              OS version CMake is building for.
7038
7039              A numeric version string for the system, on systems that support
7040              uname,  this variable is set to the output of uname -r. On other
7041              systems this is set to major-minor version numbers.
7042
7043
7044       CYGWIN True for Cygwin.
7045
7046              Set to true when using Cygwin.
7047
7048
7049       ENV    Access environment variables.
7050
7051              Use the syntax $ENV{VAR} to read environment variable VAR.   See
7052              also the set() command to set ENV{VAR}.
7053
7054
7055       MSVC   True when using Microsoft Visual C
7056
7057              Set  to true when the compiler is some version of Microsoft Vis‐
7058              ual C.
7059
7060
7061       MSVC10 True when using Microsoft Visual C 10.0
7062
7063              Set to true when the compiler is version 10.0 of Microsoft  Vis‐
7064              ual C.
7065
7066
7067       MSVC11 True when using Microsoft Visual C 11.0
7068
7069              Set  to true when the compiler is version 11.0 of Microsoft Vis‐
7070              ual C.
7071
7072
7073       MSVC12 True when using Microsoft Visual C 12.0
7074
7075              Set to true when the compiler is version 12.0 of Microsoft  Vis‐
7076              ual C.
7077
7078
7079       MSVC60 True when using Microsoft Visual C 6.0
7080
7081              Set to true when the compiler is version 6.0 of Microsoft Visual
7082              C.
7083
7084
7085       MSVC70 True when using Microsoft Visual C 7.0
7086
7087              Set to true when the compiler is version 7.0 of Microsoft Visual
7088              C.
7089
7090
7091       MSVC71 True when using Microsoft Visual C 7.1
7092
7093              Set to true when the compiler is version 7.1 of Microsoft Visual
7094              C.
7095
7096
7097       MSVC80 True when using Microsoft Visual C 8.0
7098
7099              Set to true when the compiler is version 8.0 of Microsoft Visual
7100              C.
7101
7102
7103       MSVC90 True when using Microsoft Visual C 9.0
7104
7105              Set to true when the compiler is version 9.0 of Microsoft Visual
7106              C.
7107
7108
7109       MSVC_IDE
7110              True when using the Microsoft Visual C IDE
7111
7112              Set to true when the target platform is the Microsoft  Visual  C
7113              IDE, as opposed to the command line compiler.
7114
7115
7116       MSVC_VERSION
7117              The version of Microsoft Visual C/C++ being used if any.
7118
7119              Known version numbers are:
7120
7121
7122                1200 = VS  6.0
7123                1300 = VS  7.0
7124                1310 = VS  7.1
7125                1400 = VS  8.0
7126                1500 = VS  9.0
7127                1600 = VS 10.0
7128                1700 = VS 11.0
7129                1800 = VS 12.0
7130
7131
7132       UNIX   True for UNIX and UNIX like operating systems.
7133
7134              Set  to  true  when the target system is UNIX or UNIX like (i.e.
7135              APPLE and CYGWIN).
7136
7137
7138       WIN32  True on windows systems, including win64.
7139
7140              Set to true when the target system is Windows.
7141
7142
7143       XCODE_VERSION
7144              Version of Xcode (Xcode generator only).
7145
7146              Under the Xcode generator, this is the version of Xcode as spec‐
7147              ified in "Xcode.app/Contents/version.plist" (such as "3.1.2").
7148
7149

VARIABLES COMMON TO ALL CPACK GENERATORS

7151       CPACK_ABSOLUTE_DESTINATION_FILES
7152              List  of files which have been installed using  an ABSOLUTE DES‐
7153              TINATION path.
7154
7155              This variable is a Read-Only variable which is set internally by
7156              CPack during installation and before packaging using CMAKE_ABSO‐
7157              LUTE_DESTINATION_FILES defined in  cmake_install.cmake  scripts.
7158              The  value  can  be used within CPack project configuration file
7159              and/or CPack<GEN>.cmake file of <GEN> generator.
7160
7161
7162       CPACK_BINARY_<GENNAME>
7163              CPack generated options for binary generators
7164
7165              The CPack.cmake module generates (when  CPACK_GENERATOR  is  not
7166              set) a set of CMake options (see CMake option command) which may
7167              then be used to select the CPack generator(s) to  be  used  when
7168              launching the package target.
7169
7170
7171       CPACK_CMAKE_GENERATOR
7172              What  CMake  generator  should  be  used if the project is CMake
7173              project.
7174
7175              Defaults to the value of CMAKE_GENERATOR few users will want  to
7176              change this setting.
7177
7178
7179       CPACK_COMPONENT_INCLUDE_TOPLEVEL_DIRECTORY
7180              Boolean toggle to include/exclude top level directory (component
7181              case).
7182
7183              Similar usage as CPACK_INCLUDE_TOPLEVEL_DIRECTORY  but  for  the
7184              component  case. See CPACK_INCLUDE_TOPLEVEL_DIRECTORY documenta‐
7185              tion for the detail.
7186
7187
7188       CPACK_CREATE_DESKTOP_LINKS
7189              List of desktop links to create
7190
7191
7192       CPACK_GENERATOR
7193              List of CPack generators to use
7194
7195              If  not  specified,  CPack  will  create  a   set   of   options
7196              CPACK_BINARY_<GENNAME>  (e.g.,  CPACK_BINARY_NSIS)  allowing the
7197              user to enable/disable individual generators. This variable  may
7198              be used on the command line as well as in:
7199
7200
7201                  cpack -D CPACK_GENERATOR="ZIP;TGZ" /path/to/build/tree
7202
7203
7204       CPACK_INCLUDE_TOPLEVEL_DIRECTORY
7205              Boolean toggle to include/exclude top level directory.
7206
7207              When  preparing  a  package  CPack  installs  the item under the
7208              so-called top level directory. The purpose of is to include (set
7209              to  1  or  ON or TRUE) the top level directory in the package or
7210              not (set to 0 or OFF or FALSE).
7211
7212
7213              Each CPack generator has a built-in default value for this vari‐
7214              able.  E.g.  Archive generators (ZIP, TGZ, ...) includes the top
7215              level whereas RPM or  DEB  don't.  The  user  may  override  the
7216              default value by setting this variable.
7217
7218
7219              There      is      a      similar      variable     CPACK_COMPO‐
7220              NENT_INCLUDE_TOPLEVEL_DIRECTORY which may be  used  to  override
7221              the  behavior  for  the  component packaging case which may have
7222              different default value for historical (now backward compatibil‐
7223              ity) reason.
7224
7225
7226       CPACK_INSTALLED_DIRECTORIES
7227              Extra directories to install
7228
7229
7230       CPACK_INSTALL_CMAKE_PROJECTS
7231              List of four values that specify what project to install.
7232
7233              The four values are: Build directory, Project Name, Project Com‐
7234              ponent, Directory. If omitted, CPack  will  build  an  installer
7235              that installers everything.
7236
7237
7238       CPACK_INSTALL_COMMANDS
7239              Extra commands to install components
7240
7241
7242       CPACK_INSTALL_SCRIPT
7243              Extra CMake script provided by the user.
7244
7245              If  set  this  CMake script will be executed by CPack during its
7246              local [CPack-private] installation which is  done  right  before
7247              packaging  the  files.  The  script  is not called by e.g.: make
7248              install.
7249
7250
7251       CPACK_MONOLITHIC_INSTALL
7252              Disables the component-based installation mechanism.
7253
7254              When  set  the  component  specification  is  ignored  and   all
7255              installed  items  are put in a single "MONOLITHIC" package. Some
7256              CPack generators do monolithic packaging by default and  may  be
7257              asked  to do component packaging by setting CPACK_<GENNAME>_COM‐
7258              PONENT_INSTALL to 1/TRUE.
7259
7260
7261       CPACK_OUTPUT_CONFIG_FILE
7262              The name of the CPack binary configuration file.
7263
7264              This file is the CPack configuration generated by the CPack mod‐
7265              ule for binary installers. Defaults to CPackConfig.cmake.
7266
7267
7268       CPACK_PACKAGE_DESCRIPTION_FILE
7269              A text file used to describe the project.
7270
7271              Used,  for example, the introduction screen of a CPack-generated
7272              Windows installer to describe the project.
7273
7274
7275       CPACK_PACKAGE_DESCRIPTION_SUMMARY
7276              Short description of the project (only a few words).
7277
7278
7279       CPACK_PACKAGE_DIRECTORY
7280              The directory in which CPack is doing its packaging.
7281
7282              If it is not set then this  will  default  (internally)  to  the
7283              build  dir. This variable may be defined in CPack config file or
7284              from the cpack command line option "-B". If set the command line
7285              option override the value found in the config file.
7286
7287
7288       CPACK_PACKAGE_EXECUTABLES
7289              Lists  each  of  the executables and associated text label to be
7290              used to create Start Menu shortcuts.
7291
7292              For example, setting this to the list ccmake;CMake will create a
7293              shortcut  named  "CMake"  that  will  execute the installed exe‐
7294              cutable ccmake. Not all CPack generators use it (at  least  NSIS
7295              and OSXX11 do).
7296
7297
7298       CPACK_PACKAGE_FILE_NAME
7299              The  name  of  the  package  file to generate, not including the
7300              extension.
7301
7302              For example, cmake-2.6.1-Linux-i686. The default value is
7303
7304
7305                ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}.
7306
7307
7308       CPACK_PACKAGE_ICON
7309              A branding image that will be  displayed  inside  the  installer
7310              (used by GUI installers).
7311
7312
7313       CPACK_PACKAGE_INSTALL_DIRECTORY
7314              Installation directory on the target system.
7315
7316              This may be used by some CPack generators like NSIS to create an
7317              installation directory e.g., "CMake 2.5" below the  installation
7318              prefix. All installed element will be put inside this directory.
7319
7320
7321       CPACK_PACKAGE_INSTALL_REGISTRY_KEY
7322              Registry key used when installing this project.
7323
7324              This  is only used by installer for Windows.   The default value
7325              is based on the installation directory.
7326
7327
7328
7329       CPACK_PACKAGE_NAME
7330              The name of the package (or application)
7331
7332              If not specified, defaults to the project name.
7333
7334
7335       CPACK_PACKAGE_VENDOR
7336              The name of the package vendor
7337
7338              (e.g., "Kitware").
7339
7340
7341       CPACK_PACKAGE_VERSION
7342              Package full version, used internally
7343
7344              By default,  this  is  built  from  CPACK_PACKAGE_VERSION_MAJOR,
7345              CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
7346
7347
7348       CPACK_PACKAGE_VERSION_MAJOR
7349              Package major Version
7350
7351
7352       CPACK_PACKAGE_VERSION_MINOR
7353              Package minor Version
7354
7355
7356       CPACK_PACKAGE_VERSION_PATCH
7357              Package patch Version
7358
7359
7360       CPACK_PACKAGING_INSTALL_PREFIX
7361              The prefix used in the built package.
7362
7363              Each  CPack  generator  has  a  default  value (like /usr). This
7364              default value may be overwritten from the CMakeLists.txt or  the
7365              cpack command line by setting an alternative value.
7366
7367
7368              e.g.  set(CPACK_PACKAGING_INSTALL_PREFIX "/opt")
7369
7370
7371              This  is  not  the same purpose as CMAKE_INSTALL_PREFIX which is
7372              used when installing from the  build  tree  without  building  a
7373              package.
7374
7375
7376       CPACK_PROJECT_CONFIG_FILE
7377              CPack-time project CPack configuration file.
7378
7379              This file included at cpack time, once per generator after CPack
7380              has set CPACK_GENERATOR to the actual generator being  used.  It
7381              allows per-generator setting of CPACK_* variables at cpack time.
7382
7383
7384       CPACK_RESOURCE_FILE_LICENSE
7385              License to be embedded in the installer
7386
7387              It  will  typically be displayed to the user by the produced in‐
7388              staller (often with an explicit "Accept" button,  for  graphical
7389              installers)  prior  to  installation.  This  license file is NOT
7390              added to installed file but is used  by  some  CPack  generators
7391              like  NSIS.  If  you  want to install a license file (may be the
7392              same as this one) along with your project you must add an appro‐
7393              priate CMake INSTALL command in your CMakeLists.txt.
7394
7395
7396       CPACK_RESOURCE_FILE_README
7397              ReadMe file to be embedded in the installer
7398
7399              It typically describes in some detail the purpose of the project
7400              during the installation. Not  all  CPack  generators  uses  this
7401              file.
7402
7403
7404       CPACK_RESOURCE_FILE_WELCOME
7405              Welcome file to be embedded in the installer.
7406
7407              It  welcomes  users  to  this  installer.  Typically used in the
7408              graphical installers on Windows and Mac OS X.
7409
7410
7411       CPACK_SET_DESTDIR
7412              Boolean toggle to make CPack use DESTDIR mechanism when  packag‐
7413              ing.
7414
7415              DESTDIR  means  DESTination  DIRectory.  It  is commonly used by
7416              makefile users in order to install software at non-default loca‐
7417              tion. It is a basic relocation mechanism that should not be used
7418              on Windows (see CMAKE_INSTALL_PREFIX documentation). It is  usu‐
7419              ally invoked like this:
7420
7421
7422               make DESTDIR=/home/john install
7423
7424              which will install the concerned software using the installation
7425              prefix, e.g. "/usr/local" prepended with the DESTDIR value which
7426              finally  gives "/home/john/usr/local". When preparing a package,
7427              CPack first installs the items to be packaged in a local (to the
7428              build  tree) directory by using the same DESTDIR mechanism. Nev‐
7429              ertheless, if CPACK_SET_DESTDIR is set then CPack will set DEST‐
7430              DIR  before doing the local install. The most noticeable differ‐
7431              ence is that without CPACK_SET_DESTDIR, CPack uses CPACK_PACKAG‐
7432              ING_INSTALL_PREFIX  as  a  prefix whereas with CPACK_SET_DESTDIR
7433              set, CPack will use CMAKE_INSTALL_PREFIX as a prefix.
7434
7435
7436              Manually setting CPACK_SET_DESTDIR may help (or simply be neces‐
7437              sary) if some install rules uses absolute DESTINATION (see CMake
7438              INSTALL command). However, starting with CPack/CMake  2.8.3  RPM
7439              and DEB installers tries to handle DESTDIR automatically so that
7440              it is seldom necessary for the user to set it.
7441
7442
7443       CPACK_SOURCE_GENERATOR
7444              List of generators used for the source packages.
7445
7446              As with CPACK_GENERATOR, if this is  not  specified  then  CPack
7447              will  create  a set of options (e.g., CPACK_SOURCE_ZIP) allowing
7448              users to select which packages will be generated.
7449
7450
7451       CPACK_SOURCE_IGNORE_FILES
7452              Pattern of files in the source tree that won't be packaged  when
7453              building a source package.
7454
7455              This  is  a  list  of  regular expression patterns (that must be
7456              properly                     escaped),                     e.g.,
7457              /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
7458
7459
7460       CPACK_SOURCE_OUTPUT_CONFIG_FILE
7461              The name of the CPack source configuration file.
7462
7463              This file is the CPack configuration generated by the CPack mod‐
7464              ule for source installers. Defaults to CPackSourceConfig.cmake.
7465
7466
7467       CPACK_SOURCE_PACKAGE_FILE_NAME
7468              The name of the source package
7469
7470              For example cmake-2.6.1.
7471
7472
7473       CPACK_SOURCE_STRIP_FILES
7474              List of files in the source tree that will be stripped.
7475
7476              Starting with CMake 2.6.0  CPACK_SOURCE_STRIP_FILES  will  be  a
7477              boolean variable which enables stripping of all files (a list of
7478              files evaluates to TRUE in CMake, so this change is compatible).
7479
7480
7481       CPACK_STRIP_FILES
7482              List of files to be stripped
7483
7484              Starting with CMake 2.6.0 CPACK_STRIP_FILES will  be  a  boolean
7485              variable  which  enables stripping of all files (a list of files
7486              evaluates to TRUE in CMake, so this change is compatible).
7487
7488
7489       CPACK_SYSTEM_NAME
7490              System name, defaults to the value of ${CMAKE_SYSTEM_NAME}.
7491
7492
7493       CPACK_TOPLEVEL_TAG
7494              Directory for the installed files
7495
7496
7497       CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
7498              Ask CPack to warn each time a file with absolute INSTALL  DESTI‐
7499              NATION is encountered.
7500
7501              This  variable  triggers  the  definition of CMAKE_WARN_ON_ABSO‐
7502              LUTE_INSTALL_DESTINATION  when  CPack  runs  cmake_install.cmake
7503              scripts.
7504
7505

VARIABLES CONCERNING CPACK COMPONENTS

7507       CPACK_<GENNAME>_COMPONENT_INSTALL
7508              Enable/Disable component install for CPack generator <GENNAME>.
7509
7510              Each  CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has
7511              a legacy default behavior. e.g. RPM  builds  monolithic  whereas
7512              NSIS  builds  component.  One can change the default behavior by
7513              setting this variable to 0/1 or OFF/ON.
7514
7515
7516       CPACK_COMPONENTS_ALL
7517              The list of component to install
7518
7519              The default value of this variable is computed by CPack and con‐
7520              tains all components defined by the project. The user may set it
7521              to only include the specified components.
7522
7523
7524       CPACK_COMPONENTS_GROUPING
7525              Specify how components  are  grouped  for  multi-package  compo‐
7526              nent-aware CPack generators.
7527
7528              Some  generators like RPM or ARCHIVE family (TGZ, ZIP, ...) gen‐
7529              erates several packages files when asked for  component  packag‐
7530              ing. They group the component differently depending on the value
7531              of this variable:
7532
7533
7534                - ONE_PER_GROUP (default): creates one package file per component group
7535                - ALL_COMPONENTS_IN_ONE : creates a single package with all (requested) component
7536                - IGNORE : creates one package per component, i.e. IGNORE component group
7537
7538              One can specify different grouping for different CPack generator
7539              by using a CPACK_PROJECT_CONFIG_FILE.
7540
7541
7542       CPACK_COMPONENT_<compName>_DEPENDS
7543              The  dependencies  (list  of components) on which this component
7544              depends.
7545
7546
7547       CPACK_COMPONENT_<compName>_DESCRIPTION
7548              The description of a component
7549
7550
7551       CPACK_COMPONENT_<compName>_DISPLAY_NAME
7552              The name to be displayed for a component
7553
7554
7555       CPACK_COMPONENT_<compName>_GROUP
7556              The group of a component
7557
7558
7559       CPACK_COMPONENT_<compName>_REQUIRED
7560              True is this component is required
7561
7562

VARIABLES FOR LANGUAGES

7564       CMAKE_<LANG>_ARCHIVE_APPEND
7565              Rule variable to append to a static archive.
7566
7567              This is a rule variable that tells CMake  how  to  append  to  a
7568              static  archive.   It  is  used  in  place  of CMAKE_<LANG>_CRE‐
7569              ATE_STATIC_LIBRARY on some platforms in order to  support  large
7570              object   counts.    See   also  CMAKE_<LANG>_ARCHIVE_CREATE  and
7571              CMAKE_<LANG>_ARCHIVE_FINISH.
7572
7573
7574       CMAKE_<LANG>_ARCHIVE_CREATE
7575              Rule variable to create a new static archive.
7576
7577              This is a rule variable that tells CMake how to create a  static
7578              archive.    It   is   used   in   place   of   CMAKE_<LANG>_CRE‐
7579              ATE_STATIC_LIBRARY on some platforms in order to  support  large
7580              object   counts.    See   also  CMAKE_<LANG>_ARCHIVE_APPEND  and
7581              CMAKE_<LANG>_ARCHIVE_FINISH.
7582
7583
7584       CMAKE_<LANG>_ARCHIVE_FINISH
7585              Rule variable to finish an existing static archive.
7586
7587              This is a rule variable that tells CMake how to finish a  static
7588              archive.    It   is   used   in   place   of   CMAKE_<LANG>_CRE‐
7589              ATE_STATIC_LIBRARY on some platforms in order to  support  large
7590              object   counts.    See   also  CMAKE_<LANG>_ARCHIVE_CREATE  and
7591              CMAKE_<LANG>_ARCHIVE_APPEND.
7592
7593
7594       CMAKE_<LANG>_COMPILER
7595              The full path to the compiler for LANG.
7596
7597              This is the command that will be used as  the  <LANG>  compiler.
7598              Once set, you can not change this variable.
7599
7600
7601       CMAKE_<LANG>_COMPILER_ABI
7602              An internal variable subject to change.
7603
7604              This  is  used in determining the compiler ABI and is subject to
7605              change.
7606
7607
7608       CMAKE_<LANG>_COMPILER_ID
7609              Compiler identification string.
7610
7611              A short string unique to the compiler vendor.   Possible  values
7612              include:
7613
7614
7615                Absoft = Absoft Fortran (absoft.com)
7616                ADSP = Analog VisualDSP++ (analog.com)
7617                Clang = LLVM Clang (clang.llvm.org)
7618                Cray = Cray Compiler (cray.com)
7619                Embarcadero, Borland = Embarcadero (embarcadero.com)
7620                G95 = G95 Fortran (g95.org)
7621                GNU = GNU Compiler Collection (gcc.gnu.org)
7622                HP = Hewlett-Packard Compiler (hp.com)
7623                Intel = Intel Compiler (intel.com)
7624                MIPSpro = SGI MIPSpro (sgi.com)
7625                MSVC = Microsoft Visual Studio (microsoft.com)
7626                PGI = The Portland Group (pgroup.com)
7627                PathScale = PathScale (pathscale.com)
7628                SDCC = Small Device C Compiler (sdcc.sourceforge.net)
7629                SunPro = Oracle Solaris Studio (oracle.com)
7630                TI = Texas Instruments (ti.com)
7631                TinyCC = Tiny C Compiler (tinycc.org)
7632                Watcom = Open Watcom (openwatcom.org)
7633                XL, VisualAge, zOS = IBM XL (ibm.com)
7634
7635              This  variable is not guaranteed to be defined for all compilers
7636              or languages.
7637
7638
7639       CMAKE_<LANG>_COMPILER_LOADED
7640              Defined to true if the language is enabled.
7641
7642              When language <LANG> is  enabled  by  project()  or  enable_lan‐
7643              guage() this variable is defined to 1.
7644
7645
7646       CMAKE_<LANG>_COMPILER_VERSION
7647              Compiler version string.
7648
7649              Compiler  version in major[.minor[.patch[.tweak]]] format.  This
7650              variable is not guaranteed to be defined for  all  compilers  or
7651              languages.
7652
7653
7654       CMAKE_<LANG>_COMPILE_OBJECT
7655              Rule variable to compile a single object file.
7656
7657              This is a rule variable that tells CMake how to compile a single
7658              object file for the language <LANG>.
7659
7660
7661       CMAKE_<LANG>_CREATE_SHARED_LIBRARY
7662              Rule variable to create a shared library.
7663
7664              This is a rule variable that tells CMake how to create a  shared
7665              library for the language <LANG>.
7666
7667
7668       CMAKE_<LANG>_CREATE_SHARED_MODULE
7669              Rule variable to create a shared module.
7670
7671              This  is a rule variable that tells CMake how to create a shared
7672              library for the language <LANG>.
7673
7674
7675       CMAKE_<LANG>_CREATE_STATIC_LIBRARY
7676              Rule variable to create a static library.
7677
7678              This is a rule variable that tells CMake how to create a  static
7679              library for the language <LANG>.
7680
7681
7682       CMAKE_<LANG>_FLAGS
7683              Flags for all build types.
7684
7685              <LANG> flags used regardless of the value of CMAKE_BUILD_TYPE.
7686
7687
7688       CMAKE_<LANG>_FLAGS_DEBUG
7689              Flags for Debug build type or configuration.
7690
7691              <LANG> flags used when CMAKE_BUILD_TYPE is Debug.
7692
7693
7694       CMAKE_<LANG>_FLAGS_MINSIZEREL
7695              Flags for MinSizeRel build type or configuration.
7696
7697              <LANG>  flags used when CMAKE_BUILD_TYPE is MinSizeRel.Short for
7698              minimum size release.
7699
7700
7701       CMAKE_<LANG>_FLAGS_RELEASE
7702              Flags for Release build type or configuration.
7703
7704              <LANG> flags used when CMAKE_BUILD_TYPE is Release
7705
7706
7707       CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
7708              Flags for RelWithDebInfo type or configuration.
7709
7710              <LANG>  flags  used  when  CMAKE_BUILD_TYPE  is  RelWithDebInfo.
7711              Short for Release With Debug Information.
7712
7713
7714       CMAKE_<LANG>_IGNORE_EXTENSIONS
7715              File extensions that should be ignored by the build.
7716
7717              This  is a list of file extensions that may be part of a project
7718              for a given language but are not compiled.
7719
7720
7721       CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
7722              Directories implicitly  searched  by  the  compiler  for  header
7723              files.
7724
7725              CMake  does not explicitly specify these directories on compiler
7726              command lines for language <LANG>.  This prevents system include
7727              directories  from  being  treated as user include directories on
7728              some compilers.
7729
7730
7731       CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
7732              Implicit linker search path detected for language <LANG>.
7733
7734              Compilers typically pass directories containing language runtime
7735              libraries  and  default  library search paths when they invoke a
7736              linker.  These paths are implicit linker search directories  for
7737              the  compiler's  language.   CMake  automatically  detects these
7738              directories for each language and reports the  results  in  this
7739              variable.
7740
7741
7742              When a library in one of these directories is given by full path
7743              to target_link_libraries() CMake will generate the -l<name> form
7744              on  link lines to ensure the linker searches its implicit direc‐
7745              tories for the library.  Note that some toolchains read implicit
7746              directories from an environment variable such as LIBRARY_PATH so
7747              keep its value consistent when operating in a given build tree.
7748
7749
7750       CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
7751              Implicit linker framework  search  path  detected  for  language
7752              <LANG>.
7753
7754              These paths are implicit linker framework search directories for
7755              the compiler's  language.   CMake  automatically  detects  these
7756              directories  for  each  language and reports the results in this
7757              variable.
7758
7759
7760       CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
7761              Implicit link libraries and flags detected for language <LANG>.
7762
7763              Compilers typically pass  language  runtime  library  names  and
7764              other flags when they invoke a linker.  These flags are implicit
7765              link options for the compiler's language.   CMake  automatically
7766              detects  these libraries and flags for each language and reports
7767              the results in this variable.
7768
7769
7770       CMAKE_<LANG>_LIBRARY_ARCHITECTURE
7771              Target architecture library directory name detected for <lang>.
7772
7773              If the <lang> compiler passes to the linker an architecture-spe‐
7774              cific   system   library   search   directory   such   as  <pre‐
7775              fix>/lib/<arch> this variable contains  the  <arch>  name  if/as
7776              detected by CMake.
7777
7778
7779       CMAKE_<LANG>_LINKER_PREFERENCE
7780              Preference value for linker language selection.
7781
7782              The "linker language" for executable, shared library, and module
7783              targets is the language whose compiler will invoke  the  linker.
7784              The  LINKER_LANGUAGE  target  property sets the language explic‐
7785              itly.  Otherwise, the linker language is that whose linker pref‐
7786              erence value is highest among languages compiled and linked into
7787              the target.  See also the  CMAKE_<LANG>_LINKER_PREFERENCE_PROPA‐
7788              GATES variable.
7789
7790
7791       CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES
7792              True  if  CMAKE_<LANG>_LINKER_PREFERENCE  propagates across tar‐
7793              gets.
7794
7795              This is used when CMake selects a linker language for a  target.
7796              Languages  compiled  directly into the target are always consid‐
7797              ered.  A language compiled into static libraries linked  by  the
7798              target is considered if this variable is true.
7799
7800
7801       CMAKE_<LANG>_LINK_EXECUTABLE
7802              Rule variable to link an executable.
7803
7804              Rule variable to link an executable for the given language.
7805
7806
7807       CMAKE_<LANG>_OUTPUT_EXTENSION
7808              Extension for the output of a compile for a single file.
7809
7810              This  is  the extension for an object file for the given <LANG>.
7811              For example .obj for C on Windows.
7812
7813
7814       CMAKE_<LANG>_PLATFORM_ID
7815              An internal variable subject to change.
7816
7817              This is used in determining  the  platform  and  is  subject  to
7818              change.
7819
7820
7821       CMAKE_<LANG>_SIZEOF_DATA_PTR
7822              Size of pointer-to-data types for language <LANG>.
7823
7824              This  holds  the size (in bytes) of pointer-to-data types in the
7825              target platform ABI.  It is defined  for  languages  C  and  CXX
7826              (C++).
7827
7828
7829       CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS
7830              Extensions of source files for the given language.
7831
7832              This  is  the  list  of extensions for a given language's source
7833              files.
7834
7835
7836       CMAKE_COMPILER_IS_GNU<LANG>
7837              True if the compiler is GNU.
7838
7839              If the selected <LANG> compiler is the GNU compiler then this is
7840              TRUE,  if  not it is FALSE.  Unlike the other per-language vari‐
7841              ables, this  uses  the  GNU  syntax  for  identifying  languages
7842              instead  of  the  CMake  syntax. Recognized values of the <LANG>
7843              suffix are:
7844
7845
7846                CC = C compiler
7847                CXX = C++ compiler
7848                G77 = Fortran compiler
7849
7850
7851       CMAKE_Fortran_MODDIR_DEFAULT
7852              Fortran default module output directory.
7853
7854              Most Fortran compilers write .mod files to the  current  working
7855              directory.   For  those that do not, this is set to "." and used
7856              when the Fortran_MODULE_DIRECTORY target property is not set.
7857
7858
7859       CMAKE_Fortran_MODDIR_FLAG
7860              Fortran flag for module output directory.
7861
7862              This stores the flag needed  to  pass  the  value  of  the  For‐
7863              tran_MODULE_DIRECTORY target property to the compiler.
7864
7865
7866       CMAKE_Fortran_MODOUT_FLAG
7867              Fortran flag to enable module output.
7868
7869              Most  Fortran  compilers  write  .mod files out by default.  For
7870              others, this stores the flag needed to enable module output.
7871
7872
7873       CMAKE_INTERNAL_PLATFORM_ABI
7874              An internal variable subject to change.
7875
7876              This is used in determining the compiler ABI and is  subject  to
7877              change.
7878
7879
7880       CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>
7881              Specify  a  CMake  file  that overrides platform information for
7882              <LANG>.
7883
7884              This      is      a      language-specific      version       of
7885              CMAKE_USER_MAKE_RULES_OVERRIDE  loaded  only  when enabling lan‐
7886              guage <LANG>.
7887
7888

VARIABLES SPECIFIC TO CPACK BUNDLE GENERATOR

7890       CPACK_BUNDLE_ICON
7891              Path to an OSX icon file that will be used as the icon  for  the
7892              generated bundle.
7893
7894              This  is the icon that appears in the OSX finder for the bundle,
7895              and in the OSX dock when the bundle is opened. Required.
7896
7897
7898       CPACK_BUNDLE_NAME
7899              The name of the generated bundle
7900
7901              This appears in the OSX finder as the bundle name. Required.
7902
7903
7904       CPACK_BUNDLE_PLIST
7905              Path to an OSX plist file that will be used  for  the  generated
7906              bundle.
7907
7908              This  assumes  that  the caller has generated or specified their
7909              own Info.plist file. Required.
7910
7911
7912       CPACK_BUNDLE_STARTUP_COMMAND
7913              Path to a startup script
7914
7915              This is a path to an executable or script that will be run when‐
7916              ever  an  end-user double-clicks the generated bundle in the OSX
7917              Finder. Optional.
7918
7919

VARIABLES SPECIFIC TO CPACK CYGWIN GENERATOR

7921       CPACK_CYGWIN_BUILD_SCRIPT
7922              The Cygwin build script
7923
7924                 FIXME: This documentation is incomplete.
7925
7926
7927       CPACK_CYGWIN_PATCH_FILE
7928              The Cygwin patch file
7929
7930                 FIXME: This documentation is incomplete.
7931
7932
7933       CPACK_CYGWIN_PATCH_NUMBER
7934              The Cygwin patch number
7935
7936                 FIXME: This documentation is incomplete.
7937
7938

VARIABLES SPECIFIC TO CPACK DEBIAN (DEB) GENERATOR

7940       CPACK_DEBIAN_PACKAGE_ARCHITECTURE
7941                   Mandatory : YES
7942                   Default   : Output of dpkg --print-architecture (or i386 if dpkg is not found)
7943                   The debian package architecture
7944
7945
7946       CPACK_DEBIAN_PACKAGE_BREAKS
7947                   Mandatory : NO
7948                   Default   : -
7949                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
7950                   When one binary package declares that it breaks another, dpkg will refuse to allow the
7951                   package which declares Breaks be installed unless the broken package is deconfigured first,
7952                   and it will refuse to allow the broken package to be reconfigured.
7953
7954
7955       CPACK_DEBIAN_PACKAGE_CONFLICTS
7956                   Mandatory : NO
7957                   Default   : -
7958                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
7959                   When one binary package declares a conflict with another using a Conflicts field,
7960                   dpkg will refuse to allow them to be installed on the system at the same time.
7961
7962
7963       CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
7964                   Mandatory : NO
7965                   Default   : -
7966                   This variable allow advanced user to add custom script to the control.tar.gz
7967                   Typical usage is for conffiles, postinst, postrm, prerm.
7968                   Usage: set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
7969                          "${CMAKE_CURRENT_SOURCE_DIR/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
7970
7971
7972       CPACK_DEBIAN_PACKAGE_DEBUG
7973                   Mandatory : NO
7974                   Default   : -
7975                   May be set when invoking cpack in order to trace debug information
7976                   during CPackDeb run.
7977
7978
7979       CPACK_DEBIAN_PACKAGE_DEPENDS
7980                   Mandatory : NO
7981                   Default   : -
7982                   May be used to set deb dependencies.
7983
7984
7985       CPACK_DEBIAN_PACKAGE_DESCRIPTION
7986                   Mandatory : YES
7987                   Default   : CPACK_PACKAGE_DESCRIPTION_SUMMARY
7988                   The debian package description
7989
7990
7991       CPACK_DEBIAN_PACKAGE_ENHANCES
7992                   Mandatory : NO
7993                   Default   : -
7994                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
7995                   This field is similar to Suggests but works in the opposite direction.
7996                   It is used to declare that a package can enhance the functionality of another package.
7997
7998
7999       CPACK_DEBIAN_PACKAGE_HOMEPAGE
8000                   Mandatory : NO
8001                   Default   : -
8002                   The URL of the web site for this package, preferably (when applicable) the
8003                   site from which the original source can be obtained and any additional
8004                   upstream documentation or information may be found.
8005                   The content of this field is a simple URL without any surrounding
8006                   characters such as <>.
8007
8008
8009       CPACK_DEBIAN_PACKAGE_MAINTAINER
8010                   Mandatory : YES
8011                   Default   : CPACK_PACKAGE_CONTACT
8012                   The debian package maintainer
8013
8014
8015       CPACK_DEBIAN_PACKAGE_NAME
8016                   Mandatory : YES
8017                   Default   : CPACK_PACKAGE_NAME (lower case)
8018                   The debian package summary
8019
8020
8021       CPACK_DEBIAN_PACKAGE_PREDEPENDS
8022                   Mandatory : NO
8023                   Default   : -
8024                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
8025                   This field is like Depends, except that it also forces dpkg to complete installation of
8026                   the packages named before even starting the installation of the package which declares
8027                   the pre-dependency.
8028
8029
8030       CPACK_DEBIAN_PACKAGE_PRIORITY
8031                   Mandatory : YES
8032                   Default   : 'optional'
8033                   The debian package priority
8034
8035
8036       CPACK_DEBIAN_PACKAGE_PROVIDES
8037                   Mandatory : NO
8038                   Default   : -
8039                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
8040                   A virtual package is one which appears in the Provides control field of another package.
8041
8042
8043       CPACK_DEBIAN_PACKAGE_RECOMMENDS
8044                   Mandatory : NO
8045                   Default   : -
8046                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
8047                   Allows packages to declare a strong, but not absolute, dependency on other packages.
8048
8049
8050       CPACK_DEBIAN_PACKAGE_REPLACES
8051                   Mandatory : NO
8052                   Default   : -
8053                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
8054                   Packages can declare in their control file that they should overwrite
8055                   files in certain other packages, or completely replace other packages.
8056
8057
8058       CPACK_DEBIAN_PACKAGE_SECTION
8059                   Mandatory : YES
8060                   Default   : 'devel'
8061                   The debian package section
8062
8063
8064       CPACK_DEBIAN_PACKAGE_SHLIBDEPS
8065                   Mandatory : NO
8066                   Default   : OFF
8067                   May be set to ON in order to use dpkg-shlibdeps to generate
8068                   better package dependency list.
8069                   You may need set CMAKE_INSTALL_RPATH toi appropriate value
8070                   if you use this feature, because if you don't dpkg-shlibdeps
8071                   may fail to find your own shared libs.
8072                   See http://www.cmake.org/Wiki/CMake_RPATH_handling.
8073
8074
8075       CPACK_DEBIAN_PACKAGE_SUGGESTS
8076                   Mandatory : NO
8077                   Default   : -
8078                   see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
8079                   Allows packages to declare a suggested package install grouping.
8080
8081
8082       CPACK_DEBIAN_PACKAGE_VERSION
8083                   Mandatory : YES
8084                   Default   : CPACK_PACKAGE_VERSION
8085                   The debian package version
8086
8087

VARIABLES SPECIFIC TO CPACK DRAGNDROP GENERATOR

8089       CPACK_COMMAND_HDIUTIL
8090              Path to the hdiutil(1) command used to  operate  on  disk  image
8091              files on Mac OS X.
8092
8093              This variable can be used to override the automatically detected
8094              command (or specify its location if the auto-detection fails  to
8095              find it.)
8096
8097
8098       CPACK_COMMAND_REZ
8099              Path  to  the Rez(1) command used to compile resources on Mac OS
8100              X.
8101
8102              This variable can be used to override the automatically detected
8103              command  (or specify its location if the auto-detection fails to
8104              find it.)
8105
8106
8107       CPACK_COMMAND_SETFILE
8108              Path to the SetFile(1) command used to set  extended  attributes
8109              on files and directories on Mac OS X.
8110
8111              This variable can be used to override the automatically detected
8112              command (or specify its location if the auto-detection fails  to
8113              find it.)
8114
8115
8116       CPACK_DMG_BACKGROUND_IMAGE
8117              Path to a background image file
8118
8119              This  file  will be used as the background for the Finder Window
8120              when the disk image is opened.  By default no  background  image
8121              is  set. The background image is applied after applying the cus‐
8122              tom .DS_Store file.
8123
8124
8125       CPACK_DMG_DS_STORE
8126              Path to a custom DS_Store file
8127
8128              This .DS_Store file e.g. can be used to specify the Finder  win‐
8129              dow  position/geometry  and  layout  (such  as  hidden toolbars,
8130              placement of the icons etc.). This file has to be  generated  by
8131              the  Finder (either manually or through OSA-script) using a nor‐
8132              mal folder from which the .DS_Store file can then be extracted.
8133
8134
8135       CPACK_DMG_FORMAT
8136              The disk image format
8137
8138              Common values are UDRO (UDIF read-only),  UDZO  (UDIF  zlib-com‐
8139              pressed)  or  UDBZ  (UDIF bzip2-compressed). Refer to hdiutil(1)
8140              for more information on other available formats.
8141
8142
8143       CPACK_DMG_VOLUME_NAME
8144              The volume name of the generated disk image.
8145
8146              Defaults to CPACK_PACKAGE_FILE_NAME.
8147
8148

VARIABLES SPECIFIC TO CPACK NSIS GENERATOR

8150       CPACK_NSIS_COMPRESSOR
8151              The arguments that will be passed to the NSIS SetCompressor com‐
8152              mand.
8153
8154
8155       CPACK_NSIS_CONTACT
8156              Contact information for questions and comments about the instal‐
8157              lation process.
8158
8159
8160       CPACK_NSIS_CREATE_ICONS_EXTRA
8161              Additional NSIS commands for creating start menu shortcuts.
8162
8163
8164       CPACK_NSIS_DELETE_ICONS_EXTRA
8165              Additional NSIS commands to uninstall start menu shortcuts.
8166
8167
8168       CPACK_NSIS_DISPLAY_NAME
8169              The display name string that appears in   the Windows Add/Remove
8170              Program control panel
8171
8172
8173
8174       CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL
8175              Ask about uninstalling previous versions first.
8176
8177                 If this is set to "ON", then an installer will look for previous
8178                 installed versions and if one is found, ask the user whether to
8179                 uninstall it before proceeding with the install.
8180
8181
8182       CPACK_NSIS_EXECUTABLES_DIRECTORY
8183              Creating  NSIS  start  menu links assumes that they are in 'bin'
8184              unless this variable is set.
8185
8186                 For example, you would set this to 'exec' if your executables are
8187                 in an exec directory.
8188
8189
8190       CPACK_NSIS_EXTRA_INSTALL_COMMANDS
8191              Extra NSIS commands that   will be  added  to  the  end  of  the
8192              install Section, after your
8193
8194
8195               install tree is available on the target system.
8196
8197
8198       CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS
8199              Extra NSIS commands that   will be added to the beginning of the
8200              install Section, before your
8201
8202
8203               install tree is available on the target system.
8204
8205
8206       CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS
8207              Extra NSIS commands that will   be added to the  uninstall  Sec‐
8208              tion, before your install tree is
8209
8210
8211               removed from the target system.
8212
8213
8214       CPACK_NSIS_HELP_LINK
8215              URL to a web site providing assistance in installing your appli‐
8216              cation.
8217
8218
8219       CPACK_NSIS_INSTALLED_ICON_NAME
8220              A path to the executable that contains the installer icon.
8221
8222
8223       CPACK_NSIS_INSTALLER_MUI_ICON_CODE
8224              undocumented
8225
8226
8227       CPACK_NSIS_INSTALL_ROOT
8228              The default installation directory presented to the end user  by
8229              the NSIS installer is under this root dir.
8230
8231              The full   directory presented to the end user is:
8232
8233
8234                 ${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}
8235
8236
8237       CPACK_NSIS_MENU_LINKS
8238              Specify links in [application] menu
8239
8240                 This should contain a list of pair "link" "link name". The link
8241                 may be an URL or a path relative to installation prefix.
8242                 Like:
8243                   set(CPACK_NSIS_MENU_LINKS
8244                       "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" "CMake Help"
8245                       "http://www.cmake.org" "CMake Web Site")
8246
8247
8248       CPACK_NSIS_MODIFY_PATH
8249              Modify PATH toggle
8250
8251                 If this is set to "ON", then an extra page
8252                 will appear in the installer that will allow the user to choose
8253                 whether the program directory should be added to the system PATH
8254                 variable.
8255
8256
8257       CPACK_NSIS_MUI_FINISHPAGE_RUN
8258              Specify an executable to add an option to run on the finish page
8259              of the NSIS installer.
8260
8261
8262       CPACK_NSIS_MUI_ICON
8263              An icon filename
8264
8265                 The name of a *.ico file used as the main icon for the generated
8266                 install program.
8267
8268
8269       CPACK_NSIS_MUI_UNIICON
8270              An icon filename
8271
8272                 The name of a *.ico file used as the main icon for the generated
8273                 uninstall program.
8274
8275
8276       CPACK_NSIS_PACKAGE_NAME
8277              The title displayed at the top of the installer.
8278
8279
8280       CPACK_NSIS_URL_INFO_ABOUT
8281              URL to a web site providing more information about your applica‐
8282              tion.
8283
8284

VARIABLES SPECIFIC TO CPACK PACKAGEMAKER GENERATOR

8286       CPACK_OSX_PACKAGE_VERSION
8287              The  version of Mac OS X that the resulting PackageMaker archive
8288              should be compatible with.
8289
8290              Different versions of Mac OS X support different  features.  For
8291              example, CPack can only build component-based installers for Mac
8292              OS X 10.4 or newer, and can only build installers that  download
8293              component son-the-fly for Mac OS X 10.5 or newer. If left blank,
8294              this value will be set to the minimum version of Mac OS  X  that
8295              supports the requested features. Set this variable to some value
8296              (e.g., 10.4) only if you want to guarantee that  your  installer
8297              will  work  on  that version of Mac OS X, and don't mind missing
8298              extra features available in the installer  shipping  with  later
8299              versions of Mac OS X.
8300
8301

VARIABLES SPECIFIC TO CPACK RPM GENERATOR

8303       CPACK_RPM_CHANGELOG_FILE
8304              RPM changelog file
8305
8306                   Mandatory : NO
8307                   Default   : -
8308                   May be used to embed a changelog in the spec file.
8309                   The refered file will be read and directly put after the %changelog
8310                   section.
8311
8312
8313       CPACK_RPM_COMPRESSION_TYPE
8314              RPM compression type
8315
8316                   Mandatory : NO
8317                   Default   : -
8318                   May be used to override RPM compression type to be used
8319                   to build the RPM. For example some Linux distribution now default
8320                   to lzma or xz compression whereas older cannot use such RPM.
8321                   Using this one can enforce compression type to be used.
8322                   Possible value are: lzma, xz, bzip2 and gzip.
8323
8324
8325       CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST
8326              list of path to be excluded
8327
8328                   Mandatory : NO
8329                   Default   : /etc /etc/init.d /usr /usr/share /usr/share/doc /usr/bin /usr/lib /usr/lib64 /usr/include
8330                   May be used to exclude path (directories or files) from the auto-generated
8331                   list of paths discovered by CPack RPM. The defaut value contains a reasonable
8332                   set of values if the variable is not defined by the user. If the variable
8333                   is defined by the user then CPackRPM will NOT any of the default path.
8334                   If you want to add some path to the default list then you can use
8335                   CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION variable.
8336
8337
8338       CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION
8339              additional list of path to be excluded
8340
8341                   Mandatory : NO
8342                   Default   : -
8343                   May be used to add more exclude path (directories or files) from the initial
8344                   default list of excluded paths. See CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST.
8345
8346
8347       CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE
8348              Spec file template
8349
8350                   Mandatory : NO
8351                   Default   : -
8352                   If set CPack will generate a template for USER specified binary
8353                   spec file and stop with an error. For example launch CPack like this
8354                   cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM
8355                   The user may then use this file in order to hand-craft is own
8356                   binary spec file which may be used with CPACK_RPM_USER_BINARY_SPECFILE.
8357
8358
8359       CPACK_RPM_PACKAGE_ARCHITECTURE
8360              The RPM package architecture
8361
8362                   Mandatory : NO
8363                   Default   : -
8364                   This may be set to "noarch" if you
8365                   know you are building a noarch package.
8366
8367
8368       CPACK_RPM_PACKAGE_DEBUG
8369              Toggle CPackRPM debug output
8370
8371                   Mandatory : NO
8372                   Default   : -
8373                   May be set when invoking cpack in order to trace debug information
8374                   during CPack RPM run. For example you may launch CPack like this
8375                   cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM
8376
8377
8378       CPACK_RPM_PACKAGE_DESCRIPTION
8379              RPM package description
8380
8381                   Mandatory : YES
8382                   Default   : CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available"
8383
8384
8385       CPACK_RPM_PACKAGE_GROUP
8386              The RPM package group
8387
8388                   Mandatory : YES
8389                   Default   : "unknown"
8390
8391
8392       CPACK_RPM_PACKAGE_LICENSE
8393              The RPM package license policy
8394
8395                   Mandatory : YES
8396                   Default   : "unknown"
8397
8398
8399       CPACK_RPM_PACKAGE_NAME
8400              The RPM package name
8401
8402                   Mandatory : YES
8403                   Default   : CPACK_PACKAGE_NAME
8404
8405
8406       CPACK_RPM_PACKAGE_OBSOLETES
8407              RPM spec obsoletes field
8408
8409                   Mandatory : NO
8410                   Default   : -
8411                   May be used to set RPM packages that are obsoleted by this one.
8412
8413
8414       CPACK_RPM_PACKAGE_PROVIDES
8415              RPM spec provides field
8416
8417                   Mandatory : NO
8418                   Default   : -
8419                   May be used to set RPM dependencies (provides).
8420                   The provided package list of an RPM file could be printed with
8421                   rpm -qp --provides file.rpm
8422
8423
8424       CPACK_RPM_PACKAGE_RELEASE
8425              The RPM package release
8426
8427                   Mandatory : YES
8428                   Default   : 1
8429                   This is the numbering of the RPM package
8430                   itself, i.e. the version of the packaging and not the version of the
8431                   content (see CPACK_RPM_PACKAGE_VERSION). One may change the default
8432                   value if the previous packaging was buggy and/or you want to put here
8433                   a fancy Linux distro specific numbering.
8434
8435
8436       CPACK_RPM_PACKAGE_RELOCATABLE
8437              build a relocatable RPM
8438
8439                   Mandatory : NO
8440                   Default   : CPACK_PACKAGE_RELOCATABLE
8441                   If this variable is set to TRUE or ON CPackRPM will try
8442                   to build a relocatable RPM package. A relocatable RPM may
8443                   be installed using rpm --prefix or --relocate in order to
8444                   install it at an alternate place see rpm(8).
8445                   Note that currently this may fail if CPACK_SET_DESTDIR is set to ON.
8446                   If CPACK_SET_DESTDIR is set then you will get a warning message
8447                   but if there is file installed with absolute path you'll get
8448                   unexpected behavior.
8449
8450
8451       CPACK_RPM_PACKAGE_REQUIRES
8452              RPM spec requires field
8453
8454                   Mandatory : NO
8455                   Default   : -
8456                   May be used to set RPM dependencies (requires).
8457                   Note that you must enclose the complete requires string between quotes,
8458                   for example:
8459                   set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")
8460                   The required package list of an RPM file could be printed with
8461                   rpm -qp --requires file.rpm
8462
8463
8464       CPACK_RPM_PACKAGE_SUGGESTS
8465              RPM spec suggest field
8466
8467                   Mandatory : NO
8468                   Default   : -
8469                   May be used to set weak RPM dependencies (suggests).
8470                   Note that you must enclose the complete requires string between quotes.
8471
8472
8473       CPACK_RPM_PACKAGE_SUMMARY
8474              The RPM package summary
8475
8476                   Mandatory : YES
8477                   Default   : CPACK_PACKAGE_DESCRIPTION_SUMMARY
8478
8479
8480       CPACK_RPM_PACKAGE_URL
8481              The projects URL
8482
8483                   Mandatory : NO
8484                   Default   : -
8485
8486
8487       CPACK_RPM_PACKAGE_VENDOR
8488              The RPM package vendor
8489
8490                   Mandatory : YES
8491                   Default   : CPACK_PACKAGE_VENDOR if set or "unknown"
8492
8493
8494       CPACK_RPM_PACKAGE_VERSION
8495              The RPM package version
8496
8497                   Mandatory : YES
8498                   Default   : CPACK_PACKAGE_VERSION
8499
8500
8501       CPACK_RPM_POST_INSTALL_SCRIPT_FILE
8502                CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
8503                   Mandatory : NO
8504                   Default   : -
8505                   May be used to embed a post (un)installation script in the spec file.
8506                   The refered script file(s) will be read and directly
8507                   put after the %post or %postun section
8508                   If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
8509                   each component can be overridden with
8510                   CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE and
8511                   CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE
8512                   One may verify which scriptlet has been included with
8513                    rpm -qp --scripts  package.rpm
8514
8515
8516       CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
8517                CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
8518                   Mandatory : NO
8519                   Default   : -
8520                   May be used to embed a pre (un)installation script in the spec file.
8521                   The refered script file(s) will be read and directly
8522                   put after the %pre or %preun section
8523                   If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
8524                   each component can be overridden with
8525                   CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE and
8526                   CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE
8527                   One may verify which scriptlet has been included with
8528                    rpm -qp --scripts  package.rpm
8529
8530
8531       CPACK_RPM_SPEC_INSTALL_POST
8532              [deprecated]
8533
8534                   Mandatory : NO
8535                   Default   : -
8536                   This way of specifying post-install script is deprecated use
8537                   CPACK_RPM_POST_INSTALL_SCRIPT_FILE
8538                   May be used to set an RPM post-install command inside the spec file.
8539                   For example setting it to "/bin/true" may be used to prevent
8540                   rpmbuild to strip binaries.
8541
8542
8543       CPACK_RPM_SPEC_MORE_DEFINE
8544              RPM extended spec definitions lines
8545
8546                   Mandatory : NO
8547                   Default   : -
8548                   May be used to add any %define lines to the generated spec file.
8549
8550
8551       CPACK_RPM_USER_BINARY_SPECFILE
8552              A user provided spec file
8553
8554                   Mandatory : NO
8555                   Default   : -
8556                   May be set by the user in order to specify a USER binary spec file
8557                   to be used by CPackRPM instead of generating the file.
8558                   The specified file will be processed by configure_file( @ONLY).
8559                   One can provide a component specific file by setting
8560                   CPACK_RPM_<componentName>_USER_BINARY_SPECFILE.
8561
8562
8563       CPACK_RPM_USER_FILELIST
8564                CPACK_RPM_<COMPONENT>_USER_FILELIST
8565                   Mandatory : NO
8566                   Default   : -
8567                   May be used to explicitly specify %(<directive>) file line
8568                   in the spec file. Like %config(noreplace) or any other directive
8569                   that be found in the %files section. Since CPackRPM is generating
8570                   the list of files (and directories) the user specified files of
8571                   the CPACK_RPM_<COMPONENT>_USER_FILELIST list will be removed from the generated list.
8572
8573

VARIABLES SPECIFIC TO CPACK WIX GENERATOR

8575       CPACK_WIX_CULTURES
8576              Language(s) of the installer
8577
8578              Languages  are compiled into the WixUI extension library. To use
8579              them, simply provide the name of the culture.   If  you  specify
8580              more  than one culture identifier in a comma or semicolon delim‐
8581              ited list, the first one that is found will be  used.   You  can
8582              find  a  list  of  supported  languages  at:  http://wix.source
8583              forge.net/manual-wix3/WixUI_localization.htm
8584
8585
8586
8587       CPACK_WIX_LICENSE_RTF
8588              RTF License File
8589
8590              If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is  used
8591              as-is.
8592
8593
8594              If  CPACK_RESOURCE_FILE_LICENSE  has  an  .txt  extension  it is
8595              implicitly converted to RTF by the WiX Generator.
8596
8597
8598              With CPACK_WIX_LICENSE_RTF you can  override  the  license  file
8599              used by the WiX Generator in case CPACK_RESOURCE_FILE_LICENSE is
8600              in an unsupported format or the .txt -> .rtf conversion does not
8601              work as expected.
8602
8603
8604
8605       CPACK_WIX_PRODUCT_GUID
8606              Product GUID (Product/@Id)
8607
8608              Will be automatically generated unless explicitly provided.
8609
8610
8611              If  explicitly provided this will set the Product Id of your in‐
8612              staller.
8613
8614
8615              The installer will abort if it detects a pre-existing  installa‐
8616              tion that uses the same GUID.
8617
8618
8619              The    GUID    shall    use    the    syntax    described    for
8620              CPACK_WIX_UPGRADE_GUID.
8621
8622
8623       CPACK_WIX_PRODUCT_ICON
8624              The Icon shown next to the program name in Add/Remove programs
8625
8626              If set, this icon is used in place of the default icon.
8627
8628
8629
8630       CPACK_WIX_PROGRAM_MENU_FOLDER
8631              Start menu folder name for launcher
8632
8633              If this variable  is  not  set,  it  will  be  initialized  with
8634              CPACK_PACKAGE_NAME
8635
8636
8637
8638       CPACK_WIX_TEMPLATE
8639              Template file for WiX generation
8640
8641              If  this variable is set, the specified template will be used to
8642              generate the WiX wxs file. This should be used if  further  cus‐
8643              tomization of the output is required.
8644
8645
8646              If  this  variable is not set, the default MSI template included
8647              with CMake will be used.
8648
8649
8650
8651       CPACK_WIX_UI_BANNER
8652              The bitmap will appear at the top of all installer  pages  other
8653              than the welcome and completion dialogs
8654
8655              If set, this image will replace the default banner image.
8656
8657
8658              This image must be 493 by 58 pixels.
8659
8660
8661
8662       CPACK_WIX_UI_DIALOG
8663              Background bitmap used on the welcome and completion dialogs
8664
8665              If  this variable is set, the installer will replace the default
8666              dialog image.
8667
8668
8669              This image must be 493 by 312 pixels.
8670
8671
8672
8673       CPACK_WIX_UPGRADE_GUID
8674              Upgrade GUID (Product/@UpgradeCode)
8675
8676              Will be automatically generated unless explicitly provided.
8677
8678
8679              It should be explicitly set to a  constant  generated  gloabally
8680              unique  identifier  (GUID)  to  allow your installers to replace
8681              existing installations that use the same GUID.
8682
8683
8684              You may for example explicitly set this variable in your  CMake‐
8685              Lists.txt  to the value that has been generated per default. You
8686              should not use GUIDs that you did not generate yourself or which
8687              may belong to other projects.
8688
8689
8690              A   GUID   shall   have   the  following  fixed  length  syntax:
8691              XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
8692
8693
8694                (each X represents an uppercase hexadecimal digit)
8695
8696

VARIABLES THAT CONTROL THE BUILD

8698       CMAKE_<CONFIG>_POSTFIX
8699              Default filename postfix for libraries under configuration <CON‐
8700              FIG>.
8701
8702              When  a  non-executable  target  is created its <CONFIG>_POSTFIX
8703              target property is initialized with the value of  this  variable
8704              if it is set.
8705
8706
8707       CMAKE_<LANG>_VISIBILITY_PRESET
8708              Default value for <LANG>_VISIBILITY_PRESET of targets.
8709
8710              This variable is used to initialize the <LANG>_VISIBILITY_PRESET
8711              property on all the targets.  See that target property for addi‐
8712              tional information.
8713
8714
8715       CMAKE_ARCHIVE_OUTPUT_DIRECTORY
8716              Where to put all the ARCHIVE targets when built.
8717
8718              This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY
8719              property on all the targets.  See that target property for addi‐
8720              tional information.
8721
8722
8723       CMAKE_AUTOMOC
8724              Whether to handle moc automatically for Qt targets.
8725
8726              This  variable is used to initialize the AUTOMOC property on all
8727              the targets.  See that target property for  additional  informa‐
8728              tion.
8729
8730
8731       CMAKE_AUTOMOC_MOC_OPTIONS
8732              Additional  options  for moc when using automoc (see CMAKE_AUTO‐
8733              MOC).
8734
8735              This variable is  used  to  initialize  the  AUTOMOC_MOC_OPTIONS
8736              property on all the targets.  See that target property for addi‐
8737              tional information.
8738
8739
8740       CMAKE_BUILD_WITH_INSTALL_RPATH
8741              Use the install path for the RPATH
8742
8743              Normally CMake uses the build tree for the RPATH  when  building
8744              executables  etc on systems that use RPATH. When the software is
8745              installed the executables etc are relinked by CMake to have  the
8746              install RPATH. If this variable is set to true then the software
8747              is always built with the install path for the RPATH and does not
8748              need to be relinked when installed.
8749
8750
8751       CMAKE_DEBUG_POSTFIX
8752              See variable CMAKE_<CONFIG>_POSTFIX.
8753
8754              This  variable is a special case of the more-general CMAKE_<CON‐
8755              FIG>_POSTFIX variable for the DEBUG configuration.
8756
8757
8758       CMAKE_EXE_LINKER_FLAGS
8759              Linker flags to be used to create executables.
8760
8761              These flags will be used by the linker  when  creating  an  exe‐
8762              cutable.
8763
8764
8765       CMAKE_EXE_LINKER_FLAGS_<CONFIG>
8766              Flags to be used when linking an executable.
8767
8768              Same  as  CMAKE_C_FLAGS_*  but  used by the linker when creating
8769              executables.
8770
8771
8772       CMAKE_Fortran_FORMAT
8773              Set to FIXED or FREE to indicate the Fortran source layout.
8774
8775              This variable is used to initialize the Fortran_FORMAT  property
8776              on  all  the  targets.   See that target property for additional
8777              information.
8778
8779
8780       CMAKE_Fortran_MODULE_DIRECTORY
8781              Fortran module output directory.
8782
8783              This variable is used to initialize the Fortran_MODULE_DIRECTORY
8784              property on all the targets.  See that target property for addi‐
8785              tional information.
8786
8787
8788       CMAKE_GNUtoMS
8789              Convert GNU import libraries (.dll.a) to MS format (.lib).
8790
8791              This variable is used to initialize the GNUtoMS property on tar‐
8792              gets  when they are created.  See that target property for addi‐
8793              tional information.
8794
8795
8796       CMAKE_INCLUDE_CURRENT_DIR
8797              Automatically add the current source- and build  directories  to
8798              the include path.
8799
8800              If  this  variable  is enabled, CMake automatically adds in each
8801              directory    ${CMAKE_CURRENT_SOURCE_DIR}    and     ${CMAKE_CUR‐
8802              RENT_BINARY_DIR}  to  the include path for this directory. These
8803              additional include directories do not propagate down  to  subdi‐
8804              rectories. This is useful mainly for out-of-source builds, where
8805              files generated into  the  build  tree  are  included  by  files
8806              located in the source tree.
8807
8808
8809              By default CMAKE_INCLUDE_CURRENT_DIR is OFF.
8810
8811
8812       CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
8813              Automatically  add  the current source- and build directories to
8814              the INTERFACE_INCLUDE_DIRECTORIES.
8815
8816              If this variable is enabled, CMake automatically adds  for  each
8817              shared  library target, static library target, module target and
8818              executable target, ${CMAKE_CURRENT_SOURCE_DIR} and  ${CMAKE_CUR‐
8819              RENT_BINARY_DIR} to the INTERFACE_INCLUDE_DIRECTORIES.By default
8820              CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE is OFF.
8821
8822
8823       CMAKE_INSTALL_NAME_DIR
8824              Mac OS X directory name for installed targets.
8825
8826              CMAKE_INSTALL_NAME_DIR    is    used    to    initialize     the
8827              INSTALL_NAME_DIR  property on all targets. See that target prop‐
8828              erty for more information.
8829
8830
8831       CMAKE_INSTALL_RPATH
8832              The rpath to use for installed targets.
8833
8834              A semicolon-separated  list  specifying  the  rpath  to  use  in
8835              installed targets (for platforms that support it).  This is used
8836              to initialize the target property INSTALL_RPATH for all targets.
8837
8838
8839       CMAKE_INSTALL_RPATH_USE_LINK_PATH
8840              Add paths to linker search and installed rpath.
8841
8842              CMAKE_INSTALL_RPATH_USE_LINK_PATH is a boolean that  if  set  to
8843              true  will append directories in the linker search path and out‐
8844              side the project to the INSTALL_RPATH.  This is used to initial‐
8845              ize the target property INSTALL_RPATH_USE_LINK_PATH for all tar‐
8846              gets.
8847
8848
8849       CMAKE_LIBRARY_OUTPUT_DIRECTORY
8850              Where to put all the LIBRARY targets when built.
8851
8852              This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY
8853              property on all the targets.  See that target property for addi‐
8854              tional information.
8855
8856
8857       CMAKE_LIBRARY_PATH_FLAG
8858              The flag to be used to add a library search path to a compiler.
8859
8860              The flag will be used to specify a library directory to the com‐
8861              piler.  On most compilers this is "-L".
8862
8863
8864       CMAKE_LINK_DEF_FILE_FLAG
8865              Linker flag to be used to specify a .def file for dll creation.
8866
8867              The  flag will be used to add a .def file when creating a dll on
8868              Windows; this is only defined on Windows.
8869
8870
8871       CMAKE_LINK_DEPENDS_NO_SHARED
8872              Whether to skip link dependencies on shared library files.
8873
8874              This variable initializes the LINK_DEPENDS_NO_SHARED property on
8875              targets  when  they  are  created.  See that target property for
8876              additional information.
8877
8878
8879       CMAKE_LINK_INTERFACE_LIBRARIES
8880              Default value for LINK_INTERFACE_LIBRARIES of targets.
8881
8882              This variable is used to initialize the LINK_INTERFACE_LIBRARIES
8883              property on all the targets.  See that target property for addi‐
8884              tional information.
8885
8886
8887       CMAKE_LINK_LIBRARY_FILE_FLAG
8888              Flag to be used to link a library specified by  a  path  to  its
8889              file.
8890
8891              The flag will be used before a library file path is given to the
8892              linker.  This is needed only on very few platforms.
8893
8894
8895       CMAKE_LINK_LIBRARY_FLAG
8896              Flag to be used to link a library into an executable.
8897
8898              The flag will be used to specify a library to link  to  an  exe‐
8899              cutable.  On most compilers this is "-l".
8900
8901
8902       CMAKE_MACOSX_BUNDLE
8903              Default value for MACOSX_BUNDLE of targets.
8904
8905              This  variable  is used to initialize the MACOSX_BUNDLE property
8906              on all the targets.  See that  target  property  for  additional
8907              information.
8908
8909
8910       CMAKE_MODULE_LINKER_FLAGS
8911              Linker flags to be used to create modules.
8912
8913              These flags will be used by the linker when creating a module.
8914
8915
8916       CMAKE_MODULE_LINKER_FLAGS_<CONFIG>
8917              Flags to be used when linking a module.
8918
8919              Same  as  CMAKE_C_FLAGS_*  but  used by the linker when creating
8920              modules.
8921
8922
8923       CMAKE_NO_BUILTIN_CHRPATH
8924              Do not use the builtin ELF editor to fix RPATHs on installation.
8925
8926              When an ELF binary needs to have a different RPATH after instal‐
8927              lation than it does in the build tree, CMake uses a builtin edi‐
8928              tor to change the RPATH in the installed copy.  If this variable
8929              is  set to true then CMake will relink the binary before instal‐
8930              lation instead of using its builtin editor.
8931
8932
8933       CMAKE_PDB_OUTPUT_DIRECTORY
8934              Where to put all the MS debug symbol files from linker.
8935
8936              This variable is used  to  initialize  the  PDB_OUTPUT_DIRECTORY
8937              property on all the targets.  See that target property for addi‐
8938              tional information.
8939
8940
8941       CMAKE_POSITION_INDEPENDENT_CODE
8942              Default value for POSITION_INDEPENDENT_CODE of targets.
8943
8944              This  variable  is  used  to  initialize  the  POSITION_INDEPEN‐
8945              DENT_CODE property on all the targets.  See that target property
8946              for additional information.
8947
8948
8949       CMAKE_RUNTIME_OUTPUT_DIRECTORY
8950              Where to put all the RUNTIME targets when built.
8951
8952              This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY
8953              property on all the targets.  See that target property for addi‐
8954              tional information.
8955
8956
8957       CMAKE_SHARED_LINKER_FLAGS
8958              Linker flags to be used to create shared libraries.
8959
8960              These flags will be used by the linker when  creating  a  shared
8961              library.
8962
8963
8964       CMAKE_SHARED_LINKER_FLAGS_<CONFIG>
8965              Flags to be used when linking a shared library.
8966
8967              Same  as  CMAKE_C_FLAGS_*  but  used by the linker when creating
8968              shared libraries.
8969
8970
8971       CMAKE_SKIP_BUILD_RPATH
8972              Do not include RPATHs in the build tree.
8973
8974              Normally CMake uses the build tree for the RPATH  when  building
8975              executables  etc on systems that use RPATH. When the software is
8976              installed the executables etc are relinked by CMake to have  the
8977              install RPATH. If this variable is set to true then the software
8978              is always built with no RPATH.
8979
8980
8981       CMAKE_SKIP_INSTALL_RPATH
8982              Do not include RPATHs in the install tree.
8983
8984              Normally CMake uses the build tree for the RPATH  when  building
8985              executables  etc on systems that use RPATH. When the software is
8986              installed the executables etc are relinked by CMake to have  the
8987              install RPATH. If this variable is set to true then the software
8988              is always installed without RPATH, even if RPATH is enabled when
8989              building.  This can be useful for example to allow running tests
8990              from the build directory with RPATH enabled before the installa‐
8991              tion  step.   To omit RPATH in both the build and install steps,
8992              use CMAKE_SKIP_RPATH instead.
8993
8994
8995       CMAKE_STATIC_LINKER_FLAGS
8996              Linker flags to be used to create static libraries.
8997
8998              These flags will be used by the linker when  creating  a  static
8999              library.
9000
9001
9002       CMAKE_STATIC_LINKER_FLAGS_<CONFIG>
9003              Flags to be used when linking a static library.
9004
9005              Same  as  CMAKE_C_FLAGS_*  but  used by the linker when creating
9006              static libraries.
9007
9008
9009       CMAKE_TRY_COMPILE_CONFIGURATION
9010              Build configuration used for try_compile and try_run projects.
9011
9012              Projects  built  by  try_compile  and  try_run  are  built  syn‐
9013              chronously  during  the  CMake  configuration step.  Therefore a
9014              specific build configuration must be chosen even if  the  gener‐
9015              ated build system supports multiple configurations.
9016
9017
9018       CMAKE_USE_RELATIVE_PATHS
9019              Use relative paths (May not work!).
9020
9021              If  this  is  set  to  TRUE,  then CMake will use relative paths
9022              between the source and binary tree.  This option does  not  work
9023              for  more complicated projects, and relative paths are used when
9024              possible.  In general, it is not possible to move  CMake  gener‐
9025              ated  makefiles  to a different location regardless of the value
9026              of this variable.
9027
9028
9029       CMAKE_VISIBILITY_INLINES_HIDDEN
9030              Default value for VISIBILITY_INLINES_HIDDEN of targets.
9031
9032              This variable is used to initialize the  VISIBILITY_INLINES_HID‐
9033              DEN  property  on all the targets.  See that target property for
9034              additional information.
9035
9036
9037       CMAKE_WIN32_EXECUTABLE
9038              Default value for WIN32_EXECUTABLE of targets.
9039
9040              This variable is used to initialize the  WIN32_EXECUTABLE  prop‐
9041              erty  on  all  the  targets.  See that target property for addi‐
9042              tional information.
9043
9044
9045       EXECUTABLE_OUTPUT_PATH
9046              Old executable location variable.
9047
9048              The target  property  RUNTIME_OUTPUT_DIRECTORY  supercedes  this
9049              variable for a target if it is set.  Executable targets are oth‐
9050              erwise placed in this directory.
9051
9052
9053       LIBRARY_OUTPUT_PATH
9054              Old library location variable.
9055
9056              The  target  properties  ARCHIVE_OUTPUT_DIRECTORY,  LIBRARY_OUT‐
9057              PUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY supercede this vari‐
9058              able for a target if they are set.  Library targets  are  other‐
9059              wise placed in this directory.
9060
9061

VARIABLES THAT PROVIDE INFORMATION

9063       CMAKE_AR
9064              Name of archiving tool for static libraries.
9065
9066              This  specifies  the name of the program that creates archive or
9067              static libraries.
9068
9069
9070       CMAKE_ARGC
9071              Number of command line arguments passed to CMake in script mode.
9072
9073              When run in -P script mode, CMake sets this variable to the num‐
9074              ber of command line arguments. See also CMAKE_ARGV0, 1, 2 ...
9075
9076
9077       CMAKE_ARGV0
9078              Command line argument passed to CMake in script mode.
9079
9080              When  run  in  -P  script  mode, CMake sets this variable to the
9081              first command line argument.  It  then  also  sets  CMAKE_ARGV1,
9082              CMAKE_ARGV2,  ...  and  so  on, up to the number of command line
9083              arguments given. See also CMAKE_ARGC.
9084
9085
9086       CMAKE_BINARY_DIR
9087              The path to the top level of the build tree.
9088
9089              This is the full path to the top  level  of  the  current  CMake
9090              build  tree.  For  an in-source build, this would be the same as
9091              CMAKE_SOURCE_DIR.
9092
9093
9094       CMAKE_BUILD_TOOL
9095              Tool used for the actual build process.
9096
9097              This variable is set to the program that will be needed to build
9098              the output of CMake.   If the generator selected was Visual Stu‐
9099              dio 6, the CMAKE_BUILD_TOOL will be set to msdev, for Unix Make‐
9100              files  it  will be set to make or gmake, and for Visual Studio 7
9101              it set to devenv.  For NMake Makefiles the value is nmake.  This
9102              can be useful for adding special flags and commands based on the
9103              final build environment.
9104
9105
9106       CMAKE_CACHEFILE_DIR
9107              The directory with the CMakeCache.txt file.
9108
9109              This is the full path to  the  directory  that  has  the  CMake‐
9110              Cache.txt file in it.  This is the same as CMAKE_BINARY_DIR.
9111
9112
9113       CMAKE_CACHE_MAJOR_VERSION
9114              Major version of CMake used to create the CMakeCache.txt file
9115
9116              This  stores  the  major  version of CMake used to write a CMake
9117              cache file. It is only different when  a  different  version  of
9118              CMake is run on a previously created cache file.
9119
9120
9121       CMAKE_CACHE_MINOR_VERSION
9122              Minor version of CMake used to create the CMakeCache.txt file
9123
9124              This  stores  the  minor  version of CMake used to write a CMake
9125              cache file. It is only different when  a  different  version  of
9126              CMake is run on a previously created cache file.
9127
9128
9129       CMAKE_CACHE_PATCH_VERSION
9130              Patch version of CMake used to create the CMakeCache.txt file
9131
9132              This  stores  the  patch  version of CMake used to write a CMake
9133              cache file. It is only different when  a  different  version  of
9134              CMake is run on a previously created cache file.
9135
9136
9137       CMAKE_CFG_INTDIR
9138              Build-time reference to per-configuration output subdirectory.
9139
9140              For  native  build systems supporting multiple configurations in
9141              the build tree (such as Visual Studio and Xcode), the value is a
9142              reference  to  a  build-time variable specifying the name of the
9143              per-configuration output subdirectory.  On  Makefile  generators
9144              this evaluates to "." because there is only one configuration in
9145              a build tree.  Example values:
9146
9147
9148                $(IntDir)        = Visual Studio 6
9149                $(OutDir)        = Visual Studio 7, 8, 9
9150                $(Configuration) = Visual Studio 10
9151                $(CONFIGURATION) = Xcode
9152                .                = Make-based tools
9153
9154              Since these values are evaluated by  the  native  build  system,
9155              this  variable  is  suitable  only for use in command lines that
9156              will be evaluated at build time.  Example of intended usage:
9157
9158
9159                add_executable(mytool mytool.c)
9160                add_custom_command(
9161                  OUTPUT out.txt
9162                  COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool
9163                          ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt
9164                  DEPENDS mytool in.txt
9165                  )
9166                add_custom_target(drive ALL DEPENDS out.txt)
9167
9168              Note that CMAKE_CFG_INTDIR is no longer necessary for this  pur‐
9169              pose but has been left for compatibility with existing projects.
9170              Instead add_custom_command() recognizes executable target  names
9171              in      its      COMMAND      option,      so      "${CMAKE_CUR‐
9172              RENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool" can be replaced  by
9173              just "mytool".
9174
9175
9176              This  variable  is read-only.  Setting it is undefined behavior.
9177              In multi-configuration build systems the value of this  variable
9178              is  passed as the value of preprocessor symbol "CMAKE_INTDIR" to
9179              the compilation of all source files.
9180
9181
9182       CMAKE_COMMAND
9183              The full path to the cmake executable.
9184
9185              This is the full path to the CMake  executable  cmake  which  is
9186              useful from custom commands that want to use the cmake -E option
9187              for portable system commands.  (e.g. /usr/local/bin/cmake
9188
9189
9190       CMAKE_CROSSCOMPILING
9191              Is CMake currently cross compiling.
9192
9193              This variable will be set to true by CMake  if  CMake  is  cross
9194              compiling.  Specifically if the build platform is different from
9195              the target platform.
9196
9197
9198       CMAKE_CTEST_COMMAND
9199              Full path to ctest command installed with cmake.
9200
9201              This is the full path to the CTest  executable  ctest  which  is
9202              useful from custom commands that want to use the cmake -E option
9203              for portable system commands.
9204
9205
9206       CMAKE_CURRENT_BINARY_DIR
9207              The path to the binary directory currently being processed.
9208
9209              This the full path to the  build  directory  that  is  currently
9210              being processed by cmake.  Each directory added by add_subdirec‐
9211              tory will create a binary directory in the build tree, and as it
9212              is  being  processed  this  variable will be set.  For in-source
9213              builds this is the current source directory being processed.
9214
9215
9216       CMAKE_CURRENT_LIST_DIR
9217              Full directory of the listfile currently being processed.
9218
9219              As CMake processes the listfiles in your project  this  variable
9220              will  always be set to the directory where the listfile which is
9221              currently being processed (CMAKE_CURRENT_LIST_FILE) is  located.
9222              The  value has dynamic scope.  When CMake starts processing com‐
9223              mands in a source file it sets this variable  to  the  directory
9224              where this file is located.  When CMake finishes processing com‐
9225              mands from the file it restores the previous  value.   Therefore
9226              the  value  of  the  variable  inside a macro or function is the
9227              directory of the file invoking the bottom-most entry on the call
9228              stack,  not  the  directory  of the file containing the macro or
9229              function definition.
9230
9231
9232              See also CMAKE_CURRENT_LIST_FILE.
9233
9234
9235       CMAKE_CURRENT_LIST_FILE
9236              Full path to the listfile currently being processed.
9237
9238              As CMake processes the listfiles in your project  this  variable
9239              will  always  be  set to the one currently being processed.  The
9240              value has dynamic scope.  When CMake starts processing  commands
9241              in  a  source  file it sets this variable to the location of the
9242              file.  When CMake finishes processing commands from the file  it
9243              restores  the  previous value.  Therefore the value of the vari‐
9244              able inside a macro or function is the file  invoking  the  bot‐
9245              tom-most  entry  on  the call stack, not the file containing the
9246              macro or function definition.
9247
9248
9249              See also CMAKE_PARENT_LIST_FILE.
9250
9251
9252       CMAKE_CURRENT_LIST_LINE
9253              The line number of the current file being processed.
9254
9255              This is the line number of the file currently being processed by
9256              cmake.
9257
9258
9259       CMAKE_CURRENT_SOURCE_DIR
9260              The path to the source directory currently being processed.
9261
9262              This  the  full  path  to the source directory that is currently
9263              being processed by cmake.
9264
9265
9266       CMAKE_DL_LIBS
9267              Name of library containing dlopen and dlcose.
9268
9269              The name of the library that has dlopen and dlclose in it,  usu‐
9270              ally -ldl on most UNIX machines.
9271
9272
9273       CMAKE_EDIT_COMMAND
9274              Full path to cmake-gui or ccmake.
9275
9276              This  is  the full path to the CMake executable that can graphi‐
9277              cally edit the cache.  For example, cmake-gui, ccmake, or  cmake
9278              -i.
9279
9280
9281       CMAKE_EXECUTABLE_SUFFIX
9282              The suffix for executables on this platform.
9283
9284              The  suffix to use for the end of an executable filename if any,
9285              .exe on Windows.
9286
9287
9288              CMAKE_EXECUTABLE_SUFFIX_<LANG>  overrides  this   for   language
9289              <LANG>.
9290
9291
9292       CMAKE_EXTRA_GENERATOR
9293              The extra generator used to build the project.
9294
9295              When using the Eclipse, CodeBlocks or KDevelop generators, CMake
9296              generates Makefiles (CMAKE_GENERATOR) and  additionally  project
9297              files for the respective IDE. This IDE project file generator is
9298              stored in CMAKE_EXTRA_GENERATOR (e.g. "Eclipse CDT4").
9299
9300
9301       CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
9302              Additional suffixes for shared libraries.
9303
9304              Extensions for shared libraries other  than  that  specified  by
9305              CMAKE_SHARED_LIBRARY_SUFFIX,  if any.  CMake uses this to recog‐
9306              nize external shared library files during analysis of  libraries
9307              linked by a target.
9308
9309
9310       CMAKE_GENERATOR
9311              The generator used to build the project.
9312
9313              The  name  of  the  generator that is being used to generate the
9314              build files.  (e.g. "Unix Makefiles", "Visual Studio 6", etc.)
9315
9316
9317       CMAKE_GENERATOR_TOOLSET
9318              Native build system toolset name specified by user.
9319
9320              Some CMake generators support a toolset name to be given to  the
9321              native build system to choose a compiler.  If the user specifies
9322              a toolset name (e.g. via the cmake -T option) the value will  be
9323              available in this variable.
9324
9325
9326       CMAKE_HOME_DIRECTORY
9327              Path to top of source tree.
9328
9329              This is the path to the top level of the source tree.
9330
9331
9332       CMAKE_IMPORT_LIBRARY_PREFIX
9333              The prefix for import libraries that you link to.
9334
9335              The  prefix  to use for the name of an import library if used on
9336              this platform.
9337
9338
9339              CMAKE_IMPORT_LIBRARY_PREFIX_<LANG> overrides this  for  language
9340              <LANG>.
9341
9342
9343       CMAKE_IMPORT_LIBRARY_SUFFIX
9344              The suffix for import libraries that you link to.
9345
9346              The  suffix  to use for the end of an import library filename if
9347              used on this platform.
9348
9349
9350              CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG> overrides this  for  language
9351              <LANG>.
9352
9353
9354       CMAKE_LINK_LIBRARY_SUFFIX
9355              The suffix for libraries that you link to.
9356
9357              The  suffix  to  use  for the end of a library filename, .lib on
9358              Windows.
9359
9360
9361       CMAKE_MAJOR_VERSION
9362              The Major version of cmake (i.e. the 2 in 2.X.X)
9363
9364              This specifies the major version of the CMake  executable  being
9365              run.
9366
9367
9368       CMAKE_MAKE_PROGRAM
9369              See CMAKE_BUILD_TOOL.
9370
9371              This   variable  is  around  for  backwards  compatibility,  see
9372              CMAKE_BUILD_TOOL.
9373
9374
9375       CMAKE_MINIMUM_REQUIRED_VERSION
9376              Version specified to cmake_minimum_required command
9377
9378              Variable containing  the  VERSION  component  specified  in  the
9379              cmake_minimum_required command.
9380
9381
9382       CMAKE_MINOR_VERSION
9383              The Minor version of cmake (i.e. the 4 in X.4.X).
9384
9385              This  specifies  the minor version of the CMake executable being
9386              run.
9387
9388
9389       CMAKE_PARENT_LIST_FILE
9390              Full path to the CMake file that included the current one.
9391
9392              While processing a CMake file loaded by include() or  find_pack‐
9393              age() this variable contains the full path to the file including
9394              it.  The top of the include stack is always  the  CMakeLists.txt
9395              for the current directory.  See also CMAKE_CURRENT_LIST_FILE.
9396
9397
9398       CMAKE_PATCH_VERSION
9399              The patch version of cmake (i.e. the 3 in X.X.3).
9400
9401              This  specifies  the patch version of the CMake executable being
9402              run.
9403
9404
9405       CMAKE_PROJECT_NAME
9406              The name of the current project.
9407
9408              This specifies name of the  current  project  from  the  closest
9409              inherited PROJECT command.
9410
9411
9412       CMAKE_RANLIB
9413              Name of randomizing tool for static libraries.
9414
9415              This  specifies name of the program that randomizes libraries on
9416              UNIX, not used on Windows, but may be present.
9417
9418
9419       CMAKE_ROOT
9420              Install directory for running cmake.
9421
9422              This is the install root for the running CMake and  the  Modules
9423              directory  can be found here. This is commonly used in this for‐
9424              mat: ${CMAKE_ROOT}/Modules
9425
9426
9427       CMAKE_SCRIPT_MODE_FILE
9428              Full path to the -P script file currently being processed.
9429
9430              When run in -P script mode, CMake sets this variable to the full
9431              path  of the script file. When run to configure a CMakeLists.txt
9432              file, this variable is not set.
9433
9434
9435       CMAKE_SHARED_LIBRARY_PREFIX
9436              The prefix for shared libraries that you link to.
9437
9438              The prefix to use for the name of a shared library, lib on UNIX.
9439
9440
9441              CMAKE_SHARED_LIBRARY_PREFIX_<LANG> overrides this  for  language
9442              <LANG>.
9443
9444
9445       CMAKE_SHARED_LIBRARY_SUFFIX
9446              The suffix for shared libraries that you link to.
9447
9448              The suffix to use for the end of a shared library filename, .dll
9449              on Windows.
9450
9451
9452              CMAKE_SHARED_LIBRARY_SUFFIX_<LANG> overrides this  for  language
9453              <LANG>.
9454
9455
9456       CMAKE_SHARED_MODULE_PREFIX
9457              The prefix for loadable modules that you link to.
9458
9459              The  prefix  to  use  for  the name of a loadable module on this
9460              platform.
9461
9462
9463              CMAKE_SHARED_MODULE_PREFIX_<LANG> overrides  this  for  language
9464              <LANG>.
9465
9466
9467       CMAKE_SHARED_MODULE_SUFFIX
9468              The suffix for shared libraries that you link to.
9469
9470              The  suffix  to use for the end of a loadable module filename on
9471              this platform
9472
9473
9474              CMAKE_SHARED_MODULE_SUFFIX_<LANG> overrides  this  for  language
9475              <LANG>.
9476
9477
9478       CMAKE_SIZEOF_VOID_P
9479              Size of a void pointer.
9480
9481              This  is  set  to  the  size of a pointer on the machine, and is
9482              determined by a try compile. If a 64 bit size is found, then the
9483              library  search  path  is  modified to look for 64 bit libraries
9484              first.
9485
9486
9487       CMAKE_SKIP_RPATH
9488              If true, do not add run time path information.
9489
9490              If this is set to TRUE, then the rpath information is not  added
9491              to  compiled  executables.  The default is to add rpath informa‐
9492              tion if the platform supports it.  This allows for easy  running
9493              from the build tree.  To omit RPATH in the install step, but not
9494              the build step, use CMAKE_SKIP_INSTALL_RPATH instead.
9495
9496
9497       CMAKE_SOURCE_DIR
9498              The path to the top level of the source tree.
9499
9500              This is the full path to the top  level  of  the  current  CMake
9501              source  tree.  For an in-source build, this would be the same as
9502              CMAKE_BINARY_DIR.
9503
9504
9505       CMAKE_STANDARD_LIBRARIES
9506              Libraries linked into every executable and shared library.
9507
9508              This is the list of libraries that are linked into all  executa‐
9509              bles and libraries.
9510
9511
9512       CMAKE_STATIC_LIBRARY_PREFIX
9513              The prefix for static libraries that you link to.
9514
9515              The prefix to use for the name of a static library, lib on UNIX.
9516
9517
9518              CMAKE_STATIC_LIBRARY_PREFIX_<LANG>  overrides  this for language
9519              <LANG>.
9520
9521
9522       CMAKE_STATIC_LIBRARY_SUFFIX
9523              The suffix for static libraries that you link to.
9524
9525              The suffix to use for the end of a static library filename, .lib
9526              on Windows.
9527
9528
9529              CMAKE_STATIC_LIBRARY_SUFFIX_<LANG>  overrides  this for language
9530              <LANG>.
9531
9532
9533       CMAKE_TWEAK_VERSION
9534              The tweak version of cmake (i.e. the 1 in X.X.X.1).
9535
9536              This specifies the tweak version of the CMake  executable  being
9537              run.  Releases use tweak < 20000000 and development versions use
9538              the date format CCYYMMDD for the tweak level.
9539
9540
9541       CMAKE_VERBOSE_MAKEFILE
9542              Create verbose makefiles if on.
9543
9544              This variable defaults to false. You can set  this  variable  to
9545              true to make CMake produce verbose makefiles that show each com‐
9546              mand line as it is used.
9547
9548
9549       CMAKE_VERSION
9550              The full version of cmake in major.minor.patch[.tweak[-id]] for‐
9551              mat.
9552
9553              This  specifies  the  full version of the CMake executable being
9554              run.  This variable is defined by  versions  2.6.3  and  higher.
9555              See    variables    CMAKE_MAJOR_VERSION,    CMAKE_MINOR_VERSION,
9556              CMAKE_PATCH_VERSION, and CMAKE_TWEAK_VERSION for individual ver‐
9557              sion  components.   The  [-id]  component appears in non-release
9558              versions and may be arbitrary text.
9559
9560
9561       CMAKE_VS_PLATFORM_TOOLSET
9562              Visual Studio Platform Toolset name.
9563
9564              VS 10 and above use MSBuild under the hood and support  multiple
9565              compiler  toolchains.   CMake  may specify a toolset explicitly,
9566              such as "v110" for VS 11 or "Windows7.1SDK" for  64-bit  support
9567              in VS 10 Express.  CMake provides the name of the chosen toolset
9568              in this variable.
9569
9570
9571       CMAKE_XCODE_PLATFORM_TOOLSET
9572              Xcode compiler selection.
9573
9574              Xcode supports selection of a compiler from one of the installed
9575              toolsets.  CMake provides the name of the chosen toolset in this
9576              variable, if any is explicitly selected (e.g. via the  cmake  -T
9577              option).
9578
9579
9580       PROJECT_BINARY_DIR
9581              Full path to build directory for project.
9582
9583              This is the binary directory of the most recent PROJECT command.
9584
9585
9586       PROJECT_NAME
9587              Name of the project given to the project command.
9588
9589              This is the name given to the most recent PROJECT command.
9590
9591
9592       PROJECT_SOURCE_DIR
9593              Top level source directory for the current project.
9594
9595              This is the source directory of the most recent PROJECT command.
9596
9597
9598       [Project name]_BINARY_DIR
9599              Top level binary directory for the named project.
9600
9601              A variable is created with the name used in the PROJECT command,
9602              and is the binary directory for the project.   This can be  use‐
9603              ful when SUBDIR is used to connect several projects.
9604
9605
9606       [Project name]_SOURCE_DIR
9607              Top level source directory for the named project.
9608
9609              A variable is created with the name used in the PROJECT command,
9610              and is the source directory for the project.   This can be  use‐
9611              ful when add_subdirectory is used to connect several projects.
9612
9613
9615       Copyright  2000-2012  Kitware,  Inc., Insight Software Consortium.  All
9616       rights reserved.
9617
9618
9619       Redistribution and use in source and binary forms, with or without mod‐
9620       ification,  are  permitted  provided  that the following conditions are
9621       met:
9622
9623
9624       Redistributions of source code must retain the above copyright  notice,
9625       this list of conditions and the following disclaimer.
9626
9627
9628       Redistributions  in  binary  form  must  reproduce  the above copyright
9629       notice, this list of conditions and the  following  disclaimer  in  the
9630       documentation and/or other materials provided with the distribution.
9631
9632
9633       Neither  the  names  of Kitware, Inc., the Insight Software Consortium,
9634       nor the names of their contributors may be used to endorse  or  promote
9635       products derived from this software without specific prior written per‐
9636       mission.
9637
9638
9639       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
9640       IS"  AND  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
9641       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
9642       ULAR  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
9643       CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,  INCIDENTAL,  SPECIAL,
9644       EXEMPLARY,  OR  CONSEQUENTIAL  DAMAGES  (INCLUDING, BUT NOT LIMITED TO,
9645       PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;  LOSS  OF  USE,  DATA,  OR
9646       PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
9647       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,  OR  TORT  (INCLUDING
9648       NEGLIGENCE  OR  OTHERWISE)  ARISING  IN  ANY WAY OUT OF THE USE OF THIS
9649       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
9650
9651

SEE ALSO

9653       cmake(1), ccmake(1)
9654
9655
9656       The following resources are available to get help using CMake:
9657
9658
9659       Home Page
9660              http://www.cmake.org
9661
9662              The primary starting point for learning about CMake.
9663
9664
9665       Frequently Asked Questions
9666              http://www.cmake.org/Wiki/CMake_FAQ
9667
9668              A Wiki is provided containing answers to frequently asked  ques‐
9669              tions.
9670
9671
9672       Online Documentation
9673              http://www.cmake.org/HTML/Documentation.html
9674
9675              Links to available documentation may be found on this web page.
9676
9677
9678       Mailing List
9679              http://www.cmake.org/HTML/MailingLists.html
9680
9681              For  help  and  discussion  about using cmake, a mailing list is
9682              provided at cmake@cmake.org. The list  is  member-post-only  but
9683              one  may  sign  up  on the CMake web page. Please first read the
9684              full documentation at http://www.cmake.org before posting  ques‐
9685              tions to the list.
9686
9687

AUTHOR

9689       This manual page was generated by the "--help-man" option.
9690
9691
9692
9693
9694cpack 2.8.12.2                 October 15, 2014                       cpack(1)
Impressum