Installation

BTX Node is built from source using CMake. This guide covers Linux (Ubuntu/Debian, Fedora, Arch) and macOS.

Prerequisites

Dependency	Minimum Version	Notes
CMake	3.22	Build system
C++ compiler	GCC 11.1 / Clang 16
Python	3.10	Scripts and tests
Boost	1.73.0	Required
libevent	2.1.8	Required
pkg-config	—	Required

Optional dependencies

Dependency	Purpose	CMake flag
SQLite 3.7.17+	Descriptor wallet	-DENABLE_WALLET=ON (default)
Berkeley DB 4.8	Legacy wallet	-DWITH_BDB=ON
Qt 5.11.3+	GUI	-DBUILD_GUI=ON
ZeroMQ 4.0+	Pub/sub notifications	-DWITH_ZMQ=ON
miniupnpc 2.1+	UPnP port mapping	-DWITH_MINIUPNPC=ON
libqrencode	QR codes in GUI	-DWITH_QRENCODE=ON

---

Linux

Ubuntu / Debian

Install required build tools and libraries:

sudo apt-get install build-essential cmake pkgconf python3
sudo apt-get install libevent-dev libboost-dev

For descriptor wallet support (recommended):

sudo apt-get install libsqlite3-dev

Optional packages:

# ZMQ notifications
sudo apt-get install libzmq3-dev

# UPnP port mapping
sudo apt-get install libminiupnpc-dev

# GUI (Qt 5)
sudo apt-get install qtbase5-dev qttools5-dev qttools5-dev-tools librsvg2-bin imagemagick

# QR code support (GUI)
sudo apt-get install libqrencode-dev

# USDT tracing
sudo apt-get install systemtap-sdt-dev

Fedora

sudo dnf install gcc-c++ cmake make python3
sudo dnf install libevent-devel boost-devel

For descriptor wallet support:

sudo dnf install sqlite-devel

Optional packages:

# ZMQ notifications
sudo dnf install zeromq-devel

# UPnP port mapping
sudo dnf install miniupnpc-devel

# GUI (Qt 5)
sudo dnf install qt5-qttools-devel qt5-qtbase-devel librsvg2-tools ImageMagick

# QR code support (GUI)
sudo dnf install qrencode-devel

# USDT tracing
sudo dnf install systemtap-sdt-devel

Arch Linux

pacman --sync --needed cmake boost gcc git libevent make python sqlite librsvg imagemagick

---

macOS

Prerequisites

Install the Xcode Command Line Tools:

xcode-select --install

Install Homebrew, then install the required dependencies:

brew install cmake boost pkgconf libevent

macOS ships with a usable SQLite, so descriptor wallets work out of the box.

Optional packages:

# Legacy wallet (BDB)
brew install berkeley-db@4

# GUI
brew install qt@5

# QR codes
brew install qrencode

# ZMQ notifications
brew install zeromq

# UPnP
brew install miniupnpc

---

Building from Source

1. Clone the repository

git clone https://github.com/btxchain/btx.git
cd btx

2. Configure

Basic configuration with default options (descriptor wallet enabled, no GUI):

cmake -B build-btx

To see all available options:

cmake -B build-btx -LH

3. Compile

cmake --build build-btx -j$(nproc)   # Linux
cmake --build build-btx -j$(sysctl -n hw.ncpu)  # macOS

Binaries are placed in build-btx/bin/:

• btxd — the full node daemon
• btx-cli — command-line RPC client
• test_bitcoin — unit test runner

4. Run tests (optional)

ctest --test-dir build-btx -j4

---

Build Options Reference

Flag	Default	Description
-DENABLE_WALLET=ON/OFF	ON	Build with wallet support
-DWITH_BDB=ON/OFF	OFF	Legacy wallet (requires BDB 4.8)
-DBUILD_GUI=ON/OFF	OFF	Build the Qt GUI
-DWITH_ZMQ=ON/OFF	OFF	ZMQ pub/sub notifications
-DWITH_MINIUPNPC=ON/OFF	OFF	UPnP port mapping
-DWITH_QRENCODE=ON/OFF	ON (if GUI)	QR code encoding in GUI

Example — full build with GUI and ZMQ:

cmake -B build-btx -DBUILD_GUI=ON -DWITH_ZMQ=ON -DWITH_BDB=ON
cmake --build build-btx -j$(nproc)

---

Verifying the Build

Check that the binaries run and report the correct version:

./build-btx/bin/btxd --version
./build-btx/bin/btx-cli --version

Run the unit tests to confirm a healthy build:

./build-btx/bin/test_bitcoin

---

Common Build Issues

Out of memory during compilation

C++ compilation is memory-intensive. If you have less than 1.5 GB available per job, reduce parallelism or add compiler flags to reduce memory usage:

# Reduce parallel jobs
cmake --build build-btx -j2

# Or reduce GCC memory usage
cmake -B build-btx -DCMAKE_CXX_FLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"

# Or strip debug info
cmake -B build-btx -DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O2 -g0"

# Or use Clang (often uses less memory)
cmake -B build-btx -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang

SQLite not found

If CMake reports that SQLite is missing and you do not need wallet support, disable it:

cmake -B build-btx -DENABLE_WALLET=OFF

Qt version conflicts (macOS)

Building the GUI may fail if both Qt 5 and Qt 6 are installed. Specify the version explicitly:

cmake -B build-btx -DBUILD_GUI=ON -DWITH_QT_VERSION=5

Functional tests require a symlink

The Python functional tests expect binaries in build/. Create a symlink if your build directory is named differently:

ln -sf build-btx build