I didn’t know add_custom_command(OUTPUT could accept targets as DEPENDS, I thought only add_custom_command(TARGET could.
…one of the first things you see is “Use the add_dependencies() command to add dependencies between top-level targets.”, “use DEPENDS to specify file dependencies”.
It’s even quite buried in the description.
That’s why I was saying I liked only the second signature, because I thought it was like the first, but for targets.
How I see them now is: the first signature creates basically a custom target on steroids, without properties and without the word “target”. They can do everything custom targets can, and more. But they exist as separate things. Why? I get how they differ, but not why.
The second signature is nice tho. Seems useful to avoid creating too many custom targets that perform setup steps before building a target.
Having said that, you suggested to create a “loose” (without ALL) custom target dependant on a custom command, to get the best of both worlds. The only way I know of making a custom target dependant on a custom command is to have them both in the same file (ok in this case), and to list in the target’s DEPENDS some files in the command’s OUTPUT.
set(watched_files "fileA" "fileB" "fileC") # source and configuration files that could cause a change in the documentation
build_command(sphinx_generate_html_command
TARGET sphinx_generate_html)
add_custom_target(documentation
DEPENDS "${watched_files}")
add_custom_command(OUTPUT "${watched_files}"
COMMAND "sphinx_generate_html_command")
But what happens if I download the project and install? As far as I know “undefined behaviour”, because documentation doesn’t get built (no ALL).
Also, the command doesn’t personally create any output, the custom targets in the dependency chain do. And to be fair, they aren’t even outputs, they already exist and don’t get changed by the command; they would make more sense in the command’s DEPENDS, but then the command would never be ran.
Edit 1
I wonder if you meant to use the expected final documentation files in DEPENDS and OUTPUT, and the “watched files” in the custom command’s DEPENDS.
Like some index.html. I can’t do that. I’d like to be unaware of how the built documentation files are laid off. I’d just need to know the parent directory to install them.
Edit 2
The sphinx_generate_html custom target generated by the FindSphinx.cmake I’m currently using has the ALL option…
So I think that any attempt to avoid unnecessary documentation builds would be pointless. It was the only find module that defined a target, like the official Doxygen one.
The official FindDoxygen.cmake seems to have some logic to decide the ALL option, but I’m not experienced enough to tell what it does.