1add_custom_command 2------------------ 3 4Add a custom build rule to the generated build system. 5 6There are two main signatures for ``add_custom_command``. 7 8Generating Files 9^^^^^^^^^^^^^^^^ 10 11The first signature is for adding a custom command to produce an output: 12 13.. code-block:: cmake 14 15 add_custom_command(OUTPUT output1 [output2 ...] 16 COMMAND command1 [ARGS] [args1...] 17 [COMMAND command2 [ARGS] [args2...] ...] 18 [MAIN_DEPENDENCY depend] 19 [DEPENDS [depends...]] 20 [BYPRODUCTS [files...]] 21 [IMPLICIT_DEPENDS <lang1> depend1 22 [<lang2> depend2] ...] 23 [WORKING_DIRECTORY dir] 24 [COMMENT comment] 25 [DEPFILE depfile] 26 [JOB_POOL job_pool] 27 [VERBATIM] [APPEND] [USES_TERMINAL] 28 [COMMAND_EXPAND_LISTS]) 29 30This defines a command to generate specified ``OUTPUT`` file(s). 31A target created in the same directory (``CMakeLists.txt`` file) 32that specifies any output of the custom command as a source file 33is given a rule to generate the file using the command at build time. 34Do not list the output in more than one independent target that 35may build in parallel or the two instances of the rule may conflict 36(instead use the :command:`add_custom_target` command to drive the 37command and make the other targets depend on that one). 38In makefile terms this creates a new target in the following form:: 39 40 OUTPUT: MAIN_DEPENDENCY DEPENDS 41 COMMAND 42 43The options are: 44 45``APPEND`` 46 Append the ``COMMAND`` and ``DEPENDS`` option values to the custom 47 command for the first output specified. There must have already 48 been a previous call to this command with the same output. 49 50 If the previous call specified the output via a generator expression, 51 the output specified by the current call must match in at least one 52 configuration after evaluating generator expressions. In this case, 53 the appended commands and dependencies apply to all configurations. 54 55 The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY`` 56 options are currently ignored when APPEND is given, but may be 57 used in the future. 58 59``BYPRODUCTS`` 60 .. versionadded:: 3.2 61 62 Specify the files the command is expected to produce but whose 63 modification time may or may not be newer than the dependencies. 64 If a byproduct name is a relative path it will be interpreted 65 relative to the build tree directory corresponding to the 66 current source directory. 67 Each byproduct file will be marked with the :prop_sf:`GENERATED` 68 source file property automatically. 69 70 Explicit specification of byproducts is supported by the 71 :generator:`Ninja` generator to tell the ``ninja`` build tool 72 how to regenerate byproducts when they are missing. It is 73 also useful when other build rules (e.g. custom commands) 74 depend on the byproducts. Ninja requires a build rule for any 75 generated file on which another rule depends even if there are 76 order-only dependencies to ensure the byproducts will be 77 available before their dependents build. 78 79 The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other 80 :prop_sf:`GENERATED` files during ``make clean``. 81 82 .. versionadded:: 3.20 83 Arguments to ``BYPRODUCTS`` may use a restricted set of 84 :manual:`generator expressions <cmake-generator-expressions(7)>`. 85 :ref:`Target-dependent expressions <Target-Dependent Queries>` are not 86 permitted. 87 88``COMMAND`` 89 Specify the command-line(s) to execute at build time. 90 If more than one ``COMMAND`` is specified they will be executed in order, 91 but *not* necessarily composed into a stateful shell or batch script. 92 (To run a full script, use the :command:`configure_file` command or the 93 :command:`file(GENERATE)` command to create it, and then specify 94 a ``COMMAND`` to launch it.) 95 The optional ``ARGS`` argument is for backward compatibility and 96 will be ignored. 97 98 If ``COMMAND`` specifies an executable target name (created by the 99 :command:`add_executable` command), it will automatically be replaced 100 by the location of the executable created at build time if either of 101 the following is true: 102 103 * The target is not being cross-compiled (i.e. the 104 :variable:`CMAKE_CROSSCOMPILING` variable is not set to true). 105 * .. versionadded:: 3.6 106 The target is being cross-compiled and an emulator is provided (i.e. 107 its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set). 108 In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be 109 prepended to the command before the location of the target executable. 110 111 If neither of the above conditions are met, it is assumed that the 112 command name is a program to be found on the ``PATH`` at build time. 113 114 Arguments to ``COMMAND`` may use 115 :manual:`generator expressions <cmake-generator-expressions(7)>`. 116 Use the :genex:`TARGET_FILE` generator expression to refer to the location 117 of a target later in the command line (i.e. as a command argument rather 118 than as the command to execute). 119 120 Whenever one of the following target based generator expressions are used as 121 a command to execute or is mentioned in a command argument, a target-level 122 dependency will be added automatically so that the mentioned target will be 123 built before any target using this custom command 124 (see policy :policy:`CMP0112`). 125 126 * ``TARGET_FILE`` 127 * ``TARGET_LINKER_FILE`` 128 * ``TARGET_SONAME_FILE`` 129 * ``TARGET_PDB_FILE`` 130 131 This target-level dependency does NOT add a file-level dependency that would 132 cause the custom command to re-run whenever the executable is recompiled. 133 List target names with the ``DEPENDS`` option to add such file-level 134 dependencies. 135 136 137``COMMENT`` 138 Display the given message before the commands are executed at 139 build time. 140 141``DEPENDS`` 142 Specify files on which the command depends. Each argument is converted 143 to a dependency as follows: 144 145 1. If the argument is the name of a target (created by the 146 :command:`add_custom_target`, :command:`add_executable`, or 147 :command:`add_library` command) a target-level dependency is 148 created to make sure the target is built before any target 149 using this custom command. Additionally, if the target is an 150 executable or library, a file-level dependency is created to 151 cause the custom command to re-run whenever the target is 152 recompiled. 153 154 2. If the argument is an absolute path, a file-level dependency 155 is created on that path. 156 157 3. If the argument is the name of a source file that has been 158 added to a target or on which a source file property has been set, 159 a file-level dependency is created on that source file. 160 161 4. If the argument is a relative path and it exists in the current 162 source directory, a file-level dependency is created on that 163 file in the current source directory. 164 165 5. Otherwise, a file-level dependency is created on that path relative 166 to the current binary directory. 167 168 If any dependency is an ``OUTPUT`` of another custom command in the same 169 directory (``CMakeLists.txt`` file), CMake automatically brings the other 170 custom command into the target in which this command is built. 171 172 .. versionadded:: 3.16 173 A target-level dependency is added if any dependency is listed as 174 ``BYPRODUCTS`` of a target or any of its build events in the same 175 directory to ensure the byproducts will be available. 176 177 If ``DEPENDS`` is not specified, the command will run whenever 178 the ``OUTPUT`` is missing; if the command does not actually 179 create the ``OUTPUT``, the rule will always run. 180 181 .. versionadded:: 3.1 182 Arguments to ``DEPENDS`` may use 183 :manual:`generator expressions <cmake-generator-expressions(7)>`. 184 185``COMMAND_EXPAND_LISTS`` 186 .. versionadded:: 3.8 187 188 Lists in ``COMMAND`` arguments will be expanded, including those 189 created with 190 :manual:`generator expressions <cmake-generator-expressions(7)>`, 191 allowing ``COMMAND`` arguments such as 192 ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc`` 193 to be properly expanded. 194 195``IMPLICIT_DEPENDS`` 196 Request scanning of implicit dependencies of an input file. 197 The language given specifies the programming language whose 198 corresponding dependency scanner should be used. 199 Currently only ``C`` and ``CXX`` language scanners are supported. 200 The language has to be specified for every file in the 201 ``IMPLICIT_DEPENDS`` list. Dependencies discovered from the 202 scanning are added to those of the custom command at build time. 203 Note that the ``IMPLICIT_DEPENDS`` option is currently supported 204 only for Makefile generators and will be ignored by other generators. 205 206 .. note:: 207 208 This option cannot be specified at the same time as ``DEPFILE`` option. 209 210``JOB_POOL`` 211 .. versionadded:: 3.15 212 213 Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja` 214 generator. Incompatible with ``USES_TERMINAL``, which implies 215 the ``console`` pool. 216 Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes 217 an error by ninja at build time. 218 219``MAIN_DEPENDENCY`` 220 Specify the primary input source file to the command. This is 221 treated just like any value given to the ``DEPENDS`` option 222 but also suggests to Visual Studio generators where to hang 223 the custom command. Each source file may have at most one command 224 specifying it as its main dependency. A compile command (i.e. for a 225 library or an executable) counts as an implicit main dependency which 226 gets silently overwritten by a custom command specification. 227 228``OUTPUT`` 229 Specify the output files the command is expected to produce. 230 If an output name is a relative path it will be interpreted 231 relative to the build tree directory corresponding to the 232 current source directory. 233 Each output file will be marked with the :prop_sf:`GENERATED` 234 source file property automatically. 235 If the output of the custom command is not actually created 236 as a file on disk it should be marked with the :prop_sf:`SYMBOLIC` 237 source file property. 238 239 .. versionadded:: 3.20 240 Arguments to ``OUTPUT`` may use a restricted set of 241 :manual:`generator expressions <cmake-generator-expressions(7)>`. 242 :ref:`Target-dependent expressions <Target-Dependent Queries>` are not 243 permitted. 244 245``USES_TERMINAL`` 246 .. versionadded:: 3.2 247 248 The command will be given direct access to the terminal if possible. 249 With the :generator:`Ninja` generator, this places the command in 250 the ``console`` :prop_gbl:`pool <JOB_POOLS>`. 251 252``VERBATIM`` 253 All arguments to the commands will be escaped properly for the 254 build tool so that the invoked command receives each argument 255 unchanged. Note that one level of escapes is still used by the 256 CMake language processor before add_custom_command even sees the 257 arguments. Use of ``VERBATIM`` is recommended as it enables 258 correct behavior. When ``VERBATIM`` is not given the behavior 259 is platform specific because there is no protection of 260 tool-specific special characters. 261 262``WORKING_DIRECTORY`` 263 Execute the command with the given current working directory. 264 If it is a relative path it will be interpreted relative to the 265 build tree directory corresponding to the current source directory. 266 267 .. versionadded:: 3.13 268 Arguments to ``WORKING_DIRECTORY`` may use 269 :manual:`generator expressions <cmake-generator-expressions(7)>`. 270 271``DEPFILE`` 272 .. versionadded:: 3.7 273 274 Specify a ``.d`` depfile which holds dependencies for the custom command. 275 It is usually emitted by the custom command itself. This keyword may only 276 be used if the generator supports it, as detailed below. 277 278 .. versionadded:: 3.7 279 The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword 280 was first added. 281 282 .. versionadded:: 3.17 283 Added the :generator:`Ninja Multi-Config` generator, which included 284 support for the ``DEPFILE`` keyword. 285 286 .. versionadded:: 3.20 287 Added support for :ref:`Makefile Generators`. 288 289 .. note:: 290 291 ``DEPFILE`` cannot be specified at the same time as the 292 ``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`. 293 294 .. versionadded:: 3.21 295 Added support for :ref:`Visual Studio Generators` with VS 2012 and above, 296 and for the :generator:`Xcode` generator. Support for 297 :manual:`generator expressions <cmake-generator-expressions(7)>` was also 298 added. 299 300 Using ``DEPFILE`` with generators other than those listed above is an error. 301 302 If the ``DEPFILE`` argument is relative, it should be relative to 303 :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the 304 ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`. 305 See policy :policy:`CMP0116`, which is always ``NEW`` for 306 :ref:`Makefile Generators`, :ref:`Visual Studio Generators`, 307 and the :generator:`Xcode` generator. 308 309Examples: Generating Files 310^^^^^^^^^^^^^^^^^^^^^^^^^^ 311 312Custom commands may be used to generate source files. 313For example, the code: 314 315.. code-block:: cmake 316 317 add_custom_command( 318 OUTPUT out.c 319 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt 320 -o out.c 321 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt 322 VERBATIM) 323 add_library(myLib out.c) 324 325adds a custom command to run ``someTool`` to generate ``out.c`` and then 326compile the generated source as part of a library. The generation rule 327will re-run whenever ``in.txt`` changes. 328 329.. versionadded:: 3.20 330 One may use generator expressions to specify per-configuration outputs. 331 For example, the code: 332 333 .. code-block:: cmake 334 335 add_custom_command( 336 OUTPUT "out-$<CONFIG>.c" 337 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt 338 -o "out-$<CONFIG>.c" 339 -c "$<CONFIG>" 340 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt 341 VERBATIM) 342 add_library(myLib "out-$<CONFIG>.c") 343 344 adds a custom command to run ``someTool`` to generate ``out-<config>.c``, 345 where ``<config>`` is the build configuration, and then compile the generated 346 source as part of a library. 347 348.. _`add_custom_command(TARGET)`: 349 350Build Events 351^^^^^^^^^^^^ 352 353The second signature adds a custom command to a target such as a 354library or executable. This is useful for performing an operation 355before or after building the target. The command becomes part of the 356target and will only execute when the target itself is built. If the 357target is already built, the command will not execute. 358 359.. code-block:: cmake 360 361 add_custom_command(TARGET <target> 362 PRE_BUILD | PRE_LINK | POST_BUILD 363 COMMAND command1 [ARGS] [args1...] 364 [COMMAND command2 [ARGS] [args2...] ...] 365 [BYPRODUCTS [files...]] 366 [WORKING_DIRECTORY dir] 367 [COMMENT comment] 368 [VERBATIM] [USES_TERMINAL] 369 [COMMAND_EXPAND_LISTS]) 370 371This defines a new command that will be associated with building the 372specified ``<target>``. The ``<target>`` must be defined in the current 373directory; targets defined in other directories may not be specified. 374 375When the command will happen is determined by which 376of the following is specified: 377 378``PRE_BUILD`` 379 On :ref:`Visual Studio Generators`, run before any other rules are 380 executed within the target. 381 On other generators, run just before ``PRE_LINK`` commands. 382``PRE_LINK`` 383 Run after sources have been compiled but before linking the binary 384 or running the librarian or archiver tool of a static library. 385 This is not defined for targets created by the 386 :command:`add_custom_target` command. 387``POST_BUILD`` 388 Run after all other rules within the target have been executed. 389 390.. note:: 391 Because generator expressions can be used in custom commands, 392 it is possible to define ``COMMAND`` lines or whole custom commands 393 which evaluate to empty strings for certain configurations. 394 For **Visual Studio 2010 (and newer)** generators these command 395 lines or custom commands will be omitted for the specific 396 configuration and no "empty-string-command" will be added. 397 398 This allows to add individual build events for every configuration. 399 400.. versionadded:: 3.21 401 Support for target-dependent generator expressions. 402 403Examples: Build Events 404^^^^^^^^^^^^^^^^^^^^^^ 405 406A ``POST_BUILD`` event may be used to post-process a binary after linking. 407For example, the code: 408 409.. code-block:: cmake 410 411 add_executable(myExe myExe.c) 412 add_custom_command( 413 TARGET myExe POST_BUILD 414 COMMAND someHasher -i "$<TARGET_FILE:myExe>" 415 -o "$<TARGET_FILE:myExe>.hash" 416 VERBATIM) 417 418will run ``someHasher`` to produce a ``.hash`` file next to the executable 419after linking. 420 421.. versionadded:: 3.20 422 One may use generator expressions to specify per-configuration byproducts. 423 For example, the code: 424 425 .. code-block:: cmake 426 427 add_library(myPlugin MODULE myPlugin.c) 428 add_custom_command( 429 TARGET myPlugin POST_BUILD 430 COMMAND someHasher -i "$<TARGET_FILE:myPlugin>" 431 --as-code "myPlugin-hash-$<CONFIG>.c" 432 BYPRODUCTS "myPlugin-hash-$<CONFIG>.c" 433 VERBATIM) 434 add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c") 435 436 will run ``someHasher`` after linking ``myPlugin``, e.g. to produce a ``.c`` 437 file containing code to check the hash of ``myPlugin`` that the ``myExe`` 438 executable can use to verify it before loading. 439 440Ninja Multi-Config 441^^^^^^^^^^^^^^^^^^ 442 443.. versionadded:: 3.20 444 445 ``add_custom_command`` supports the :generator:`Ninja Multi-Config` 446 generator's cross-config capabilities. See the generator documentation 447 for more information. 448