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