Section 3.1. Compiling Code


3.1. Compiling Code

The javac task compiles Java source code. You've seen javac at work many times in this book but haven't exhausted what this task has to offer by any means. You can get an idea how extensive a task it is by its huge number of attributes, shown in Table 3-1.

Table 3-1. The javac task's attributes

Attribute

Description

Required

Default

bootclasspath

Specifies where to find any bootstrap class files.

No

 

bootclasspathref

Specifies where to find any bootstrap class files, given as a reference.

No

 

classpath

Specifies the classpath you want to use.

No

 

classpathref

Specifies the classpath you want to use, given as a reference to a path.

No

 

compiler

Specifies the compiler you want to use. If you don't set this attribute, this task will use the compiler pointed to by the build.compiler property, if set. If that property is not set, the default compiler for the current JVM is used.

No

 

debug

Specifies whether or not your code should be compiled to include debug data. Corresponds to the compiler's -g option.

No

no

debuglevel

Specifies keywords that will be added to the command line with the -g switch. Possible values are none or a comma-separated list of these keywords: lines, vars, and source. This attribute requires debug to be set to true; if it's not, this attribute is ignored.

No

 

depend

Specifies that you want to use dependency tracking if your compiler supports it.

No

 

deprecation

Specifies that you want the compiler to display deprecation information.

No

no

destdir

Specifies the destination directory for the generated class files.

No

 

encoding

Specifies the encoding of your Java files.

No

 

excludes

Specifies a list of files that you want to exclude. A comma- or space-separated list of files.

No

 

excludesfile

Specifies a file containing a list of files you want to exclude.

No

 

executable

Specifies the path to the javac executable that will be used when fork is used. Defaults to the compiler currently used by Ant.

No

 

extdirs

Specifies the location of installed extensions, if any.

No

 

failonerror

Specifies if you want the build to fail if there are compilation errors.

No

true

fork

Specifies if to execute javac in a forked process.

No

no

includeAntRuntime

Specifies whether you want to make the Ant run-time libraries accessible to the compiler.

No

yes

includeJavaRuntime

Specifies whether you want to make the default runtime Java libraries accessible to the executing JVM.

No

no

includes

Specifies a list of files that you want to include. A comma- or space-separated list of files.

No

 

includesfile

Specifies a file containing a list of files you want to include.

No

 

listfiles

Specifies whether you want to list the source files to be compiled.

No

no

memoryInitialSize

Specifies the starting size of the memory for the JVM. Applies only if javac is run externally.

No

 

memoryMaximumSize

Specifies the maximum size of memory you want to use for the JVM, if you're forking it.

No

 

nowarn

Specifies whether you want to pass the -nowarn switch to the compiler.

No

off

optimize

Specifies whether you want to compile using optimization, using the -O switch.

No

off

source

Specifies whether you want to use the -source switch. Legal values are 1.3, 1.4, and 1.5.

No

no -source argument will be used

sourcepath

Specifies the source path to use.

No

The value of the srcdir attribute (or nested src elements)

sourcepathref

Specifies the source path you want to use, given in reference form.

No

 

srcdir

Specifies where to find the Java source files you want to compile.

Yes, unless nested src elements are present

 

target

Specifies that you want to generate class files for particular Java version (e.g., 1.1 or 1.2).

No

 

tempdir

Specifies the directory where temporary files should go. Used only if the task is forked and the length of the command line arguments is over 4 K. Available since Ant 1.6.

No; default is the current working directory

 

verbose

Specifies that you want the compiler to generate verbose output.

No

no


This is where the meat is for most Java authors. This taskwhich should be one of your staplesmakes sure the source directory will be recursively scanned for Java source files to compile and compiles them. Only Java files that have no corresponding .class file or where the class file is older than the .java file will be compiled.

The javac task forms an implicit FileSet and supports all attributes of fileset (note that dir becomes srcdir) as well as the nested include, exclude and patternset elements. And because the javac task's srcdir, classpath, sourcepath, bootclasspath, and extdirs attributes are path-like structures, they can be set via nested src, classpath, sourcepath, bootclasspath and extdirs elements.

3.1.1. Compiling Source Files

Here are a few javac examples, starting with a standard example that compiles all .java files in and under the ${src} directory and stores the .class files in the ${bin} directory. In this case, the classpath includes common.jar, and we're compiling with debug information turned on:

<javac srcdir="${src}"     debug="on"     destdir="${bin}"     classpath="common.jar" />

