Behavior of execute_process not clear from documentation.
There are two obvious expected behaviors of execute_process which are both violated. The error messages are obtuse and the documentation fails to point out these things clearly, which can cause much time waste:
Expectation 1: it can execute multiple commands in sequence.
This is violated but the reason is not clear, nor is the actual behavior. The call supports multiple COMMAND arguments, yet fails to execute them in sequence, begging the question: why are there multiple COMMAND arguments allowed and how are they dispatched? Randomly? In parallel? The use case set for parallel command seems pretty small compared to the far-more-often-useful ability to execute commands in sequence. It's not even clear that parallel execution is how the call works from the documentation but when I tried to do a sequence of git command using it, it failed miserably and seemed to be due to out-of-order execution. There is a small blurb on the execute_process doc page: "If a sequential execution of multiple commands is required, use multiple execute_process() calls with a single COMMAND argument." But this is not clear and no accompanying reasoning is attached like "Each COMMAND argument will spin off a separate process in parallel, so if the 2nd depends on the 1st, this will fail, and so forth." Such an addendum would have saved me debugging time.
I also don't understand why this isn't provided. It's extremely cumbersome to manage 5 or 6 execute_process calls all having to capture output and results separately, etc.
One might suggest placing the actual logic into a bash script file and execute_process'ing that but that's a no-go in an aggressively cross-platform build system.
Expectation 2: A command string can include spaces in their "natural" interpretation.
Command arguments will be treated as such as indicated by spaces in the (single) COMMAND string. This is violated, requiring multiple strings to the COMMAND argument like COMMAND "{cmd}" "
{arg1}" "{arg2}" instead of a string like "
{cmd} ${arg1} ${arg2}". This is not clearly mentioned in the documentation for the COMMAND argument and requires googling forums to discover. I understand this limitation but I think the documentation should explain it too.
Expectation 3: RESULT_VARIABLE should only hold integer return codes and not be used for error communication from CMake itself.
The variable specified to the GIT_RESULT argument should only ever contain an integer from the process itself, if anything at all, and not a STRING error message from CMAKE itself when it fails to parse the command and find the process properly (perhaps due to expectation #2, which only compounds the confusion to a new user of execute_process). Furthermore, the message is "The system cannot find the file specified" stored into RESULT_VARIABLE (not OUTPUT_VARIABLE or ERROR_VARIABLE). THis includes no clues as to the source of the error (CMake's execute_process), and is so generic that it's far more likely to be interpreted as coming from the process itself (which in reality was never started). This is confusing and anti-documenting and it leads the user to believe that RESULT is more like OUTPUT or something and to think the process is running but complaining about something related to files not found. The error message should be improved to make it clear that execute_process has failed to find and run whatever was specified by COMMAND, and should furthermore probably not be stuffed into an integer-valued RESULT_VARIABLE in particular.