Custom targets

A custom target is added with a call to add_custom_target.

It is analogous to a GNU make phony target

The cmake documentation says add_custom_target "adds a target with no output so it will always be built". That is a little misleading. Rather it adds a target which is always considered out of date. It will be built if and only if 'ALL' is specified or there exists some downstream target which is being built which depends on it.

For example, consider a target named T defined as follows:

add_custom_target(T 
    COMMENT "copying file" 
    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/readme.txt .)

Building target T means running its associated commands. Here the COMMAND uses cmake itself to copy a file named readme.txt from the current source directory to the current binary directory.

If there are no targets depending on T, the copy command will never run. To force it to run 'ALL' can be specified to indicate that the target should be added to the default build target so that it runs every time:

add_custom_target(T ALL 
    COMMENT "copying file" 
    COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/readme.txt .)

Dependencies

The following command declares a custom target named T that depends on file1 and file2:

add_custom_target(T DEPENDS file1 file2)

This means that when T is built, file1 and file2 will first be brought up to date (if there are build rules to create them).

If there are no rules to make file1 or file2 then cmake doesn't report an error during the configure phase. If you are using the ninja generator, then an error such as "file1 needed by T missing and no known rule to make it" is reported when ninja runs.

Sources

When sources are specified, they will be added to IDE project files for convenience in editing even if they have no build rules:

add_custom_target(mytarget SOURCES file1 file2 file3)