.\" Man page generated from reStructuredText.

.

.TH "CMAKE-COMMANDS" "7" "October 14, 2015" "3.3.2" "CMake"

.SH NAME

cmake-commands \- CMake Language Command Reference

.

.nr rst2man-indent-level 0

.

.de1 rstReportMargin

\\$1 \\n[an-margin]

level \\n[rst2man-indent-level]

level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

-

\\n[rst2man-indent0]

\\n[rst2man-indent1]

\\n[rst2man-indent2]

..

.de1 INDENT

.\" .rstReportMargin pre:

. RS \\$1

. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

. nr rst2man-indent-level +1

.\" .rstReportMargin post:

..

.de UNINDENT

. RE

.\" indent \\n[an-margin]

.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

.nr rst2man-indent-level -1

.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

.in \\n[rst2man-indent\\n[rst2man-indent-level]]u

..

.SH NORMAL COMMANDS

.sp

These commands may be used freely in CMake projects.

.SS add_compile_options

.sp

Adds options to the compilation of source files.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_compile_options(<option> ...)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Adds options to the compiler command line for targets in the current

directory and below that are added after this command is invoked.

See documentation of the \fBdirectory\fP and

\fBtarget\fP \fBCOMPILE_OPTIONS\fP properties.

.sp

This command can be used to add any options, but alternative commands

exist to add preprocessor definitions (\fBtarget_compile_definitions()\fP

and \fBadd_definitions()\fP) or include directories

(\fBtarget_include_directories()\fP and \fBinclude_directories()\fP).

.sp

Arguments to \fBadd_compile_options\fP may use "generator expressions" with

the syntax \fB$<...>\fP\&.  See the \fBcmake\-generator\-expressions(7)\fP

manual for available expressions.  See the \fBcmake\-buildsystem(7)\fP

manual for more on defining buildsystem properties.

.SS add_custom_command

.sp

Add a custom build rule to the generated build system.

.sp

There are two main signatures for \fBadd_custom_command\fP\&.

.SS Generating Files

.sp

The first signature is for adding a custom command to produce an output:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_custom_command(OUTPUT output1 [output2 ...]

                   COMMAND command1 [ARGS] [args1...]

                   [COMMAND command2 [ARGS] [args2...] ...]

                   [MAIN_DEPENDENCY depend]

                   [DEPENDS [depends...]]

                   [BYPRODUCTS [files...]]

                   [IMPLICIT_DEPENDS <lang1> depend1

                                    [<lang2> depend2] ...]

                   [WORKING_DIRECTORY dir]

                   [COMMENT comment]

                   [VERBATIM] [APPEND] [USES_TERMINAL])

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

This defines a command to generate specified \fBOUTPUT\fP file(s).

A target created in the same directory (\fBCMakeLists.txt\fP 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 the \fBadd_custom_target()\fP command to drive the

command and make the other targets depend on that one).

In makefile terms this creates a new target in the following form:

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

OUTPUT: MAIN_DEPENDENCY DEPENDS

        COMMAND

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

The options are:

.INDENT 0.0

.TP

.B \fBAPPEND\fP

Append the \fBCOMMAND\fP and \fBDEPENDS\fP option values to the custom

command for the first output specified.  There must have already

been a previous call to this command with the same output.

The \fBCOMMENT\fP, \fBMAIN_DEPENDENCY\fP, and \fBWORKING_DIRECTORY\fP

options are currently ignored when APPEND is given, but may be

used in the future.

.TP

.B \fBBYPRODUCTS\fP

Specify the files the command is expected to produce but whose

modification time may or may not be newer than the dependencies.

If a byproduct name is a relative path it will be interpreted

relative to the build tree directory corresponding to the

current source directory.

Each byproduct file will be marked with the \fBGENERATED\fP

source file property automatically.

.sp

Explicit specification of byproducts is supported by the

\fBNinja\fP generator to tell the \fBninja\fP build tool

how to regenerate byproducts when they are missing.  It is

also useful when other build rules (e.g. custom commands)

depend on the byproducts.  Ninja requires a build rule for any

generated file on which another rule depends even if there are

order\-only dependencies to ensure the byproducts will be

available before their dependents build.

.sp

The \fBBYPRODUCTS\fP option is ignored on non\-Ninja generators

except to mark byproducts \fBGENERATED\fP\&.

.TP

.B \fBCOMMAND\fP

Specify the command\-line(s) to execute at build time.

