Bitcoin Core Development on MacOS — A Step by Step Guide
By: Matthew Ward
Tags: Bitcoin Core, Education, Company, Bitcoin, Guides And Tutorials

Background

CoinCorner is a UK Bitcoin exchange founded in 2014 — we’re a small, dedicated team of Bitcoin enthusiasts.

Last summer, we were finally in a position as a company (over the years we’ve chosen to stay independent and not take VC/institutional investment, but that’s a whole different story…) where we could begin to assign some of our team’s resources to giving back to the community/industry. We began a number of projects — one being an introduction to core development for our tech team — in the hope that they would not only continue to contribute in their own time, but also help to encourage others to get involved.

The tech team assigned 2 hours per week to slowly delve into the Bitcoin Core code and development process. We worked together to eventually begin to understand the masterpiece that is Bitcoin and fixed some issues within the code. 4 of the team have now contributed to the latest version of Bitcoin Core —myself, Zakk, Danny, and Jeremy.

Please be aware that this guide is a very basic flow of how you would go about beginning to contribute to Bitcoin Core. This may not be the best, most efficient or in some people’s opinion even the correct way, but it’s the route we’ve taken so far!

CoinCorner’s Bitcoin Core Contributors

Introduction

In this article, we’ve produced a step-by-step guide for contributing code to Bitcoin Core, allowing developers with little to no experience within Bitcoin development to learn the basic process and start their Bitcoin Core development career.

Developing with Bitcoin Core can seem daunting at first, especially if you don’t have experience with some of the technologies used by Bitcoin Core, such as Git or C++. Don’t worry though, as long as you have some programming knowledge and experience, your first pull request will be a breeze.

Bitcoin is open-source and contributed to by developers from around the world — anyone can contribute and at different levels. We, of course, want more coding geniuses to work on Bitcoin. What’s great about Bitcoin is that it’s so vast with various technologies that you can contribute in many different ways.

The industry is always screaming for more contributors, whether that’s just reviewing or testing, every little helps! So, with a very strong tone here, “Don’t be scared to jump in!”.

Prerequisites

Firstly, you’ll need a MacOS computer, with at least 3GB of free disk space (some of the dependencies will require more space, but you may have these installed already).

You’ll need a GitHub account (sign up for a free one here) in order to create a fork of the repository, create pull requests and comment on issues.

Creating your own fork

Make sure you’re signed in to GitHub and then navigate to https://github.com/bitcoin/bitcoin and click “Fork” in the top right corner.

Essentially, this will create your own copy of the Bitcoin code, that you can modify freely in your own environment. Any changes made to this fork won’t affect other developers.

This “copy” is attached to your GitHub account, so you can access this from anywhere, on any computer.

Downloading to your local environment

To edit, build and debug the code, you’ll need to have your fork available to you locally. To achieve this, you’ll need a Git client. There are many options available, so feel free to use anything you have previous experience with, or research the client best for you.

At CoinCorner, we’ve used two popular clients: GitHub desktop and the Git CLI. After using both with Bitcoin Core, we recommend the CLI for now, as GitHub Desktop has a few issues and isn’t as powerful as the CLI. (Please note: if you use the CLI, you’ll need to have basic knowledge of a computer terminal — there are many resources online to teach this and it’s a simple concept to learn).

To install the Git CLI, open a terminal and type “ git --version ”. If it’s installed, it will respond with a version number. If not, it will prompt you to install.

Some versions of Mac won’t prompt you to install at this point however, so if this fails, you can download the .dmg from https://git-scm.com/download/mac. Just run through the installer like a normal .dmg and restart your computer after installation.

Open a new terminal window and navigate using ‘ cd path/to/folder ’ to the folder you want to download Bitcoin Core to (e.g. ‘ cd /Documents ’). Create a Bitcoin directory by typing ‘ mkdir bitcoin ’. Navigate again to this new directory by typing ‘ cd bitcoin ’.

