Page https://cmake.org/cmake/help/latest/prop_test/LABELS.html is also of no great help. It could be greatly improved by adding an example how to to set a label.
Doc page ctest(1) has a section "Label Matching" that says: "Tests may have labels attached to them."
At this point, one might look for a link to an explanation how to set such labels.
Different CMake commands process COMMAND arguments in different ways. Specifically for an empty-string argument we may, or may not, need to escape quotation marks:
execute_process(COMMAND binder --bind "")
add_custom_command(OUTPUT ... COMMAND binder --bind \"\")
If this cannot be homogenized in source, then at least it ought to be documented in Help.
The old text talks about file creation in sentence 1, mine only in sentence 2.
Anyway, I can do no more than point to text I found misleading or difficult to understand, and make suggestions for improvement. Up to you to adopt or adapt whatever you find useful.
ok, see new version
Joachim Wuttke (84df679f) at 06 May 11:32
Help: rewrite intro of add_custom_target
The current doc page says: "The target has no output file." This is correct only when understood in a precise technical sense: The target has no formal output, but the commands invoked by the target are well allowed to generate output files.
Furthermore, the doc page says: "it will always be built." This is only true if the flag ALL
is given. Otherwise, the target will only be built when explicitly invoked.
This is my attempt to describe the purpose of the command in a simple, yet precise way. Feel free to edit the wording.
Joachim Wuttke (e1625ebf) at 06 May 09:11
Help: rewrite intro of add_custom_target
Joachim Wuttke (82c64ece) at 05 May 03:17
Help: for message(FATAL_ERROR), document nonzero exit code
ok, done in 82c64ece
Joachim Wuttke (b7c90334) at 05 May 03:15
Help: from command:if, link to environment variables
... and 2 more commits
ok, done in 9efc9084
Joachim Wuttke (099f99b7) at 04 May 14:05
Help: from command:if, link to environment variables
... and 2 more commits
ok, done in 099f99b7ok, done in
Sorry, remnant from an intermediary version. Reverted in 7443908b
ok, done in 7443908b
ok, done in 7443908b
Ok, done.
Question though: Why not fully document the current behavior, and thereby define it as a feature?
Joachim Wuttke (cb7408e8) at 04 May 13:55
Help: for message(FATAL_ERROR), document nonzero exit code
In particular, hint to commands cmake -E environment
and cmake -E env
. Finding these two commands used to be very difficult.