4 Add a custom build rule to the generated build system.
6 There are two main signatures for ``add_custom_command``.
11 The first signature is for adding a custom command to produce an output:
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]
27 [VERBATIM] [APPEND] [USES_TERMINAL]
28 [COMMAND_EXPAND_LISTS])
30 This defines a command to generate specified ``OUTPUT`` file(s).
31 A target created in the same directory (``CMakeLists.txt`` file)
32 that specifies any output of the custom command as a source file
33 is given a rule to generate the file using the command at build time.
34 Do not list the output in more than one independent target that
35 may build in parallel or the two instances of the rule may conflict
36 (instead use the :command:`add_custom_target` command to drive the
37 command and make the other targets depend on that one).
38 In makefile terms this creates a new target in the following form::
40 OUTPUT: MAIN_DEPENDENCY DEPENDS
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.
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.
55 The ``COMMENT``, ``MAIN_DEPENDENCY``, and ``WORKING_DIRECTORY``
56 options are currently ignored when APPEND is given, but may be
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.
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.
79 The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
80 :prop_sf:`GENERATED` files during ``make clean``.
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
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
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:
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.
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.
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).
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`).
127 * ``TARGET_LINKER_FILE``
128 * ``TARGET_SONAME_FILE``
129 * ``TARGET_PDB_FILE``
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
138 Display the given message before the commands are executed at
142 Specify files on which the command depends. Each argument is converted
143 to a dependency as follows:
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
154 2. If the argument is an absolute path, a file-level dependency
155 is created on that path.
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.
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.
165 5. Otherwise, a file-level dependency is created on that path relative
166 to the current binary directory.
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.
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.
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.
181 .. versionadded:: 3.1
182 Arguments to ``DEPENDS`` may use
183 :manual:`generator expressions <cmake-generator-expressions(7)>`.
185 ``COMMAND_EXPAND_LISTS``
186 .. versionadded:: 3.8
188 Lists in ``COMMAND`` arguments will be expanded, including those
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.
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.
208 This option cannot be specified at the same time as ``DEPFILE`` option.
211 .. versionadded:: 3.15
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.
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.
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.
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
246 .. versionadded:: 3.2
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>`.
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.
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.
267 .. versionadded:: 3.13
268 Arguments to ``WORKING_DIRECTORY`` may use
269 :manual:`generator expressions <cmake-generator-expressions(7)>`.
272 .. versionadded:: 3.7
274 Specify a depfile which holds dependencies for the custom command. It is
275 usually emitted by the custom command itself. This keyword may only be used
276 if the generator supports it, as detailed below.
278 The expected format, compatible with what is generated by ``gcc`` with the
279 option ``-M``, is independent of the generator or platform.
281 The formal syntax, as specified using
282 `BNF <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ notation with
283 the regular extensions, is the following:
289 .. productionlist:: depfile
291 rule: `targets` (':' (`separator` `dependencies`?)?)? `eol`
292 targets: `target` (`separator` `target`)* `separator`*
294 dependencies: `dependency` (`separator` `dependency`)* `separator`*
295 dependency: `pathname`
296 separator: (`space` | `line_continue`)+
297 line_continue: '\' `eol`
299 pathname: `character`+
300 character: `std_character` | `dollar` | `hash` | `whitespace`
301 std_character: <any character except '$', '#' or ' '>
313 As part of ``pathname``, any slash and backslash is interpreted as
314 a directory separator.
316 .. versionadded:: 3.7
317 The :generator:`Ninja` generator supports ``DEPFILE`` since the keyword
320 .. versionadded:: 3.17
321 Added the :generator:`Ninja Multi-Config` generator, which included
322 support for the ``DEPFILE`` keyword.
324 .. versionadded:: 3.20
325 Added support for :ref:`Makefile Generators`.
329 ``DEPFILE`` cannot be specified at the same time as the
330 ``IMPLICIT_DEPENDS`` option for :ref:`Makefile Generators`.
332 .. versionadded:: 3.21
333 Added support for :ref:`Visual Studio Generators` with VS 2012 and above,
334 and for the :generator:`Xcode` generator. Support for
335 :manual:`generator expressions <cmake-generator-expressions(7)>` was also
338 Using ``DEPFILE`` with generators other than those listed above is an error.
340 If the ``DEPFILE`` argument is relative, it should be relative to
341 :variable:`CMAKE_CURRENT_BINARY_DIR`, and any relative paths inside the
342 ``DEPFILE`` should also be relative to :variable:`CMAKE_CURRENT_BINARY_DIR`.
343 See policy :policy:`CMP0116`, which is always ``NEW`` for
344 :ref:`Makefile Generators`, :ref:`Visual Studio Generators`,
345 and the :generator:`Xcode` generator.
347 Examples: Generating Files
348 ^^^^^^^^^^^^^^^^^^^^^^^^^^
350 Custom commands may be used to generate source files.
351 For example, the code:
353 .. code-block:: cmake
357 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
359 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
361 add_library(myLib out.c)
363 adds a custom command to run ``someTool`` to generate ``out.c`` and then
364 compile the generated source as part of a library. The generation rule
365 will re-run whenever ``in.txt`` changes.
367 .. versionadded:: 3.20
368 One may use generator expressions to specify per-configuration outputs.
369 For example, the code:
371 .. code-block:: cmake
374 OUTPUT "out-$<CONFIG>.c"
375 COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
378 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
380 add_library(myLib "out-$<CONFIG>.c")
382 adds a custom command to run ``someTool`` to generate ``out-<config>.c``,
383 where ``<config>`` is the build configuration, and then compile the generated
384 source as part of a library.
386 .. _`add_custom_command(TARGET)`:
391 The second signature adds a custom command to a target such as a
392 library or executable. This is useful for performing an operation
393 before or after building the target. The command becomes part of the
394 target and will only execute when the target itself is built. If the
395 target is already built, the command will not execute.
397 .. code-block:: cmake
399 add_custom_command(TARGET <target>
400 PRE_BUILD | PRE_LINK | POST_BUILD
401 COMMAND command1 [ARGS] [args1...]
402 [COMMAND command2 [ARGS] [args2...] ...]
403 [BYPRODUCTS [files...]]
404 [WORKING_DIRECTORY dir]
406 [VERBATIM] [USES_TERMINAL]
407 [COMMAND_EXPAND_LISTS])
409 This defines a new command that will be associated with building the
410 specified ``<target>``. The ``<target>`` must be defined in the current
411 directory; targets defined in other directories may not be specified.
413 When the command will happen is determined by which
414 of the following is specified:
417 On :ref:`Visual Studio Generators`, run before any other rules are
418 executed within the target.
419 On other generators, run just before ``PRE_LINK`` commands.
421 Run after sources have been compiled but before linking the binary
422 or running the librarian or archiver tool of a static library.
423 This is not defined for targets created by the
424 :command:`add_custom_target` command.
426 Run after all other rules within the target have been executed.
428 Projects should always specify one of the above three keywords when using
429 the ``TARGET`` form. For backward compatibility reasons, ``POST_BUILD`` is
430 assumed if no such keyword is given, but projects should explicitly provide
431 one of the keywords to make clear the behavior they expect.
434 Because generator expressions can be used in custom commands,
435 it is possible to define ``COMMAND`` lines or whole custom commands
436 which evaluate to empty strings for certain configurations.
437 For **Visual Studio 2010 (and newer)** generators these command
438 lines or custom commands will be omitted for the specific
439 configuration and no "empty-string-command" will be added.
441 This allows to add individual build events for every configuration.
443 .. versionadded:: 3.21
444 Support for target-dependent generator expressions.
446 Examples: Build Events
447 ^^^^^^^^^^^^^^^^^^^^^^
449 A ``POST_BUILD`` event may be used to post-process a binary after linking.
450 For example, the code:
452 .. code-block:: cmake
454 add_executable(myExe myExe.c)
456 TARGET myExe POST_BUILD
457 COMMAND someHasher -i "$<TARGET_FILE:myExe>"
458 -o "$<TARGET_FILE:myExe>.hash"
461 will run ``someHasher`` to produce a ``.hash`` file next to the executable
464 .. versionadded:: 3.20
465 One may use generator expressions to specify per-configuration byproducts.
466 For example, the code:
468 .. code-block:: cmake
470 add_library(myPlugin MODULE myPlugin.c)
472 TARGET myPlugin POST_BUILD
473 COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
474 --as-code "myPlugin-hash-$<CONFIG>.c"
475 BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
477 add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
479 will run ``someHasher`` after linking ``myPlugin``, e.g. to produce a ``.c``
480 file containing code to check the hash of ``myPlugin`` that the ``myExe``
481 executable can use to verify it before loading.
486 .. versionadded:: 3.20
488 ``add_custom_command`` supports the :generator:`Ninja Multi-Config`
489 generator's cross-config capabilities. See the generator documentation
490 for more information.