include()
include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
[NO_POLICY_SCOPE])
[doc]. Load and run CMake code from the file given. Variable reads and writes access the scope of the caller (dynamic scoping). If OPTIONAL is present, then no error is raised if the file does not exist.
If RESULT_VARIABLE is given the variable will be set to the full filename which has been included or NOTFOUND if it failed.
If a module is specified instead of a file, the file with name <modulename>.cmake is searched first in CMAKE_MODULE_PATH, then in the CMake module directory. There is one exception to this: if the file which calls include() is located itself in the CMake module directory, then first the CMake module directory is searched and CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
See the cmake_policy() command documentation for discussion of the NO_POLICY_SCOPE option.
add_executable()
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL]
source1 [source2 ...])
[doc] Adds an executable target called<name>to be built from the source files listed in the command invocation. The<name>corresponds to the logical target name and must be globally unique within a project. The actual file name of the executable built is constructed based on conventions of the native platform (such as<name>.exeor just<name>.
By default the executable file will be created in the build tree directory corresponding to the source tree directory in which the command was invoked. See documentation of theRUNTIME_OUTPUT_DIRECTORYtarget property to change this location. See documentation of theOUTPUT_NAMEtarget property to change the<name>part of the final file name.
target_link_libraries()
target_link_libraries(<target> [item1 [item2 [...]]]
[[debug|optimized|general] <item>] ...)
Specify libraries or flags to use when linking a given target. The named<target>must have been created in the current directory by a command such asadd_executable()oradd_library(). The remaining arguments specify library names or flags. Repeated calls for the same<target>append items in the order called.
If a library name matches that of another target in the project a dependency will automatically be added in the build system to make sure the library being linked is up-to-date before the target links. Item names starting with-, but not-lor-framework, are treated as linker flags.
Adebug,optimized, orgeneralkeyword indicates that the library immediately following it is to be used only for the corresponding build configuration. Thedebugkeyword corresponds to the Debug configuration (or to configurations named in theDEBUG_CONFIGURATIONSglobal property if it is set). Theoptimizedkeyword corresponds to all other configurations. Thegeneralkeyword corresponds to all configurations, and is purely optional (assumed if omitted). Higher granularity may be achieved for per-configuration rules by creating and linking toIMPORTED library targets.
Library dependencies are transitive by default with this signature. When this target is linked into another target then the libraries linked to this target will appear on the link line for the other target too. This transitive “link interface” is stored in theINTERFACE_LINK_LIBRARIEStarget property and may be overridden by setting the property directly. WhenCMP0022is not set toNEW, transitive linking is built in but may be overridden by theLINK_INTERFACE_LIBRARIESproperty. Calls to other signatures of this command may set the property making any libraries linked exclusively by this signature private.
add_dependencies()
add_dependencies(<target> [<target-dependency>]...)
[doc] Make a top-level <target> depend on other top-level targets to ensure that they build before <target> does. A top-level target is one created by ADD_EXECUTABLE, ADD_LIBRARY, or ADD_CUSTOM_TARGET. Dependencies added to an IMPORTED target are followed transitively in its place since the target itself does not build.
See the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND for adding file-level dependencies in custom rules. See the OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add file-level dependencies to object files.
functions()
function(<name> [arg1 [arg2 [arg3 ...]]])
COMMAND1(ARGS ...)
COMMAND2(ARGS ...)
...
endfunction(<name>)
[doc] Define a function named <name> that takes arguments named arg1 arg2 arg3 (...). Commands listed after function, but before the matching endfunction, are not invoked until the function is invoked. When it is invoked, the commands recorded in the function are first modified by replacing formal parameters (${arg1}) with the arguments passed, and then invoked as normal commands. In addition to referencing the formal parameters you can reference the variable ARGC which will be set to the number of arguments passed into the function as well as ARGV0 ARGV1 ARGV2 ... which will have the actual values of the arguments passed in. This facilitates creating functions with optional arguments. Additionally ARGV holds the list of all arguments given to the function and ARGN holds the list of arguments past the last expected argument.
A function opens a new scope: see set(var PARENT_SCOPE) for details.
See the cmake_policy() command documentation for the behavior of policies inside functions.
set()
set(<variable> <value>
[[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
[doc] Within CMake sets <variable> to the value <value>. <value> is expanded before <variable> is set to it. Normally, set will set a regular CMake variable. If CACHE is present, then the <variable> is put in the cache instead, unless it is already in the cache. See section ‘Variable types in CMake’ below for details of regular and cache variables and their interactions. If CACHE is used, <type> and <docstring> are required. <type> is used by the CMake GUI to choose a widget with which the user sets a value. The value for <type> may be one of
FILEPATH = File chooser dialog.
PATH = Directory chooser dialog.
STRING = Arbitrary string.
BOOL = Boolean ON/OFF checkbox.
INTERNAL = No GUI entry (used for persistent variables).
If <type> is INTERNAL, the cache variable is marked as internal, and will not be shown to the user in tools like cmake-gui. This is intended for values that should be persisted in the cache, but which users should not normally change. INTERNAL implies FORCE.
Normally, set(...CACHE...) creates cache variables, but does not modify them. If FORCE is specified, the value of the cache variable is set, even if the variable is already in the cache. This should normally be avoided, as it will remove any changes to the cache variable’s value by the user.
If PARENT_SCOPE is present, the variable will be set in the scope above the current scope. Each new directory or function creates a new scope. This command will set the value of a variable into the parent directory or calling function (whichever is applicable to the case at hand). PARENT_SCOPE cannot be combined with CACHE.
list()
list(LENGTH <list> <output variable>)
list(GET <list> <element index> [<element index> ...]
<output variable>)
list(APPEND <list> [<element> ...])
list(FIND <list> <value> <output variable>)
list(INSERT <list> <element_index> <element> [<element> ...])
list(REMOVE_ITEM <list> <value> [<value> ...])
list(REMOVE_AT <list> <index> [<index> ...])
list(REMOVE_DUPLICATES <list>)
list(REVERSE <list>)
list(SORT <list>)
LENGTH will return a given list’s length.
GET will return list of elements specified by indices from the list.
APPEND will append elements to the list.
FIND will return the index of the element specified in the list or -1 if it wasn’t found.
INSERT will insert elements to the list to the specified location.
REMOVE_AT and REMOVE_ITEM will remove items from the list. The difference is that REMOVE_ITEM will remove the given items, while REMOVE_AT will remove the items at the given indices.
REMOVE_DUPLICATES will remove duplicated items in the list.
REVERSE reverses the contents of the list in-place.
SORT sorts the list in-place alphabetically.
The list subcommands APPEND, INSERT, REMOVE_AT, REMOVE_ITEM, REMOVE_DUPLICATES, REVERSE and SORT may create new values for the list within the current CMake variable scope. Similar to the SET command, the LIST command creates new variable values in the current scope, even if the list itself is actually defined in a parent scope. To propagate the results of these operations upwards, use SET with PARENT_SCOPE, SET with CACHE INTERNAL, or some other means of value propagation.
NOTES: A list in cmake is a ; separated group of strings. To create a list the set command can be used. For example, set(var a b c d e) creates a list with a;b;c;d;e, and set(var “a b c d e”) creates a string or a list with one item in it. (Note macro arguments are not variables, and therefore cannot be used in LIST commands.)
When specifying index values, if <element index> is 0 or greater, it is indexed from the beginning of the list, with 0 representing the first list element. If <element index> is -1 or lesser, it is indexed from the end of the list, with -1 representing the last list element. Be careful when counting with negative indices: they do not start from 0. -0 is equivalent to 0, the first list element.
add_custom_command()
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[MAIN_DEPENDENCY depend]
[DEPENDS [depends...]]
[IMPLICIT_DEPENDS <lang1> depend1
[<lang2> depend2] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM] [APPEND])
[doc] This defines a command to generate specified OUTPUT file(s). A target created in the same directory (CMakeLists.txt file) that specifies any output of the custom command as a source file is given a rule to generate the file using the command at build time. Do not list the output in more than one independent target that may build in parallel or the two instances of the rule may conflict (instead use add_custom_target to drive the command and make the other targets depend on that one). If an output name is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory.
add_custom_target()
add_custom_target(Name [ALL] [command1 [args1...]]
[COMMAND command2 [args2...] ...]
[DEPENDS depend depend depend ... ]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM]
[SOURCES src1 [src2...]])
[doc] Add a target with no output so it will always be built. Adds a target with the given name that executes the given commands. The target has no output file and is ALWAYS CONSIDERED OUT OF DATE even if the commands try to create a file with the name of the target. Use ADD_CUSTOM_COMMAND to generate a file with dependencies. By default nothing depends on the custom target. Use ADD_DEPENDENCIES to add dependencies to or from other targets. If the ALL option is specified it indicates that this target should be added to the default build target so that it will be run every time (the command cannot be called ALL). The command and arguments are optional and if not specified an empty target will be created. If WORKING_DIRECTORY is set, then the command will be run in that directory. If it is a relative path it will be interpreted relative to the build tree directory corresponding to the current source directory. If COMMENT is set, the value will be displayed as a message before the commands are executed at build time. Dependencies listed with the DEPENDS argument may reference files and outputs of custom commands created with add_custom_command() in the same directory (CMakeLists.txt file).
If VERBATIM is given then all arguments to the commands will be escaped properly for the build tool so that the invoked command receives each argument unchanged. Note that one level of escapes is still used by the CMake language processor before add_custom_target even sees the arguments. Use of VERBATIM is recommended as it enables correct behavior. When VERBATIM is not given the behavior is platform specific because there is no protection of tool-specific special characters.
The SOURCES option specifies additional source files to be included in the custom target. Specified source files will be added to IDE project files for convenience in editing even if they have not build rules.
add_subdirectory()
add_subdirectory(source_dir [binary_dir]
[EXCLUDE_FROM_ALL])
[doc] Add a subdirectory to the build. The source_dir specifies the directory in which the source CMakeLists.txt and code files are located. If it is a relative path it will be evaluated with respect to the current directory (the typical usage), but it may also be an absolute path. The binary_dir specifies the directory in which to place the output files. If it is a relative path it will be evaluated with respect to the current output directory, but it may also be an absolute path. If binary_dir is not specified, the value of source_dir, before expanding any relative path, will be used (the typical usage). The CMakeLists.txt file in the specified source directory will be processed immediately by CMake before processing in the current input file continues beyond this command.
If the EXCLUDE_FROM_ALL argument is provided then targets in the subdirectory will not be included in the ALL target of the parent directory by default, and will be excluded from IDE project files. Users must explicitly build targets in the subdirectory. This is meant for use when the subdirectory contains a separate part of the project that is useful but not necessary, such as a set of examples. Typically the subdirectory should contain its own project() command invocation so that a full build system will be generated in the subdirectory (such as a VS IDE solution file). Note that inter-target dependencies supercede this exclusion. If a target built by the parent project depends on a target in the subdirectory, the dependee target will be included in the parent project build system to satisfy the dependency.
add_library()
add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL]
source1 [source2 ...])
[doc] Adds a library target called<name>to be built from the source files listed in the command invocation. The<name>corresponds to the logical target name and must be globally unique within a project. The actual file name of the library built is constructed based on conventions of the native platform (such aslib<name>.aor<name>.lib).
STATIC,SHARED, orMODULEmay be given to specify the type of library to be created.STATIClibraries are archives of object files for use when linking other targets.SHAREDlibraries are linked dynamically and loaded at runtime.MODULElibraries are plugins that are not linked into other targets but may be loaded dynamically at runtime using dlopen-like functionality. If no type is given explicitly the type isSTATICorSHAREDbased on whether the current value of the variableBUILD_SHARED_LIBSisON. ForSHAREDandMODULElibraries thePOSITION_INDEPENDENT_CODEtarget property is set toONautomatically.
By default the library file will be created in the build tree directory corresponding to the source tree directory in which thecommand was invoked. See documentation of theARCHIVE_OUTPUT_DIRECTORY,LIBRARY_OUTPUT_DIRECTORY, andRUNTIME_OUTPUT_DIRECTORYtarget properties to change this location. See documentation of theOUTPUT_NAMEtarget property to change the<name>part of the final file name.
IfEXCLUDE_FROM_ALLis given the corresponding property will be set on the created target. See documentation of theEXCLUDE_FROM_ALLtarget property for details.
set_target_properties()
set_target_properties(target1 target2 ...
PROPERTIES prop1 value1
prop2 value2 ...)
[doc] Targets can have properties that affect how they are built. Set properties on a target. The syntax for the command is to list all the files you want to change, and then provide the values you want to set next. You can use any prop value pair you want and extract it later with the GET_TARGET_PROPERTY command.
Properties that affect the name of a target’s output file are as follows. The PREFIX and SUFFIX properties override the default target name prefix (such as “lib”) and suffix (such as ”.so”). IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties for the import library corresponding to a DLL (for SHARED library targets). OUTPUT_NAME sets the real name of a target when it is built and can be used to help create two targets of the same name even though CMake requires unique logical target names. There is also a <CONFIG>_OUTPUT_NAME that can set the output name on a per-configuration basis. <CONFIG>_POSTFIX sets a postfix for the real name of the target when it is built under the configuration named by <CONFIG> (in upper-case, such as “DEBUG_POSTFIX”). The value of this property is initialized when the target is created to the value of the variable CMAKE_<CONFIG>_POSTFIX (except for executable targets because earlier CMake versions which did not use this variable for executables).
set_source_file_properties()
set_source_files_properties([file1 [file2 [...]]]
PROPERTIES prop1 value1
[prop2 value2 [...]])
[doc] Set properties associated with source files using a key/value paired list. See Properties on Source Files for the list of properties known to CMake. Source file properties are visible only to targets added in the same directory (CMakeLists.txt).
file()
file(WRITE filename "message to write"... )
file(APPEND filename "message to write"... )
file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
file(STRINGS filename variable [LIMIT_COUNT num]
[LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
[LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
[NEWLINE_CONSUME] [REGEX regex]
[NO_HEX_CONVERSION])
file(GLOB variable [RELATIVE path] [globbing expressions]...)
file(GLOB_RECURSE variable [RELATIVE path]
[FOLLOW_SYMLINKS] [globbing expressions]...)
file(RENAME <oldname> <newname>)
file(REMOVE [file1 ...])
file(REMOVE_RECURSE [file1 ...])
file(MAKE_DIRECTORY [directory1 directory2 ...])
file(RELATIVE_PATH variable directory file)
file(TO_CMAKE_PATH path result)
file(TO_NATIVE_PATH path result)
file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
[TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
[EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
[TLS_VERIFY on|off] [TLS_CAINFO file])
file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
[TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
file(TIMESTAMP filename variable [<format string>] [UTC])
file(GENERATE OUTPUT output_file
<INPUT input_file|CONTENT input_content>
[CONDITION expression])
WRITE will write a message into a file called ‘filename’. It overwrites the file if it already exists, and creates the file if it does not exist. (If the file is a build input, use configure_file to update the file only when its content changes.)
APPEND will write a message into a file same as WRITE, except it will append it to the end of the file
READ will read the content of a file and store it into the variable. It will start at the given offset and read up to numBytes. If the argument HEX is given, the binary data will be converted to hexadecimal representation and this will be stored in the variable.
MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a cryptographic hash of the content of a file.
STRINGS will parse a list of ASCII strings from a file and store it in a variable. Binary data in the file are ignored. Carriage return (CR) characters are ignored. It works also for Intel Hex and Motorola S-record files, which are automatically converted to binary format when reading them. Disable this using NO_HEX_CONVERSION.
LIMIT_COUNT sets the maximum number of strings to return. LIMIT_INPUT sets the maximum number of bytes to read from the input file. LIMIT_OUTPUT sets the maximum number of bytes to store in the output variable. LENGTH_MINIMUM sets the minimum length of a string to return. Shorter strings are ignored. LENGTH_MAXIMUM sets the maximum length of a string to return. Longer strings are split into strings no longer than the maximum length. NEWLINE_CONSUME allows newlines to be included in strings instead of terminating them.
REGEX specifies a regular expression that a string must match to be returned. Typical usage
file(STRINGS myfile.txt myfile)
stores a list in the variable “myfile” in which each item is a line from the input file.
GLOB will generate a list of all files that match the globbing expressions and store it into the variable. Globbing expressions are similar to regular expressions, but much simpler. If RELATIVE flag is specified for an expression, the results will be returned as a relative path to the given path. (We do not recommend using GLOB to collect a list of source files from your source tree. If no CMakeLists.txt file changes when a source is added or removed then the generated build system cannot know when to ask CMake to regenerate.)
Examples of globbing expressions include:
*.cxx - match all files with extension cxx
*.vt? - match all files with extension vta,...,vtz
f[3-5].txt - match files f3.txt, f4.txt, f5.txt
GLOB_RECURSE will generate a list similar to the regular GLOB, except it will traverse all the subdirectories of the matched directory and match the files. Subdirectories that are symlinks are only traversed if FOLLOW_SYMLINKS is given or cmake policy CMP0009 is not set to NEW. See cmake –help-policy CMP0009 for more information.
Examples of recursive globbing include:
/dir/*.py - match all python files in /dir and subdirectories
MAKE_DIRECTORY will create the given directories, also if their parent directories don’t exist yet
RENAME moves a file or directory within a filesystem, replacing the destination atomically.
REMOVE will remove the given files, also in subdirectories
REMOVE_RECURSE will remove the given files and directories, also non-empty directories
RELATIVE_PATH will determine relative path from directory to the given file.
TO_CMAKE_PATH will convert path into a cmake style path with unix /. The input can be a single path or a system path like “$ENV{PATH}”. Note the double quotes around the ENV call TO_CMAKE_PATH only takes one argument. This command will also convert the native list delimiters for a list of paths like the PATH environment variable.
TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert from a cmake style path into the native path style for windows and / for UNIX.
DOWNLOAD will download the given URL to the given file. If LOG var is specified a log of the download will be put in var. If STATUS var is specified the status of the operation will be put in var. The status is returned in a list of length 2. The first element is the numeric return value for the operation, and the second element is a string value for the error. A 0 numeric error means no error in the operation. If TIMEOUT time is specified, the operation will timeout after time seconds, time should be specified as an integer. The INACTIVITY_TIMEOUT specifies an integer number of seconds of inactivity after which the operation should terminate. If EXPECTED_HASH ALGO=value is specified, the operation will verify that the downloaded file’s actual hash matches the expected value, where ALGO is one of MD5, SHA1, SHA224, SHA256, SHA384, or SHA512. If it does not match, the operation fails with an error. (“EXPECTED_MD5 sum” is short-hand for “EXPECTED_HASH MD5=sum”.) If SHOW_PROGRESS is specified, progress information will be printed as status messages until the operation is complete. For https URLs CMake must be built with OpenSSL. TLS/SSL certificates are not checked by default. Set TLS_VERIFY to ON to check certificates and/or use EXPECTED_HASH to verify downloaded content. Set TLS_CAINFO to specify a custom Certificate Authority file. If either TLS option is not given CMake will check variables CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO, respectively.
UPLOAD will upload the given file to the given URL. If LOG var is specified a log of the upload will be put in var. If STATUS var is specified the status of the operation will be put in var. The status is returned in a list of length 2. The first element is the numeric return value for the operation, and the second element is a string value for the error. A 0 numeric error means no error in the operation. If TIMEOUT time is specified, the operation will timeout after time seconds, time should be specified as an integer. The INACTIVITY_TIMEOUT specifies an integer number of seconds of inactivity after which the operation should terminate. If SHOW_PROGRESS is specified, progress information will be printed as status messages until the operation is complete.
TIMESTAMP will write a string representation of the modification time of filename to variable.
cmake_parse_arguments()
CMAKE_PARSE_ARGUMENTS(<prefix><options><one_value_keywords><multi_value_keywords> args...)
CMAKE_PARSE_ARGUMENTS() is intended to be used in macros or functions for parsing the arguments given to that macro or function. It processes the arguments and defines a set of variables which hold the values of the respective options.
The <options> argument contains all options for the respective macro, i.e. keywords which can be used when calling the macro without any value following, like e.g. the OPTIONAL keyword of the install() command.
The <one_value_keywords> argument contains all keywords for this macro which are followed by one value, like e.g. DESTINATION keyword of the install() command.
The <multi_value_keywords> argument contains all keywords for this macro which can be followed by more than one value, like e.g. the TARGETS or FILES keywords of the install() command.
When done, CMAKE_PARSE_ARGUMENTS() will have defined for each of the keywords listed in <options>, <one_value_keywords> and <multi_value_keywords> a variable composed of the given <prefix> followed by “_” and the name of the respective keyword. These variables will then hold the respective value from the argument list. For the <options> keywords this will be TRUE or FALSE.
All remaining arguments are collected in a variable <prefix>_UNPARSED_ARGUMENTS, this can be checked afterwards to see whether your macro was called with unrecognized parameters.
install()