I spent some time recently to figure out GWT’s new super dev mode. What is super dev mode?

In GWT, you had two modes of running your app so far. You could either start it in dev mode or compile it and deploy it to a web server for testing.

In dev mode, a JVM would be spun up, that is actually running all your Java code, and in the browser, a plugin would bridge the Java code with the Javascript code. This is extremely slow, especially for apps like games, to the point where it is unusable. However, it was also the only way to properly debug your GWT application. The issue with dev mode is, that you will not detect errors that only crop up if you compile to Javascript. That’s because in dev mode you can use the full Java runtime library. When compiled to Javascript, your app can only rely on the GWT Java library emulation. To make sure you don’t use anything that’s not supported in GWT, you have to compile things. The dev mode plugin required for the browser can also be a bit frickle, and new browser versions often require a new plugin, which may not be available instantaniously from the GWT team.

In compiled mode, or prod mode, your Java code gets compiled to Javascript by the GWT compiler. This takes quite a bit of time, depending on the size of your Java code. Also, once compiled, you can not debug your app anymore. The generated Javascript is usually impenetrable by mere humans.

Enter super dev mode. In super dev mode, you spin up a so called code server. That server is responsible for compiling your Java code to Javascript code on the fly. It observes your source directories and will dynamically recompile any changes you made. This recompilation takes a lot less time than the initial compilation. In general you can let the code server just run and let it do its thing. Besides the compilation speed up on changes, the code server also provides source maps. These are metadata that tells the browser which lines in the Javascript code correspond to what lines in the original Java source code. This mechanism is also used for other XXX-to-Javascript compilers. You can then debug your Java code within the browser, without plugins or the reliance on a JVM!

The official docs are a bit sparse, so i figured i’d provide a tutorial on how to setup your libgdx project to use GWT super dev mode. Be warned, the process is a bit involved at the moment.

I started out by generating a project via the setup-ui, then load it into Eclipse. You can do the following on existing projects as well of course. My initial setup looks like this:

All changes will be made to the HTML project!

Modifying the gwt.xml file

First we have to change the linker options on the gwt.xml file of the HTML project, located in project-html/src/your/package/here. You should see something like this:

We need to add three new elements, specifying the linker, that we ignore script tags, and that the dev mode redirect is enabled (this will make sure the code server can inject the compiled Javascript into the HTML site later). The modified version looks like this:

Copying soundmanager javascript files

We use SoundManager2 for the GWT’s audio backend implementation. This library has two Javascript files that we need to include. With the normal linker, those are included automatically, however, the xsiframe linker doesn’t do that. To fix this, we have to put the files into the war/ directory, and load them manually in the index.html file.

soundmanager-setup.js can be found here.
soundmanager2-jsmin.js can be found here

Put those two files into your project-html/war folder, right next to the index.html file. Should look like this:

Now include those two files into your index.html file, like this:

Note that the order matters, setup before jsmin, and both before the inclusion of our compiled Javascript code.

Configuring and starting the code server

To start the code server, it’s easiest to create a new Run Configuration in Eclipse. Go to Run -> Run Configurations…, then create a new Java Application run config.

Give it a nice name (mygame code server), and as Project, set your html project. As main class specify com.google.gwt.dev.codeserver.CodeServer. This class is responsible for compiling the code and serving it to the browser.

The class is found in a jar file of the GWT SDK, so we need to add that to the classpath of the Run Configuration. Go to the Classpath tab, select User Entries, then click the Add External Jars… button

You can find the jar gwt-codeserver.jar file in your Eclipse installation folder

Finally we need to specify the arguments to the code server. It wants to know where our sources are, and which GWT module to compile. We need to tell it about the gdx-sources.jar, the gdx-backend-gwt-sources.jar, the core project’s src/ folder and the src/ folder of the HTML project itself. The code server doesn’t like jar files, so we have to unzip them in their respective directories (project-core/libs/gdx-sources.jar, project-html/war/WEB-INF/libs/gdx-backend-gwt-sources.jar), ending up with this:

Now we can specify the arguments of the run configuration, html project, gdx gwt backend, gdx sources, and the core project’s sources:

Hit Apply then Run, and you should see this after 20 seconds:

Click the link at the bottom of the console output, which will open a browser and display this:

Drag the Dev Mode On bookmark to your bookmark bar (already done in the above screenshot). We’ll need to click on that later.

With this we have configured and started the code server. It can just sit there running while you code your game. You will have to redo the setup for every new project of yours.

Running the app in super dev mode

Now for the fun part. The code server only serves source maps and Java script code. We need to still host the index.html and asset files in the project-html/war folder through a webserver. I usually point Mongoose at my project-html/war folder. That will serve the war/ folder contents at http://localhost:8080/.

An alternative is to start the html project like we do in dev mode (right click project, Run As -> Web Application, click on the URL in the Development Mode view). The URL is usually something like http://127.0.0.1:8888/index.html?gwt.codesvr=127.0.0.1:9997, just remove the part after the ? to end up with http://127.0.0.1:8888/index.html

Once you opened the index.html in the browser (either served through a proper web server or dev mode), you will see this:

Click OK, then click on the “Dev Mode On” book marklet your previously added to the bookmarks bar of your browser. You’ll see this:

Click on compile, which will tell the code server to recompile all Java files to Javascript and inject the result into the website. (Watch the code server console in Eclipse, if you run out of memory, add a VM argument like -Xmx1024m to the code server run configuration). After compilation is done, you’ll be greeted with the same dialog as above again, just ignore it. Your game now runs in the browser.

Debugging!

Now for the magic part. Bring up the developer tools of your browser. I use Chrome, which has super duper source map support, haven’t tested other browsers yet. In Chrome, you can press F12 or right click the site and click “Inspect Elements”. You’ll see this

Click on Sources, then click on the “Show Navigator” button:

This will bring up this view, expand the entries under localhost:9876, and there you have your Java code. Select one of your fails, e.g. your ApplicationListener, and set a break point, e.g. like this:

You can now inspect variables, see the call stack, step over/into statements and so on.

If you changed your source files, just click the “Dev Mode On” bookmarklet, click Compile and let things reload.

And that’s super dev mode. Hopefully the GWT team will add better integration, at the moment the setup is a bit convoluted.