Merge commit 'upstream/1.2.0.d20091224'

1 files changed, 433 insertions, 0 deletions

diff --git a/doc/user/java.xml b/doc/user/java.xml
new file mode 100644
index 0000000..8198b65
--- /dev/null
+++ b/doc/user/java.xml
@@ -0,0 +1,433 @@
+<!--
+
+  Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+  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 &b-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 &b-link-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>
+
+    <programlisting>
+      Java('classes', 'src')
+    </programlisting>
+
+    <para>
+
+    If the <filename>src</filename> directory contains
+    three <filename>.java</filename> source files,
+    then running &SCons; might look like this:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
+    </screen>
+
+    <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>
+
+    <para>
+
+    In addition to searching the source directory for
+    <filename>.java</filename> files,
+    &SCons; actually runs the <filename>.java</filename> files
+    through a stripped-down Java parser that figures out
+    what classes are defined.
+    In other words, &SCons; knows,
+    without you having to tell it,
+    what <filename>.class</filename> files
+    will be produced by the &javac; call.
+    So our one-liner example from the preceding section:
+
+    </para>
+
+    <programlisting>
+      Java('classes', 'src')
+    </programlisting>
+
+    <para>
+
+    Will not only tell you reliably
+    that the <filename>.class</filename> files
+    in the <filename>classes</filename> subdirectory 
+    are up-to-date:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
+      % <userinput>scons -Q classes</userinput>
+      scons: `classes' is up to date.
+    </screen>
+
+    <para>
+
+    But it will also remove all of the generated
+    <filename>.class</filename> files,
+    even for inner classes,
+    without you having to specify them manually.
+    For example, if our
+    <filename>Example1.java</filename>
+    and
+    <filename>Example3.java</filename>
+    files both define additional classes,
+    and the class defined in <filename>Example2.java</filename>
+    has an inner class,
+    running <userinput>scons -c</userinput>
+    will clean up all of those <filename>.class</filename> files
+    as well:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
+      % <userinput>scons -Q -c classes</userinput>
+      Removed classes/Example1.class
+      Removed classes/AdditionalClass1.class
+      Removed classes/Example2$Inner2.class
+      Removed classes/Example2.class
+      Removed classes/Example3.class
+      Removed classes/AdditionalClass3.class
+    </screen>
+
+    <para>
+
+    To ensure correct handling of <filename>.class</filename>
+    dependencies in all cases, you need to tell &SCons; which Java
+    version is being used.  This is needed because Java 1.5 changed
+    the <filename>.class</filename> file names for nested anonymous
+    inner classes.  Use the <varname>JAVAVERSION</varname> construction
+    variable to specify the version in use.  With Java 1.6, the
+    one-liner example can then be defined like this:
+
+    </para> 
+
+    <programlisting>
+      Java('classes', 'src', JAVAVERSION='1.6')
+    </programlisting>
+
+    <para>
+    See <varname>JAVAVERSION</varname> in the man page for more information.
+    </para>
+
+  </section>
+
+  <section>
+  <title>Building Java Archive (<filename>.jar</filename>) Files:  the &b-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 &b-link-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 &b-Jar; source:
+
+    </para>
+
+    <programlisting>
+      Java(target = 'classes', source = 'src')
+      Jar(target = 'test.jar', source = 'classes')
+    </programlisting>
+
+    <para>
+
+    &SCons; will then pass that directory
+    to the &jar; command,
+    which will collect all of the underlying
+    <filename>.class</filename> files:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src src/Example1.java src/Example2.java src/Example3.java
+      jar cf test.jar classes
+    </screen>
+
+    <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 &b-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 &b-link-Java; builder
+    as sources to the various &b-Jar; calls:
+
+    </para>
+
+    <programlisting>
+      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)
+    </programlisting>
+
+    <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>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath prog1 prog1/Example1.java prog1/Example2.java
+      javac -d classes -sourcepath prog2 prog2/Example3.java prog2/Example4.java
+      jar cf prog1.jar -C classes Example1.class -C classes Example2.class
+      jar cf prog2.jar -C classes Example3.class -C classes Example4.class
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Building C Header and Stub Files:  the &b-JavaH; Builder</title>
+
+    <para>
+
+    You can generate C header and source files
+    for implementing native methods,
+    by using the &b-link-JavaH; Builder.
+    There are several ways of using the &JavaH; Builder.
+    One typical invocation might look like:
+
+    </para>
+
+    <programlisting>
+      classes = Java(target = 'classes', source = 'src/pkg/sub')
+      JavaH(target = 'native', source = classes)
+    </programlisting>
+
+    <para>
+
+    The source is a list of class files generated by the
+    call to the &b-link-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>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java
+      javah -d native -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3
+    </screen>
+
+    <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 &b-Java; Builder
+    as the source of a call to the &b-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
+    &cv-link-JAVACLASSDIR; construction variable
+    when calling &b-JavaH;:
+
+    </para>
+
+    <programlisting>
+      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')
+    </programlisting>
+
+    <para>
+
+    The &cv-JAVACLASSDIR; value then
+    gets converted into the <option>-classpath</option>
+    when &SCons; runs &javah;:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java
+      javah -d native -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3
+    </screen>
+
+    <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 &b-JavaH; Builder:
+
+    </para>
+
+    <programlisting>
+      classes = Java(target = 'classes', source = 'src/pkg/sub')
+      JavaH(target = File('native.h'), source = classes)
+    </programlisting>
+
+    <para>
+
+    Because &SCons; assumes by default
+    that the target of the &b-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>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java src/pkg/sub/Example3.java
+      javah -o native.h -classpath classes pkg.sub.Example1 pkg.sub.Example2 pkg.sub.Example3
+    </screen>
+
+  </section>
+
+  <section>
+  <title>Building RMI Stub and Skeleton Class Files:  the &b-RMIC; Builder</title>
+
+    <para>
+
+    You can generate Remote Method Invocation stubs
+    by using the &b-link-RMIC; Builder.
+    The source is a list of directories,
+    typically returned by a call to the &b-link-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>
+
+    <programlisting>
+      classes = Java(target = 'classes', source = 'src/pkg/sub')
+      RMIC(target = 'outdir', source = classes)
+    </programlisting>
+
+    <para>
+
+    As it did with the &b-link-JavaH; Builder,
+    &SCons; remembers the class directory
+    and passes it as the <option>-classpath</option> option
+    to &rmic;:
+
+    </para>
+
+    <screen>
+      % <userinput>scons -Q</userinput>
+      javac -d classes -sourcepath src/pkg/sub src/pkg/sub/Example1.java src/pkg/sub/Example2.java
+      rmic -d outdir -classpath classes pkg.sub.Example1 pkg.sub.Example2
+    </screen>
+
+    <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>