1 .\" Man page generated from reStructuredText.

     2 .

     3 .TH "CMAKE-GENERATOR-EXPRESSIONS" "7" "October 14, 2015" "3.3.2" "CMake"

     4 .SH NAME

     5 cmake-generator-expressions \- CMake Generator Expressions

     6 .

     7 .nr rst2man-indent-level 0

     8 .

     9 .de1 rstReportMargin

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

    11 level \\n[rst2man-indent-level]

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

    13 -

    14 \\n[rst2man-indent0]

    15 \\n[rst2man-indent1]

    16 \\n[rst2man-indent2]

    17 ..

    18 .de1 INDENT

    19 .\" .rstReportMargin pre:

    20 . RS \\$1

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

    22 . nr rst2man-indent-level +1

    23 .\" .rstReportMargin post:

    24 ..

    25 .de UNINDENT

    26 . RE

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

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

    29 .nr rst2man-indent-level -1

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

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

    32 ..

    33 .SH INTRODUCTION

    34 .sp

    35 Generator expressions are evaluated during build system generation to produce

    36 information specific to each build configuration.

    37 .sp

    38 Generator expressions are allowed in the context of many target properties,

    39 such as \fBLINK_LIBRARIES\fP, \fBINCLUDE_DIRECTORIES\fP,

    40 \fBCOMPILE_DEFINITIONS\fP and others.  They may also be used when using

    41 commands to populate those properties, such as \fBtarget_link_libraries()\fP,

    42 \fBtarget_include_directories()\fP, \fBtarget_compile_definitions()\fP

    43 and others.

    44 .sp

    45 This means that they enable conditional linking, conditional

    46 definitions used when compiling, and conditional include directories and

    47 more.  The conditions may be based on the build configuration, target

    48 properties, platform information or any other queryable information.

    49 .SH LOGICAL EXPRESSIONS

    50 .sp

    51 Logical expressions are used to create conditional output.  The basic

    52 expressions are the \fB0\fP and \fB1\fP expressions.  Because other logical

    53 expressions evaluate to either \fB0\fP or \fB1\fP, they can be composed to

    54 create conditional output:

    55 .INDENT 0.0

    56 .INDENT 3.5

    57 .sp

    58 .nf

    59 .ft C

    60 $<$<CONFIG:Debug>:DEBUG_MODE>

    61 .ft P

    62 .fi

    63 .UNINDENT

    64 .UNINDENT

    65 .sp

    66 expands to \fBDEBUG_MODE\fP when the \fBDebug\fP configuration is used, and

    67 otherwise expands to nothing.

    68 .sp

    69 Available logical expressions are:

    70 .INDENT 0.0

    71 .TP

    72 .B \fB$<BOOL:...>\fP

    73 \fB1\fP if the \fB\&...\fP is true, else \fB0\fP

    74 .TP

    75 .B \fB$<AND:?[,?]...>\fP

    76 \fB1\fP if all \fB?\fP are \fB1\fP, else \fB0\fP

    77 .sp

    78 The \fB?\fP must always be either \fB0\fP or \fB1\fP in boolean expressions.

    79 .TP

    80 .B \fB$<OR:?[,?]...>\fP

    81 \fB0\fP if all \fB?\fP are \fB0\fP, else \fB1\fP

    82 .TP

    83 .B \fB$<NOT:?>\fP

    84 \fB0\fP if \fB?\fP is \fB1\fP, else \fB1\fP

    85 .TP

    86 .B \fB$<STREQUAL:a,b>\fP

    87 \fB1\fP if \fBa\fP is STREQUAL \fBb\fP, else \fB0\fP

    88 .TP

    89 .B \fB$<EQUAL:a,b>\fP

    90 \fB1\fP if \fBa\fP is EQUAL \fBb\fP in a numeric comparison, else \fB0\fP

    91 .TP

    92 .B \fB$<CONFIG:cfg>\fP

    93 \fB1\fP if config is \fBcfg\fP, else \fB0\fP\&. This is a case\-insensitive comparison.

    94 The mapping in \fBMAP_IMPORTED_CONFIG_<CONFIG>\fP is also considered by

    95 this expression when it is evaluated on a property on an \fBIMPORTED\fP

    96 target.

    97 .TP

    98 .B \fB$<PLATFORM_ID:comp>\fP

    99 \fB1\fP if the CMake\-id of the platform matches \fBcomp\fP, otherwise \fB0\fP\&.

   100 .TP

   101 .B \fB$<C_COMPILER_ID:comp>\fP

   102 \fB1\fP if the CMake\-id of the C compiler matches \fBcomp\fP, otherwise \fB0\fP\&.

   103 .TP

   104 .B \fB$<CXX_COMPILER_ID:comp>\fP

   105 \fB1\fP if the CMake\-id of the CXX compiler matches \fBcomp\fP, otherwise \fB0\fP\&.

   106 .TP

   107 .B \fB$<VERSION_GREATER:v1,v2>\fP

   108 \fB1\fP if \fBv1\fP is a version greater than \fBv2\fP, else \fB0\fP\&.

   109 .TP

   110 .B \fB$<VERSION_LESS:v1,v2>\fP

   111 \fB1\fP if \fBv1\fP is a version less than \fBv2\fP, else \fB0\fP\&.

   112 .TP

   113 .B \fB$<VERSION_EQUAL:v1,v2>\fP

   114 \fB1\fP if \fBv1\fP is the same version as \fBv2\fP, else \fB0\fP\&.

   115 .TP

   116 .B \fB$<C_COMPILER_VERSION:ver>\fP

   117 \fB1\fP if the version of the C compiler matches \fBver\fP, otherwise \fB0\fP\&.

   118 .TP

   119 .B \fB$<CXX_COMPILER_VERSION:ver>\fP

   120 \fB1\fP if the version of the CXX compiler matches \fBver\fP, otherwise \fB0\fP\&.

   121 .TP

   122 .B \fB$<TARGET_POLICY:pol>\fP

   123 \fB1\fP if the policy \fBpol\fP was NEW when the \(aqhead\(aq target was created,

   124 else \fB0\fP\&.  If the policy was not set, the warning message for the policy

   125 will be emitted. This generator expression only works for a subset of

   126 policies.

   127 .TP

   128 .B \fB$<COMPILE_FEATURES:feature[,feature]...>\fP

   129 \fB1\fP if all of the \fBfeature\fP features are available for the \(aqhead\(aq

   130 target, and \fB0\fP otherwise. If this expression is used while evaluating

   131 the link implementation of a target and if any dependency transitively

   132 increases the required \fBC_STANDARD\fP or \fBCXX_STANDARD\fP

   133 for the \(aqhead\(aq target, an error is reported.  See the

   134 \fBcmake\-compile\-features(7)\fP manual for information on

   135 compile features and a list of supported compilers.

   136 .TP

   137 .B \fB$<COMPILE_LANGUAGE:lang>\fP

   138 \fB1\fP when the language used for compilation unit matches \fBlang\fP,

   139 otherwise \fB0\fP\&.  This expression used to specify compile options for

   140 source files of a particular language in a target. For example, to specify

   141 the use of the \fB\-fno\-exceptions\fP compile option (compiler id checks

   142 elided):

   143 .INDENT 7.0

   144 .INDENT 3.5

   145 .sp

   146 .nf

   147 .ft C

   148 add_executable(myapp main.cpp foo.c bar.cpp)

   149 target_compile_options(myapp

   150   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:\-fno\-exceptions>

   151 )

   152 .ft P

   153 .fi

   154 .UNINDENT

   155 .UNINDENT

   156 .sp

   157 This generator expression has limited use because it is not possible to

   158 use it with the Visual Studio generators.  Portable buildsystems would

   159 not use this expression, and would create separate libraries for each

   160 source file language instead:

   161 .INDENT 7.0

   162 .INDENT 3.5

   163 .sp

   164 .nf

   165 .ft C

   166 add_library(myapp_c foo.c)

   167 add_library(myapp_cxx foo.c)

   168 target_compile_options(myapp_cxx PUBLIC \-fno\-exceptions)

   169 add_executable(myapp main.cpp)

   170 target_link_libraries(myapp myapp_c myapp_cxx)

   171 .ft P

   172 .fi

   173 .UNINDENT

   174 .UNINDENT

   175 .sp

   176 The \fBMakefile\fP and \fBNinja\fP based generators can also use this

   177 expression to specify compile\-language specific compile definitions

   178 and include directories:

   179 .INDENT 7.0

   180 .INDENT 3.5

   181 .sp

   182 .nf

   183 .ft C

   184 add_executable(myapp main.cpp foo.c bar.cpp)

   185 target_compile_definitions(myapp

   186   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:COMPILING_CXX>

   187 )

   188 target_include_directories(myapp

   189   PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers>

   190 )

   191 .ft P

   192 .fi

   193 .UNINDENT

   194 .UNINDENT

   195 .UNINDENT

   196 .SH INFORMATIONAL EXPRESSIONS

   197 .sp

   198 These expressions expand to some information. The information may be used

   199 directly, eg:

   200 .INDENT 0.0

   201 .INDENT 3.5

   202 .sp

   203 .nf

   204 .ft C

   205 include_directories(/usr/include/$<CXX_COMPILER_ID>/)

   206 .ft P

   207 .fi

   208 .UNINDENT

   209 .UNINDENT

   210 .sp

   211 expands to \fB/usr/include/GNU/\fP or \fB/usr/include/Clang/\fP etc, depending on

   212 the Id of the compiler.

   213 .sp

   214 These expressions may also may be combined with logical expressions:

   215 .INDENT 0.0

   216 .INDENT 3.5

   217 .sp

   218 .nf

   219 .ft C

   220 $<$<VERSION_LESS:$<CXX_COMPILER_VERSION>,4.2.0>:OLD_COMPILER>

   221 .ft P

   222 .fi

   223 .UNINDENT

   224 .UNINDENT

   225 .sp

   226 expands to \fBOLD_COMPILER\fP if the

   227 \fBCMAKE_CXX_COMPILER_VERSION\fP is less

   228 than 4.2.0.

   229 .sp

   230 Available informational expressions are:

   231 .INDENT 0.0

   232 .TP

   233 .B \fB$<CONFIGURATION>\fP

   234 Configuration name. Deprecated. Use \fBCONFIG\fP instead.

   235 .TP

   236 .B \fB$<CONFIG>\fP

   237 Configuration name

   238 .TP

   239 .B \fB$<PLATFORM_ID>\fP

   240 The CMake\-id of the platform.

   241 See also the \fBCMAKE_SYSTEM_NAME\fP variable.

   242 .TP

   243 .B \fB$<C_COMPILER_ID>\fP

   244 The CMake\-id of the C compiler used.

   245 See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.

   246 .TP

   247 .B \fB$<CXX_COMPILER_ID>\fP

   248 The CMake\-id of the CXX compiler used.

   249 See also the \fBCMAKE_<LANG>_COMPILER_ID\fP variable.

   250 .TP

   251 .B \fB$<C_COMPILER_VERSION>\fP

   252 The version of the C compiler used.

   253 See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.

   254 .TP

   255 .B \fB$<CXX_COMPILER_VERSION>\fP

   256 The version of the CXX compiler used.

   257 See also the \fBCMAKE_<LANG>_COMPILER_VERSION\fP variable.

   258 .TP

   259 .B \fB$<TARGET_FILE:tgt>\fP

   260 Full path to main file (.exe, .so.1.2, .a) where \fBtgt\fP is the name of a target.

   261 .TP

   262 .B \fB$<TARGET_FILE_NAME:tgt>\fP

   263 Name of main file (.exe, .so.1.2, .a).

   264 .TP

   265 .B \fB$<TARGET_FILE_DIR:tgt>\fP

   266 Directory of main file (.exe, .so.1.2, .a).

   267 .TP

   268 .B \fB$<TARGET_LINKER_FILE:tgt>\fP

   269 File used to link (.a, .lib, .so) where \fBtgt\fP is the name of a target.

   270 .TP

   271 .B \fB$<TARGET_LINKER_FILE_NAME:tgt>\fP

   272 Name of file used to link (.a, .lib, .so).

   273 .TP

   274 .B \fB$<TARGET_LINKER_FILE_DIR:tgt>\fP

   275 Directory of file used to link (.a, .lib, .so).

   276 .TP

   277 .B \fB$<TARGET_SONAME_FILE:tgt>\fP

   278 File with soname (.so.3) where \fBtgt\fP is the name of a target.

   279 .TP

   280 .B \fB$<TARGET_SONAME_FILE_NAME:tgt>\fP

   281 Name of file with soname (.so.3).

   282 .TP

   283 .B \fB$<TARGET_SONAME_FILE_DIR:tgt>\fP

   284 Directory of with soname (.so.3).

   285 .TP

   286 .B \fB$<TARGET_PDB_FILE:tgt>\fP

   287 Full path to the linker generated program database file (.pdb)

   288 where \fBtgt\fP is the name of a target.

   289 .sp

   290 See also the \fBPDB_NAME\fP and \fBPDB_OUTPUT_DIRECTORY\fP

   291 target properties and their configuration specific variants

   292 \fBPDB_NAME_<CONFIG>\fP and \fBPDB_OUTPUT_DIRECTORY_<CONFIG>\fP\&.

   293 .TP

   294 .B \fB$<TARGET_PDB_FILE_NAME:tgt>\fP

   295 Name of the linker generated program database file (.pdb).

   296 .TP

   297 .B \fB$<TARGET_PDB_FILE_DIR:tgt>\fP

   298 Directory of the linker generated program database file (.pdb).

   299 .TP

   300 .B \fB$<TARGET_PROPERTY:tgt,prop>\fP

   301 Value of the property \fBprop\fP on the target \fBtgt\fP\&.

   302 .sp

   303 Note that \fBtgt\fP is not added as a dependency of the target this

   304 expression is evaluated on.

   305 .TP

   306 .B \fB$<TARGET_PROPERTY:prop>\fP

   307 Value of the property \fBprop\fP on the target on which the generator

   308 expression is evaluated.

   309 .TP

   310 .B \fB$<INSTALL_PREFIX>\fP

   311 Content of the install prefix when the target is exported via

   312 \fBinstall(EXPORT)\fP and empty otherwise.

   313 .TP

   314 .B \fB$<COMPILE_LANGUAGE>\fP

   315 The compile language of source files when evaluating compile options. See

   316 the unary version for notes about portability of this generator

   317 expression.

   318 .UNINDENT

   319 .SH OUTPUT EXPRESSIONS

   320 .sp

   321 These expressions generate output, in some cases depending on an input. These

   322 expressions may be combined with other expressions for information or logical

   323 comparison:

   324 .INDENT 0.0

   325 .INDENT 3.5

   326 .sp

   327 .nf

   328 .ft C

   329 \-I$<JOIN:$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>, \-I>

   330 .ft P

   331 .fi

   332 .UNINDENT

   333 .UNINDENT

   334 .sp

   335 generates a string of the entries in the \fBINCLUDE_DIRECTORIES\fP target

   336 property with each entry preceeded by \fB\-I\fP\&. Note that a more\-complete use

   337 in this situation would require first checking if the INCLUDE_DIRECTORIES

   338 property is non\-empty:

   339 .INDENT 0.0

   340 .INDENT 3.5

   341 .sp

   342 .nf

   343 .ft C

   344 $<$<BOOL:${prop}>:\-I$<JOIN:${prop}, \-I>>

   345 .ft P

   346 .fi

   347 .UNINDENT

   348 .UNINDENT

   349 .sp

   350 where \fB${prop}\fP refers to a helper variable:

   351 .INDENT 0.0

   352 .INDENT 3.5

   353 .sp

   354 .nf

   355 .ft C

   356 set(prop "$<TARGET_PROPERTY:INCLUDE_DIRECTORIES>")

   357 .ft P

   358 .fi

   359 .UNINDENT

   360 .UNINDENT

   361 .sp

   362 Available output expressions are:

   363 .INDENT 0.0

   364 .TP

   365 .B \fB$<0:...>\fP

   366 Empty string (ignores \fB\&...\fP)

   367 .TP

   368 .B \fB$<1:...>\fP

   369 Content of \fB\&...\fP

   370 .TP

   371 .B \fB$<JOIN:list,...>\fP

   372 Joins the list with the content of \fB\&...\fP

   373 .TP

   374 .B \fB$<ANGLE\-R>\fP

   375 A literal \fB>\fP\&. Used to compare strings which contain a \fB>\fP for example.

   376 .TP

   377 .B \fB$<COMMA>\fP

   378 A literal \fB,\fP\&. Used to compare strings which contain a \fB,\fP for example.

   379 .TP

   380 .B \fB$<SEMICOLON>\fP

   381 A literal \fB;\fP\&. Used to prevent list expansion on an argument with \fB;\fP\&.

   382 .TP

   383 .B \fB$<TARGET_NAME:...>\fP

   384 Marks \fB\&...\fP as being the name of a target.  This is required if exporting

   385 targets to multiple dependent export sets.  The \fB\&...\fP must be a literal

   386 name of a target\- it may not contain generator expressions.

   387 .TP

   388 .B \fB$<LINK_ONLY:...>\fP

   389 Content of \fB\&...\fP except when evaluated in a link interface while

   390 propagating Target Usage Requirements, in which case it is the

   391 empty string.

   392 Intended for use only in an \fBINTERFACE_LINK_LIBRARIES\fP target

   393 property, perhaps via the \fBtarget_link_libraries()\fP command,

   394 to specify private link dependencies without other usage requirements.

   395 .TP

   396 .B \fB$<INSTALL_INTERFACE:...>\fP

   397 Content of \fB\&...\fP when the property is exported using \fBinstall(EXPORT)\fP,

   398 and empty otherwise.

   399 .TP

   400 .B \fB$<BUILD_INTERFACE:...>\fP

   401 Content of \fB\&...\fP when the property is exported using \fBexport()\fP, or

   402 when the target is used by another target in the same buildsystem. Expands to

   403 the empty string otherwise.

   404 .TP

   405 .B \fB$<LOWER_CASE:...>\fP

   406 Content of \fB\&...\fP converted to lower case.

   407 .TP

   408 .B \fB$<UPPER_CASE:...>\fP

   409 Content of \fB\&...\fP converted to upper case.

   410 .TP

   411 .B \fB$<MAKE_C_IDENTIFIER:...>\fP

   412 Content of \fB\&...\fP converted to a C identifier.

   413 .TP

   414 .B \fB$<TARGET_OBJECTS:objLib>\fP

   415 List of objects resulting from build of \fBobjLib\fP\&. \fBobjLib\fP must be an

   416 object of type \fBOBJECT_LIBRARY\fP\&.  This expression may only be used in

   417 the sources of \fBadd_library()\fP and \fBadd_executable()\fP

   418 commands.

   419 .UNINDENT

   420 .SH COPYRIGHT

   421 2000-2015 Kitware, Inc.

   422 .\" Generated by docutils manpage writer.

   423 .