Compile Reports & Optimization

-compileReport ("Compile a report that tells the Story of Your Compile", default off) collects, for every permutation, the size contributed by each package and class and how the code is distributed over fragments, and writes a set of static HTML pages. The gwt-maven-plugin compile goal has no compileReport parameter, so pass the flag through compilerArgs. With the plugin the extras directory is target/extras, and the report ends up in target/extras/<module>/soycReport/compile-report/.

Source: GWT — Compile Report: Usage, gwt-maven-plugin — gwt:compile

The run printed the location of the extras, and the report is not part of the war:

With the command-line compiler the same flag works with -extra dir. The flags related to the report are:

The -XsoycDetailed flag is a size-for-time trade: the documentation says it is "at the expense of compile time". In this application the difference was within the noise of the machine. Two more switches (-XenableJsonSoyc and -XdisableSoycHtml) exist in the 2.13.1 source as undocumented experimental flags and were not run here.

For one permutation (locale=en, user.agent=safari) the report directory held 102 files and 6.2 MB, and the extras directory 8.4 MB. A six-permutation compile with -XsoycDetailed wrote about 40 MB of extras.

Source: GWT — Compile Report: Features

Open compile-report/index.html directly from disk. It lists the permutations with their property values ('locale' : 'en' , 'user.agent' : 'safari' and so on). Without -XcompilerMetrics the "Compiler Metrics" link under each permutation points to a page that was not written.

The permutation dashboard shows three numbers and the split points. For the Bookshelf permutation:

The Developer Guide explains the relation: without code splitting the initial download equals the full code size. Here the admin area is a trivial panel, so the split point moves only 633 bytes (0.2 %) out of the initial download. The same 633 bytes can be seen in a JFR event further down. The numbers are formatted with the default locale of the JVM that ran the compiler: on the machine used here they read 262.930 for 262,930 and 66,2 % for 66.2 %. A report generated on a build server with another locale looks different.

The sizes are the compiled program; the permutation file <hash>.cache.js was 265,852 bytes because the linker adds its wrapper, and about 89,500 bytes after gzip -9. Serve the .cache.js files compressed: it matters more than most flags below.

The initial download of that permutation, by code type:

The report also states that 4,202 bytes are strings and that 21,041 bytes cannot be attributed to a package or code type. The largest packages of the initial download were:

Drilling into a package lists classes: the largest allOther classes were com.google.gwt.i18n.client.NumberFormat (6,510 bytes), AbstractCellTable (5,916) and HasDataPresenter (5,547), and in the jre group java.util.ArrayList (1,922), java.util.AbstractMap (1,838) and java.lang.Throwable (1,672). The reading is immediate: the Bookshelf’s own code is 2 % of the program and the DataGrid is 15 %. Cutting application code would be pointless; the levers are the widget choice, the locale machinery and the runtime flags of the next section.

The dependency pages answer "I expected this to be left out". The Developer Guide describes the procedure: from the overview open the permutation, follow the "Report" link under "Initial download size", open the package and then the class; the page shows a chain of calls back to the entry point. The same information is in dependencies<n>.xml.gz, where every method lists its called by entries. Following the first caller at every step for the sort-icon initializer of the grid gave:

The DataGrid constructor is the link to break: create the grid inside a split point and the whole chain, including the generated client bundle, leaves the initial download. The "Split point status" and "Leftover status" pages explain the opposite case, an item that is only in the leftover fragment because two split points need it (each page offers a "See why it’s not exclusive to s.p. #n" link). The mechanics of exclusive and leftover fragments belong to Code Splitting.

Source: GWT — Compile Report: Features, GWT — Compile Report: Use cases

The overview lists every permutation, so differences between user agents or locales can be compared one by one. The four use cases named by the Developer Guide are reducing the whole download, the initial fragment, specific fragments and comparing permutations.

The report contains class names, method names and, with -XsoycDetailed, JavaScript snippets mapped to Java. Keep it out of the public site. With the Maven plugin the extras folder is outside the war (a search of the war found no soyc or symbol-map file), and the same holds for -extra of the command-line compiler as long as that directory is not inside -war. Never point -extra at the web root.

By default GWT keeps metadata so that Class.getName() and getSimpleName() work (-X[no]classMetadata, default on). Turning it off saved 119,370 bytes over the six files. The price is visible at run time. A line that logs App.class.getName() + " / " + App.class.getSimpleName() printed, in a headless Chrome:

So do not use the flag in an application that logs, serializes or switches on class names. In the source the disabled mode names a class "Class$" plus an id.

Source: GWT — Command Line Tools, GWT source — Class.java

The JRE emulation contains checks that Java programs get from the JVM. They are controlled by properties defined in Preconditions.gwt.xml: jre.checks.checkLevel (NORMAL, the default, OPTIMIZED or MINIMAL) and the four finer switches jre.checks.bounds, jre.checks.api, jre.checks.numeric and jre.checks.type, each AUTO (follow the level), ENABLED or DISABLED. In InternalPreconditions the bounds, API and numeric checks are on only at NORMAL, and the type check at OPTIMIZED or higher. Set the level in the module or on the command line:

