ProfilingWesnoth

Linux

When using either scons or cmake to build, there are four options available for profiling which are listed below. For cmake use -DPROFILER=<name>, for scons use profiler=<name>.

gperftools

To use gperftools:

1. Install the packages google-perftools (needed later for running google-pprof) and libgoogle-perftools-dev (needed in order to use the -lprofiler linker option).
2. In a terminal, export the CPUPROFILE variable, such as export CPUPROFILE=./wesnoth-prof.
3. Build any executable while setting either -DPROFILER=gperftools (cmake) or profiler=gperftools (scons).
4. Run the executable and have it do any task(s) as needed to get relevant profiling information.
5. Generate the human-readable profiling output using the command google-pprof <executable> <profiling info> > prof.txt for a text file, or google-pprof -gif <executable> <profiling info> > prof.gif for a viewable gif image.

Unfortunately, the output, whether graphical or text, doesn't provide any labels for what the values mean. For the text output, the columns are:

1. The number of profiling samples in this function
2. The percentage of profiling samples in this function
3. The percentage of profiling samples in the functions printed so far
4. The number of profiling samples in this function and its callees
5. The percentage of profiling samples in this function and its callees
6. The function name

For the graphical output, each square will contain:

1. The namespace/class/method profiled, each of those on a separate line
2. The number of profiling samples in this function
3. The percentage of profiling samples in this function (in parenthesis)
4. The number of profiling samples in this function and its callees
5. The percentage of profiling samples in this function and its callees (in parenthesis)

perf

To use perf:

1. Install the packages linux-tools-common and linux-tools-<kernel version>, ie linux-tools-5.8.0-55-generic.
2. Run perf record <executable>. To do this you will need to either:
   1. Run the executable as root
   2. Switch to root and run echo 2 > /proc/sys/kernel/perf_event_paranoid
   3. Create a new group that has rights to use perf and add your user to it, ie:

cd /usr/bin

groupadd perf_users

chgrp perf_users perf

chmod o-rwx perf

setcap cap_sys_admin,cap_sys_ptrace,cap_syslog=ep perf

Once that's complete, there will be a perf.data file created, and commands like perf report can be run.

gcov

To use gcov:

1. After the executable is built and been executed as needed, there will be many .gcda and .gcno files in the source directory.
2. Generate the human readable information from those files with gcov ./**/*.gcno. This will generate a .gcov file for each source file.
3. Open any gcov file(s) of interest.