Branch for documentation changes.

1 files changed, 540 insertions, 0 deletions

diff --git a/doc/user/java.in b/doc/user/java.in
new file mode 100644
index 0000000..6b22de8
--- /dev/null
+++ b/doc/user/java.in
@@ -0,0 +1,540 @@
+<!--
+
+  __COPYRIGHT__
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+  <para>
+
+  So far, we've been using examples of
+  building C and C++ programs
+  to demonstrate the features of &SCons;.
+  &SCons; also supports building Java programs,
+  but Java builds are handled slightly differently,
+  which reflects the ways in which
+  the Java compiler and tools
+  build programs differently than
+  other languages' tool chains.
+
+  </para>
+
+  <section>
+  <title>Building Java Class Files:  the &Java; Builder</title>
+
+    <para>
+
+    The basic activity when programming in Java,
+    of course, is to take one or more <filename>.java</filename> files
+    containing Java source code
+    and to call the Java compiler
+    to turn them into one or more
+    <filename>.class</filename> files.
+    In &SCons;, you do this
+    by giving the &Java; Builder
+    a target directory in which
+    to put the <filename>.class</filename> files,
+    and a source directory that contains
+    the <filename>.java</filename> files:
+
+    </para>
+
+    <scons_example name="java">
+      <file name="SConstruct" printme="1">
+      Java('classes', 'src')
+      </file>
+      <file name="src/Example1.java">
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="src/Example2.java">
+      public class Example2
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="src/Example3.java">
+      public class Example3
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    If the <filename>src</filename> directory contains
+    three <filename>.java</filename> source files,
+    then running &SCons; might look like this:
+
+    </para>
+
+    <scons_output example="java">
+      <command>scons -Q</command>
+    </scons_output>
+
+    <para>
+
+    &SCons; will actually search the <filename>src</filename>
+    directory tree for all of the <filename>.java</filename> files.
+    The Java compiler will then create the
+    necessary class files in the <filename>classes</filename> subdirectory,
+    based on the class names found in the <filename>.java</filename> files.
+
+    </para>
+
+  </section>
+
+  <section>
+  <title>How &SCons; Handles Java Dependencies</title>
+
+    <scons_output example="java">
+      <command>scons -Q</command>
+      <command>scons -Q classes</command>
+    </scons_output>
+
+  </section>
+
+  <section>
+  <title>Building Java Archive (<filename>.jar</filename>) Files:  the &Jar; Builder</title>
+
+    <para>
+
+    After building the class files,
+    it's common to collect them into
+    a Java archive (<filename>.jar</filename>) file,
+    which you do by calling the &Jar; Builder method.
+    If you want to just collect all of the
+    class files within a subdirectory,
+    you can just specify that subdirectory
+    as the &Jar; source:
+
+    </para>
+
+    <scons_example name="jar1">
+      <file name="SConstruct" printme="1">
+      Java(target = 'classes', source = 'src')
+      Jar(target = 'test.jar', source = 'classes')
+      </file>
+      <file name="src/Example1.java">
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="src/Example2.java">
+      public class Example2
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="src/Example3.java">
+      public class Example3
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    &SCons; will then pass that directory
+    to the &jar; command,
+    which will collect all of the underlying
+    <filename>.class</filename> files:
+
+    </para>
+
+    <scons_output example="jar1">
+      <command>scons -Q</command>
+    </scons_output>
+
+    <para>
+
+    If you want to keep all of the
+    <filename>.class</filename> files
+    for multiple programs in one location,
+    and only archive some of them in
+    each <filename>.jar</filename> file,
+    you can pass the &Jar; builder a
+    list of files as its source.
+    It's extremely simple to create multiple
+    <filename>.jar</filename> files this way,
+    using the lists of target class files created
+    by calls to the &Java; builder
+    as sources to the various &Jar; calls:
+
+    </para>
+
+    <scons_example name="jar2">
+      <file name="SConstruct" printme="1">
+      prog1_class_files = Java(target = 'classes', source = 'prog1')
+      prog2_class_files = Java(target = 'classes', source = 'prog2')
+      Jar(target = 'prog1.jar', source = prog1_class_files)
+      Jar(target = 'prog2.jar', source = prog2_class_files)
+      </file>
+      <file name="prog1/Example1.java">
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="prog1/Example2.java">
+      public class Example2
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="prog2/Example3.java">
+      public class Example3
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+      <file name="prog2/Example4.java">
+      public class Example4
+      {
+        public static void main(String[] args)
+        {
+          System.out.println("Hello Java world!\n");
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    This will then create
+    <filename>prog1.jar</filename>
+    and <filename>prog2.jar</filename>
+    next to the subdirectories
+    that contain their <filename>.java</filename> files:
+
+    </para>
+
+    <scons_output example="jar2">
+      <command>scons -Q</command>
+    </scons_output>
+
+  </section>
+
+  <section>
+  <title>Building C Header and Stub Files:  the &JavaH; Builder</title>
+
+    <para>
+
+    You can generate C header and source files
+    for implementing native methods,
+    by using the &JavaH; Builder.
+    There are several ways of using the &JavaH Builder.
+    One typical invocation might look like:
+
+    </para>
+
+    <scons_example name="javah">
+      <file name="SConstruct" printme="1">
+      classes = Java(target = 'classes', source = 'src/pkg/sub')
+      JavaH(target = 'native', source = classes)
+      </file>
+      <file name="src/pkg/sub/Example1.java">
+      package pkg.sub;
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+      <file name="src/pkg/sub/Example2.java">
+      package pkg.sub;
+      public class Example2
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+      <file name="src/pkg/sub/Example3.java">
+      package pkg.sub;
+      public class Example3
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    The source is a list of class files generated by the
+    call to the &Java; Builder,
+    and the target is the output directory in
+    which we want the C header files placed.
+    The target
+    gets converted into the <option>-d</option>
+    when &SCons; runs &javah;:
+
+    </para>
+
+    <scons_output example="javah">
+      <command>scons -Q</command>
+    </scons_output>
+
+    <para>
+
+    In this case,
+    the call to &javah;
+    will generate the header files
+    <filename>native/pkg_sub_Example1.h</filename>,
+    <filename>native/pkg_sub_Example2.h</filename>
+    and
+    <filename>native/pkg_sub_Example3.h</filename>.
+    Notice that &SCons; remembered that the class
+    files were generated with a target directory of
+    <filename>classes</filename>,
+    and that it then specified that target directory
+    as the <option>-classpath</option> option
+    to the call to &javah;.
+
+    </para>
+
+    <para>
+
+    Although it's more convenient to use
+    the list of class files returned by
+    the &Java; Builder
+    as the source of a call to the &JavaH; Builder,
+    you <emphasis>can</emphasis>
+    specify the list of class files
+    by hand, if you prefer.
+    If you do,
+    you need to set the
+    &JAVACLASSDIR; construction variable
+    when calling &JavaH;:
+
+    </para>
+
+    <scons_example name="JAVACLASSDIR">
+      <file name="SConstruct" printme="1">
+      Java(target = 'classes', source = 'src/pkg/sub')
+      class_file_list = ['classes/pkg/sub/Example1.class',
+                         'classes/pkg/sub/Example2.class',
+                         'classes/pkg/sub/Example3.class']
+      JavaH(target = 'native', source = class_file_list, JAVACLASSDIR = 'classes')
+      </file>
+      <file name="src/pkg/sub/Example1.java">
+      package pkg.sub;
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+      <file name="src/pkg/sub/Example2.java">
+      package pkg.sub;
+      public class Example2
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+      <file name="src/pkg/sub/Example3.java">
+      package pkg.sub;
+      public class Example3
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    The &JAVACLASSDIR; value then
+    gets converted into the <option>-classpath</option>
+    when &SCons; runs &javah;:
+
+    </para>
+
+    <scons_output example="JAVACLASSDIR">
+      <command>scons -Q</command>
+    </scons_output>
+
+    <para>
+
+    Lastly, if you don't want a separate header file
+    generated for each source file,
+    you can specify an explicit File Node
+    as the target of the &JavaH; Builder:
+
+    </para>
+
+    <scons_example name="javah_file">
+      <file name="SConstruct" printme="1">
+      classes = Java(target = 'classes', source = 'src/pkg/sub')
+      JavaH(target = File('native.h'), source = classes)
+      </file>
+      <file name="src/pkg/sub/Example1.java">
+      package pkg.sub;
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+      <file name="src/pkg/sub/Example2.java">
+      package pkg.sub;
+      public class Example2
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+      <file name="src/pkg/sub/Example3.java">
+      package pkg.sub;
+      public class Example3
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    Because &SCons; assumes by default
+    that the target of the &JavaH; builder is a directory,
+    you need to use the &File; function
+    to make sure that &SCons; doesn't
+    create a directory named <filename>native.h</filename>.
+    When a file is used, though,
+    &SCons; correctly converts the file name
+    into the &javah; <option>-o</option> option:
+
+    </para>
+
+    <scons_output example="javah_file">
+      <command>scons -Q</command>
+    </scons_output>
+
+  </section>
+
+  <section>
+  <title>Building RMI Stub and Skeleton Class Files:  the &RMIC; Builder</title>
+
+    <para>
+
+    You can generate Remote Method Invocation stubs
+    by using the &RMIC; Builder.
+    The source is a list of directories,
+    typically returned by a call to the &Java; Builder,
+    and the target is an output directory
+    where the <filename>_Stub.class</filename>
+    and <filename>_Skel.class</filename> files will
+    be placed:
+
+    </para>
+
+    <scons_example name="RMIC">
+      <file name="SConstruct" printme="1">
+      classes = Java(target = 'classes', source = 'src/pkg/sub')
+      RMIC(target = 'outdir', source = classes)
+      </file>
+      <file name="src/pkg/sub/Example1.java">
+      package pkg.sub;
+      public class Example1
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+      <file name="src/pkg/sub/Example2.java">
+      package pkg.sub;
+      public class Example2
+      {
+        public static void main(String[] args)
+        {
+        }
+      }
+      </file>
+    </scons_example>
+
+    <para>
+
+    As it did with the &JavaH; Builder,
+    &SCons; remembers the class directory
+    and passes it as the <option>-classpath</option> option
+    to &rmic:
+
+    </para>
+
+    <scons_output example="RMIC">
+      <command>scons -Q</command>
+    </scons_output>
+
+    <para>
+
+    This example would generate the files
+    <filename>outdir/pkg/sub/Example1_Skel.class</filename>,
+    <filename>outdir/pkg/sub/Example1_Stub.class</filename>,
+    <filename>outdir/pkg/sub/Example2_Skel.class</filename> and
+    <filename>outdir/pkg/sub/Example2_Stub.class</filename>.
+
+    </para>
+
+  </section>