UseJava.cmake: document add_jar compat shim

Document the logic that parses for backward compatibility the old
variables that were used to control add_jar prior to named argument
support. In particular, document that the reason this logic exists is
for backward compatibility, and that new features do not need to add to
it.

1 files changed, 7 insertions, 0 deletions

diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake
index 9c23127..0242b24 100644
--- a/Modules/UseJava.cmake
+++ b/Modules/UseJava.cmake
@@ -221,6 +221,13 @@ set(_JAVA_SYMLINK_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/UseJavaSymlinks.cmake)
 
 function(add_jar _TARGET_NAME)
 
+    # In CMake < 2.8.12, add_jar used variables which were set prior to calling
+    # add_jar for customizing the behavior of add_jar. In order to be backwards
+    # compatible, check if any of those variables are set, and use them to
+    # initialize values of the named arguments. (Giving the corresponding named
+    # argument will override the value set here.)
+    #
+    # New features should use named arguments only.
     if(DEFINED CMAKE_JAVA_TARGET_VERSION)
         set(_add_jar_VERSION "${CMAKE_JAVA_TARGET_VERSION}")
     endif()