Compiler & Compilation

com.google.gwt.dev.Compiler is the production-mode compiler. It takes the name of one or more modules (a *.gwt.xml file found on the classpath, see Project structure and modules) and turns the Java source reachable from that module’s entry points into JavaScript. It does this in three steps, which show up as separate pieces of the output:

The tool exits with status 0 on success and 1 on failure, which is what makes it usable from a script or CI job.

Source: GWT — Compiling and Debugging: Understanding the GWT Compiler, GWT source — Compiler.java

The compiler is an ordinary Java main class in gwt-dev. Its classpath must contain gwt-user, gwt-dev, the validation and other dependencies of the project, the Java source of the client and shared code (not only the compiled classes, because GWT compiles from source) and the module descriptors. Source directories should come first. With Maven the simplest way to get the dependency part is to let the build print it:

Source: GWT — Compiling and Debugging: Understanding the GWT Compiler

The module com.example.bookshelf.App is generated by gwt-maven-plugin from src/main/module.gwt.xml into target/classes (that is why target/classes is on the classpath) and carries rename-to="bookshelf", so the output lives in a bookshelf folder. The default run printed:

Source: GWT — Compiling and Debugging: Understanding the GWT Compiler

(The warning about the plural form one is a real finding about the Internationalization page, not noise: a message with a plural form needs a locale-specific properties file even for English.) The numbers to read in that output are "Compiling 6 permutations" (see Permutations) and the time. Times in this page come from a laptop that was running other jobs, so treat them as orders of magnitude and compare sizes, which are exact.

With no arguments the compiler prints its usage and the first problem it found:

Source: GWT — Compiling and Debugging: GWT Compiler Options

The [no] notation means that a boolean flag has a -name and a -noname form, and the -X prefix marks an experimental flag. The help text of the version in use is the authoritative list, because the options "can differ slightly from version to version", as the official page itself says. Several flags have older spellings that still work: -strict for -failOnError, -ea for -checkAssertions, -XcompilePerFile for -incremental, and -XdisableCastChecking and -XdisableClassMetadata for the experimental flags with the same labels.

The tables below follow the help text of 2.13.1, which is also what the Developer Guide page "Compiling and Debugging" prints. The "Measured" column states the effect on the Bookshelf (one permutation, user.agent=gecko1_8, locale=en, 244,639 bytes of main JavaScript with the default flags) so that the abstract descriptions have a size attached.

The Developer Guide page prints the compiler help verbatim, and the help says -sourceLevel [auto, 1.8, 9, 10, 11, 17] and "defaults to 1.8". Two points about that statement, checked on 2.13.1 against the source and by running the compiler:

For the command-line compiler the statement is true. The argument processor applies -sourceLevel 1.8 when the flag is absent. A client class using a Java 16 record, compiled under JDK 21 with no -sourceLevel, fails:

Source: GWT — Compiling and Debugging: GWT Compiler Options

-sourceLevel 11 fails with the same two errors, while -sourceLevel 17 and -sourceLevel auto both succeed (exit 0). So the default of the command-line compiler is 1.8 (the default argument is registered in ToolBase), not the level of the running JVM, even though SourceLevel.DEFAULT_SOURCE_LEVEL in the source is computed from java.specification.version. That constant is what auto resolves to, and the initial value inside the options objects used by tools that do not go through the command-line parser. Java 12-17 syntax needs an explicit -sourceLevel 17. The gwt-maven-plugin <sourceLevel> parameter takes its default from maven.compiler.source.

The statement is stale in its consequences. GWT has supported Java 12-17 language features (text blocks, instanceof patterns, records, switch expressions) since 2.12.0, but none of them compile unless the build says so. The archetype therefore sets <sourceLevel>17</sourceLevel> on gwt-maven-plugin (the plugin passes it through; its user property is maven.compiler.source). There is no level between 11 and 17 and none above 17: -sourceLevel 21 is rejected. The help also still lists the values from 1.8 upwards while the roadmap says Java 21 language features are a goal.

The decision for a project is simple: pass -sourceLevel 17 (or the Maven sourceLevel setting) explicitly, and keep the release setting of maven-compiler-plugin aligned with it so the Java compiler and the GWT compiler accept the same language.

Source: GWT — Compiling and Debugging: GWT Compiler Options, GWT source — ArgHandlerSourceLevel.java

-style controls readability, not behaviour. The same exported method, ExportedApi.formatCopies, in the three styles (one permutation each, with -generateJsInteropExports):

