1CMAKE-COMMANDS(7) CMake CMAKE-COMMANDS(7)
2
6 cmake-commands - CMake Language Command Reference
7
9 These commands are always available.
10 block
12 New in version 3.25.
13 Evaluate a group of commands with a dedicated variable and/or policy
16 scope.
17 block([SCOPE_FOR [POLICIES] [VARIABLES] ] [PROPAGATE <var-name>...])
19 <commands>
20 endblock()
21 All commands between block() and the matching endblock() are recorded
23 without being invoked. Once the endblock() is evaluated, the recorded
24 list of commands is invoked inside the requested scopes, then the
25 scopes created by the block() command are removed.
26 SCOPE_FOR
28 Specify which scopes must be created.
29 POLICIES
31 Create a new policy scope. This is equivalent to
32 cmake_policy(PUSH).
33 VARIABLES
35 Create a new variable scope.
36 If SCOPE_FOR is not specified, this is equivalent to:
38 block(SCOPE_FOR VARIABLES POLICIES)
40 PROPAGATE
42 When a variable scope is created by the block() command, this
43 option sets or unsets the specified variables in the parent
44 scope. This is equivalent to set(PARENT_SCOPE) or
45 unset(PARENT_SCOPE) commands.
46 set(var1 "INIT1")
48 set(var2 "INIT2")
49 block(PROPAGATE var1 var2)
51 set(var1 "VALUE1")
52 unset(var2)
53 endblock()
54 # Now var1 holds VALUE1, and var2 is unset
56 This option is only allowed when a variable scope is created. An
58 error will be raised in the other cases.
59 When the block() is inside a foreach() or while() command, the break()
61 and continue() commands can be used inside the block.
62 while(TRUE)
64 block()
65 ...
66 # the break() command will terminate the while() command
67 break()
68 endblock()
69 endwhile()
70 See Also
72 • endblock()
73 • return()
75 • cmake_policy()
77 break
79 Break from an enclosing foreach or while loop.
80 break()
82 Breaks from an enclosing foreach() or while() loop.
84 See also the continue() command.
86 cmake_host_system_information
88 Query various host system information.
89 Synopsis
91 Query host system specific information
92 cmake_host_system_information(RESULT <variable> QUERY <key> ...)
93 Query Windows registry
95 cmake_host_system_information(RESULT <variable> QUERY WINDOWS_REGISTRY <key> ...)
96 Query host system specific information
98 cmake_host_system_information(RESULT <variable> QUERY <key> ...)
99 Queries system information of the host system on which cmake runs. One
101 or more <key> can be provided to select the information to be queried.
102 The list of queried values is stored in <variable>.
103 <key> can be one of the following values:
105 NUMBER_OF_LOGICAL_CORES
107 Number of logical cores
108 NUMBER_OF_PHYSICAL_CORES
110 Number of physical cores
111 HOSTNAME
113 Hostname
114 FQDN Fully qualified domain name
116 TOTAL_VIRTUAL_MEMORY
118 Total virtual memory in MiB [1]
119 AVAILABLE_VIRTUAL_MEMORY
121 Available virtual memory in MiB [1]
122 TOTAL_PHYSICAL_MEMORY
124 Total physical memory in MiB [1]
125 AVAILABLE_PHYSICAL_MEMORY
127 Available physical memory in MiB [1]
128 IS_64BIT
130 New in version 3.10.
131 One if processor is 64Bit
134 HAS_FPU
136 New in version 3.10.
137 One if processor has floating point unit
140 HAS_MMX
142 New in version 3.10.
143 One if processor supports MMX instructions
146 HAS_MMX_PLUS
148 New in version 3.10.
149 One if processor supports Ext. MMX instructions
152 HAS_SSE
154 New in version 3.10.
155 One if processor supports SSE instructions
158 HAS_SSE2
160 New in version 3.10.
161 One if processor supports SSE2 instructions
164 HAS_SSE_FP
166 New in version 3.10.
167 One if processor supports SSE FP instructions
170 HAS_SSE_MMX
172 New in version 3.10.
173 One if processor supports SSE MMX instructions
176 HAS_AMD_3DNOW
178 New in version 3.10.
179 One if processor supports 3DNow instructions
182 HAS_AMD_3DNOW_PLUS
184 New in version 3.10.
185 One if processor supports 3DNow+ instructions
188 HAS_IA64
190 New in version 3.10.
191 One if IA64 processor emulating x86
194 HAS_SERIAL_NUMBER
196 New in version 3.10.
197 One if processor has serial number
200 PROCESSOR_SERIAL_NUMBER
202 New in version 3.10.
203 Processor serial number
206 PROCESSOR_NAME
208 New in version 3.10.
209 Human readable processor name
212 PROCESSOR_DESCRIPTION
214 New in version 3.10.
215 Human readable full processor description
218 OS_NAME
220 New in version 3.10.
221 See CMAKE_HOST_SYSTEM_NAME
224 OS_RELEASE
226 New in version 3.10.
227 The OS sub-type e.g. on Windows Professional
230 OS_VERSION
232 New in version 3.10.
233 The OS build ID
236 OS_PLATFORM
238 New in version 3.10.
239 See CMAKE_HOST_SYSTEM_PROCESSOR
242 DISTRIB_INFO
244 New in version 3.22.
245 Read /etc/os-release file and define the given <variable> into a
248 list of read variables
249 DISTRIB_<name>
251 New in version 3.22.
252 Get the <name> variable (see man 5 os-release) if it exists in
255 the /etc/os-release file
256 Example:
258 cmake_host_system_information(RESULT PRETTY_NAME QUERY DISTRIB_PRETTY_NAME)
260 message(STATUS "${PRETTY_NAME}")
261 cmake_host_system_information(RESULT DISTRO QUERY DISTRIB_INFO)
263 foreach(VAR IN LISTS DISTRO)
265 message(STATUS "${VAR}=`${${VAR}}`")
266 endforeach()
267 Output:
269 -- Ubuntu 20.04.2 LTS
271 -- DISTRO_BUG_REPORT_URL=`https://bugs.launchpad.net/ubuntu/`
272 -- DISTRO_HOME_URL=`https://www.ubuntu.com/`
273 -- DISTRO_ID=`ubuntu`
274 -- DISTRO_ID_LIKE=`debian`
275 -- DISTRO_NAME=`Ubuntu`
276 -- DISTRO_PRETTY_NAME=`Ubuntu 20.04.2 LTS`
277 -- DISTRO_PRIVACY_POLICY_URL=`https://www.ubuntu.com/legal/terms-and-policies/privacy-policy`
278 -- DISTRO_SUPPORT_URL=`https://help.ubuntu.com/`
279 -- DISTRO_UBUNTU_CODENAME=`focal`
280 -- DISTRO_VERSION=`20.04.2 LTS (Focal Fossa)`
281 -- DISTRO_VERSION_CODENAME=`focal`
282 -- DISTRO_VERSION_ID=`20.04`
283 If /etc/os-release file is not found, the command tries to gather OS
285 identification via fallback scripts. The fallback script can use
286 various distribution-specific files to collect OS identification data
287 and map it into man 5 os-release variables.
288 Fallback Interface Variables
290 CMAKE_GET_OS_RELEASE_FALLBACK_SCRIPTS
291 In addition to the scripts shipped with CMake, a user may append
292 full paths to his script(s) to the this list. The script file‐
293 name has the following format: NNN-<name>.cmake, where NNN is
294 three digits used to apply collected scripts in a specific or‐
295 der.
296 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname>
298 Variables collected by the user provided fallback script ought
299 to be assigned to CMake variables using this naming convention.
300 Example, the ID variable from the manual becomes
301 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID.
302 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
304 The fallback script ought to store names of all assigned
305 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_<varname> variables in this
306 list.
307 Example:
309 # Try to detect some old distribution
311 # See also
312 # - http://linuxmafia.com/faq/Admin/release-files.html
313 #
314 if(NOT EXISTS "${CMAKE_SYSROOT}/etc/foobar-release")
315 return()
316 endif()
317 # Get the first string only
318 file(
319 STRINGS "${CMAKE_SYSROOT}/etc/foobar-release" CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT
320 LIMIT_COUNT 1
321 )
322 #
323 # Example:
324 #
325 # Foobar distribution release 1.2.3 (server)
326 #
327 if(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT MATCHES "Foobar distribution release ([0-9\.]+) .*")
328 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME Foobar)
329 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME "${CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT}")
330 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID foobar)
331 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION ${CMAKE_MATCH_1})
332 set(CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID ${CMAKE_MATCH_1})
333 list(
334 APPEND CMAKE_GET_OS_RELEASE_FALLBACK_RESULT
335 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_NAME
336 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_PRETTY_NAME
337 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_ID
338 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION
339 CMAKE_GET_OS_RELEASE_FALLBACK_RESULT_VERSION_ID
340 )
341 endif()
342 unset(CMAKE_GET_OS_RELEASE_FALLBACK_CONTENT)
343
345 [1] One MiB (mebibyte) is equal to 1024x1024 bytes.
346 Query Windows registry
348 New in version 3.24.
349 cmake_host_system_information(RESULT <variable>
352 QUERY WINDOWS_REGISTRY <key> [VALUE_NAMES|SUBKEYS|VALUE <name>]
353 [VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
354 [SEPARATOR <separator>]
355 [ERROR_VARIABLE <result>])
356 Performs query operations on local computer registry subkey. Returns a
358 list of subkeys or value names that are located under the specified
359 subkey in the registry or the data of the specified value name. The re‐
360 sult of the queried entity is stored in <variable>.
361 NOTE:
363 Querying registry for any other platforms than Windows, including
364 CYGWIN, will always returns an empty string and sets an error mes‐
365 sage in the variable specified with sub-option ERROR_VARIABLE.
366 <key> specify the full path of a subkey on the local computer. The
368 <key> must include a valid root key. Valid root keys for the local com‐
369 puter are:
370 • HKLM or HKEY_LOCAL_MACHINE
372 • HKCU or HKEY_CURRENT_USER
374 • HKCR or HKEY_CLASSES_ROOT
376 • HKU or HKEY_USERS
378 • HKCC or HKEY_CURRENT_CONFIG
380 And, optionally, the path to a subkey under the specified root key. The
382 path separator can be the slash or the backslash. <key> is not case
383 sensitive. For example:
384 cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM")
386 cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
387 cmake_host_system_information(RESULT result QUERY WINDOWS_REGISTRY "HKCU\\SOFTWARE\\Kitware")
388 VALUE_NAMES
390 Request the list of value names defined under <key>. If a de‐
391 fault value is defined, it will be identified with the special
392 name (default).
393 SUBKEYS
395 Request the list of subkeys defined under <key>.
396 VALUE <name>
398 Request the data stored in value named <name>. If VALUE is not
399 specified or argument is the special name (default), the content
400 of the default value, if any, will be returned.
401 # query default value for HKLM/SOFTWARE/Kitware key
403 cmake_host_system_information(RESULT result
404 QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware")
405 # query default value for HKLM/SOFTWARE/Kitware key using special value name
407 cmake_host_system_information(RESULT result
408 QUERY WINDOWS_REGISTRY "HKLM/SOFTWARE/Kitware"
409 VALUE "(default)")
410 Supported types are:
412 • REG_SZ.
414 • REG_EXPAND_SZ. The returned data is expanded.
416 • REG_MULTI_SZ. The returned is expressed as a CMake list. See
418 also SEPARATOR sub-option.
419 • REG_DWORD.
421 • REG_QWORD.
423 For all other types, an empty string is returned.
425 VIEW Specify which registry views must be queried. When not speci‐
427 fied, BOTH view is used.
428 64 Query the 64bit registry. On 32bit Windows, returns al‐
430 ways an empty string.
431 32 Query the 32bit registry.
433 64_32 For VALUE sub-option or default value, query the registry
435 using view 64, and if the request failed, query the reg‐
436 istry using view 32. For VALUE_NAMES and SUBKEYS sub-op‐
437 tions, query both views (64 and 32) and merge the results
438 (sorted and duplicates removed).
439 32_64 For VALUE sub-option or default value, query the registry
441 using view 32, and if the request failed, query the reg‐
442 istry using view 64. For VALUE_NAMES and SUBKEYS sub-op‐
443 tions, query both views (32 and 64) and merge the results
444 (sorted and duplicates removed).
445 HOST Query the registry matching the architecture of the host:
447 64 on 64bit Windows and 32 on 32bit Windows.
448 TARGET Query the registry matching the architecture specified by
450 CMAKE_SIZEOF_VOID_P variable. If not defined, fallback to
451 HOST view.
452 BOTH Query both views (32 and 64). The order depends of the
454 following rules: If CMAKE_SIZEOF_VOID_P variable is de‐
455 fined. Use the following view depending of the content of
456 this variable:
457 • 8: 64_32
459 • 4: 32_64
461 If CMAKE_SIZEOF_VOID_P variable is not defined, rely on
463 architecture of the host:
464 • 64bit: 64_32
466 • 32bit: 32
468 SEPARATOR
470 Specify the separator character for REG_MULTI_SZ type. When not
471 specified, the character \0 is used.
472 ERROR_VARIABLE <result>
474 Returns any error raised during query operation. In case of suc‐
475 cess, the variable holds an empty string.
476 cmake_language
478 New in version 3.18.
479 Call meta-operations on CMake commands.
482 Synopsis
484 cmake_language(CALL <command> [<arg>...])
485 cmake_language(EVAL CODE <code>...)
486 cmake_language(DEFER <options>... CALL <command> [<arg>...])
487 cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS <methods>...)
488 cmake_language(GET_MESSAGE_LOG_LEVEL <out-var>)
489 Introduction
491 This command will call meta-operations on built-in CMake commands or
492 those created via the macro() or function() commands.
493 cmake_language does not introduce a new variable or policy scope.
495 Calling Commands
497 cmake_language(CALL <command> [<arg>...])
498 Calls the named <command> with the given arguments (if any). For exam‐
500 ple, the code:
501 set(message_command "message")
503 cmake_language(CALL ${message_command} STATUS "Hello World!")
504 is equivalent to
506 message(STATUS "Hello World!")
508 NOTE:
510 To ensure consistency of the code, the following commands are not
511 allowed:
512 • if / elseif / else / endif
514 • block / endblock
516 • while / endwhile
518 • foreach / endforeach
520 • function / endfunction
522 • macro / endmacro
524 Evaluating Code
526 cmake_language(EVAL CODE <code>...)
527 Evaluates the <code>... as CMake code.
529 For example, the code:
531 set(A TRUE)
533 set(B TRUE)
534 set(C TRUE)
535 set(condition "(A AND B) OR C")
536 cmake_language(EVAL CODE "
538 if (${condition})
539 message(STATUS TRUE)
540 else()
541 message(STATUS FALSE)
542 endif()"
543 )
544 is equivalent to
546 set(A TRUE)
548 set(B TRUE)
549 set(C TRUE)
550 set(condition "(A AND B) OR C")
551 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
553 if (${condition})
554 message(STATUS TRUE)
555 else()
556 message(STATUS FALSE)
557 endif()"
558 )
559 include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
561 Deferring Calls
563 New in version 3.19.
564 cmake_language(DEFER <options>... CALL <command> [<arg>...])
567 Schedules a call to the named <command> with the given arguments (if
569 any) to occur at a later time. By default, deferred calls are executed
570 as if written at the end of the current directory's CMakeLists.txt
571 file, except that they run even after a return() call. Variable refer‐
572 ences in arguments are evaluated at the time the deferred call is exe‐
573 cuted.
574 The options are:
576 DIRECTORY <dir>
578 Schedule the call for the end of the given directory instead of
579 the current directory. The <dir> may reference either a source
580 directory or its corresponding binary directory. Relative paths
581 are treated as relative to the current source directory.
582 The given directory must be known to CMake, being either the
584 top-level directory or one added by add_subdirectory(). Fur‐
585 thermore, the given directory must not yet be finished process‐
586 ing. This means it can be the current directory or one of its
587 ancestors.
588 ID <id>
590 Specify an identification for the deferred call. The <id> may
591 not be empty and may not begin with a capital letter A-Z. The
592 <id> may begin with an underscore (_) only if it was generated
593 automatically by an earlier call that used ID_VAR to get the id.
594 ID_VAR <var>
596 Specify a variable in which to store the identification for the
597 deferred call. If ID <id> is not given, a new identification
598 will be generated and the generated id will start with an under‐
599 score (_).
600 The currently scheduled list of deferred calls may be retrieved:
602 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
604 This will store in <var> a semicolon-separated list of deferred call
606 ids. The ids are for the directory scope in which the calls have been
607 deferred to (i.e. where they will be executed), which can be different
608 to the scope in which they were created. The DIRECTORY option can be
609 used to specify the scope for which to retrieve the call ids. If that
610 option is not given, the call ids for the current directory scope will
611 be returned.
612 Details of a specific call may be retrieved from its id:
614 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
616 This will store in <var> a semicolon-separated list in which the first
618 element is the name of the command to be called, and the remaining ele‐
619 ments are its unevaluated arguments (any contained ; characters are in‐
620 cluded literally and cannot be distinguished from multiple arguments).
621 If multiple calls are scheduled with the same id, this retrieves the
622 first one. If no call is scheduled with the given id in the specified
623 DIRECTORY scope (or the current directory scope if no DIRECTORY option
624 is given), this stores an empty string in the variable.
625 Deferred calls may be canceled by their id:
627 cmake_language(DEFER [DIRECTORY <dir>] CANCEL_CALL <id>...)
629 This cancels all deferred calls matching any of the given ids in the
631 specified DIRECTORY scope (or the current directory scope if no DIREC‐
632 TORY option is given). Unknown ids are silently ignored.
633 Deferred Call Examples
635 For example, the code:
636 cmake_language(DEFER CALL message "${deferred_message}")
638 cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
639 cmake_language(DEFER CANCEL_CALL ${id})
640 message("Immediate Message")
641 set(deferred_message "Deferred Message")
642 prints:
644 Immediate Message
646 Deferred Message
647 The Cancelled Message is never printed because its command is canceled.
649 The deferred_message variable reference is not evaluated until the call
650 site, so it can be set after the deferred call is scheduled.
651 In order to evaluate variable references immediately when scheduling a
653 deferred call, wrap it using cmake_language(EVAL). However, note that
654 arguments will be re-evaluated in the deferred call, though that can be
655 avoided by using bracket arguments. For example:
656 set(deferred_message "Deferred Message 1")
658 set(re_evaluated [[${deferred_message}]])
659 cmake_language(EVAL CODE "
660 cmake_language(DEFER CALL message [[${deferred_message}]])
661 cmake_language(DEFER CALL message \"${re_evaluated}\")
662 ")
663 message("Immediate Message")
664 set(deferred_message "Deferred Message 2")
665 also prints:
667 Immediate Message
669 Deferred Message 1
670 Deferred Message 2
671 Dependency Providers
673 New in version 3.24.
674 NOTE:
677 A high-level introduction to this feature can be found in the Using
678 Dependencies Guide.
679 cmake_language(SET_DEPENDENCY_PROVIDER <command>
681 SUPPORTED_METHODS <methods>...)
682 When a call is made to find_package() or FetchContent_MakeAvailable(),
684 the call may be forwarded to a dependency provider which then has the
685 opportunity to fulfill the request. If the request is for one of the
686 <methods> specified when the provider was set, CMake calls the
687 provider's <command> with a set of method-specific arguments. If the
688 provider does not fulfill the request, or if the provider doesn't sup‐
689 port the request's method, or no provider is set, the built-in
690 find_package() or FetchContent_MakeAvailable() implementation is used
691 to fulfill the request in the usual way.
692 One or more of the following values can be specified for the <methods>
694 when setting the provider:
695 FIND_PACKAGE
697 The provider command accepts find_package() requests.
698 FETCHCONTENT_MAKEAVAILABLE_SERIAL
700 The provider command accepts FetchContent_MakeAvailable() re‐
701 quests. It expects each dependency to be fed to the provider
702 command one at a time, not the whole list in one go.
703 Only one provider can be set at any point in time. If a provider is
705 already set when cmake_language(SET_DEPENDENCY_PROVIDER) is called, the
706 new provider replaces the previously set one. The specified <command>
707 must already exist when cmake_language(SET_DEPENDENCY_PROVIDER) is
708 called. As a special case, providing an empty string for the <command>
709 and no <methods> will discard any previously set provider.
710 The dependency provider can only be set while processing one of the
712 files specified by the CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable.
713 Thus, dependency providers can only be set as part of the first call to
714 project(). Calling cmake_language(SET_DEPENDENCY_PROVIDER) outside of
715 that context will result in an error.
716 NOTE:
718 The choice of dependency provider should always be under the user's
719 control. As a convenience, a project may choose to provide a file
720 that users can list in their CMAKE_PROJECT_TOP_LEVEL_INCLUDES vari‐
721 able, but the use of such a file should always be the user's choice.
722 Provider commands
724 Providers define a single <command> to accept requests. The name of
725 the command should be specific to that provider, not something overly
726 generic that another provider might also use. This enables users to
727 compose different providers in their own custom provider. The recom‐
728 mended form is xxx_provide_dependency(), where xxx is the provider-spe‐
729 cific part (e.g. vcpkg_provide_dependency(), conan_provide_depen‐
730 dency(), ourcompany_provide_dependency(), and so on).
731 xxx_provide_dependency(<method> [<method-specific-args>...])
733 Because some methods expect certain variables to be set in the calling
735 scope, the provider command should typically be implemented as a macro
736 rather than a function. This ensures it does not introduce a new vari‐
737 able scope.
738 The arguments CMake passes to the dependency provider depend on the
740 type of request. The first argument is always the method, and it will
741 only ever be one of the <methods> that was specified when setting the
742 provider.
743 FIND_PACKAGE
745 The <method-specific-args> will be everything passed to the
746 find_package() call that requested the dependency. The first of
747 these <method-specific-args> will therefore always be the name
748 of the dependency. Dependency names are case-sensitive for this
749 method because find_package() treats them case-sensitively too.
750 If the provider command fulfills the request, it must set the
752 same variable that find_package() expects to be set. For a de‐
753 pendency named depName, the provider must set depName_FOUND to
754 true if it fulfilled the request. If the provider returns with‐
755 out setting this variable, CMake will assume the request was not
756 fulfilled and will fall back to the built-in implementation.
757 If the provider needs to call the built-in find_package() imple‐
759 mentation as part of its processing, it can do so by including
760 the BYPASS_PROVIDER keyword as one of the arguments.
761 FETCHCONTENT_MAKEAVAILABE_SERIAL
763 The <method-specific-args> will be everything passed to the
764 FetchContent_Declare() call that corresponds to the requested
765 dependency, with the following exceptions:
766 • If SOURCE_DIR or BINARY_DIR were not part of the original de‐
768 clared arguments, they will be added with their default val‐
769 ues.
770 • If FETCHCONTENT_TRY_FIND_PACKAGE_MODE is set to NEVER, any
772 FIND_PACKAGE_ARGS will be omitted.
773 • The OVERRIDE_FIND_PACKAGE keyword is always omitted.
775 The first of the <method-specific-args> will always be the name
777 of the dependency. Dependency names are case-insensitive for
778 this method because FetchContent also treats them case-insensi‐
779 tively.
780 If the provider fulfills the request, it should call
782 FetchContent_SetPopulated(), passing the name of the dependency
783 as the first argument. The SOURCE_DIR and BINARY_DIR arguments
784 to that command should only be given if the provider makes the
785 dependency's source and build directories available in exactly
786 the same way as the built-in FetchContent_MakeAvailable() com‐
787 mand.
788 If the provider returns without calling
790 FetchContent_SetPopulated() for the named dependency, CMake will
791 assume the request was not fulfilled and will fall back to the
792 built-in implementation.
793 Note that empty arguments may be significant for this method
795 (e.g. an empty string following a GIT_SUBMODULES keyword).
796 Therefore, if forwarding these arguments on to another command,
797 extra care must be taken to avoid such arguments being silently
798 dropped.
799 If FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> is set, then the
801 dependency provider will never see requests for the <depName>
802 dependency for this method. When the user sets such a variable,
803 they are explicitly overriding where to get that dependency from
804 and are taking on the responsibility that their overriding ver‐
805 sion meets any requirements for that dependency and is compati‐
806 ble with whatever else in the project uses it. Depending on the
807 value of FETCHCONTENT_TRY_FIND_PACKAGE_MODE and whether the
808 OVERRIDE_FIND_PACKAGE option was given to
809 FetchContent_Declare(), having FETCHCONTENT_SOURCE_DIR_<upper‐
810 caseDepName> set may also prevent the dependency provider from
811 seeing requests for a find_package(depName) call too.
812 Provider Examples
814 This first example only intercepts find_package() calls. The provider
815 command runs an external tool which copies the relevant artifacts into
816 a provider-specific directory, if that tool knows about the dependency.
817 It then relies on the built-in implementation to then find those arti‐
818 facts. FetchContent_MakeAvailable() calls would not go through the
819 provider.
820 mycomp_provider.cmake
822 # Always ensure we have the policy settings this provider expects
824 cmake_minimum_required(VERSION 3.24)
825 set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
827 CACHE PATH "The directory this provider installs packages to"
828 )
829 # Tell the built-in implementation to look in our area first, unless
830 # the find_package() call uses NO_..._PATH options to exclude it
831 list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
832 list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})
833 macro(mycomp_provide_dependency method package_name)
835 execute_process(
836 COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
837 COMMAND_ERROR_IS_FATAL ANY
838 )
839 endmacro()
840 cmake_language(
842 SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
843 SUPPORTED_METHODS FIND_PACKAGE
844 )
845 The user would then typically use the above file like so:
847 cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...
849 The next example demonstrates a provider that accepts both methods, but
851 only handles one specific dependency. It enforces providing Google
852 Test using FetchContent, but leaves all other dependencies to be ful‐
853 filled by CMake's built-in implementation. It accepts a few different
854 names, which demonstrates one way of working around projects that
855 hard-code an unusual or undesirable way of adding this particular de‐
856 pendency to the build. The example also demonstrates how to use the
857 list() command to preserve variables that may be overwritten by a call
858 to FetchContent_MakeAvailable().
859 mycomp_provider.cmake
861 cmake_minimum_required(VERSION 3.24)
863 # Because we declare this very early, it will take precedence over any
865 # details the project might declare later for the same thing
866 include(FetchContent)
867 FetchContent_Declare(
868 googletest
869 GIT_REPOSITORY https://github.com/google/googletest.git
870 GIT_TAG e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
871 )
872 # Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
874 # the package or dependency name as the first method-specific argument.
875 macro(mycomp_provide_dependency method dep_name)
876 if("${dep_name}" MATCHES "^(gtest|googletest)$")
877 # Save our current command arguments in case we are called recursively
878 list(APPEND mycomp_provider_args ${method} ${dep_name})
879 # This will forward to the built-in FetchContent implementation,
881 # which detects a recursive call for the same thing and avoids calling
882 # the provider again if dep_name is the same as the current call.
883 FetchContent_MakeAvailable(googletest)
884 # Restore our command arguments
886 list(POP_BACK mycomp_provider_args dep_name method)
887 # Tell the caller we fulfilled the request
889 if("${method}" STREQUAL "FIND_PACKAGE")
890 # We need to set this if we got here from a find_package() call
891 # since we used a different method to fulfill the request.
892 # This example assumes projects only use the gtest targets,
893 # not any of the variables the FindGTest module may define.
894 set(${dep_name}_FOUND TRUE)
895 elseif(NOT "${dep_name}" STREQUAL "googletest")
896 # We used the same method, but were given a different name to the
897 # one we populated with. Tell the caller about the name it used.
898 FetchContent_SetPopulated(${dep_name}
899 SOURCE_DIR "${googletest_SOURCE_DIR}"
900 BINARY_DIR "${googletest_BINARY_DIR}"
901 )
902 endif()
903 endif()
904 endmacro()
905 cmake_language(
907 SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
908 SUPPORTED_METHODS
909 FIND_PACKAGE
910 FETCHCONTENT_MAKEAVAILABLE_SERIAL
911 )
912 The final example demonstrates how to modify arguments to a
914 find_package() call. It forces all such calls to have the QUIET key‐
915 word. It uses the BYPASS_PROVIDER keyword to prevent calling the
916 provider command recursively for the same dependency.
917 mycomp_provider.cmake
919 cmake_minimum_required(VERSION 3.24)
921 macro(mycomp_provide_dependency method)
923 find_package(${ARGN} BYPASS_PROVIDER QUIET)
924 endmacro()
925 cmake_language(
927 SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
928 SUPPORTED_METHODS FIND_PACKAGE
929 )
930 Getting current message log level
932 New in version 3.25.
933 cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
936 Writes the current message() logging level into the given <output_vari‐
938 able>.
939 See message() for the possible logging levels.
941 The current message logging level can be set either using the
943 --log-level command line option of the cmake(1) program or using the
944 CMAKE_MESSAGE_LOG_LEVEL variable.
945 If both the command line option and the variable are set, the command
947 line option takes precedence. If neither are set, the default logging
948 level is returned.
949 cmake_minimum_required
951 Require a minimum version of cmake.
952 cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])
954 New in version 3.12: The optional <policy_max> version.
956 Sets the minimum required version of cmake for a project. Also updates
959 the policy settings as explained below.
960 <min> and the optional <policy_max> are each CMake versions of the form
962 major.minor[.patch[.tweak]], and the ... is literal.
963 If the running version of CMake is lower than the <min> required ver‐
965 sion it will stop processing the project and report an error. The op‐
966 tional <policy_max> version, if specified, must be at least the <min>
967 version and affects policy settings as described in Policy Settings.
968 If the running version of CMake is older than 3.12, the extra ... dots
969 will be seen as version component separators, resulting in the ...<max>
970 part being ignored and preserving the pre-3.12 behavior of basing poli‐
971 cies on <min>.
972 This command will set the value of the CMAKE_MINIMUM_REQUIRED_VERSION
974 variable to <min>.
975 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
977 It should be specified so CMake versions 2.4 and lower fail with an er‐
978 ror instead of just a warning.
979 NOTE:
981 Call the cmake_minimum_required() command at the beginning of the
982 top-level CMakeLists.txt file even before calling the project() com‐
983 mand. It is important to establish version and policy settings be‐
984 fore invoking other commands whose behavior they may affect. See
985 also policy CMP0000.
986 Calling cmake_minimum_required() inside a function() limits some ef‐
988 fects to the function scope when invoked. For example, the
989 CMAKE_MINIMUM_REQUIRED_VERSION variable won't be set in the calling
990 scope. Functions do not introduce their own policy scope though, so
991 policy settings of the caller will be affected (see below). Due to
992 this mix of things that do and do not affect the calling scope,
993 calling cmake_minimum_required() inside a function is generally dis‐
994 couraged.
995 Policy Settings
997 The cmake_minimum_required(VERSION) command implicitly invokes the
998 cmake_policy(VERSION) command to specify that the current project code
999 is written for the given range of CMake versions. All policies known
1000 to the running version of CMake and introduced in the <min> (or <max>,
1001 if specified) version or earlier will be set to use NEW behavior. All
1002 policies introduced in later versions will be unset. This effectively
1003 requests behavior preferred as of a given CMake version and tells newer
1004 CMake versions to warn about their new policies.
1005 When a <min> version higher than 2.4 is specified the command implic‐
1007 itly invokes
1008 cmake_policy(VERSION <min>[...<max>])
1010 which sets CMake policies based on the range of versions specified.
1012 When a <min> version 2.4 or lower is given the command implicitly in‐
1013 vokes
1014 cmake_policy(VERSION 2.4[...<max>])
1016 which enables compatibility features for CMake 2.4 and lower.
1018 cmake_parse_arguments
1020 Parse function or macro arguments.
1021 cmake_parse_arguments(<prefix> <options> <one_value_keywords>
1023 <multi_value_keywords> <args>...)
1024 cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
1026 <one_value_keywords> <multi_value_keywords>)
1027 New in version 3.5: This command is implemented natively. Previously,
1029 it has been defined in the module CMakeParseArguments.
1030 This command is for use in macros or functions. It processes the argu‐
1033 ments given to that macro or function, and defines a set of variables
1034 which hold the values of the respective options.
1035 The first signature reads processes arguments passed in the <args>....
1037 This may be used in either a macro() or a function().
1038 New in version 3.7: The PARSE_ARGV signature is only for use in a
1040 function() body. In this case the arguments that are parsed come from
1041 the ARGV# variables of the calling function. The parsing starts with
1042 the <N>-th argument, where <N> is an unsigned integer. This allows for
1043 the values to have special characters like ; in them.
1044 The <options> argument contains all options for the respective macro,
1047 i.e. keywords which can be used when calling the macro without any
1048 value following, like e.g. the OPTIONAL keyword of the install() com‐
1049 mand.
1050 The <one_value_keywords> argument contains all keywords for this macro
1052 which are followed by one value, like e.g. DESTINATION keyword of the
1053 install() command.
1054 The <multi_value_keywords> argument contains all keywords for this
1056 macro which can be followed by more than one value, like e.g. the TAR‐
1057 GETS or FILES keywords of the install() command.
1058 Changed in version 3.5: All keywords shall be unique. I.e. every key‐
1060 word shall only be specified once in either <options>, <one_value_key‐
1061 words> or <multi_value_keywords>. A warning will be emitted if unique‐
1062 ness is violated.
1063 When done, cmake_parse_arguments will consider for each of the keywords
1066 listed in <options>, <one_value_keywords> and <multi_value_keywords> a
1067 variable composed of the given <prefix> followed by "_" and the name of
1068 the respective keyword. These variables will then hold the respective
1069 value from the argument list or be undefined if the associated option
1070 could not be found. For the <options> keywords, these will always be
1071 defined, to TRUE or FALSE, whether the option is in the argument list
1072 or not.
1073 All remaining arguments are collected in a variable <prefix>_UN‐
1075 PARSED_ARGUMENTS that will be undefined if all arguments were recog‐
1076 nized. This can be checked afterwards to see whether your macro was
1077 called with unrecognized parameters.
1078 New in version 3.15: <one_value_keywords> and <multi_value_keywords>
1080 that were given no values at all are collected in a variable <pre‐
1081 fix>_KEYWORDS_MISSING_VALUES that will be undefined if all keywords re‐
1082 ceived values. This can be checked to see if there were keywords with‐
1083 out any values given.
1084 Consider the following example macro, my_install(), which takes similar
1087 arguments to the real install() command:
1088 macro(my_install)
1090 set(options OPTIONAL FAST)
1091 set(oneValueArgs DESTINATION RENAME)
1092 set(multiValueArgs TARGETS CONFIGURATIONS)
1093 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
1094 "${multiValueArgs}" ${ARGN} )
1095 # ...
1097 Assume my_install() has been called like this:
1099 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
1101 After the cmake_parse_arguments call the macro will have set or unde‐
1103 fined the following variables:
1104 MY_INSTALL_OPTIONAL = TRUE
1106 MY_INSTALL_FAST = FALSE # was not used in call to my_install
1107 MY_INSTALL_DESTINATION = "bin"
1108 MY_INSTALL_RENAME <UNDEFINED> # was not used
1109 MY_INSTALL_TARGETS = "foo;bar"
1110 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
1111 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
1112 MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
1113 # No value for "CONFIGURATIONS" given
1114 You can then continue and process these variables.
1116 Keywords terminate lists of values, e.g. if directly after a
1118 one_value_keyword another recognized keyword follows, this is inter‐
1119 preted as the beginning of the new option. E.g. my_install(TARGETS
1120 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
1121 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
1122 will be empty (but added to MY_INSTALL_KEYWORDS_MISSING_VALUES) and
1123 MY_INSTALL_OPTIONAL will therefore be set to TRUE.
1124 cmake_path
1126 New in version 3.20.
1127 This command is for the manipulation of paths. Only syntactic aspects
1130 of paths are handled, there is no interaction of any kind with any un‐
1131 derlying file system. The path may represent a non-existing path or
1132 even one that is not allowed to exist on the current file system or
1133 platform. For operations that do interact with the filesystem, see the
1134 file() command.
1135 NOTE:
1137 The cmake_path command handles paths in the format of the build sys‐
1138 tem (i.e. the host platform), not the target system. When
1139 cross-compiling, if the path contains elements that are not repre‐
1140 sentable on the host platform (e.g. a drive letter when the host is
1141 not Windows), the results will be unpredictable.
1142 Synopsis
1144 Conventions
1145 Path Structure And Terminology
1147 Normalization
1149 Decomposition
1151 cmake_path(GET <path-var> ROOT_NAME <out-var>)
1152 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
1153 cmake_path(GET <path-var> ROOT_PATH <out-var>)
1154 cmake_path(GET <path-var> FILENAME <out-var>)
1155 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
1156 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
1157 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
1158 cmake_path(GET <path-var> PARENT_PATH <out-var>)
1159 Query
1161 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
1162 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
1163 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
1164 cmake_path(HAS_FILENAME <path-var> <out-var>)
1165 cmake_path(HAS_EXTENSION <path-var> <out-var>)
1166 cmake_path(HAS_STEM <path-var> <out-var>)
1167 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
1168 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
1169 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
1170 cmake_path(IS_RELATIVE <path-var> <out-var>)
1171 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
1172 cmake_path(COMPARE <input1> <OP> <input2> <out-var>)
1173 Modification
1175 cmake_path(SET <path-var> [NORMALIZE] <input>)
1176 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1177 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1178 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
1179 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
1180 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
1181 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])
1182 Generation
1184 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
1185 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
1186 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])
1187 Native Conversion
1189 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
1190 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
1191 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
1192 Hashing
1194 cmake_path(HASH <path-var> <out-var>)
1195 Conventions
1197 The following conventions are used in this command's documentation:
1198 <path-var>
1200 Always the name of a variable. For commands that expect a
1201 <path-var> as input, the variable must exist and it is expected
1202 to hold a single path.
1203 <input>
1205 A string literal which may contain a path, path fragment, or
1206 multiple paths with a special separator depending on the com‐
1207 mand. See the description of each command to see how this is
1208 interpreted.
1209 <input>...
1211 Zero or more string literal arguments.
1212 <out-var>
1214 The name of a variable into which the result of a command will
1215 be written.
1216 Path Structure And Terminology
1218 A path has the following structure (all components are optional, with
1219 some constraints):
1220 root-name root-directory-separator (item-name directory-separator)* filename
1222 root-name
1224 Identifies the root on a filesystem with multiple roots (such as
1225 "C:" or "//myserver"). It is optional.
1226 root-directory-separator
1228 A directory separator that, if present, indicates that this path
1229 is absolute. If it is missing and the first element other than
1230 the root-name is an item-name, then the path is relative.
1231 item-name
1233 A sequence of characters that aren't directory separators. This
1234 name may identify a file, a hard link, a symbolic link, or a di‐
1235 rectory. Two special cases are recognized:
1236 • The item name consisting of a single dot character . is a
1238 directory name that refers to the current directory.
1239 • The item name consisting of two dot characters .. is a di‐
1241 rectory name that refers to the parent directory.
1242 The (...)* pattern shown above is to indicate that there can be
1244 zero or more item names, with multiple items separated by a di‐
1245 rectory-separator. The ()* characters are not part of the path.
1246 directory-separator
1248 The only recognized directory separator is a forward slash char‐
1249 acter /. If this character is repeated, it is treated as a sin‐
1250 gle directory separator. In other words, /usr///////lib is the
1251 same as /usr/lib.
1252 filename
1254 A path has a filename if it does not end with a directory-sepa‐
1255 rator. The filename is effectively the last item-name of the
1256 path, so it can also be a hard link, symbolic link or a direc‐
1257 tory.
1258 A filename can have an extension. By default, the extension is
1260 defined as the sub-string beginning at the left-most period (in‐
1261 cluding the period) and until the end of the filename. In com‐
1262 mands that accept a LAST_ONLY keyword, LAST_ONLY changes the in‐
1263 terpretation to the sub-string beginning at the right-most pe‐
1264 riod.
1265 The following exceptions apply to the above interpretation:
1267 • If the first character in the filename is a period, that
1269 period is ignored (i.e. a filename like ".profile" is
1270 treated as having no extension).
1271 • If the filename is either . or .., it has no extension.
1273 The stem is the part of the filename before the extension.
1275 Some commands refer to a root-path. This is the concatenation of
1277 root-name and root-directory-separator, either or both of which can be
1278 empty. A relative-part refers to the full path with any root-path re‐
1279 moved.
1280 Creating A Path Variable
1282 While a path can be created with care using an ordinary set() command,
1283 it is recommended to use cmake_path(SET) instead, as it automatically
1284 converts the path to the required form where required. The
1285 cmake_path(APPEND) subcommand may be another suitable alternative where
1286 a path needs to be constructed by joining fragments. The following ex‐
1287 ample compares the three methods for constructing the same path:
1288 set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")
1290 cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")
1292 cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")
1294 Modification and Generation sub-commands can either store the result
1296 in-place, or in a separate variable named after an OUTPUT_VARIABLE key‐
1297 word. All other sub-commands store the result in a mandatory <out-var>
1298 variable.
1299 Normalization
1301 Some sub-commands support normalizing a path. The algorithm used to
1302 normalize a path is as follows:
1303 1. If the path is empty, stop (the normalized form of an empty path is
1305 also an empty path).
1306 2. Replace each directory-separator, which may consist of multiple sep‐
1308 arators, with a single / (/a///b --> /a/b).
1309 3. Remove each solitary period (.) and any immediately following direc‐
1311 tory-separator (/a/./b/. --> /a/b).
1312 4. Remove each item-name (other than ..) that is immediately followed
1314 by a directory-separator and a .., along with any immediately fol‐
1315 lowing directory-separator (/a/b/../c --> a/c).
1316 5. If there is a root-directory, remove any .. and any directory-sepa‐
1318 rators immediately following them. The parent of the root directory
1319 is treated as still the root directory (/../a --> /a).
1320 6. If the last item-name is .., remove any trailing directory-separator
1322 (../ --> ..).
1323 7. If the path is empty by this stage, add a dot (normal form of ./ is
1325 .).
1326 Decomposition
1328 The following forms of the GET subcommand each retrieve a different
1329 component or group of components from a path. See Path Structure And
1330 Terminology for the meaning of each path component.
1331 cmake_path(GET <path-var> ROOT_NAME <out-var>)
1333 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
1334 cmake_path(GET <path-var> ROOT_PATH <out-var>)
1335 cmake_path(GET <path-var> FILENAME <out-var>)
1336 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
1337 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
1338 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
1339 cmake_path(GET <path-var> PARENT_PATH <out-var>)
1340 If a requested component is not present in the path, an empty string
1342 will be stored in <out-var>. For example, only Windows systems have
1343 the concept of a root-name, so when the host machine is non-Windows,
1344 the ROOT_NAME subcommand will always return an empty string.
1345 For PARENT_PATH, if the HAS_RELATIVE_PART subcommand returns false, the
1347 result is a copy of <path-var>. Note that this implies that a root di‐
1348 rectory is considered to have a parent, with that parent being itself.
1349 Where HAS_RELATIVE_PART returns true, the result will essentially be
1350 <path-var> with one less element.
1351 Root examples
1353 set(path "c:/a")
1354 cmake_path(GET path ROOT_NAME rootName)
1356 cmake_path(GET path ROOT_DIRECTORY rootDir)
1357 cmake_path(GET path ROOT_PATH rootPath)
1358 message("Root name is \"${rootName}\"")
1360 message("Root directory is \"${rootDir}\"")
1361 message("Root path is \"${rootPath}\"")
1362 Root name is "c:"
1364 Root directory is "/"
1365 Root path is "c:/"
1366 Filename examples
1368 set(path "/a/b")
1369 cmake_path(GET path FILENAME filename)
1370 message("First filename is \"${filename}\"")
1371 # Trailing slash means filename is empty
1373 set(path "/a/b/")
1374 cmake_path(GET path FILENAME filename)
1375 message("Second filename is \"${filename}\"")
1376 First filename is "b"
1378 Second filename is ""
1379 Extension and stem examples
1381 set(path "name.ext1.ext2")
1382 cmake_path(GET path EXTENSION fullExt)
1384 cmake_path(GET path STEM fullStem)
1385 message("Full extension is \"${fullExt}\"")
1386 message("Full stem is \"${fullStem}\"")
1387 # Effect of LAST_ONLY
1389 cmake_path(GET path EXTENSION LAST_ONLY lastExt)
1390 cmake_path(GET path STEM LAST_ONLY lastStem)
1391 message("Last extension is \"${lastExt}\"")
1392 message("Last stem is \"${lastStem}\"")
1393 # Special cases
1395 set(dotPath "/a/.")
1396 set(dotDotPath "/a/..")
1397 set(someMorePath "/a/.some.more")
1398 cmake_path(GET dotPath EXTENSION dotExt)
1399 cmake_path(GET dotPath STEM dotStem)
1400 cmake_path(GET dotDotPath EXTENSION dotDotExt)
1401 cmake_path(GET dotDotPath STEM dotDotStem)
1402 cmake_path(GET dotMorePath EXTENSION someMoreExt)
1403 cmake_path(GET dotMorePath STEM someMoreStem)
1404 message("Dot extension is \"${dotExt}\"")
1405 message("Dot stem is \"${dotStem}\"")
1406 message("Dot-dot extension is \"${dotDotExt}\"")
1407 message("Dot-dot stem is \"${dotDotStem}\"")
1408 message(".some.more extension is \"${someMoreExt}\"")
1409 message(".some.more stem is \"${someMoreStem}\"")
1410 Full extension is ".ext1.ext2"
1412 Full stem is "name"
1413 Last extension is ".ext2"
1414 Last stem is "name.ext1"
1415 Dot extension is ""
1416 Dot stem is "."
1417 Dot-dot extension is ""
1418 Dot-dot stem is ".."
1419 .some.more extension is ".more"
1420 .some.more stem is ".some"
1421 Relative part examples
1423 set(path "c:/a/b")
1424 cmake_path(GET path RELATIVE_PART result)
1425 message("Relative part is \"${result}\"")
1426 set(path "c/d")
1428 cmake_path(GET path RELATIVE_PART result)
1429 message("Relative part is \"${result}\"")
1430 set(path "/")
1432 cmake_path(GET path RELATIVE_PART result)
1433 message("Relative part is \"${result}\"")
1434 Relative part is "a/b"
1436 Relative part is "c/d"
1437 Relative part is ""
1438 Path traversal examples
1440 set(path "c:/a/b")
1441 cmake_path(GET path PARENT_PATH result)
1442 message("Parent path is \"${result}\"")
1443 set(path "c:/")
1445 cmake_path(GET path PARENT_PATH result)
1446 message("Parent path is \"${result}\"")
1447 Parent path is "c:/a"
1449 Parent path is "c:/"
1450 Query
1452 Each of the GET subcommands has a corresponding HAS_... subcommand
1453 which can be used to discover whether a particular path component is
1454 present. See Path Structure And Terminology for the meaning of each
1455 path component.
1456 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
1458 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
1459 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
1460 cmake_path(HAS_FILENAME <path-var> <out-var>)
1461 cmake_path(HAS_EXTENSION <path-var> <out-var>)
1462 cmake_path(HAS_STEM <path-var> <out-var>)
1463 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
1464 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
1465 Each of the above follows the predictable pattern of setting <out-var>
1467 to true if the path has the associated component, or false otherwise.
1468 Note the following special cases:
1469 • For HAS_ROOT_PATH, a true result will only be returned if at least
1471 one of root-name or root-directory is non-empty.
1472 • For HAS_PARENT_PATH, the root directory is also considered to have a
1474 parent, which will be itself. The result is true except if the path
1475 consists of just a filename.
1476 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
1478 Sets <out-var> to true if <path-var> is absolute. An absolute path is
1480 a path that unambiguously identifies the location of a file without
1481 reference to an additional starting location. On Windows, this means
1482 the path must have both a root-name and a root-directory-separator to
1483 be considered absolute. On other platforms, just a root-directory-sep‐
1484 arator is sufficient. Note that this means on Windows, IS_ABSOLUTE can
1485 be false while HAS_ROOT_DIRECTORY can be true.
1486 cmake_path(IS_RELATIVE <path-var> <out-var>)
1488 This will store the opposite of IS_ABSOLUTE in <out-var>.
1490 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
1492 Checks if <path-var> is the prefix of <input>.
1494 When the NORMALIZE option is specified, <path-var> and <input> are
1496 normalized before the check.
1497 set(path "/a/b/c")
1499 cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
1500 cmake_path(IS_PREFIX path "/a/b" result) # result = false
1501 cmake_path(IS_PREFIX path "/x/y/z" result) # result = false
1502 set(path "/a/b")
1504 cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
1505 cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
1507 cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
1508 Compares the lexical representations of two paths provided as string
1510 literals. No normalization is performed on either path, except multi‐
1511 ple consecutive directory separators are effectively collapsed into a
1512 single separator. Equality is determined according to the following
1513 pseudo-code logic:
1514 if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
1516 return FALSE
1517 if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
1519 return FALSE
1520 Return FALSE if a relative portion of <input1> is not lexicographically
1522 equal to the relative portion of <input2>. This comparison is performed path
1523 component-wise. If all of the components compare equal, then return TRUE.
1524 NOTE:
1526 Unlike most other cmake_path() subcommands, the COMPARE subcommand
1527 takes literal strings as input, not the names of variables.
1528 Modification
1530 cmake_path(SET <path-var> [NORMALIZE] <input>)
1531 Assign the <input> path to <path-var>. If <input> is a native path, it
1533 is converted into a cmake-style path with forward-slashes (/). On Win‐
1534 dows, the long filename marker is taken into account.
1535 When the NORMALIZE option is specified, the path is normalized after
1537 the conversion.
1538 For example:
1540 set(native_path "c:\\a\\b/..\\c")
1542 cmake_path(SET path "${native_path}")
1543 message("CMake path is \"${path}\"")
1544 cmake_path(SET path NORMALIZE "${native_path}")
1546 message("Normalized CMake path is \"${path}\"")
1547 Output:
1549 CMake path is "c:/a/b/../c"
1551 Normalized CMake path is "c:/a/c"
1552 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1554 Append all the <input> arguments to the <path-var> using / as the di‐
1556 rectory-separator. Depending on the <input>, the previous contents of
1557 <path-var> may be discarded. For each <input> argument, the following
1558 algorithm (pseudo-code) applies:
1559 # <path> is the contents of <path-var>
1561 if(<input>.is_absolute() OR
1563 (<input>.has_root_name() AND
1564 NOT <input>.root_name() STREQUAL <path>.root_name()))
1565 replace <path> with <input>
1566 return()
1567 endif()
1568 if(<input>.has_root_directory())
1570 remove any root-directory and the entire relative path from <path>
1571 elseif(<path>.has_filename() OR
1572 (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
1573 append directory-separator to <path>
1574 endif()
1575 append <input> omitting any root-name to <path>
1577 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1579 Append all the <input> arguments to the <path-var> without adding any
1581 directory-separator.
1582 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
1584 Removes the filename component (as returned by GET ... FILENAME) from
1586 <path-var>. After removal, any trailing directory-separator is left
1587 alone, if present.
1588 If OUTPUT_VARIABLE is not given, then after this function returns,
1590 HAS_FILENAME returns false for <path-var>.
1591 For example:
1593 set(path "/a/b")
1595 cmake_path(REMOVE_FILENAME path)
1596 message("First path is \"${path}\"")
1597 # filename is now already empty, the following removes nothing
1599 cmake_path(REMOVE_FILENAME path)
1600 message("Second path is \"${result}\"")
1601 Output:
1603 First path is "/a/"
1605 Second path is "/a/"
1606 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
1608 Replaces the filename component from <path-var> with <input>. If
1610 <path-var> has no filename component (i.e. HAS_FILENAME returns
1611 false), the path is unchanged. The operation is equivalent to the fol‐
1612 lowing:
1613 cmake_path(HAS_FILENAME path has_filename)
1615 if(has_filename)
1616 cmake_path(REMOVE_FILENAME path)
1617 cmake_path(APPEND path input);
1618 endif()
1619 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
1621 [OUTPUT_VARIABLE <out-var>])
1622 Removes the extension, if any, from <path-var>.
1624 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
1626 [OUTPUT_VARIABLE <out-var>])
1627 Replaces the extension with <input>. Its effect is equivalent to the
1629 following:
1630 cmake_path(REMOVE_EXTENSION path)
1632 if(NOT "input" MATCHES "^\\.")
1633 cmake_path(APPEND_STRING path ".")
1634 endif()
1635 cmake_path(APPEND_STRING path "input")
1636 Generation
1638 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
1639 Normalize <path-var> according the steps described in Normalization.
1641 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
1643 [OUTPUT_VARIABLE <out-var>])
1644 Modifies <path-var> to make it relative to the BASE_DIRECTORY argument.
1646 If BASE_DIRECTORY is not specified, the default base directory will be
1647 CMAKE_CURRENT_SOURCE_DIR.
1648 For reference, the algorithm used to compute the relative path is the
1650 same as that used by C++ std::filesystem::path::lexically_relative.
1651 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
1653 [OUTPUT_VARIABLE <out-var>])
1654 If <path-var> is a relative path (IS_RELATIVE is true), it is evaluated
1656 relative to the given base directory specified by BASE_DIRECTORY op‐
1657 tion. If BASE_DIRECTORY is not specified, the default base directory
1658 will be CMAKE_CURRENT_SOURCE_DIR.
1659 When the NORMALIZE option is specified, the path is normalized after
1661 the path computation.
1662 Because cmake_path() does not access the filesystem, symbolic links are
1664 not resolved and any leading tilde is not expanded. To compute a real
1665 path with symbolic links resolved and leading tildes expanded, use the
1666 file(REAL_PATH) command instead.
1667 Native Conversion
1669 For commands in this section, native refers to the host platform, not
1670 the target platform when cross-compiling.
1671 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
1673 Converts a cmake-style <path-var> into a native path with platform-spe‐
1675 cific slashes (\ on Windows hosts and / elsewhere).
1676 When the NORMALIZE option is specified, the path is normalized before
1678 the conversion.
1679 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
1681 Converts a native <input> path into a cmake-style path with forward
1683 slashes (/). On Windows hosts, the long filename marker is taken into
1684 account. The input can be a single path or a system search path like
1685 $ENV{PATH}. A search path will be converted to a cmake-style list sep‐
1686 arated by ; characters (on non-Windows platforms, this essentially
1687 means : separators are replaced with ;). The result of the conversion
1688 is stored in the <out-var> variable.
1689 When the NORMALIZE option is specified, the path is normalized before
1691 the conversion.
1692 NOTE:
1694 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1695 takes a literal string as input, not the name of a variable.
1696 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
1698 Converts a cmake-style <input> path into a native path with plat‐
1700 form-specific slashes (\ on Windows hosts and / elsewhere). The input
1701 can be a single path or a cmake-style list. A list will be converted
1702 into a native search path (;-separated on Windows, :-separated on other
1703 platforms). The result of the conversion is stored in the <out-var>
1704 variable.
1705 When the NORMALIZE option is specified, the path is normalized before
1707 the conversion.
1708 NOTE:
1710 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1711 takes a literal string as input, not the name of a variable.
1712 For example:
1714 set(paths "/a/b/c" "/x/y/z")
1716 cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
1717 message("Native path list is \"${native_paths}\"")
1718 Output on Windows:
1720 Native path list is "\a\b\c;\x\y\z"
1722 Output on all other platforms:
1724 Native path list is "/a/b/c:/x/y/z"
1726 Hashing
1728 cmake_path(HASH <path-var> <out-var>)
1729 Compute a hash value of <path-var> such that for two paths p1 and p2
1731 that compare equal (COMPARE ... EQUAL), the hash value of p1 is equal
1732 to the hash value of p2. The path is always normalized before the hash
1733 is computed.
1734 cmake_policy
1736 Manage CMake Policy settings. See the cmake-policies(7) manual for de‐
1737 fined policies.
1738 As CMake evolves it is sometimes necessary to change existing behavior
1740 in order to fix bugs or improve implementations of existing features.
1741 The CMake Policy mechanism is designed to help keep existing projects
1742 building as new versions of CMake introduce changes in behavior. Each
1743 new policy (behavioral change) is given an identifier of the form
1744 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
1745 with each policy describes the OLD and NEW behavior and the reason the
1746 policy was introduced. Projects may set each policy to select the de‐
1747 sired behavior. When CMake needs to know which behavior to use it
1748 checks for a setting specified by the project. If no setting is avail‐
1749 able the OLD behavior is assumed and a warning is produced requesting
1750 that the policy be set.
1751 Setting Policies by CMake Version
1753 The cmake_policy command is used to set policies to OLD or NEW behav‐
1754 ior. While setting policies individually is supported, we encourage
1755 projects to set policies based on CMake versions:
1756 cmake_policy(VERSION <min>[...<max>])
1758 New in version 3.12: The optional <max> version.
1760 <min> and the optional <max> are each CMake versions of the form ma‐
1763 jor.minor[.patch[.tweak]], and the ... is literal. The <min> version
1764 must be at least 2.4 and at most the running version of CMake. The
1765 <max> version, if specified, must be at least the <min> version but may
1766 exceed the running version of CMake. If the running version of CMake
1767 is older than 3.12, the extra ... dots will be seen as version compo‐
1768 nent separators, resulting in the ...<max> part being ignored and pre‐
1769 serving the pre-3.12 behavior of basing policies on <min>.
1770 This specifies that the current CMake code is written for the given
1772 range of CMake versions. All policies known to the running version of
1773 CMake and introduced in the <min> (or <max>, if specified) version or
1774 earlier will be set to use NEW behavior. All policies introduced in
1775 later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
1776 variable sets a default). This effectively requests behavior preferred
1777 as of a given CMake version and tells newer CMake versions to warn
1778 about their new policies.
1779 Note that the cmake_minimum_required(VERSION) command implicitly calls
1781 cmake_policy(VERSION) too.
1782 Setting Policies Explicitly
1784 cmake_policy(SET CMP<NNNN> NEW)
1785 cmake_policy(SET CMP<NNNN> OLD)
1786 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
1788 depending on the old behavior of a given policy may silence a policy
1789 warning by setting the policy state to OLD. Alternatively one may fix
1790 the project to work with the new behavior and set the policy state to
1791 NEW.
1792 NOTE:
1794 The OLD behavior of a policy is deprecated by definition and may be
1795 removed in a future version of CMake.
1796 Checking Policy Settings
1798 cmake_policy(GET CMP<NNNN> <variable>)
1799 Check whether a given policy is set to OLD or NEW behavior. The output
1801 <variable> value will be OLD or NEW if the policy is set, and empty
1802 otherwise.
1803 CMake Policy Stack
1805 CMake keeps policy settings on a stack, so changes made by the
1806 cmake_policy command affect only the top of the stack. A new entry on
1807 the policy stack is managed automatically for each subdirectory to pro‐
1808 tect its parents and siblings. CMake also manages a new entry for
1809 scripts loaded by include() and find_package() commands except when in‐
1810 voked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
1811 cmake_policy command provides an interface to manage custom entries on
1812 the policy stack:
1813 cmake_policy(PUSH)
1815 cmake_policy(POP)
1816 Each PUSH must have a matching POP to erase any changes. This is use‐
1818 ful to make temporary changes to policy settings. Calls to the
1819 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
1820 icy(SET) commands influence only the current top of the policy stack.
1821 New in version 3.25: The block() and endblock() commands offer a more
1823 flexible and more secure way to manage the policy stack. The pop action
1824 is done automatically when the endblock() command is executed, so it
1825 avoid to call the cmake_policy(POP) command before each return() com‐
1826 mand.
1827 # stack management with cmake_policy()
1829 function(my_func)
1830 cmake_policy(PUSH)
1831 cmake_policy(SET ...)
1832 if (<cond1>)
1833 ...
1834 cmake_policy(POP)
1835 return()
1836 elseif(<cond2>)
1837 ...
1838 cmake_policy(POP)
1839 return()
1840 endif()
1841 ...
1842 cmake_policy(POP)
1843 endfunction()
1844 # stack management with block()/endblock()
1846 function(my_func)
1847 block(SCOPE_FOR POLICIES)
1848 cmake_policy(SET ...)
1849 if (<cond1>)
1850 ...
1851 return()
1852 elseif(<cond2>)
1853 ...
1854 return()
1855 endif()
1856 ...
1857 endblock()
1858 endfunction()
1859 Commands created by the function() and macro() commands record policy
1862 settings when they are created and use the pre-record policies when
1863 they are invoked. If the function or macro implementation sets poli‐
1864 cies, the changes automatically propagate up through callers until they
1865 reach the closest nested policy stack entry.
1866 configure_file
1868 Copy a file to another location and modify its contents.
1869 configure_file(<input> <output>
1871 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
1872 FILE_PERMISSIONS <permissions>...]
1873 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
1874 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
1875 Copies an <input> file to an <output> file and substitutes variable
1877 values referenced as @VAR@ or ${VAR} in the input file content. Each
1878 variable reference will be replaced with the current value of the vari‐
1879 able, or the empty string if the variable is not defined. Furthermore,
1880 input lines of the form
1881 #cmakedefine VAR ...
1883 will be replaced with either
1885 #define VAR ...
1887 or
1889 /* #undef VAR */
1891 depending on whether VAR is set in CMake to any value not considered a
1893 false constant by the if() command. The "..." content on the line af‐
1894 ter the variable name, if any, is processed as above.
1895 Unlike lines of the form #cmakedefine VAR ..., in lines of the form
1897 #cmakedefine01 VAR, VAR itself will expand to VAR 0 or VAR 1 rather
1898 than being assigned the value .... Therefore, input lines of the form
1899 #cmakedefine01 VAR
1901 will be replaced with either
1903 #define VAR 0
1905 or
1907 #define VAR 1
1909 Input lines of the form #cmakedefine01 VAR ... will expand as #cmakede‐
1911 fine01 VAR ... 0 or #cmakedefine01 VAR ... 0, which may lead to unde‐
1912 fined behavior.
1913 New in version 3.10: The result lines (with the exception of the #undef
1915 comments) can be indented using spaces and/or tabs between the # char‐
1916 acter and the cmakedefine or cmakedefine01 words. This whitespace in‐
1917 dentation will be preserved in the output lines:
1918 # cmakedefine VAR
1920 # cmakedefine01 VAR
1921 will be replaced, if VAR is defined, with
1923 # define VAR
1925 # define VAR 1
1926 If the input file is modified the build system will re-run CMake to
1929 re-configure the file and generate the build system again. The gener‐
1930 ated file is modified and its timestamp updated on subsequent cmake
1931 runs only if its content is changed.
1932 The arguments are:
1934 <input>
1936 Path to the input file. A relative path is treated with respect
1937 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
1938 be a file, not a directory.
1939 <output>
1941 Path to the output file or directory. A relative path is
1942 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
1943 If the path names an existing directory the output file is
1944 placed in that directory with the same file name as the input
1945 file. If the path contains non-existent directories, they are
1946 created.
1947 NO_SOURCE_PERMISSIONS
1949 New in version 3.19.
1950 Do not transfer the permissions of the input file to the output
1953 file. The copied file permissions default to the standard 644
1954 value (-rw-r--r--).
1955 USE_SOURCE_PERMISSIONS
1957 New in version 3.20.
1958 Transfer the permissions of the input file to the output file.
1961 This is already the default behavior if none of the three per‐
1962 missions-related keywords are given (NO_SOURCE_PERMISSIONS,
1963 USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The
1964 USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making
1965 the intended behavior clearer at the call site.
1966 FILE_PERMISSIONS <permissions>...
1968 New in version 3.20.
1969 Ignore the input file's permissions and use the specified <per‐
1972 missions> for the output file instead.
1973 COPYONLY
1975 Copy the file without replacing any variable references or other
1976 content. This option may not be used with NEWLINE_STYLE.
1977 ESCAPE_QUOTES
1979 Escape any substituted quotes with backslashes (C-style).
1980 @ONLY Restrict variable replacement to references of the form @VAR@.
1982 This is useful for configuring scripts that use ${VAR} syntax.
1983 NEWLINE_STYLE <style>
1985 Specify the newline style for the output file. Specify UNIX or
1986 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
1987 lines. This option may not be used with COPYONLY.
1988 Example
1990 Consider a source tree containing a foo.h.in file:
1991 #cmakedefine FOO_ENABLE
1993 #cmakedefine FOO_STRING "@FOO_STRING@"
1994 An adjacent CMakeLists.txt may use configure_file to configure the
1996 header:
1997 option(FOO_ENABLE "Enable Foo" ON)
1999 if(FOO_ENABLE)
2000 set(FOO_STRING "foo")
2001 endif()
2002 configure_file(foo.h.in foo.h @ONLY)
2003 This creates a foo.h in the build directory corresponding to this
2005 source directory. If the FOO_ENABLE option is on, the configured file
2006 will contain:
2007 #define FOO_ENABLE
2009 #define FOO_STRING "foo"
2010 Otherwise it will contain:
2012 /* #undef FOO_ENABLE */
2014 /* #undef FOO_STRING */
2015 One may then use the include_directories() command to specify the out‐
2017 put directory as an include directory:
2018 include_directories(${CMAKE_CURRENT_BINARY_DIR})
2020 so that sources may include the header as #include <foo.h>.
2022 continue
2024 New in version 3.2.
2025 Continue to the top of enclosing foreach or while loop.
2028 continue()
2030 The continue() command allows a cmake script to abort the rest of the
2032 current iteration of a foreach() or while() loop, and start at the top
2033 of the next iteration.
2034 See also the break() command.
2036 else
2038 Starts the else portion of an if block.
2039 else([<condition>])
2041 See the if() command.
2043 elseif
2045 Starts an elseif portion of an if block.
2046 elseif(<condition>)
2048 See the if() command, especially for the syntax and logic of the <con‐
2050 dition>.
2051 endblock
2053 New in version 3.25.
2054 Ends a list of commands in a block() and removes the scopes created by
2057 the block() command.
2058 endblock()
2060 endforeach
2062 Ends a list of commands in a foreach block.
2063 endforeach([<loop_var>])
2065 See the foreach() command.
2067 The optional <loop_var> argument is supported for backward compatibil‐
2069 ity only. If used it must be a verbatim repeat of the <loop_var> argu‐
2070 ment of the opening foreach clause.
2071 endfunction
2073 Ends a list of commands in a function block.
2074 endfunction([<name>])
2076 See the function() command.
2078 The optional <name> argument is supported for backward compatibility
2080 only. If used it must be a verbatim repeat of the <name> argument of
2081 the opening function command.
2082 endif
2084 Ends a list of commands in an if block.
2085 endif([<condition>])
2087 See the if() command.
2089 The optional <condition> argument is supported for backward compatibil‐
2091 ity only. If used it must be a verbatim repeat of the argument of the
2092 opening if clause.
2093 endmacro
2095 Ends a list of commands in a macro block.
2096 endmacro([<name>])
2098 See the macro() command.
2100 The optional <name> argument is supported for backward compatibility
2102 only. If used it must be a verbatim repeat of the <name> argument of
2103 the opening macro command.
2104 endwhile
2106 Ends a list of commands in a while block.
2107 endwhile([<condition>])
2109 See the while() command.
2111 The optional <condition> argument is supported for backward compatibil‐
2113 ity only. If used it must be a verbatim repeat of the argument of the
2114 opening while clause.
2115 execute_process
2117 Execute one or more child processes.
2118 execute_process(COMMAND <cmd1> [<arguments>]
2120 [COMMAND <cmd2> [<arguments>]]...
2121 [WORKING_DIRECTORY <directory>]
2122 [TIMEOUT <seconds>]
2123 [RESULT_VARIABLE <variable>]
2124 [RESULTS_VARIABLE <variable>]
2125 [OUTPUT_VARIABLE <variable>]
2126 [ERROR_VARIABLE <variable>]
2127 [INPUT_FILE <file>]
2128 [OUTPUT_FILE <file>]
2129 [ERROR_FILE <file>]
2130 [OUTPUT_QUIET]
2131 [ERROR_QUIET]
2132 [COMMAND_ECHO <where>]
2133 [OUTPUT_STRIP_TRAILING_WHITESPACE]
2134 [ERROR_STRIP_TRAILING_WHITESPACE]
2135 [ENCODING <name>]
2136 [ECHO_OUTPUT_VARIABLE]
2137 [ECHO_ERROR_VARIABLE]
2138 [COMMAND_ERROR_IS_FATAL <ANY|LAST>])
2139 Runs the given sequence of one or more commands.
2141 Commands are executed concurrently as a pipeline, with the standard
2143 output of each process piped to the standard input of the next. A sin‐
2144 gle standard error pipe is used for all processes.
2145 Options:
2147 COMMAND
2149 A child process command line.
2150 CMake executes the child process using operating system APIs di‐
2152 rectly:
2153 • On POSIX platforms, the command line is passed to the child
2155 process in an argv[] style array.
2156 • On Windows platforms, the command line is encoded as a string
2158 such that child processes using CommandLineToArgvW will decode
2159 the original arguments.
2160 No intermediate shell is used, so shell operators such as > are
2162 treated as normal arguments. (Use the INPUT_*, OUTPUT_*, and
2163 ERROR_* options to redirect stdin, stdout, and stderr.)
2164 If a sequential execution of multiple commands is required, use
2166 multiple execute_process() calls with a single COMMAND argument.
2167 WORKING_DIRECTORY
2169 The named directory will be set as the current working directory
2170 of the child processes.
2171 TIMEOUT
2173 After the specified number of seconds (fractions allowed), all
2174 unfinished child processes will be terminated, and the RE‐
2175 SULT_VARIABLE will be set to a string mentioning the "timeout".
2176 RESULT_VARIABLE
2178 The variable will be set to contain the result of last child
2179 process. This will be an integer return code from the last
2180 child or a string describing an error condition.
2181 RESULTS_VARIABLE <variable>
2183 New in version 3.10.
2184 The variable will be set to contain the result of all processes
2187 as a semicolon-separated list, in order of the given COMMAND ar‐
2188 guments. Each entry will be an integer return code from the
2189 corresponding child or a string describing an error condition.
2190 OUTPUT_VARIABLE, ERROR_VARIABLE
2192 The variable named will be set with the contents of the standard
2193 output and standard error pipes, respectively. If the same
2194 variable is named for both pipes their output will be merged in
2195 the order produced.
2196 INPUT_FILE, OUTPUT_FILE, ERROR_FILE
2198 The file named will be attached to the standard input of the
2199 first process, standard output of the last process, or standard
2200 error of all processes, respectively.
2201 New in version 3.3: If the same file is named for both output
2203 and error then it will be used for both.
2204 OUTPUT_QUIET, ERROR_QUIET
2207 The standard output or standard error results will be quietly
2208 ignored.
2209 COMMAND_ECHO <where>
2211 New in version 3.15.
2212 The command being run will be echo'ed to <where> with <where>
2215 being set to one of STDERR, STDOUT or NONE. See the
2216 CMAKE_EXECUTE_PROCESS_COMMAND_ECHO variable for a way to control
2217 the default behavior when this option is not present.
2218 ENCODING <name>
2220 New in version 3.8.
2221 On Windows, the encoding that is used to decode output from the
2224 process. Ignored on other platforms. Valid encoding names are:
2225 NONE Perform no decoding. This assumes that the process out‐
2227 put is encoded in the same way as CMake's internal encod‐
2228 ing (UTF-8). This is the default.
2229 AUTO Use the current active console's codepage or if that
2231 isn't available then use ANSI.
2232 ANSI Use the ANSI codepage.
2234 OEM Use the original equipment manufacturer (OEM) code page.
2236 UTF8 or UTF-8
2238 Use the UTF-8 codepage.
2239 New in version 3.11: Accept UTF-8 spelling for consis‐
2241 tency with the UTF-8 RFC naming convention.
2242 ECHO_OUTPUT_VARIABLE, ECHO_ERROR_VARIABLE
2245 New in version 3.18.
2246 The standard output or standard error will not be exclusively
2249 redirected to the configured variables.
2250 The output will be duplicated, it will be sent into the config‐
2252 ured variables and also on standard output or standard error.
2253 This is analogous to the tee Unix command.
2255 COMMAND_ERROR_IS_FATAL <ANY|LAST>
2257 New in version 3.19.
2258 The option following COMMAND_ERROR_IS_FATAL determines the be‐
2261 havior when an error is encountered:
2262 ANY If any of the commands in the list of commands fail, the
2263 execute_process() command halts with an error.
2264 LAST If the last command in the list of commands fails, the
2266 execute_process() command halts with an error. Commands ear‐
2267 lier in the list will not cause a fatal error.
2268 If more than one OUTPUT_* or ERROR_* option is given for the same pipe
2270 the precedence is not specified. If no OUTPUT_* or ERROR_* options are
2271 given the output will be shared with the corresponding pipes of the
2272 CMake process itself.
2273 The execute_process() command is a newer more powerful version of
2275 exec_program(), but the old command has been kept for compatibility.
2276 Both commands run while CMake is processing the project prior to build
2277 system generation. Use add_custom_target() and add_custom_command() to
2278 create custom commands that run at build time.
2279 file
2281 File manipulation command.
2282 This command is dedicated to file and path manipulation requiring ac‐
2284 cess to the filesystem.
2285 For other path manipulation, handling only syntactic aspects, have a
2287 look at cmake_path() command.
2288 NOTE:
2290 The sub-commands RELATIVE_PATH, TO_CMAKE_PATH and TO_NATIVE_PATH has
2291 been superseded, respectively, by sub-commands RELATIVE_PATH,
2292 CONVERT ... TO_CMAKE_PATH_LIST and CONVERT ... TO_NATIVE_PATH_LIST
2293 of cmake_path() command.
2294 Synopsis
2296 Reading
2297 file(READ <filename> <out-var> [...])
2298 file(STRINGS <filename> <out-var> [...])
2299 file(<HASH> <filename> <out-var>)
2300 file(TIMESTAMP <filename> <out-var> [...])
2301 file(GET_RUNTIME_DEPENDENCIES [...])
2302 Writing
2304 file({WRITE | APPEND} <filename> <content>...)
2305 file({TOUCH | TOUCH_NOCREATE} [<file>...])
2306 file(GENERATE OUTPUT <output-file> [...])
2307 file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])
2308 Filesystem
2310 file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
2311 file(MAKE_DIRECTORY [<dir>...])
2312 file({REMOVE | REMOVE_RECURSE } [<files>...])
2313 file(RENAME <oldname> <newname> [...])
2314 file(COPY_FILE <oldname> <newname> [...])
2315 file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
2316 file(SIZE <filename> <out-var>)
2317 file(READ_SYMLINK <linkname> <out-var>)
2318 file(CREATE_LINK <original> <linkname> [...])
2319 file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
2320 file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])
2321 Path Conversion
2323 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
2324 file(RELATIVE_PATH <out-var> <directory> <file>)
2325 file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)
2326 Transfer
2328 file(DOWNLOAD <url> [<file>] [...])
2329 file(UPLOAD <file> <url> [...])
2330 Locking
2332 file(LOCK <path> [...])
2333 Archiving
2335 file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
2336 file(ARCHIVE_EXTRACT INPUT <archive> [...])
2337 Reading
2339 file(READ <filename> <variable>
2340 [OFFSET <offset>] [LIMIT <max-in>] [HEX])
2341 Read content from a file called <filename> and store it in a <vari‐
2343 able>. Optionally start from the given <offset> and read at most
2344 <max-in> bytes. The HEX option causes data to be converted to a hexa‐
2345 decimal representation (useful for binary data). If the HEX option is
2346 specified, letters in the output (a through f) are in lowercase.
2347 file(STRINGS <filename> <variable> [<options>...])
2349 Parse a list of ASCII strings from <filename> and store it in <vari‐
2351 able>. Binary data in the file are ignored. Carriage return (\r, CR)
2352 characters are ignored. The options are:
2353 LENGTH_MAXIMUM <max-len>
2355 Consider only strings of at most a given length.
2356 LENGTH_MINIMUM <min-len>
2358 Consider only strings of at least a given length.
2359 LIMIT_COUNT <max-num>
2361 Limit the number of distinct strings to be extracted.
2362 LIMIT_INPUT <max-in>
2364 Limit the number of input bytes to read from the file.
2365 LIMIT_OUTPUT <max-out>
2367 Limit the number of total bytes to store in the <variable>.
2368 NEWLINE_CONSUME
2370 Treat newline characters (\n, LF) as part of string content in‐
2371 stead of terminating at them.
2372 NO_HEX_CONVERSION
2374 Intel Hex and Motorola S-record files are automatically con‐
2375 verted to binary while reading unless this option is given.
2376 REGEX <regex>
2378 Consider only strings that match the given regular expression,
2379 as described under string(REGEX).
2380 ENCODING <encoding-type>
2382 New in version 3.1.
2383 Consider strings of a given encoding. Currently supported en‐
2386 codings are: UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE. If
2387 the ENCODING option is not provided and the file has a Byte Or‐
2388 der Mark, the ENCODING option will be defaulted to respect the
2389 Byte Order Mark.
2390 New in version 3.2: Added the UTF-16LE, UTF-16BE, UTF-32LE,
2392 UTF-32BE encodings.
2393 For example, the code
2396 file(STRINGS myfile.txt myfile)
2398 stores a list in the variable myfile in which each item is a line from
2400 the input file.
2401 file(<HASH> <filename> <variable>)
2403 Compute a cryptographic hash of the content of <filename> and store it
2405 in a <variable>. The supported <HASH> algorithm names are those listed
2406 by the string(<HASH>) command.
2407 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
2409 Compute a string representation of the modification time of <filename>
2411 and store it in <variable>. Should the command be unable to obtain a
2412 timestamp variable will be set to the empty string ("").
2413 See the string(TIMESTAMP) command for documentation of the <format> and
2415 UTC options.
2416 file(GET_RUNTIME_DEPENDENCIES
2418 [RESOLVED_DEPENDENCIES_VAR <deps_var>]
2419 [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
2420 [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
2421 [EXECUTABLES [<executable_files>...]]
2422 [LIBRARIES [<library_files>...]]
2423 [MODULES [<module_files>...]]
2424 [DIRECTORIES [<directories>...]]
2425 [BUNDLE_EXECUTABLE <bundle_executable_file>]
2426 [PRE_INCLUDE_REGEXES [<regexes>...]]
2427 [PRE_EXCLUDE_REGEXES [<regexes>...]]
2428 [POST_INCLUDE_REGEXES [<regexes>...]]
2429 [POST_EXCLUDE_REGEXES [<regexes>...]]
2430 [POST_INCLUDE_FILES [<files>...]]
2431 [POST_EXCLUDE_FILES [<files>...]]
2432 )
2433 New in version 3.16.
2435 Recursively get the list of libraries depended on by the given files.
2438 Please note that this sub-command is not intended to be used in project
2440 mode. It is intended for use at install time, either from code gener‐
2441 ated by the install(RUNTIME_DEPENDENCY_SET) command, or from code pro‐
2442 vided by the project via install(CODE) or install(SCRIPT). For exam‐
2443 ple:
2444 install(CODE [[
2446 file(GET_RUNTIME_DEPENDENCIES
2447 # ...
2448 )
2449 ]])
2450 The arguments are as follows:
2452 RESOLVED_DEPENDENCIES_VAR <deps_var>
2454 Name of the variable in which to store the list of resolved de‐
2455 pendencies.
2456 UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>
2458 Name of the variable in which to store the list of unresolved
2459 dependencies. If this variable is not specified, and there are
2460 any unresolved dependencies, an error is issued.
2461 CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>
2463 Variable prefix in which to store conflicting dependency infor‐
2464 mation. Dependencies are conflicting if two files with the same
2465 name are found in two different directories. The list of file‐
2466 names that conflict are stored in <conflicting_deps_pre‐
2467 fix>_FILENAMES. For each filename, the list of paths that were
2468 found for that filename are stored in <conflicting_deps_pre‐
2469 fix>_<filename>.
2470 EXECUTABLES <executable_files>
2472 List of executable files to read for dependencies. These are ex‐
2473 ecutables that are typically created with add_executable(), but
2474 they do not have to be created by CMake. On Apple platforms, the
2475 paths to these files determine the value of @executable_path
2476 when recursively resolving the libraries. Specifying any kind
2477 of library (STATIC, MODULE, or SHARED) here will result in unde‐
2478 fined behavior.
2479 LIBRARIES <library_files>
2481 List of library files to read for dependencies. These are li‐
2482 braries that are typically created with add_library(SHARED), but
2483 they do not have to be created by CMake. Specifying STATIC li‐
2484 braries, MODULE libraries, or executables here will result in
2485 undefined behavior.
2486 MODULES <module_files>
2488 List of loadable module files to read for dependencies. These
2489 are modules that are typically created with add_library(MODULE),
2490 but they do not have to be created by CMake. They are typically
2491 used by calling dlopen() at runtime rather than linked at link
2492 time with ld -l. Specifying STATIC libraries, SHARED libraries,
2493 or executables here will result in undefined behavior.
2494 DIRECTORIES <directories>
2496 List of additional directories to search for dependencies. On
2497 Linux platforms, these directories are searched if the depen‐
2498 dency is not found in any of the other usual paths. If it is
2499 found in such a directory, a warning is issued, because it means
2500 that the file is incomplete (it does not list all of the direc‐
2501 tories that contain its dependencies). On Windows platforms,
2502 these directories are searched if the dependency is not found in
2503 any of the other search paths, but no warning is issued, because
2504 searching other paths is a normal part of Windows dependency
2505 resolution. On Apple platforms, this argument has no effect.
2506 BUNDLE_EXECUTABLE <bundle_executable_file>
2508 Executable to treat as the "bundle executable" when resolving
2509 libraries. On Apple platforms, this argument determines the
2510 value of @executable_path when recursively resolving libraries
2511 for LIBRARIES and MODULES files. It has no effect on EXECUTA‐
2512 BLES files. On other platforms, it has no effect. This is typi‐
2513 cally (but not always) one of the executables in the EXECUTABLES
2514 argument which designates the "main" executable of the package.
2515 The following arguments specify filters for including or excluding li‐
2517 braries to be resolved. See below for a full description of how they
2518 work.
2519 PRE_INCLUDE_REGEXES <regexes>
2521 List of pre-include regexes through which to filter the names of
2522 not-yet-resolved dependencies.
2523 PRE_EXCLUDE_REGEXES <regexes>
2525 List of pre-exclude regexes through which to filter the names of
2526 not-yet-resolved dependencies.
2527 POST_INCLUDE_REGEXES <regexes>
2529 List of post-include regexes through which to filter the names
2530 of resolved dependencies.
2531 POST_EXCLUDE_REGEXES <regexes>
2533 List of post-exclude regexes through which to filter the names
2534 of resolved dependencies.
2535 POST_INCLUDE_FILES <files>
2537 New in version 3.21.
2538 List of post-include filenames through which to filter the names
2541 of resolved dependencies. Symlinks are resolved when attempting
2542 to match these filenames.
2543 POST_EXCLUDE_FILES <files>
2545 New in version 3.21.
2546 List of post-exclude filenames through which to filter the names
2549 of resolved dependencies. Symlinks are resolved when attempting
2550 to match these filenames.
2551 These arguments can be used to exclude unwanted system libraries when
2553 resolving the dependencies, or to include libraries from a specific di‐
2554 rectory. The filtering works as follows:
2555 1. If the not-yet-resolved dependency matches any of the PRE_IN‐
2557 CLUDE_REGEXES, steps 2 and 3 are skipped, and the dependency resolu‐
2558 tion proceeds to step 4.
2559 2. If the not-yet-resolved dependency matches any of the PRE_EX‐
2561 CLUDE_REGEXES, dependency resolution stops for that dependency.
2562 3. Otherwise, dependency resolution proceeds.
2564 4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency according
2566 to the linking rules of the platform (see below).
2567 5. If the dependency is found, and its full path matches one of the
2569 POST_INCLUDE_REGEXES or POST_INCLUDE_FILES, the full path is added
2570 to the resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES) re‐
2571 cursively resolves that library's own dependencies. Otherwise, reso‐
2572 lution proceeds to step 6.
2573 6. If the dependency is found, but its full path matches one of the
2575 POST_EXCLUDE_REGEXES or POST_EXCLUDE_FILES, it is not added to the
2576 resolved dependencies, and dependency resolution stops for that de‐
2577 pendency.
2578 7. If the dependency is found, and its full path does not match either
2580 POST_INCLUDE_REGEXES, POST_INCLUDE_FILES, POST_EXCLUDE_REGEXES, or
2581 POST_EXCLUDE_FILES, the full path is added to the resolved dependen‐
2582 cies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves that
2583 library's own dependencies.
2584 Different platforms have different rules for how dependencies are re‐
2586 solved. These specifics are described here.
2587 On Linux platforms, library resolution works as follows:
2589 1. If the depending file does not have any RUNPATH entries, and the li‐
2591 brary exists in one of the depending file's RPATH entries, or its
2592 parents', in that order, the dependency is resolved to that file.
2593 2. Otherwise, if the depending file has any RUNPATH entries, and the
2595 library exists in one of those entries, the dependency is resolved
2596 to that file.
2597 3. Otherwise, if the library exists in one of the directories listed by
2599 ldconfig, the dependency is resolved to that file.
2600 4. Otherwise, if the library exists in one of the DIRECTORIES entries,
2602 the dependency is resolved to that file. In this case, a warning is
2603 issued, because finding a file in one of the DIRECTORIES means that
2604 the depending file is not complete (it does not list all the direc‐
2605 tories from which it pulls dependencies).
2606 5. Otherwise, the dependency is unresolved.
2608 On Windows platforms, library resolution works as follows:
2610 1. The dependent DLL name is converted to lowercase. Windows DLL names
2612 are case-insensitive, and some linkers mangle the case of the DLL
2613 dependency names. However, this makes it more difficult for PRE_IN‐
2614 CLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and
2615 POST_EXCLUDE_REGEXES to properly filter DLL names - every regex
2616 would have to check for both uppercase and lowercase letters. For
2617 example:
2618 file(GET_RUNTIME_DEPENDENCIES
2620 # ...
2621 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
2622 )
2623 Converting the DLL name to lowercase allows the regexes to only
2625 match lowercase names, thus simplifying the regex. For example:
2626 file(GET_RUNTIME_DEPENDENCIES
2628 # ...
2629 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
2630 )
2631 This regex will match mylibrary.dll regardless of how it is cased,
2633 either on disk or in the depending file. (For example, it will match
2634 mylibrary.dll, MyLibrary.dll, and MYLIBRARY.DLL.)
2635 Please note that the directory portion of any resolved DLLs retains
2637 its casing and is not converted to lowercase. Only the filename por‐
2638 tion is converted.
2639 2. (Not yet implemented) If the depending file is a Windows Store app,
2641 and the dependency is listed as a dependency in the application's
2642 package manifest, the dependency is resolved to that file.
2643 3. Otherwise, if the library exists in the same directory as the de‐
2645 pending file, the dependency is resolved to that file.
2646 4. Otherwise, if the library exists in either the operating system's
2648 system32 directory or the Windows directory, in that order, the de‐
2649 pendency is resolved to that file.
2650 5. Otherwise, if the library exists in one of the directories specified
2652 by DIRECTORIES, in the order they are listed, the dependency is re‐
2653 solved to that file. In this case, a warning is not issued, because
2654 searching other directories is a normal part of Windows library res‐
2655 olution.
2656 6. Otherwise, the dependency is unresolved.
2658 On Apple platforms, library resolution works as follows:
2660 1. If the dependency starts with @executable_path/, and an EXECUTABLES
2662 argument is in the process of being resolved, and replacing @exe‐
2663 cutable_path/ with the directory of the executable yields an exist‐
2664 ing file, the dependency is resolved to that file.
2665 2. Otherwise, if the dependency starts with @executable_path/, and
2667 there is a BUNDLE_EXECUTABLE argument, and replacing @exe‐
2668 cutable_path/ with the directory of the bundle executable yields an
2669 existing file, the dependency is resolved to that file.
2670 3. Otherwise, if the dependency starts with @loader_path/, and replac‐
2672 ing @loader_path/ with the directory of the depending file yields an
2673 existing file, the dependency is resolved to that file.
2674 4. Otherwise, if the dependency starts with @rpath/, and replacing
2676 @rpath/ with one of the RPATH entries of the depending file yields
2677 an existing file, the dependency is resolved to that file. Note that
2678 RPATH entries that start with @executable_path/ or @loader_path/
2679 also have these items replaced with the appropriate path.
2680 5. Otherwise, if the dependency is an absolute file that exists, the
2682 dependency is resolved to that file.
2683 6. Otherwise, the dependency is unresolved.
2685 This function accepts several variables that determine which tool is
2687 used for dependency resolution:
2688 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
2690 Determines which operating system and executable format the
2691 files are built for. This could be one of several values:
2692 • linux+elf
2694 • windows+pe
2696 • macos+macho
2698 If this variable is not specified, it is determined automati‐
2700 cally by system introspection.
2701 CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
2703 Determines the tool to use for dependency resolution. It could
2704 be one of several values, depending on the value of
2705 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:
2706 ┌─────────────────────────┬──────────────────────────┐
2708 │CMAKE_GET_RUNTIME_DEPEN‐ │ CMAKE_GET_RUNTIME_DEPEN‐ │
2709 │DENCIES_PLATFORM │ DENCIES_TOOL │
2710 ├─────────────────────────┼──────────────────────────┤
2711 │linux+elf │ objdump │
2712 ├─────────────────────────┼──────────────────────────┤
2713 │windows+pe │ dumpbin │
2714 ├─────────────────────────┼──────────────────────────┤
2715 │windows+pe │ objdump │
2716 ├─────────────────────────┼──────────────────────────┤
2717 │macos+macho │ otool │
2718 └─────────────────────────┴──────────────────────────┘
2719 If this variable is not specified, it is determined automati‐
2721 cally by system introspection.
2722 CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
2724 Determines the path to the tool to use for dependency resolu‐
2725 tion. This is the actual path to objdump, dumpbin, or otool.
2726 If this variable is not specified, it is determined by the value
2728 of CMAKE_OBJDUMP if set, else by system introspection.
2729 New in version 3.18: Use CMAKE_OBJDUMP if set.
2731 Writing
2734 file(WRITE <filename> <content>...)
2735 file(APPEND <filename> <content>...)
2736 Write <content> into a file called <filename>. If the file does not
2738 exist, it will be created. If the file already exists, WRITE mode will
2739 overwrite it and APPEND mode will append to the end. Any directories
2740 in the path specified by <filename> that do not exist will be created.
2741 If the file is a build input, use the configure_file() command to up‐
2743 date the file only when its content changes.
2744 file(TOUCH [<files>...])
2746 file(TOUCH_NOCREATE [<files>...])
2747 New in version 3.12.
2749 Create a file with no content if it does not yet exist. If the file al‐
2752 ready exists, its access and/or modification will be updated to the
2753 time when the function call is executed.
2754 Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a
2756 file does not exist it will be silently ignored.
2757 With TOUCH and TOUCH_NOCREATE the contents of an existing file will not
2759 be modified.
2760 file(GENERATE OUTPUT output-file
2762 <INPUT input-file|CONTENT content>
2763 [CONDITION expression] [TARGET target]
2764 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
2765 FILE_PERMISSIONS <permissions>...]
2766 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2767 Generate an output file for each build configuration supported by the
2769 current CMake Generator. Evaluate generator expressions from the input
2770 content to produce the output content. The options are:
2771 CONDITION <condition>
2773 Generate the output file for a particular configuration only if
2774 the condition is true. The condition must be either 0 or 1 af‐
2775 ter evaluating generator expressions.
2776 CONTENT <content>
2778 Use the content given explicitly as input.
2779 INPUT <input-file>
2781 Use the content from a given file as input.
2782 Changed in version 3.10: A relative path is treated with respect
2784 to the value of CMAKE_CURRENT_SOURCE_DIR. See policy CMP0070.
2785 OUTPUT <output-file>
2788 Specify the output file name to generate. Use generator expres‐
2789 sions such as $<CONFIG> to specify a configuration-specific out‐
2790 put file name. Multiple configurations may generate the same
2791 output file only if the generated content is identical. Other‐
2792 wise, the <output-file> must evaluate to an unique name for each
2793 configuration.
2794 Changed in version 3.10: A relative path (after evaluating gen‐
2796 erator expressions) is treated with respect to the value of
2797 CMAKE_CURRENT_BINARY_DIR. See policy CMP0070.
2798 TARGET <target>
2801 New in version 3.19.
2802 Specify which target to use when evaluating generator expres‐
2805 sions that require a target for evaluation (e.g. $<COMPILE_FEA‐
2806 TURES:...>, $<TARGET_PROPERTY:prop>).
2807 NO_SOURCE_PERMISSIONS
2809 New in version 3.20.
2810 The generated file permissions default to the standard 644 value
2813 (-rw-r--r--).
2814 USE_SOURCE_PERMISSIONS
2816 New in version 3.20.
2817 Transfer the file permissions of the INPUT file to the generated
2820 file. This is already the default behavior if none of the three
2821 permissions-related keywords are given (NO_SOURCE_PERMISSIONS,
2822 USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The
2823 USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making
2824 the intended behavior clearer at the call site. It is an error
2825 to specify this option without INPUT.
2826 FILE_PERMISSIONS <permissions>...
2828 New in version 3.20.
2829 Use the specified permissions for the generated file.
2832 NEWLINE_STYLE <style>
2834 New in version 3.20.
2835 Specify the newline style for the generated file. Specify UNIX
2838 or LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n
2839 newlines.
2840 Exactly one CONTENT or INPUT option must be given. A specific OUTPUT
2842 file may be named by at most one invocation of file(GENERATE). Gener‐
2843 ated files are modified and their timestamp updated on subsequent cmake
2844 runs only if their content is changed.
2845 Note also that file(GENERATE) does not create the output file until the
2847 generation phase. The output file will not yet have been written when
2848 the file(GENERATE) command returns, it is written only after processing
2849 all of a project's CMakeLists.txt files.
2850 file(CONFIGURE OUTPUT output-file
2852 CONTENT content
2853 [ESCAPE_QUOTES] [@ONLY]
2854 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2855 New in version 3.18.
2857 Generate an output file using the input given by CONTENT and substitute
2860 variable values referenced as @VAR@ or ${VAR} contained therein. The
2861 substitution rules behave the same as the configure_file() command. In
2862 order to match configure_file()'s behavior, generator expressions are
2863 not supported for both OUTPUT and CONTENT.
2864 The arguments are:
2866 OUTPUT <output-file>
2868 Specify the output file name to generate. A relative path is
2869 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
2870 <output-file> does not support generator expressions.
2871 CONTENT <content>
2873 Use the content given explicitly as input. <content> does not
2874 support generator expressions.
2875 ESCAPE_QUOTES
2877 Escape any substituted quotes with backslashes (C-style).
2878 @ONLY Restrict variable replacement to references of the form @VAR@.
2880 This is useful for configuring scripts that use ${VAR} syntax.
2881 NEWLINE_STYLE <style>
2883 Specify the newline style for the output file. Specify UNIX or
2884 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
2885 lines.
2886 Filesystem
2888 file(GLOB <variable>
2889 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
2890 [<globbing-expressions>...])
2891 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
2892 [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
2893 [<globbing-expressions>...])
2894 Generate a list of files that match the <globbing-expressions> and
2896 store it into the <variable>. Globbing expressions are similar to reg‐
2897 ular expressions, but much simpler. If RELATIVE flag is specified, the
2898 results will be returned as relative paths to the given path.
2899 Changed in version 3.6: The results will be ordered lexicographically.
2901 On Windows and macOS, globbing is case-insensitive even if the underly‐
2904 ing filesystem is case-sensitive (both filenames and globbing expres‐
2905 sions are converted to lowercase before matching). On other platforms,
2906 globbing is case-sensitive.
2907 New in version 3.3: By default GLOB lists directories - directories are
2909 omitted in result if LIST_DIRECTORIES is set to false.
2910 New in version 3.12: If the CONFIGURE_DEPENDS flag is specified, CMake
2913 will add logic to the main build system check target to rerun the
2914 flagged GLOB commands at build time. If any of the outputs change,
2915 CMake will regenerate the build system.
2916 NOTE:
2919 We do not recommend using GLOB to collect a list of source files
2920 from your source tree. If no CMakeLists.txt file changes when a
2921 source is added or removed then the generated build system cannot
2922 know when to ask CMake to regenerate. The CONFIGURE_DEPENDS flag
2923 may not work reliably on all generators, or if a new generator is
2924 added in the future that cannot support it, projects using it will
2925 be stuck. Even if CONFIGURE_DEPENDS works reliably, there is still a
2926 cost to perform the check on every rebuild.
2927 Examples of globbing expressions include:
2929 *.cxx - match all files with extension cxx
2931 *.vt? - match all files with extension vta,...,vtz
2932 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
2933 The GLOB_RECURSE mode will traverse all the subdirectories of the
2935 matched directory and match the files. Subdirectories that are sym‐
2936 links are only traversed if FOLLOW_SYMLINKS is given or policy CMP0009
2937 is not set to NEW.
2938 New in version 3.3: By default GLOB_RECURSE omits directories from re‐
2940 sult list - setting LIST_DIRECTORIES to true adds directories to result
2941 list. If FOLLOW_SYMLINKS is given or policy CMP0009 is not set to NEW
2942 then LIST_DIRECTORIES treats symlinks as directories.
2943 Examples of recursive globbing include:
2946 /dir/*.py - match all python files in /dir and subdirectories
2948 file(MAKE_DIRECTORY [<directories>...])
2950 Create the given directories and their parents as needed.
2952 file(REMOVE [<files>...])
2954 file(REMOVE_RECURSE [<files>...])
2955 Remove the given files. The REMOVE_RECURSE mode will remove the given
2957 files and directories, also non-empty directories. No error is emitted
2958 if a given file does not exist. Relative input paths are evaluated
2959 with respect to the current source directory.
2960 Changed in version 3.15: Empty input paths are ignored with a warning.
2962 Previous versions of CMake interpreted empty strings as a relative path
2963 with respect to the current directory and removed its contents.
2964 file(RENAME <oldname> <newname>
2967 [RESULT <result>]
2968 [NO_REPLACE])
2969 Move a file or directory within a filesystem from <oldname> to <new‐
2971 name>, replacing the destination atomically.
2972 The options are:
2974 RESULT <result>
2976 New in version 3.21.
2977 Set <result> variable to 0 on success or an error message other‐
2980 wise. If RESULT is not specified and the operation fails, an
2981 error is emitted.
2982 NO_REPLACE
2984 New in version 3.21.
2985 If the <newname> path already exists, do not replace it. If RE‐
2988 SULT <result> is used, the result variable will be set to NO_RE‐
2989 PLACE. Otherwise, an error is emitted.
2990 file(COPY_FILE <oldname> <newname>
2992 [RESULT <result>]
2993 [ONLY_IF_DIFFERENT])
2994 New in version 3.21.
2996 Copy a file from <oldname> to <newname>. Directories are not supported.
2999 Symlinks are ignored and <oldfile>'s content is read and written to
3000 <newname> as a new file.
3001 The options are:
3003 RESULT <result>
3005 Set <result> variable to 0 on success or an error message other‐
3006 wise. If RESULT is not specified and the operation fails, an
3007 error is emitted.
3008 ONLY_IF_DIFFERENT
3010 If the <newname> path already exists, do not replace it if the
3011 file's contents are already the same as <oldname> (this avoids
3012 updating <newname>'s timestamp).
3013 This sub-command has some similarities to configure_file() with the
3015 COPYONLY option. An important difference is that configure_file() cre‐
3016 ates a dependency on the source file, so CMake will be re-run if it
3017 changes. The file(COPY_FILE) sub-command does not create such a depen‐
3018 dency.
3019 See also the file(COPY) sub-command just below which provides further
3021 file-copying capabilities.
3022 file(<COPY|INSTALL> <files>... DESTINATION <dir>
3024 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
3025 [FILE_PERMISSIONS <permissions>...]
3026 [DIRECTORY_PERMISSIONS <permissions>...]
3027 [FOLLOW_SYMLINK_CHAIN]
3028 [FILES_MATCHING]
3029 [[PATTERN <pattern> | REGEX <regex>]
3030 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
3031 NOTE:
3033 For a simple file copying operation, the file(COPY_FILE) sub-command
3034 just above may be easier to use.
3035 The COPY signature copies files, directories, and symlinks to a desti‐
3037 nation folder. Relative input paths are evaluated with respect to the
3038 current source directory, and a relative destination is evaluated with
3039 respect to the current build directory. Copying preserves input file
3040 timestamps, and optimizes out a file if it exists at the destination
3041 with the same timestamp. Copying preserves input permissions unless
3042 explicit permissions or NO_SOURCE_PERMISSIONS are given (default is
3043 USE_SOURCE_PERMISSIONS).
3044 New in version 3.15: If FOLLOW_SYMLINK_CHAIN is specified, COPY will
3046 recursively resolve the symlinks at the paths given until a real file
3047 is found, and install a corresponding symlink in the destination for
3048 each symlink encountered. For each symlink that is installed, the reso‐
3049 lution is stripped of the directory, leaving only the filename, meaning
3050 that the new symlink points to a file in the same directory as the sym‐
3051 link. This feature is useful on some Unix systems, where libraries are
3052 installed as a chain of symlinks with version numbers, with less spe‐
3053 cific versions pointing to more specific versions. FOLLOW_SYM‐
3054 LINK_CHAIN will install all of these symlinks and the library itself
3055 into the destination directory. For example, if you have the following
3056 directory structure:
3057 • /opt/foo/lib/libfoo.so.1.2.3
3060 • /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3
3062 • /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2
3064 • /opt/foo/lib/libfoo.so -> libfoo.so.1
3066 and you do:
3068 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
3070 This will install all of the symlinks and libfoo.so.1.2.3 itself into
3072 lib.
3073 See the install(DIRECTORY) command for documentation of permissions,
3075 FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options. Copying directo‐
3076 ries preserves the structure of their content even if options are used
3077 to select a subset of files.
3078 The INSTALL signature differs slightly from COPY: it prints status mes‐
3080 sages, and NO_SOURCE_PERMISSIONS is default.
3081 Installation scripts generated by the install() command use this signa‐
3083 ture (with some undocumented options for internal use).
3084 Changed in version 3.22: The environment variable CMAKE_INSTALL_MODE
3086 can override the default copying behavior of file(INSTALL).
3087 file(SIZE <filename> <variable>)
3090 New in version 3.14.
3092 Determine the file size of the <filename> and put the result in <vari‐
3095 able> variable. Requires that <filename> is a valid path pointing to a
3096 file and is readable.
3097 file(READ_SYMLINK <linkname> <variable>)
3099 New in version 3.14.
3101 This subcommand queries the symlink <linkname> and stores the path it
3104 points to in the result <variable>. If <linkname> does not exist or is
3105 not a symlink, CMake issues a fatal error.
3106 Note that this command returns the raw symlink path and does not re‐
3108 solve a relative path. The following is an example of how to ensure
3109 that an absolute path is obtained:
3110 set(linkname "/path/to/foo.sym")
3112 file(READ_SYMLINK "${linkname}" result)
3113 if(NOT IS_ABSOLUTE "${result}")
3114 get_filename_component(dir "${linkname}" DIRECTORY)
3115 set(result "${dir}/${result}")
3116 endif()
3117 file(CREATE_LINK <original> <linkname>
3119 [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])
3120 New in version 3.14.
3122 Create a link <linkname> that points to <original>. It will be a hard
3125 link by default, but providing the SYMBOLIC option results in a sym‐
3126 bolic link instead. Hard links require that original exists and is a
3127 file, not a directory. If <linkname> already exists, it will be over‐
3128 written.
3129 The <result> variable, if specified, receives the status of the opera‐
3131 tion. It is set to 0 upon success or an error message otherwise. If
3132 RESULT is not specified and the operation fails, a fatal error is emit‐
3133 ted.
3134 Specifying COPY_ON_ERROR enables copying the file as a fallback if cre‐
3136 ating the link fails. It can be useful for handling situations such as
3137 <original> and <linkname> being on different drives or mount points,
3138 which would make them unable to support a hard link.
3139 file(CHMOD <files>... <directories>...
3141 [PERMISSIONS <permissions>...]
3142 [FILE_PERMISSIONS <permissions>...]
3143 [DIRECTORY_PERMISSIONS <permissions>...])
3144 New in version 3.19.
3146 Set the permissions for the <files>... and <directories>... specified.
3149 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
3150 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
3151 WORLD_EXECUTE, SETUID, SETGID.
3152 Valid combination of keywords are:
3154 PERMISSIONS
3156 All items are changed.
3157 FILE_PERMISSIONS
3159 Only files are changed.
3160 DIRECTORY_PERMISSIONS
3162 Only directories are changed.
3163 PERMISSIONS and FILE_PERMISSIONS
3165 FILE_PERMISSIONS overrides PERMISSIONS for files.
3166 PERMISSIONS and DIRECTORY_PERMISSIONS
3168 DIRECTORY_PERMISSIONS overrides PERMISSIONS for directories.
3169 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS
3171 Use FILE_PERMISSIONS for files and DIRECTORY_PERMISSIONS for di‐
3172 rectories.
3173 file(CHMOD_RECURSE <files>... <directories>...
3175 [PERMISSIONS <permissions>...]
3176 [FILE_PERMISSIONS <permissions>...]
3177 [DIRECTORY_PERMISSIONS <permissions>...])
3178 New in version 3.19.
3180 Same as CHMOD, but change the permissions of files and directories
3183 present in the <directories>... recursively.
3184 Path Conversion
3186 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
3187 New in version 3.19.
3189 Compute the absolute path to an existing file or directory with sym‐
3192 links resolved.
3193 BASE_DIRECTORY <dir>
3195 If the provided <path> is a relative path, it is evaluated rela‐
3196 tive to the given base directory <dir>. If no base directory is
3197 provided, the default base directory will be
3198 CMAKE_CURRENT_SOURCE_DIR.
3199 EXPAND_TILDE
3201 New in version 3.21.
3202 If the <path> is ~ or starts with ~/, the ~ is replaced by the
3205 user's home directory. The path to the home directory is ob‐
3206 tained from environment variables. On Windows, the USERPROFILE
3207 environment variable is used, falling back to the HOME environ‐
3208 ment variable if USERPROFILE is not defined. On all other plat‐
3209 forms, only HOME is used.
3210 file(RELATIVE_PATH <variable> <directory> <file>)
3212 Compute the relative path from a <directory> to a <file> and store it
3214 in the <variable>.
3215 file(TO_CMAKE_PATH "<path>" <variable>)
3217 file(TO_NATIVE_PATH "<path>" <variable>)
3218 The TO_CMAKE_PATH mode converts a native <path> into a cmake-style path
3220 with forward-slashes (/). The input can be a single path or a system
3221 search path like $ENV{PATH}. A search path will be converted to a
3222 cmake-style list separated by ; characters.
3223 The TO_NATIVE_PATH mode converts a cmake-style <path> into a native
3225 path with platform-specific slashes (\ on Windows hosts and / else‐
3226 where).
3227 Always use double quotes around the <path> to be sure it is treated as
3229 a single argument to this command.
3230 Transfer
3232 file(DOWNLOAD <url> [<file>] [<options>...])
3233 file(UPLOAD <file> <url> [<options>...])
3234 The DOWNLOAD subcommand downloads the given <url> to a local <file>.
3236 The UPLOAD mode uploads a local <file> to a given <url>.
3237 New in version 3.19: If <file> is not specified for file(DOWNLOAD), the
3239 file is not saved. This can be useful if you want to know if a file
3240 can be downloaded (for example, to check that it exists) without actu‐
3241 ally saving it anywhere.
3242 Options to both DOWNLOAD and UPLOAD are:
3245 INACTIVITY_TIMEOUT <seconds>
3247 Terminate the operation after a period of inactivity.
3248 LOG <variable>
3250 Store a human-readable log of the operation in a variable.
3251 SHOW_PROGRESS
3253 Print progress information as status messages until the opera‐
3254 tion is complete.
3255 STATUS <variable>
3257 Store the resulting status of the operation in a variable. The
3258 status is a ; separated list of length 2. The first element is
3259 the numeric return value for the operation, and the second ele‐
3260 ment is a string value for the error. A 0 numeric error means
3261 no error in the operation.
3262 TIMEOUT <seconds>
3264 Terminate the operation after a given total time has elapsed.
3265 USERPWD <username>:<password>
3267 New in version 3.7.
3268 Set username and password for operation.
3271 HTTPHEADER <HTTP-header>
3273 New in version 3.7.
3274 HTTP header for operation. Suboption can be repeated several
3277 times.
3278 NETRC <level>
3280 New in version 3.11.
3281 Specify whether the .netrc file is to be used for operation. If
3284 this option is not specified, the value of the CMAKE_NETRC vari‐
3285 able will be used instead. Valid levels are:
3286 IGNORED
3288 The .netrc file is ignored. This is the default.
3289 OPTIONAL
3291 The .netrc file is optional, and information in the URL
3292 is preferred. The file will be scanned to find which
3293 ever information is not specified in the URL.
3294 REQUIRED
3296 The .netrc file is required, and information in the URL
3297 is ignored.
3298 NETRC_FILE <file>
3300 New in version 3.11.
3301 Specify an alternative .netrc file to the one in your home di‐
3304 rectory, if the NETRC level is OPTIONAL or REQUIRED. If this op‐
3305 tion is not specified, the value of the CMAKE_NETRC_FILE vari‐
3306 able will be used instead.
3307 TLS_VERIFY <ON|OFF>
3309 Specify whether to verify the server certificate for https://
3310 URLs. The default is to not verify. If this option is not spec‐
3311 ified, the value of the CMAKE_TLS_VERIFY variable will be used
3312 instead.
3313 New in version 3.18: Added support to file(UPLOAD).
3315 TLS_CAINFO <file>
3318 Specify a custom Certificate Authority file for https:// URLs.
3319 If this option is not specified, the value of the
3320 CMAKE_TLS_CAINFO variable will be used instead.
3321 New in version 3.18: Added support to file(UPLOAD).
3323 For https:// URLs CMake must be built with OpenSSL support. TLS/SSL
3326 certificates are not checked by default. Set TLS_VERIFY to ON to check
3327 certificates.
3328 Additional options to DOWNLOAD are:
3330 EXPECTED_HASH ALGO=<value>
3332 Verify that the downloaded content hash matches the expected value,
3333 where ALGO is one of the algorithms supported by file(<HASH>). If
3334 the file already exists and matches the hash, the download is
3335 skipped. If the file already exists and does not match the hash,
3336 the file is downloaded again. If after download the file does not
3337 match the hash, the operation fails with an error. It is an error to
3338 specify this option if DOWNLOAD is not given a <file>.
3339 EXPECTED_MD5 <value>
3341 Historical short-hand for EXPECTED_HASH MD5=<value>. It is an
3342 error to specify this if DOWNLOAD is not given a <file>.
3343 RANGE_START <value>
3345 New in version 3.24.
3346 Offset of the start of the range in file in bytes. Could be
3349 omitted to download up to the specified RANGE_END.
3350 RANGE_END <value>
3352 New in version 3.24.
3353 Offset of the end of the range in file in bytes. Could be omit‐
3356 ted to download everything from the specified RANGE_START to the
3357 end of file.
3358 Locking
3360 file(LOCK <path> [DIRECTORY] [RELEASE]
3361 [GUARD <FUNCTION|FILE|PROCESS>]
3362 [RESULT_VARIABLE <variable>]
3363 [TIMEOUT <seconds>])
3364 New in version 3.2.
3366 Lock a file specified by <path> if no DIRECTORY option present and file
3369 <path>/cmake.lock otherwise. File will be locked for scope defined by
3370 GUARD option (default value is PROCESS). RELEASE option can be used to
3371 unlock file explicitly. If option TIMEOUT is not specified CMake will
3372 wait until lock succeed or until fatal error occurs. If TIMEOUT is set
3373 to 0 lock will be tried once and result will be reported immediately.
3374 If TIMEOUT is not 0 CMake will try to lock file for the period speci‐
3375 fied by <seconds> value. Any errors will be interpreted as fatal if
3376 there is no RESULT_VARIABLE option. Otherwise result will be stored in
3377 <variable> and will be 0 on success or error message on failure.
3378 Note that lock is advisory - there is no guarantee that other processes
3380 will respect this lock, i.e. lock synchronize two or more CMake in‐
3381 stances sharing some modifiable resources. Similar logic applied to DI‐
3382 RECTORY option - locking parent directory doesn't prevent other LOCK
3383 commands to lock any child directory or file.
3384 Trying to lock file twice is not allowed. Any intermediate directories
3386 and file itself will be created if they not exist. GUARD and TIMEOUT
3387 options ignored on RELEASE operation.
3388 Archiving
3390 file(ARCHIVE_CREATE OUTPUT <archive>
3391 PATHS <paths>...
3392 [FORMAT <format>]
3393 [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
3394 [MTIME <mtime>]
3395 [VERBOSE])
3396 New in version 3.18.
3398 Creates the specified <archive> file with the files and directories
3401 listed in <paths>. Note that <paths> must list actual files or direc‐
3402 tories, wildcards are not supported.
3403 Use the FORMAT option to specify the archive format. Supported values
3405 for <format> are 7zip, gnutar, pax, paxr, raw and zip. If FORMAT is
3406 not given, the default format is paxr.
3407 Some archive formats allow the type of compression to be specified.
3409 The 7zip and zip archive formats already imply a specific type of com‐
3410 pression. The other formats use no compression by default, but can be
3411 directed to do so with the COMPRESSION option. Valid values for <com‐
3412 pression> are None, BZip2, GZip, XZ, and Zstd.
3413 New in version 3.19: The compression level can be specified with the
3415 COMPRESSION_LEVEL option. The <compression-level> should be between
3416 0-9, with the default being 0. The COMPRESSION option must be present
3417 when COMPRESSION_LEVEL is given.
3418 NOTE:
3421 With FORMAT set to raw only one file will be compressed with the
3422 compression type specified by COMPRESSION.
3423 The VERBOSE option enables verbose output for the archive operation.
3425 To specify the modification time recorded in tarball entries, use the
3427 MTIME option.
3428 file(ARCHIVE_EXTRACT INPUT <archive>
3430 [DESTINATION <dir>]
3431 [PATTERNS <patterns>...]
3432 [LIST_ONLY]
3433 [VERBOSE]
3434 [TOUCH])
3435 New in version 3.18.
3437 Extracts or lists the content of the specified <archive>.
3440 The directory where the content of the archive will be extracted to can
3442 be specified using the DESTINATION option. If the directory does not
3443 exist, it will be created. If DESTINATION is not given, the current
3444 binary directory will be used.
3445 If required, you may select which files and directories to list or ex‐
3447 tract from the archive using the specified <patterns>. Wildcards are
3448 supported. If the PATTERNS option is not given, the entire archive
3449 will be listed or extracted.
3450 LIST_ONLY will list the files in the archive rather than extract them.
3452 New in version 3.24: The TOUCH option gives extracted files a current
3454 local timestamp instead of extracting file timestamps from the archive.
3455 With VERBOSE, the command will produce verbose output.
3458 find_file
3460 A short-hand signature is:
3461 find_file (<VAR> name1 [path1 path2 ...])
3463 The general signature is:
3465 find_file (
3467 <VAR>
3468 name | NAMES name1 [name2 ...]
3469 [HINTS [path | ENV var]... ]
3470 [PATHS [path | ENV var]... ]
3471 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
3472 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3473 [VALIDATOR function]
3474 [DOC "cache documentation string"]
3475 [NO_CACHE]
3476 [REQUIRED]
3477 [NO_DEFAULT_PATH]
3478 [NO_PACKAGE_ROOT_PATH]
3479 [NO_CMAKE_PATH]
3480 [NO_CMAKE_ENVIRONMENT_PATH]
3481 [NO_SYSTEM_ENVIRONMENT_PATH]
3482 [NO_CMAKE_SYSTEM_PATH]
3483 [NO_CMAKE_INSTALL_PREFIX]
3484 [CMAKE_FIND_ROOT_PATH_BOTH |
3485 ONLY_CMAKE_FIND_ROOT_PATH |
3486 NO_CMAKE_FIND_ROOT_PATH]
3487 )
3488 This command is used to find a full path to named file. A cache entry,
3490 or a normal variable if NO_CACHE is specified, named by <VAR> is cre‐
3491 ated to store the result of this command. If the full path to a file
3492 is found the result is stored in the variable and the search will not
3493 be repeated unless the variable is cleared. If nothing is found, the
3494 result will be <VAR>-NOTFOUND.
3495 Options include:
3497 NAMES Specify one or more possible names for the full path to a file.
3499 When using this to specify names with and without a version suf‐
3501 fix, we recommend specifying the unversioned name first so that
3502 locally-built packages can be found before those provided by
3503 distributions.
3504 HINTS, PATHS
3506 Specify directories to search in addition to the default loca‐
3507 tions. The ENV var sub-option reads paths from a system envi‐
3508 ronment variable.
3509 Changed in version 3.24: On Windows platform, it is possible to
3511 include registry queries as part of the directories, using a
3512 dedicated syntax. Such specifications will be ignored on all
3513 other platforms.
3514 REGISTRY_VIEW
3517 New in version 3.24.
3518 Specify which registry views must be queried. This option is
3521 only meaningful on Windows platforms and will be ignored on
3522 other ones. When not specified, the TARGET view is used when the
3523 CMP0134 policy is NEW. Refer to CMP0134 for the default view
3524 when the policy is OLD.
3525 64 Query the 64-bit registry. On 32-bit Windows, it always
3527 returns the string /REGISTRY-NOTFOUND.
3528 32 Query the 32-bit registry.
3530 64_32 Query both views (64 and 32) and generate a path for
3532 each.
3533 32_64 Query both views (32 and 64) and generate a path for
3535 each.
3536 HOST Query the registry matching the architecture of the host:
3538 64 on 64-bit Windows and 32 on 32-bit Windows.
3539 TARGET Query the registry matching the architecture specified by
3541 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
3542 back to HOST view.
3543 BOTH Query both views (32 and 64). The order depends on the
3545 following rules: If the CMAKE_SIZEOF_VOID_P variable is
3546 defined, use the following view depending on the content
3547 of this variable:
3548 • 8: 64_32
3550 • 4: 32_64
3552 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
3554 on the architecture of the host:
3555 • 64-bit: 64_32
3557 • 32-bit: 32
3559 PATH_SUFFIXES
3561 Specify additional subdirectories to check below each directory
3562 location otherwise considered.
3563 VALIDATOR
3565 New in version 3.25.
3566 Specify a function() to be called for each candidate item found
3569 (a macro() cannot be provided, that will result in an error).
3570 Two arguments will be passed to the validator function: the name
3571 of a result variable, and the absolute path to the candidate
3572 item. The item will be accepted and the search will end unless
3573 the function sets the value in the result variable to false in
3574 the calling scope. The result variable will hold a true value
3575 when the validator function is entered.
3576 function(my_check validator_result_var item)
3578 if(NOT item MATCHES ...)
3579 set(${validator_result_var} FALSE PARENT_SCOPE)
3580 endif()
3581 endfunction()
3582 find_file (result NAMES ... VALIDATOR my_check)
3584 Note that if a cached result is used, the search is skipped and
3586 any VALIDATOR is ignored. The cached result is not required to
3587 pass the validation function.
3588 DOC Specify the documentation string for the <VAR> cache entry.
3590 NO_CACHE
3592 New in version 3.21.
3593 The result of the search will be stored in a normal variable
3596 rather than a cache entry.
3597 NOTE:
3599 If the variable is already set before the call (as a normal
3600 or cache variable) then the search will not occur.
3601 WARNING:
3603 This option should be used with caution because it can
3604 greatly increase the cost of repeated configure steps.
3605 REQUIRED
3607 New in version 3.18.
3608 Stop processing with an error message if nothing is found, oth‐
3611 erwise the search will be attempted again the next time
3612 find_file is invoked with the same variable.
3613 If NO_DEFAULT_PATH is specified, then no additional paths are added to
3615 the search. If NO_DEFAULT_PATH is not specified, the search process is
3616 as follows:
3617 1. New in version 3.12: If called from within a find module or any
3619 other script loaded by a call to find_package(<PackageName>), search
3620 prefixes unique to the current package being found. Specifically,
3621 look in the <PackageName>_ROOT CMake variable and the
3622 <PackageName>_ROOT environment variable. The package root variables
3623 are maintained as a stack, so if called from nested find modules or
3624 config packages, root paths from the parent's find module or config
3625 package will be searched after paths from the current module or
3626 package. In other words, the search order would be <CurrentPack‐
3627 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
3628 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
3629 AGE_ROOT_PATH is passed or by setting the
3630 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
3631 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3634 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
3635 variable and the <PackageName>_ROOT environment variable if called
3636 from within a find module loaded by find_package(<PackageName>)
3637 2. Search paths specified in cmake-specific cache variables. These are
3639 intended to be used on the command line with a -DVAR=value. The
3640 values are interpreted as semicolon-separated lists. This can be
3641 skipped if NO_CMAKE_PATH is passed or by setting the
3642 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
3643 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3645 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3646 • CMAKE_INCLUDE_PATH
3648 • CMAKE_FRAMEWORK_PATH
3650 3. Search paths specified in cmake-specific environment variables.
3652 These are intended to be set in the user's shell configuration, and
3653 therefore use the host's native path separator (; on Windows and :
3654 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3655 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3656 FALSE.
3657 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3659 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3660 • CMAKE_INCLUDE_PATH
3662 • CMAKE_FRAMEWORK_PATH
3664 4. Search the paths specified by the HINTS option. These should be
3666 paths computed by system introspection, such as a hint provided by
3667 the location of another item already found. Hard-coded guesses
3668 should be specified with the PATHS option.
3669 5. Search the standard system environment variables. This can be
3671 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3672 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3673 • The directories in INCLUDE and PATH.
3675 • On Windows hosts: <prefix>/include/<arch> if
3677 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for each
3678 <prefix>/[s]bin in PATH, and <entry>/include for other entries in
3679 PATH.
3680 6. Search cmake variables defined in the Platform files for the current
3682 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
3683 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
3684 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
3685 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
3686 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3687 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3689 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3690 • CMAKE_SYSTEM_INCLUDE_PATH
3692 • CMAKE_SYSTEM_FRAMEWORK_PATH
3694 The platform paths that these variables contain are locations that
3696 typically include installed software. An example being /usr/local
3697 for UNIX based platforms.
3698 7. Search the paths specified by the PATHS option or in the short-hand
3700 version of the command. These are typically hard-coded guesses.
3701 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
3703 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
3704 can also cause some of the above locations to be ignored.
3705 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
3707 globally disable various search locations.
3708 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
3711 determine the order of preference between Apple-style and unix-style
3712 package components.
3713 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3715 ries to be prepended to all other search directories. This effectively
3716 "re-roots" the entire search under given locations. Paths which are
3717 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3718 ing, because that variable is always a path on the host system. By de‐
3719 fault the CMAKE_FIND_ROOT_PATH is empty.
3720 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3722 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3723 fects. See the documentation for that variable for more.
3724 These variables are especially useful when cross-compiling to point to
3726 the root directory of the target environment and CMake will search
3727 there too. By default at first the directories listed in
3728 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3729 searched, and then the non-rooted directories will be searched. The
3730 default behavior can be adjusted by setting
3731 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
3732 ridden on a per-call basis using options:
3733 CMAKE_FIND_ROOT_PATH_BOTH
3735 Search in the order described above.
3736 NO_CMAKE_FIND_ROOT_PATH
3738 Do not use the CMAKE_FIND_ROOT_PATH variable.
3739 ONLY_CMAKE_FIND_ROOT_PATH
3741 Search only the re-rooted directories and directories below
3742 CMAKE_STAGING_PREFIX.
3743 The default search order is designed to be most-specific to least-spe‐
3745 cific for common use cases. Projects may override the order by simply
3746 calling the command multiple times and using the NO_* options:
3747 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3749 find_file (<VAR> NAMES name)
3750 Once one of the calls succeeds the result variable will be set and
3752 stored in the cache so that no call will search again.
3753 find_library
3755 A short-hand signature is:
3756 find_library (<VAR> name1 [path1 path2 ...])
3758 The general signature is:
3760 find_library (
3762 <VAR>
3763 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
3764 [HINTS [path | ENV var]... ]
3765 [PATHS [path | ENV var]... ]
3766 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
3767 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3768 [VALIDATOR function]
3769 [DOC "cache documentation string"]
3770 [NO_CACHE]
3771 [REQUIRED]
3772 [NO_DEFAULT_PATH]
3773 [NO_PACKAGE_ROOT_PATH]
3774 [NO_CMAKE_PATH]
3775 [NO_CMAKE_ENVIRONMENT_PATH]
3776 [NO_SYSTEM_ENVIRONMENT_PATH]
3777 [NO_CMAKE_SYSTEM_PATH]
3778 [NO_CMAKE_INSTALL_PREFIX]
3779 [CMAKE_FIND_ROOT_PATH_BOTH |
3780 ONLY_CMAKE_FIND_ROOT_PATH |
3781 NO_CMAKE_FIND_ROOT_PATH]
3782 )
3783 This command is used to find a library. A cache entry, or a normal
3785 variable if NO_CACHE is specified, named by <VAR> is created to store
3786 the result of this command. If the library is found the result is
3787 stored in the variable and the search will not be repeated unless the
3788 variable is cleared. If nothing is found, the result will be
3789 <VAR>-NOTFOUND.
3790 Options include:
3792 NAMES Specify one or more possible names for the library.
3794 When using this to specify names with and without a version suf‐
3796 fix, we recommend specifying the unversioned name first so that
3797 locally-built packages can be found before those provided by
3798 distributions.
3799 HINTS, PATHS
3801 Specify directories to search in addition to the default loca‐
3802 tions. The ENV var sub-option reads paths from a system envi‐
3803 ronment variable.
3804 Changed in version 3.24: On Windows platform, it is possible to
3806 include registry queries as part of the directories, using a
3807 dedicated syntax. Such specifications will be ignored on all
3808 other platforms.
3809 REGISTRY_VIEW
3812 New in version 3.24.
3813 Specify which registry views must be queried. This option is
3816 only meaningful on Windows platforms and will be ignored on
3817 other ones. When not specified, the TARGET view is used when the
3818 CMP0134 policy is NEW. Refer to CMP0134 for the default view
3819 when the policy is OLD.
3820 64 Query the 64-bit registry. On 32-bit Windows, it always
3822 returns the string /REGISTRY-NOTFOUND.
3823 32 Query the 32-bit registry.
3825 64_32 Query both views (64 and 32) and generate a path for
3827 each.
3828 32_64 Query both views (32 and 64) and generate a path for
3830 each.
3831 HOST Query the registry matching the architecture of the host:
3833 64 on 64-bit Windows and 32 on 32-bit Windows.
3834 TARGET Query the registry matching the architecture specified by
3836 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
3837 back to HOST view.
3838 BOTH Query both views (32 and 64). The order depends on the
3840 following rules: If the CMAKE_SIZEOF_VOID_P variable is
3841 defined, use the following view depending on the content
3842 of this variable:
3843 • 8: 64_32
3845 • 4: 32_64
3847 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
3849 on the architecture of the host:
3850 • 64-bit: 64_32
3852 • 32-bit: 32
3854 PATH_SUFFIXES
3856 Specify additional subdirectories to check below each directory
3857 location otherwise considered.
3858 VALIDATOR
3860 New in version 3.25.
3861 Specify a function() to be called for each candidate item found
3864 (a macro() cannot be provided, that will result in an error).
3865 Two arguments will be passed to the validator function: the name
3866 of a result variable, and the absolute path to the candidate
3867 item. The item will be accepted and the search will end unless
3868 the function sets the value in the result variable to false in
3869 the calling scope. The result variable will hold a true value
3870 when the validator function is entered.
3871 function(my_check validator_result_var item)
3873 if(NOT item MATCHES ...)
3874 set(${validator_result_var} FALSE PARENT_SCOPE)
3875 endif()
3876 endfunction()
3877 find_library (result NAMES ... VALIDATOR my_check)
3879 Note that if a cached result is used, the search is skipped and
3881 any VALIDATOR is ignored. The cached result is not required to
3882 pass the validation function.
3883 DOC Specify the documentation string for the <VAR> cache entry.
3885 NO_CACHE
3887 New in version 3.21.
3888 The result of the search will be stored in a normal variable
3891 rather than a cache entry.
3892 NOTE:
3894 If the variable is already set before the call (as a normal
3895 or cache variable) then the search will not occur.
3896 WARNING:
3898 This option should be used with caution because it can
3899 greatly increase the cost of repeated configure steps.
3900 REQUIRED
3902 New in version 3.18.
3903 Stop processing with an error message if nothing is found, oth‐
3906 erwise the search will be attempted again the next time find_li‐
3907 brary is invoked with the same variable.
3908 If NO_DEFAULT_PATH is specified, then no additional paths are added to
3910 the search. If NO_DEFAULT_PATH is not specified, the search process is
3911 as follows:
3912 1. New in version 3.12: If called from within a find module or any
3914 other script loaded by a call to find_package(<PackageName>), search
3915 prefixes unique to the current package being found. Specifically,
3916 look in the <PackageName>_ROOT CMake variable and the
3917 <PackageName>_ROOT environment variable. The package root variables
3918 are maintained as a stack, so if called from nested find modules or
3919 config packages, root paths from the parent's find module or config
3920 package will be searched after paths from the current module or
3921 package. In other words, the search order would be <CurrentPack‐
3922 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
3923 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
3924 AGE_ROOT_PATH is passed or by setting the
3925 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
3926 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3929 <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake
3930 variable and the <PackageName>_ROOT environment variable if called
3931 from within a find module loaded by find_package(<PackageName>)
3932 2. Search paths specified in cmake-specific cache variables. These are
3934 intended to be used on the command line with a -DVAR=value. The
3935 values are interpreted as semicolon-separated lists. This can be
3936 skipped if NO_CMAKE_PATH is passed or by setting the
3937 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
3938 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3940 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
3941 • CMAKE_LIBRARY_PATH
3943 • CMAKE_FRAMEWORK_PATH
3945 3. Search paths specified in cmake-specific environment variables.
3947 These are intended to be set in the user's shell configuration, and
3948 therefore use the host's native path separator (; on Windows and :
3949 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3950 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3951 FALSE.
3952 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3954 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
3955 • CMAKE_LIBRARY_PATH
3957 • CMAKE_FRAMEWORK_PATH
3959 4. Search the paths specified by the HINTS option. These should be
3961 paths computed by system introspection, such as a hint provided by
3962 the location of another item already found. Hard-coded guesses
3963 should be specified with the PATHS option.
3964 5. Search the standard system environment variables. This can be
3966 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3967 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3968 • The directories in LIB and PATH.
3970 • On Windows hosts: <prefix>/lib/<arch> if
3972 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <pre‐
3973 fix>/[s]bin in PATH, and <entry>/lib for other entries in PATH.
3974 6. Search cmake variables defined in the Platform files for the current
3976 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
3977 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
3978 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
3979 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
3980 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3981 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3983 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3984 • CMAKE_SYSTEM_LIBRARY_PATH
3986 • CMAKE_SYSTEM_FRAMEWORK_PATH
3988 The platform paths that these variables contain are locations that
3990 typically include installed software. An example being /usr/local
3991 for UNIX based platforms.
3992 7. Search the paths specified by the PATHS option or in the short-hand
3994 version of the command. These are typically hard-coded guesses.
3995 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
3997 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
3998 can also cause some of the above locations to be ignored.
3999 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
4001 globally disable various search locations.
4002 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
4005 determine the order of preference between Apple-style and unix-style
4006 package components.
4007 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
4009 ries to be prepended to all other search directories. This effectively
4010 "re-roots" the entire search under given locations. Paths which are
4011 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
4012 ing, because that variable is always a path on the host system. By de‐
4013 fault the CMAKE_FIND_ROOT_PATH is empty.
4014 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
4016 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
4017 fects. See the documentation for that variable for more.
4018 These variables are especially useful when cross-compiling to point to
4020 the root directory of the target environment and CMake will search
4021 there too. By default at first the directories listed in
4022 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
4023 searched, and then the non-rooted directories will be searched. The
4024 default behavior can be adjusted by setting
4025 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
4026 ridden on a per-call basis using options:
4027 CMAKE_FIND_ROOT_PATH_BOTH
4029 Search in the order described above.
4030 NO_CMAKE_FIND_ROOT_PATH
4032 Do not use the CMAKE_FIND_ROOT_PATH variable.
4033 ONLY_CMAKE_FIND_ROOT_PATH
4035 Search only the re-rooted directories and directories below
4036 CMAKE_STAGING_PREFIX.
4037 The default search order is designed to be most-specific to least-spe‐
4039 cific for common use cases. Projects may override the order by simply
4040 calling the command multiple times and using the NO_* options:
4041 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
4043 find_library (<VAR> NAMES name)
4044 Once one of the calls succeeds the result variable will be set and
4046 stored in the cache so that no call will search again.
4047 When more than one value is given to the NAMES option this command by
4049 default will consider one name at a time and search every directory for
4050 it. The NAMES_PER_DIR option tells this command to consider one direc‐
4051 tory at a time and search for all names in it.
4052 Each library name given to the NAMES option is first considered as a
4054 library file name and then considered with platform-specific prefixes
4055 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
4056 file names such as libfoo.a directly. This can be used to locate
4057 static libraries on UNIX-like systems.
4058 If the library found is a framework, then <VAR> will be set to the full
4060 path to the framework <fullPath>/A.framework. When a full path to a
4061 framework is used as a library, CMake will use a -framework A, and a
4062 -F<fullPath> to link the framework to the target.
4063 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
4065 paths will be tested as normal, with the suffix appended, and with all
4066 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
4067 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
4068 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
4069 properties.
4070 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
4072 paths will be tested as normal, with 32/ appended, and with all matches
4073 of lib/ replaced with lib32/. This property is automatically set for
4074 the platforms that are known to need it if at least one of the lan‐
4075 guages supported by the project() command is enabled.
4076 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
4078 paths will be tested as normal, with x32/ appended, and with all
4079 matches of lib/ replaced with libx32/. This property is automatically
4080 set for the platforms that are known to need it if at least one of the
4081 languages supported by the project() command is enabled.
4082 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
4084 paths will be tested as normal, with 64/ appended, and with all matches
4085 of lib/ replaced with lib64/. This property is automatically set for
4086 the platforms that are known to need it if at least one of the lan‐
4087 guages supported by the project() command is enabled.
4088 find_package
4090 NOTE:
4091 The Using Dependencies Guide provides a high-level introduction to
4092 this general topic. It provides a broader overview of where the
4093 find_package() command fits into the bigger picture, including its
4094 relationship to the FetchContent module. The guide is recommended
4095 pre-reading before moving on to the details below.
4096 Find a package (usually provided by something external to the project),
4098 and load its package-specific details. Calls to this command can also
4099 be intercepted by dependency providers.
4100 Search Modes
4102 The command has a few modes by which it searches for packages:
4103 Module mode
4105 In this mode, CMake searches for a file called Find<Package‐
4106 Name>.cmake, looking first in the locations listed in the
4107 CMAKE_MODULE_PATH, then among the Find Modules provided by the
4108 CMake installation. If the file is found, it is read and pro‐
4109 cessed by CMake. It is responsible for finding the package,
4110 checking the version, and producing any needed messages. Some
4111 Find modules provide limited or no support for versioning; check
4112 the Find module's documentation.
4113 The Find<PackageName>.cmake file is not typically provided by
4115 the package itself. Rather, it is normally provided by some‐
4116 thing external to the package, such as the operating system,
4117 CMake itself, or even the project from which the find_package()
4118 command was called. Being externally provided, Find Modules
4119 tend to be heuristic in nature and are susceptible to becoming
4120 out-of-date. They typically search for certain libraries, files
4121 and other package artifacts.
4122 Module mode is only supported by the basic command signature.
4124 Config mode
4126 In this mode, CMake searches for a file called <lowercasePacka‐
4127 geName>-config.cmake or <PackageName>Config.cmake. It will also
4128 look for <lowercasePackageName>-config-version.cmake or <Packa‐
4129 geName>ConfigVersion.cmake if version details were specified
4130 (see Config Mode Version Selection for an explanation of how
4131 these separate version files are used).
4132 In config mode, the command can be given a list of names to
4134 search for as package names. The locations where CMake searches
4135 for the config and version files is considerably more compli‐
4136 cated than for Module mode (see Config Mode Search Procedure).
4137 The config and version files are typically installed as part of
4139 the package, so they tend to be more reliable than Find modules.
4140 They usually contain direct knowledge of the package contents,
4141 so no searching or heuristics are needed within the config or
4142 version files themselves.
4143 Config mode is supported by both the basic and full command sig‐
4145 natures.
4146 FetchContent redirection mode
4148 New in version 3.24: A call to find_package() can be redirected
4149 internally to a package provided by the FetchContent module. To
4150 the caller, the behavior will appear similar to Config mode, ex‐
4151 cept that the search logic is by-passed and the component infor‐
4152 mation is not used. See FetchContent_Declare() and
4153 FetchContent_MakeAvailable() for further details.
4154 When not redirected to a package provided by FetchContent, the command
4157 arguments determine whether Module or Config mode is used. When the
4158 basic signature is used, the command searches in Module mode first. If
4159 the package is not found, the search falls back to Config mode. A user
4160 may set the CMAKE_FIND_PACKAGE_PREFER_CONFIG variable to true to re‐
4161 verse the priority and direct CMake to search using Config mode first
4162 before falling back to Module mode. The basic signature can also be
4163 forced to use only Module mode with a MODULE keyword. If the full sig‐
4164 nature is used, the command only searches in Config mode.
4165 Where possible, user code should generally look for packages using the
4167 basic signature, since that allows the package to be found with any
4168 mode. Project maintainers wishing to provide a config package should
4169 understand the bigger picture, as explained in Full Signature and all
4170 subsequent sections on this page.
4171 Basic Signature
4173 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
4174 [REQUIRED] [[COMPONENTS] [components...]]
4175 [OPTIONAL_COMPONENTS components...]
4176 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
4177 [GLOBAL]
4178 [NO_POLICY_SCOPE]
4179 [BYPASS_PROVIDER])
4180 The basic signature is supported by both Module and Config modes. The
4182 MODULE keyword implies that only Module mode can be used to find the
4183 package, with no fallback to Config mode.
4184 Regardless of the mode used, a <PackageName>_FOUND variable will be set
4186 to indicate whether the package was found. When the package is found,
4187 package-specific information may be provided through other variables
4188 and Imported Targets documented by the package itself. The QUIET op‐
4189 tion disables informational messages, including those indicating that
4190 the package cannot be found if it is not REQUIRED. The REQUIRED option
4191 stops processing with an error message if the package cannot be found.
4192 A package-specific list of required components may be listed after the
4194 COMPONENTS keyword. If any of these components are not able to be sat‐
4195 isfied, the package overall is considered to be not found. If the RE‐
4196 QUIRED option is also present, this is treated as a fatal error, other‐
4197 wise execution still continues. As a form of shorthand, if the RE‐
4198 QUIRED option is present, the COMPONENTS keyword can be omitted and the
4199 required components can be listed directly after REQUIRED.
4200 Additional optional components may be listed after OPTIONAL_COMPONENTS.
4202 If these cannot be satisfied, the package overall can still be consid‐
4203 ered found, as long as all required components are satisfied.
4204 The set of available components and their meaning are defined by the
4206 target package. Formally, it is up to the target package how to inter‐
4207 pret the component information given to it, but it should follow the
4208 expectations stated above. For calls where no components are speci‐
4209 fied, there is no single expected behavior and target packages should
4210 clearly define what occurs in such cases. Common arrangements include
4211 assuming it should find all components, no components or some well-de‐
4212 fined subset of the available components.
4213 New in version 3.24: The REGISTRY_VIEW keyword specifies which registry
4215 views should be queried. This keyword is only meaningful on Windows
4216 platforms and will be ignored on all others. Formally, it is up to the
4217 target package how to interpret the registry view information given to
4218 it.
4219 New in version 3.24: Specifying the GLOBAL keyword will promote all im‐
4222 ported targets to a global scope in the importing project. Alterna‐
4223 tively, this functionality can be enabled by setting the
4224 CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable.
4225 The [version] argument requests a version with which the package found
4228 should be compatible. There are two possible forms in which it may be
4229 specified:
4230 • A single version with the format major[.minor[.patch[.tweak]]],
4232 where each component is a numeric value.
4233 • A version range with the format versionMin...[<]versionMax where
4235 versionMin and versionMax have the same format and constraints on
4236 components being integers as the single version. By default, both
4237 end points are included. By specifying <, the upper end point
4238 will be excluded. Version ranges are only supported with CMake
4239 3.19 or later.
4240 The EXACT option requests that the version be matched exactly. This op‐
4242 tion is incompatible with the specification of a version range.
4243 If no [version] and/or component list is given to a recursive invoca‐
4245 tion inside a find-module, the corresponding arguments are forwarded
4246 automatically from the outer call (including the EXACT flag for [ver‐
4247 sion]). Version support is currently provided only on a pack‐
4248 age-by-package basis (see the Version Selection section below). When a
4249 version range is specified but the package is only designed to expect a
4250 single version, the package will ignore the upper end point of the
4251 range and only take the single version at the lower end of the range
4252 into account.
4253 See the cmake_policy() command documentation for discussion of the
4255 NO_POLICY_SCOPE option.
4256 New in version 3.24: The BYPASS_PROVIDER keyword is only allowed when
4258 find_package() is being called by a dependency provider. It can be
4259 used by providers to call the built-in find_package() implementation
4260 directly and prevent that call from being re-routed back to itself.
4261 Future versions of CMake may detect attempts to use this keyword from
4262 places other than a dependency provider and halt with a fatal error.
4263 Full Signature
4266 find_package(<PackageName> [version] [EXACT] [QUIET]
4267 [REQUIRED] [[COMPONENTS] [components...]]
4268 [OPTIONAL_COMPONENTS components...]
4269 [CONFIG|NO_MODULE]
4270 [GLOBAL]
4271 [NO_POLICY_SCOPE]
4272 [BYPASS_PROVIDER]
4273 [NAMES name1 [name2 ...]]
4274 [CONFIGS config1 [config2 ...]]
4275 [HINTS path1 [path2 ... ]]
4276 [PATHS path1 [path2 ... ]]
4277 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
4278 [PATH_SUFFIXES suffix1 [suffix2 ...]]
4279 [NO_DEFAULT_PATH]
4280 [NO_PACKAGE_ROOT_PATH]
4281 [NO_CMAKE_PATH]
4282 [NO_CMAKE_ENVIRONMENT_PATH]
4283 [NO_SYSTEM_ENVIRONMENT_PATH]
4284 [NO_CMAKE_PACKAGE_REGISTRY]
4285 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
4286 [NO_CMAKE_SYSTEM_PATH]
4287 [NO_CMAKE_INSTALL_PREFIX]
4288 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
4289 [CMAKE_FIND_ROOT_PATH_BOTH |
4290 ONLY_CMAKE_FIND_ROOT_PATH |
4291 NO_CMAKE_FIND_ROOT_PATH])
4292 The CONFIG option, the synonymous NO_MODULE option, or the use of op‐
4294 tions not specified in the basic signature all enforce pure Config
4295 mode. In pure Config mode, the command skips Module mode search and
4296 proceeds at once with Config mode search.
4297 Config mode search attempts to locate a configuration file provided by
4299 the package to be found. A cache entry called <PackageName>_DIR is
4300 created to hold the directory containing the file. By default, the
4301 command searches for a package with the name <PackageName>. If the
4302 NAMES option is given, the names following it are used instead of
4303 <PackageName>. The names are also considered when determining whether
4304 to redirect the call to a package provided by FetchContent.
4305 The command searches for a file called <PackageName>Config.cmake or
4307 <lowercasePackageName>-config.cmake for each name specified. A re‐
4308 placement set of possible configuration file names may be given using
4309 the CONFIGS option. The Config Mode Search Procedure is specified be‐
4310 low. Once found, any version constraint is checked, and if satisfied,
4311 the configuration file is read and processed by CMake. Since the file
4312 is provided by the package it already knows the location of package
4313 contents. The full path to the configuration file is stored in the
4314 cmake variable <PackageName>_CONFIG.
4315 All configuration files which have been considered by CMake while
4317 searching for the package with an appropriate version are stored in the
4318 <PackageName>_CONSIDERED_CONFIGS variable, and the associated versions
4319 in the <PackageName>_CONSIDERED_VERSIONS variable.
4320 If the package configuration file cannot be found CMake will generate
4322 an error describing the problem unless the QUIET argument is specified.
4323 If REQUIRED is specified and the package is not found a fatal error is
4324 generated and the configure step stops executing. If <PackageName>_DIR
4325 has been set to a directory not containing a configuration file CMake
4326 will ignore it and search from scratch.
4327 Package maintainers providing CMake package configuration files are en‐
4329 couraged to name and install them such that the Config Mode Search Pro‐
4330 cedure outlined below will find them without requiring use of addi‐
4331 tional options.
4332 Config Mode Search Procedure
4334 NOTE:
4335 When Config mode is used, this search procedure is applied regard‐
4336 less of whether the full or basic signature was given.
4337 New in version 3.24: All calls to find_package() (even in Module mode)
4339 first look for a config package file in the
4340 CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory. The FetchContent module,
4341 or even the project itself, may write files to that location to redi‐
4342 rect find_package() calls to content already provided by the project.
4343 If no config package file is found in that location, the search pro‐
4344 ceeds with the logic described below.
4345 CMake constructs a set of possible installation prefixes for the pack‐
4348 age. Under each prefix several directories are searched for a configu‐
4349 ration file. The tables below show the directories searched. Each en‐
4350 try is meant for installation trees following Windows (W), UNIX (U), or
4351 Apple (A) conventions:
4352 ┌────────────────────────────────────────────────────────────┬────────────┐
4354 │Entry │ Convention │
4355 ├────────────────────────────────────────────────────────────┼────────────┤
4356 │<prefix>/ │ W │
4357 ├────────────────────────────────────────────────────────────┼────────────┤
4358 │<prefix>/(cmake|CMake)/ │ W │
4359 ├────────────────────────────────────────────────────────────┼────────────┤
4360 │<prefix>/<name>*/ │ W │
4361 ├────────────────────────────────────────────────────────────┼────────────┤
4362 │<pre‐ │ W │
4363 │fix>/<name>*/(cmake|CMake)/ │ │
4364 ├────────────────────────────────────────────────────────────┼────────────┤
4365 │<pre‐ │ W │
4366 │fix>/<name>*/(cmake|CMake)/<name>*/ │ │
4367 │[1] │ │
4368 ├────────────────────────────────────────────────────────────┼────────────┤
4369 │<pre‐ │ U │
4370 │fix>/(lib/<arch>|lib*|share)/cmake/<name>*/ │ │
4371 ├────────────────────────────────────────────────────────────┼────────────┤
4372 │<prefix>/(lib/<arch>|lib*|share)/<name>*/ │ U │
4373 ├────────────────────────────────────────────────────────────┼────────────┤
4374 │<pre‐ │ U │
4375 │fix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ │ │
4376 ├────────────────────────────────────────────────────────────┼────────────┤
4377 │<pre‐ │ W/U │
4378 │fix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ │ │
4379 ├────────────────────────────────────────────────────────────┼────────────┤
4380 │<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ │ W/U │
4381 ├────────────────────────────────────────────────────────────┼────────────┤
4382 │<pre‐ │ W/U │
4383 │fix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ │ │
4384 └────────────────────────────────────────────────────────────┴────────────┘
4385 [1] New in version 3.25.
4387 On systems supporting macOS FRAMEWORK and BUNDLE, the following
4390 directories are searched for Frameworks or Application Bundles
4391 containing a configuration file:
4392 ┌───────────────────────────┬────────────┐
4394 │Entry │ Convention │
4395 ├───────────────────────────┼────────────┤
4396 │<prefix>/<name>.frame‐ │ A │
4397 │work/Resources/ │ │
4398 ├───────────────────────────┼────────────┤
4399 │<prefix>/<name>.frame‐ │ A │
4400 │work/Resources/CMake/ │ │
4401 ├───────────────────────────┼────────────┤
4402 │<prefix>/<name>.frame‐ │ A │
4403 │work/Versions/*/Resources/ │ │
4404 ├───────────────────────────┼────────────┤
4405 │<prefix>/<name>.frame‐ │ A │
4406 │work/Versions/*/Re‐ │ │
4407 │sources/CMake/ │ │
4408 ├───────────────────────────┼────────────┤
4409 │<prefix>/<name>.app/Con‐ │ A │
4410 │tents/Resources/ │ │
4411 ├───────────────────────────┼────────────┤
4412 │<prefix>/<name>.app/Con‐ │ A │
4413 │tents/Resources/CMake/ │ │
4414 └───────────────────────────┴────────────┘
4415 In all cases the <name> is treated as case-insensitive and corre‐
4417 sponds to any of the names specified (<PackageName> or names given
4418 by NAMES).
4419 Paths with lib/<arch> are enabled if the
4421 CMAKE_LIBRARY_ARCHITECTURE variable is set. lib* includes one or
4422 more of the values lib64, lib32, libx32 or lib (searched in that
4423 order).
4424 • Paths with lib64 are searched on 64 bit platforms if the
4426 FIND_LIBRARY_USE_LIB64_PATHS property is set to TRUE.
4427 • Paths with lib32 are searched on 32 bit platforms if the
4429 FIND_LIBRARY_USE_LIB32_PATHS property is set to TRUE.
4430 • Paths with libx32 are searched on platforms using the x32 ABI if the
4432 FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.
4433 • The lib path is always searched.
4435 Changed in version 3.24: On Windows platform, it is possible to include
4437 registry queries as part of the directories specified through HINTS and
4438 PATHS keywords, using a dedicated syntax. Such specifications will be
4439 ignored on all other platforms.
4440 New in version 3.24: REGISTRY_VIEW can be specified to manage Windows
4443 registry queries specified as part of PATHS and HINTS.
4444 Specify which registry views must be queried. This option is only mean‐
4447 ingful on Windows platforms and will be ignored on other ones. When not
4448 specified, the TARGET view is used when the CMP0134 policy is NEW. Re‐
4449 fer to CMP0134 for the default view when the policy is OLD.
4450 64 Query the 64-bit registry. On 32-bit Windows, it always returns
4452 the string /REGISTRY-NOTFOUND.
4453 32 Query the 32-bit registry.
4455 64_32 Query both views (64 and 32) and generate a path for each.
4457 32_64 Query both views (32 and 64) and generate a path for each.
4459 HOST Query the registry matching the architecture of the host: 64 on
4461 64-bit Windows and 32 on 32-bit Windows.
4462 TARGET Query the registry matching the architecture specified by the
4464 CMAKE_SIZEOF_VOID_P variable. If not defined, fall back to HOST
4465 view.
4466 BOTH Query both views (32 and 64). The order depends on the following
4468 rules: If the CMAKE_SIZEOF_VOID_P variable is defined, use the
4469 following view depending on the content of this variable:
4470 • 8: 64_32
4472 • 4: 32_64
4474 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely on the
4476 architecture of the host:
4477 • 64-bit: 64_32
4479 • 32-bit: 32
4481 If PATH_SUFFIXES is specified, the suffixes are appended to each (W) or
4483 (U) directory entry one-by-one.
4484 This set of directories is intended to work in cooperation with
4486 projects that provide configuration files in their installation trees.
4487 Directories above marked with (W) are intended for installations on
4488 Windows where the prefix may point at the top of an application's in‐
4489 stallation directory. Those marked with (U) are intended for installa‐
4490 tions on UNIX platforms where the prefix is shared by multiple pack‐
4491 ages. This is merely a convention, so all (W) and (U) directories are
4492 still searched on all platforms. Directories marked with (A) are in‐
4493 tended for installations on Apple platforms. The CMAKE_FIND_FRAMEWORK
4494 and CMAKE_FIND_APPBUNDLE variables determine the order of preference.
4495 The set of installation prefixes is constructed using the following
4497 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
4498 1. New in version 3.12: Search paths specified in the
4500 <PackageName>_ROOT CMake variable and the <PackageName>_ROOT envi‐
4501 ronment variable, where <PackageName> is the package to be found.
4502 The package root variables are maintained as a stack so if called
4503 from within a find module, root paths from the parent's find module
4504 will also be searched after paths for the current package. This can
4505 be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
4506 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
4507 2. Search paths specified in cmake-specific cache variables. These are
4510 intended to be used on the command line with a -DVAR=VALUE. The
4511 values are interpreted as semicolon-separated lists. This can be
4512 skipped if NO_CMAKE_PATH is passed or by setting the
4513 CMAKE_FIND_USE_CMAKE_PATH to FALSE:
4514 • CMAKE_PREFIX_PATH
4516 • CMAKE_FRAMEWORK_PATH
4518 • CMAKE_APPBUNDLE_PATH
4520 3. Search paths specified in cmake-specific environment variables.
4522 These are intended to be set in the user's shell configuration, and
4523 therefore use the host's native path separator (; on Windows and :
4524 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
4525 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
4526 FALSE:
4527 • <PackageName>_DIR
4529 • CMAKE_PREFIX_PATH
4531 • CMAKE_FRAMEWORK_PATH
4533 • CMAKE_APPBUNDLE_PATH
4535 4. Search paths specified by the HINTS option. These should be paths
4537 computed by system introspection, such as a hint provided by the lo‐
4538 cation of another item already found. Hard-coded guesses should be
4539 specified with the PATHS option.
4540 5. Search the standard system environment variables. This can be
4542 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
4543 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE. Path entries ending
4544 in /bin or /sbin are automatically converted to their parent direc‐
4545 tories:
4546 • PATH
4548 6. Search paths stored in the CMake User Package Registry. This can be
4550 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
4551 variable CMAKE_FIND_USE_PACKAGE_REGISTRY to FALSE or the deprecated
4552 variable CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.
4553 See the cmake-packages(7) manual for details on the user package
4555 registry.
4556 7. Search cmake variables defined in the Platform files for the current
4558 system. The searching of CMAKE_INSTALL_PREFIX and
4559 CMAKE_STAGING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is
4560 passed or by setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All
4561 these locations can be skipped if NO_CMAKE_SYSTEM_PATH is passed or
4562 by setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE:
4563 • CMAKE_SYSTEM_PREFIX_PATH
4565 • CMAKE_SYSTEM_FRAMEWORK_PATH
4567 • CMAKE_SYSTEM_APPBUNDLE_PATH
4569 The platform paths that these variables contain are locations that
4571 typically include installed software. An example being /usr/local
4572 for UNIX based platforms.
4573 8. Search paths stored in the CMake System Package Registry. This can
4575 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
4576 ting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to FALSE or
4577 the deprecated variable
4578 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to TRUE.
4579 See the cmake-packages(7) manual for details on the system package
4581 registry.
4582 9. Search paths specified by the PATHS option. These are typically
4584 hard-coded guesses.
4585 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
4587 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
4588 can also cause some of the above locations to be ignored.
4589 New in version 3.16: Added the CMAKE_FIND_USE_<CATEGORY> variables to
4591 globally disable various search locations.
4592 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
4595 ries to be prepended to all other search directories. This effectively
4596 "re-roots" the entire search under given locations. Paths which are
4597 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
4598 ing, because that variable is always a path on the host system. By de‐
4599 fault the CMAKE_FIND_ROOT_PATH is empty.
4600 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
4602 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
4603 fects. See the documentation for that variable for more.
4604 These variables are especially useful when cross-compiling to point to
4606 the root directory of the target environment and CMake will search
4607 there too. By default at first the directories listed in
4608 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
4609 searched, and then the non-rooted directories will be searched. The
4610 default behavior can be adjusted by setting
4611 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
4612 ridden on a per-call basis using options:
4613 CMAKE_FIND_ROOT_PATH_BOTH
4615 Search in the order described above.
4616 NO_CMAKE_FIND_ROOT_PATH
4618 Do not use the CMAKE_FIND_ROOT_PATH variable.
4619 ONLY_CMAKE_FIND_ROOT_PATH
4621 Search only the re-rooted directories and directories below
4622 CMAKE_STAGING_PREFIX.
4623 The default search order is designed to be most-specific to least-spe‐
4625 cific for common use cases. Projects may override the order by simply
4626 calling the command multiple times and using the NO_* options:
4627 find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
4629 find_package (<PackageName>)
4630 Once one of the calls succeeds the result variable will be set and
4632 stored in the cache so that no call will search again.
4633 By default the value stored in the result variable will be the path at
4635 which the file is found. The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS vari‐
4636 able may be set to TRUE before calling find_package in order to resolve
4637 symbolic links and store the real path to the file.
4638 Every non-REQUIRED find_package call can be disabled or made REQUIRED:
4640 • Setting the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE
4642 disables the package. This also disables redirection to a package
4643 provided by FetchContent.
4644 • Setting the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable to TRUE
4646 makes the package REQUIRED.
4647 Setting both variables to TRUE simultaneously is an error.
4649 Config Mode Version Selection
4651 NOTE:
4652 When Config mode is used, this version selection process is applied
4653 regardless of whether the full or basic signature was given.
4654 When the [version] argument is given, Config mode will only find a ver‐
4656 sion of the package that claims compatibility with the requested ver‐
4657 sion (see format specification). If the EXACT option is given, only a
4658 version of the package claiming an exact match of the requested version
4659 may be found. CMake does not establish any convention for the meaning
4660 of version numbers. Package version numbers are checked by "version"
4661 files provided by the packages themselves or by FetchContent. For a
4662 candidate package configuration file <config-file>.cmake the corre‐
4663 sponding version file is located next to it and named either <con‐
4664 fig-file>-version.cmake or <config-file>Version.cmake. If no such ver‐
4665 sion file is available then the configuration file is assumed to not be
4666 compatible with any requested version. A basic version file containing
4667 generic version matching code can be created using the
4668 CMakePackageConfigHelpers module. When a version file is found it is
4669 loaded to check the requested version number. The version file is
4670 loaded in a nested scope in which the following variables have been de‐
4671 fined:
4672 PACKAGE_FIND_NAME
4674 The <PackageName>
4675 PACKAGE_FIND_VERSION
4677 Full requested version string
4678 PACKAGE_FIND_VERSION_MAJOR
4680 Major version if requested, else 0
4681 PACKAGE_FIND_VERSION_MINOR
4683 Minor version if requested, else 0
4684 PACKAGE_FIND_VERSION_PATCH
4686 Patch version if requested, else 0
4687 PACKAGE_FIND_VERSION_TWEAK
4689 Tweak version if requested, else 0
4690 PACKAGE_FIND_VERSION_COUNT
4692 Number of version components, 0 to 4
4693 When a version range is specified, the above version variables will
4695 hold values based on the lower end of the version range. This is to
4696 preserve compatibility with packages that have not been implemented to
4697 expect version ranges. In addition, the version range will be de‐
4698 scribed by the following variables:
4699 PACKAGE_FIND_VERSION_RANGE
4701 Full requested version range string
4702 PACKAGE_FIND_VERSION_RANGE_MIN
4704 This specifies whether the lower end point of the version range
4705 should be included or excluded. Currently, the only supported
4706 value for this variable is INCLUDE.
4707 PACKAGE_FIND_VERSION_RANGE_MAX
4709 This specifies whether the upper end point of the version range
4710 should be included or excluded. The supported values for this
4711 variable are INCLUDE and EXCLUDE.
4712 PACKAGE_FIND_VERSION_MIN
4714 Full requested version string of the lower end point of the
4715 range
4716 PACKAGE_FIND_VERSION_MIN_MAJOR
4718 Major version of the lower end point if requested, else 0
4719 PACKAGE_FIND_VERSION_MIN_MINOR
4721 Minor version of the lower end point if requested, else 0
4722 PACKAGE_FIND_VERSION_MIN_PATCH
4724 Patch version of the lower end point if requested, else 0
4725 PACKAGE_FIND_VERSION_MIN_TWEAK
4727 Tweak version of the lower end point if requested, else 0
4728 PACKAGE_FIND_VERSION_MIN_COUNT
4730 Number of version components of the lower end point, 0 to 4
4731 PACKAGE_FIND_VERSION_MAX
4733 Full requested version string of the upper end point of the
4734 range
4735 PACKAGE_FIND_VERSION_MAX_MAJOR
4737 Major version of the upper end point if requested, else 0
4738 PACKAGE_FIND_VERSION_MAX_MINOR
4740 Minor version of the upper end point if requested, else 0
4741 PACKAGE_FIND_VERSION_MAX_PATCH
4743 Patch version of the upper end point if requested, else 0
4744 PACKAGE_FIND_VERSION_MAX_TWEAK
4746 Tweak version of the upper end point if requested, else 0
4747 PACKAGE_FIND_VERSION_MAX_COUNT
4749 Number of version components of the upper end point, 0 to 4
4750 Regardless of whether a single version or a version range is specified,
4752 the variable PACKAGE_FIND_VERSION_COMPLETE will be defined and will
4753 hold the full requested version string as specified.
4754 The version file checks whether it satisfies the requested version and
4756 sets these variables:
4757 PACKAGE_VERSION
4759 Full provided version string
4760 PACKAGE_VERSION_EXACT
4762 True if version is exact match
4763 PACKAGE_VERSION_COMPATIBLE
4765 True if version is compatible
4766 PACKAGE_VERSION_UNSUITABLE
4768 True if unsuitable as any version
4769 These variables are checked by the find_package command to determine
4771 whether the configuration file provides an acceptable version. They
4772 are not available after the find_package call returns. If the version
4773 is acceptable the following variables are set:
4774 <PackageName>_VERSION
4776 Full provided version string
4777 <PackageName>_VERSION_MAJOR
4779 Major version if provided, else 0
4780 <PackageName>_VERSION_MINOR
4782 Minor version if provided, else 0
4783 <PackageName>_VERSION_PATCH
4785 Patch version if provided, else 0
4786 <PackageName>_VERSION_TWEAK
4788 Tweak version if provided, else 0
4789 <PackageName>_VERSION_COUNT
4791 Number of version components, 0 to 4
4792 and the corresponding package configuration file is loaded. When mul‐
4794 tiple package configuration files are available whose version files
4795 claim compatibility with the version requested it is unspecified which
4796 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
4797 no attempt is made to choose a highest or closest version number.
4798 To control the order in which find_package checks for compatibility use
4800 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and
4801 CMAKE_FIND_PACKAGE_SORT_DIRECTION. For instance in order to select the
4802 highest version one can set
4803 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
4805 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
4806 before calling find_package.
4808 Package File Interface Variables
4810 When loading a find module or package configuration file find_package
4811 defines variables to provide information about the call arguments (and
4812 restores their original state before returning):
4813 CMAKE_FIND_PACKAGE_NAME
4815 The <PackageName> which is searched for
4816 <PackageName>_FIND_REQUIRED
4818 True if REQUIRED option was given
4819 <PackageName>_FIND_QUIETLY
4821 True if QUIET option was given
4822 <PackageName>_FIND_REGISTRY_VIEW
4824 The requested view if REGISTRY_VIEW option was given
4825 <PackageName>_FIND_VERSION
4827 Full requested version string
4828 <PackageName>_FIND_VERSION_MAJOR
4830 Major version if requested, else 0
4831 <PackageName>_FIND_VERSION_MINOR
4833 Minor version if requested, else 0
4834 <PackageName>_FIND_VERSION_PATCH
4836 Patch version if requested, else 0
4837 <PackageName>_FIND_VERSION_TWEAK
4839 Tweak version if requested, else 0
4840 <PackageName>_FIND_VERSION_COUNT
4842 Number of version components, 0 to 4
4843 <PackageName>_FIND_VERSION_EXACT
4845 True if EXACT option was given
4846 <PackageName>_FIND_COMPONENTS
4848 List of specified components (required and optional)
4849 <PackageName>_FIND_REQUIRED_<c>
4851 True if component <c> is required, false if component <c> is op‐
4852 tional
4853 When a version range is specified, the above version variables will
4855 hold values based on the lower end of the version range. This is to
4856 preserve compatibility with packages that have not been implemented to
4857 expect version ranges. In addition, the version range will be de‐
4858 scribed by the following variables:
4859 <PackageName>_FIND_VERSION_RANGE
4861 Full requested version range string
4862 <PackageName>_FIND_VERSION_RANGE_MIN
4864 This specifies whether the lower end point of the version range
4865 is included or excluded. Currently, INCLUDE is the only sup‐
4866 ported value.
4867 <PackageName>_FIND_VERSION_RANGE_MAX
4869 This specifies whether the upper end point of the version range
4870 is included or excluded. The possible values for this variable
4871 are INCLUDE or EXCLUDE.
4872 <PackageName>_FIND_VERSION_MIN
4874 Full requested version string of the lower end point of the
4875 range
4876 <PackageName>_FIND_VERSION_MIN_MAJOR
4878 Major version of the lower end point if requested, else 0
4879 <PackageName>_FIND_VERSION_MIN_MINOR
4881 Minor version of the lower end point if requested, else 0
4882 <PackageName>_FIND_VERSION_MIN_PATCH
4884 Patch version of the lower end point if requested, else 0
4885 <PackageName>_FIND_VERSION_MIN_TWEAK
4887 Tweak version of the lower end point if requested, else 0
4888 <PackageName>_FIND_VERSION_MIN_COUNT
4890 Number of version components of the lower end point, 0 to 4
4891 <PackageName>_FIND_VERSION_MAX
4893 Full requested version string of the upper end point of the
4894 range
4895 <PackageName>_FIND_VERSION_MAX_MAJOR
4897 Major version of the upper end point if requested, else 0
4898 <PackageName>_FIND_VERSION_MAX_MINOR
4900 Minor version of the upper end point if requested, else 0
4901 <PackageName>_FIND_VERSION_MAX_PATCH
4903 Patch version of the upper end point if requested, else 0
4904 <PackageName>_FIND_VERSION_MAX_TWEAK
4906 Tweak version of the upper end point if requested, else 0
4907 <PackageName>_FIND_VERSION_MAX_COUNT
4909 Number of version components of the upper end point, 0 to 4
4910 Regardless of whether a single version or a version range is specified,
4912 the variable <PackageName>_FIND_VERSION_COMPLETE will be defined and
4913 will hold the full requested version string as specified.
4914 In Module mode the loaded find module is responsible to honor the re‐
4916 quest detailed by these variables; see the find module for details. In
4917 Config mode find_package handles REQUIRED, QUIET, and [version] options
4918 automatically but leaves it to the package configuration file to handle
4919 components in a way that makes sense for the package. The package con‐
4920 figuration file may set <PackageName>_FOUND to false to tell find_pack‐
4921 age that component requirements are not satisfied.
4922 find_path
4924 A short-hand signature is:
4925 find_path (<VAR> name1 [path1 path2 ...])
4927 The general signature is:
4929 find_path (
4931 <VAR>
4932 name | NAMES name1 [name2 ...]
4933 [HINTS [path | ENV var]... ]
4934 [PATHS [path | ENV var]... ]
4935 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
4936 [PATH_SUFFIXES suffix1 [suffix2 ...]]
4937 [VALIDATOR function]
4938 [DOC "cache documentation string"]
4939 [NO_CACHE]
4940 [REQUIRED]
4941 [NO_DEFAULT_PATH]
4942 [NO_PACKAGE_ROOT_PATH]
4943 [NO_CMAKE_PATH]
4944 [NO_CMAKE_ENVIRONMENT_PATH]
4945 [NO_SYSTEM_ENVIRONMENT_PATH]
4946 [NO_CMAKE_SYSTEM_PATH]
4947 [NO_CMAKE_INSTALL_PREFIX]
4948 [CMAKE_FIND_ROOT_PATH_BOTH |
4949 ONLY_CMAKE_FIND_ROOT_PATH |
4950 NO_CMAKE_FIND_ROOT_PATH]
4951 )
4952 This command is used to find a directory containing the named file. A
4954 cache entry, or a normal variable if NO_CACHE is specified, named by
4955 <VAR> is created to store the result of this command. If the file in a
4956 directory is found the result is stored in the variable and the search
4957 will not be repeated unless the variable is cleared. If nothing is
4958 found, the result will be <VAR>-NOTFOUND.
4959 Options include:
4961 NAMES Specify one or more possible names for the file in a directory.
4963 When using this to specify names with and without a version suf‐
4965 fix, we recommend specifying the unversioned name first so that
4966 locally-built packages can be found before those provided by
4967 distributions.
4968 HINTS, PATHS
4970 Specify directories to search in addition to the default loca‐
4971 tions. The ENV var sub-option reads paths from a system envi‐
4972 ronment variable.
4973 Changed in version 3.24: On Windows platform, it is possible to
4975 include registry queries as part of the directories, using a
4976 dedicated syntax. Such specifications will be ignored on all
4977 other platforms.
4978 REGISTRY_VIEW
4981 New in version 3.24.
4982 Specify which registry views must be queried. This option is
4985 only meaningful on Windows platforms and will be ignored on
4986 other ones. When not specified, the TARGET view is used when the
4987 CMP0134 policy is NEW. Refer to CMP0134 for the default view
4988 when the policy is OLD.
4989 64 Query the 64-bit registry. On 32-bit Windows, it always
4991 returns the string /REGISTRY-NOTFOUND.
4992 32 Query the 32-bit registry.
4994 64_32 Query both views (64 and 32) and generate a path for
4996 each.
4997 32_64 Query both views (32 and 64) and generate a path for
4999 each.
5000 HOST Query the registry matching the architecture of the host:
5002 64 on 64-bit Windows and 32 on 32-bit Windows.
5003 TARGET Query the registry matching the architecture specified by
5005 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
5006 back to HOST view.
5007 BOTH Query both views (32 and 64). The order depends on the
5009 following rules: If the CMAKE_SIZEOF_VOID_P variable is
5010 defined, use the following view depending on the content
5011 of this variable:
5012 • 8: 64_32
5014 • 4: 32_64
5016 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
5018 on the architecture of the host:
5019 • 64-bit: 64_32
5021 • 32-bit: 32
5023 PATH_SUFFIXES
5025 Specify additional subdirectories to check below each directory
5026 location otherwise considered.
5027 VALIDATOR
5029 New in version 3.25.
5030 Specify a function() to be called for each candidate item found
5033 (a macro() cannot be provided, that will result in an error).
5034 Two arguments will be passed to the validator function: the name
5035 of a result variable, and the absolute path to the candidate
5036 item. The item will be accepted and the search will end unless
5037 the function sets the value in the result variable to false in
5038 the calling scope. The result variable will hold a true value
5039 when the validator function is entered.
5040 function(my_check validator_result_var item)
5042 if(NOT item MATCHES ...)
5043 set(${validator_result_var} FALSE PARENT_SCOPE)
5044 endif()
5045 endfunction()
5046 find_path (result NAMES ... VALIDATOR my_check)
5048 Note that if a cached result is used, the search is skipped and
5050 any VALIDATOR is ignored. The cached result is not required to
5051 pass the validation function.
5052 DOC Specify the documentation string for the <VAR> cache entry.
5054 NO_CACHE
5056 New in version 3.21.
5057 The result of the search will be stored in a normal variable
5060 rather than a cache entry.
5061 NOTE:
5063 If the variable is already set before the call (as a normal
5064 or cache variable) then the search will not occur.
5065 WARNING:
5067 This option should be used with caution because it can
5068 greatly increase the cost of repeated configure steps.
5069 REQUIRED
5071 New in version 3.18.
5072 Stop processing with an error message if nothing is found, oth‐
5075 erwise the search will be attempted again the next time
5076 find_path is invoked with the same variable.
5077 If NO_DEFAULT_PATH is specified, then no additional paths are added to
5079 the search. If NO_DEFAULT_PATH is not specified, the search process is
5080 as follows:
5081 1. New in version 3.12: If called from within a find module or any
5083 other script loaded by a call to find_package(<PackageName>), search
5084 prefixes unique to the current package being found. Specifically,
5085 look in the <PackageName>_ROOT CMake variable and the
5086 <PackageName>_ROOT environment variable. The package root variables
5087 are maintained as a stack, so if called from nested find modules or
5088 config packages, root paths from the parent's find module or config
5089 package will be searched after paths from the current module or
5090 package. In other words, the search order would be <CurrentPack‐
5091 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
5092 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
5093 AGE_ROOT_PATH is passed or by setting the
5094 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
5095 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5098 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
5099 variable and the <PackageName>_ROOT environment variable if called
5100 from within a find module loaded by find_package(<PackageName>)
5101 2. Search paths specified in cmake-specific cache variables. These are
5103 intended to be used on the command line with a -DVAR=value. The
5104 values are interpreted as semicolon-separated lists. This can be
5105 skipped if NO_CMAKE_PATH is passed or by setting the
5106 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
5107 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5109 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
5110 • CMAKE_INCLUDE_PATH
5112 • CMAKE_FRAMEWORK_PATH
5114 3. Search paths specified in cmake-specific environment variables.
5116 These are intended to be set in the user's shell configuration, and
5117 therefore use the host's native path separator (; on Windows and :
5118 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
5119 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
5120 FALSE.
5121 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5123 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
5124 • CMAKE_INCLUDE_PATH
5126 • CMAKE_FRAMEWORK_PATH
5128 4. Search the paths specified by the HINTS option. These should be
5130 paths computed by system introspection, such as a hint provided by
5131 the location of another item already found. Hard-coded guesses
5132 should be specified with the PATHS option.
5133 5. Search the standard system environment variables. This can be
5135 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
5136 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
5137 • The directories in INCLUDE and PATH.
5139 • On Windows hosts: <prefix>/include/<arch> if
5141 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for each
5142 <prefix>/[s]bin in PATH, and <entry>/include for other entries in
5143 PATH.
5144 6. Search cmake variables defined in the Platform files for the current
5146 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
5147 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
5148 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
5149 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
5150 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
5151 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5153 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
5154 • CMAKE_SYSTEM_INCLUDE_PATH
5156 • CMAKE_SYSTEM_FRAMEWORK_PATH
5158 The platform paths that these variables contain are locations that
5160 typically include installed software. An example being /usr/local
5161 for UNIX based platforms.
5162 7. Search the paths specified by the PATHS option or in the short-hand
5164 version of the command. These are typically hard-coded guesses.
5165 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
5167 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
5168 can also cause some of the above locations to be ignored.
5169 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
5171 globally disable various search locations.
5172 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
5175 determine the order of preference between Apple-style and unix-style
5176 package components.
5177 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
5179 ries to be prepended to all other search directories. This effectively
5180 "re-roots" the entire search under given locations. Paths which are
5181 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
5182 ing, because that variable is always a path on the host system. By de‐
5183 fault the CMAKE_FIND_ROOT_PATH is empty.
5184 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
5186 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
5187 fects. See the documentation for that variable for more.
5188 These variables are especially useful when cross-compiling to point to
5190 the root directory of the target environment and CMake will search
5191 there too. By default at first the directories listed in
5192 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
5193 searched, and then the non-rooted directories will be searched. The
5194 default behavior can be adjusted by setting
5195 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
5196 ridden on a per-call basis using options:
5197 CMAKE_FIND_ROOT_PATH_BOTH
5199 Search in the order described above.
5200 NO_CMAKE_FIND_ROOT_PATH
5202 Do not use the CMAKE_FIND_ROOT_PATH variable.
5203 ONLY_CMAKE_FIND_ROOT_PATH
5205 Search only the re-rooted directories and directories below
5206 CMAKE_STAGING_PREFIX.
5207 The default search order is designed to be most-specific to least-spe‐
5209 cific for common use cases. Projects may override the order by simply
5210 calling the command multiple times and using the NO_* options:
5211 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
5213 find_path (<VAR> NAMES name)
5214 Once one of the calls succeeds the result variable will be set and
5216 stored in the cache so that no call will search again.
5217 When searching for frameworks, if the file is specified as A/b.h, then
5219 the framework search will look for A.framework/Headers/b.h. If that is
5220 found the path will be set to the path to the framework. CMake will
5221 convert this to the correct -F option to include the file.
5222 find_program
5224 A short-hand signature is:
5225 find_program (<VAR> name1 [path1 path2 ...])
5227 The general signature is:
5229 find_program (
5231 <VAR>
5232 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
5233 [HINTS [path | ENV var]... ]
5234 [PATHS [path | ENV var]... ]
5235 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
5236 [PATH_SUFFIXES suffix1 [suffix2 ...]]
5237 [VALIDATOR function]
5238 [DOC "cache documentation string"]
5239 [NO_CACHE]
5240 [REQUIRED]
5241 [NO_DEFAULT_PATH]
5242 [NO_PACKAGE_ROOT_PATH]
5243 [NO_CMAKE_PATH]
5244 [NO_CMAKE_ENVIRONMENT_PATH]
5245 [NO_SYSTEM_ENVIRONMENT_PATH]
5246 [NO_CMAKE_SYSTEM_PATH]
5247 [NO_CMAKE_INSTALL_PREFIX]
5248 [CMAKE_FIND_ROOT_PATH_BOTH |
5249 ONLY_CMAKE_FIND_ROOT_PATH |
5250 NO_CMAKE_FIND_ROOT_PATH]
5251 )
5252 This command is used to find a program. A cache entry, or a normal
5254 variable if NO_CACHE is specified, named by <VAR> is created to store
5255 the result of this command. If the program is found the result is
5256 stored in the variable and the search will not be repeated unless the
5257 variable is cleared. If nothing is found, the result will be
5258 <VAR>-NOTFOUND.
5259 Options include:
5261 NAMES Specify one or more possible names for the program.
5263 When using this to specify names with and without a version suf‐
5265 fix, we recommend specifying the unversioned name first so that
5266 locally-built packages can be found before those provided by
5267 distributions.
5268 HINTS, PATHS
5270 Specify directories to search in addition to the default loca‐
5271 tions. The ENV var sub-option reads paths from a system envi‐
5272 ronment variable.
5273 Changed in version 3.24: On Windows platform, it is possible to
5275 include registry queries as part of the directories, using a
5276 dedicated syntax. Such specifications will be ignored on all
5277 other platforms.
5278 REGISTRY_VIEW
5281 New in version 3.24.
5282 Specify which registry views must be queried. This option is
5285 only meaningful on Windows platforms and will be ignored on
5286 other ones. When not specified, the BOTH view is used when the
5287 CMP0134 policy is NEW. Refer to CMP0134 for the default view
5288 when the policy is OLD.
5289 64 Query the 64-bit registry. On 32-bit Windows, it always
5291 returns the string /REGISTRY-NOTFOUND.
5292 32 Query the 32-bit registry.
5294 64_32 Query both views (64 and 32) and generate a path for
5296 each.
5297 32_64 Query both views (32 and 64) and generate a path for
5299 each.
5300 HOST Query the registry matching the architecture of the host:
5302 64 on 64-bit Windows and 32 on 32-bit Windows.
5303 TARGET Query the registry matching the architecture specified by
5305 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
5306 back to HOST view.
5307 BOTH Query both views (32 and 64). The order depends on the
5309 following rules: If the CMAKE_SIZEOF_VOID_P variable is
5310 defined, use the following view depending on the content
5311 of this variable:
5312 • 8: 64_32
5314 • 4: 32_64
5316 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
5318 on the architecture of the host:
5319 • 64-bit: 64_32
5321 • 32-bit: 32
5323 PATH_SUFFIXES
5325 Specify additional subdirectories to check below each directory
5326 location otherwise considered.
5327 VALIDATOR
5329 New in version 3.25.
5330 Specify a function() to be called for each candidate item found
5333 (a macro() cannot be provided, that will result in an error).
5334 Two arguments will be passed to the validator function: the name
5335 of a result variable, and the absolute path to the candidate
5336 item. The item will be accepted and the search will end unless
5337 the function sets the value in the result variable to false in
5338 the calling scope. The result variable will hold a true value
5339 when the validator function is entered.
5340 function(my_check validator_result_var item)
5342 if(NOT item MATCHES ...)
5343 set(${validator_result_var} FALSE PARENT_SCOPE)
5344 endif()
5345 endfunction()
5346 find_program (result NAMES ... VALIDATOR my_check)
5348 Note that if a cached result is used, the search is skipped and
5350 any VALIDATOR is ignored. The cached result is not required to
5351 pass the validation function.
5352 DOC Specify the documentation string for the <VAR> cache entry.
5354 NO_CACHE
5356 New in version 3.21.
5357 The result of the search will be stored in a normal variable
5360 rather than a cache entry.
5361 NOTE:
5363 If the variable is already set before the call (as a normal
5364 or cache variable) then the search will not occur.
5365 WARNING:
5367 This option should be used with caution because it can
5368 greatly increase the cost of repeated configure steps.
5369 REQUIRED
5371 New in version 3.18.
5372 Stop processing with an error message if nothing is found, oth‐
5375 erwise the search will be attempted again the next time
5376 find_program is invoked with the same variable.
5377 If NO_DEFAULT_PATH is specified, then no additional paths are added to
5379 the search. If NO_DEFAULT_PATH is not specified, the search process is
5380 as follows:
5381 1. New in version 3.12: If called from within a find module or any
5383 other script loaded by a call to find_package(<PackageName>), search
5384 prefixes unique to the current package being found. Specifically,
5385 look in the <PackageName>_ROOT CMake variable and the
5386 <PackageName>_ROOT environment variable. The package root variables
5387 are maintained as a stack, so if called from nested find modules or
5388 config packages, root paths from the parent's find module or config
5389 package will be searched after paths from the current module or
5390 package. In other words, the search order would be <CurrentPack‐
5391 age>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT,
5392 ENV{<ParentPackage>_ROOT}, etc. This can be skipped if NO_PACK‐
5393 AGE_ROOT_PATH is passed or by setting the
5394 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE. See policy CMP0074.
5395 • <prefix>/[s]bin for each <prefix> in the <PackageName>_ROOT CMake
5398 variable and the <PackageName>_ROOT environment variable if called
5399 from within a find module loaded by find_package(<PackageName>)
5400 2. Search paths specified in cmake-specific cache variables. These are
5402 intended to be used on the command line with a -DVAR=value. The
5403 values are interpreted as semicolon-separated lists. This can be
5404 skipped if NO_CMAKE_PATH is passed or by setting the
5405 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
5406 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
5408 • CMAKE_PROGRAM_PATH
5410 • CMAKE_APPBUNDLE_PATH
5412 3. Search paths specified in cmake-specific environment variables.
5414 These are intended to be set in the user's shell configuration, and
5415 therefore use the host's native path separator (; on Windows and :
5416 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
5417 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
5418 FALSE.
5419 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
5421 • CMAKE_PROGRAM_PATH
5423 • CMAKE_APPBUNDLE_PATH
5425 4. Search the paths specified by the HINTS option. These should be
5427 paths computed by system introspection, such as a hint provided by
5428 the location of another item already found. Hard-coded guesses
5429 should be specified with the PATHS option.
5430 5. Search the standard system environment variables. This can be
5432 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
5433 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
5434 • The directories in PATH itself.
5436 • On Windows hosts no extra search paths are included
5438 6. Search cmake variables defined in the Platform files for the current
5440 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
5441 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
5442 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
5443 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
5444 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
5445 • <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
5447 • CMAKE_SYSTEM_PROGRAM_PATH
5449 • CMAKE_SYSTEM_APPBUNDLE_PATH
5451 The platform paths that these variables contain are locations that
5453 typically include installed software. An example being /usr/local
5454 for UNIX based platforms.
5455 7. Search the paths specified by the PATHS option or in the short-hand
5457 version of the command. These are typically hard-coded guesses.
5458 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
5460 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
5461 can also cause some of the above locations to be ignored.
5462 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
5464 globally disable various search locations.
5465 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
5468 determine the order of preference between Apple-style and unix-style
5469 package components.
5470 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
5472 ries to be prepended to all other search directories. This effectively
5473 "re-roots" the entire search under given locations. Paths which are
5474 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
5475 ing, because that variable is always a path on the host system. By de‐
5476 fault the CMAKE_FIND_ROOT_PATH is empty.
5477 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
5479 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
5480 fects. See the documentation for that variable for more.
5481 These variables are especially useful when cross-compiling to point to
5483 the root directory of the target environment and CMake will search
5484 there too. By default at first the directories listed in
5485 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
5486 searched, and then the non-rooted directories will be searched. The
5487 default behavior can be adjusted by setting
5488 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
5489 ridden on a per-call basis using options:
5490 CMAKE_FIND_ROOT_PATH_BOTH
5492 Search in the order described above.
5493 NO_CMAKE_FIND_ROOT_PATH
5495 Do not use the CMAKE_FIND_ROOT_PATH variable.
5496 ONLY_CMAKE_FIND_ROOT_PATH
5498 Search only the re-rooted directories and directories below
5499 CMAKE_STAGING_PREFIX.
5500 The default search order is designed to be most-specific to least-spe‐
5502 cific for common use cases. Projects may override the order by simply
5503 calling the command multiple times and using the NO_* options:
5504 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
5506 find_program (<VAR> NAMES name)
5507 Once one of the calls succeeds the result variable will be set and
5509 stored in the cache so that no call will search again.
5510 When more than one value is given to the NAMES option this command by
5512 default will consider one name at a time and search every directory for
5513 it. The NAMES_PER_DIR option tells this command to consider one direc‐
5514 tory at a time and search for all names in it.
5515 foreach
5517 Evaluate a group of commands for each value in a list.
5518 foreach(<loop_var> <items>)
5520 <commands>
5521 endforeach()
5522 where <items> is a list of items that are separated by semicolon or
5524 whitespace. All commands between foreach and the matching endforeach
5525 are recorded without being invoked. Once the endforeach is evaluated,
5526 the recorded list of commands is invoked once for each item in <items>.
5527 At the beginning of each iteration the variable <loop_var> will be set
5528 to the value of the current item.
5529 The scope of <loop_var> is restricted to the loop scope. See policy
5531 CMP0124 for details.
5532 The commands break() and continue() provide means to escape from the
5534 normal control flow.
5535 Per legacy, the endforeach() command admits an optional <loop_var> ar‐
5537 gument. If used, it must be a verbatim repeat of the argument of the
5538 opening foreach command.
5539 foreach(<loop_var> RANGE <stop>)
5541 In this variant, foreach iterates over the numbers 0, 1, ... up to (and
5543 including) the nonnegative integer <stop>.
5544 foreach(<loop_var> RANGE <start> <stop> [<step>])
5546 In this variant, foreach iterates over the numbers from <start> up to
5548 at most <stop> in steps of <step>. If <step> is not specified, then
5549 the step size is 1. The three arguments <start> <stop> <step> must all
5550 be nonnegative integers, and <stop> must not be smaller than <start>;
5551 otherwise you enter the danger zone of undocumented behavior that may
5552 change in future releases.
5553 foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
5555 In this variant, <lists> is a whitespace or semicolon separated list of
5557 list-valued variables. The foreach command iterates over each item in
5558 each given list. The <items> following the ITEMS keyword are processed
5559 as in the first variant of the foreach command. The forms LISTS A and
5560 ITEMS ${A} are equivalent.
5561 The following example shows how the LISTS option is processed:
5563 set(A 0;1)
5565 set(B 2 3)
5566 set(C "4 5")
5567 set(D 6;7 8)
5568 set(E "")
5569 foreach(X IN LISTS A B C D E)
5570 message(STATUS "X=${X}")
5571 endforeach()
5572 yields
5574 -- X=0
5576 -- X=1
5577 -- X=2
5578 -- X=3
5579 -- X=4 5
5580 -- X=6
5581 -- X=7
5582 -- X=8
5583 foreach(<loop_var>... IN ZIP_LISTS <lists>)
5585 New in version 3.17.
5587 In this variant, <lists> is a whitespace or semicolon separated list of
5590 list-valued variables. The foreach command iterates over each list si‐
5591 multaneously setting the iteration variables as follows:
5592 • if the only loop_var given, then it sets a series of loop_var_N vari‐
5594 ables to the current item from the corresponding list;
5595 • if multiple variable names passed, their count should match the lists
5597 variables count;
5598 • if any of the lists are shorter, the corresponding iteration variable
5600 is not defined for the current iteration.
5601 list(APPEND English one two three four)
5603 list(APPEND Bahasa satu dua tiga)
5604 foreach(num IN ZIP_LISTS English Bahasa)
5606 message(STATUS "num_0=${num_0}, num_1=${num_1}")
5607 endforeach()
5608 foreach(en ba IN ZIP_LISTS English Bahasa)
5610 message(STATUS "en=${en}, ba=${ba}")
5611 endforeach()
5612 yields
5614 -- num_0=one, num_1=satu
5616 -- num_0=two, num_1=dua
5617 -- num_0=three, num_1=tiga
5618 -- num_0=four, num_1=
5619 -- en=one, ba=satu
5620 -- en=two, ba=dua
5621 -- en=three, ba=tiga
5622 -- en=four, ba=
5623 See Also
5625 • break()
5626 • continue()
5628 • endforeach()
5630 • while()
5632 function
5634 Start recording a function for later invocation as a command.
5635 function(<name> [<arg1> ...])
5637 <commands>
5638 endfunction()
5639 Defines a function named <name> that takes arguments named <arg1>, ...
5641 The <commands> in the function definition are recorded; they are not
5642 executed until the function is invoked.
5643 Per legacy, the endfunction() command admits an optional <name> argu‐
5645 ment. If used, it must be a verbatim repeat of the argument of the
5646 opening function command.
5647 A function opens a new scope: see set(var PARENT_SCOPE) for details.
5649 See the cmake_policy() command documentation for the behavior of poli‐
5651 cies inside functions.
5652 See the macro() command documentation for differences between CMake
5654 functions and macros.
5655 Invocation
5657 The function invocation is case-insensitive. A function defined as
5658 function(foo)
5660 <commands>
5661 endfunction()
5662 can be invoked through any of
5664 foo()
5666 Foo()
5667 FOO()
5668 cmake_language(CALL foo)
5669 and so on. However, it is strongly recommended to stay with the case
5671 chosen in the function definition. Typically functions use all-lower‐
5672 case names.
5673 New in version 3.18: The cmake_language(CALL ...) command can also be
5675 used to invoke the function.
5676 Arguments
5679 When the function is invoked, the recorded <commands> are first modi‐
5680 fied by replacing formal parameters (${arg1}, ...) with the arguments
5681 passed, and then invoked as normal commands.
5682 In addition to referencing the formal parameters you can reference the
5684 ARGC variable which will be set to the number of arguments passed into
5685 the function as well as ARGV0, ARGV1, ARGV2, ... which will have the
5686 actual values of the arguments passed in. This facilitates creating
5687 functions with optional arguments.
5688 Furthermore, ARGV holds the list of all arguments given to the function
5690 and ARGN holds the list of arguments past the last expected argument.
5691 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
5692 Checking that ARGC is greater than # is the only way to ensure that
5693 ARGV# was passed to the function as an extra argument.
5694 See Also
5696 • endfunction()
5697 • return()
5699 get_cmake_property
5701 Get a global property of the CMake instance.
5702 get_cmake_property(<var> <property>)
5704 Gets a global property from the CMake instance. The value of the
5706 <property> is stored in the variable <var>. If the property is not
5707 found, <var> will be set to NOTFOUND. See the cmake-properties(7) man‐
5708 ual for available properties.
5709 See also the get_property() command GLOBAL option.
5711 In addition to global properties, this command (for historical reasons)
5713 also supports the VARIABLES and MACROS directory properties. It also
5714 supports a special COMPONENTS global property that lists the components
5715 given to the install() command.
5716 get_directory_property
5718 Get a property of DIRECTORY scope.
5719 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
5721 Stores a property of directory scope in the named <variable>.
5723 The DIRECTORY argument specifies another directory from which to re‐
5725 trieve the property value instead of the current directory. Relative
5726 paths are treated as relative to the current source directory. CMake
5727 must already know about the directory, either by having added it
5728 through a call to add_subdirectory() or being the top level directory.
5729 New in version 3.19: <dir> may reference a binary directory.
5731 If the property is not defined for the nominated directory scope, an
5734 empty string is returned. In the case of INHERITED properties, if the
5735 property is not found for the nominated directory scope, the search
5736 will chain to a parent scope as described for the define_property()
5737 command.
5738 get_directory_property(<variable> [DIRECTORY <dir>]
5740 DEFINITION <var-name>)
5741 Get a variable definition from a directory. This form is useful to get
5743 a variable definition from another directory.
5744 See also the more general get_property() command.
5746 get_filename_component
5748 Get a specific component of a full filename.
5749 Changed in version 3.20: This command has been superseded by
5751 cmake_path() command, except REALPATH now offered by file(REAL_PATH)
5752 command and PROGRAM now available in separate_arguments(PROGRAM) com‐
5753 mand.
5754 Changed in version 3.24: The undocumented feature offering the capabil‐
5757 ity to query the Windows registry is superseded by
5758 cmake_host_system_information(QUERY WINDOWS_REGISTRY) command.
5759 get_filename_component(<var> <FileName> <mode> [CACHE])
5762 Sets <var> to a component of <FileName>, where <mode> is one of:
5764 DIRECTORY = Directory without file name
5766 NAME = File name without directory
5767 EXT = File name longest extension (.b.c from d/a.b.c)
5768 NAME_WE = File name with neither the directory nor the longest extension
5769 LAST_EXT = File name last extension (.c from d/a.b.c)
5770 NAME_WLE = File name with neither the directory nor the last extension
5771 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
5772 New in version 3.14: Added the LAST_EXT and NAME_WLE modes.
5774 Paths are returned with forward slashes and have no trailing slashes.
5777 If the optional CACHE argument is specified, the result variable is
5778 added to the cache.
5779 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
5781 New in version 3.4.
5783 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
5786 ABSOLUTE = Full path to file
5788 REALPATH = Full path to existing file with symlinks resolved
5789 If the provided <FileName> is a relative path, it is evaluated relative
5791 to the given base directory <dir>. If no base directory is provided,
5792 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
5793 Paths are returned with forward slashes and have no trailing slashes.
5795 If the optional CACHE argument is specified, the result variable is
5796 added to the cache.
5797 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
5799 The program in <FileName> will be found in the system search path or
5801 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
5802 command-line arguments present in the <FileName> string are split from
5803 the program name and stored in <arg_var>. This is used to separate a
5804 program name from its arguments in a command line string.
5805 get_property
5807 Get a property.
5808 get_property(<variable>
5810 <GLOBAL |
5811 DIRECTORY [<dir>] |
5812 TARGET <target> |
5813 SOURCE <source>
5814 [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
5815 INSTALL <file> |
5816 TEST <test> |
5817 CACHE <entry> |
5818 VARIABLE >
5819 PROPERTY <name>
5820 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
5821 Gets one property from one object in a scope.
5823 The first argument specifies the variable in which to store the result.
5825 The second argument determines the scope from which to get the prop‐
5826 erty. It must be one of the following:
5827 GLOBAL Scope is unique and does not accept a name.
5829 DIRECTORY
5831 Scope defaults to the current directory but another directory
5832 (already processed by CMake) may be named by the full or rela‐
5833 tive path <dir>. Relative paths are treated as relative to the
5834 current source directory. See also the get_directory_property()
5835 command.
5836 New in version 3.19: <dir> may reference a binary directory.
5838 TARGET Scope must name one existing target. See also the
5841 get_target_property() command.
5842 SOURCE Scope must name one source file. By default, the source file's
5844 property will be read from the current source directory's scope.
5845 New in version 3.18: Directory scope can be overridden with one
5847 of the following sub-options:
5848 DIRECTORY <dir>
5850 The source file property will be read from the <dir> di‐
5851 rectory's scope. CMake must already know about the di‐
5852 rectory, either by having added it through a call to
5853 add_subdirectory() or <dir> being the top level direc‐
5854 tory. Relative paths are treated as relative to the cur‐
5855 rent source directory.
5856 New in version 3.19: <dir> may reference a binary direc‐
5858 tory.
5859 TARGET_DIRECTORY <target>
5862 The source file property will be read from the directory
5863 scope in which <target> was created (<target> must there‐
5864 fore already exist).
5865 See also the get_source_file_property() command.
5868 INSTALL
5870 New in version 3.1.
5871 Scope must name one installed file path.
5874 TEST Scope must name one existing test. See also the
5876 get_test_property() command.
5877 CACHE Scope must name one cache entry.
5879 VARIABLE
5881 Scope is unique and does not accept a name.
5882 The required PROPERTY option is immediately followed by the name of the
5884 property to get. If the property is not set an empty value is re‐
5885 turned, although some properties support inheriting from a parent scope
5886 if defined to behave that way (see define_property()).
5887 If the SET option is given the variable is set to a boolean value indi‐
5889 cating whether the property has been set. If the DEFINED option is
5890 given the variable is set to a boolean value indicating whether the
5891 property has been defined such as with the define_property() command.
5892 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
5894 string containing documentation for the requested property. If docu‐
5895 mentation is requested for a property that has not been defined NOT‐
5896 FOUND is returned.
5897 NOTE:
5899 The GENERATED source file property may be globally visible. See its
5900 documentation for details.
5901 if
5903 Conditionally execute a group of commands.
5904 Synopsis
5906 if(<condition>)
5907 <commands>
5908 elseif(<condition>) # optional block, can be repeated
5909 <commands>
5910 else() # optional block
5911 <commands>
5912 endif()
5913 Evaluates the condition argument of the if clause according to the
5915 Condition syntax described below. If the result is true, then the com‐
5916 mands in the if block are executed. Otherwise, optional elseif blocks
5917 are processed in the same way. Finally, if no condition is true, com‐
5918 mands in the optional else block are executed.
5919 Per legacy, the else() and endif() commands admit an optional <condi‐
5921 tion> argument. If used, it must be a verbatim repeat of the argument
5922 of the opening if command.
5923 Condition Syntax
5925 The following syntax applies to the condition argument of the if, el‐
5926 seif and while() clauses.
5927 Compound conditions are evaluated in the following order of precedence:
5929 1. Parentheses.
5931 2. Unary tests such as EXISTS, COMMAND, and DEFINED.
5933 3. Binary tests such as EQUAL, LESS, LESS_EQUAL, GREATER,
5935 GREATER_EQUAL, STREQUAL, STRLESS, STRLESS_EQUAL, STRGREATER,
5936 STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS, VERSION_LESS_EQUAL,
5937 VERSION_GREATER, VERSION_GREATER_EQUAL, PATH_EQUAL, and MATCHES.
5938 4. Unary logical operator NOT.
5940 5. Binary logical operators AND and OR, from left to right, without any
5942 short-circuit.
5943 Basic Expressions
5945 if(<constant>)
5946 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
5947 ber (including floating point numbers). False if the constant
5948 is 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, the empty string, or
5949 ends in the suffix -NOTFOUND. Named boolean constants are
5950 case-insensitive. If the argument is not one of these specific
5951 constants, it is treated as a variable or string (see Variable
5952 Expansion further below) and one of the following two forms ap‐
5953 plies.
5954 if(<variable>)
5956 True if given a variable that is defined to a value that is not
5957 a false constant. False otherwise, including if the variable is
5958 undefined. Note that macro arguments are not variables.
5959 Environment Variables also cannot be tested this way, e.g.
5960 if(ENV{some_var}) will always evaluate to false.
5961 if(<string>)
5963 A quoted string always evaluates to false unless:
5964 • The string's value is one of the true constants, or
5966 • Policy CMP0054 is not set to NEW and the string's value hap‐
5968 pens to be a variable name that is affected by CMP0054's be‐
5969 havior.
5970 Logic Operators
5972 if(NOT <condition>)
5973 True if the condition is not true.
5974 if(<cond1> AND <cond2>)
5976 True if both conditions would be considered true individually.
5977 if(<cond1> OR <cond2>)
5979 True if either condition would be considered true individually.
5980 if((condition) AND (condition OR (condition)))
5982 The conditions inside the parenthesis are evaluated first and
5983 then the remaining condition is evaluated as in the other exam‐
5984 ples. Where there are nested parenthesis the innermost are
5985 evaluated as part of evaluating the condition that contains
5986 them.
5987 Existence Checks
5989 if(COMMAND command-name)
5990 True if the given name is a command, macro or function that can
5991 be invoked.
5992 if(POLICY policy-id)
5994 True if the given name is an existing policy (of the form
5995 CMP<NNNN>).
5996 if(TARGET target-name)
5998 True if the given name is an existing logical target name cre‐
5999 ated by a call to the add_executable(), add_library(), or
6000 add_custom_target() command that has already been invoked (in
6001 any directory).
6002 if(TEST test-name)
6004 New in version 3.3: True if the given name is an existing test
6005 name created by the add_test() command.
6006 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
6009 True if a variable, cache variable or environment variable with
6010 given <name> is defined. The value of the variable does not mat‐
6011 ter. Note the following caveats:
6012 • Macro arguments are not variables.
6014 • It is not possible to test directly whether a <name> is a
6016 non-cache variable. The expression if(DEFINED someName) will
6017 evaluate to true if either a cache or non-cache variable some‐
6018 Name exists. In comparison, the expression if(DEFINED
6019 CACHE{someName}) will only evaluate to true if a cache vari‐
6020 able someName exists. Both expressions need to be tested if
6021 you need to know whether a non-cache variable exists: if(DE‐
6022 FINED someName AND NOT DEFINED CACHE{someName}).
6023 New in version 3.14: Added support for CACHE{<name>} variables.
6025 if(<variable|string> IN_LIST <variable>)
6028 New in version 3.3: True if the given element is contained in
6029 the named list variable.
6030 File Operations
6033 if(EXISTS path-to-file-or-directory)
6034 True if the named file or directory exists. Behavior is
6035 well-defined only for explicit full paths (a leading ~/ is not
6036 expanded as a home directory and is considered a relative path).
6037 Resolves symbolic links, i.e. if the named file or directory is
6038 a symbolic link, returns true if the target of the symbolic link
6039 exists.
6040 if(file1 IS_NEWER_THAN file2)
6042 True if file1 is newer than file2 or if one of the two files
6043 doesn't exist. Behavior is well-defined only for full paths.
6044 If the file time stamps are exactly the same, an IS_NEWER_THAN
6045 comparison returns true, so that any dependent build operations
6046 will occur in the event of a tie. This includes the case of
6047 passing the same file name for both file1 and file2.
6048 if(IS_DIRECTORY path-to-directory)
6050 True if the given name is a directory. Behavior is well-defined
6051 only for full paths.
6052 if(IS_SYMLINK file-name)
6054 True if the given name is a symbolic link. Behavior is well-de‐
6055 fined only for full paths.
6056 if(IS_ABSOLUTE path)
6058 True if the given path is an absolute path. Note the following
6059 special cases:
6060 • An empty path evaluates to false.
6062 • On Windows hosts, any path that begins with a drive letter and
6064 colon (e.g. C:), a forward slash or a backslash will evaluate
6065 to true. This means a path like C:no\base\dir will evaluate
6066 to true, even though the non-drive part of the path is rela‐
6067 tive.
6068 • On non-Windows hosts, any path that begins with a tilde (~)
6070 evaluates to true.
6071 Comparisons
6073 if(<variable|string> MATCHES regex)
6074 True if the given string or variable's value matches the given
6075 regular expression. See Regex Specification for regex format.
6076 New in version 3.9: () groups are captured in CMAKE_MATCH_<n>
6078 variables.
6079 if(<variable|string> LESS <variable|string>)
6082 True if the given string or variable's value is a valid number
6083 and less than that on the right.
6084 if(<variable|string> GREATER <variable|string>)
6086 True if the given string or variable's value is a valid number
6087 and greater than that on the right.
6088 if(<variable|string> EQUAL <variable|string>)
6090 True if the given string or variable's value is a valid number
6091 and equal to that on the right.
6092 if(<variable|string> LESS_EQUAL <variable|string>)
6094 New in version 3.7: True if the given string or variable's value
6095 is a valid number and less than or equal to that on the right.
6096 if(<variable|string> GREATER_EQUAL <variable|string>)
6099 New in version 3.7: True if the given string or variable's value
6100 is a valid number and greater than or equal to that on the
6101 right.
6102 if(<variable|string> STRLESS <variable|string>)
6105 True if the given string or variable's value is lexicographi‐
6106 cally less than the string or variable on the right.
6107 if(<variable|string> STRGREATER <variable|string>)
6109 True if the given string or variable's value is lexicographi‐
6110 cally greater than the string or variable on the right.
6111 if(<variable|string> STREQUAL <variable|string>)
6113 True if the given string or variable's value is lexicographi‐
6114 cally equal to the string or variable on the right.
6115 if(<variable|string> STRLESS_EQUAL <variable|string>)
6117 New in version 3.7: True if the given string or variable's value
6118 is lexicographically less than or equal to the string or vari‐
6119 able on the right.
6120 if(<variable|string> STRGREATER_EQUAL <variable|string>)
6123 New in version 3.7: True if the given string or variable's value
6124 is lexicographically greater than or equal to the string or
6125 variable on the right.
6126 Version Comparisons
6129 if(<variable|string> VERSION_LESS <variable|string>)
6130 Component-wise integer version number comparison (version format
6131 is major[.minor[.patch[.tweak]]], omitted components are treated
6132 as zero). Any non-integer version component or non-integer
6133 trailing part of a version component effectively truncates the
6134 string at that point.
6135 if(<variable|string> VERSION_GREATER <variable|string>)
6137 Component-wise integer version number comparison (version format
6138 is major[.minor[.patch[.tweak]]], omitted components are treated
6139 as zero). Any non-integer version component or non-integer
6140 trailing part of a version component effectively truncates the
6141 string at that point.
6142 if(<variable|string> VERSION_EQUAL <variable|string>)
6144 Component-wise integer version number comparison (version format
6145 is major[.minor[.patch[.tweak]]], omitted components are treated
6146 as zero). Any non-integer version component or non-integer
6147 trailing part of a version component effectively truncates the
6148 string at that point.
6149 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
6151 New in version 3.7: Component-wise integer version number com‐
6152 parison (version format is major[.minor[.patch[.tweak]]], omit‐
6153 ted components are treated as zero). Any non-integer version
6154 component or non-integer trailing part of a version component
6155 effectively truncates the string at that point.
6156 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
6159 New in version 3.7: Component-wise integer version number com‐
6160 parison (version format is major[.minor[.patch[.tweak]]], omit‐
6161 ted components are treated as zero). Any non-integer version
6162 component or non-integer trailing part of a version component
6163 effectively truncates the string at that point.
6164 Path Comparisons
6167 if(<variable|string> PATH_EQUAL <variable|string>)
6168 New in version 3.24.
6169 Compares the two paths component-by-component. Only if every
6172 component of both paths match will the two paths compare equal.
6173 Multiple path separators are effectively collapsed into a single
6174 separator, but note that backslashes are not converted to for‐
6175 ward slashes. No other path normalization is performed.
6176 Component-wise comparison is superior to string-based comparison
6178 due to the handling of multiple path separators. In the follow‐
6179 ing example, the expression evaluates to true using PATH_EQUAL,
6180 but false with STREQUAL:
6181 # comparison is TRUE
6183 if ("/a//b/c" PATH_EQUAL "/a/b/c")
6184 ...
6185 endif()
6186 # comparison is FALSE
6188 if ("/a//b/c" STREQUAL "/a/b/c")
6189 ...
6190 endif()
6191 See cmake_path(COMPARE) for more details.
6193 Variable Expansion
6195 The if command was written very early in CMake's history, predating the
6196 ${} variable evaluation syntax, and for convenience evaluates variables
6197 named by its arguments as shown in the above signatures. Note that
6198 normal variable evaluation with ${} applies before the if command even
6199 receives the arguments. Therefore code like
6200 set(var1 OFF)
6202 set(var2 "var1")
6203 if(${var2})
6204 appears to the if command as
6206 if(var1)
6208 and is evaluated according to the if(<variable>) case documented above.
6210 The result is OFF which is false. However, if we remove the ${} from
6211 the example then the command sees
6212 if(var2)
6214 which is true because var2 is defined to var1 which is not a false con‐
6216 stant.
6217 Automatic evaluation applies in the other cases whenever the above-doc‐
6219 umented condition syntax accepts <variable|string>:
6220 • The left hand argument to MATCHES is first checked to see if it is a
6222 defined variable, if so the variable's value is used, otherwise the
6223 original value is used.
6224 • If the left hand argument to MATCHES is missing it returns false
6226 without error
6227 • Both left and right hand arguments to LESS, GREATER, EQUAL,
6229 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
6230 they are defined variables, if so their defined values are used oth‐
6231 erwise the original value is used.
6232 • Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
6234 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
6235 if they are defined variables, if so their defined values are used
6236 otherwise the original value is used.
6237 • Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
6239 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are in‐
6240 dependently tested to see if they are defined variables, if so their
6241 defined values are used otherwise the original value is used.
6242 • The right hand argument to NOT is tested to see if it is a boolean
6244 constant, if so the value is used, otherwise it is assumed to be a
6245 variable and it is dereferenced.
6246 • The left and right hand arguments to AND and OR are independently
6248 tested to see if they are boolean constants, if so they are used as
6249 such, otherwise they are assumed to be variables and are derefer‐
6250 enced.
6251 Changed in version 3.1: To prevent ambiguity, potential variable or
6253 keyword names can be specified in a Quoted Argument or a Bracket Argu‐
6254 ment. A quoted or bracketed variable or keyword will be interpreted as
6255 a string and not dereferenced or interpreted. See policy CMP0054.
6256 There is no automatic evaluation for environment or cache Variable Ref‐
6259 erences. Their values must be referenced as $ENV{<name>} or
6260 $CACHE{<name>} wherever the above-documented condition syntax accepts
6261 <variable|string>.
6262 See also
6264 • else()
6265 • elseif()
6267 • endif()
6269 include
6271 Load and run CMake code from a file or module.
6272 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
6274 [NO_POLICY_SCOPE])
6275 Loads and runs CMake code from the file given. Variable reads and
6277 writes access the scope of the caller (dynamic scoping). If OPTIONAL
6278 is present, then no error is raised if the file does not exist. If RE‐
6279 SULT_VARIABLE is given the variable <var> will be set to the full file‐
6280 name which has been included or NOTFOUND if it failed.
6281 If a module is specified instead of a file, the file with name <module‐
6283 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
6284 module directory. There is one exception to this: if the file which
6285 calls include() is located itself in the CMake builtin module direc‐
6286 tory, then first the CMake builtin module directory is searched and
6287 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
6288 See the cmake_policy() command documentation for discussion of the
6290 NO_POLICY_SCOPE option.
6291 include_guard
6293 New in version 3.10.
6294 Provides an include guard for the file currently being processed by
6297 CMake.
6298 include_guard([DIRECTORY|GLOBAL])
6300 Sets up an include guard for the current CMake file (see the
6302 CMAKE_CURRENT_LIST_FILE variable documentation).
6303 CMake will end its processing of the current file at the location of
6305 the include_guard() command if the current file has already been pro‐
6306 cessed for the applicable scope (see below). This provides functional‐
6307 ity similar to the include guards commonly used in source headers or to
6308 the #pragma once directive. If the current file has been processed pre‐
6309 viously for the applicable scope, the effect is as though return() had
6310 been called. Do not call this command from inside a function being de‐
6311 fined within the current file.
6312 An optional argument specifying the scope of the guard may be provided.
6314 Possible values for the option are:
6315 DIRECTORY
6317 The include guard applies within the current directory and be‐
6318 low. The file will only be included once within this directory
6319 scope, but may be included again by other files outside of this
6320 directory (i.e. a parent directory or another directory not
6321 pulled in by add_subdirectory() or include() from the current
6322 file or its children).
6323 GLOBAL The include guard applies globally to the whole build. The cur‐
6325 rent file will only be included once regardless of the scope.
6326 If no arguments given, include_guard has the same scope as a variable,
6328 meaning that the include guard effect is isolated by the most recent
6329 function scope or current directory if no inner function scopes exist.
6330 In this case the command behavior is the same as:
6331 if(__CURRENT_FILE_VAR__)
6333 return()
6334 endif()
6335 set(__CURRENT_FILE_VAR__ TRUE)
6336 list
6338 List operations.
6339 Synopsis
6341 Reading
6342 list(LENGTH <list> <out-var>)
6343 list(GET <list> <element index> [<index> ...] <out-var>)
6344 list(JOIN <list> <glue> <out-var>)
6345 list(SUBLIST <list> <begin> <length> <out-var>)
6346 Search
6348 list(FIND <list> <value> <out-var>)
6349 Modification
6351 list(APPEND <list> [<element>...])
6352 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
6353 list(INSERT <list> <index> [<element>...])
6354 list(POP_BACK <list> [<out-var>...])
6355 list(POP_FRONT <list> [<out-var>...])
6356 list(PREPEND <list> [<element>...])
6357 list(REMOVE_ITEM <list> <value>...)
6358 list(REMOVE_AT <list> <index>...)
6359 list(REMOVE_DUPLICATES <list>)
6360 list(TRANSFORM <list> <ACTION> [...])
6361 Ordering
6363 list(REVERSE <list>)
6364 list(SORT <list> [...])
6365 Introduction
6367 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
6368 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
6369 may create new values for the list within the current CMake variable
6370 scope. Similar to the set() command, the LIST command creates new
6371 variable values in the current scope, even if the list itself is actu‐
6372 ally defined in a parent scope. To propagate the results of these op‐
6373 erations upwards, use set() with PARENT_SCOPE, set() with CACHE INTER‐
6374 NAL, or some other means of value propagation.
6375 NOTE:
6377 A list in cmake is a ; separated group of strings. To create a list
6378 the set command can be used. For example, set(var a b c d e) cre‐
6379 ates a list with a;b;c;d;e, and set(var "a b c d e") creates a
6380 string or a list with one item in it. (Note macro arguments are
6381 not variables, and therefore cannot be used in LIST commands.)
6382 NOTE:
6384 When specifying index values, if <element index> is 0 or greater, it
6385 is indexed from the beginning of the list, with 0 representing the
6386 first list element. If <element index> is -1 or lesser, it is in‐
6387 dexed from the end of the list, with -1 representing the last list
6388 element. Be careful when counting with negative indices: they do
6389 not start from 0. -0 is equivalent to 0, the first list element.
6390 Reading
6392 list(LENGTH <list> <output variable>)
6393 Returns the list's length.
6395 list(GET <list> <element index> [<element index> ...] <output variable>)
6397 Returns the list of elements specified by indices from the list.
6399 list(JOIN <list> <glue> <output variable>)
6401 New in version 3.12.
6403 Returns a string joining all list's elements using the glue string. To
6406 join multiple strings, which are not part of a list, use JOIN operator
6407 from string() command.
6408 list(SUBLIST <list> <begin> <length> <output variable>)
6410 New in version 3.12.
6412 Returns a sublist of the given list. If <length> is 0, an empty list
6415 will be returned. If <length> is -1 or the list is smaller than <be‐
6416 gin>+<length> then the remaining elements of the list starting at <be‐
6417 gin> will be returned.
6418 Search
6420 list(FIND <list> <value> <output variable>)
6421 Returns the index of the element specified in the list or -1 if it
6423 wasn't found.
6424 Modification
6426 list(APPEND <list> [<element> ...])
6427 Appends elements to the list. If no variable named <list> exists in the
6429 current scope its value is treated as empty and the elements are ap‐
6430 pended to that empty list.
6431 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
6433 New in version 3.6.
6435 Includes or removes items from the list that match the mode's pattern.
6438 In REGEX mode, items will be matched against the given regular expres‐
6439 sion.
6440 For more information on regular expressions look under string(REGEX).
6442 list(INSERT <list> <element_index> <element> [<element> ...])
6444 Inserts elements to the list to the specified index. It is an error to
6446 specify an out-of-range index. Valid indexes are 0 to N where N is the
6447 length of the list, inclusive. An empty list has length 0. If no vari‐
6448 able named <list> exists in the current scope its value is treated as
6449 empty and the elements are inserted in that empty list.
6450 list(POP_BACK <list> [<out-var>...])
6452 New in version 3.15.
6454 If no variable name is given, removes exactly one element. Otherwise,
6457 with N variable names provided, assign the last N elements' values to
6458 the given variables and then remove the last N values from <list>.
6459 list(POP_FRONT <list> [<out-var>...])
6461 New in version 3.15.
6463 If no variable name is given, removes exactly one element. Otherwise,
6466 with N variable names provided, assign the first N elements' values to
6467 the given variables and then remove the first N values from <list>.
6468 list(PREPEND <list> [<element> ...])
6470 New in version 3.15.
6472 Insert elements to the 0th position in the list. If no variable named
6475 <list> exists in the current scope its value is treated as empty and
6476 the elements are prepended to that empty list.
6477 list(REMOVE_ITEM <list> <value> [<value> ...])
6479 Removes all instances of the given items from the list.
6481 list(REMOVE_AT <list> <index> [<index> ...])
6483 Removes items at given indices from the list.
6485 list(REMOVE_DUPLICATES <list>)
6487 Removes duplicated items in the list. The relative order of items is
6489 preserved, but if duplicates are encountered, only the first instance
6490 is preserved.
6491 list(TRANSFORM <list> <ACTION> [<SELECTOR>]
6493 [OUTPUT_VARIABLE <output variable>])
6494 New in version 3.12.
6496 Transforms the list by applying an action to all or, by specifying a
6499 <SELECTOR>, to the selected elements of the list, storing the result
6500 in-place or in the specified output variable.
6501 NOTE:
6503 The TRANSFORM sub-command does not change the number of elements in
6504 the list. If a <SELECTOR> is specified, only some elements will be
6505 changed, the other ones will remain the same as before the transfor‐
6506 mation.
6507 <ACTION> specifies the action to apply to the elements of the list.
6509 The actions have exactly the same semantics as sub-commands of the
6510 string() command. <ACTION> must be one of the following:
6511 APPEND, PREPEND: Append, prepend specified value to each element of the
6513 list.
6514 list(TRANSFORM <list> <APPEND|PREPEND> <value> ...)
6516 TOUPPER, TOLOWER: Convert each element of the list to upper, lower
6518 characters.
6519 list(TRANSFORM <list> <TOLOWER|TOUPPER> ...)
6521 STRIP: Remove leading and trailing spaces from each element of the
6523 list.
6524 list(TRANSFORM <list> STRIP ...)
6526 GENEX_STRIP: Strip any generator expressions from each element of the
6528 list.
6529 list(TRANSFORM <list> GENEX_STRIP ...)
6531 REPLACE: Match the regular expression as many times as possible and
6533 substitute the replacement expression for the match for each element of
6534 the list (Same semantic as REGEX REPLACE from string() command).
6535 list(TRANSFORM <list> REPLACE <regular_expression>
6537 <replace_expression> ...)
6538 <SELECTOR> determines which elements of the list will be transformed.
6540 Only one type of selector can be specified at a time. When given, <SE‐
6541 LECTOR> must be one of the following:
6542 AT: Specify a list of indexes.
6544 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
6546 FOR: Specify a range with, optionally, an increment used to iterate
6548 over the range.
6549 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
6551 REGEX: Specify a regular expression. Only elements matching the regular
6553 expression will be transformed.
6554 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
6556 Ordering
6558 list(REVERSE <list>)
6559 Reverses the contents of the list in-place.
6561 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
6563 Sorts the list in-place alphabetically.
6565 New in version 3.13: Added the COMPARE, CASE, and ORDER options.
6567 New in version 3.18: Added the COMPARE NATURAL option.
6570 Use the COMPARE keyword to select the comparison method for sorting.
6573 The <compare> option should be one of:
6574 • STRING: Sorts a list of strings alphabetically. This is the default
6576 behavior if the COMPARE option is not given.
6577 • FILE_BASENAME: Sorts a list of pathnames of files by their basenames.
6579 • NATURAL: Sorts a list of strings using natural order (see strver‐
6581 scmp(3) manual), i.e. such that contiguous digits are compared as
6582 whole numbers. For example: the following list 10.0 1.1 2.1 8.0 2.0
6583 3.1 will be sorted as 1.1 2.0 2.1 3.1 8.0 10.0 if the NATURAL compar‐
6584 ison is selected where it will be sorted as 1.1 10.0 2.0 2.1 3.1 8.0
6585 with the STRING comparison.
6586 Use the CASE keyword to select a case sensitive or case insensitive
6588 sort mode. The <case> option should be one of:
6589 • SENSITIVE: List items are sorted in a case-sensitive manner. This is
6591 the default behavior if the CASE option is not given.
6592 • INSENSITIVE: List items are sorted case insensitively. The order of
6594 items which differ only by upper/lowercase is not specified.
6595 To control the sort order, the ORDER keyword can be given. The <order>
6597 option should be one of:
6598 • ASCENDING: Sorts the list in ascending order. This is the default
6600 behavior when the ORDER option is not given.
6601 • DESCENDING: Sorts the list in descending order.
6603 macro
6605 Start recording a macro for later invocation as a command
6606 macro(<name> [<arg1> ...])
6608 <commands>
6609 endmacro()
6610 Defines a macro named <name> that takes arguments named <arg1>, ...
6612 Commands listed after macro, but before the matching endmacro(), are
6613 not executed until the macro is invoked.
6614 Per legacy, the endmacro() command admits an optional <name> argument.
6616 If used, it must be a verbatim repeat of the argument of the opening
6617 macro command.
6618 See the cmake_policy() command documentation for the behavior of poli‐
6620 cies inside macros.
6621 See the Macro vs Function section below for differences between CMake
6623 macros and functions.
6624 Invocation
6626 The macro invocation is case-insensitive. A macro defined as
6627 macro(foo)
6629 <commands>
6630 endmacro()
6631 can be invoked through any of
6633 foo()
6635 Foo()
6636 FOO()
6637 cmake_language(CALL foo)
6638 and so on. However, it is strongly recommended to stay with the case
6640 chosen in the macro definition. Typically macros use all-lowercase
6641 names.
6642 New in version 3.18: The cmake_language(CALL ...) command can also be
6644 used to invoke the macro.
6645 Arguments
6648 When a macro is invoked, the commands recorded in the macro are first
6649 modified by replacing formal parameters (${arg1}, ...) with the argu‐
6650 ments passed, and then invoked as normal commands.
6651 In addition to referencing the formal parameters you can reference the
6653 values ${ARGC} which will be set to the number of arguments passed into
6654 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, ... which will
6655 have the actual values of the arguments passed in. This facilitates
6656 creating macros with optional arguments.
6657 Furthermore, ${ARGV} holds the list of all arguments given to the macro
6659 and ${ARGN} holds the list of arguments past the last expected argu‐
6660 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
6661 behavior. Checking that ${ARGC} is greater than # is the only way to
6662 ensure that ${ARGV#} was passed to the function as an extra argument.
6663 Macro vs Function
6665 The macro command is very similar to the function() command. Nonethe‐
6666 less, there are a few important differences.
6667 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, ... are true vari‐
6669 ables in the usual CMake sense. In a macro, they are not, they are
6670 string replacements much like the C preprocessor would do with a macro.
6671 This has a number of consequences, as explained in the Argument Caveats
6672 section below.
6673 Another difference between macros and functions is the control flow. A
6675 function is executed by transferring control from the calling statement
6676 to the function body. A macro is executed as if the macro body were
6677 pasted in place of the calling statement. This has the consequence
6678 that a return() in a macro body does not just terminate execution of
6679 the macro; rather, control is returned from the scope of the macro
6680 call. To avoid confusion, it is recommended to avoid return() in
6681 macros altogether.
6682 Unlike a function, the CMAKE_CURRENT_FUNCTION,
6684 CMAKE_CURRENT_FUNCTION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE,
6685 CMAKE_CURRENT_FUNCTION_LIST_LINE variables are not set for a macro.
6686 Argument Caveats
6688 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
6689 able to use commands like
6690 if(ARGV1) # ARGV1 is not a variable
6692 if(DEFINED ARGV2) # ARGV2 is not a variable
6693 if(ARGC GREATER 2) # ARGC is not a variable
6694 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
6695 In the first case, you can use if(${ARGV1}). In the second and third
6697 case, the proper way to check if an optional variable was passed to the
6698 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
6699 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
6700 need to include them, you can use
6701 set(list_var "${ARGN}")
6703 foreach(loop_var IN LISTS list_var)
6704 Note that if you have a variable with the same name in the scope from
6706 which the macro is called, using unreferenced names will use the exist‐
6707 ing variable instead of the arguments. For example:
6708 macro(bar)
6710 foreach(arg IN LISTS ARGN)
6711 <commands>
6712 endforeach()
6713 endmacro()
6714 function(foo)
6716 bar(x y z)
6717 endfunction()
6718 foo(a b c)
6720 Will loop over a;b;c and not over x;y;z as one might have expected. If
6722 you want true CMake variables and/or better CMake scope control you
6723 should look at the function command.
6724 mark_as_advanced
6726 Mark cmake cached variables as advanced.
6727 mark_as_advanced([CLEAR|FORCE] <var1> ...)
6729 Sets the advanced/non-advanced state of the named cached variables.
6731 An advanced variable will not be displayed in any of the cmake GUIs un‐
6733 less the show advanced option is on. In script mode, the ad‐
6734 vanced/non-advanced state has no effect.
6735 If the keyword CLEAR is given then advanced variables are changed back
6737 to unadvanced. If the keyword FORCE is given then the variables are
6738 made advanced. If neither FORCE nor CLEAR is specified, new values
6739 will be marked as advanced, but if a variable already has an ad‐
6740 vanced/non-advanced state, it will not be changed.
6741 Changed in version 3.17: Variables passed to this command which are not
6743 already in the cache are ignored. See policy CMP0102.
6744 math
6747 Evaluate a mathematical expression.
6748 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
6750 Evaluates a mathematical <expression> and sets <variable> to the re‐
6752 sulting value. The result of the expression must be representable as a
6753 64-bit signed integer.
6754 The mathematical expression must be given as a string (i.e. enclosed in
6756 double quotation marks). An example is "5 * (10 + 13)". Supported op‐
6757 erators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have the
6758 same meaning as in C code.
6759 New in version 3.13: Hexadecimal numbers are recognized when prefixed
6761 with 0x, as in C code.
6762 New in version 3.13: The result is formatted according to the option
6765 OUTPUT_FORMAT, where <format> is one of
6766 HEXADECIMAL
6768 Hexadecimal notation as in C code, i. e. starting with "0x".
6769 DECIMAL
6771 Decimal notation. Which is also used if no OUTPUT_FORMAT option
6772 is specified.
6773 For example
6776 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
6778 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
6779 message
6781 Log a message.
6782 Synopsis
6784 General messages
6785 message([<mode>] "message text" ...)
6786 Reporting checks
6788 message(<checkState> "message text" ...)
6789 General messages
6791 message([<mode>] "message text" ...)
6792 Record the specified message text in the log. If more than one message
6794 string is given, they are concatenated into a single message with no
6795 separator between the strings.
6796 The optional <mode> keyword determines the type of message, which in‐
6798 fluences the way the message is handled:
6799 FATAL_ERROR
6801 CMake Error, stop processing and generation.
6802 The cmake(1) executable will return a non-zero exit code.
6804 SEND_ERROR
6806 CMake Error, continue processing, but skip generation.
6807 WARNING
6809 CMake Warning, continue processing.
6810 AUTHOR_WARNING
6812 CMake Warning (dev), continue processing.
6813 DEPRECATION
6815 CMake Deprecation Error or Warning if variable
6816 CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED is enabled, re‐
6817 spectively, else no message.
6818 (none) or NOTICE
6820 Important message printed to stderr to attract user's attention.
6821 STATUS The main interesting messages that project users might be inter‐
6823 ested in. Ideally these should be concise, no more than a sin‐
6824 gle line, but still informative.
6825 VERBOSE
6827 Detailed informational messages intended for project users.
6828 These messages should provide additional details that won't be
6829 of interest in most cases, but which may be useful to those
6830 building the project when they want deeper insight into what's
6831 happening.
6832 DEBUG Detailed informational messages intended for developers working
6834 on the project itself as opposed to users who just want to build
6835 it. These messages will not typically be of interest to other
6836 users building the project and will often be closely related to
6837 internal implementation details.
6838 TRACE Fine-grained messages with very low-level implementation de‐
6840 tails. Messages using this log level would normally only be
6841 temporary and would expect to be removed before releasing the
6842 project, packaging up the files, etc.
6843 New in version 3.15: Added the NOTICE, VERBOSE, DEBUG, and TRACE lev‐
6845 els.
6846 The CMake command-line tool displays STATUS to TRACE messages on stdout
6849 with the message preceded by two hyphens and a space. All other mes‐
6850 sage types are sent to stderr and are not prefixed with hyphens. The
6851 CMake GUI displays all messages in its log area. The curses interface
6852 shows STATUS to TRACE messages one at a time on a status line and other
6853 messages in an interactive pop-up box. The --log-level command-line
6854 option to each of these tools can be used to control which messages
6855 will be shown.
6856 New in version 3.17: To make a log level persist between CMake runs,
6858 the CMAKE_MESSAGE_LOG_LEVEL variable can be set instead. Note that the
6859 command line option takes precedence over the cache variable.
6860 New in version 3.16: Messages of log levels NOTICE and below will have
6863 each line preceded by the content of the CMAKE_MESSAGE_INDENT variable
6864 (converted to a single string by concatenating its list items). For
6865 STATUS to TRACE messages, this indenting content will be inserted after
6866 the hyphens.
6867 New in version 3.17: Messages of log levels NOTICE and below can also
6870 have each line preceded with context of the form [some.context.exam‐
6871 ple]. The content between the square brackets is obtained by convert‐
6872 ing the CMAKE_MESSAGE_CONTEXT list variable to a dot-separated string.
6873 The message context will always appear before any indenting content but
6874 after any automatically added leading hyphens. By default, message con‐
6875 text is not shown, it has to be explicitly enabled by giving the cmake
6876 --log-context command-line option or by setting the
6877 CMAKE_MESSAGE_CONTEXT_SHOW variable to true. See the
6878 CMAKE_MESSAGE_CONTEXT documentation for usage examples.
6879 CMake Warning and Error message text displays using a simple markup
6882 language. Non-indented text is formatted in line-wrapped paragraphs
6883 delimited by newlines. Indented text is considered pre-formatted.
6884 Reporting checks
6886 New in version 3.17.
6887 A common pattern in CMake output is a message indicating the start of
6890 some sort of check, followed by another message reporting the result of
6891 that check. For example:
6892 message(STATUS "Looking for someheader.h")
6894 #... do the checks, set checkSuccess with the result
6895 if(checkSuccess)
6896 message(STATUS "Looking for someheader.h - found")
6897 else()
6898 message(STATUS "Looking for someheader.h - not found")
6899 endif()
6900 This can be more robustly and conveniently expressed using the
6902 CHECK_... keyword form of the message() command:
6903 message(<checkState> "message" ...)
6905 where <checkState> must be one of the following:
6907 CHECK_START
6909 Record a concise message about the check about to be per‐
6910 formed.
6911 CHECK_PASS
6913 Record a successful result for a check.
6914 CHECK_FAIL
6916 Record an unsuccessful result for a check.
6917 When recording a check result, the command repeats the message from the
6919 most recently started check for which no result has yet been reported,
6920 then some separator characters and then the message text provided after
6921 the CHECK_PASS or CHECK_FAIL keyword. Check messages are always re‐
6922 ported at STATUS log level.
6923 Checks may be nested and every CHECK_START should have exactly one
6925 matching CHECK_PASS or CHECK_FAIL. The CMAKE_MESSAGE_INDENT variable
6926 can also be used to add indenting to nested checks if desired. For ex‐
6927 ample:
6928 message(CHECK_START "Finding my things")
6930 list(APPEND CMAKE_MESSAGE_INDENT " ")
6931 unset(missingComponents)
6932 message(CHECK_START "Finding partA")
6934 # ... do check, assume we find A
6935 message(CHECK_PASS "found")
6936 message(CHECK_START "Finding partB")
6938 # ... do check, assume we don't find B
6939 list(APPEND missingComponents B)
6940 message(CHECK_FAIL "not found")
6941 list(POP_BACK CMAKE_MESSAGE_INDENT)
6943 if(missingComponents)
6944 message(CHECK_FAIL "missing components: ${missingComponents}")
6945 else()
6946 message(CHECK_PASS "all components found")
6947 endif()
6948 Output from the above would appear something like the following:
6950 -- Finding my things
6952 -- Finding partA
6953 -- Finding partA - found
6954 -- Finding partB
6955 -- Finding partB - not found
6956 -- Finding my things - missing components: B
6957 option
6959 Provide a boolean option that the user can optionally select.
6960 option(<variable> "<help_text>" [value])
6962 If no initial <value> is provided, boolean OFF is the default value.
6964 If <variable> is already set as a normal or cache variable, then the
6965 command does nothing (see policy CMP0077).
6966 For options that depend on the values of other options, see the module
6968 help for CMakeDependentOption.
6969 In CMake project mode, a boolean cache variable is created with the op‐
6971 tion value. In CMake script mode, a boolean variable is set with the
6972 option value.
6973 return
6975 Return from a file, directory or function.
6976 return([PROPAGATE <var-name>...])
6978 When this command is encountered in an included file (via include() or
6980 find_package()), it causes processing of the current file to stop and
6981 control is returned to the including file. If it is encountered in a
6982 file which is not included by another file, e.g. a CMakeLists.txt, de‐
6983 ferred calls scheduled by cmake_language(DEFER) are invoked and control
6984 is returned to the parent directory if there is one.
6985 If return() is called in a function, control is returned to the caller
6987 of that function. Note that a macro(), unlike a function(), is ex‐
6988 panded in place and therefore cannot handle return().
6989 Policy CMP0140 controls the behavior regarding the arguments of the
6991 command. All arguments are ignored unless that policy is set to NEW.
6992 PROPAGATE
6994 New in version 3.25.
6995 This option sets or unsets the specified variables in the parent
6998 directory or function caller scope. This is equivalent to
6999 set(PARENT_SCOPE) or unset(PARENT_SCOPE) commands, except for
7000 the way it interacts with the block() command, as described be‐
7001 low.
7002 The PROPAGATE option can be very useful in conjunction with the
7004 block() command. A return() will propagate the specified vari‐
7005 ables through any enclosing block scopes created by the block()
7006 commands. Inside a function, this ensures the variables are
7007 propagated to the function's caller, regardless of any blocks
7008 within the function. If not inside a function, it ensures the
7009 variables are propagated to the parent file or directory scope.
7010 For example:
7011 CMakeLists.txt
7013 cmake_version_required(VERSION 3.25)
7015 project(example)
7016 set(var1 "top-value")
7018 block(SCOPE_FOR VARIABLES)
7020 add_subdirectory(subDir)
7021 # var1 has the value "block-nested"
7022 endblock()
7023 # var1 has the value "top-value"
7025 subDir/CMakeLists.txt
7027 function(multi_scopes result_var1 result_var2)
7029 block(SCOPE_FOR VARIABLES)
7030 # This would only propagate out of the immediate block, not to
7031 # the caller of the function.
7032 #set(${result_var1} "new-value" PARENT_SCOPE)
7033 #unset(${result_var2} PARENT_SCOPE)
7034 # This propagates the variables through the enclosing block and
7036 # out to the caller of the function.
7037 set(${result_var1} "new-value")
7038 unset(${result_var2})
7039 return(PROPAGATE ${result_var1} ${result_var2})
7040 endblock()
7041 endfunction()
7042 set(var1 "some-value")
7044 set(var2 "another-value")
7045 multi_scopes(var1 var2)
7047 # Now var1 will hold "new-value" and var2 will be unset
7048 block(SCOPE_FOR VARIABLES)
7050 # This return() will set var1 in the directory scope that included us
7051 # via add_subdirectory(). The surrounding block() here does not limit
7052 # propagation to the current file, but the block() in the parent
7053 # directory scope does prevent propagation going any further.
7054 set(var1 "block-nested")
7055 return(PROPAGATE var1)
7056 endblock()
7057 See Also
7059 • block()
7060 separate_arguments
7062 Parse command-line arguments into a semicolon-separated list.
7063 separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)
7065 Parses a space-separated string <args> into a list of items, and stores
7067 this list in semicolon-separated standard form in <variable>.
7068 This function is intended for parsing command-line arguments. The en‐
7070 tire command line must be passed as one string in the argument <args>.
7071 The exact parsing rules depend on the operating system. They are spec‐
7073 ified by the <mode> argument which must be one of the following key‐
7074 words:
7075 UNIX_COMMAND
7077 Arguments are separated by unquoted whitespace. Both sin‐
7078 gle-quote and double-quote pairs are respected. A backslash es‐
7079 capes the next literal character (\" is "); there are no special
7080 escapes (\n is just n).
7081 WINDOWS_COMMAND
7083 A Windows command-line is parsed using the same syntax the run‐
7084 time library uses to construct argv at startup. It separates
7085 arguments by whitespace that is not double-quoted. Backslashes
7086 are literal unless they precede double-quotes. See the MSDN ar‐
7087 ticle Parsing C Command-Line Arguments for details.
7088 NATIVE_COMMAND
7090 New in version 3.9.
7091 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
7094 dows. Otherwise proceeds as in UNIX_COMMAND mode.
7095 PROGRAM
7097 New in version 3.19.
7098 The first item in <args> is assumed to be an executable and will
7101 be searched in the system search path or left as a full path. If
7102 not found, <variable> will be empty. Otherwise, <variable> is a
7103 list of 2 elements:
7104 0. Absolute path of the program
7106 1. Any command-line arguments present in <args> as a string
7108 For example:
7110 separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")
7112 • First element of the list: /path/to/cc
7114 • Second element of the list: " -c main.c"
7116 SEPARATE_ARGS
7118 When this sub-option of PROGRAM option is specified, com‐
7119 mand-line arguments will be split as well and stored in <vari‐
7120 able>.
7121 For example:
7123 separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")
7125 The contents of out will be: /path/to/cc;-c;main.c
7127 separate_arguments(<var>)
7129 Convert the value of <var> to a semi-colon separated list. All spaces
7131 are replaced with ';'. This helps with generating command lines.
7132 set
7134 Set a normal, cache, or environment variable to a given value. See the
7135 cmake-language(7) variables documentation for the scopes and interac‐
7136 tion of normal variables and cache entries.
7137 Signatures of this command that specify a <value>... placeholder expect
7139 zero or more arguments. Multiple arguments will be joined as a
7140 semicolon-separated list to form the actual variable value to be set.
7141 Zero arguments will cause normal variables to be unset. See the
7142 unset() command to unset variables explicitly.
7143 Set Normal Variable
7145 set(<variable> <value>... [PARENT_SCOPE])
7146 Sets the given <variable> in the current function or directory scope.
7148 If the PARENT_SCOPE option is given the variable will be set in the
7150 scope above the current scope. Each new directory or function() com‐
7151 mand creates a new scope. A scope can also be created with the block()
7152 command. This command will set the value of a variable into the parent
7153 directory, calling function or encompassing scope (whichever is appli‐
7154 cable to the case at hand). The previous state of the variable's value
7155 stays the same in the current scope (e.g., if it was undefined before,
7156 it is still undefined and if it had a value, it is still that value).
7157 The block(PROPAGATE) and return(PROPAGATE) commands can be used as an
7159 alternate method to the set(PARENT_SCOPE) and unset(PARENT_SCOPE) com‐
7160 mands to update the parent scope.
7161 Set Cache Entry
7163 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
7164 Sets the given cache <variable> (cache entry). Since cache entries are
7166 meant to provide user-settable values this does not overwrite existing
7167 cache entries by default. Use the FORCE option to overwrite existing
7168 entries.
7169 The <type> must be specified as one of:
7171 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
7173 FILEPATH
7175 Path to a file on disk. cmake-gui(1) offers a file dialog.
7176 PATH Path to a directory on disk. cmake-gui(1) offers a file dialog.
7178 STRING A line of text. cmake-gui(1) offers a text field or a drop-down
7180 selection if the STRINGS cache entry property is set.
7181 INTERNAL
7183 A line of text. cmake-gui(1) does not show internal entries.
7184 They may be used to store variables persistently across runs.
7185 Use of this type implies FORCE.
7186 The <docstring> must be specified as a line of text providing a quick
7188 summary of the option for presentation to cmake-gui(1) users.
7189 If the cache entry does not exist prior to the call or the FORCE option
7191 is given then the cache entry will be set to the given value.
7192 NOTE:
7194 The content of the cache variable will not be directly accessible if
7195 a normal variable of the same name already exists (see rules of
7196 variable evaluation). If policy CMP0126 is set to OLD, any normal
7197 variable binding in the current scope will be removed.
7198 It is possible for the cache entry to exist prior to the call but have
7200 no type set if it was created on the cmake(1) command line by a user
7201 through the -D<var>=<value> option without specifying a type. In this
7202 case the set command will add the type. Furthermore, if the <type> is
7203 PATH or FILEPATH and the <value> provided on the command line is a rel‐
7204 ative path, then the set command will treat the path as relative to the
7205 current working directory and convert it to an absolute path.
7206 Set Environment Variable
7208 set(ENV{<variable>} [<value>])
7209 Sets an Environment Variable to the given value. Subsequent calls of
7211 $ENV{<variable>} will return this new value.
7212 This command affects only the current CMake process, not the process
7214 from which CMake was called, nor the system environment at large, nor
7215 the environment of subsequent build or test processes.
7216 If no argument is given after ENV{<variable>} or if <value> is an empty
7218 string, then this command will clear any existing value of the environ‐
7219 ment variable.
7220 Arguments after <value> are ignored. If extra arguments are found, then
7222 an author warning is issued.
7223 set_directory_properties
7225 Set properties of the current directory and subdirectories.
7226 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
7228 Sets properties of the current directory and its subdirectories in
7230 key-value pairs.
7231 See also the set_property(DIRECTORY) command.
7233 See Properties on Directories for the list of properties known to CMake
7235 and their individual documentation for the behavior of each property.
7236 set_property
7238 Set a named property in a given scope.
7239 set_property(<GLOBAL |
7241 DIRECTORY [<dir>] |
7242 TARGET [<target1> ...] |
7243 SOURCE [<src1> ...]
7244 [DIRECTORY <dirs> ...]
7245 [TARGET_DIRECTORY <targets> ...] |
7246 INSTALL [<file1> ...] |
7247 TEST [<test1> ...] |
7248 CACHE [<entry1> ...] >
7249 [APPEND] [APPEND_STRING]
7250 PROPERTY <name> [<value1> ...])
7251 Sets one property on zero or more objects of a scope.
7253 The first argument determines the scope in which the property is set.
7255 It must be one of the following:
7256 GLOBAL Scope is unique and does not accept a name.
7258 DIRECTORY
7260 Scope defaults to the current directory but other directories
7261 (already processed by CMake) may be named by full or relative
7262 path. Relative paths are treated as relative to the current
7263 source directory. See also the set_directory_properties() com‐
7264 mand.
7265 New in version 3.19: <dir> may reference a binary directory.
7267 TARGET Scope may name zero or more existing targets. See also the
7270 set_target_properties() command.
7271 SOURCE Scope may name zero or more source files. By default, source
7273 file properties are only visible to targets added in the same
7274 directory (CMakeLists.txt).
7275 New in version 3.18: Visibility can be set in other directory
7277 scopes using one or both of the following sub-options:
7278 DIRECTORY <dirs>...
7280 The source file property will be set in each of the
7281 <dirs> directories' scopes. CMake must already know
7282 about each of these directories, either by having added
7283 them through a call to add_subdirectory() or it being the
7284 top level source directory. Relative paths are treated
7285 as relative to the current source directory.
7286 New in version 3.19: <dirs> may reference a binary direc‐
7288 tory.
7289 TARGET_DIRECTORY <targets>...
7292 The source file property will be set in each of the di‐
7293 rectory scopes where any of the specified <targets> were
7294 created (the <targets> must therefore already exist).
7295 See also the set_source_files_properties() command.
7298 INSTALL
7300 New in version 3.1.
7301 Scope may name zero or more installed file paths. These are
7304 made available to CPack to influence deployment.
7305 Both the property key and value may use generator expressions.
7307 Specific properties may apply to installed files and/or directo‐
7308 ries.
7309 Path components have to be separated by forward slashes, must be
7311 normalized and are case sensitive.
7312 To reference the installation prefix itself with a relative path
7314 use ..
7315 Currently installed file properties are only defined for the WIX
7317 generator where the given paths are relative to the installation
7318 prefix.
7319 TEST Scope may name zero or more existing tests. See also the
7321 set_tests_properties() command.
7322 Test property values may be specified using generator expres‐
7324 sions for tests created by the add_test(NAME) signature.
7325 CACHE Scope must name zero or more cache existing entries.
7327 The required PROPERTY option is immediately followed by the name of the
7329 property to set. Remaining arguments are used to compose the property
7330 value in the form of a semicolon-separated list.
7331 If the APPEND option is given the list is appended to any existing
7333 property value (except that empty values are ignored and not appended).
7334 If the APPEND_STRING option is given the string is appended to any ex‐
7335 isting property value as string, i.e. it results in a longer string and
7336 not a list of strings. When using APPEND or APPEND_STRING with a prop‐
7337 erty defined to support INHERITED behavior (see define_property()), no
7338 inheriting occurs when finding the initial value to append to. If the
7339 property is not already directly set in the nominated scope, the com‐
7340 mand will behave as though APPEND or APPEND_STRING had not been given.
7341 See the cmake-properties(7) manual for a list of properties in each
7343 scope.
7344 NOTE:
7346 The GENERATED source file property may be globally visible. See its
7347 documentation for details.
7348 site_name
7350 Set the given variable to the name of the computer.
7351 site_name(variable)
7353 On UNIX-like platforms, if the variable HOSTNAME is set, its value will
7355 be executed as a command expected to print out the host name, much like
7356 the hostname command-line tool.
7357 string
7359 String operations.
7360 Synopsis
7362 Search and Replace
7363 string(FIND <string> <substring> <out-var> [...])
7364 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
7365 string(REGEX MATCH <match-regex> <out-var> <input>...)
7366 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
7367 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
7368 Manipulation
7370 string(APPEND <string-var> [<input>...])
7371 string(PREPEND <string-var> [<input>...])
7372 string(CONCAT <out-var> [<input>...])
7373 string(JOIN <glue> <out-var> [<input>...])
7374 string(TOLOWER <string> <out-var>)
7375 string(TOUPPER <string> <out-var>)
7376 string(LENGTH <string> <out-var>)
7377 string(SUBSTRING <string> <begin> <length> <out-var>)
7378 string(STRIP <string> <out-var>)
7379 string(GENEX_STRIP <string> <out-var>)
7380 string(REPEAT <string> <count> <out-var>)
7381 Comparison
7383 string(COMPARE <op> <string1> <string2> <out-var>)
7384 Hashing
7386 string(<HASH> <out-var> <input>)
7387 Generation
7389 string(ASCII <number>... <out-var>)
7390 string(HEX <string> <out-var>)
7391 string(CONFIGURE <string> <out-var> [...])
7392 string(MAKE_C_IDENTIFIER <string> <out-var>)
7393 string(RANDOM [<option>...] <out-var>)
7394 string(TIMESTAMP <out-var> [<format string>] [UTC])
7395 string(UUID <out-var> ...)
7396 JSON
7398 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7399 {GET | TYPE | LENGTH | REMOVE}
7400 <json-string> <member|index> [<member|index> ...])
7401 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7402 MEMBER <json-string>
7403 [<member|index> ...] <index>)
7404 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7405 SET <json-string>
7406 <member|index> [<member|index> ...] <value>)
7407 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7408 EQUAL <json-string1> <json-string2>)
7409 Search and Replace
7411 Search and Replace With Plain Strings
7412 string(FIND <string> <substring> <output_variable> [REVERSE])
7413 Return the position where the given <substring> was found in the sup‐
7415 plied <string>. If the REVERSE flag was used, the command will search
7416 for the position of the last occurrence of the specified <substring>.
7417 If the <substring> is not found, a position of -1 is returned.
7418 The string(FIND) subcommand treats all strings as ASCII-only charac‐
7420 ters. The index stored in <output_variable> will also be counted in
7421 bytes, so strings containing multi-byte characters may lead to unex‐
7422 pected results.
7423 string(REPLACE <match_string>
7425 <replace_string> <output_variable>
7426 <input> [<input>...])
7427 Replace all occurrences of <match_string> in the <input> with <re‐
7429 place_string> and store the result in the <output_variable>.
7430 Search and Replace With Regular Expressions
7432 string(REGEX MATCH <regular_expression>
7433 <output_variable> <input> [<input>...])
7434 Match the <regular_expression> once and store the match in the <out‐
7436 put_variable>. All <input> arguments are concatenated before matching.
7437 Regular expressions are specified in the subsection just below.
7438 string(REGEX MATCHALL <regular_expression>
7440 <output_variable> <input> [<input>...])
7441 Match the <regular_expression> as many times as possible and store the
7443 matches in the <output_variable> as a list. All <input> arguments are
7444 concatenated before matching.
7445 string(REGEX REPLACE <regular_expression>
7447 <replacement_expression> <output_variable>
7448 <input> [<input>...])
7449 Match the <regular_expression> as many times as possible and substitute
7451 the <replacement_expression> for the match in the output. All <input>
7452 arguments are concatenated before matching.
7453 The <replacement_expression> may refer to parenthesis-delimited subex‐
7455 pressions of the match using \1, \2, ..., \9. Note that two back‐
7456 slashes (\\1) are required in CMake code to get a backslash through ar‐
7457 gument parsing.
7458 Regex Specification
7460 The following characters have special meaning in regular expressions:
7461 ^ Matches at beginning of input
7463 $ Matches at end of input
7465 . Matches any single character
7467 \<char>
7469 Matches the single character specified by <char>. Use this to
7470 match special regex characters, e.g. \. for a literal . or \\
7471 for a literal backslash \. Escaping a non-special character is
7472 unnecessary but allowed, e.g. \a matches a.
7473 [ ] Matches any character(s) inside the brackets
7475 [^ ] Matches any character(s) not inside the brackets
7477 - Inside brackets, specifies an inclusive range between characters
7479 on either side e.g. [a-f] is [abcdef] To match a literal - using
7480 brackets, make it the first or the last character e.g. [+*/-]
7481 matches basic mathematical operators.
7482 * Matches preceding pattern zero or more times
7484 + Matches preceding pattern one or more times
7486 ? Matches preceding pattern zero or once only
7488 | Matches a pattern on either side of the |
7490 () Saves a matched subexpression, which can be referenced in the
7492 REGEX REPLACE operation.
7493 New in version 3.9: All regular expression-related commands, in‐
7495 cluding e.g. if(MATCHES), save subgroup matches in the vari‐
7496 ables CMAKE_MATCH_<n> for <n> 0..9.
7497 *, + and ? have higher precedence than concatenation. | has lower
7500 precedence than concatenation. This means that the regular expression
7501 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
7502 matches ab but not abd.
7503 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
7505 to construct literal tabs, carriage returns, newlines, and backslashes
7506 (respectively) to pass in a regex. For example:
7507 • The quoted argument "[ \t\r\n]" specifies a regex that matches any
7509 single whitespace character.
7510 • The quoted argument "[/\\]" specifies a regex that matches a single
7512 forward slash / or backslash \.
7513 • The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
7515 single "word" character in the C locale.
7516 • The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
7518 the exact string (a+b). Each \\ is parsed in a quoted argument as
7519 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
7520 natively be specified in a Bracket Argument without having to escape
7521 the backslashes, e.g. [[\(\a\+\b\)]].
7522 Manipulation
7524 string(APPEND <string_variable> [<input>...])
7525 New in version 3.4.
7527 Append all the <input> arguments to the string.
7530 string(PREPEND <string_variable> [<input>...])
7532 New in version 3.10.
7534 Prepend all the <input> arguments to the string.
7537 string(CONCAT <output_variable> [<input>...])
7539 Concatenate all the <input> arguments together and store the result in
7541 the named <output_variable>.
7542 string(JOIN <glue> <output_variable> [<input>...])
7544 New in version 3.12.
7546 Join all the <input> arguments together using the <glue> string and
7549 store the result in the named <output_variable>.
7550 To join a list's elements, prefer to use the JOIN operator from the
7552 list() command. This allows for the elements to have special charac‐
7553 ters like ; in them.
7554 string(TOLOWER <string> <output_variable>)
7556 Convert <string> to lower characters.
7558 string(TOUPPER <string> <output_variable>)
7560 Convert <string> to upper characters.
7562 string(LENGTH <string> <output_variable>)
7564 Store in an <output_variable> a given string's length in bytes. Note
7566 that this means if <string> contains multi-byte characters, the result
7567 stored in <output_variable> will not be the number of characters.
7568 string(SUBSTRING <string> <begin> <length> <output_variable>)
7570 Store in an <output_variable> a substring of a given <string>. If
7572 <length> is -1 the remainder of the string starting at <begin> will be
7573 returned.
7574 Changed in version 3.2: If <string> is shorter than <length> then the
7576 end of the string is used instead. Previous versions of CMake reported
7577 an error in this case.
7578 Both <begin> and <length> are counted in bytes, so care must be exer‐
7581 cised if <string> could contain multi-byte characters.
7582 string(STRIP <string> <output_variable>)
7584 Store in an <output_variable> a substring of a given <string> with
7586 leading and trailing spaces removed.
7587 string(GENEX_STRIP <string> <output_variable>)
7589 New in version 3.1.
7591 Strip any generator expressions from the input <string> and store the
7594 result in the <output_variable>.
7595 string(REPEAT <string> <count> <output_variable>)
7597 New in version 3.15.
7599 Produce the output string as the input <string> repeated <count> times.
7602 Comparison
7604 string(COMPARE LESS <string1> <string2> <output_variable>)
7605 string(COMPARE GREATER <string1> <string2> <output_variable>)
7606 string(COMPARE EQUAL <string1> <string2> <output_variable>)
7607 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
7608 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
7609 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
7610 Compare the strings and store true or false in the <output_variable>.
7612 New in version 3.7: Added the LESS_EQUAL and GREATER_EQUAL options.
7614 Hashing
7617 string(<HASH> <output_variable> <input>)
7618 Compute a cryptographic hash of the <input> string. The supported
7620 <HASH> algorithm names are:
7621 MD5 Message-Digest Algorithm 5, RFC 1321.
7623 SHA1 US Secure Hash Algorithm 1, RFC 3174.
7625 SHA224 US Secure Hash Algorithms, RFC 4634.
7627 SHA256 US Secure Hash Algorithms, RFC 4634.
7629 SHA384 US Secure Hash Algorithms, RFC 4634.
7631 SHA512 US Secure Hash Algorithms, RFC 4634.
7633 SHA3_224
7635 Keccak SHA-3.
7636 SHA3_256
7638 Keccak SHA-3.
7639 SHA3_384
7641 Keccak SHA-3.
7642 SHA3_512
7644 Keccak SHA-3.
7645 New in version 3.8: Added the SHA3_* hash algorithms.
7647 Generation
7650 string(ASCII <number> [<number> ...] <output_variable>)
7651 Convert all numbers into corresponding ASCII characters.
7653 string(HEX <string> <output_variable>)
7655 New in version 3.18.
7657 Convert each byte in the input <string> to its hexadecimal representa‐
7660 tion and store the concatenated hex digits in the <output_variable>.
7661 Letters in the output (a through f) are in lowercase.
7662 string(CONFIGURE <string> <output_variable>
7664 [@ONLY] [ESCAPE_QUOTES])
7665 Transform a <string> like configure_file() transforms a file.
7667 string(MAKE_C_IDENTIFIER <string> <output_variable>)
7669 Convert each non-alphanumeric character in the input <string> to an un‐
7671 derscore and store the result in the <output_variable>. If the first
7672 character of the <string> is a digit, an underscore will also be
7673 prepended to the result.
7674 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
7676 [RANDOM_SEED <seed>] <output_variable>)
7677 Return a random string of given <length> consisting of characters from
7679 the given <alphabet>. Default length is 5 characters and default al‐
7680 phabet is all numbers and upper and lower case letters. If an integer
7681 RANDOM_SEED is given, its value will be used to seed the random number
7682 generator.
7683 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
7685 Write a string representation of the current date and/or time to the
7687 <output_variable>.
7688 If the command is unable to obtain a timestamp, the <output_variable>
7690 will be set to the empty string "".
7691 The optional UTC flag requests the current date/time representation to
7693 be in Coordinated Universal Time (UTC) rather than local time.
7694 The optional <format_string> may contain the following format speci‐
7696 fiers:
7697 %% New in version 3.8.
7699 A literal percent sign (%).
7702 %d The day of the current month (01-31).
7704 %H The hour on a 24-hour clock (00-23).
7706 %I The hour on a 12-hour clock (01-12).
7708 %j The day of the current year (001-366).
7710 %m The month of the current year (01-12).
7712 %b New in version 3.7.
7714 Abbreviated month name (e.g. Oct).
7717 %B New in version 3.10.
7719 Full month name (e.g. October).
7722 %M The minute of the current hour (00-59).
7724 %s New in version 3.6.
7726 Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
7729 %S The second of the current minute. 60 represents a leap second.
7731 (00-60)
7732 %f New in version 3.23.
7734 The microsecond of the current second (000000-999999).
7737 %U The week number of the current year (00-53).
7739 %V New in version 3.22.
7741 The ISO 8601 week number of the current year (01-53).
7744 %w The day of the current week. 0 is Sunday. (0-6)
7746 %a New in version 3.7.
7748 Abbreviated weekday name (e.g. Fri).
7751 %A New in version 3.10.
7753 Full weekday name (e.g. Friday).
7756 %y The last two digits of the current year (00-99).
7758 %Y The current year.
7760 Unknown format specifiers will be ignored and copied to the output
7762 as-is.
7763 If no explicit <format_string> is given, it will default to:
7765 %Y-%m-%dT%H:%M:%S for local time.
7767 %Y-%m-%dT%H:%M:%SZ for UTC.
7768 New in version 3.8: If the SOURCE_DATE_EPOCH environment variable is
7770 set, its value will be used instead of the current time. See
7771 https://reproducible-builds.org/specs/source-date-epoch/ for details.
7772 string(UUID <output_variable> NAMESPACE <namespace> NAME <name>
7775 TYPE <MD5|SHA1> [UPPER])
7776 New in version 3.1.
7778 Create a universally unique identifier (aka GUID) as per RFC4122 based
7781 on the hash of the combined values of <namespace> (which itself has to
7782 be a valid UUID) and <name>. The hash algorithm can be either MD5
7783 (Version 3 UUID) or SHA1 (Version 5 UUID). A UUID has the format
7784 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where each x represents a lower
7785 case hexadecimal character. Where required, an uppercase representa‐
7786 tion can be requested with the optional UPPER flag.
7787 JSON
7789 New in version 3.19.
7790 Functionality for querying a JSON string.
7793 NOTE:
7795 In each of the following JSON-related subcommands, if the optional
7796 ERROR_VARIABLE argument is given, errors will be reported in <er‐
7797 ror-variable> and the <out-var> will be set to <member|index>-[<mem‐
7798 ber|index>...]-NOTFOUND with the path elements up to the point where
7799 the error occurred, or just NOTFOUND if there is no relevant path.
7800 If an error occurs but the ERROR_VARIABLE option is not present, a
7801 fatal error message is generated. If no error occurs, the <er‐
7802 ror-variable> will be set to NOTFOUND.
7803 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
7805 GET <json-string> <member|index> [<member|index> ...])
7806 Get an element from <json-string> at the location given by the list of
7808 <member|index> arguments. Array and object elements will be returned
7809 as a JSON string. Boolean elements will be returned as ON or OFF.
7810 Null elements will be returned as an empty string. Number and string
7811 types will be returned as strings.
7812 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
7814 TYPE <json-string> <member|index> [<member|index> ...])
7815 Get the type of an element in <json-string> at the location given by
7817 the list of <member|index> arguments. The <out-var> will be set to one
7818 of NULL, NUMBER, STRING, BOOLEAN, ARRAY, or OBJECT.
7819 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7821 MEMBER <json-string>
7822 [<member|index> ...] <index>)
7823 Get the name of the <index>-th member in <json-string> at the location
7825 given by the list of <member|index> arguments. Requires an element of
7826 object type.
7827 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
7829 LENGTH <json-string> [<member|index> ...])
7830 Get the length of an element in <json-string> at the location given by
7832 the list of <member|index> arguments. Requires an element of array or
7833 object type.
7834 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
7836 REMOVE <json-string> <member|index> [<member|index> ...])
7837 Remove an element from <json-string> at the location given by the list
7839 of <member|index> arguments. The JSON string without the removed ele‐
7840 ment will be stored in <out-var>.
7841 string(JSON <out-var> [ERROR_VARIABLE <error-variable>]
7843 SET <json-string> <member|index> [<member|index> ...] <value>)
7844 Set an element in <json-string> at the location given by the list of
7846 <member|index> arguments to <value>. The contents of <value> should be
7847 valid JSON.
7848 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7850 EQUAL <json-string1> <json-string2>)
7851 Compare the two JSON objects given by <json-string1> and <json-string2>
7853 for equality. The contents of <json-string1> and <json-string2> should
7854 be valid JSON. The <out-var> will be set to a true value if the JSON
7855 objects are considered equal, or a false value otherwise.
7856 unset
7858 Unset a variable, cache variable, or environment variable.
7859 Unset Normal Variable or Cache Entry
7861 unset(<variable> [CACHE | PARENT_SCOPE])
7862 Removes a normal variable from the current scope, causing it to become
7864 undefined. If CACHE is present, then a cache variable is removed in‐
7865 stead of a normal variable. Note that when evaluating Variable Refer‐
7866 ences of the form ${VAR}, CMake first searches for a normal variable
7867 with that name. If no such normal variable exists, CMake will then
7868 search for a cache entry with that name. Because of this unsetting a
7869 normal variable can expose a cache variable that was previously hidden.
7870 To force a variable reference of the form ${VAR} to return an empty
7871 string, use set(<variable> ""), which clears the normal variable but
7872 leaves it defined.
7873 If PARENT_SCOPE is present then the variable is removed from the scope
7875 above the current scope. See the same option in the set() command for
7876 further details.
7877 Unset Environment Variable
7879 unset(ENV{<variable>})
7880 Removes <variable> from the currently available Environment Variables.
7882 Subsequent calls of $ENV{<variable>} will return the empty string.
7883 This command affects only the current CMake process, not the process
7885 from which CMake was called, nor the system environment at large, nor
7886 the environment of subsequent build or test processes.
7887 variable_watch
7889 Watch the CMake variable for change.
7890 variable_watch(<variable> [<command>])
7892 If the specified <variable> changes and no <command> is given, a mes‐
7894 sage will be printed to inform about the change.
7895 If <command> is given, this command will be executed instead. The com‐
7897 mand will receive the following arguments: COMMAND(<variable> <access>
7898 <value> <current_list_file> <stack>)
7899 <variable>
7901 Name of the variable being accessed.
7902 <access>
7904 One of READ_ACCESS, UNKNOWN_READ_ACCESS, MODIFIED_ACCESS, UN‐
7905 KNOWN_MODIFIED_ACCESS, or REMOVED_ACCESS. The UNKNOWN_ values
7906 are only used when the variable has never been set. Once set,
7907 they are never used again during the same CMake run, even if the
7908 variable is later unset.
7909 <value>
7911 The value of the variable. On a modification, this is the new
7912 (modified) value of the variable. On removal, the value is
7913 empty.
7914 <current_list_file>
7916 Full path to the file doing the access.
7917 <stack>
7919 List of absolute paths of all files currently on the stack of
7920 file inclusion, with the bottom-most file first and the cur‐
7921 rently processed file (that is, current_list_file) last.
7922 Note that for some accesses such as list(APPEND), the watcher is exe‐
7924 cuted twice, first with a read access and then with a write one. Also
7925 note that an if(DEFINED) query on the variable does not register as an
7926 access and the watcher is not executed.
7927 Only non-cache variables can be watched using this command. Access to
7929 cache variables is never watched. However, the existence of a cache
7930 variable var causes accesses to the non-cache variable var to not use
7931 the UNKNOWN_ prefix, even if a non-cache variable var has never ex‐
7932 isted.
7933 while
7935 Evaluate a group of commands while a condition is true
7936 while(<condition>)
7938 <commands>
7939 endwhile()
7940 All commands between while and the matching endwhile() are recorded
7942 without being invoked. Once the endwhile() is evaluated, the recorded
7943 list of commands is invoked as long as the <condition> is true.
7944 The <condition> has the same syntax and is evaluated using the same
7946 logic as described at length for the if() command.
7947 The commands break() and continue() provide means to escape from the
7949 normal control flow.
7950 Per legacy, the endwhile() command admits an optional <condition> argu‐
7952 ment. If used, it must be a verbatim repeat of the argument of the
7953 opening while command.
7954 See Also
7956 • break()
7957 • continue()
7959 • foreach()
7961 • endwhile()
7963
7965 These commands are available only in CMake projects.
7966 add_compile_definitions
7968 New in version 3.12.
7969 Add preprocessor definitions to the compilation of source files.
7972 add_compile_definitions(<definition> ...)
7974 Adds preprocessor definitions to the compiler command line.
7976 The preprocessor definitions are added to the COMPILE_DEFINITIONS di‐
7978 rectory property for the current CMakeLists file. They are also added
7979 to the COMPILE_DEFINITIONS target property for each target in the cur‐
7980 rent CMakeLists file.
7981 Definitions are specified using the syntax VAR or VAR=value. Func‐
7983 tion-style definitions are not supported. CMake will automatically es‐
7984 cape the value correctly for the native build system (note that CMake
7985 language syntax may require escapes to specify some values).
7986 Arguments to add_compile_definitions may use "generator expressions"
7988 with the syntax $<...>. See the cmake-generator-expressions(7) manual
7989 for available expressions. See the cmake-buildsystem(7) manual for
7990 more on defining buildsystem properties.
7991 add_compile_options
7993 Add options to the compilation of source files.
7994 add_compile_options(<option> ...)
7996 Adds options to the COMPILE_OPTIONS directory property. These options
7998 are used when compiling targets from the current directory and below.
7999 Arguments
8001 Arguments to add_compile_options may use "generator expressions" with
8002 the syntax $<...>. See the cmake-generator-expressions(7) manual for
8003 available expressions. See the cmake-buildsystem(7) manual for more on
8004 defining buildsystem properties.
8005 Option De-duplication
8007 The final set of options used for a target is constructed by accumulat‐
8008 ing options from the current target and the usage requirements of its
8009 dependencies. The set of options is de-duplicated to avoid repetition.
8010 New in version 3.12: While beneficial for individual options, the
8012 de-duplication step can break up option groups. For example, -option A
8013 -option B becomes -option A B. One may specify a group of options us‐
8014 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
8015 is dropped, and the rest of the option string is parsed using the
8016 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
8017 "SHELL:-option B" becomes -option A -option B.
8018 Example
8021 Since different compilers support different options, a typical use of
8022 this command is in a compiler-specific conditional clause:
8023 if (MSVC)
8025 # warning level 4 and all warnings as errors
8026 add_compile_options(/W4 /WX)
8027 else()
8028 # lots of warnings and all warnings as errors
8029 add_compile_options(-Wall -Wextra -pedantic -Werror)
8030 endif()
8031 See Also
8033 This command can be used to add any options. However, for adding pre‐
8034 processor definitions and include directories it is recommended to use
8035 the more specific commands add_compile_definitions() and
8036 include_directories().
8037 The command target_compile_options() adds target-specific options.
8039 The source file property COMPILE_OPTIONS adds options to one source
8041 file.
8042 add_custom_command
8044 Add a custom build rule to the generated build system.
8045 There are two main signatures for add_custom_command.
8047 Generating Files
8049 The first signature is for adding a custom command to produce an out‐
8050 put:
8051 add_custom_command(OUTPUT output1 [output2 ...]
8053 COMMAND command1 [ARGS] [args1...]
8054 [COMMAND command2 [ARGS] [args2...] ...]
8055 [MAIN_DEPENDENCY depend]
8056 [DEPENDS [depends...]]
8057 [BYPRODUCTS [files...]]
8058 [IMPLICIT_DEPENDS <lang1> depend1
8059 [<lang2> depend2] ...]
8060 [WORKING_DIRECTORY dir]
8061 [COMMENT comment]
8062 [DEPFILE depfile]
8063 [JOB_POOL job_pool]
8064 [VERBATIM] [APPEND] [USES_TERMINAL]
8065 [COMMAND_EXPAND_LISTS])
8066 This defines a command to generate specified OUTPUT file(s). A target
8068 created in the same directory (CMakeLists.txt file) that specifies any
8069 output of the custom command as a source file is given a rule to gener‐
8070 ate the file using the command at build time. Do not list the output
8071 in more than one independent target that may build in parallel or the
8072 two instances of the rule may conflict (instead use the
8073 add_custom_target() command to drive the command and make the other
8074 targets depend on that one). In makefile terms this creates a new tar‐
8075 get in the following form:
8076 OUTPUT: MAIN_DEPENDENCY DEPENDS
8078 COMMAND
8079 The options are:
8081 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
8083 mand for the first output specified. There must have already
8084 been a previous call to this command with the same output.
8085 If the previous call specified the output via a generator ex‐
8087 pression, the output specified by the current call must match in
8088 at least one configuration after evaluating generator expres‐
8089 sions. In this case, the appended commands and dependencies ap‐
8090 ply to all configurations.
8091 The COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are
8093 currently ignored when APPEND is given, but may be used in the
8094 future.
8095 BYPRODUCTS
8097 New in version 3.2.
8098 Specify the files the command is expected to produce but whose
8101 modification time may or may not be newer than the dependencies.
8102 If a byproduct name is a relative path it will be interpreted
8103 relative to the build tree directory corresponding to the cur‐
8104 rent source directory. Each byproduct file will be marked with
8105 the GENERATED source file property automatically.
8106 See policy CMP0058 for the motivation behind this feature.
8108 Explicit specification of byproducts is supported by the Ninja
8110 generator to tell the ninja build tool how to regenerate byprod‐
8111 ucts when they are missing. It is also useful when other build
8112 rules (e.g. custom commands) depend on the byproducts. Ninja
8113 requires a build rule for any generated file on which another
8114 rule depends even if there are order-only dependencies to ensure
8115 the byproducts will be available before their dependents build.
8116 The Makefile Generators will remove BYPRODUCTS and other
8118 GENERATED files during make clean.
8119 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
8121 stricted set of generator expressions. Target-dependent expres‐
8122 sions are not permitted.
8123 COMMAND
8126 Specify the command-line(s) to execute at build time. If more
8127 than one COMMAND is specified they will be executed in order,
8128 but not necessarily composed into a stateful shell or batch
8129 script. (To run a full script, use the configure_file() command
8130 or the file(GENERATE) command to create it, and then specify a
8131 COMMAND to launch it.) The optional ARGS argument is for back‐
8132 ward compatibility and will be ignored.
8133 If COMMAND specifies an executable target name (created by the
8135 add_executable() command), it will automatically be replaced by
8136 the location of the executable created at build time if either
8137 of the following is true:
8138 • The target is not being cross-compiled (i.e. the
8140 CMAKE_CROSSCOMPILING variable is not set to true).
8141 • New in version 3.6: The target is being cross-compiled and an
8143 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
8144 property is set). In this case, the contents of
8145 CROSSCOMPILING_EMULATOR will be prepended to the command be‐
8146 fore the location of the target executable.
8147 If neither of the above conditions are met, it is assumed that
8150 the command name is a program to be found on the PATH at build
8151 time.
8152 Arguments to COMMAND may use generator expressions. Use the
8154 TARGET_FILE generator expression to refer to the location of a
8155 target later in the command line (i.e. as a command argument
8156 rather than as the command to execute).
8157 Whenever one of the following target based generator expressions
8159 are used as a command to execute or is mentioned in a command
8160 argument, a target-level dependency will be added automatically
8161 so that the mentioned target will be built before any target us‐
8162 ing this custom command (see policy CMP0112).
8163 • TARGET_FILE
8165 • TARGET_LINKER_FILE
8167 • TARGET_SONAME_FILE
8169 • TARGET_PDB_FILE
8171 This target-level dependency does NOT add a file-level depen‐
8173 dency that would cause the custom command to re-run whenever the
8174 executable is recompiled. List target names with the DEPENDS
8175 option to add such file-level dependencies.
8176 COMMENT
8178 Display the given message before the commands are executed at
8179 build time.
8180 DEPENDS
8182 Specify files on which the command depends. Each argument is
8183 converted to a dependency as follows:
8184 1. If the argument is the name of a target (created by the
8186 add_custom_target(), add_executable(), or add_library() com‐
8187 mand) a target-level dependency is created to make sure the
8188 target is built before any target using this custom command.
8189 Additionally, if the target is an executable or library, a
8190 file-level dependency is created to cause the custom command
8191 to re-run whenever the target is recompiled.
8192 2. If the argument is an absolute path, a file-level dependency
8194 is created on that path.
8195 3. If the argument is the name of a source file that has been
8197 added to a target or on which a source file property has been
8198 set, a file-level dependency is created on that source file.
8199 4. If the argument is a relative path and it exists in the cur‐
8201 rent source directory, a file-level dependency is created on
8202 that file in the current source directory.
8203 5. Otherwise, a file-level dependency is created on that path
8205 relative to the current binary directory.
8206 If any dependency is an OUTPUT of another custom command in the
8208 same directory (CMakeLists.txt file), CMake automatically brings
8209 the other custom command into the target in which this command
8210 is built.
8211 New in version 3.16: A target-level dependency is added if any
8213 dependency is listed as BYPRODUCTS of a target or any of its
8214 build events in the same directory to ensure the byproducts will
8215 be available.
8216 If DEPENDS is not specified, the command will run whenever the
8219 OUTPUT is missing; if the command does not actually create the
8220 OUTPUT, the rule will always run.
8221 New in version 3.1: Arguments to DEPENDS may use generator ex‐
8223 pressions.
8224 COMMAND_EXPAND_LISTS
8227 New in version 3.8.
8228 Lists in COMMAND arguments will be expanded, including those
8231 created with generator expressions, allowing COMMAND arguments
8232 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
8233 RIES>,;-I>" foo.cc to be properly expanded.
8234 IMPLICIT_DEPENDS
8236 Request scanning of implicit dependencies of an input file. The
8237 language given specifies the programming language whose corre‐
8238 sponding dependency scanner should be used. Currently only C
8239 and CXX language scanners are supported. The language has to be
8240 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
8241 dencies discovered from the scanning are added to those of the
8242 custom command at build time. Note that the IMPLICIT_DEPENDS
8243 option is currently supported only for Makefile generators and
8244 will be ignored by other generators.
8245 NOTE:
8247 This option cannot be specified at the same time as DEPFILE
8248 option.
8249 JOB_POOL
8251 New in version 3.15.
8252 Specify a pool for the Ninja generator. Incompatible with
8255 USES_TERMINAL, which implies the console pool. Using a pool
8256 that is not defined by JOB_POOLS causes an error by ninja at
8257 build time.
8258 MAIN_DEPENDENCY
8260 Specify the primary input source file to the command. This is
8261 treated just like any value given to the DEPENDS option but also
8262 suggests to Visual Studio generators where to hang the custom
8263 command. Each source file may have at most one command specify‐
8264 ing it as its main dependency. A compile command (i.e. for a li‐
8265 brary or an executable) counts as an implicit main dependency
8266 which gets silently overwritten by a custom command specifica‐
8267 tion.
8268 OUTPUT Specify the output files the command is expected to produce. If
8270 an output name is a relative path it will be interpreted rela‐
8271 tive to the build tree directory corresponding to the current
8272 source directory. Each output file will be marked with the
8273 GENERATED source file property automatically. If the output of
8274 the custom command is not actually created as a file on disk it
8275 should be marked with the SYMBOLIC source file property.
8276 New in version 3.20: Arguments to OUTPUT may use a restricted
8278 set of generator expressions. Target-dependent expressions are
8279 not permitted.
8280 USES_TERMINAL
8283 New in version 3.2.
8284 The command will be given direct access to the terminal if pos‐
8287 sible. With the Ninja generator, this places the command in the
8288 console pool.
8289 VERBATIM
8291 All arguments to the commands will be escaped properly for the
8292 build tool so that the invoked command receives each argument
8293 unchanged. Note that one level of escapes is still used by the
8294 CMake language processor before add_custom_command even sees the
8295 arguments. Use of VERBATIM is recommended as it enables correct
8296 behavior. When VERBATIM is not given the behavior is platform
8297 specific because there is no protection of tool-specific special
8298 characters.
8299 WORKING_DIRECTORY
8301 Execute the command with the given current working directory.
8302 If it is a relative path it will be interpreted relative to the
8303 build tree directory corresponding to the current source direc‐
8304 tory.
8305 New in version 3.13: Arguments to WORKING_DIRECTORY may use
8307 generator expressions.
8308 DEPFILE
8311 New in version 3.7.
8312 Specify a depfile which holds dependencies for the custom com‐
8315 mand. It is usually emitted by the custom command itself. This
8316 keyword may only be used if the generator supports it, as de‐
8317 tailed below.
8318 The expected format, compatible with what is generated by gcc
8320 with the option -M, is independent of the generator or platform.
8321 The formal syntax, as specified using BNF notation with the reg‐
8323 ular extensions, is the following:
8324 depfile ::= rule*
8326 rule ::= targets (':' (separator dependencies?)?)? eol
8327 targets ::= target (separator target)* separator*
8328 target ::= pathname
8329 dependencies ::= dependency (separator dependency)* separator*
8330 dependency ::= pathname
8331 separator ::= (space | line_continue)+
8332 line_continue ::= '\' eol
8333 space ::= ' ' | '\t'
8334 pathname ::= character+
8335 character ::= std_character | dollar | hash | whitespace
8336 std_character ::= <any character except '$', '#' or ' '>
8337 dollar ::= '$$'
8338 hash ::= '\#'
8339 whitespace ::= '\ '
8340 eol ::= '\r'? '\n'
8341 NOTE:
8344 As part of pathname, any slash and backslash is interpreted
8345 as a directory separator.
8346 New in version 3.7: The Ninja generator supports DEPFILE since
8348 the keyword was first added.
8349 New in version 3.17: Added the Ninja Multi-Config generator,
8352 which included support for the DEPFILE keyword.
8353 New in version 3.20: Added support for Makefile Generators.
8356 NOTE:
8358 DEPFILE cannot be specified at the same time as the IM‐
8359 PLICIT_DEPENDS option for Makefile Generators.
8360 New in version 3.21: Added support for Visual Studio Generators
8363 with VS 2012 and above, and for the Xcode generator. Support
8364 for generator expressions was also added.
8365 Using DEPFILE with generators other than those listed above is
8368 an error.
8369 If the DEPFILE argument is relative, it should be relative to
8371 CMAKE_CURRENT_BINARY_DIR, and any relative paths inside the DEP‐
8372 FILE should also be relative to CMAKE_CURRENT_BINARY_DIR. See
8373 policy CMP0116, which is always NEW for Makefile Generators,
8374 Visual Studio Generators, and the Xcode generator.
8375 Examples: Generating Files
8377 Custom commands may be used to generate source files. For example, the
8378 code:
8379 add_custom_command(
8381 OUTPUT out.c
8382 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8383 -o out.c
8384 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8385 VERBATIM)
8386 add_library(myLib out.c)
8387 adds a custom command to run someTool to generate out.c and then com‐
8389 pile the generated source as part of a library. The generation rule
8390 will re-run whenever in.txt changes.
8391 New in version 3.20: One may use generator expressions to specify
8393 per-configuration outputs. For example, the code:
8394 add_custom_command(
8396 OUTPUT "out-$<CONFIG>.c"
8397 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8398 -o "out-$<CONFIG>.c"
8399 -c "$<CONFIG>"
8400 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8401 VERBATIM)
8402 add_library(myLib "out-$<CONFIG>.c")
8403 adds a custom command to run someTool to generate out-<config>.c, where
8405 <config> is the build configuration, and then compile the generated
8406 source as part of a library.
8407 Build Events
8410 The second signature adds a custom command to a target such as a li‐
8411 brary or executable. This is useful for performing an operation before
8412 or after building the target. The command becomes part of the target
8413 and will only execute when the target itself is built. If the target
8414 is already built, the command will not execute.
8415 add_custom_command(TARGET <target>
8417 PRE_BUILD | PRE_LINK | POST_BUILD
8418 COMMAND command1 [ARGS] [args1...]
8419 [COMMAND command2 [ARGS] [args2...] ...]
8420 [BYPRODUCTS [files...]]
8421 [WORKING_DIRECTORY dir]
8422 [COMMENT comment]
8423 [VERBATIM] [USES_TERMINAL]
8424 [COMMAND_EXPAND_LISTS])
8425 This defines a new command that will be associated with building the
8427 specified <target>. The <target> must be defined in the current direc‐
8428 tory; targets defined in other directories may not be specified.
8429 When the command will happen is determined by which of the following is
8431 specified:
8432 PRE_BUILD
8434 On Visual Studio Generators, run before any other rules are exe‐
8435 cuted within the target. On other generators, run just before
8436 PRE_LINK commands.
8437 PRE_LINK
8439 Run after sources have been compiled but before linking the bi‐
8440 nary or running the librarian or archiver tool of a static li‐
8441 brary. This is not defined for targets created by the
8442 add_custom_target() command.
8443 POST_BUILD
8445 Run after all other rules within the target have been executed.
8446 Projects should always specify one of the above three keywords when us‐
8448 ing the TARGET form. For backward compatibility reasons, POST_BUILD is
8449 assumed if no such keyword is given, but projects should explicitly
8450 provide one of the keywords to make clear the behavior they expect.
8451 NOTE:
8453 Because generator expressions can be used in custom commands, it is
8454 possible to define COMMAND lines or whole custom commands which
8455 evaluate to empty strings for certain configurations. For Visual
8456 Studio 11 2012 (and newer) generators these command lines or custom
8457 commands will be omitted for the specific configuration and no
8458 "empty-string-command" will be added.
8459 This allows to add individual build events for every configuration.
8461 New in version 3.21: Support for target-dependent generator expres‐
8463 sions.
8464 Examples: Build Events
8467 A POST_BUILD event may be used to post-process a binary after linking.
8468 For example, the code:
8469 add_executable(myExe myExe.c)
8471 add_custom_command(
8472 TARGET myExe POST_BUILD
8473 COMMAND someHasher -i "$<TARGET_FILE:myExe>"
8474 -o "$<TARGET_FILE:myExe>.hash"
8475 VERBATIM)
8476 will run someHasher to produce a .hash file next to the executable af‐
8478 ter linking.
8479 New in version 3.20: One may use generator expressions to specify
8481 per-configuration byproducts. For example, the code:
8482 add_library(myPlugin MODULE myPlugin.c)
8484 add_custom_command(
8485 TARGET myPlugin POST_BUILD
8486 COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
8487 --as-code "myPlugin-hash-$<CONFIG>.c"
8488 BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
8489 VERBATIM)
8490 add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
8491 will run someHasher after linking myPlugin, e.g. to produce a .c file
8493 containing code to check the hash of myPlugin that the myExe executable
8494 can use to verify it before loading.
8495 Ninja Multi-Config
8498 New in version 3.20: add_custom_command supports the Ninja Multi-Config
8499 generator's cross-config capabilities. See the generator documentation
8500 for more information.
8501 add_custom_target
8504 Add a target with no output so it will always be built.
8505 add_custom_target(Name [ALL] [command1 [args1...]]
8507 [COMMAND command2 [args2...] ...]
8508 [DEPENDS depend depend depend ... ]
8509 [BYPRODUCTS [files...]]
8510 [WORKING_DIRECTORY dir]
8511 [COMMENT comment]
8512 [JOB_POOL job_pool]
8513 [VERBATIM] [USES_TERMINAL]
8514 [COMMAND_EXPAND_LISTS]
8515 [SOURCES src1 [src2...]])
8516 Adds a target with the given name that executes the given commands.
8518 The target has no output file and is always considered out of date even
8519 if the commands try to create a file with the name of the target. Use
8520 the add_custom_command() command to generate a file with dependencies.
8521 By default nothing depends on the custom target. Use the
8522 add_dependencies() command to add dependencies to or from other tar‐
8523 gets.
8524 The options are:
8526 ALL Indicate that this target should be added to the default build
8528 target so that it will be run every time (the command cannot be
8529 called ALL).
8530 BYPRODUCTS
8532 New in version 3.2.
8533 Specify the files the command is expected to produce but whose
8536 modification time may or may not be updated on subsequent
8537 builds. If a byproduct name is a relative path it will be in‐
8538 terpreted relative to the build tree directory corresponding to
8539 the current source directory. Each byproduct file will be
8540 marked with the GENERATED source file property automatically.
8541 See policy CMP0058 for the motivation behind this feature.
8543 Explicit specification of byproducts is supported by the Ninja
8545 generator to tell the ninja build tool how to regenerate byprod‐
8546 ucts when they are missing. It is also useful when other build
8547 rules (e.g. custom commands) depend on the byproducts. Ninja
8548 requires a build rule for any generated file on which another
8549 rule depends even if there are order-only dependencies to ensure
8550 the byproducts will be available before their dependents build.
8551 The Makefile Generators will remove BYPRODUCTS and other
8553 GENERATED files during make clean.
8554 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
8556 stricted set of generator expressions. Target-dependent expres‐
8557 sions are not permitted.
8558 COMMAND
8561 Specify the command-line(s) to execute at build time. If more
8562 than one COMMAND is specified they will be executed in order,
8563 but not necessarily composed into a stateful shell or batch
8564 script. (To run a full script, use the configure_file() command
8565 or the file(GENERATE) command to create it, and then specify a
8566 COMMAND to launch it.)
8567 If COMMAND specifies an executable target name (created by the
8569 add_executable() command), it will automatically be replaced by
8570 the location of the executable created at build time if either
8571 of the following is true:
8572 • The target is not being cross-compiled (i.e. the
8574 CMAKE_CROSSCOMPILING variable is not set to true).
8575 • New in version 3.6: The target is being cross-compiled and an
8577 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
8578 property is set). In this case, the contents of
8579 CROSSCOMPILING_EMULATOR will be prepended to the command be‐
8580 fore the location of the target executable.
8581 If neither of the above conditions are met, it is assumed that
8584 the command name is a program to be found on the PATH at build
8585 time.
8586 Arguments to COMMAND may use generator expressions. Use the
8588 TARGET_FILE generator expression to refer to the location of a
8589 target later in the command line (i.e. as a command argument
8590 rather than as the command to execute).
8591 Whenever one of the following target based generator expressions
8593 are used as a command to execute or is mentioned in a command
8594 argument, a target-level dependency will be added automatically
8595 so that the mentioned target will be built before this custom
8596 target (see policy CMP0112).
8597 • TARGET_FILE
8599 • TARGET_LINKER_FILE
8601 • TARGET_SONAME_FILE
8603 • TARGET_PDB_FILE
8605 The command and arguments are optional and if not specified an
8607 empty target will be created.
8608 COMMENT
8610 Display the given message before the commands are executed at
8611 build time.
8612 DEPENDS
8614 Reference files and outputs of custom commands created with
8615 add_custom_command() command calls in the same directory (CMake‐
8616 Lists.txt file). They will be brought up to date when the tar‐
8617 get is built.
8618 Changed in version 3.16: A target-level dependency is added if
8620 any dependency is a byproduct of a target or any of its build
8621 events in the same directory to ensure the byproducts will be
8622 available before this target is built.
8623 Use the add_dependencies() command to add dependencies on other
8626 targets.
8627 COMMAND_EXPAND_LISTS
8629 New in version 3.8.
8630 Lists in COMMAND arguments will be expanded, including those
8633 created with generator expressions, allowing COMMAND arguments
8634 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
8635 RIES>,;-I>" foo.cc to be properly expanded.
8636 JOB_POOL
8638 New in version 3.15.
8639 Specify a pool for the Ninja generator. Incompatible with
8642 USES_TERMINAL, which implies the console pool. Using a pool
8643 that is not defined by JOB_POOLS causes an error by ninja at
8644 build time.
8645 SOURCES
8647 Specify additional source files to be included in the custom
8648 target. Specified source files will be added to IDE project
8649 files for convenience in editing even if they have no build
8650 rules.
8651 VERBATIM
8653 All arguments to the commands will be escaped properly for the
8654 build tool so that the invoked command receives each argument
8655 unchanged. Note that one level of escapes is still used by the
8656 CMake language processor before add_custom_target even sees the
8657 arguments. Use of VERBATIM is recommended as it enables correct
8658 behavior. When VERBATIM is not given the behavior is platform
8659 specific because there is no protection of tool-specific special
8660 characters.
8661 USES_TERMINAL
8663 New in version 3.2.
8664 The command will be given direct access to the terminal if pos‐
8667 sible. With the Ninja generator, this places the command in the
8668 console pool.
8669 WORKING_DIRECTORY
8671 Execute the command with the given current working directory.
8672 If it is a relative path it will be interpreted relative to the
8673 build tree directory corresponding to the current source direc‐
8674 tory.
8675 New in version 3.13: Arguments to WORKING_DIRECTORY may use
8677 generator expressions.
8678 Ninja Multi-Config
8681 New in version 3.20: add_custom_target supports the Ninja Multi-Config
8682 generator's cross-config capabilities. See the generator documentation
8683 for more information.
8684 add_definitions
8687 Add -D define flags to the compilation of source files.
8688 add_definitions(-DFOO -DBAR ...)
8690 Adds definitions to the compiler command line for targets in the cur‐
8692 rent directory, whether added before or after this command is invoked,
8693 and for the ones in sub-directories added after. This command can be
8694 used to add any flags, but it is intended to add preprocessor defini‐
8695 tions.
8696 NOTE:
8698 This command has been superseded by alternatives:
8699 • Use add_compile_definitions() to add preprocessor definitions.
8701 • Use include_directories() to add include directories.
8703 • Use add_compile_options() to add other options.
8705 Flags beginning in -D or /D that look like preprocessor definitions are
8707 automatically added to the COMPILE_DEFINITIONS directory property for
8708 the current directory. Definitions with non-trivial values may be left
8709 in the set of flags instead of being converted for reasons of backwards
8710 compatibility. See documentation of the directory, target, source file
8711 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
8712 nitions to specific scopes and configurations.
8713 See the cmake-buildsystem(7) manual for more on defining buildsystem
8715 properties.
8716 add_dependencies
8718 Add a dependency between top-level targets.
8719 add_dependencies(<target> [<target-dependency>]...)
8721 Makes a top-level <target> depend on other top-level targets to ensure
8723 that they build before <target> does. A top-level target is one cre‐
8724 ated by one of the add_executable(), add_library(), or
8725 add_custom_target() commands (but not targets generated by CMake like
8726 install).
8727 Dependencies added to an imported target or an interface library are
8729 followed transitively in its place since the target itself does not
8730 build.
8731 New in version 3.3: Allow adding dependencies to interface libraries.
8733 See the DEPENDS option of add_custom_target() and add_custom_command()
8736 commands for adding file-level dependencies in custom rules. See the
8737 OBJECT_DEPENDS source file property to add file-level dependencies to
8738 object files.
8739 add_executable
8741 Add an executable to the project using the specified source files.
8742 Normal Executables
8744 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
8745 [EXCLUDE_FROM_ALL]
8746 [source1] [source2 ...])
8747 Adds an executable target called <name> to be built from the source
8749 files listed in the command invocation. The <name> corresponds to the
8750 logical target name and must be globally unique within a project. The
8751 actual file name of the executable built is constructed based on con‐
8752 ventions of the native platform (such as <name>.exe or just <name>).
8753 New in version 3.1: Source arguments to add_executable may use "genera‐
8755 tor expressions" with the syntax $<...>. See the
8756 cmake-generator-expressions(7) manual for available expressions.
8757 New in version 3.11: The source files can be omitted if they are added
8760 later using target_sources().
8761 By default the executable file will be created in the build tree direc‐
8764 tory corresponding to the source tree directory in which the command
8765 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
8766 property to change this location. See documentation of the OUTPUT_NAME
8767 target property to change the <name> part of the final file name.
8768 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
8770 get created. See documentation of that target property for details.
8771 If MACOSX_BUNDLE is given the corresponding property will be set on the
8773 created target. See documentation of the MACOSX_BUNDLE target property
8774 for details.
8775 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
8777 the created target. See documentation of the EXCLUDE_FROM_ALL target
8778 property for details.
8779 See the cmake-buildsystem(7) manual for more on defining buildsystem
8781 properties.
8782 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
8784 cessed, and you want to have the original sources reachable from within
8785 IDE.
8786 Imported Executables
8788 add_executable(<name> IMPORTED [GLOBAL])
8789 An IMPORTED executable target references an executable file located
8791 outside the project. No rules are generated to build it, and the
8792 IMPORTED target property is True. The target name has scope in the di‐
8793 rectory in which it is created and below, but the GLOBAL option extends
8794 visibility. It may be referenced like any target built within the
8795 project. IMPORTED executables are useful for convenient reference from
8796 commands like add_custom_command(). Details about the imported exe‐
8797 cutable are specified by setting properties whose names begin in IM‐
8798 PORTED_. The most important such property is IMPORTED_LOCATION (and
8799 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
8800 fies the location of the main executable file on disk. See documenta‐
8801 tion of the IMPORTED_* properties for more information.
8802 Alias Executables
8804 add_executable(<name> ALIAS <target>)
8805 Creates an Alias Target, such that <name> can be used to refer to <tar‐
8807 get> in subsequent commands. The <name> does not appear in the gener‐
8808 ated buildsystem as a make target. The <target> may not be an ALIAS.
8809 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
8811 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
8814 Such alias is scoped to the directory in which it is created and subdi‐
8815 rectories. The ALIAS_GLOBAL target property can be used to check if
8816 the alias is global or not.
8817 ALIAS targets can be used as targets to read properties from, executa‐
8820 bles for custom commands and custom targets. They can also be tested
8821 for existence with the regular if(TARGET) subcommand. The <name> may
8822 not be used to modify properties of <target>, that is, it may not be
8823 used as the operand of set_property(), set_target_properties(),
8824 target_link_libraries() etc. An ALIAS target may not be installed or
8825 exported.
8826 add_library
8828 Add a library to the project using the specified source files.
8829 Normal Libraries
8831 add_library(<name> [STATIC | SHARED | MODULE]
8832 [EXCLUDE_FROM_ALL]
8833 [<source>...])
8834 Adds a library target called <name> to be built from the source files
8836 listed in the command invocation. The <name> corresponds to the logi‐
8837 cal target name and must be globally unique within a project. The ac‐
8838 tual file name of the library built is constructed based on conventions
8839 of the native platform (such as lib<name>.a or <name>.lib).
8840 New in version 3.1: Source arguments to add_library may use "generator
8842 expressions" with the syntax $<...>. See the
8843 cmake-generator-expressions(7) manual for available expressions.
8844 New in version 3.11: The source files can be omitted if they are added
8847 later using target_sources().
8848 STATIC, SHARED, or MODULE may be given to specify the type of library
8851 to be created. STATIC libraries are archives of object files for use
8852 when linking other targets. SHARED libraries are linked dynamically
8853 and loaded at runtime. MODULE libraries are plugins that are not
8854 linked into other targets but may be loaded dynamically at runtime us‐
8855 ing dlopen-like functionality. If no type is given explicitly the type
8856 is STATIC or SHARED based on whether the current value of the variable
8857 BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the
8858 POSITION_INDEPENDENT_CODE target property is set to ON automatically.
8859 A SHARED library may be marked with the FRAMEWORK target property to
8860 create an macOS Framework.
8861 New in version 3.8: A STATIC library may be marked with the FRAMEWORK
8863 target property to create a static Framework.
8864 If a library does not export any symbols, it must not be declared as a
8867 SHARED library. For example, a Windows resource DLL or a managed
8868 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
8869 library. This is because CMake expects a SHARED library to always have
8870 an associated import library on Windows.
8871 By default the library file will be created in the build tree directory
8873 corresponding to the source tree directory in which the command was in‐
8874 voked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
8875 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target proper‐
8876 ties to change this location. See documentation of the OUTPUT_NAME
8877 target property to change the <name> part of the final file name.
8878 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
8880 the created target. See documentation of the EXCLUDE_FROM_ALL target
8881 property for details.
8882 See the cmake-buildsystem(7) manual for more on defining buildsystem
8884 properties.
8885 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
8887 cessed, and you want to have the original sources reachable from within
8888 IDE.
8889 Object Libraries
8891 add_library(<name> OBJECT [<source>...])
8892 Creates an Object Library. An object library compiles source files but
8894 does not archive or link their object files into a library. Instead
8895 other targets created by add_library() or add_executable() may refer‐
8896 ence the objects using an expression of the form $<TARGET_OBJECTS:ob‐
8897 jlib> as a source, where objlib is the object library name. For exam‐
8898 ple:
8899 add_library(... $<TARGET_OBJECTS:objlib> ...)
8901 add_executable(... $<TARGET_OBJECTS:objlib> ...)
8902 will include objlib's object files in a library and an executable along
8904 with those compiled from their own sources. Object libraries may con‐
8905 tain only sources that compile, header files, and other files that
8906 would not affect linking of a normal library (e.g. .txt). They may
8907 contain custom commands generating such sources, but not PRE_BUILD,
8908 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
8909 Xcode) may not like targets that have only object files, so consider
8910 adding at least one real source file to any target that references
8911 $<TARGET_OBJECTS:objlib>.
8912 New in version 3.12: Object libraries can be linked to with
8914 target_link_libraries().
8915 Interface Libraries
8918 add_library(<name> INTERFACE)
8919 Creates an Interface Library. An INTERFACE library target does not
8921 compile sources and does not produce a library artifact on disk. How‐
8922 ever, it may have properties set on it and it may be installed and ex‐
8923 ported. Typically, INTERFACE_* properties are populated on an inter‐
8924 face target using the commands:
8925 • set_property(),
8927 • target_link_libraries(INTERFACE),
8929 • target_link_options(INTERFACE),
8931 • target_include_directories(INTERFACE),
8933 • target_compile_options(INTERFACE),
8935 • target_compile_definitions(INTERFACE), and
8937 • target_sources(INTERFACE),
8939 and then it is used as an argument to target_link_libraries() like any
8941 other target.
8942 An interface library created with the above signature has no source
8944 files itself and is not included as a target in the generated buildsys‐
8945 tem.
8946 New in version 3.15: An interface library can have PUBLIC_HEADER and
8948 PRIVATE_HEADER properties. The headers specified by those properties
8949 can be installed using the install(TARGETS) command.
8950 New in version 3.19: An interface library target may be created with
8953 source files:
8954 add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
8956 Source files may be listed directly in the add_library call or added
8958 later by calls to target_sources() with the PRIVATE or PUBLIC keywords.
8959 If an interface library has source files (i.e. the SOURCES target prop‐
8961 erty is set), or header sets (i.e. the HEADER_SETS target property is
8962 set), it will appear in the generated buildsystem as a build target
8963 much like a target defined by the add_custom_target() command. It does
8964 not compile any sources, but does contain build rules for custom com‐
8965 mands created by the add_custom_command() command.
8966 NOTE:
8969 In most command signatures where the INTERFACE keyword appears, the
8970 items listed after it only become part of that target's usage re‐
8971 quirements and are not part of the target's own settings. However,
8972 in this signature of add_library, the INTERFACE keyword refers to
8973 the library type only. Sources listed after it in the add_library
8974 call are PRIVATE to the interface library and do not appear in its
8975 INTERFACE_SOURCES target property.
8976 Imported Libraries
8978 add_library(<name> <type> IMPORTED [GLOBAL])
8979 Creates an IMPORTED library target called <name>. No rules are gener‐
8981 ated to build it, and the IMPORTED target property is True. The target
8982 name has scope in the directory in which it is created and below, but
8983 the GLOBAL option extends visibility. It may be referenced like any
8984 target built within the project. IMPORTED libraries are useful for
8985 convenient reference from commands like target_link_libraries(). De‐
8986 tails about the imported library are specified by setting properties
8987 whose names begin in IMPORTED_ and INTERFACE_.
8988 The <type> must be one of:
8990 STATIC, SHARED, MODULE, UNKNOWN
8992 References a library file located outside the project. The
8993 IMPORTED_LOCATION target property (or its per-configuration
8994 variant IMPORTED_LOCATION_<CONFIG>) specifies the location of
8995 the main library file on disk:
8996 • For a SHARED library on most non-Windows platforms, the main
8998 library file is the .so or .dylib file used by both linkers
8999 and dynamic loaders. If the referenced library file has a
9000 SONAME (or on macOS, has a LC_ID_DYLIB starting in @rpath/),
9001 the value of that field should be set in the IMPORTED_SONAME
9002 target property. If the referenced library file does not have
9003 a SONAME, but the platform supports it, then the
9004 IMPORTED_NO_SONAME target property should be set.
9005 • For a SHARED library on Windows, the IMPORTED_IMPLIB target
9007 property (or its per-configuration variant
9008 IMPORTED_IMPLIB_<CONFIG>) specifies the location of the DLL
9009 import library file (.lib or .dll.a) on disk, and the IM‐
9010 PORTED_LOCATION is the location of the .dll runtime library
9011 (and is optional, but needed by the TARGET_RUNTIME_DLLS gener‐
9012 ator expression).
9013 Additional usage requirements may be specified in INTERFACE_*
9015 properties.
9016 An UNKNOWN library type is typically only used in the implemen‐
9018 tation of Find Modules. It allows the path to an imported li‐
9019 brary (often found using the find_library() command) to be used
9020 without having to know what type of library it is. This is es‐
9021 pecially useful on Windows where a static library and a DLL's
9022 import library both have the same file extension.
9023 OBJECT References a set of object files located outside the project.
9025 The IMPORTED_OBJECTS target property (or its per-configuration
9026 variant IMPORTED_OBJECTS_<CONFIG>) specifies the locations of
9027 object files on disk. Additional usage requirements may be
9028 specified in INTERFACE_* properties.
9029 INTERFACE
9031 Does not reference any library or object files on disk, but may
9032 specify usage requirements in INTERFACE_* properties.
9033 See documentation of the IMPORTED_* and INTERFACE_* properties for more
9035 information.
9036 Alias Libraries
9038 add_library(<name> ALIAS <target>)
9039 Creates an Alias Target, such that <name> can be used to refer to <tar‐
9041 get> in subsequent commands. The <name> does not appear in the gener‐
9042 ated buildsystem as a make target. The <target> may not be an ALIAS.
9043 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
9045 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
9048 Such alias is scoped to the directory in which it is created and below.
9049 The ALIAS_GLOBAL target property can be used to check if the alias is
9050 global or not.
9051 ALIAS targets can be used as linkable targets and as targets to read
9054 properties from. They can also be tested for existence with the regu‐
9055 lar if(TARGET) subcommand. The <name> may not be used to modify prop‐
9056 erties of <target>, that is, it may not be used as the operand of
9057 set_property(), set_target_properties(), target_link_libraries() etc.
9058 An ALIAS target may not be installed or exported.
9059 add_link_options
9061 New in version 3.13.
9062 Add options to the link step for executable, shared library or module
9065 library targets in the current directory and below that are added after
9066 this command is invoked.
9067 add_link_options(<option> ...)
9069 This command can be used to add any link options, but alternative com‐
9071 mands exist to add libraries (target_link_libraries() or
9072 link_libraries()). See documentation of the directory and target
9073 LINK_OPTIONS properties.
9074 NOTE:
9076 This command cannot be used to add options for static library tar‐
9077 gets, since they do not use a linker. To add archiver or MSVC li‐
9078 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
9079 Arguments to add_link_options may use "generator expressions" with the
9081 syntax $<...>. See the cmake-generator-expressions(7) manual for
9082 available expressions. See the cmake-buildsystem(7) manual for more on
9083 defining buildsystem properties.
9084 Host And Device Specific Link Options
9086 New in version 3.18: When a device link step is involved, which is con‐
9087 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
9088 properties and policy CMP0105, the raw options will be delivered to the
9089 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
9090 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
9091 sion will be used only for the device link step. Options wrapped with
9092 $<HOST_LINK:...> generator expression will be used only for the host
9093 link step.
9094 Option De-duplication
9097 The final set of options used for a target is constructed by accumulat‐
9098 ing options from the current target and the usage requirements of its
9099 dependencies. The set of options is de-duplicated to avoid repetition.
9100 New in version 3.12: While beneficial for individual options, the
9102 de-duplication step can break up option groups. For example, -option A
9103 -option B becomes -option A B. One may specify a group of options us‐
9104 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
9105 is dropped, and the rest of the option string is parsed using the
9106 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
9107 "SHELL:-option B" becomes -option A -option B.
9108 Handling Compiler Driver Differences
9111 To pass options to the linker tool, each compiler driver has its own
9112 syntax. The LINKER: prefix and , separator can be used to specify, in
9113 a portable way, options to pass to the linker tool. LINKER: is replaced
9114 by the appropriate driver option and , by the appropriate driver sepa‐
9115 rator. The driver prefix and driver separator are given by the values
9116 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
9117 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
9118 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
9120 Clang and -Wl,-z,defs for GNU GCC.
9121 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
9123 sion.
9124 The LINKER: prefix supports, as an alternative syntax, specification of
9126 arguments using the SHELL: prefix and space as separator. The previous
9127 example then becomes "LINKER:SHELL:-z defs".
9128 NOTE:
9130 Specifying the SHELL: prefix anywhere other than at the beginning of
9131 the LINKER: prefix is not supported.
9132 add_subdirectory
9134 Add a subdirectory to the build.
9135 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
9137 Adds a subdirectory to the build. The source_dir specifies the direc‐
9139 tory in which the source CMakeLists.txt and code files are located. If
9140 it is a relative path, it will be evaluated with respect to the current
9141 directory (the typical usage), but it may also be an absolute path.
9142 The binary_dir specifies the directory in which to place the output
9143 files. If it is a relative path, it will be evaluated with respect to
9144 the current output directory, but it may also be an absolute path. If
9145 binary_dir is not specified, the value of source_dir, before expanding
9146 any relative path, will be used (the typical usage). The CMake‐
9147 Lists.txt file in the specified source directory will be processed im‐
9148 mediately by CMake before processing in the current input file contin‐
9149 ues beyond this command.
9150 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
9152 rectory will not be included in the ALL target of the parent directory
9153 by default, and will be excluded from IDE project files. Users must
9154 explicitly build targets in the subdirectory. This is meant for use
9155 when the subdirectory contains a separate part of the project that is
9156 useful but not necessary, such as a set of examples. Typically the
9157 subdirectory should contain its own project() command invocation so
9158 that a full build system will be generated in the subdirectory (such as
9159 a Visual Studio IDE solution file). Note that inter-target dependen‐
9160 cies supersede this exclusion. If a target built by the parent project
9161 depends on a target in the subdirectory, the dependee target will be
9162 included in the parent project build system to satisfy the dependency.
9163 New in version 3.25: If the SYSTEM argument is provided, the SYSTEM di‐
9165 rectory property of the subdirectory will be set to true. This prop‐
9166 erty is used to initialize the SYSTEM property of each non-imported
9167 target created in that subdirectory.
9168 add_test
9171 Add a test to the project to be run by ctest(1).
9172 add_test(NAME <name> COMMAND <command> [<arg>...]
9174 [CONFIGURATIONS <config>...]
9175 [WORKING_DIRECTORY <dir>]
9176 [COMMAND_EXPAND_LISTS])
9177 Adds a test called <name>. The test name may contain arbitrary charac‐
9179 ters, expressed as a Quoted Argument or Bracket Argument if necessary.
9180 See policy CMP0110. The options are:
9181 COMMAND
9183 Specify the test command-line. If <command> specifies an exe‐
9184 cutable target (created by add_executable()) it will automati‐
9185 cally be replaced by the location of the executable created at
9186 build time.
9187 The command may be specified using generator expressions.
9189 CONFIGURATIONS
9191 Restrict execution of the test only to the named configurations.
9192 WORKING_DIRECTORY
9194 Set the WORKING_DIRECTORY test property to specify the working
9195 directory in which to execute the test. If not specified the
9196 test will be run with the current working directory set to the
9197 build directory corresponding to the current source directory.
9198 The working directory may be specified using generator expres‐
9200 sions.
9201 COMMAND_EXPAND_LISTS
9203 New in version 3.16.
9204 Lists in COMMAND arguments will be expanded, including those
9207 created with generator expressions.
9208 The given test command is expected to exit with code 0 to pass and
9210 non-zero to fail, or vice-versa if the WILL_FAIL test property is set.
9211 Any output written to stdout or stderr will be captured by ctest(1) but
9212 does not affect the pass/fail status unless the
9213 PASS_REGULAR_EXPRESSION, FAIL_REGULAR_EXPRESSION or
9214 SKIP_REGULAR_EXPRESSION test property is used.
9215 New in version 3.16: Added SKIP_REGULAR_EXPRESSION property.
9217 Tests added with the add_test(NAME) signature support using generator
9220 expressions in test properties set by set_property(TEST) or
9221 set_tests_properties().
9222 Example usage:
9224 add_test(NAME mytest
9226 COMMAND testDriver --config $<CONFIG>
9227 --exe $<TARGET_FILE:myexe>)
9228 This creates a test mytest whose command runs a testDriver tool passing
9230 the configuration name and the full path to the executable file pro‐
9231 duced by target myexe.
9232 NOTE:
9234 CMake will generate tests only if the enable_testing() command has
9235 been invoked. The CTest module invokes the command automatically
9236 unless the BUILD_TESTING option is turned OFF.
9237 ----
9240 This command also supports a simpler, but less flexible, signature:
9244 add_test(<name> <command> [<arg>...])
9246 Add a test called <name> with the given command-line.
9248 Unlike the above NAME signature, target names are not supported in the
9250 command-line. Furthermore, tests added with this signature do not sup‐
9251 port generator expressions in the command-line or test properties.
9252 aux_source_directory
9254 Find all source files in a directory.
9255 aux_source_directory(<dir> <variable>)
9257 Collects the names of all the source files in the specified directory
9259 and stores the list in the <variable> provided. This command is in‐
9260 tended to be used by projects that use explicit template instantiation.
9261 Template instantiation files can be stored in a Templates subdirectory
9262 and collected automatically using this command to avoid manually list‐
9263 ing all instantiations.
9264 It is tempting to use this command to avoid writing the list of source
9266 files for a library or executable target. While this seems to work,
9267 there is no way for CMake to generate a build system that knows when a
9268 new source file has been added. Normally the generated build system
9269 knows when it needs to rerun CMake because the CMakeLists.txt file is
9270 modified to add a new source. When the source is just added to the di‐
9271 rectory without modifying this file, one would have to manually rerun
9272 CMake to generate a build system incorporating the new file.
9273 build_command
9275 Get a command line to build the current project. This is mainly in‐
9276 tended for internal use by the CTest module.
9277 build_command(<variable>
9279 [CONFIGURATION <config>]
9280 [PARALLEL_LEVEL <parallel>]
9281 [TARGET <target>]
9282 [PROJECT_NAME <projname>] # legacy, causes warning
9283 )
9284 Sets the given <variable> to a command-line string of the form:
9286 <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]
9288 where <cmake> is the location of the cmake(1) command-line tool, and
9290 <config>, <parallel> and <target> are the values provided to the CON‐
9291 FIGURATION, PARALLEL_LEVEL and TARGET options, if any. The trailing --
9292 -i option is added for Makefile Generators if policy CMP0061 is not set
9293 to NEW.
9294 When invoked, this cmake --build command line will launch the underly‐
9296 ing build system tool.
9297 New in version 3.21: The PARALLEL_LEVEL argument can be used to set the
9299 --parallel flag.
9300 build_command(<cachevariable> <makecommand>)
9303 This second signature is deprecated, but still available for backwards
9305 compatibility. Use the first signature instead.
9306 It sets the given <cachevariable> to a command-line string as above but
9308 without the --target option. The <makecommand> is ignored but should
9309 be the full path to devenv, nmake, make or one of the end user build
9310 tools for legacy invocations.
9311 NOTE:
9313 In CMake versions prior to 3.0 this command returned a command line
9314 that directly invokes the native build tool for the current genera‐
9315 tor. Their implementation of the PROJECT_NAME option had no useful
9316 effects, so CMake now warns on use of the option.
9317 create_test_sourcelist
9319 Create a test driver and source list for building test programs.
9320 create_test_sourcelist(sourceListName driverName
9322 test1 test2 test3
9323 EXTRA_INCLUDE include.h
9324 FUNCTION function)
9325 A test driver is a program that links together many small tests into a
9327 single executable. This is useful when building static executables
9328 with large libraries to shrink the total required size. The list of
9329 source files needed to build the test driver will be in sourceListName.
9330 driverName is the name of the test driver program. The rest of the ar‐
9331 guments consist of a list of test source files, can be semicolon sepa‐
9332 rated. Each test source file should have a function in it that is the
9333 same name as the file with no extension (foo.cxx should have int
9334 foo(int, char*[]);) driverName will be able to call each of the tests
9335 by name on the command line. If EXTRA_INCLUDE is specified, then the
9336 next argument is included into the generated file. If FUNCTION is
9337 specified, then the next argument is taken as a function name that is
9338 passed a pointer to ac and av. This can be used to add extra command
9339 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
9340 cmake variable can be set to have code that will be placed directly be‐
9341 fore calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
9342 can be set to have code that will be placed directly after the call to
9343 the test main function.
9344 define_property
9346 Define and document custom properties.
9347 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
9349 TEST | VARIABLE | CACHED_VARIABLE>
9350 PROPERTY <name> [INHERITED]
9351 [BRIEF_DOCS <brief-doc> [docs...]]
9352 [FULL_DOCS <full-doc> [docs...]]
9353 [INITIALIZE_FROM_VARIABLE <variable>])
9354 Defines one property in a scope for use with the set_property() and
9356 get_property() commands. It is mainly useful for defining the way a
9357 property is initialized or inherited. Historically, the command also
9358 associated documentation with a property, but that is no longer consid‐
9359 ered a primary use case.
9360 The first argument determines the kind of scope in which the property
9362 should be used. It must be one of the following:
9363 GLOBAL = associated with the global namespace
9365 DIRECTORY = associated with one directory
9366 TARGET = associated with one target
9367 SOURCE = associated with one source file
9368 TEST = associated with a test named with add_test
9369 VARIABLE = documents a CMake language variable
9370 CACHED_VARIABLE = documents a CMake cache variable
9371 Note that unlike set_property() and get_property() no actual scope
9373 needs to be given; only the kind of scope is important.
9374 The required PROPERTY option is immediately followed by the name of the
9376 property being defined.
9377 If the INHERITED option is given, then the get_property() command will
9379 chain up to the next higher scope when the requested property is not
9380 set in the scope given to the command.
9381 • DIRECTORY scope chains to its parent directory's scope, continuing
9383 the walk up parent directories until a directory has the property set
9384 or there are no more parents. If still not found at the top level
9385 directory, it chains to the GLOBAL scope.
9386 • TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
9388 ing further chaining up the directories, etc. as needed.
9389 Note that this scope chaining behavior only applies to calls to
9391 get_property(), get_directory_property(), get_target_property(),
9392 get_source_file_property() and get_test_property(). There is no inher‐
9393 iting behavior when setting properties, so using APPEND or AP‐
9394 PEND_STRING with the set_property() command will not consider inherited
9395 values when working out the contents to append to.
9396 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as‐
9398 sociated with the property as its brief and full documentation. CMake
9399 does not use this documentation other than making it available to the
9400 project via corresponding options to the get_property() command.
9401 Changed in version 3.23: The BRIEF_DOCS and FULL_DOCS options are op‐
9403 tional.
9404 New in version 3.23: The INITIALIZE_FROM_VARIABLE option specifies a
9407 variable from which the property should be initialized. It can only be
9408 used with target properties. The <variable> name must end with the
9409 property name and must not begin with CMAKE_ or _CMAKE_. The property
9410 name must contain at least one underscore. It is recommended that the
9411 property name have a prefix specific to the project.
9412 enable_language
9415 Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
9416 enable_language(<lang>... [OPTIONAL])
9418 Enables support for the named languages in CMake. This is the same as
9420 the project() command but does not create any of the extra variables
9421 that are created by the project command. Example languages are CXX, C,
9422 CUDA, OBJC, OBJCXX, Fortran, HIP, ISPC, and ASM.
9423 New in version 3.8: Added CUDA support.
9425 New in version 3.16: Added OBJC and OBJCXX support.
9428 New in version 3.18: Added ISPC support.
9431 New in version 3.21: Added HIP support.
9434 If enabling ASM, enable it last so that CMake can check whether compil‐
9437 ers for other languages like C work for assembly too.
9438 This command must be called in file scope, not in a function call.
9440 Furthermore, it must be called in the highest directory common to all
9441 targets using the named language directly for compiling sources or in‐
9442 directly through link dependencies. It is simplest to enable all
9443 needed languages in the top-level directory of a project.
9444 The OPTIONAL keyword is a placeholder for future implementation and
9446 does not currently work. Instead you can use the CheckLanguage module
9447 to verify support before enabling.
9448 enable_testing
9450 Enable testing for current directory and below.
9451 enable_testing()
9453 Enables testing for this directory and below.
9455 This command should be in the source directory root because ctest ex‐
9457 pects to find a test file in the build directory root.
9458 This command is automatically invoked when the CTest module is in‐
9460 cluded, except if the BUILD_TESTING option is turned off.
9461 See also the add_test() command.
9463 export
9465 Export targets or packages for outside projects to use them directly
9466 from the current project's build tree, without installation.
9467 See the install(EXPORT) command to export targets from an install tree.
9469 Synopsis
9471 export(TARGETS <target>... [...])
9472 export(EXPORT <export-name> [...])
9473 export(PACKAGE <PackageName>)
9474 Exporting Targets
9476 export(TARGETS <target>... [NAMESPACE <namespace>]
9477 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
9478 [CXX_MODULES_DIRECTORY <directory>])
9479 Creates a file <filename> that may be included by outside projects to
9481 import targets named by <target>... from the current project's build
9482 tree. This is useful during cross-compiling to build utility executa‐
9483 bles that can run on the host platform in one project and then import
9484 them into another project being compiled for the target platform.
9485 The file created by this command is specific to the build tree and
9487 should never be installed. See the install(EXPORT) command to export
9488 targets from an install tree.
9489 The options are:
9491 NAMESPACE <namespace>
9493 Prepend the <namespace> string to all target names written to
9494 the file.
9495 APPEND Append to the file instead of overwriting it. This can be used
9497 to incrementally export multiple targets to the same file.
9498 EXPORT_LINK_INTERFACE_LIBRARIES
9500 Include the contents of the properties named with the pattern
9501 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? in the export,
9502 even when policy CMP0022 is NEW. This is useful to support con‐
9503 sumers using CMake versions older than 2.8.12.
9504 CXX_MODULES_DIRECTORY <directory>
9506 NOTE:
9508 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
9509 Export C++ module properties to files under the given directory.
9511 Each file will be named according to the target's export name (with‐
9512 out any namespace). These files will automatically be included from
9513 the export file.
9514 This signature requires all targets to be listed explicitly. If a li‐
9516 brary target is included in the export, but a target to which it links
9517 is not included, the behavior is unspecified. See the export(EXPORT)
9518 signature to automatically export the same targets from the build tree
9519 as install(EXPORT) would from an install tree.
9520 NOTE:
9522 Object Libraries under Xcode have special handling if multiple ar‐
9523 chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
9524 they will be exported as Interface Libraries with no object files
9525 available to clients. This is sufficient to satisfy transitive us‐
9526 age requirements of other targets that link to the object libraries
9527 in their implementation.
9528 Exporting Targets to Android.mk
9530 export(TARGETS <target>... ANDROID_MK <filename>)
9531 New in version 3.7.
9533 This signature exports cmake built targets to the android ndk build
9536 system by creating an Android.mk file that references the prebuilt tar‐
9537 gets. The Android NDK supports the use of prebuilt libraries, both
9538 static and shared. This allows cmake to build the libraries of a
9539 project and make them available to an ndk build system complete with
9540 transitive dependencies, include flags and defines required to use the
9541 libraries. The signature takes a list of targets and puts them in the
9542 Android.mk file specified by the <filename> given. This signature can
9543 only be used if policy CMP0022 is NEW for all targets given. A error
9544 will be issued if that policy is set to OLD for one of the targets.
9545 Exporting Targets matching install(EXPORT)
9547 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
9548 [CXX_MODULES_DIRECTORY <directory>])
9549 Creates a file <filename> that may be included by outside projects to
9551 import targets from the current project's build tree. This is the same
9552 as the export(TARGETS) signature, except that the targets are not ex‐
9553 plicitly listed. Instead, it exports the targets associated with the
9554 installation export <export-name>. Target installations may be associ‐
9555 ated with the export <export-name> using the EXPORT option of the
9556 install(TARGETS) command.
9557 Exporting Packages
9559 export(PACKAGE <PackageName>)
9560 Store the current build directory in the CMake user package registry
9562 for package <PackageName>. The find_package() command may consider the
9563 directory while searching for package <PackageName>. This helps depen‐
9564 dent projects find and use a package from the current project's build
9565 tree without help from the user. Note that the entry in the package
9566 registry that this command creates works only in conjunction with a
9567 package configuration file (<PackageName>Config.cmake) that works with
9568 the build tree. In some cases, for example for packaging and for system
9569 wide installations, it is not desirable to write the user package reg‐
9570 istry.
9571 Changed in version 3.1: If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY vari‐
9573 able is enabled, the export(PACKAGE) command will do nothing.
9574 Changed in version 3.15: By default the export(PACKAGE) command does
9577 nothing (see policy CMP0090) because populating the user package reg‐
9578 istry has effects outside the source and build trees. Set the
9579 CMAKE_EXPORT_PACKAGE_REGISTRY variable to add build directories to the
9580 CMake user package registry.
9581 fltk_wrap_ui
9584 Create FLTK user interfaces Wrappers.
9585 fltk_wrap_ui(resultingLibraryName source1
9587 source2 ... sourceN )
9588 Produce .h and .cxx files for all the .fl and .fld files listed. The
9590 resulting .h and .cxx files will be added to a variable named result‐
9591 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
9592 get_source_file_property
9594 Get a property for a source file.
9595 get_source_file_property(<variable> <file>
9597 [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
9598 <property>)
9599 Gets a property from a source file. The value of the property is
9601 stored in the specified <variable>. If the source property is not
9602 found, the behavior depends on whether it has been defined to be an IN‐
9603 HERITED property or not (see define_property()). Non-inherited proper‐
9604 ties will set variable to NOTFOUND, whereas inherited properties will
9605 search the relevant parent scope as described for the define_property()
9606 command and if still unable to find the property, variable will be set
9607 to an empty string.
9608 By default, the source file's property will be read from the current
9610 source directory's scope.
9611 New in version 3.18: Directory scope can be overridden with one of the
9613 following sub-options:
9614 DIRECTORY <dir>
9616 The source file property will be read from the <dir> directory's
9617 scope. CMake must already know about that source directory, ei‐
9618 ther by having added it through a call to add_subdirectory() or
9619 <dir> being the top level source directory. Relative paths are
9620 treated as relative to the current source directory.
9621 TARGET_DIRECTORY <target>
9623 The source file property will be read from the directory scope
9624 in which <target> was created (<target> must therefore already
9625 exist).
9626 Use set_source_files_properties() to set property values. Source file
9629 properties usually control how the file is built. One property that is
9630 always there is LOCATION.
9631 See also the more general get_property() command.
9633 NOTE:
9635 The GENERATED source file property may be globally visible. See its
9636 documentation for details.
9637 get_target_property
9639 Get a property from a target.
9640 get_target_property(<VAR> target property)
9642 Get a property from a target. The value of the property is stored in
9644 the variable <VAR>. If the target property is not found, the behavior
9645 depends on whether it has been defined to be an INHERITED property or
9646 not (see define_property()). Non-inherited properties will set <VAR>
9647 to <VAR>-NOTFOUND, whereas inherited properties will search the rele‐
9648 vant parent scope as described for the define_property() command and if
9649 still unable to find the property, <VAR> will be set to an empty
9650 string.
9651 Use set_target_properties() to set target property values. Properties
9653 are usually used to control how a target is built, but some query the
9654 target instead. This command can get properties for any target so far
9655 created. The targets do not need to be in the current CMakeLists.txt
9656 file.
9657 See also the more general get_property() command.
9659 See Properties on Targets for the list of properties known to CMake.
9661 get_test_property
9663 Get a property of the test.
9664 get_test_property(test property VAR)
9666 Get a property from the test. The value of the property is stored in
9668 the variable VAR. If the test property is not found, the behavior de‐
9669 pends on whether it has been defined to be an INHERITED property or not
9670 (see define_property()). Non-inherited properties will set VAR to
9671 "NOTFOUND", whereas inherited properties will search the relevant par‐
9672 ent scope as described for the define_property() command and if still
9673 unable to find the property, VAR will be set to an empty string.
9674 For a list of standard properties you can type cmake --help-prop‐
9676 erty-list.
9677 See also the more general get_property() command.
9679 include_directories
9681 Add include directories to the build.
9682 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
9684 Add the given directories to those the compiler uses to search for in‐
9686 clude files. Relative paths are interpreted as relative to the current
9687 source directory.
9688 The include directories are added to the INCLUDE_DIRECTORIES directory
9690 property for the current CMakeLists file. They are also added to the
9691 INCLUDE_DIRECTORIES target property for each target in the current
9692 CMakeLists file. The target property values are the ones used by the
9693 generators.
9694 By default the directories specified are appended onto the current list
9696 of directories. This default behavior can be changed by setting
9697 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE ex‐
9698 plicitly, you can select between appending and prepending, independent
9699 of the default.
9700 If the SYSTEM option is given, the compiler will be told the directo‐
9702 ries are meant as system include directories on some platforms. Sig‐
9703 nalling this setting might achieve effects such as the compiler skip‐
9704 ping warnings, or these fixed-install system files not being considered
9705 in dependency calculations - see compiler docs.
9706 Arguments to include_directories may use "generator expressions" with
9708 the syntax "$<...>". See the cmake-generator-expressions(7) manual for
9709 available expressions. See the cmake-buildsystem(7) manual for more on
9710 defining buildsystem properties.
9711 NOTE:
9713 Prefer the target_include_directories() command to add include di‐
9714 rectories to individual targets and optionally propagate/export them
9715 to dependents.
9716 include_external_msproject
9718 Include an external Microsoft project file in a workspace.
9719 include_external_msproject(projectname location
9721 [TYPE projectTypeGUID]
9722 [GUID projectGUID]
9723 [PLATFORM platformName]
9724 dep1 dep2 ...)
9725 Includes an external Microsoft project in the generated workspace file.
9727 Currently does nothing on UNIX. This will create a target named [pro‐
9728 jectname]. This can be used in the add_dependencies() command to make
9729 things depend on the external project.
9730 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
9732 ify the type of project, id (GUID) of the project and the name of the
9733 target platform. This is useful for projects requiring values other
9734 than the default (e.g. WIX projects).
9735 New in version 3.9: If the imported project has different configuration
9737 names than the current project, set the MAP_IMPORTED_CONFIG_<CONFIG>
9738 target property to specify the mapping.
9739 include_regular_expression
9742 Set the regular expression used for dependency checking.
9743 include_regular_expression(regex_match [regex_complain])
9745 Sets the regular expressions used in dependency checking. Only files
9747 matching regex_match will be traced as dependencies. Only files match‐
9748 ing regex_complain will generate warnings if they cannot be found
9749 (standard header paths are not searched). The defaults are:
9750 regex_match = "^.*$" (match everything)
9752 regex_complain = "^$" (match empty string only)
9753 install
9755 Specify rules to run at install time.
9756 Synopsis
9758 install(TARGETS <target>... [...])
9759 install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
9760 install({FILES | PROGRAMS} <file>... [...])
9761 install(DIRECTORY <dir>... [...])
9762 install(SCRIPT <file> [...])
9763 install(CODE <code> [...])
9764 install(EXPORT <export-name> [...])
9765 install(RUNTIME_DEPENDENCY_SET <set-name> [...])
9766 Introduction
9768 This command generates installation rules for a project. Install rules
9769 specified by calls to the install() command within a source directory
9770 are executed in order during installation.
9771 Changed in version 3.14: Install rules in subdirectories added by calls
9773 to the add_subdirectory() command are interleaved with those in the
9774 parent directory to run in the order declared (see policy CMP0082).
9775 Changed in version 3.22: The environment variable CMAKE_INSTALL_MODE
9778 can override the default copying behavior of install().
9779 There are multiple signatures for this command. Some of them define
9782 installation options for files and targets. Options common to multiple
9783 signatures are covered here but they are valid only for signatures that
9784 specify them. The common options are:
9785 DESTINATION
9787 Specify the directory on disk to which a file will be installed.
9788 Arguments can be relative or absolute paths.
9789 If a relative path is given it is interpreted relative to the
9791 value of the CMAKE_INSTALL_PREFIX variable. The prefix can be
9792 relocated at install time using the DESTDIR mechanism explained
9793 in the CMAKE_INSTALL_PREFIX variable documentation.
9794 If an absolute path (with a leading slash or drive letter) is
9796 given it is used verbatim.
9797 As absolute paths are not supported by cpack installer genera‐
9799 tors, it is preferable to use relative paths throughout. In
9800 particular, there is no need to make paths absolute by prepend‐
9801 ing CMAKE_INSTALL_PREFIX; this prefix is used by default if the
9802 DESTINATION is a relative path.
9803 PERMISSIONS
9805 Specify permissions for installed files. Valid permissions are
9806 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
9807 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
9808 and SETGID. Permissions that do not make sense on certain plat‐
9809 forms are ignored on those platforms.
9810 CONFIGURATIONS
9812 Specify a list of build configurations for which the install
9813 rule applies (Debug, Release, etc.). Note that the values speci‐
9814 fied for this option only apply to options listed AFTER the CON‐
9815 FIGURATIONS option. For example, to set separate install paths
9816 for the Debug and Release configurations, do the following:
9817 install(TARGETS target
9819 CONFIGURATIONS Debug
9820 RUNTIME DESTINATION Debug/bin)
9821 install(TARGETS target
9822 CONFIGURATIONS Release
9823 RUNTIME DESTINATION Release/bin)
9824 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
9826 COMPONENT
9828 Specify an installation component name with which the install
9829 rule is associated, such as Runtime or Development. During com‐
9830 ponent-specific installation only install rules associated with
9831 the given component name will be executed. During a full in‐
9832 stallation all components are installed unless marked with EX‐
9833 CLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
9834 nent "Unspecified" is created. The default component name may
9835 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
9836 variable.
9837 EXCLUDE_FROM_ALL
9839 New in version 3.6.
9840 Specify that the file is excluded from a full installation and
9843 only installed as part of a component-specific installation
9844 RENAME Specify a name for an installed file that may be different from
9846 the original file. Renaming is allowed only when a single file
9847 is installed by the command.
9848 OPTIONAL
9850 Specify that it is not an error if the file to be installed does
9851 not exist.
9852 New in version 3.1: Command signatures that install files may print
9854 messages during installation. Use the CMAKE_INSTALL_MESSAGE variable
9855 to control which messages are printed.
9856 New in version 3.11: Many of the install() variants implicitly create
9859 the directories containing the installed files. If
9860 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS is set, these directories
9861 will be created with the permissions specified. Otherwise, they will be
9862 created according to the uname rules on Unix-like platforms. Windows
9863 platforms are unaffected.
9864 Installing Targets
9867 install(TARGETS targets... [EXPORT <export-name>]
9868 [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
9869 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
9870 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI]
9871 [DESTINATION <dir>]
9872 [PERMISSIONS permissions...]
9873 [CONFIGURATIONS [Debug|Release|...]]
9874 [COMPONENT <component>]
9875 [NAMELINK_COMPONENT <component>]
9876 [OPTIONAL] [EXCLUDE_FROM_ALL]
9877 [NAMELINK_ONLY|NAMELINK_SKIP]
9878 ] [...]
9879 [INCLUDES DESTINATION [<dir> ...]]
9880 )
9881 The TARGETS form specifies rules for installing targets from a project.
9883 There are several kinds of target Output Artifacts that may be in‐
9884 stalled:
9885 ARCHIVE
9887 Target artifacts of this kind include:
9888 • Static libraries (except on macOS when marked as FRAMEWORK,
9890 see below);
9891 • DLL import libraries (on all Windows-based systems including
9893 Cygwin; they have extension .lib, in contrast to the .dll li‐
9894 braries that go to RUNTIME);
9895 • On AIX, the linker import file created for executables with
9897 ENABLE_EXPORTS enabled.
9898 LIBRARY
9900 Target artifacts of this kind include:
9901 • Shared libraries, except
9903 • DLLs (these go to RUNTIME, see below),
9905 • on macOS when marked as FRAMEWORK (see below).
9907 RUNTIME
9909 Target artifacts of this kind include:
9910 • Executables (except on macOS when marked as MACOSX_BUNDLE, see
9912 BUNDLE below);
9913 • DLLs (on all Windows-based systems including Cygwin; note that
9915 the accompanying import libraries are of kind ARCHIVE).
9916 OBJECTS
9918 New in version 3.9.
9919 Object files associated with object libraries.
9922 FRAMEWORK
9924 Both static and shared libraries marked with the FRAMEWORK prop‐
9925 erty are treated as FRAMEWORK targets on macOS.
9926 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
9928 as BUNDLE targets on macOS.
9929 PUBLIC_HEADER
9931 Any PUBLIC_HEADER files associated with a library are installed
9932 in the destination specified by the PUBLIC_HEADER argument on
9933 non-Apple platforms. Rules defined by this argument are ignored
9934 for FRAMEWORK libraries on Apple platforms because the associ‐
9935 ated files are installed into the appropriate locations inside
9936 the framework folder. See PUBLIC_HEADER for details.
9937 PRIVATE_HEADER
9939 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See
9940 PRIVATE_HEADER for details.
9941 RESOURCE
9943 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
9944 files. See RESOURCE for details.
9945 FILE_SET <set>
9947 New in version 3.23.
9948 File sets are defined by the target_sources(FILE_SET) command.
9951 If the file set <set> exists and is PUBLIC or INTERFACE, any
9952 files in the set are installed under the destination (see be‐
9953 low). The directory structure relative to the file set's base
9954 directories is preserved. For example, a file added to the file
9955 set as /blah/include/myproj/here.h with a base directory
9956 /blah/include would be installed to myproj/here.h below the des‐
9957 tination.
9958 CXX_MODULES_BMI
9960 NOTE:
9962 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
9963 Any module files from C++ modules from PUBLIC sources in a file set
9965 of type CXX_MODULES will be installed to the given DESTINATION. All
9966 modules are placed directly in the destination as no directory
9967 structure is derived from the names of the modules. An empty DESTI‐
9968 NATION may be used to suppress installing these files (for use in
9969 generic code).
9970 For each of these arguments given, the arguments following them only
9972 apply to the target or file type specified in the argument. If none is
9973 given, the installation properties apply to all target types.
9974 For regular executables, static libraries and shared libraries, the
9976 DESTINATION argument is not required. For these target types, when
9977 DESTINATION is omitted, a default destination will be taken from the
9978 appropriate variable from GNUInstallDirs, or set to a built-in default
9979 value if that variable is not defined. The same is true for file sets,
9980 and the public and private headers associated with the installed tar‐
9981 gets through the PUBLIC_HEADER and PRIVATE_HEADER target properties. A
9982 destination must always be provided for module libraries, Apple bundles
9983 and frameworks. A destination can be omitted for interface and object
9984 libraries, but they are handled differently (see the discussion of this
9985 topic toward the end of this section).
9986 For shared libraries on DLL platforms, if neither RUNTIME nor ARCHIVE
9988 destinations are specified, both the RUNTIME and ARCHIVE components are
9989 installed to their default destinations. If either a RUNTIME or ARCHIVE
9990 destination is specified, the component is installed to that destina‐
9991 tion, and the other component is not installed. If both RUNTIME and AR‐
9992 CHIVE destinations are specified, then both components are installed to
9993 their respective destinations.
9994 The following table shows the target types with their associated vari‐
9996 ables and built-in defaults that apply when no destination is given:
9997 ┌────────────────────┬─────────────────────┬──────────────────┐
9999 │Target Type │ GNUInstallDirs │ Built-In Default │
10000 │ │ Variable │ │
10001 ├────────────────────┼─────────────────────┼──────────────────┤
10002 │RUNTIME │ ${CMAKE_IN‐ │ bin │
10003 │ │ STALL_BINDIR} │ │
10004 ├────────────────────┼─────────────────────┼──────────────────┤
10005 │LIBRARY │ ${CMAKE_IN‐ │ lib │
10006 │ │ STALL_LIBDIR} │ │
10007 └────────────────────┴─────────────────────┴──────────────────┘
10008 │ARCHIVE │ ${CMAKE_IN‐ │ lib │
10010 │ │ STALL_LIBDIR} │ │
10011 ├────────────────────┼─────────────────────┼──────────────────┤
10012 │PRIVATE_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
10013 │ │ CLUDEDIR} │ │
10014 ├────────────────────┼─────────────────────┼──────────────────┤
10015 │PUBLIC_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
10016 │ │ CLUDEDIR} │ │
10017 ├────────────────────┼─────────────────────┼──────────────────┤
10018 │FILE_SET (type │ ${CMAKE_INSTALL_IN‐ │ include │
10019 │HEADERS) │ CLUDEDIR} │ │
10020 └────────────────────┴─────────────────────┴──────────────────┘
10021 Projects wishing to follow the common practice of installing headers
10023 into a project-specific subdirectory may prefer using file sets with
10024 appropriate paths and base directories. Otherwise, they must provide a
10025 DESTINATION instead of being able to rely on the above (see next exam‐
10026 ple below).
10027 To make packages compliant with distribution filesystem layout poli‐
10029 cies, if projects must specify a DESTINATION, it is recommended that
10030 they use a path that begins with the appropriate GNUInstallDirs vari‐
10031 able. This allows package maintainers to control the install destina‐
10032 tion by setting the appropriate cache variables. The following example
10033 shows a static library being installed to the default destination pro‐
10034 vided by GNUInstallDirs, but with its headers installed to a
10035 project-specific subdirectory without using file sets:
10036 add_library(mylib STATIC ...)
10038 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
10039 include(GNUInstallDirs)
10040 install(TARGETS mylib
10041 PUBLIC_HEADER
10042 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
10043 )
10044 In addition to the common options listed above, each target can accept
10046 the following additional arguments:
10047 NAMELINK_COMPONENT
10049 New in version 3.12.
10050 On some platforms a versioned shared library has a symbolic link
10053 such as:
10054 lib<name>.so -> lib<name>.so.1
10056 where lib<name>.so.1 is the soname of the library and
10058 lib<name>.so is a "namelink" allowing linkers to find the li‐
10059 brary when given -l<name>. The NAMELINK_COMPONENT option is sim‐
10060 ilar to the COMPONENT option, but it changes the installation
10061 component of a shared library namelink if one is generated. If
10062 not specified, this defaults to the value of COMPONENT. It is an
10063 error to use this parameter outside of a LIBRARY block.
10064 Consider the following example:
10066 install(TARGETS mylib
10068 LIBRARY
10069 COMPONENT Libraries
10070 NAMELINK_COMPONENT Development
10071 PUBLIC_HEADER
10072 COMPONENT Development
10073 )
10074 In this scenario, if you choose to install only the Development
10076 component, both the headers and namelink will be installed with‐
10077 out the library. (If you don't also install the Libraries compo‐
10078 nent, the namelink will be a dangling symlink, and projects that
10079 link to the library will have build errors.) If you install only
10080 the Libraries component, only the library will be installed,
10081 without the headers and namelink.
10082 This option is typically used for package managers that have
10084 separate runtime and development packages. For example, on De‐
10085 bian systems, the library is expected to be in the runtime pack‐
10086 age, and the headers and namelink are expected to be in the de‐
10087 velopment package.
10088 See the VERSION and SOVERSION target properties for details on
10090 creating versioned shared libraries.
10091 NAMELINK_ONLY
10093 This option causes the installation of only the namelink when a
10094 library target is installed. On platforms where versioned shared
10095 libraries do not have namelinks or when a library is not ver‐
10096 sioned, the NAMELINK_ONLY option installs nothing. It is an er‐
10097 ror to use this parameter outside of a LIBRARY block.
10098 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
10100 NENT may be used to specify the installation component of the
10101 namelink, but COMPONENT should generally be preferred.
10102 NAMELINK_SKIP
10104 Similar to NAMELINK_ONLY, but it has the opposite effect: it
10105 causes the installation of library files other than the namelink
10106 when a library target is installed. When neither NAMELINK_ONLY
10107 or NAMELINK_SKIP are given, both portions are installed. On
10108 platforms where versioned shared libraries do not have symlinks
10109 or when a library is not versioned, NAMELINK_SKIP installs the
10110 library. It is an error to use this parameter outside of a LI‐
10111 BRARY block.
10112 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
10114 It is not recommended to use NAMELINK_SKIP in conjunction with
10115 NAMELINK_COMPONENT.
10116 The install(TARGETS) command can also accept the following options at
10118 the top level:
10119 EXPORT This option associates the installed target files with an export
10121 called <export-name>. It must appear before any target options.
10122 To actually install the export file itself, call
10123 install(EXPORT), documented below. See documentation of the
10124 EXPORT_NAME target property to change the name of the exported
10125 target.
10126 If EXPORT is used and the targets include PUBLIC or INTERFACE
10128 file sets, all of them must be specified with FILE_SET argu‐
10129 ments. All PUBLIC or INTERFACE file sets associated with a tar‐
10130 get are included in the export.
10131 INCLUDES DESTINATION
10133 This option specifies a list of directories which will be added
10134 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
10135 <targets> when exported by the install(EXPORT) command. If a
10136 relative path is specified, it is treated as relative to the
10137 $<INSTALL_PREFIX>.
10138 RUNTIME_DEPENDENCY_SET
10140 New in version 3.21.
10141 This option causes all runtime dependencies of installed exe‐
10144 cutable, shared library, and module targets to be added to the
10145 specified runtime dependency set. This set can then be installed
10146 with an install(RUNTIME_DEPENDENCY_SET) command.
10147 This keyword and the RUNTIME_DEPENDENCIES keyword are mutually
10149 exclusive.
10150 RUNTIME_DEPENDENCIES
10152 New in version 3.21.
10153 This option causes all runtime dependencies of installed exe‐
10156 cutable, shared library, and module targets to be installed
10157 along with the targets themselves. The RUNTIME, LIBRARY, FRAME‐
10158 WORK, and generic arguments are used to determine the properties
10159 (DESTINATION, COMPONENT, etc.) of the installation of these de‐
10160 pendencies.
10161 RUNTIME_DEPENDENCIES is semantically equivalent to the following
10163 pair of calls:
10164 install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
10166 install(RUNTIME_DEPENDENCY_SET <set-name> args...)
10167 where <set-name> will be a randomly generated set name. The
10169 args... may include any of the following keywords supported by
10170 the install(RUNTIME_DEPENDENCY_SET) command:
10171 • DIRECTORIES
10173 • PRE_INCLUDE_REGEXES
10175 • PRE_EXCLUDE_REGEXES
10177 • POST_INCLUDE_REGEXES
10179 • POST_EXCLUDE_REGEXES
10181 • POST_INCLUDE_FILES
10183 • POST_EXCLUDE_FILES
10185 The RUNTIME_DEPENDENCIES and RUNTIME_DEPENDENCY_SET keywords are
10187 mutually exclusive.
10188 One or more groups of properties may be specified in a single call to
10190 the TARGETS form of this command. A target may be installed more than
10191 once to different locations. Consider hypothetical targets myExe,
10192 mySharedLib, and myStaticLib. The code:
10193 install(TARGETS myExe mySharedLib myStaticLib
10195 RUNTIME DESTINATION bin
10196 LIBRARY DESTINATION lib
10197 ARCHIVE DESTINATION lib/static)
10198 install(TARGETS mySharedLib DESTINATION /some/full/path)
10199 will install myExe to <prefix>/bin and myStaticLib to <pre‐
10201 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
10202 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
10203 will be installed to <prefix>/bin and /some/full/path and its import
10204 library will be installed to <prefix>/lib/static and /some/full/path.
10205 Interface Libraries may be listed among the targets to install. They
10207 install no artifacts but will be included in an associated EXPORT. If
10208 Object Libraries are listed but given no destination for their object
10209 files, they will be exported as Interface Libraries. This is suffi‐
10210 cient to satisfy transitive usage requirements of other targets that
10211 link to the object libraries in their implementation.
10212 Installing a target with the EXCLUDE_FROM_ALL target property set to
10214 TRUE has undefined behavior.
10215 New in version 3.3: An install destination given as a DESTINATION argu‐
10217 ment may use "generator expressions" with the syntax $<...>. See the
10218 cmake-generator-expressions(7) manual for available expressions.
10219 New in version 3.13: install(TARGETS) can install targets that were
10222 created in other directories. When using such cross-directory install
10223 rules, running make install (or similar) from a subdirectory will not
10224 guarantee that targets from other directories are up-to-date. You can
10225 use target_link_libraries() or add_dependencies() to ensure that such
10226 out-of-directory targets are built before the subdirectory-specific in‐
10227 stall rules are run.
10228 Installing Imported Runtime Artifacts
10231 New in version 3.21.
10232 install(IMPORTED_RUNTIME_ARTIFACTS targets...
10235 [RUNTIME_DEPENDENCY_SET <set-name>]
10236 [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
10237 [DESTINATION <dir>]
10238 [PERMISSIONS permissions...]
10239 [CONFIGURATIONS [Debug|Release|...]]
10240 [COMPONENT <component>]
10241 [OPTIONAL] [EXCLUDE_FROM_ALL]
10242 ] [...]
10243 )
10244 The IMPORTED_RUNTIME_ARTIFACTS form specifies rules for installing the
10246 runtime artifacts of imported targets. Projects may do this if they
10247 want to bundle outside executables or modules inside their installa‐
10248 tion. The LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE arguments have the
10249 same semantics that they do in the TARGETS mode. Only the runtime arti‐
10250 facts of imported targets are installed (except in the case of
10251 FRAMEWORK libraries, MACOSX_BUNDLE executables, and BUNDLE CFBundles.)
10252 For example, headers and import libraries associated with DLLs are not
10253 installed. In the case of FRAMEWORK libraries, MACOSX_BUNDLE executa‐
10254 bles, and BUNDLE CFBundles, the entire directory is installed.
10255 The RUNTIME_DEPENDENCY_SET option causes the runtime artifacts of the
10257 imported executable, shared library, and module library targets to be
10258 added to the <set-name> runtime dependency set. This set can then be
10259 installed with an install(RUNTIME_DEPENDENCY_SET) command.
10260 Installing Files
10262 NOTE:
10263 If installing header files, consider using file sets defined by
10264 target_sources(FILE_SET) instead. File sets associate headers with a
10265 target and they install as part of the target.
10266 install(<FILES|PROGRAMS> files...
10268 TYPE <type> | DESTINATION <dir>
10269 [PERMISSIONS permissions...]
10270 [CONFIGURATIONS [Debug|Release|...]]
10271 [COMPONENT <component>]
10272 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
10273 The FILES form specifies rules for installing files for a project.
10275 File names given as relative paths are interpreted with respect to the
10276 current source directory. Files installed by this form are by default
10277 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
10278 if no PERMISSIONS argument is given.
10279 The PROGRAMS form is identical to the FILES form except that the de‐
10281 fault permissions for the installed file also include OWNER_EXECUTE,
10282 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
10283 programs that are not targets, such as shell scripts. Use the TARGETS
10284 form to install targets built within the project.
10285 The list of files... given to FILES or PROGRAMS may use "generator ex‐
10287 pressions" with the syntax $<...>. See the
10288 cmake-generator-expressions(7) manual for available expressions. How‐
10289 ever, if any item begins in a generator expression it must evaluate to
10290 a full path.
10291 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
10293 argument specifies the generic file type of the files being installed.
10294 A destination will then be set automatically by taking the correspond‐
10295 ing variable from GNUInstallDirs, or by using a built-in default if
10296 that variable is not defined. See the table below for the supported
10297 file types and their corresponding variables and built-in defaults.
10298 Projects can provide a DESTINATION argument instead of a file type if
10299 they wish to explicitly define the install destination.
10300 ┌──────────────┬─────────────────────┬─────────────────────┐
10302 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
10303 │ │ Variable │ │
10304 ├──────────────┼─────────────────────┼─────────────────────┤
10305 │BIN │ ${CMAKE_IN‐ │ bin │
10306 │ │ STALL_BINDIR} │ │
10307 ├──────────────┼─────────────────────┼─────────────────────┤
10308 │SBIN │ ${CMAKE_IN‐ │ sbin │
10309 │ │ STALL_SBINDIR} │ │
10310 ├──────────────┼─────────────────────┼─────────────────────┤
10311 │LIB │ ${CMAKE_IN‐ │ lib │
10312 │ │ STALL_LIBDIR} │ │
10313 ├──────────────┼─────────────────────┼─────────────────────┤
10314 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
10315 │ │ CLUDEDIR} │ │
10316 ├──────────────┼─────────────────────┼─────────────────────┤
10317 │SYSCONF │ ${CMAKE_IN‐ │ etc │
10318 │ │ STALL_SYSCONFDIR} │ │
10319 ├──────────────┼─────────────────────┼─────────────────────┤
10320 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
10321 │ │ STALL_SHARESTATE‐ │ │
10322 │ │ DIR} │ │
10323 ├──────────────┼─────────────────────┼─────────────────────┤
10324 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
10325 │ │ CALSTATEDIR} │ │
10326 ├──────────────┼─────────────────────┼─────────────────────┤
10327 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
10328 │ │ STALL_RUNSTATEDIR} │ dir>/run │
10329 ├──────────────┼─────────────────────┼─────────────────────┤
10330 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
10331 │ │ STALL_DATADIR} │ │
10332 ├──────────────┼─────────────────────┼─────────────────────┤
10333 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
10334 │ │ FODIR} │ │
10335 ├──────────────┼─────────────────────┼─────────────────────┤
10336 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
10337 │ │ CALEDIR} │ cale │
10338 ├──────────────┼─────────────────────┼─────────────────────┤
10339 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
10340 │ │ STALL_MANDIR} │ │
10341 ├──────────────┼─────────────────────┼─────────────────────┤
10342 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
10343 │ │ STALL_DOCDIR} │ │
10344 └──────────────┴─────────────────────┴─────────────────────┘
10345 Projects wishing to follow the common practice of installing headers
10347 into a project-specific subdirectory will need to provide a destination
10348 rather than rely on the above. Using file sets for headers instead of
10349 install(FILES) would be even better (see target_sources(FILE_SET)).
10350 Note that some of the types' built-in defaults use the DATAROOT direc‐
10352 tory as a prefix. The DATAROOT prefix is calculated similarly to the
10353 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
10354 built-in default. You cannot use DATAROOT as a TYPE parameter; please
10355 use DATA instead.
10356 To make packages compliant with distribution filesystem layout poli‐
10358 cies, if projects must specify a DESTINATION, it is recommended that
10359 they use a path that begins with the appropriate GNUInstallDirs vari‐
10360 able. This allows package maintainers to control the install destina‐
10361 tion by setting the appropriate cache variables. The following example
10362 shows how to follow this advice while installing an image to a
10363 project-specific documentation subdirectory:
10364 include(GNUInstallDirs)
10366 install(FILES logo.png
10367 DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
10368 )
10369 New in version 3.4: An install destination given as a DESTINATION argu‐
10371 ment may use "generator expressions" with the syntax $<...>. See the
10372 cmake-generator-expressions(7) manual for available expressions.
10373 New in version 3.20: An install rename given as a RENAME argument may
10376 use "generator expressions" with the syntax $<...>. See the
10377 cmake-generator-expressions(7) manual for available expressions.
10378 Installing Directories
10381 NOTE:
10382 To install a directory sub-tree of headers, consider using file sets
10383 defined by target_sources(FILE_SET) instead. File sets not only pre‐
10384 serve directory structure, they also associate headers with a target
10385 and install as part of the target.
10386 install(DIRECTORY dirs...
10388 TYPE <type> | DESTINATION <dir>
10389 [FILE_PERMISSIONS permissions...]
10390 [DIRECTORY_PERMISSIONS permissions...]
10391 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
10392 [CONFIGURATIONS [Debug|Release|...]]
10393 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
10394 [FILES_MATCHING]
10395 [[PATTERN <pattern> | REGEX <regex>]
10396 [EXCLUDE] [PERMISSIONS permissions...]] [...])
10397 The DIRECTORY form installs contents of one or more directories to a
10399 given destination. The directory structure is copied verbatim to the
10400 destination. The last component of each directory name is appended to
10401 the destination directory but a trailing slash may be used to avoid
10402 this because it leaves the last component empty. Directory names given
10403 as relative paths are interpreted with respect to the current source
10404 directory. If no input directory names are given the destination di‐
10405 rectory will be created but nothing will be installed into it. The
10406 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
10407 given to files and directories in the destination. If USE_SOURCE_PER‐
10408 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
10409 will be copied from the source directory structure. If no permissions
10410 are specified files will be given the default permissions specified in
10411 the FILES form of the command, and the directories will be given the
10412 default permissions specified in the PROGRAMS form of the command.
10413 New in version 3.1: The MESSAGE_NEVER option disables file installation
10415 status output.
10416 Installation of directories may be controlled with fine granularity us‐
10419 ing the PATTERN or REGEX options. These "match" options specify a
10420 globbing pattern or regular expression to match directories or files
10421 encountered within input directories. They may be used to apply cer‐
10422 tain options (see below) to a subset of the files and directories en‐
10423 countered. The full path to each input file or directory (with forward
10424 slashes) is matched against the expression. A PATTERN will match only
10425 complete file names: the portion of the full path matching the pattern
10426 must occur at the end of the file name and be preceded by a slash. A
10427 REGEX will match any portion of the full path but it may use / and $ to
10428 simulate the PATTERN behavior. By default all files and directories
10429 are installed whether or not they are matched. The FILES_MATCHING op‐
10430 tion may be given before the first match option to disable installation
10431 of files (but not directories) not matched by any expression. For ex‐
10432 ample, the code
10433 install(DIRECTORY src/ DESTINATION doc/myproj
10435 FILES_MATCHING PATTERN "*.png")
10436 will extract and install images from a source tree.
10438 Some options may follow a PATTERN or REGEX expression as described un‐
10440 der string(REGEX) and are applied only to files or directories matching
10441 them. The EXCLUDE option will skip the matched file or directory. The
10442 PERMISSIONS option overrides the permissions setting for the matched
10443 file or directory. For example the code
10444 install(DIRECTORY icons scripts/ DESTINATION share/myproj
10446 PATTERN "CVS" EXCLUDE
10447 PATTERN "scripts/*"
10448 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
10449 GROUP_EXECUTE GROUP_READ)
10450 will install the icons directory to share/myproj/icons and the scripts
10452 directory to share/myproj. The icons will get default file permis‐
10453 sions, the scripts will be given specific permissions, and any CVS di‐
10454 rectories will be excluded.
10455 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
10457 argument specifies the generic file type of the files within the listed
10458 directories being installed. A destination will then be set automati‐
10459 cally by taking the corresponding variable from GNUInstallDirs, or by
10460 using a built-in default if that variable is not defined. See the ta‐
10461 ble below for the supported file types and their corresponding vari‐
10462 ables and built-in defaults. Projects can provide a DESTINATION argu‐
10463 ment instead of a file type if they wish to explicitly define the in‐
10464 stall destination.
10465 ┌──────────────┬─────────────────────┬─────────────────────┐
10467 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
10468 │ │ Variable │ │
10469 ├──────────────┼─────────────────────┼─────────────────────┤
10470 │BIN │ ${CMAKE_IN‐ │ bin │
10471 │ │ STALL_BINDIR} │ │
10472 ├──────────────┼─────────────────────┼─────────────────────┤
10473 │SBIN │ ${CMAKE_IN‐ │ sbin │
10474 │ │ STALL_SBINDIR} │ │
10475 ├──────────────┼─────────────────────┼─────────────────────┤
10476 │LIB │ ${CMAKE_IN‐ │ lib │
10477 │ │ STALL_LIBDIR} │ │
10478 ├──────────────┼─────────────────────┼─────────────────────┤
10479 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
10480 │ │ CLUDEDIR} │ │
10481 ├──────────────┼─────────────────────┼─────────────────────┤
10482 │SYSCONF │ ${CMAKE_IN‐ │ etc │
10483 │ │ STALL_SYSCONFDIR} │ │
10484 ├──────────────┼─────────────────────┼─────────────────────┤
10485 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
10486 │ │ STALL_SHARESTATE‐ │ │
10487 │ │ DIR} │ │
10488 ├──────────────┼─────────────────────┼─────────────────────┤
10489 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
10490 │ │ CALSTATEDIR} │ │
10491 ├──────────────┼─────────────────────┼─────────────────────┤
10492 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
10493 │ │ STALL_RUNSTATEDIR} │ dir>/run │
10494 ├──────────────┼─────────────────────┼─────────────────────┤
10495 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
10496 │ │ STALL_DATADIR} │ │
10497 ├──────────────┼─────────────────────┼─────────────────────┤
10498 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
10499 │ │ FODIR} │ │
10500 ├──────────────┼─────────────────────┼─────────────────────┤
10501 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
10502 │ │ CALEDIR} │ cale │
10503 ├──────────────┼─────────────────────┼─────────────────────┤
10504 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
10505 │ │ STALL_MANDIR} │ │
10506 ├──────────────┼─────────────────────┼─────────────────────┤
10507 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
10508 │ │ STALL_DOCDIR} │ │
10509 └──────────────┴─────────────────────┴─────────────────────┘
10510 Note that some of the types' built-in defaults use the DATAROOT direc‐
10512 tory as a prefix. The DATAROOT prefix is calculated similarly to the
10513 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
10514 built-in default. You cannot use DATAROOT as a TYPE parameter; please
10515 use DATA instead.
10516 To make packages compliant with distribution filesystem layout poli‐
10518 cies, if projects must specify a DESTINATION, it is recommended that
10519 they use a path that begins with the appropriate GNUInstallDirs vari‐
10520 able. This allows package maintainers to control the install destina‐
10521 tion by setting the appropriate cache variables.
10522 New in version 3.4: An install destination given as a DESTINATION argu‐
10524 ment may use "generator expressions" with the syntax $<...>. See the
10525 cmake-generator-expressions(7) manual for available expressions.
10526 New in version 3.5: The list of dirs... given to DIRECTORY may use
10529 "generator expressions" too.
10530 Custom Installation Logic
10533 install([[SCRIPT <file>] [CODE <code>]]
10534 [ALL_COMPONENTS | COMPONENT <component>]
10535 [EXCLUDE_FROM_ALL] [...])
10536 The SCRIPT form will invoke the given CMake script files during instal‐
10538 lation. If the script file name is a relative path it will be inter‐
10539 preted with respect to the current source directory. The CODE form
10540 will invoke the given CMake code during installation. Code is speci‐
10541 fied as a single argument inside a double-quoted string. For example,
10542 the code
10543 install(CODE "MESSAGE(\"Sample install message.\")")
10545 will print a message during installation.
10547 New in version 3.21: When the ALL_COMPONENTS option is given, the cus‐
10549 tom installation script code will be executed for every component of a
10550 component-specific installation. This option is mutually exclusive
10551 with the COMPONENT option.
10552 New in version 3.14: <file> or <code> may use "generator expressions"
10555 with the syntax $<...> (in the case of <file>, this refers to their use
10556 in the file name, not the file's contents). See the
10557 cmake-generator-expressions(7) manual for available expressions.
10558 Installing Exports
10561 install(EXPORT <export-name> DESTINATION <dir>
10562 [NAMESPACE <namespace>] [FILE <name>.cmake]
10563 [PERMISSIONS permissions...]
10564 [CONFIGURATIONS [Debug|Release|...]
10565 [CXX_MODULES_DIRECTORY <directory>]
10566 [EXPORT_LINK_INTERFACE_LIBRARIES]
10567 [COMPONENT <component>]
10568 [EXCLUDE_FROM_ALL])
10569 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
10570 The EXPORT form generates and installs a CMake file containing code to
10572 import targets from the installation tree into another project. Target
10573 installations are associated with the export <export-name> using the
10574 EXPORT option of the install(TARGETS) signature documented above. The
10575 NAMESPACE option will prepend <namespace> to the target names as they
10576 are written to the import file. By default the generated file will be
10577 called <export-name>.cmake but the FILE option may be used to specify a
10578 different name. The value given to the FILE option must be a file name
10579 with the .cmake extension. If a CONFIGURATIONS option is given then
10580 the file will only be installed when one of the named configurations is
10581 installed. Additionally, the generated import file will reference only
10582 the matching target configurations. The EXPORT_LINK_INTERFACE_LI‐
10583 BRARIES keyword, if present, causes the contents of the properties
10584 matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be ex‐
10585 ported, when policy CMP0022 is NEW.
10586 NOTE:
10588 The installed <export-name>.cmake file may come with additional
10589 per-configuration <export-name>-*.cmake files to be loaded by glob‐
10590 bing. Do not use an export name that is the same as the package
10591 name in combination with installing a <package-name>-config.cmake
10592 file or the latter may be incorrectly matched by the glob and
10593 loaded.
10594 When a COMPONENT option is given, the listed <component> implicitly de‐
10596 pends on all components mentioned in the export set. The exported
10597 <name>.cmake file will require each of the exported components to be
10598 present in order for dependent projects to build properly. For example,
10599 a project may define components Runtime and Development, with shared
10600 libraries going into the Runtime component and static libraries and
10601 headers going into the Development component. The export set would also
10602 typically be part of the Development component, but it would export
10603 targets from both the Runtime and Development components. Therefore,
10604 the Runtime component would need to be installed if the Development
10605 component was installed, but not vice versa. If the Development compo‐
10606 nent was installed without the Runtime component, dependent projects
10607 that try to link against it would have build errors. Package managers,
10608 such as APT and RPM, typically handle this by listing the Runtime com‐
10609 ponent as a dependency of the Development component in the package
10610 metadata, ensuring that the library is always installed if the headers
10611 and CMake export file are present.
10612 New in version 3.7: In addition to cmake language files, the EXPORT_AN‐
10614 DROID_MK mode may be used to specify an export to the android ndk build
10615 system. This mode accepts the same options as the normal export mode.
10616 The Android NDK supports the use of prebuilt libraries, both static and
10617 shared. This allows cmake to build the libraries of a project and make
10618 them available to an ndk build system complete with transitive depen‐
10619 dencies, include flags and defines required to use the libraries.
10620 CXX_MODULES_DIRECTORY
10623 NOTE:
10625 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
10626 Specify a subdirectory to store C++ module information for targets
10628 in the export set. This directory will be populated with files which
10629 add the necessary target property information to the relevant tar‐
10630 gets. Note that without this information, none of the C++ modules
10631 which are part of the targets in the export set will support being
10632 imported in consuming targets.
10633 The EXPORT form is useful to help outside projects use targets built
10635 and installed by the current project. For example, the code
10636 install(TARGETS myexe EXPORT myproj DESTINATION bin)
10638 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
10639 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
10640 will install the executable myexe to <prefix>/bin and code to import it
10642 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
10643 fix>/share/ndk-modules/Android.mk. An outside project may load this
10644 file with the include command and reference the myexe executable from
10645 the installation tree using the imported target name mp_myexe as if the
10646 target were built in its own tree.
10647 NOTE:
10649 This command supersedes the install_targets() command and the
10650 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
10651 also replaces the FILES forms of the install_files() and
10652 install_programs() commands. The processing order of these install
10653 rules relative to those generated by install_targets(),
10654 install_files(), and install_programs() commands is not defined.
10655 Installing Runtime Dependencies
10657 New in version 3.21.
10658 install(RUNTIME_DEPENDENCY_SET <set-name>
10661 [[LIBRARY|RUNTIME|FRAMEWORK]
10662 [DESTINATION <dir>]
10663 [PERMISSIONS permissions...]
10664 [CONFIGURATIONS [Debug|Release|...]]
10665 [COMPONENT <component>]
10666 [NAMELINK_COMPONENT <component>]
10667 [OPTIONAL] [EXCLUDE_FROM_ALL]
10668 ] [...]
10669 [PRE_INCLUDE_REGEXES regexes...]
10670 [PRE_EXCLUDE_REGEXES regexes...]
10671 [POST_INCLUDE_REGEXES regexes...]
10672 [POST_EXCLUDE_REGEXES regexes...]
10673 [POST_INCLUDE_FILES files...]
10674 [POST_EXCLUDE_FILES files...]
10675 [DIRECTORIES directories...]
10676 )
10677 Installs a runtime dependency set previously created by one or more
10679 install(TARGETS) or install(IMPORTED_RUNTIME_ARTIFACTS) commands. The
10680 dependencies of targets belonging to a runtime dependency set are in‐
10681 stalled in the RUNTIME destination and component on DLL platforms, and
10682 in the LIBRARY destination and component on non-DLL platforms. macOS
10683 frameworks are installed in the FRAMEWORK destination and component.
10684 Targets built within the build tree will never be installed as runtime
10685 dependencies, nor will their own dependencies, unless the targets them‐
10686 selves are installed with install(TARGETS).
10687 The generated install script calls file(GET_RUNTIME_DEPENDENCIES) on
10689 the build-tree files to calculate the runtime dependencies. The
10690 build-tree executable files are passed as the EXECUTABLES argument, the
10691 build-tree shared libraries as the LIBRARIES argument, and the
10692 build-tree modules as the MODULES argument. On macOS, if one of the ex‐
10693 ecutables is a MACOSX_BUNDLE, that executable is passed as the BUN‐
10694 DLE_EXECUTABLE argument. At most one such bundle executable may be in
10695 the runtime dependency set on macOS. The MACOSX_BUNDLE property has no
10696 effect on other platforms. Note that file(GET_RUNTIME_DEPENDENCIES)
10697 only supports collecting the runtime dependencies for Windows, Linux
10698 and macOS platforms, so install(RUNTIME_DEPENDENCY_SET) has the same
10699 limitation.
10700 The following sub-arguments are forwarded through as the corresponding
10702 arguments to file(GET_RUNTIME_DEPENDENCIES) (for those that provide a
10703 non-empty list of directories, regular expressions or files). They all
10704 support generator expressions.
10705 • DIRECTORIES <directories>
10707 • PRE_INCLUDE_REGEXES <regexes>
10709 • PRE_EXCLUDE_REGEXES <regexes>
10711 • POST_INCLUDE_REGEXES <regexes>
10713 • POST_EXCLUDE_REGEXES <regexes>
10715 • POST_INCLUDE_FILES <files>
10717 • POST_EXCLUDE_FILES <files>
10719 Generated Installation Script
10721 NOTE:
10722 Use of this feature is not recommended. Please consider using the
10723 cmake --install instead.
10724 The install() command generates a file, cmake_install.cmake, inside the
10726 build directory, which is used internally by the generated install tar‐
10727 get and by CPack. You can also invoke this script manually with cmake
10728 -P. This script accepts several variables:
10729 COMPONENT
10731 Set this variable to install only a single CPack component as
10732 opposed to all of them. For example, if you only want to install
10733 the Development component, run cmake -DCOMPONENT=Development -P
10734 cmake_install.cmake.
10735 BUILD_TYPE
10737 Set this variable to change the build type if you are using a
10738 multi-config generator. For example, to install with the Debug
10739 configuration, run cmake -DBUILD_TYPE=Debug -P cmake_in‐
10740 stall.cmake.
10741 DESTDIR
10743 This is an environment variable rather than a CMake variable. It
10744 allows you to change the installation prefix on UNIX systems.
10745 See DESTDIR for details.
10746 link_directories
10748 Add directories in which the linker will look for libraries.
10749 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
10751 Adds the paths in which the linker should search for libraries. Rela‐
10753 tive paths given to this command are interpreted as relative to the
10754 current source directory, see CMP0015.
10755 The command will apply only to targets created after it is called.
10757 New in version 3.13: The directories are added to the LINK_DIRECTORIES
10759 directory property for the current CMakeLists.txt file, converting rel‐
10760 ative paths to absolute as needed. See the cmake-buildsystem(7) manual
10761 for more on defining buildsystem properties.
10762 New in version 3.13: By default the directories specified are appended
10765 onto the current list of directories. This default behavior can be
10766 changed by setting CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER
10767 or BEFORE explicitly, you can select between appending and prepending,
10768 independent of the default.
10769 New in version 3.13: Arguments to link_directories may use "generator
10772 expressions" with the syntax "$<...>". See the
10773 cmake-generator-expressions(7) manual for available expressions.
10774 NOTE:
10777 This command is rarely necessary and should be avoided where there
10778 are other choices. Prefer to pass full absolute paths to libraries
10779 where possible, since this ensures the correct library will always
10780 be linked. The find_library() command provides the full path, which
10781 can generally be used directly in calls to target_link_libraries().
10782 Situations where a library search path may be needed include:
10783 • Project generators like Xcode where the user can switch target ar‐
10785 chitecture at build time, but a full path to a library cannot be
10786 used because it only provides one architecture (i.e. it is not a
10787 universal binary).
10788 • Libraries may themselves have other private library dependencies
10790 that expect to be found via RPATH mechanisms, but some linkers are
10791 not able to fully decode those paths (e.g. due to the presence of
10792 things like $ORIGIN).
10793 If a library search path must be provided, prefer to localize the
10795 effect where possible by using the target_link_directories() command
10796 rather than link_directories(). The target-specific command can
10797 also control how the search directories propagate to other dependent
10798 targets.
10799 link_libraries
10801 Link libraries to all targets added later.
10802 link_libraries([item1 [item2 [...]]]
10804 [[debug|optimized|general] <item>] ...)
10805 Specify libraries or flags to use when linking any targets created
10807 later in the current directory or below by commands such as
10808 add_executable() or add_library(). See the target_link_libraries()
10809 command for meaning of arguments.
10810 NOTE:
10812 The target_link_libraries() command should be preferred whenever
10813 possible. Library dependencies are chained automatically, so direc‐
10814 tory-wide specification of link libraries is rarely needed.
10815 load_cache
10817 Load in the values from another project's CMake cache.
10818 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
10820 Reads the cache and store the requested entries in variables with their
10822 name prefixed with the given prefix. This only reads the values, and
10823 does not create entries in the local project's cache.
10824 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
10826 [INCLUDE_INTERNALS entry1...])
10827 Loads in the values from another cache and store them in the local
10829 project's cache as internal entries. This is useful for a project that
10830 depends on another project built in a different tree. EXCLUDE option
10831 can be used to provide a list of entries to be excluded. INCLUDE_IN‐
10832 TERNALS can be used to provide a list of internal entries to be in‐
10833 cluded. Normally, no internal entries are brought in. Use of this
10834 form of the command is strongly discouraged, but it is provided for
10835 backward compatibility.
10836 project
10838 Set the name of the project.
10839 Synopsis
10841 project(<PROJECT-NAME> [<language-name>...])
10842 project(<PROJECT-NAME>
10843 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
10844 [DESCRIPTION <project-description-string>]
10845 [HOMEPAGE_URL <url-string>]
10846 [LANGUAGES <language-name>...])
10847 Sets the name of the project, and stores it in the variable
10849 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
10850 the project name in the variable CMAKE_PROJECT_NAME.
10851 Also sets the variables:
10853 PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
10855 Absolute path to the source directory for the project.
10856 PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
10858 Absolute path to the binary directory for the project.
10859 PROJECT_IS_TOP_LEVEL, <PROJECT-NAME>_IS_TOP_LEVEL
10861 New in version 3.21.
10862 Boolean value indicating whether the project is top-level.
10865 Further variables are set by the optional arguments described in the
10867 following. If any of these arguments is not used, then the correspond‐
10868 ing variables are set to the empty string.
10869 Options
10871 The options are:
10872 VERSION <version>
10874 Optional; may not be used unless policy CMP0048 is set to NEW.
10875 Takes a <version> argument composed of non-negative integer com‐
10877 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
10878 the variables
10879 • PROJECT_VERSION, <PROJECT-NAME>_VERSION
10881 • PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
10883 • PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
10885 • PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
10887 • PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
10889 New in version 3.12: When the project() command is called from
10891 the top-level CMakeLists.txt, then the version is also stored in
10892 the variable CMAKE_PROJECT_VERSION.
10893 DESCRIPTION <project-description-string>
10896 New in version 3.9.
10897 Optional. Sets the variables
10900 • PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
10902 to <project-description-string>. It is recommended that this
10904 description is a relatively short string, usually no more than a
10905 few words.
10906 When the project() command is called from the top-level CMake‐
10908 Lists.txt, then the description is also stored in the variable
10909 CMAKE_PROJECT_DESCRIPTION.
10910 New in version 3.12: Added the <PROJECT-NAME>_DESCRIPTION vari‐
10912 able.
10913 HOMEPAGE_URL <url-string>
10916 New in version 3.12.
10917 Optional. Sets the variables
10920 • PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
10922 to <url-string>, which should be the canonical home URL for the
10924 project.
10925 When the project() command is called from the top-level CMake‐
10927 Lists.txt, then the URL also is stored in the variable
10928 CMAKE_PROJECT_HOMEPAGE_URL.
10929 LANGUAGES <language-name>...
10931 Optional. Can also be specified without LANGUAGES keyword per
10932 the first, short signature.
10933 Selects which programming languages are needed to build the
10935 project. Supported languages include C, CXX (i.e. C++), CUDA,
10936 OBJC (i.e. Objective-C), OBJCXX, Fortran, HIP, ISPC, and ASM.
10937 By default C and CXX are enabled if no language options are
10938 given. Specify language NONE, or use the LANGUAGES keyword and
10939 list no languages, to skip enabling any languages.
10940 New in version 3.8: Added CUDA support.
10942 New in version 3.16: Added OBJC and OBJCXX support.
10945 New in version 3.18: Added ISPC support.
10948 If enabling ASM, list it last so that CMake can check whether
10951 compilers for other languages like C work for assembly too.
10952 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL op‐
10954 tions are intended for use as default values in package metadata and
10955 documentation.
10956 Code Injection
10958 A number of variables can be defined by the user to specify files to
10959 include at different points during the execution of the project() com‐
10960 mand. The following outlines the steps performed during a project()
10961 call:
10962 • New in version 3.15: For every project() call regardless of the
10964 project name, include the file named by CMAKE_PROJECT_INCLUDE_BEFORE,
10965 if set.
10966 • New in version 3.17: If the project() command specifies
10969 <PROJECT-NAME> as its project name, include the file named by
10970 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, if set.
10971 • Set the various project-specific variables detailed in the Synopsis
10974 and Options sections above.
10975 • For the very first project() call only:
10977 • If CMAKE_TOOLCHAIN_FILE is set, read it at least once. It may be
10979 read multiple times and it may also be read again when enabling
10980 languages later (see below).
10981 • Set the variables describing the host and target platforms. Lan‐
10983 guage-specific variables might or might not be set at this point.
10984 On the first run, the only language-specific variables that might
10985 be defined are those a toolchain file may have set. On subsequent
10986 runs, language-specific variables cached from a previous run may be
10987 set.
10988 • New in version 3.24: Include each file listed in
10990 CMAKE_PROJECT_TOP_LEVEL_INCLUDES, if set. The variable is ignored
10991 by CMake thereafter.
10992 • Enable any languages specified in the call, or the default languages
10995 if none were provided. The toolchain file may be re-read when en‐
10996 abling a language for the first time.
10997 • New in version 3.15: For every project() call regardless of the
10999 project name, include the file named by CMAKE_PROJECT_INCLUDE, if
11000 set.
11001 • If the project() command specifies <PROJECT-NAME> as its project
11004 name, include the file named by CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
11005 if set.
11006 Usage
11008 The top-level CMakeLists.txt file for a project must contain a literal,
11009 direct call to the project() command; loading one through the include()
11010 command is not sufficient. If no such call exists, CMake will issue a
11011 warning and pretend there is a project(Project) at the top to enable
11012 the default languages (C and CXX).
11013 NOTE:
11015 Call the project() command near the top of the top-level CMake‐
11016 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
11017 tant to establish version and policy settings before invoking other
11018 commands whose behavior they may affect. See also policy CMP0000.
11019 remove_definitions
11021 Remove -D define flags added by add_definitions().
11022 remove_definitions(-DFOO -DBAR ...)
11024 Removes flags (added by add_definitions()) from the compiler command
11026 line for sources in the current directory and below.
11027 set_source_files_properties
11029 Source files can have properties that affect how they are built.
11030 set_source_files_properties(<files> ...
11032 [DIRECTORY <dirs> ...]
11033 [TARGET_DIRECTORY <targets> ...]
11034 PROPERTIES <prop1> <value1>
11035 [<prop2> <value2>] ...)
11036 Sets properties associated with source files using a key/value paired
11038 list.
11039 New in version 3.18: By default, source file properties are only visi‐
11041 ble to targets added in the same directory (CMakeLists.txt). Visibil‐
11042 ity can be set in other directory scopes using one or both of the fol‐
11043 lowing options:
11044 DIRECTORY <dirs>...
11047 The source file properties will be set in each of the <dirs> di‐
11048 rectories' scopes. CMake must already know about each of these
11049 source directories, either by having added them through a call
11050 to add_subdirectory() or it being the top level source direc‐
11051 tory. Relative paths are treated as relative to the current
11052 source directory.
11053 TARGET_DIRECTORY <targets>...
11055 The source file properties will be set in each of the directory
11056 scopes where any of the specified <targets> were created (the
11057 <targets> must therefore already exist).
11058 Use get_source_file_property() to get property values. See also the
11060 set_property(SOURCE) command.
11061 See Properties on Source Files for the list of properties known to
11063 CMake.
11064 NOTE:
11066 The GENERATED source file property may be globally visible. See its
11067 documentation for details.
11068 set_target_properties
11070 Targets can have properties that affect how they are built.
11071 set_target_properties(target1 target2 ...
11073 PROPERTIES prop1 value1
11074 prop2 value2 ...)
11075 Sets properties on targets. The syntax for the command is to list all
11077 the targets you want to change, and then provide the values you want to
11078 set next. You can use any prop value pair you want and extract it
11079 later with the get_property() or get_target_property() command.
11080 See also the set_property(TARGET) command.
11082 See Properties on Targets for the list of properties known to CMake.
11084 set_tests_properties
11086 Set a property of the tests.
11087 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
11089 Sets a property for the tests. If the test is not found, CMake will
11091 report an error.
11092 Test property values may be specified using generator expressions for
11094 tests created by the add_test(NAME) signature.
11095 See also the set_property(TEST) command.
11097 See Properties on Tests for the list of properties known to CMake.
11099 source_group
11101 Define a grouping for source files in IDE project generation. There
11102 are two different signatures to create source groups.
11103 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
11105 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
11106 Defines a group into which sources will be placed in project files.
11108 This is intended to set up file tabs in Visual Studio. The group is
11109 scoped in the directory where the command is called, and applies to
11110 sources in targets created in that directory.
11111 The options are:
11113 TREE New in version 3.8.
11115 CMake will automatically detect, from <src> files paths, source
11118 groups it needs to create, to keep structure of source groups
11119 analogically to the actual files and directories structure in
11120 the project. Paths of <src> files will be cut to be relative to
11121 <root>. The command fails if the paths within src do not start
11122 with root.
11123 PREFIX New in version 3.8.
11125 Source group and files located directly in <root> path, will be
11128 placed in <prefix> source groups.
11129 FILES Any source file specified explicitly will be placed in group
11131 <name>. Relative paths are interpreted with respect to the cur‐
11132 rent source directory.
11133 REGULAR_EXPRESSION
11135 Any source file whose name matches the regular expression will
11136 be placed in group <name>.
11137 If a source file matches multiple groups, the last group that explic‐
11139 itly lists the file with FILES will be favored, if any. If no group
11140 explicitly lists the file, the last group whose regular expression
11141 matches the file will be favored.
11142 The <name> of the group and <prefix> argument may contain forward
11144 slashes or backslashes to specify subgroups. Backslashes need to be
11145 escaped appropriately:
11146 source_group(base/subdir ...)
11148 source_group(outer\\inner ...)
11149 source_group(TREE <root> PREFIX sources\\inc ...)
11150 New in version 3.18: Allow using forward slashes (/) to specify sub‐
11152 groups.
11153 For backwards compatibility, the short-hand signature
11156 source_group(<name> <regex>)
11158 is equivalent to
11160 source_group(<name> REGULAR_EXPRESSION <regex>)
11162 target_compile_definitions
11164 Add compile definitions to a target.
11165 target_compile_definitions(<target>
11167 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11168 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11169 Specifies compile definitions to use when compiling a given <target>.
11171 The named <target> must have been created by a command such as
11172 add_executable() or add_library() and must not be an ALIAS target.
11173 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11175 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
11176 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
11177 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
11178 get>. The following arguments specify compile definitions. Repeated
11179 calls for the same <target> append items in the order called.
11180 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
11182 Arguments to target_compile_definitions may use "generator expressions"
11185 with the syntax $<...>. See the cmake-generator-expressions(7) manual
11186 for available expressions. See the cmake-buildsystem(7) manual for
11187 more on defining buildsystem properties.
11188 Any leading -D on an item will be removed. Empty items are ignored.
11190 For example, the following are all equivalent:
11191 target_compile_definitions(foo PUBLIC FOO)
11193 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
11194 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
11195 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
11196 Definitions may optionally have values:
11198 target_compile_definitions(foo PUBLIC FOO=1)
11200 Note that many compilers treat -DFOO as equivalent to -DFOO=1, but
11202 other tools may not recognize this in all circumstances (e.g. Intel‐
11203 liSense).
11204 target_compile_features
11206 New in version 3.1.
11207 Add expected compiler features to a target.
11210 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
11212 Specifies compiler features required when compiling a given target. If
11214 the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
11215 CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
11216 then an error will be reported by CMake. If the use of the feature re‐
11217 quires an additional compiler flag, such as -std=gnu++11, the flag will
11218 be added automatically.
11219 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11221 scope of the features. PRIVATE and PUBLIC items will populate the
11222 COMPILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
11223 populate the INTERFACE_COMPILE_FEATURES property of <target>. Repeated
11224 calls for the same <target> append items.
11225 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
11227 The named <target> must have been created by a command such as
11230 add_executable() or add_library() and must not be an ALIAS target.
11231 Arguments to target_compile_features may use "generator expressions"
11233 with the syntax $<...>. See the cmake-generator-expressions(7) manual
11234 for available expressions. See the cmake-compile-features(7) manual
11235 for information on compile features and a list of supported compilers.
11236 target_compile_options
11238 Add compile options to a target.
11239 target_compile_options(<target> [BEFORE]
11241 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11242 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11243 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
11245 properties. These options are used when compiling the given <target>,
11246 which must have been created by a command such as add_executable() or
11247 add_library() and must not be an ALIAS target.
11248 Arguments
11250 If BEFORE is specified, the content will be prepended to the property
11251 instead of being appended.
11252 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11254 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
11255 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
11256 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
11257 The following arguments specify compile options. Repeated calls for
11258 the same <target> append items in the order called.
11259 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
11261 Arguments to target_compile_options may use "generator expressions"
11264 with the syntax $<...>. See the cmake-generator-expressions(7) manual
11265 for available expressions. See the cmake-buildsystem(7) manual for
11266 more on defining buildsystem properties.
11267 Option De-duplication
11269 The final set of options used for a target is constructed by accumulat‐
11270 ing options from the current target and the usage requirements of its
11271 dependencies. The set of options is de-duplicated to avoid repetition.
11272 New in version 3.12: While beneficial for individual options, the
11274 de-duplication step can break up option groups. For example, -option A
11275 -option B becomes -option A B. One may specify a group of options us‐
11276 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
11277 is dropped, and the rest of the option string is parsed using the
11278 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
11279 "SHELL:-option B" becomes -option A -option B.
11280 See Also
11283 This command can be used to add any options. However, for adding pre‐
11284 processor definitions and include directories it is recommended to use
11285 the more specific commands target_compile_definitions() and
11286 target_include_directories().
11287 For directory-wide settings, there is the command
11289 add_compile_options().
11290 For file-specific settings, there is the source file property
11292 COMPILE_OPTIONS.
11293 target_include_directories
11295 Add include directories to a target.
11296 target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
11298 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11299 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11300 Specifies include directories to use when compiling a given target.
11302 The named <target> must have been created by a command such as
11303 add_executable() or add_library() and must not be an ALIAS target.
11304 By using AFTER or BEFORE explicitly, you can select between appending
11306 and prepending, independent of the default.
11307 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11309 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
11310 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTERFACE
11311 items will populate the INTERFACE_INCLUDE_DIRECTORIES property of <tar‐
11312 get>. The following arguments specify include directories.
11313 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
11315 Repeated calls for the same <target> append items in the order called.
11318 If SYSTEM is specified, the compiler will be told the directories are
11320 meant as system include directories on some platforms. This may have
11321 effects such as suppressing warnings or skipping the contained headers
11322 in dependency calculations (see compiler documentation). Additionally,
11323 system include directories are searched after normal include directo‐
11324 ries regardless of the order specified.
11325 If SYSTEM is used together with PUBLIC or INTERFACE, the
11327 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target property will be populated
11328 with the specified directories.
11329 Arguments to target_include_directories may use "generator expressions"
11331 with the syntax $<...>. See the cmake-generator-expressions(7) manual
11332 for available expressions. See the cmake-buildsystem(7) manual for
11333 more on defining buildsystem properties.
11334 Specified include directories may be absolute paths or relative paths.
11336 A relative path will be interpreted as relative to the current source
11337 directory (i.e. CMAKE_CURRENT_SOURCE_DIR) and converted to an absolute
11338 path before storing it in the associated target property. If the path
11339 starts with a generator expression, it will always be assumed to be an
11340 absolute path (with one exception noted below) and will be used unmodi‐
11341 fied.
11342 Include directories usage requirements commonly differ between the
11344 build-tree and the install-tree. The BUILD_INTERFACE and
11345 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
11346 rate usage requirements based on the usage location. Relative paths
11347 are allowed within the INSTALL_INTERFACE expression and are interpreted
11348 as relative to the installation prefix. Relative paths should not be
11349 used in BUILD_INTERFACE expressions because they will not be converted
11350 to absolute. For example:
11351 target_include_directories(mylib PUBLIC
11353 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
11354 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
11355 )
11356 Creating Relocatable Packages
11358 Note that it is not advisable to populate the INSTALL_INTERFACE of the
11359 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
11360 include directories of dependencies. That would hard-code into in‐
11361 stalled packages the include directory paths for dependencies as found
11362 on the machine the package was made on.
11363 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
11365 suitable for specifying the required include directories for headers
11366 provided with the target itself, not those provided by the transitive
11367 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
11368 Those dependencies should themselves be targets that specify their own
11369 header locations in INTERFACE_INCLUDE_DIRECTORIES.
11370 See the Creating Relocatable Packages section of the cmake-packages(7)
11372 manual for discussion of additional care that must be taken when speci‐
11373 fying usage requirements while creating packages for redistribution.
11374 target_link_directories
11376 New in version 3.13.
11377 Add link directories to a target.
11380 target_link_directories(<target> [BEFORE]
11382 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11383 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11384 Specifies the paths in which the linker should search for libraries
11386 when linking a given target. Each item can be an absolute or relative
11387 path, with the latter being interpreted as relative to the current
11388 source directory. These items will be added to the link command.
11389 The named <target> must have been created by a command such as
11391 add_executable() or add_library() and must not be an ALIAS target.
11392 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11394 scope of the items that follow them. PRIVATE and PUBLIC items will pop‐
11395 ulate the LINK_DIRECTORIES property of <target>. PUBLIC and INTERFACE
11396 items will populate the INTERFACE_LINK_DIRECTORIES property of <target>
11397 (IMPORTED targets only support INTERFACE items). Each item specifies a
11398 link directory and will be converted to an absolute path if necessary
11399 before adding it to the relevant property. Repeated calls for the same
11400 <target> append items in the order called.
11401 If BEFORE is specified, the content will be prepended to the relevant
11403 property instead of being appended.
11404 Arguments to target_link_directories may use "generator expressions"
11406 with the syntax $<...>. See the cmake-generator-expressions(7) manual
11407 for available expressions. See the cmake-buildsystem(7) manual for
11408 more on defining buildsystem properties.
11409 NOTE:
11411 This command is rarely necessary and should be avoided where there
11412 are other choices. Prefer to pass full absolute paths to libraries
11413 where possible, since this ensures the correct library will always
11414 be linked. The find_library() command provides the full path, which
11415 can generally be used directly in calls to target_link_libraries().
11416 Situations where a library search path may be needed include:
11417 • Project generators like Xcode where the user can switch target ar‐
11419 chitecture at build time, but a full path to a library cannot be
11420 used because it only provides one architecture (i.e. it is not a
11421 universal binary).
11422 • Libraries may themselves have other private library dependencies
11424 that expect to be found via RPATH mechanisms, but some linkers are
11425 not able to fully decode those paths (e.g. due to the presence of
11426 things like $ORIGIN).
11427 target_link_libraries
11429 Specify libraries or flags to use when linking a given target and/or
11430 its dependents. Usage requirements from linked library targets will be
11431 propagated. Usage requirements of a target's dependencies affect com‐
11432 pilation of its own sources.
11433 Overview
11435 This command has several signatures as detailed in subsections below.
11436 All of them have the general form
11437 target_link_libraries(<target> ... <item>... ...)
11439 The named <target> must have been created by a command such as
11441 add_executable() or add_library() and must not be an ALIAS target. If
11442 policy CMP0079 is not set to NEW then the target must have been created
11443 in the current directory. Repeated calls for the same <target> append
11444 items in the order called.
11445 New in version 3.13: The <target> doesn't have to be defined in the
11447 same directory as the target_link_libraries call.
11448 Each <item> may be:
11451 • A library target name: The generated link line will have the full
11453 path to the linkable library file associated with the target. The
11454 buildsystem will have a dependency to re-link <target> if the library
11455 file changes.
11456 The named target must be created by add_library() within the project
11458 or as an IMPORTED library. If it is created within the project an
11459 ordering dependency will automatically be added in the build system
11460 to make sure the named library target is up-to-date before the <tar‐
11461 get> links.
11462 If an imported library has the IMPORTED_NO_SONAME target property
11464 set, CMake may ask the linker to search for the library instead of
11465 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
11466 The full path to the target's artifact will be quoted/escaped for the
11468 shell automatically.
11469 • A full path to a library file: The generated link line will normally
11471 preserve the full path to the file. The buildsystem will have a de‐
11472 pendency to re-link <target> if the library file changes.
11473 There are some cases where CMake may ask the linker to search for the
11475 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
11476 shared library is detected to have no SONAME field. See policy
11477 CMP0060 for discussion of another case.
11478 If the library file is in a macOS framework, the Headers directory of
11480 the framework will also be processed as a usage requirement. This
11481 has the same effect as passing the framework directory as an include
11482 directory.
11483 New in version 3.8: On Visual Studio Generators for VS 2010 and
11485 above, library files ending in .targets will be treated as MSBuild
11486 targets files and imported into generated project files. This is not
11487 supported by other generators.
11488 The full path to the library file will be quoted/escaped for the
11491 shell automatically.
11492 • A plain library name: The generated link line will ask the linker to
11494 search for the library (e.g. foo becomes -lfoo or foo.lib).
11495 The library name/flag is treated as a command-line string fragment
11497 and will be used with no extra quoting or escaping.
11498 • A link flag: Item names starting with -, but not -l or -framework,
11500 are treated as linker flags. Note that such flags will be treated
11501 like any other library link item for purposes of transitive dependen‐
11502 cies, so they are generally safe to specify only as private link
11503 items that will not propagate to dependents.
11504 Link flags specified here are inserted into the link command in the
11506 same place as the link libraries. This might not be correct, depend‐
11507 ing on the linker. Use the LINK_OPTIONS target property or
11508 target_link_options() command to add link flags explicitly. The flags
11509 will then be placed at the toolchain-defined flag position in the
11510 link command.
11511 New in version 3.13: LINK_OPTIONS target property and
11513 target_link_options() command. For earlier versions of CMake, use
11514 LINK_FLAGS property instead.
11515 The link flag is treated as a command-line string fragment and will
11518 be used with no extra quoting or escaping.
11519 • A generator expression: A $<...> generator expression may evaluate to
11521 any of the above items or to a semicolon-separated list of them. If
11522 the ... contains any ; characters, e.g. after evaluation of a ${list}
11523 variable, be sure to use an explicitly quoted argument "$<...>" so
11524 that this command receives it as a single <item>.
11525 Additionally, a generator expression may be used as a fragment of any
11527 of the above items, e.g. foo$<1:_d>.
11528 Note that generator expressions will not be used in OLD handling of
11530 policy CMP0003 or policy CMP0004.
11531 • A debug, optimized, or general keyword immediately followed by an‐
11533 other <item>. The item following such a keyword will be used only
11534 for the corresponding build configuration. The debug keyword corre‐
11535 sponds to the Debug configuration (or to configurations named in the
11536 DEBUG_CONFIGURATIONS global property if it is set). The optimized
11537 keyword corresponds to all other configurations. The general keyword
11538 corresponds to all configurations, and is purely optional. Higher
11539 granularity may be achieved for per-configuration rules by creating
11540 and linking to IMPORTED library targets. These keywords are inter‐
11541 preted immediately by this command and therefore have no special
11542 meaning when produced by a generator expression.
11543 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
11545 ALIAS library target names and will cause an error if no such target
11546 exists. See policy CMP0028.
11547 See the cmake-buildsystem(7) manual for more on defining buildsystem
11549 properties.
11550 Libraries for a Target and/or its Dependents
11552 target_link_libraries(<target>
11553 <PRIVATE|PUBLIC|INTERFACE> <item>...
11554 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
11555 The PUBLIC, PRIVATE and INTERFACE scope keywords can be used to specify
11557 both the link dependencies and the link interface in one command.
11558 Libraries and targets following PUBLIC are linked to, and are made part
11560 of the link interface. Libraries and targets following PRIVATE are
11561 linked to, but are not made part of the link interface. Libraries fol‐
11562 lowing INTERFACE are appended to the link interface and are not used
11563 for linking <target>.
11564 Libraries for both a Target and its Dependents
11566 target_link_libraries(<target> <item>...)
11567 Library dependencies are transitive by default with this signature.
11569 When this target is linked into another target then the libraries
11570 linked to this target will appear on the link line for the other target
11571 too. This transitive "link interface" is stored in the
11572 INTERFACE_LINK_LIBRARIES target property and may be overridden by set‐
11573 ting the property directly. When CMP0022 is not set to NEW, transitive
11574 linking is built in but may be overridden by the
11575 LINK_INTERFACE_LIBRARIES property. Calls to other signatures of this
11576 command may set the property making any libraries linked exclusively by
11577 this signature private.
11578 Libraries for a Target and/or its Dependents (Legacy)
11580 target_link_libraries(<target>
11581 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
11582 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
11583 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
11585 link dependencies and the link interface in one command.
11586 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
11588 keywords instead.
11589 Libraries and targets following LINK_PUBLIC are linked to, and are made
11591 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
11592 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
11593 targets following LINK_PRIVATE are linked to, but are not made part of
11594 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
11595 Libraries for Dependents Only (Legacy)
11597 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
11598 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
11600 INTERFACE_LINK_LIBRARIES target property instead of using them for
11601 linking. If policy CMP0022 is not NEW, then this mode also appends li‐
11602 braries to the LINK_INTERFACE_LIBRARIES and its per-configuration
11603 equivalent.
11604 This signature is for compatibility only. Prefer the INTERFACE mode
11606 instead.
11607 Libraries specified as debug are wrapped in a generator expression to
11609 correspond to debug builds. If policy CMP0022 is not NEW, the li‐
11610 braries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
11611 erty (or to the properties corresponding to configurations listed in
11612 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
11613 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
11614 property. If policy CMP0022 is not NEW, they are also appended to the
11615 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
11616 without any keyword) are treated as if specified for both debug and op‐
11617 timized.
11618 Linking Object Libraries
11620 New in version 3.12.
11621 Object Libraries may be used as the <target> (first) argument of tar‐
11624 get_link_libraries to specify dependencies of their sources on other
11625 libraries. For example, the code
11626 add_library(A SHARED a.c)
11628 target_compile_definitions(A PUBLIC A)
11629 add_library(obj OBJECT obj.c)
11631 target_compile_definitions(obj PUBLIC OBJ)
11632 target_link_libraries(obj PUBLIC A)
11633 compiles obj.c with -DA -DOBJ and establishes usage requirements for
11635 obj that propagate to its dependents.
11636 Normal libraries and executables may link to Object Libraries to get
11638 their objects and usage requirements. Continuing the above example,
11639 the code
11640 add_library(B SHARED b.c)
11642 target_link_libraries(B PUBLIC obj)
11643 compiles b.c with -DA -DOBJ, creates shared library B with object files
11645 from b.c and obj.c, and links B to A. Furthermore, the code
11646 add_executable(main main.c)
11648 target_link_libraries(main B)
11649 compiles main.c with -DA -DOBJ and links executable main to B and A.
11651 The object library's usage requirements are propagated transitively
11652 through B, but its object files are not.
11653 Object Libraries may "link" to other object libraries to get usage re‐
11655 quirements, but since they do not have a link step nothing is done with
11656 their object files. Continuing from the above example, the code:
11657 add_library(obj2 OBJECT obj2.c)
11659 target_link_libraries(obj2 PUBLIC obj)
11660 add_executable(main2 main2.c)
11662 target_link_libraries(main2 obj2)
11663 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
11665 files from main2.c and obj2.c, and links main2 to A.
11666 In other words, when Object Libraries appear in a target's
11668 INTERFACE_LINK_LIBRARIES property they will be treated as Interface Li‐
11669 braries, but when they appear in a target's LINK_LIBRARIES property
11670 their object files will be included in the link too.
11671 Linking Object Libraries via $<TARGET_OBJECTS>
11673 New in version 3.21.
11674 The object files associated with an object library may be referenced by
11677 the $<TARGET_OBJECTS> generator expression. Such object files are
11678 placed on the link line before all libraries, regardless of their rela‐
11679 tive order. Additionally, an ordering dependency will be added to the
11680 build system to make sure the object library is up-to-date before the
11681 dependent target links. For example, the code
11682 add_library(obj3 OBJECT obj3.c)
11684 target_compile_definitions(obj3 PUBLIC OBJ3)
11685 add_executable(main3 main3.c)
11687 target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)
11688 links executable main3 with object files from main3.c and obj3.c fol‐
11690 lowed by the a3 and b3 libraries. main3.c is not compiled with usage
11691 requirements from obj3, such as -DOBJ3.
11692 This approach can be used to achieve transitive inclusion of object
11694 files in link lines as usage requirements. Continuing the above exam‐
11695 ple, the code
11696 add_library(iface_obj3 INTERFACE)
11698 target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)
11699 creates an interface library iface_obj3 that forwards the obj3 usage
11701 requirements and adds the obj3 object files to dependents' link lines.
11702 The code
11703 add_executable(use_obj3 use_obj3.c)
11705 target_link_libraries(use_obj3 PRIVATE iface_obj3)
11706 compiles use_obj3.c with -DOBJ3 and links executable use_obj3 with ob‐
11708 ject files from use_obj3.c and obj3.c.
11709 This also works transitively through a static library. Since a static
11711 library does not link, it does not consume the object files from object
11712 libraries referenced this way. Instead, the object files become tran‐
11713 sitive link dependencies of the static library. Continuing the above
11714 example, the code
11715 add_library(static3 STATIC static3.c)
11717 target_link_libraries(static3 PRIVATE iface_obj3)
11718 add_executable(use_static3 use_static3.c)
11720 target_link_libraries(use_static3 PRIVATE static3)
11721 compiles static3.c with -DOBJ3 and creates libstatic3.a using only its
11723 own object file. use_static3.c is compiled without -DOBJ3 because the
11724 usage requirement is not transitive through the private dependency of
11725 static3. However, the link dependencies of static3 are propagated, in‐
11726 cluding the iface_obj3 reference to $<TARGET_OBJECTS:obj3>. The
11727 use_static3 executable is created with object files from use_static3.c
11728 and obj3.c, and linked to library libstatic3.a.
11729 When using this approach, it is the project's responsibility to avoid
11731 linking multiple dependent binaries to iface_obj3, because they will
11732 all get the obj3 object files on their link lines.
11733 NOTE:
11735 Referencing $<TARGET_OBJECTS> in target_link_libraries calls worked
11736 in versions of CMake prior to 3.21 for some cases, but was not fully
11737 supported:
11738 • It did not place the object files before libraries on link lines.
11740 • It did not add an ordering dependency on the object library.
11742 • It did not work in Xcode with multiple architectures.
11744 Cyclic Dependencies of Static Libraries
11746 The library dependency graph is normally acyclic (a DAG), but in the
11747 case of mutually-dependent STATIC libraries CMake allows the graph to
11748 contain cycles (strongly connected components). When another target
11749 links to one of the libraries, CMake repeats the entire connected com‐
11750 ponent. For example, the code
11751 add_library(A STATIC a.c)
11753 add_library(B STATIC b.c)
11754 target_link_libraries(A B)
11755 target_link_libraries(B A)
11756 add_executable(main main.c)
11757 target_link_libraries(main A)
11758 links main to A B A B. While one repetition is usually sufficient,
11760 pathological object file and symbol arrangements can require more. One
11761 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
11762 property or by manually repeating the component in the last tar‐
11763 get_link_libraries call. However, if two archives are really so inter‐
11764 dependent they should probably be combined into a single archive, per‐
11765 haps by using Object Libraries.
11766 Creating Relocatable Packages
11768 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
11769 of a target with absolute paths to dependencies. That would hard-code
11770 into installed packages the library file paths for dependencies as
11771 found on the machine the package was made on.
11772 See the Creating Relocatable Packages section of the cmake-packages(7)
11774 manual for discussion of additional care that must be taken when speci‐
11775 fying usage requirements while creating packages for redistribution.
11776 target_link_options
11778 New in version 3.13.
11779 Add options to the link step for an executable, shared library or mod‐
11782 ule library target.
11783 target_link_options(<target> [BEFORE]
11785 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11786 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11787 The named <target> must have been created by a command such as
11789 add_executable() or add_library() and must not be an ALIAS target.
11790 This command can be used to add any link options, but alternative com‐
11792 mands exist to add libraries (target_link_libraries() or
11793 link_libraries()). See documentation of the directory and target
11794 LINK_OPTIONS properties.
11795 NOTE:
11797 This command cannot be used to add options for static library tar‐
11798 gets, since they do not use a linker. To add archiver or MSVC li‐
11799 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
11800 If BEFORE is specified, the content will be prepended to the property
11802 instead of being appended.
11803 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11805 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
11806 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
11807 will populate the INTERFACE_LINK_OPTIONS property of <target>. The
11808 following arguments specify link options. Repeated calls for the same
11809 <target> append items in the order called.
11810 NOTE:
11812 IMPORTED targets only support INTERFACE items.
11813 Arguments to target_link_options may use "generator expressions" with
11815 the syntax $<...>. See the cmake-generator-expressions(7) manual for
11816 available expressions. See the cmake-buildsystem(7) manual for more on
11817 defining buildsystem properties.
11818 Host And Device Specific Link Options
11820 New in version 3.18: When a device link step is involved, which is con‐
11821 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
11822 properties and policy CMP0105, the raw options will be delivered to the
11823 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
11824 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
11825 sion will be used only for the device link step. Options wrapped with
11826 $<HOST_LINK:...> generator expression will be used only for the host
11827 link step.
11828 Option De-duplication
11831 The final set of options used for a target is constructed by accumulat‐
11832 ing options from the current target and the usage requirements of its
11833 dependencies. The set of options is de-duplicated to avoid repetition.
11834 New in version 3.12: While beneficial for individual options, the
11836 de-duplication step can break up option groups. For example, -option A
11837 -option B becomes -option A B. One may specify a group of options us‐
11838 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
11839 is dropped, and the rest of the option string is parsed using the
11840 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
11841 "SHELL:-option B" becomes -option A -option B.
11842 Handling Compiler Driver Differences
11845 To pass options to the linker tool, each compiler driver has its own
11846 syntax. The LINKER: prefix and , separator can be used to specify, in
11847 a portable way, options to pass to the linker tool. LINKER: is replaced
11848 by the appropriate driver option and , by the appropriate driver sepa‐
11849 rator. The driver prefix and driver separator are given by the values
11850 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
11851 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
11852 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
11854 Clang and -Wl,-z,defs for GNU GCC.
11855 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
11857 sion.
11858 The LINKER: prefix supports, as an alternative syntax, specification of
11860 arguments using the SHELL: prefix and space as separator. The previous
11861 example then becomes "LINKER:SHELL:-z defs".
11862 NOTE:
11864 Specifying the SHELL: prefix anywhere other than at the beginning of
11865 the LINKER: prefix is not supported.
11866 target_precompile_headers
11868 New in version 3.16.
11869 Add a list of header files to precompile.
11872 Precompiling header files can speed up compilation by creating a par‐
11874 tially processed version of some header files, and then using that ver‐
11875 sion during compilations rather than repeatedly parsing the original
11876 headers.
11877 Main Form
11879 target_precompile_headers(<target>
11880 <INTERFACE|PUBLIC|PRIVATE> [header1...]
11881 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
11882 The command adds header files to the PRECOMPILE_HEADERS and/or
11884 INTERFACE_PRECOMPILE_HEADERS target properties of <target>. The named
11885 <target> must have been created by a command such as add_executable()
11886 or add_library() and must not be an ALIAS target.
11887 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11889 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
11890 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
11891 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
11892 get> (IMPORTED targets only support INTERFACE items). Repeated calls
11893 for the same <target> will append items in the order called.
11894 Projects should generally avoid using PUBLIC or INTERFACE for targets
11896 that will be exported, or they should at least use the
11897 $<BUILD_INTERFACE:...> generator expression to prevent precompile head‐
11898 ers from appearing in an installed exported target. Consumers of a
11899 target should typically be in control of what precompile headers they
11900 use, not have precompile headers forced on them by the targets being
11901 consumed (since precompile headers are not typically usage require‐
11902 ments). A notable exception to this is where an interface library is
11903 created to define a commonly used set of precompile headers in one
11904 place and then other targets link to that interface library privately.
11905 In this case, the interface library exists specifically to propagate
11906 the precompile headers to its consumers and the consumer is effectively
11907 still in control, since it decides whether to link to the interface li‐
11908 brary or not.
11909 The list of header files is used to generate a header file named
11911 cmake_pch.h|xx which is used to generate the precompiled header file
11912 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
11913 force included (-include for GCC, /FI for MSVC) to all source files, so
11914 sources do not need to have #include "pch.h".
11915 Header file names specified with angle brackets (e.g. <unordered_map>)
11917 or explicit double quotes (escaped for the cmake-language(7), e.g.
11918 [["other_header.h"]]) will be treated as is, and include directories
11919 must be available for the compiler to find them. Other header file
11920 names (e.g. project_header.h) are interpreted as being relative to the
11921 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
11922 included by absolute path. For example:
11923 target_precompile_headers(myTarget
11925 PUBLIC
11926 project_header.h
11927 PRIVATE
11928 [["other_header.h"]]
11929 <unordered_map>
11930 )
11931 Arguments to target_precompile_headers() may use "generator expres‐
11933 sions" with the syntax $<...>. See the cmake-generator-expressions(7)
11934 manual for available expressions. The $<COMPILE_LANGUAGE:...> genera‐
11935 tor expression is particularly useful for specifying a language-spe‐
11936 cific header to precompile for only one language (e.g. CXX and not C).
11937 In this case, header file names that are not explicitly in double
11938 quotes or angle brackets must be specified by absolute path. Also,
11939 when specifying angle brackets inside a generator expression, be sure
11940 to encode the closing > as $<ANGLE-R>. For example:
11941 target_precompile_headers(mylib PRIVATE
11943 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
11944 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
11945 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
11946 )
11947 Reusing Precompile Headers
11949 The command also supports a second signature which can be used to spec‐
11950 ify that one target re-uses a precompiled header file artifact from an‐
11951 other target instead of generating its own:
11952 target_precompile_headers(<target> REUSE_FROM <other_target>)
11954 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
11956 <other_target> and adds a dependency such that <target> will depend on
11957 <other_target>. CMake will halt with an error if the
11958 PRECOMPILE_HEADERS property of <target> is already set when the RE‐
11959 USE_FROM form is used.
11960 NOTE:
11962 The REUSE_FROM form requires the same set of compiler options, com‐
11963 piler flags and compiler definitions for both <target> and
11964 <other_target>. Some compilers (e.g. GCC) may issue a warning if
11965 the precompiled header file cannot be used (-Winvalid-pch).
11966 See Also
11968 To disable precompile headers for specific targets, see the
11969 DISABLE_PRECOMPILE_HEADERS target property.
11970 To prevent precompile headers from being used when compiling a specific
11972 source file, see the SKIP_PRECOMPILE_HEADERS source file property.
11973 target_sources
11975 New in version 3.1.
11976 Add sources to a target.
11979 target_sources(<target>
11981 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11982 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11983 Specifies sources to use when building a target and/or its dependents.
11985 The named <target> must have been created by a command such as
11986 add_executable() or add_library() or add_custom_target() and must not
11987 be an ALIAS target. The <items> may use generator expressions.
11988 New in version 3.20: <target> can be a custom target.
11990 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11993 scope of the source file paths (<items>) that follow them. PRIVATE and
11994 PUBLIC items will populate the SOURCES property of <target>, which are
11995 used when building the target itself. PUBLIC and INTERFACE items will
11996 populate the INTERFACE_SOURCES property of <target>, which are used
11997 when building dependents. A target created by add_custom_target() can
11998 only have PRIVATE scope.
11999 Repeated calls for the same <target> append items in the order called.
12001 New in version 3.3: Allow exporting targets with INTERFACE_SOURCES.
12003 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
12006 Changed in version 3.13: Relative source file paths are interpreted as
12009 being relative to the current source directory (i.e.
12010 CMAKE_CURRENT_SOURCE_DIR). See policy CMP0076.
12011 A path that begins with a generator expression is left unmodified.
12014 When a target's SOURCE_DIR property differs from
12015 CMAKE_CURRENT_SOURCE_DIR, use absolute paths in generator expressions
12016 to ensure the sources are correctly assigned to the target.
12017 # WRONG: starts with generator expression, but relative path used
12019 target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:dbgsrc.cpp>")
12020 # CORRECT: absolute path used inside the generator expression
12022 target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
12023 See the cmake-buildsystem(7) manual for more on defining buildsystem
12025 properties.
12026 File Sets
12028 New in version 3.23.
12029 target_sources(<target>
12032 [<INTERFACE|PUBLIC|PRIVATE>
12033 [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
12034 ]...)
12035 Adds a file set to a target, or adds files to an existing file set.
12037 Targets have zero or more named file sets. Each file set has a name, a
12038 type, a scope of INTERFACE, PUBLIC, or PRIVATE, one or more base direc‐
12039 tories, and files within those directories. The acceptable types in‐
12040 clude:
12041 HEADERS
12043 Sources intended to be used via a language's #include mechanism.
12044 CXX_MODULES
12046 NOTE:
12048 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
12049 Sources which contain C++ interface module or partition units (i.e.,
12051 those using the export keyword). This file set type may not have an
12052 INTERFACE scope except on IMPORTED targets.
12053 CXX_MODULE_HEADER_UNITS
12055 NOTE:
12057 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
12058 C++ header sources which may be imported by other C++ source code.
12060 This file set type may not have an INTERFACE scope except on IM‐
12061 PORTED targets.
12062 The optional default file sets are named after their type. The target
12064 may not be a custom target or FRAMEWORK target.
12065 Files in a PRIVATE or PUBLIC file set are marked as source files for
12067 the purposes of IDE integration. Additionally, files in HEADERS file
12068 sets have their HEADER_FILE_ONLY property set to TRUE. Files in an IN‐
12069 TERFACE or PUBLIC file set can be installed with the install(TARGETS)
12070 command, and exported with the install(EXPORT) and export() commands.
12071 Each target_sources(FILE_SET) entry starts with INTERFACE, PUBLIC, or
12073 PRIVATE and accepts the following arguments:
12074 FILE_SET <set>
12076 The name of the file set to create or add to. It must contain only
12077 letters, numbers and underscores. Names starting with a capital let‐
12078 ter are reserved for built-in file sets predefined by CMake. The
12079 only predefined set names are those matching the acceptable types.
12080 All other set names must not start with a capital letter or under‐
12081 score.
12082 TYPE <type>
12084 Every file set is associated with a particular type of file. Only
12085 types specified above may be used and it is an error to specify any‐
12086 thing else. As a special case, if the name of the file set is one of
12087 the types, the type does not need to be specified and the TYPE
12088 <type> arguments can be omitted. For all other file set names, TYPE
12089 is required.
12090 BASE_DIRS <dirs>...
12092 An optional list of base directories of the file set. Any relative
12093 path is treated as relative to the current source directory (i.e.
12094 CMAKE_CURRENT_SOURCE_DIR). If no BASE_DIRS are specified when the
12095 file set is first created, the value of CMAKE_CURRENT_SOURCE_DIR is
12096 added. This argument supports generator expressions.
12097 No two base directories for a file set may be sub-directories of
12099 each other. This requirement must be met across all base directo‐
12100 ries added to a file set, not just those within a single call to
12101 target_sources().
12102 FILES <files>...
12104 An optional list of files to add to the file set. Each file must be
12105 in one of the base directories, or a subdirectory of one of the base
12106 directories. This argument supports generator expressions.
12107 If relative paths are specified, they are considered relative to
12109 CMAKE_CURRENT_SOURCE_DIR at the time target_sources() is called. An
12110 exception to this is a path starting with $<. Such paths are treated
12111 as relative to the target's source directory after evaluation of
12112 generator expressions.
12113 The following target properties are set by target_sources(FILE_SET),
12115 but they should not generally be manipulated directly:
12116 For file sets of type HEADERS:
12118 • HEADER_SETS
12120 • INTERFACE_HEADER_SETS
12122 • HEADER_SET
12124 • HEADER_SET_<NAME>
12126 • HEADER_DIRS
12128 • HEADER_DIRS_<NAME>
12130 For file sets of type CXX_MODULES:
12132 • CXX_MODULE_SETS
12134 • INTERFACE_CXX_MODULE_SETS
12136 • CXX_MODULE_SET
12138 • CXX_MODULE_SET_<NAME>
12140 • CXX_MODULE_DIRS
12142 • CXX_MODULE_DIRS_<NAME>
12144 For file sets of type CXX_MODULE_HEADER_UNITS:
12146 • CXX_MODULE_HEADER_UNIT_SETS
12148 • INTERFACE_CXX_MODULE_HEADER_UNIT_SETS
12150 • CXX_MODULE_HEADER_UNIT_SET
12152 • CXX_MODULE_HEADER_UNIT_SET_<NAME>
12154 • CXX_MODULE_HEADER_UNIT_DIRS
12156 • CXX_MODULE_HEADER_UNIT_DIRS_<NAME>
12158 Target properties related to include directories are also modified by
12160 target_sources(FILE_SET) as follows:
12161 INCLUDE_DIRECTORIES
12163 If the TYPE is HEADERS or CXX_MODULE_HEADER_UNITS, and the scope of
12164 the file set is PRIVATE or PUBLIC, all of the BASE_DIRS of the file
12165 set are wrapped in $<BUILD_INTERFACE> and appended to this property.
12166 INTERFACE_INCLUDE_DIRECTORIES
12168 If the TYPE is HEADERS or CXX_MODULE_HEADER_UNITS, and the scope of
12169 the file set is INTERFACE or PUBLIC, all of the BASE_DIRS of the
12170 file set are wrapped in $<BUILD_INTERFACE> and appended to this
12171 property.
12172 try_compile
12174 Try building some code.
12175 Try Compiling Whole Projects
12177 try_compile(<resultVar> PROJECT <projectName>
12178 SOURCE_DIR <srcdir>
12179 [BINARY_DIR <bindir>]
12180 [TARGET <targetName>]
12181 [NO_CACHE]
12182 [CMAKE_FLAGS <flags>...]
12183 [OUTPUT_VARIABLE <var>])
12184 New in version 3.25.
12186 Try building a project. The success or failure of the try_compile,
12189 i.e. TRUE or FALSE respectively, is returned in <resultVar>.
12190 In this form, <srcdir> should contain a complete CMake project with a
12192 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
12193 not be deleted after this command is run. Specify <targetName> to
12194 build a specific target instead of the all or ALL_BUILD target. See
12195 below for the meaning of other options.
12196 Changed in version 3.24: CMake variables describing platform settings,
12198 and those listed by the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable,
12199 are propagated into the project's build configuration. See policy
12200 CMP0137. Previously this was only done by the source file signature.
12201 This command also supports an alternate signature which was present in
12204 older versions of CMake:
12205 try_compile(<resultVar> <bindir> <srcdir>
12207 <projectName> [<targetName>]
12208 [NO_CACHE]
12209 [CMAKE_FLAGS <flags>...]
12210 [OUTPUT_VARIABLE <var>])
12211 Try Compiling Source Files
12213 try_compile(<resultVar>
12214 <SOURCES <srcfile...> |
12215 SOURCE_FROM_CONTENT <name> <content> |
12216 SOURCE_FROM_VAR <name> <var> |
12217 SOURCE_FROM_FILE <name> <path> >...
12218 [NO_CACHE]
12219 [CMAKE_FLAGS <flags>...]
12220 [COMPILE_DEFINITIONS <defs>...]
12221 [LINK_OPTIONS <options>...]
12222 [LINK_LIBRARIES <libs>...]
12223 [OUTPUT_VARIABLE <var>]
12224 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
12225 [<LANG>_STANDARD <std>]
12226 [<LANG>_STANDARD_REQUIRED <bool>]
12227 [<LANG>_EXTENSIONS <bool>]
12228 )
12229 New in version 3.25.
12231 Try building an executable or static library from one or more source
12234 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
12235 variable). The success or failure of the try_compile, i.e. TRUE or
12236 FALSE respectively, is returned in <resultVar>.
12237 In this form, one or more source files must be provided. Additionally,
12239 one of SOURCES and/or SOURCE_FROM_* must precede other keywords.
12240 If CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
12242 sources must include a definition for main and CMake will create a
12243 CMakeLists.txt file to build the source(s) as an executable. If
12244 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static li‐
12245 brary will be built instead and no definition for main is required.
12246 For an executable, the generated CMakeLists.txt file would contain
12247 something like the following:
12248 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
12250 include_directories(${INCLUDE_DIRECTORIES})
12251 link_directories(${LINK_DIRECTORIES})
12252 add_executable(cmTryCompileExec <srcfile>...)
12253 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
12254 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
12255 CMake automatically generates, for each try_compile operation, a unique
12257 directory under ${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch with an un‐
12258 specified name. These directories are cleaned automatically unless
12259 --debug-trycompile is passed to cmake. Such directories from previous
12260 runs are also unconditionally cleaned at the beginning of any cmake ex‐
12261 ecution.
12262 This command also supports an alternate signature which was present in
12264 older versions of CMake:
12265 try_compile(<resultVar> <bindir> <srcfile|SOURCES srcfile...>
12267 [NO_CACHE]
12268 [CMAKE_FLAGS <flags>...]
12269 [COMPILE_DEFINITIONS <defs>...]
12270 [LINK_OPTIONS <options>...]
12271 [LINK_LIBRARIES <libs>...]
12272 [OUTPUT_VARIABLE <var>]
12273 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
12274 [<LANG>_STANDARD <std>]
12275 [<LANG>_STANDARD_REQUIRED <bool>]
12276 [<LANG>_EXTENSIONS <bool>]
12277 )
12278 In this version, try_compile will use <bindir>/CMakeFiles/CMakeTmp for
12280 its operation, and all such files will be cleaned automatically. For
12281 debugging, --debug-trycompile can be passed to cmake to avoid this
12282 clean. However, multiple sequential try_compile operations, if given
12283 the same <bindir>, will reuse this single output directory, such that
12284 you can only debug one such try_compile call at a time. Use of the
12285 newer signature is recommended to simplify debugging of multiple
12286 try_compile operations.
12287 The options are:
12289 CMAKE_FLAGS <flags>...
12291 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
12292 cmake(1) command-line used to drive the test build. The above
12293 example shows how values for variables INCLUDE_DIRECTORIES,
12294 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
12295 COMPILE_DEFINITIONS <defs>...
12297 Specify -Ddefinition arguments to pass to add_definitions() in
12298 the generated test project.
12299 COPY_FILE <fileName>
12301 Copy the built executable or static library to the given <file‐
12302 Name>.
12303 COPY_FILE_ERROR <var>
12305 Use after COPY_FILE to capture into variable <var> any error
12306 message encountered while trying to copy the file.
12307 LINK_LIBRARIES <libs>...
12309 Specify libraries to be linked in the generated project. The
12310 list of libraries may refer to system libraries and to Imported
12311 Targets from the calling project.
12312 If this option is specified, any -DLINK_LIBRARIES=... value
12314 given to the CMAKE_FLAGS option will be ignored.
12315 LINK_OPTIONS <options>...
12317 New in version 3.14.
12318 Specify link step options to pass to target_link_options() or to
12321 set the STATIC_LIBRARY_OPTIONS target property in the generated
12322 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
12323 able.
12324 NO_CACHE
12326 New in version 3.25.
12327 The result will be stored in a normal variable rather than a
12330 cache entry.
12331 The result variable is normally cached so that a simple pattern
12333 can be used to avoid repeating the test on subsequent executions
12334 of CMake:
12335 if(NOT DEFINED RESULTVAR)
12337 # ...(check-specific setup code)...
12338 try_compile(RESULTVAR ...)
12339 # ...(check-specific logging and cleanup code)...
12340 endif()
12341 If the guard variable and result variable are not the same (for
12343 example, if the test is part of a larger inspection), NO_CACHE
12344 may be useful to avoid leaking the intermediate result variable
12345 into the cache.
12346 OUTPUT_VARIABLE <var>
12348 Store the output from the build process in the given variable.
12349 SOURCE_FROM_CONTENT <name> <content>
12351 New in version 3.25.
12352 Write <content> to a file named <name> in the operation direc‐
12355 tory. This can be used to bypass the need to separately write a
12356 source file when the contents of the file are dynamically speci‐
12357 fied. The specified <name> is not allowed to contain path compo‐
12358 nents.
12359 SOURCE_FROM_CONTENT may be specified multiple times.
12361 SOURCE_FROM_FILE <name> <path>
12363 New in version 3.25.
12364 Copy <path> to a file named <name> in the operation directory.
12367 This can be used to consolidate files into the operation direc‐
12368 tory, which may be useful if a source which already exists (i.e.
12369 as a stand-alone file in a project's source repository) needs to
12370 refer to other file(s) created by SOURCE_FROM_*. (Otherwise,
12371 SOURCES is usually more convenient.) The specified <name> is not
12372 allowed to contain path components.
12373 SOURCE_FROM_VAR <name> <var>
12375 New in version 3.25.
12376 Write the contents of <var> to a file named <name> in the opera‐
12379 tion directory. This is the same as SOURCE_FROM_CONTENT, but
12380 takes the contents from the specified CMake variable, rather
12381 than directly, which may be useful when passing arguments
12382 through a function which wraps try_compile. The specified <name>
12383 is not allowed to contain path components.
12384 SOURCE_FROM_VAR may be specified multiple times.
12386 <LANG>_STANDARD <std>
12388 New in version 3.8.
12389 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD,
12392 OBJCXX_STANDARD, or CUDA_STANDARD target property of the gener‐
12393 ated project.
12394 <LANG>_STANDARD_REQUIRED <bool>
12396 New in version 3.8.
12397 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
12400 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or
12401 CUDA_STANDARD_REQUIRED target property of the generated project.
12402 <LANG>_EXTENSIONS <bool>
12404 New in version 3.8.
12405 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS,
12408 OBJCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the
12409 generated project.
12410 Other Behavior Settings
12412 New in version 3.4: If set, the following variables are passed in to
12413 the generated try_compile CMakeLists.txt to initialize compile target
12414 properties with default values:
12415 • CMAKE_CUDA_RUNTIME_LIBRARY
12417 • CMAKE_ENABLE_EXPORTS
12419 • CMAKE_LINK_SEARCH_START_STATIC
12421 • CMAKE_LINK_SEARCH_END_STATIC
12423 • CMAKE_MSVC_RUNTIME_LIBRARY
12425 • CMAKE_POSITION_INDEPENDENT_CODE
12427 • CMAKE_WATCOM_RUNTIME_LIBRARY
12429 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
12431 well.
12432 Changed in version 3.14: If CMP0083 is set to NEW, then in order to ob‐
12435 tain correct behavior at link time, the check_pie_supported() command
12436 from the CheckPIESupported module must be called before using the
12437 try_compile() command.
12438 The current settings of CMP0065 and CMP0083 are propagated through to
12441 the generated test project.
12442 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
12444 figuration.
12445 New in version 3.6: Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to
12447 specify the type of target used for the source file signature.
12448 New in version 3.6: Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES vari‐
12451 able to specify variables that must be propagated into the test
12452 project. This variable is meant for use only in toolchain files and is
12453 only honored by the try_compile() command for the source files form,
12454 not when given a whole project.
12455 Changed in version 3.8: If CMP0067 is set to NEW, or any of the
12458 <LANG>_STANDARD, <LANG>_STANDARD_REQUIRED, or <LANG>_EXTENSIONS options
12459 are used, then the language standard variables are honored:
12460 • CMAKE_C_STANDARD
12462 • CMAKE_C_STANDARD_REQUIRED
12464 • CMAKE_C_EXTENSIONS
12466 • CMAKE_CXX_STANDARD
12468 • CMAKE_CXX_STANDARD_REQUIRED
12470 • CMAKE_CXX_EXTENSIONS
12472 • CMAKE_OBJC_STANDARD
12474 • CMAKE_OBJC_STANDARD_REQUIRED
12476 • CMAKE_OBJC_EXTENSIONS
12478 • CMAKE_OBJCXX_STANDARD
12480 • CMAKE_OBJCXX_STANDARD_REQUIRED
12482 • CMAKE_OBJCXX_EXTENSIONS
12484 • CMAKE_CUDA_STANDARD
12486 • CMAKE_CUDA_STANDARD_REQUIRED
12488 • CMAKE_CUDA_EXTENSIONS
12490 Their values are used to set the corresponding target properties in the
12492 generated project (unless overridden by an explicit option).
12493 Changed in version 3.14: For the Green Hills MULTI generator, the GHS
12496 toolset and target system customization cache variables are also propa‐
12497 gated into the test project.
12498 New in version 3.24: The CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES vari‐
12501 able may be set to disable passing platform variables into the test
12502 project.
12503 New in version 3.25: If CMP0141 is set to NEW, one can use
12506 CMAKE_MSVC_DEBUG_INFORMATION_FORMAT to specify the MSVC debug informa‐
12507 tion format.
12508 try_run
12511 Try compiling and then running some code.
12512 Try Compiling and Running Source Files
12514 try_run(<runResultVar> <compileResultVar>
12515 <SOURCES <srcfile...> |
12516 SOURCE_FROM_CONTENT <name> <content> |
12517 SOURCE_FROM_VAR <name> <var> |
12518 SOURCE_FROM_FILE <name> <path> >...
12519 [NO_CACHE]
12520 [CMAKE_FLAGS <flags>...]
12521 [COMPILE_DEFINITIONS <defs>...]
12522 [LINK_OPTIONS <options>...]
12523 [LINK_LIBRARIES <libs>...]
12524 [COMPILE_OUTPUT_VARIABLE <var>]
12525 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
12526 [<LANG>_STANDARD <std>]
12527 [<LANG>_STANDARD_REQUIRED <bool>]
12528 [<LANG>_EXTENSIONS <bool>]
12529 [RUN_OUTPUT_VARIABLE <var>]
12530 [RUN_OUTPUT_STDOUT_VARIABLE <var>]
12531 [RUN_OUTPUT_STDERR_VARIABLE <var>]
12532 [OUTPUT_VARIABLE <var>]
12533 [WORKING_DIRECTORY <var>]
12534 [ARGS <args>...]
12535 )
12536 New in version 3.25.
12538 Try compiling a <srcfile>. Returns TRUE or FALSE for success or fail‐
12541 ure in <compileResultVar>. If the compile succeeded, runs the exe‐
12542 cutable and returns its exit code in <runResultVar>. If the executable
12543 was built, but failed to run, then <runResultVar> will be set to
12544 FAILED_TO_RUN. See the try_compile() command for documentation of op‐
12545 tions common to both commands, and for information on how the test
12546 project is constructed to build the source file.
12547 One or more source files must be provided. Additionally, one of SOURCES
12549 and/or SOURCE_FROM_* must precede other keywords.
12550 This command also supports an alternate signature which was present in
12552 older versions of CMake:
12553 try_run(<runResultVar> <compileResultVar>
12555 <bindir> <srcfile|SOURCES srcfile...>
12556 [NO_CACHE]
12557 [CMAKE_FLAGS <flags>...]
12558 [COMPILE_DEFINITIONS <defs>...]
12559 [LINK_OPTIONS <options>...]
12560 [LINK_LIBRARIES <libs>...]
12561 [COMPILE_OUTPUT_VARIABLE <var>]
12562 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
12563 [<LANG>_STANDARD <std>]
12564 [<LANG>_STANDARD_REQUIRED <bool>]
12565 [<LANG>_EXTENSIONS <bool>]
12566 [RUN_OUTPUT_VARIABLE <var>]
12567 [RUN_OUTPUT_STDOUT_VARIABLE <var>]
12568 [RUN_OUTPUT_STDERR_VARIABLE <var>]
12569 [OUTPUT_VARIABLE <var>]
12570 [WORKING_DIRECTORY <var>]
12571 [ARGS <args>...]
12572 )
12573 The options specific to try_run are:
12575 COMPILE_OUTPUT_VARIABLE <var>
12577 Report the compile step build output in a given variable.
12578 OUTPUT_VARIABLE <var>
12580 Report the compile build output and the output from running the
12581 executable in the given variable. This option exists for legacy
12582 reasons and is only supported by the old try_run signature.
12583 Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE instead.
12584 RUN_OUTPUT_VARIABLE <var>
12586 Report the output from running the executable in a given vari‐
12587 able.
12588 RUN_OUTPUT_STDOUT_VARIABLE <var>
12590 New in version 3.25.
12591 Report the output of stdout from running the executable in a
12594 given variable.
12595 RUN_OUTPUT_STDERR_VARIABLE <var>
12597 New in version 3.25.
12598 Report the output of stderr from running the executable in a
12601 given variable.
12602 WORKING_DIRECTORY <var>
12604 New in version 3.20.
12605 Run the executable in the given directory. If no WORKING_DIREC‐
12608 TORY is specified, the executable will run in <bindir> or the
12609 current build directory.
12610 ARGS <args>...
12612 Additional arguments to pass to the executable when running it.
12613 Other Behavior Settings
12615 Set the CMAKE_TRY_COMPILE_CONFIGURATION variable to choose a build con‐
12616 figuration.
12617 Behavior when Cross Compiling
12619 New in version 3.3: Use CMAKE_CROSSCOMPILING_EMULATOR when running
12620 cross-compiled binaries.
12621 When cross compiling, the executable compiled in the first step usually
12624 cannot be run on the build host. The try_run command checks the
12625 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
12626 piling mode. If that is the case, it will still try to compile the ex‐
12627 ecutable, but it will not try to run the executable unless the
12628 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
12629 cache variables which must be filled by the user or by presetting them
12630 in some CMake script file to the values the executable would have pro‐
12631 duced if it had been run on its actual target platform. These cache
12632 entries are:
12633 <runResultVar>
12635 Exit code if the executable were to be run on the target plat‐
12636 form.
12637 <runResultVar>__TRYRUN_OUTPUT
12639 Output from stdout and stderr if the executable were to be run
12640 on the target platform. This is created only if the RUN_OUT‐
12641 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
12642 In order to make cross compiling your project easier, use try_run only
12644 if really required. If you use try_run, use the RUN_OUTPUT_STD‐
12645 OUT_VARIABLE, RUN_OUTPUT_STDERR_VARIABLE, RUN_OUTPUT_VARIABLE or OUT‐
12646 PUT_VARIABLE options only if really required. Using them will require
12647 that when cross-compiling, the cache variables will have to be set man‐
12648 ually to the output of the executable. You can also "guard" the calls
12649 to try_run with an if() block checking the CMAKE_CROSSCOMPILING vari‐
12650 able and provide an easy-to-preset alternative for this case.
12651
12653 These commands are available only in CTest scripts.
12654 ctest_build
12656 Perform the CTest Build Step as a Dashboard Client.
12657 ctest_build([BUILD <build-dir>] [APPEND]
12659 [CONFIGURATION <config>]
12660 [PARALLEL_LEVEL <parallel>]
12661 [FLAGS <flags>]
12662 [PROJECT_NAME <project-name>]
12663 [TARGET <target-name>]
12664 [NUMBER_ERRORS <num-err-var>]
12665 [NUMBER_WARNINGS <num-warn-var>]
12666 [RETURN_VALUE <result-var>]
12667 [CAPTURE_CMAKE_ERROR <result-var>]
12668 )
12669 Build the project and store results in Build.xml for submission with
12671 the ctest_submit() command.
12672 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
12674 build command line. Otherwise the build command line is computed auto‐
12675 matically based on the options given.
12676 The options are:
12678 BUILD <build-dir>
12680 Specify the top-level build directory. If not given, the
12681 CTEST_BINARY_DIRECTORY variable is used.
12682 APPEND Mark Build.xml for append to results previously submitted to a
12684 dashboard server since the last ctest_start() call. Append se‐
12685 mantics are defined by the dashboard server in use. This does
12686 not cause results to be appended to a .xml file produced by a
12687 previous call to this command.
12688 CONFIGURATION <config>
12690 Specify the build configuration (e.g. Debug). If not specified
12691 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
12692 wise the -C <cfg> option given to the ctest(1) command will be
12693 used, if any.
12694 PARALLEL_LEVEL <parallel>
12696 New in version 3.21.
12697 Specify the parallel level of the underlying build system. If
12700 not specified, the CMAKE_BUILD_PARALLEL_LEVEL environment vari‐
12701 able will be checked.
12702 FLAGS <flags>
12704 Pass additional arguments to the underlying build command. If
12705 not specified the CTEST_BUILD_FLAGS variable will be checked.
12706 This can, e.g., be used to trigger a parallel build using the -j
12707 option of make. See the ProcessorCount module for an example.
12708 PROJECT_NAME <project-name>
12710 Ignored since CMake 3.0.
12711 Changed in version 3.14: This value is no longer required.
12713 TARGET <target-name>
12716 Specify the name of a target to build. If not specified the
12717 CTEST_BUILD_TARGET variable will be checked. Otherwise the de‐
12718 fault target will be built. This is the "all" target (called
12719 ALL_BUILD in Visual Studio Generators).
12720 NUMBER_ERRORS <num-err-var>
12722 Store the number of build errors detected in the given variable.
12723 NUMBER_WARNINGS <num-warn-var>
12725 Store the number of build warnings detected in the given vari‐
12726 able.
12727 RETURN_VALUE <result-var>
12729 Store the return value of the native build tool in the given
12730 variable.
12731 CAPTURE_CMAKE_ERROR <result-var>
12733 New in version 3.7.
12734 Store in the <result-var> variable -1 if there are any errors
12737 running the command and prevent ctest from returning non-zero if
12738 an error occurs.
12739 QUIET New in version 3.3.
12741 Suppress any CTest-specific non-error output that would have
12744 been printed to the console otherwise. The summary of warnings
12745 / errors, as well as the output from the native build tool is
12746 unaffected by this option.
12747 ctest_configure
12749 Perform the CTest Configure Step as a Dashboard Client.
12750 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
12752 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
12753 [CAPTURE_CMAKE_ERROR <result-var>])
12754 Configure the project build tree and record results in Configure.xml
12756 for submission with the ctest_submit() command.
12757 The options are:
12759 BUILD <build-dir>
12761 Specify the top-level build directory. If not given, the
12762 CTEST_BINARY_DIRECTORY variable is used.
12763 SOURCE <source-dir>
12765 Specify the source directory. If not given, the
12766 CTEST_SOURCE_DIRECTORY variable is used.
12767 APPEND Mark Configure.xml for append to results previously submitted to
12769 a dashboard server since the last ctest_start() call. Append
12770 semantics are defined by the dashboard server in use. This does
12771 not cause results to be appended to a .xml file produced by a
12772 previous call to this command.
12773 OPTIONS <options>
12775 Specify command-line arguments to pass to the configuration
12776 tool.
12777 RETURN_VALUE <result-var>
12779 Store in the <result-var> variable the return value of the na‐
12780 tive configuration tool.
12781 CAPTURE_CMAKE_ERROR <result-var>
12783 New in version 3.7.
12784 Store in the <result-var> variable -1 if there are any errors
12787 running the command and prevent ctest from returning non-zero if
12788 an error occurs.
12789 QUIET New in version 3.3.
12791 Suppress any CTest-specific non-error messages that would have
12794 otherwise been printed to the console. Output from the underly‐
12795 ing configure command is not affected.
12796 ctest_coverage
12798 Perform the CTest Coverage Step as a Dashboard Client.
12799 ctest_coverage([BUILD <build-dir>] [APPEND]
12801 [LABELS <label>...]
12802 [RETURN_VALUE <result-var>]
12803 [CAPTURE_CMAKE_ERROR <result-var>]
12804 [QUIET]
12805 )
12806 Collect coverage tool results and stores them in Coverage.xml for sub‐
12808 mission with the ctest_submit() command.
12809 The options are:
12811 BUILD <build-dir>
12813 Specify the top-level build directory. If not given, the
12814 CTEST_BINARY_DIRECTORY variable is used.
12815 APPEND Mark Coverage.xml for append to results previously submitted to
12817 a dashboard server since the last ctest_start() call. Append
12818 semantics are defined by the dashboard server in use. This does
12819 not cause results to be appended to a .xml file produced by a
12820 previous call to this command.
12821 LABELS Filter the coverage report to include only source files labeled
12823 with at least one of the labels specified.
12824 RETURN_VALUE <result-var>
12826 Store in the <result-var> variable 0 if coverage tools ran with‐
12827 out error and non-zero otherwise.
12828 CAPTURE_CMAKE_ERROR <result-var>
12830 New in version 3.7.
12831 Store in the <result-var> variable -1 if there are any errors
12834 running the command and prevent ctest from returning non-zero if
12835 an error occurs.
12836 QUIET New in version 3.3.
12838 Suppress any CTest-specific non-error output that would have
12841 been printed to the console otherwise. The summary indicating
12842 how many lines of code were covered is unaffected by this op‐
12843 tion.
12844 ctest_empty_binary_directory
12846 empties the binary directory
12847 ctest_empty_binary_directory( directory )
12849 Removes a binary directory. This command will perform some checks
12851 prior to deleting the directory in an attempt to avoid malicious or ac‐
12852 cidental directory deletion.
12853 ctest_memcheck
12855 Perform the CTest MemCheck Step as a Dashboard Client.
12856 ctest_memcheck([BUILD <build-dir>] [APPEND]
12858 [START <start-number>]
12859 [END <end-number>]
12860 [STRIDE <stride-number>]
12861 [EXCLUDE <exclude-regex>]
12862 [INCLUDE <include-regex>]
12863 [EXCLUDE_LABEL <label-exclude-regex>]
12864 [INCLUDE_LABEL <label-include-regex>]
12865 [EXCLUDE_FIXTURE <regex>]
12866 [EXCLUDE_FIXTURE_SETUP <regex>]
12867 [EXCLUDE_FIXTURE_CLEANUP <regex>]
12868 [PARALLEL_LEVEL <level>]
12869 [RESOURCE_SPEC_FILE <file>]
12870 [TEST_LOAD <threshold>]
12871 [SCHEDULE_RANDOM <ON|OFF>]
12872 [STOP_ON_FAILURE]
12873 [STOP_TIME <time-of-day>]
12874 [RETURN_VALUE <result-var>]
12875 [CAPTURE_CMAKE_ERROR <result-var>]
12876 [REPEAT <mode>:<n>]
12877 [OUTPUT_JUNIT <file>]
12878 [DEFECT_COUNT <defect-count-var>]
12879 [QUIET]
12880 )
12881 Run tests with a dynamic analysis tool and store results in Mem‐
12883 Check.xml for submission with the ctest_submit() command.
12884 Most options are the same as those for the ctest_test() command.
12886 The options unique to this command are:
12888 DEFECT_COUNT <defect-count-var>
12890 New in version 3.8.
12891 Store in the <defect-count-var> the number of defects found.
12894 ctest_read_custom_files
12896 read CTestCustom files.
12897 ctest_read_custom_files( directory ... )
12899 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
12901 given directory.
12902 By default, invoking ctest(1) without a script will read custom files
12904 from the binary directory.
12905 ctest_run_script
12907 runs a ctest -S script
12908 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
12910 script_file_name2 ... [RETURN_VALUE var])
12911 Runs a script or scripts much like if it was run from ctest -S. If no
12913 argument is provided then the current script is run using the current
12914 settings of the variables. If NEW_PROCESS is specified then each
12915 script will be run in a separate process.If RETURN_VALUE is specified
12916 the return value of the last script run will be put into var.
12917 ctest_sleep
12919 sleeps for some amount of time
12920 ctest_sleep(<seconds>)
12922 Sleep for given number of seconds.
12924 ctest_sleep(<time1> <duration> <time2>)
12926 Sleep for t=(time1 + duration - time2) seconds if t > 0.
12928 ctest_start
12930 Starts the testing for a given model
12931 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
12933 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
12935 Starts the testing for a given model. The command should be called af‐
12937 ter the binary directory is initialized.
12938 The parameters are as follows:
12940 <model>
12942 Set the dashboard model. Must be one of Experimental, Continu‐
12943 ous, or Nightly. This parameter is required unless APPEND is
12944 specified.
12945 <source>
12947 Set the source directory. If not specified, the value of
12948 CTEST_SOURCE_DIRECTORY is used instead.
12949 <binary>
12951 Set the binary directory. If not specified, the value of
12952 CTEST_BINARY_DIRECTORY is used instead.
12953 GROUP <group>
12955 If GROUP is used, the submissions will go to the specified group
12956 on the CDash server. If no GROUP is specified, the name of the
12957 model is used by default.
12958 Changed in version 3.16: This replaces the deprecated option
12960 TRACK. Despite the name change its behavior is unchanged.
12961 APPEND If APPEND is used, the existing TAG is used rather than creating
12964 a new one based on the current time stamp. If you use APPEND,
12965 you can omit the <model> and GROUP <group> parameters, because
12966 they will be read from the generated TAG file. For example:
12967 ctest_start(Experimental GROUP GroupExperimental)
12969 Later, in another ctest -S script:
12971 ctest_start(APPEND)
12973 When the second script runs ctest_start(APPEND), it will read
12975 the Experimental model and GroupExperimental group from the TAG
12976 file generated by the first ctest_start() command. Please note
12977 that if you call ctest_start(APPEND) and specify a different
12978 model or group than in the first ctest_start() command, a warn‐
12979 ing will be issued, and the new model and group will be used.
12980 QUIET New in version 3.3.
12982 If QUIET is used, CTest will suppress any non-error messages
12985 that it otherwise would have printed to the console.
12986 The parameters for ctest_start() can be issued in any order, with the
12988 exception that <model>, <source>, and <binary> have to appear in that
12989 order with respect to each other. The following are all valid and
12990 equivalent:
12991 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
12993 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
12995 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
12997 However, for the sake of readability, it is recommended that you order
12999 your parameters in the order listed at the top of this page.
13000 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
13002 able) is set, its content is treated as command-line. The command is
13003 invoked with the current working directory set to the parent of the
13004 source directory, even if the source directory already exists. This
13005 can be used to create the source tree from a version control reposi‐
13006 tory.
13007 ctest_submit
13009 Perform the CTest Submit Step as a Dashboard Client.
13010 ctest_submit([PARTS <part>...] [FILES <file>...]
13012 [SUBMIT_URL <url>]
13013 [BUILD_ID <result-var>]
13014 [HTTPHEADER <header>]
13015 [RETRY_COUNT <count>]
13016 [RETRY_DELAY <delay>]
13017 [RETURN_VALUE <result-var>]
13018 [CAPTURE_CMAKE_ERROR <result-var>]
13019 [QUIET]
13020 )
13021 Submit results to a dashboard server. By default all available parts
13023 are submitted.
13024 The options are:
13026 PARTS <part>...
13028 Specify a subset of parts to submit. Valid part names are:
13029 Start = nothing
13031 Update = ctest_update results, in Update.xml
13032 Configure = ctest_configure results, in Configure.xml
13033 Build = ctest_build results, in Build.xml
13034 Test = ctest_test results, in Test.xml
13035 Coverage = ctest_coverage results, in Coverage.xml
13036 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and
13037 DynamicAnalysis-Test.xml
13038 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
13039 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
13040 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
13041 Submit = nothing
13042 Done = Build is complete, in Done.xml
13043 FILES <file>...
13045 Specify an explicit list of specific files to be submitted.
13046 Each individual file must exist at the time of the call.
13047 SUBMIT_URL <url>
13049 New in version 3.14.
13050 The http or https URL of the dashboard server to send the sub‐
13053 mission to. If not given, the CTEST_SUBMIT_URL variable is
13054 used.
13055 BUILD_ID <result-var>
13057 New in version 3.15.
13058 Store in the <result-var> variable the ID assigned to this build
13061 by CDash.
13062 HTTPHEADER <HTTP-header>
13064 New in version 3.9.
13065 Specify HTTP header to be included in the request to CDash dur‐
13068 ing submission. For example, CDash can be configured to only
13069 accept submissions from authenticated clients. In this case, you
13070 should provide a bearer token in your header:
13071 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
13073 This suboption can be repeated several times for multiple head‐
13075 ers.
13076 RETRY_COUNT <count>
13078 Specify how many times to retry a timed-out submission.
13079 RETRY_DELAY <delay>
13081 Specify how long (in seconds) to wait after a timed-out submis‐
13082 sion before attempting to re-submit.
13083 RETURN_VALUE <result-var>
13085 Store in the <result-var> variable 0 for success and non-zero on
13086 failure.
13087 CAPTURE_CMAKE_ERROR <result-var>
13089 New in version 3.13.
13090 Store in the <result-var> variable -1 if there are any errors
13093 running the command and prevent ctest from returning non-zero if
13094 an error occurs.
13095 QUIET New in version 3.3.
13097 Suppress all non-error messages that would have otherwise been
13100 printed to the console.
13101 Submit to CDash Upload API
13103 New in version 3.2.
13104 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
13107 [SUBMIT_URL <url>]
13108 [BUILD_ID <result-var>]
13109 [HTTPHEADER <header>]
13110 [RETRY_COUNT <count>]
13111 [RETRY_DELAY <delay>]
13112 [RETURN_VALUE <result-var>]
13113 [QUIET])
13114 This second signature is used to upload files to CDash via the CDash
13116 file upload API. The API first sends a request to upload to CDash along
13117 with a content hash of the file. If CDash does not already have the
13118 file, then it is uploaded. Along with the file, a CDash type string is
13119 specified to tell CDash which handler to use to process the data.
13120 This signature interprets options in the same way as the first one.
13122 New in version 3.8: Added the RETRY_COUNT, RETRY_DELAY, QUIET options.
13124 New in version 3.9: Added the HTTPHEADER option.
13127 New in version 3.13: Added the RETURN_VALUE option.
13130 New in version 3.14: Added the SUBMIT_URL option.
13133 New in version 3.15: Added the BUILD_ID option.
13136 ctest_test
13139 Perform the CTest Test Step as a Dashboard Client.
13140 ctest_test([BUILD <build-dir>] [APPEND]
13142 [START <start-number>]
13143 [END <end-number>]
13144 [STRIDE <stride-number>]
13145 [EXCLUDE <exclude-regex>]
13146 [INCLUDE <include-regex>]
13147 [EXCLUDE_LABEL <label-exclude-regex>]
13148 [INCLUDE_LABEL <label-include-regex>]
13149 [EXCLUDE_FIXTURE <regex>]
13150 [EXCLUDE_FIXTURE_SETUP <regex>]
13151 [EXCLUDE_FIXTURE_CLEANUP <regex>]
13152 [PARALLEL_LEVEL <level>]
13153 [RESOURCE_SPEC_FILE <file>]
13154 [TEST_LOAD <threshold>]
13155 [SCHEDULE_RANDOM <ON|OFF>]
13156 [STOP_ON_FAILURE]
13157 [STOP_TIME <time-of-day>]
13158 [RETURN_VALUE <result-var>]
13159 [CAPTURE_CMAKE_ERROR <result-var>]
13160 [REPEAT <mode>:<n>]
13161 [OUTPUT_JUNIT <file>]
13162 [QUIET]
13163 )
13164 Run tests in the project build tree and store results in Test.xml for
13166 submission with the ctest_submit() command.
13167 The options are:
13169 BUILD <build-dir>
13171 Specify the top-level build directory. If not given, the
13172 CTEST_BINARY_DIRECTORY variable is used.
13173 APPEND Mark Test.xml for append to results previously submitted to a
13175 dashboard server since the last ctest_start() call. Append se‐
13176 mantics are defined by the dashboard server in use. This does
13177 not cause results to be appended to a .xml file produced by a
13178 previous call to this command.
13179 START <start-number>
13181 Specify the beginning of a range of test numbers.
13182 END <end-number>
13184 Specify the end of a range of test numbers.
13185 STRIDE <stride-number>
13187 Specify the stride by which to step across a range of test num‐
13188 bers.
13189 EXCLUDE <exclude-regex>
13191 Specify a regular expression matching test names to exclude.
13192 INCLUDE <include-regex>
13194 Specify a regular expression matching test names to include.
13195 Tests not matching this expression are excluded.
13196 EXCLUDE_LABEL <label-exclude-regex>
13198 Specify a regular expression matching test labels to exclude.
13199 INCLUDE_LABEL <label-include-regex>
13201 Specify a regular expression matching test labels to include.
13202 Tests not matching this expression are excluded.
13203 EXCLUDE_FIXTURE <regex>
13205 New in version 3.7.
13206 If a test in the set of tests to be executed requires a particu‐
13209 lar fixture, that fixture's setup and cleanup tests would nor‐
13210 mally be added to the test set automatically. This option pre‐
13211 vents adding setup or cleanup tests for fixtures matching the
13212 <regex>. Note that all other fixture behavior is retained, in‐
13213 cluding test dependencies and skipping tests that have fixture
13214 setup tests that fail.
13215 EXCLUDE_FIXTURE_SETUP <regex>
13217 New in version 3.7.
13218 Same as EXCLUDE_FIXTURE except only matching setup tests are ex‐
13221 cluded.
13222 EXCLUDE_FIXTURE_CLEANUP <regex>
13224 New in version 3.7.
13225 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
13228 excluded.
13229 PARALLEL_LEVEL <level>
13231 Specify a positive number representing the number of tests to be
13232 run in parallel.
13233 RESOURCE_SPEC_FILE <file>
13235 New in version 3.16.
13236 Specify a resource specification file. See Resource Allocation
13239 for more information.
13240 TEST_LOAD <threshold>
13242 New in version 3.4.
13243 While running tests in parallel, try not to start tests when
13246 they may cause the CPU load to pass above a given threshold. If
13247 not specified the CTEST_TEST_LOAD variable will be checked, and
13248 then the --test-load command-line argument to ctest(1). See also
13249 the TestLoad setting in the CTest Test Step.
13250 REPEAT <mode>:<n>
13252 New in version 3.17.
13253 Run tests repeatedly based on the given <mode> up to <n> times.
13256 The modes are:
13257 UNTIL_FAIL
13259 Require each test to run <n> times without failing in or‐
13260 der to pass. This is useful in finding sporadic failures
13261 in test cases.
13262 UNTIL_PASS
13264 Allow each test to run up to <n> times in order to pass.
13265 Repeats tests if they fail for any reason. This is use‐
13266 ful in tolerating sporadic failures in test cases.
13267 AFTER_TIMEOUT
13269 Allow each test to run up to <n> times in order to pass.
13270 Repeats tests only if they timeout. This is useful in
13271 tolerating sporadic timeouts in test cases on busy ma‐
13272 chines.
13273 SCHEDULE_RANDOM <ON|OFF>
13275 Launch tests in a random order. This may be useful for detect‐
13276 ing implicit test dependencies.
13277 STOP_ON_FAILURE
13279 New in version 3.18.
13280 Stop the execution of the tests once one has failed.
13283 STOP_TIME <time-of-day>
13285 Specify a time of day at which the tests should all stop run‐
13286 ning.
13287 RETURN_VALUE <result-var>
13289 Store in the <result-var> variable 0 if all tests passed. Store
13290 non-zero if anything went wrong.
13291 CAPTURE_CMAKE_ERROR <result-var>
13293 New in version 3.7.
13294 Store in the <result-var> variable -1 if there are any errors
13297 running the command and prevent ctest from returning non-zero if
13298 an error occurs.
13299 OUTPUT_JUNIT <file>
13301 New in version 3.21.
13302 Write test results to <file> in JUnit XML format. If <file> is a
13305 relative path, it will be placed in the build directory. If
13306 <file> already exists, it will be overwritten. Note that the re‐
13307 sulting JUnit XML file is not uploaded to CDash because it would
13308 be redundant with CTest's Test.xml file.
13309 QUIET New in version 3.3.
13311 Suppress any CTest-specific non-error messages that would have
13314 otherwise been printed to the console. Output from the underly‐
13315 ing test command is not affected. Summary info detailing the
13316 percentage of passing tests is also unaffected by the QUIET op‐
13317 tion.
13318 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE,
13320 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE and
13321 CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION variables, along with their corre‐
13322 sponding ctest(1) command line options --test-output-size-passed,
13323 --test-output-size-failed, and --test-output-truncation.
13324 Additional Test Measurements
13326 CTest can parse the output of your tests for extra measurements to re‐
13327 port to CDash.
13328 When run as a Dashboard Client, CTest will include these custom mea‐
13330 surements in the Test.xml file that gets uploaded to CDash.
13331 Check the CDash test measurement documentation for more information on
13333 the types of test measurements that CDash recognizes.
13334 The following example demonstrates how to output a variety of custom
13336 test measurements.
13337 std::cout <<
13339 "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
13340 << std::endl;
13341 std::cout <<
13343 "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
13344 << std::endl;
13345 std::cout <<
13347 "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
13348 << std::endl;
13349 std::cout <<
13351 "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
13352 "line 1.\n" <<
13353 " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
13354 "line 3. Not bold or indented...\n" <<
13355 "</CTestMeasurement>" << std::endl;
13356 Image Measurements
13358 The following example demonstrates how to upload test images to CDash.
13359 std::cout <<
13361 "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
13362 "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;
13363 std::cout <<
13365 "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
13366 "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;
13367 std::cout <<
13369 "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
13370 "/dir/to/img.png</CTestMeasurementFile>"
13371 << std::endl;
13372 Images will be displayed together in an interactive comparison mode on
13374 CDash if they are provided with two or more of the following names.
13375 • TestImage
13377 • ValidImage
13379 • BaselineImage
13381 • DifferenceImage2
13383 By convention, TestImage is the image generated by your test, and Va‐
13385 lidImage (or BaselineImage) is basis of comparison used to determine if
13386 the test passed or failed.
13387 If another image name is used it will be displayed by CDash as a static
13389 image separate from the interactive comparison UI.
13390 Attached Files
13392 New in version 3.21.
13393 The following example demonstrates how to upload non-image files to
13396 CDash.
13397 std::cout <<
13399 "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
13400 "/dir/to/data1.csv</CTestMeasurementFile>\n" <<
13401 "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
13402 "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl;
13403 If the name of the file to upload is known at configure time, you can
13405 use the ATTACHED_FILES or ATTACHED_FILES_ON_FAIL test properties in‐
13406 stead.
13407 Custom Details
13409 New in version 3.21.
13410 The following example demonstrates how to specify a custom value for
13413 the Test Details field displayed on CDash.
13414 std::cout <<
13416 "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;
13417 Additional Labels
13419 New in version 3.22.
13420 The following example demonstrates how to add additional labels to a
13423 test at runtime.
13424 std::cout <<
13426 "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
13427 "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl;
13428 Use the LABELS test property instead for labels that can be determined
13430 at configure time.
13431 ctest_update
13433 Perform the CTest Update Step as a Dashboard Client.
13434 ctest_update([SOURCE <source-dir>]
13436 [RETURN_VALUE <result-var>]
13437 [CAPTURE_CMAKE_ERROR <result-var>]
13438 [QUIET])
13439 Update the source tree from version control and record results in Up‐
13441 date.xml for submission with the ctest_submit() command.
13442 The options are:
13444 SOURCE <source-dir>
13446 Specify the source directory. If not given, the
13447 CTEST_SOURCE_DIRECTORY variable is used.
13448 RETURN_VALUE <result-var>
13450 Store in the <result-var> variable the number of files updated
13451 or -1 on error.
13452 CAPTURE_CMAKE_ERROR <result-var>
13454 New in version 3.13.
13455 Store in the <result-var> variable -1 if there are any errors
13458 running the command and prevent ctest from returning non-zero if
13459 an error occurs.
13460 QUIET New in version 3.3.
13462 Tell CTest to suppress most non-error messages that it would
13465 have otherwise printed to the console. CTest will still report
13466 the new revision of the repository and any conflicting files
13467 that were found.
13468 The update always follows the version control branch currently checked
13470 out in the source directory. See the CTest Update Step documentation
13471 for information about variables that change the behavior of ctest_up‐
13472 date().
13473 ctest_upload
13475 Upload files to a dashboard server as a Dashboard Client.
13476 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
13478 The options are:
13480 FILES <file>...
13482 Specify a list of files to be sent along with the build results
13483 to the dashboard server.
13484 QUIET New in version 3.3.
13486 Suppress any CTest-specific non-error output that would have
13489 been printed to the console otherwise.
13490 CAPTURE_CMAKE_ERROR <result-var>
13492 New in version 3.7.
13493 Store in the <result-var> variable -1 if there are any errors
13496 running the command and prevent ctest from returning non-zero if
13497 an error occurs.
13498
13500 These commands are deprecated and are only made available to maintain
13501 backward compatibility. The documentation of each command states the
13502 CMake version in which it was deprecated. Do not use these commands in
13503 new code.
13504 build_name
13506 Disallowed since version 3.0. See CMake Policy CMP0036.
13507 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
13509 build_name(variable)
13511 Sets the specified variable to a string representing the platform and
13513 compiler settings. These values are now available through the
13514 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
13515 exec_program
13517 Deprecated since version 3.0: Use the execute_process() command in‐
13518 stead.
13519 Run an executable program during the processing of the CMakeList.txt
13522 file.
13523 exec_program(Executable [directory in which to run]
13525 [ARGS <arguments to executable>]
13526 [OUTPUT_VARIABLE <var>]
13527 [RETURN_VALUE <var>])
13528 The executable is run in the optionally specified directory. The exe‐
13530 cutable can include arguments if it is double quoted, but it is better
13531 to use the optional ARGS argument to specify arguments to the program.
13532 This is because cmake will then be able to escape spaces in the exe‐
13533 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
13534 able in which to store the output. To capture the return value of the
13535 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
13536 then no output will go to the stdout/stderr of the console running
13537 cmake.
13538 export_library_dependencies
13540 Disallowed since version 3.0. See CMake Policy CMP0033.
13541 Use install(EXPORT) or export() command.
13543 This command generates an old-style library dependencies file.
13545 Projects requiring CMake 2.6 or later should not use the command. Use
13546 instead the install(EXPORT) command to help export targets from an in‐
13547 stallation tree and the export() command to export targets from a build
13548 tree.
13549 The old-style library dependencies file does not take into account
13551 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
13552 target property.
13553 export_library_dependencies(<file> [APPEND])
13555 Create a file named <file> that can be included into a CMake listfile
13557 with the INCLUDE command. The file will contain a number of SET com‐
13558 mands that will set all the variables needed for library dependency in‐
13559 formation. This should be the last command in the top level CMake‐
13560 Lists.txt file of the project. If the APPEND option is specified, the
13561 SET commands will be appended to the given file instead of replacing
13562 it.
13563 install_files
13565 Deprecated since version 3.0: Use the install(FILES) command instead.
13566 This command has been superseded by the install() command. It is pro‐
13569 vided for compatibility with older CMake code. The FILES form is di‐
13570 rectly replaced by the FILES form of the install() command. The regexp
13571 form can be expressed more clearly using the GLOB form of the file()
13572 command.
13573 install_files(<dir> extension file file ...)
13575 Create rules to install the listed files with the given extension into
13577 the given directory. Only files existing in the current source tree or
13578 its corresponding location in the binary tree may be listed. If a file
13579 specified already has an extension, that extension will be removed
13580 first. This is useful for providing lists of source files such as
13581 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
13582 cal extension is .h.
13583 install_files(<dir> regexp)
13585 Any files in the current source directory that match the regular ex‐
13587 pression will be installed.
13588 install_files(<dir> FILES file file ...)
13590 Any files listed after the FILES keyword will be installed explicitly
13592 from the names given. Full paths are allowed in this form.
13593 The directory <dir> is relative to the installation prefix, which is
13595 stored in the variable CMAKE_INSTALL_PREFIX.
13596 install_programs
13598 Deprecated since version 3.0: Use the install(PROGRAMS) command in‐
13599 stead.
13600 This command has been superseded by the install() command. It is pro‐
13603 vided for compatibility with older CMake code. The FILES form is di‐
13604 rectly replaced by the PROGRAMS form of the install() command. The
13605 regexp form can be expressed more clearly using the GLOB form of the
13606 file() command.
13607 install_programs(<dir> file1 file2 [file3 ...])
13609 install_programs(<dir> FILES file1 [file2 ...])
13610 Create rules to install the listed programs into the given directory.
13612 Use the FILES argument to guarantee that the file list version of the
13613 command will be used even when there is only one argument.
13614 install_programs(<dir> regexp)
13616 In the second form any program in the current source directory that
13618 matches the regular expression will be installed.
13619 This command is intended to install programs that are not built by
13621 cmake, such as shell scripts. See the TARGETS form of the install()
13622 command to create installation rules for targets built by cmake.
13623 The directory <dir> is relative to the installation prefix, which is
13625 stored in the variable CMAKE_INSTALL_PREFIX.
13626 install_targets
13628 Deprecated since version 3.0: Use the install(TARGETS) command instead.
13629 This command has been superseded by the install() command. It is pro‐
13632 vided for compatibility with older CMake code.
13633 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
13635 Create rules to install the listed targets into the given directory.
13637 The directory <dir> is relative to the installation prefix, which is
13638 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
13639 specified, then on systems with special runtime files (Windows DLL),
13640 the files will be copied to that directory.
13641 load_command
13643 Disallowed since version 3.0. See CMake Policy CMP0031.
13644 Load a command into a running CMake.
13646 load_command(COMMAND_NAME <loc1> [loc2 ...])
13648 The given locations are searched for a library whose name is cmCOM‐
13650 MAND_NAME. If found, it is loaded as a module and the command is added
13651 to the set of available CMake commands. Usually, try_compile() is used
13652 before this command to compile the module. If the command is success‐
13653 fully loaded a variable named
13654 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
13656 will be set to the full path of the module that was loaded. Otherwise
13658 the variable will not be set.
13659 make_directory
13661 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command in‐
13662 stead.
13663 make_directory(directory)
13666 Creates the specified directory. Full paths should be given. Any par‐
13668 ent directories that do not exist will also be created. Use with care.
13669 output_required_files
13671 Disallowed since version 3.0. See CMake Policy CMP0032.
13672 Approximate C preprocessor dependency scanning.
13674 This command exists only because ancient CMake versions provided it.
13676 CMake handles preprocessor dependency scanning automatically using a
13677 more advanced scanner.
13678 output_required_files(srcfile outputfile)
13680 Outputs a list of all the source files that are required by the speci‐
13682 fied srcfile. This list is written into outputfile. This is similar
13683 to writing out the dependencies for srcfile except that it jumps from
13684 .h files into .cxx, .c and .cpp files if possible.
13685 qt_wrap_cpp
13687 Deprecated since version 3.14: This command was originally added to
13688 support Qt 3 before the add_custom_command() command was sufficiently
13689 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
13690 should be used instead for Qt 4 projects. For projects using Qt 5 or
13691 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
13692 vides qt5_wrap_cpp()).
13693 Manually create Qt Wrappers.
13696 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
13698 Produces moc files for all the .h files listed in the SourceLists. The
13700 moc files will be added to the library using the DestName source list.
13701 Consider updating the project to use the AUTOMOC target property in‐
13703 stead for a more automated way of invoking the moc tool.
13704 qt_wrap_ui
13706 Deprecated since version 3.14: This command was originally added to
13707 support Qt 3 before the add_custom_command() command was sufficiently
13708 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
13709 should be used instead for Qt 4 projects. For projects using Qt 5 or
13710 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
13711 vides qt5_wrap_ui()).
13712 Manually create Qt user interfaces Wrappers.
13715 qt_wrap_ui(resultingLibraryName HeadersDestName
13717 SourcesDestName SourceLists ...)
13718 Produces .h and .cxx files for all the .ui files listed in the
13720 SourceLists. The .h files will be added to the library using the Head‐
13721 ersDestNamesource list. The .cxx files will be added to the library
13722 using the SourcesDestNamesource list.
13723 Consider updating the project to use the AUTOUIC target property in‐
13725 stead for a more automated way of invoking the uic tool.
13726 remove
13728 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command in‐
13729 stead.
13730 remove(VAR VALUE VALUE ...)
13733 Removes VALUE from the variable VAR. This is typically used to remove
13735 entries from a vector (e.g. semicolon separated list). VALUE is ex‐
13736 panded.
13737 subdir_depends
13739 Disallowed since version 3.0. See CMake Policy CMP0029.
13740 Does nothing.
13742 subdir_depends(subdir dep1 dep2 ...)
13744 Does not do anything. This command used to help projects order paral‐
13746 lel builds correctly. This functionality is now automatic.
13747 subdirs
13749 Deprecated since version 3.0: Use the add_subdirectory() command in‐
13750 stead.
13751 Add a list of subdirectories to the build.
13754 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
13756 [PREORDER] )
13757 Add a list of subdirectories to the build. The add_subdirectory() com‐
13759 mand should be used instead of subdirs although subdirs will still
13760 work. This will cause any CMakeLists.txt files in the sub directories
13761 to be processed by CMake. Any directories after the PREORDER flag are
13762 traversed first by makefile builds, the PREORDER flag has no effect on
13763 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
13764 not be included in the top level makefile or project file. This is
13765 useful for having CMake create makefiles or projects for a set of exam‐
13766 ples in a project. You would want CMake to generate makefiles or
13767 project files for all the examples at the same time, but you would not
13768 want them to show up in the top level project or be built each time
13769 make is run from the top.
13770 use_mangled_mesa
13772 Disallowed since version 3.0. See CMake Policy CMP0030.
13773 Copy mesa headers for use in combination with system GL.
13775 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
13777 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
13779 ers are copied to the specified output directory. This allows mangled
13780 mesa headers to override other GL headers by being added to the include
13781 directory path earlier.
13782 utility_source
13784 Disallowed since version 3.0. See CMake Policy CMP0034.
13785 Specify the source tree of a third-party utility.
13787 utility_source(cache_entry executable_name
13789 path_to_source [file1 file2 ...])
13790 When a third-party utility's source is included in the distribution,
13792 this command specifies its location and name. The cache entry will not
13793 be set unless the path_to_source and all listed files exist. It is as‐
13794 sumed that the source tree of the utility will have been built before
13795 it is needed.
13796 When cross compiling CMake will print a warning if a utility_source()
13798 command is executed, because in many cases it is used to build an exe‐
13799 cutable which is executed later on. This doesn't work when cross com‐
13800 piling, since the executable can run only on their target platform. So
13801 in this case the cache entry has to be adjusted manually so it points
13802 to an executable which is runnable on the build host.
13803 variable_requires
13805 Disallowed since version 3.0. See CMake Policy CMP0035.
13806 Use the if() command instead.
13808 Assert satisfaction of an option's required variables.
13810 variable_requires(TEST_VARIABLE RESULT_VARIABLE
13812 REQUIRED_VARIABLE1
13813 REQUIRED_VARIABLE2 ...)
13814 The first argument (TEST_VARIABLE) is the name of the variable to be
13816 tested, if that variable is false nothing else is done. If TEST_VARI‐
13817 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
13818 that is set to true if all the required variables are set. The rest of
13819 the arguments are variables that must be true or not set to NOTFOUND to
13820 avoid an error. If any are not true, an error is reported.
13821 write_file
13823 Deprecated since version 3.0: Use the file(WRITE) command instead.
13824 write_file(filename "message to write"... [APPEND])
13827 The first argument is the file name, the rest of the arguments are mes‐
13829 sages to write. If the argument APPEND is specified, then the message
13830 will be appended.
13831 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
13833 but add some more functionality.
13834 NOTE 2: When using write_file the produced file cannot be used as an
13836 input to CMake (CONFIGURE_FILE, source file ...) because it will lead
13837 to an infinite loop. Use configure_file() if you want to generate in‐
13838 put files to CMake.
13839
13841 2000-2023 Kitware, Inc. and Contributors
138423.25.2 Jan 19, 2023 CMAKE-COMMANDS(7)