Improve FILE(DOWNLOAD) and ExternalProject.

Improve FILE(DOWNLOAD ...):

- Add percent complete progress output to the FILE DOWNLOAD
  command. This progress output is off by default to
  preserve existing behavior. To turn it on, pass
  SHOW_PROGRESS as an argument.

- Add EXPECTED_MD5 argument. Verify that the downloaded
  file has the expected md5 sum after download is complete.

- Add documentation for SHOW_PROGRESS and EXPECTED_MD5.

  When the destination file exists already and has the
  expected md5 sum, then do not bother re-downloading
  the file. ("Short circuit" return.)

  Also, add a test that checks for the status output
  indicating that the short circuit behavior is actually
  occurring. Use a binary file for the test so that the
  md5 sum is guaranteed to be the same on all platforms
  regardless of "shifting text file line ending" issues.

Improve ExternalProject:

- Add argument URL_MD5.

- Add verify step that compares md5 sum of .tar.gz file
  before extracting it.

- Add md5 check to download step, too, to prevent
  unnecessary downloads.

- Emit a warning message when a file is not verified.
  Indicate that the file may be corrupt or that no
  checksum was specified.

1 files changed, 8 insertions, 2 deletions

diff --git a/Source/cmFileCommand.h b/Source/cmFileCommand.h
index c6da301..e771092 100644
--- a/Source/cmFileCommand.h
+++ b/Source/cmFileCommand.h
@@ -80,7 +80,8 @@ public:
       "  file(RELATIVE_PATH variable directory file)\n"
       "  file(TO_CMAKE_PATH path result)\n"
       "  file(TO_NATIVE_PATH path result)\n"
-      "  file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log])\n"
+      "  file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log]\n"
+      "       [EXPECTED_MD5 sum] [SHOW_PROGRESS])\n"
       "WRITE will write a message into a file called 'filename'. It "
       "overwrites the file if it already exists, and creates the file "
       "if it does not exist.\n"
@@ -152,7 +153,12 @@ public:
       "and the second element is a string value for the error. A 0 "
       "numeric error means no error in the operation. "
       "If TIMEOUT time is specified, the operation will "
-      "timeout after time seconds, time should be specified as an integer."
+      "timeout after time seconds, time should be specified as an integer. "
+      "If EXPECTED_MD5 sum is specified, the operation will verify that the "
+      "downloaded file's actual md5 sum matches the expected value. If it "
+      "does not match, the operation fails with an error. "
+      "If SHOW_PROGRESS is specified, progress information will be printed "
+      "as status messages until the operation is complete."
       "\n"
       "The file() command also provides COPY and INSTALL signatures:\n"
       "  file(<COPY|INSTALL> files... DESTINATION <dir>\n"