Merge commit 'upstream/1.2.0.d20091224'

1 files changed, 224 insertions, 0 deletions

diff --git a/src/engine/SCons/Tool/javac.xml b/src/engine/SCons/Tool/javac.xml
new file mode 100644
index 0000000..a55e514
--- /dev/null
+++ b/src/engine/SCons/Tool/javac.xml
@@ -0,0 +1,224 @@
+<!--
+Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The SCons Foundation
+
+This file is processed by the bin/SConsDoc.py module.
+See its __doc__ string for a discussion of the format.
+-->
+<tool name="javac">
+<summary>
+Sets construction variables for the &javac; compiler.
+</summary>
+<sets>
+JAVAC
+JAVACFLAGS
+JAVACCOM
+JAVACLASSSUFFIX
+JAVASUFFIX
+JAVABOOTCLASSPATH
+JAVACLASSPATH
+JAVASOURCEPATH
+</sets>
+<uses>
+JAVACCOMSTR
+</uses>
+</tool>
+
+<builder name="Java">
+<summary>
+Builds one or more Java class files.
+The sources may be any combination of explicit
+<filename>.java</filename> files,
+or directory trees which will be scanned
+for <filename>.java</filename> files.
+
+SCons will parse each source <filename>.java</filename> file
+to find the classes
+(including inner classes)
+defined within that file,
+and from that figure out the
+target <filename>.class</filename> files that will be created.
+The class files will be placed underneath
+the specified target directory.
+
+SCons will also search each Java file
+for the Java package name,
+which it assumes can be found on a line
+beginning with the string
+<literal>package</literal>
+in the first column;
+the resulting <filename>.class</filename> files
+will be placed in a directory reflecting
+the specified package name.
+For example,
+the file
+<filename>Foo.java</filename>
+defining a single public
+<classname>Foo</classname>
+class and
+containing a package name of
+<classname>sub.dir</classname>
+will generate a corresponding
+<filename>sub/dir/Foo.class</filename>
+class file.
+
+Examples:
+
+<example>
+env.Java(target = 'classes', source = 'src')
+env.Java(target = 'classes', source = ['src1', 'src2'])
+env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
+</example>
+
+Java source files can use the native encoding for the underlying OS.
+Since SCons compiles in simple ASCII mode by default,
+the compiler will generate warnings about unmappable characters,
+which may lead to errors as the file is processed further.
+In this case, the user must specify the <literal>LANG</literal>
+environment variable to tell the compiler what encoding is used.
+For portibility, it's best if the encoding is hard-coded
+so that the compile will work if it is done on a system
+with a different encoding.
+
+<example>
+env = Environment()
+env['ENV']['LANG'] = 'en_GB.UTF-8'
+</example>
+</summary>
+</builder>
+
+<cvar name="JAVABOOTCLASSPATH">
+<summary>
+Specifies the list of directories that
+will be added to the
+&javac; command line
+via the <option>-bootclasspath</option> option.
+The individual directory names will be
+separated by the operating system's path separate character
+(<filename>:</filename> on UNIX/Linux/POSIX,
+<filename>;</filename> on Windows).
+</summary>
+</cvar>
+
+<cvar name="JAVAC">
+<summary>
+The Java compiler.
+</summary>
+</cvar>
+
+<cvar name="JAVACCOM">
+<summary>
+The command line used to compile a directory tree containing
+Java source files to
+corresponding Java class files.
+Any options specified in the &cv-link-JAVACFLAGS; construction variable
+are included on this command line.
+</summary>
+</cvar>
+
+<cvar name="JAVACCOMSTR">
+<summary>
+The string displayed when compiling
+a directory tree of Java source files to
+corresponding Java class files.
+If this is not set, then &cv-link-JAVACCOM; (the command line) is displayed.
+
+<example>
+env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
+</example>
+</summary>
+</cvar>
+
+<cvar name="JAVACFLAGS">
+<summary>
+General options that are passed to the Java compiler.
+</summary>
+</cvar>
+
+<cvar name="JAVACLASSDIR">
+<summary>
+The directory in which Java class files may be found.
+This is stripped from the beginning of any Java .class
+file names supplied to the
+<literal>JavaH</literal>
+builder.
+</summary>
+</cvar>
+
+<cvar name="JAVACLASSPATH">
+<summary>
+Specifies the list of directories that
+will be searched for Java
+<filename>.class</filename> file.
+The directories in this list will be added to the
+&javac; and &javah; command lines
+via the <option>-classpath</option> option.
+The individual directory names will be
+separated by the operating system's path separate character
+(<filename>:</filename> on UNIX/Linux/POSIX,
+<filename>;</filename> on Windows).
+
+Note that this currently just adds the specified
+directory via the <option>-classpath</option> option.
+&SCons; does not currently search the
+&cv-JAVACLASSPATH; directories for dependency
+<filename>.class</filename> files.
+</summary>
+</cvar>
+
+<cvar name="JAVACLASSSUFFIX">
+<summary>
+The suffix for Java class files;
+<filename>.class</filename>
+by default.
+</summary>
+</cvar>
+
+<cvar name="JAVASOURCEPATH">
+<summary>
+Specifies the list of directories that
+will be searched for input
+<filename>.java</filename> file.
+The directories in this list will be added to the
+&javac; command line
+via the <option>-sourcepath</option> option.
+The individual directory names will be
+separated by the operating system's path separate character
+(<filename>:</filename> on UNIX/Linux/POSIX,
+<filename>;</filename> on Windows).
+
+Note that this currently just adds the specified
+directory via the <option>-sourcepath</option> option.
+&SCons; does not currently search the
+&cv-JAVASOURCEPATH; directories for dependency
+<filename>.java</filename> files.
+</summary>
+</cvar>
+
+<cvar name="JAVASUFFIX">
+<summary>
+The suffix for Java files;
+<filename>.java</filename>
+by default.
+</summary>
+</cvar>
+
+<cvar name="JAVAVERSION">
+<summary>
+Specifies the Java version being used by the &b-Java; builder.
+This is <emphasis>not</emphasis> currently used to select one
+version of the Java compiler vs. another.
+Instead, you should set this to specify the version of Java
+supported by your &javac; compiler.
+The default is <literal>1.4</literal>.
+
+This is sometimes necessary because
+Java 1.5 changed the file names that are created
+for nested anonymous inner classes,
+which can cause a mismatch with the files
+that &SCons; expects will be generated by the &javac; compiler.
+Setting &cv-JAVAVERSION; to <literal>1.5</literal>
+(or <literal>1.6</literal>, as appropriate)
+can make &SCons; realize that a Java 1.5 or 1.6
+build is actually up to date.
+</summary>
+</cvar>