This next example compiles .java files in and under the ${src} and ${src2} directories, storing .class files in ${bin}, including common.jar in the classpath, and turns debug information on. In this case, only files in packages/archive/** and packages/backup/** will be includedand those in packages/archive/betapackage/** will be excluded:

<javac srcdir="${src}:${src2}"     destdir="${build}"     includes="packages/archive/**,packages/backup/**"     excludes="packages/archive/betapackage/**"     classpath="common.jar"     debug="on" />

Ant only uses the names of the source and class files to find the classes that need a rebuild. It doesn't read the source codes, and so has no knowledge about nested classes. If you want to specify dependencies that Ant is having trouble with, use the Ant depend task (covered in Chapter 6) for advanced dependency checking.

One of the new aspects of Ant 1.6 is that it's OK to use 1.5, the newest version of Java, as the Java version in javac attributes as source.


3.1.1.1 Selecting which files to compile

You can make javac compile only files that you explicitly specify, as opposed to all files under the specified source directory. You do that by disabling the javac task's default searching mechanism by unsetting the sourcepath attribute and specifying the files you want to include and exclude explicitly, as here, where I'm including only .java files in the ${src} directory:

<javac sourcepath="" srcdir="${src}"     destdir="${bin}" >     <include name="*.java" /> </javac>

3.1.1.2 Forking the compiler

Forking the Java compiler makes it run in a new process, something that's often useful if you want to use another compiler or want to configure the compiler's runtime environment. When the compiler is used in unforked mode in Windows, it may lock the files in the classpath of the javac task. That means you won't be able to delete or move those files later in the build. If you need to change that, fork the compiler, using the fork attribute.

Here's an example that compiles all .java files under the ${src} directory, stores the .class files in the ${bin} directory, and forks the javac compiler into its own thread process:

<javac srcdir="${src}"     fork="yes"     destdir="${bin}" />

Here's an example showing how you can tell Ant which Java compiler you want to run after forking:

<javac srcdir="${src}"     destdir="${bin}"     fork="yes"     executable="/opt/java/jdk1.3/bin/javac"     compiler="javac1.3" />

In the early days, if you were using Ant on Windows, a new DOS window would pop up for every use of an external compiler. If you use a JDK after 1.2, this won't be a problem.


3.1.2. Setting Command-Line Options

You can explicitly specify command-line arguments for the compiler with nested compilerarg elements:

<javac srcdir="${src}"     destdir="${build}"     classpath="xyz.jar"     debug="on">     <compilerarg value="-l -a"/> </javac>

The attributes of the compilerarg element appear in Table 3-2.

Table 3-2. The compilerarg attributes

Attribute

Description

Required

compiler

Specifies the required version of the compiler you want to use; if the compiler is not of this version, the argument won't be passed to it. For possible values, see the Section 3.1.3.

No

file

Specifies the name of a file as a command-line argument.

Exactly one of value, line, file, or path.

line

Specifies a list of command-line arguments, delimited by spaces.

Exactly one of value, line, file, or path.

path

Specifies a path-like string as a command-line argument. You can use ; or : as path separators if you wish. (Ant will convert them to local path separators.)

Exactly one of value, line, file, or path.

value

Specifies a command-line argument.

Exactly one of value, line, file, or path.


Here's an example that stores the output of the compilation in a directory named output1.4 if the compiler version is 1.3, 1.4, 1.5, all of which correspond to the "modern" option (see the section Section 3.1.3 for details on specifying the compiler version):

<javac srcdir="${src}"     destdir="${build}">     <compilerarg compiler="modern" value="-d output1.4"/> </javac>

Here's an example where the compiler switches to use are in a file named options:

<javac srcdir="${src}"     destdir="${build}">     <compilerarg file="options"/> </javac>

3.1.3. Using a Different Java Compiler

Using javac, you can specify the compiler you want to use with the global build.compiler property (which affects all javac tasks throughout the build) or with the compiler attribute (specific to the current javac task). Here's an example:

<javac srcdir="${src}"     compiler="javac1.3"     destdir="${out}"     classpath="servlet-api.jar" />

Here are the possible values for the build.compiler property or the compiler attribute:


classic

Specifies that you want to use the standard JDK 1.1/1.2 compiler; you can use javac1.1 and javac1.2 as aliases.


extJavac

Specifies that you want to use modern or classic in a JVM of its own.


gcj

Specifies that you want to use the gcj compiler from gcc.


jikes

Specifies that you want to use the Jikes compiler.


jvc

Specifies that you want to use the Command-Line compiler from Microsoft's Java/Visual J++. You can use microsoft as an alias.


kjc

Specifies that you want to use the kopi compiler.


modern

Specifies that you want to use the JDK 1.3/1.4/1.5 compiler. Here, you can use javac1.3, javac1.4, and javac1.5 as aliases.


sj

Specifies that you want to use the Symantec Java compiler. You can use symantec as an alias.



    Ant. The Definitive Guide
    Ant: The Definitive Guide, 2nd Edition
    ISBN: 0596006098
    EAN: 2147483647
    Year: 2003
    Pages: 115
    Authors: Steve Holzner

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net