4 Add a target with no output so it will always be built.
8 add_custom_target(Name [ALL] [command1 [args1...]]
9 [COMMAND command2 [args2...] ...]
10 [DEPENDS depend depend depend ... ]
11 [BYPRODUCTS [files...]]
12 [WORKING_DIRECTORY dir]
15 [VERBATIM] [USES_TERMINAL]
16 [COMMAND_EXPAND_LISTS]
17 [SOURCES src1 [src2...]])
19 Adds a target with the given name that executes the given commands.
20 The target has no output file and is *always considered out of date*
21 even if the commands try to create a file with the name of the target.
22 Use the :command:`add_custom_command` command to generate a file with
23 dependencies. By default nothing depends on the custom target. Use
24 the :command:`add_dependencies` command to add dependencies to or
30 Indicate that this target should be added to the default build
31 target so that it will be run every time (the command cannot be
37 Specify the files the command is expected to produce but whose
38 modification time may or may not be updated on subsequent builds.
39 If a byproduct name is a relative path it will be interpreted
40 relative to the build tree directory corresponding to the
41 current source directory.
42 Each byproduct file will be marked with the :prop_sf:`GENERATED`
43 source file property automatically.
45 *See policy* :policy:`CMP0058` *for the motivation behind this feature.*
47 Explicit specification of byproducts is supported by the
48 :generator:`Ninja` generator to tell the ``ninja`` build tool
49 how to regenerate byproducts when they are missing. It is
50 also useful when other build rules (e.g. custom commands)
51 depend on the byproducts. Ninja requires a build rule for any
52 generated file on which another rule depends even if there are
53 order-only dependencies to ensure the byproducts will be
54 available before their dependents build.
56 The :ref:`Makefile Generators` will remove ``BYPRODUCTS`` and other
57 :prop_sf:`GENERATED` files during ``make clean``.
59 .. versionadded:: 3.20
60 Arguments to ``BYPRODUCTS`` may use a restricted set of
61 :manual:`generator expressions <cmake-generator-expressions(7)>`.
62 :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
66 Specify the command-line(s) to execute at build time.
67 If more than one ``COMMAND`` is specified they will be executed in order,
68 but *not* necessarily composed into a stateful shell or batch script.
69 (To run a full script, use the :command:`configure_file` command or the
70 :command:`file(GENERATE)` command to create it, and then specify
71 a ``COMMAND`` to launch it.)
73 If ``COMMAND`` specifies an executable target name (created by the
74 :command:`add_executable` command), it will automatically be replaced
75 by the location of the executable created at build time if either of
76 the following is true:
78 * The target is not being cross-compiled (i.e. the
79 :variable:`CMAKE_CROSSCOMPILING` variable is not set to true).
80 * .. versionadded:: 3.6
81 The target is being cross-compiled and an emulator is provided (i.e.
82 its :prop_tgt:`CROSSCOMPILING_EMULATOR` target property is set).
83 In this case, the contents of :prop_tgt:`CROSSCOMPILING_EMULATOR` will be
84 prepended to the command before the location of the target executable.
86 If neither of the above conditions are met, it is assumed that the
87 command name is a program to be found on the ``PATH`` at build time.
89 Arguments to ``COMMAND`` may use
90 :manual:`generator expressions <cmake-generator-expressions(7)>`.
91 Use the :genex:`TARGET_FILE` generator expression to refer to the location
92 of a target later in the command line (i.e. as a command argument rather
93 than as the command to execute).
95 Whenever one of the following target based generator expressions are used as
96 a command to execute or is mentioned in a command argument, a target-level
97 dependency will be added automatically so that the mentioned target will be
98 built before this custom target (see policy :policy:`CMP0112`).
101 * ``TARGET_LINKER_FILE``
102 * ``TARGET_SONAME_FILE``
103 * ``TARGET_PDB_FILE``
105 The command and arguments are optional and if not specified an empty
106 target will be created.
109 Display the given message before the commands are executed at
113 Reference files and outputs of custom commands created with
114 :command:`add_custom_command` command calls in the same directory
115 (``CMakeLists.txt`` file). They will be brought up to date when
118 .. versionchanged:: 3.16
119 A target-level dependency is added if any dependency is a byproduct
120 of a target or any of its build events in the same directory to ensure
121 the byproducts will be available before this target is built.
123 Use the :command:`add_dependencies` command to add dependencies
126 ``COMMAND_EXPAND_LISTS``
127 .. versionadded:: 3.8
129 Lists in ``COMMAND`` arguments will be expanded, including those
131 :manual:`generator expressions <cmake-generator-expressions(7)>`,
132 allowing ``COMMAND`` arguments such as
133 ``${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc``
134 to be properly expanded.
137 .. versionadded:: 3.15
139 Specify a :prop_gbl:`pool <JOB_POOLS>` for the :generator:`Ninja`
140 generator. Incompatible with ``USES_TERMINAL``, which implies
141 the ``console`` pool.
142 Using a pool that is not defined by :prop_gbl:`JOB_POOLS` causes
143 an error by ninja at build time.
146 Specify additional source files to be included in the custom target.
147 Specified source files will be added to IDE project files for
148 convenience in editing even if they have no build rules.
151 All arguments to the commands will be escaped properly for the
152 build tool so that the invoked command receives each argument
153 unchanged. Note that one level of escapes is still used by the
154 CMake language processor before ``add_custom_target`` even sees
155 the arguments. Use of ``VERBATIM`` is recommended as it enables
156 correct behavior. When ``VERBATIM`` is not given the behavior
157 is platform specific because there is no protection of
158 tool-specific special characters.
161 .. versionadded:: 3.2
163 The command will be given direct access to the terminal if possible.
164 With the :generator:`Ninja` generator, this places the command in
165 the ``console`` :prop_gbl:`pool <JOB_POOLS>`.
167 ``WORKING_DIRECTORY``
168 Execute the command with the given current working directory.
169 If it is a relative path it will be interpreted relative to the
170 build tree directory corresponding to the current source directory.
172 .. versionadded:: 3.13
173 Arguments to ``WORKING_DIRECTORY`` may use
174 :manual:`generator expressions <cmake-generator-expressions(7)>`.
179 .. versionadded:: 3.20
181 ``add_custom_target`` supports the :generator:`Ninja Multi-Config`
182 generator's cross-config capabilities. See the generator documentation
183 for more information.