The basic-simulator, when compiled, is a self-contained jar capable of running complete simulations. It runs locally on one machine and is therefore well suited for rapid testing and debugging.
After cloning and building the basic-simulator repository, the program can be started using the
run.sh script inside
The basic-simulator project is a Maven project. It is thus built using
mvn clean install -s settings.xml. TODO link to maven tutorial.
The following window should open:
The browser on the left shows the content of the folders that are alongside the
basic-simulator.jar file. The OSM maps can be visualized by selecting them. When selecting a scenario, it will immediately load the corresponding simulation and show simulation controls at the top. Using these, simulations can be started, paused and reset. The speed at which the simulation should run can also be set.
The map visualization can be used to copy coordinates (for scenarios).
The basic-simulator JAR can be used in a CLI fashion to run simulations without the GUI.
Just pass the path to a scenario file as argument when running the simulator. This can be done with the
run script of the install folder or by making the proper underlying java call.
The result (SUCCESS/FAILURE) of the simulation will be printed and the return value will be different than 0 on failure (to use in CI, ...).
Next: Simulation Configuration
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.
Debugging with VSCode
The basic-simulator contains a default
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+clickon the type name, this will open the
.classfile 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
TCPBackendshould open the
TCPBackend.classfile. (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_libfile 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.
- 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.
For other debuggers, if they require a process id to attach to, this id can easily be found by running
jps (Java process utility).
Next: Simulation Configuration