Find a CMake file-generating add_custom_command example in which DEPENDS option is necessary

Question

I want a simple example to illustrate the DEPENDS option of file generating add_custom_command(OUTPUT ...), that is, if we comment the DEPENDS part, the example will give different output or totally crash.

In the following example (there are files london and good.cpp in the current working directory), DEPENDS is dispensable:

cmake_minimum_required(VERSION 3.10)
project(Tutorial VERSION 1.0)

add_custom_command(OUTPUT foo
COMMAND cp london foo
#DEPENDS london
COMMENT "I'm testing the new method.")

add_executable(cake good.cpp foo)

I did read the documentation. I have little knowledge about building system, neither Make nor CMake. The first sentence Specify files on which the command depends. confuses me. I don't understand how a command depends on other files, in my casual example, the command line itself seems to locate everything. I want a CMake code example to show how command depends on other files, with the necessary help of DEPENDS.

@Ysyvarev I gave the casual example just to show some scenario where DEPENDS is dispensable. My goal is to find an example where DEPENDS is really necessary. — Neymar87, Nov 16 '21 at 10:56
Actually, I find strange a question which tells "the option XXX could be omitted because everything works without it". It is you as a project's developer decide which **functionality** do you need. If desired functionality is provided by the option XXX, then you use the option. If you don't need a functionality, then you don't need to use the option. — Tsyvarev, Nov 16 '21 at 10:56
@Tsyvarev You're totally right from the engineering perspective. I'm now learning CMake and want to understand how to make use of this option, I'm not trying to solve a real problem. — Neymar87, Nov 16 '21 at 11:00
If you want to understand how the option works, then the first place to check is [documentation](https://cmake.org/cmake/help/latest/command/add_custom_command.html). Have you read it? What is not clear in it? E.g. "If `DEPENDS` is not specified, the command will run whenever the `OUTPUT` is missing; if the command does not actually create the `OUTPUT`, the rule will always run." If you are familiar with Make, then documentation provides Make-view on the dependencies: `OUTPUT: MAIN_DEPENDENCY DEPENDS`. — Tsyvarev, Nov 16 '21 at 11:04
@Tsyvarev I did read the documentation. I have little knowledge about building system, neither Make nor CMake. The first sentence `Specify files on which the command depends. ` confuses me. I don't understand how a command depends on other files, in my casual example, the command line itself seems to locate everything. I want a CMake code example to show how command depends on other files, with the necessary help of `DEPENDS`. — Neymar87, Nov 16 '21 at 11:14
Well, your [last comment](https://stackoverflow.com/questions/69987498/find-a-cmake-file-generating-add-custom-command-example-in-which-depends-option?noredirect=1#comment123719209_69987498) seems to state your **actual problem**. Please, incorporate it into the **question post** (On Stack Overflow a question post should be understandable without reading the comments. The comments themselves are "secondary citizen".) — Tsyvarev, Nov 16 '21 at 11:30
`I don't understand how a command depends on other files` Wouldn't you want `foo` to change when `london` is changed? Development is about editing files, you edit `london` and recompile your project - so you expect `foo` to be changed, and `cake` to be changed. Without `DEPENDS`, nothing will be done, because cmake will not know anything changed. — KamilCuk, Nov 16 '21 at 11:56
@KamilCuk Your comment helps me truly understand the function of `DEPENDS`! Awesome! — Neymar87, Nov 16 '21 at 12:08

score 0 · Accepted Answer · answered Nov 16 '21 at 12:22

The phrase in documentation

Specify files on which the command depends.

is better understandable as

Specify files on which content of the command's output file(s) depends.

As one could guess, a content of the output file of the command cp london foo depends only from london, so it is reasonable to specify option DEPENDS london for add_custom_command.

As a build system, CMake uses information in DEPENDS for decide, whether to run the command or not. If:

OUTPUT file has already been created on previous run, and
since previous run the DEPENDS file has not been updated,

then the command won't be run again. The reasoning is simple: no needs to run the command if it results with the same file(s).

Taking into account source (CMAKE_SOURCE_DIR) and build (CMAKE_BINARY_DIR) directories separation, the example could be rewritten as follows:

cmake_minimum_required(VERSION 3.10)
project(Tutorial VERSION 1.0)

add_custom_command(
  OUTPUT foo # relative path denotes a file in the build directory
  COMMAND cp ${CMAKE_SOURCE_DIR}/london foo # The command will be run from the build directory,
    # so need to use absolute path for the file in the source directory
  DEPENDS london # relative path is resolved in the source directory,
    # assuming that corresponded file is already existed
  WORKING_DIRECTORY ${CMAKE_BINARY_DIR} # specifies a directory from which run the COMMAND
    # build directory is used by default, so the option can be omitted
  COMMENT "I'm testing the new method."
)

add_executable(cake
  good.cpp # relative path is resolved in the source directory,
    # assuming that corresponded file is already existed
  foo # because given file is absent in the source directory,
    # the path is resolved relative to the build directory.
)

When build the project the first time, both foo and executable will be built.

When build the project the second time (without changing in london) nothing will be rebuilt.

When change london file and build the project again, foo will be re-built (because it depends on london). As foo is rebuilt, the executable will be rebuilt too, because it depends on foo.

Find a CMake file-generating add_custom_command example in which DEPENDS option is necessary

1 Answers1