Next, run the following command: ‘ git clone https://github.com/bitcoin/bitcoin.git ’

This will download the code to your computer. It should only take a few minutes depending on your internet speed.

Installing dependencies

We used this guide to help install Bitcoin Core on Mac, so feel free to use this and come back after the installation is complete, or keep reading and follow our similar guide.

To build Bitcoin Core on Mac, you need quite a few third-party dependencies.

Start by installing Xcode CLI Tools by running this command in a terminal window: ‘ xcode-select --install ’. This will bring up a pop-up window that will ask permission to install.

If you usually develop software on your Mac, you may already have homebrew installed. However, if not, follow these steps to install.

There are many dependencies that Bitcoin Core relies on but with Homebrew, you can easily install most of these with one command.

Run: ‘ brew install automake berkeley-db4 libtool boost miniupnpc pkg-config python qt libevent qrencode ’ in a terminal window. This might take a while, so grab a coffee while you wait.

If you want to be able to build a disk image (.dmg) file, you’ll also need to install RSVG with the following command: ‘ brew install librsvg ’.

Make sure you’re in the root of your repository (‘bitcoin’ folder) in a terminal window, and run the following command: ‘ ./contrib/install_db4.sh . ’.

Please note: This command only needs to run if the wallet is enabled, which we don’t disable the wallet in our builds. The wallet would be disabled if your intention is to run a P2P node without a wallet, but since we’re writing code, we’ll want to keep the wallet enabled.

Note: If you’re having issues with some commands, make sure you’re not running this on an exFAT or a FAT32 partition, as this can cause some issues with file permissions.

Now that you’ve installed each dependency, it’s time to build the code for the first time and get your development version of Bitcoin Core running.

There are several commands that should be used, giving you access to several different build states.

For now, here are the main commands you’ll be using to run unit tests on your code and build an executable.

./autogen.sh — Prepares the files for build (based on your platform) and creates configure file. ./configure — Creates make file, allowing ‘make’ commands to run. make — Builds (this might take a while). make check — Builds and runs unit tests. make deploy — Builds and creates a deployable application.

When running the ‘make’ command, it’s recommended to also run the unit tests along with it. This can be done by writing ‘ make check ’.

Unit testing is a great way to check you haven’t accidentally broken any existing functionality when writing code by automatically testing most logic code. More details can be found here.

Run each of these 5 commands in the root of your repository (the Bitcoin folder you created before) in order for full testability.

Branching for each feature

Git comes with a handy feature that keeps different changes separate before they’re ready to be merged into master. This is called ‘branching’ — it essentially creates a separate copy of the codebase from a specified point in time.

It’s a good idea to create a branch for each feature/bug request that you work on as it gives a more organised structure and makes it easier to find historical changesets. It also allows you to move freely between development tracks with only one command.

Before creating your branch, check you’re on the master branch by entering the following command: ‘ git branch ’.

Next, update your master to the latest remote commit using these two commands:

‘ git fetch origin ’

‘ git pull ’

Now you’re up to date, you can create your new branch (remember to give it a short, but still descriptive name that will be easy to refer back to in future. E.g. Dec-19-remove-fee-label). Type the following command: ‘ git checkout -b name_of_new_branch ’

Using testnet/regtest

Instead of downloading the mainnet blockchain to test with and possibly corrupting the blocks for yourself (trust me, it takes too long to download each time if you’re just developing), you can use either the testnet or regtest.

The testnet allows you to use a real blockchain with other developers/testers, but you can use public faucets to give yourself coins.

However, please don’t abuse these faucets — only take what you’re going to need to test with. Consider sending the coins back when you’re finished.

To use testnet, simply add ‘ -testnet ’ to the command when running the bitcoind (see section “Running CLI or GUI” below for details), or if you’re running the GUI, add ‘ testnet=1 ’ to your bitcoin.conf file.

