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).
499 For example, the code:
500 set(message_command "message")
502 cmake_language(CALL ${message_command} STATUS "Hello World!")
503 is equivalent to
505 message(STATUS "Hello World!")
507 NOTE:
509 To ensure consistency of the code, the following commands are
510 not allowed:
511 • if / elseif / else / endif
513 • block / endblock
515 • while / endwhile
517 • foreach / endforeach
519 • function / endfunction
521 • macro / endmacro
523 Evaluating Code
525 cmake_language(EVAL CODE <code>...)
526 Evaluates the <code>... as CMake code.
527 For example, the code:
529 set(A TRUE)
531 set(B TRUE)
532 set(C TRUE)
533 set(condition "(A AND B) OR C")
534 cmake_language(EVAL CODE "
536 if (${condition})
537 message(STATUS TRUE)
538 else()
539 message(STATUS FALSE)
540 endif()"
541 )
542 is equivalent to
544 set(A TRUE)
546 set(B TRUE)
547 set(C TRUE)
548 set(condition "(A AND B) OR C")
549 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/eval.cmake "
551 if (${condition})
552 message(STATUS TRUE)
553 else()
554 message(STATUS FALSE)
555 endif()"
556 )
557 include(${CMAKE_CURRENT_BINARY_DIR}/eval.cmake)
559 Deferring Calls
561 New in version 3.19.
562 cmake_language(DEFER <options>... CALL <command> [<arg>...])
565 Schedules a call to the named <command> with the given arguments
566 (if any) to occur at a later time. By default, deferred calls
567 are executed as if written at the end of the current directory's
568 CMakeLists.txt file, except that they run even after a return()
569 call. Variable references in arguments are evaluated at the
570 time the deferred call is executed.
571 The options are:
573 DIRECTORY <dir>
575 Schedule the call for the end of the given directory in‐
576 stead of the current directory. The <dir> may reference
577 either a source directory or its corresponding binary di‐
578 rectory. Relative paths are treated as relative to the
579 current source directory.
580 The given directory must be known to CMake, being either
582 the top-level directory or one added by
583 add_subdirectory(). Furthermore, the given directory
584 must not yet be finished processing. This means it can
585 be the current directory or one of its ancestors.
586 ID <id>
588 Specify an identification for the deferred call. The
589 <id> may not be empty and may not begin with a capital
590 letter A-Z. The <id> may begin with an underscore (_)
591 only if it was generated automatically by an earlier call
592 that used ID_VAR to get the id.
593 ID_VAR <var>
595 Specify a variable in which to store the identification
596 for the deferred call. If ID <id> is not given, a new
597 identification will be generated and the generated id
598 will start with an underscore (_).
599 The currently scheduled list of deferred calls may be retrieved:
601 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL_IDS <var>)
603 This will store in <var> a semicolon-separated list of deferred
605 call ids. The ids are for the directory scope in which the
606 calls have been deferred to (i.e. where they will be executed),
607 which can be different to the scope in which they were created.
608 The DIRECTORY option can be used to specify the scope for which
609 to retrieve the call ids. If that option is not given, the call
610 ids for the current directory scope will be returned.
611 Details of a specific call may be retrieved from its id:
613 cmake_language(DEFER [DIRECTORY <dir>] GET_CALL <id> <var>)
615 This will store in <var> a semicolon-separated list in which the
617 first element is the name of the command to be called, and the
618 remaining elements are its unevaluated arguments (any contained
619 ; characters are included literally and cannot be distinguished
620 from multiple arguments). If multiple calls are scheduled with
621 the same id, this retrieves the first one. If no call is sched‐
622 uled with the given id in the specified DIRECTORY scope (or the
623 current directory scope if no DIRECTORY option is given), this
624 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
631 the specified DIRECTORY scope (or the current directory scope if
632 no DIRECTORY option is given). Unknown ids are silently ig‐
633 nored.
634 Deferred Call Examples
636 For example, the code:
637 cmake_language(DEFER CALL message "${deferred_message}")
639 cmake_language(DEFER ID_VAR id CALL message "Canceled Message")
640 cmake_language(DEFER CANCEL_CALL ${id})
641 message("Immediate Message")
642 set(deferred_message "Deferred Message")
643 prints:
645 Immediate Message
647 Deferred Message
648 The Cancelled Message is never printed because its command is canceled.
650 The deferred_message variable reference is not evaluated until the call
651 site, so it can be set after the deferred call is scheduled.
652 In order to evaluate variable references immediately when scheduling a
654 deferred call, wrap it using cmake_language(EVAL). However, note that
655 arguments will be re-evaluated in the deferred call, though that can be
656 avoided by using bracket arguments. For example:
657 set(deferred_message "Deferred Message 1")
659 set(re_evaluated [[${deferred_message}]])
660 cmake_language(EVAL CODE "
661 cmake_language(DEFER CALL message [[${deferred_message}]])
662 cmake_language(DEFER CALL message \"${re_evaluated}\")
663 ")
664 message("Immediate Message")
665 set(deferred_message "Deferred Message 2")
666 also prints:
668 Immediate Message
670 Deferred Message 1
671 Deferred Message 2
672 Dependency Providers
674 New in version 3.24.
675 NOTE:
678 A high-level introduction to this feature can be found in the Using
679 Dependencies Guide.
680 cmake_language(SET_DEPENDENCY_PROVIDER <command> SUPPORTED_METHODS
682 <methods>...)
683 When a call is made to find_package() or
684 FetchContent_MakeAvailable(), the call may be forwarded to a de‐
685 pendency provider which then has the opportunity to fulfill the
686 request. If the request is for one of the <methods> specified
687 when the provider was set, CMake calls the provider's <command>
688 with a set of method-specific arguments. If the provider does
689 not fulfill the request, or if the provider doesn't support the
690 request's method, or no provider is set, the built-in
691 find_package() or FetchContent_MakeAvailable() implementation is
692 used to fulfill the request in the usual way.
693 One or more of the following values can be specified for the
695 <methods> when setting the provider:
696 FIND_PACKAGE
698 The provider command accepts find_package() requests.
699 FETCHCONTENT_MAKEAVAILABLE_SERIAL
701 The provider command accepts FetchContent_MakeAvailable()
702 requests. It expects each dependency to be fed to the
703 provider command one at a time, not the whole list in one
704 go.
705 Only one provider can be set at any point in time. If a
707 provider is already set when cmake_language(SET_DEPEN‐
708 DENCY_PROVIDER) is called, the new provider replaces the previ‐
709 ously set one. The specified <command> must already exist when
710 cmake_language(SET_DEPENDENCY_PROVIDER) is called. As a special
711 case, providing an empty string for the <command> and no <meth‐
712 ods> will discard any previously set provider.
713 The dependency provider can only be set while processing one of
715 the files specified by the CMAKE_PROJECT_TOP_LEVEL_INCLUDES
716 variable. Thus, dependency providers can only be set as part of
717 the first call to project(). Calling cmake_language(SET_DEPEN‐
718 DENCY_PROVIDER) outside of that context will result in an error.
719 NOTE:
721 The choice of dependency provider should always be under the
722 user's control. As a convenience, a project may choose to
723 provide a file that users can list in their
724 CMAKE_PROJECT_TOP_LEVEL_INCLUDES variable, but the use of
725 such a file should always be the user's choice.
726 Provider commands
728 Providers define a single <command> to accept requests. The name of
729 the command should be specific to that provider, not something overly
730 generic that another provider might also use. This enables users to
731 compose different providers in their own custom provider. The recom‐
732 mended form is xxx_provide_dependency(), where xxx is the provider-spe‐
733 cific part (e.g. vcpkg_provide_dependency(), conan_provide_depen‐
734 dency(), ourcompany_provide_dependency(), and so on).
735 xxx_provide_dependency(<method> [<method-specific-args>...])
737 Because some methods expect certain variables to be set in the calling
739 scope, the provider command should typically be implemented as a macro
740 rather than a function. This ensures it does not introduce a new vari‐
741 able scope.
742 The arguments CMake passes to the dependency provider depend on the
744 type of request. The first argument is always the method, and it will
745 only ever be one of the <methods> that was specified when setting the
746 provider.
747 FIND_PACKAGE
749 The <method-specific-args> will be everything passed to the
750 find_package() call that requested the dependency. The first of
751 these <method-specific-args> will therefore always be the name
752 of the dependency. Dependency names are case-sensitive for this
753 method because find_package() treats them case-sensitively too.
754 If the provider command fulfills the request, it must set the
756 same variable that find_package() expects to be set. For a de‐
757 pendency named depName, the provider must set depName_FOUND to
758 true if it fulfilled the request. If the provider returns with‐
759 out setting this variable, CMake will assume the request was not
760 fulfilled and will fall back to the built-in implementation.
761 If the provider needs to call the built-in find_package() imple‐
763 mentation as part of its processing, it can do so by including
764 the BYPASS_PROVIDER keyword as one of the arguments.
765 FETCHCONTENT_MAKEAVAILABE_SERIAL
767 The <method-specific-args> will be everything passed to the
768 FetchContent_Declare() call that corresponds to the requested
769 dependency, with the following exceptions:
770 • If SOURCE_DIR or BINARY_DIR were not part of the original de‐
772 clared arguments, they will be added with their default val‐
773 ues.
774 • If FETCHCONTENT_TRY_FIND_PACKAGE_MODE is set to NEVER, any
776 FIND_PACKAGE_ARGS will be omitted.
777 • The OVERRIDE_FIND_PACKAGE keyword is always omitted.
779 The first of the <method-specific-args> will always be the name
781 of the dependency. Dependency names are case-insensitive for
782 this method because FetchContent also treats them case-insensi‐
783 tively.
784 If the provider fulfills the request, it should call
786 FetchContent_SetPopulated(), passing the name of the dependency
787 as the first argument. The SOURCE_DIR and BINARY_DIR arguments
788 to that command should only be given if the provider makes the
789 dependency's source and build directories available in exactly
790 the same way as the built-in FetchContent_MakeAvailable() com‐
791 mand.
792 If the provider returns without calling
794 FetchContent_SetPopulated() for the named dependency, CMake will
795 assume the request was not fulfilled and will fall back to the
796 built-in implementation.
797 Note that empty arguments may be significant for this method
799 (e.g. an empty string following a GIT_SUBMODULES keyword).
800 Therefore, if forwarding these arguments on to another command,
801 extra care must be taken to avoid such arguments being silently
802 dropped.
803 If FETCHCONTENT_SOURCE_DIR_<uppercaseDepName> is set, then the
805 dependency provider will never see requests for the <depName>
806 dependency for this method. When the user sets such a variable,
807 they are explicitly overriding where to get that dependency from
808 and are taking on the responsibility that their overriding ver‐
809 sion meets any requirements for that dependency and is compati‐
810 ble with whatever else in the project uses it. Depending on the
811 value of FETCHCONTENT_TRY_FIND_PACKAGE_MODE and whether the
812 OVERRIDE_FIND_PACKAGE option was given to
813 FetchContent_Declare(), having FETCHCONTENT_SOURCE_DIR_<upper‐
814 caseDepName> set may also prevent the dependency provider from
815 seeing requests for a find_package(depName) call too.
816 Provider Examples
818 This first example only intercepts find_package() calls. The provider
819 command runs an external tool which copies the relevant artifacts into
820 a provider-specific directory, if that tool knows about the dependency.
821 It then relies on the built-in implementation to then find those arti‐
822 facts. FetchContent_MakeAvailable() calls would not go through the
823 provider.
824 mycomp_provider.cmake
826 # Always ensure we have the policy settings this provider expects
828 cmake_minimum_required(VERSION 3.24)
829 set(MYCOMP_PROVIDER_INSTALL_DIR ${CMAKE_BINARY_DIR}/mycomp_packages
831 CACHE PATH "The directory this provider installs packages to"
832 )
833 # Tell the built-in implementation to look in our area first, unless
834 # the find_package() call uses NO_..._PATH options to exclude it
835 list(APPEND CMAKE_MODULE_PATH ${MYCOMP_PROVIDER_INSTALL_DIR}/cmake)
836 list(APPEND CMAKE_PREFIX_PATH ${MYCOMP_PROVIDER_INSTALL_DIR})
837 macro(mycomp_provide_dependency method package_name)
839 execute_process(
840 COMMAND some_tool ${package_name} --installdir ${MYCOMP_PROVIDER_INSTALL_DIR}
841 COMMAND_ERROR_IS_FATAL ANY
842 )
843 endmacro()
844 cmake_language(
846 SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
847 SUPPORTED_METHODS FIND_PACKAGE
848 )
849 The user would then typically use the above file like so:
851 cmake -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=/path/to/mycomp_provider.cmake ...
853 The next example demonstrates a provider that accepts both methods, but
855 only handles one specific dependency. It enforces providing Google
856 Test using FetchContent, but leaves all other dependencies to be ful‐
857 filled by CMake's built-in implementation. It accepts a few different
858 names, which demonstrates one way of working around projects that
859 hard-code an unusual or undesirable way of adding this particular de‐
860 pendency to the build. The example also demonstrates how to use the
861 list() command to preserve variables that may be overwritten by a call
862 to FetchContent_MakeAvailable().
863 mycomp_provider.cmake
865 cmake_minimum_required(VERSION 3.24)
867 # Because we declare this very early, it will take precedence over any
869 # details the project might declare later for the same thing
870 include(FetchContent)
871 FetchContent_Declare(
872 googletest
873 GIT_REPOSITORY https://github.com/google/googletest.git
874 GIT_TAG e2239ee6043f73722e7aa812a459f54a28552929 # release-1.11.0
875 )
876 # Both FIND_PACKAGE and FETCHCONTENT_MAKEAVAILABLE_SERIAL methods provide
878 # the package or dependency name as the first method-specific argument.
879 macro(mycomp_provide_dependency method dep_name)
880 if("${dep_name}" MATCHES "^(gtest|googletest)$")
881 # Save our current command arguments in case we are called recursively
882 list(APPEND mycomp_provider_args ${method} ${dep_name})
883 # This will forward to the built-in FetchContent implementation,
885 # which detects a recursive call for the same thing and avoids calling
886 # the provider again if dep_name is the same as the current call.
887 FetchContent_MakeAvailable(googletest)
888 # Restore our command arguments
890 list(POP_BACK mycomp_provider_args dep_name method)
891 # Tell the caller we fulfilled the request
893 if("${method}" STREQUAL "FIND_PACKAGE")
894 # We need to set this if we got here from a find_package() call
895 # since we used a different method to fulfill the request.
896 # This example assumes projects only use the gtest targets,
897 # not any of the variables the FindGTest module may define.
898 set(${dep_name}_FOUND TRUE)
899 elseif(NOT "${dep_name}" STREQUAL "googletest")
900 # We used the same method, but were given a different name to the
901 # one we populated with. Tell the caller about the name it used.
902 FetchContent_SetPopulated(${dep_name}
903 SOURCE_DIR "${googletest_SOURCE_DIR}"
904 BINARY_DIR "${googletest_BINARY_DIR}"
905 )
906 endif()
907 endif()
908 endmacro()
909 cmake_language(
911 SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
912 SUPPORTED_METHODS
913 FIND_PACKAGE
914 FETCHCONTENT_MAKEAVAILABLE_SERIAL
915 )
916 The final example demonstrates how to modify arguments to a
918 find_package() call. It forces all such calls to have the QUIET key‐
919 word. It uses the BYPASS_PROVIDER keyword to prevent calling the
920 provider command recursively for the same dependency.
921 mycomp_provider.cmake
923 cmake_minimum_required(VERSION 3.24)
925 macro(mycomp_provide_dependency method)
927 find_package(${ARGN} BYPASS_PROVIDER QUIET)
928 endmacro()
929 cmake_language(
931 SET_DEPENDENCY_PROVIDER mycomp_provide_dependency
932 SUPPORTED_METHODS FIND_PACKAGE
933 )
934 Getting current message log level
936 New in version 3.25.
937 cmake_language(GET_MESSAGE_LOG_LEVEL <output_variable>)
940 Writes the current message() logging level into the given <out‐
941 put_variable>.
942 See message() for the possible logging levels.
944 The current message logging level can be set either using the
946 --log-level command line option of the cmake(1) program or using
947 the CMAKE_MESSAGE_LOG_LEVEL variable.
948 If both the command line option and the variable are set, the
950 command line option takes precedence. If neither are set, the
951 default logging level is returned.
952 cmake_minimum_required
954 Require a minimum version of cmake.
955 cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])
957 New in version 3.12: The optional <policy_max> version.
959 Sets the minimum required version of cmake for a project. Also updates
962 the policy settings as explained below.
963 <min> and the optional <policy_max> are each CMake versions of the form
965 major.minor[.patch[.tweak]], and the ... is literal.
966 If the running version of CMake is lower than the <min> required ver‐
968 sion it will stop processing the project and report an error. The op‐
969 tional <policy_max> version, if specified, must be at least the <min>
970 version and affects policy settings as described in Policy Settings.
971 If the running version of CMake is older than 3.12, the extra ... dots
972 will be seen as version component separators, resulting in the ...<max>
973 part being ignored and preserving the pre-3.12 behavior of basing poli‐
974 cies on <min>.
975 This command will set the value of the CMAKE_MINIMUM_REQUIRED_VERSION
977 variable to <min>.
978 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and higher.
980 It should be specified so CMake versions 2.4 and lower fail with an er‐
981 ror instead of just a warning.
982 NOTE:
984 Call the cmake_minimum_required() command at the beginning of the
985 top-level CMakeLists.txt file even before calling the project() com‐
986 mand. It is important to establish version and policy settings be‐
987 fore invoking other commands whose behavior they may affect. See
988 also policy CMP0000.
989 Calling cmake_minimum_required() inside a function() limits some ef‐
991 fects to the function scope when invoked. For example, the
992 CMAKE_MINIMUM_REQUIRED_VERSION variable won't be set in the calling
993 scope. Functions do not introduce their own policy scope though, so
994 policy settings of the caller will be affected (see below). Due to
995 this mix of things that do and do not affect the calling scope,
996 calling cmake_minimum_required() inside a function is generally dis‐
997 couraged.
998 Policy Settings
1000 The cmake_minimum_required(VERSION) command implicitly invokes the
1001 cmake_policy(VERSION) command to specify that the current project code
1002 is written for the given range of CMake versions. All policies known
1003 to the running version of CMake and introduced in the <min> (or <max>,
1004 if specified) version or earlier will be set to use NEW behavior. All
1005 policies introduced in later versions will be unset. This effectively
1006 requests behavior preferred as of a given CMake version and tells newer
1007 CMake versions to warn about their new policies.
1008 When a <min> version higher than 2.4 is specified the command implic‐
1010 itly invokes
1011 cmake_policy(VERSION <min>[...<max>])
1013 which sets CMake policies based on the range of versions specified.
1015 When a <min> version 2.4 or lower is given the command implicitly in‐
1016 vokes
1017 cmake_policy(VERSION 2.4[...<max>])
1019 which enables compatibility features for CMake 2.4 and lower.
1021 Changed in version 3.27: Compatibility with versions of CMake older
1023 than 3.5 is deprecated. Calls to cmake_minimum_required(VERSION) or
1024 cmake_policy(VERSION) that do not specify at least 3.5 as their policy
1025 version (optionally via ...<max>) will produce a deprecation warning in
1026 CMake 3.27 and above.
1027 Changed in version 3.19: Compatibility with versions of CMake older
1030 than 2.8.12 is deprecated. Calls to cmake_minimum_required(VERSION) or
1031 cmake_policy(VERSION) that do not specify at least 2.8.12 as their pol‐
1032 icy version (optionally via ...<max>) will produce a deprecation warn‐
1033 ing in CMake 3.19 and above.
1034 See Also
1037 • cmake_policy()
1038 cmake_parse_arguments
1040 Parse function or macro arguments.
1041 cmake_parse_arguments(<prefix> <options> <one_value_keywords>
1043 <multi_value_keywords> <args>...)
1044 cmake_parse_arguments(PARSE_ARGV <N> <prefix> <options>
1046 <one_value_keywords> <multi_value_keywords>)
1047 New in version 3.5: This command is implemented natively. Previously,
1049 it has been defined in the module CMakeParseArguments.
1050 This command is for use in macros or functions. It processes the argu‐
1053 ments given to that macro or function, and defines a set of variables
1054 which hold the values of the respective options.
1055 The first signature reads processes arguments passed in the <args>....
1057 This may be used in either a macro() or a function().
1058 New in version 3.7: The PARSE_ARGV signature is only for use in a
1060 function() body. In this case the arguments that are parsed come from
1061 the ARGV# variables of the calling function. The parsing starts with
1062 the <N>-th argument, where <N> is an unsigned integer. This allows for
1063 the values to have special characters like ; in them.
1064 The <options> argument contains all options for the respective macro,
1067 i.e. keywords which can be used when calling the macro without any
1068 value following, like e.g. the OPTIONAL keyword of the install() com‐
1069 mand.
1070 The <one_value_keywords> argument contains all keywords for this macro
1072 which are followed by one value, like e.g. DESTINATION keyword of the
1073 install() command.
1074 The <multi_value_keywords> argument contains all keywords for this
1076 macro which can be followed by more than one value, like e.g. the TAR‐
1077 GETS or FILES keywords of the install() command.
1078 Changed in version 3.5: All keywords shall be unique. I.e. every key‐
1080 word shall only be specified once in either <options>, <one_value_key‐
1081 words> or <multi_value_keywords>. A warning will be emitted if unique‐
1082 ness is violated.
1083 When done, cmake_parse_arguments will consider for each of the keywords
1086 listed in <options>, <one_value_keywords> and <multi_value_keywords> a
1087 variable composed of the given <prefix> followed by "_" and the name of
1088 the respective keyword. These variables will then hold the respective
1089 value from the argument list or be undefined if the associated option
1090 could not be found. For the <options> keywords, these will always be
1091 defined, to TRUE or FALSE, whether the option is in the argument list
1092 or not.
1093 All remaining arguments are collected in a variable <prefix>_UN‐
1095 PARSED_ARGUMENTS that will be undefined if all arguments were recog‐
1096 nized. This can be checked afterwards to see whether your macro was
1097 called with unrecognized parameters.
1098 New in version 3.15: <one_value_keywords> and <multi_value_keywords>
1100 that were given no values at all are collected in a variable <pre‐
1101 fix>_KEYWORDS_MISSING_VALUES that will be undefined if all keywords re‐
1102 ceived values. This can be checked to see if there were keywords with‐
1103 out any values given.
1104 Consider the following example macro, my_install(), which takes similar
1107 arguments to the real install() command:
1108 macro(my_install)
1110 set(options OPTIONAL FAST)
1111 set(oneValueArgs DESTINATION RENAME)
1112 set(multiValueArgs TARGETS CONFIGURATIONS)
1113 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
1114 "${multiValueArgs}" ${ARGN} )
1115 # ...
1117 Assume my_install() has been called like this:
1119 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub CONFIGURATIONS)
1121 After the cmake_parse_arguments call the macro will have set or unde‐
1123 fined the following variables:
1124 MY_INSTALL_OPTIONAL = TRUE
1126 MY_INSTALL_FAST = FALSE # was not used in call to my_install
1127 MY_INSTALL_DESTINATION = "bin"
1128 MY_INSTALL_RENAME <UNDEFINED> # was not used
1129 MY_INSTALL_TARGETS = "foo;bar"
1130 MY_INSTALL_CONFIGURATIONS <UNDEFINED> # was not used
1131 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" # nothing expected after "OPTIONAL"
1132 MY_INSTALL_KEYWORDS_MISSING_VALUES = "CONFIGURATIONS"
1133 # No value for "CONFIGURATIONS" given
1134 You can then continue and process these variables.
1136 Keywords terminate lists of values, e.g. if directly after a
1138 one_value_keyword another recognized keyword follows, this is inter‐
1139 preted as the beginning of the new option. E.g. my_install(TARGETS
1140 foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
1141 "OPTIONAL", but as OPTIONAL is a keyword itself MY_INSTALL_DESTINATION
1142 will be empty (but added to MY_INSTALL_KEYWORDS_MISSING_VALUES) and
1143 MY_INSTALL_OPTIONAL will therefore be set to TRUE.
1144 See Also
1146 • function()
1147 • macro()
1149 cmake_path
1151 New in version 3.20.
1152 This command is for the manipulation of paths. Only syntactic aspects
1155 of paths are handled, there is no interaction of any kind with any un‐
1156 derlying file system. The path may represent a non-existing path or
1157 even one that is not allowed to exist on the current file system or
1158 platform. For operations that do interact with the filesystem, see the
1159 file() command.
1160 NOTE:
1162 The cmake_path command handles paths in the format of the build sys‐
1163 tem (i.e. the host platform), not the target system. When
1164 cross-compiling, if the path contains elements that are not repre‐
1165 sentable on the host platform (e.g. a drive letter when the host is
1166 not Windows), the results will be unpredictable.
1167 Synopsis
1169 Conventions
1170 Path Structure And Terminology
1172 Normalization
1174 Decomposition
1176 cmake_path(GET <path-var> ROOT_NAME <out-var>)
1177 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
1178 cmake_path(GET <path-var> ROOT_PATH <out-var>)
1179 cmake_path(GET <path-var> FILENAME <out-var>)
1180 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
1181 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
1182 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
1183 cmake_path(GET <path-var> PARENT_PATH <out-var>)
1184 Query
1186 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
1187 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
1188 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
1189 cmake_path(HAS_FILENAME <path-var> <out-var>)
1190 cmake_path(HAS_EXTENSION <path-var> <out-var>)
1191 cmake_path(HAS_STEM <path-var> <out-var>)
1192 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
1193 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
1194 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
1195 cmake_path(IS_RELATIVE <path-var> <out-var>)
1196 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
1197 cmake_path(COMPARE <input1> <OP> <input2> <out-var>)
1198 Modification
1200 cmake_path(SET <path-var> [NORMALIZE] <input>)
1201 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1202 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1203 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
1204 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
1205 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
1206 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])
1207 Generation
1209 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
1210 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
1211 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])
1212 Native Conversion
1214 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
1215 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
1216 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
1217 Hashing
1219 cmake_path(HASH <path-var> <out-var>)
1220 Conventions
1222 The following conventions are used in this command's documentation:
1223 <path-var>
1225 Always the name of a variable. For commands that expect a
1226 <path-var> as input, the variable must exist and it is expected
1227 to hold a single path.
1228 <input>
1230 A string literal which may contain a path, path fragment, or
1231 multiple paths with a special separator depending on the com‐
1232 mand. See the description of each command to see how this is
1233 interpreted.
1234 <input>...
1236 Zero or more string literal arguments.
1237 <out-var>
1239 The name of a variable into which the result of a command will
1240 be written.
1241 Path Structure And Terminology
1243 A path has the following structure (all components are optional, with
1244 some constraints):
1245 root-name root-directory-separator (item-name directory-separator)* filename
1247 root-name
1249 Identifies the root on a filesystem with multiple roots (such as
1250 "C:" or "//myserver"). It is optional.
1251 root-directory-separator
1253 A directory separator that, if present, indicates that this path
1254 is absolute. If it is missing and the first element other than
1255 the root-name is an item-name, then the path is relative.
1256 item-name
1258 A sequence of characters that aren't directory separators. This
1259 name may identify a file, a hard link, a symbolic link, or a di‐
1260 rectory. Two special cases are recognized:
1261 • The item name consisting of a single dot character . is a
1263 directory name that refers to the current directory.
1264 • The item name consisting of two dot characters .. is a di‐
1266 rectory name that refers to the parent directory.
1267 The (...)* pattern shown above is to indicate that there can be
1269 zero or more item names, with multiple items separated by a di‐
1270 rectory-separator. The ()* characters are not part of the path.
1271 directory-separator
1273 The only recognized directory separator is a forward slash char‐
1274 acter /. If this character is repeated, it is treated as a sin‐
1275 gle directory separator. In other words, /usr///////lib is the
1276 same as /usr/lib.
1277 filename
1279 A path has a filename if it does not end with a directory-sepa‐
1280 rator. The filename is effectively the last item-name of the
1281 path, so it can also be a hard link, symbolic link or a direc‐
1282 tory.
1283 A filename can have an extension. By default, the extension is
1285 defined as the sub-string beginning at the left-most period (in‐
1286 cluding the period) and until the end of the filename. In com‐
1287 mands that accept a LAST_ONLY keyword, LAST_ONLY changes the in‐
1288 terpretation to the sub-string beginning at the right-most pe‐
1289 riod.
1290 The following exceptions apply to the above interpretation:
1292 • If the first character in the filename is a period, that
1294 period is ignored (i.e. a filename like ".profile" is
1295 treated as having no extension).
1296 • If the filename is either . or .., it has no extension.
1298 The stem is the part of the filename before the extension.
1300 Some commands refer to a root-path. This is the concatenation of
1302 root-name and root-directory-separator, either or both of which can be
1303 empty. A relative-part refers to the full path with any root-path re‐
1304 moved.
1305 Creating A Path Variable
1307 While a path can be created with care using an ordinary set() command,
1308 it is recommended to use cmake_path(SET) instead, as it automatically
1309 converts the path to the required form where required. The
1310 cmake_path(APPEND) subcommand may be another suitable alternative where
1311 a path needs to be constructed by joining fragments. The following ex‐
1312 ample compares the three methods for constructing the same path:
1313 set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")
1315 cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")
1317 cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")
1319 Modification and Generation sub-commands can either store the result
1321 in-place, or in a separate variable named after an OUTPUT_VARIABLE key‐
1322 word. All other sub-commands store the result in a mandatory <out-var>
1323 variable.
1324 Normalization
1326 Some sub-commands support normalizing a path. The algorithm used to
1327 normalize a path is as follows:
1328 1. If the path is empty, stop (the normalized form of an empty path is
1330 also an empty path).
1331 2. Replace each directory-separator, which may consist of multiple sep‐
1333 arators, with a single / (/a///b --> /a/b).
1334 3. Remove each solitary period (.) and any immediately following direc‐
1336 tory-separator (/a/./b/. --> /a/b).
1337 4. Remove each item-name (other than ..) that is immediately followed
1339 by a directory-separator and a .., along with any immediately fol‐
1340 lowing directory-separator (/a/b/../c --> a/c).
1341 5. If there is a root-directory, remove any .. and any directory-sepa‐
1343 rators immediately following them. The parent of the root directory
1344 is treated as still the root directory (/../a --> /a).
1345 6. If the last item-name is .., remove any trailing directory-separator
1347 (../ --> ..).
1348 7. If the path is empty by this stage, add a dot (normal form of ./ is
1350 .).
1351 Decomposition
1353 The following forms of the GET subcommand each retrieve a different
1354 component or group of components from a path. See Path Structure And
1355 Terminology for the meaning of each path component.
1356 cmake_path(GET <path-var> ROOT_NAME <out-var>)
1358 cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
1359 cmake_path(GET <path-var> ROOT_PATH <out-var>)
1360 cmake_path(GET <path-var> FILENAME <out-var>)
1361 cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
1362 cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
1363 cmake_path(GET <path-var> RELATIVE_PART <out-var>)
1364 cmake_path(GET <path-var> PARENT_PATH <out-var>)
1365 If a requested component is not present in the path, an empty string
1367 will be stored in <out-var>. For example, only Windows systems have
1368 the concept of a root-name, so when the host machine is non-Windows,
1369 the ROOT_NAME subcommand will always return an empty string.
1370 For PARENT_PATH, if the HAS_RELATIVE_PART subcommand returns false, the
1372 result is a copy of <path-var>. Note that this implies that a root di‐
1373 rectory is considered to have a parent, with that parent being itself.
1374 Where HAS_RELATIVE_PART returns true, the result will essentially be
1375 <path-var> with one less element.
1376 Root examples
1378 set(path "c:/a")
1379 cmake_path(GET path ROOT_NAME rootName)
1381 cmake_path(GET path ROOT_DIRECTORY rootDir)
1382 cmake_path(GET path ROOT_PATH rootPath)
1383 message("Root name is \"${rootName}\"")
1385 message("Root directory is \"${rootDir}\"")
1386 message("Root path is \"${rootPath}\"")
1387 Root name is "c:"
1389 Root directory is "/"
1390 Root path is "c:/"
1391 Filename examples
1393 set(path "/a/b")
1394 cmake_path(GET path FILENAME filename)
1395 message("First filename is \"${filename}\"")
1396 # Trailing slash means filename is empty
1398 set(path "/a/b/")
1399 cmake_path(GET path FILENAME filename)
1400 message("Second filename is \"${filename}\"")
1401 First filename is "b"
1403 Second filename is ""
1404 Extension and stem examples
1406 set(path "name.ext1.ext2")
1407 cmake_path(GET path EXTENSION fullExt)
1409 cmake_path(GET path STEM fullStem)
1410 message("Full extension is \"${fullExt}\"")
1411 message("Full stem is \"${fullStem}\"")
1412 # Effect of LAST_ONLY
1414 cmake_path(GET path EXTENSION LAST_ONLY lastExt)
1415 cmake_path(GET path STEM LAST_ONLY lastStem)
1416 message("Last extension is \"${lastExt}\"")
1417 message("Last stem is \"${lastStem}\"")
1418 # Special cases
1420 set(dotPath "/a/.")
1421 set(dotDotPath "/a/..")
1422 set(someMorePath "/a/.some.more")
1423 cmake_path(GET dotPath EXTENSION dotExt)
1424 cmake_path(GET dotPath STEM dotStem)
1425 cmake_path(GET dotDotPath EXTENSION dotDotExt)
1426 cmake_path(GET dotDotPath STEM dotDotStem)
1427 cmake_path(GET dotMorePath EXTENSION someMoreExt)
1428 cmake_path(GET dotMorePath STEM someMoreStem)
1429 message("Dot extension is \"${dotExt}\"")
1430 message("Dot stem is \"${dotStem}\"")
1431 message("Dot-dot extension is \"${dotDotExt}\"")
1432 message("Dot-dot stem is \"${dotDotStem}\"")
1433 message(".some.more extension is \"${someMoreExt}\"")
1434 message(".some.more stem is \"${someMoreStem}\"")
1435 Full extension is ".ext1.ext2"
1437 Full stem is "name"
1438 Last extension is ".ext2"
1439 Last stem is "name.ext1"
1440 Dot extension is ""
1441 Dot stem is "."
1442 Dot-dot extension is ""
1443 Dot-dot stem is ".."
1444 .some.more extension is ".more"
1445 .some.more stem is ".some"
1446 Relative part examples
1448 set(path "c:/a/b")
1449 cmake_path(GET path RELATIVE_PART result)
1450 message("Relative part is \"${result}\"")
1451 set(path "c/d")
1453 cmake_path(GET path RELATIVE_PART result)
1454 message("Relative part is \"${result}\"")
1455 set(path "/")
1457 cmake_path(GET path RELATIVE_PART result)
1458 message("Relative part is \"${result}\"")
1459 Relative part is "a/b"
1461 Relative part is "c/d"
1462 Relative part is ""
1463 Path traversal examples
1465 set(path "c:/a/b")
1466 cmake_path(GET path PARENT_PATH result)
1467 message("Parent path is \"${result}\"")
1468 set(path "c:/")
1470 cmake_path(GET path PARENT_PATH result)
1471 message("Parent path is \"${result}\"")
1472 Parent path is "c:/a"
1474 Parent path is "c:/"
1475 Query
1477 Each of the GET subcommands has a corresponding HAS_... subcommand
1478 which can be used to discover whether a particular path component is
1479 present. See Path Structure And Terminology for the meaning of each
1480 path component.
1481 cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
1483 cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
1484 cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
1485 cmake_path(HAS_FILENAME <path-var> <out-var>)
1486 cmake_path(HAS_EXTENSION <path-var> <out-var>)
1487 cmake_path(HAS_STEM <path-var> <out-var>)
1488 cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
1489 cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
1490 Each of the above follows the predictable pattern of setting <out-var>
1492 to true if the path has the associated component, or false otherwise.
1493 Note the following special cases:
1494 • For HAS_ROOT_PATH, a true result will only be returned if at least
1496 one of root-name or root-directory is non-empty.
1497 • For HAS_PARENT_PATH, the root directory is also considered to have a
1499 parent, which will be itself. The result is true except if the path
1500 consists of just a filename.
1501 cmake_path(IS_ABSOLUTE <path-var> <out-var>)
1503 Sets <out-var> to true if <path-var> is absolute. An absolute path is
1505 a path that unambiguously identifies the location of a file without
1506 reference to an additional starting location. On Windows, this means
1507 the path must have both a root-name and a root-directory-separator to
1508 be considered absolute. On other platforms, just a root-directory-sep‐
1509 arator is sufficient. Note that this means on Windows, IS_ABSOLUTE can
1510 be false while HAS_ROOT_DIRECTORY can be true.
1511 cmake_path(IS_RELATIVE <path-var> <out-var>)
1513 This will store the opposite of IS_ABSOLUTE in <out-var>.
1515 cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)
1517 Checks if <path-var> is the prefix of <input>.
1519 When the NORMALIZE option is specified, <path-var> and <input> are
1521 normalized before the check.
1522 set(path "/a/b/c")
1524 cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
1525 cmake_path(IS_PREFIX path "/a/b" result) # result = false
1526 cmake_path(IS_PREFIX path "/x/y/z" result) # result = false
1527 set(path "/a/b")
1529 cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result) # result = true
1530 cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)
1532 cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)
1533 Compares the lexical representations of two paths provided as string
1535 literals. No normalization is performed on either path, except multi‐
1536 ple consecutive directory separators are effectively collapsed into a
1537 single separator. Equality is determined according to the following
1538 pseudo-code logic:
1539 if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
1541 return FALSE
1542 if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
1544 return FALSE
1545 Return FALSE if a relative portion of <input1> is not lexicographically
1547 equal to the relative portion of <input2>. This comparison is performed path
1548 component-wise. If all of the components compare equal, then return TRUE.
1549 NOTE:
1551 Unlike most other cmake_path() subcommands, the COMPARE subcommand
1552 takes literal strings as input, not the names of variables.
1553 Modification
1555 cmake_path(SET <path-var> [NORMALIZE] <input>)
1556 Assign the <input> path to <path-var>. If <input> is a native path, it
1558 is converted into a cmake-style path with forward-slashes (/). On Win‐
1559 dows, the long filename marker is taken into account.
1560 When the NORMALIZE option is specified, the path is normalized after
1562 the conversion.
1563 For example:
1565 set(native_path "c:\\a\\b/..\\c")
1567 cmake_path(SET path "${native_path}")
1568 message("CMake path is \"${path}\"")
1569 cmake_path(SET path NORMALIZE "${native_path}")
1571 message("Normalized CMake path is \"${path}\"")
1572 Output:
1574 CMake path is "c:/a/b/../c"
1576 Normalized CMake path is "c:/a/c"
1577 cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1579 Append all the <input> arguments to the <path-var> using / as the di‐
1581 rectory-separator. Depending on the <input>, the previous contents of
1582 <path-var> may be discarded. For each <input> argument, the following
1583 algorithm (pseudo-code) applies:
1584 # <path> is the contents of <path-var>
1586 if(<input>.is_absolute() OR
1588 (<input>.has_root_name() AND
1589 NOT <input>.root_name() STREQUAL <path>.root_name()))
1590 replace <path> with <input>
1591 return()
1592 endif()
1593 if(<input>.has_root_directory())
1595 remove any root-directory and the entire relative path from <path>
1596 elseif(<path>.has_filename() OR
1597 (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
1598 append directory-separator to <path>
1599 endif()
1600 append <input> omitting any root-name to <path>
1602 cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
1604 Append all the <input> arguments to the <path-var> without adding any
1606 directory-separator.
1607 cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
1609 Removes the filename component (as returned by GET ... FILENAME) from
1611 <path-var>. After removal, any trailing directory-separator is left
1612 alone, if present.
1613 If OUTPUT_VARIABLE is not given, then after this function returns,
1615 HAS_FILENAME returns false for <path-var>.
1616 For example:
1618 set(path "/a/b")
1620 cmake_path(REMOVE_FILENAME path)
1621 message("First path is \"${path}\"")
1622 # filename is now already empty, the following removes nothing
1624 cmake_path(REMOVE_FILENAME path)
1625 message("Second path is \"${result}\"")
1626 Output:
1628 First path is "/a/"
1630 Second path is "/a/"
1631 cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
1633 Replaces the filename component from <path-var> with <input>. If
1635 <path-var> has no filename component (i.e. HAS_FILENAME returns
1636 false), the path is unchanged. The operation is equivalent to the fol‐
1637 lowing:
1638 cmake_path(HAS_FILENAME path has_filename)
1640 if(has_filename)
1641 cmake_path(REMOVE_FILENAME path)
1642 cmake_path(APPEND path input);
1643 endif()
1644 cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY]
1646 [OUTPUT_VARIABLE <out-var>])
1647 Removes the extension, if any, from <path-var>.
1649 cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input>
1651 [OUTPUT_VARIABLE <out-var>])
1652 Replaces the extension with <input>. Its effect is equivalent to the
1654 following:
1655 cmake_path(REMOVE_EXTENSION path)
1657 if(NOT "input" MATCHES "^\\.")
1658 cmake_path(APPEND_STRING path ".")
1659 endif()
1660 cmake_path(APPEND_STRING path "input")
1661 Generation
1663 cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
1664 Normalize <path-var> according the steps described in Normalization.
1666 cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>]
1668 [OUTPUT_VARIABLE <out-var>])
1669 Modifies <path-var> to make it relative to the BASE_DIRECTORY argument.
1671 If BASE_DIRECTORY is not specified, the default base directory will be
1672 CMAKE_CURRENT_SOURCE_DIR.
1673 For reference, the algorithm used to compute the relative path is the
1675 same as that used by C++ std::filesystem::path::lexically_relative.
1676 cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE]
1678 [OUTPUT_VARIABLE <out-var>])
1679 If <path-var> is a relative path (IS_RELATIVE is true), it is evaluated
1681 relative to the given base directory specified by BASE_DIRECTORY op‐
1682 tion. If BASE_DIRECTORY is not specified, the default base directory
1683 will be CMAKE_CURRENT_SOURCE_DIR.
1684 When the NORMALIZE option is specified, the path is normalized after
1686 the path computation.
1687 Because cmake_path() does not access the filesystem, symbolic links are
1689 not resolved and any leading tilde is not expanded. To compute a real
1690 path with symbolic links resolved and leading tildes expanded, use the
1691 file(REAL_PATH) command instead.
1692 Native Conversion
1694 For commands in this section, native refers to the host platform, not
1695 the target platform when cross-compiling.
1696 cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
1698 Converts a cmake-style <path-var> into a native path with platform-spe‐
1700 cific slashes (\ on Windows hosts and / elsewhere).
1701 When the NORMALIZE option is specified, the path is normalized before
1703 the conversion.
1704 cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
1706 Converts a native <input> path into a cmake-style path with forward
1708 slashes (/). On Windows hosts, the long filename marker is taken into
1709 account. The input can be a single path or a system search path like
1710 $ENV{PATH}. A search path will be converted to a cmake-style list sep‐
1711 arated by ; characters (on non-Windows platforms, this essentially
1712 means : separators are replaced with ;). The result of the conversion
1713 is stored in the <out-var> variable.
1714 When the NORMALIZE option is specified, the path is normalized before
1716 the conversion.
1717 NOTE:
1719 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1720 takes a literal string as input, not the name of a variable.
1721 cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])
1723 Converts a cmake-style <input> path into a native path with plat‐
1725 form-specific slashes (\ on Windows hosts and / elsewhere). The input
1726 can be a single path or a cmake-style list. A list will be converted
1727 into a native search path (;-separated on Windows, :-separated on other
1728 platforms). The result of the conversion is stored in the <out-var>
1729 variable.
1730 When the NORMALIZE option is specified, the path is normalized before
1732 the conversion.
1733 NOTE:
1735 Unlike most other cmake_path() subcommands, the CONVERT subcommand
1736 takes a literal string as input, not the name of a variable.
1737 For example:
1739 set(paths "/a/b/c" "/x/y/z")
1741 cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
1742 message("Native path list is \"${native_paths}\"")
1743 Output on Windows:
1745 Native path list is "\a\b\c;\x\y\z"
1747 Output on all other platforms:
1749 Native path list is "/a/b/c:/x/y/z"
1751 Hashing
1753 cmake_path(HASH <path-var> <out-var>)
1754 Compute a hash value of <path-var> such that for two paths p1 and p2
1756 that compare equal (COMPARE ... EQUAL), the hash value of p1 is equal
1757 to the hash value of p2. The path is always normalized before the hash
1758 is computed.
1759 cmake_policy
1761 Manage CMake Policy settings. See the cmake-policies(7) manual for de‐
1762 fined policies.
1763 As CMake evolves it is sometimes necessary to change existing behavior
1765 in order to fix bugs or improve implementations of existing features.
1766 The CMake Policy mechanism is designed to help keep existing projects
1767 building as new versions of CMake introduce changes in behavior. Each
1768 new policy (behavioral change) is given an identifier of the form
1769 CMP<NNNN> where <NNNN> is an integer index. Documentation associated
1770 with each policy describes the OLD and NEW behavior and the reason the
1771 policy was introduced. Projects may set each policy to select the de‐
1772 sired behavior. When CMake needs to know which behavior to use it
1773 checks for a setting specified by the project. If no setting is avail‐
1774 able the OLD behavior is assumed and a warning is produced requesting
1775 that the policy be set.
1776 Setting Policies by CMake Version
1778 The cmake_policy command is used to set policies to OLD or NEW behav‐
1779 ior. While setting policies individually is supported, we encourage
1780 projects to set policies based on CMake versions:
1781 cmake_policy(VERSION <min>[...<max>])
1783 New in version 3.12: The optional <max> version.
1785 <min> and the optional <max> are each CMake versions of the form ma‐
1788 jor.minor[.patch[.tweak]], and the ... is literal. The <min> version
1789 must be at least 2.4 and at most the running version of CMake. The
1790 <max> version, if specified, must be at least the <min> version but may
1791 exceed the running version of CMake. If the running version of CMake
1792 is older than 3.12, the extra ... dots will be seen as version compo‐
1793 nent separators, resulting in the ...<max> part being ignored and pre‐
1794 serving the pre-3.12 behavior of basing policies on <min>.
1795 This specifies that the current CMake code is written for the given
1797 range of CMake versions. All policies known to the running version of
1798 CMake and introduced in the <min> (or <max>, if specified) version or
1799 earlier will be set to use NEW behavior. All policies introduced in
1800 later versions will be unset (unless the CMAKE_POLICY_DEFAULT_CMP<NNNN>
1801 variable sets a default). This effectively requests behavior preferred
1802 as of a given CMake version and tells newer CMake versions to warn
1803 about their new policies.
1804 Note that the cmake_minimum_required(VERSION) command implicitly calls
1806 cmake_policy(VERSION) too.
1807 Changed in version 3.27: Compatibility with versions of CMake older
1809 than 3.5 is deprecated. Calls to cmake_minimum_required(VERSION) or
1810 cmake_policy(VERSION) that do not specify at least 3.5 as their policy
1811 version (optionally via ...<max>) will produce a deprecation warning in
1812 CMake 3.27 and above.
1813 Changed in version 3.19: Compatibility with versions of CMake older
1816 than 2.8.12 is deprecated. Calls to cmake_minimum_required(VERSION) or
1817 cmake_policy(VERSION) that do not specify at least 2.8.12 as their pol‐
1818 icy version (optionally via ...<max>) will produce a deprecation warn‐
1819 ing in CMake 3.19 and above.
1820 Setting Policies Explicitly
1823 cmake_policy(SET CMP<NNNN> NEW)
1824 cmake_policy(SET CMP<NNNN> OLD)
1825 Tell CMake to use the OLD or NEW behavior for a given policy. Projects
1827 depending on the old behavior of a given policy may silence a policy
1828 warning by setting the policy state to OLD. Alternatively one may fix
1829 the project to work with the new behavior and set the policy state to
1830 NEW.
1831 NOTE:
1833 The OLD behavior of a policy is deprecated by definition and may be
1834 removed in a future version of CMake.
1835 Checking Policy Settings
1837 cmake_policy(GET CMP<NNNN> <variable>)
1838 Check whether a given policy is set to OLD or NEW behavior. The output
1840 <variable> value will be OLD or NEW if the policy is set, and empty
1841 otherwise.
1842 CMake Policy Stack
1844 CMake keeps policy settings on a stack, so changes made by the
1845 cmake_policy command affect only the top of the stack. A new entry on
1846 the policy stack is managed automatically for each subdirectory to pro‐
1847 tect its parents and siblings. CMake also manages a new entry for
1848 scripts loaded by include() and find_package() commands except when in‐
1849 voked with the NO_POLICY_SCOPE option (see also policy CMP0011). The
1850 cmake_policy command provides an interface to manage custom entries on
1851 the policy stack:
1852 cmake_policy(PUSH)
1854 cmake_policy(POP)
1855 Each PUSH must have a matching POP to erase any changes. This is use‐
1857 ful to make temporary changes to policy settings. Calls to the
1858 cmake_minimum_required(VERSION), cmake_policy(VERSION), or cmake_pol‐
1859 icy(SET) commands influence only the current top of the policy stack.
1860 New in version 3.25: The block() and endblock() commands offer a more
1862 flexible and more secure way to manage the policy stack. The pop action
1863 is done automatically when the endblock() command is executed, so it
1864 avoid to call the cmake_policy(POP) command before each return() com‐
1865 mand.
1866 # stack management with cmake_policy()
1868 function(my_func)
1869 cmake_policy(PUSH)
1870 cmake_policy(SET ...)
1871 if (<cond1>)
1872 ...
1873 cmake_policy(POP)
1874 return()
1875 elseif(<cond2>)
1876 ...
1877 cmake_policy(POP)
1878 return()
1879 endif()
1880 ...
1881 cmake_policy(POP)
1882 endfunction()
1883 # stack management with block()/endblock()
1885 function(my_func)
1886 block(SCOPE_FOR POLICIES)
1887 cmake_policy(SET ...)
1888 if (<cond1>)
1889 ...
1890 return()
1891 elseif(<cond2>)
1892 ...
1893 return()
1894 endif()
1895 ...
1896 endblock()
1897 endfunction()
1898 Commands created by the function() and macro() commands record policy
1901 settings when they are created and use the pre-record policies when
1902 they are invoked. If the function or macro implementation sets poli‐
1903 cies, the changes automatically propagate up through callers until they
1904 reach the closest nested policy stack entry.
1905 See Also
1907 • cmake_minimum_required()
1908 configure_file
1910 Copy a file to another location and modify its contents.
1911 configure_file(<input> <output>
1913 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
1914 FILE_PERMISSIONS <permissions>...]
1915 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
1916 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
1917 Copies an <input> file to an <output> file and substitutes variable
1919 values referenced as @VAR@, ${VAR}, $CACHE{VAR} or $ENV{VAR} in the in‐
1920 put file content. Each variable reference will be replaced with the
1921 current value of the variable, or the empty string if the variable is
1922 not defined. Furthermore, input lines of the form
1923 #cmakedefine VAR ...
1925 will be replaced with either
1927 #define VAR ...
1929 or
1931 /* #undef VAR */
1933 depending on whether VAR is set in CMake to any value not considered a
1935 false constant by the if() command. The "..." content on the line af‐
1936 ter the variable name, if any, is processed as above.
1937 Unlike lines of the form #cmakedefine VAR ..., in lines of the form
1939 #cmakedefine01 VAR, VAR itself will expand to VAR 0 or VAR 1 rather
1940 than being assigned the value .... Therefore, input lines of the form
1941 #cmakedefine01 VAR
1943 will be replaced with either
1945 #define VAR 0
1947 or
1949 #define VAR 1
1951 Input lines of the form #cmakedefine01 VAR ... will expand as #cmakede‐
1953 fine01 VAR ... 0 or #cmakedefine01 VAR ... 1, which may lead to unde‐
1954 fined behavior.
1955 New in version 3.10: The result lines (with the exception of the #undef
1957 comments) can be indented using spaces and/or tabs between the # char‐
1958 acter and the cmakedefine or cmakedefine01 words. This whitespace in‐
1959 dentation will be preserved in the output lines:
1960 # cmakedefine VAR
1962 # cmakedefine01 VAR
1963 will be replaced, if VAR is defined, with
1965 # define VAR
1967 # define VAR 1
1968 If the input file is modified the build system will re-run CMake to
1971 re-configure the file and generate the build system again. The gener‐
1972 ated file is modified and its timestamp updated on subsequent cmake
1973 runs only if its content is changed.
1974 The arguments are:
1976 <input>
1978 Path to the input file. A relative path is treated with respect
1979 to the value of CMAKE_CURRENT_SOURCE_DIR. The input path must
1980 be a file, not a directory.
1981 <output>
1983 Path to the output file or directory. A relative path is
1984 treated with respect to the value of CMAKE_CURRENT_BINARY_DIR.
1985 If the path names an existing directory the output file is
1986 placed in that directory with the same file name as the input
1987 file. If the path contains non-existent directories, they are
1988 created.
1989 NO_SOURCE_PERMISSIONS
1991 New in version 3.19.
1992 Do not transfer the permissions of the input file to the output
1995 file. The copied file permissions default to the standard 644
1996 value (-rw-r--r--).
1997 USE_SOURCE_PERMISSIONS
1999 New in version 3.20.
2000 Transfer the permissions of the input file to the output file.
2003 This is already the default behavior if none of the three per‐
2004 missions-related keywords are given (NO_SOURCE_PERMISSIONS,
2005 USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The
2006 USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making
2007 the intended behavior clearer at the call site.
2008 FILE_PERMISSIONS <permissions>...
2010 New in version 3.20.
2011 Ignore the input file's permissions and use the specified <per‐
2014 missions> for the output file instead.
2015 COPYONLY
2017 Copy the file without replacing any variable references or other
2018 content. This option may not be used with NEWLINE_STYLE.
2019 ESCAPE_QUOTES
2021 Escape any substituted quotes with backslashes (C-style).
2022 @ONLY Restrict variable replacement to references of the form @VAR@.
2024 This is useful for configuring scripts that use ${VAR} syntax.
2025 NEWLINE_STYLE <style>
2027 Specify the newline style for the output file. Specify UNIX or
2028 LF for \n newlines, or specify DOS, WIN32, or CRLF for \r\n new‐
2029 lines. This option may not be used with COPYONLY.
2030 Example
2032 Consider a source tree containing a foo.h.in file:
2033 #cmakedefine FOO_ENABLE
2035 #cmakedefine FOO_STRING "@FOO_STRING@"
2036 An adjacent CMakeLists.txt may use configure_file to configure the
2038 header:
2039 option(FOO_ENABLE "Enable Foo" ON)
2041 if(FOO_ENABLE)
2042 set(FOO_STRING "foo")
2043 endif()
2044 configure_file(foo.h.in foo.h @ONLY)
2045 This creates a foo.h in the build directory corresponding to this
2047 source directory. If the FOO_ENABLE option is on, the configured file
2048 will contain:
2049 #define FOO_ENABLE
2051 #define FOO_STRING "foo"
2052 Otherwise it will contain:
2054 /* #undef FOO_ENABLE */
2056 /* #undef FOO_STRING */
2057 One may then use the target_include_directories() command to specify
2059 the output directory as an include directory:
2060 target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")
2062 so that sources may include the header as #include <foo.h>.
2064 See Also
2066 • file(GENERATE)
2067 continue
2069 New in version 3.2.
2070 Continue to the top of enclosing foreach or while loop.
2073 continue()
2075 The continue() command allows a cmake script to abort the rest of the
2077 current iteration of a foreach() or while() loop, and start at the top
2078 of the next iteration.
2079 See also the break() command.
2081 else
2083 Starts the else portion of an if block.
2084 else([<condition>])
2086 See the if() command.
2088 elseif
2090 Starts an elseif portion of an if block.
2091 elseif(<condition>)
2093 See the if() command, especially for the syntax and logic of the <con‐
2095 dition>.
2096 endblock
2098 New in version 3.25.
2099 Ends a list of commands in a block() and removes the scopes created by
2102 the block() command.
2103 endblock()
2105 endforeach
2107 Ends a list of commands in a foreach block.
2108 endforeach([<loop_var>])
2110 See the foreach() command.
2112 The optional <loop_var> argument is supported for backward compatibil‐
2114 ity only. If used it must be a verbatim repeat of the <loop_var> argu‐
2115 ment of the opening foreach clause.
2116 endfunction
2118 Ends a list of commands in a function block.
2119 endfunction([<name>])
2121 See the function() command.
2123 The optional <name> argument is supported for backward compatibility
2125 only. If used it must be a verbatim repeat of the <name> argument of
2126 the opening function command.
2127 endif
2129 Ends a list of commands in an if block.
2130 endif([<condition>])
2132 See the if() command.
2134 The optional <condition> argument is supported for backward compatibil‐
2136 ity only. If used it must be a verbatim repeat of the argument of the
2137 opening if clause.
2138 endmacro
2140 Ends a list of commands in a macro block.
2141 endmacro([<name>])
2143 See the macro() command.
2145 The optional <name> argument is supported for backward compatibility
2147 only. If used it must be a verbatim repeat of the <name> argument of
2148 the opening macro command.
2149 endwhile
2151 Ends a list of commands in a while block.
2152 endwhile([<condition>])
2154 See the while() command.
2156 The optional <condition> argument is supported for backward compatibil‐
2158 ity only. If used it must be a verbatim repeat of the argument of the
2159 opening while clause.
2160 execute_process
2162 Execute one or more child processes.
2163 execute_process(COMMAND <cmd1> [<arguments>]
2165 [COMMAND <cmd2> [<arguments>]]...
2166 [WORKING_DIRECTORY <directory>]
2167 [TIMEOUT <seconds>]
2168 [RESULT_VARIABLE <variable>]
2169 [RESULTS_VARIABLE <variable>]
2170 [OUTPUT_VARIABLE <variable>]
2171 [ERROR_VARIABLE <variable>]
2172 [INPUT_FILE <file>]
2173 [OUTPUT_FILE <file>]
2174 [ERROR_FILE <file>]
2175 [OUTPUT_QUIET]
2176 [ERROR_QUIET]
2177 [COMMAND_ECHO <where>]
2178 [OUTPUT_STRIP_TRAILING_WHITESPACE]
2179 [ERROR_STRIP_TRAILING_WHITESPACE]
2180 [ENCODING <name>]
2181 [ECHO_OUTPUT_VARIABLE]
2182 [ECHO_ERROR_VARIABLE]
2183 [COMMAND_ERROR_IS_FATAL <ANY|LAST>])
2184 Runs the given sequence of one or more commands.
2186 Commands are executed concurrently as a pipeline, with the standard
2188 output of each process piped to the standard input of the next. A sin‐
2189 gle standard error pipe is used for all processes.
2190 execute_process runs commands while CMake is configuring the project,
2192 prior to build system generation. Use the add_custom_target() and
2193 add_custom_command() commands to create custom commands that run at
2194 build time.
2195 Options:
2197 COMMAND
2199 A child process command line.
2200 CMake executes the child process using operating system APIs di‐
2202 rectly:
2203 • On POSIX platforms, the command line is passed to the child
2205 process in an argv[] style array.
2206 • On Windows platforms, the command line is encoded as a string
2208 such that child processes using CommandLineToArgvW will decode
2209 the original arguments.
2210 No intermediate shell is used, so shell operators such as > are
2212 treated as normal arguments. (Use the INPUT_*, OUTPUT_*, and
2213 ERROR_* options to redirect stdin, stdout, and stderr.)
2214 For sequential execution of multiple commands use multiple exe‐
2216 cute_process calls each with a single COMMAND argument.
2217 WORKING_DIRECTORY
2219 The named directory will be set as the current working directory
2220 of the child processes.
2221 TIMEOUT
2223 After the specified number of seconds (fractions allowed), all
2224 unfinished child processes will be terminated, and the RE‐
2225 SULT_VARIABLE will be set to a string mentioning the "timeout".
2226 RESULT_VARIABLE
2228 The variable will be set to contain the result of last child
2229 process. This will be an integer return code from the last
2230 child or a string describing an error condition.
2231 RESULTS_VARIABLE <variable>
2233 New in version 3.10.
2234 The variable will be set to contain the result of all processes
2237 as a semicolon-separated list, in order of the given COMMAND ar‐
2238 guments. Each entry will be an integer return code from the
2239 corresponding child or a string describing an error condition.
2240 INPUT_FILE <file>
2242 <file> is attached to the standard input pipe of the first COM‐
2243 MAND process.
2244 OUTPUT_FILE <file>
2246 <file> is attached to the standard output pipe of the last COM‐
2247 MAND process.
2248 ERROR_FILE <file>
2250 <file> is attached to the standard error pipe of all COMMAND
2251 processes.
2252 New in version 3.3: If the same <file> is named for both OUTPUT_FILE
2254 and ERROR_FILE then it will be used for both standard output and stan‐
2255 dard error pipes.
2256 OUTPUT_QUIET, ERROR_QUIET
2259 The standard output on OUTPUT_VARIABLE or standard error on ER‐
2260 ROR_VARIABLE are not connected (no variable content). The
2261 *_FILE and ECHO_*_VARIABLE options are not affected.
2262 OUTPUT_VARIABLE, ERROR_VARIABLE
2264 The variable named will be set with the contents of the standard
2265 output and standard error pipes, respectively. If the same
2266 variable is named for both pipes their output will be merged in
2267 the order produced.
2268 ECHO_OUTPUT_VARIABLE, ECHO_ERROR_VARIABLE
2270 New in version 3.18.
2271 The standard output or standard error will not be exclusively
2274 redirected to the specified variables.
2275 The output will be duplicated into the specified variables and
2277 also onto standard output or standard error analogous to the tee
2278 Unix command.
2279 NOTE:
2281 If more than one OUTPUT_* or ERROR_* option is given for the same
2282 pipe the precedence is not specified. If no OUTPUT_* or ERROR_* op‐
2283 tions are given the output will be shared with the corresponding
2284 pipes of the CMake process itself.
2285 COMMAND_ECHO <where>
2287 New in version 3.15.
2288 The command being run will be echo'ed to <where> with <where>
2291 being set to one of STDERR, STDOUT or NONE. See the
2292 CMAKE_EXECUTE_PROCESS_COMMAND_ECHO variable for a way to control
2293 the default behavior when this option is not present.
2294 ENCODING <name>
2296 New in version 3.8.
2297 On Windows, the encoding that is used to decode output from the
2300 process. Ignored on other platforms. Valid encoding names are:
2301 NONE Perform no decoding. This assumes that the process out‐
2303 put is encoded in the same way as CMake's internal encod‐
2304 ing (UTF-8). This is the default.
2305 AUTO Use the current active console's codepage or if that
2307 isn't available then use ANSI.
2308 ANSI Use the ANSI codepage.
2310 OEM Use the original equipment manufacturer (OEM) code page.
2312 UTF8 or UTF-8
2314 Use the UTF-8 codepage.
2315 New in version 3.11: Accept UTF-8 spelling for consis‐
2317 tency with the UTF-8 RFC naming convention.
2318 COMMAND_ERROR_IS_FATAL <ANY|LAST>
2321 New in version 3.19.
2322 The option following COMMAND_ERROR_IS_FATAL determines the be‐
2325 havior when an error is encountered:
2326 ANY If any of the commands in the list of commands fail, the
2327 execute_process() command halts with an error.
2328 LAST If the last command in the list of commands fails, the
2330 execute_process() command halts with an error. Commands ear‐
2331 lier in the list will not cause a fatal error.
2332 file
2334 File manipulation command.
2335 This command is dedicated to file and path manipulation requiring ac‐
2337 cess to the filesystem.
2338 For other path manipulation, handling only syntactic aspects, have a
2340 look at cmake_path() command.
2341 NOTE:
2343 The sub-commands RELATIVE_PATH, TO_CMAKE_PATH and TO_NATIVE_PATH has
2344 been superseded, respectively, by sub-commands RELATIVE_PATH,
2345 CONVERT ... TO_CMAKE_PATH_LIST and CONVERT ... TO_NATIVE_PATH_LIST
2346 of cmake_path() command.
2347 Synopsis
2349 Reading
2350 file(READ <filename> <out-var> [...])
2351 file(STRINGS <filename> <out-var> [...])
2352 file(<HASH> <filename> <out-var>)
2353 file(TIMESTAMP <filename> <out-var> [...])
2354 file(GET_RUNTIME_DEPENDENCIES [...])
2355 Writing
2357 file({WRITE | APPEND} <filename> <content>...)
2358 file({TOUCH | TOUCH_NOCREATE} [<file>...])
2359 file(GENERATE OUTPUT <output-file> [...])
2360 file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])
2361 Filesystem
2363 file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
2364 file(MAKE_DIRECTORY [<dir>...])
2365 file({REMOVE | REMOVE_RECURSE } [<files>...])
2366 file(RENAME <oldname> <newname> [...])
2367 file(COPY_FILE <oldname> <newname> [...])
2368 file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
2369 file(SIZE <filename> <out-var>)
2370 file(READ_SYMLINK <linkname> <out-var>)
2371 file(CREATE_LINK <original> <linkname> [...])
2372 file(CHMOD <files>... <directories>... PERMISSIONS <permissions>... [...])
2373 file(CHMOD_RECURSE <files>... <directories>... PERMISSIONS <permissions>... [...])
2374 Path Conversion
2376 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
2377 file(RELATIVE_PATH <out-var> <directory> <file>)
2378 file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)
2379 Transfer
2381 file(DOWNLOAD <url> [<file>] [...])
2382 file(UPLOAD <file> <url> [...])
2383 Locking
2385 file(LOCK <path> [...])
2386 Archiving
2388 file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
2389 file(ARCHIVE_EXTRACT INPUT <archive> [...])
2390 Reading
2392 file(READ <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>]
2393 [HEX])
2394 Read content from a file called <filename> and store it in a
2395 <variable>. Optionally start from the given <offset> and read
2396 at most <max-in> bytes. The HEX option causes data to be con‐
2397 verted to a hexadecimal representation (useful for binary data).
2398 If the HEX option is specified, letters in the output (a through
2399 f) are in lowercase.
2400 file(STRINGS <filename> <variable> [<options>...])
2402 Parse a list of ASCII strings from <filename> and store it in
2403 <variable>. Binary data in the file are ignored. Carriage re‐
2404 turn (\r, CR) characters are ignored. The options are:
2405 LENGTH_MAXIMUM <max-len>
2407 Consider only strings of at most a given length.
2408 LENGTH_MINIMUM <min-len>
2410 Consider only strings of at least a given length.
2411 LIMIT_COUNT <max-num>
2413 Limit the number of distinct strings to be extracted.
2414 LIMIT_INPUT <max-in>
2416 Limit the number of input bytes to read from the file.
2417 LIMIT_OUTPUT <max-out>
2419 Limit the number of total bytes to store in the <vari‐
2420 able>.
2421 NEWLINE_CONSUME
2423 Treat newline characters (\n, LF) as part of string
2424 content instead of terminating at them.
2425 NO_HEX_CONVERSION
2427 Intel Hex and Motorola S-record files are automati‐
2428 cally converted to binary while reading unless this
2429 option is given.
2430 REGEX <regex>
2432 Consider only strings that match the given regular ex‐
2433 pression, as described under string(REGEX).
2434 ENCODING <encoding-type>
2436 New in version 3.1.
2437 Consider strings of a given encoding. Currently sup‐
2440 ported encodings are: UTF-8, UTF-16LE, UTF-16BE,
2441 UTF-32LE, UTF-32BE. If the ENCODING option is not
2442 provided and the file has a Byte Order Mark, the EN‐
2443 CODING option will be defaulted to respect the Byte
2444 Order Mark.
2445 New in version 3.2: Added the UTF-16LE, UTF-16BE, UTF-32LE,
2447 UTF-32BE encodings.
2448 For example, the code
2451 file(STRINGS myfile.txt myfile)
2453 stores a list in the variable myfile in which each item is a
2455 line from the input file.
2456 file(<HASH> <filename> <variable>)
2458 Compute a cryptographic hash of the content of <filename> and
2459 store it in a <variable>. The supported <HASH> algorithm names
2460 are those listed by the string(<HASH>) command.
2461 file(TIMESTAMP <filename> <variable> [<format>] [UTC])
2463 Compute a string representation of the modification time of
2464 <filename> and store it in <variable>. Should the command be
2465 unable to obtain a timestamp variable will be set to the empty
2466 string ("").
2467 See the string(TIMESTAMP) command for documentation of the <for‐
2469 mat> and UTC options.
2470 file(GET_RUNTIME_DEPENDENCIES [...])
2472 New in version 3.16.
2473 Recursively get the list of libraries depended on by the given
2476 files:
2477 file(GET_RUNTIME_DEPENDENCIES
2479 [RESOLVED_DEPENDENCIES_VAR <deps_var>]
2480 [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
2481 [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
2482 [EXECUTABLES [<executable_files>...]]
2483 [LIBRARIES [<library_files>...]]
2484 [MODULES [<module_files>...]]
2485 [DIRECTORIES [<directories>...]]
2486 [BUNDLE_EXECUTABLE <bundle_executable_file>]
2487 [PRE_INCLUDE_REGEXES [<regexes>...]]
2488 [PRE_EXCLUDE_REGEXES [<regexes>...]]
2489 [POST_INCLUDE_REGEXES [<regexes>...]]
2490 [POST_EXCLUDE_REGEXES [<regexes>...]]
2491 [POST_INCLUDE_FILES [<files>...]]
2492 [POST_EXCLUDE_FILES [<files>...]]
2493 )
2494 Please note that this sub-command is not intended to be used in
2496 project mode. It is intended for use at install time, either
2497 from code generated by the install(RUNTIME_DEPENDENCY_SET) com‐
2498 mand, or from code provided by the project via install(CODE) or
2499 install(SCRIPT). For example:
2500 install(CODE [[
2502 file(GET_RUNTIME_DEPENDENCIES
2503 # ...
2504 )
2505 ]])
2506 The arguments are as follows:
2508 RESOLVED_DEPENDENCIES_VAR <deps_var>
2510 Name of the variable in which to store the list of re‐
2511 solved dependencies.
2512 UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>
2514 Name of the variable in which to store the list of un‐
2515 resolved dependencies. If this variable is not speci‐
2516 fied, and there are any unresolved dependencies, an
2517 error is issued.
2518 CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>
2520 Variable prefix in which to store conflicting depen‐
2521 dency information. Dependencies are conflicting if
2522 two files with the same name are found in two differ‐
2523 ent directories. The list of filenames that conflict
2524 are stored in <conflicting_deps_prefix>_FILENAMES. For
2525 each filename, the list of paths that were found for
2526 that filename are stored in <conflicting_deps_pre‐
2527 fix>_<filename>.
2528 EXECUTABLES <executable_files>
2530 List of executable files to read for dependencies.
2531 These are executables that are typically created with
2532 add_executable(), but they do not have to be created
2533 by CMake. On Apple platforms, the paths to these files
2534 determine the value of @executable_path when recur‐
2535 sively resolving the libraries. Specifying any kind of
2536 library (STATIC, MODULE, or SHARED) here will result
2537 in undefined behavior.
2538 LIBRARIES <library_files>
2540 List of library files to read for dependencies. These
2541 are libraries that are typically created with
2542 add_library(SHARED), but they do not have to be cre‐
2543 ated by CMake. Specifying STATIC libraries, MODULE li‐
2544 braries, or executables here will result in undefined
2545 behavior.
2546 MODULES <module_files>
2548 List of loadable module files to read for dependen‐
2549 cies. These are modules that are typically created
2550 with add_library(MODULE), but they do not have to be
2551 created by CMake. They are typically used by calling
2552 dlopen() at runtime rather than linked at link time
2553 with ld -l. Specifying STATIC libraries, SHARED li‐
2554 braries, or executables here will result in undefined
2555 behavior.
2556 DIRECTORIES <directories>
2558 List of additional directories to search for dependen‐
2559 cies. On Linux platforms, these directories are
2560 searched if the dependency is not found in any of the
2561 other usual paths. If it is found in such a directory,
2562 a warning is issued, because it means that the file is
2563 incomplete (it does not list all of the directories
2564 that contain its dependencies). On Windows platforms,
2565 these directories are searched if the dependency is
2566 not found in any of the other search paths, but no
2567 warning is issued, because searching other paths is a
2568 normal part of Windows dependency resolution. On Apple
2569 platforms, this argument has no effect.
2570 BUNDLE_EXECUTABLE <bundle_executable_file>
2572 Executable to treat as the "bundle executable" when
2573 resolving libraries. On Apple platforms, this argu‐
2574 ment determines the value of @executable_path when re‐
2575 cursively resolving libraries for LIBRARIES and MOD‐
2576 ULES files. It has no effect on EXECUTABLES files. On
2577 other platforms, it has no effect. This is typically
2578 (but not always) one of the executables in the EXE‐
2579 CUTABLES argument which designates the "main" exe‐
2580 cutable of the package.
2581 The following arguments specify filters for including or exclud‐
2583 ing libraries to be resolved. See below for a full description
2584 of how they work.
2585 PRE_INCLUDE_REGEXES <regexes>
2587 List of pre-include regexes through which to filter
2588 the names of not-yet-resolved dependencies.
2589 PRE_EXCLUDE_REGEXES <regexes>
2591 List of pre-exclude regexes through which to filter
2592 the names of not-yet-resolved dependencies.
2593 POST_INCLUDE_REGEXES <regexes>
2595 List of post-include regexes through which to filter
2596 the names of resolved dependencies.
2597 POST_EXCLUDE_REGEXES <regexes>
2599 List of post-exclude regexes through which to filter
2600 the names of resolved dependencies.
2601 POST_INCLUDE_FILES <files>
2603 New in version 3.21.
2604 List of post-include filenames through which to filter
2607 the names of resolved dependencies. Symlinks are re‐
2608 solved when attempting to match these filenames.
2609 POST_EXCLUDE_FILES <files>
2611 New in version 3.21.
2612 List of post-exclude filenames through which to filter
2615 the names of resolved dependencies. Symlinks are re‐
2616 solved when attempting to match these filenames.
2617 These arguments can be used to exclude unwanted system libraries
2619 when resolving the dependencies, or to include libraries from a
2620 specific directory. The filtering works as follows:
2621 1. If the not-yet-resolved dependency matches any of the PRE_IN‐
2623 CLUDE_REGEXES, steps 2 and 3 are skipped, and the dependency
2624 resolution proceeds to step 4.
2625 2. If the not-yet-resolved dependency matches any of the PRE_EX‐
2627 CLUDE_REGEXES, dependency resolution stops for that depen‐
2628 dency.
2629 3. Otherwise, dependency resolution proceeds.
2631 4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency
2633 according to the linking rules of the platform (see below).
2634 5. If the dependency is found, and its full path matches one of
2636 the POST_INCLUDE_REGEXES or POST_INCLUDE_FILES, the full path
2637 is added to the resolved dependencies, and file(GET_RUN‐
2638 TIME_DEPENDENCIES) recursively resolves that library's own
2639 dependencies. Otherwise, resolution proceeds to step 6.
2640 6. If the dependency is found, but its full path matches one of
2642 the POST_EXCLUDE_REGEXES or POST_EXCLUDE_FILES, it is not
2643 added to the resolved dependencies, and dependency resolution
2644 stops for that dependency.
2645 7. If the dependency is found, and its full path does not match
2647 either POST_INCLUDE_REGEXES, POST_INCLUDE_FILES, POST_EX‐
2648 CLUDE_REGEXES, or POST_EXCLUDE_FILES, the full path is added
2649 to the resolved dependencies, and file(GET_RUNTIME_DEPENDEN‐
2650 CIES) recursively resolves that library's own dependencies.
2651 Different platforms have different rules for how dependencies
2653 are resolved. These specifics are described here.
2654 On Linux platforms, library resolution works as follows:
2656 1. If the depending file does not have any RUNPATH entries, and
2658 the library exists in one of the depending file's RPATH en‐
2659 tries, or its parents', in that order, the dependency is re‐
2660 solved to that file.
2661 2. Otherwise, if the depending file has any RUNPATH entries, and
2663 the library exists in one of those entries, the dependency is
2664 resolved to that file.
2665 3. Otherwise, if the library exists in one of the directories
2667 listed by ldconfig, the dependency is resolved to that file.
2668 4. Otherwise, if the library exists in one of the DIRECTORIES
2670 entries, the dependency is resolved to that file. In this
2671 case, a warning is issued, because finding a file in one of
2672 the DIRECTORIES means that the depending file is not complete
2673 (it does not list all the directories from which it pulls de‐
2674 pendencies).
2675 5. Otherwise, the dependency is unresolved.
2677 On Windows platforms, library resolution works as follows:
2679 1. DLL dependency names are converted to lowercase for matching
2681 filters. Windows DLL names are case-insensitive, and some
2682 linkers mangle the case of the DLL dependency names. How‐
2683 ever, this makes it more difficult for PRE_INCLUDE_REGEXES,
2684 PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and POST_EX‐
2685 CLUDE_REGEXES to properly filter DLL names - every regex
2686 would have to check for both uppercase and lowercase letters.
2687 For example:
2688 file(GET_RUNTIME_DEPENDENCIES
2690 # ...
2691 PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
2692 )
2693 Converting the DLL name to lowercase allows the regexes to
2695 only match lowercase names, thus simplifying the regex. For
2696 example:
2697 file(GET_RUNTIME_DEPENDENCIES
2699 # ...
2700 PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
2701 )
2702 This regex will match mylibrary.dll regardless of how it is
2704 cased, either on disk or in the depending file. (For example,
2705 it will match mylibrary.dll, MyLibrary.dll, and MYLI‐
2706 BRARY.DLL.)
2707 Changed in version 3.27: The conversion to lowercase only ap‐
2709 plies while matching filters. Results reported after filter‐
2710 ing case-preserve each DLL name as it is found on disk, if
2711 resolved, and otherwise as it is referenced by the dependent
2712 binary.
2713 Prior to CMake 3.27, the results were reported with lowercase
2715 DLL file names, but the directory portion retained its cas‐
2716 ing.
2717 2. (Not yet implemented) If the depending file is a Windows
2720 Store app, and the dependency is listed as a dependency in
2721 the application's package manifest, the dependency is re‐
2722 solved to that file.
2723 3. Otherwise, if the library exists in the same directory as the
2725 depending file, the dependency is resolved to that file.
2726 4. Otherwise, if the library exists in either the operating sys‐
2728 tem's system32 directory or the Windows directory, in that
2729 order, the dependency is resolved to that file.
2730 5. Otherwise, if the library exists in one of the directories
2732 specified by DIRECTORIES, in the order they are listed, the
2733 dependency is resolved to that file. In this case, a warning
2734 is not issued, because searching other directories is a nor‐
2735 mal part of Windows library resolution.
2736 6. Otherwise, the dependency is unresolved.
2738 On Apple platforms, library resolution works as follows:
2740 1. If the dependency starts with @executable_path/, and an EXE‐
2742 CUTABLES argument is in the process of being resolved, and
2743 replacing @executable_path/ with the directory of the exe‐
2744 cutable yields an existing file, the dependency is resolved
2745 to that file.
2746 2. Otherwise, if the dependency starts with @executable_path/,
2748 and there is a BUNDLE_EXECUTABLE argument, and replacing @ex‐
2749 ecutable_path/ with the directory of the bundle executable
2750 yields an existing file, the dependency is resolved to that
2751 file.
2752 3. Otherwise, if the dependency starts with @loader_path/, and
2754 replacing @loader_path/ with the directory of the depending
2755 file yields an existing file, the dependency is resolved to
2756 that file.
2757 4. Otherwise, if the dependency starts with @rpath/, and replac‐
2759 ing @rpath/ with one of the RPATH entries of the depending
2760 file yields an existing file, the dependency is resolved to
2761 that file. Note that RPATH entries that start with @exe‐
2762 cutable_path/ or @loader_path/ also have these items replaced
2763 with the appropriate path.
2764 5. Otherwise, if the dependency is an absolute file that exists,
2766 the dependency is resolved to that file.
2767 6. Otherwise, the dependency is unresolved.
2769 This function accepts several variables that determine which
2771 tool is used for dependency resolution:
2772 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM
2774 Determines which operating system and executable format
2775 the files are built for. This could be one of several
2776 values:
2777 • linux+elf
2779 • windows+pe
2781 • macos+macho
2783 If this variable is not specified, it is determined auto‐
2785 matically by system introspection.
2786 CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
2788 Determines the tool to use for dependency resolution. It
2789 could be one of several values, depending on the value of
2790 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:
2791 ┌─────────────────────────┬──────────────────────────┐
2793 │CMAKE_GET_RUNTIME_DEPEN‐ │ CMAKE_GET_RUNTIME_DEPEN‐ │
2794 │DENCIES_PLATFORM │ DENCIES_TOOL │
2795 ├─────────────────────────┼──────────────────────────┤
2796 │linux+elf │ objdump │
2797 ├─────────────────────────┼──────────────────────────┤
2798 │windows+pe │ objdump or dumpbin │
2799 ├─────────────────────────┼──────────────────────────┤
2800 │macos+macho │ otool │
2801 └─────────────────────────┴──────────────────────────┘
2802 If this variable is not specified, it is determined auto‐
2804 matically by system introspection.
2805 CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND
2807 Determines the path to the tool to use for dependency
2808 resolution. This is the actual path to objdump, dumpbin,
2809 or otool.
2810 If this variable is not specified, it is determined by
2812 the value of CMAKE_OBJDUMP if set, else by system intro‐
2813 spection.
2814 New in version 3.18: Use CMAKE_OBJDUMP if set.
2816 Writing
2819 file(WRITE <filename> <content>...)
2820 file(APPEND <filename> <content>...)
2822 Write <content> into a file called <filename>. If the file does
2823 not exist, it will be created. If the file already exists,
2824 WRITE mode will overwrite it and APPEND mode will append to the
2825 end. Any directories in the path specified by <filename> that
2826 do not exist will be created.
2827 If the file is a build input, use the configure_file() command
2829 to update the file only when its content changes.
2830 file(TOUCH [<files>...])
2832 file(TOUCH_NOCREATE [<files>...])
2834 New in version 3.12.
2835 Create a file with no content if it does not yet exist. If the
2838 file already exists, its access and/or modification will be up‐
2839 dated to the time when the function call is executed.
2840 Use TOUCH_NOCREATE to touch a file if it exists but not create
2842 it. If a file does not exist it will be silently ignored.
2843 With TOUCH and TOUCH_NOCREATE, the contents of an existing file
2845 will not be modified.
2846 file(GENERATE [...])
2848 Generate an output file for each build configuration supported
2849 by the current CMake Generator. Evaluate generator expressions
2850 from the input content to produce the output content.
2851 file(GENERATE OUTPUT <output-file>
2853 <INPUT <input-file>|CONTENT <content>>
2854 [CONDITION <expression>] [TARGET <target>]
2855 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
2856 FILE_PERMISSIONS <permissions>...]
2857 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2858 The options are:
2860 CONDITION <condition>
2862 Generate the output file for a particular configura‐
2863 tion only if the condition is true. The condition
2864 must be either 0 or 1 after evaluating generator ex‐
2865 pressions.
2866 CONTENT <content>
2868 Use the content given explicitly as input.
2869 INPUT <input-file>
2871 Use the content from a given file as input.
2872 Changed in version 3.10: A relative path is treated
2874 with respect to the value of CMAKE_CURRENT_SOURCE_DIR.
2875 See policy CMP0070.
2876 OUTPUT <output-file>
2879 Specify the output file name to generate. Use genera‐
2880 tor expressions such as $<CONFIG> to specify a config‐
2881 uration-specific output file name. Multiple configu‐
2882 rations may generate the same output file only if the
2883 generated content is identical. Otherwise, the <out‐
2884 put-file> must evaluate to an unique name for each
2885 configuration.
2886 Changed in version 3.10: A relative path (after evalu‐
2888 ating generator expressions) is treated with respect
2889 to the value of CMAKE_CURRENT_BINARY_DIR. See policy
2890 CMP0070.
2891 TARGET <target>
2894 New in version 3.19.
2895 Specify which target to use when evaluating generator
2898 expressions that require a target for evaluation (e.g.
2899 $<COMPILE_FEATURES:...>, $<TARGET_PROPERTY:prop>).
2900 NO_SOURCE_PERMISSIONS
2902 New in version 3.20.
2903 The generated file permissions default to the standard
2906 644 value (-rw-r--r--).
2907 USE_SOURCE_PERMISSIONS
2909 New in version 3.20.
2910 Transfer the file permissions of the INPUT file to the
2913 generated file. This is already the default behavior
2914 if none of the three permissions-related keywords are
2915 given (NO_SOURCE_PERMISSIONS, USE_SOURCE_PERMISSIONS
2916 or FILE_PERMISSIONS). The USE_SOURCE_PERMISSIONS key‐
2917 word mostly serves as a way of making the intended be‐
2918 havior clearer at the call site. It is an error to
2919 specify this option without INPUT.
2920 FILE_PERMISSIONS <permissions>...
2922 New in version 3.20.
2923 Use the specified permissions for the generated file.
2926 NEWLINE_STYLE <style>
2928 New in version 3.20.
2929 Specify the newline style for the generated file.
2932 Specify UNIX or LF for \n newlines, or specify DOS,
2933 WIN32, or CRLF for \r\n newlines.
2934 Exactly one CONTENT or INPUT option must be given. A specific
2936 OUTPUT file may be named by at most one invocation of file(GEN‐
2937 ERATE). Generated files are modified and their timestamp up‐
2938 dated on subsequent cmake runs only if their content is changed.
2939 Note also that file(GENERATE) does not create the output file
2941 until the generation phase. The output file will not yet have
2942 been written when the file(GENERATE) command returns, it is
2943 written only after processing all of a project's CMakeLists.txt
2944 files.
2945 file(CONFIGURE OUTPUT <output-file> CONTENT <content> [ESCAPE_QUOTES]
2947 [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
2948 New in version 3.18.
2949 Generate an output file using the input given by CONTENT and
2952 substitute variable values referenced as @VAR@ or ${VAR} con‐
2953 tained therein. The substitution rules behave the same as the
2954 configure_file() command. In order to match configure_file()'s
2955 behavior, generator expressions are not supported for both OUT‐
2956 PUT and CONTENT.
2957 The arguments are:
2959 OUTPUT <output-file>
2961 Specify the output file name to generate. A relative
2962 path is treated with respect to the value of
2963 CMAKE_CURRENT_BINARY_DIR. <output-file> does not sup‐
2964 port generator expressions.
2965 CONTENT <content>
2967 Use the content given explicitly as input. <content>
2968 does not support generator expressions.
2969 ESCAPE_QUOTES
2971 Escape any substituted quotes with backslashes
2972 (C-style).
2973 @ONLY Restrict variable replacement to references of the
2975 form @VAR@. This is useful for configuring scripts
2976 that use ${VAR} syntax.
2977 NEWLINE_STYLE <style>
2979 Specify the newline style for the output file. Spec‐
2980 ify UNIX or LF for \n newlines, or specify DOS, WIN32,
2981 or CRLF for \r\n newlines.
2982 Filesystem
2984 file(GLOB <variable> [LIST_DIRECTORIES true|false] [RELATIVE <path>]
2985 [CONFIGURE_DEPENDS] [<globbing-expressions>...])
2986 file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS] [LIST_DIRECTO‐
2988 RIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS] [<globbing-ex‐
2989 pressions>...])
2990 Generate a list of files that match the <globbing-expressions>
2991 and store it into the <variable>. Globbing expressions are sim‐
2992 ilar to regular expressions, but much simpler. If RELATIVE flag
2993 is specified, the results will be returned as relative paths to
2994 the given path.
2995 Changed in version 3.6: The results will be ordered lexicograph‐
2997 ically.
2998 On Windows and macOS, globbing is case-insensitive even if the
3001 underlying filesystem is case-sensitive (both filenames and
3002 globbing expressions are converted to lowercase before match‐
3003 ing). On other platforms, globbing is case-sensitive.
3004 New in version 3.3: By default GLOB lists directories. Directo‐
3006 ries are omitted in the result if LIST_DIRECTORIES is set to
3007 false.
3008 New in version 3.12: If the CONFIGURE_DEPENDS flag is specified,
3011 CMake will add logic to the main build system check target to
3012 rerun the flagged GLOB commands at build time. If any of the
3013 outputs change, CMake will regenerate the build system.
3014 NOTE:
3017 We do not recommend using GLOB to collect a list of source
3018 files from your source tree. If no CMakeLists.txt file
3019 changes when a source is added or removed then the generated
3020 build system cannot know when to ask CMake to regenerate.
3021 The CONFIGURE_DEPENDS flag may not work reliably on all gen‐
3022 erators, or if a new generator is added in the future that
3023 cannot support it, projects using it will be stuck. Even if
3024 CONFIGURE_DEPENDS works reliably, there is still a cost to
3025 perform the check on every rebuild.
3026 Examples of globbing expressions include:
3028 ┌───────────┬────────────────────────────┐
3030 │*.cxx │ match all files with ex‐ │
3031 │ │ tension cxx │
3032 ├───────────┼────────────────────────────┤
3033 │*.vt? │ match all files with ex‐ │
3034 │ │ tension vta, ..., vtz │
3035 ├───────────┼────────────────────────────┤
3036 │f[3-5].txt │ match files f3.txt, │
3037 │ │ f4.txt, f5.txt │
3038 └───────────┴────────────────────────────┘
3039 The GLOB_RECURSE mode will traverse all the subdirectories of
3041 the matched directory and match the files. Subdirectories that
3042 are symlinks are only traversed if FOLLOW_SYMLINKS is given or
3043 policy CMP0009 is not set to NEW.
3044 New in version 3.3: By default GLOB_RECURSE omits directories
3046 from result list. Setting LIST_DIRECTORIES to true adds directo‐
3047 ries to result list. If FOLLOW_SYMLINKS is given or policy
3048 CMP0009 is not set to NEW then LIST_DIRECTORIES treats symlinks
3049 as directories.
3050 Examples of recursive globbing include:
3053 ┌──────────┬────────────────────────────┐
3055 │/dir/*.py │ match all python files in │
3056 │ │ /dir and subdirectories │
3057 └──────────┴────────────────────────────┘
3058 file(MAKE_DIRECTORY [<directories>...])
3060 Create the given directories and their parents as needed.
3061 file(REMOVE [<files>...])
3063 file(REMOVE_RECURSE [<files>...])
3065 Remove the given files. The REMOVE_RECURSE mode will remove the
3066 given files and directories, including non-empty directories. No
3067 error is emitted if a given file does not exist. Relative input
3068 paths are evaluated with respect to the current source direc‐
3069 tory.
3070 Changed in version 3.15: Empty input paths are ignored with a
3072 warning. Previous versions of CMake interpreted empty strings
3073 as a relative path with respect to the current directory and re‐
3074 moved its contents.
3075 file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])
3078 Move a file or directory within a filesystem from <oldname> to
3079 <newname>, replacing the destination atomically.
3080 The options are:
3082 RESULT <result>
3084 New in version 3.21.
3085 Set <result> variable to 0 on success or an error mes‐
3088 sage otherwise. If RESULT is not specified and the op‐
3089 eration fails, an error is emitted.
3090 NO_REPLACE
3092 New in version 3.21.
3093 If the <newname> path already exists, do not replace
3096 it. If RESULT <result> is used, the result variable
3097 will be set to NO_REPLACE. Otherwise, an error is
3098 emitted.
3099 file(COPY_FILE <oldname> <newname> [RESULT <result>] [ONLY_IF_DIFFER‐
3101 ENT] [INPUT_MAY_BE_RECENT])
3102 New in version 3.21.
3103 Copy a file from <oldname> to <newname>. Directories are not
3106 supported. Symlinks are ignored and <oldfile>'s content is read
3107 and written to <newname> as a new file.
3108 The options are:
3110 RESULT <result>
3112 Set <result> variable to 0 on success or an error mes‐
3113 sage otherwise. If RESULT is not specified and the
3114 operation fails, an error is emitted.
3115 ONLY_IF_DIFFERENT
3117 If the <newname> path already exists, do not replace
3118 it if the file's contents are already the same as
3119 <oldname> (this avoids updating <newname>'s time‐
3120 stamp).
3121 INPUT_MAY_BE_RECENT
3123 New in version 3.26.
3124 Tell CMake that the input file may have been recently
3127 created. This is meaningful only on Windows, where
3128 files may be inaccessible for a short time after they
3129 are created. With this option, if permission is de‐
3130 nied, CMake will retry reading the input a few times.
3131 This sub-command has some similarities to configure_file() with
3133 the COPYONLY option. An important difference is that
3134 configure_file() creates a dependency on the source file, so
3135 CMake will be re-run if it changes. The file(COPY_FILE) sub-com‐
3136 mand does not create such a dependency.
3137 See also the file(COPY) sub-command just below which provides
3139 further file-copying capabilities.
3140 file(COPY [...])
3142 file(INSTALL [...])
3144 The COPY signature copies files, directories, and symlinks to a
3145 destination folder. Relative input paths are evaluated with re‐
3146 spect to the current source directory, and a relative destina‐
3147 tion is evaluated with respect to the current build directory.
3148 Copying preserves input file timestamps, and optimizes out a
3149 file if it exists at the destination with the same timestamp.
3150 Copying preserves input permissions unless explicit permissions
3151 or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PER‐
3152 MISSIONS).
3153 file(<COPY|INSTALL> <files>... DESTINATION <dir>
3155 [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
3156 [FILE_PERMISSIONS <permissions>...]
3157 [DIRECTORY_PERMISSIONS <permissions>...]
3158 [FOLLOW_SYMLINK_CHAIN]
3159 [FILES_MATCHING]
3160 [[PATTERN <pattern> | REGEX <regex>]
3161 [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
3162 NOTE:
3164 For a simple file copying operation, the file(COPY_FILE)
3165 sub-command just above may be easier to use.
3166 New in version 3.15: If FOLLOW_SYMLINK_CHAIN is specified, COPY
3168 will recursively resolve the symlinks at the paths given until a
3169 real file is found, and install a corresponding symlink in the
3170 destination for each symlink encountered. For each symlink that
3171 is installed, the resolution is stripped of the directory, leav‐
3172 ing only the filename, meaning that the new symlink points to a
3173 file in the same directory as the symlink. This feature is use‐
3174 ful on some Unix systems, where libraries are installed as a
3175 chain of symlinks with version numbers, with less specific ver‐
3176 sions pointing to more specific versions. FOLLOW_SYMLINK_CHAIN
3177 will install all of these symlinks and the library itself into
3178 the destination directory. For example, if you have the follow‐
3179 ing directory structure:
3180 • /opt/foo/lib/libfoo.so.1.2.3
3182 • /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3
3184 • /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2
3186 • /opt/foo/lib/libfoo.so -> libfoo.so.1
3188 and you do:
3190 file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)
3192 This will install all of the symlinks and libfoo.so.1.2.3 itself
3194 into lib.
3195 See the install(DIRECTORY) command for documentation of permis‐
3198 sions, FILES_MATCHING, PATTERN, REGEX, and EXCLUDE options.
3199 Copying directories preserves the structure of their content
3200 even if options are used to select a subset of files.
3201 The INSTALL signature differs slightly from COPY: it prints sta‐
3203 tus messages, and NO_SOURCE_PERMISSIONS is default. Installation
3204 scripts generated by the install() command use this signature
3205 (with some undocumented options for internal use).
3206 Changed in version 3.22: The environment variable
3208 CMAKE_INSTALL_MODE can override the default copying behavior of
3209 file(INSTALL).
3210 file(SIZE <filename> <variable>)
3213 New in version 3.14.
3214 Determine the file size of the <filename> and put the result in
3217 <variable> variable. Requires that <filename> is a valid path
3218 pointing to a file and is readable.
3219 file(READ_SYMLINK <linkname> <variable>)
3221 New in version 3.14.
3222 Query the symlink <linkname> and stores the path it points to in
3225 the result <variable>. If <linkname> does not exist or is not a
3226 symlink, CMake issues a fatal error.
3227 Note that this command returns the raw symlink path and does not
3229 resolve a relative path. The following is an example of how to
3230 ensure that an absolute path is obtained:
3231 set(linkname "/path/to/foo.sym")
3233 file(READ_SYMLINK "${linkname}" result)
3234 if(NOT IS_ABSOLUTE "${result}")
3235 get_filename_component(dir "${linkname}" DIRECTORY)
3236 set(result "${dir}/${result}")
3237 endif()
3238 file(CREATE_LINK <original> <linkname> [RESULT <result>] [COPY_ON_ER‐
3240 ROR] [SYMBOLIC])
3241 New in version 3.14.
3242 Create a link <linkname> that points to <original>. It will be
3245 a hard link by default, but providing the SYMBOLIC option re‐
3246 sults in a symbolic link instead. Hard links require that orig‐
3247 inal exists and is a file, not a directory. If <linkname> al‐
3248 ready exists, it will be overwritten.
3249 The <result> variable, if specified, receives the status of the
3251 operation. It is set to 0 upon success or an error message oth‐
3252 erwise. If RESULT is not specified and the operation fails, a
3253 fatal error is emitted.
3254 Specifying COPY_ON_ERROR enables copying the file as a fallback
3256 if creating the link fails. It can be useful for handling situ‐
3257 ations such as <original> and <linkname> being on different
3258 drives or mount points, which would make them unable to support
3259 a hard link.
3260 file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...]
3262 [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permis‐
3263 sions>...])
3264 New in version 3.19.
3265 Set the permissions for the <files>... and <directories>...
3268 specified. Valid permissions are OWNER_READ, OWNER_WRITE,
3269 OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE,
3270 WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, SETGID.
3271 Valid combination of keywords are:
3273 PERMISSIONS
3275 All items are changed.
3276 FILE_PERMISSIONS
3278 Only files are changed.
3279 DIRECTORY_PERMISSIONS
3281 Only directories are changed.
3282 PERMISSIONS and FILE_PERMISSIONS
3284 FILE_PERMISSIONS overrides PERMISSIONS for files.
3285 PERMISSIONS and DIRECTORY_PERMISSIONS
3287 DIRECTORY_PERMISSIONS overrides PERMISSIONS for direc‐
3288 tories.
3289 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS
3291 Use FILE_PERMISSIONS for files and DIRECTORY_PERMIS‐
3292 SIONS for directories.
3293 file(CHMOD_RECURSE <files>... <directories>... [PERMISSIONS <permis‐
3295 sions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMIS‐
3296 SIONS <permissions>...])
3297 New in version 3.19.
3298 Same as CHMOD, but change the permissions of files and directo‐
3301 ries present in the <directories>... recursively.
3302 Path Conversion
3304 file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
3305 New in version 3.19.
3306 Compute the absolute path to an existing file or directory with
3309 symlinks resolved. The options are:
3310 BASE_DIRECTORY <dir>
3312 If the provided <path> is a relative path, it is eval‐
3313 uated relative to the given base directory <dir>. If
3314 no base directory is provided, the default base direc‐
3315 tory will be CMAKE_CURRENT_SOURCE_DIR.
3316 EXPAND_TILDE
3318 New in version 3.21.
3319 If the <path> is ~ or starts with ~/, the ~ is re‐
3322 placed by the user's home directory. The path to the
3323 home directory is obtained from environment variables.
3324 On Windows, the USERPROFILE environment variable is
3325 used, falling back to the HOME environment variable if
3326 USERPROFILE is not defined. On all other platforms,
3327 only HOME is used.
3328 file(RELATIVE_PATH <variable> <directory> <file>)
3330 Compute the relative path from a <directory> to a <file> and
3331 store it in the <variable>.
3332 file(TO_CMAKE_PATH "<path>" <variable>)
3334 file(TO_NATIVE_PATH "<path>" <variable>)
3336 The TO_CMAKE_PATH mode converts a native <path> into a
3337 cmake-style path with forward-slashes (/). The input can be a
3338 single path or a system search path like $ENV{PATH}. A search
3339 path will be converted to a cmake-style list separated by ;
3340 characters.
3341 The TO_NATIVE_PATH mode converts a cmake-style <path> into a na‐
3343 tive path with platform-specific slashes (\ on Windows hosts and
3344 / elsewhere).
3345 Always use double quotes around the <path> to be sure it is
3347 treated as a single argument to this command.
3348 Transfer
3350 file(DOWNLOAD <url> [<file>] [<options>...])
3351 file(UPLOAD <file> <url> [<options>...])
3353 The DOWNLOAD subcommand downloads the given <url> to a local
3354 <file>. The UPLOAD mode uploads a local <file> to a given
3355 <url>.
3356 New in version 3.19: If <file> is not specified for file(DOWN‐
3358 LOAD), the file is not saved. This can be useful if you want to
3359 know if a file can be downloaded (for example, to check that it
3360 exists) without actually saving it anywhere.
3361 Options to both DOWNLOAD and UPLOAD are:
3364 INACTIVITY_TIMEOUT <seconds>
3366 Terminate the operation after a period of inactivity.
3367 LOG <variable>
3369 Store a human-readable log of the operation in a vari‐
3370 able.
3371 SHOW_PROGRESS
3373 Print progress information as status messages until
3374 the operation is complete.
3375 STATUS <variable>
3377 Store the resulting status of the operation in a vari‐
3378 able. The status is a ; separated list of length 2.
3379 The first element is the numeric return value for the
3380 operation, and the second element is a string value
3381 for the error. A 0 numeric error means no error in
3382 the operation.
3383 TIMEOUT <seconds>
3385 Terminate the operation after a given total time has
3386 elapsed.
3387 USERPWD <username>:<password>
3389 New in version 3.7.
3390 Set username and password for operation.
3393 HTTPHEADER <HTTP-header>
3395 New in version 3.7.
3396 HTTP header for DOWNLOAD and UPLOAD operations. HTTP‐
3399 HEADER can be repeated for multiple options:
3400 file(DOWNLOAD <url>
3402 HTTPHEADER "Authorization: Bearer <auth-token>"
3403 HTTPHEADER "UserAgent: Mozilla/5.0")
3404 NETRC <level>
3406 New in version 3.11.
3407 Specify whether the .netrc file is to be used for op‐
3410 eration. If this option is not specified, the value
3411 of the CMAKE_NETRC variable will be used instead.
3412 Valid levels are:
3414 IGNORED
3416 The .netrc file is ignored. This is the
3417 default.
3418 OPTIONAL
3420 The .netrc file is optional, and informa‐
3421 tion in the URL is preferred. The file
3422 will be scanned to find which ever informa‐
3423 tion is not specified in the URL.
3424 REQUIRED
3426 The .netrc file is required, and informa‐
3427 tion in the URL is ignored.
3428 NETRC_FILE <file>
3430 New in version 3.11.
3431 Specify an alternative .netrc file to the one in your
3434 home directory, if the NETRC level is OPTIONAL or RE‐
3435 QUIRED. If this option is not specified, the value of
3436 the CMAKE_NETRC_FILE variable will be used instead.
3437 TLS_VERIFY <ON|OFF>
3439 Specify whether to verify the server certificate for
3440 https:// URLs. The default is to not verify. If this
3441 option is not specified, the value of the
3442 CMAKE_TLS_VERIFY variable will be used instead.
3443 New in version 3.18: Added support to file(UPLOAD).
3445 TLS_CAINFO <file>
3448 Specify a custom Certificate Authority file for
3449 https:// URLs. If this option is not specified, the
3450 value of the CMAKE_TLS_CAINFO variable will be used
3451 instead.
3452 New in version 3.18: Added support to file(UPLOAD).
3454 For https:// URLs CMake must be built with OpenSSL support.
3457 TLS/SSL certificates are not checked by default. Set TLS_VERIFY
3458 to ON to check certificates.
3459 Additional options to DOWNLOAD are:
3461 EXPECTED_HASH <algorithm>=<value>
3463 Verify that the downloaded content hash matches the
3464 expected value, where <algorithm> is one of the algo‐
3465 rithms supported by <HASH>. If the file already ex‐
3466 ists and matches the hash, the download is skipped.
3467 If the file already exists and does not match the
3468 hash, the file is downloaded again. If after download
3469 the file does not match the hash, the operation fails
3470 with an error. It is an error to specify this option
3471 if DOWNLOAD is not given a <file>.
3472 EXPECTED_MD5 <value>
3474 Historical short-hand for EXPECTED_HASH MD5=<value>.
3475 It is an error to specify this if DOWNLOAD is not
3476 given a <file>.
3477 RANGE_START <value>
3479 New in version 3.24.
3480 Offset of the start of the range in file in bytes.
3483 Could be omitted to download up to the specified
3484 RANGE_END.
3485 RANGE_END <value>
3487 New in version 3.24.
3488 Offset of the end of the range in file in bytes. Could
3491 be omitted to download everything from the specified
3492 RANGE_START to the end of file.
3493 Locking
3495 file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>]
3496 [RESULT_VARIABLE <variable>] [TIMEOUT <seconds>])
3497 New in version 3.2.
3498 Lock a file specified by <path> if no DIRECTORY option present
3501 and file <path>/cmake.lock otherwise. The file will be locked
3502 for the scope defined by the GUARD option (default value is
3503 PROCESS). The RELEASE option can be used to unlock the file ex‐
3504 plicitly. If the TIMEOUT option is not specified, CMake will
3505 wait until the lock succeeds or until a fatal error occurs. If
3506 TIMEOUT is set to 0, locking will be tried once and the result
3507 will be reported immediately. If TIMEOUT is not 0, CMake will
3508 try to lock the file for the period specified by the TIMEOUT
3509 <seconds> value. Any errors will be interpreted as fatal if
3510 there is no RESULT_VARIABLE option. Otherwise, the result will
3511 be stored in <variable> and will be 0 on success or an error
3512 message on failure.
3513 Note that lock is advisory; there is no guarantee that other
3515 processes will respect this lock, i.e. lock synchronize two or
3516 more CMake instances sharing some modifiable resources. Similar
3517 logic applies to the DIRECTORY option; locking a parent direc‐
3518 tory doesn't prevent other LOCK commands from locking any child
3519 directory or file.
3520 Trying to lock the same file twice is not allowed. Any interme‐
3522 diate directories and the file itself will be created if they
3523 not exist. The GUARD and TIMEOUT options are ignored on the RE‐
3524 LEASE operation.
3525 Archiving
3527 file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [FORMAT <format>]
3528 [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]]
3529 [MTIME <mtime>] [VERBOSE])
3530 New in version 3.18.
3531 Creates the specified <archive> file with the files and directo‐
3534 ries listed in <paths>. Note that <paths> must list actual
3535 files or directories; wildcards are not supported.
3536 Use the FORMAT option to specify the archive format. Supported
3538 values for <format> are 7zip, gnutar, pax, paxr, raw and zip.
3539 If FORMAT is not given, the default format is paxr.
3540 Some archive formats allow the type of compression to be speci‐
3542 fied. The 7zip and zip archive formats already imply a specific
3543 type of compression. The other formats use no compression by
3544 default, but can be directed to do so with the COMPRESSION op‐
3545 tion. Valid values for <compression> are None, BZip2, GZip, XZ,
3546 and Zstd.
3547 New in version 3.19: The compression level can be specified with
3549 the COMPRESSION_LEVEL option. The <compression-level> should be
3550 between 0-9, with the default being 0. The COMPRESSION option
3551 must be present when COMPRESSION_LEVEL is given.
3552 New in version 3.26: The <compression-level> of the Zstd algo‐
3555 rithm can be set between 0-19.
3556 NOTE:
3559 With FORMAT set to raw, only one file will be compressed with
3560 the compression type specified by COMPRESSION.
3561 The VERBOSE option enables verbose output for the archive opera‐
3563 tion.
3564 To specify the modification time recorded in tarball entries,
3566 use the MTIME option.
3567 file(ARCHIVE_EXTRACT INPUT <archive> [DESTINATION <dir>] [PAT‐
3569 TERNS <patterns>...] [LIST_ONLY] [VERBOSE] [TOUCH])
3570 New in version 3.18.
3571 Extracts or lists the content of the specified <archive>.
3574 The directory where the content of the archive will be extracted
3576 to can be specified using the DESTINATION option. If the direc‐
3577 tory does not exist, it will be created. If DESTINATION is not
3578 given, the current binary directory will be used.
3579 If required, you may select which files and directories to list
3581 or extract from the archive using the specified <patterns>.
3582 Wildcards are supported. If the PATTERNS option is not given,
3583 the entire archive will be listed or extracted.
3584 LIST_ONLY will list the files in the archive rather than extract
3586 them.
3587 New in version 3.24: The TOUCH option gives extracted files a
3589 current local timestamp instead of extracting file timestamps
3590 from the archive.
3591 With VERBOSE, the command will produce verbose output.
3594 find_file
3596 A short-hand signature is:
3597 find_file (<VAR> name1 [path1 path2 ...])
3599 The general signature is:
3601 find_file (
3603 <VAR>
3604 name | NAMES name1 [name2 ...]
3605 [HINTS [path | ENV var]... ]
3606 [PATHS [path | ENV var]... ]
3607 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
3608 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3609 [VALIDATOR function]
3610 [DOC "cache documentation string"]
3611 [NO_CACHE]
3612 [REQUIRED]
3613 [NO_DEFAULT_PATH]
3614 [NO_PACKAGE_ROOT_PATH]
3615 [NO_CMAKE_PATH]
3616 [NO_CMAKE_ENVIRONMENT_PATH]
3617 [NO_SYSTEM_ENVIRONMENT_PATH]
3618 [NO_CMAKE_SYSTEM_PATH]
3619 [NO_CMAKE_INSTALL_PREFIX]
3620 [CMAKE_FIND_ROOT_PATH_BOTH |
3621 ONLY_CMAKE_FIND_ROOT_PATH |
3622 NO_CMAKE_FIND_ROOT_PATH]
3623 )
3624 This command is used to find a full path to named file. A cache entry,
3626 or a normal variable if NO_CACHE is specified, named by <VAR> is cre‐
3627 ated to store the result of this command. If the full path to a file
3628 is found the result is stored in the variable and the search will not
3629 be repeated unless the variable is cleared. If nothing is found, the
3630 result will be <VAR>-NOTFOUND.
3631 Options include:
3633 NAMES Specify one or more possible names for the full path to a file.
3635 When using this to specify names with and without a version suf‐
3637 fix, we recommend specifying the unversioned name first so that
3638 locally-built packages can be found before those provided by
3639 distributions.
3640 HINTS, PATHS
3642 Specify directories to search in addition to the default loca‐
3643 tions. The ENV var sub-option reads paths from a system envi‐
3644 ronment variable.
3645 Changed in version 3.24: On Windows platform, it is possible to
3647 include registry queries as part of the directories, using a
3648 dedicated syntax. Such specifications will be ignored on all
3649 other platforms.
3650 REGISTRY_VIEW
3653 New in version 3.24.
3654 Specify which registry views must be queried. This option is
3657 only meaningful on Windows platforms and will be ignored on
3658 other ones. When not specified, the TARGET view is used when the
3659 CMP0134 policy is NEW. Refer to CMP0134 for the default view
3660 when the policy is OLD.
3661 64 Query the 64-bit registry. On 32-bit Windows, it always
3663 returns the string /REGISTRY-NOTFOUND.
3664 32 Query the 32-bit registry.
3666 64_32 Query both views (64 and 32) and generate a path for
3668 each.
3669 32_64 Query both views (32 and 64) and generate a path for
3671 each.
3672 HOST Query the registry matching the architecture of the host:
3674 64 on 64-bit Windows and 32 on 32-bit Windows.
3675 TARGET Query the registry matching the architecture specified by
3677 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
3678 back to HOST view.
3679 BOTH Query both views (32 and 64). The order depends on the
3681 following rules: If the CMAKE_SIZEOF_VOID_P variable is
3682 defined, use the following view depending on the content
3683 of this variable:
3684 • 8: 64_32
3686 • 4: 32_64
3688 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
3690 on the architecture of the host:
3691 • 64-bit: 64_32
3693 • 32-bit: 32
3695 PATH_SUFFIXES
3697 Specify additional subdirectories to check below each directory
3698 location otherwise considered.
3699 VALIDATOR
3701 New in version 3.25.
3702 Specify a function() to be called for each candidate item found
3705 (a macro() cannot be provided, that will result in an error).
3706 Two arguments will be passed to the validator function: the name
3707 of a result variable, and the absolute path to the candidate
3708 item. The item will be accepted and the search will end unless
3709 the function sets the value in the result variable to false in
3710 the calling scope. The result variable will hold a true value
3711 when the validator function is entered.
3712 function(my_check validator_result_var item)
3714 if(NOT item MATCHES ...)
3715 set(${validator_result_var} FALSE PARENT_SCOPE)
3716 endif()
3717 endfunction()
3718 find_file (result NAMES ... VALIDATOR my_check)
3720 Note that if a cached result is used, the search is skipped and
3722 any VALIDATOR is ignored. The cached result is not required to
3723 pass the validation function.
3724 DOC Specify the documentation string for the <VAR> cache entry.
3726 NO_CACHE
3728 New in version 3.21.
3729 The result of the search will be stored in a normal variable
3732 rather than a cache entry.
3733 NOTE:
3735 If the variable is already set before the call (as a normal
3736 or cache variable) then the search will not occur.
3737 WARNING:
3739 This option should be used with caution because it can
3740 greatly increase the cost of repeated configure steps.
3741 REQUIRED
3743 New in version 3.18.
3744 Stop processing with an error message if nothing is found, oth‐
3747 erwise the search will be attempted again the next time
3748 find_file is invoked with the same variable.
3749 If NO_DEFAULT_PATH is specified, then no additional paths are added to
3751 the search. If NO_DEFAULT_PATH is not specified, the search process is
3752 as follows:
3753 1. If called from within a find module or any other script loaded by a
3755 call to find_package(<PackageName>), search prefixes unique to the
3756 current package being found. See policy CMP0074.
3757 New in version 3.12.
3759 Specifically, search paths specified by the following variables, in
3762 order:
3763 a. <PackageName>_ROOT CMake variable, where <PackageName> is the
3765 case-preserved package name.
3766 b. <PACKAGENAME>_ROOT CMake variable, where <PACKAGENAME> is the up‐
3768 per-cased package name. See policy CMP0144.
3769 New in version 3.27.
3771 c. <PackageName>_ROOT environment variable, where <PackageName> is
3774 the case-preserved package name.
3775 d. <PACKAGENAME>_ROOT environment variable, where <PACKAGENAME> is
3777 the upper-cased package name. See policy CMP0144.
3778 New in version 3.27.
3780 The package root variables are maintained as a stack, so if called
3783 from nested find modules or config packages, root paths from the
3784 parent's find module or config package will be searched after paths
3785 from the current module or package. In other words, the search or‐
3786 der would be <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT},
3787 <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc. This can be
3788 skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
3789 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.
3790 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3792 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
3793 variable and the <PackageName>_ROOT environment variable if called
3794 from within a find module loaded by find_package(<PackageName>)
3795 2. Search paths specified in cmake-specific cache variables. These are
3797 intended to be used on the command line with a -DVAR=value. The
3798 values are interpreted as semicolon-separated lists. This can be
3799 skipped if NO_CMAKE_PATH is passed or by setting the
3800 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
3801 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3803 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3804 • CMAKE_INCLUDE_PATH
3806 • CMAKE_FRAMEWORK_PATH
3808 3. Search paths specified in cmake-specific environment variables.
3810 These are intended to be set in the user's shell configuration, and
3811 therefore use the host's native path separator (; on Windows and :
3812 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
3813 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
3814 FALSE.
3815 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3817 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
3818 • CMAKE_INCLUDE_PATH
3820 • CMAKE_FRAMEWORK_PATH
3822 4. Search the paths specified by the HINTS option. These should be
3824 paths computed by system introspection, such as a hint provided by
3825 the location of another item already found. Hard-coded guesses
3826 should be specified with the PATHS option.
3827 5. Search the standard system environment variables. This can be
3829 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
3830 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
3831 • The directories in INCLUDE and PATH.
3833 • On Windows hosts: <prefix>/include/<arch> if
3835 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for each
3836 <prefix>/[s]bin in PATH, and <entry>/include for other entries in
3837 PATH.
3838 6. Search cmake variables defined in the Platform files for the current
3840 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
3841 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
3842 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
3843 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
3844 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
3845 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
3847 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3848 • CMAKE_SYSTEM_INCLUDE_PATH
3850 • CMAKE_SYSTEM_FRAMEWORK_PATH
3852 The platform paths that these variables contain are locations that
3854 typically include installed software. An example being /usr/local
3855 for UNIX based platforms.
3856 7. Search the paths specified by the PATHS option or in the short-hand
3858 version of the command. These are typically hard-coded guesses.
3859 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
3861 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
3862 can also cause some of the above locations to be ignored.
3863 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
3865 globally disable various search locations.
3866 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
3869 determine the order of preference between Apple-style and unix-style
3870 package components.
3871 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
3873 ries to be prepended to all other search directories. This effectively
3874 "re-roots" the entire search under given locations. Paths which are
3875 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
3876 ing, because that variable is always a path on the host system. By de‐
3877 fault the CMAKE_FIND_ROOT_PATH is empty.
3878 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
3880 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
3881 fects. See the documentation for that variable for more.
3882 These variables are especially useful when cross-compiling to point to
3884 the root directory of the target environment and CMake will search
3885 there too. By default at first the directories listed in
3886 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
3887 searched, and then the non-rooted directories will be searched. The
3888 default behavior can be adjusted by setting
3889 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
3890 ridden on a per-call basis using options:
3891 CMAKE_FIND_ROOT_PATH_BOTH
3893 Search in the order described above.
3894 NO_CMAKE_FIND_ROOT_PATH
3896 Do not use the CMAKE_FIND_ROOT_PATH variable.
3897 ONLY_CMAKE_FIND_ROOT_PATH
3899 Search only the re-rooted directories and directories below
3900 CMAKE_STAGING_PREFIX.
3901 The default search order is designed to be most-specific to least-spe‐
3903 cific for common use cases. Projects may override the order by simply
3904 calling the command multiple times and using the NO_* options:
3905 find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3907 find_file (<VAR> NAMES name)
3908 Once one of the calls succeeds the result variable will be set and
3910 stored in the cache so that no call will search again.
3911 find_library
3913 A short-hand signature is:
3914 find_library (<VAR> name1 [path1 path2 ...])
3916 The general signature is:
3918 find_library (
3920 <VAR>
3921 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
3922 [HINTS [path | ENV var]... ]
3923 [PATHS [path | ENV var]... ]
3924 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
3925 [PATH_SUFFIXES suffix1 [suffix2 ...]]
3926 [VALIDATOR function]
3927 [DOC "cache documentation string"]
3928 [NO_CACHE]
3929 [REQUIRED]
3930 [NO_DEFAULT_PATH]
3931 [NO_PACKAGE_ROOT_PATH]
3932 [NO_CMAKE_PATH]
3933 [NO_CMAKE_ENVIRONMENT_PATH]
3934 [NO_SYSTEM_ENVIRONMENT_PATH]
3935 [NO_CMAKE_SYSTEM_PATH]
3936 [NO_CMAKE_INSTALL_PREFIX]
3937 [CMAKE_FIND_ROOT_PATH_BOTH |
3938 ONLY_CMAKE_FIND_ROOT_PATH |
3939 NO_CMAKE_FIND_ROOT_PATH]
3940 )
3941 This command is used to find a library. A cache entry, or a normal
3943 variable if NO_CACHE is specified, named by <VAR> is created to store
3944 the result of this command. If the library is found the result is
3945 stored in the variable and the search will not be repeated unless the
3946 variable is cleared. If nothing is found, the result will be
3947 <VAR>-NOTFOUND.
3948 Options include:
3950 NAMES Specify one or more possible names for the library.
3952 When using this to specify names with and without a version suf‐
3954 fix, we recommend specifying the unversioned name first so that
3955 locally-built packages can be found before those provided by
3956 distributions.
3957 HINTS, PATHS
3959 Specify directories to search in addition to the default loca‐
3960 tions. The ENV var sub-option reads paths from a system envi‐
3961 ronment variable.
3962 Changed in version 3.24: On Windows platform, it is possible to
3964 include registry queries as part of the directories, using a
3965 dedicated syntax. Such specifications will be ignored on all
3966 other platforms.
3967 REGISTRY_VIEW
3970 New in version 3.24.
3971 Specify which registry views must be queried. This option is
3974 only meaningful on Windows platforms and will be ignored on
3975 other ones. When not specified, the TARGET view is used when the
3976 CMP0134 policy is NEW. Refer to CMP0134 for the default view
3977 when the policy is OLD.
3978 64 Query the 64-bit registry. On 32-bit Windows, it always
3980 returns the string /REGISTRY-NOTFOUND.
3981 32 Query the 32-bit registry.
3983 64_32 Query both views (64 and 32) and generate a path for
3985 each.
3986 32_64 Query both views (32 and 64) and generate a path for
3988 each.
3989 HOST Query the registry matching the architecture of the host:
3991 64 on 64-bit Windows and 32 on 32-bit Windows.
3992 TARGET Query the registry matching the architecture specified by
3994 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
3995 back to HOST view.
3996 BOTH Query both views (32 and 64). The order depends on the
3998 following rules: If the CMAKE_SIZEOF_VOID_P variable is
3999 defined, use the following view depending on the content
4000 of this variable:
4001 • 8: 64_32
4003 • 4: 32_64
4005 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
4007 on the architecture of the host:
4008 • 64-bit: 64_32
4010 • 32-bit: 32
4012 PATH_SUFFIXES
4014 Specify additional subdirectories to check below each directory
4015 location otherwise considered.
4016 VALIDATOR
4018 New in version 3.25.
4019 Specify a function() to be called for each candidate item found
4022 (a macro() cannot be provided, that will result in an error).
4023 Two arguments will be passed to the validator function: the name
4024 of a result variable, and the absolute path to the candidate
4025 item. The item will be accepted and the search will end unless
4026 the function sets the value in the result variable to false in
4027 the calling scope. The result variable will hold a true value
4028 when the validator function is entered.
4029 function(my_check validator_result_var item)
4031 if(NOT item MATCHES ...)
4032 set(${validator_result_var} FALSE PARENT_SCOPE)
4033 endif()
4034 endfunction()
4035 find_library (result NAMES ... VALIDATOR my_check)
4037 Note that if a cached result is used, the search is skipped and
4039 any VALIDATOR is ignored. The cached result is not required to
4040 pass the validation function.
4041 DOC Specify the documentation string for the <VAR> cache entry.
4043 NO_CACHE
4045 New in version 3.21.
4046 The result of the search will be stored in a normal variable
4049 rather than a cache entry.
4050 NOTE:
4052 If the variable is already set before the call (as a normal
4053 or cache variable) then the search will not occur.
4054 WARNING:
4056 This option should be used with caution because it can
4057 greatly increase the cost of repeated configure steps.
4058 REQUIRED
4060 New in version 3.18.
4061 Stop processing with an error message if nothing is found, oth‐
4064 erwise the search will be attempted again the next time find_li‐
4065 brary is invoked with the same variable.
4066 If NO_DEFAULT_PATH is specified, then no additional paths are added to
4068 the search. If NO_DEFAULT_PATH is not specified, the search process is
4069 as follows:
4070 1. If called from within a find module or any other script loaded by a
4072 call to find_package(<PackageName>), search prefixes unique to the
4073 current package being found. See policy CMP0074.
4074 New in version 3.12.
4076 Specifically, search paths specified by the following variables, in
4079 order:
4080 a. <PackageName>_ROOT CMake variable, where <PackageName> is the
4082 case-preserved package name.
4083 b. <PACKAGENAME>_ROOT CMake variable, where <PACKAGENAME> is the up‐
4085 per-cased package name. See policy CMP0144.
4086 New in version 3.27.
4088 c. <PackageName>_ROOT environment variable, where <PackageName> is
4091 the case-preserved package name.
4092 d. <PACKAGENAME>_ROOT environment variable, where <PACKAGENAME> is
4094 the upper-cased package name. See policy CMP0144.
4095 New in version 3.27.
4097 The package root variables are maintained as a stack, so if called
4100 from nested find modules or config packages, root paths from the
4101 parent's find module or config package will be searched after paths
4102 from the current module or package. In other words, the search or‐
4103 der would be <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT},
4104 <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc. This can be
4105 skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
4106 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.
4107 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4109 <prefix>/lib for each <prefix> in the <PackageName>_ROOT CMake
4110 variable and the <PackageName>_ROOT environment variable if called
4111 from within a find module loaded by find_package(<PackageName>)
4112 2. Search paths specified in cmake-specific cache variables. These are
4114 intended to be used on the command line with a -DVAR=value. The
4115 values are interpreted as semicolon-separated lists. This can be
4116 skipped if NO_CMAKE_PATH is passed or by setting the
4117 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
4118 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4120 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
4121 • CMAKE_LIBRARY_PATH
4123 • CMAKE_FRAMEWORK_PATH
4125 3. Search paths specified in cmake-specific environment variables.
4127 These are intended to be set in the user's shell configuration, and
4128 therefore use the host's native path separator (; on Windows and :
4129 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
4130 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
4131 FALSE.
4132 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4134 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
4135 • CMAKE_LIBRARY_PATH
4137 • CMAKE_FRAMEWORK_PATH
4139 4. Search the paths specified by the HINTS option. These should be
4141 paths computed by system introspection, such as a hint provided by
4142 the location of another item already found. Hard-coded guesses
4143 should be specified with the PATHS option.
4144 5. Search the standard system environment variables. This can be
4146 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
4147 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
4148 • The directories in LIB and PATH.
4150 • On Windows hosts: <prefix>/lib/<arch> if
4152 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/lib for each <pre‐
4153 fix>/[s]bin in PATH, and <entry>/lib for other entries in PATH.
4154 6. Search cmake variables defined in the Platform files for the current
4156 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
4157 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
4158 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
4159 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
4160 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
4161 • <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
4163 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
4164 • CMAKE_SYSTEM_LIBRARY_PATH
4166 • CMAKE_SYSTEM_FRAMEWORK_PATH
4168 The platform paths that these variables contain are locations that
4170 typically include installed software. An example being /usr/local
4171 for UNIX based platforms.
4172 7. Search the paths specified by the PATHS option or in the short-hand
4174 version of the command. These are typically hard-coded guesses.
4175 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
4177 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
4178 can also cause some of the above locations to be ignored.
4179 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
4181 globally disable various search locations.
4182 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
4185 determine the order of preference between Apple-style and unix-style
4186 package components.
4187 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
4189 ries to be prepended to all other search directories. This effectively
4190 "re-roots" the entire search under given locations. Paths which are
4191 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
4192 ing, because that variable is always a path on the host system. By de‐
4193 fault the CMAKE_FIND_ROOT_PATH is empty.
4194 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
4196 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
4197 fects. See the documentation for that variable for more.
4198 These variables are especially useful when cross-compiling to point to
4200 the root directory of the target environment and CMake will search
4201 there too. By default at first the directories listed in
4202 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
4203 searched, and then the non-rooted directories will be searched. The
4204 default behavior can be adjusted by setting
4205 CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. This behavior can be manually over‐
4206 ridden on a per-call basis using options:
4207 CMAKE_FIND_ROOT_PATH_BOTH
4209 Search in the order described above.
4210 NO_CMAKE_FIND_ROOT_PATH
4212 Do not use the CMAKE_FIND_ROOT_PATH variable.
4213 ONLY_CMAKE_FIND_ROOT_PATH
4215 Search only the re-rooted directories and directories below
4216 CMAKE_STAGING_PREFIX.
4217 The default search order is designed to be most-specific to least-spe‐
4219 cific for common use cases. Projects may override the order by simply
4220 calling the command multiple times and using the NO_* options:
4221 find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
4223 find_library (<VAR> NAMES name)
4224 Once one of the calls succeeds the result variable will be set and
4226 stored in the cache so that no call will search again.
4227 When more than one value is given to the NAMES option this command by
4229 default will consider one name at a time and search every directory for
4230 it. The NAMES_PER_DIR option tells this command to consider one direc‐
4231 tory at a time and search for all names in it.
4232 Each library name given to the NAMES option is first considered as a
4234 library file name and then considered with platform-specific prefixes
4235 (e.g. lib) and suffixes (e.g. .so). Therefore one may specify library
4236 file names such as libfoo.a directly. This can be used to locate
4237 static libraries on UNIX-like systems.
4238 If the library found is a framework, then <VAR> will be set to the full
4240 path to the framework <fullPath>/A.framework. When a full path to a
4241 framework is used as a library, CMake will use a -framework A, and a
4242 -F<fullPath> to link the framework to the target.
4243 If the CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX variable is set all search
4245 paths will be tested as normal, with the suffix appended, and with all
4246 matches of lib/ replaced with lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUF‐
4247 FIX}/. This variable overrides the FIND_LIBRARY_USE_LIB32_PATHS,
4248 FIND_LIBRARY_USE_LIBX32_PATHS, and FIND_LIBRARY_USE_LIB64_PATHS global
4249 properties.
4250 If the FIND_LIBRARY_USE_LIB32_PATHS global property is set all search
4252 paths will be tested as normal, with 32/ appended, and with all matches
4253 of lib/ replaced with lib32/. This property is automatically set for
4254 the platforms that are known to need it if at least one of the lan‐
4255 guages supported by the project() command is enabled.
4256 If the FIND_LIBRARY_USE_LIBX32_PATHS global property is set all search
4258 paths will be tested as normal, with x32/ appended, and with all
4259 matches of lib/ replaced with libx32/. This property is automatically
4260 set for the platforms that are known to need it if at least one of the
4261 languages supported by the project() command is enabled.
4262 If the FIND_LIBRARY_USE_LIB64_PATHS global property is set all search
4264 paths will be tested as normal, with 64/ appended, and with all matches
4265 of lib/ replaced with lib64/. This property is automatically set for
4266 the platforms that are known to need it if at least one of the lan‐
4267 guages supported by the project() command is enabled.
4268 find_package
4270 NOTE:
4271 The Using Dependencies Guide provides a high-level introduction to
4272 this general topic. It provides a broader overview of where the
4273 find_package() command fits into the bigger picture, including its
4274 relationship to the FetchContent module. The guide is recommended
4275 pre-reading before moving on to the details below.
4276 Find a package (usually provided by something external to the project),
4278 and load its package-specific details. Calls to this command can also
4279 be intercepted by dependency providers.
4280 Search Modes
4282 The command has a few modes by which it searches for packages:
4283 Module mode
4285 In this mode, CMake searches for a file called Find<Package‐
4286 Name>.cmake, looking first in the locations listed in the
4287 CMAKE_MODULE_PATH, then among the Find Modules provided by the
4288 CMake installation. If the file is found, it is read and pro‐
4289 cessed by CMake. It is responsible for finding the package,
4290 checking the version, and producing any needed messages. Some
4291 Find modules provide limited or no support for versioning; check
4292 the Find module's documentation.
4293 The Find<PackageName>.cmake file is not typically provided by
4295 the package itself. Rather, it is normally provided by some‐
4296 thing external to the package, such as the operating system,
4297 CMake itself, or even the project from which the find_package()
4298 command was called. Being externally provided, Find Modules
4299 tend to be heuristic in nature and are susceptible to becoming
4300 out-of-date. They typically search for certain libraries, files
4301 and other package artifacts.
4302 Module mode is only supported by the basic command signature.
4304 Config mode
4306 In this mode, CMake searches for a file called <lowercasePacka‐
4307 geName>-config.cmake or <PackageName>Config.cmake. It will also
4308 look for <lowercasePackageName>-config-version.cmake or <Packa‐
4309 geName>ConfigVersion.cmake if version details were specified
4310 (see Config Mode Version Selection for an explanation of how
4311 these separate version files are used).
4312 In config mode, the command can be given a list of names to
4314 search for as package names. The locations where CMake searches
4315 for the config and version files is considerably more compli‐
4316 cated than for Module mode (see Config Mode Search Procedure).
4317 The config and version files are typically installed as part of
4319 the package, so they tend to be more reliable than Find modules.
4320 They usually contain direct knowledge of the package contents,
4321 so no searching or heuristics are needed within the config or
4322 version files themselves.
4323 Config mode is supported by both the basic and full command sig‐
4325 natures.
4326 FetchContent redirection mode
4328 New in version 3.24: A call to find_package() can be redirected
4329 internally to a package provided by the FetchContent module. To
4330 the caller, the behavior will appear similar to Config mode, ex‐
4331 cept that the search logic is by-passed and the component infor‐
4332 mation is not used. See FetchContent_Declare() and
4333 FetchContent_MakeAvailable() for further details.
4334 When not redirected to a package provided by FetchContent, the command
4337 arguments determine whether Module or Config mode is used. When the
4338 basic signature is used, the command searches in Module mode first. If
4339 the package is not found, the search falls back to Config mode. A user
4340 may set the CMAKE_FIND_PACKAGE_PREFER_CONFIG variable to true to re‐
4341 verse the priority and direct CMake to search using Config mode first
4342 before falling back to Module mode. The basic signature can also be
4343 forced to use only Module mode with a MODULE keyword. If the full sig‐
4344 nature is used, the command only searches in Config mode.
4345 Where possible, user code should generally look for packages using the
4347 basic signature, since that allows the package to be found with any
4348 mode. Project maintainers wishing to provide a config package should
4349 understand the bigger picture, as explained in Full Signature and all
4350 subsequent sections on this page.
4351 Basic Signature
4353 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
4354 [REQUIRED] [[COMPONENTS] [components...]]
4355 [OPTIONAL_COMPONENTS components...]
4356 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
4357 [GLOBAL]
4358 [NO_POLICY_SCOPE]
4359 [BYPASS_PROVIDER])
4360 The basic signature is supported by both Module and Config modes. The
4362 MODULE keyword implies that only Module mode can be used to find the
4363 package, with no fallback to Config mode.
4364 Regardless of the mode used, a <PackageName>_FOUND variable will be set
4366 to indicate whether the package was found. When the package is found,
4367 package-specific information may be provided through other variables
4368 and Imported Targets documented by the package itself. The QUIET op‐
4369 tion disables informational messages, including those indicating that
4370 the package cannot be found if it is not REQUIRED. The REQUIRED option
4371 stops processing with an error message if the package cannot be found.
4372 A package-specific list of required components may be listed after the
4374 COMPONENTS keyword. If any of these components are not able to be sat‐
4375 isfied, the package overall is considered to be not found. If the RE‐
4376 QUIRED option is also present, this is treated as a fatal error, other‐
4377 wise execution still continues. As a form of shorthand, if the RE‐
4378 QUIRED option is present, the COMPONENTS keyword can be omitted and the
4379 required components can be listed directly after REQUIRED.
4380 Additional optional components may be listed after OPTIONAL_COMPONENTS.
4382 If these cannot be satisfied, the package overall can still be consid‐
4383 ered found, as long as all required components are satisfied.
4384 The set of available components and their meaning are defined by the
4386 target package. Formally, it is up to the target package how to inter‐
4387 pret the component information given to it, but it should follow the
4388 expectations stated above. For calls where no components are speci‐
4389 fied, there is no single expected behavior and target packages should
4390 clearly define what occurs in such cases. Common arrangements include
4391 assuming it should find all components, no components or some well-de‐
4392 fined subset of the available components.
4393 New in version 3.24: The REGISTRY_VIEW keyword specifies which registry
4395 views should be queried. This keyword is only meaningful on Windows
4396 platforms and will be ignored on all others. Formally, it is up to the
4397 target package how to interpret the registry view information given to
4398 it.
4399 New in version 3.24: Specifying the GLOBAL keyword will promote all im‐
4402 ported targets to a global scope in the importing project. Alterna‐
4403 tively, this functionality can be enabled by setting the
4404 CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable.
4405 The [version] argument requests a version with which the package found
4408 should be compatible. There are two possible forms in which it may be
4409 specified:
4410 • A single version with the format major[.minor[.patch[.tweak]]],
4412 where each component is a numeric value.
4413 • A version range with the format versionMin...[<]versionMax where
4415 versionMin and versionMax have the same format and constraints on
4416 components being integers as the single version. By default, both
4417 end points are included. By specifying <, the upper end point
4418 will be excluded. Version ranges are only supported with CMake
4419 3.19 or later.
4420 The EXACT option requests that the version be matched exactly. This op‐
4422 tion is incompatible with the specification of a version range.
4423 If no [version] and/or component list is given to a recursive invoca‐
4425 tion inside a find-module, the corresponding arguments are forwarded
4426 automatically from the outer call (including the EXACT flag for [ver‐
4427 sion]). Version support is currently provided only on a pack‐
4428 age-by-package basis (see the Version Selection section below). When a
4429 version range is specified but the package is only designed to expect a
4430 single version, the package will ignore the upper end point of the
4431 range and only take the single version at the lower end of the range
4432 into account.
4433 See the cmake_policy() command documentation for discussion of the
4435 NO_POLICY_SCOPE option.
4436 New in version 3.24: The BYPASS_PROVIDER keyword is only allowed when
4438 find_package() is being called by a dependency provider. It can be
4439 used by providers to call the built-in find_package() implementation
4440 directly and prevent that call from being re-routed back to itself.
4441 Future versions of CMake may detect attempts to use this keyword from
4442 places other than a dependency provider and halt with a fatal error.
4443 Full Signature
4446 find_package(<PackageName> [version] [EXACT] [QUIET]
4447 [REQUIRED] [[COMPONENTS] [components...]]
4448 [OPTIONAL_COMPONENTS components...]
4449 [CONFIG|NO_MODULE]
4450 [GLOBAL]
4451 [NO_POLICY_SCOPE]
4452 [BYPASS_PROVIDER]
4453 [NAMES name1 [name2 ...]]
4454 [CONFIGS config1 [config2 ...]]
4455 [HINTS path1 [path2 ... ]]
4456 [PATHS path1 [path2 ... ]]
4457 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
4458 [PATH_SUFFIXES suffix1 [suffix2 ...]]
4459 [NO_DEFAULT_PATH]
4460 [NO_PACKAGE_ROOT_PATH]
4461 [NO_CMAKE_PATH]
4462 [NO_CMAKE_ENVIRONMENT_PATH]
4463 [NO_SYSTEM_ENVIRONMENT_PATH]
4464 [NO_CMAKE_PACKAGE_REGISTRY]
4465 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
4466 [NO_CMAKE_SYSTEM_PATH]
4467 [NO_CMAKE_INSTALL_PREFIX]
4468 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
4469 [CMAKE_FIND_ROOT_PATH_BOTH |
4470 ONLY_CMAKE_FIND_ROOT_PATH |
4471 NO_CMAKE_FIND_ROOT_PATH])
4472 The CONFIG option, the synonymous NO_MODULE option, or the use of op‐
4474 tions not specified in the basic signature all enforce pure Config
4475 mode. In pure Config mode, the command skips Module mode search and
4476 proceeds at once with Config mode search.
4477 Config mode search attempts to locate a configuration file provided by
4479 the package to be found. A cache entry called <PackageName>_DIR is
4480 created to hold the directory containing the file. By default, the
4481 command searches for a package with the name <PackageName>. If the
4482 NAMES option is given, the names following it are used instead of
4483 <PackageName>. The names are also considered when determining whether
4484 to redirect the call to a package provided by FetchContent.
4485 The command searches for a file called <PackageName>Config.cmake or
4487 <lowercasePackageName>-config.cmake for each name specified. A re‐
4488 placement set of possible configuration file names may be given using
4489 the CONFIGS option. The Config Mode Search Procedure is specified be‐
4490 low. Once found, any version constraint is checked, and if satisfied,
4491 the configuration file is read and processed by CMake. Since the file
4492 is provided by the package it already knows the location of package
4493 contents. The full path to the configuration file is stored in the
4494 cmake variable <PackageName>_CONFIG.
4495 All configuration files which have been considered by CMake while
4497 searching for the package with an appropriate version are stored in the
4498 <PackageName>_CONSIDERED_CONFIGS variable, and the associated versions
4499 in the <PackageName>_CONSIDERED_VERSIONS variable.
4500 If the package configuration file cannot be found CMake will generate
4502 an error describing the problem unless the QUIET argument is specified.
4503 If REQUIRED is specified and the package is not found a fatal error is
4504 generated and the configure step stops executing. If <PackageName>_DIR
4505 has been set to a directory not containing a configuration file CMake
4506 will ignore it and search from scratch.
4507 Package maintainers providing CMake package configuration files are en‐
4509 couraged to name and install them such that the Config Mode Search Pro‐
4510 cedure outlined below will find them without requiring use of addi‐
4511 tional options.
4512 Config Mode Search Procedure
4514 NOTE:
4515 When Config mode is used, this search procedure is applied regard‐
4516 less of whether the full or basic signature was given.
4517 New in version 3.24: All calls to find_package() (even in Module mode)
4519 first look for a config package file in the
4520 CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory. The FetchContent module,
4521 or even the project itself, may write files to that location to redi‐
4522 rect find_package() calls to content already provided by the project.
4523 If no config package file is found in that location, the search pro‐
4524 ceeds with the logic described below.
4525 CMake constructs a set of possible installation prefixes for the pack‐
4528 age. Under each prefix several directories are searched for a configu‐
4529 ration file. The tables below show the directories searched. Each en‐
4530 try is meant for installation trees following Windows (W), UNIX (U), or
4531 Apple (A) conventions:
4532 ┌────────────────────────────────────────────────────────────┬────────────┐
4534 │Entry │ Convention │
4535 ├────────────────────────────────────────────────────────────┼────────────┤
4536 │<prefix>/ │ W │
4537 ├────────────────────────────────────────────────────────────┼────────────┤
4538 │<prefix>/(cmake|CMake)/ │ W │
4539 ├────────────────────────────────────────────────────────────┼────────────┤
4540 │<prefix>/<name>*/ │ W │
4541 ├────────────────────────────────────────────────────────────┼────────────┤
4542 │<pre‐ │ W │
4543 │fix>/<name>*/(cmake|CMake)/ │ │
4544 ├────────────────────────────────────────────────────────────┼────────────┤
4545 │<pre‐ │ W │
4546 │fix>/<name>*/(cmake|CMake)/<name>*/ │ │
4547 │[1] │ │
4548 ├────────────────────────────────────────────────────────────┼────────────┤
4549 │<pre‐ │ U │
4550 │fix>/(lib/<arch>|lib*|share)/cmake/<name>*/ │ │
4551 ├────────────────────────────────────────────────────────────┼────────────┤
4552 │<prefix>/(lib/<arch>|lib*|share)/<name>*/ │ U │
4553 ├────────────────────────────────────────────────────────────┼────────────┤
4554 │<pre‐ │ U │
4555 │fix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ │ │
4556 ├────────────────────────────────────────────────────────────┼────────────┤
4557 │<pre‐ │ W/U │
4558 │fix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ │ │
4559 ├────────────────────────────────────────────────────────────┼────────────┤
4560 │<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ │ W/U │
4561 ├────────────────────────────────────────────────────────────┼────────────┤
4562 │<pre‐ │ W/U │
4563 │fix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ │ │
4564 └────────────────────────────────────────────────────────────┴────────────┘
4565 [1] New in version 3.25.
4567 On systems supporting macOS FRAMEWORK and BUNDLE, the following
4570 directories are searched for Frameworks or Application Bundles
4571 containing a configuration file:
4572 ┌───────────────────────────┬────────────┐
4574 │Entry │ Convention │
4575 ├───────────────────────────┼────────────┤
4576 │<prefix>/<name>.frame‐ │ A │
4577 │work/Resources/ │ │
4578 ├───────────────────────────┼────────────┤
4579 │<prefix>/<name>.frame‐ │ A │
4580 │work/Resources/CMake/ │ │
4581 └───────────────────────────┴────────────┘
4582 │<prefix>/<name>.frame‐ │ A │
4586 │work/Versions/*/Resources/ │ │
4587 ├───────────────────────────┼────────────┤
4588 │<prefix>/<name>.frame‐ │ A │
4589 │work/Versions/*/Re‐ │ │
4590 │sources/CMake/ │ │
4591 ├───────────────────────────┼────────────┤
4592 │<prefix>/<name>.app/Con‐ │ A │
4593 │tents/Resources/ │ │
4594 ├───────────────────────────┼────────────┤
4595 │<prefix>/<name>.app/Con‐ │ A │
4596 │tents/Resources/CMake/ │ │
4597 └───────────────────────────┴────────────┘
4598 In all cases the <name> is treated as case-insensitive and corre‐
4600 sponds to any of the names specified (<PackageName> or names given
4601 by NAMES).
4602 Paths with lib/<arch> are enabled if the
4604 CMAKE_LIBRARY_ARCHITECTURE variable is set. lib* includes one or
4605 more of the values lib64, lib32, libx32 or lib (searched in that
4606 order).
4607 • Paths with lib64 are searched on 64 bit platforms if the
4609 FIND_LIBRARY_USE_LIB64_PATHS property is set to TRUE.
4610 • Paths with lib32 are searched on 32 bit platforms if the
4612 FIND_LIBRARY_USE_LIB32_PATHS property is set to TRUE.
4613 • Paths with libx32 are searched on platforms using the x32 ABI if the
4615 FIND_LIBRARY_USE_LIBX32_PATHS property is set to TRUE.
4616 • The lib path is always searched.
4618 Changed in version 3.24: On Windows platform, it is possible to include
4620 registry queries as part of the directories specified through HINTS and
4621 PATHS keywords, using a dedicated syntax. Such specifications will be
4622 ignored on all other platforms.
4623 New in version 3.24: REGISTRY_VIEW can be specified to manage Windows
4626 registry queries specified as part of PATHS and HINTS.
4627 Specify which registry views must be queried. This option is only mean‐
4630 ingful on Windows platforms and will be ignored on other ones. When not
4631 specified, the TARGET view is used when the CMP0134 policy is NEW. Re‐
4632 fer to CMP0134 for the default view when the policy is OLD.
4633 64 Query the 64-bit registry. On 32-bit Windows, it always returns
4635 the string /REGISTRY-NOTFOUND.
4636 32 Query the 32-bit registry.
4638 64_32 Query both views (64 and 32) and generate a path for each.
4640 32_64 Query both views (32 and 64) and generate a path for each.
4642 HOST Query the registry matching the architecture of the host: 64 on
4644 64-bit Windows and 32 on 32-bit Windows.
4645 TARGET Query the registry matching the architecture specified by the
4647 CMAKE_SIZEOF_VOID_P variable. If not defined, fall back to HOST
4648 view.
4649 BOTH Query both views (32 and 64). The order depends on the following
4651 rules: If the CMAKE_SIZEOF_VOID_P variable is defined, use the
4652 following view depending on the content of this variable:
4653 • 8: 64_32
4655 • 4: 32_64
4657 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely on the
4659 architecture of the host:
4660 • 64-bit: 64_32
4662 • 32-bit: 32
4664 If PATH_SUFFIXES is specified, the suffixes are appended to each (W) or
4666 (U) directory entry one-by-one.
4667 This set of directories is intended to work in cooperation with
4669 projects that provide configuration files in their installation trees.
4670 Directories above marked with (W) are intended for installations on
4671 Windows where the prefix may point at the top of an application's in‐
4672 stallation directory. Those marked with (U) are intended for installa‐
4673 tions on UNIX platforms where the prefix is shared by multiple pack‐
4674 ages. This is merely a convention, so all (W) and (U) directories are
4675 still searched on all platforms. Directories marked with (A) are in‐
4676 tended for installations on Apple platforms. The CMAKE_FIND_FRAMEWORK
4677 and CMAKE_FIND_APPBUNDLE variables determine the order of preference.
4678 The set of installation prefixes is constructed using the following
4680 steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled.
4681 1. Search prefixes unique to the current <PackageName> being found.
4683 See policy CMP0074.
4684 New in version 3.12.
4686 Specifically, search prefixes specified by the following variables,
4689 in order:
4690 a. <PackageName>_ROOT CMake variable, where <PackageName> is the
4692 case-preserved package name.
4693 b. <PACKAGENAME>_ROOT CMake variable, where <PACKAGENAME> is the up‐
4695 per-cased package name. See policy CMP0144.
4696 New in version 3.27.
4698 c. <PackageName>_ROOT environment variable, where <PackageName> is
4701 the case-preserved package name.
4702 d. <PACKAGENAME>_ROOT environment variable, where <PACKAGENAME> is
4704 the upper-cased package name. See policy CMP0144.
4705 New in version 3.27.
4707 The package root variables are maintained as a stack so if called
4710 from within a find module, root paths from the parent's find module
4711 will also be searched after paths for the current package. This can
4712 be skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
4713 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.
4714 2. Search paths specified in cmake-specific cache variables. These are
4716 intended to be used on the command line with a -DVAR=VALUE. The
4717 values are interpreted as semicolon-separated lists. This can be
4718 skipped if NO_CMAKE_PATH is passed or by setting the
4719 CMAKE_FIND_USE_CMAKE_PATH to FALSE:
4720 • CMAKE_PREFIX_PATH
4722 • CMAKE_FRAMEWORK_PATH
4724 • CMAKE_APPBUNDLE_PATH
4726 3. Search paths specified in cmake-specific environment variables.
4728 These are intended to be set in the user's shell configuration, and
4729 therefore use the host's native path separator (; on Windows and :
4730 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
4731 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
4732 FALSE:
4733 • <PackageName>_DIR
4735 • CMAKE_PREFIX_PATH
4737 • CMAKE_FRAMEWORK_PATH
4739 • CMAKE_APPBUNDLE_PATH
4741 4. Search paths specified by the HINTS option. These should be paths
4743 computed by system introspection, such as a hint provided by the lo‐
4744 cation of another item already found. Hard-coded guesses should be
4745 specified with the PATHS option.
4746 5. Search the standard system environment variables. This can be
4748 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
4749 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE. Path entries ending
4750 in /bin or /sbin are automatically converted to their parent direc‐
4751 tories:
4752 • PATH
4754 6. Search paths stored in the CMake User Package Registry. This can be
4756 skipped if NO_CMAKE_PACKAGE_REGISTRY is passed or by setting the
4757 variable CMAKE_FIND_USE_PACKAGE_REGISTRY to FALSE or the deprecated
4758 variable CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY to TRUE.
4759 See the cmake-packages(7) manual for details on the user package
4761 registry.
4762 7. Search cmake variables defined in the Platform files for the current
4764 system. The searching of CMAKE_INSTALL_PREFIX and
4765 CMAKE_STAGING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is
4766 passed or by setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All
4767 these locations can be skipped if NO_CMAKE_SYSTEM_PATH is passed or
4768 by setting the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE:
4769 • CMAKE_SYSTEM_PREFIX_PATH
4771 • CMAKE_SYSTEM_FRAMEWORK_PATH
4773 • CMAKE_SYSTEM_APPBUNDLE_PATH
4775 The platform paths that these variables contain are locations that
4777 typically include installed software. An example being /usr/local
4778 for UNIX based platforms.
4779 8. Search paths stored in the CMake System Package Registry. This can
4781 be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed or by set‐
4782 ting the CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY variable to FALSE or
4783 the deprecated variable
4784 CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY to TRUE.
4785 See the cmake-packages(7) manual for details on the system package
4787 registry.
4788 9. Search paths specified by the PATHS option. These are typically
4790 hard-coded guesses.
4791 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
4793 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
4794 can also cause some of the above locations to be ignored.
4795 New in version 3.16: Added the CMAKE_FIND_USE_<CATEGORY> variables to
4797 globally disable various search locations.
4798 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
4801 ries to be prepended to all other search directories. This effectively
4802 "re-roots" the entire search under given locations. Paths which are
4803 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
4804 ing, because that variable is always a path on the host system. By de‐
4805 fault the CMAKE_FIND_ROOT_PATH is empty.
4806 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
4808 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
4809 fects. See the documentation for that variable for more.
4810 These variables are especially useful when cross-compiling to point to
4812 the root directory of the target environment and CMake will search
4813 there too. By default at first the directories listed in
4814 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
4815 searched, and then the non-rooted directories will be searched. The
4816 default behavior can be adjusted by setting
4817 CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually over‐
4818 ridden on a per-call basis using options:
4819 CMAKE_FIND_ROOT_PATH_BOTH
4821 Search in the order described above.
4822 NO_CMAKE_FIND_ROOT_PATH
4824 Do not use the CMAKE_FIND_ROOT_PATH variable.
4825 ONLY_CMAKE_FIND_ROOT_PATH
4827 Search only the re-rooted directories and directories below
4828 CMAKE_STAGING_PREFIX.
4829 The default search order is designed to be most-specific to least-spe‐
4831 cific for common use cases. Projects may override the order by simply
4832 calling the command multiple times and using the NO_* options:
4833 find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
4835 find_package (<PackageName>)
4836 Once one of the calls succeeds the result variable will be set and
4838 stored in the cache so that no call will search again.
4839 By default the value stored in the result variable will be the path at
4841 which the file is found. The CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS vari‐
4842 able may be set to TRUE before calling find_package in order to resolve
4843 symbolic links and store the real path to the file.
4844 Every non-REQUIRED find_package call can be disabled or made REQUIRED:
4846 • Setting the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to TRUE
4848 disables the package. This also disables redirection to a package
4849 provided by FetchContent.
4850 • Setting the CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> variable to TRUE
4852 makes the package REQUIRED.
4853 Setting both variables to TRUE simultaneously is an error.
4855 Config Mode Version Selection
4857 NOTE:
4858 When Config mode is used, this version selection process is applied
4859 regardless of whether the full or basic signature was given.
4860 When the [version] argument is given, Config mode will only find a ver‐
4862 sion of the package that claims compatibility with the requested ver‐
4863 sion (see format specification). If the EXACT option is given, only a
4864 version of the package claiming an exact match of the requested version
4865 may be found. CMake does not establish any convention for the meaning
4866 of version numbers. Package version numbers are checked by "version"
4867 files provided by the packages themselves or by FetchContent. For a
4868 candidate package configuration file <config-file>.cmake the corre‐
4869 sponding version file is located next to it and named either <con‐
4870 fig-file>-version.cmake or <config-file>Version.cmake. If no such ver‐
4871 sion file is available then the configuration file is assumed to not be
4872 compatible with any requested version. A basic version file containing
4873 generic version matching code can be created using the
4874 CMakePackageConfigHelpers module. When a version file is found it is
4875 loaded to check the requested version number. The version file is
4876 loaded in a nested scope in which the following variables have been de‐
4877 fined:
4878 PACKAGE_FIND_NAME
4880 The <PackageName>
4881 PACKAGE_FIND_VERSION
4883 Full requested version string
4884 PACKAGE_FIND_VERSION_MAJOR
4886 Major version if requested, else 0
4887 PACKAGE_FIND_VERSION_MINOR
4889 Minor version if requested, else 0
4890 PACKAGE_FIND_VERSION_PATCH
4892 Patch version if requested, else 0
4893 PACKAGE_FIND_VERSION_TWEAK
4895 Tweak version if requested, else 0
4896 PACKAGE_FIND_VERSION_COUNT
4898 Number of version components, 0 to 4
4899 When a version range is specified, the above version variables will
4901 hold values based on the lower end of the version range. This is to
4902 preserve compatibility with packages that have not been implemented to
4903 expect version ranges. In addition, the version range will be de‐
4904 scribed by the following variables:
4905 PACKAGE_FIND_VERSION_RANGE
4907 Full requested version range string
4908 PACKAGE_FIND_VERSION_RANGE_MIN
4910 This specifies whether the lower end point of the version range
4911 should be included or excluded. Currently, the only supported
4912 value for this variable is INCLUDE.
4913 PACKAGE_FIND_VERSION_RANGE_MAX
4915 This specifies whether the upper end point of the version range
4916 should be included or excluded. The supported values for this
4917 variable are INCLUDE and EXCLUDE.
4918 PACKAGE_FIND_VERSION_MIN
4920 Full requested version string of the lower end point of the
4921 range
4922 PACKAGE_FIND_VERSION_MIN_MAJOR
4924 Major version of the lower end point if requested, else 0
4925 PACKAGE_FIND_VERSION_MIN_MINOR
4927 Minor version of the lower end point if requested, else 0
4928 PACKAGE_FIND_VERSION_MIN_PATCH
4930 Patch version of the lower end point if requested, else 0
4931 PACKAGE_FIND_VERSION_MIN_TWEAK
4933 Tweak version of the lower end point if requested, else 0
4934 PACKAGE_FIND_VERSION_MIN_COUNT
4936 Number of version components of the lower end point, 0 to 4
4937 PACKAGE_FIND_VERSION_MAX
4939 Full requested version string of the upper end point of the
4940 range
4941 PACKAGE_FIND_VERSION_MAX_MAJOR
4943 Major version of the upper end point if requested, else 0
4944 PACKAGE_FIND_VERSION_MAX_MINOR
4946 Minor version of the upper end point if requested, else 0
4947 PACKAGE_FIND_VERSION_MAX_PATCH
4949 Patch version of the upper end point if requested, else 0
4950 PACKAGE_FIND_VERSION_MAX_TWEAK
4952 Tweak version of the upper end point if requested, else 0
4953 PACKAGE_FIND_VERSION_MAX_COUNT
4955 Number of version components of the upper end point, 0 to 4
4956 Regardless of whether a single version or a version range is specified,
4958 the variable PACKAGE_FIND_VERSION_COMPLETE will be defined and will
4959 hold the full requested version string as specified.
4960 The version file checks whether it satisfies the requested version and
4962 sets these variables:
4963 PACKAGE_VERSION
4965 Full provided version string
4966 PACKAGE_VERSION_EXACT
4968 True if version is exact match
4969 PACKAGE_VERSION_COMPATIBLE
4971 True if version is compatible
4972 PACKAGE_VERSION_UNSUITABLE
4974 True if unsuitable as any version
4975 These variables are checked by the find_package command to determine
4977 whether the configuration file provides an acceptable version. They
4978 are not available after the find_package call returns. If the version
4979 is acceptable the following variables are set:
4980 <PackageName>_VERSION
4982 Full provided version string
4983 <PackageName>_VERSION_MAJOR
4985 Major version if provided, else 0
4986 <PackageName>_VERSION_MINOR
4988 Minor version if provided, else 0
4989 <PackageName>_VERSION_PATCH
4991 Patch version if provided, else 0
4992 <PackageName>_VERSION_TWEAK
4994 Tweak version if provided, else 0
4995 <PackageName>_VERSION_COUNT
4997 Number of version components, 0 to 4
4998 and the corresponding package configuration file is loaded. When mul‐
5000 tiple package configuration files are available whose version files
5001 claim compatibility with the version requested it is unspecified which
5002 one is chosen: unless the variable CMAKE_FIND_PACKAGE_SORT_ORDER is set
5003 no attempt is made to choose a highest or closest version number.
5004 To control the order in which find_package checks for compatibility use
5006 the two variables CMAKE_FIND_PACKAGE_SORT_ORDER and
5007 CMAKE_FIND_PACKAGE_SORT_DIRECTION. For instance in order to select the
5008 highest version one can set
5009 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
5011 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
5012 before calling find_package.
5014 Package File Interface Variables
5016 When loading a find module or package configuration file find_package
5017 defines variables to provide information about the call arguments (and
5018 restores their original state before returning):
5019 CMAKE_FIND_PACKAGE_NAME
5021 The <PackageName> which is searched for
5022 <PackageName>_FIND_REQUIRED
5024 True if REQUIRED option was given
5025 <PackageName>_FIND_QUIETLY
5027 True if QUIET option was given
5028 <PackageName>_FIND_REGISTRY_VIEW
5030 The requested view if REGISTRY_VIEW option was given
5031 <PackageName>_FIND_VERSION
5033 Full requested version string
5034 <PackageName>_FIND_VERSION_MAJOR
5036 Major version if requested, else 0
5037 <PackageName>_FIND_VERSION_MINOR
5039 Minor version if requested, else 0
5040 <PackageName>_FIND_VERSION_PATCH
5042 Patch version if requested, else 0
5043 <PackageName>_FIND_VERSION_TWEAK
5045 Tweak version if requested, else 0
5046 <PackageName>_FIND_VERSION_COUNT
5048 Number of version components, 0 to 4
5049 <PackageName>_FIND_VERSION_EXACT
5051 True if EXACT option was given
5052 <PackageName>_FIND_COMPONENTS
5054 List of specified components (required and optional)
5055 <PackageName>_FIND_REQUIRED_<c>
5057 True if component <c> is required, false if component <c> is op‐
5058 tional
5059 When a version range is specified, the above version variables will
5061 hold values based on the lower end of the version range. This is to
5062 preserve compatibility with packages that have not been implemented to
5063 expect version ranges. In addition, the version range will be de‐
5064 scribed by the following variables:
5065 <PackageName>_FIND_VERSION_RANGE
5067 Full requested version range string
5068 <PackageName>_FIND_VERSION_RANGE_MIN
5070 This specifies whether the lower end point of the version range
5071 is included or excluded. Currently, INCLUDE is the only sup‐
5072 ported value.
5073 <PackageName>_FIND_VERSION_RANGE_MAX
5075 This specifies whether the upper end point of the version range
5076 is included or excluded. The possible values for this variable
5077 are INCLUDE or EXCLUDE.
5078 <PackageName>_FIND_VERSION_MIN
5080 Full requested version string of the lower end point of the
5081 range
5082 <PackageName>_FIND_VERSION_MIN_MAJOR
5084 Major version of the lower end point if requested, else 0
5085 <PackageName>_FIND_VERSION_MIN_MINOR
5087 Minor version of the lower end point if requested, else 0
5088 <PackageName>_FIND_VERSION_MIN_PATCH
5090 Patch version of the lower end point if requested, else 0
5091 <PackageName>_FIND_VERSION_MIN_TWEAK
5093 Tweak version of the lower end point if requested, else 0
5094 <PackageName>_FIND_VERSION_MIN_COUNT
5096 Number of version components of the lower end point, 0 to 4
5097 <PackageName>_FIND_VERSION_MAX
5099 Full requested version string of the upper end point of the
5100 range
5101 <PackageName>_FIND_VERSION_MAX_MAJOR
5103 Major version of the upper end point if requested, else 0
5104 <PackageName>_FIND_VERSION_MAX_MINOR
5106 Minor version of the upper end point if requested, else 0
5107 <PackageName>_FIND_VERSION_MAX_PATCH
5109 Patch version of the upper end point if requested, else 0
5110 <PackageName>_FIND_VERSION_MAX_TWEAK
5112 Tweak version of the upper end point if requested, else 0
5113 <PackageName>_FIND_VERSION_MAX_COUNT
5115 Number of version components of the upper end point, 0 to 4
5116 Regardless of whether a single version or a version range is specified,
5118 the variable <PackageName>_FIND_VERSION_COMPLETE will be defined and
5119 will hold the full requested version string as specified.
5120 In Module mode the loaded find module is responsible to honor the re‐
5122 quest detailed by these variables; see the find module for details. In
5123 Config mode find_package handles REQUIRED, QUIET, and [version] options
5124 automatically but leaves it to the package configuration file to handle
5125 components in a way that makes sense for the package. The package con‐
5126 figuration file may set <PackageName>_FOUND to false to tell find_pack‐
5127 age that component requirements are not satisfied.
5128 find_path
5130 A short-hand signature is:
5131 find_path (<VAR> name1 [path1 path2 ...])
5133 The general signature is:
5135 find_path (
5137 <VAR>
5138 name | NAMES name1 [name2 ...]
5139 [HINTS [path | ENV var]... ]
5140 [PATHS [path | ENV var]... ]
5141 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
5142 [PATH_SUFFIXES suffix1 [suffix2 ...]]
5143 [VALIDATOR function]
5144 [DOC "cache documentation string"]
5145 [NO_CACHE]
5146 [REQUIRED]
5147 [NO_DEFAULT_PATH]
5148 [NO_PACKAGE_ROOT_PATH]
5149 [NO_CMAKE_PATH]
5150 [NO_CMAKE_ENVIRONMENT_PATH]
5151 [NO_SYSTEM_ENVIRONMENT_PATH]
5152 [NO_CMAKE_SYSTEM_PATH]
5153 [NO_CMAKE_INSTALL_PREFIX]
5154 [CMAKE_FIND_ROOT_PATH_BOTH |
5155 ONLY_CMAKE_FIND_ROOT_PATH |
5156 NO_CMAKE_FIND_ROOT_PATH]
5157 )
5158 This command is used to find a directory containing the named file. A
5160 cache entry, or a normal variable if NO_CACHE is specified, named by
5161 <VAR> is created to store the result of this command. If the file in a
5162 directory is found the result is stored in the variable and the search
5163 will not be repeated unless the variable is cleared. If nothing is
5164 found, the result will be <VAR>-NOTFOUND.
5165 Options include:
5167 NAMES Specify one or more possible names for the file in a directory.
5169 When using this to specify names with and without a version suf‐
5171 fix, we recommend specifying the unversioned name first so that
5172 locally-built packages can be found before those provided by
5173 distributions.
5174 HINTS, PATHS
5176 Specify directories to search in addition to the default loca‐
5177 tions. The ENV var sub-option reads paths from a system envi‐
5178 ronment variable.
5179 Changed in version 3.24: On Windows platform, it is possible to
5181 include registry queries as part of the directories, using a
5182 dedicated syntax. Such specifications will be ignored on all
5183 other platforms.
5184 REGISTRY_VIEW
5187 New in version 3.24.
5188 Specify which registry views must be queried. This option is
5191 only meaningful on Windows platforms and will be ignored on
5192 other ones. When not specified, the TARGET view is used when the
5193 CMP0134 policy is NEW. Refer to CMP0134 for the default view
5194 when the policy is OLD.
5195 64 Query the 64-bit registry. On 32-bit Windows, it always
5197 returns the string /REGISTRY-NOTFOUND.
5198 32 Query the 32-bit registry.
5200 64_32 Query both views (64 and 32) and generate a path for
5202 each.
5203 32_64 Query both views (32 and 64) and generate a path for
5205 each.
5206 HOST Query the registry matching the architecture of the host:
5208 64 on 64-bit Windows and 32 on 32-bit Windows.
5209 TARGET Query the registry matching the architecture specified by
5211 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
5212 back to HOST view.
5213 BOTH Query both views (32 and 64). The order depends on the
5215 following rules: If the CMAKE_SIZEOF_VOID_P variable is
5216 defined, use the following view depending on the content
5217 of this variable:
5218 • 8: 64_32
5220 • 4: 32_64
5222 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
5224 on the architecture of the host:
5225 • 64-bit: 64_32
5227 • 32-bit: 32
5229 PATH_SUFFIXES
5231 Specify additional subdirectories to check below each directory
5232 location otherwise considered.
5233 VALIDATOR
5235 New in version 3.25.
5236 Specify a function() to be called for each candidate item found
5239 (a macro() cannot be provided, that will result in an error).
5240 Two arguments will be passed to the validator function: the name
5241 of a result variable, and the absolute path to the candidate
5242 item. The item will be accepted and the search will end unless
5243 the function sets the value in the result variable to false in
5244 the calling scope. The result variable will hold a true value
5245 when the validator function is entered.
5246 function(my_check validator_result_var item)
5248 if(NOT item MATCHES ...)
5249 set(${validator_result_var} FALSE PARENT_SCOPE)
5250 endif()
5251 endfunction()
5252 find_path (result NAMES ... VALIDATOR my_check)
5254 Note that if a cached result is used, the search is skipped and
5256 any VALIDATOR is ignored. The cached result is not required to
5257 pass the validation function.
5258 DOC Specify the documentation string for the <VAR> cache entry.
5260 NO_CACHE
5262 New in version 3.21.
5263 The result of the search will be stored in a normal variable
5266 rather than a cache entry.
5267 NOTE:
5269 If the variable is already set before the call (as a normal
5270 or cache variable) then the search will not occur.
5271 WARNING:
5273 This option should be used with caution because it can
5274 greatly increase the cost of repeated configure steps.
5275 REQUIRED
5277 New in version 3.18.
5278 Stop processing with an error message if nothing is found, oth‐
5281 erwise the search will be attempted again the next time
5282 find_path is invoked with the same variable.
5283 If NO_DEFAULT_PATH is specified, then no additional paths are added to
5285 the search. If NO_DEFAULT_PATH is not specified, the search process is
5286 as follows:
5287 1. If called from within a find module or any other script loaded by a
5289 call to find_package(<PackageName>), search prefixes unique to the
5290 current package being found. See policy CMP0074.
5291 New in version 3.12.
5293 Specifically, search paths specified by the following variables, in
5296 order:
5297 a. <PackageName>_ROOT CMake variable, where <PackageName> is the
5299 case-preserved package name.
5300 b. <PACKAGENAME>_ROOT CMake variable, where <PACKAGENAME> is the up‐
5302 per-cased package name. See policy CMP0144.
5303 New in version 3.27.
5305 c. <PackageName>_ROOT environment variable, where <PackageName> is
5308 the case-preserved package name.
5309 d. <PACKAGENAME>_ROOT environment variable, where <PACKAGENAME> is
5311 the upper-cased package name. See policy CMP0144.
5312 New in version 3.27.
5314 The package root variables are maintained as a stack, so if called
5317 from nested find modules or config packages, root paths from the
5318 parent's find module or config package will be searched after paths
5319 from the current module or package. In other words, the search or‐
5320 der would be <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT},
5321 <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc. This can be
5322 skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
5323 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.
5324 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5326 <prefix>/include for each <prefix> in the <PackageName>_ROOT CMake
5327 variable and the <PackageName>_ROOT environment variable if called
5328 from within a find module loaded by find_package(<PackageName>)
5329 2. Search paths specified in cmake-specific cache variables. These are
5331 intended to be used on the command line with a -DVAR=value. The
5332 values are interpreted as semicolon-separated lists. This can be
5333 skipped if NO_CMAKE_PATH is passed or by setting the
5334 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
5335 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5337 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
5338 • CMAKE_INCLUDE_PATH
5340 • CMAKE_FRAMEWORK_PATH
5342 3. Search paths specified in cmake-specific environment variables.
5344 These are intended to be set in the user's shell configuration, and
5345 therefore use the host's native path separator (; on Windows and :
5346 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
5347 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
5348 FALSE.
5349 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5351 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
5352 • CMAKE_INCLUDE_PATH
5354 • CMAKE_FRAMEWORK_PATH
5356 4. Search the paths specified by the HINTS option. These should be
5358 paths computed by system introspection, such as a hint provided by
5359 the location of another item already found. Hard-coded guesses
5360 should be specified with the PATHS option.
5361 5. Search the standard system environment variables. This can be
5363 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
5364 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
5365 • The directories in INCLUDE and PATH.
5367 • On Windows hosts: <prefix>/include/<arch> if
5369 CMAKE_LIBRARY_ARCHITECTURE is set, and <prefix>/include for each
5370 <prefix>/[s]bin in PATH, and <entry>/include for other entries in
5371 PATH.
5372 6. Search cmake variables defined in the Platform files for the current
5374 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
5375 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
5376 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
5377 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
5378 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
5379 • <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
5381 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
5382 • CMAKE_SYSTEM_INCLUDE_PATH
5384 • CMAKE_SYSTEM_FRAMEWORK_PATH
5386 The platform paths that these variables contain are locations that
5388 typically include installed software. An example being /usr/local
5389 for UNIX based platforms.
5390 7. Search the paths specified by the PATHS option or in the short-hand
5392 version of the command. These are typically hard-coded guesses.
5393 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
5395 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
5396 can also cause some of the above locations to be ignored.
5397 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
5399 globally disable various search locations.
5400 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
5403 determine the order of preference between Apple-style and unix-style
5404 package components.
5405 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
5407 ries to be prepended to all other search directories. This effectively
5408 "re-roots" the entire search under given locations. Paths which are
5409 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
5410 ing, because that variable is always a path on the host system. By de‐
5411 fault the CMAKE_FIND_ROOT_PATH is empty.
5412 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
5414 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
5415 fects. See the documentation for that variable for more.
5416 These variables are especially useful when cross-compiling to point to
5418 the root directory of the target environment and CMake will search
5419 there too. By default at first the directories listed in
5420 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
5421 searched, and then the non-rooted directories will be searched. The
5422 default behavior can be adjusted by setting
5423 CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. This behavior can be manually over‐
5424 ridden on a per-call basis using options:
5425 CMAKE_FIND_ROOT_PATH_BOTH
5427 Search in the order described above.
5428 NO_CMAKE_FIND_ROOT_PATH
5430 Do not use the CMAKE_FIND_ROOT_PATH variable.
5431 ONLY_CMAKE_FIND_ROOT_PATH
5433 Search only the re-rooted directories and directories below
5434 CMAKE_STAGING_PREFIX.
5435 The default search order is designed to be most-specific to least-spe‐
5437 cific for common use cases. Projects may override the order by simply
5438 calling the command multiple times and using the NO_* options:
5439 find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
5441 find_path (<VAR> NAMES name)
5442 Once one of the calls succeeds the result variable will be set and
5444 stored in the cache so that no call will search again.
5445 When searching for frameworks, if the file is specified as A/b.h, then
5447 the framework search will look for A.framework/Headers/b.h. If that is
5448 found the path will be set to the path to the framework. CMake will
5449 convert this to the correct -F option to include the file.
5450 find_program
5452 A short-hand signature is:
5453 find_program (<VAR> name1 [path1 path2 ...])
5455 The general signature is:
5457 find_program (
5459 <VAR>
5460 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
5461 [HINTS [path | ENV var]... ]
5462 [PATHS [path | ENV var]... ]
5463 [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
5464 [PATH_SUFFIXES suffix1 [suffix2 ...]]
5465 [VALIDATOR function]
5466 [DOC "cache documentation string"]
5467 [NO_CACHE]
5468 [REQUIRED]
5469 [NO_DEFAULT_PATH]
5470 [NO_PACKAGE_ROOT_PATH]
5471 [NO_CMAKE_PATH]
5472 [NO_CMAKE_ENVIRONMENT_PATH]
5473 [NO_SYSTEM_ENVIRONMENT_PATH]
5474 [NO_CMAKE_SYSTEM_PATH]
5475 [NO_CMAKE_INSTALL_PREFIX]
5476 [CMAKE_FIND_ROOT_PATH_BOTH |
5477 ONLY_CMAKE_FIND_ROOT_PATH |
5478 NO_CMAKE_FIND_ROOT_PATH]
5479 )
5480 This command is used to find a program. A cache entry, or a normal
5482 variable if NO_CACHE is specified, named by <VAR> is created to store
5483 the result of this command. If the program is found the result is
5484 stored in the variable and the search will not be repeated unless the
5485 variable is cleared. If nothing is found, the result will be
5486 <VAR>-NOTFOUND.
5487 Options include:
5489 NAMES Specify one or more possible names for the program.
5491 When using this to specify names with and without a version suf‐
5493 fix, we recommend specifying the unversioned name first so that
5494 locally-built packages can be found before those provided by
5495 distributions.
5496 HINTS, PATHS
5498 Specify directories to search in addition to the default loca‐
5499 tions. The ENV var sub-option reads paths from a system envi‐
5500 ronment variable.
5501 Changed in version 3.24: On Windows platform, it is possible to
5503 include registry queries as part of the directories, using a
5504 dedicated syntax. Such specifications will be ignored on all
5505 other platforms.
5506 REGISTRY_VIEW
5509 New in version 3.24.
5510 Specify which registry views must be queried. This option is
5513 only meaningful on Windows platforms and will be ignored on
5514 other ones. When not specified, the BOTH view is used when the
5515 CMP0134 policy is NEW. Refer to CMP0134 for the default view
5516 when the policy is OLD.
5517 64 Query the 64-bit registry. On 32-bit Windows, it always
5519 returns the string /REGISTRY-NOTFOUND.
5520 32 Query the 32-bit registry.
5522 64_32 Query both views (64 and 32) and generate a path for
5524 each.
5525 32_64 Query both views (32 and 64) and generate a path for
5527 each.
5528 HOST Query the registry matching the architecture of the host:
5530 64 on 64-bit Windows and 32 on 32-bit Windows.
5531 TARGET Query the registry matching the architecture specified by
5533 the CMAKE_SIZEOF_VOID_P variable. If not defined, fall
5534 back to HOST view.
5535 BOTH Query both views (32 and 64). The order depends on the
5537 following rules: If the CMAKE_SIZEOF_VOID_P variable is
5538 defined, use the following view depending on the content
5539 of this variable:
5540 • 8: 64_32
5542 • 4: 32_64
5544 If the CMAKE_SIZEOF_VOID_P variable is not defined, rely
5546 on the architecture of the host:
5547 • 64-bit: 64_32
5549 • 32-bit: 32
5551 PATH_SUFFIXES
5553 Specify additional subdirectories to check below each directory
5554 location otherwise considered.
5555 VALIDATOR
5557 New in version 3.25.
5558 Specify a function() to be called for each candidate item found
5561 (a macro() cannot be provided, that will result in an error).
5562 Two arguments will be passed to the validator function: the name
5563 of a result variable, and the absolute path to the candidate
5564 item. The item will be accepted and the search will end unless
5565 the function sets the value in the result variable to false in
5566 the calling scope. The result variable will hold a true value
5567 when the validator function is entered.
5568 function(my_check validator_result_var item)
5570 if(NOT item MATCHES ...)
5571 set(${validator_result_var} FALSE PARENT_SCOPE)
5572 endif()
5573 endfunction()
5574 find_program (result NAMES ... VALIDATOR my_check)
5576 Note that if a cached result is used, the search is skipped and
5578 any VALIDATOR is ignored. The cached result is not required to
5579 pass the validation function.
5580 DOC Specify the documentation string for the <VAR> cache entry.
5582 NO_CACHE
5584 New in version 3.21.
5585 The result of the search will be stored in a normal variable
5588 rather than a cache entry.
5589 NOTE:
5591 If the variable is already set before the call (as a normal
5592 or cache variable) then the search will not occur.
5593 WARNING:
5595 This option should be used with caution because it can
5596 greatly increase the cost of repeated configure steps.
5597 REQUIRED
5599 New in version 3.18.
5600 Stop processing with an error message if nothing is found, oth‐
5603 erwise the search will be attempted again the next time
5604 find_program is invoked with the same variable.
5605 If NO_DEFAULT_PATH is specified, then no additional paths are added to
5607 the search. If NO_DEFAULT_PATH is not specified, the search process is
5608 as follows:
5609 1. If called from within a find module or any other script loaded by a
5611 call to find_package(<PackageName>), search prefixes unique to the
5612 current package being found. See policy CMP0074.
5613 New in version 3.12.
5615 Specifically, search paths specified by the following variables, in
5618 order:
5619 a. <PackageName>_ROOT CMake variable, where <PackageName> is the
5621 case-preserved package name.
5622 b. <PACKAGENAME>_ROOT CMake variable, where <PACKAGENAME> is the up‐
5624 per-cased package name. See policy CMP0144.
5625 New in version 3.27.
5627 c. <PackageName>_ROOT environment variable, where <PackageName> is
5630 the case-preserved package name.
5631 d. <PACKAGENAME>_ROOT environment variable, where <PACKAGENAME> is
5633 the upper-cased package name. See policy CMP0144.
5634 New in version 3.27.
5636 The package root variables are maintained as a stack, so if called
5639 from nested find modules or config packages, root paths from the
5640 parent's find module or config package will be searched after paths
5641 from the current module or package. In other words, the search or‐
5642 der would be <CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT},
5643 <ParentPackage>_ROOT, ENV{<ParentPackage>_ROOT}, etc. This can be
5644 skipped if NO_PACKAGE_ROOT_PATH is passed or by setting the
5645 CMAKE_FIND_USE_PACKAGE_ROOT_PATH to FALSE.
5646 • <prefix>/[s]bin for each <prefix> in the <PackageName>_ROOT CMake
5648 variable and the <PackageName>_ROOT environment variable if called
5649 from within a find module loaded by find_package(<PackageName>)
5650 2. Search paths specified in cmake-specific cache variables. These are
5652 intended to be used on the command line with a -DVAR=value. The
5653 values are interpreted as semicolon-separated lists. This can be
5654 skipped if NO_CMAKE_PATH is passed or by setting the
5655 CMAKE_FIND_USE_CMAKE_PATH to FALSE.
5656 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
5658 • CMAKE_PROGRAM_PATH
5660 • CMAKE_APPBUNDLE_PATH
5662 3. Search paths specified in cmake-specific environment variables.
5664 These are intended to be set in the user's shell configuration, and
5665 therefore use the host's native path separator (; on Windows and :
5666 on UNIX). This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
5667 passed or by setting the CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH to
5668 FALSE.
5669 • <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
5671 • CMAKE_PROGRAM_PATH
5673 • CMAKE_APPBUNDLE_PATH
5675 4. Search the paths specified by the HINTS option. These should be
5677 paths computed by system introspection, such as a hint provided by
5678 the location of another item already found. Hard-coded guesses
5679 should be specified with the PATHS option.
5680 5. Search the standard system environment variables. This can be
5682 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed or by setting the
5683 CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH to FALSE.
5684 • The directories in PATH itself.
5686 • On Windows hosts no extra search paths are included
5688 6. Search cmake variables defined in the Platform files for the current
5690 system. The searching of CMAKE_INSTALL_PREFIX and CMAKE_STAG‐
5691 ING_PREFIX can be skipped if NO_CMAKE_INSTALL_PREFIX is passed or by
5692 setting the CMAKE_FIND_USE_INSTALL_PREFIX to FALSE. All these loca‐
5693 tions can be skipped if NO_CMAKE_SYSTEM_PATH is passed or by setting
5694 the CMAKE_FIND_USE_CMAKE_SYSTEM_PATH to FALSE.
5695 • <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
5697 • CMAKE_SYSTEM_PROGRAM_PATH
5699 • CMAKE_SYSTEM_APPBUNDLE_PATH
5701 The platform paths that these variables contain are locations that
5703 typically include installed software. An example being /usr/local
5704 for UNIX based platforms.
5705 7. Search the paths specified by the PATHS option or in the short-hand
5707 version of the command. These are typically hard-coded guesses.
5708 The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
5710 CMAKE_SYSTEM_IGNORE_PATH and CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables
5711 can also cause some of the above locations to be ignored.
5712 New in version 3.16: Added CMAKE_FIND_USE_<CATEGORY>_PATH variables to
5714 globally disable various search locations.
5715 On macOS the CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE variables
5718 determine the order of preference between Apple-style and unix-style
5719 package components.
5720 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more directo‐
5722 ries to be prepended to all other search directories. This effectively
5723 "re-roots" the entire search under given locations. Paths which are
5724 descendants of the CMAKE_STAGING_PREFIX are excluded from this re-root‐
5725 ing, because that variable is always a path on the host system. By de‐
5726 fault the CMAKE_FIND_ROOT_PATH is empty.
5727 The CMAKE_SYSROOT variable can also be used to specify exactly one di‐
5729 rectory to use as a prefix. Setting CMAKE_SYSROOT also has other ef‐
5730 fects. See the documentation for that variable for more.
5731 These variables are especially useful when cross-compiling to point to
5733 the root directory of the target environment and CMake will search
5734 there too. By default at first the directories listed in
5735 CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT directory is
5736 searched, and then the non-rooted directories will be searched. The
5737 default behavior can be adjusted by setting
5738 CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. This behavior can be manually over‐
5739 ridden on a per-call basis using options:
5740 CMAKE_FIND_ROOT_PATH_BOTH
5742 Search in the order described above.
5743 NO_CMAKE_FIND_ROOT_PATH
5745 Do not use the CMAKE_FIND_ROOT_PATH variable.
5746 ONLY_CMAKE_FIND_ROOT_PATH
5748 Search only the re-rooted directories and directories below
5749 CMAKE_STAGING_PREFIX.
5750 The default search order is designed to be most-specific to least-spe‐
5752 cific for common use cases. Projects may override the order by simply
5753 calling the command multiple times and using the NO_* options:
5754 find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
5756 find_program (<VAR> NAMES name)
5757 Once one of the calls succeeds the result variable will be set and
5759 stored in the cache so that no call will search again.
5760 When more than one value is given to the NAMES option this command by
5762 default will consider one name at a time and search every directory for
5763 it. The NAMES_PER_DIR option tells this command to consider one direc‐
5764 tory at a time and search for all names in it.
5765 foreach
5767 Evaluate a group of commands for each value in a list.
5768 foreach(<loop_var> <items>)
5770 <commands>
5771 endforeach()
5772 where <items> is a list of items that are separated by semicolon or
5774 whitespace. All commands between foreach and the matching endforeach
5775 are recorded without being invoked. Once the endforeach is evaluated,
5776 the recorded list of commands is invoked once for each item in <items>.
5777 At the beginning of each iteration the variable <loop_var> will be set
5778 to the value of the current item.
5779 The scope of <loop_var> is restricted to the loop scope. See policy
5781 CMP0124 for details.
5782 The commands break() and continue() provide means to escape from the
5784 normal control flow.
5785 Per legacy, the endforeach() command admits an optional <loop_var> ar‐
5787 gument. If used, it must be a verbatim repeat of the argument of the
5788 opening foreach command.
5789 foreach(<loop_var> RANGE <stop>)
5791 In this variant, foreach iterates over the numbers 0, 1, ... up to (and
5793 including) the nonnegative integer <stop>.
5794 foreach(<loop_var> RANGE <start> <stop> [<step>])
5796 In this variant, foreach iterates over the numbers from <start> up to
5798 at most <stop> in steps of <step>. If <step> is not specified, then
5799 the step size is 1. The three arguments <start> <stop> <step> must all
5800 be nonnegative integers, and <stop> must not be smaller than <start>;
5801 otherwise you enter the danger zone of undocumented behavior that may
5802 change in future releases.
5803 foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])
5805 In this variant, <lists> is a whitespace or semicolon separated list of
5807 list-valued variables. The foreach command iterates over each item in
5808 each given list. The <items> following the ITEMS keyword are processed
5809 as in the first variant of the foreach command. The forms LISTS A and
5810 ITEMS ${A} are equivalent.
5811 The following example shows how the LISTS option is processed:
5813 set(A 0;1)
5815 set(B 2 3)
5816 set(C "4 5")
5817 set(D 6;7 8)
5818 set(E "")
5819 foreach(X IN LISTS A B C D E)
5820 message(STATUS "X=${X}")
5821 endforeach()
5822 yields:
5824 -- X=0
5826 -- X=1
5827 -- X=2
5828 -- X=3
5829 -- X=4 5
5830 -- X=6
5831 -- X=7
5832 -- X=8
5833 foreach(<loop_var>... IN ZIP_LISTS <lists>)
5835 New in version 3.17.
5837 In this variant, <lists> is a whitespace or semicolon separated list of
5840 list-valued variables. The foreach command iterates over each list si‐
5841 multaneously setting the iteration variables as follows:
5842 • if the only loop_var given, then it sets a series of loop_var_N vari‐
5844 ables to the current item from the corresponding list;
5845 • if multiple variable names passed, their count should match the lists
5847 variables count;
5848 • if any of the lists are shorter, the corresponding iteration variable
5850 is not defined for the current iteration.
5851 list(APPEND English one two three four)
5853 list(APPEND Bahasa satu dua tiga)
5854 foreach(num IN ZIP_LISTS English Bahasa)
5856 message(STATUS "num_0=${num_0}, num_1=${num_1}")
5857 endforeach()
5858 foreach(en ba IN ZIP_LISTS English Bahasa)
5860 message(STATUS "en=${en}, ba=${ba}")
5861 endforeach()
5862 yields:
5864 -- num_0=one, num_1=satu
5866 -- num_0=two, num_1=dua
5867 -- num_0=three, num_1=tiga
5868 -- num_0=four, num_1=
5869 -- en=one, ba=satu
5870 -- en=two, ba=dua
5871 -- en=three, ba=tiga
5872 -- en=four, ba=
5873 See Also
5875 • break()
5876 • continue()
5878 • endforeach()
5880 • while()
5882 function
5884 Start recording a function for later invocation as a command.
5885 function(<name> [<arg1> ...])
5887 <commands>
5888 endfunction()
5889 Defines a function named <name> that takes arguments named <arg1>, ...
5891 The <commands> in the function definition are recorded; they are not
5892 executed until the function is invoked.
5893 Per legacy, the endfunction() command admits an optional <name> argu‐
5895 ment. If used, it must be a verbatim repeat of the argument of the
5896 opening function command.
5897 A function opens a new scope: see set(var PARENT_SCOPE) for details.
5899 See the cmake_policy() command documentation for the behavior of poli‐
5901 cies inside functions.
5902 See the macro() command documentation for differences between CMake
5904 functions and macros.
5905 Invocation
5907 The function invocation is case-insensitive. A function defined as
5908 function(foo)
5910 <commands>
5911 endfunction()
5912 can be invoked through any of
5914 foo()
5916 Foo()
5917 FOO()
5918 cmake_language(CALL foo)
5919 and so on. However, it is strongly recommended to stay with the case
5921 chosen in the function definition. Typically functions use all-lower‐
5922 case names.
5923 New in version 3.18: The cmake_language(CALL ...) command can also be
5925 used to invoke the function.
5926 Arguments
5929 When the function is invoked, the recorded <commands> are first modi‐
5930 fied by replacing formal parameters (${arg1}, ...) with the arguments
5931 passed, and then invoked as normal commands.
5932 In addition to referencing the formal parameters you can reference the
5934 ARGC variable which will be set to the number of arguments passed into
5935 the function as well as ARGV0, ARGV1, ARGV2, ... which will have the
5936 actual values of the arguments passed in. This facilitates creating
5937 functions with optional arguments.
5938 Furthermore, ARGV holds the list of all arguments given to the function
5940 and ARGN holds the list of arguments past the last expected argument.
5941 Referencing to ARGV# arguments beyond ARGC have undefined behavior.
5942 Checking that ARGC is greater than # is the only way to ensure that
5943 ARGV# was passed to the function as an extra argument.
5944 See Also
5946 • cmake_parse_arguments()
5947 • endfunction()
5949 • return()
5951 get_cmake_property
5953 Get a global property of the CMake instance.
5954 get_cmake_property(<var> <property>)
5956 Gets a global property from the CMake instance. The value of the
5958 <property> is stored in the variable <var>. If the property is not
5959 found, <var> will be set to NOTFOUND. See the cmake-properties(7) man‐
5960 ual for available properties.
5961 In addition to global properties, this command (for historical reasons)
5963 also supports the VARIABLES and MACROS directory properties. It also
5964 supports a special COMPONENTS global property that lists the components
5965 given to the install() command.
5966 See Also
5968 • the get_property() command GLOBAL option
5969 get_directory_property
5971 Get a property of DIRECTORY scope.
5972 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
5974 Stores a property of directory scope in the named <variable>.
5976 The DIRECTORY argument specifies another directory from which to re‐
5978 trieve the property value instead of the current directory. Relative
5979 paths are treated as relative to the current source directory. CMake
5980 must already know about the directory, either by having added it
5981 through a call to add_subdirectory() or being the top level directory.
5982 New in version 3.19: <dir> may reference a binary directory.
5984 If the property is not defined for the nominated directory scope, an
5987 empty string is returned. In the case of INHERITED properties, if the
5988 property is not found for the nominated directory scope, the search
5989 will chain to a parent scope as described for the define_property()
5990 command.
5991 get_directory_property(<variable> [DIRECTORY <dir>]
5993 DEFINITION <var-name>)
5994 Get a variable definition from a directory. This form is useful to get
5996 a variable definition from another directory.
5997 See Also
5999 • define_property()
6000 • the more general get_property() command
6002 get_filename_component
6004 Get a specific component of a full filename.
6005 Changed in version 3.20: This command has been superseded by the
6007 cmake_path() command, except for REALPATH, which is now offered by
6008 file(REAL_PATH), and PROGRAM, now available in
6009 separate_arguments(PROGRAM).
6010 Changed in version 3.24: The undocumented feature offering the capabil‐
6013 ity to query the Windows registry is superseded by
6014 cmake_host_system_information(QUERY WINDOWS_REGISTRY) command.
6015 get_filename_component(<var> <FileName> <mode> [CACHE])
6018 Sets <var> to a component of <FileName>, where <mode> is one of:
6020 DIRECTORY = Directory without file name
6022 NAME = File name without directory
6023 EXT = File name longest extension (.b.c from d/a.b.c)
6024 NAME_WE = File name with neither the directory nor the longest extension
6025 LAST_EXT = File name last extension (.c from d/a.b.c)
6026 NAME_WLE = File name with neither the directory nor the last extension
6027 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
6028 New in version 3.14: Added the LAST_EXT and NAME_WLE modes.
6030 Paths are returned with forward slashes and have no trailing slashes.
6033 If the optional CACHE argument is specified, the result variable is
6034 added to the cache.
6035 get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])
6037 New in version 3.4.
6039 Sets <var> to the absolute path of <FileName>, where <mode> is one of:
6042 ABSOLUTE = Full path to file
6044 REALPATH = Full path to existing file with symlinks resolved
6045 If the provided <FileName> is a relative path, it is evaluated relative
6047 to the given base directory <dir>. If no base directory is provided,
6048 the default base directory will be CMAKE_CURRENT_SOURCE_DIR.
6049 Paths are returned with forward slashes and have no trailing slashes.
6051 If the optional CACHE argument is specified, the result variable is
6052 added to the cache.
6053 get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])
6055 The program in <FileName> will be found in the system search path or
6057 left as a full path. If PROGRAM_ARGS is present with PROGRAM, then any
6058 command-line arguments present in the <FileName> string are split from
6059 the program name and stored in <arg_var>. This is used to separate a
6060 program name from its arguments in a command line string.
6061 See Also
6063 • cmake_path()
6064 get_property
6066 Get a property.
6067 get_property(<variable>
6069 <GLOBAL |
6070 DIRECTORY [<dir>] |
6071 TARGET <target> |
6072 SOURCE <source>
6073 [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
6074 INSTALL <file> |
6075 TEST <test> |
6076 CACHE <entry> |
6077 VARIABLE >
6078 PROPERTY <name>
6079 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
6080 Gets one property from one object in a scope.
6082 The first argument specifies the variable in which to store the result.
6084 The second argument determines the scope from which to get the prop‐
6085 erty. It must be one of the following:
6086 GLOBAL Scope is unique and does not accept a name.
6088 DIRECTORY
6090 Scope defaults to the current directory but another directory
6091 (already processed by CMake) may be named by the full or rela‐
6092 tive path <dir>. Relative paths are treated as relative to the
6093 current source directory. See also the get_directory_property()
6094 command.
6095 New in version 3.19: <dir> may reference a binary directory.
6097 TARGET Scope must name one existing target. See also the
6100 get_target_property() command.
6101 SOURCE Scope must name one source file. By default, the source file's
6103 property will be read from the current source directory's scope.
6104 New in version 3.18: Directory scope can be overridden with one
6106 of the following sub-options:
6107 DIRECTORY <dir>
6109 The source file property will be read from the <dir> di‐
6110 rectory's scope. CMake must already know about the di‐
6111 rectory, either by having added it through a call to
6112 add_subdirectory() or <dir> being the top level direc‐
6113 tory. Relative paths are treated as relative to the cur‐
6114 rent source directory.
6115 New in version 3.19: <dir> may reference a binary direc‐
6117 tory.
6118 TARGET_DIRECTORY <target>
6121 The source file property will be read from the directory
6122 scope in which <target> was created (<target> must there‐
6123 fore already exist).
6124 See also the get_source_file_property() command.
6127 INSTALL
6129 New in version 3.1.
6130 Scope must name one installed file path.
6133 TEST Scope must name one existing test. See also the
6135 get_test_property() command.
6136 CACHE Scope must name one cache entry.
6138 VARIABLE
6140 Scope is unique and does not accept a name.
6141 The required PROPERTY option is immediately followed by the name of the
6143 property to get. If the property is not set an empty value is re‐
6144 turned, although some properties support inheriting from a parent scope
6145 if defined to behave that way (see define_property()).
6146 If the SET option is given the variable is set to a boolean value indi‐
6148 cating whether the property has been set. If the DEFINED option is
6149 given the variable is set to a boolean value indicating whether the
6150 property has been defined such as with the define_property() command.
6151 If BRIEF_DOCS or FULL_DOCS is given then the variable is set to a
6153 string containing documentation for the requested property. If docu‐
6154 mentation is requested for a property that has not been defined NOT‐
6155 FOUND is returned.
6156 NOTE:
6158 The GENERATED source file property may be globally visible. See its
6159 documentation for details.
6160 See Also
6162 • define_property()
6163 • set_property()
6165 if
6167 Conditionally execute a group of commands.
6168 Synopsis
6170 if(<condition>)
6171 <commands>
6172 elseif(<condition>) # optional block, can be repeated
6173 <commands>
6174 else() # optional block
6175 <commands>
6176 endif()
6177 Evaluates the condition argument of the if clause according to the
6179 Condition syntax described below. If the result is true, then the com‐
6180 mands in the if block are executed. Otherwise, optional elseif blocks
6181 are processed in the same way. Finally, if no condition is true, com‐
6182 mands in the optional else block are executed.
6183 Per legacy, the else() and endif() commands admit an optional <condi‐
6185 tion> argument. If used, it must be a verbatim repeat of the argument
6186 of the opening if command.
6187 Condition Syntax
6189 The following syntax applies to the condition argument of the if, el‐
6190 seif and while() clauses.
6191 Compound conditions are evaluated in the following order of precedence:
6193 1. Parentheses.
6195 2. Unary tests such as EXISTS, COMMAND, and DEFINED.
6197 3. Binary tests such as EQUAL, LESS, LESS_EQUAL, GREATER,
6199 GREATER_EQUAL, STREQUAL, STRLESS, STRLESS_EQUAL, STRGREATER,
6200 STRGREATER_EQUAL, VERSION_EQUAL, VERSION_LESS, VERSION_LESS_EQUAL,
6201 VERSION_GREATER, VERSION_GREATER_EQUAL, PATH_EQUAL, and MATCHES.
6202 4. Unary logical operator NOT.
6204 5. Binary logical operators AND and OR, from left to right, without any
6206 short-circuit.
6207 Basic Expressions
6209 if(<constant>)
6210 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
6211 ber (including floating point numbers). False if the constant
6212 is 0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, the empty string, or
6213 ends in the suffix -NOTFOUND. Named boolean constants are
6214 case-insensitive. If the argument is not one of these specific
6215 constants, it is treated as a variable or string (see Variable
6216 Expansion further below) and one of the following two forms ap‐
6217 plies.
6218 if(<variable>)
6220 True if given a variable that is defined to a value that is not
6221 a false constant. False otherwise, including if the variable is
6222 undefined. Note that macro arguments are not variables.
6223 Environment Variables also cannot be tested this way, e.g.
6224 if(ENV{some_var}) will always evaluate to false.
6225 if(<string>)
6227 A quoted string always evaluates to false unless:
6228 • The string's value is one of the true constants, or
6230 • Policy CMP0054 is not set to NEW and the string's value hap‐
6232 pens to be a variable name that is affected by CMP0054's be‐
6233 havior.
6234 Logic Operators
6236 if(NOT <condition>)
6237 True if the condition is not true.
6238 if(<cond1> AND <cond2>)
6240 True if both conditions would be considered true individually.
6241 if(<cond1> OR <cond2>)
6243 True if either condition would be considered true individually.
6244 if((condition) AND (condition OR (condition)))
6246 The conditions inside the parenthesis are evaluated first and
6247 then the remaining condition is evaluated as in the other exam‐
6248 ples. Where there are nested parenthesis the innermost are
6249 evaluated as part of evaluating the condition that contains
6250 them.
6251 Existence Checks
6253 if(COMMAND <command-name>)
6254 True if the given name is a command, macro or function that can
6255 be invoked.
6256 if(POLICY <policy-id>)
6258 True if the given name is an existing policy (of the form
6259 CMP<NNNN>).
6260 if(TARGET <target-name>)
6262 True if the given name is an existing logical target name cre‐
6263 ated by a call to the add_executable(), add_library(), or
6264 add_custom_target() command that has already been invoked (in
6265 any directory).
6266 if(TEST <test-name>)
6268 New in version 3.3.
6269 True if the given name is an existing test name created by the
6272 add_test() command.
6273 if(DEFINED <name>|CACHE{<name>}|ENV{<name>})
6275 True if a variable, cache variable or environment variable
6276 with given <name> is defined. The value of the variable does
6277 not matter. Note the following caveats:
6278 • Macro arguments are not variables.
6280 • It is not possible to test directly whether a <name> is a
6282 non-cache variable. The expression if(DEFINED someName)
6283 will evaluate to true if either a cache or non-cache vari‐
6284 able someName exists. In comparison, the expression if(DE‐
6285 FINED CACHE{someName}) will only evaluate to true if a
6286 cache variable someName exists. Both expressions need to
6287 be tested if you need to know whether a non-cache variable
6288 exists: if(DEFINED someName AND NOT DEFINED CACHE{some‐
6289 Name}).
6290 New in version 3.14: Added support for CACHE{<name>} variables.
6292 if(<variable|string> IN_LIST <variable>)
6295 New in version 3.3.
6296 True if the given element is contained in the named list vari‐
6299 able.
6300 File Operations
6302 if(EXISTS <path-to-file-or-directory>)
6303 True if the named file or directory exists and is readable. Be‐
6304 havior is well-defined only for explicit full paths (a leading
6305 ~/ is not expanded as a home directory and is considered a rela‐
6306 tive path). Resolves symbolic links, i.e. if the named file or
6307 directory is a symbolic link, returns true if the target of the
6308 symbolic link exists.
6309 False if the given path is an empty string.
6311 if(<file1> IS_NEWER_THAN <file2>)
6313 True if file1 is newer than file2 or if one of the two files
6314 doesn't exist. Behavior is well-defined only for full paths.
6315 If the file time stamps are exactly the same, an IS_NEWER_THAN
6316 comparison returns true, so that any dependent build operations
6317 will occur in the event of a tie. This includes the case of
6318 passing the same file name for both file1 and file2.
6319 if(IS_DIRECTORY <path>)
6321 True if path is a directory. Behavior is well-defined only for
6322 full paths.
6323 False if the given path is an empty string.
6325 if(IS_SYMLINK <path>)
6327 True if the given path is a symbolic link. Behavior is well-de‐
6328 fined only for full paths.
6329 if(IS_ABSOLUTE <path>)
6331 True if the given path is an absolute path. Note the following
6332 special cases:
6333 • An empty path evaluates to false.
6335 • On Windows hosts, any path that begins with a drive letter and
6337 colon (e.g. C:), a forward slash or a backslash will evaluate
6338 to true. This means a path like C:no\base\dir will evaluate
6339 to true, even though the non-drive part of the path is rela‐
6340 tive.
6341 • On non-Windows hosts, any path that begins with a tilde (~)
6343 evaluates to true.
6344 Comparisons
6346 if(<variable|string> MATCHES <regex>)
6347 True if the given string or variable's value matches the given
6348 regular expression. See Regex Specification for regex format.
6349 New in version 3.9: () groups are captured in CMAKE_MATCH_<n>
6351 variables.
6352 if(<variable|string> LESS <variable|string>)
6355 True if the given string or variable's value is a valid number
6356 and less than that on the right.
6357 if(<variable|string> GREATER <variable|string>)
6359 True if the given string or variable's value is a valid number
6360 and greater than that on the right.
6361 if(<variable|string> EQUAL <variable|string>)
6363 True if the given string or variable's value is a valid number
6364 and equal to that on the right.
6365 if(<variable|string> LESS_EQUAL <variable|string>)
6367 New in version 3.7.
6368 True if the given string or variable's value is a valid number
6371 and less than or equal to that on the right.
6372 if(<variable|string> GREATER_EQUAL <variable|string>)
6374 New in version 3.7.
6375 True if the given string or variable's value is a valid number
6378 and greater than or equal to that on the right.
6379 if(<variable|string> STRLESS <variable|string>)
6381 True if the given string or variable's value is lexicographi‐
6382 cally less than the string or variable on the right.
6383 if(<variable|string> STRGREATER <variable|string>)
6385 True if the given string or variable's value is lexicographi‐
6386 cally greater than the string or variable on the right.
6387 if(<variable|string> STREQUAL <variable|string>)
6389 True if the given string or variable's value is lexicographi‐
6390 cally equal to the string or variable on the right.
6391 if(<variable|string> STRLESS_EQUAL <variable|string>)
6393 New in version 3.7.
6394 True if the given string or variable's value is lexicographi‐
6397 cally less than or equal to the string or variable on the right.
6398 if(<variable|string> STRGREATER_EQUAL <variable|string>)
6400 New in version 3.7.
6401 True if the given string or variable's value is lexicographi‐
6404 cally greater than or equal to the string or variable on the
6405 right.
6406 Version Comparisons
6408 if(<variable|string> VERSION_LESS <variable|string>)
6409 Component-wise integer version number comparison (version format
6410 is major[.minor[.patch[.tweak]]], omitted components are treated
6411 as zero). Any non-integer version component or non-integer
6412 trailing part of a version component effectively truncates the
6413 string at that point.
6414 if(<variable|string> VERSION_GREATER <variable|string>)
6416 Component-wise integer version number comparison (version format
6417 is major[.minor[.patch[.tweak]]], omitted components are treated
6418 as zero). Any non-integer version component or non-integer
6419 trailing part of a version component effectively truncates the
6420 string at that point.
6421 if(<variable|string> VERSION_EQUAL <variable|string>)
6423 Component-wise integer version number comparison (version format
6424 is major[.minor[.patch[.tweak]]], omitted components are treated
6425 as zero). Any non-integer version component or non-integer
6426 trailing part of a version component effectively truncates the
6427 string at that point.
6428 if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
6430 New in version 3.7.
6431 Component-wise integer version number comparison (version format
6434 is major[.minor[.patch[.tweak]]], omitted components are treated
6435 as zero). Any non-integer version component or non-integer
6436 trailing part of a version component effectively truncates the
6437 string at that point.
6438 if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
6440 New in version 3.7.
6441 Component-wise integer version number comparison (version format
6444 is major[.minor[.patch[.tweak]]], omitted components are treated
6445 as zero). Any non-integer version component or non-integer
6446 trailing part of a version component effectively truncates the
6447 string at that point.
6448 Path Comparisons
6450 if(<variable|string> PATH_EQUAL <variable|string>)
6451 New in version 3.24.
6452 Compares the two paths component-by-component. Only if every
6455 component of both paths match will the two paths compare equal.
6456 Multiple path separators are effectively collapsed into a single
6457 separator, but note that backslashes are not converted to for‐
6458 ward slashes. No other path normalization is performed.
6459 Component-wise comparison is superior to string-based comparison
6461 due to the handling of multiple path separators. In the follow‐
6462 ing example, the expression evaluates to true using PATH_EQUAL,
6463 but false with STREQUAL:
6464 # comparison is TRUE
6466 if ("/a//b/c" PATH_EQUAL "/a/b/c")
6467 ...
6468 endif()
6469 # comparison is FALSE
6471 if ("/a//b/c" STREQUAL "/a/b/c")
6472 ...
6473 endif()
6474 See cmake_path(COMPARE) for more details.
6476 Variable Expansion
6478 The if command was written very early in CMake's history, predating the
6479 ${} variable evaluation syntax, and for convenience evaluates variables
6480 named by its arguments as shown in the above signatures. Note that
6481 normal variable evaluation with ${} applies before the if command even
6482 receives the arguments. Therefore code like
6483 set(var1 OFF)
6485 set(var2 "var1")
6486 if(${var2})
6487 appears to the if command as
6489 if(var1)
6491 and is evaluated according to the if(<variable>) case documented above.
6493 The result is OFF which is false. However, if we remove the ${} from
6494 the example then the command sees
6495 if(var2)
6497 which is true because var2 is defined to var1 which is not a false con‐
6499 stant.
6500 Automatic evaluation applies in the other cases whenever the above-doc‐
6502 umented condition syntax accepts <variable|string>:
6503 • The left hand argument to MATCHES is first checked to see if it is a
6505 defined variable. If so, the variable's value is used, otherwise the
6506 original value is used.
6507 • If the left hand argument to MATCHES is missing it returns false
6509 without error
6510 • Both left and right hand arguments to LESS, GREATER, EQUAL,
6512 LESS_EQUAL, and GREATER_EQUAL, are independently tested to see if
6513 they are defined variables. If so, their defined values are used
6514 otherwise the original value is used.
6515 • Both left and right hand arguments to STRLESS, STRGREATER, STREQUAL,
6517 STRLESS_EQUAL, and STRGREATER_EQUAL are independently tested to see
6518 if they are defined variables. If so, their defined values are used
6519 otherwise the original value is used.
6520 • Both left and right hand arguments to VERSION_LESS, VERSION_GREATER,
6522 VERSION_EQUAL, VERSION_LESS_EQUAL, and VERSION_GREATER_EQUAL are in‐
6523 dependently tested to see if they are defined variables. If so,
6524 their defined values are used otherwise the original value is used.
6525 • The right hand argument to NOT is tested to see if it is a boolean
6527 constant. If so, the value is used, otherwise it is assumed to be a
6528 variable and it is dereferenced.
6529 • The left and right hand arguments to AND and OR are independently
6531 tested to see if they are boolean constants. If so, they are used as
6532 such, otherwise they are assumed to be variables and are derefer‐
6533 enced.
6534 Changed in version 3.1: To prevent ambiguity, potential variable or
6536 keyword names can be specified in a Quoted Argument or a Bracket Argu‐
6537 ment. A quoted or bracketed variable or keyword will be interpreted as
6538 a string and not dereferenced or interpreted. See policy CMP0054.
6539 There is no automatic evaluation for environment or cache Variable Ref‐
6542 erences. Their values must be referenced as $ENV{<name>} or
6543 $CACHE{<name>} wherever the above-documented condition syntax accepts
6544 <variable|string>.
6545 See also
6547 • else()
6548 • elseif()
6550 • endif()
6552 include
6554 Load and run CMake code from a file or module.
6555 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
6557 [NO_POLICY_SCOPE])
6558 Loads and runs CMake code from the file given. Variable reads and
6560 writes access the scope of the caller (dynamic scoping). If OPTIONAL
6561 is present, then no error is raised if the file does not exist. If RE‐
6562 SULT_VARIABLE is given the variable <var> will be set to the full file‐
6563 name which has been included or NOTFOUND if it failed.
6564 If a module is specified instead of a file, the file with name <module‐
6566 name>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake
6567 module directory. There is one exception to this: if the file which
6568 calls include() is located itself in the CMake builtin module direc‐
6569 tory, then first the CMake builtin module directory is searched and
6570 CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
6571 See the cmake_policy() command documentation for discussion of the
6573 NO_POLICY_SCOPE option.
6574 include_guard
6576 New in version 3.10.
6577 Provides an include guard for the file currently being processed by
6580 CMake.
6581 include_guard([DIRECTORY|GLOBAL])
6583 Sets up an include guard for the current CMake file (see the
6585 CMAKE_CURRENT_LIST_FILE variable documentation).
6586 CMake will end its processing of the current file at the location of
6588 the include_guard command if the current file has already been pro‐
6589 cessed for the applicable scope (see below). This provides functional‐
6590 ity similar to the include guards commonly used in source headers or to
6591 the #pragma once directive. If the current file has been processed pre‐
6592 viously for the applicable scope, the effect is as though return() had
6593 been called. Do not call this command from inside a function being de‐
6594 fined within the current file.
6595 An optional argument specifying the scope of the guard may be provided.
6597 Possible values for the option are:
6598 DIRECTORY
6600 The include guard applies within the current directory and be‐
6601 low. The file will only be included once within this directory
6602 scope, but may be included again by other files outside of this
6603 directory (i.e. a parent directory or another directory not
6604 pulled in by add_subdirectory() or include() from the current
6605 file or its children).
6606 GLOBAL The include guard applies globally to the whole build. The cur‐
6608 rent file will only be included once regardless of the scope.
6609 If no arguments given, include_guard has the same scope as a variable,
6611 meaning that the include guard effect is isolated by the most recent
6612 function scope or current directory if no inner function scopes exist.
6613 In this case the command behavior is the same as:
6614 if(__CURRENT_FILE_VAR__)
6616 return()
6617 endif()
6618 set(__CURRENT_FILE_VAR__ TRUE)
6619 list
6621 Operations on semicolon-separated lists.
6622 Synopsis
6624 Reading
6625 list(LENGTH <list> <out-var>)
6626 list(GET <list> <element index> [<index> ...] <out-var>)
6627 list(JOIN <list> <glue> <out-var>)
6628 list(SUBLIST <list> <begin> <length> <out-var>)
6629 Search
6631 list(FIND <list> <value> <out-var>)
6632 Modification
6634 list(APPEND <list> [<element>...])
6635 list(FILTER <list> {INCLUDE | EXCLUDE} REGEX <regex>)
6636 list(INSERT <list> <index> [<element>...])
6637 list(POP_BACK <list> [<out-var>...])
6638 list(POP_FRONT <list> [<out-var>...])
6639 list(PREPEND <list> [<element>...])
6640 list(REMOVE_ITEM <list> <value>...)
6641 list(REMOVE_AT <list> <index>...)
6642 list(REMOVE_DUPLICATES <list>)
6643 list(TRANSFORM <list> <ACTION> [...])
6644 Ordering
6646 list(REVERSE <list>)
6647 list(SORT <list> [...])
6648 Introduction
6650 The list subcommands APPEND, INSERT, FILTER, PREPEND, POP_BACK,
6651 POP_FRONT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT
6652 may create new values for the list within the current CMake variable
6653 scope. Similar to the set() command, the list command creates new
6654 variable values in the current scope, even if the list itself is actu‐
6655 ally defined in a parent scope. To propagate the results of these op‐
6656 erations upwards, use set() with PARENT_SCOPE, set() with CACHE INTER‐
6657 NAL, or some other means of value propagation.
6658 NOTE:
6660 A list in cmake is a ; separated group of strings. To create a
6661 list, the set() command can be used. For example, set(var a b c d
6662 e) creates a list with a;b;c;d;e, and set(var "a b c d e") creates a
6663 string or a list with one item in it. (Note that macro arguments
6664 are not variables, and therefore cannot be used in LIST commands.)
6665 Individual elements may not contain an unequal number of [ and ]
6667 characters, and may not end in a backslash (\). See
6668 semicolon-separated lists for details.
6669 NOTE:
6671 When specifying index values, if <element index> is 0 or greater, it
6672 is indexed from the beginning of the list, with 0 representing the
6673 first list element. If <element index> is -1 or lesser, it is in‐
6674 dexed from the end of the list, with -1 representing the last list
6675 element. Be careful when counting with negative indices: they do
6676 not start from 0. -0 is equivalent to 0, the first list element.
6677 Reading
6679 list(LENGTH <list> <output variable>)
6680 Returns the list's length.
6681 list(GET <list> <element index> [<element index> ...] <output vari‐
6683 able>)
6684 Returns the list of elements specified by indices from the list.
6685 list(JOIN <list> <glue> <output variable>)
6687 New in version 3.12.
6688 Returns a string joining all list's elements using the glue
6691 string. To join multiple strings, which are not part of a list,
6692 use string(JOIN).
6693 list(SUBLIST <list> <begin> <length> <output variable>)
6695 New in version 3.12.
6696 Returns a sublist of the given list. If <length> is 0, an empty
6699 list will be returned. If <length> is -1 or the list is smaller
6700 than <begin>+<length> then the remaining elements of the list
6701 starting at <begin> will be returned.
6702 Search
6704 list(FIND <list> <value> <output variable>)
6705 Returns the index of the element specified in the list or -1 if
6706 it wasn't found.
6707 Modification
6709 list(APPEND <list> [<element> ...])
6710 Appends elements to the list. If no variable named <list> exists
6711 in the current scope its value is treated as empty and the ele‐
6712 ments are appended to that empty list.
6713 list(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>)
6715 New in version 3.6.
6717 Includes or removes items from the list that match the mode's pattern.
6720 In REGEX mode, items will be matched against the given regular expres‐
6721 sion.
6722 For more information on regular expressions look under string(REGEX).
6724 list(INSERT <list> <element_index> <element> [<element> ...])
6726 Inserts elements to the list to the specified index. It is an
6727 error to specify an out-of-range index. Valid indexes are 0 to N
6728 where N is the length of the list, inclusive. An empty list has
6729 length 0. If no variable named <list> exists in the current
6730 scope its value is treated as empty and the elements are in‐
6731 serted in that empty list.
6732 list(POP_BACK <list> [<out-var>...])
6734 New in version 3.15.
6735 If no variable name is given, removes exactly one element. Oth‐
6738 erwise, with N variable names provided, assign the last N ele‐
6739 ments' values to the given variables and then remove the last N
6740 values from <list>.
6741 list(POP_FRONT <list> [<out-var>...])
6743 New in version 3.15.
6744 If no variable name is given, removes exactly one element. Oth‐
6747 erwise, with N variable names provided, assign the first N ele‐
6748 ments' values to the given variables and then remove the first N
6749 values from <list>.
6750 list(PREPEND <list> [<element> ...])
6752 New in version 3.15.
6753 Insert elements to the 0th position in the list. If no variable
6756 named <list> exists in the current scope its value is treated as
6757 empty and the elements are prepended to that empty list.
6758 list(REMOVE_ITEM <list> <value> [<value> ...])
6760 Removes all instances of the given items from the list.
6761 list(REMOVE_AT <list> <index> [<index> ...])
6763 Removes items at given indices from the list.
6764 list(REMOVE_DUPLICATES <list>)
6766 Removes duplicated items in the list. The relative order of
6767 items is preserved, but if duplicates are encountered, only the
6768 first instance is preserved.
6769 list(TRANSFORM <list> <ACTION> [<SELECTOR>] [OUTPUT_VARIABLE <out‐
6771 put variable>])
6772 New in version 3.12.
6773 Transforms the list by applying an <ACTION> to all or, by speci‐
6776 fying a <SELECTOR>, to the selected elements of the list, stor‐
6777 ing the result in-place or in the specified output variable.
6778 NOTE:
6780 The TRANSFORM sub-command does not change the number of ele‐
6781 ments in the list. If a <SELECTOR> is specified, only some
6782 elements will be changed, the other ones will remain the same
6783 as before the transformation.
6784 <ACTION> specifies the action to apply to the elements of the
6786 list. The actions have exactly the same semantics as sub-com‐
6787 mands of the string() command. <ACTION> must be one of the fol‐
6788 lowing:
6789 APPEND, PREPEND
6791 Append, prepend specified value to each element of the
6792 list.
6793 list(TRANSFORM <list> (APPEND|PREPEND) <value> ...)
6795 TOLOWER, TOUPPER
6797 Convert each element of the list to lower, upper char‐
6798 acters.
6799 list(TRANSFORM <list> (TOLOWER|TOUPPER) ...)
6801 STRIP Remove leading and trailing spaces from each element
6803 of the list.
6804 list(TRANSFORM <list> STRIP ...)
6806 GENEX_STRIP
6808 Strip any generator expressions from each element of
6809 the list.
6810 list(TRANSFORM <list> GENEX_STRIP ...)
6812 REPLACE:
6814 Match the regular expression as many times as possible
6815 and substitute the replacement expression for the
6816 match for each element of the list (same semantic as
6817 string(REGEX REPLACE)).
6818 list(TRANSFORM <list> REPLACE <regular_expression>
6820 <replace_expression> ...)
6821 <SELECTOR> determines which elements of the list will be trans‐
6823 formed. Only one type of selector can be specified at a time.
6824 When given, <SELECTOR> must be one of the following:
6825 AT Specify a list of indexes.
6827 list(TRANSFORM <list> <ACTION> AT <index> [<index> ...] ...)
6829 FOR Specify a range with, optionally, an increment used to
6831 iterate over the range.
6832 list(TRANSFORM <list> <ACTION> FOR <start> <stop> [<step>] ...)
6834 REGEX Specify a regular expression. Only elements matching
6836 the regular expression will be transformed.
6837 list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
6839 Ordering
6841 list(REVERSE <list>)
6842 Reverses the contents of the list in-place.
6843 list(SORT <list> [COMPARE <compare>] [CASE <case>] [ORDER <order>])
6845 Sorts the list in-place alphabetically.
6846 New in version 3.13: Added the COMPARE, CASE, and ORDER options.
6848 New in version 3.18: Added the COMPARE NATURAL option.
6851 Use the COMPARE keyword to select the comparison method for
6854 sorting. The <compare> option should be one of:
6855 STRING Sorts a list of strings alphabetically. This is the
6857 default behavior if the COMPARE option is not given.
6858 FILE_BASENAME
6860 Sorts a list of pathnames of files by their basenames.
6861 NATURAL
6863 Sorts a list of strings using natural order (see
6864 strverscmp(3) manual), i.e. such that contiguous dig‐
6865 its are compared as whole numbers. For example: the
6866 following list 10.0 1.1 2.1 8.0 2.0 3.1 will be sorted
6867 as 1.1 2.0 2.1 3.1 8.0 10.0 if the NATURAL comparison
6868 is selected where it will be sorted as 1.1 10.0 2.0
6869 2.1 3.1 8.0 with the STRING comparison.
6870 Use the CASE keyword to select a case sensitive or case insensi‐
6872 tive sort mode. The <case> option should be one of:
6873 SENSITIVE
6875 List items are sorted in a case-sensitive manner.
6876 This is the default behavior if the CASE option is not
6877 given.
6878 INSENSITIVE
6880 List items are sorted case insensitively. The order
6881 of items which differ only by upper/lowercase is not
6882 specified.
6883 To control the sort order, the ORDER keyword can be given. The
6885 <order> option should be one of:
6886 ASCENDING
6888 Sorts the list in ascending order. This is the de‐
6889 fault behavior when the ORDER option is not given.
6890 DESCENDING
6892 Sorts the list in descending order.
6893 macro
6895 Start recording a macro for later invocation as a command
6896 macro(<name> [<arg1> ...])
6898 <commands>
6899 endmacro()
6900 Defines a macro named <name> that takes arguments named <arg1>, ...
6902 Commands listed after macro, but before the matching endmacro(), are
6903 not executed until the macro is invoked.
6904 Per legacy, the endmacro() command admits an optional <name> argument.
6906 If used, it must be a verbatim repeat of the argument of the opening
6907 macro command.
6908 See the cmake_policy() command documentation for the behavior of poli‐
6910 cies inside macros.
6911 See the Macro vs Function section below for differences between CMake
6913 macros and functions.
6914 Invocation
6916 The macro invocation is case-insensitive. A macro defined as
6917 macro(foo)
6919 <commands>
6920 endmacro()
6921 can be invoked through any of
6923 foo()
6925 Foo()
6926 FOO()
6927 cmake_language(CALL foo)
6928 and so on. However, it is strongly recommended to stay with the case
6930 chosen in the macro definition. Typically macros use all-lowercase
6931 names.
6932 New in version 3.18: The cmake_language(CALL ...) command can also be
6934 used to invoke the macro.
6935 Arguments
6938 When a macro is invoked, the commands recorded in the macro are first
6939 modified by replacing formal parameters (${arg1}, ...) with the argu‐
6940 ments passed, and then invoked as normal commands.
6941 In addition to referencing the formal parameters you can reference the
6943 values ${ARGC} which will be set to the number of arguments passed into
6944 the function as well as ${ARGV0}, ${ARGV1}, ${ARGV2}, ... which will
6945 have the actual values of the arguments passed in. This facilitates
6946 creating macros with optional arguments.
6947 Furthermore, ${ARGV} holds the list of all arguments given to the macro
6949 and ${ARGN} holds the list of arguments past the last expected argu‐
6950 ment. Referencing to ${ARGV#} arguments beyond ${ARGC} have undefined
6951 behavior. Checking that ${ARGC} is greater than # is the only way to
6952 ensure that ${ARGV#} was passed to the function as an extra argument.
6953 Macro vs Function
6955 The macro command is very similar to the function() command. Nonethe‐
6956 less, there are a few important differences.
6957 In a function, ARGN, ARGC, ARGV and ARGV0, ARGV1, ... are true vari‐
6959 ables in the usual CMake sense. In a macro, they are not, they are
6960 string replacements much like the C preprocessor would do with a macro.
6961 This has a number of consequences, as explained in the Argument Caveats
6962 section below.
6963 Another difference between macros and functions is the control flow. A
6965 function is executed by transferring control from the calling statement
6966 to the function body. A macro is executed as if the macro body were
6967 pasted in place of the calling statement. This has the consequence
6968 that a return() in a macro body does not just terminate execution of
6969 the macro; rather, control is returned from the scope of the macro
6970 call. To avoid confusion, it is recommended to avoid return() in
6971 macros altogether.
6972 Unlike a function, the CMAKE_CURRENT_FUNCTION,
6974 CMAKE_CURRENT_FUNCTION_LIST_DIR, CMAKE_CURRENT_FUNCTION_LIST_FILE,
6975 CMAKE_CURRENT_FUNCTION_LIST_LINE variables are not set for a macro.
6976 Argument Caveats
6978 Since ARGN, ARGC, ARGV, ARGV0 etc. are not variables, you will NOT be
6979 able to use commands like
6980 if(ARGV1) # ARGV1 is not a variable
6982 if(DEFINED ARGV2) # ARGV2 is not a variable
6983 if(ARGC GREATER 2) # ARGC is not a variable
6984 foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
6985 In the first case, you can use if(${ARGV1}). In the second and third
6987 case, the proper way to check if an optional variable was passed to the
6988 macro is to use if(${ARGC} GREATER 2). In the last case, you can use
6989 foreach(loop_var ${ARGN}) but this will skip empty arguments. If you
6990 need to include them, you can use
6991 set(list_var "${ARGN}")
6993 foreach(loop_var IN LISTS list_var)
6994 Note that if you have a variable with the same name in the scope from
6996 which the macro is called, using unreferenced names will use the exist‐
6997 ing variable instead of the arguments. For example:
6998 macro(bar)
7000 foreach(arg IN LISTS ARGN)
7001 <commands>
7002 endforeach()
7003 endmacro()
7004 function(foo)
7006 bar(x y z)
7007 endfunction()
7008 foo(a b c)
7010 Will loop over a;b;c and not over x;y;z as one might have expected. If
7012 you want true CMake variables and/or better CMake scope control you
7013 should look at the function command.
7014 See Also
7016 • cmake_parse_arguments()
7017 • endmacro()
7019 mark_as_advanced
7021 Mark cmake cached variables as advanced.
7022 mark_as_advanced([CLEAR|FORCE] <var1> ...)
7024 Sets the advanced/non-advanced state of the named cached variables.
7026 An advanced variable will not be displayed in any of the cmake GUIs un‐
7028 less the show advanced option is on. In script mode, the ad‐
7029 vanced/non-advanced state has no effect.
7030 If the keyword CLEAR is given then advanced variables are changed back
7032 to unadvanced. If the keyword FORCE is given then the variables are
7033 made advanced. If neither FORCE nor CLEAR is specified, new values
7034 will be marked as advanced, but if a variable already has an ad‐
7035 vanced/non-advanced state, it will not be changed.
7036 Changed in version 3.17: Variables passed to this command which are not
7038 already in the cache are ignored. See policy CMP0102.
7039 math
7042 Evaluate a mathematical expression.
7043 math(EXPR <variable> "<expression>" [OUTPUT_FORMAT <format>])
7045 Evaluates a mathematical <expression> and sets <variable> to the re‐
7047 sulting value. The result of the expression must be representable as a
7048 64-bit signed integer. Floating point inputs are invalid e.g. 1.1 * 10.
7049 Non-integer results e.g. 3 / 2 are truncated.
7050 The mathematical expression must be given as a string (i.e. enclosed in
7052 double quotation marks). An example is "5 * (10 + 13)". Supported op‐
7053 erators are +, -, *, /, %, |, &, ^, ~, <<, >>, and (...); they have the
7054 same meaning as in C code.
7055 New in version 3.13: Hexadecimal numbers are recognized when prefixed
7057 with 0x, as in C code.
7058 New in version 3.13: The result is formatted according to the option
7061 OUTPUT_FORMAT, where <format> is one of
7062 HEXADECIMAL
7064 Hexadecimal notation as in C code, i. e. starting with "0x".
7065 DECIMAL
7067 Decimal notation. Which is also used if no OUTPUT_FORMAT option
7068 is specified.
7069 For example
7072 math(EXPR value "100 * 0xA" OUTPUT_FORMAT DECIMAL) # value is set to "1000"
7074 math(EXPR value "100 * 0xA" OUTPUT_FORMAT HEXADECIMAL) # value is set to "0x3e8"
7075 message
7077 Log a message.
7078 Synopsis
7080 General messages
7081 message([<mode>] "message text" ...)
7082 Reporting checks
7084 message(<checkState> "message text" ...)
7085 Configure Log
7087 message(CONFIGURE_LOG <text>...)
7088 General messages
7090 message([<mode>] "message text" ...)
7091 Record the specified message text in the log. If more than one message
7093 string is given, they are concatenated into a single message with no
7094 separator between the strings.
7095 The optional <mode> keyword determines the type of message, which in‐
7097 fluences the way the message is handled:
7098 FATAL_ERROR
7100 CMake Error, stop processing and generation.
7101 The cmake(1) executable will return a non-zero exit code.
7103 SEND_ERROR
7105 CMake Error, continue processing, but skip generation.
7106 WARNING
7108 CMake Warning, continue processing.
7109 AUTHOR_WARNING
7111 CMake Warning (dev), continue processing.
7112 DEPRECATION
7114 CMake Deprecation Error or Warning if variable
7115 CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED is enabled, re‐
7116 spectively, else no message.
7117 (none) or NOTICE
7119 Important message printed to stderr to attract user's attention.
7120 STATUS The main interesting messages that project users might be inter‐
7122 ested in. Ideally these should be concise, no more than a sin‐
7123 gle line, but still informative.
7124 VERBOSE
7126 Detailed informational messages intended for project users.
7127 These messages should provide additional details that won't be
7128 of interest in most cases, but which may be useful to those
7129 building the project when they want deeper insight into what's
7130 happening.
7131 DEBUG Detailed informational messages intended for developers working
7133 on the project itself as opposed to users who just want to build
7134 it. These messages will not typically be of interest to other
7135 users building the project and will often be closely related to
7136 internal implementation details.
7137 TRACE Fine-grained messages with very low-level implementation de‐
7139 tails. Messages using this log level would normally only be
7140 temporary and would expect to be removed before releasing the
7141 project, packaging up the files, etc.
7142 New in version 3.15: Added the NOTICE, VERBOSE, DEBUG, and TRACE lev‐
7144 els.
7145 The CMake command-line tool displays STATUS to TRACE messages on stdout
7148 with the message preceded by two hyphens and a space. All other mes‐
7149 sage types are sent to stderr and are not prefixed with hyphens. The
7150 CMake GUI displays all messages in its log area. The curses interface
7151 shows STATUS to TRACE messages one at a time on a status line and other
7152 messages in an interactive pop-up box. The --log-level command-line
7153 option to each of these tools can be used to control which messages
7154 will be shown.
7155 New in version 3.17: To make a log level persist between CMake runs,
7157 the CMAKE_MESSAGE_LOG_LEVEL variable can be set instead. Note that the
7158 command line option takes precedence over the cache variable.
7159 New in version 3.16: Messages of log levels NOTICE and below will have
7162 each line preceded by the content of the CMAKE_MESSAGE_INDENT variable
7163 (converted to a single string by concatenating its list items). For
7164 STATUS to TRACE messages, this indenting content will be inserted after
7165 the hyphens.
7166 New in version 3.17: Messages of log levels NOTICE and below can also
7169 have each line preceded with context of the form [some.context.exam‐
7170 ple]. The content between the square brackets is obtained by convert‐
7171 ing the CMAKE_MESSAGE_CONTEXT list variable to a dot-separated string.
7172 The message context will always appear before any indenting content but
7173 after any automatically added leading hyphens. By default, message con‐
7174 text is not shown, it has to be explicitly enabled by giving the cmake
7175 --log-context command-line option or by setting the
7176 CMAKE_MESSAGE_CONTEXT_SHOW variable to true. See the
7177 CMAKE_MESSAGE_CONTEXT documentation for usage examples.
7178 CMake Warning and Error message text displays using a simple markup
7181 language. Non-indented text is formatted in line-wrapped paragraphs
7182 delimited by newlines. Indented text is considered pre-formatted.
7183 Reporting checks
7185 New in version 3.17.
7186 A common pattern in CMake output is a message indicating the start of
7189 some sort of check, followed by another message reporting the result of
7190 that check. For example:
7191 message(STATUS "Looking for someheader.h")
7193 #... do the checks, set checkSuccess with the result
7194 if(checkSuccess)
7195 message(STATUS "Looking for someheader.h - found")
7196 else()
7197 message(STATUS "Looking for someheader.h - not found")
7198 endif()
7199 This can be more robustly and conveniently expressed using the
7201 CHECK_... keyword form of the message() command:
7202 message(<checkState> "message" ...)
7204 where <checkState> must be one of the following:
7206 CHECK_START
7208 Record a concise message about the check about to be per‐
7209 formed.
7210 CHECK_PASS
7212 Record a successful result for a check.
7213 CHECK_FAIL
7215 Record an unsuccessful result for a check.
7216 When recording a check result, the command repeats the message from the
7218 most recently started check for which no result has yet been reported,
7219 then some separator characters and then the message text provided after
7220 the CHECK_PASS or CHECK_FAIL keyword. Check messages are always re‐
7221 ported at STATUS log level.
7222 Checks may be nested and every CHECK_START should have exactly one
7224 matching CHECK_PASS or CHECK_FAIL. The CMAKE_MESSAGE_INDENT variable
7225 can also be used to add indenting to nested checks if desired. For ex‐
7226 ample:
7227 message(CHECK_START "Finding my things")
7229 list(APPEND CMAKE_MESSAGE_INDENT " ")
7230 unset(missingComponents)
7231 message(CHECK_START "Finding partA")
7233 # ... do check, assume we find A
7234 message(CHECK_PASS "found")
7235 message(CHECK_START "Finding partB")
7237 # ... do check, assume we don't find B
7238 list(APPEND missingComponents B)
7239 message(CHECK_FAIL "not found")
7240 list(POP_BACK CMAKE_MESSAGE_INDENT)
7242 if(missingComponents)
7243 message(CHECK_FAIL "missing components: ${missingComponents}")
7244 else()
7245 message(CHECK_PASS "all components found")
7246 endif()
7247 Output from the above would appear something like the following:
7249 -- Finding my things
7251 -- Finding partA
7252 -- Finding partA - found
7253 -- Finding partB
7254 -- Finding partB - not found
7255 -- Finding my things - missing components: B
7256 Configure Log
7258 New in version 3.26.
7259 message(CONFIGURE_LOG <text>...)
7262 Record a configure-log message event with the specified <text>. By
7264 convention, if the text contains more than one line, the first line
7265 should be a summary of the event.
7266 This mode is intended to record the details of a system inspection
7268 check or other one-time operation guarded by a cache entry, but that is
7269 not performed using try_compile() or try_run(), which automatically log
7270 their details. Projects should avoid calling it every time CMake runs.
7271 For example:
7272 if (NOT DEFINED MY_CHECK_RESULT)
7274 # Print check summary in configure output.
7275 message(CHECK_START "My Check")
7276 # ... perform system inspection, e.g., with execute_process ...
7278 # Cache the result so we do not run the check again.
7280 set(MY_CHECK_RESULT "${MY_CHECK_RESULT}" CACHE INTERNAL "My Check")
7281 # Record the check details in the cmake-configure-log.
7283 message(CONFIGURE_LOG
7284 "My Check Result: ${MY_CHECK_RESULT}\n"
7285 "${details}"
7286 )
7287 # Print check result in configure output.
7289 if(MY_CHECK_RESULT)
7290 message(CHECK_PASS "passed")
7291 else()
7292 message(CHECK_FAIL "failed")
7293 endif()
7294 endif()
7295 If no project is currently being configured, such as in cmake -P script
7297 mode, this command does nothing.
7298 See Also
7300 • cmake_language(GET_MESSAGE_LOG_LEVEL)
7301 option
7303 Provide a boolean option that the user can optionally select.
7304 option(<variable> "<help_text>" [value])
7306 If no initial <value> is provided, boolean OFF is the default value.
7308 If <variable> is already set as a normal or cache variable, then the
7309 command does nothing (see policy CMP0077).
7310 For options that depend on the values of other options, see the module
7312 help for CMakeDependentOption.
7313 In CMake project mode, a boolean cache variable is created with the op‐
7315 tion value. In CMake script mode, a boolean variable is set with the
7316 option value.
7317 return
7319 Return from a file, directory or function.
7320 return([PROPAGATE <var-name>...])
7322 When this command is encountered in an included file (via include() or
7324 find_package()), it causes processing of the current file to stop and
7325 control is returned to the including file. If it is encountered in a
7326 file which is not included by another file, e.g. a CMakeLists.txt, de‐
7327 ferred calls scheduled by cmake_language(DEFER) are invoked and control
7328 is returned to the parent directory if there is one.
7329 If return() is called in a function, control is returned to the caller
7331 of that function. Note that a macro(), unlike a function(), is ex‐
7332 panded in place and therefore cannot handle return().
7333 Policy CMP0140 controls the behavior regarding the arguments of the
7335 command. All arguments are ignored unless that policy is set to NEW.
7336 PROPAGATE
7338 New in version 3.25.
7339 This option sets or unsets the specified variables in the parent
7342 directory or function caller scope. This is equivalent to
7343 set(PARENT_SCOPE) or unset(PARENT_SCOPE) commands, except for
7344 the way it interacts with the block() command, as described be‐
7345 low.
7346 The PROPAGATE option can be very useful in conjunction with the
7348 block() command. A return will propagate the specified vari‐
7349 ables through any enclosing block scopes created by the block()
7350 commands. Inside a function, this ensures the variables are
7351 propagated to the function's caller, regardless of any blocks
7352 within the function. If not inside a function, it ensures the
7353 variables are propagated to the parent file or directory scope.
7354 For example:
7355 CMakeLists.txt
7357 cmake_version_required(VERSION 3.25)
7359 project(example)
7360 set(var1 "top-value")
7362 block(SCOPE_FOR VARIABLES)
7364 add_subdirectory(subDir)
7365 # var1 has the value "block-nested"
7366 endblock()
7367 # var1 has the value "top-value"
7369 subDir/CMakeLists.txt
7371 function(multi_scopes result_var1 result_var2)
7373 block(SCOPE_FOR VARIABLES)
7374 # This would only propagate out of the immediate block, not to
7375 # the caller of the function.
7376 #set(${result_var1} "new-value" PARENT_SCOPE)
7377 #unset(${result_var2} PARENT_SCOPE)
7378 # This propagates the variables through the enclosing block and
7380 # out to the caller of the function.
7381 set(${result_var1} "new-value")
7382 unset(${result_var2})
7383 return(PROPAGATE ${result_var1} ${result_var2})
7384 endblock()
7385 endfunction()
7386 set(var1 "some-value")
7388 set(var2 "another-value")
7389 multi_scopes(var1 var2)
7391 # Now var1 will hold "new-value" and var2 will be unset
7392 block(SCOPE_FOR VARIABLES)
7394 # This return() will set var1 in the directory scope that included us
7395 # via add_subdirectory(). The surrounding block() here does not limit
7396 # propagation to the current file, but the block() in the parent
7397 # directory scope does prevent propagation going any further.
7398 set(var1 "block-nested")
7399 return(PROPAGATE var1)
7400 endblock()
7401 See Also
7403 • block()
7404 • function()
7406 separate_arguments
7408 Parse command-line arguments into a semicolon-separated list.
7409 separate_arguments(<variable> <mode> [PROGRAM [SEPARATE_ARGS]] <args>)
7411 Parses a space-separated string <args> into a list of items, and stores
7413 this list in semicolon-separated standard form in <variable>.
7414 This function is intended for parsing command-line arguments. The en‐
7416 tire command line must be passed as one string in the argument <args>.
7417 The exact parsing rules depend on the operating system. They are spec‐
7419 ified by the <mode> argument which must be one of the following key‐
7420 words:
7421 UNIX_COMMAND
7423 Arguments are separated by unquoted whitespace. Both sin‐
7424 gle-quote and double-quote pairs are respected. A backslash es‐
7425 capes the next literal character (\" is "); there are no special
7426 escapes (\n is just n).
7427 WINDOWS_COMMAND
7429 A Windows command-line is parsed using the same syntax the run‐
7430 time library uses to construct argv at startup. It separates
7431 arguments by whitespace that is not double-quoted. Backslashes
7432 are literal unless they precede double-quotes. See the MSDN ar‐
7433 ticle Parsing C Command-Line Arguments for details.
7434 NATIVE_COMMAND
7436 New in version 3.9.
7437 Proceeds as in WINDOWS_COMMAND mode if the host system is Win‐
7440 dows. Otherwise proceeds as in UNIX_COMMAND mode.
7441 PROGRAM
7443 New in version 3.19.
7444 The first item in <args> is assumed to be an executable and will
7447 be searched in the system search path or left as a full path. If
7448 not found, <variable> will be empty. Otherwise, <variable> is a
7449 list of 2 elements:
7450 0. Absolute path of the program
7452 1. Any command-line arguments present in <args> as a string
7454 For example:
7456 separate_arguments (out UNIX_COMMAND PROGRAM "cc -c main.c")
7458 • First element of the list: /path/to/cc
7460 • Second element of the list: " -c main.c"
7462 SEPARATE_ARGS
7464 When this sub-option of PROGRAM option is specified, com‐
7465 mand-line arguments will be split as well and stored in <vari‐
7466 able>.
7467 For example:
7469 separate_arguments (out UNIX_COMMAND PROGRAM SEPARATE_ARGS "cc -c main.c")
7471 The contents of out will be: /path/to/cc;-c;main.c
7473 separate_arguments(<var>)
7475 Convert the value of <var> to a semi-colon separated list. All spaces
7477 are replaced with ';'. This helps with generating command lines.
7478 set
7480 Set a normal, cache, or environment variable to a given value. See the
7481 cmake-language(7) variables documentation for the scopes and interac‐
7482 tion of normal variables and cache entries.
7483 Signatures of this command that specify a <value>... placeholder expect
7485 zero or more arguments. Multiple arguments will be joined as a
7486 semicolon-separated list to form the actual variable value to be set.
7487 Set Normal Variable
7489 set(<variable> <value>... [PARENT_SCOPE])
7490 Set or unset <variable> in the current function or directory
7491 scope:
7492 • If at least one <value>... is given, set the variable to that
7494 value.
7495 • If no value is given, unset the variable. This is equivalent
7497 to unset(<variable>).
7498 If the PARENT_SCOPE option is given the variable will be set in
7500 the scope above the current scope. Each new directory or
7501 function() command creates a new scope. A scope can also be
7502 created with the block() command. This command will set the
7503 value of a variable into the parent directory, calling function
7504 or encompassing scope (whichever is applicable to the case at
7505 hand). The previous state of the variable's value stays the same
7506 in the current scope (e.g., if it was undefined before, it is
7507 still undefined and if it had a value, it is still that value).
7508 The block(PROPAGATE) and return(PROPAGATE) commands can be used
7510 as an alternate method to the set(PARENT_SCOPE) and
7511 unset(PARENT_SCOPE) commands to update the parent scope.
7512 NOTE:
7514 When evaluating Variable References of the form ${VAR}, CMake first
7515 searches for a normal variable with that name. If no such normal
7516 variable exists, CMake will then search for a cache entry with that
7517 name. Because of this, unsetting a normal variable can expose a
7518 cache variable that was previously hidden. To force a variable ref‐
7519 erence of the form ${VAR} to return an empty string, use set(<vari‐
7520 able> ""), which clears the normal variable but leaves it defined.
7521 Set Cache Entry
7523 set(<variable> <value>... CACHE <type> <docstring> [FORCE])
7524 Sets the given cache <variable> (cache entry). Since cache en‐
7525 tries are meant to provide user-settable values this does not
7526 overwrite existing cache entries by default. Use the FORCE op‐
7527 tion to overwrite existing entries.
7528 The <type> must be specified as one of:
7530 BOOL Boolean ON/OFF value. cmake-gui(1) offers a checkbox.
7532 FILEPATH
7534 Path to a file on disk. cmake-gui(1) offers a file
7535 dialog.
7536 PATH Path to a directory on disk. cmake-gui(1) offers a
7538 file dialog.
7539 STRING A line of text. cmake-gui(1) offers a text field or a
7541 drop-down selection if the STRINGS cache entry prop‐
7542 erty is set.
7543 INTERNAL
7545 A line of text. cmake-gui(1) does not show internal
7546 entries. They may be used to store variables persis‐
7547 tently across runs. Use of this type implies FORCE.
7548 The <docstring> must be specified as a line of text providing a
7550 quick summary of the option for presentation to cmake-gui(1)
7551 users.
7552 If the cache entry does not exist prior to the call or the FORCE
7554 option is given then the cache entry will be set to the given
7555 value.
7556 NOTE:
7558 The content of the cache variable will not be directly acces‐
7559 sible if a normal variable of the same name already exists
7560 (see rules of variable evaluation). If policy CMP0126 is set
7561 to OLD, any normal variable binding in the current scope will
7562 be removed.
7563 It is possible for the cache entry to exist prior to the call
7565 but have no type set if it was created on the cmake(1) command
7566 line by a user through the -D<var>=<value> option without speci‐
7567 fying a type. In this case the set command will add the type.
7568 Furthermore, if the <type> is PATH or FILEPATH and the <value>
7569 provided on the command line is a relative path, then the set
7570 command will treat the path as relative to the current working
7571 directory and convert it to an absolute path.
7572 Set Environment Variable
7574 set(ENV{<variable>} [<value>])
7575 Sets an Environment Variable to the given value. Subsequent
7576 calls of $ENV{<variable>} will return this new value.
7577 This command affects only the current CMake process, not the
7579 process from which CMake was called, nor the system environment
7580 at large, nor the environment of subsequent build or test pro‐
7581 cesses.
7582 If no argument is given after ENV{<variable>} or if <value> is
7584 an empty string, then this command will clear any existing value
7585 of the environment variable.
7586 Arguments after <value> are ignored. If extra arguments are
7588 found, then an author warning is issued.
7589 See Also
7591 • unset()
7592 set_directory_properties
7594 Set properties of the current directory and subdirectories.
7595 set_directory_properties(PROPERTIES prop1 value1 [prop2 value2] ...)
7597 Sets properties of the current directory and its subdirectories in
7599 key-value pairs.
7600 See also the set_property(DIRECTORY) command.
7602 See Properties on Directories for the list of properties known to CMake
7604 and their individual documentation for the behavior of each property.
7605 See Also
7607 • define_property()
7608 • get_directory_property()
7610 • the more general set_property() command
7612 set_property
7614 Set a named property in a given scope.
7615 set_property(<GLOBAL |
7617 DIRECTORY [<dir>] |
7618 TARGET [<target1> ...] |
7619 SOURCE [<src1> ...]
7620 [DIRECTORY <dirs> ...]
7621 [TARGET_DIRECTORY <targets> ...] |
7622 INSTALL [<file1> ...] |
7623 TEST [<test1> ...] |
7624 CACHE [<entry1> ...] >
7625 [APPEND] [APPEND_STRING]
7626 PROPERTY <name> [<value1> ...])
7627 Sets one property on zero or more objects of a scope.
7629 The first argument determines the scope in which the property is set.
7631 It must be one of the following:
7632 GLOBAL Scope is unique and does not accept a name.
7634 DIRECTORY
7636 Scope defaults to the current directory but other directories
7637 (already processed by CMake) may be named by full or relative
7638 path. Relative paths are treated as relative to the current
7639 source directory. See also the set_directory_properties() com‐
7640 mand.
7641 New in version 3.19: <dir> may reference a binary directory.
7643 TARGET Scope may name zero or more existing targets. See also the
7646 set_target_properties() command.
7647 Alias Targets do not support setting target properties.
7649 SOURCE Scope may name zero or more source files. By default, source
7651 file properties are only visible to targets added in the same
7652 directory (CMakeLists.txt).
7653 New in version 3.18: Visibility can be set in other directory
7655 scopes using one or both of the following sub-options:
7656 DIRECTORY <dirs>...
7658 The source file property will be set in each of the
7659 <dirs> directories' scopes. CMake must already know
7660 about each of these directories, either by having added
7661 them through a call to add_subdirectory() or it being the
7662 top level source directory. Relative paths are treated
7663 as relative to the current source directory.
7664 New in version 3.19: <dirs> may reference a binary direc‐
7666 tory.
7667 TARGET_DIRECTORY <targets>...
7670 The source file property will be set in each of the di‐
7671 rectory scopes where any of the specified <targets> were
7672 created (the <targets> must therefore already exist).
7673 See also the set_source_files_properties() command.
7676 INSTALL
7678 New in version 3.1.
7679 Scope may name zero or more installed file paths. These are
7682 made available to CPack to influence deployment.
7683 Both the property key and value may use generator expressions.
7685 Specific properties may apply to installed files and/or directo‐
7686 ries.
7687 Path components have to be separated by forward slashes, must be
7689 normalized and are case sensitive.
7690 To reference the installation prefix itself with a relative path
7692 use ..
7693 Currently installed file properties are only defined for the WIX
7695 generator where the given paths are relative to the installation
7696 prefix.
7697 TEST Scope is limited to the directory the command is called in. It
7699 may name zero or more existing tests. See also command
7700 set_tests_properties().
7701 Test property values may be specified using generator expres‐
7703 sions for tests created by the add_test(NAME) signature.
7704 CACHE Scope must name zero or more existing cache entries.
7706 The required PROPERTY option is immediately followed by the name of the
7708 property to set. Remaining arguments are used to compose the property
7709 value in the form of a semicolon-separated list.
7710 If the APPEND option is given the list is appended to any existing
7712 property value (except that empty values are ignored and not appended).
7713 If the APPEND_STRING option is given the string is appended to any ex‐
7714 isting property value as string, i.e. it results in a longer string and
7715 not a list of strings. When using APPEND or APPEND_STRING with a prop‐
7716 erty defined to support INHERITED behavior (see define_property()), no
7717 inheriting occurs when finding the initial value to append to. If the
7718 property is not already directly set in the nominated scope, the com‐
7719 mand will behave as though APPEND or APPEND_STRING had not been given.
7720 NOTE:
7722 The GENERATED source file property may be globally visible. See its
7723 documentation for details.
7724 See Also
7726 • define_property()
7727 • get_property()
7729 • The cmake-properties(7) manual for a list of properties in each
7731 scope.
7732 site_name
7734 Set the given variable to the name of the computer.
7735 site_name(variable)
7737 On UNIX-like platforms, if the variable HOSTNAME is set, its value will
7739 be executed as a command expected to print out the host name, much like
7740 the hostname command-line tool.
7741 string
7743 String operations.
7744 Synopsis
7746 Search and Replace
7747 string(FIND <string> <substring> <out-var> [...])
7748 string(REPLACE <match-string> <replace-string> <out-var> <input>...)
7749 string(REGEX MATCH <match-regex> <out-var> <input>...)
7750 string(REGEX MATCHALL <match-regex> <out-var> <input>...)
7751 string(REGEX REPLACE <match-regex> <replace-expr> <out-var> <input>...)
7752 Manipulation
7754 string(APPEND <string-var> [<input>...])
7755 string(PREPEND <string-var> [<input>...])
7756 string(CONCAT <out-var> [<input>...])
7757 string(JOIN <glue> <out-var> [<input>...])
7758 string(TOLOWER <string> <out-var>)
7759 string(TOUPPER <string> <out-var>)
7760 string(LENGTH <string> <out-var>)
7761 string(SUBSTRING <string> <begin> <length> <out-var>)
7762 string(STRIP <string> <out-var>)
7763 string(GENEX_STRIP <string> <out-var>)
7764 string(REPEAT <string> <count> <out-var>)
7765 Comparison
7767 string(COMPARE <op> <string1> <string2> <out-var>)
7768 Hashing
7770 string(<HASH> <out-var> <input>)
7771 Generation
7773 string(ASCII <number>... <out-var>)
7774 string(HEX <string> <out-var>)
7775 string(CONFIGURE <string> <out-var> [...])
7776 string(MAKE_C_IDENTIFIER <string> <out-var>)
7777 string(RANDOM [<option>...] <out-var>)
7778 string(TIMESTAMP <out-var> [<format string>] [UTC])
7779 string(UUID <out-var> ...)
7780 JSON
7782 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7783 {GET | TYPE | LENGTH | REMOVE}
7784 <json-string> <member|index> [<member|index> ...])
7785 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7786 MEMBER <json-string>
7787 [<member|index> ...] <index>)
7788 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7789 SET <json-string>
7790 <member|index> [<member|index> ...] <value>)
7791 string(JSON <out-var> [ERROR_VARIABLE <error-var>]
7792 EQUAL <json-string1> <json-string2>)
7793 Search and Replace
7795 Search and Replace With Plain Strings
7796 string(FIND <string> <substring> <output_variable> [REVERSE])
7797 Return the position where the given <substring> was found in the
7798 supplied <string>. If the REVERSE flag was used, the command
7799 will search for the position of the last occurrence of the spec‐
7800 ified <substring>. If the <substring> is not found, a position
7801 of -1 is returned.
7802 The string(FIND) subcommand treats all strings as ASCII-only
7804 characters. The index stored in <output_variable> will also be
7805 counted in bytes, so strings containing multi-byte characters
7806 may lead to unexpected results.
7807 string(REPLACE <match_string> <replace_string> <output_variable> <in‐
7809 put> [<input>...])
7810 Replace all occurrences of <match_string> in the <input> with
7811 <replace_string> and store the result in the <output_variable>.
7812 Search and Replace With Regular Expressions
7814 string(REGEX MATCH <regular_expression> <output_variable> <input> [<in‐
7815 put>...])
7816 Match the <regular_expression> once and store the match in the
7817 <output_variable>. All <input> arguments are concatenated be‐
7818 fore matching. Regular expressions are specified in the subsec‐
7819 tion just below.
7820 string(REGEX MATCHALL <regular_expression> <output_variable> <input>
7822 [<input>...])
7823 Match the <regular_expression> as many times as possible and
7824 store the matches in the <output_variable> as a list. All <in‐
7825 put> arguments are concatenated before matching.
7826 string(REGEX REPLACE <regular_expression> <replacement_expression>
7828 <output_variable> <input> [<input>...])
7829 Match the <regular_expression> as many times as possible and
7830 substitute the <replacement_expression> for the match in the
7831 output. All <input> arguments are concatenated before matching.
7832 The <replacement_expression> may refer to parenthesis-delimited
7834 subexpressions of the match using \1, \2, ..., \9. Note that
7835 two backslashes (\\1) are required in CMake code to get a back‐
7836 slash through argument parsing.
7837 Regex Specification
7839 The following characters have special meaning in regular expressions:
7840 ^ Matches at beginning of input
7842 $ Matches at end of input
7844 . Matches any single character
7846 \<char>
7848 Matches the single character specified by <char>. Use this to
7849 match special regex characters, e.g. \. for a literal . or \\
7850 for a literal backslash \. Escaping a non-special character is
7851 unnecessary but allowed, e.g. \a matches a.
7852 [ ] Matches any character(s) inside the brackets
7854 [^ ] Matches any character(s) not inside the brackets
7856 - Inside brackets, specifies an inclusive range between characters
7858 on either side e.g. [a-f] is [abcdef] To match a literal - using
7859 brackets, make it the first or the last character e.g. [+*/-]
7860 matches basic mathematical operators.
7861 * Matches preceding pattern zero or more times
7863 + Matches preceding pattern one or more times
7865 ? Matches preceding pattern zero or once only
7867 | Matches a pattern on either side of the |
7869 () Saves a matched subexpression, which can be referenced in the
7871 REGEX REPLACE operation.
7872 New in version 3.9: All regular expression-related commands, in‐
7874 cluding e.g. if(MATCHES), save subgroup matches in the vari‐
7875 ables CMAKE_MATCH_<n> for <n> 0..9.
7876 *, + and ? have higher precedence than concatenation. | has lower
7879 precedence than concatenation. This means that the regular expression
7880 ^ab+d$ matches abbd but not ababd, and the regular expression ^(ab|cd)$
7881 matches ab but not abd.
7882 CMake language Escape Sequences such as \t, \r, \n, and \\ may be used
7884 to construct literal tabs, carriage returns, newlines, and backslashes
7885 (respectively) to pass in a regex. For example:
7886 • The quoted argument "[ \t\r\n]" specifies a regex that matches any
7888 single whitespace character.
7889 • The quoted argument "[/\\]" specifies a regex that matches a single
7891 forward slash / or backslash \.
7892 • The quoted argument "[A-Za-z0-9_]" specifies a regex that matches any
7894 single "word" character in the C locale.
7895 • The quoted argument "\\(\\a\\+b\\)" specifies a regex that matches
7897 the exact string (a+b). Each \\ is parsed in a quoted argument as
7898 just \, so the regex itself is actually \(\a\+\b\). This can alter‐
7899 natively be specified in a Bracket Argument without having to escape
7900 the backslashes, e.g. [[\(\a\+\b\)]].
7901 Manipulation
7903 string(APPEND <string_variable> [<input>...])
7904 New in version 3.4.
7905 Append all the <input> arguments to the string.
7908 string(PREPEND <string_variable> [<input>...])
7910 New in version 3.10.
7911 Prepend all the <input> arguments to the string.
7914 string(CONCAT <output_variable> [<input>...])
7916 Concatenate all the <input> arguments together and store the re‐
7917 sult in the named <output_variable>.
7918 string(JOIN <glue> <output_variable> [<input>...])
7920 New in version 3.12.
7921 Join all the <input> arguments together using the <glue> string
7924 and store the result in the named <output_variable>.
7925 To join a list's elements, prefer to use the JOIN operator from
7927 the list() command. This allows for the elements to have spe‐
7928 cial characters like ; in them.
7929 string(TOLOWER <string> <output_variable>)
7931 Convert <string> to lower characters.
7932 string(TOUPPER <string> <output_variable>)
7934 Convert <string> to upper characters.
7935 string(LENGTH <string> <output_variable>)
7937 Store in an <output_variable> a given string's length in bytes.
7938 Note that this means if <string> contains multi-byte characters,
7939 the result stored in <output_variable> will not be the number of
7940 characters.
7941 string(SUBSTRING <string> <begin> <length> <output_variable>)
7943 Store in an <output_variable> a substring of a given <string>.
7944 If <length> is -1 the remainder of the string starting at <be‐
7945 gin> will be returned.
7946 Changed in version 3.2: If <string> is shorter than <length>
7948 then the end of the string is used instead. Previous versions
7949 of CMake reported an error in this case.
7950 Both <begin> and <length> are counted in bytes, so care must be
7953 exercised if <string> could contain multi-byte characters.
7954 string(STRIP <string> <output_variable>)
7956 Store in an <output_variable> a substring of a given <string>
7957 with leading and trailing spaces removed.
7958 string(GENEX_STRIP <string> <output_variable>)
7960 New in version 3.1.
7961 Strip any generator expressions from the input <string> and
7964 store the result in the <output_variable>.
7965 string(REPEAT <string> <count> <output_variable>)
7967 New in version 3.15.
7968 Produce the output string as the input <string> repeated <count>
7971 times.
7972 Comparison
7974 string(COMPARE LESS <string1> <string2> <output_variable>)
7975 string(COMPARE GREATER <string1> <string2> <output_variable>)
7977 string(COMPARE EQUAL <string1> <string2> <output_variable>)
7979 string(COMPARE NOTEQUAL <string1> <string2> <output_variable>)
7981 string(COMPARE LESS_EQUAL <string1> <string2> <output_variable>)
7983 string(COMPARE GREATER_EQUAL <string1> <string2> <output_variable>)
7985 Compare the strings and store true or false in the <output_vari‐
7986 able>.
7987 New in version 3.7: Added the LESS_EQUAL and GREATER_EQUAL op‐
7989 tions.
7990 Hashing
7993 string(<HASH> <output_variable> <input>)
7994 Compute a cryptographic hash of the <input> string. The sup‐
7995 ported <HASH> algorithm names are:
7996 MD5 Message-Digest Algorithm 5, RFC 1321.
7998 SHA1 US Secure Hash Algorithm 1, RFC 3174.
8000 SHA224 US Secure Hash Algorithms, RFC 4634.
8002 SHA256 US Secure Hash Algorithms, RFC 4634.
8004 SHA384 US Secure Hash Algorithms, RFC 4634.
8006 SHA512 US Secure Hash Algorithms, RFC 4634.
8008 SHA3_224
8010 Keccak SHA-3.
8011 SHA3_256
8013 Keccak SHA-3.
8014 SHA3_384
8016 Keccak SHA-3.
8017 SHA3_512
8019 Keccak SHA-3.
8020 New in version 3.8: Added the SHA3_* hash algorithms.
8022 Generation
8025 string(ASCII <number> [<number> ...] <output_variable>)
8026 Convert all numbers into corresponding ASCII characters.
8027 string(HEX <string> <output_variable>)
8029 New in version 3.18.
8030 Convert each byte in the input <string> to its hexadecimal rep‐
8033 resentation and store the concatenated hex digits in the <out‐
8034 put_variable>. Letters in the output (a through f) are in low‐
8035 ercase.
8036 string(CONFIGURE <string> <output_variable> [@ONLY] [ESCAPE_QUOTES])
8038 Transform a <string> like configure_file() transforms a file.
8039 string(MAKE_C_IDENTIFIER <string> <output_variable>)
8041 Convert each non-alphanumeric character in the input <string> to
8042 an underscore and store the result in the <output_variable>. If
8043 the first character of the <string> is a digit, an underscore
8044 will also be prepended to the result.
8045 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] [RAN‐
8047 DOM_SEED <seed>] <output_variable>)
8048 Return a random string of given <length> consisting of charac‐
8049 ters from the given <alphabet>. Default length is 5 characters
8050 and default alphabet is all numbers and upper and lower case
8051 letters. If an integer RANDOM_SEED is given, its value will be
8052 used to seed the random number generator.
8053 string(TIMESTAMP <output_variable> [<format_string>] [UTC])
8055 Write a string representation of the current date and/or time to
8056 the <output_variable>.
8057 If the command is unable to obtain a timestamp, the <out‐
8059 put_variable> will be set to the empty string "".
8060 The optional UTC flag requests the current date/time representa‐
8062 tion to be in Coordinated Universal Time (UTC) rather than local
8063 time.
8064 The optional <format_string> may contain the following format
8066 specifiers:
8067 %% New in version 3.8.
8069 A literal percent sign (%).
8072 %d The day of the current month (01-31).
8074 %H The hour on a 24-hour clock (00-23).
8076 %I The hour on a 12-hour clock (01-12).
8078 %j The day of the current year (001-366).
8080 %m The month of the current year (01-12).
8082 %b New in version 3.7.
8084 Abbreviated month name (e.g. Oct).
8087 %B New in version 3.10.
8089 Full month name (e.g. October).
8092 %M The minute of the current hour (00-59).
8094 %s New in version 3.6.
8096 Seconds since midnight (UTC) 1-Jan-1970 (UNIX time).
8099 %S The second of the current minute. 60 represents a leap
8101 second. (00-60)
8102 %f New in version 3.23.
8104 The microsecond of the current second (000000-999999).
8107 %U The week number of the current year (00-53).
8109 %V New in version 3.22.
8111 The ISO 8601 week number of the current year (01-53).
8114 %w The day of the current week. 0 is Sunday. (0-6)
8116 %a New in version 3.7.
8118 Abbreviated weekday name (e.g. Fri).
8121 %A New in version 3.10.
8123 Full weekday name (e.g. Friday).
8126 %y The last two digits of the current year (00-99).
8128 %Y The current year.
8130 %z New in version 3.26.
8132 The offset of the time zone from UTC, in hours and min‐
8135 utes, with format +hhmm or -hhmm.
8136 %Z New in version 3.26.
8138 The time zone name.
8141 Unknown format specifiers will be ignored and copied to the out‐
8143 put as-is.
8144 If no explicit <format_string> is given, it will default to:
8146 %Y-%m-%dT%H:%M:%S for local time.
8148 %Y-%m-%dT%H:%M:%SZ for UTC.
8149 New in version 3.8: If the SOURCE_DATE_EPOCH environment vari‐
8151 able is set, its value will be used instead of the current time.
8152 See https://reproducible-builds.org/specs/source-date-epoch/ for
8153 details.
8154 string(UUID <output_variable> NAMESPACE <namespace> NAME <name> TYPE
8157 <MD5|SHA1> [UPPER])
8158 New in version 3.1.
8159 Create a universally unique identifier (aka GUID) as per RFC4122
8162 based on the hash of the combined values of <namespace> (which
8163 itself has to be a valid UUID) and <name>. The hash algorithm
8164 can be either MD5 (Version 3 UUID) or SHA1 (Version 5 UUID). A
8165 UUID has the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where
8166 each x represents a lower case hexadecimal character. Where re‐
8167 quired, an uppercase representation can be requested with the
8168 optional UPPER flag.
8169 JSON
8171 New in version 3.19.
8172 Functionality for querying a JSON string.
8175 NOTE:
8177 In each of the following JSON-related subcommands, if the optional
8178 ERROR_VARIABLE argument is given, errors will be reported in <er‐
8179 ror-variable> and the <out-var> will be set to <member|index>-[<mem‐
8180 ber|index>...]-NOTFOUND with the path elements up to the point where
8181 the error occurred, or just NOTFOUND if there is no relevant path.
8182 If an error occurs but the ERROR_VARIABLE option is not present, a
8183 fatal error message is generated. If no error occurs, the <er‐
8184 ror-variable> will be set to NOTFOUND.
8185 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] GET
8187 <json-string> <member|index> [<member|index> ...])
8188 Get an element from <json-string> at the location given by the
8189 list of <member|index> arguments. Array and object elements
8190 will be returned as a JSON string. Boolean elements will be re‐
8191 turned as ON or OFF. Null elements will be returned as an empty
8192 string. Number and string types will be returned as strings.
8193 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] TYPE
8195 <json-string> <member|index> [<member|index> ...])
8196 Get the type of an element in <json-string> at the location
8197 given by the list of <member|index> arguments. The <out-var>
8198 will be set to one of NULL, NUMBER, STRING, BOOLEAN, ARRAY, or
8199 OBJECT.
8200 string(JSON <out-var> [ERROR_VARIABLE <error-var>] MEMBER <json-string>
8202 [<member|index> ...] <index>)
8203 Get the name of the <index>-th member in <json-string> at the
8204 location given by the list of <member|index> arguments. Re‐
8205 quires an element of object type.
8206 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] LENGTH
8208 <json-string> [<member|index> ...])
8209 Get the length of an element in <json-string> at the location
8210 given by the list of <member|index> arguments. Requires an ele‐
8211 ment of array or object type.
8212 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] REMOVE
8214 <json-string> <member|index> [<member|index> ...])
8215 Remove an element from <json-string> at the location given by
8216 the list of <member|index> arguments. The JSON string without
8217 the removed element will be stored in <out-var>.
8218 string(JSON <out-var> [ERROR_VARIABLE <error-variable>] SET
8220 <json-string> <member|index> [<member|index> ...] <value>)
8221 Set an element in <json-string> at the location given by the
8222 list of <member|index> arguments to <value>. The contents of
8223 <value> should be valid JSON. If <json-string> is an array,
8224 <value> can be appended to the end of the array by using a num‐
8225 ber greater or equal to the array length as the <member|index>
8226 argument.
8227 string(JSON <out-var> [ERROR_VARIABLE <error-var>] EQUAL <json-string1>
8229 <json-string2>)
8230 Compare the two JSON objects given by <json-string1> and
8231 <json-string2> for equality. The contents of <json-string1> and
8232 <json-string2> should be valid JSON. The <out-var> will be set
8233 to a true value if the JSON objects are considered equal, or a
8234 false value otherwise.
8235 unset
8237 Unset a variable, cache variable, or environment variable.
8238 Unset Normal Variable or Cache Entry
8240 unset(<variable> [CACHE | PARENT_SCOPE])
8241 Removes a normal variable from the current scope, causing it to become
8243 undefined. If CACHE is present, then a cache variable is removed in‐
8244 stead of a normal variable.
8245 If PARENT_SCOPE is present then the variable is removed from the scope
8247 above the current scope. See the same option in the set() command for
8248 further details.
8249 NOTE:
8251 When evaluating Variable References of the form ${VAR}, CMake first
8252 searches for a normal variable with that name. If no such normal
8253 variable exists, CMake will then search for a cache entry with that
8254 name. Because of this, unsetting a normal variable can expose a
8255 cache variable that was previously hidden. To force a variable ref‐
8256 erence of the form ${VAR} to return an empty string, use set(<vari‐
8257 able> ""), which clears the normal variable but leaves it defined.
8258 Unset Environment Variable
8260 unset(ENV{<variable>})
8261 Removes <variable> from the currently available Environment Variables.
8263 Subsequent calls of $ENV{<variable>} will return the empty string.
8264 This command affects only the current CMake process, not the process
8266 from which CMake was called, nor the system environment at large, nor
8267 the environment of subsequent build or test processes.
8268 See Also
8270 • set()
8271 variable_watch
8273 Watch the CMake variable for change.
8274 variable_watch(<variable> [<command>])
8276 If the specified <variable> changes and no <command> is given, a mes‐
8278 sage will be printed to inform about the change.
8279 If <command> is given, this command will be executed instead. The com‐
8281 mand will receive the following arguments: COMMAND(<variable> <access>
8282 <value> <current_list_file> <stack>)
8283 <variable>
8285 Name of the variable being accessed.
8286 <access>
8288 One of READ_ACCESS, UNKNOWN_READ_ACCESS, MODIFIED_ACCESS, UN‐
8289 KNOWN_MODIFIED_ACCESS, or REMOVED_ACCESS. The UNKNOWN_ values
8290 are only used when the variable has never been set. Once set,
8291 they are never used again during the same CMake run, even if the
8292 variable is later unset.
8293 <value>
8295 The value of the variable. On a modification, this is the new
8296 (modified) value of the variable. On removal, the value is
8297 empty.
8298 <current_list_file>
8300 Full path to the file doing the access.
8301 <stack>
8303 List of absolute paths of all files currently on the stack of
8304 file inclusion, with the bottom-most file first and the cur‐
8305 rently processed file (that is, current_list_file) last.
8306 Note that for some accesses such as list(APPEND), the watcher is exe‐
8308 cuted twice, first with a read access and then with a write one. Also
8309 note that an if(DEFINED) query on the variable does not register as an
8310 access and the watcher is not executed.
8311 Only non-cache variables can be watched using this command. Access to
8313 cache variables is never watched. However, the existence of a cache
8314 variable var causes accesses to the non-cache variable var to not use
8315 the UNKNOWN_ prefix, even if a non-cache variable var has never ex‐
8316 isted.
8317 while
8319 Evaluate a group of commands while a condition is true
8320 while(<condition>)
8322 <commands>
8323 endwhile()
8324 All commands between while and the matching endwhile() are recorded
8326 without being invoked. Once the endwhile() is evaluated, the recorded
8327 list of commands is invoked as long as the <condition> is true.
8328 The <condition> has the same syntax and is evaluated using the same
8330 logic as described at length for the if() command.
8331 The commands break() and continue() provide means to escape from the
8333 normal control flow.
8334 Per legacy, the endwhile() command admits an optional <condition> argu‐
8336 ment. If used, it must be a verbatim repeat of the argument of the
8337 opening while command.
8338 See Also
8340 • break()
8341 • continue()
8343 • foreach()
8345 • endwhile()
8347
8349 These commands are available only in CMake projects.
8350 add_compile_definitions
8352 New in version 3.12.
8353 Add preprocessor definitions to the compilation of source files.
8356 add_compile_definitions(<definition> ...)
8358 Adds preprocessor definitions to the compiler command line.
8360 The preprocessor definitions are added to the COMPILE_DEFINITIONS di‐
8362 rectory property for the current CMakeLists file. They are also added
8363 to the COMPILE_DEFINITIONS target property for each target in the cur‐
8364 rent CMakeLists file.
8365 Definitions are specified using the syntax VAR or VAR=value. Func‐
8367 tion-style definitions are not supported. CMake will automatically es‐
8368 cape the value correctly for the native build system (note that CMake
8369 language syntax may require escapes to specify some values).
8370 New in version 3.26: Any leading -D on an item will be removed.
8372 Arguments to add_compile_definitions may use generator expressions with
8375 the syntax $<...>. See the cmake-generator-expressions(7) manual for
8376 available expressions. See the cmake-buildsystem(7) manual for more on
8377 defining buildsystem properties.
8378 See Also
8380 • The command target_compile_definitions() adds target-specific defini‐
8381 tions.
8382 add_compile_options
8384 Add options to the compilation of source files.
8385 add_compile_options(<option> ...)
8387 Adds options to the COMPILE_OPTIONS directory property. These options
8389 are used when compiling targets from the current directory and below.
8390 NOTE:
8392 These options are not used when linking. See the add_link_options()
8393 command for that.
8394 Arguments
8396 Arguments to add_compile_options may use generator expressions with the
8397 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
8398 able expressions. See the cmake-buildsystem(7) manual for more on
8399 defining buildsystem properties.
8400 Option De-duplication
8402 The final set of options used for a target is constructed by accumulat‐
8403 ing options from the current target and the usage requirements of its
8404 dependencies. The set of options is de-duplicated to avoid repetition.
8405 New in version 3.12: While beneficial for individual options, the
8407 de-duplication step can break up option groups. For example, -option A
8408 -option B becomes -option A B. One may specify a group of options us‐
8409 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
8410 is dropped, and the rest of the option string is parsed using the
8411 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
8412 "SHELL:-option B" becomes -option A -option B.
8413 Example
8416 Since different compilers support different options, a typical use of
8417 this command is in a compiler-specific conditional clause:
8418 if (MSVC)
8420 # warning level 4
8421 add_compile_options(/W4)
8422 else()
8423 # additional warnings
8424 add_compile_options(-Wall -Wextra -Wpedantic)
8425 endif()
8426 To set per-language options, use the $<COMPILE_LANGUAGE> or
8428 $<COMPILE_LANGUAGE:languages> generator expressions.
8429 See Also
8431 • This command can be used to add any options. However, for adding pre‐
8432 processor definitions and include directories it is recommended to
8433 use the more specific commands add_compile_definitions() and
8434 include_directories().
8435 • The command target_compile_options() adds target-specific options.
8437 • This command adds compile options for all languages. Use the
8439 COMPILE_LANGUAGE generator expression to specify per-language compile
8440 options.
8441 • The source file property COMPILE_OPTIONS adds options to one source
8443 file.
8444 • add_link_options() adds options for linking.
8446 • CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> add language-wide
8448 flags passed to all invocations of the compiler. This includes invo‐
8449 cations that drive compiling and those that drive linking.
8450 add_custom_command
8452 Add a custom build rule to the generated build system.
8453 There are two main signatures for add_custom_command.
8455 Generating Files
8457 The first signature is for adding a custom command to produce an out‐
8458 put:
8459 add_custom_command(OUTPUT output1 [output2 ...]
8461 COMMAND command1 [ARGS] [args1...]
8462 [COMMAND command2 [ARGS] [args2...] ...]
8463 [MAIN_DEPENDENCY depend]
8464 [DEPENDS [depends...]]
8465 [BYPRODUCTS [files...]]
8466 [IMPLICIT_DEPENDS <lang1> depend1
8467 [<lang2> depend2] ...]
8468 [WORKING_DIRECTORY dir]
8469 [COMMENT comment]
8470 [DEPFILE depfile]
8471 [JOB_POOL job_pool]
8472 [VERBATIM] [APPEND] [USES_TERMINAL]
8473 [COMMAND_EXPAND_LISTS]
8474 [DEPENDS_EXPLICIT_ONLY])
8475 This defines a command to generate specified OUTPUT file(s). A target
8477 created in the same directory (CMakeLists.txt file) that specifies any
8478 output of the custom command as a source file is given a rule to gener‐
8479 ate the file using the command at build time.
8480 Do not list the output in more than one independent target that may
8482 build in parallel or the instances of the rule may conflict. Instead,
8483 use the add_custom_target() command to drive the command and make the
8484 other targets depend on that one. See the Example: Generating Files
8485 for Multiple Targets below.
8486 The options are:
8488 APPEND Append the COMMAND and DEPENDS option values to the custom com‐
8490 mand for the first output specified. There must have already
8491 been a previous call to this command with the same output.
8492 If the previous call specified the output via a generator ex‐
8494 pression, the output specified by the current call must match in
8495 at least one configuration after evaluating generator expres‐
8496 sions. In this case, the appended commands and dependencies ap‐
8497 ply to all configurations.
8498 The COMMENT, MAIN_DEPENDENCY, and WORKING_DIRECTORY options are
8500 currently ignored when APPEND is given, but may be used in the
8501 future.
8502 BYPRODUCTS
8504 New in version 3.2.
8505 Specify the files the command is expected to produce but whose
8508 modification time may or may not be newer than the dependencies.
8509 If a byproduct name is a relative path it will be interpreted
8510 relative to the build tree directory corresponding to the cur‐
8511 rent source directory. Each byproduct file will be marked with
8512 the GENERATED source file property automatically.
8513 See policy CMP0058 for the motivation behind this feature.
8515 Explicit specification of byproducts is supported by the Ninja
8517 generator to tell the ninja build tool how to regenerate byprod‐
8518 ucts when they are missing. It is also useful when other build
8519 rules (e.g. custom commands) depend on the byproducts. Ninja
8520 requires a build rule for any generated file on which another
8521 rule depends even if there are order-only dependencies to ensure
8522 the byproducts will be available before their dependents build.
8523 The Makefile Generators will remove BYPRODUCTS and other
8525 GENERATED files during make clean.
8526 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
8528 stricted set of generator expressions. Target-dependent expres‐
8529 sions are not permitted.
8530 COMMAND
8533 Specify the command-line(s) to execute at build time. If more
8534 than one COMMAND is specified they will be executed in order,
8535 but not necessarily composed into a stateful shell or batch
8536 script. (To run a full script, use the configure_file() command
8537 or the file(GENERATE) command to create it, and then specify a
8538 COMMAND to launch it.) The optional ARGS argument is for back‐
8539 ward compatibility and will be ignored.
8540 If COMMAND specifies an executable target name (created by the
8542 add_executable() command), it will automatically be replaced by
8543 the location of the executable created at build time if either
8544 of the following is true:
8545 • The target is not being cross-compiled (i.e. the
8547 CMAKE_CROSSCOMPILING variable is not set to true).
8548 • New in version 3.6: The target is being cross-compiled and an
8550 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
8551 property is set). In this case, the contents of
8552 CROSSCOMPILING_EMULATOR will be prepended to the command be‐
8553 fore the location of the target executable.
8554 If neither of the above conditions are met, it is assumed that
8557 the command name is a program to be found on the PATH at build
8558 time.
8559 Arguments to COMMAND may use generator expressions. Use the
8561 TARGET_FILE generator expression to refer to the location of a
8562 target later in the command line (i.e. as a command argument
8563 rather than as the command to execute).
8564 Whenever one of the following target based generator expressions
8566 are used as a command to execute or is mentioned in a command
8567 argument, a target-level dependency will be added automatically
8568 so that the mentioned target will be built before any target us‐
8569 ing this custom command (see policy CMP0112).
8570 • TARGET_FILE
8572 • TARGET_LINKER_FILE
8574 • TARGET_SONAME_FILE
8576 • TARGET_PDB_FILE
8578 This target-level dependency does NOT add a file-level depen‐
8580 dency that would cause the custom command to re-run whenever the
8581 executable is recompiled. List target names with the DEPENDS
8582 option to add such file-level dependencies.
8583 COMMENT
8585 Display the given message before the commands are executed at
8586 build time.
8587 New in version 3.26: Arguments to COMMENT may use generator ex‐
8589 pressions.
8590 DEPENDS
8593 Specify files on which the command depends. Each argument is
8594 converted to a dependency as follows:
8595 1. If the argument is the name of a target (created by the
8597 add_custom_target(), add_executable(), or add_library() com‐
8598 mand) a target-level dependency is created to make sure the
8599 target is built before any target using this custom command.
8600 Additionally, if the target is an executable or library, a
8601 file-level dependency is created to cause the custom command
8602 to re-run whenever the target is recompiled.
8603 2. If the argument is an absolute path, a file-level dependency
8605 is created on that path.
8606 3. If the argument is the name of a source file that has been
8608 added to a target or on which a source file property has been
8609 set, a file-level dependency is created on that source file.
8610 4. If the argument is a relative path and it exists in the cur‐
8612 rent source directory, a file-level dependency is created on
8613 that file in the current source directory.
8614 5. Otherwise, a file-level dependency is created on that path
8616 relative to the current binary directory.
8617 If any dependency is an OUTPUT of another custom command in the
8619 same directory (CMakeLists.txt file), CMake automatically brings
8620 the other custom command into the target in which this command
8621 is built.
8622 New in version 3.16: A target-level dependency is added if any
8624 dependency is listed as BYPRODUCTS of a target or any of its
8625 build events in the same directory to ensure the byproducts will
8626 be available.
8627 If DEPENDS is not specified, the command will run whenever the
8630 OUTPUT is missing; if the command does not actually create the
8631 OUTPUT, the rule will always run.
8632 New in version 3.1: Arguments to DEPENDS may use generator ex‐
8634 pressions.
8635 COMMAND_EXPAND_LISTS
8638 New in version 3.8.
8639 Lists in COMMAND arguments will be expanded, including those
8642 created with generator expressions, allowing COMMAND arguments
8643 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
8644 RIES>,;-I>" foo.cc to be properly expanded.
8645 IMPLICIT_DEPENDS
8647 Request scanning of implicit dependencies of an input file. The
8648 language given specifies the programming language whose corre‐
8649 sponding dependency scanner should be used. Currently only C
8650 and CXX language scanners are supported. The language has to be
8651 specified for every file in the IMPLICIT_DEPENDS list. Depen‐
8652 dencies discovered from the scanning are added to those of the
8653 custom command at build time. Note that the IMPLICIT_DEPENDS
8654 option is currently supported only for Makefile generators and
8655 will be ignored by other generators.
8656 NOTE:
8658 This option cannot be specified at the same time as DEPFILE
8659 option.
8660 JOB_POOL
8662 New in version 3.15.
8663 Specify a pool for the Ninja generator. Incompatible with
8666 USES_TERMINAL, which implies the console pool. Using a pool
8667 that is not defined by JOB_POOLS causes an error by ninja at
8668 build time.
8669 MAIN_DEPENDENCY
8671 Specify the primary input source file to the command. This is
8672 treated just like any value given to the DEPENDS option but also
8673 suggests to Visual Studio generators where to hang the custom
8674 command. Each source file may have at most one command specify‐
8675 ing it as its main dependency. A compile command (i.e. for a li‐
8676 brary or an executable) counts as an implicit main dependency
8677 which gets silently overwritten by a custom command specifica‐
8678 tion.
8679 OUTPUT Specify the output files the command is expected to produce.
8681 Each output file will be marked with the GENERATED source file
8682 property automatically. If the output of the custom command is
8683 not actually created as a file on disk it should be marked with
8684 the SYMBOLIC source file property.
8685 If an output file name is a relative path, its absolute path is
8687 determined by interpreting it relative to:
8688 1. the build directory corresponding to the current source di‐
8690 rectory (CMAKE_CURRENT_BINARY_DIR), or
8691 2. the current source directory (CMAKE_CURRENT_SOURCE_DIR).
8693 The path in the build directory is preferred unless the path in
8695 the source tree is mentioned as an absolute source file path
8696 elsewhere in the current directory.
8697 New in version 3.20: Arguments to OUTPUT may use a restricted
8699 set of generator expressions. Target-dependent expressions are
8700 not permitted.
8701 USES_TERMINAL
8704 New in version 3.2.
8705 The command will be given direct access to the terminal if pos‐
8708 sible. With the Ninja generator, this places the command in the
8709 console pool.
8710 VERBATIM
8712 All arguments to the commands will be escaped properly for the
8713 build tool so that the invoked command receives each argument
8714 unchanged. Note that one level of escapes is still used by the
8715 CMake language processor before add_custom_command even sees the
8716 arguments. Use of VERBATIM is recommended as it enables correct
8717 behavior. When VERBATIM is not given the behavior is platform
8718 specific because there is no protection of tool-specific special
8719 characters.
8720 WORKING_DIRECTORY
8722 Execute the command with the given current working directory.
8723 If it is a relative path it will be interpreted relative to the
8724 build tree directory corresponding to the current source direc‐
8725 tory.
8726 New in version 3.13: Arguments to WORKING_DIRECTORY may use
8728 generator expressions.
8729 DEPFILE
8732 New in version 3.7.
8733 Specify a depfile which holds dependencies for the custom com‐
8736 mand. It is usually emitted by the custom command itself. This
8737 keyword may only be used if the generator supports it, as de‐
8738 tailed below.
8739 The expected format, compatible with what is generated by gcc
8741 with the option -M, is independent of the generator or platform.
8742 The formal syntax, as specified using BNF notation with the reg‐
8744 ular extensions, is the following:
8745 depfile ::= rule*
8747 rule ::= targets (':' (separator dependencies?)?)? eol
8748 targets ::= target (separator target)* separator*
8749 target ::= pathname
8750 dependencies ::= dependency (separator dependency)* separator*
8751 dependency ::= pathname
8752 separator ::= (space | line_continue)+
8753 line_continue ::= '\' eol
8754 space ::= ' ' | '\t'
8755 pathname ::= character+
8756 character ::= std_character | dollar | hash | whitespace
8757 std_character ::= <any character except '$', '#' or ' '>
8758 dollar ::= '$$'
8759 hash ::= '\#'
8760 whitespace ::= '\ '
8761 eol ::= '\r'? '\n'
8762 NOTE:
8765 As part of pathname, any slash and backslash is interpreted
8766 as a directory separator.
8767 New in version 3.7: The Ninja generator supports DEPFILE since
8769 the keyword was first added.
8770 New in version 3.17: Added the Ninja Multi-Config generator,
8773 which included support for the DEPFILE keyword.
8774 New in version 3.20: Added support for Makefile Generators.
8777 NOTE:
8779 DEPFILE cannot be specified at the same time as the IM‐
8780 PLICIT_DEPENDS option for Makefile Generators.
8781 New in version 3.21: Added support for Visual Studio Generators
8784 with VS 2012 and above, and for the Xcode generator. Support
8785 for generator expressions was also added.
8786 Using DEPFILE with generators other than those listed above is
8789 an error.
8790 If the DEPFILE argument is relative, it should be relative to
8792 CMAKE_CURRENT_BINARY_DIR, and any relative paths inside the DEP‐
8793 FILE should also be relative to CMAKE_CURRENT_BINARY_DIR. See
8794 policy CMP0116, which is always NEW for Makefile Generators,
8795 Visual Studio Generators, and the Xcode generator.
8796 DEPENDS_EXPLICIT_ONLY
8798 New in version 3.27.
8799 Indicates that the command's DEPENDS argument represents all files
8802 required by the command and implicit dependencies are not required.
8803 Without this option, if any target uses the output of the custom
8805 command, CMake will consider that target's dependencies as implicit
8806 dependencies for the custom command in case this custom command re‐
8807 quires files implicitly created by those targets.
8808 This option can be enabled on all custom commands by setting
8810 CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY to ON.
8811 Only the Ninja Generators actually use this information to remove
8813 unnecessary implicit dependencies.
8814 See also the OPTIMIZE_DEPENDENCIES target property, which may pro‐
8816 vide another way for reducing the impact of target dependencies in
8817 some scenarios.
8818 Examples: Generating Files
8820 Custom commands may be used to generate source files. For example, the
8821 code:
8822 add_custom_command(
8824 OUTPUT out.c
8825 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8826 -o out.c
8827 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8828 VERBATIM)
8829 add_library(myLib out.c)
8830 adds a custom command to run someTool to generate out.c and then com‐
8832 pile the generated source as part of a library. The generation rule
8833 will re-run whenever in.txt changes.
8834 New in version 3.20: One may use generator expressions to specify
8836 per-configuration outputs. For example, the code:
8837 add_custom_command(
8839 OUTPUT "out-$<CONFIG>.c"
8840 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8841 -o "out-$<CONFIG>.c"
8842 -c "$<CONFIG>"
8843 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
8844 VERBATIM)
8845 add_library(myLib "out-$<CONFIG>.c")
8846 adds a custom command to run someTool to generate out-<config>.c, where
8848 <config> is the build configuration, and then compile the generated
8849 source as part of a library.
8850 Example: Generating Files for Multiple Targets
8853 If multiple independent targets need the same custom command output, it
8854 must be attached to a single custom target on which they all depend.
8855 Consider the following example:
8856 add_custom_command(
8858 OUTPUT table.csv
8859 COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
8860 -o table.csv
8861 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
8862 VERBATIM)
8863 add_custom_target(generate_table_csv DEPENDS table.csv)
8864 add_custom_command(
8866 OUTPUT foo.cxx
8867 COMMAND genFromTable -i table.csv -case foo -o foo.cxx
8868 DEPENDS table.csv # file-level dependency
8869 generate_table_csv # target-level dependency
8870 VERBATIM)
8871 add_library(foo foo.cxx)
8872 add_custom_command(
8874 OUTPUT bar.cxx
8875 COMMAND genFromTable -i table.csv -case bar -o bar.cxx
8876 DEPENDS table.csv # file-level dependency
8877 generate_table_csv # target-level dependency
8878 VERBATIM)
8879 add_library(bar bar.cxx)
8880 Output foo.cxx is needed only by target foo and output bar.cxx is
8882 needed only by target bar, but both targets need table.csv, transi‐
8883 tively. Since foo and bar are independent targets that may build con‐
8884 currently, we prevent them from racing to generate table.csv by placing
8885 its custom command in a separate target, generate_table_csv. The cus‐
8886 tom commands generating foo.cxx and bar.cxx each specify a target-level
8887 dependency on generate_table_csv, so the targets using them, foo and
8888 bar, will not build until after target generate_table_csv is built.
8889 Build Events
8891 The second signature adds a custom command to a target such as a li‐
8892 brary or executable. This is useful for performing an operation before
8893 or after building the target. The command becomes part of the target
8894 and will only execute when the target itself is built. If the target
8895 is already built, the command will not execute.
8896 add_custom_command(TARGET <target>
8898 PRE_BUILD | PRE_LINK | POST_BUILD
8899 COMMAND command1 [ARGS] [args1...]
8900 [COMMAND command2 [ARGS] [args2...] ...]
8901 [BYPRODUCTS [files...]]
8902 [WORKING_DIRECTORY dir]
8903 [COMMENT comment]
8904 [VERBATIM]
8905 [COMMAND_EXPAND_LISTS])
8906 This defines a new command that will be associated with building the
8908 specified <target>. The <target> must be defined in the current direc‐
8909 tory; targets defined in other directories may not be specified.
8910 When the command will happen is determined by which of the following is
8912 specified:
8913 PRE_BUILD
8915 This option has unique behavior for the Visual Studio Genera‐
8916 tors. When using one of the Visual Studio generators, the com‐
8917 mand will run before any other rules are executed within the
8918 target. With all other generators, this option behaves the same
8919 as PRE_LINK instead. Because of this, it is recommended to
8920 avoid using PRE_BUILD except when it is known that a Visual Stu‐
8921 dio generator is being used.
8922 PRE_LINK
8924 Run after sources have been compiled but before linking the bi‐
8925 nary or running the librarian or archiver tool of a static li‐
8926 brary. This is not defined for targets created by the
8927 add_custom_target() command.
8928 POST_BUILD
8930 Run after all other rules within the target have been executed.
8931 Projects should always specify one of the above three keywords when us‐
8933 ing the TARGET form. For backward compatibility reasons, POST_BUILD is
8934 assumed if no such keyword is given, but projects should explicitly
8935 provide one of the keywords to make clear the behavior they expect.
8936 NOTE:
8938 Because generator expressions can be used in custom commands, it is
8939 possible to define COMMAND lines or whole custom commands which
8940 evaluate to empty strings for certain configurations. For Visual
8941 Studio 11 2012 (and newer) generators these command lines or custom
8942 commands will be omitted for the specific configuration and no
8943 "empty-string-command" will be added.
8944 This allows to add individual build events for every configuration.
8946 New in version 3.21: Support for target-dependent generator expres‐
8948 sions.
8949 Examples: Build Events
8952 A POST_BUILD event may be used to post-process a binary after linking.
8953 For example, the code:
8954 add_executable(myExe myExe.c)
8956 add_custom_command(
8957 TARGET myExe POST_BUILD
8958 COMMAND someHasher -i "$<TARGET_FILE:myExe>"
8959 -o "$<TARGET_FILE:myExe>.hash"
8960 VERBATIM)
8961 will run someHasher to produce a .hash file next to the executable af‐
8963 ter linking.
8964 New in version 3.20: One may use generator expressions to specify
8966 per-configuration byproducts. For example, the code:
8967 add_library(myPlugin MODULE myPlugin.c)
8969 add_custom_command(
8970 TARGET myPlugin POST_BUILD
8971 COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
8972 --as-code "myPlugin-hash-$<CONFIG>.c"
8973 BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
8974 VERBATIM)
8975 add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
8976 will run someHasher after linking myPlugin, e.g. to produce a .c file
8978 containing code to check the hash of myPlugin that the myExe executable
8979 can use to verify it before loading.
8980 Ninja Multi-Config
8983 New in version 3.20: add_custom_command supports the Ninja Multi-Config
8984 generator's cross-config capabilities. See the generator documentation
8985 for more information.
8986 See Also
8989 • add_custom_target()
8990 add_custom_target
8992 Add a target with no output so it will always be built.
8993 add_custom_target(Name [ALL] [command1 [args1...]]
8995 [COMMAND command2 [args2...] ...]
8996 [DEPENDS depend depend depend ... ]
8997 [BYPRODUCTS [files...]]
8998 [WORKING_DIRECTORY dir]
8999 [COMMENT comment]
9000 [JOB_POOL job_pool]
9001 [VERBATIM] [USES_TERMINAL]
9002 [COMMAND_EXPAND_LISTS]
9003 [SOURCES src1 [src2...]])
9004 Adds a target with the given name that executes the given commands.
9006 The target has no output file and is always considered out of date even
9007 if the commands try to create a file with the name of the target. Use
9008 the add_custom_command() command to generate a file with dependencies.
9009 By default nothing depends on the custom target. Use the
9010 add_dependencies() command to add dependencies to or from other tar‐
9011 gets.
9012 The options are:
9014 ALL Indicate that this target should be added to the default build
9016 target so that it will be run every time (the command cannot be
9017 called ALL).
9018 BYPRODUCTS
9020 New in version 3.2.
9021 Specify the files the command is expected to produce but whose
9024 modification time may or may not be updated on subsequent
9025 builds. If a byproduct name is a relative path it will be in‐
9026 terpreted relative to the build tree directory corresponding to
9027 the current source directory. Each byproduct file will be
9028 marked with the GENERATED source file property automatically.
9029 See policy CMP0058 for the motivation behind this feature.
9031 Explicit specification of byproducts is supported by the Ninja
9033 generator to tell the ninja build tool how to regenerate byprod‐
9034 ucts when they are missing. It is also useful when other build
9035 rules (e.g. custom commands) depend on the byproducts. Ninja
9036 requires a build rule for any generated file on which another
9037 rule depends even if there are order-only dependencies to ensure
9038 the byproducts will be available before their dependents build.
9039 The Makefile Generators will remove BYPRODUCTS and other
9041 GENERATED files during make clean.
9042 New in version 3.20: Arguments to BYPRODUCTS may use a re‐
9044 stricted set of generator expressions. Target-dependent expres‐
9045 sions are not permitted.
9046 COMMAND
9049 Specify the command-line(s) to execute at build time. If more
9050 than one COMMAND is specified they will be executed in order,
9051 but not necessarily composed into a stateful shell or batch
9052 script. (To run a full script, use the configure_file() command
9053 or the file(GENERATE) command to create it, and then specify a
9054 COMMAND to launch it.)
9055 If COMMAND specifies an executable target name (created by the
9057 add_executable() command), it will automatically be replaced by
9058 the location of the executable created at build time if either
9059 of the following is true:
9060 • The target is not being cross-compiled (i.e. the
9062 CMAKE_CROSSCOMPILING variable is not set to true).
9063 • New in version 3.6: The target is being cross-compiled and an
9065 emulator is provided (i.e. its CROSSCOMPILING_EMULATOR target
9066 property is set). In this case, the contents of
9067 CROSSCOMPILING_EMULATOR will be prepended to the command be‐
9068 fore the location of the target executable.
9069 If neither of the above conditions are met, it is assumed that
9072 the command name is a program to be found on the PATH at build
9073 time.
9074 Arguments to COMMAND may use generator expressions. Use the
9076 TARGET_FILE generator expression to refer to the location of a
9077 target later in the command line (i.e. as a command argument
9078 rather than as the command to execute).
9079 Whenever one of the following target based generator expressions
9081 are used as a command to execute or is mentioned in a command
9082 argument, a target-level dependency will be added automatically
9083 so that the mentioned target will be built before this custom
9084 target (see policy CMP0112).
9085 • TARGET_FILE
9087 • TARGET_LINKER_FILE
9089 • TARGET_SONAME_FILE
9091 • TARGET_PDB_FILE
9093 The command and arguments are optional and if not specified an
9095 empty target will be created.
9096 COMMENT
9098 Display the given message before the commands are executed at
9099 build time.
9100 New in version 3.26: Arguments to COMMENT may use generator ex‐
9102 pressions.
9103 DEPENDS
9106 Reference files and outputs of custom commands created with
9107 add_custom_command() command calls in the same directory (CMake‐
9108 Lists.txt file). They will be brought up to date when the tar‐
9109 get is built.
9110 Changed in version 3.16: A target-level dependency is added if
9112 any dependency is a byproduct of a target or any of its build
9113 events in the same directory to ensure the byproducts will be
9114 available before this target is built.
9115 Use the add_dependencies() command to add dependencies on other
9118 targets.
9119 COMMAND_EXPAND_LISTS
9121 New in version 3.8.
9122 Lists in COMMAND arguments will be expanded, including those
9125 created with generator expressions, allowing COMMAND arguments
9126 such as ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTO‐
9127 RIES>,;-I>" foo.cc to be properly expanded.
9128 JOB_POOL
9130 New in version 3.15.
9131 Specify a pool for the Ninja generator. Incompatible with
9134 USES_TERMINAL, which implies the console pool. Using a pool
9135 that is not defined by JOB_POOLS causes an error by ninja at
9136 build time.
9137 SOURCES
9139 Specify additional source files to be included in the custom
9140 target. Specified source files will be added to IDE project
9141 files for convenience in editing even if they have no build
9142 rules.
9143 VERBATIM
9145 All arguments to the commands will be escaped properly for the
9146 build tool so that the invoked command receives each argument
9147 unchanged. Note that one level of escapes is still used by the
9148 CMake language processor before add_custom_target even sees the
9149 arguments. Use of VERBATIM is recommended as it enables correct
9150 behavior. When VERBATIM is not given the behavior is platform
9151 specific because there is no protection of tool-specific special
9152 characters.
9153 USES_TERMINAL
9155 New in version 3.2.
9156 The command will be given direct access to the terminal if pos‐
9159 sible. With the Ninja generator, this places the command in the
9160 console pool.
9161 WORKING_DIRECTORY
9163 Execute the command with the given current working directory.
9164 If it is a relative path it will be interpreted relative to the
9165 build tree directory corresponding to the current source direc‐
9166 tory.
9167 New in version 3.13: Arguments to WORKING_DIRECTORY may use
9169 generator expressions.
9170 Ninja Multi-Config
9173 New in version 3.20: add_custom_target supports the Ninja Multi-Config
9174 generator's cross-config capabilities. See the generator documentation
9175 for more information.
9176 See Also
9179 • add_custom_command()
9180 add_definitions
9182 Add -D define flags to the compilation of source files.
9183 add_definitions(-DFOO -DBAR ...)
9185 Adds definitions to the compiler command line for targets in the cur‐
9187 rent directory, whether added before or after this command is invoked,
9188 and for the ones in sub-directories added after. This command can be
9189 used to add any flags, but it is intended to add preprocessor defini‐
9190 tions.
9191 NOTE:
9193 This command has been superseded by alternatives:
9194 • Use add_compile_definitions() to add preprocessor definitions.
9196 • Use include_directories() to add include directories.
9198 • Use add_compile_options() to add other options.
9200 Flags beginning in -D or /D that look like preprocessor definitions are
9202 automatically added to the COMPILE_DEFINITIONS directory property for
9203 the current directory. Definitions with non-trivial values may be left
9204 in the set of flags instead of being converted for reasons of backwards
9205 compatibility. See documentation of the directory, target, source file
9206 COMPILE_DEFINITIONS properties for details on adding preprocessor defi‐
9207 nitions to specific scopes and configurations.
9208 See Also
9210 • The cmake-buildsystem(7) manual for more on defining buildsystem
9211 properties.
9212 add_dependencies
9214 Add a dependency between top-level targets.
9215 add_dependencies(<target> [<target-dependency>]...)
9217 Makes a top-level <target> depend on other top-level targets to ensure
9219 that they build before <target> does. A top-level target is one cre‐
9220 ated by one of the add_executable(), add_library(), or
9221 add_custom_target() commands (but not targets generated by CMake like
9222 install).
9223 Dependencies added to an imported target or an interface library are
9225 followed transitively in its place since the target itself does not
9226 build.
9227 New in version 3.3: Allow adding dependencies to interface libraries.
9229 See Also
9232 • The DEPENDS option of add_custom_target() and add_custom_command()
9233 commands for adding file-level dependencies in custom rules.
9234 • The OBJECT_DEPENDS source file property to add file-level dependen‐
9236 cies to object files.
9237 add_executable
9239 Add an executable to the project using the specified source files.
9240 Normal Executables
9242 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
9243 [EXCLUDE_FROM_ALL]
9244 [source1] [source2 ...])
9245 Adds an executable target called <name> to be built from the source
9247 files listed in the command invocation. The <name> corresponds to the
9248 logical target name and must be globally unique within a project. The
9249 actual file name of the executable built is constructed based on con‐
9250 ventions of the native platform (such as <name>.exe or just <name>).
9251 New in version 3.1: Source arguments to add_executable may use "genera‐
9253 tor expressions" with the syntax $<...>. See the
9254 cmake-generator-expressions(7) manual for available expressions.
9255 New in version 3.11: The source files can be omitted if they are added
9258 later using target_sources().
9259 By default the executable file will be created in the build tree direc‐
9262 tory corresponding to the source tree directory in which the command
9263 was invoked. See documentation of the RUNTIME_OUTPUT_DIRECTORY target
9264 property to change this location. See documentation of the OUTPUT_NAME
9265 target property to change the <name> part of the final file name.
9266 If WIN32 is given the property WIN32_EXECUTABLE will be set on the tar‐
9268 get created. See documentation of that target property for details.
9269 If MACOSX_BUNDLE is given the corresponding property will be set on the
9271 created target. See documentation of the MACOSX_BUNDLE target property
9272 for details.
9273 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
9275 the created target. See documentation of the EXCLUDE_FROM_ALL target
9276 property for details.
9277 See the cmake-buildsystem(7) manual for more on defining buildsystem
9279 properties.
9280 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
9282 cessed, and you want to have the original sources reachable from within
9283 IDE.
9284 Imported Executables
9286 add_executable(<name> IMPORTED [GLOBAL])
9287 An IMPORTED executable target references an executable file located
9289 outside the project. No rules are generated to build it, and the
9290 IMPORTED target property is True. The target name has scope in the di‐
9291 rectory in which it is created and below, but the GLOBAL option extends
9292 visibility. It may be referenced like any target built within the
9293 project. IMPORTED executables are useful for convenient reference from
9294 commands like add_custom_command(). Details about the imported exe‐
9295 cutable are specified by setting properties whose names begin in IM‐
9296 PORTED_. The most important such property is IMPORTED_LOCATION (and
9297 its per-configuration version IMPORTED_LOCATION_<CONFIG>) which speci‐
9298 fies the location of the main executable file on disk. See documenta‐
9299 tion of the IMPORTED_* properties for more information.
9300 Alias Executables
9302 add_executable(<name> ALIAS <target>)
9303 Creates an Alias Target, such that <name> can be used to refer to <tar‐
9305 get> in subsequent commands. The <name> does not appear in the gener‐
9306 ated buildsystem as a make target. The <target> may not be an ALIAS.
9307 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
9309 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
9312 Such alias is scoped to the directory in which it is created and subdi‐
9313 rectories. The ALIAS_GLOBAL target property can be used to check if
9314 the alias is global or not.
9315 ALIAS targets can be used as targets to read properties from, executa‐
9318 bles for custom commands and custom targets. They can also be tested
9319 for existence with the regular if(TARGET) subcommand. The <name> may
9320 not be used to modify properties of <target>, that is, it may not be
9321 used as the operand of set_property(), set_target_properties(),
9322 target_link_libraries() etc. An ALIAS target may not be installed or
9323 exported.
9324 See Also
9326 • add_library()
9327 add_library
9329 Add a library to the project using the specified source files.
9330 Normal Libraries
9332 add_library(<name> [STATIC | SHARED | MODULE]
9333 [EXCLUDE_FROM_ALL]
9334 [<source>...])
9335 Adds a library target called <name> to be built from the source files
9337 listed in the command invocation. The <name> corresponds to the logi‐
9338 cal target name and must be globally unique within a project. The ac‐
9339 tual file name of the library built is constructed based on conventions
9340 of the native platform (such as lib<name>.a or <name>.lib).
9341 New in version 3.1: Source arguments to add_library may use "generator
9343 expressions" with the syntax $<...>. See the
9344 cmake-generator-expressions(7) manual for available expressions.
9345 New in version 3.11: The source files can be omitted if they are added
9348 later using target_sources().
9349 STATIC, SHARED, or MODULE may be given to specify the type of library
9352 to be created. STATIC libraries are archives of object files for use
9353 when linking other targets. SHARED libraries are linked dynamically
9354 and loaded at runtime. MODULE libraries are plugins that are not
9355 linked into other targets but may be loaded dynamically at runtime us‐
9356 ing dlopen-like functionality. If no type is given explicitly the type
9357 is STATIC or SHARED based on whether the current value of the variable
9358 BUILD_SHARED_LIBS is ON. For SHARED and MODULE libraries the
9359 POSITION_INDEPENDENT_CODE target property is set to ON automatically.
9360 A SHARED library may be marked with the FRAMEWORK target property to
9361 create an macOS Framework.
9362 New in version 3.8: A STATIC library may be marked with the FRAMEWORK
9364 target property to create a static Framework.
9365 If a library does not export any symbols, it must not be declared as a
9368 SHARED library. For example, a Windows resource DLL or a managed
9369 C++/CLI DLL that exports no unmanaged symbols would need to be a MODULE
9370 library. This is because CMake expects a SHARED library to always have
9371 an associated import library on Windows.
9372 By default the library file will be created in the build tree directory
9374 corresponding to the source tree directory in which the command was in‐
9375 voked. See documentation of the ARCHIVE_OUTPUT_DIRECTORY,
9376 LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY target proper‐
9377 ties to change this location. See documentation of the OUTPUT_NAME
9378 target property to change the <name> part of the final file name.
9379 If EXCLUDE_FROM_ALL is given the corresponding property will be set on
9381 the created target. See documentation of the EXCLUDE_FROM_ALL target
9382 property for details.
9383 See the cmake-buildsystem(7) manual for more on defining buildsystem
9385 properties.
9386 See also HEADER_FILE_ONLY on what to do if some sources are pre-pro‐
9388 cessed, and you want to have the original sources reachable from within
9389 IDE.
9390 Object Libraries
9392 add_library(<name> OBJECT [<source>...])
9393 Creates an Object Library. An object library compiles source files but
9395 does not archive or link their object files into a library. Instead
9396 other targets created by add_library or add_executable() may reference
9397 the objects using an expression of the form $<TARGET_OBJECTS:objlib> as
9398 a source, where objlib is the object library name. For example:
9399 add_library(... $<TARGET_OBJECTS:objlib> ...)
9401 add_executable(... $<TARGET_OBJECTS:objlib> ...)
9402 will include objlib's object files in a library and an executable along
9404 with those compiled from their own sources. Object libraries may con‐
9405 tain only sources that compile, header files, and other files that
9406 would not affect linking of a normal library (e.g. .txt). They may
9407 contain custom commands generating such sources, but not PRE_BUILD,
9408 PRE_LINK, or POST_BUILD commands. Some native build systems (such as
9409 Xcode) may not like targets that have only object files, so consider
9410 adding at least one real source file to any target that references
9411 $<TARGET_OBJECTS:objlib>.
9412 New in version 3.12: Object libraries can be linked to with
9414 target_link_libraries().
9415 Interface Libraries
9418 add_library(<name> INTERFACE)
9419 Creates an Interface Library. An INTERFACE library target does not
9421 compile sources and does not produce a library artifact on disk. How‐
9422 ever, it may have properties set on it and it may be installed and ex‐
9423 ported. Typically, INTERFACE_* properties are populated on an inter‐
9424 face target using the commands:
9425 • set_property(),
9427 • target_link_libraries(INTERFACE),
9429 • target_link_options(INTERFACE),
9431 • target_include_directories(INTERFACE),
9433 • target_compile_options(INTERFACE),
9435 • target_compile_definitions(INTERFACE), and
9437 • target_sources(INTERFACE),
9439 and then it is used as an argument to target_link_libraries() like any
9441 other target.
9442 An interface library created with the above signature has no source
9444 files itself and is not included as a target in the generated buildsys‐
9445 tem.
9446 New in version 3.15: An interface library can have PUBLIC_HEADER and
9448 PRIVATE_HEADER properties. The headers specified by those properties
9449 can be installed using the install(TARGETS) command.
9450 New in version 3.19: An interface library target may be created with
9453 source files:
9454 add_library(<name> INTERFACE [<source>...] [EXCLUDE_FROM_ALL])
9456 Source files may be listed directly in the add_library call or added
9458 later by calls to target_sources() with the PRIVATE or PUBLIC keywords.
9459 If an interface library has source files (i.e. the SOURCES target prop‐
9461 erty is set), or header sets (i.e. the HEADER_SETS target property is
9462 set), it will appear in the generated buildsystem as a build target
9463 much like a target defined by the add_custom_target() command. It does
9464 not compile any sources, but does contain build rules for custom com‐
9465 mands created by the add_custom_command() command.
9466 NOTE:
9469 In most command signatures where the INTERFACE keyword appears, the
9470 items listed after it only become part of that target's usage re‐
9471 quirements and are not part of the target's own settings. However,
9472 in this signature of add_library, the INTERFACE keyword refers to
9473 the library type only. Sources listed after it in the add_library
9474 call are PRIVATE to the interface library and do not appear in its
9475 INTERFACE_SOURCES target property.
9476 Imported Libraries
9478 add_library(<name> <type> IMPORTED [GLOBAL])
9479 Creates an IMPORTED library target called <name>. No rules are gener‐
9481 ated to build it, and the IMPORTED target property is True. The target
9482 name has scope in the directory in which it is created and below, but
9483 the GLOBAL option extends visibility. It may be referenced like any
9484 target built within the project. IMPORTED libraries are useful for
9485 convenient reference from commands like target_link_libraries(). De‐
9486 tails about the imported library are specified by setting properties
9487 whose names begin in IMPORTED_ and INTERFACE_.
9488 The <type> must be one of:
9490 STATIC, SHARED, MODULE, UNKNOWN
9492 References a library file located outside the project. The
9493 IMPORTED_LOCATION target property (or its per-configuration
9494 variant IMPORTED_LOCATION_<CONFIG>) specifies the location of
9495 the main library file on disk:
9496 • For a SHARED library on most non-Windows platforms, the main
9498 library file is the .so or .dylib file used by both linkers
9499 and dynamic loaders. If the referenced library file has a
9500 SONAME (or on macOS, has a LC_ID_DYLIB starting in @rpath/),
9501 the value of that field should be set in the IMPORTED_SONAME
9502 target property. If the referenced library file does not have
9503 a SONAME, but the platform supports it, then the
9504 IMPORTED_NO_SONAME target property should be set.
9505 • For a SHARED library on Windows, the IMPORTED_IMPLIB target
9507 property (or its per-configuration variant
9508 IMPORTED_IMPLIB_<CONFIG>) specifies the location of the DLL
9509 import library file (.lib or .dll.a) on disk, and the IM‐
9510 PORTED_LOCATION is the location of the .dll runtime library
9511 (and is optional, but needed by the TARGET_RUNTIME_DLLS gener‐
9512 ator expression).
9513 Additional usage requirements may be specified in INTERFACE_*
9515 properties.
9516 An UNKNOWN library type is typically only used in the implemen‐
9518 tation of Find Modules. It allows the path to an imported li‐
9519 brary (often found using the find_library() command) to be used
9520 without having to know what type of library it is. This is es‐
9521 pecially useful on Windows where a static library and a DLL's
9522 import library both have the same file extension.
9523 OBJECT References a set of object files located outside the project.
9525 The IMPORTED_OBJECTS target property (or its per-configuration
9526 variant IMPORTED_OBJECTS_<CONFIG>) specifies the locations of
9527 object files on disk. Additional usage requirements may be
9528 specified in INTERFACE_* properties.
9529 INTERFACE
9531 Does not reference any library or object files on disk, but may
9532 specify usage requirements in INTERFACE_* properties.
9533 See documentation of the IMPORTED_* and INTERFACE_* properties for more
9535 information.
9536 Alias Libraries
9538 add_library(<name> ALIAS <target>)
9539 Creates an Alias Target, such that <name> can be used to refer to <tar‐
9541 get> in subsequent commands. The <name> does not appear in the gener‐
9542 ated buildsystem as a make target. The <target> may not be an ALIAS.
9543 New in version 3.11: An ALIAS can target a GLOBAL Imported Target
9545 New in version 3.18: An ALIAS can target a non-GLOBAL Imported Target.
9548 Such alias is scoped to the directory in which it is created and below.
9549 The ALIAS_GLOBAL target property can be used to check if the alias is
9550 global or not.
9551 ALIAS targets can be used as linkable targets and as targets to read
9554 properties from. They can also be tested for existence with the regu‐
9555 lar if(TARGET) subcommand. The <name> may not be used to modify prop‐
9556 erties of <target>, that is, it may not be used as the operand of
9557 set_property(), set_target_properties(), target_link_libraries() etc.
9558 An ALIAS target may not be installed or exported.
9559 See Also
9561 • add_executable()
9562 add_link_options
9564 New in version 3.13.
9565 Add options to the link step for executable, shared library or module
9568 library targets in the current directory and below that are added after
9569 this command is invoked.
9570 add_link_options(<option> ...)
9572 This command can be used to add any link options, but alternative com‐
9574 mands exist to add libraries (target_link_libraries() or
9575 link_libraries()). See documentation of the directory and target
9576 LINK_OPTIONS properties.
9577 NOTE:
9579 This command cannot be used to add options for static library tar‐
9580 gets, since they do not use a linker. To add archiver or MSVC li‐
9581 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
9582 Arguments to add_link_options may use generator expressions with the
9584 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
9585 able expressions. See the cmake-buildsystem(7) manual for more on
9586 defining buildsystem properties.
9587 Host And Device Specific Link Options
9589 New in version 3.18: When a device link step is involved, which is con‐
9590 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
9591 properties and policy CMP0105, the raw options will be delivered to the
9592 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
9593 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
9594 sion will be used only for the device link step. Options wrapped with
9595 $<HOST_LINK:...> generator expression will be used only for the host
9596 link step.
9597 Option De-duplication
9600 The final set of options used for a target is constructed by accumulat‐
9601 ing options from the current target and the usage requirements of its
9602 dependencies. The set of options is de-duplicated to avoid repetition.
9603 New in version 3.12: While beneficial for individual options, the
9605 de-duplication step can break up option groups. For example, -option A
9606 -option B becomes -option A B. One may specify a group of options us‐
9607 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
9608 is dropped, and the rest of the option string is parsed using the
9609 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
9610 "SHELL:-option B" becomes -option A -option B.
9611 Handling Compiler Driver Differences
9614 To pass options to the linker tool, each compiler driver has its own
9615 syntax. The LINKER: prefix and , separator can be used to specify, in
9616 a portable way, options to pass to the linker tool. LINKER: is replaced
9617 by the appropriate driver option and , by the appropriate driver sepa‐
9618 rator. The driver prefix and driver separator are given by the values
9619 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
9620 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
9621 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
9623 Clang and -Wl,-z,defs for GNU GCC.
9624 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
9626 sion.
9627 The LINKER: prefix supports, as an alternative syntax, specification of
9629 arguments using the SHELL: prefix and space as separator. The previous
9630 example then becomes "LINKER:SHELL:-z defs".
9631 NOTE:
9633 Specifying the SHELL: prefix anywhere other than at the beginning of
9634 the LINKER: prefix is not supported.
9635 See Also
9637 • link_libraries()
9638 • target_link_libraries()
9640 • target_link_options()
9642 • CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> add language-wide
9644 flags passed to all invocations of the compiler. This includes invo‐
9645 cations that drive compiling and those that drive linking.
9646 add_subdirectory
9648 Add a subdirectory to the build.
9649 add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])
9651 Adds a subdirectory to the build. The source_dir specifies the direc‐
9653 tory in which the source CMakeLists.txt and code files are located. If
9654 it is a relative path, it will be evaluated with respect to the current
9655 directory (the typical usage), but it may also be an absolute path.
9656 The binary_dir specifies the directory in which to place the output
9657 files. If it is a relative path, it will be evaluated with respect to
9658 the current output directory, but it may also be an absolute path. If
9659 binary_dir is not specified, the value of source_dir, before expanding
9660 any relative path, will be used (the typical usage). The CMake‐
9661 Lists.txt file in the specified source directory will be processed im‐
9662 mediately by CMake before processing in the current input file contin‐
9663 ues beyond this command.
9664 If the EXCLUDE_FROM_ALL argument is provided then targets in the subdi‐
9666 rectory will not be included in the ALL target of the parent directory
9667 by default, and will be excluded from IDE project files. Users must
9668 explicitly build targets in the subdirectory. This is meant for use
9669 when the subdirectory contains a separate part of the project that is
9670 useful but not necessary, such as a set of examples. Typically the
9671 subdirectory should contain its own project() command invocation so
9672 that a full build system will be generated in the subdirectory (such as
9673 a Visual Studio IDE solution file). Note that inter-target dependen‐
9674 cies supersede this exclusion. If a target built by the parent project
9675 depends on a target in the subdirectory, the dependee target will be
9676 included in the parent project build system to satisfy the dependency.
9677 New in version 3.25: If the SYSTEM argument is provided, the SYSTEM di‐
9679 rectory property of the subdirectory will be set to true. This prop‐
9680 erty is used to initialize the SYSTEM property of each non-imported
9681 target created in that subdirectory.
9682 add_test
9685 Add a test to the project to be run by ctest(1).
9686 add_test(NAME <name> COMMAND <command> [<arg>...]
9688 [CONFIGURATIONS <config>...]
9689 [WORKING_DIRECTORY <dir>]
9690 [COMMAND_EXPAND_LISTS])
9691 Adds a test called <name>. The test name may contain arbitrary charac‐
9693 ters, expressed as a Quoted Argument or Bracket Argument if necessary.
9694 See policy CMP0110.
9695 CMake only generates tests if the enable_testing() command has been in‐
9697 voked. The CTest module invokes enable_testing automatically unless
9698 BUILD_TESTING is set to OFF.
9699 Tests added with the add_test(NAME) signature support using generator
9701 expressions in test properties set by set_property(TEST) or
9702 set_tests_properties(). Test properties may only be set in the direc‐
9703 tory the test is created in.
9704 add_test options are:
9706 COMMAND
9708 Specify the test command-line. If <command> specifies an exe‐
9709 cutable target created by add_executable(), it will automati‐
9710 cally be replaced by the location of the executable created at
9711 build time.
9712 The command may be specified using generator expressions.
9714 CONFIGURATIONS
9716 Restrict execution of the test only to the named configurations.
9717 WORKING_DIRECTORY
9719 Set the test property WORKING_DIRECTORY in which to execute the
9720 test. If not specified, the test will be run in
9721 CMAKE_CURRENT_BINARY_DIR. The working directory may be specified
9722 using generator expressions.
9723 COMMAND_EXPAND_LISTS
9725 New in version 3.16.
9726 Lists in COMMAND arguments will be expanded, including those
9729 created with generator expressions.
9730 If the test command exits with code 0 the test passes. Non-zero exit
9732 code is a "failed" test. The test property WILL_FAIL inverts this
9733 logic. Note that system-level test failures such as segmentation faults
9734 or heap errors will still fail the test even if WILL_FALL is true. Out‐
9735 put written to stdout or stderr is captured by ctest(1) and only af‐
9736 fects the pass/fail status via the PASS_REGULAR_EXPRESSION,
9737 FAIL_REGULAR_EXPRESSION, or SKIP_REGULAR_EXPRESSION test properties.
9738 New in version 3.16: Added SKIP_REGULAR_EXPRESSION property.
9740 Example usage:
9743 add_test(NAME mytest
9745 COMMAND testDriver --config $<CONFIG>
9746 --exe $<TARGET_FILE:myexe>)
9747 This creates a test mytest whose command runs a testDriver tool passing
9749 the configuration name and the full path to the executable file pro‐
9750 duced by target myexe.
9751 ----
9754 The command syntax above is recommended over the older, less flexible
9758 form:
9759 add_test(<name> <command> [<arg>...])
9761 Add a test called <name> with the given command-line.
9763 Unlike the above NAME signature, target names are not supported in the
9765 command-line. Furthermore, tests added with this signature do not sup‐
9766 port generator expressions in the command-line or test properties.
9767 aux_source_directory
9769 Find all source files in a directory.
9770 aux_source_directory(<dir> <variable>)
9772 Collects the names of all the source files in the specified directory
9774 and stores the list in the <variable> provided. This command is in‐
9775 tended to be used by projects that use explicit template instantiation.
9776 Template instantiation files can be stored in a Templates subdirectory
9777 and collected automatically using this command to avoid manually list‐
9778 ing all instantiations.
9779 It is tempting to use this command to avoid writing the list of source
9781 files for a library or executable target. While this seems to work,
9782 there is no way for CMake to generate a build system that knows when a
9783 new source file has been added. Normally the generated build system
9784 knows when it needs to rerun CMake because the CMakeLists.txt file is
9785 modified to add a new source. When the source is just added to the di‐
9786 rectory without modifying this file, one would have to manually rerun
9787 CMake to generate a build system incorporating the new file.
9788 build_command
9790 Get a command line to build the current project. This is mainly in‐
9791 tended for internal use by the CTest module.
9792 build_command(<variable>
9794 [CONFIGURATION <config>]
9795 [PARALLEL_LEVEL <parallel>]
9796 [TARGET <target>]
9797 [PROJECT_NAME <projname>] # legacy, causes warning
9798 )
9799 Sets the given <variable> to a command-line string of the form:
9801 <cmake> --build . [--config <config>] [--parallel <parallel>] [--target <target>...] [-- -i]
9803 where <cmake> is the location of the cmake(1) command-line tool, and
9805 <config>, <parallel> and <target> are the values provided to the CON‐
9806 FIGURATION, PARALLEL_LEVEL and TARGET options, if any. The trailing --
9807 -i option is added for Makefile Generators if policy CMP0061 is not set
9808 to NEW.
9809 When invoked, this cmake --build command line will launch the underly‐
9811 ing build system tool.
9812 New in version 3.21: The PARALLEL_LEVEL argument can be used to set the
9814 --parallel flag.
9815 build_command(<cachevariable> <makecommand>)
9818 This second signature is deprecated, but still available for backwards
9820 compatibility. Use the first signature instead.
9821 It sets the given <cachevariable> to a command-line string as above but
9823 without the --target option. The <makecommand> is ignored but should
9824 be the full path to devenv, nmake, make or one of the end user build
9825 tools for legacy invocations.
9826 NOTE:
9828 In CMake versions prior to 3.0 this command returned a command line
9829 that directly invokes the native build tool for the current genera‐
9830 tor. Their implementation of the PROJECT_NAME option had no useful
9831 effects, so CMake now warns on use of the option.
9832 cmake_file_api
9834 New in version 3.27.
9835 Enables interacting with the CMake file API.
9838 cmake_file_api(QUERY ...)
9840 The QUERY subcommand adds a file API query for the current CMake
9841 invocation.
9842 cmake_file_api(
9844 QUERY
9845 API_VERSION <version>
9846 [CODEMODEL <versions>...]
9847 [CACHE <versions>...]
9848 [CMAKEFILES <versions>...]
9849 [TOOLCHAINS <versions>...]
9850 )
9851 The API_VERSION must always be given. Currently, the only sup‐
9853 ported value for <version> is 1. See API v1 for details of the
9854 reply content and location.
9855 Each of the optional keywords CODEMODEL, CACHE, CMAKEFILES and
9857 TOOLCHAINS correspond to one of the object kinds that can be re‐
9858 quested by the project. The configureLog object kind cannot be
9859 set with this command, since it must be set before CMake starts
9860 reading the top level CMakeLists.txt file.
9861 For each of the optional keywords, the <versions> list must con‐
9863 tain one or more version values of the form major or major.mi‐
9864 nor, where major and minor are integers. Projects should list
9865 the versions they accept in their preferred order, as only the
9866 first supported value from the list will be selected. The com‐
9867 mand will ignore versions with a major version higher than any
9868 major version it supports for that object kind. It will raise
9869 an error if it encounters an invalid version number, or if none
9870 of the requested versions is supported.
9871 For each type of object kind requested, a query equivalent to a
9873 shared, stateless query will be added internally. No query file
9874 will be created in the file system. The reply will be written
9875 to the file system at generation time.
9876 It is not an error to add a query for the same thing more than
9878 once, whether from query files or from multiple calls to
9879 cmake_file_api(QUERY). The final set of queries will be a
9880 merged combination of all queries specified on disk and queries
9881 submitted by the project.
9882 Example
9884 A project may want to use replies from the file API at build time to
9885 implement some form of verification task. Instead of relying on some‐
9886 thing outside of CMake to create a query file, the project can use
9887 cmake_file_api(QUERY) to request the required information for the cur‐
9888 rent run. It can then create a custom command to run at build time,
9889 knowing that the requested information should always be available.
9890 cmake_file_api(
9892 QUERY
9893 API_VERSION 1
9894 CODEMODEL 2.3
9895 TOOLCHAINS 1
9896 )
9897 add_custom_target(verify_project
9899 COMMAND ${CMAKE_COMMAND}
9900 -D BUILD_DIR=${CMAKE_BINARY_DIR}
9901 -D CONFIG=$<CONFIG>
9902 -P ${CMAKE_CURRENT_SOURCE_DIR}/verify_project.cmake
9903 )
9904 create_test_sourcelist
9906 Create a test driver and source list for building test programs.
9907 create_test_sourcelist(sourceListName driverName
9909 test1 test2 test3
9910 EXTRA_INCLUDE include.h
9911 FUNCTION function)
9912 A test driver is a program that links together many small tests into a
9914 single executable. This is useful when building static executables
9915 with large libraries to shrink the total required size. The list of
9916 source files needed to build the test driver will be in sourceListName.
9917 driverName is the name of the test driver program. The rest of the ar‐
9918 guments consist of a list of test source files, can be semicolon sepa‐
9919 rated. Each test source file should have a function in it that is the
9920 same name as the file with no extension (foo.cxx should have int
9921 foo(int, char*[]);) driverName will be able to call each of the tests
9922 by name on the command line. If EXTRA_INCLUDE is specified, then the
9923 next argument is included into the generated file. If FUNCTION is
9924 specified, then the next argument is taken as a function name that is
9925 passed a pointer to ac and av. This can be used to add extra command
9926 line processing to each test. The CMAKE_TESTDRIVER_BEFORE_TESTMAIN
9927 cmake variable can be set to have code that will be placed directly be‐
9928 fore calling the test main function. CMAKE_TESTDRIVER_AFTER_TESTMAIN
9929 can be set to have code that will be placed directly after the call to
9930 the test main function.
9931 define_property
9933 Define and document custom properties.
9934 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
9936 TEST | VARIABLE | CACHED_VARIABLE>
9937 PROPERTY <name> [INHERITED]
9938 [BRIEF_DOCS <brief-doc> [docs...]]
9939 [FULL_DOCS <full-doc> [docs...]]
9940 [INITIALIZE_FROM_VARIABLE <variable>])
9941 Defines one property in a scope for use with the set_property() and
9943 get_property() commands. It is mainly useful for defining the way a
9944 property is initialized or inherited. Historically, the command also
9945 associated documentation with a property, but that is no longer consid‐
9946 ered a primary use case.
9947 The first argument determines the kind of scope in which the property
9949 should be used. It must be one of the following:
9950 GLOBAL = associated with the global namespace
9952 DIRECTORY = associated with one directory
9953 TARGET = associated with one target
9954 SOURCE = associated with one source file
9955 TEST = associated with a test named with add_test
9956 VARIABLE = documents a CMake language variable
9957 CACHED_VARIABLE = documents a CMake cache variable
9958 Note that unlike set_property() and get_property() no actual scope
9960 needs to be given; only the kind of scope is important.
9961 The required PROPERTY option is immediately followed by the name of the
9963 property being defined.
9964 If the INHERITED option is given, then the get_property() command will
9966 chain up to the next higher scope when the requested property is not
9967 set in the scope given to the command.
9968 • DIRECTORY scope chains to its parent directory's scope, continuing
9970 the walk up parent directories until a directory has the property set
9971 or there are no more parents. If still not found at the top level
9972 directory, it chains to the GLOBAL scope.
9973 • TARGET, SOURCE and TEST properties chain to DIRECTORY scope, includ‐
9975 ing further chaining up the directories, etc. as needed.
9976 Note that this scope chaining behavior only applies to calls to
9978 get_property(), get_directory_property(), get_target_property(),
9979 get_source_file_property() and get_test_property(). There is no inher‐
9980 iting behavior when setting properties, so using APPEND or AP‐
9981 PEND_STRING with the set_property() command will not consider inherited
9982 values when working out the contents to append to.
9983 The BRIEF_DOCS and FULL_DOCS options are followed by strings to be as‐
9985 sociated with the property as its brief and full documentation. CMake
9986 does not use this documentation other than making it available to the
9987 project via corresponding options to the get_property() command.
9988 Changed in version 3.23: The BRIEF_DOCS and FULL_DOCS options are op‐
9990 tional.
9991 New in version 3.23: The INITIALIZE_FROM_VARIABLE option specifies a
9994 variable from which the property should be initialized. It can only be
9995 used with target properties. The <variable> name must end with the
9996 property name and must not begin with CMAKE_ or _CMAKE_. The property
9997 name must contain at least one underscore. It is recommended that the
9998 property name have a prefix specific to the project.
9999 See Also
10002 • get_property()
10003 • set_property()
10005 enable_language
10007 Enable languages (CXX/C/OBJC/OBJCXX/Fortran/etc)
10008 enable_language(<lang>... [OPTIONAL])
10010 Enables support for the named languages in CMake. This is the same as
10012 the project() command but does not create any of the extra variables
10013 that are created by the project command.
10014 Supported languages are C, CXX (i.e. C++), CSharp (i.e. C#), CUDA,
10016 OBJC (i.e. Objective-C), OBJCXX (i.e. Objective-C++), Fortran, HIP,
10017 ISPC, Swift, ASM, ASM_NASM, ASM_MARMASM, ASM_MASM, and ASM-ATT.
10018 New in version 3.8: Added CSharp and CUDA support.
10019 New in version 3.15: Added Swift support.
10022 New in version 3.16: Added OBJC and OBJCXX support.
10025 New in version 3.18: Added ISPC support.
10028 New in version 3.21: Added HIP support.
10031 New in version 3.26: Added ASM_MARMASM support.
10034 If enabling ASM, list it last so that CMake can check whether compilers
10037 for other languages like C work for assembly too.
10038 This command must be called in file scope, not in a function call.
10040 Furthermore, it must be called in the highest directory common to all
10041 targets using the named language directly for compiling sources or in‐
10042 directly through link dependencies. It is simplest to enable all
10043 needed languages in the top-level directory of a project.
10044 The OPTIONAL keyword is a placeholder for future implementation and
10046 does not currently work. Instead you can use the CheckLanguage module
10047 to verify support before enabling.
10048 enable_testing
10050 Enable testing for current directory and below.
10051 enable_testing()
10053 Enables testing for this directory and below.
10055 This command should be in the source directory root because ctest ex‐
10057 pects to find a test file in the build directory root.
10058 This command is automatically invoked when the CTest module is in‐
10060 cluded, except if the BUILD_TESTING option is turned off.
10061 See also the add_test() command.
10063 export
10065 Export targets or packages for outside projects to use them directly
10066 from the current project's build tree, without installation.
10067 See the install(EXPORT) command to export targets from an install tree.
10069 Synopsis
10071 export(TARGETS <target>... [...])
10072 export(EXPORT <export-name> [...])
10073 export(PACKAGE <PackageName>)
10074 Exporting Targets
10076 export(TARGETS <target>... [NAMESPACE <namespace>]
10077 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES]
10078 [CXX_MODULES_DIRECTORY <directory>])
10079 Creates a file <filename> that may be included by outside projects to
10081 import targets named by <target>... from the current project's build
10082 tree. This is useful during cross-compiling to build utility executa‐
10083 bles that can run on the host platform in one project and then import
10084 them into another project being compiled for the target platform.
10085 The file created by this command is specific to the build tree and
10087 should never be installed. See the install(EXPORT) command to export
10088 targets from an install tree.
10089 The options are:
10091 NAMESPACE <namespace>
10093 Prepend the <namespace> string to all target names written to
10094 the file.
10095 APPEND Append to the file instead of overwriting it. This can be used
10097 to incrementally export multiple targets to the same file.
10098 EXPORT_LINK_INTERFACE_LIBRARIES
10100 Include the contents of the properties named with the pattern
10101 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? in the export,
10102 even when policy CMP0022 is NEW. This is useful to support con‐
10103 sumers using CMake versions older than 2.8.12.
10104 CXX_MODULES_DIRECTORY <directory>
10106 NOTE:
10108 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
10109 Export C++ module properties to files under the given directory.
10111 Each file will be named according to the target's export name (with‐
10112 out any namespace). These files will automatically be included from
10113 the export file.
10114 This signature requires all targets to be listed explicitly. If a li‐
10116 brary target is included in the export, but a target to which it links
10117 is not included, the behavior is unspecified. See the export(EXPORT)
10118 signature to automatically export the same targets from the build tree
10119 as install(EXPORT) would from an install tree.
10120 NOTE:
10122 Object Libraries under Xcode have special handling if multiple ar‐
10123 chitectures are listed in CMAKE_OSX_ARCHITECTURES. In this case
10124 they will be exported as Interface Libraries with no object files
10125 available to clients. This is sufficient to satisfy transitive us‐
10126 age requirements of other targets that link to the object libraries
10127 in their implementation.
10128 This command exports all Build Configurations from the build tree. See
10130 the CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable to map configurations
10131 of dependent projects to the exported configurations.
10132 Exporting Targets to Android.mk
10134 export(TARGETS <target>... ANDROID_MK <filename>)
10135 New in version 3.7.
10137 This signature exports cmake built targets to the android ndk build
10140 system by creating an Android.mk file that references the prebuilt tar‐
10141 gets. The Android NDK supports the use of prebuilt libraries, both
10142 static and shared. This allows cmake to build the libraries of a
10143 project and make them available to an ndk build system complete with
10144 transitive dependencies, include flags and defines required to use the
10145 libraries. The signature takes a list of targets and puts them in the
10146 Android.mk file specified by the <filename> given. This signature can
10147 only be used if policy CMP0022 is NEW for all targets given. A error
10148 will be issued if that policy is set to OLD for one of the targets.
10149 Exporting Targets matching install(EXPORT)
10151 export(EXPORT <export-name> [NAMESPACE <namespace>] [FILE <filename>]
10152 [CXX_MODULES_DIRECTORY <directory>])
10153 Creates a file <filename> that may be included by outside projects to
10155 import targets from the current project's build tree. This is the same
10156 as the export(TARGETS) signature, except that the targets are not ex‐
10157 plicitly listed. Instead, it exports the targets associated with the
10158 installation export <export-name>. Target installations may be associ‐
10159 ated with the export <export-name> using the EXPORT option of the
10160 install(TARGETS) command.
10161 Exporting Packages
10163 export(PACKAGE <PackageName>)
10164 Store the current build directory in the CMake user package registry
10166 for package <PackageName>. The find_package() command may consider the
10167 directory while searching for package <PackageName>. This helps depen‐
10168 dent projects find and use a package from the current project's build
10169 tree without help from the user. Note that the entry in the package
10170 registry that this command creates works only in conjunction with a
10171 package configuration file (<PackageName>Config.cmake) that works with
10172 the build tree. In some cases, for example for packaging and for system
10173 wide installations, it is not desirable to write the user package reg‐
10174 istry.
10175 Changed in version 3.1: If the CMAKE_EXPORT_NO_PACKAGE_REGISTRY vari‐
10177 able is enabled, the export(PACKAGE) command will do nothing.
10178 Changed in version 3.15: By default the export(PACKAGE) command does
10181 nothing (see policy CMP0090) because populating the user package reg‐
10182 istry has effects outside the source and build trees. Set the
10183 CMAKE_EXPORT_PACKAGE_REGISTRY variable to add build directories to the
10184 CMake user package registry.
10185 fltk_wrap_ui
10188 Create FLTK user interfaces Wrappers.
10189 fltk_wrap_ui(resultingLibraryName source1
10191 source2 ... sourceN )
10192 Produce .h and .cxx files for all the .fl and .fld files listed. The
10194 resulting .h and .cxx files will be added to a variable named result‐
10195 ingLibraryName_FLTK_UI_SRCS which should be added to your library.
10196 get_source_file_property
10198 Get a property for a source file.
10199 get_source_file_property(<variable> <file>
10201 [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
10202 <property>)
10203 Gets a property from a source file. The value of the property is
10205 stored in the specified <variable>. If the source property is not
10206 found, the behavior depends on whether it has been defined to be an IN‐
10207 HERITED property or not (see define_property()). Non-inherited proper‐
10208 ties will set variable to NOTFOUND, whereas inherited properties will
10209 search the relevant parent scope as described for the define_property()
10210 command and if still unable to find the property, variable will be set
10211 to an empty string.
10212 By default, the source file's property will be read from the current
10214 source directory's scope.
10215 New in version 3.18: Directory scope can be overridden with one of the
10217 following sub-options:
10218 DIRECTORY <dir>
10220 The source file property will be read from the <dir> directory's
10221 scope. CMake must already know about that source directory, ei‐
10222 ther by having added it through a call to add_subdirectory() or
10223 <dir> being the top level source directory. Relative paths are
10224 treated as relative to the current source directory.
10225 TARGET_DIRECTORY <target>
10227 The source file property will be read from the directory scope
10228 in which <target> was created (<target> must therefore already
10229 exist).
10230 Use set_source_files_properties() to set property values. Source file
10233 properties usually control how the file is built. One property that is
10234 always there is LOCATION.
10235 NOTE:
10237 The GENERATED source file property may be globally visible. See its
10238 documentation for details.
10239 See Also
10241 • define_property()
10242 • the more general get_property() command
10244 • set_source_files_properties()
10246 get_target_property
10248 Get a property from a target.
10249 get_target_property(<VAR> target property)
10251 Get a property from a target. The value of the property is stored in
10253 the variable <VAR>. If the target property is not found, the behavior
10254 depends on whether it has been defined to be an INHERITED property or
10255 not (see define_property()). Non-inherited properties will set <VAR>
10256 to <VAR>-NOTFOUND, whereas inherited properties will search the rele‐
10257 vant parent scope as described for the define_property() command and if
10258 still unable to find the property, <VAR> will be set to an empty
10259 string.
10260 Use set_target_properties() to set target property values. Properties
10262 are usually used to control how a target is built, but some query the
10263 target instead. This command can get properties for any target so far
10264 created. The targets do not need to be in the current CMakeLists.txt
10265 file.
10266 See Also
10268 • define_property()
10269 • the more general get_property() command
10271 • set_target_properties()
10273 • Properties on Targets for the list of properties known to CMake
10275 get_test_property
10277 Get a property of the test.
10278 get_test_property(test property VAR)
10280 Get a property from the test. The value of the property is stored in
10282 the variable VAR. If the test property is not found, the behavior de‐
10283 pends on whether it has been defined to be an INHERITED property or not
10284 (see define_property()). Non-inherited properties will set VAR to
10285 "NOTFOUND", whereas inherited properties will search the relevant par‐
10286 ent scope as described for the define_property() command and if still
10287 unable to find the property, VAR will be set to an empty string.
10288 For a list of standard properties you can type cmake --help-prop‐
10290 erty-list.
10291 See Also
10293 • define_property()
10294 • the more general get_property() command
10296 include_directories
10298 Add include directories to the build.
10299 include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
10301 Add the given directories to those the compiler uses to search for in‐
10303 clude files. Relative paths are interpreted as relative to the current
10304 source directory.
10305 The include directories are added to the INCLUDE_DIRECTORIES directory
10307 property for the current CMakeLists file. They are also added to the
10308 INCLUDE_DIRECTORIES target property for each target in the current
10309 CMakeLists file. The target property values are the ones used by the
10310 generators.
10311 By default the directories specified are appended onto the current list
10313 of directories. This default behavior can be changed by setting
10314 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE ex‐
10315 plicitly, you can select between appending and prepending, independent
10316 of the default.
10317 If the SYSTEM option is given, the compiler will be told the directo‐
10319 ries are meant as system include directories on some platforms. Sig‐
10320 naling this setting might achieve effects such as the compiler skipping
10321 warnings, or these fixed-install system files not being considered in
10322 dependency calculations - see compiler docs.
10323 Arguments to include_directories may use generator expressions with the
10325 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
10326 able expressions. See the cmake-buildsystem(7) manual for more on
10327 defining buildsystem properties.
10328 NOTE:
10330 Prefer the target_include_directories() command to add include di‐
10331 rectories to individual targets and optionally propagate/export them
10332 to dependents.
10333 See Also
10335 • target_include_directories()
10336 include_external_msproject
10338 Include an external Microsoft project file in a workspace.
10339 include_external_msproject(projectname location
10341 [TYPE projectTypeGUID]
10342 [GUID projectGUID]
10343 [PLATFORM platformName]
10344 dep1 dep2 ...)
10345 Includes an external Microsoft project in the generated workspace file.
10347 Currently does nothing on UNIX. This will create a target named [pro‐
10348 jectname]. This can be used in the add_dependencies() command to make
10349 things depend on the external project.
10350 TYPE, GUID and PLATFORM are optional parameters that allow one to spec‐
10352 ify the type of project, id (GUID) of the project and the name of the
10353 target platform. This is useful for projects requiring values other
10354 than the default (e.g. WIX projects).
10355 New in version 3.9: If the imported project has different configuration
10357 names than the current project, set the MAP_IMPORTED_CONFIG_<CONFIG>
10358 target property to specify the mapping.
10359 include_regular_expression
10362 Set the regular expression used for dependency checking.
10363 include_regular_expression(regex_match [regex_complain])
10365 Sets the regular expressions used in dependency checking. Only files
10367 matching regex_match will be traced as dependencies. Only files match‐
10368 ing regex_complain will generate warnings if they cannot be found
10369 (standard header paths are not searched). The defaults are:
10370 regex_match = "^.*$" (match everything)
10372 regex_complain = "^$" (match empty string only)
10373 install
10375 Specify rules to run at install time.
10376 Synopsis
10378 install(TARGETS <target>... [...])
10379 install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
10380 install({FILES | PROGRAMS} <file>... [...])
10381 install(DIRECTORY <dir>... [...])
10382 install(SCRIPT <file> [...])
10383 install(CODE <code> [...])
10384 install(EXPORT <export-name> [...])
10385 install(RUNTIME_DEPENDENCY_SET <set-name> [...])
10386 Introduction
10388 This command generates installation rules for a project. Install rules
10389 specified by calls to the install() command within a source directory
10390 are executed in order during installation.
10391 Changed in version 3.14: Install rules in subdirectories added by calls
10393 to the add_subdirectory() command are interleaved with those in the
10394 parent directory to run in the order declared (see policy CMP0082).
10395 Changed in version 3.22: The environment variable CMAKE_INSTALL_MODE
10398 can override the default copying behavior of install().
10399 There are multiple signatures for this command. Some of them define
10402 installation options for files and targets. Options common to multiple
10403 signatures are covered here but they are valid only for signatures that
10404 specify them. The common options are:
10405 DESTINATION
10407 Specify the directory on disk to which a file will be installed.
10408 Arguments can be relative or absolute paths.
10409 If a relative path is given it is interpreted relative to the
10411 value of the CMAKE_INSTALL_PREFIX variable. The prefix can be
10412 relocated at install time using the DESTDIR mechanism explained
10413 in the CMAKE_INSTALL_PREFIX variable documentation.
10414 If an absolute path (with a leading slash or drive letter) is
10416 given it is used verbatim.
10417 As absolute paths are not supported by cpack installer genera‐
10419 tors, it is preferable to use relative paths throughout. In
10420 particular, there is no need to make paths absolute by prepend‐
10421 ing CMAKE_INSTALL_PREFIX; this prefix is used by default if the
10422 DESTINATION is a relative path.
10423 PERMISSIONS
10425 Specify permissions for installed files. Valid permissions are
10426 OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE,
10427 GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID,
10428 and SETGID. Permissions that do not make sense on certain plat‐
10429 forms are ignored on those platforms.
10430 CONFIGURATIONS
10432 Specify a list of build configurations for which the install
10433 rule applies (Debug, Release, etc.). Note that the values speci‐
10434 fied for this option only apply to options listed AFTER the CON‐
10435 FIGURATIONS option. For example, to set separate install paths
10436 for the Debug and Release configurations, do the following:
10437 install(TARGETS target
10439 CONFIGURATIONS Debug
10440 RUNTIME DESTINATION Debug/bin)
10441 install(TARGETS target
10442 CONFIGURATIONS Release
10443 RUNTIME DESTINATION Release/bin)
10444 Note that CONFIGURATIONS appears BEFORE RUNTIME DESTINATION.
10446 COMPONENT
10448 Specify an installation component name with which the install
10449 rule is associated, such as Runtime or Development. During com‐
10450 ponent-specific installation only install rules associated with
10451 the given component name will be executed. During a full in‐
10452 stallation all components are installed unless marked with EX‐
10453 CLUDE_FROM_ALL. If COMPONENT is not provided a default compo‐
10454 nent "Unspecified" is created. The default component name may
10455 be controlled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
10456 variable.
10457 EXCLUDE_FROM_ALL
10459 New in version 3.6.
10460 Specify that the file is excluded from a full installation and
10463 only installed as part of a component-specific installation
10464 RENAME Specify a name for an installed file that may be different from
10466 the original file. Renaming is allowed only when a single file
10467 is installed by the command.
10468 OPTIONAL
10470 Specify that it is not an error if the file to be installed does
10471 not exist.
10472 New in version 3.1: Command signatures that install files may print
10474 messages during installation. Use the CMAKE_INSTALL_MESSAGE variable
10475 to control which messages are printed.
10476 New in version 3.11: Many of the install() variants implicitly create
10479 the directories containing the installed files. If
10480 CMAKE_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS is set, these directories
10481 will be created with the permissions specified. Otherwise, they will be
10482 created according to the uname rules on Unix-like platforms. Windows
10483 platforms are unaffected.
10484 Installing Targets
10487 install(TARGETS targets... [EXPORT <export-name>]
10488 [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
10489 [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
10490 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI]
10491 [DESTINATION <dir>]
10492 [PERMISSIONS permissions...]
10493 [CONFIGURATIONS [Debug|Release|...]]
10494 [COMPONENT <component>]
10495 [NAMELINK_COMPONENT <component>]
10496 [OPTIONAL] [EXCLUDE_FROM_ALL]
10497 [NAMELINK_ONLY|NAMELINK_SKIP]
10498 ] [...]
10499 [INCLUDES DESTINATION [<dir> ...]]
10500 )
10501 The TARGETS form specifies rules for installing targets from a project.
10503 There are several kinds of target Output Artifacts that may be in‐
10504 stalled:
10505 ARCHIVE
10507 Target artifacts of this kind include:
10508 • Static libraries (except on macOS when marked as FRAMEWORK,
10510 see below);
10511 • DLL import libraries (on all Windows-based systems including
10513 Cygwin; they have extension .lib, in contrast to the .dll li‐
10514 braries that go to RUNTIME);
10515 • On AIX, the linker import file created for executables with
10517 ENABLE_EXPORTS enabled.
10518 • On macOS, the linker import file created for shared libraries
10520 with ENABLE_EXPORTS enabled (except when marked as FRAMEWORK,
10521 see below).
10522 LIBRARY
10524 Target artifacts of this kind include:
10525 • Shared libraries, except
10527 • DLLs (these go to RUNTIME, see below),
10529 • on macOS when marked as FRAMEWORK (see below).
10531 RUNTIME
10533 Target artifacts of this kind include:
10534 • Executables (except on macOS when marked as MACOSX_BUNDLE, see
10536 BUNDLE below);
10537 • DLLs (on all Windows-based systems including Cygwin; note that
10539 the accompanying import libraries are of kind ARCHIVE).
10540 OBJECTS
10542 New in version 3.9.
10543 Object files associated with object libraries.
10546 FRAMEWORK
10548 Both static and shared libraries marked with the FRAMEWORK prop‐
10549 erty are treated as FRAMEWORK targets on macOS.
10550 BUNDLE Executables marked with the MACOSX_BUNDLE property are treated
10552 as BUNDLE targets on macOS.
10553 PUBLIC_HEADER
10555 Any PUBLIC_HEADER files associated with a library are installed
10556 in the destination specified by the PUBLIC_HEADER argument on
10557 non-Apple platforms. Rules defined by this argument are ignored
10558 for FRAMEWORK libraries on Apple platforms because the associ‐
10559 ated files are installed into the appropriate locations inside
10560 the framework folder. See PUBLIC_HEADER for details.
10561 PRIVATE_HEADER
10563 Similar to PUBLIC_HEADER, but for PRIVATE_HEADER files. See
10564 PRIVATE_HEADER for details.
10565 RESOURCE
10567 Similar to PUBLIC_HEADER and PRIVATE_HEADER, but for RESOURCE
10568 files. See RESOURCE for details.
10569 FILE_SET <set>
10571 New in version 3.23.
10572 File sets are defined by the target_sources(FILE_SET) command.
10575 If the file set <set> exists and is PUBLIC or INTERFACE, any
10576 files in the set are installed under the destination (see be‐
10577 low). The directory structure relative to the file set's base
10578 directories is preserved. For example, a file added to the file
10579 set as /blah/include/myproj/here.h with a base directory
10580 /blah/include would be installed to myproj/here.h below the des‐
10581 tination.
10582 CXX_MODULES_BMI
10584 NOTE:
10586 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
10587 Any module files from C++ modules from PUBLIC sources in a file set
10589 of type CXX_MODULES will be installed to the given DESTINATION. All
10590 modules are placed directly in the destination as no directory
10591 structure is derived from the names of the modules. An empty DESTI‐
10592 NATION may be used to suppress installing these files (for use in
10593 generic code).
10594 For each of these arguments given, the arguments following them only
10596 apply to the target or file type specified in the argument. If none is
10597 given, the installation properties apply to all target types.
10598 For regular executables, static libraries and shared libraries, the
10600 DESTINATION argument is not required. For these target types, when
10601 DESTINATION is omitted, a default destination will be taken from the
10602 appropriate variable from GNUInstallDirs, or set to a built-in default
10603 value if that variable is not defined. The same is true for file sets,
10604 and the public and private headers associated with the installed tar‐
10605 gets through the PUBLIC_HEADER and PRIVATE_HEADER target properties. A
10606 destination must always be provided for module libraries, Apple bundles
10607 and frameworks. A destination can be omitted for interface and object
10608 libraries, but they are handled differently (see the discussion of this
10609 topic toward the end of this section).
10610 For shared libraries on DLL platforms, if neither RUNTIME nor ARCHIVE
10612 destinations are specified, both the RUNTIME and ARCHIVE components are
10613 installed to their default destinations. If either a RUNTIME or ARCHIVE
10614 destination is specified, the component is installed to that destina‐
10615 tion, and the other component is not installed. If both RUNTIME and AR‐
10616 CHIVE destinations are specified, then both components are installed to
10617 their respective destinations.
10618 The following table shows the target types with their associated vari‐
10620 ables and built-in defaults that apply when no destination is given:
10621 ┌────────────────────┬─────────────────────┬──────────────────┐
10623 │Target Type │ GNUInstallDirs │ Built-In Default │
10624 │ │ Variable │ │
10625 ├────────────────────┼─────────────────────┼──────────────────┤
10626 │RUNTIME │ ${CMAKE_IN‐ │ bin │
10627 │ │ STALL_BINDIR} │ │
10628 ├────────────────────┼─────────────────────┼──────────────────┤
10629 │LIBRARY │ ${CMAKE_IN‐ │ lib │
10630 │ │ STALL_LIBDIR} │ │
10631 ├────────────────────┼─────────────────────┼──────────────────┤
10632 │ARCHIVE │ ${CMAKE_IN‐ │ lib │
10633 │ │ STALL_LIBDIR} │ │
10634 ├────────────────────┼─────────────────────┼──────────────────┤
10635 │PRIVATE_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
10636 │ │ CLUDEDIR} │ │
10637 ├────────────────────┼─────────────────────┼──────────────────┤
10638 │PUBLIC_HEADER │ ${CMAKE_INSTALL_IN‐ │ include │
10639 │ │ CLUDEDIR} │ │
10640 ├────────────────────┼─────────────────────┼──────────────────┤
10641 │FILE_SET (type │ ${CMAKE_INSTALL_IN‐ │ include │
10642 │HEADERS) │ CLUDEDIR} │ │
10643 └────────────────────┴─────────────────────┴──────────────────┘
10644 Projects wishing to follow the common practice of installing headers
10646 into a project-specific subdirectory may prefer using file sets with
10647 appropriate paths and base directories. Otherwise, they must provide a
10648 DESTINATION instead of being able to rely on the above (see next exam‐
10649 ple below).
10650 To make packages compliant with distribution filesystem layout poli‐
10652 cies, if projects must specify a DESTINATION, it is recommended that
10653 they use a path that begins with the appropriate GNUInstallDirs vari‐
10654 able. This allows package maintainers to control the install destina‐
10655 tion by setting the appropriate cache variables. The following example
10656 shows a static library being installed to the default destination pro‐
10657 vided by GNUInstallDirs, but with its headers installed to a
10658 project-specific subdirectory without using file sets:
10659 add_library(mylib STATIC ...)
10661 set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)
10662 include(GNUInstallDirs)
10663 install(TARGETS mylib
10664 PUBLIC_HEADER
10665 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj
10666 )
10667 In addition to the common options listed above, each target can accept
10669 the following additional arguments:
10670 NAMELINK_COMPONENT
10672 New in version 3.12.
10673 On some platforms a versioned shared library has a symbolic link
10676 such as:
10677 lib<name>.so -> lib<name>.so.1
10679 where lib<name>.so.1 is the soname of the library and
10681 lib<name>.so is a "namelink" allowing linkers to find the li‐
10682 brary when given -l<name>. The NAMELINK_COMPONENT option is sim‐
10683 ilar to the COMPONENT option, but it changes the installation
10684 component of a shared library namelink if one is generated. If
10685 not specified, this defaults to the value of COMPONENT. It is an
10686 error to use this parameter outside of a LIBRARY block.
10687 Changed in version 3.27: This parameter is also usable for an
10689 ARCHIVE block to manage the linker import file created, on
10690 macOS, for shared libraries with ENABLE_EXPORTS enabled.
10691 Consider the following example:
10694 install(TARGETS mylib
10696 LIBRARY
10697 COMPONENT Libraries
10698 NAMELINK_COMPONENT Development
10699 PUBLIC_HEADER
10700 COMPONENT Development
10701 )
10702 In this scenario, if you choose to install only the Development
10704 component, both the headers and namelink will be installed with‐
10705 out the library. (If you don't also install the Libraries compo‐
10706 nent, the namelink will be a dangling symlink, and projects that
10707 link to the library will have build errors.) If you install only
10708 the Libraries component, only the library will be installed,
10709 without the headers and namelink.
10710 This option is typically used for package managers that have
10712 separate runtime and development packages. For example, on De‐
10713 bian systems, the library is expected to be in the runtime pack‐
10714 age, and the headers and namelink are expected to be in the de‐
10715 velopment package.
10716 See the VERSION and SOVERSION target properties for details on
10718 creating versioned shared libraries.
10719 NAMELINK_ONLY
10721 This option causes the installation of only the namelink when a
10722 library target is installed. On platforms where versioned shared
10723 libraries do not have namelinks or when a library is not ver‐
10724 sioned, the NAMELINK_ONLY option installs nothing. It is an er‐
10725 ror to use this parameter outside of a LIBRARY block.
10726 Changed in version 3.27: This parameter is also usable for an
10728 ARCHIVE block to manage the linker import file created, on
10729 macOS, for shared libraries with ENABLE_EXPORTS enabled.
10730 When NAMELINK_ONLY is given, either NAMELINK_COMPONENT or COMPO‐
10733 NENT may be used to specify the installation component of the
10734 namelink, but COMPONENT should generally be preferred.
10735 NAMELINK_SKIP
10737 Similar to NAMELINK_ONLY, but it has the opposite effect: it
10738 causes the installation of library files other than the namelink
10739 when a library target is installed. When neither NAMELINK_ONLY
10740 or NAMELINK_SKIP are given, both portions are installed. On
10741 platforms where versioned shared libraries do not have symlinks
10742 or when a library is not versioned, NAMELINK_SKIP installs the
10743 library. It is an error to use this parameter outside of a LI‐
10744 BRARY block.
10745 Changed in version 3.27: This parameter is also usable for an
10747 ARCHIVE block to manage the linker import file created, on
10748 macOS, for shared libraries with ENABLE_EXPORTS enabled.
10749 If NAMELINK_SKIP is specified, NAMELINK_COMPONENT has no effect.
10752 It is not recommended to use NAMELINK_SKIP in conjunction with
10753 NAMELINK_COMPONENT.
10754 The install(TARGETS) command can also accept the following options at
10756 the top level:
10757 EXPORT This option associates the installed target files with an export
10759 called <export-name>. It must appear before any target options.
10760 To actually install the export file itself, call
10761 install(EXPORT), documented below. See documentation of the
10762 EXPORT_NAME target property to change the name of the exported
10763 target.
10764 If EXPORT is used and the targets include PUBLIC or INTERFACE
10766 file sets, all of them must be specified with FILE_SET argu‐
10767 ments. All PUBLIC or INTERFACE file sets associated with a tar‐
10768 get are included in the export.
10769 INCLUDES DESTINATION
10771 This option specifies a list of directories which will be added
10772 to the INTERFACE_INCLUDE_DIRECTORIES target property of the
10773 <targets> when exported by the install(EXPORT) command. If a
10774 relative path is specified, it is treated as relative to the
10775 $<INSTALL_PREFIX>.
10776 RUNTIME_DEPENDENCY_SET
10778 New in version 3.21.
10779 This option causes all runtime dependencies of installed exe‐
10782 cutable, shared library, and module targets to be added to the
10783 specified runtime dependency set. This set can then be installed
10784 with an install(RUNTIME_DEPENDENCY_SET) command.
10785 This keyword and the RUNTIME_DEPENDENCIES keyword are mutually
10787 exclusive.
10788 RUNTIME_DEPENDENCIES
10790 New in version 3.21.
10791 This option causes all runtime dependencies of installed exe‐
10794 cutable, shared library, and module targets to be installed
10795 along with the targets themselves. The RUNTIME, LIBRARY, FRAME‐
10796 WORK, and generic arguments are used to determine the properties
10797 (DESTINATION, COMPONENT, etc.) of the installation of these de‐
10798 pendencies.
10799 RUNTIME_DEPENDENCIES is semantically equivalent to the following
10801 pair of calls:
10802 install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
10804 install(RUNTIME_DEPENDENCY_SET <set-name> args...)
10805 where <set-name> will be a randomly generated set name. The
10807 args... may include any of the following keywords supported by
10808 the install(RUNTIME_DEPENDENCY_SET) command:
10809 • DIRECTORIES
10811 • PRE_INCLUDE_REGEXES
10813 • PRE_EXCLUDE_REGEXES
10815 • POST_INCLUDE_REGEXES
10817 • POST_EXCLUDE_REGEXES
10819 • POST_INCLUDE_FILES
10821 • POST_EXCLUDE_FILES
10823 The RUNTIME_DEPENDENCIES and RUNTIME_DEPENDENCY_SET keywords are
10825 mutually exclusive.
10826 One or more groups of properties may be specified in a single call to
10828 the TARGETS form of this command. A target may be installed more than
10829 once to different locations. Consider hypothetical targets myExe,
10830 mySharedLib, and myStaticLib. The code:
10831 install(TARGETS myExe mySharedLib myStaticLib
10833 RUNTIME DESTINATION bin
10834 LIBRARY DESTINATION lib
10835 ARCHIVE DESTINATION lib/static)
10836 install(TARGETS mySharedLib DESTINATION /some/full/path)
10837 will install myExe to <prefix>/bin and myStaticLib to <pre‐
10839 fix>/lib/static. On non-DLL platforms mySharedLib will be installed to
10840 <prefix>/lib and /some/full/path. On DLL platforms the mySharedLib DLL
10841 will be installed to <prefix>/bin and /some/full/path and its import
10842 library will be installed to <prefix>/lib/static and /some/full/path.
10843 Interface Libraries may be listed among the targets to install. They
10845 install no artifacts but will be included in an associated EXPORT. If
10846 Object Libraries are listed but given no destination for their object
10847 files, they will be exported as Interface Libraries. This is suffi‐
10848 cient to satisfy transitive usage requirements of other targets that
10849 link to the object libraries in their implementation.
10850 Installing a target with the EXCLUDE_FROM_ALL target property set to
10852 TRUE has undefined behavior.
10853 New in version 3.3: An install destination given as a DESTINATION argu‐
10855 ment may use "generator expressions" with the syntax $<...>. See the
10856 cmake-generator-expressions(7) manual for available expressions.
10857 New in version 3.13: install(TARGETS) can install targets that were
10860 created in other directories. When using such cross-directory install
10861 rules, running make install (or similar) from a subdirectory will not
10862 guarantee that targets from other directories are up-to-date. You can
10863 use target_link_libraries() or add_dependencies() to ensure that such
10864 out-of-directory targets are built before the subdirectory-specific in‐
10865 stall rules are run.
10866 Installing Imported Runtime Artifacts
10869 New in version 3.21.
10870 install(IMPORTED_RUNTIME_ARTIFACTS targets...
10873 [RUNTIME_DEPENDENCY_SET <set-name>]
10874 [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
10875 [DESTINATION <dir>]
10876 [PERMISSIONS permissions...]
10877 [CONFIGURATIONS [Debug|Release|...]]
10878 [COMPONENT <component>]
10879 [OPTIONAL] [EXCLUDE_FROM_ALL]
10880 ] [...]
10881 )
10882 The IMPORTED_RUNTIME_ARTIFACTS form specifies rules for installing the
10884 runtime artifacts of imported targets. Projects may do this if they
10885 want to bundle outside executables or modules inside their installa‐
10886 tion. The LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE arguments have the
10887 same semantics that they do in the TARGETS mode. Only the runtime arti‐
10888 facts of imported targets are installed (except in the case of
10889 FRAMEWORK libraries, MACOSX_BUNDLE executables, and BUNDLE CFBundles.)
10890 For example, headers and import libraries associated with DLLs are not
10891 installed. In the case of FRAMEWORK libraries, MACOSX_BUNDLE executa‐
10892 bles, and BUNDLE CFBundles, the entire directory is installed.
10893 The RUNTIME_DEPENDENCY_SET option causes the runtime artifacts of the
10895 imported executable, shared library, and module library targets to be
10896 added to the <set-name> runtime dependency set. This set can then be
10897 installed with an install(RUNTIME_DEPENDENCY_SET) command.
10898 Installing Files
10900 NOTE:
10901 If installing header files, consider using file sets defined by
10902 target_sources(FILE_SET) instead. File sets associate headers with a
10903 target and they install as part of the target.
10904 install(<FILES|PROGRAMS> files...
10906 TYPE <type> | DESTINATION <dir>
10907 [PERMISSIONS permissions...]
10908 [CONFIGURATIONS [Debug|Release|...]]
10909 [COMPONENT <component>]
10910 [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])
10911 The FILES form specifies rules for installing files for a project.
10913 File names given as relative paths are interpreted with respect to the
10914 current source directory. Files installed by this form are by default
10915 given permissions OWNER_WRITE, OWNER_READ, GROUP_READ, and WORLD_READ
10916 if no PERMISSIONS argument is given.
10917 The PROGRAMS form is identical to the FILES form except that the de‐
10919 fault permissions for the installed file also include OWNER_EXECUTE,
10920 GROUP_EXECUTE, and WORLD_EXECUTE. This form is intended to install
10921 programs that are not targets, such as shell scripts. Use the TARGETS
10922 form to install targets built within the project.
10923 The list of files... given to FILES or PROGRAMS may use "generator ex‐
10925 pressions" with the syntax $<...>. See the
10926 cmake-generator-expressions(7) manual for available expressions. How‐
10927 ever, if any item begins in a generator expression it must evaluate to
10928 a full path.
10929 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
10931 argument specifies the generic file type of the files being installed.
10932 A destination will then be set automatically by taking the correspond‐
10933 ing variable from GNUInstallDirs, or by using a built-in default if
10934 that variable is not defined. See the table below for the supported
10935 file types and their corresponding variables and built-in defaults.
10936 Projects can provide a DESTINATION argument instead of a file type if
10937 they wish to explicitly define the install destination.
10938 ┌──────────────┬─────────────────────┬─────────────────────┐
10940 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
10941 │ │ Variable │ │
10942 ├──────────────┼─────────────────────┼─────────────────────┤
10943 │BIN │ ${CMAKE_IN‐ │ bin │
10944 │ │ STALL_BINDIR} │ │
10945 ├──────────────┼─────────────────────┼─────────────────────┤
10946 │SBIN │ ${CMAKE_IN‐ │ sbin │
10947 │ │ STALL_SBINDIR} │ │
10948 ├──────────────┼─────────────────────┼─────────────────────┤
10949 │LIB │ ${CMAKE_IN‐ │ lib │
10950 │ │ STALL_LIBDIR} │ │
10951 ├──────────────┼─────────────────────┼─────────────────────┤
10952 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
10953 │ │ CLUDEDIR} │ │
10954 ├──────────────┼─────────────────────┼─────────────────────┤
10955 │SYSCONF │ ${CMAKE_IN‐ │ etc │
10956 │ │ STALL_SYSCONFDIR} │ │
10957 ├──────────────┼─────────────────────┼─────────────────────┤
10958 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
10959 │ │ STALL_SHARESTATE‐ │ │
10960 │ │ DIR} │ │
10961 ├──────────────┼─────────────────────┼─────────────────────┤
10962 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
10963 │ │ CALSTATEDIR} │ │
10964 ├──────────────┼─────────────────────┼─────────────────────┤
10965 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
10966 │ │ STALL_RUNSTATEDIR} │ dir>/run │
10967 ├──────────────┼─────────────────────┼─────────────────────┤
10968 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
10969 │ │ STALL_DATADIR} │ │
10970 ├──────────────┼─────────────────────┼─────────────────────┤
10971 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
10972 │ │ FODIR} │ │
10973 ├──────────────┼─────────────────────┼─────────────────────┤
10974 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
10975 │ │ CALEDIR} │ cale │
10976 ├──────────────┼─────────────────────┼─────────────────────┤
10977 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
10978 │ │ STALL_MANDIR} │ │
10979 ├──────────────┼─────────────────────┼─────────────────────┤
10980 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
10981 │ │ STALL_DOCDIR} │ │
10982 └──────────────┴─────────────────────┴─────────────────────┘
10983 Projects wishing to follow the common practice of installing headers
10985 into a project-specific subdirectory will need to provide a destination
10986 rather than rely on the above. Using file sets for headers instead of
10987 install(FILES) would be even better (see target_sources(FILE_SET)).
10988 Note that some of the types' built-in defaults use the DATAROOT direc‐
10990 tory as a prefix. The DATAROOT prefix is calculated similarly to the
10991 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
10992 built-in default. You cannot use DATAROOT as a TYPE parameter; please
10993 use DATA instead.
10994 To make packages compliant with distribution filesystem layout poli‐
10996 cies, if projects must specify a DESTINATION, it is recommended that
10997 they use a path that begins with the appropriate GNUInstallDirs vari‐
10998 able. This allows package maintainers to control the install destina‐
10999 tion by setting the appropriate cache variables. The following example
11000 shows how to follow this advice while installing an image to a
11001 project-specific documentation subdirectory:
11002 include(GNUInstallDirs)
11004 install(FILES logo.png
11005 DESTINATION ${CMAKE_INSTALL_DOCDIR}/myproj
11006 )
11007 New in version 3.4: An install destination given as a DESTINATION argu‐
11009 ment may use "generator expressions" with the syntax $<...>. See the
11010 cmake-generator-expressions(7) manual for available expressions.
11011 New in version 3.20: An install rename given as a RENAME argument may
11014 use "generator expressions" with the syntax $<...>. See the
11015 cmake-generator-expressions(7) manual for available expressions.
11016 Installing Directories
11019 NOTE:
11020 To install a directory sub-tree of headers, consider using file sets
11021 defined by target_sources(FILE_SET) instead. File sets not only pre‐
11022 serve directory structure, they also associate headers with a target
11023 and install as part of the target.
11024 install(DIRECTORY dirs...
11026 TYPE <type> | DESTINATION <dir>
11027 [FILE_PERMISSIONS permissions...]
11028 [DIRECTORY_PERMISSIONS permissions...]
11029 [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
11030 [CONFIGURATIONS [Debug|Release|...]]
11031 [COMPONENT <component>] [EXCLUDE_FROM_ALL]
11032 [FILES_MATCHING]
11033 [[PATTERN <pattern> | REGEX <regex>]
11034 [EXCLUDE] [PERMISSIONS permissions...]] [...])
11035 The DIRECTORY form installs contents of one or more directories to a
11037 given destination. The directory structure is copied verbatim to the
11038 destination. The last component of each directory name is appended to
11039 the destination directory but a trailing slash may be used to avoid
11040 this because it leaves the last component empty. Directory names given
11041 as relative paths are interpreted with respect to the current source
11042 directory. If no input directory names are given the destination di‐
11043 rectory will be created but nothing will be installed into it. The
11044 FILE_PERMISSIONS and DIRECTORY_PERMISSIONS options specify permissions
11045 given to files and directories in the destination. If USE_SOURCE_PER‐
11046 MISSIONS is specified and FILE_PERMISSIONS is not, file permissions
11047 will be copied from the source directory structure. If no permissions
11048 are specified files will be given the default permissions specified in
11049 the FILES form of the command, and the directories will be given the
11050 default permissions specified in the PROGRAMS form of the command.
11051 New in version 3.1: The MESSAGE_NEVER option disables file installation
11053 status output.
11054 Installation of directories may be controlled with fine granularity us‐
11057 ing the PATTERN or REGEX options. These "match" options specify a
11058 globbing pattern or regular expression to match directories or files
11059 encountered within input directories. They may be used to apply cer‐
11060 tain options (see below) to a subset of the files and directories en‐
11061 countered. The full path to each input file or directory (with forward
11062 slashes) is matched against the expression. A PATTERN will match only
11063 complete file names: the portion of the full path matching the pattern
11064 must occur at the end of the file name and be preceded by a slash. A
11065 REGEX will match any portion of the full path but it may use / and $ to
11066 simulate the PATTERN behavior. By default all files and directories
11067 are installed whether or not they are matched. The FILES_MATCHING op‐
11068 tion may be given before the first match option to disable installation
11069 of files (but not directories) not matched by any expression. For ex‐
11070 ample, the code
11071 install(DIRECTORY src/ DESTINATION doc/myproj
11073 FILES_MATCHING PATTERN "*.png")
11074 will extract and install images from a source tree.
11076 Some options may follow a PATTERN or REGEX expression as described un‐
11078 der string(REGEX) and are applied only to files or directories matching
11079 them. The EXCLUDE option will skip the matched file or directory. The
11080 PERMISSIONS option overrides the permissions setting for the matched
11081 file or directory. For example the code
11082 install(DIRECTORY icons scripts/ DESTINATION share/myproj
11084 PATTERN "CVS" EXCLUDE
11085 PATTERN "scripts/*"
11086 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
11087 GROUP_EXECUTE GROUP_READ)
11088 will install the icons directory to share/myproj/icons and the scripts
11090 directory to share/myproj. The icons will get default file permis‐
11091 sions, the scripts will be given specific permissions, and any CVS di‐
11092 rectories will be excluded.
11093 Either a TYPE or a DESTINATION must be provided, but not both. A TYPE
11095 argument specifies the generic file type of the files within the listed
11096 directories being installed. A destination will then be set automati‐
11097 cally by taking the corresponding variable from GNUInstallDirs, or by
11098 using a built-in default if that variable is not defined. See the ta‐
11099 ble below for the supported file types and their corresponding vari‐
11100 ables and built-in defaults. Projects can provide a DESTINATION argu‐
11101 ment instead of a file type if they wish to explicitly define the in‐
11102 stall destination.
11103 ┌──────────────┬─────────────────────┬─────────────────────┐
11105 │TYPE Argument │ GNUInstallDirs │ Built-In Default │
11106 │ │ Variable │ │
11107 └──────────────┴─────────────────────┴─────────────────────┘
11108 │BIN │ ${CMAKE_IN‐ │ bin │
11110 │ │ STALL_BINDIR} │ │
11111 ├──────────────┼─────────────────────┼─────────────────────┤
11112 │SBIN │ ${CMAKE_IN‐ │ sbin │
11113 │ │ STALL_SBINDIR} │ │
11114 ├──────────────┼─────────────────────┼─────────────────────┤
11115 │LIB │ ${CMAKE_IN‐ │ lib │
11116 │ │ STALL_LIBDIR} │ │
11117 ├──────────────┼─────────────────────┼─────────────────────┤
11118 │INCLUDE │ ${CMAKE_INSTALL_IN‐ │ include │
11119 │ │ CLUDEDIR} │ │
11120 ├──────────────┼─────────────────────┼─────────────────────┤
11121 │SYSCONF │ ${CMAKE_IN‐ │ etc │
11122 │ │ STALL_SYSCONFDIR} │ │
11123 ├──────────────┼─────────────────────┼─────────────────────┤
11124 │SHAREDSTATE │ ${CMAKE_IN‐ │ com │
11125 │ │ STALL_SHARESTATE‐ │ │
11126 │ │ DIR} │ │
11127 ├──────────────┼─────────────────────┼─────────────────────┤
11128 │LOCALSTATE │ ${CMAKE_INSTALL_LO‐ │ var │
11129 │ │ CALSTATEDIR} │ │
11130 ├──────────────┼─────────────────────┼─────────────────────┤
11131 │RUNSTATE │ ${CMAKE_IN‐ │ <LOCALSTATE │
11132 │ │ STALL_RUNSTATEDIR} │ dir>/run │
11133 ├──────────────┼─────────────────────┼─────────────────────┤
11134 │DATA │ ${CMAKE_IN‐ │ <DATAROOT dir> │
11135 │ │ STALL_DATADIR} │ │
11136 ├──────────────┼─────────────────────┼─────────────────────┤
11137 │INFO │ ${CMAKE_INSTALL_IN‐ │ <DATAROOT dir>/info │
11138 │ │ FODIR} │ │
11139 ├──────────────┼─────────────────────┼─────────────────────┤
11140 │LOCALE │ ${CMAKE_INSTALL_LO‐ │ <DATAROOT dir>/lo‐ │
11141 │ │ CALEDIR} │ cale │
11142 ├──────────────┼─────────────────────┼─────────────────────┤
11143 │MAN │ ${CMAKE_IN‐ │ <DATAROOT dir>/man │
11144 │ │ STALL_MANDIR} │ │
11145 ├──────────────┼─────────────────────┼─────────────────────┤
11146 │DOC │ ${CMAKE_IN‐ │ <DATAROOT dir>/doc │
11147 │ │ STALL_DOCDIR} │ │
11148 └──────────────┴─────────────────────┴─────────────────────┘
11149 Note that some of the types' built-in defaults use the DATAROOT direc‐
11151 tory as a prefix. The DATAROOT prefix is calculated similarly to the
11152 types, with CMAKE_INSTALL_DATAROOTDIR as the variable and share as the
11153 built-in default. You cannot use DATAROOT as a TYPE parameter; please
11154 use DATA instead.
11155 To make packages compliant with distribution filesystem layout poli‐
11157 cies, if projects must specify a DESTINATION, it is recommended that
11158 they use a path that begins with the appropriate GNUInstallDirs vari‐
11159 able. This allows package maintainers to control the install destina‐
11160 tion by setting the appropriate cache variables.
11161 New in version 3.4: An install destination given as a DESTINATION argu‐
11163 ment may use "generator expressions" with the syntax $<...>. See the
11164 cmake-generator-expressions(7) manual for available expressions.
11165 New in version 3.5: The list of dirs... given to DIRECTORY may use
11168 "generator expressions" too.
11169 Custom Installation Logic
11172 install([[SCRIPT <file>] [CODE <code>]]
11173 [ALL_COMPONENTS | COMPONENT <component>]
11174 [EXCLUDE_FROM_ALL] [...])
11175 The SCRIPT form will invoke the given CMake script files during instal‐
11177 lation. If the script file name is a relative path it will be inter‐
11178 preted with respect to the current source directory. The CODE form
11179 will invoke the given CMake code during installation. Code is speci‐
11180 fied as a single argument inside a double-quoted string. For example,
11181 the code
11182 install(CODE "MESSAGE(\"Sample install message.\")")
11184 will print a message during installation.
11186 New in version 3.21: When the ALL_COMPONENTS option is given, the cus‐
11188 tom installation script code will be executed for every component of a
11189 component-specific installation. This option is mutually exclusive
11190 with the COMPONENT option.
11191 New in version 3.14: <file> or <code> may use "generator expressions"
11194 with the syntax $<...> (in the case of <file>, this refers to their use
11195 in the file name, not the file's contents). See the
11196 cmake-generator-expressions(7) manual for available expressions.
11197 Installing Exports
11200 install(EXPORT <export-name> DESTINATION <dir>
11201 [NAMESPACE <namespace>] [FILE <name>.cmake]
11202 [PERMISSIONS permissions...]
11203 [CONFIGURATIONS [Debug|Release|...]
11204 [CXX_MODULES_DIRECTORY <directory>]
11205 [EXPORT_LINK_INTERFACE_LIBRARIES]
11206 [COMPONENT <component>]
11207 [EXCLUDE_FROM_ALL])
11208 install(EXPORT_ANDROID_MK <export-name> DESTINATION <dir> [...])
11209 The EXPORT form generates and installs a CMake file containing code to
11211 import targets from the installation tree into another project. Target
11212 installations are associated with the export <export-name> using the
11213 EXPORT option of the install(TARGETS) signature documented above. The
11214 NAMESPACE option will prepend <namespace> to the target names as they
11215 are written to the import file. By default the generated file will be
11216 called <export-name>.cmake but the FILE option may be used to specify a
11217 different name. The value given to the FILE option must be a file name
11218 with the .cmake extension. If a CONFIGURATIONS option is given then
11219 the file will only be installed when one of the named configurations is
11220 installed. Additionally, the generated import file will reference only
11221 the matching target configurations. See the
11222 CMAKE_MAP_IMPORTED_CONFIG_<CONFIG> variable to map configurations of
11223 dependent projects to the installed configurations. The EX‐
11224 PORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the contents
11225 of the properties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CON‐
11226 FIG>)? to be exported, when policy CMP0022 is NEW.
11227 NOTE:
11229 The installed <export-name>.cmake file may come with additional
11230 per-configuration <export-name>-*.cmake files to be loaded by glob‐
11231 bing. Do not use an export name that is the same as the package
11232 name in combination with installing a <package-name>-config.cmake
11233 file or the latter may be incorrectly matched by the glob and
11234 loaded.
11235 When a COMPONENT option is given, the listed <component> implicitly de‐
11237 pends on all components mentioned in the export set. The exported
11238 <name>.cmake file will require each of the exported components to be
11239 present in order for dependent projects to build properly. For example,
11240 a project may define components Runtime and Development, with shared
11241 libraries going into the Runtime component and static libraries and
11242 headers going into the Development component. The export set would also
11243 typically be part of the Development component, but it would export
11244 targets from both the Runtime and Development components. Therefore,
11245 the Runtime component would need to be installed if the Development
11246 component was installed, but not vice versa. If the Development compo‐
11247 nent was installed without the Runtime component, dependent projects
11248 that try to link against it would have build errors. Package managers,
11249 such as APT and RPM, typically handle this by listing the Runtime com‐
11250 ponent as a dependency of the Development component in the package
11251 metadata, ensuring that the library is always installed if the headers
11252 and CMake export file are present.
11253 New in version 3.7: In addition to cmake language files, the EXPORT_AN‐
11255 DROID_MK mode may be used to specify an export to the android ndk build
11256 system. This mode accepts the same options as the normal export mode.
11257 The Android NDK supports the use of prebuilt libraries, both static and
11258 shared. This allows cmake to build the libraries of a project and make
11259 them available to an ndk build system complete with transitive depen‐
11260 dencies, include flags and defines required to use the libraries.
11261 CXX_MODULES_DIRECTORY
11264 NOTE:
11266 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
11267 Specify a subdirectory to store C++ module information for targets
11269 in the export set. This directory will be populated with files which
11270 add the necessary target property information to the relevant tar‐
11271 gets. Note that without this information, none of the C++ modules
11272 which are part of the targets in the export set will support being
11273 imported in consuming targets.
11274 The EXPORT form is useful to help outside projects use targets built
11276 and installed by the current project. For example, the code
11277 install(TARGETS myexe EXPORT myproj DESTINATION bin)
11279 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
11280 install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
11281 will install the executable myexe to <prefix>/bin and code to import it
11283 in the file <prefix>/lib/myproj/myproj.cmake and <pre‐
11284 fix>/share/ndk-modules/Android.mk. An outside project may load this
11285 file with the include command and reference the myexe executable from
11286 the installation tree using the imported target name mp_myexe as if the
11287 target were built in its own tree.
11288 NOTE:
11290 This command supersedes the install_targets() command and the
11291 PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT target properties. It
11292 also replaces the FILES forms of the install_files() and
11293 install_programs() commands. The processing order of these install
11294 rules relative to those generated by install_targets(),
11295 install_files(), and install_programs() commands is not defined.
11296 Installing Runtime Dependencies
11298 New in version 3.21.
11299 install(RUNTIME_DEPENDENCY_SET <set-name>
11302 [[LIBRARY|RUNTIME|FRAMEWORK]
11303 [DESTINATION <dir>]
11304 [PERMISSIONS permissions...]
11305 [CONFIGURATIONS [Debug|Release|...]]
11306 [COMPONENT <component>]
11307 [NAMELINK_COMPONENT <component>]
11308 [OPTIONAL] [EXCLUDE_FROM_ALL]
11309 ] [...]
11310 [PRE_INCLUDE_REGEXES regexes...]
11311 [PRE_EXCLUDE_REGEXES regexes...]
11312 [POST_INCLUDE_REGEXES regexes...]
11313 [POST_EXCLUDE_REGEXES regexes...]
11314 [POST_INCLUDE_FILES files...]
11315 [POST_EXCLUDE_FILES files...]
11316 [DIRECTORIES directories...]
11317 )
11318 Installs a runtime dependency set previously created by one or more
11320 install(TARGETS) or install(IMPORTED_RUNTIME_ARTIFACTS) commands. The
11321 dependencies of targets belonging to a runtime dependency set are in‐
11322 stalled in the RUNTIME destination and component on DLL platforms, and
11323 in the LIBRARY destination and component on non-DLL platforms. macOS
11324 frameworks are installed in the FRAMEWORK destination and component.
11325 Targets built within the build tree will never be installed as runtime
11326 dependencies, nor will their own dependencies, unless the targets them‐
11327 selves are installed with install(TARGETS).
11328 The generated install script calls file(GET_RUNTIME_DEPENDENCIES) on
11330 the build-tree files to calculate the runtime dependencies. The
11331 build-tree executable files are passed as the EXECUTABLES argument, the
11332 build-tree shared libraries as the LIBRARIES argument, and the
11333 build-tree modules as the MODULES argument. On macOS, if one of the ex‐
11334 ecutables is a MACOSX_BUNDLE, that executable is passed as the BUN‐
11335 DLE_EXECUTABLE argument. At most one such bundle executable may be in
11336 the runtime dependency set on macOS. The MACOSX_BUNDLE property has no
11337 effect on other platforms. Note that file(GET_RUNTIME_DEPENDENCIES)
11338 only supports collecting the runtime dependencies for Windows, Linux
11339 and macOS platforms, so install(RUNTIME_DEPENDENCY_SET) has the same
11340 limitation.
11341 The following sub-arguments are forwarded through as the corresponding
11343 arguments to file(GET_RUNTIME_DEPENDENCIES) (for those that provide a
11344 non-empty list of directories, regular expressions or files). They all
11345 support generator expressions.
11346 • DIRECTORIES <directories>
11348 • PRE_INCLUDE_REGEXES <regexes>
11350 • PRE_EXCLUDE_REGEXES <regexes>
11352 • POST_INCLUDE_REGEXES <regexes>
11354 • POST_EXCLUDE_REGEXES <regexes>
11356 • POST_INCLUDE_FILES <files>
11358 • POST_EXCLUDE_FILES <files>
11360 Generated Installation Script
11362 NOTE:
11363 Use of this feature is not recommended. Please consider using the
11364 cmake --install instead.
11365 The install() command generates a file, cmake_install.cmake, inside the
11367 build directory, which is used internally by the generated install tar‐
11368 get and by CPack. You can also invoke this script manually with cmake
11369 -P. This script accepts several variables:
11370 COMPONENT
11372 Set this variable to install only a single CPack component as
11373 opposed to all of them. For example, if you only want to install
11374 the Development component, run cmake -DCOMPONENT=Development -P
11375 cmake_install.cmake.
11376 BUILD_TYPE
11378 Set this variable to change the build type if you are using a
11379 multi-config generator. For example, to install with the Debug
11380 configuration, run cmake -DBUILD_TYPE=Debug -P cmake_in‐
11381 stall.cmake.
11382 DESTDIR
11384 This is an environment variable rather than a CMake variable. It
11385 allows you to change the installation prefix on UNIX systems.
11386 See DESTDIR for details.
11387 link_directories
11389 Add directories in which the linker will look for libraries.
11390 link_directories([AFTER|BEFORE] directory1 [directory2 ...])
11392 Adds the paths in which the linker should search for libraries. Rela‐
11394 tive paths given to this command are interpreted as relative to the
11395 current source directory, see CMP0015.
11396 The command will apply only to targets created after it is called.
11398 New in version 3.13: The directories are added to the LINK_DIRECTORIES
11400 directory property for the current CMakeLists.txt file, converting rel‐
11401 ative paths to absolute as needed. See the cmake-buildsystem(7) manual
11402 for more on defining buildsystem properties.
11403 New in version 3.13: By default the directories specified are appended
11406 onto the current list of directories. This default behavior can be
11407 changed by setting CMAKE_LINK_DIRECTORIES_BEFORE to ON. By using AFTER
11408 or BEFORE explicitly, you can select between appending and prepending,
11409 independent of the default.
11410 New in version 3.13: Arguments to link_directories may use "generator
11413 expressions" with the syntax "$<...>". See the
11414 cmake-generator-expressions(7) manual for available expressions.
11415 NOTE:
11418 This command is rarely necessary and should be avoided where there
11419 are other choices. Prefer to pass full absolute paths to libraries
11420 where possible, since this ensures the correct library will always
11421 be linked. The find_library() command provides the full path, which
11422 can generally be used directly in calls to target_link_libraries().
11423 Situations where a library search path may be needed include:
11424 • Project generators like Xcode where the user can switch target ar‐
11426 chitecture at build time, but a full path to a library cannot be
11427 used because it only provides one architecture (i.e. it is not a
11428 universal binary).
11429 • Libraries may themselves have other private library dependencies
11431 that expect to be found via RPATH mechanisms, but some linkers are
11432 not able to fully decode those paths (e.g. due to the presence of
11433 things like $ORIGIN).
11434 If a library search path must be provided, prefer to localize the
11436 effect where possible by using the target_link_directories() command
11437 rather than link_directories(). The target-specific command can
11438 also control how the search directories propagate to other dependent
11439 targets.
11440 See Also
11442 • target_link_directories()
11443 • target_link_libraries()
11445 link_libraries
11447 Link libraries to all targets added later.
11448 link_libraries([item1 [item2 [...]]]
11450 [[debug|optimized|general] <item>] ...)
11451 Specify libraries or flags to use when linking any targets created
11453 later in the current directory or below by commands such as
11454 add_executable() or add_library(). See the target_link_libraries()
11455 command for meaning of arguments.
11456 NOTE:
11458 The target_link_libraries() command should be preferred whenever
11459 possible. Library dependencies are chained automatically, so direc‐
11460 tory-wide specification of link libraries is rarely needed.
11461 load_cache
11463 Load in the values from another project's CMake cache.
11464 load_cache(pathToBuildDirectory READ_WITH_PREFIX prefix entry1...)
11466 Reads the cache and store the requested entries in variables with their
11468 name prefixed with the given prefix. This only reads the values, and
11469 does not create entries in the local project's cache.
11470 load_cache(pathToBuildDirectory [EXCLUDE entry1...]
11472 [INCLUDE_INTERNALS entry1...])
11473 Loads in the values from another cache and store them in the local
11475 project's cache as internal entries. This is useful for a project that
11476 depends on another project built in a different tree. EXCLUDE option
11477 can be used to provide a list of entries to be excluded. INCLUDE_IN‐
11478 TERNALS can be used to provide a list of internal entries to be in‐
11479 cluded. Normally, no internal entries are brought in. Use of this
11480 form of the command is strongly discouraged, but it is provided for
11481 backward compatibility.
11482 project
11484 Set the name of the project.
11485 Synopsis
11487 project(<PROJECT-NAME> [<language-name>...])
11488 project(<PROJECT-NAME>
11489 [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
11490 [DESCRIPTION <project-description-string>]
11491 [HOMEPAGE_URL <url-string>]
11492 [LANGUAGES <language-name>...])
11493 Sets the name of the project, and stores it in the variable
11495 PROJECT_NAME. When called from the top-level CMakeLists.txt also stores
11496 the project name in the variable CMAKE_PROJECT_NAME.
11497 Also sets the variables:
11499 PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR
11501 Absolute path to the source directory for the project.
11502 PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR
11504 Absolute path to the binary directory for the project.
11505 PROJECT_IS_TOP_LEVEL, <PROJECT-NAME>_IS_TOP_LEVEL
11507 New in version 3.21.
11508 Boolean value indicating whether the project is top-level.
11511 Further variables are set by the optional arguments described in the
11513 following. If any of these arguments is not used, then the correspond‐
11514 ing variables are set to the empty string.
11515 Options
11517 The options are:
11518 VERSION <version>
11520 Optional; may not be used unless policy CMP0048 is set to NEW.
11521 Takes a <version> argument composed of non-negative integer com‐
11523 ponents, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets
11524 the variables
11525 • PROJECT_VERSION, <PROJECT-NAME>_VERSION
11527 • PROJECT_VERSION_MAJOR, <PROJECT-NAME>_VERSION_MAJOR
11529 • PROJECT_VERSION_MINOR, <PROJECT-NAME>_VERSION_MINOR
11531 • PROJECT_VERSION_PATCH, <PROJECT-NAME>_VERSION_PATCH
11533 • PROJECT_VERSION_TWEAK, <PROJECT-NAME>_VERSION_TWEAK.
11535 New in version 3.12: When the project() command is called from
11537 the top-level CMakeLists.txt, then the version is also stored in
11538 the variable CMAKE_PROJECT_VERSION.
11539 DESCRIPTION <project-description-string>
11542 New in version 3.9.
11543 Optional. Sets the variables
11546 • PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION
11548 to <project-description-string>. It is recommended that this
11550 description is a relatively short string, usually no more than a
11551 few words.
11552 When the project() command is called from the top-level CMake‐
11554 Lists.txt, then the description is also stored in the variable
11555 CMAKE_PROJECT_DESCRIPTION.
11556 New in version 3.12: Added the <PROJECT-NAME>_DESCRIPTION vari‐
11558 able.
11559 HOMEPAGE_URL <url-string>
11562 New in version 3.12.
11563 Optional. Sets the variables
11566 • PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL
11568 to <url-string>, which should be the canonical home URL for the
11570 project.
11571 When the project() command is called from the top-level CMake‐
11573 Lists.txt, then the URL also is stored in the variable
11574 CMAKE_PROJECT_HOMEPAGE_URL.
11575 LANGUAGES <language-name>...
11577 Optional. Can also be specified without LANGUAGES keyword per
11578 the first, short signature.
11579 Selects which programming languages are needed to build the
11581 project.
11582 Supported languages are C, CXX (i.e. C++), CSharp (i.e. C#), CUDA,
11584 OBJC (i.e. Objective-C), OBJCXX (i.e. Objective-C++), Fortran, HIP,
11585 ISPC, Swift, ASM, ASM_NASM, ASM_MARMASM, ASM_MASM, and ASM-ATT.
11586 New in version 3.8: Added CSharp and CUDA support.
11587 New in version 3.15: Added Swift support.
11590 New in version 3.16: Added OBJC and OBJCXX support.
11593 New in version 3.18: Added ISPC support.
11596 New in version 3.21: Added HIP support.
11599 New in version 3.26: Added ASM_MARMASM support.
11602 If enabling ASM, list it last so that CMake can check whether compilers
11605 for other languages like C work for assembly too.
11606 By default C and CXX are enabled if no language options are given.
11608 Specify language NONE, or use the LANGUAGES keyword and list no lan‐
11609 guages, to skip enabling any languages.
11610 The variables set through the VERSION, DESCRIPTION and HOMEPAGE_URL op‐
11612 tions are intended for use as default values in package metadata and
11613 documentation.
11614 Code Injection
11616 A number of variables can be defined by the user to specify files to
11617 include at different points during the execution of the project() com‐
11618 mand. The following outlines the steps performed during a project()
11619 call:
11620 • New in version 3.15: For every project() call regardless of the
11622 project name, include the file named by CMAKE_PROJECT_INCLUDE_BEFORE,
11623 if set.
11624 • New in version 3.17: If the project() command specifies
11627 <PROJECT-NAME> as its project name, include the file named by
11628 CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, if set.
11629 • Set the various project-specific variables detailed in the Synopsis
11632 and Options sections above.
11633 • For the very first project() call only:
11635 • If CMAKE_TOOLCHAIN_FILE is set, read it at least once. It may be
11637 read multiple times and it may also be read again when enabling
11638 languages later (see below).
11639 • Set the variables describing the host and target platforms. Lan‐
11641 guage-specific variables might or might not be set at this point.
11642 On the first run, the only language-specific variables that might
11643 be defined are those a toolchain file may have set. On subsequent
11644 runs, language-specific variables cached from a previous run may be
11645 set.
11646 • New in version 3.24: Include each file listed in
11648 CMAKE_PROJECT_TOP_LEVEL_INCLUDES, if set. The variable is ignored
11649 by CMake thereafter.
11650 • Enable any languages specified in the call, or the default languages
11653 if none were provided. The toolchain file may be re-read when en‐
11654 abling a language for the first time.
11655 • New in version 3.15: For every project() call regardless of the
11657 project name, include the file named by CMAKE_PROJECT_INCLUDE, if
11658 set.
11659 • If the project() command specifies <PROJECT-NAME> as its project
11662 name, include the file named by CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE,
11663 if set.
11664 Usage
11666 The top-level CMakeLists.txt file for a project must contain a literal,
11667 direct call to the project() command; loading one through the include()
11668 command is not sufficient. If no such call exists, CMake will issue a
11669 warning and pretend there is a project(Project) at the top to enable
11670 the default languages (C and CXX).
11671 NOTE:
11673 Call the project() command near the top of the top-level CMake‐
11674 Lists.txt, but after calling cmake_minimum_required(). It is impor‐
11675 tant to establish version and policy settings before invoking other
11676 commands whose behavior they may affect and for this reason the
11677 project() command will issue a warning if this order is not kept.
11678 See also policy CMP0000.
11679 remove_definitions
11681 Remove -D define flags added by add_definitions().
11682 remove_definitions(-DFOO -DBAR ...)
11684 Removes flags (added by add_definitions()) from the compiler command
11686 line for sources in the current directory and below.
11687 set_source_files_properties
11689 Source files can have properties that affect how they are built.
11690 set_source_files_properties(<files> ...
11692 [DIRECTORY <dirs> ...]
11693 [TARGET_DIRECTORY <targets> ...]
11694 PROPERTIES <prop1> <value1>
11695 [<prop2> <value2>] ...)
11696 Sets properties associated with source files using a key/value paired
11698 list.
11699 New in version 3.18: By default, source file properties are only visi‐
11701 ble to targets added in the same directory (CMakeLists.txt). Visibil‐
11702 ity can be set in other directory scopes using one or both of the fol‐
11703 lowing options:
11704 DIRECTORY <dirs>...
11707 The source file properties will be set in each of the <dirs> di‐
11708 rectories' scopes. CMake must already know about each of these
11709 source directories, either by having added them through a call
11710 to add_subdirectory() or it being the top level source direc‐
11711 tory. Relative paths are treated as relative to the current
11712 source directory.
11713 TARGET_DIRECTORY <targets>...
11715 The source file properties will be set in each of the directory
11716 scopes where any of the specified <targets> were created (the
11717 <targets> must therefore already exist).
11718 Use get_source_file_property() to get property values. See also the
11720 set_property(SOURCE) command.
11721 NOTE:
11723 The GENERATED source file property may be globally visible. See its
11724 documentation for details.
11725 See Also
11727 • define_property()
11728 • get_source_file_property()
11730 • Properties on Source Files for the list of properties known to CMake
11732 set_target_properties
11734 Targets can have properties that affect how they are built.
11735 set_target_properties(target1 target2 ...
11737 PROPERTIES prop1 value1
11738 prop2 value2 ...)
11739 Sets properties on targets. The syntax for the command is to list all
11741 the targets you want to change, and then provide the values you want to
11742 set next. You can use any prop value pair you want and extract it
11743 later with the get_property() or get_target_property() command.
11744 Alias Targets do not support setting target properties.
11746 See Also
11748 • define_property()
11749 • get_target_property()
11751 • the more general set_property() command
11753 • Properties on Targets for the list of properties known to CMake
11755 set_tests_properties
11757 Set a property of the tests.
11758 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
11760 Sets a property for the tests. If the test is not found, CMake will
11762 report an error.
11763 Test property values may be specified using generator expressions for
11765 tests created by the add_test(NAME) signature.
11766 See Also
11768 • add_test()
11769 • define_property()
11771 • the more general set_property() command
11773 • Properties on Targets for the list of properties known to CMake
11775 source_group
11777 Define a grouping for source files in IDE project generation. There
11778 are two different signatures to create source groups.
11779 source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
11781 source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...])
11782 Defines a group into which sources will be placed in project files.
11784 This is intended to set up file tabs in Visual Studio. The group is
11785 scoped in the directory where the command is called, and applies to
11786 sources in targets created in that directory.
11787 The options are:
11789 TREE New in version 3.8.
11791 CMake will automatically detect, from <src> files paths, source
11794 groups it needs to create, to keep structure of source groups
11795 analogically to the actual files and directories structure in
11796 the project. Paths of <src> files will be cut to be relative to
11797 <root>. The command fails if the paths within src do not start
11798 with root.
11799 PREFIX New in version 3.8.
11801 Source group and files located directly in <root> path, will be
11804 placed in <prefix> source groups.
11805 FILES Any source file specified explicitly will be placed in group
11807 <name>. Relative paths are interpreted with respect to the cur‐
11808 rent source directory.
11809 REGULAR_EXPRESSION
11811 Any source file whose name matches the regular expression will
11812 be placed in group <name>.
11813 If a source file matches multiple groups, the last group that explic‐
11815 itly lists the file with FILES will be favored, if any. If no group
11816 explicitly lists the file, the last group whose regular expression
11817 matches the file will be favored.
11818 The <name> of the group and <prefix> argument may contain forward
11820 slashes or backslashes to specify subgroups. Backslashes need to be
11821 escaped appropriately:
11822 source_group(base/subdir ...)
11824 source_group(outer\\inner ...)
11825 source_group(TREE <root> PREFIX sources\\inc ...)
11826 New in version 3.18: Allow using forward slashes (/) to specify sub‐
11828 groups.
11829 For backwards compatibility, the short-hand signature
11832 source_group(<name> <regex>)
11834 is equivalent to
11836 source_group(<name> REGULAR_EXPRESSION <regex>)
11838 target_compile_definitions
11840 Add compile definitions to a target.
11841 target_compile_definitions(<target>
11843 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11844 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11845 Specifies compile definitions to use when compiling a given <target>.
11847 The named <target> must have been created by a command such as
11848 add_executable() or add_library() and must not be an ALIAS target.
11849 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11851 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
11852 late the COMPILE_DEFINITIONS property of <target>. PUBLIC and INTERFACE
11853 items will populate the INTERFACE_COMPILE_DEFINITIONS property of <tar‐
11854 get>. The following arguments specify compile definitions. Repeated
11855 calls for the same <target> append items in the order called.
11856 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
11858 Arguments to target_compile_definitions may use generator expressions
11861 with the syntax $<...>. See the cmake-generator-expressions(7) manual
11862 for available expressions. See the cmake-buildsystem(7) manual for
11863 more on defining buildsystem properties.
11864 Any leading -D on an item will be removed. Empty items are ignored.
11866 For example, the following are all equivalent:
11867 target_compile_definitions(foo PUBLIC FOO)
11869 target_compile_definitions(foo PUBLIC -DFOO) # -D removed
11870 target_compile_definitions(foo PUBLIC "" FOO) # "" ignored
11871 target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored
11872 Definitions may optionally have values:
11874 target_compile_definitions(foo PUBLIC FOO=1)
11876 Note that many compilers treat -DFOO as equivalent to -DFOO=1, but
11878 other tools may not recognize this in all circumstances (e.g. Intel‐
11879 liSense).
11880 See Also
11882 • add_compile_definitions()
11883 • target_compile_features()
11885 • target_compile_options()
11887 • target_include_directories()
11889 • target_link_libraries()
11891 • target_link_directories()
11893 • target_link_options()
11895 • target_precompile_headers()
11897 • target_sources()
11899 target_compile_features
11901 New in version 3.1.
11902 Add expected compiler features to a target.
11905 target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
11907 Specifies compiler features required when compiling a given target. If
11909 the feature is not listed in the CMAKE_C_COMPILE_FEATURES,
11910 CMAKE_CUDA_COMPILE_FEATURES, or CMAKE_CXX_COMPILE_FEATURES variables,
11911 then an error will be reported by CMake. If the use of the feature re‐
11912 quires an additional compiler flag, such as -std=gnu++11, the flag will
11913 be added automatically.
11914 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11916 scope of the features. PRIVATE and PUBLIC items will populate the
11917 COMPILE_FEATURES property of <target>. PUBLIC and INTERFACE items will
11918 populate the INTERFACE_COMPILE_FEATURES property of <target>. Repeated
11919 calls for the same <target> append items.
11920 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
11922 The named <target> must have been created by a command such as
11925 add_executable() or add_library() and must not be an ALIAS target.
11926 for more on defining buildsystem properties.
11927 Arguments to target_compile_features may use generator expressions with
11929 the syntax $<...>. See the cmake-generator-expressions(7) manual for
11930 available expressions. See the cmake-compile-features(7) manual for
11931 information on compile features and a list of supported compilers.
11932 See Also
11934 • target_compile_definitions()
11935 • target_compile_options()
11937 • target_include_directories()
11939 • target_link_libraries()
11941 • target_link_directories()
11943 • target_link_options()
11945 • target_precompile_headers()
11947 • target_sources()
11949 target_compile_options
11951 Add compile options to a target.
11952 target_compile_options(<target> [BEFORE]
11954 <INTERFACE|PUBLIC|PRIVATE> [items1...]
11955 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
11956 Adds options to the COMPILE_OPTIONS or INTERFACE_COMPILE_OPTIONS target
11958 properties. These options are used when compiling the given <target>,
11959 which must have been created by a command such as add_executable() or
11960 add_library() and must not be an ALIAS target.
11961 NOTE:
11963 These options are not used when linking the target. See the
11964 target_link_options() command for that.
11965 Arguments
11967 If BEFORE is specified, the content will be prepended to the property
11968 instead of being appended. See policy CMP0101 which affects whether
11969 BEFORE will be ignored in certain cases.
11970 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
11972 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
11973 late the COMPILE_OPTIONS property of <target>. PUBLIC and INTERFACE
11974 items will populate the INTERFACE_COMPILE_OPTIONS property of <target>.
11975 The following arguments specify compile options. Repeated calls for
11976 the same <target> append items in the order called.
11977 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
11979 Arguments to target_compile_options may use generator expressions with
11982 the syntax $<...>. See the cmake-generator-expressions(7) manual for
11983 available expressions. See the cmake-buildsystem(7) manual for more on
11984 defining buildsystem properties.
11985 Option De-duplication
11987 The final set of options used for a target is constructed by accumulat‐
11988 ing options from the current target and the usage requirements of its
11989 dependencies. The set of options is de-duplicated to avoid repetition.
11990 New in version 3.12: While beneficial for individual options, the
11992 de-duplication step can break up option groups. For example, -option A
11993 -option B becomes -option A B. One may specify a group of options us‐
11994 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
11995 is dropped, and the rest of the option string is parsed using the
11996 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
11997 "SHELL:-option B" becomes -option A -option B.
11998 See Also
12001 • This command can be used to add any options. However, for adding pre‐
12002 processor definitions and include directories it is recommended to
12003 use the more specific commands target_compile_definitions() and
12004 target_include_directories().
12005 • For directory-wide settings, there is the command
12007 add_compile_options().
12008 • For file-specific settings, there is the source file property
12010 COMPILE_OPTIONS.
12011 • This command adds compile options for all languages in a target. Use
12013 the COMPILE_LANGUAGE generator expression to specify per-language
12014 compile options.
12015 • target_compile_features()
12017 • target_link_libraries()
12019 • target_link_directories()
12021 • target_link_options()
12023 • target_precompile_headers()
12025 • target_sources()
12027 • CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> add language-wide
12029 flags passed to all invocations of the compiler. This includes invo‐
12030 cations that drive compiling and those that drive linking.
12031 target_include_directories
12033 Add include directories to a target.
12034 target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
12036 <INTERFACE|PUBLIC|PRIVATE> [items1...]
12037 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
12038 Specifies include directories to use when compiling a given target.
12040 The named <target> must have been created by a command such as
12041 add_executable() or add_library() and must not be an ALIAS target.
12042 By using AFTER or BEFORE explicitly, you can select between appending
12044 and prepending, independent of the default.
12045 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
12047 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
12048 late the INCLUDE_DIRECTORIES property of <target>. PUBLIC and INTERFACE
12049 items will populate the INTERFACE_INCLUDE_DIRECTORIES property of <tar‐
12050 get>. The following arguments specify include directories.
12051 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
12053 Repeated calls for the same <target> append items in the order called.
12056 If SYSTEM is specified, the compiler will be told the directories are
12058 meant as system include directories on some platforms. This may have
12059 effects such as suppressing warnings or skipping the contained headers
12060 in dependency calculations (see compiler documentation). Additionally,
12061 system include directories are searched after normal include directo‐
12062 ries regardless of the order specified.
12063 If SYSTEM is used together with PUBLIC or INTERFACE, the
12065 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES target property will be populated
12066 with the specified directories.
12067 Arguments to target_include_directories may use generator expressions
12069 with the syntax $<...>. See the cmake-generator-expressions(7) manual
12070 for available expressions. See the cmake-buildsystem(7) manual for
12071 more on defining buildsystem properties.
12072 Specified include directories may be absolute paths or relative paths.
12074 A relative path will be interpreted as relative to the current source
12075 directory (i.e. CMAKE_CURRENT_SOURCE_DIR) and converted to an absolute
12076 path before storing it in the associated target property. If the path
12077 starts with a generator expression, it will always be assumed to be an
12078 absolute path (with one exception noted below) and will be used unmodi‐
12079 fied.
12080 Include directories usage requirements commonly differ between the
12082 build-tree and the install-tree. The BUILD_INTERFACE and
12083 INSTALL_INTERFACE generator expressions can be used to describe sepa‐
12084 rate usage requirements based on the usage location. Relative paths
12085 are allowed within the INSTALL_INTERFACE expression and are interpreted
12086 as relative to the installation prefix. Relative paths should not be
12087 used in BUILD_INTERFACE expressions because they will not be converted
12088 to absolute. For example:
12089 target_include_directories(mylib PUBLIC
12091 $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
12092 $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
12093 )
12094 Creating Relocatable Packages
12096 Note that it is not advisable to populate the INSTALL_INTERFACE of the
12097 INTERFACE_INCLUDE_DIRECTORIES of a target with absolute paths to the
12098 include directories of dependencies. That would hard-code into in‐
12099 stalled packages the include directory paths for dependencies as found
12100 on the machine the package was made on.
12101 The INSTALL_INTERFACE of the INTERFACE_INCLUDE_DIRECTORIES is only
12103 suitable for specifying the required include directories for headers
12104 provided with the target itself, not those provided by the transitive
12105 dependencies listed in its INTERFACE_LINK_LIBRARIES target property.
12106 Those dependencies should themselves be targets that specify their own
12107 header locations in INTERFACE_INCLUDE_DIRECTORIES.
12108 See the Creating Relocatable Packages section of the cmake-packages(7)
12110 manual for discussion of additional care that must be taken when speci‐
12111 fying usage requirements while creating packages for redistribution.
12112 See Also
12114 • include_directories()
12115 • target_compile_definitions()
12117 • target_compile_features()
12119 • target_compile_options()
12121 • target_link_libraries()
12123 • target_link_directories()
12125 • target_link_options()
12127 • target_precompile_headers()
12129 • target_sources()
12131 target_link_directories
12133 New in version 3.13.
12134 Add link directories to a target.
12137 target_link_directories(<target> [BEFORE]
12139 <INTERFACE|PUBLIC|PRIVATE> [items1...]
12140 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
12141 Specifies the paths in which the linker should search for libraries
12143 when linking a given target. Each item can be an absolute or relative
12144 path, with the latter being interpreted as relative to the current
12145 source directory. These items will be added to the link command.
12146 The named <target> must have been created by a command such as
12148 add_executable() or add_library() and must not be an ALIAS target.
12149 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
12151 scope of the items that follow them. PRIVATE and PUBLIC items will pop‐
12152 ulate the LINK_DIRECTORIES property of <target>. PUBLIC and INTERFACE
12153 items will populate the INTERFACE_LINK_DIRECTORIES property of <target>
12154 (IMPORTED targets only support INTERFACE items). Each item specifies a
12155 link directory and will be converted to an absolute path if necessary
12156 before adding it to the relevant property. Repeated calls for the same
12157 <target> append items in the order called.
12158 If BEFORE is specified, the content will be prepended to the relevant
12160 property instead of being appended.
12161 Arguments to target_link_directories may use generator expressions with
12163 the syntax $<...>. See the cmake-generator-expressions(7) manual for
12164 available expressions. See the cmake-buildsystem(7) manual for more on
12165 defining buildsystem properties.
12166 NOTE:
12168 This command is rarely necessary and should be avoided where there
12169 are other choices. Prefer to pass full absolute paths to libraries
12170 where possible, since this ensures the correct library will always
12171 be linked. The find_library() command provides the full path, which
12172 can generally be used directly in calls to target_link_libraries().
12173 Situations where a library search path may be needed include:
12174 • Project generators like Xcode where the user can switch target ar‐
12176 chitecture at build time, but a full path to a library cannot be
12177 used because it only provides one architecture (i.e. it is not a
12178 universal binary).
12179 • Libraries may themselves have other private library dependencies
12181 that expect to be found via RPATH mechanisms, but some linkers are
12182 not able to fully decode those paths (e.g. due to the presence of
12183 things like $ORIGIN).
12184 See Also
12186 • link_directories()
12187 • target_compile_definitions()
12189 • target_compile_features()
12191 • target_compile_options()
12193 • target_include_directories()
12195 • target_link_libraries()
12197 • target_link_options()
12199 • target_precompile_headers()
12201 • target_sources()
12203 target_link_libraries
12205 Specify libraries or flags to use when linking a given target and/or
12206 its dependents. Usage requirements from linked library targets will be
12207 propagated. Usage requirements of a target's dependencies affect com‐
12208 pilation of its own sources.
12209 Overview
12211 This command has several signatures as detailed in subsections below.
12212 All of them have the general form
12213 target_link_libraries(<target> ... <item>... ...)
12215 The named <target> must have been created by a command such as
12217 add_executable() or add_library() and must not be an ALIAS target. If
12218 policy CMP0079 is not set to NEW then the target must have been created
12219 in the current directory. Repeated calls for the same <target> append
12220 items in the order called.
12221 New in version 3.13: The <target> doesn't have to be defined in the
12223 same directory as the target_link_libraries call.
12224 Each <item> may be:
12227 • A library target name: The generated link line will have the full
12229 path to the linkable library file associated with the target. The
12230 buildsystem will have a dependency to re-link <target> if the library
12231 file changes.
12232 The named target must be created by add_library() within the project
12234 or as an IMPORTED library. If it is created within the project an
12235 ordering dependency will automatically be added in the build system
12236 to make sure the named library target is up-to-date before the <tar‐
12237 get> links.
12238 If an imported library has the IMPORTED_NO_SONAME target property
12240 set, CMake may ask the linker to search for the library instead of
12241 using the full path (e.g. /usr/lib/libfoo.so becomes -lfoo).
12242 The full path to the target's artifact will be quoted/escaped for the
12244 shell automatically.
12245 • A full path to a library file: The generated link line will normally
12247 preserve the full path to the file. The buildsystem will have a de‐
12248 pendency to re-link <target> if the library file changes.
12249 There are some cases where CMake may ask the linker to search for the
12251 library (e.g. /usr/lib/libfoo.so becomes -lfoo), such as when a
12252 shared library is detected to have no SONAME field. See policy
12253 CMP0060 for discussion of another case.
12254 If the library file is in a macOS framework, the Headers directory of
12256 the framework will also be processed as a usage requirement. This
12257 has the same effect as passing the framework directory as an include
12258 directory.
12259 New in version 3.8: On Visual Studio Generators for VS 2010 and
12261 above, library files ending in .targets will be treated as MSBuild
12262 targets files and imported into generated project files. This is not
12263 supported by other generators.
12264 The full path to the library file will be quoted/escaped for the
12267 shell automatically.
12268 • A plain library name: The generated link line will ask the linker to
12270 search for the library (e.g. foo becomes -lfoo or foo.lib).
12271 The library name/flag is treated as a command-line string fragment
12273 and will be used with no extra quoting or escaping.
12274 • A link flag: Item names starting with -, but not -l or -framework,
12276 are treated as linker flags. Note that such flags will be treated
12277 like any other library link item for purposes of transitive dependen‐
12278 cies, so they are generally safe to specify only as private link
12279 items that will not propagate to dependents.
12280 Link flags specified here are inserted into the link command in the
12282 same place as the link libraries. This might not be correct, depend‐
12283 ing on the linker. Use the LINK_OPTIONS target property or
12284 target_link_options() command to add link flags explicitly. The flags
12285 will then be placed at the toolchain-defined flag position in the
12286 link command.
12287 New in version 3.13: LINK_OPTIONS target property and
12289 target_link_options() command. For earlier versions of CMake, use
12290 LINK_FLAGS property instead.
12291 The link flag is treated as a command-line string fragment and will
12294 be used with no extra quoting or escaping.
12295 • A generator expression: A $<...> generator expression may evaluate to
12297 any of the above items or to a semicolon-separated list of them. If
12298 the ... contains any ; characters, e.g. after evaluation of a ${list}
12299 variable, be sure to use an explicitly quoted argument "$<...>" so
12300 that this command receives it as a single <item>.
12301 Additionally, a generator expression may be used as a fragment of any
12303 of the above items, e.g. foo$<1:_d>.
12304 Note that generator expressions will not be used in OLD handling of
12306 policy CMP0003 or policy CMP0004.
12307 • A debug, optimized, or general keyword immediately followed by an‐
12309 other <item>. The item following such a keyword will be used only
12310 for the corresponding build configuration. The debug keyword corre‐
12311 sponds to the Debug configuration (or to configurations named in the
12312 DEBUG_CONFIGURATIONS global property if it is set). The optimized
12313 keyword corresponds to all other configurations. The general keyword
12314 corresponds to all configurations, and is purely optional. Higher
12315 granularity may be achieved for per-configuration rules by creating
12316 and linking to IMPORTED library targets. These keywords are inter‐
12317 preted immediately by this command and therefore have no special
12318 meaning when produced by a generator expression.
12319 Items containing ::, such as Foo::Bar, are assumed to be IMPORTED or
12321 ALIAS library target names and will cause an error if no such target
12322 exists. See policy CMP0028.
12323 See the cmake-buildsystem(7) manual for more on defining buildsystem
12325 properties.
12326 Libraries for a Target and/or its Dependents
12328 target_link_libraries(<target>
12329 <PRIVATE|PUBLIC|INTERFACE> <item>...
12330 [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
12331 The PUBLIC, PRIVATE and INTERFACE scope keywords can be used to specify
12333 both the link dependencies and the link interface in one command.
12334 Libraries and targets following PUBLIC are linked to, and are made part
12336 of the link interface. Libraries and targets following PRIVATE are
12337 linked to, but are not made part of the link interface. Libraries fol‐
12338 lowing INTERFACE are appended to the link interface and are not used
12339 for linking <target>.
12340 Libraries for both a Target and its Dependents
12342 target_link_libraries(<target> <item>...)
12343 Library dependencies are transitive by default with this signature.
12345 When this target is linked into another target then the libraries
12346 linked to this target will appear on the link line for the other target
12347 too. This transitive "link interface" is stored in the
12348 INTERFACE_LINK_LIBRARIES target property and may be overridden by set‐
12349 ting the property directly. When CMP0022 is not set to NEW, transitive
12350 linking is built in but may be overridden by the
12351 LINK_INTERFACE_LIBRARIES property. Calls to other signatures of this
12352 command may set the property making any libraries linked exclusively by
12353 this signature private.
12354 Libraries for a Target and/or its Dependents (Legacy)
12356 target_link_libraries(<target>
12357 <LINK_PRIVATE|LINK_PUBLIC> <lib>...
12358 [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
12359 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify both the
12361 link dependencies and the link interface in one command.
12362 This signature is for compatibility only. Prefer the PUBLIC or PRIVATE
12364 keywords instead.
12365 Libraries and targets following LINK_PUBLIC are linked to, and are made
12367 part of the INTERFACE_LINK_LIBRARIES. If policy CMP0022 is not NEW,
12368 they are also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
12369 targets following LINK_PRIVATE are linked to, but are not made part of
12370 the INTERFACE_LINK_LIBRARIES (or LINK_INTERFACE_LIBRARIES).
12371 Libraries for Dependents Only (Legacy)
12373 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
12374 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
12376 INTERFACE_LINK_LIBRARIES target property instead of using them for
12377 linking. If policy CMP0022 is not NEW, then this mode also appends li‐
12378 braries to the LINK_INTERFACE_LIBRARIES and its per-configuration
12379 equivalent.
12380 This signature is for compatibility only. Prefer the INTERFACE mode
12382 instead.
12383 Libraries specified as debug are wrapped in a generator expression to
12385 correspond to debug builds. If policy CMP0022 is not NEW, the li‐
12386 braries are also appended to the LINK_INTERFACE_LIBRARIES_DEBUG prop‐
12387 erty (or to the properties corresponding to configurations listed in
12388 the DEBUG_CONFIGURATIONS global property if it is set). Libraries
12389 specified as optimized are appended to the INTERFACE_LINK_LIBRARIES
12390 property. If policy CMP0022 is not NEW, they are also appended to the
12391 LINK_INTERFACE_LIBRARIES property. Libraries specified as general (or
12392 without any keyword) are treated as if specified for both debug and op‐
12393 timized.
12394 Linking Object Libraries
12396 New in version 3.12.
12397 Object Libraries may be used as the <target> (first) argument of tar‐
12400 get_link_libraries to specify dependencies of their sources on other
12401 libraries. For example, the code
12402 add_library(A SHARED a.c)
12404 target_compile_definitions(A PUBLIC A)
12405 add_library(obj OBJECT obj.c)
12407 target_compile_definitions(obj PUBLIC OBJ)
12408 target_link_libraries(obj PUBLIC A)
12409 compiles obj.c with -DA -DOBJ and establishes usage requirements for
12411 obj that propagate to its dependents.
12412 Normal libraries and executables may link to Object Libraries to get
12414 their objects and usage requirements. Continuing the above example,
12415 the code
12416 add_library(B SHARED b.c)
12418 target_link_libraries(B PUBLIC obj)
12419 compiles b.c with -DA -DOBJ, creates shared library B with object files
12421 from b.c and obj.c, and links B to A. Furthermore, the code
12422 add_executable(main main.c)
12424 target_link_libraries(main B)
12425 compiles main.c with -DA -DOBJ and links executable main to B and A.
12427 The object library's usage requirements are propagated transitively
12428 through B, but its object files are not.
12429 Object Libraries may "link" to other object libraries to get usage re‐
12431 quirements, but since they do not have a link step nothing is done with
12432 their object files. Continuing from the above example, the code:
12433 add_library(obj2 OBJECT obj2.c)
12435 target_link_libraries(obj2 PUBLIC obj)
12436 add_executable(main2 main2.c)
12438 target_link_libraries(main2 obj2)
12439 compiles obj2.c with -DA -DOBJ, creates executable main2 with object
12441 files from main2.c and obj2.c, and links main2 to A.
12442 In other words, when Object Libraries appear in a target's
12444 INTERFACE_LINK_LIBRARIES property they will be treated as Interface Li‐
12445 braries, but when they appear in a target's LINK_LIBRARIES property
12446 their object files will be included in the link too.
12447 Linking Object Libraries via $<TARGET_OBJECTS>
12449 New in version 3.21.
12450 The object files associated with an object library may be referenced by
12453 the $<TARGET_OBJECTS> generator expression. Such object files are
12454 placed on the link line before all libraries, regardless of their rela‐
12455 tive order. Additionally, an ordering dependency will be added to the
12456 build system to make sure the object library is up-to-date before the
12457 dependent target links. For example, the code
12458 add_library(obj3 OBJECT obj3.c)
12460 target_compile_definitions(obj3 PUBLIC OBJ3)
12461 add_executable(main3 main3.c)
12463 target_link_libraries(main3 PRIVATE a3 $<TARGET_OBJECTS:obj3> b3)
12464 links executable main3 with object files from main3.c and obj3.c fol‐
12466 lowed by the a3 and b3 libraries. main3.c is not compiled with usage
12467 requirements from obj3, such as -DOBJ3.
12468 This approach can be used to achieve transitive inclusion of object
12470 files in link lines as usage requirements. Continuing the above exam‐
12471 ple, the code
12472 add_library(iface_obj3 INTERFACE)
12474 target_link_libraries(iface_obj3 INTERFACE obj3 $<TARGET_OBJECTS:obj3>)
12475 creates an interface library iface_obj3 that forwards the obj3 usage
12477 requirements and adds the obj3 object files to dependents' link lines.
12478 The code
12479 add_executable(use_obj3 use_obj3.c)
12481 target_link_libraries(use_obj3 PRIVATE iface_obj3)
12482 compiles use_obj3.c with -DOBJ3 and links executable use_obj3 with ob‐
12484 ject files from use_obj3.c and obj3.c.
12485 This also works transitively through a static library. Since a static
12487 library does not link, it does not consume the object files from object
12488 libraries referenced this way. Instead, the object files become tran‐
12489 sitive link dependencies of the static library. Continuing the above
12490 example, the code
12491 add_library(static3 STATIC static3.c)
12493 target_link_libraries(static3 PRIVATE iface_obj3)
12494 add_executable(use_static3 use_static3.c)
12496 target_link_libraries(use_static3 PRIVATE static3)
12497 compiles static3.c with -DOBJ3 and creates libstatic3.a using only its
12499 own object file. use_static3.c is compiled without -DOBJ3 because the
12500 usage requirement is not transitive through the private dependency of
12501 static3. However, the link dependencies of static3 are propagated, in‐
12502 cluding the iface_obj3 reference to $<TARGET_OBJECTS:obj3>. The
12503 use_static3 executable is created with object files from use_static3.c
12504 and obj3.c, and linked to library libstatic3.a.
12505 When using this approach, it is the project's responsibility to avoid
12507 linking multiple dependent binaries to iface_obj3, because they will
12508 all get the obj3 object files on their link lines.
12509 NOTE:
12511 Referencing $<TARGET_OBJECTS> in target_link_libraries calls worked
12512 in versions of CMake prior to 3.21 for some cases, but was not fully
12513 supported:
12514 • It did not place the object files before libraries on link lines.
12516 • It did not add an ordering dependency on the object library.
12518 • It did not work in Xcode with multiple architectures.
12520 Cyclic Dependencies of Static Libraries
12522 The library dependency graph is normally acyclic (a DAG), but in the
12523 case of mutually-dependent STATIC libraries CMake allows the graph to
12524 contain cycles (strongly connected components). When another target
12525 links to one of the libraries, CMake repeats the entire connected com‐
12526 ponent. For example, the code
12527 add_library(A STATIC a.c)
12529 add_library(B STATIC b.c)
12530 target_link_libraries(A B)
12531 target_link_libraries(B A)
12532 add_executable(main main.c)
12533 target_link_libraries(main A)
12534 links main to A B A B. While one repetition is usually sufficient,
12536 pathological object file and symbol arrangements can require more. One
12537 may handle such cases by using the LINK_INTERFACE_MULTIPLICITY target
12538 property or by manually repeating the component in the last tar‐
12539 get_link_libraries call. However, if two archives are really so inter‐
12540 dependent they should probably be combined into a single archive, per‐
12541 haps by using Object Libraries.
12542 Creating Relocatable Packages
12544 Note that it is not advisable to populate the INTERFACE_LINK_LIBRARIES
12545 of a target with absolute paths to dependencies. That would hard-code
12546 into installed packages the library file paths for dependencies as
12547 found on the machine the package was made on.
12548 See the Creating Relocatable Packages section of the cmake-packages(7)
12550 manual for discussion of additional care that must be taken when speci‐
12551 fying usage requirements while creating packages for redistribution.
12552 See Also
12554 • target_compile_definitions()
12555 • target_compile_features()
12557 • target_compile_options()
12559 • target_include_directories()
12561 • target_link_directories()
12563 • target_link_options()
12565 • target_precompile_headers()
12567 • target_sources()
12569 target_link_options
12571 New in version 3.13.
12572 Add options to the link step for an executable, shared library or mod‐
12575 ule library target.
12576 target_link_options(<target> [BEFORE]
12578 <INTERFACE|PUBLIC|PRIVATE> [items1...]
12579 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
12580 The named <target> must have been created by a command such as
12582 add_executable() or add_library() and must not be an ALIAS target.
12583 This command can be used to add any link options, but alternative com‐
12585 mands exist to add libraries (target_link_libraries() or
12586 link_libraries()). See documentation of the directory and target
12587 LINK_OPTIONS properties.
12588 NOTE:
12590 This command cannot be used to add options for static library tar‐
12591 gets, since they do not use a linker. To add archiver or MSVC li‐
12592 brarian flags, see the STATIC_LIBRARY_OPTIONS target property.
12593 If BEFORE is specified, the content will be prepended to the property
12595 instead of being appended.
12596 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
12598 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
12599 late the LINK_OPTIONS property of <target>. PUBLIC and INTERFACE items
12600 will populate the INTERFACE_LINK_OPTIONS property of <target>. The
12601 following arguments specify link options. Repeated calls for the same
12602 <target> append items in the order called.
12603 NOTE:
12605 IMPORTED targets only support INTERFACE items.
12606 Arguments to target_link_options may use generator expressions with the
12608 syntax $<...>. See the cmake-generator-expressions(7) manual for avail‐
12609 able expressions. See the cmake-buildsystem(7) manual for more on
12610 defining buildsystem properties.
12611 Host And Device Specific Link Options
12613 New in version 3.18: When a device link step is involved, which is con‐
12614 trolled by CUDA_SEPARABLE_COMPILATION and CUDA_RESOLVE_DEVICE_SYMBOLS
12615 properties and policy CMP0105, the raw options will be delivered to the
12616 host and device link steps (wrapped in -Xcompiler or equivalent for de‐
12617 vice link). Options wrapped with $<DEVICE_LINK:...> generator expres‐
12618 sion will be used only for the device link step. Options wrapped with
12619 $<HOST_LINK:...> generator expression will be used only for the host
12620 link step.
12621 Option De-duplication
12624 The final set of options used for a target is constructed by accumulat‐
12625 ing options from the current target and the usage requirements of its
12626 dependencies. The set of options is de-duplicated to avoid repetition.
12627 New in version 3.12: While beneficial for individual options, the
12629 de-duplication step can break up option groups. For example, -option A
12630 -option B becomes -option A B. One may specify a group of options us‐
12631 ing shell-like quoting along with a SHELL: prefix. The SHELL: prefix
12632 is dropped, and the rest of the option string is parsed using the
12633 separate_arguments() UNIX_COMMAND mode. For example, "SHELL:-option A"
12634 "SHELL:-option B" becomes -option A -option B.
12635 Handling Compiler Driver Differences
12638 To pass options to the linker tool, each compiler driver has its own
12639 syntax. The LINKER: prefix and , separator can be used to specify, in
12640 a portable way, options to pass to the linker tool. LINKER: is replaced
12641 by the appropriate driver option and , by the appropriate driver sepa‐
12642 rator. The driver prefix and driver separator are given by the values
12643 of the CMAKE_<LANG>_LINKER_WRAPPER_FLAG and
12644 CMAKE_<LANG>_LINKER_WRAPPER_FLAG_SEP variables.
12645 For example, "LINKER:-z,defs" becomes -Xlinker -z -Xlinker defs for
12647 Clang and -Wl,-z,defs for GNU GCC.
12648 The LINKER: prefix can be specified as part of a SHELL: prefix expres‐
12650 sion.
12651 The LINKER: prefix supports, as an alternative syntax, specification of
12653 arguments using the SHELL: prefix and space as separator. The previous
12654 example then becomes "LINKER:SHELL:-z defs".
12655 NOTE:
12657 Specifying the SHELL: prefix anywhere other than at the beginning of
12658 the LINKER: prefix is not supported.
12659 See Also
12661 • target_compile_definitions()
12662 • target_compile_features()
12664 • target_compile_options()
12666 • target_include_directories()
12668 • target_link_libraries()
12670 • target_link_directories()
12672 • target_precompile_headers()
12674 • target_sources()
12676 • CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> add language-wide
12678 flags passed to all invocations of the compiler. This includes invo‐
12679 cations that drive compiling and those that drive linking.
12680 target_precompile_headers
12682 New in version 3.16.
12683 Add a list of header files to precompile.
12686 Precompiling header files can speed up compilation by creating a par‐
12688 tially processed version of some header files, and then using that ver‐
12689 sion during compilations rather than repeatedly parsing the original
12690 headers.
12691 Main Form
12693 target_precompile_headers(<target>
12694 <INTERFACE|PUBLIC|PRIVATE> [header1...]
12695 [<INTERFACE|PUBLIC|PRIVATE> [header2...] ...])
12696 The command adds header files to the PRECOMPILE_HEADERS and/or
12698 INTERFACE_PRECOMPILE_HEADERS target properties of <target>. The named
12699 <target> must have been created by a command such as add_executable()
12700 or add_library() and must not be an ALIAS target.
12701 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
12703 scope of the following arguments. PRIVATE and PUBLIC items will popu‐
12704 late the PRECOMPILE_HEADERS property of <target>. PUBLIC and INTERFACE
12705 items will populate the INTERFACE_PRECOMPILE_HEADERS property of <tar‐
12706 get> (IMPORTED targets only support INTERFACE items). Repeated calls
12707 for the same <target> will append items in the order called.
12708 Projects should generally avoid using PUBLIC or INTERFACE for targets
12710 that will be exported, or they should at least use the
12711 $<BUILD_INTERFACE:...> generator expression to prevent precompile head‐
12712 ers from appearing in an installed exported target. Consumers of a
12713 target should typically be in control of what precompile headers they
12714 use, not have precompile headers forced on them by the targets being
12715 consumed (since precompile headers are not typically usage require‐
12716 ments). A notable exception to this is where an interface library is
12717 created to define a commonly used set of precompile headers in one
12718 place and then other targets link to that interface library privately.
12719 In this case, the interface library exists specifically to propagate
12720 the precompile headers to its consumers and the consumer is effectively
12721 still in control, since it decides whether to link to the interface li‐
12722 brary or not.
12723 The list of header files is used to generate a header file named
12725 cmake_pch.h|xx which is used to generate the precompiled header file
12726 (.pch, .gch, .pchi) artifact. The cmake_pch.h|xx header file will be
12727 force included (-include for GCC, /FI for MSVC) to all source files, so
12728 sources do not need to have #include "pch.h".
12729 Header file names specified with angle brackets (e.g. <unordered_map>)
12731 or explicit double quotes (escaped for the cmake-language(7), e.g.
12732 [["other_header.h"]]) will be treated as is, and include directories
12733 must be available for the compiler to find them. Other header file
12734 names (e.g. project_header.h) are interpreted as being relative to the
12735 current source directory (e.g. CMAKE_CURRENT_SOURCE_DIR) and will be
12736 included by absolute path. For example:
12737 target_precompile_headers(myTarget
12739 PUBLIC
12740 project_header.h
12741 PRIVATE
12742 [["other_header.h"]]
12743 <unordered_map>
12744 )
12745 for more on defining buildsystem properties.
12746 Arguments to target_precompile_headers may use generator expressions
12748 with the syntax $<...>. See the cmake-generator-expressions(7) manual
12749 for available expressions. The $<COMPILE_LANGUAGE:...> generator ex‐
12750 pression is particularly useful for specifying a language-specific
12751 header to precompile for only one language (e.g. CXX and not C). In
12752 this case, header file names that are not explicitly in double quotes
12753 or angle brackets must be specified by absolute path. Also, when spec‐
12754 ifying angle brackets inside a generator expression, be sure to encode
12755 the closing > as $<ANGLE-R>. For example:
12756 target_precompile_headers(mylib PRIVATE
12758 "$<$<COMPILE_LANGUAGE:CXX>:${CMAKE_CURRENT_SOURCE_DIR}/cxx_only.h>"
12759 "$<$<COMPILE_LANGUAGE:C>:<stddef.h$<ANGLE-R>>"
12760 "$<$<COMPILE_LANGUAGE:CXX>:<cstddef$<ANGLE-R>>"
12761 )
12762 Reusing Precompile Headers
12764 The command also supports a second signature which can be used to spec‐
12765 ify that one target re-uses a precompiled header file artifact from an‐
12766 other target instead of generating its own:
12767 target_precompile_headers(<target> REUSE_FROM <other_target>)
12769 This form sets the PRECOMPILE_HEADERS_REUSE_FROM property to
12771 <other_target> and adds a dependency such that <target> will depend on
12772 <other_target>. CMake will halt with an error if the
12773 PRECOMPILE_HEADERS property of <target> is already set when the RE‐
12774 USE_FROM form is used.
12775 NOTE:
12777 The REUSE_FROM form requires the same set of compiler options, com‐
12778 piler flags and compiler definitions for both <target> and
12779 <other_target>. Some compilers (e.g. GCC) may issue a warning if
12780 the precompiled header file cannot be used (-Winvalid-pch).
12781 See Also
12783 • To disable precompile headers for specific targets, see the
12784 DISABLE_PRECOMPILE_HEADERS target property.
12785 • To prevent precompile headers from being used when compiling a spe‐
12787 cific source file, see the SKIP_PRECOMPILE_HEADERS source file prop‐
12788 erty.
12789 • target_compile_definitions()
12791 • target_compile_features()
12793 • target_compile_options()
12795 • target_include_directories()
12797 • target_link_libraries()
12799 • target_link_directories()
12801 • target_link_options()
12803 • target_sources()
12805 target_sources
12807 New in version 3.1.
12808 Add sources to a target.
12811 target_sources(<target>
12813 <INTERFACE|PUBLIC|PRIVATE> [items1...]
12814 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
12815 Specifies sources to use when building a target and/or its dependents.
12817 The named <target> must have been created by a command such as
12818 add_executable() or add_library() or add_custom_target() and must not
12819 be an ALIAS target. The <items> may use generator expressions.
12820 New in version 3.20: <target> can be a custom target.
12822 The INTERFACE, PUBLIC and PRIVATE keywords are required to specify the
12825 scope of the source file paths (<items>) that follow them. PRIVATE and
12826 PUBLIC items will populate the SOURCES property of <target>, which are
12827 used when building the target itself. PUBLIC and INTERFACE items will
12828 populate the INTERFACE_SOURCES property of <target>, which are used
12829 when building dependents. A target created by add_custom_target() can
12830 only have PRIVATE scope.
12831 Repeated calls for the same <target> append items in the order called.
12833 New in version 3.3: Allow exporting targets with INTERFACE_SOURCES.
12835 New in version 3.11: Allow setting INTERFACE items on IMPORTED targets.
12838 Changed in version 3.13: Relative source file paths are interpreted as
12841 being relative to the current source directory (i.e.
12842 CMAKE_CURRENT_SOURCE_DIR). See policy CMP0076.
12843 A path that begins with a generator expression is left unmodified.
12846 When a target's SOURCE_DIR property differs from
12847 CMAKE_CURRENT_SOURCE_DIR, use absolute paths in generator expressions
12848 to ensure the sources are correctly assigned to the target.
12849 # WRONG: starts with generator expression, but relative path used
12851 target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:dbgsrc.cpp>")
12852 # CORRECT: absolute path used inside the generator expression
12854 target_sources(MyTarget PRIVATE "$<$<CONFIG:Debug>:${CMAKE_CURRENT_SOURCE_DIR}/dbgsrc.cpp>")
12855 See the cmake-buildsystem(7) manual for more on defining buildsystem
12857 properties.
12858 File Sets
12860 New in version 3.23.
12861 target_sources(<target>
12864 [<INTERFACE|PUBLIC|PRIVATE>
12865 [FILE_SET <set> [TYPE <type>] [BASE_DIRS <dirs>...] [FILES <files>...]]...
12866 ]...)
12867 Adds a file set to a target, or adds files to an existing file set.
12869 Targets have zero or more named file sets. Each file set has a name, a
12870 type, a scope of INTERFACE, PUBLIC, or PRIVATE, one or more base direc‐
12871 tories, and files within those directories. The acceptable types in‐
12872 clude:
12873 HEADERS
12875 Sources intended to be used via a language's #include mechanism.
12876 CXX_MODULES
12878 NOTE:
12880 Experimental. Gated by CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API
12881 Sources which contain C++ interface module or partition units (i.e.,
12883 those using the export keyword). This file set type may not have an
12884 INTERFACE scope except on IMPORTED targets.
12885 The optional default file sets are named after their type. The target
12887 may not be a custom target or FRAMEWORK target.
12888 Files in a PRIVATE or PUBLIC file set are marked as source files for
12890 the purposes of IDE integration. Additionally, files in HEADERS file
12891 sets have their HEADER_FILE_ONLY property set to TRUE. Files in an IN‐
12892 TERFACE or PUBLIC file set can be installed with the install(TARGETS)
12893 command, and exported with the install(EXPORT) and export() commands.
12894 Each target_sources(FILE_SET) entry starts with INTERFACE, PUBLIC, or
12896 PRIVATE and accepts the following arguments:
12897 FILE_SET <set>
12899 The name of the file set to create or add to. It must contain only
12900 letters, numbers and underscores. Names starting with a capital let‐
12901 ter are reserved for built-in file sets predefined by CMake. The
12902 only predefined set names are those matching the acceptable types.
12903 All other set names must not start with a capital letter or under‐
12904 score.
12905 TYPE <type>
12907 Every file set is associated with a particular type of file. Only
12908 types specified above may be used and it is an error to specify any‐
12909 thing else. As a special case, if the name of the file set is one of
12910 the types, the type does not need to be specified and the TYPE
12911 <type> arguments can be omitted. For all other file set names, TYPE
12912 is required.
12913 BASE_DIRS <dirs>...
12915 An optional list of base directories of the file set. Any relative
12916 path is treated as relative to the current source directory (i.e.
12917 CMAKE_CURRENT_SOURCE_DIR). If no BASE_DIRS are specified when the
12918 file set is first created, the value of CMAKE_CURRENT_SOURCE_DIR is
12919 added. This argument supports generator expressions.
12920 No two base directories for a file set may be sub-directories of
12922 each other. This requirement must be met across all base directo‐
12923 ries added to a file set, not just those within a single call to
12924 target_sources().
12925 FILES <files>...
12927 An optional list of files to add to the file set. Each file must be
12928 in one of the base directories, or a subdirectory of one of the base
12929 directories. This argument supports generator expressions.
12930 If relative paths are specified, they are considered relative to
12932 CMAKE_CURRENT_SOURCE_DIR at the time target_sources() is called. An
12933 exception to this is a path starting with $<. Such paths are treated
12934 as relative to the target's source directory after evaluation of
12935 generator expressions.
12936 The following target properties are set by target_sources(FILE_SET),
12938 but they should not generally be manipulated directly:
12939 For file sets of type HEADERS:
12941 • HEADER_SETS
12943 • INTERFACE_HEADER_SETS
12945 • HEADER_SET
12947 • HEADER_SET_<NAME>
12949 • HEADER_DIRS
12951 • HEADER_DIRS_<NAME>
12953 For file sets of type CXX_MODULES:
12955 • CXX_MODULE_SETS
12957 • INTERFACE_CXX_MODULE_SETS
12959 • CXX_MODULE_SET
12961 • CXX_MODULE_SET_<NAME>
12963 • CXX_MODULE_DIRS
12965 • CXX_MODULE_DIRS_<NAME>
12967 Target properties related to include directories are also modified by
12969 target_sources(FILE_SET) as follows:
12970 INCLUDE_DIRECTORIES
12972 If the TYPE is HEADERS, and the scope of the file set is PRIVATE or
12973 PUBLIC, all of the BASE_DIRS of the file set are wrapped in
12974 $<BUILD_INTERFACE> and appended to this property.
12975 INTERFACE_INCLUDE_DIRECTORIES
12977 If the TYPE is HEADERS, and the scope of the file set is INTERFACE
12978 or PUBLIC, all of the BASE_DIRS of the file set are wrapped in
12979 $<BUILD_INTERFACE> and appended to this property.
12980 See Also
12982 • add_executable()
12983 • add_library()
12985 • target_compile_definitions()
12987 • target_compile_features()
12989 • target_compile_options()
12991 • target_include_directories()
12993 • target_link_libraries()
12995 • target_link_directories()
12997 • target_link_options()
12999 • target_precompile_headers()
13001 try_compile
13003 Try building some code.
13004 Try Compiling Whole Projects
13006 try_compile(<compileResultVar> PROJECT <projectName>
13007 SOURCE_DIR <srcdir>
13008 [BINARY_DIR <bindir>]
13009 [TARGET <targetName>]
13010 [LOG_DESCRIPTION <text>]
13011 [NO_CACHE]
13012 [NO_LOG]
13013 [CMAKE_FLAGS <flags>...]
13014 [OUTPUT_VARIABLE <var>])
13015 New in version 3.25.
13017 Try building a project. Build success returns TRUE and build failure
13020 returns FALSE in <compileResultVar>.
13021 In this form, <srcdir> should contain a complete CMake project with a
13023 CMakeLists.txt file and all sources. The <bindir> and <srcdir> will
13024 not be deleted after this command is run. Specify <targetName> to
13025 build a specific target instead of the all or ALL_BUILD target. See
13026 below for the meaning of other options.
13027 Changed in version 3.24: CMake variables describing platform settings,
13029 and those listed by the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES variable,
13030 are propagated into the project's build configuration. See policy
13031 CMP0137. Previously this was only done by the source file signature.
13032 New in version 3.26: This command records a configure-log try_compile
13035 event if the NO_LOG option is not specified.
13036 This command supports an alternate signature for CMake older than 3.25.
13039 The signature above is recommended for clarity.
13040 try_compile(<compileResultVar> <bindir> <srcdir>
13042 <projectName> [<targetName>]
13043 [CMAKE_FLAGS <flags>...]
13044 [OUTPUT_VARIABLE <var>])
13045 Try Compiling Source Files
13047 try_compile(<compileResultVar>
13048 <SOURCES <srcfile...> |
13049 SOURCE_FROM_CONTENT <name> <content> |
13050 SOURCE_FROM_VAR <name> <var> |
13051 SOURCE_FROM_FILE <name> <path> >...
13052 [LOG_DESCRIPTION <text>]
13053 [NO_CACHE]
13054 [NO_LOG]
13055 [CMAKE_FLAGS <flags>...]
13056 [COMPILE_DEFINITIONS <defs>...]
13057 [LINK_OPTIONS <options>...]
13058 [LINK_LIBRARIES <libs>...]
13059 [OUTPUT_VARIABLE <var>]
13060 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
13061 [<LANG>_STANDARD <std>]
13062 [<LANG>_STANDARD_REQUIRED <bool>]
13063 [<LANG>_EXTENSIONS <bool>]
13064 )
13065 New in version 3.25.
13067 Try building an executable or static library from one or more source
13070 files (which one is determined by the CMAKE_TRY_COMPILE_TARGET_TYPE
13071 variable). Build success returns TRUE and build failure returns FALSE
13072 in <compileResultVar>.
13073 In this form, one or more source files must be provided. Additionally,
13075 one of SOURCES and/or SOURCE_FROM_* must precede other keywords.
13076 If CMAKE_TRY_COMPILE_TARGET_TYPE is unset or is set to EXECUTABLE, the
13078 sources must include a definition for main and CMake will create a
13079 CMakeLists.txt file to build the source(s) as an executable. If
13080 CMAKE_TRY_COMPILE_TARGET_TYPE is set to STATIC_LIBRARY, a static li‐
13081 brary will be built instead and no definition for main is required.
13082 For an executable, the generated CMakeLists.txt file would contain
13083 something like the following:
13084 add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
13086 include_directories(${INCLUDE_DIRECTORIES})
13087 link_directories(${LINK_DIRECTORIES})
13088 add_executable(cmTryCompileExec <srcfile>...)
13089 target_link_options(cmTryCompileExec PRIVATE <LINK_OPTIONS from caller>)
13090 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
13091 CMake automatically generates, for each try_compile operation, a unique
13093 directory under ${CMAKE_BINARY_DIR}/CMakeFiles/CMakeScratch with an un‐
13094 specified name. These directories are cleaned automatically unless
13095 --debug-trycompile is passed to cmake. Such directories from previous
13096 runs are also unconditionally cleaned at the beginning of any cmake ex‐
13097 ecution.
13098 This command supports an alternate signature for CMake older than 3.25.
13100 The signature above is recommended for clarity.
13101 try_compile(<compileResultVar> <bindir> <srcfile|SOURCES srcfile...>
13103 [CMAKE_FLAGS <flags>...]
13104 [COMPILE_DEFINITIONS <defs>...]
13105 [LINK_OPTIONS <options>...]
13106 [LINK_LIBRARIES <libs>...]
13107 [OUTPUT_VARIABLE <var>]
13108 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
13109 [<LANG>_STANDARD <std>]
13110 [<LANG>_STANDARD_REQUIRED <bool>]
13111 [<LANG>_EXTENSIONS <bool>]
13112 )
13113 In this version, try_compile will use <bindir>/CMakeFiles/CMakeTmp for
13115 its operation, and all such files will be cleaned automatically. For
13116 debugging, --debug-trycompile can be passed to cmake to avoid this
13117 clean. However, multiple sequential try_compile operations, if given
13118 the same <bindir>, will reuse this single output directory, such that
13119 you can only debug one such try_compile call at a time. Use of the
13120 newer signature is recommended to simplify debugging of multiple
13121 try_compile operations.
13122 The options are:
13124 CMAKE_FLAGS <flags>...
13126 Specify flags of the form -DVAR:TYPE=VALUE to be passed to the
13127 cmake(1) command-line used to drive the test build. The above
13128 example shows how values for variables INCLUDE_DIRECTORIES,
13129 LINK_DIRECTORIES, and LINK_LIBRARIES are used.
13130 COMPILE_DEFINITIONS <defs>...
13132 Specify -Ddefinition arguments to pass to add_definitions() in
13133 the generated test project.
13134 COPY_FILE <fileName>
13136 Copy the built executable or static library to the given <file‐
13137 Name>.
13138 COPY_FILE_ERROR <var>
13140 Use after COPY_FILE to capture into variable <var> any error
13141 message encountered while trying to copy the file.
13142 LINK_LIBRARIES <libs>...
13144 Specify libraries to be linked in the generated project. The
13145 list of libraries may refer to system libraries and to Imported
13146 Targets from the calling project.
13147 If this option is specified, any -DLINK_LIBRARIES=... value
13149 given to the CMAKE_FLAGS option will be ignored.
13150 LINK_OPTIONS <options>...
13152 New in version 3.14.
13153 Specify link step options to pass to target_link_options() or to
13156 set the STATIC_LIBRARY_OPTIONS target property in the generated
13157 project, depending on the CMAKE_TRY_COMPILE_TARGET_TYPE vari‐
13158 able.
13159 LOG_DESCRIPTION <text>
13161 New in version 3.26.
13162 Specify a non-empty text description of the purpose of the
13165 check. This is recorded in the cmake-configure-log(7) entry.
13166 NO_CACHE
13168 New in version 3.25.
13169 The result will be stored in a normal variable rather than a
13172 cache entry.
13173 The result variable is normally cached so that a simple pattern
13175 can be used to avoid repeating the test on subsequent executions
13176 of CMake:
13177 if(NOT DEFINED RESULTVAR)
13179 # ...(check-specific setup code)...
13180 try_compile(RESULTVAR ...)
13181 # ...(check-specific logging and cleanup code)...
13182 endif()
13183 If the guard variable and result variable are not the same (for
13185 example, if the test is part of a larger inspection), NO_CACHE
13186 may be useful to avoid leaking the intermediate result variable
13187 into the cache.
13188 NO_LOG New in version 3.26.
13190 Do not record a cmake-configure-log(7) entry for this call.
13193 OUTPUT_VARIABLE <var>
13195 Store the output from the build process in the given variable.
13196 SOURCE_FROM_CONTENT <name> <content>
13198 New in version 3.25.
13199 Write <content> to a file named <name> in the operation direc‐
13202 tory. This can be used to bypass the need to separately write a
13203 source file when the contents of the file are dynamically speci‐
13204 fied. The specified <name> is not allowed to contain path compo‐
13205 nents.
13206 SOURCE_FROM_CONTENT may be specified multiple times.
13208 SOURCE_FROM_FILE <name> <path>
13210 New in version 3.25.
13211 Copy <path> to a file named <name> in the operation directory.
13214 This can be used to consolidate files into the operation direc‐
13215 tory, which may be useful if a source which already exists (i.e.
13216 as a stand-alone file in a project's source repository) needs to
13217 refer to other file(s) created by SOURCE_FROM_*. (Otherwise,
13218 SOURCES is usually more convenient.) The specified <name> is not
13219 allowed to contain path components.
13220 SOURCE_FROM_VAR <name> <var>
13222 New in version 3.25.
13223 Write the contents of <var> to a file named <name> in the opera‐
13226 tion directory. This is the same as SOURCE_FROM_CONTENT, but
13227 takes the contents from the specified CMake variable, rather
13228 than directly, which may be useful when passing arguments
13229 through a function which wraps try_compile. The specified <name>
13230 is not allowed to contain path components.
13231 SOURCE_FROM_VAR may be specified multiple times.
13233 <LANG>_STANDARD <std>
13235 New in version 3.8.
13236 Specify the C_STANDARD, CXX_STANDARD, OBJC_STANDARD,
13239 OBJCXX_STANDARD, or CUDA_STANDARD target property of the gener‐
13240 ated project.
13241 <LANG>_STANDARD_REQUIRED <bool>
13243 New in version 3.8.
13244 Specify the C_STANDARD_REQUIRED, CXX_STANDARD_REQUIRED,
13247 OBJC_STANDARD_REQUIRED, OBJCXX_STANDARD_REQUIRED,or
13248 CUDA_STANDARD_REQUIRED target property of the generated project.
13249 <LANG>_EXTENSIONS <bool>
13251 New in version 3.8.
13252 Specify the C_EXTENSIONS, CXX_EXTENSIONS, OBJC_EXTENSIONS,
13255 OBJCXX_EXTENSIONS, or CUDA_EXTENSIONS target property of the
13256 generated project.
13257 Other Behavior Settings
13259 New in version 3.4: If set, the following variables are passed in to
13260 the generated try_compile CMakeLists.txt to initialize compile target
13261 properties with default values:
13262 • CMAKE_CUDA_RUNTIME_LIBRARY
13264 • CMAKE_ENABLE_EXPORTS
13266 • CMAKE_LINK_SEARCH_START_STATIC
13268 • CMAKE_LINK_SEARCH_END_STATIC
13270 • CMAKE_MSVC_RUNTIME_LIBRARY
13272 • CMAKE_POSITION_INDEPENDENT_CODE
13274 • CMAKE_WATCOM_RUNTIME_LIBRARY
13276 If CMP0056 is set to NEW, then CMAKE_EXE_LINKER_FLAGS is passed in as
13278 well.
13279 Changed in version 3.14: If CMP0083 is set to NEW, then in order to ob‐
13282 tain correct behavior at link time, the check_pie_supported() command
13283 from the CheckPIESupported module must be called before using the
13284 try_compile command.
13285 The current settings of CMP0065 and CMP0083 are propagated through to
13288 the generated test project.
13289 Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build configu‐
13291 ration:
13292 • For multi-config generators, this selects which configuration to
13294 build.
13295 • For single-config generators, this sets CMAKE_BUILD_TYPE in the test
13297 project.
13298 New in version 3.6: Set the CMAKE_TRY_COMPILE_TARGET_TYPE variable to
13300 specify the type of target used for the source file signature.
13301 New in version 3.6: Set the CMAKE_TRY_COMPILE_PLATFORM_VARIABLES vari‐
13304 able to specify variables that must be propagated into the test
13305 project. This variable is meant for use only in toolchain files and is
13306 only honored by the try_compile() command for the source files form,
13307 not when given a whole project.
13308 Changed in version 3.8: If CMP0067 is set to NEW, or any of the
13311 <LANG>_STANDARD, <LANG>_STANDARD_REQUIRED, or <LANG>_EXTENSIONS options
13312 are used, then the language standard variables are honored:
13313 • CMAKE_C_STANDARD
13315 • CMAKE_C_STANDARD_REQUIRED
13317 • CMAKE_C_EXTENSIONS
13319 • CMAKE_CXX_STANDARD
13321 • CMAKE_CXX_STANDARD_REQUIRED
13323 • CMAKE_CXX_EXTENSIONS
13325 • CMAKE_OBJC_STANDARD
13327 • CMAKE_OBJC_STANDARD_REQUIRED
13329 • CMAKE_OBJC_EXTENSIONS
13331 • CMAKE_OBJCXX_STANDARD
13333 • CMAKE_OBJCXX_STANDARD_REQUIRED
13335 • CMAKE_OBJCXX_EXTENSIONS
13337 • CMAKE_CUDA_STANDARD
13339 • CMAKE_CUDA_STANDARD_REQUIRED
13341 • CMAKE_CUDA_EXTENSIONS
13343 Their values are used to set the corresponding target properties in the
13345 generated project (unless overridden by an explicit option).
13346 Changed in version 3.14: For the Green Hills MULTI generator, the GHS
13349 toolset and target system customization cache variables are also propa‐
13350 gated into the test project.
13351 New in version 3.24: The CMAKE_TRY_COMPILE_NO_PLATFORM_VARIABLES vari‐
13354 able may be set to disable passing platform variables into the test
13355 project.
13356 New in version 3.25: If CMP0141 is set to NEW, one can use
13359 CMAKE_MSVC_DEBUG_INFORMATION_FORMAT to specify the MSVC debug informa‐
13360 tion format.
13361 See Also
13364 • try_run()
13365 try_run
13367 Try compiling and then running some code.
13368 Try Compiling and Running Source Files
13370 try_run(<runResultVar> <compileResultVar>
13371 <SOURCES <srcfile...> |
13372 SOURCE_FROM_CONTENT <name> <content> |
13373 SOURCE_FROM_VAR <name> <var> |
13374 SOURCE_FROM_FILE <name> <path> >...
13375 [LOG_DESCRIPTION <text>]
13376 [NO_CACHE]
13377 [NO_LOG]
13378 [CMAKE_FLAGS <flags>...]
13379 [COMPILE_DEFINITIONS <defs>...]
13380 [LINK_OPTIONS <options>...]
13381 [LINK_LIBRARIES <libs>...]
13382 [COMPILE_OUTPUT_VARIABLE <var>]
13383 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
13384 [<LANG>_STANDARD <std>]
13385 [<LANG>_STANDARD_REQUIRED <bool>]
13386 [<LANG>_EXTENSIONS <bool>]
13387 [RUN_OUTPUT_VARIABLE <var>]
13388 [RUN_OUTPUT_STDOUT_VARIABLE <var>]
13389 [RUN_OUTPUT_STDERR_VARIABLE <var>]
13390 [WORKING_DIRECTORY <var>]
13391 [ARGS <args>...]
13392 )
13393 New in version 3.25.
13395 Try building an executable from one or more source files. Build suc‐
13398 cess returns TRUE and build failure returns FALSE in <compileResult‐
13399 Var>. If the build succeeds, this runs the executable and stores the
13400 exit code in <runResultVar>. If the executable was built, but failed
13401 to run, then <runResultVar> will be set to FAILED_TO_RUN. See command
13402 try_compile() for documentation of options common to both commands, and
13403 for information on how the test project is constructed to build the
13404 source file.
13405 One or more source files must be provided. Additionally, one of SOURCES
13407 and/or SOURCE_FROM_* must precede other keywords.
13408 New in version 3.26: This command records a configure-log try_run event
13410 if the NO_LOG option is not specified.
13411 This command supports an alternate signature for CMake older than 3.25.
13414 The signature above is recommended for clarity.
13415 try_run(<runResultVar> <compileResultVar>
13417 <bindir> <srcfile|SOURCES srcfile...>
13418 [CMAKE_FLAGS <flags>...]
13419 [COMPILE_DEFINITIONS <defs>...]
13420 [LINK_OPTIONS <options>...]
13421 [LINK_LIBRARIES <libs>...]
13422 [COMPILE_OUTPUT_VARIABLE <var>]
13423 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]]
13424 [<LANG>_STANDARD <std>]
13425 [<LANG>_STANDARD_REQUIRED <bool>]
13426 [<LANG>_EXTENSIONS <bool>]
13427 [RUN_OUTPUT_VARIABLE <var>]
13428 [OUTPUT_VARIABLE <var>]
13429 [WORKING_DIRECTORY <var>]
13430 [ARGS <args>...]
13431 )
13432 The options specific to try_run are:
13434 COMPILE_OUTPUT_VARIABLE <var>
13436 Report the compile step build output in a given variable.
13437 OUTPUT_VARIABLE <var>
13439 Report the compile build output and the output from running the
13440 executable in the given variable. This option exists for legacy
13441 reasons and is only supported by the old try_run signature.
13442 Prefer COMPILE_OUTPUT_VARIABLE and RUN_OUTPUT_VARIABLE instead.
13443 RUN_OUTPUT_VARIABLE <var>
13445 Report the output from running the executable in a given vari‐
13446 able.
13447 RUN_OUTPUT_STDOUT_VARIABLE <var>
13449 New in version 3.25.
13450 Report the output of stdout from running the executable in a
13453 given variable.
13454 RUN_OUTPUT_STDERR_VARIABLE <var>
13456 New in version 3.25.
13457 Report the output of stderr from running the executable in a
13460 given variable.
13461 WORKING_DIRECTORY <var>
13463 New in version 3.20.
13464 Run the executable in the given directory. If no WORKING_DIREC‐
13467 TORY is specified, the executable will run in <bindir> or the
13468 current build directory.
13469 ARGS <args>...
13471 Additional arguments to pass to the executable when running it.
13472 Other Behavior Settings
13474 Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build configu‐
13475 ration:
13476 • For multi-config generators, this selects which configuration to
13478 build.
13479 • For single-config generators, this sets CMAKE_BUILD_TYPE in the test
13481 project.
13482 Behavior when Cross Compiling
13484 New in version 3.3: Use CMAKE_CROSSCOMPILING_EMULATOR when running
13485 cross-compiled binaries.
13486 When cross compiling, the executable compiled in the first step usually
13489 cannot be run on the build host. The try_run command checks the
13490 CMAKE_CROSSCOMPILING variable to detect whether CMake is in cross-com‐
13491 piling mode. If that is the case, it will still try to compile the ex‐
13492 ecutable, but it will not try to run the executable unless the
13493 CMAKE_CROSSCOMPILING_EMULATOR variable is set. Instead it will create
13494 cache variables which must be filled by the user or by presetting them
13495 in some CMake script file to the values the executable would have pro‐
13496 duced if it had been run on its actual target platform. These cache
13497 entries are:
13498 <runResultVar>
13500 Exit code if the executable were to be run on the target plat‐
13501 form.
13502 <runResultVar>__TRYRUN_OUTPUT
13504 Output from stdout and stderr if the executable were to be run
13505 on the target platform. This is created only if the RUN_OUT‐
13506 PUT_VARIABLE or OUTPUT_VARIABLE option was used.
13507 In order to make cross compiling your project easier, use try_run only
13509 if really required. If you use try_run, use the RUN_OUTPUT_STD‐
13510 OUT_VARIABLE, RUN_OUTPUT_STDERR_VARIABLE, RUN_OUTPUT_VARIABLE or OUT‐
13511 PUT_VARIABLE options only if really required. Using them will require
13512 that when cross-compiling, the cache variables will have to be set man‐
13513 ually to the output of the executable. You can also "guard" the calls
13514 to try_run with an if() block checking the CMAKE_CROSSCOMPILING vari‐
13515 able and provide an easy-to-preset alternative for this case.
13516
13518 These commands are available only in CTest scripts.
13519 ctest_build
13521 Perform the CTest Build Step as a Dashboard Client.
13522 ctest_build([BUILD <build-dir>] [APPEND]
13524 [CONFIGURATION <config>]
13525 [PARALLEL_LEVEL <parallel>]
13526 [FLAGS <flags>]
13527 [PROJECT_NAME <project-name>]
13528 [TARGET <target-name>]
13529 [NUMBER_ERRORS <num-err-var>]
13530 [NUMBER_WARNINGS <num-warn-var>]
13531 [RETURN_VALUE <result-var>]
13532 [CAPTURE_CMAKE_ERROR <result-var>]
13533 )
13534 Build the project and store results in Build.xml for submission with
13536 the ctest_submit() command.
13537 The CTEST_BUILD_COMMAND variable may be set to explicitly specify the
13539 build command line. Otherwise the build command line is computed auto‐
13540 matically based on the options given.
13541 The options are:
13543 BUILD <build-dir>
13545 Specify the top-level build directory. If not given, the
13546 CTEST_BINARY_DIRECTORY variable is used.
13547 APPEND Mark Build.xml for append to results previously submitted to a
13549 dashboard server since the last ctest_start() call. Append se‐
13550 mantics are defined by the dashboard server in use. This does
13551 not cause results to be appended to a .xml file produced by a
13552 previous call to this command.
13553 CONFIGURATION <config>
13555 Specify the build configuration (e.g. Debug). If not specified
13556 the CTEST_BUILD_CONFIGURATION variable will be checked. Other‐
13557 wise the -C <cfg> option given to the ctest(1) command will be
13558 used, if any.
13559 PARALLEL_LEVEL <parallel>
13561 New in version 3.21.
13562 Specify the parallel level of the underlying build system. If
13565 not specified, the CMAKE_BUILD_PARALLEL_LEVEL environment vari‐
13566 able will be checked.
13567 FLAGS <flags>
13569 Pass additional arguments to the underlying build command. If
13570 not specified the CTEST_BUILD_FLAGS variable will be checked.
13571 This can, e.g., be used to trigger a parallel build using the -j
13572 option of make. See the ProcessorCount module for an example.
13573 PROJECT_NAME <project-name>
13575 Ignored since CMake 3.0.
13576 Changed in version 3.14: This value is no longer required.
13578 TARGET <target-name>
13581 Specify the name of a target to build. If not specified the
13582 CTEST_BUILD_TARGET variable will be checked. Otherwise the de‐
13583 fault target will be built. This is the "all" target (called
13584 ALL_BUILD in Visual Studio Generators).
13585 NUMBER_ERRORS <num-err-var>
13587 Store the number of build errors detected in the given variable.
13588 NUMBER_WARNINGS <num-warn-var>
13590 Store the number of build warnings detected in the given vari‐
13591 able.
13592 RETURN_VALUE <result-var>
13594 Store the return value of the native build tool in the given
13595 variable.
13596 CAPTURE_CMAKE_ERROR <result-var>
13598 New in version 3.7.
13599 Store in the <result-var> variable -1 if there are any errors
13602 running the command and prevent ctest from returning non-zero if
13603 an error occurs.
13604 QUIET New in version 3.3.
13606 Suppress any CTest-specific non-error output that would have
13609 been printed to the console otherwise. The summary of warnings
13610 / errors, as well as the output from the native build tool is
13611 unaffected by this option.
13612 ctest_configure
13614 Perform the CTest Configure Step as a Dashboard Client.
13615 ctest_configure([BUILD <build-dir>] [SOURCE <source-dir>] [APPEND]
13617 [OPTIONS <options>] [RETURN_VALUE <result-var>] [QUIET]
13618 [CAPTURE_CMAKE_ERROR <result-var>])
13619 Configure the project build tree and record results in Configure.xml
13621 for submission with the ctest_submit() command.
13622 The options are:
13624 BUILD <build-dir>
13626 Specify the top-level build directory. If not given, the
13627 CTEST_BINARY_DIRECTORY variable is used.
13628 SOURCE <source-dir>
13630 Specify the source directory. If not given, the
13631 CTEST_SOURCE_DIRECTORY variable is used.
13632 APPEND Mark Configure.xml for append to results previously submitted to
13634 a dashboard server since the last ctest_start() call. Append
13635 semantics are defined by the dashboard server in use. This does
13636 not cause results to be appended to a .xml file produced by a
13637 previous call to this command.
13638 OPTIONS <options>
13640 Specify command-line arguments to pass to the configuration
13641 tool.
13642 RETURN_VALUE <result-var>
13644 Store in the <result-var> variable the return value of the na‐
13645 tive configuration tool.
13646 CAPTURE_CMAKE_ERROR <result-var>
13648 New in version 3.7.
13649 Store in the <result-var> variable -1 if there are any errors
13652 running the command and prevent ctest from returning non-zero if
13653 an error occurs.
13654 QUIET New in version 3.3.
13656 Suppress any CTest-specific non-error messages that would have
13659 otherwise been printed to the console. Output from the underly‐
13660 ing configure command is not affected.
13661 ctest_coverage
13663 Perform the CTest Coverage Step as a Dashboard Client.
13664 ctest_coverage([BUILD <build-dir>] [APPEND]
13666 [LABELS <label>...]
13667 [RETURN_VALUE <result-var>]
13668 [CAPTURE_CMAKE_ERROR <result-var>]
13669 [QUIET]
13670 )
13671 Collect coverage tool results and stores them in Coverage.xml for sub‐
13673 mission with the ctest_submit() command.
13674 The options are:
13676 BUILD <build-dir>
13678 Specify the top-level build directory. If not given, the
13679 CTEST_BINARY_DIRECTORY variable is used.
13680 APPEND Mark Coverage.xml for append to results previously submitted to
13682 a dashboard server since the last ctest_start() call. Append
13683 semantics are defined by the dashboard server in use. This does
13684 not cause results to be appended to a .xml file produced by a
13685 previous call to this command.
13686 LABELS Filter the coverage report to include only source files labeled
13688 with at least one of the labels specified.
13689 RETURN_VALUE <result-var>
13691 Store in the <result-var> variable 0 if coverage tools ran with‐
13692 out error and non-zero otherwise.
13693 CAPTURE_CMAKE_ERROR <result-var>
13695 New in version 3.7.
13696 Store in the <result-var> variable -1 if there are any errors
13699 running the command and prevent ctest from returning non-zero if
13700 an error occurs.
13701 QUIET New in version 3.3.
13703 Suppress any CTest-specific non-error output that would have
13706 been printed to the console otherwise. The summary indicating
13707 how many lines of code were covered is unaffected by this op‐
13708 tion.
13709 ctest_empty_binary_directory
13711 empties the binary directory
13712 ctest_empty_binary_directory(<directory>)
13714 Removes a binary directory. This command will perform some checks
13716 prior to deleting the directory in an attempt to avoid malicious or ac‐
13717 cidental directory deletion.
13718 ctest_memcheck
13720 Perform the CTest MemCheck Step as a Dashboard Client.
13721 ctest_memcheck([BUILD <build-dir>] [APPEND]
13723 [START <start-number>]
13724 [END <end-number>]
13725 [STRIDE <stride-number>]
13726 [EXCLUDE <exclude-regex>]
13727 [INCLUDE <include-regex>]
13728 [EXCLUDE_LABEL <label-exclude-regex>]
13729 [INCLUDE_LABEL <label-include-regex>]
13730 [EXCLUDE_FIXTURE <regex>]
13731 [EXCLUDE_FIXTURE_SETUP <regex>]
13732 [EXCLUDE_FIXTURE_CLEANUP <regex>]
13733 [PARALLEL_LEVEL <level>]
13734 [RESOURCE_SPEC_FILE <file>]
13735 [TEST_LOAD <threshold>]
13736 [SCHEDULE_RANDOM <ON|OFF>]
13737 [STOP_ON_FAILURE]
13738 [STOP_TIME <time-of-day>]
13739 [RETURN_VALUE <result-var>]
13740 [CAPTURE_CMAKE_ERROR <result-var>]
13741 [REPEAT <mode>:<n>]
13742 [OUTPUT_JUNIT <file>]
13743 [DEFECT_COUNT <defect-count-var>]
13744 [QUIET]
13745 )
13746 Run tests with a dynamic analysis tool and store results in Mem‐
13748 Check.xml for submission with the ctest_submit() command.
13749 Most options are the same as those for the ctest_test() command.
13751 The options unique to this command are:
13753 DEFECT_COUNT <defect-count-var>
13755 New in version 3.8.
13756 Store in the <defect-count-var> the number of defects found.
13759 ctest_read_custom_files
13761 read CTestCustom files.
13762 ctest_read_custom_files(<directory>...)
13764 Read all the CTestCustom.ctest or CTestCustom.cmake files from the
13766 given directory.
13767 By default, invoking ctest(1) without a script will read custom files
13769 from the binary directory.
13770 ctest_run_script
13772 runs a ctest -S script
13773 ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
13775 script_file_name2 ... [RETURN_VALUE var])
13776 Runs a script or scripts much like if it was run from ctest -S. If no
13778 argument is provided then the current script is run using the current
13779 settings of the variables. If NEW_PROCESS is specified then each
13780 script will be run in a separate process.If RETURN_VALUE is specified
13781 the return value of the last script run will be put into var.
13782 ctest_sleep
13784 sleeps for some amount of time
13785 ctest_sleep(<seconds>)
13787 Sleep for given number of seconds.
13789 ctest_sleep(<time1> <duration> <time2>)
13791 Sleep for t=(time1 + duration - time2) seconds if t > 0.
13793 ctest_start
13795 Starts the testing for a given model
13796 ctest_start(<model> [<source> [<binary>]] [GROUP <group>] [QUIET])
13798 ctest_start([<model> [<source> [<binary>]]] [GROUP <group>] APPEND [QUIET])
13800 Starts the testing for a given model. The command should be called af‐
13802 ter the binary directory is initialized.
13803 The parameters are as follows:
13805 <model>
13807 Set the dashboard model. Must be one of Experimental, Continu‐
13808 ous, or Nightly. This parameter is required unless APPEND is
13809 specified.
13810 <source>
13812 Set the source directory. If not specified, the value of
13813 CTEST_SOURCE_DIRECTORY is used instead.
13814 <binary>
13816 Set the binary directory. If not specified, the value of
13817 CTEST_BINARY_DIRECTORY is used instead.
13818 GROUP <group>
13820 If GROUP is used, the submissions will go to the specified group
13821 on the CDash server. If no GROUP is specified, the name of the
13822 model is used by default.
13823 Changed in version 3.16: This replaces the deprecated option
13825 TRACK. Despite the name change its behavior is unchanged.
13826 APPEND If APPEND is used, the existing TAG is used rather than creating
13829 a new one based on the current time stamp. If you use APPEND,
13830 you can omit the <model> and GROUP <group> parameters, because
13831 they will be read from the generated TAG file. For example:
13832 ctest_start(Experimental GROUP GroupExperimental)
13834 Later, in another ctest -S script:
13836 ctest_start(APPEND)
13838 When the second script runs ctest_start(APPEND), it will read
13840 the Experimental model and GroupExperimental group from the TAG
13841 file generated by the first ctest_start() command. Please note
13842 that if you call ctest_start(APPEND) and specify a different
13843 model or group than in the first ctest_start() command, a warn‐
13844 ing will be issued, and the new model and group will be used.
13845 QUIET New in version 3.3.
13847 If QUIET is used, CTest will suppress any non-error messages
13850 that it otherwise would have printed to the console.
13851 The parameters for ctest_start() can be issued in any order, with the
13853 exception that <model>, <source>, and <binary> have to appear in that
13854 order with respect to each other. The following are all valid and
13855 equivalent:
13856 ctest_start(Experimental path/to/source path/to/binary GROUP SomeGroup QUIET APPEND)
13858 ctest_start(GROUP SomeGroup Experimental QUIET path/to/source APPEND path/to/binary)
13860 ctest_start(APPEND QUIET Experimental path/to/source GROUP SomeGroup path/to/binary)
13862 However, for the sake of readability, it is recommended that you order
13864 your parameters in the order listed at the top of this page.
13865 If the CTEST_CHECKOUT_COMMAND variable (or the CTEST_CVS_CHECKOUT vari‐
13867 able) is set, its content is treated as command-line. The command is
13868 invoked with the current working directory set to the parent of the
13869 source directory, even if the source directory already exists. This
13870 can be used to create the source tree from a version control reposi‐
13871 tory.
13872 ctest_submit
13874 Perform the CTest Submit Step as a Dashboard Client.
13875 ctest_submit([PARTS <part>...] [FILES <file>...]
13877 [SUBMIT_URL <url>]
13878 [BUILD_ID <result-var>]
13879 [HTTPHEADER <header>]
13880 [RETRY_COUNT <count>]
13881 [RETRY_DELAY <delay>]
13882 [RETURN_VALUE <result-var>]
13883 [CAPTURE_CMAKE_ERROR <result-var>]
13884 [QUIET]
13885 )
13886 Submit results to a dashboard server. By default all available parts
13888 are submitted.
13889 The options are:
13891 PARTS <part>...
13893 Specify a subset of parts to submit. Valid part names are:
13894 Start = nothing
13896 Update = ctest_update results, in Update.xml
13897 Configure = ctest_configure results, in Configure.xml
13898 Build = ctest_build results, in Build.xml
13899 Test = ctest_test results, in Test.xml
13900 Coverage = ctest_coverage results, in Coverage.xml
13901 MemCheck = ctest_memcheck results, in DynamicAnalysis.xml and
13902 DynamicAnalysis-Test.xml
13903 Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
13904 ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
13905 Upload = Files prepared for upload by ctest_upload(), in Upload.xml
13906 Submit = nothing
13907 Done = Build is complete, in Done.xml
13908 FILES <file>...
13910 Specify an explicit list of specific files to be submitted.
13911 Each individual file must exist at the time of the call.
13912 SUBMIT_URL <url>
13914 New in version 3.14.
13915 The http or https URL of the dashboard server to send the sub‐
13918 mission to. If not given, the CTEST_SUBMIT_URL variable is
13919 used.
13920 BUILD_ID <result-var>
13922 New in version 3.15.
13923 Store in the <result-var> variable the ID assigned to this build
13926 by CDash.
13927 HTTPHEADER <HTTP-header>
13929 New in version 3.9.
13930 Specify HTTP header to be included in the request to CDash dur‐
13933 ing submission. For example, CDash can be configured to only
13934 accept submissions from authenticated clients. In this case, you
13935 should provide a bearer token in your header:
13936 ctest_submit(HTTPHEADER "Authorization: Bearer <auth-token>")
13938 This suboption can be repeated several times for multiple head‐
13940 ers.
13941 RETRY_COUNT <count>
13943 Specify how many times to retry a timed-out submission.
13944 RETRY_DELAY <delay>
13946 Specify how long (in seconds) to wait after a timed-out submis‐
13947 sion before attempting to re-submit.
13948 RETURN_VALUE <result-var>
13950 Store in the <result-var> variable 0 for success and non-zero on
13951 failure.
13952 CAPTURE_CMAKE_ERROR <result-var>
13954 New in version 3.13.
13955 Store in the <result-var> variable -1 if there are any errors
13958 running the command and prevent ctest from returning non-zero if
13959 an error occurs.
13960 QUIET New in version 3.3.
13962 Suppress all non-error messages that would have otherwise been
13965 printed to the console.
13966 Submit to CDash Upload API
13968 New in version 3.2.
13969 ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>]
13972 [SUBMIT_URL <url>]
13973 [BUILD_ID <result-var>]
13974 [HTTPHEADER <header>]
13975 [RETRY_COUNT <count>]
13976 [RETRY_DELAY <delay>]
13977 [RETURN_VALUE <result-var>]
13978 [QUIET])
13979 This second signature is used to upload files to CDash via the CDash
13981 file upload API. The API first sends a request to upload to CDash along
13982 with a content hash of the file. If CDash does not already have the
13983 file, then it is uploaded. Along with the file, a CDash type string is
13984 specified to tell CDash which handler to use to process the data.
13985 This signature interprets options in the same way as the first one.
13987 New in version 3.8: Added the RETRY_COUNT, RETRY_DELAY, QUIET options.
13989 New in version 3.9: Added the HTTPHEADER option.
13992 New in version 3.13: Added the RETURN_VALUE option.
13995 New in version 3.14: Added the SUBMIT_URL option.
13998 New in version 3.15: Added the BUILD_ID option.
14001 ctest_test
14004 Perform the CTest Test Step as a Dashboard Client.
14005 ctest_test([BUILD <build-dir>] [APPEND]
14007 [START <start-number>]
14008 [END <end-number>]
14009 [STRIDE <stride-number>]
14010 [EXCLUDE <exclude-regex>]
14011 [INCLUDE <include-regex>]
14012 [EXCLUDE_LABEL <label-exclude-regex>]
14013 [INCLUDE_LABEL <label-include-regex>]
14014 [EXCLUDE_FIXTURE <regex>]
14015 [EXCLUDE_FIXTURE_SETUP <regex>]
14016 [EXCLUDE_FIXTURE_CLEANUP <regex>]
14017 [PARALLEL_LEVEL <level>]
14018 [RESOURCE_SPEC_FILE <file>]
14019 [TEST_LOAD <threshold>]
14020 [SCHEDULE_RANDOM <ON|OFF>]
14021 [STOP_ON_FAILURE]
14022 [STOP_TIME <time-of-day>]
14023 [RETURN_VALUE <result-var>]
14024 [CAPTURE_CMAKE_ERROR <result-var>]
14025 [REPEAT <mode>:<n>]
14026 [OUTPUT_JUNIT <file>]
14027 [QUIET]
14028 )
14029 Run tests in the project build tree and store results in Test.xml for
14031 submission with the ctest_submit() command.
14032 The options are:
14034 BUILD <build-dir>
14036 Specify the top-level build directory. If not given, the
14037 CTEST_BINARY_DIRECTORY variable is used.
14038 APPEND Mark Test.xml for append to results previously submitted to a
14040 dashboard server since the last ctest_start() call. Append se‐
14041 mantics are defined by the dashboard server in use. This does
14042 not cause results to be appended to a .xml file produced by a
14043 previous call to this command.
14044 START <start-number>
14046 Specify the beginning of a range of test numbers.
14047 END <end-number>
14049 Specify the end of a range of test numbers.
14050 STRIDE <stride-number>
14052 Specify the stride by which to step across a range of test num‐
14053 bers.
14054 EXCLUDE <exclude-regex>
14056 Specify a regular expression matching test names to exclude.
14057 INCLUDE <include-regex>
14059 Specify a regular expression matching test names to include.
14060 Tests not matching this expression are excluded.
14061 EXCLUDE_LABEL <label-exclude-regex>
14063 Specify a regular expression matching test labels to exclude.
14064 INCLUDE_LABEL <label-include-regex>
14066 Specify a regular expression matching test labels to include.
14067 Tests not matching this expression are excluded.
14068 EXCLUDE_FIXTURE <regex>
14070 New in version 3.7.
14071 If a test in the set of tests to be executed requires a particu‐
14074 lar fixture, that fixture's setup and cleanup tests would nor‐
14075 mally be added to the test set automatically. This option pre‐
14076 vents adding setup or cleanup tests for fixtures matching the
14077 <regex>. Note that all other fixture behavior is retained, in‐
14078 cluding test dependencies and skipping tests that have fixture
14079 setup tests that fail.
14080 EXCLUDE_FIXTURE_SETUP <regex>
14082 New in version 3.7.
14083 Same as EXCLUDE_FIXTURE except only matching setup tests are ex‐
14086 cluded.
14087 EXCLUDE_FIXTURE_CLEANUP <regex>
14089 New in version 3.7.
14090 Same as EXCLUDE_FIXTURE except only matching cleanup tests are
14093 excluded.
14094 PARALLEL_LEVEL <level>
14096 Specify a positive number representing the number of tests to be
14097 run in parallel.
14098 RESOURCE_SPEC_FILE <file>
14100 New in version 3.16.
14101 Specify a resource specification file. See Resource Allocation
14104 for more information.
14105 TEST_LOAD <threshold>
14107 New in version 3.4.
14108 While running tests in parallel, try not to start tests when
14111 they may cause the CPU load to pass above a given threshold. If
14112 not specified the CTEST_TEST_LOAD variable will be checked, and
14113 then the --test-load command-line argument to ctest(1). See also
14114 the TestLoad setting in the CTest Test Step.
14115 REPEAT <mode>:<n>
14117 New in version 3.17.
14118 Run tests repeatedly based on the given <mode> up to <n> times.
14121 The modes are:
14122 UNTIL_FAIL
14124 Require each test to run <n> times without failing in or‐
14125 der to pass. This is useful in finding sporadic failures
14126 in test cases.
14127 UNTIL_PASS
14129 Allow each test to run up to <n> times in order to pass.
14130 Repeats tests if they fail for any reason. This is use‐
14131 ful in tolerating sporadic failures in test cases.
14132 AFTER_TIMEOUT
14134 Allow each test to run up to <n> times in order to pass.
14135 Repeats tests only if they timeout. This is useful in
14136 tolerating sporadic timeouts in test cases on busy ma‐
14137 chines.
14138 SCHEDULE_RANDOM <ON|OFF>
14140 Launch tests in a random order. This may be useful for detect‐
14141 ing implicit test dependencies.
14142 STOP_ON_FAILURE
14144 New in version 3.18.
14145 Stop the execution of the tests once one has failed.
14148 STOP_TIME <time-of-day>
14150 Specify a time of day at which the tests should all stop run‐
14151 ning.
14152 RETURN_VALUE <result-var>
14154 Store in the <result-var> variable 0 if all tests passed. Store
14155 non-zero if anything went wrong.
14156 CAPTURE_CMAKE_ERROR <result-var>
14158 New in version 3.7.
14159 Store in the <result-var> variable -1 if there are any errors
14162 running the command and prevent ctest from returning non-zero if
14163 an error occurs.
14164 OUTPUT_JUNIT <file>
14166 New in version 3.21.
14167 Write test results to <file> in JUnit XML format. If <file> is a
14170 relative path, it will be placed in the build directory. If
14171 <file> already exists, it will be overwritten. Note that the re‐
14172 sulting JUnit XML file is not uploaded to CDash because it would
14173 be redundant with CTest's Test.xml file.
14174 QUIET New in version 3.3.
14176 Suppress any CTest-specific non-error messages that would have
14179 otherwise been printed to the console. Output from the underly‐
14180 ing test command is not affected. Summary info detailing the
14181 percentage of passing tests is also unaffected by the QUIET op‐
14182 tion.
14183 See also the CTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE,
14185 CTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE and
14186 CTEST_CUSTOM_TEST_OUTPUT_TRUNCATION variables, along with their corre‐
14187 sponding ctest(1) command line options --test-output-size-passed,
14188 --test-output-size-failed, and --test-output-truncation.
14189 Additional Test Measurements
14191 CTest can parse the output of your tests for extra measurements to re‐
14192 port to CDash.
14193 When run as a Dashboard Client, CTest will include these custom mea‐
14195 surements in the Test.xml file that gets uploaded to CDash.
14196 Check the CDash test measurement documentation for more information on
14198 the types of test measurements that CDash recognizes.
14199 The following example demonstrates how to output a variety of custom
14201 test measurements.
14202 std::cout <<
14204 "<CTestMeasurement type=\"numeric/double\" name=\"score\">28.3</CTestMeasurement>"
14205 << std::endl;
14206 std::cout <<
14208 "<CTestMeasurement type=\"text/string\" name=\"color\">red</CTestMeasurement>"
14209 << std::endl;
14210 std::cout <<
14212 "<CTestMeasurement type=\"text/link\" name=\"CMake URL\">https://cmake.org</CTestMeasurement>"
14213 << std::endl;
14214 std::cout <<
14216 "<CTestMeasurement type=\"text/preformatted\" name=\"Console Output\">" <<
14217 "line 1.\n" <<
14218 " \033[31;1m line 2. Bold red, and indented!\033[0;0ml\n" <<
14219 "line 3. Not bold or indented...\n" <<
14220 "</CTestMeasurement>" << std::endl;
14221 Image Measurements
14223 The following example demonstrates how to upload test images to CDash.
14224 std::cout <<
14226 "<CTestMeasurementFile type=\"image/jpg\" name=\"TestImage\">" <<
14227 "/dir/to/test_img.jpg</CTestMeasurementFile>" << std::endl;
14228 std::cout <<
14230 "<CTestMeasurementFile type=\"image/gif\" name=\"ValidImage\">" <<
14231 "/dir/to/valid_img.gif</CTestMeasurementFile>" << std::endl;
14232 std::cout <<
14234 "<CTestMeasurementFile type=\"image/png\" name=\"AlgoResult\">" <<
14235 "/dir/to/img.png</CTestMeasurementFile>"
14236 << std::endl;
14237 Images will be displayed together in an interactive comparison mode on
14239 CDash if they are provided with two or more of the following names.
14240 • TestImage
14242 • ValidImage
14244 • BaselineImage
14246 • DifferenceImage2
14248 By convention, TestImage is the image generated by your test, and Va‐
14250 lidImage (or BaselineImage) is basis of comparison used to determine if
14251 the test passed or failed.
14252 If another image name is used it will be displayed by CDash as a static
14254 image separate from the interactive comparison UI.
14255 Attached Files
14257 New in version 3.21.
14258 The following example demonstrates how to upload non-image files to
14261 CDash.
14262 std::cout <<
14264 "<CTestMeasurementFile type=\"file\" name=\"TestInputData1\">" <<
14265 "/dir/to/data1.csv</CTestMeasurementFile>\n" <<
14266 "<CTestMeasurementFile type=\"file\" name=\"TestInputData2\">" <<
14267 "/dir/to/data2.csv</CTestMeasurementFile>" << std::endl;
14268 If the name of the file to upload is known at configure time, you can
14270 use the ATTACHED_FILES or ATTACHED_FILES_ON_FAIL test properties in‐
14271 stead.
14272 Custom Details
14274 New in version 3.21.
14275 The following example demonstrates how to specify a custom value for
14278 the Test Details field displayed on CDash.
14279 std::cout <<
14281 "<CTestDetails>My Custom Details Value</CTestDetails>" << std::endl;
14282 Additional Labels
14284 New in version 3.22.
14285 The following example demonstrates how to add additional labels to a
14288 test at runtime.
14289 std::cout <<
14291 "<CTestLabel>Custom Label 1</CTestLabel>\n" <<
14292 "<CTestLabel>Custom Label 2</CTestLabel>" << std::endl;
14293 Use the LABELS test property instead for labels that can be determined
14295 at configure time.
14296 ctest_update
14298 Perform the CTest Update Step as a Dashboard Client.
14299 ctest_update([SOURCE <source-dir>]
14301 [RETURN_VALUE <result-var>]
14302 [CAPTURE_CMAKE_ERROR <result-var>]
14303 [QUIET])
14304 Update the source tree from version control and record results in Up‐
14306 date.xml for submission with the ctest_submit() command.
14307 The options are:
14309 SOURCE <source-dir>
14311 Specify the source directory. If not given, the
14312 CTEST_SOURCE_DIRECTORY variable is used.
14313 RETURN_VALUE <result-var>
14315 Store in the <result-var> variable the number of files updated
14316 or -1 on error.
14317 CAPTURE_CMAKE_ERROR <result-var>
14319 New in version 3.13.
14320 Store in the <result-var> variable -1 if there are any errors
14323 running the command and prevent ctest from returning non-zero if
14324 an error occurs.
14325 QUIET New in version 3.3.
14327 Tell CTest to suppress most non-error messages that it would
14330 have otherwise printed to the console. CTest will still report
14331 the new revision of the repository and any conflicting files
14332 that were found.
14333 The update always follows the version control branch currently checked
14335 out in the source directory. See the CTest Update Step documentation
14336 for information about variables that change the behavior of ctest_up‐
14337 date().
14338 ctest_upload
14340 Upload files to a dashboard server as a Dashboard Client.
14341 ctest_upload(FILES <file>... [QUIET] [CAPTURE_CMAKE_ERROR <result-var>])
14343 The options are:
14345 FILES <file>...
14347 Specify a list of files to be sent along with the build results
14348 to the dashboard server.
14349 QUIET New in version 3.3.
14351 Suppress any CTest-specific non-error output that would have
14354 been printed to the console otherwise.
14355 CAPTURE_CMAKE_ERROR <result-var>
14357 New in version 3.7.
14358 Store in the <result-var> variable -1 if there are any errors
14361 running the command and prevent ctest from returning non-zero if
14362 an error occurs.
14363
14365 These commands are deprecated and are only made available to maintain
14366 backward compatibility. The documentation of each command states the
14367 CMake version in which it was deprecated. Do not use these commands in
14368 new code.
14369 build_name
14371 Disallowed since version 3.0. See CMake Policy CMP0036.
14372 Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
14374 build_name(variable)
14376 Sets the specified variable to a string representing the platform and
14378 compiler settings. These values are now available through the
14379 CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
14380 exec_program
14382 Deprecated since version 3.0: Use the execute_process() command in‐
14383 stead.
14384 Run an executable program during the processing of the CMakeList.txt
14387 file.
14388 exec_program(Executable [directory in which to run]
14390 [ARGS <arguments to executable>]
14391 [OUTPUT_VARIABLE <var>]
14392 [RETURN_VALUE <var>])
14393 The executable is run in the optionally specified directory. The exe‐
14395 cutable can include arguments if it is double quoted, but it is better
14396 to use the optional ARGS argument to specify arguments to the program.
14397 This is because cmake will then be able to escape spaces in the exe‐
14398 cutable path. An optional argument OUTPUT_VARIABLE specifies a vari‐
14399 able in which to store the output. To capture the return value of the
14400 execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is specified,
14401 then no output will go to the stdout/stderr of the console running
14402 cmake.
14403 export_library_dependencies
14405 Disallowed since version 3.0. See CMake Policy CMP0033.
14406 Use install(EXPORT) or export() command.
14408 This command generates an old-style library dependencies file.
14410 Projects requiring CMake 2.6 or later should not use the command. Use
14411 instead the install(EXPORT) command to help export targets from an in‐
14412 stallation tree and the export() command to export targets from a build
14413 tree.
14414 The old-style library dependencies file does not take into account
14416 per-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
14417 target property.
14418 export_library_dependencies(<file> [APPEND])
14420 Create a file named <file> that can be included into a CMake listfile
14422 with the INCLUDE command. The file will contain a number of SET com‐
14423 mands that will set all the variables needed for library dependency in‐
14424 formation. This should be the last command in the top level CMake‐
14425 Lists.txt file of the project. If the APPEND option is specified, the
14426 SET commands will be appended to the given file instead of replacing
14427 it.
14428 install_files
14430 Deprecated since version 3.0: Use the install(FILES) command instead.
14431 This command has been superseded by the install() command. It is pro‐
14434 vided for compatibility with older CMake code. The FILES form is di‐
14435 rectly replaced by the FILES form of the install() command. The regexp
14436 form can be expressed more clearly using the GLOB form of the file()
14437 command.
14438 install_files(<dir> extension file file ...)
14440 Create rules to install the listed files with the given extension into
14442 the given directory. Only files existing in the current source tree or
14443 its corresponding location in the binary tree may be listed. If a file
14444 specified already has an extension, that extension will be removed
14445 first. This is useful for providing lists of source files such as
14446 foo.cxx when you want the corresponding foo.h to be installed. A typi‐
14447 cal extension is .h.
14448 install_files(<dir> regexp)
14450 Any files in the current source directory that match the regular ex‐
14452 pression will be installed.
14453 install_files(<dir> FILES file file ...)
14455 Any files listed after the FILES keyword will be installed explicitly
14457 from the names given. Full paths are allowed in this form.
14458 The directory <dir> is relative to the installation prefix, which is
14460 stored in the variable CMAKE_INSTALL_PREFIX.
14461 install_programs
14463 Deprecated since version 3.0: Use the install(PROGRAMS) command in‐
14464 stead.
14465 This command has been superseded by the install() command. It is pro‐
14468 vided for compatibility with older CMake code. The FILES form is di‐
14469 rectly replaced by the PROGRAMS form of the install() command. The
14470 regexp form can be expressed more clearly using the GLOB form of the
14471 file() command.
14472 install_programs(<dir> file1 file2 [file3 ...])
14474 install_programs(<dir> FILES file1 [file2 ...])
14475 Create rules to install the listed programs into the given directory.
14477 Use the FILES argument to guarantee that the file list version of the
14478 command will be used even when there is only one argument.
14479 install_programs(<dir> regexp)
14481 In the second form any program in the current source directory that
14483 matches the regular expression will be installed.
14484 This command is intended to install programs that are not built by
14486 cmake, such as shell scripts. See the TARGETS form of the install()
14487 command to create installation rules for targets built by cmake.
14488 The directory <dir> is relative to the installation prefix, which is
14490 stored in the variable CMAKE_INSTALL_PREFIX.
14491 install_targets
14493 Deprecated since version 3.0: Use the install(TARGETS) command instead.
14494 This command has been superseded by the install() command. It is pro‐
14497 vided for compatibility with older CMake code.
14498 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
14500 Create rules to install the listed targets into the given directory.
14502 The directory <dir> is relative to the installation prefix, which is
14503 stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
14504 specified, then on systems with special runtime files (Windows DLL),
14505 the files will be copied to that directory.
14506 load_command
14508 Disallowed since version 3.0. See CMake Policy CMP0031.
14509 Load a command into a running CMake.
14511 load_command(COMMAND_NAME <loc1> [loc2 ...])
14513 The given locations are searched for a library whose name is cmCOM‐
14515 MAND_NAME. If found, it is loaded as a module and the command is added
14516 to the set of available CMake commands. Usually, try_compile() is used
14517 before this command to compile the module. If the command is success‐
14518 fully loaded a variable named
14519 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
14521 will be set to the full path of the module that was loaded. Otherwise
14523 the variable will not be set.
14524 make_directory
14526 Deprecated since version 3.0: Use the file(MAKE_DIRECTORY) command in‐
14527 stead.
14528 make_directory(directory)
14531 Creates the specified directory. Full paths should be given. Any par‐
14533 ent directories that do not exist will also be created. Use with care.
14534 output_required_files
14536 Disallowed since version 3.0. See CMake Policy CMP0032.
14537 Approximate C preprocessor dependency scanning.
14539 This command exists only because ancient CMake versions provided it.
14541 CMake handles preprocessor dependency scanning automatically using a
14542 more advanced scanner.
14543 output_required_files(srcfile outputfile)
14545 Outputs a list of all the source files that are required by the speci‐
14547 fied srcfile. This list is written into outputfile. This is similar
14548 to writing out the dependencies for srcfile except that it jumps from
14549 .h files into .cxx, .c and .cpp files if possible.
14550 qt_wrap_cpp
14552 Deprecated since version 3.14: This command was originally added to
14553 support Qt 3 before the add_custom_command() command was sufficiently
14554 mature. The FindQt4 module provides the qt4_wrap_cpp() macro, which
14555 should be used instead for Qt 4 projects. For projects using Qt 5 or
14556 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
14557 vides qt5_wrap_cpp()).
14558 Manually create Qt Wrappers.
14561 qt_wrap_cpp(resultingLibraryName DestName SourceLists ...)
14563 Produces moc files for all the .h files listed in the SourceLists. The
14565 moc files will be added to the library using the DestName source list.
14566 Consider updating the project to use the AUTOMOC target property in‐
14568 stead for a more automated way of invoking the moc tool.
14569 qt_wrap_ui
14571 Deprecated since version 3.14: This command was originally added to
14572 support Qt 3 before the add_custom_command() command was sufficiently
14573 mature. The FindQt4 module provides the qt4_wrap_ui() macro, which
14574 should be used instead for Qt 4 projects. For projects using Qt 5 or
14575 later, use the equivalent macro provided by Qt itself (e.g. Qt 5 pro‐
14576 vides qt5_wrap_ui()).
14577 Manually create Qt user interfaces Wrappers.
14580 qt_wrap_ui(resultingLibraryName HeadersDestName
14582 SourcesDestName SourceLists ...)
14583 Produces .h and .cxx files for all the .ui files listed in the
14585 SourceLists. The .h files will be added to the library using the Head‐
14586 ersDestNamesource list. The .cxx files will be added to the library
14587 using the SourcesDestNamesource list.
14588 Consider updating the project to use the AUTOUIC target property in‐
14590 stead for a more automated way of invoking the uic tool.
14591 remove
14593 Deprecated since version 3.0: Use the list(REMOVE_ITEM) command in‐
14594 stead.
14595 remove(VAR VALUE VALUE ...)
14598 Removes VALUE from the variable VAR. This is typically used to remove
14600 entries from a vector (e.g. semicolon separated list). VALUE is ex‐
14601 panded.
14602 subdir_depends
14604 Disallowed since version 3.0. See CMake Policy CMP0029.
14605 Does nothing.
14607 subdir_depends(subdir dep1 dep2 ...)
14609 Does not do anything. This command used to help projects order paral‐
14611 lel builds correctly. This functionality is now automatic.
14612 subdirs
14614 Deprecated since version 3.0: Use the add_subdirectory() command in‐
14615 stead.
14616 Add a list of subdirectories to the build.
14619 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
14621 [PREORDER] )
14622 Add a list of subdirectories to the build. The add_subdirectory() com‐
14624 mand should be used instead of subdirs although subdirs will still
14625 work. This will cause any CMakeLists.txt files in the sub directories
14626 to be processed by CMake. Any directories after the PREORDER flag are
14627 traversed first by makefile builds, the PREORDER flag has no effect on
14628 IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
14629 not be included in the top level makefile or project file. This is
14630 useful for having CMake create makefiles or projects for a set of exam‐
14631 ples in a project. You would want CMake to generate makefiles or
14632 project files for all the examples at the same time, but you would not
14633 want them to show up in the top level project or be built each time
14634 make is run from the top.
14635 use_mangled_mesa
14637 Disallowed since version 3.0. See CMake Policy CMP0030.
14638 Copy mesa headers for use in combination with system GL.
14640 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
14642 The path to mesa includes, should contain gl_mangle.h. The mesa head‐
14644 ers are copied to the specified output directory. This allows mangled
14645 mesa headers to override other GL headers by being added to the include
14646 directory path earlier.
14647 utility_source
14649 Disallowed since version 3.0. See CMake Policy CMP0034.
14650 Specify the source tree of a third-party utility.
14652 utility_source(cache_entry executable_name
14654 path_to_source [file1 file2 ...])
14655 When a third-party utility's source is included in the distribution,
14657 this command specifies its location and name. The cache entry will not
14658 be set unless the path_to_source and all listed files exist. It is as‐
14659 sumed that the source tree of the utility will have been built before
14660 it is needed.
14661 When cross compiling CMake will print a warning if a utility_source()
14663 command is executed, because in many cases it is used to build an exe‐
14664 cutable which is executed later on. This doesn't work when cross com‐
14665 piling, since the executable can run only on their target platform. So
14666 in this case the cache entry has to be adjusted manually so it points
14667 to an executable which is runnable on the build host.
14668 variable_requires
14670 Disallowed since version 3.0. See CMake Policy CMP0035.
14671 Use the if() command instead.
14673 Assert satisfaction of an option's required variables.
14675 variable_requires(TEST_VARIABLE RESULT_VARIABLE
14677 REQUIRED_VARIABLE1
14678 REQUIRED_VARIABLE2 ...)
14679 The first argument (TEST_VARIABLE) is the name of the variable to be
14681 tested, if that variable is false nothing else is done. If TEST_VARI‐
14682 ABLE is true, then the next argument (RESULT_VARIABLE) is a variable
14683 that is set to true if all the required variables are set. The rest of
14684 the arguments are variables that must be true or not set to NOTFOUND to
14685 avoid an error. If any are not true, an error is reported.
14686 write_file
14688 Deprecated since version 3.0: Use the file(WRITE) command instead.
14689 write_file(filename "message to write"... [APPEND])
14692 The first argument is the file name, the rest of the arguments are mes‐
14694 sages to write. If the argument APPEND is specified, then the message
14695 will be appended.
14696 NOTE 1: file(WRITE) and file(APPEND) do exactly the same as this one
14698 but add some more functionality.
14699 NOTE 2: When using write_file the produced file cannot be used as an
14701 input to CMake (CONFIGURE_FILE, source file ...) because it will lead
14702 to an infinite loop. Use configure_file() if you want to generate in‐
14703 put files to CMake.
14704
14706 2000-2023 Kitware, Inc. and Contributors
147073.27.7 Oct 07, 2023 CMAKE-COMMANDS(7)