Debugging the Basic Simulator

The basic-simulator setup is local and self-contained. This allows you to run the java debugger on the jar.

For this create a Run/Debug configuration that executes the jar and specify a folder in which to run it. (Ex: the install folder inside the basic-simulator project). You can then start the simulator in normal or debug mode, set breakpoints and step through almost the entire code.

This can be done with any editor/debugger. The following sections give examples on how to do this with VSCode and IntelliJ.

It is recommended to run the debugger on the jar and not directly in the editor, since there might be problems with the dependencies otherwise.

Note: In order to step through code from dependencies, it might be necessary to build the different dependencies locally.

Debugging with VSCode

The basic-simulator contains a default launch.json config. This debugging configuration assumes the simulator is built and the jar lies in the install folder (this is the default behavior when running mvn install ...). This launch configuration can be started in the Run and Debug tab of VSCode.

Tip: Setting breakpoints in the classes of dependencies is not trivial in VSCode. A trick to do so involves the following:

• In a class of the basic-simulator project (ex: App.java), create a dummy variable of the class you want to set a breakpoint in.
• Ctrl+click on the type name, this will open the .class file of the class. You can then set your breakpoints.

As example, to set a breakpoint in the constructor or measuredCycle() function of the TCPBackend.java class of the hardware-emulator, you can temporarily create this dummy variable anywhere in the basic-simulator (ex: App.java): TCPBackend dummy;. Then ctrl+clicking on TCPBackend should open the TCPBackend.class file. (If the Java extension for VSCode is installed).

Once the breakpoint is set, the class file and the breakpoint will remain accessible in the breakpoints list in the Run and Debug tab.

Debugging with IntelliJ

IntelliJ configuration example for running the jar in the install folder:

Debugging the hardware_emulator

The hardware_emulator is C++ code run as native-library inside the simulator.

The steps to step through/set breakpoints in the hardware_emulator are a bit more complex:

• Build the hardware_emulator in debug mode.
• Replace the hardware_emulator_lib file alongside the basic-simulator jar with the debug version.
• Start the basic-simulator.
• Attach to the Java thread of the simulator with a C++ debugger (attach inside the hardware_emulator project).
• Set your breakpoints in the C++ project, run the simulator.
• To return to using the default release version of the hardware_emulator, just delete the library alongside the basic-simulator jar; it will be re-exported.

This is easily done in the Visual Studio solution for the hardware_emulator. For this, open the hardware_emulator.sln solution in the build directory of the hardware_emulator. Then attach to the simulator thread by going to Debug -> Attach to Process and searching for java in the filter and select the basic-simulator.

For other debuggers, if they require a process id to attach to, this id can easily be found by running jps (Java process utility).