[cmake-developers] Error handling in dashboard scripts

[Kyle Edwards]

Hi all,

I'm working on a set of build scripts that use CMake and CTest, and I'm 
trying to figure out the best way to handle failures in CTest (I'm using 
a dashboard script internally.) If the configure or build step fails, I 
want the failure to be reported to CDash with ctest_submit(), but I also 
want CTest to exit with an error code so that the calling process can 
detect a failure.

The documentation for ctest_configure(), ctest_build(), and 
ctest_submit() isn't completely clear on what happens if one of these 
steps fails. Let's say I have the following dashboard script (this is 
pseudocode, arguments have been deliberately omitted for brevity, this 
example won't work):

ctest_start()
ctest_configure()
ctest_build()
ctest_test()
ctest_submit()

What happens if ctest_configure() fails (for example, because CMake 
failed to find a needed library)? Does the entire script stop right 
there? Or does it continue and try to execute ctest_build() anyway? Does 
ctest_build() silently do nothing because the configure step failed? 
Looking through the documentation for ctest_configure() and 
ctest_build(), I see some information on the RETURN_VALUE and 
CAPTURE_CMAKE_ERROR arguments, but it's not clear what happens if these 
aren't used.

If someone could clarify for me what's supposed to happen here, and what 
the recommended best practices are for making sure that ctest_submit() 
still gets called in the event of a failure, I will gladly submit a 
documentation patch with this information. I'm guessing it involves 
using the RETURN_VALUE and CAPTURE_CMAKE_ERROR arguments, but the 
documentation doesn't state this.

Kyle