<?xml version="1.0"?>
<!--
SPDX-License-Identifier: MIT

Copyright The SCons Foundation

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->

<!DOCTYPE sconsdoc [
        <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
        %scons;
        <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
        %builders-mod;
        <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
        %functions-mod;
        <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
        %tools-mod;
        <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
        %variables-mod;
        ]>

<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

    <tool name="javac">
        <summary>
            <para>
                Sets construction variables for the &javac; compiler.
            </para>
        </summary>
        <sets>
            <item>JAVAC</item>
            <item>JAVACFLAGS</item>
            <item>JAVACCOM</item>
            <item>JAVACLASSSUFFIX</item>
            <item>JAVAINCLUDES</item>
            <item>JAVASUFFIX</item>
            <item>JAVABOOTCLASSPATH</item>
            <item>JAVACLASSPATH</item>
            <item>JAVASOURCEPATH</item>
        </sets>
        <uses>
            <item>JAVACCOMSTR</item>
        </uses>
    </tool>

    <builder name="Java">
        <summary>
            <para>
                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.
            </para>

            <para>
                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.
            </para>

            <para>
                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.
            </para>

            <para>
                Examples:
            </para>

            <example_commands>
env.Java(target='classes', source='src')
env.Java(target='classes', source=['src1', 'src2'])
env.Java(target='classes', source=['File1.java', 'File2.java'])
            </example_commands>

            <para>
                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.
            </para>

            <example_commands>
env = Environment()
env['ENV']['LANG'] = 'en_GB.UTF-8'
            </example_commands>
        </summary>
    </builder>

    <cvar name="JAVABOOTCLASSPATH">
        <summary>
            <para>
                Specifies the location of the bootstrap class files.
                Can be specified as a string or Node object,
                or as a list of strings or Node objects.
            </para>
            <para>
                The value will be added to the JDK command lines
                via the <option>-bootclasspath</option> option,
                which requires a system-specific search path separator.
                This will be supplied by &SCons; as needed when it
                constructs the command line if &cv-JAVABOOTCLASSPATH; is
                provided in list form.
                If &cv-JAVABOOTCLASSPATH; is a single string containing
                search path separator characters
                (<literal>:</literal> for POSIX systems or
                <literal>;</literal> for Windows), it will not be modified;
                and so is inherently system-specific;
                to supply the path in a system-independent manner,
                give &cv-JAVABOOTCLASSPATH; as a list of paths instead.
            </para>
            <note>
                <para>
                    Can only be used when compiling for releases prior to JDK 9.
                </para>
            </note>
        </summary>
    </cvar>

    <cvar name="JAVAPROCESSORPATH">
        <summary>
            <para>
                Specifies the location of the annotation processor class files.
                Can be specified as a string or Node object,
                or as a list of strings or Node objects.
            </para>
            <para>
                The value will be added to the JDK command lines
                via the <option>-processorpath</option> option,
                which requires a system-specific search path separator.
                This will be supplied by &SCons; as needed when it
                constructs the command line if &cv-JAVAPROCESSORPATH; is
                provided in list form.
                If &cv-JAVAPROCESSORPATH; is a single string containing
                search path separator characters
                (<literal>:</literal> for POSIX systems or
                <literal>;</literal> for Windows), it will not be modified;
                and so is inherently system-specific;
                to supply the path in a system-independent manner,
                give &cv-JAVAPROCESSORPATH; as a list of paths instead.
            </para>
            <para>
                <emphasis>New in version 4.5.0</emphasis>
            </para>
        </summary>
    </cvar>

    <cvar name="JAVAINCLUDES">
        <summary>
            <para>
                Include path for Java header files
                (such as <filename>jni.h</filename>).
            </para>
        </summary>
    </cvar>

    <cvar name="JAVAC">
        <summary>
            <para>
                The Java compiler.
            </para>
        </summary>
    </cvar>

    <cvar name="JAVACCOM">
        <summary>
            <para>
                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.
            </para>
        </summary>
    </cvar>

    <cvar name="JAVACCOMSTR">
        <summary>
            <para>
                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.
            </para>

            <example_commands>
