Besides using a debugger (e.g. gdb) with the debug build (see below), the SUMO source code offers debugging macros at several locations, which are usually deactivated (e.g., commented out). Activating the macros can yield a detailed program output, that can be configured by given parameters.
Debug Build#
To create debugging symbols during the build, see the build instructions
for your operating system (Linux /
Windows /
macOS). The corresponding binaries
receive the suffix D
(e.g. sumoD
instead of sumo
). The debug
configuration defines a preprocessor macro _DEBUG
that may be used to
encapsulate debug specific code. For simple text debugging, local macros
should be used that can be switched on and off more flexibly, see below.
Local Debug Macros#
The recommended style for inserting reusable debugging code in SUMO is
encapsulation by preprocessor directives. This is done by placing a
#define DEBUG_THIS_CODE
at the beginning of a source (preferably just
below any other #include
or #define
macros). The debugging code
(e.g. some output to std::cout
) should then be surrounded by
#ifdef DEBUG_THIS_CODE
...
#endif
Thus, it can be switched on and off by (un)commenting the
#define DEBUG_THIS_CODE
line.
Sometimes it is useful to combine this with a condition for more specific debugging output. For instance, if only output for the vehicle with ID 'my_new_ferrari' is needed while looping through all vehicles, you should insert a corresponding debug condition
#define DEBUG_COND (veh.getID() == "my_new_ferrari")
(at the same location as the #define DEBUG_THIS_CODE
) and encapsulate
the debug code further as
#ifdef DEBUG_THIS_CODE
if DEBUG_COND {
...
}
#endif
Note that this presupposes that veh
is a reference to the current
vehicle, which is being looped over. It is worth mentioning that you can
also define debug conditions with arguments to become a bit more
flexible. For example:
#define DEBUG_COND(x) (x != 0 && x->getID() == "my_new_ferrari")
...
#ifdef DEBUG_THIS_CODE
if DEBUG_COND(veh_pointer) {
...
}
#endif
Debugging macros already exist at several locations (see some of these before implementing your own):
- src/microsim/MSLane.cpp
- src/microsim/MSLink.cpp
- src/microsim/MSVehicle.cpp
- src/microsim/lcmodel/MSLCM_LC2013.cpp
- src/guisim/GUIVehicle.cpp
- src/guisim/GUILane.cpp
Selection based vehicle debugging#
The header utils/common/StdDefs.h
provides the String
gDebugSelectedVehicle
, which always holds the id of the last vehicle,
which was selected in the GUI, and can be used in the debugging
conditions to obtain a dynamic debugging selection (provided the
corresponding macro is activated).
Debugging external libraries#
Debugging symbols (.pdb
files) are available for some of the external libraries included in SUMOLibraries. To use them in Visual Studio, simply add the path of the desired symbol to the "Symbol file locations" in the Options menu. Do so by going to Tools > Options... > Debugging > Symbols and adding the path to the .pdb
file of the desired external library as a new location (see the example image below). The .pdb
files are usually located in the lib or bin directory, for each library.
Example: Adding the FOX debugging symbol