If more than one \fBCOMMAND\fP is specified they will be executed in order,

but \fInot\fP necessarily composed into a stateful shell or batch script.

(To run a full script, use the \fBconfigure_file()\fP command or the

\fBfile(GENERATE)\fP command to create it, and then specify

a \fBCOMMAND\fP to launch it.)

The optional \fBARGS\fP argument is for backward compatibility and

will be ignored.

.sp

If \fBCOMMAND\fP specifies an executable target (created by the

\fBadd_executable()\fP command) it will automatically be replaced

by the location of the executable created at build time.

(Use the \fBTARGET_FILE\fP

\fBgenerator expression\fP to

reference an executable later in the command line.)

Additionally a target\-level dependency will be added so that the

executable target will be built before any target using this custom

command.  However this does NOT add a file\-level dependency that

would cause the custom command to re\-run whenever the executable is

recompiled.

.sp

Arguments to \fBCOMMAND\fP may use

\fBgenerator expressions\fP\&.

References to target names in generator expressions imply target\-level

dependencies, but NOT file\-level dependencies.  List target names with

the \fBDEPENDS\fP option to add file\-level dependencies.

.TP

.B \fBCOMMENT\fP

Display the given message before the commands are executed at

build time.

.TP

.B \fBDEPENDS\fP

Specify files on which the command depends.  If any dependency is

an \fBOUTPUT\fP of another custom command in the same directory

(\fBCMakeLists.txt\fP file) CMake automatically brings the other

custom command into the target in which this command is built.

If \fBDEPENDS\fP is not specified the command will run whenever

the \fBOUTPUT\fP is missing; if the command does not actually

create the \fBOUTPUT\fP then the rule will always run.

If \fBDEPENDS\fP specifies any target (created by the

\fBadd_custom_target()\fP, \fBadd_executable()\fP, or

\fBadd_library()\fP command) a target\-level dependency is

created to make sure the target is built before any target

using this custom command.  Additionally, if the target is an

executable or library a file\-level dependency is created to

cause the custom command to re\-run whenever the target is

recompiled.

.sp

Arguments to \fBDEPENDS\fP may use

\fBgenerator expressions\fP\&.

.TP

.B \fBIMPLICIT_DEPENDS\fP

Request scanning of implicit dependencies of an input file.

The language given specifies the programming language whose

corresponding dependency scanner should be used.

Currently only \fBC\fP and \fBCXX\fP language scanners are supported.

The language has to be specified for every file in the

\fBIMPLICIT_DEPENDS\fP list.  Dependencies discovered from the

scanning are added to those of the custom command at build time.

Note that the \fBIMPLICIT_DEPENDS\fP option is currently supported

only for Makefile generators and will be ignored by other generators.

.TP

.B \fBMAIN_DEPENDENCY\fP

Specify the primary input source file to the command.  This is

treated just like any value given to the \fBDEPENDS\fP option

but also suggests to Visual Studio generators where to hang

the custom command.  At most one custom command may specify a

given source file as its main dependency.

.TP

.B \fBOUTPUT\fP

Specify the output files the command is expected to produce.

If an output name is a relative path it will be interpreted

relative to the build tree directory corresponding to the

current source directory.

Each output file will be marked with the \fBGENERATED\fP

source file property automatically.

If the output of the custom command is not actually created

as a file on disk it should be marked with the \fBSYMBOLIC\fP

source file property.

.TP

.B \fBUSES_TERMINAL\fP

The command will be given direct access to the terminal if possible.

With the \fBNinja\fP generator, this places the command in

the \fBconsole\fP \fBpool\fP\&.

.TP

.B \fBVERBATIM\fP

All arguments to the commands will be escaped properly for the

build tool so that the invoked command receives each argument

unchanged.  Note that one level of escapes is still used by the

CMake language processor before add_custom_command even sees the

arguments.  Use of \fBVERBATIM\fP is recommended as it enables

correct behavior.  When \fBVERBATIM\fP is not given the behavior

is platform specific because there is no protection of

tool\-specific special characters.

.TP

.B \fBWORKING_DIRECTORY\fP

Execute the command with the given current working directory.

If it is a relative path it will be interpreted relative to the

build tree directory corresponding to the current source directory.

.UNINDENT

.SS Build Events

.sp

The second signature adds a custom command to a target such as a

library or executable.  This is useful for performing an operation

before or after building the target.  The command becomes part of the