To edit your bitcoin.conf file, navigate to ‘ /Users/<username>/Library/Application Support/Bitcoin/bitcoin.conf ’ and right click the ‘bitcoin.conf’ file, opening it with a text editor (such as Text Edit). (Please note: if you edit this, you must restart Bitcoin Core before changes can take effect. This file may also not exist yet. If it doesn’t, simply create a file named ‘bitcoin.conf’ and you can edit this freely).

Regtest is slightly different given the fact that you have your own private blockchain and can create blocks / give yourself coins via the command line (it’s essentially god mode). This blockchain isn’t shared with other developers, so feel free to use this as a learning tool.

For more information, visit here.

Exploring issues

Now you should be raring and ready to go with Bitcoin Core development.

There are two routes you can go down when deciding what to develop if you’re not already clear on the changes you want to make.

You can either explore the active issues on GitHub, or you can use the application for a while and find bug fixes/improvements that might be helpful.

If you choose the latter, create an issue for any changes you might want to make so you can discuss it with other developers first.

Finding the perfect issue to work on can be made easier by using the labels that are attached to each issue. We would recommend two labels for your first issue, both the good first issue and the GUI labels. The first is self-explanatory, and the GUI issues are usually quite easy to wrap your head around if you’re not an experienced C++ developer.

You can filter the issues and sort them by open/closed in the toolbar at the top.

To get an idea for the kind of first-issues you can begin with, take a look at one of my first pull requests. It’s a very simple documentation change, but it allowed me to get used to the whole process and I learned about the structure of the Bitcoin repo at the same time.

The actual change — https://github.com/bitcoin/bitcoin/pull/17157/files

Running CLI or GUI

By now you should have found an issue you want to work on/change you want to make. This issue will define whether you should be running the CLI or the GUI.

Running the GUI on Mac requires the RSVG library we talked about before. After you run ‘ make deploy ’, a .dmg file should appear. Treat this as one you might have downloaded before and install it into your applications folder.

Running the CLI on Mac is as simple as running ‘ ./src/bitcoind -daemon ’ in your development folder, after you’ve successfully run ‘ make check ‘. (Remember to add -testnet to this command if you’re running testnet.)

Running ‘ ./src/bitcoin-cli --help ’ will output a list of commands that you can use.

Committing change

Once you’ve made a valuable change and have tested it works, you can commit this change to your forked repo. This is the first step in getting your code change into the master Bitcoin repository.

Before doing this, you’ll want to do two things. Add the master Bitcoin repository to your upstream (meaning you pull any new changes from the Bitcoin remote repository when you get the latest version) and then sync these changes.

Start adding the upstream by running this command ‘ git remote add upstream https://github.com/bitcoin/bitcoin.git ’.

You can then pull any changes with this command: git pull upstream

(Note: You may need to make some merges. Don’t remove anyone else’s changes or your pull request will be denied.)

Now you’ve synced all new code changes from the upstream repository, you can commit your changes.

To begin, use this command to commit to your local git repository: ‘ git commit -a -m “Insert Informative Commit Message Here” ’.

Then use this command to push to your forked repository in GitHub: ‘ git push origin ’.

Creating a pull request

Jump back over to GitHub now to create your pull request on the Bitcoin repository.

Go to the Bitcoin repository and click “new pull request”.

Since we’ve made the change in a different repository on GitHub, we need to click “compare across forks”.

This will give you access to choose from different repositories. Under “base repository”, choose your own repository, and under “base” choose your branch that you made the changes on.

This should bring in your changes into the section below.

Read through the help text in the text field, as this will tell you what you need to write, to make your pull request useful. Fill out this field in as much detail as possible for your change and click “Create Pull Request”.

If all goes well, your pull request will be merged into the master branch. This will mean your change has been accepted and will go live in the next release of Bitcoin Core (which is roughly every 4-6 months).

Additional changes to Pull Request

Once your code has been reviewed, another developer might ask you to make changes to your code. If this happens, the commit process will be slightly different.