Source: GWT source — Preconditions.gwt.xml

The property is a deferred-binding property, so it does not add permutations when it has one value. The trade-off is correctness: with the checks gone an out-of-range list.get(10) or a failed cast is no longer reported the way Java reports it. Measure the gain first (2.3 % here) and try OPTIMIZED before MINIMAL. The old -XcheckCasts flag is deprecated in favour of jre.checks.checkLevel, as the -help text says.

The report’s jre group is the cost of Java library classes that you pull in. A single call chain using BigDecimal to compute a late fee, new BigDecimal("0.25").multiply(BigDecimal.valueOf(days)).setScale(2, RoundingMode.HALF_UP), made one permutation grow from 265,852 to 290,470 bytes (+24,618, +9.3 %); the report named java.math as 21,220 bytes (8.1 %). Computing the fee in whole cents with int removes all of it:

Other classes with the same effect are listed on the JRE emulation page; see JRE Emulation & Shared Code. Prefer plain int, double and String in shared code, and check the report’s jre list after adding a library.

Source: GWT — Compile Report: Package and code type breakdown

The cheapest saving is to compile fewer permutations while developing. Fixing the properties reduced six permutations to one:

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

The Maven user properties gwt.draftCompile, gwt.optimize and gwt.localWorkers exist on the compile goal.

-localWorkers count is the number of workers that compile permutations. The 2.13.1 source shows what a worker is: ThreadedPermutationWorkerFactory creates in-process threads, but caps them at the system property gwt.jjs.maxThreads, whose default is 1. Every further worker is launched by ExternalPermutationWorkerFactory as a separate JVM that inherits the JVM arguments of the compiler (-Xmx and -D options) unless gwt.jjs.javaArgs overrides them. Consequences:

-incremental compiles faster by reusing data from the previous compile, but it works on one permutation only:

Combine it with -setProperty values that fix every property, as the code server does. The flag is meant for development; the compiler page lists its other restrictions. -validateOnly -failOnError checks the sources without producing output and is the cheapest first step of a pull-request build.

The lightweight metrics system is a global JavaScript function, __gwtStatsEvent, that the compiled code and the bootstrap call with an event object. If the host page does not define it, nothing is reported (the compiled code checks for it before building an event). The event is a plain object with these fields:

Some events carry more: sessionId, method (the RPC proxy and method), fragment and size (fragment downloads) and bytes (RPC payloads). The collector must return true or false to say whether it recorded the event, and it has to be defined before the bootstrap script runs.

Source: GWT — Lightweight Metrics: How it works

The Developer Guide’s example writes each event into the page with innerHTML. A collector should never render event fields as HTML (custom events can carry any string), so this one stores text only and prints it with textContent:

Source: GWT — Lightweight Metrics: Global collector function

Served by a static server and loaded in headless Chrome, the page printed (RPC lines are from the XSRF token request, which got a 404 because no servlet container ran; the events appear all the same):

The startup events come from the bootstrap script, moduleStartup from the module loading (see Linkers & Bootstrap), rpc from the RPC proxies and runAsync from the fragment loader. Opening the admin place added the split point downloads, with the leftover fragment first:

Source: GWT — Lightweight Metrics: Measurable events already in place

The Developer Guide extends the system with a JSNI method. In 2.13 a native JsInterop binding does the same without JSNI, and JsPackage.GLOBAL reached the host page’s __gwtStatsEvent (the compiled code runs inside the xsiframe iframe, and the call still arrived):

Source: GWT — Lightweight Metrics: Extending the system

The shell begin and shell end lines in the output above come from this code. Several modules on one page report to the same collector with their own moduleName, which allows comparing them (the "multiple modules" section of the guide).

The events are ordinary jdk.jfr.Event subclasses in the GWT category with @StackTrace(false). They are written when a recording is running in the compiler JVM. With Maven the compiler is a forked JVM, so pass the option in jvmArgs:

Source: GWT — Release Notes 2.13.0, GWT source — util/log/perf

The summary of the six-permutation compile listed these GWT events (count of events in the recording):

The fragment events tie the two tools together. For permutation 0 the recording has fragment 0 with jsBytes = 259606 and fragment 1 with jsBytes = 658; the compile report of the same permutation reported an initial download of 259,606 bytes and a split point of 658.

Printing as JSON and aggregating gave this picture for the Bookshelf compile:

Nested tasks overlap, so the figures do not add up. Two conclusions followed: the time before the permutations (parsing and type resolution) is as large as the optimisation, and generators are almost free here, so trimming UiBinder templates would not shorten this build while fewer permutations would.

The gwt.jjs.dumpAst system property, which the release notes say was tweaked in 2.13.0, dumps the Java and JavaScript AST between passes to a file; gwt.jjs.dumpAst.filter restricts the output to source files and line ranges. It is a compiler-developer tool and is only mentioned for completeness.