Source: GWT — Compiling and Debugging: GWT Compiler Options

For the Bookshelf without exports the three styles produced 244,639 (OBFUSCATED), 685,398 (PRETTY) and 2,074,085 (DETAILED) bytes. Use PRETTY or DETAILED only to read the output; production uses OBFUSCATED, which is also the only style whose names an attacker cannot read straight off the page. Obfuscation is size and convenience, not secrecy: never place secrets in client code in any style.

Two settings decide how much checking code is compiled in.

-checkAssertions keeps Java assert statements. They throw an AssertionError in the browser, so use them in development and in GWTTestCase runs (the Maven gwt:test goal sets enableAssertions), not in production.

jre.checks.checkLevel is a deferred-binding property defined by the JRE emulation (Preconditions.gwt.xml) that chooses how many of the emulated library’s own checks (index bounds, API misuse, numeric and type errors) stay in the code. It is set with -setProperty or <set-property> in a module:

Source: GWT — Compiling and Debugging: GWT Compiler Options, GWT source — Preconditions.gwt.xml

The Bookshelf main file shrank from 244,639 to 239,501 bytes (about 2 percent). Lower levels turn exceptions that Java programs rely on (an IndexOutOfBoundsException from List.get) into undefined behaviour, so lowering the level is an optimisation for code that is known to be correct, never a way to fix a bug. In development mode the checks always run, converted to an AssertionError when a level disables them, so that reliance on the exceptions is found early; that works only if the module uses the same level in every environment. The finer jre.checks.bounds, jre.checks.api, jre.checks.numeric and jre.checks.type properties (AUTO, ENABLED or DISABLED) exist for the same purpose, and the deprecated -XcheckCasts flag only sets jre.checks.type.

Source: GWT — Compiling and Debugging: GWT Compiler Options, GWT source — InternalPreconditions.java, GWT source — Preconditions.gwt.xml

By default the compiler is lenient. A source file with a compile error is ignored unless the application reaches it, because GWT compiles only what the entry points can reach. Here a stray java.io.File (not part of the JRE emulation) in a class nothing uses did not stop the compile:

Source: GWT — Compiling and Debugging: GWT Compiler Options, GWT — Release Notes 2.13.0

(exit status 0). With -failOnError (or -strict), the same input fails:

Source: GWT — Compiling and Debugging: GWT Compiler Options, GWT — Release Notes 2.13.0

(exit status 1). When the unsupported class is reachable from the entry point, the compile fails even without the flag, with the same error followed by [ERROR] Hint: Check the inheritance chain from your module; it may not be inheriting a required module or a module may not be adding its source path entries properly. Turn failOnError on in every CI build: a lenient compile hides errors that appear later, in a different permutation or when someone starts using the class. The 2.13.0 release notes added -strict support to test arguments for the same reason.

-validateOnly stops after the validation step. In the Bookshelf it printed only the i18n warning, wrote no output directory and returned 0, which makes it a quick pre-commit or pull-request check; combined with -failOnError it fails with the same messages as above.

Source: GWT — Compiling and Debugging: GWT Compiler Options, GWT — Release Notes 2.13.0

GWT sends every browser only the code it needs. To make that possible without runtime branching, the compiler compiles the application once for every combination of the values of the deferred-binding properties the application depends on. Each combination is a permutation, and each permutation becomes a complete JavaScript file. The properties come from two kinds of place: GWT’s own modules (the user.agent property of UserAgent.gwt.xml has, in 2.13.1, the values gecko1_8 and safari) and the application’s (the Bookshelf adds the locale values en and es to the default locale). Two user agents times three locale values give the six permutations that the compiler announced, and the linker recorded which combination each file serves in compilation-mappings.txt:

Source: GWT — Linkers: Available linkers

(The file lists the six combinations followed by many compiler.* and ClientBundle.* settings of the first permutation.) At run time the small bookshelf.nocache.js script computes the same properties in the browser (the user agent, the locale from the locale query parameter or a <meta> tag; a cookie only when locale.cookie is configured) and loads exactly one of the files.

Source: GWT — Coding Basics: Deferred Binding, GWT — Organizing Projects: The Bootstrap Sequence

The Bookshelf compile wrote the following (names are MD5-style "strong names" of the permutation; the six permutations are shown once and the repeated entries are indicated with dots):

Source: GWT — Compiling and Debugging: Key application files

