Debugging Simulations
When developing your simulation, you will need to inspect and debug your application. To aid this, the Aether Engine SDK provides debugging support, which you can work with inside Visual Studio. Currently we support debugging a single process within your simulation code running locally.
Prerequisites
Make sure you have the following Visual Studio components installed:
- Linux Development with C++
- CMake tools for Linux
You can add these components by launching the Visual Studio Installer from the start menu and choosing 'Modify' for your Visual Studio installation.
In order for debugging to work well, you must ensure that your CMake build includes debug information, and it is strongly suggested that you disable optimisations. To ensure a good experience, include the
--debug, -O0 and -fno-omit-frame-pointer in your CMAKE_CXX_FLAGS for your project.Please review the Important Irregularities and Limitations section before debugging or if you have any issues whilst debugging.
In order to debug a simulation, you first must declare the code-paths at which you wish to pause the running simulation, before starting it. This is done by adding a call to
hadean::stop("reason") in your simulation code, which will cause that process to pause at that call, allowing a debugger to be attached. The reason provided is an arbitrary string of your choosing so you can identify the point and process that has been paused.You can start your simulation with the appropriate debugging infrastructure by ensuring that debug_enabled is set to true in your runtime configuration. By enabling debugging
hadean::stop() calls to be respected, and Hadean Platform will also launch the appropriate additional tooling required to enable a debugger to be attached to your simulation.Note that for a Simulate simulation, if a single process is paused during a call to
hadean::stop(), other processes will pause at the end of the current tick. This avoids the issue of the other processes in the simulation from continuing to simulate whilst you are trying to debugging a specific process.To attach the Visual Studio debugger click on the Visual Studio toolbar to see a list of paused processes for attachment
Hadean Visual Studio Toolbar
Visual Studio list of available paused processes
If you are unable to see these, ensure you have activated the Hadean Toolbar by right clicking on a blank space in the Visual Studio toolbar docking area, and select "Hadean Toolbar".
After selecting a process and hitting the debug button Visual Studio connects to that process, allowing you to inspect the running process, modify variable values, step through or continue execution of your simulation code and set breakpoints, using the normal Visual Studio shortcuts and buttons.
Note that any breakpoints you set in Visual Studio will be hit whilst the debugger is connected, although once you detach from the simulation they will stop having any effect, and only your original
hadean::stop() calls will then re-pause the simulation. Also note that if you set breakpoints inside Visual Studio these will not work until you connect the debugger to a specific process.When you have finished debugging, you can detach from the process being debugged by using the "Detach from Hadean Process" button. This will cause the simulation to continue to run, at least as far as the next
hadean::stop() call.If your simulation stops on a
hadean::stop() call, but you wish to continue the simulation without attaching a debugger, then you can run hadean debug continue-all to continue any processes that have stopped. If you run this whilst debugging a specific process, then all the other processes will continue.When opening Visual Studio, you should open the simulation directory for the simulation you wish to debug, rather than just a single file, in particular you should have the root CMakeLists.txt of your simulation be at the root of the Visual Studio open folder.
You must not press
stop in Visual Studio when debugging a simulation.Due to the nature of our internal implementation, visual studio will stop twice on each
hadean::stop call.While a simulation is paused, care should be taken to avoid clients continuing to send interaction input. Large amounts of buffered input may be processed in a single tick if clients continue to send during a debugging pause and may have a negative impact on the simulation.
Currently you can only debug a single process at a time, if you need to debug more than one process you will need to detach from the first process and connect to the second.
Last modified 6mo ago