# Developer's Guide for Debugging Radare2

This document explains common development practices used to debug radare2
in order to find, identify and fix bugs, memory corruptions, leaks or race
conditions.

## Compilation

When changing your code you need to rebuild r2 to test it. In case you use ACR/Make
you just need to type `make` in the directory where you changed the code. But if you
use `meson` you must run `ninja -C ../../b` instead.

Bear in mind that meson tracks source dependencies more deeply than acr/make, so it's
possible that for some changes in `.h` files `meson` builds will require a full
recompilation, while `make` could just be faster and handier.

The reason why source build changes are available system wide is because the default
installation method `./sys/install.sh` uses `sudo make symstall` which creates
symlinks instead of copying the executables, libraries and support files to $PREFIX.

Other important `CFLAGS` are:

* `-Wall` - show more warnings useful to improve code quality
* `-Wshadow` - show if you have variables with the same name in nested scopes
* `-w` - in case `-Werror` is set, stop treating warnings as errors

## Multiple r2

In order to develop for r2 it is common to have two or more builds of radare2,
so you can compare `master` behaviour with your patched code at any time.

You can achieve this in different ways, but bear in mind that using `--with-rpath`
for meson or acr builds is important to avoid having one r2 using the other r2's
libraries.

* Use ACR source build for your patched code
* Keep a --with-rpath meson build in a custom directory for running it
* Statically build r2 (`sys/static.sh`)
* Use `r2env` to switch between release or git builds

## Symbols

By default radare2 is compiled with debug symbols, but in case the source-line
information is not available you may want to set the `CFLAGS=-g` before calling
`./configure` or `meson b`.

## ASAN

Stands for Address Sanitizer and it's a compiler plugin available for clang, gcc
and msvc that adds extra checks in the generated binary, which permits to identify
many types of bugs.

* undefined: behaviour (binary operations on signed variable)
* memory: uninitialized variables (compiler warnings may catch that too)
* thread: sanitizer - detect race conditions and deadlocks
* address: memory corruption, read and write overflows
* leak: track memory usage and detect memory leaks

In case you are coming from another branch or another non-sanitized build you may
want to have a clean build dir. To do this, reset your git state into a clean state.

```
$ make mrproper
$ git clean -xdf
$ rm -rf shlr/capstone
```

Works like valgrind, but faster. Use `sys/sanitize.sh` to get that build ready to use.

```
$ export SANITIZE=$leak memory address"
$ sys/sanitize.sh
```

Now you can just run `r2` and get a nice crash report without the need of a debugger.

But it is also compatible with any debugger like `gdb` or `lldb`.

## Valgrind

It's a Linux tool that pseudo-emulates programs in order to detect runtime memory
corruption problems and other types (like the ones listed above).

Valgrind was working on macOS and other BSDs, but it lacks for that porting. So
we may want to use it only when we are on Linux and we dont want to modify the
binary we want to execute.

There are different *plugins* that can be used for different purposes:

### Memory Profiling

By default *valgrind* will identify `undefined behaviour`, `memory corruptions`,
`race conditions` and more. Just call it like this:

```
$ valgrind r2 /bin/ls
```

### Time Profiling

Identifying bottlenecks is an important thing to do when looking for optimizations.
This can be achieved with `callgrind` which is a plugin for tracing function calls
and profile the time spent on them, specifying how many times are called.

```
$ valgrind --tool=callgrind --dump-instr=yes --simulate-cache=yes --collect-jumps=yes \
    /usr/local/bin/r2 /bin/ls
```

To visualize the generated logs use `kcachegrind`

```
kcachegrind callgrind.*
```

## GPerfTools

This package can be used on macOS or Linux systems and uses *tcmalloc* to track heap
allocations and create a graph with the memory allocated by each function during the
execution.

```
$ brew ls gperftools
$ DYLD_INSERT_LIBRARIES=/opt/homebrew/Cellar/gperftools/2.9.1_1/lib/libtcmalloc.4.dylib \
  HEAPPROFILE=/tmp/b.txt \
  r2 /bin/ls
$ pprof --web /usr/local/bin/radare2 /tmp/b.txt*
```

## Frida-Trace

One of the tools shipped with `frida` is `frida-trace`, and allows us to trace function
calls easily, and visualize their arguments, what they return and its backtraec.

```
$ frida-trace -i 'r_core_cmd*' r2 /bin/ls
```

## Debuggers

You can also debug r2 using `gdb`, `lldb`, `x64dbg` or any other debugger you like.

Launching lldb and r2 in the same terminal it's usually handy, unless you are going to debug
a bug in visual or panels mode, because the terminal configuration may be different. In
those cases you may want to attach to the process by calling it with `lldb -p <pidofr2>`

## PD

Read the `DEVELOPERS.md` document for more development and debugging tips!

--pancake