Running Bitcoin Valgrind Tests on macOS with Docker

Getting Valgrind running on macOS can be tricky. One of the easiest methods is to use Louis Brunner's patch, however, Big Sur is not currently supported.

Instead, we can use Docker to run Valgrind from within a virtualized Ubuntu environment.

Installing Docker

You can install Docker Desktop by using homebrew:

brew install --cask docker

or from Docker's website.

Create Dockerfile

Create a new directory and a file named Dockerfile within it. The contents of the file should be as follows:

FROM ubuntu:16.04

RUN apt-get update
RUN apt-get upgrade -y
RUN apt-get install git build-essential valgrind automake libtool -y

WORKDIR /bitcoin

CMD ["/bin/bash"]

ubuntu:16.04 can be replaced by an operating system and version of your choosing, and the dependencies installed by apt-get can be altered as well. The instructions provided above are sufficient to build the bitcoin tests and run Valgrind.

WORKDIR /bitcoin will set the working directory to the one that will be linked to the local bitcoin repository when we run the image.

CMD ["/bin/bash"] will execute bash so that we can access an interactive shell, by default, upon running the image.

Build Image

Build the image by executing the following command from the same directory as the Dockerfile:

docker build -t bitcoin .

Run the Image

Run the image by executing the following command:

docker run -it -v /path/to/local/bitcoin-repo:/bitcoin bitcoin

Be careful because any changes you make to /bitcoin from within the docker image will be written to the same directory with which it is linked.

Build Bitcoin

Build bitcoin in the docker environment:

make clean
./autogen.sh
./configure
make -j"$(($(nproc)+1))"
make -j"$(($(nproc)+1))" check

Run Valgrind

valgrind --error-exitcode=42 --track-origins=yes ./tests 16

You can also use vgdb to allow gdb debugging on errors:

valgrind --error-exitcode=42 --track-origins=yes --vgdb-error=1 ./tests 16

You'll need another terminal session from which to run gdb. One way to accomplish this is to install tmux:

apt-get install tmux

Once you have tmux installed, you can start a session and split the window vertically by pressing Ctrl+b and %. You can switch between panes with Ctrl+b and o. When Valgrind triggers an error it will include instructions for gdb:

==5734== TO DEBUG THIS PROCESS USING GDB: start GDB like this
==5734==   /path/to/gdb ./tests
==5734== and then give GDB the following command
==5734==   target remote | /usr/lib/valgrind/../../bin/vgdb --pid=5734

In gdb you can step through your code and print state.