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 on the local VM.
Preparing the simulation
In order to debug an Aether Engine simulation within Visual Studio 2019, ensure you have installed the "Linux Development with C++" component, including the "C++ CMake tools for Linux" optional component. You can add these components by launching the Visual Studio Installer from the start menu and choosing 'Modify' for your Visual Studio installation. You will also need to have installed the Aether Engine CLI and virtual machine to debug simulations locally, along with the Visual Studio extension.
When installing the Visual Studio extension, you will be asked to choose a location to install to. After installation this location will contain the
.vsix file that contains the extension, double click this to install the extension into Visual Studio.
Required CMake setup
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
-fno-omit-frame-pointer in your
CMAKE_CXX_FLAGS for your project.
Debugging a simulation
Please review the Important Irregularities and Limitations section before debugging or if you have any issues whilst debugging.
If you do not have an existing simulation you wish to debug, you can use the
aether new command to create a template simulation. 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 adding the
--debug flag to
aether run. By using
aether run --debug you will enable the
hadean::stop() calls to be respected, and Hadean OS will also launch the appropriate additional tooling required to enable a debugger to be attached to your simulation.
Note that for an Aether Engine 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, first identify the process you wish to debug. This can be done with
aether list-paused-processes, which will present the Hadean PID and the reason that process paused. For example, if you add the line
hadean::stop("A collision occurred"); to the physics demo collision callback, then the output of
aether list-paused-processes may look like this:
$ aether list-paused-processesID | Reason----------------- | --------------------127.0.0.1.32684.0 | A collision occurred
Copy the ID of the process you wish to debug, and open Visual Studio. On your toolbar you can see "Connect to Local VM" and "Detach from Hadean Process" buttons. Note that the ID should be treated as an opaque string, and is subject to change.
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".
A message box will be presented that allows you to input the ID of the process to connect to. Type or paste the ID of the process you wish to debug and click "Connect". Note that occassionally this Window can start behind the Visual Studio window, in which case you can use the Windows Taskbar to activate it.
Visual Studio then 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
If your simulation stops on a
hadean::stop() call, but you wish to continue the simulation without attaching a debugger, then you can run
aether 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.
Important Irregularities and Limitations
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
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.
If the simulation becomes "stuck", for example if the simulation starts but produces no logs, it may be necessary to restart the VM.