Dev Notes

Software Development Resources by David Egan.

Build Bitcoin Core in Ubuntu


Bitcoin
David Egan

This article describes how to clone, configure, make and install Bitcoin Core on a newly installed Ubuntu 20.04 Focal Fossa operating system.

If you’re not a native Linux user, you could consider building and running Bitcoin Core in a Linux virtual machine using something like VirtualBox or a suitable Docker image.

Install Required Build Tools

There are a number of software tools that are necessary for the build process.

Assuming a completely fresh Ubuntu install, you need to install the required build tools, as outlined in doc/build-unix.md:

sudo apt git install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3

Clone Bitcoin Core

Clone the Bitcoin Core codebase and move into the project directory:

git clone https://github.com/bitcoin/bitcoin.git
cd bitcoin

Dependencies

Bitcoin Core has a number of dependencies - it relies on other pieces of software to work and these must be available when compiling Bitcoin Core binaries.

You can either:

  1. Install dependencies system-wide using the Ubuntu package management system - see the following note for a caveat
  2. Build them yourself and reference them appropriately during the Bitcoin Core build process

The second option may be best if you need to ensure compatibility with wallets generated by the distributed binaries, which are compiled with BerkeleyDB version 4.8.

This is incompatible with the version of BerkeleyDB distributed by Ubuntu - which is likely to be version 5.1 or greater. This means that if you use the Ubuntu package manager to install BerkeleyDB (using sudo apt install libdb-dev libdb++-dev) the wallet that you generate will be incompatible with wallets generated by the distributed binaries.

If you choose to do this, you’ll need to pass the --with-incompatible-bdb option to the configure script. I’ve also had problems in the past with incompatible Boost library versions - so if you’re building Bitcoin on a development machine, it might be better to build dependencies. If you do self-build dependencies, you avoid all incompatibility hassles. On the other hand, the build process for dependencies adds to the total build time considerably.

If you are building from self-compiled dependencies, skip the “install required dependencies” in the Bitcoin Core build-unix.md instructions.

Build Dependencies

To build dependencies for the current architecture & OS, move into the depends subdirectory and:

  1. Install dependencies required for the build process
  2. Run make
# Move into the depends subdirectory
cd bitcoin/depends

# Install the tools required in order to build dependencies 
# Some of the dependencies may already have been installed - if this is the case, they will be ignored by `apt` (or `apt-get`) so don't worry about it.
sudo apt install make automake cmake curl g++-multilib libtool binutils-gold bsdmainutils pkg-config python3 patch

# Bitcoin core provides a suitable Makefile that makes self-building of dependencies straightforward: 
cd ~/bitcoin/depends
make

At this point you may want to go and make a cup of tea because this step is going to take some time. Amongst other packages, this process downloads and builds:

  • Berekely DB 4.8.3
  • Boost 1.70.0
  • QT
  • QR Encode

Once the process has finished, you will have an architecture/OS specific directory in the depends subdirectory.

In the case of Ubuntu 20.04 on a modern PC with an x86 processor, this will likely be in a directory named x86_64-pc-linux-gnu.

To configure for building, move back up into the project directory:

cd ..

Configure

The configure command creates the necessary Makefiles. It allows you to configure(!) the build process.

To generate the configure script, move into the bitcoin core project directory and run:

./autogen.sh

The configure script guesses values for system dependent variables. If you have self-built dependencies you need to set the --prefix command option to the directory that was created when building dependencies (i.e. when make was run in the depends sub-directory). This tells the configure script to pick up libraries, tools and settings from the depends build: --prefix=PREFIX instructs the configure script to install architecture-independent files in PREFIX.

It also means that the generated binaries will be located in a bin subdirectory of the prefix dir.

# Run configure for self-built dependencies
# From the bitcoin core directory
./configure --prefix=$PWD/depends/x86_64-pc-linux-gnu

By default, the generated Makefile includes the compile flags -g -O2 - the build includes debugging symbols and is optimized for code size & execution time. You can change this by passing an option to ./configure:

# Compile without debugging symbols
./configure CXXFLAGS="-O2"

If the config script completes successfully, you are ready to run make to build the executables.

Make

Run make to build bitcoind and bitcoin-qt if dependencies are met.

If the make process is successful, the following binaries can be found in the src directory under the project root:

  • bitcoind
  • bitcoin-cli
  • bitcoin-tx
  • bitcoin-wallet

…and in the src/qt subdirectory:

  • bitcoin-qt

Make bitcoind & bitcoin-qt System Commands

This can be achieved by symlinking the executables in a directory that is present in your command search path: $PATH.

For our purposes, usr/local/bin is a good choice:

sudo ln -s ~/bitcoin/src/bitcoin{d,-cli} /usr/local/bin
sudo ln -s ~/bitcoin/src/qt/bitcoin-qt /usr/local/bin

Alternatively, run sudo make install in the project core directory after making the project.

Full Install Instructions, Installed Dependencies

If you’re not worried about wallet compatibility, the commands below are probably the easiest way to build a Bitcoin Core node.

Complete commands to install Bitcoin Core on a new Ubuntu 20.04 installation

# Update OS before starting
# -----------------------------------------------------------------------------------------------------------
sudo apt update && sudo apt upgrade

# Install Dependencies
# -----------------------------------------------------------------------------------------------------------
# Build requirements:
sudo apt install git build-essential libtool autotools-dev automake pkg-config bsdmainutils python3

# Install required dependencies
sudo apt install libevent-dev libboost-system-dev libboost-filesystem-dev libboost-test-dev libboost-thread-dev

# Install the BerkeleyDB from Ubuntu repositories:
sudo apt install libdb-dev libdb++-dev

# Optional: upnpc
sudo apt install libminiupnpc-dev

# Optional ZMQ:
sudo apt install libzmq3-dev

# For GUI:
sudo apt install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools

# For QR Code support
sudo apt install libqrencode-dev

# Install Bitcoin
# -----------------------------------------------------------------------------------------------------------
git clone https://github.com/bitcoin/bitcoin.git

# Move into project directory
cd bitcoin

# Config
# -----------------------------------------------------------------------------------------------------------
# Generate config script
./autogen.sh

# Configure, with incompatible BerkeleyDB
./configure --with-incompatible-bdb

# If debugging symbols not required, amend compile flags:
./configure --with-incompatible-bdb CXXFLAGS="-O2"

# ...lot's of checking...

# Make
# -----------------------------------------------------------------------------------------------------------
make

# Install - sudo is required to install binaries in /usr/local/bin
sudo make install

Developer Notes

If you’re intending to work on Bitcoin Core, you should fork a copy on GitHub, before cloning and building your own fork.

It you do this, you’ll need to keep your fork in sync with upstream development.

Configure Remote

Check current remotes:

git remote

This will probably output origin, denoting that your repo has a single remote.

Configure a Git remote for the upstream (original) repo:

git remote add upstream https://github.com/original-project/original-project.git

Check:

git remote

# Output:
origin
upstream

Sync Local Fork with Upstream

There are now three repositories:

  • local
  • origin (GitHub, Bitbucket etc)
  • upstream (The original repo)

Sync from upstream to local, then push changes to origin:

# fetch changes
git fetch upstream

# switch to master branch
git checkout master

# Merge changes from upstream into master
git merge upstream/master

# Push local changes to origin
git push

References

comments powered by Disqus