Debugging Simutrans

After learning to compile Simutrans, you may wish to change the code and see how it affects the game. As part of this process, it can be helpful to use a performance profiler. This stops the game many times every second to see which part of the code was just processed by the CPU(s) and then summarizes the totals. In this way, you can see what parts of the code are doing the most work.

Setting up Simutranslink

This guide assumes you have already know how to compile Simutrans link-external and you have compiled a debug version (uncommenting “DEBUG = 3” in config.default).

If you want to be able to read more debugging messages in simu.log, you can also set MSG_LEVEL = 3, but this will mean that you are profiling the debug build. In most cases you want the build that you are profiling to be as close as possible to a ‘normal’ build.

For debugging, you have to set the correct working directory, i.e. the directory where the pak/folders are located and use the -use_workdir command line option. You can also copy the /build/default/sim executable to your game directory. Changing the name to something like “simutrans-debug” is also recommended, to avoid any confusion.

Debugging on Windows with mingwlink

I recommend to run drmingw -i once in a shell. You will get a caller history in case of an error; gdb does not really work well and is a pain to use with the text interface.

Debugging on Linux with perflink

Installing perflink

We are going to use the perf profiler, which is also used for profiling the Linux kernel.

On Ubuntu/Debian
Open a terminal and run:
sudo apt install perf

If you are lucky, perf may install immediately. But in Ubuntu, you will get an error message talking about your kernel version, presumably because perf is tightly tied to the kernel. Note your kernel version: we will use 5.4 as an example. Run this command, adjusted for your version number:
sudo apt update
sudo apt install linux-5.4-tools-common
sudo apt install linux-tools-common

If that doesn’t work and you are using another Debian distribution, try this instead (remembering to use your kernel version):
sudo apt install linux-perf-5.4

sudo zypper ref
sudo zypper in perf

Arch Linux / Manjaro
sudo pacman -Syu perf

Using perf to measure Simutranslink

Open a terminal in your game directory and run:
sudo perf record -g ./simutrans-debug

Simutrans will load and you can play-test your changes. As you do this, perf will measure the game’s performance and generate logfiles. For reasons that will become clear later, you can only play for a short time: from my limited experience, perhaps one minute for every GiB of RAM in your system. If you want to test on a new map, it might be better to make your map before you start profiling. When you have reached your time limit, exit Simutrans in the normal way (saving if you want to).

It is common for Simutrans to crash when you are testing new code. When you are using perf, you may not be able to close a crashed program in the usual ways. If your build has “simutrans” in its name, then you can close the crashed Simutrans using pkill command:
sudo pkill -9 simutrans

Once this is done, perf will save its logs and close.

Convert the perf logs into an ASCII graphlink

We now need to convert those logs into something humans can understand. This conversion requires very large amounts of RAM, hence the one minute of play per 1 GiB of RAM rule of thumb. You may need to shut down your browser and other RAM-hungry programs during the conversion.
The traditional approach is to analyze the results as an ASCII graph. To do this, run the following in your game directory:
sudo perf report -g graph,0.05 --stdio > graph

After several minutes, this will generate a text file called graph that can be opened in any text editor. It’s possible to stop here. However, the graph is difficult to read, so the following steps will describe how to create an alternative called a flamegraph. But I recommend making an ASCII graph once to check that perf is working correctly, and that you have enough RAM, before you continue.

Install Perl and flamegraphlink

Most Linux distributions install the Perl programming language by default, but if you don’t have it for some reason, then do it.

On Ubuntu/Debian:
sudo apt install perl

Now download these Perl scripts to your game directory:
Which were written by Brendan Gregg and are distributed under the CDDL link-external.

Convert the perf logs into a flamegraphlink

Open a terminal in your game directory and run:
sudo perf script | ./stackcollapse-perf.pl > out.perf-folded
sudo grep -v cpu_idle out.perf-folded | ./flamegraph.pl > debug.svg

Again, this conversion will take several minutes, though it requires less RAM than the traditional method.

Those commands should exclude functions which are stalled while waiting for I/O, so the results are biased towards ordinary play and away from the start-up process (especially if you are using a traditional hard drive). If loading and saving paksets or savegames is the part of Simutrans that you are interested in, then you may need to adjust this step.

Open your flamegraphlink

Open a new tab in a web browser (Firefox/Chrome) and load debug.svg from your game directory. Scroll down, and you should see a brightly-coloured graph. Although image viewers can also open SVG files, you need to use a browser to access the interactive elements.

The X axis shows how much time your CPU is spending on each function. For example, if half the X axis is used by main, then your CPU is spending half its time running that function. Note that the X axis is not chronological: it is showing you ‘how much’, not ‘when’.

The Y axis shows the relationship of different functions to each other. For example, the only real job of main() to call sysmain, which is therefore stacked on top of it.

You can hover over functions to see the exact percentage of CPU time that they used. You can click on functions to zoom in on them; you can zoom out again in the top left-hand corner. You can find particular functions using Ctrl+F or the ‘Search’ text in the top-right hand corner (click on ‘ic’ to toggle case sensitivity). This is essential for many Simutrans functions. Some functions are called by multiple functions (especially the _tpl templates), so use Search to make sure that you have identified all the calls. You can reset Search in the top right-hand corner of the graph.
Rate this page:

Contributors to this page: Roboron3042 .
Page last modified on Tuesday September 29, 2020 14:55:47 GMT-0000 by Roboron3042.

Online Users

14 online users

Newest Forum Posts

No records to display