Comment 4 for bug 931816

OK, I've completed #2 and #3.

There's a new macro, which needs some better documentation once we understand exactly what the whole Java story is:

# Inform Zorba of a .jar file that should be made available on the CLASSPATH
# of the JVM, should the JVM be started. QQQ more doc needed
#
# Args: FILE - path to file (must be absolute)
#       EXTERNAL - (optional) FILE specifies a path that should be added
#              to CLASSPATH as-is
#       TEST_ONLY - (optional) Jar file is for testcases only and should not
#              be installed

MACRO (DECLARE_ZORBA_JAR)
  ....

There's also a test case in test/rbkt/modules/java. For the time being this doesn't do anything module-ish; it just creates a .jar file and uses DECLARE_ZORBA_JAR() on it. Also note that the test case depends on CMake 2.8.6, which has significantly improved support for Java.

DECLARE_ZORBA_JAR(FILE ..../foo.jar) will put foo.jar into the directory "jars/" on Zorba's library path (ie, LIB_PATH/jars in your build directory, or lib/zorba/core/2.1.0/jars (Zorba core module) or lib/zorba/jars (non-core module) in your installed Zorba).

DECLARE_ZORBA_JAR(FILE ..../foo.jar EXTERNAL) will cause a file called <project>-jars.txt to be created in the same "jars/" directories as above, with the full path to foo.jar listed in it. (Multiple external jars for the same project will be listed on separate lines in that file.)

The upshot is that when Zorba needs to create a classpath for the JVM, all it needs to do is:

1. Step through each directory on the Library Path until it finds a "jars" directory; call this JARS_DIR.
2. Add each .jar file in JARS_DIR to the classpath.
3. For each -jars.txt file in JARS_DIR, add each line of the file to the classpath.