Introduce "generator expressions" to add_test()

This introduces a new syntax called "generator expressions" to the test
COMMAND option of the add_test(NAME) command mode.  These expressions
have a syntax like $<TARGET_FILE:mytarget> and are evaluated during
build system generation.  This syntax allows per-configuration target
output files to be referenced in test commands and arguments.

1 files changed, 23 insertions, 0 deletions

diff --git a/Source/cmAddTestCommand.h b/Source/cmAddTestCommand.h
index a971fd7..0b9ca3c 100644
--- a/Source/cmAddTestCommand.h
+++ b/Source/cmAddTestCommand.h
@@ -79,6 +79,29 @@ public:
       "of the executable created at build time.  "
       "If a CONFIGURATIONS option is given then the test will be executed "
       "only when testing under one of the named configurations."
+      "\n"
+      "Arguments after COMMAND may use \"generator expressions\" with the "
+      "syntax \"$<...>\".  "
+      "These expressions are evaluted during build system generation and "
+      "produce information specific to each generated build configuration.  "
+      "Valid expressions are:\n"
+      "  $<CONFIGURATION>          = configuration name\n"
+      "  $<TARGET_FILE:tgt>        = main file (.exe, .so.1.2, .a)\n"
+      "  $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)\n"
+      "  $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)\n"
+      "where \"tgt\" is the name of a target.  "
+      "Target file expressions produce a full path, but _DIR and _NAME "
+      "versions can produce the directory and file name components:\n"
+      "  $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>\n"
+      "  $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>\n"
+      "  $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>\n"
+      "Example usage:\n"
+      "  add_test(NAME mytest\n"
+      "           COMMAND testDriver --config $<CONFIGURATION>\n"
+      "                              --exe $<TARGET_FILE:myexe>)\n"
+      "This creates a test \"mytest\" whose command runs a testDriver "
+      "tool passing the configuration name and the full path to the "
+      "executable file produced by target \"myexe\"."
       ;
     }