What each file is for:

Two details matter for deployment. First, the bootstrap and cache pair is the basis of "perfect caching": the official guide shows Apache rules that mark *.nocache.* as always revalidated and *.cache.* as cacheable for a year. Second, public resources (images, stylesheets) can live anywhere under war/; the module’s <public> path still copies files into the module folder, and ClientBundle output also goes there.

Source: GWT — Compiling and Debugging: Perfect Caching, GWT — Compiling and Debugging: Public Resources, GWT — Linkers: Available linkers, GWT — Code Splitting: How to use it

The sample output in the official Developer Guide is from GWT 2.6.1 and shows five .cache.html files, a hosted.html and an Ant build; the real 2.13 output above has .cache.js files, no hosted.html and a devmode.js. The 2007 book that this section cross-checks predates all of this: its compile scripts and per-browser .cache.html files do not exist any more.

Debugging optimised JavaScript in the browser needs source maps. Source map generation is the module property compiler.useSourceMaps (default false in CompilerParameters.gwt.xml), and the code server turns it on for its own compiles, which is why debugging in Super Dev Mode works without any flag (the 2.12.0 notes say source maps are enabled by default in all browsers, which refers to that use). The plain compiler does not generate them. -saveSource alone therefore does nothing useful:

Source: GWT source — CompilerParameters.gwt.xml, GWT — Release Notes 2.12.0

With the property set, the same run produced the maps and the sources next to them:

Source: GWT source — CompilerParameters.gwt.xml, GWT — Release Notes 2.12.0

Source: GWT source — CompilerParameters.gwt.xml, GWT — Release Notes 2.12.0

It wrote symbolMaps/<name>_sourceMap0.json, _sourceMap1.json and _sourceMap2.json (one per fragment, in both -deploy and -extra) and 517 source files under extra/bookshelf/src (the application sources and the generated types under src/gen). Serve the maps and the src tree only in environments where exposing source is acceptable; a production site normally does not. The Development mode and debugging page covers browsing them in the devtools.

Source: GWT — Release Notes 2.12.0, GWT source — CompilerParameters.gwt.xml, GWT source — Recompiler.java

-compileReport asks the compiler to collect "the Story of Your Compile": for every permutation, how many bytes each package and each class contributed and how the code is distributed over fragments. With no -extra the report goes to extras/<module>/soycReport/compile-report/ in the working directory, which matches the Developer Guide; with -extra dir it goes under that directory. Open compile-report/index.html in a browser.

Source: GWT — Compile Report: Usage

The report for one permutation was 4.9 MB of HTML and compressed XML (stories0.xml.gz 45,137 bytes, dependencies0.xml.gz 63,734 bytes). -XsoycDetailed added detailedStories0.xml.gz (228,145 bytes). The report is the right answer to "why is my initial download big" and to "which package pulled in this class", and it can compare permutations. It is a debugging aid and normally not part of a deployment.

Source: GWT — Compile Report: Usage

Almost nobody runs Compiler by hand. gwt-maven-plugin (the net.ltgt.gwt.maven plugin; Build tools: Maven and Gradle covers all its goals) starts it with the project’s classpath in a forked JVM. The packaging gwt-app binds its compile goal to the prepare-package phase. The parameters map to the flags of this page:

A command that overrides the production defaults for a quick local build looks like this (the second line is the output):

Source: gwt-maven-plugin — gwt:compile

Source: gwt-maven-plugin — gwt:compile

The same compilerArgs block carries the module’s flags in the Bookshelf client pom.xml:

Source: gwt-maven-plugin — gwt:compile, GWT — Compiling and Debugging: GWT Compiler Options

The Maven build also printed a JsInterop warning worth knowing about (-generateJsInteropExports was on):

Source: GWT — JsInterop

It means a public exported method takes a Java type JavaScript cannot use meaningfully. The fix is to keep such methods out of the exported surface (or make them non-public), not only to suppress the warning.

Source: GWT — JsInterop

A realistic compile plan for the Bookshelf has two builds that use the same module and differ only in flags:

The release row has to compile everything: a developer machine seldom needs all six files. The first two flags of the left column cost almost nothing and catch most of the problems of the right column: -validateOnly -failOnError reported the stray java.io.File of the earlier section in a few seconds without producing output.

Source: GWT — Compiling and Debugging: GWT Compiler Options

Source: GWT — Release Notes 2.12.0, GWT — Release Notes 2.13.0