target and will only execute when the target itself is built.  If the

target is already built, the command will not execute.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_custom_command(TARGET target

                   PRE_BUILD | PRE_LINK | POST_BUILD

                   COMMAND command1 [ARGS] [args1...]

                   [COMMAND command2 [ARGS] [args2...] ...]

                   [BYPRODUCTS [files...]]

                   [WORKING_DIRECTORY dir]

                   [COMMENT comment]

                   [VERBATIM] [USES_TERMINAL])

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

This defines a new command that will be associated with building the

specified target.  When the command will happen is determined by which

of the following is specified:

.INDENT 0.0

.TP

.B \fBPRE_BUILD\fP

Run before any other rules are executed within the target.

This is supported only on Visual Studio 7 or later.

For all other generators \fBPRE_BUILD\fP will be treated as

\fBPRE_LINK\fP\&.

.TP

.B \fBPRE_LINK\fP

Run after sources have been compiled but before linking the binary

or running the librarian or archiver tool of a static library.

This is not defined for targets created by the

\fBadd_custom_target()\fP command.

.TP

.B \fBPOST_BUILD\fP

Run after all other rules within the target have been executed.

.UNINDENT

.SS add_custom_target

.sp

Add a target with no output so it will always be built.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_custom_target(Name [ALL] [command1 [args1...]]

                  [COMMAND command2 [args2...] ...]

                  [DEPENDS depend depend depend ... ]

                  [BYPRODUCTS [files...]]

                  [WORKING_DIRECTORY dir]

                  [COMMENT comment]

                  [VERBATIM] [USES_TERMINAL]

                  [SOURCES src1 [src2...]])

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Adds a target with the given name that executes the given commands.

The target has no output file and is \fIalways considered out of date\fP

even if the commands try to create a file with the name of the target.

Use the \fBadd_custom_command()\fP command to generate a file with

dependencies.  By default nothing depends on the custom target.  Use

the \fBadd_dependencies()\fP command to add dependencies to or

from other targets.

.sp

The options are:

.INDENT 0.0

.TP

.B \fBALL\fP

Indicate that this target should be added to the default build

target so that it will be run every time (the command cannot be

called \fBALL\fP).

.TP

.B \fBBYPRODUCTS\fP

Specify the files the command is expected to produce but whose

modification time may or may not be updated on subsequent builds.

If a byproduct name is a relative path it will be interpreted

relative to the build tree directory corresponding to the

current source directory.

Each byproduct file will be marked with the \fBGENERATED\fP

source file property automatically.

.sp

Explicit specification of byproducts is supported by the

\fBNinja\fP generator to tell the \fBninja\fP build tool

how to regenerate byproducts when they are missing.  It is

also useful when other build rules (e.g. custom commands)

depend on the byproducts.  Ninja requires a build rule for any

generated file on which another rule depends even if there are

order\-only dependencies to ensure the byproducts will be

available before their dependents build.

.sp

The \fBBYPRODUCTS\fP option is ignored on non\-Ninja generators

except to mark byproducts \fBGENERATED\fP\&.

.TP

.B \fBCOMMAND\fP

Specify the command\-line(s) to execute at build time.

If more than one \fBCOMMAND\fP is specified they will be executed in order,

but \fInot\fP necessarily composed into a stateful shell or batch script.

(To run a full script, use the \fBconfigure_file()\fP command or the

\fBfile(GENERATE)\fP command to create it, and then specify

a \fBCOMMAND\fP to launch it.)

.sp

If \fBCOMMAND\fP specifies an executable target (created by the

\fBadd_executable()\fP command) it will automatically be replaced

by the location of the executable created at build time.

Additionally a target\-level dependency will be added so that the

executable target will be built before this custom target.

.sp

Arguments to \fBCOMMAND\fP may use

\fBgenerator expressions\fP\&.

References to target names in generator expressions imply target\-level

dependencies.

.sp

The command and arguments are optional and if not specified an empty

target will be created.

.TP

.B \fBCOMMENT\fP

Display the given message before the commands are executed at

build time.

.TP

.B \fBDEPENDS\fP

Reference files and outputs of custom commands created with

\fBadd_custom_command()\fP command calls in the same directory

(\fBCMakeLists.txt\fP file).  They will be brought up to date when

the target is built.

.sp

Use the \fBadd_dependencies()\fP command to add dependencies

on other targets.

.TP

.B \fBSOURCES\fP

