Debugging

When something goes wrong with your application, you need some debugging. However, JavaScript generated by TeaVM is sometimes hard to understand. Fortunately, you don’t need to debug JavaScript manually. TeaVM supports two ways of debugging your applications: generate source maps or use IDEA debugger for TeaVM. Of course, both of them require class files to contain debug information.

Generating source maps

The preferred way of building TeaVM is to build it by Maven. Generating source maps in this case is straightforward: in the teavm-maven-plugin set the sourceMapsGenerated property to true. Also, you will need your source files to be included in your web application. If you don’t want to copy the source files manually, you can also set the sourceFilesCopied property. See the following snippet:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.teavm</groupId>
        <artifactId>teavm-maven-plugin</artifactId>
        <version>0.6.1</version>
        <executions>
          <execution>
            ...
            <configuration>
              ...
              <sourceMapsGenerated>true</sourceMapsGenerated>
              <sourceFilesCopied>true</sourceFilesCopied>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

These two properties are set by default if you generate the project by the teavm-maven-webapp archetype.

Note that IDEA builder automatically configured from Maven, so if you have configured Maven plugin to generate source maps, IDEA builder will generate them as well.

Using IDEA debugger

TeaVM has its own built-in debugger. It requires a special file, that contains mapping between JVM and JavaScript locations, names, etc. You should enable generation of this file in your Maven configuration. Simply set the debugInformationGenerated property to true, as in the following snippet:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.teavm</groupId>
        <artifactId>teavm-maven-plugin</artifactId>
        <version>0.6.1</version>
        <executions>
          <execution>
            ...
            <configuration>
              ...
              <debugInformationGenerated>true</debugInformationGenerated>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>

Note that enabling this option does not affect the generated JavaScript file, so you can debug code without performance penalty.

Debugger connects to a backend that can control execution of JavaScript code and translates your commands into commands to this backend, mapping all locations and names. For now only backend for remote Google Chrome available. This backend simply exposes Google Chrome remote debug protocol over WebSocket.

To debug TeaVM application, you should first install TeaVM debug agent for Google Chrome.

To start debug session, you need to launch a TeaVM debug configuration. In menu, select Run -> Edit configurations…. Click on the plus button and pick TeaVM debug server, a new launch configuration should appear. Close configuration window by pressing OK and start a new debug session.

Now you should connect Google Chrome to TeaVM debug server. Open your application in Google Chrome and press the TeaVM debugger agent button beside the address bar (the green teapot icon). Put breakpoints on your Java code and when they hit, you can see the execution state of your code and issue debug commands.

Notice that in the Debug view you have two threads: main and JavaScript. They are not threads, but different representations of the debug process.