env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
            </example_commands>
        </summary>
    </cvar>

    <cvar name="JAVACFLAGS">
        <summary>
            <para>
                General options that are passed to the Java compiler.
            </para>
        </summary>
    </cvar>

    <cvar name="JAVACLASSDIR">
        <summary>
            <para>
                The directory in which Java class files may be found.
                This is stripped from the beginning of any Java
                <filename>.class</filename>
                file names supplied to the &b-link-JavaH; builder.
            </para>
        </summary>
    </cvar>

    <cvar name="JAVACLASSPATH">
        <summary>
            <para>
                Specifies the class search path for the JDK tools.
                Can be specified as a string or Node object,
                or as a list of strings or Node objects.
                Class path entries may be directory names to search
                for class files or packages, pathnames to archives
                (<filename>.jar</filename> or <filename>.zip</filename>)
                containing classes, or paths ending in a "base name wildcard"
                character (<literal>*</literal>), which matches files
                in that directory with a <filename>.jar</filename> suffix.
                See the Java documentation for more details.
            </para>
            <para>
                The value will be added to the JDK command lines
                via the <option>-classpath</option> option,
                which requires a system-specific search path separator.
                This will be supplied by &SCons; as needed when it
                constructs the command line if &cv-JAVACLASSPATH; is
                provided in list form.
                If &cv-JAVACLASSPATH; is a single string containing
                search path separator characters
                (<literal>:</literal> for POSIX systems or
                <literal>;</literal> for Windows), 
                it will be split on the separator into a list of individual
                paths for dependency scanning purposes.
                It will not be modified for JDK command-line usage,
                so such a string is inherently system-specific;
                to supply the path in a system-independent manner,
                give &cv-JAVACLASSPATH; as a list of paths instead.
            </para>
            <note>
              <para>
                &SCons; <emphasis role="bold">always</emphasis>
                supplies a <option>-sourcepath</option> 
                when invoking the Java compiler &javac;,
                regardless of the setting of &cv-link-JAVASOURCEPATH;,
                as it passes the path(s) to the source(s) supplied
                in the call to the &b-link-Java; builder via
                <option>-sourcepath</option> .
                From the documentation of the standard Java toolkit for &javac;:
                <quote>If not compiling code for modules, if the
                <option>--source-path</option> or <option>-sourcepath</option>
                option is not specified, then the user class path is also
                searched for source files.</quote>
                Since <option>-sourcepath</option> is always supplied,
                &javac; will not use the contents of the value of
                &cv-JAVACLASSPATH; when searching for sources.
              </para>
            </note>
        </summary>
    </cvar>

    <cvar name="JAVACLASSSUFFIX">
        <summary>
            <para>
                The suffix for Java class files;
                <filename>.class</filename>
                by default.
            </para>
        </summary>
    </cvar>

    <cvar name="JAVASOURCEPATH">
        <summary>
            <para>
                Specifies the list of directories that
                will be searched for input (source)
                <filename>.java</filename> files.
                Can be specified as a string or Node object,
                or as a list of strings or Node objects.
            </para>
            <para>
                The value will be added to the JDK command lines
                via the <option>-sourcepath</option> option,
                which requires a system-specific search path separator,
                This will be supplied by &SCons; as needed when it
                constructs the command line if &cv-JAVASOURCEPATH; is
                provided in list form.
                If &cv-JAVASOURCEPATH; is a single string containing
                search path separator characters
                (<literal>:</literal> for POSIX systems or
                <literal>;</literal> for Windows), it will not be modified,
                and so is inherently system-specific;
                to supply the path in a system-independent manner,
                give &cv-JAVASOURCEPATH; as a list of paths instead.
            </para>
            <para>
                Note that the specified directories are only added to
                the command line via the <option>-sourcepath</option> option.
                &SCons; does not currently search the
                &cv-JAVASOURCEPATH; directories for dependent
                <filename>.java</filename>
                files.
            </para>
        </summary>
    </cvar>

    <cvar name="JAVASUFFIX">
        <summary>
            <para>
                The suffix for Java files;
                <filename>.java</filename>
                by default.
            </para>
        </summary>
    </cvar>

    <cvar name="JAVAVERSION">
        <summary>
            <para>
                Specifies the Java version being used by the &b-link-Java;
                builder. Set this to specify the version of Java targeted
                by the &javac; compiler.
                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 a version greater than
                <literal>1.4</literal> makes &SCons; realize that a build
                with such a compiler is actually up to date.
                The default is <literal>1.4</literal>.
            </para>
            <para>
                While this is <emphasis>not</emphasis> primarily intended for
                selecting one version of the Java compiler vs. another,
                it does have that effect on the Windows platform. A
                more precise approach is to set &cv-link-JAVAC; (and related
                &consvars; for related utilities) to the path to the specific
                Java compiler you want, if that is not the default compiler.
                On non-Windows platforms, the
                <systemitem>alternatives</systemitem> system may provide a
                way to adjust the default Java compiler without
                having to specify explicit paths.
            </para>
        </summary>
    </cvar>

</sconsdoc>
