Help: Document file(DIFFERENT)

It has been around since CMake 2.6.3 for generated install scripts but
was never documented.  Added a test for the result too, since nothing
checked it before.

Fixes: #28154

Help/command/file.rst

@@ -28,6 +28,7 @@ Synopsis
     file(`STRINGS`_ <filename> <out-var> [...])
     file(`\<HASH\>`_ <filename> <out-var>)
     file(`TIMESTAMP`_ <filename> <out-var> [...])
+    file(`DIFFERENT`_ <out-var> FILES <file1> <file2>)
 
   `Writing`_
     file({`WRITE`_ | `APPEND`_} <filename> <content>...)
@@ -160,6 +161,16 @@ Reading
   See the :command:`string(TIMESTAMP)` command for documentation of
   the ``<format>`` and ``UTC`` options.
 
+.. signature::
+  file(DIFFERENT <variable> FILES <file1> <file2>)
+
+  Compare the contents of ``<file1>`` and ``<file2>`` byte for byte and
+  store true in ``<variable>`` if they differ, or false if they are the
+  same.  If either file does not exist, or an error occurs while comparing
+  the files, the files are considered different.  Relative paths are
+  evaluated with respect to the current working directory rather than the
+  current source directory, so absolute paths are recommended.
+
 Writing
 ^^^^^^^
 

Tests/RunCMake/file/DIFFERENT.cmake

@@ -0,0 +1,24 @@
+set(a "${CMAKE_CURRENT_BINARY_DIR}/a.txt")
+set(b "${CMAKE_CURRENT_BINARY_DIR}/b.txt")
+set(c "${CMAKE_CURRENT_BINARY_DIR}/c.txt")
+set(d "${CMAKE_CURRENT_BINARY_DIR}/d.txt")
+set(missing "${CMAKE_CURRENT_BINARY_DIR}/missing.txt")
+file(CONFIGURE OUTPUT "${a}" CONTENT "same\n" NEWLINE_STYLE LF)
+file(CONFIGURE OUTPUT "${b}" CONTENT "same\n" NEWLINE_STYLE LF)
+file(CONFIGURE OUTPUT "${c}" CONTENT "same\n" NEWLINE_STYLE CRLF)
+file(CONFIGURE OUTPUT "${d}" CONTENT "diff\n" NEWLINE_STYLE LF)
+file(REMOVE "${missing}")
+
+file(DIFFERENT result FILES "${a}" "${b}")
+if(result)
+  message(SEND_ERROR "Identical files reported as different")
+endif()
+
+foreach(pair IN ITEMS "a;c" "a;d" "a;missing" "missing;a" "missing;missing")
+  list(GET pair 0 lhs)
+  list(GET pair 1 rhs)
+  file(DIFFERENT result FILES "${${lhs}}" "${${rhs}}")
+  if(NOT result)
+    message(SEND_ERROR "Files ${lhs} and ${rhs} reported as same")
+  endif()
+endforeach()

Tests/RunCMake/file/RunCMakeTest.cmake

@@ -42,6 +42,8 @@ run_cmake(TIMESTAMP)
 
 run_cmake(REMOVE-empty)
 
+run_cmake_script(DIFFERENT)
+
 run_cmake_script(COPY_FILE-file-replace)
 run_cmake_script(COPY_FILE-dir-to-file-capture)
 run_cmake_script(COPY_FILE-dir-to-file-fail)