Specify 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 no build rules.

.TP

.B \fBVERBATIM\fP

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 \fBadd_custom_target\fP even sees

the arguments.  Use of \fBVERBATIM\fP is recommended as it enables

correct behavior.  When \fBVERBATIM\fP is not given the behavior

is platform specific because there is no protection of

tool\-specific special characters.

.TP

.B \fBUSES_TERMINAL\fP

The command will be given direct access to the terminal if possible.

With the \fBNinja\fP generator, this places the command in

the \fBconsole\fP \fBpool\fP\&.

.TP

.B \fBWORKING_DIRECTORY\fP

Execute the command with the given current working directory.

If it is a relative path it will be interpreted relative to the

build tree directory corresponding to the current source directory.

.UNINDENT

.SS add_definitions

.sp

Adds \-D define flags to the compilation of source files.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_definitions(\-DFOO \-DBAR ...)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Adds definitions to the compiler command line for targets in the current

directory and below (whether added before or after this command is invoked).

This command can be used to add any flags, but it is intended to add

preprocessor definitions (see the \fBadd_compile_options()\fP command

to add other flags).

Flags beginning in \-D or /D that look like preprocessor definitions are

automatically added to the \fBCOMPILE_DEFINITIONS\fP directory

property for the current directory.  Definitions with non\-trivial values

may be left in the set of flags instead of being converted for reasons of

backwards compatibility.  See documentation of the

\fBdirectory\fP,

\fBtarget\fP,

\fBsource file\fP \fBCOMPILE_DEFINITIONS\fP

properties for details on adding preprocessor definitions to specific

scopes and configurations.

.sp

See the \fBcmake\-buildsystem(7)\fP manual for more on defining

buildsystem properties.

.SS add_dependencies

.sp

Add a dependency between top\-level targets.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_dependencies(<target> [<target\-dependency>]...)

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Make a top\-level \fB<target>\fP depend on other top\-level targets to

ensure that they build before \fB<target>\fP does.  A top\-level target

is one created by one of the \fBadd_executable()\fP,

\fBadd_library()\fP, or \fBadd_custom_target()\fP commands

(but not targets generated by CMake like \fBinstall\fP).

.sp

Dependencies added to an imported target

or an interface library are followed

transitively in its place since the target itself does not build.

.sp

See the \fBDEPENDS\fP option of \fBadd_custom_target()\fP and

\fBadd_custom_command()\fP commands for adding file\-level

dependencies in custom rules.  See the \fBOBJECT_DEPENDS\fP

source file property to add file\-level dependencies to object files.

.SS add_executable

.sp

Add an executable to the project using the specified source files.

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_executable(<name> [WIN32] [MACOSX_BUNDLE]

               [EXCLUDE_FROM_ALL]

               source1 [source2 ...])

.ft P

.fi

.UNINDENT

.UNINDENT

.sp

Adds an executable target called \fB<name>\fP to be built from the source

files listed in the command invocation.  The \fB<name>\fP 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 \fB<name>.exe\fP or just

\fB<name>\fP\&.

.sp

By default the executable file will be created in the build tree

directory corresponding to the source tree directory in which the

command was invoked.  See documentation of the

\fBRUNTIME_OUTPUT_DIRECTORY\fP target property to change this

location.  See documentation of the \fBOUTPUT_NAME\fP target property

to change the \fB<name>\fP part of the final file name.

.sp

If \fBWIN32\fP is given the property \fBWIN32_EXECUTABLE\fP will be

set on the target created.  See documentation of that target property for

details.

.sp

If \fBMACOSX_BUNDLE\fP is given the corresponding property will be set on

the created target.  See documentation of the \fBMACOSX_BUNDLE\fP

target property for details.

.sp

If \fBEXCLUDE_FROM_ALL\fP is given the corresponding property will be set on

the created target.  See documentation of the \fBEXCLUDE_FROM_ALL\fP

target property for details.

.sp

Source arguments to \fBadd_executable\fP may use "generator expressions" with

the syntax \fB$<...>\fP\&.  See the \fBcmake\-generator\-expressions(7)\fP

manual for available expressions.  See the \fBcmake\-buildsystem(7)\fP

manual for more on defining buildsystem properties.

.sp

.ce

----

.ce 0

.sp

.INDENT 0.0

.INDENT 3.5

.sp

.nf

.ft C

add_executable(<name> IMPORTED [GLOBAL])

.ft P