Firstly, you won’t need to make another pull request as long as you commit this change to the same branch that you created earlier. The one that you made your changes on.

Secondly, after you make the new change you’ll need to squash your commits and rebase.

After you’ve made this change, commit it with ‘ git commit -a -m “Insert Informative Commit Message Here” ’.

Then, before pushing the commit to the remote repository, you need to rebase ‘ git rebase -i HEAD~n ’.

Replace “n” with the number of commits in the pull request (if you have only made one commit before this, replace with 1. E.g. ‘ git rebase -i HEAD~1 ’).

Next, set commits (except the one in the first line) from ‘pick’ to ‘squash’, save and quit. On the next screen, edit/refine commit messages, and save and quit.

After you’re done, you need to force push this to GitHub with the following command: ‘ git push -f # ’.

This should be automatically picked up by your pull request.

Double check the pull request has updated with the new change, then comment that you’ve made the change and “squashed & rebased”. Ask for a review on the change again and another developer should pick it up.

Peer reviews

As Bitcoin is open-source software, most developers are working on it in their spare time. This might mean peer reviews on your issue/pull request can take a little while longer than traditional feedback you may be used to. Be patient and make sure that when you’re responding to anybody, you’re descriptive of what you’re trying to say and you’re polite.

At first, some of the terms developers might use on GitHub may be rather confusing. Here is a quick glossary of some terms you might see:

Concept ACK — Agrees with the change but hasn’t reviewed/tested any code.

— Agrees with the change but hasn’t reviewed/tested any code. ACK — Change acknowledged (very loose term).

— Change acknowledged (very loose term). NACK — Change not acknowledged.

— Change not acknowledged. utACK — Change acknowledged and code briefly reviewed but not tested the code.

— Change acknowledged and code briefly reviewed but not tested the code. Tested ACK — Changed acknowledged and code reviewed/tested.

— Changed acknowledged and code reviewed/tested. NIT — Small imperfection.

Code formatting

If you’ve worked on open-source software before, you’ll know that the formatting of your code is important. Developers like consistency, so it’s vital that you follow the same formatting rules as everyone else.

As a quick overview, Bitcoin Core follows these basic rules when writing code:

Braces on new lines for classes, functions and methods. The same line for everything else.

4 space indentation (no tabs)… This one is controversial 😉

No spaces in parenthesis ‘ ( string NotLikeThis ) ’ but (string LikeThis)

’ but ‘++i ’ instead of ‘ i++ ’.

You can read a full description of the code formatting that Bitcoin uses here. This is well worth a read if you’re looking to do multiple pull requests.

IRC chat for help

If you get to a stage where you’re stuck, you can find other Bitcoin developers on the IRC development channel. Feel free to ask any questions you may have here, somebody will always be online, ready to help.

Don’t feel awkward asking questions. Everyone has to start at some point and asking experienced Bitcoin developers for help is a great way of learning.

Tips and tricks

Jameson Lopp has created a handy tool to generate bitcoin.conf files, for whatever you may be developing at the time.

What next?

Keep working on more issues, gradually try and push yourself out of your comfort zone and pick issues that confuse you at first. You’ll quickly get the gist of it.

You can also review/test other developers’ code/pull requests. The more developers that test code, the less likely bugs are going to fall into the system. It’s helpful to other developers and is a good way of getting your name out there.

Bitcoin has a mailing list for developers to talk about new/controversial features. You can join this and become part of the bigger discussion. Find out more here.

You can also read old BIPs (Bitcoin Improvement Protocol) on GitHub. BIPs are a way for Bitcoin developers to propose large changes to Bitcoin RPC and Bitcoin Core.

Spend some time sitting and reading through some of the existing code, and especially reading the comments. Try to understand what the code might be doing, even if you’re not quite sure. Search around the Bitcoin forums for what features might be doing, and ask the IRC chat for explanations into what functions might be for.