Appendix A

javac

javac is a Java compiler for compiling Java programs to bytecode. Source files must have a java extension and be organized in a directory structure that reflects the package tree. The results are class files in a directory structure reflecting the package tree.

javac has the following syntax.

javac [options] [sourceFiles] [@argFiles]

where options are command-line options, sourceFiles one or more Java source files, and @argFiles one or more files that list options and source files.

You can pass source code file names to javac in one of two ways:

• List the file names on the command line. This method is suitable if the number of source files is small.
• List the file names in a file, separated by blanks or line breaks, then pass the path to the list file to the javac command line prefixed by an @ character. This is appropriate for a large number of source files.

Options

Options are used to pass instructions to javac. For example, you can tell javac where to find classes referenced in the source files, where to put the generated class files, etc. There are two types of options, standard and nonstandard. Nonstandard options start with -X.

Here are the lists of standard and nonstandard options.

Standard Options

-classpath classpath 

If in your source files you reference other Java types than those packaged in the Java standard libraries, you need to tell javac how to find these external types by using the –classpath option. The value should be the path to a directory containing referenced Java types or a jar file containing them. The path can be absolute or relative to the current directory. Two paths are separated by a semicolon in Windows and by a colon in Unix/Linux.

For example, the following Windows command line compiles MyClass.java that references the primer.FileObject class located in the C:programclasses directory.

      javac -classpath C:/program/classes/ MyClass.java

Note that the FileObject class is in the primer package, so you pass the directory containing the package.

The following Linux command line compiles MyClass.java that references the primer.FileObject class located in the /home/user1/classes directory.

      javac -classpath /home/user1/classes/ MyClass.java

To reference class files packaged in a jar file, pass the full path to the jar file. For instance, here is how you compile MyClass.java that reference primer.FileObject in the MyLib.jar file located in C: emp in a Windows system.

      javac -classpath C:/temp/MyLib.jar MyClass.java

This example compiles MyClass.java that references classes located in the /home/user1/lib directory and packaged in the Exercises.jar file located in the /home/jars directory in Linux:

      javac -classpath /home/user1/lib/:/home/user1/Exercises.jar 
      MyClass.java

If you are referencing a class whose root is the same as the class being compiled, you can pass ./ as the value for the classpath. For example, the following command line compiles MyClass.java that references both C: emp and the current directory:

      javac -classpath C:/temp/;./ MyClass.java

The alternative to the classpath option is to assign the value to the CLASSPATH environment variable. However, if the classpath option is present, the value of the CLASSPATH environment variable will be overridden.

If the -sourcepath option is not specified, the user class path is searched for both source files and class files.

-cp classpath

The same as -classpath.

-Djava.endorsed.dirs=directories 

Override the location of endorsed standards path.

-d directory 

Specify the target directory for class files. The target directory must already exist. javac puts the class files in a directory structure that reflects the package name, creating directories as needed.

By default, javac creates class files in the same directory as the source file.

-deprecation 

List each use or override of a deprecated member or class. Without this option, javac shows the names of source files that use or override deprecated members or classes. -deprecation is shorthand for -Xlint:deprecation.

-encoding encoding 

Specify the source file encoding name, such as UTF-8. By default, javac uses the platform default converter.

-g 

Print debug information, including local variables. By default, only line number and source file information is generated.

-g:none 

Prevent javac from generating debug information.

-g:{keyword list} 

Generate only some kinds of debug information, specified by a comma separated list of keywords. Valid keywords are:

• ? source. Source file debug information
• ? lines. Line number debug information
• ? vars. Local variable debug information

-help 

Print a description of standard options.

-nowarn 

Disable warning messages. This has the same effect as -Xlint:none.

-source release 

Specifies the version of source code accepted. The values allowed are 1.3 to 1.8 and 6 to 8.

-sourcepath sourcePath 

Set the source code path to search for class or interface definitions. As with the user class path, source path entries are separated by semicolons (in Windows) or colons (in Linux/Unix) and can be directories, jar archives, or zip archives. If packages are used, the local path name within the directory or archive must reflect the package name.

Note: Classes found through the classpath are subject to automatic recompilation if their sources are found.

-verbose 

Include information about each class loaded and each source file compiled.

-X 

Display information about nonstandard options.

Nonstandard Options

-Xbootclasspath/p:path 

Prepend to the bootstrap class path.

-Xbootclasspath/a:path 

Append to the bootstrap class path.

-Xbootclasspath/:path 

Override location of bootstrap class files.

-Xlint 

Enable all recommended warnings.

-Xlint:none 

Disable all warnings not mandated by the Java Language Specification.

-Xlint:-xxx 

Disable warning xxx, where xxx is one of the warning names supported for -Xlint:xxx.

Xlint:unchecked 

Provide more detail for unchecked conversion warnings that are mandated by the Java Language Specification.

-Xlint:path 

Warn about nonexistent path directories specified in the classpath, sourcepath, or other option.

-Xlint:serial 

Warn about missing serialVersionUID definitions on serializable classes.

-Xlint:finally 

Warn about finally clauses that cannot complete normally.

-Xlint:fallthrough 

Check switch blocks for fall-through cases and provide a warning message for any that are found. Fall-through cases are cases in a switch block, other than the last case in the block, whose code does not include a break statement.

-Xmaxerrors number 

Specify the maximum number of errors that will be reported

-Xmaxwarns number 

Specify the maximum number of warnings to be reported.

-Xstdout filename 

Send compiler messages to the named file. By default, compiler messages go to System.err.

The -J Option

-Joption 

Pass option to the java launcher called by javac. For example,

-J-Xms48m sets the startup memory to 48 megabytes. Although it does not begin with -X, it is not a `standard option' of javac. It is a common convention for -J to pass options to the underlying VM executing applications written in Java.

Command Line Argument Files

If you have to pass long arguments to javac again and again, you will save a lot typing if you save those arguments in a file and pass the file to javac instead. An argument file can include both javac options and source filenames in any combination. Within an argument file, you can separate arguments using a space or separate them as new lines. The javac tool even allows multiple argument files.

For example, the following command line invokes javac and passes the file MyArguments to it:

javac @MyArguments

The following passes two argument files, Args1 and Args2:

javac @Args1 @Args2