Joseph D. Darcy's Sun Weblog

Thursday August 06, 2009

Build Advice: Set Source, Target, and Encoding

When using javac to compile nontrivial programs, it is almost always prudent to explicitly set the source, target, and encoding options (-source, -target, and -encoding, respectively). Leading by example, the JDK 7 build was recently changed to use explicit source and target settings ahead of upgrading those settings to 7 (6854244, 6827026).

The source option picks which version of the language to accept. Note that to perform a proper cross-compile to an older version of the platform the bootclasspath also needs to be set to an appropriate library. The target option selects which class file version to use for output. The same source construct, for example, a class literal, may be compiled differently and with slightly different semantics under various source and target settings. More directly, the target setting affects which JDK versions the resulting class files will run on. The default source and target change over time; specifying these options explicitly rather than relying on the defaults requests and documents the desired semantics the compiler should use for the input sources and output class files.

The encoding option controls the initial mapping of bytes from the physical file into a raw stream of Unicode characters comprising the source file. (Further translations can occur on the raw stream of Unicode characters before the logical stream of tokens is constructed.) If not set explicitly, the platform's default encoding is used to perform the initial mapping. The default encoding for a platform is stored in the file.encoding system property. Encoding errors can cause contents of a file to be interpreted as gibberish and may lead to a compiler error.

One kind of program where using the default source and target is reasonable is regression tests for the compiler and related tools. Unnecessary source and target options were removed from the JDK 7 langtools repository (6843761) as part of the overall effort to update the default source and target to 7 . Many of the now extraneous options in those regression tests were introduced in JDK 5 before the default source was switched to 1.5 in that release. Switching the default source setting early in a feature release avoids the need to have explicit options in tests of new language features.