Debugging Forge

Forge logfiles

As of CR1 (and SNAPSHOTS since Beta5,) Forge produces a debug logfile located at:


Eclipse integrated debugging

A new feature of JBoss Tools 4.0 is the debug option of the Forge plugin.

Under Window > Preferences > Forge the option “Start Forge in Debug Mode” enables you to fully debug the Forge runtime. Hitting the famous [CTRL+4] keys will then launch Forge in Eclipse debugger. This way you may watch Forge registering and launching your plugin. Don’t forget to switch to Debug perspective.

Depending of your use case you may additionally change the Forge runtime by registering your current Forge core source tree under “Installed Forge Runtimes”.

Current Shortcomings

The current eclipse plugin does not yet associate sources automatically, so you have to add relevant sources using “Edit Source Lookup” on the debug configuration. The generated debug configuration is available during the Forge debug session and will be cleaned up afterwards.

Enable debug mode

Start Forge by using the following parameter:

forge --debug

If you don’t want to use the —debug parameter, you need to set the following FORGE_OPTS (JVM arguments) in your console before starting Forge (this does not work when running Forge in the IDE – it must be run from the command line).

For Unix:

export FORGE_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"

For Windows (note no quotes):

set FORGE_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000

Then run Forge. If you’ve done this step correctly, Java should state that it is waiting for the debugger to attach on port 8000.

Connect the debugger

If you are using Eclipse, in addition to having the Forge sources imported as projects in your workspace, you will need to create a new project (for this example, call it ‘maven-debug’), then right-click on that project, and click “Debug as → Remote Java Application”

Make sure the remote debugger port is set to 8000 (or the port you’ve selected,) much like debugging Maven.

Attach the sources

If Eclipse complains that it cannot find the source attachment for a breakpoint, make sure to add all related Forge projects as source attachments to your new ‘maven-debug’ project by clicking the “Attach Sources” button.