-
Notifications
You must be signed in to change notification settings - Fork 2
/
commands.txt
5346 lines (4049 loc) · 207 KB
/
commands.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
cmake-commands(7)
*****************
Normal Commands
===============
These commands may be used freely in CMake projects.
add_compile_options
-------------------
Adds options to the compilation of source files.
::
add_compile_options(<option> ...)
Adds options to the compiler command line for sources in the current
directory and below. This command can be used to add any options, but
alternative commands exist to add preprocessor definitions
(``target_compile_definitions()`` and ``add_definitions()``) or
include directories (``target_include_directories()`` and
``include_directories()``). See documentation of the
``directory`` and
`` target`` ``COMPILE_OPTIONS`` properties.
Arguments to ``add_compile_options`` may use "generator expressions" with
the syntax ``$<...>``. See the ``cmake-generator-expressions(7)``
manual for available expressions. See the ``cmake-buildsystem(7)``
manual for more on defining buildsystem properties.
add_custom_command
------------------
Add a custom build rule to the generated build system.
There are two main signatures for add_custom_command The first
signature is for adding a custom command to produce an output.
::
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[MAIN_DEPENDENCY depend]
[DEPENDS [depends...]]
[IMPLICIT_DEPENDS <lang1> depend1
[<lang2> depend2] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM] [APPEND])
This defines a command to generate specified OUTPUT file(s). A target
created in the same directory (CMakeLists.txt file) that specifies any
output of the custom command as a source file is given a rule to
generate the file using the command at build time. Do not list the
output in more than one independent target that may build in parallel
or the two instances of the rule may conflict (instead use
add_custom_target to drive the command and make the other targets
depend on that one). If an output name is a relative path it will be
interpreted relative to the build tree directory corresponding to the
current source directory. Note that MAIN_DEPENDENCY is completely
optional and is used as a suggestion to visual studio about where to
hang the custom command. In makefile terms this creates a new target
in the following form:
::
OUTPUT: MAIN_DEPENDENCY DEPENDS
COMMAND
If more than one command is specified they will be executed in order.
The optional ARGS argument is for backward compatibility and will be
ignored.
The second signature adds a custom command to a target such as a
library or executable. This is useful for performing an operation
before or after building the target. The command becomes part of the
target and will only execute when the target itself is built. If the
target is already built, the command will not execute.
::
add_custom_command(TARGET target
PRE_BUILD | PRE_LINK | POST_BUILD
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM])
This defines a new command that will be associated with building the
specified target. When the command will happen is determined by which
of the following is specified:
::
PRE_BUILD - run before all other dependencies
PRE_LINK - run after other dependencies
POST_BUILD - run after the target has been built
Note that the PRE_BUILD option is only supported on Visual Studio 7 or
later. For all other generators PRE_BUILD will be treated as
PRE_LINK.
If WORKING_DIRECTORY is specified the command will be executed in the
directory given. If it is a relative path it will be interpreted
relative to the build tree directory corresponding to the current
source directory. If COMMENT is set, the value will be displayed as a
message before the commands are executed at build time. If APPEND is
specified the COMMAND and DEPENDS option values are appended to the
custom command for the first output specified. There must have
already been a previous call to this command with the same output.
The COMMENT, WORKING_DIRECTORY, and MAIN_DEPENDENCY options are
currently ignored when APPEND is given, but may be used in the future.
If VERBATIM is given then all arguments to the commands will be
escaped properly for the build tool so that the invoked command
receives each argument unchanged. Note that one level of escapes is
still used by the CMake language processor before add_custom_command
even sees the arguments. Use of VERBATIM is recommended as it enables
correct behavior. When VERBATIM is not given the behavior is platform
specific because there is no protection of tool-specific special
characters.
If the output of the custom command is not actually created as a file
on disk it should be marked as SYMBOLIC with
SET_SOURCE_FILES_PROPERTIES.
The IMPLICIT_DEPENDS option requests scanning of implicit dependencies
of an input file. The language given specifies the programming
language whose corresponding dependency scanner should be used.
Currently only C and CXX language scanners are supported. The
language has to be specified for every file in the IMPLICIT_DEPENDS
list. Dependencies discovered from the scanning are added to those of
the custom command at build time. Note that the IMPLICIT_DEPENDS
option is currently supported only for Makefile generators and will be
ignored by other generators.
If COMMAND specifies an executable target (created by ADD_EXECUTABLE)
it will automatically be replaced by the location of the executable
created at build time. Additionally a target-level dependency will be
added so that the executable target will be built before any target
using this custom command. However this does NOT add a file-level
dependency that would cause the custom command to re-run whenever the
executable is recompiled.
Arguments to COMMAND may use "generator expressions" with the syntax
``$<...>``. See the ``cmake-generator-expressions(7)`` manual for
available expressions.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
::
$<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.
$<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
Boolean expressions:
::
$<AND:?[,?]...> = '1' if all '?' are '1', else '0'
$<OR:?[,?]...> = '0' if all '?' are '0', else '1'
$<NOT:?> = '0' if '?' is '1', else '1'
where '?' is always either '0' or '1'.
Expressions with an implicit 'this' target:
::
$<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
References to target names in generator expressions imply target-level
dependencies, but NOT file-level dependencies. List target names with
the DEPENDS option to add file dependencies.
The DEPENDS option specifies files on which the command depends. If
any dependency is an OUTPUT of another custom command in the same
directory (CMakeLists.txt file) CMake automatically brings the other
custom command into the target in which this command is built. If
DEPENDS is not specified the command will run whenever the OUTPUT is
missing; if the command does not actually create the OUTPUT then the
rule will always run. If DEPENDS specifies any target (created by an
ADD_* command) a target-level dependency is created to make sure the
target is built before any target using this custom command.
Additionally, if the target is an executable or library a file-level
dependency is created to cause the custom command to re-run whenever
the target is recompiled.
add_custom_target
-----------------
Add a target with no output so it will always be built.
::
add_custom_target(Name [ALL] [command1 [args1...]]
[COMMAND command2 [args2...] ...]
[DEPENDS depend depend depend ... ]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM]
[SOURCES src1 [src2...]])
Adds a target with the given name that executes the given commands.
The target has no output file and is ALWAYS CONSIDERED OUT OF DATE
even if the commands try to create a file with the name of the target.
Use ADD_CUSTOM_COMMAND to generate a file with dependencies. By
default nothing depends on the custom target. Use ADD_DEPENDENCIES to
add dependencies to or from other targets. If the ALL option is
specified it indicates that this target should be added to the default
build target so that it will be run every time (the command cannot be
called ALL). The command and arguments are optional and if not
specified an empty target will be created. If WORKING_DIRECTORY is
set, then the command will be run in that directory. If it is a
relative path it will be interpreted relative to the build tree
directory corresponding to the current source directory. If COMMENT
is set, the value will be displayed as a message before the commands
are executed at build time. Dependencies listed with the DEPENDS
argument may reference files and outputs of custom commands created
with add_custom_command() in the same directory (CMakeLists.txt file).
If VERBATIM is given then all arguments to the commands will be
escaped properly for the build tool so that the invoked command
receives each argument unchanged. Note that one level of escapes is
still used by the CMake language processor before add_custom_target
even sees the arguments. Use of VERBATIM is recommended as it enables
correct behavior. When VERBATIM is not given the behavior is platform
specific because there is no protection of tool-specific special
characters.
The SOURCES option specifies additional source files to be included in
the custom target. Specified source files will be added to IDE
project files for convenience in editing even if they have not build
rules.
add_definitions
---------------
Adds -D define flags to the compilation of source files.
::
add_definitions(-DFOO -DBAR ...)
Adds definitions to the compiler command line for sources in the current
directory and below. This command can be used to add any flags, but
it is intended to add preprocessor definitions. Flags
beginning in -D or /D that look like preprocessor definitions are
automatically added to the ``COMPILE_DEFINITIONS`` directory
property for the current directory. Definitions with non-trivial values
may be left in the set of flags instead of being converted for reasons of
backwards compatibility. See documentation of the
``directory``,
``target``,
``source file`` ``COMPILE_DEFINITIONS``
properties for details on adding preprocessor definitions to specific
scopes and configurations.
See the ``cmake-buildsystem(7)`` manual for more on defining
buildsystem properties.
add_dependencies
----------------
Add a dependency between top-level targets.
::
add_dependencies(<target> [<target-dependency>]...)
Make a top-level <target> depend on other top-level targets to ensure
that they build before <target> does. A top-level target is one
created by ADD_EXECUTABLE, ADD_LIBRARY, or ADD_CUSTOM_TARGET.
Dependencies added to an IMPORTED target are followed transitively in
its place since the target itself does not build.
See the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND for
adding file-level dependencies in custom rules. See the
OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add file-level
dependencies to object files.
add_executable
--------------
Add an executable to the project using the specified source files.
::
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL]
source1 [source2 ...])
Adds an executable target called ``<name>`` to be built from the source
files listed in the command invocation. The ``<name>`` corresponds to the
logical target name and must be globally unique within a project. The
actual file name of the executable built is constructed based on
conventions of the native platform (such as ``<name>.exe`` or just
``<name>``.
By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked. See documentation of the
``RUNTIME_OUTPUT_DIRECTORY`` target property to change this
location. See documentation of the ``OUTPUT_NAME`` target property
to change the ``<name>`` part of the final file name.
If ``WIN32`` is given the property ``WIN32_EXECUTABLE`` will be
set on the target created. See documentation of that target property for
details.
If ``MACOSX_BUNDLE`` is given the corresponding property will be set on
the created target. See documentation of the ``MACOSX_BUNDLE``
target property for details.
If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the ``EXCLUDE_FROM_ALL``
target property for details.
See the ``cmake-buildsystem(7)`` manual for more on defining
buildsystem properties.
--------------------------------------------------------------------------
::
add_executable(<name> IMPORTED [GLOBAL])
An :ref:`IMPORTED executable target <Imported Targets>` references an
executable file located outside the project. No rules are generated to
build it, and the ``IMPORTED`` target property is ``True``. The
target name has scope in the directory in which it is created and below, but
the ``GLOBAL`` option extends visibility. It may be referenced like any
target built within the project. ``IMPORTED`` executables are useful
for convenient reference from commands like ``add_custom_command()``.
Details about the imported executable are specified by setting properties
whose names begin in ``IMPORTED_``. The most important such property is
``IMPORTED_LOCATION`` (and its per-configuration version
``IMPORTED_LOCATION_<CONFIG>``) which specifies the location of
the main executable file on disk. See documentation of the ``IMPORTED_*``
properties for more information.
--------------------------------------------------------------------------
::
add_executable(<name> ALIAS <target>)
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can
be used to refer to ``<target>`` in subsequent commands. The ``<name>``
does not appear in the generated buildsystem as a make target. The
``<target>`` may not be an :ref:`Imported Target <Imported Targets>` or an
``ALIAS``. ``ALIAS`` targets can be used as targets to read properties
from, executables for custom commands and custom targets. They can also be
tested for existance with the regular ``if(TARGET)`` subcommand.
The ``<name>`` may not be used to modify properties of ``<target>``, that
is, it may not be used as the operand of ``set_property()``,
``set_target_properties()``, ``target_link_libraries()`` etc.
An ``ALIAS`` target may not be installed or exported.
add_library
-----------
Add a library to the project using the specified source files.
::
add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL]
source1 [source2 ...])
Adds a library target called ``<name>`` to be built from the source files
listed in the command invocation. The ``<name>`` corresponds to the
logical target name and must be globally unique within a project. The
actual file name of the library built is constructed based on
conventions of the native platform (such as ``lib<name>.a`` or
``<name>.lib``).
``STATIC``, ``SHARED``, or ``MODULE`` may be given to specify the type of
library to be created. ``STATIC`` libraries are archives of object files
for use when linking other targets. ``SHARED`` libraries are linked
dynamically and loaded at runtime. ``MODULE`` libraries are plugins that
are not linked into other targets but may be loaded dynamically at runtime
using dlopen-like functionality. If no type is given explicitly the
type is ``STATIC`` or ``SHARED`` based on whether the current value of the
variable ``BUILD_SHARED_LIBS`` is ``ON``. For ``SHARED`` and
``MODULE`` libraries the ``POSITION_INDEPENDENT_CODE`` target
property is set to ``ON`` automatically.
By default the library file will be created in the build tree directory
corresponding to the source tree directory in which thecommand was
invoked. See documentation of the ``ARCHIVE_OUTPUT_DIRECTORY``,
``LIBRARY_OUTPUT_DIRECTORY``, and
``RUNTIME_OUTPUT_DIRECTORY`` target properties to change this
location. See documentation of the ``OUTPUT_NAME`` target
property to change the ``<name>`` part of the final file name.
If ``EXCLUDE_FROM_ALL`` is given the corresponding property will be set on
the created target. See documentation of the ``EXCLUDE_FROM_ALL``
target property for details.
See the ``cmake-buildsystem(7)`` manual for more on defining buildsystem
properties.
--------------------------------------------------------------------------
::
add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
[GLOBAL])
An :ref:`IMPORTED library target <Imported Targets>` references a library
file located outside the project. No rules are generated to build it, and
the ``IMPORTED`` target property is ``True``. The target name has
scope in the directory in which it is created and below, but the ``GLOBAL``
option extends visibility. It may be referenced like any target built
within the project. ``IMPORTED`` libraries are useful for convenient
reference from commands like ``target_link_libraries()``. Details
about the imported library are specified by setting properties whose names
begin in ``IMPORTED_`` and ``INTERFACE_``. The most important such
property is ``IMPORTED_LOCATION`` (and its per-configuration
variant ``IMPORTED_LOCATION_<CONFIG>``) which specifies the
location of the main library file on disk. See documentation of the
``IMPORTED_*`` and ``INTERFACE_*`` properties for more information.
--------------------------------------------------------------------------
::
add_library(<name> OBJECT <src>...)
Creates a special "object library" target. An object library compiles
source files but does not archive or link their object files into a
library. Instead other targets created by ``add_library()`` or
``add_executable()`` may reference the objects using an expression of the
form ``$<TARGET_OBJECTS:objlib>`` as a source, where ``objlib`` is the
object library name. For example:
add_library(... $<TARGET_OBJECTS:objlib> ...)
add_executable(... $<TARGET_OBJECTS:objlib> ...)
will include objlib's object files in a library and an executable
along with those compiled from their own sources. Object libraries
may contain only sources (and headers) that compile to object files.
They may contain custom commands generating such sources, but not
``PRE_BUILD``, ``PRE_LINK``, or ``POST_BUILD`` commands. Object libraries
cannot be imported, exported, installed, or linked. Some native build
systems may not like targets that have only object files, so consider
adding at least one real source file to any target that references
``$<TARGET_OBJECTS:objlib>``.
--------------------------------------------------------------------------
::
add_library(<name> ALIAS <target>)
Creates an :ref:`Alias Target <Alias Targets>`, such that ``<name>`` can be
used to refer to ``<target>`` in subsequent commands. The ``<name>`` does
not appear in the generatedbuildsystem as a make target. The ``<target>``
may not be an :ref:`Imported Target <Imported Targets>` or an ``ALIAS``.
``ALIAS`` targets can be used as linkable targets and as targets to
read properties from. They can also be tested for existance with the
regular ``if(TARGET)`` subcommand. The ``<name>`` may not be used
to modify properties of ``<target>``, that is, it may not be used as the
operand of ``set_property()``, ``set_target_properties()``,
``target_link_libraries()`` etc. An ``ALIAS`` target may not be
installed or exported.
--------------------------------------------------------------------------
::
add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
Creates an :ref:`Interface Library <Interface Libraries>`. An ``INTERFACE``
library target does not directly create build output, though it may
have properties set on it and it may be installed, exported and
imported. Typically the ``INTERFACE_*`` properties are populated on
the interface target using the ``set_property()``,
``target_link_libraries(INTERFACE)``,
``target_include_directories(INTERFACE)``,
``target_compile_options(INTERFACE)``
and ``target_compile_definitions(INTERFACE)`` commands, and then it
is used as an argument to ``target_link_libraries()`` like any other
target.
An ``INTERFACE`` :ref:`Imported Target <Imported Targets>` may also be
created with this signature. An ``IMPORTED`` library target references a
library defined outside the project. The target name has scope in the
directory in which it is created and below, but the ``GLOBAL`` option
extends visibility. It may be referenced like any target built within
the project. ``IMPORTED`` libraries are useful for convenient reference
from commands like ``target_link_libraries()``.
add_subdirectory
----------------
Add a subdirectory to the build.
::
add_subdirectory(source_dir [binary_dir]
[EXCLUDE_FROM_ALL])
Add a subdirectory to the build. The source_dir specifies the
directory in which the source CMakeLists.txt and code files are
located. If it is a relative path it will be evaluated with respect
to the current directory (the typical usage), but it may also be an
absolute path. The binary_dir specifies the directory in which to
place the output files. If it is a relative path it will be evaluated
with respect to the current output directory, but it may also be an
absolute path. If binary_dir is not specified, the value of
source_dir, before expanding any relative path, will be used (the
typical usage). The CMakeLists.txt file in the specified source
directory will be processed immediately by CMake before processing in
the current input file continues beyond this command.
If the EXCLUDE_FROM_ALL argument is provided then targets in the
subdirectory will not be included in the ALL target of the parent
directory by default, and will be excluded from IDE project files.
Users must explicitly build targets in the subdirectory. This is
meant for use when the subdirectory contains a separate part of the
project that is useful but not necessary, such as a set of examples.
Typically the subdirectory should contain its own project() command
invocation so that a full build system will be generated in the
subdirectory (such as a VS IDE solution file). Note that inter-target
dependencies supercede this exclusion. If a target built by the
parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.
add_test
--------
Add a test to the project to be run by ``ctest(1)``.
::
add_test(NAME <name> COMMAND <command> [<arg>...]
[CONFIGURATIONS <config>...]
[WORKING_DIRECTORY <dir>])
Add a test called ``<name>``. The test name may not contain spaces,
quotes, or other characters special in CMake syntax. The options are:
``COMMAND``
Specify the test command-line. If ``<command>`` specifies an
executable target (created by ``add_executable()``) it will
automatically be replaced by the location of the executable created
at build time.
``CONFIGURATIONS``
Restrict execution of the test only to the named configurations.
``WORKING_DIRECTORY``
Set the ``WORKING_DIRECTORY`` test property to
specify the working directory in which to execute the test.
If not specified the test will be run with the current working
directory set to the build directory corresponding to the
current source directory.
The ``COMMAND`` and ``WORKING_DIRECTORY`` options may use "generator
expressions" with the syntax ``$<...>``. See the
``cmake-generator-expressions(7)`` manual for available expressions.
Example usage::
add_test(NAME mytest
COMMAND testDriver --config $<CONFIGURATION>
--exe $<TARGET_FILE:myexe>)
This creates a test ``mytest`` whose command runs a ``testDriver`` tool
passing the configuration name and the full path to the executable
file produced by target ``myexe``.
.. note::
CMake will generate tests only if the ``enable_testing()``
command has been invoked. The ``CTest`` module invokes the
command automatically when the ``BUILD_TESTING`` option is ``ON``.
---------------------------------------------------------------------
::
add_test(<name> <command> [<arg>...])
Add a test called ``<name>`` with the given command-line. Unlike
the above ``NAME`` signature no transformation is performed on the
command-line to support target names or generator expressions.
aux_source_directory
--------------------
Find all source files in a directory.
::
aux_source_directory(<dir> <variable>)
Collects the names of all the source files in the specified directory
and stores the list in the <variable> provided. This command is
intended to be used by projects that use explicit template
instantiation. Template instantiation files can be stored in a
"Templates" subdirectory and collected automatically using this
command to avoid manually listing all instantiations.
It is tempting to use this command to avoid writing the list of source
files for a library or executable target. While this seems to work,
there is no way for CMake to generate a build system that knows when a
new source file has been added. Normally the generated build system
knows when it needs to rerun CMake because the CMakeLists.txt file is
modified to add a new source. When the source is just added to the
directory without modifying this file, one would have to manually
rerun CMake to generate a build system incorporating the new file.
break
-----
Break from an enclosing foreach or while loop.
::
break()
Breaks from an enclosing foreach loop or while loop
build_command
-------------
Get a command line to build the current project.
This is mainly intended for internal use by the ``CTest`` module.
build_command(<variable>
[CONFIGURATION <config>]
[TARGET <target>]
[PROJECT_NAME <projname>] # legacy, causes warning
)
Sets the given ``<variable>`` to a command-line string of the form::
<cmake> --build . [--config <config>] [--target <target>] [-- -i]
where ``<cmake>`` is the location of the ``cmake(1)`` command-line
tool, and ``<config>`` and ``<target>`` are the values provided to the
``CONFIGURATION`` and ``TARGET`` options, if any. The trailing ``-- -i``
option is added for Makefile generators.
When invoked, this ``cmake --build`` command line will launch the
underlying build system tool.
build_command(<cachevariable> <makecommand>)
This second signature is deprecated, but still available for backwards
compatibility. Use the first signature instead.
It sets the given ``<cachevariable>`` to a command-line string as
above but without the ``--config`` or ``--target`` options.
The ``<makecommand>`` is ignored but should be the full path to
msdev, devenv, nmake, make or one of the end user build tools
for legacy invocations.
.. note::
In CMake versions prior to 3.0 this command returned a command
line that directly invokes the native build tool for the current
generator. Their implementation of the ``PROJECT_NAME`` option
had no useful effects, so CMake now warns on use of the option.
cmake_host_system_information
-----------------------------
Query host system specific information.
::
cmake_host_system_information(RESULT <variable> QUERY <key> ...)
Queries system information of the host system on which cmake runs.
One or more <key> can be provided to select the information to be
queried. The list of queried values is stored in <variable>.
<key> can be one of the following values:
::
NUMBER_OF_LOGICAL_CORES = Number of logical cores.
NUMBER_OF_PHYSICAL_CORES = Number of physical cores.
HOSTNAME = Hostname.
FQDN = Fully qualified domain name.
TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes.
AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes.
TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes.
AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
cmake_minimum_required
----------------------
Set the minimum required version of cmake for a project.
::
cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
[FATAL_ERROR])
If the current version of CMake is lower than that required it will
stop processing the project and report an error. When a version
higher than 2.4 is specified the command implicitly invokes
::
cmake_policy(VERSION major[.minor[.patch[.tweak]]])
which sets the cmake policy version level to the version specified.
When version 2.4 or lower is given the command implicitly invokes
::
cmake_policy(VERSION 2.4)
which enables compatibility features for CMake 2.4 and lower.
The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
higher. It should be specified so CMake versions 2.4 and lower fail
with an error instead of just a warning.
cmake_policy
------------
Manage CMake Policy settings.
As CMake evolves it is sometimes necessary to change existing behavior
in order to fix bugs or improve implementations of existing features.
The CMake Policy mechanism is designed to help keep existing projects
building as new versions of CMake introduce changes in behavior. Each
new policy (behavioral change) is given an identifier of the form
"CMP<NNNN>" where "<NNNN>" is an integer index. Documentation
associated with each policy describes the OLD and NEW behavior and the
reason the policy was introduced. Projects may set each policy to
select the desired behavior. When CMake needs to know which behavior
to use it checks for a setting specified by the project. If no
setting is available the OLD behavior is assumed and a warning is
produced requesting that the policy be set.
The cmake_policy command is used to set policies to OLD or NEW
behavior. While setting policies individually is supported, we
encourage projects to set policies based on CMake versions.
::
cmake_policy(VERSION major.minor[.patch[.tweak]])
Specify that the current CMake list file is written for the given
version of CMake. All policies introduced in the specified version or
earlier will be set to use NEW behavior. All policies introduced
after the specified version will be unset (unless variable
CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default). This effectively
requests behavior preferred as of a given CMake version and tells
newer CMake versions to warn about their new policies. The policy
version specified must be at least 2.4 or the command will report an
error. In order to get compatibility features supporting versions
earlier than 2.4 see documentation of policy CMP0001.
::
cmake_policy(SET CMP<NNNN> NEW)
cmake_policy(SET CMP<NNNN> OLD)
Tell CMake to use the OLD or NEW behavior for a given policy.
Projects depending on the old behavior of a given policy may silence a
policy warning by setting the policy state to OLD. Alternatively one
may fix the project to work with the new behavior and set the policy
state to NEW.
::
cmake_policy(GET CMP<NNNN> <variable>)
Check whether a given policy is set to OLD or NEW behavior. The
output variable value will be "OLD" or "NEW" if the policy is set, and
empty otherwise.
CMake keeps policy settings on a stack, so changes made by the
cmake_policy command affect only the top of the stack. A new entry on
the policy stack is managed automatically for each subdirectory to
protect its parents and siblings. CMake also manages a new entry for
scripts loaded by include() and find_package() commands except when
invoked with the NO_POLICY_SCOPE option (see also policy CMP0011).
The cmake_policy command provides an interface to manage custom
entries on the policy stack:
::
cmake_policy(PUSH)
cmake_policy(POP)
Each PUSH must have a matching POP to erase any changes. This is
useful to make temporary changes to policy settings.
Functions and macros record policy settings when they are created and
use the pre-record policies when they are invoked. If the function or
macro implementation sets policies, the changes automatically
propagate up through callers until they reach the closest nested
policy stack entry.
configure_file
--------------
Copy a file to another location and modify its contents.
::
configure_file(<input> <output>
[COPYONLY] [ESCAPE_QUOTES] [@ONLY]
[NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
Copies a file <input> to file <output> and substitutes variable values
referenced in the file content. If <input> is a relative path it is
evaluated with respect to the current source directory. The <input>
must be a file, not a directory. If <output> is a relative path it is
evaluated with respect to the current binary directory. If <output>
names an existing directory the input file is placed in that directory
with its original name.
If the <input> file is modified the build system will re-run CMake to
re-configure the file and generate the build system again.
This command replaces any variables in the input file referenced as
${VAR} or @VAR@ with their values as determined by CMake. If a
variable is not defined, it will be replaced with nothing. If
COPYONLY is specified, then no variable expansion will take place. If
ESCAPE_QUOTES is specified then any substituted quotes will be C-style
escaped. The file will be configured with the current values of CMake
variables. If @ONLY is specified, only variables of the form @VAR@
will be replaced and ${VAR} will be ignored. This is useful for
configuring scripts that use ${VAR}.
Input file lines of the form "#cmakedefine VAR ..." will be replaced
with either "#define VAR ..." or ``/* #undef VAR */`` depending on
whether VAR is set in CMake to any value not considered a false
constant by the if() command. (Content of "...", if any, is processed
as above.) Input file lines of the form "#cmakedefine01 VAR" will be
replaced with either "#define VAR 1" or "#define VAR 0" similarly.
With NEWLINE_STYLE the line ending could be adjusted:
::
'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
COPYONLY must not be used with NEWLINE_STYLE.
create_test_sourcelist
----------------------
Create a test driver and source list for building test programs.
::
create_test_sourcelist(sourceListName driverName
test1 test2 test3
EXTRA_INCLUDE include.h
FUNCTION function)
A test driver is a program that links together many small tests into a
single executable. This is useful when building static executables
with large libraries to shrink the total required size. The list of
source files needed to build the test driver will be in
sourceListName. DriverName is the name of the test driver program.
The rest of the arguments consist of a list of test source files, can
be semicolon separated. Each test source file should have a function
in it that is the same name as the file with no extension (foo.cxx
should have int foo(int, char*[]);) DriverName will be able to call
each of the tests by name on the command line. If EXTRA_INCLUDE is
specified, then the next argument is included into the generated file.
If FUNCTION is specified, then the next argument is taken as a
function name that is passed a pointer to ac and av. This can be used
to add extra command line processing to each test. The cmake variable
CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code that will be
placed directly before calling the test main function.
CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code that will be
placed directly after the call to the test main function.
define_property
---------------
Define and document custom properties.
::
define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
TEST | VARIABLE | CACHED_VARIABLE>
PROPERTY <name> [INHERITED]
BRIEF_DOCS <brief-doc> [docs...]
FULL_DOCS <full-doc> [docs...])
Define one property in a scope for use with the set_property and
get_property commands. This is primarily useful to associate
documentation with property names that may be retrieved with the
get_property command. The first argument determines the kind of scope
in which the property should be used. It must be one of the
following:
::
GLOBAL = associated with the global namespace
DIRECTORY = associated with one directory
TARGET = associated with one target
SOURCE = associated with one source file
TEST = associated with a test named with add_test
VARIABLE = documents a CMake language variable
CACHED_VARIABLE = documents a CMake cache variable
Note that unlike set_property and get_property no actual scope needs
to be given; only the kind of scope is important.
The required PROPERTY option is immediately followed by the name of
the property being defined.
If the INHERITED option then the get_property command will chain up to
the next higher scope when the requested property is not set in the
scope given to the command. DIRECTORY scope chains to GLOBAL.
TARGET, SOURCE, and TEST chain to DIRECTORY.
The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
associated with the property as its brief and full documentation.
Corresponding options to the get_property command will retrieve the
documentation.
elseif
------
Starts the elseif portion of an if block.
::
elseif(expression)
See the if command.
else
----
Starts the else portion of an if block.
::
else(expression)
See the if command.
enable_language
---------------
Enable a language (CXX/C/Fortran/etc)
::
enable_language(<lang> [OPTIONAL] )
This command enables support for the named language in CMake. This is
the same as the project command but does not create any of the extra
variables that are created by the project command. Example languages
are CXX, C, Fortran.
This command must be called in file scope, not in a function call.
Furthermore, it must be called in the highest directory common to all
targets using the named language directly for compiling sources or
indirectly through link dependencies. It is simplest to enable all
needed languages in the top-level directory of a project.
The OPTIONAL keyword is a placeholder for future implementation and
does not currently work.
enable_testing
--------------
Enable testing for current directory and below.
::
enable_testing()
Enables testing for this directory and below. See also the add_test
command. Note that ctest expects to find a test file in the build
directory root. Therefore, this command should be in the source
directory root.
endforeach
----------
Ends a list of commands in a FOREACH block.
::
endforeach(expression)
See the FOREACH command.
endfunction