1UNIX BUILD NOTES 2==================== 3Some notes on how to build Bitcoin Core in Unix. 4 5(For BSD specific instructions, see `build-*bsd.md` in this directory.) 6 7Note 8--------------------- 9Always use absolute paths to configure and compile Bitcoin Core and the dependencies. 10For example, when specifying the path of the dependency: 11 12 ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX 13 14Here BDB_PREFIX must be an absolute path - it is defined using $(pwd) which ensures 15the usage of the absolute path. 16 17To Build 18--------------------- 19 20```bash 21./autogen.sh 22./configure 23make # use "-j N" for N parallel jobs 24make install # optional 25``` 26 27This will build bitcoin-qt as well, if the dependencies are met. 28 29Dependencies 30--------------------- 31 32These dependencies are required: 33 34 Library | Purpose | Description 35 ------------|------------------|---------------------- 36 libboost | Utility | Library for threading, data structures, etc 37 libevent | Networking | OS independent asynchronous networking 38 39Optional dependencies: 40 41 Library | Purpose | Description 42 ------------|------------------|---------------------- 43 miniupnpc | UPnP Support | Firewall-jumping support 44 libnatpmp | NAT-PMP Support | Firewall-jumping support 45 libdb4.8 | Berkeley DB | Optional, wallet storage (only needed when wallet enabled) 46 qt | GUI | GUI toolkit (only needed when GUI enabled) 47 libqrencode | QR codes in GUI | Optional for generating QR codes (only needed when GUI enabled) 48 univalue | Utility | JSON parsing and encoding (bundled version will be used unless --with-system-univalue passed to configure) 49 libzmq3 | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.0.0) 50 sqlite3 | SQLite DB | Optional, wallet storage (only needed when wallet enabled) 51 52For the versions used, see [dependencies.md](dependencies.md) 53 54Memory Requirements 55-------------------- 56 57C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of 58memory available when compiling Bitcoin Core. On systems with less, gcc can be 59tuned to conserve memory with additional CXXFLAGS: 60 61 62 ./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768" 63 64Alternatively, or in addition, debugging information can be skipped for compilation. The default compile flags are 65`-g -O2`, and can be changed with: 66 67 ./configure CXXFLAGS="-O2" 68 69Finally, clang (often less resource hungry) can be used instead of gcc, which is used by default: 70 71 ./configure CXX=clang++ CC=clang 72 73## Linux Distribution Specific Instructions 74 75### Ubuntu & Debian 76 77#### Dependency Build Instructions 78 79Build requirements: 80 81 sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3 82 83Now, you can either build from self-compiled [depends](/depends/README.md) or install the required dependencies: 84 85 sudo apt-get install libevent-dev libboost-dev libboost-system-dev libboost-filesystem-dev libboost-test-dev 86 87Berkeley DB is required for the wallet. 88 89Ubuntu and Debian have their own `libdb-dev` and `libdb++-dev` packages, but these will install 90Berkeley DB 5.1 or later. This will break binary wallet compatibility with the distributed executables, which 91are based on BerkeleyDB 4.8. If you do not care about wallet compatibility, 92pass `--with-incompatible-bdb` to configure. 93 94Otherwise, you can build Berkeley DB [yourself](#berkeley-db). 95 96SQLite is required for the descriptor wallet: 97 98 sudo apt install libsqlite3-dev 99 100To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode) 101 102Optional port mapping libraries (see: `--with-miniupnpc`, `--enable-upnp-default`, and `--with-natpmp`, `--enable-natpmp-default`): 103 104 sudo apt install libminiupnpc-dev libnatpmp-dev 105 106ZMQ dependencies (provides ZMQ API): 107 108 sudo apt-get install libzmq3-dev 109 110GUI dependencies: 111 112If you want to build bitcoin-qt, make sure that the required packages for Qt development 113are installed. Qt 5 is necessary to build the GUI. 114To build without GUI pass `--without-gui`. 115 116To build with Qt 5 you need the following: 117 118 sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools 119 120libqrencode (optional) can be installed with: 121 122 sudo apt-get install libqrencode-dev 123 124Once these are installed, they will be found by configure and a bitcoin-qt executable will be 125built by default. 126 127 128### Fedora 129 130#### Dependency Build Instructions 131 132Build requirements: 133 134 sudo dnf install gcc-c++ libtool make autoconf automake python3 135 136Now, you can either build from self-compiled [depends](/depends/README.md) or install the required dependencies: 137 138 sudo dnf install libevent-devel boost-devel 139 140Berkeley DB is required for the wallet: 141 142 sudo dnf install libdb4-devel libdb4-cxx-devel 143 144Newer Fedora releases, since Fedora 33, have only `libdb-devel` and `libdb-cxx-devel` packages, but these will install 145Berkeley DB 5.3 or later. This will break binary wallet compatibility with the distributed executables, which 146are based on Berkeley DB 4.8. If you do not care about wallet compatibility, 147pass `--with-incompatible-bdb` to configure. 148 149Otherwise, you can build Berkeley DB [yourself](#berkeley-db). 150 151SQLite is required for the descriptor wallet: 152 153 sudo dnf install sqlite-devel 154 155To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode) 156 157Optional port mapping libraries (see: `--with-miniupnpc`, `--enable-upnp-default`, and `--with-natpmp`, `--enable-natpmp-default`): 158 159 sudo dnf install miniupnpc-devel libnatpmp-devel 160 161ZMQ dependencies (provides ZMQ API): 162 163 sudo dnf install zeromq-devel 164 165GUI dependencies: 166 167If you want to build bitcoin-qt, make sure that the required packages for Qt development 168are installed. Qt 5 is necessary to build the GUI. 169To build without GUI pass `--without-gui`. 170 171To build with Qt 5 you need the following: 172 173 sudo dnf install qt5-qttools-devel qt5-qtbase-devel 174 175libqrencode (optional) can be installed with: 176 177 sudo dnf install qrencode-devel 178 179Once these are installed, they will be found by configure and a bitcoin-qt executable will be 180built by default. 181 182Notes 183----- 184The release is built with GCC and then "strip bitcoind" to strip the debug 185symbols, which reduces the executable size by about 90%. 186 187miniupnpc 188--------- 189 190[miniupnpc](https://miniupnp.tuxfamily.org) may be used for UPnP port mapping. It can be downloaded from [here]( 191https://miniupnp.tuxfamily.org/files/). UPnP support is compiled in and 192turned off by default. See the configure options for UPnP behavior desired: 193 194 --without-miniupnpc No UPnP support, miniupnp not required 195 --disable-upnp-default (the default) UPnP support turned off by default at runtime 196 --enable-upnp-default UPnP support turned on by default at runtime 197 198libnatpmp 199--------- 200 201[libnatpmp](https://miniupnp.tuxfamily.org/libnatpmp.html) may be used for NAT-PMP port mapping. It can be downloaded 202from [here](https://miniupnp.tuxfamily.org/files/). NAT-PMP support is compiled in and 203turned off by default. See the configure options for NAT-PMP behavior desired: 204 205 --without-natpmp No NAT-PMP support, libnatpmp not required 206 --disable-natpmp-default (the default) NAT-PMP support turned off by default at runtime 207 --enable-natpmp-default NAT-PMP support turned on by default at runtime 208 209Berkeley DB 210----------- 211It is recommended to use Berkeley DB 4.8. If you have to build it yourself, 212you can use [the installation script included in contrib/](/contrib/install_db4.sh) 213like so: 214 215```shell 216./contrib/install_db4.sh `pwd` 217``` 218 219from the root of the repository. 220 221Otherwise, you can build Bitcoin Core from self-compiled [depends](/depends/README.md). 222 223**Note**: You only need Berkeley DB if the wallet is enabled (see [*Disable-wallet mode*](#disable-wallet-mode)). 224 225Boost 226----- 227If you need to build Boost yourself: 228 229 sudo su 230 ./bootstrap.sh 231 ./bjam install 232 233 234Security 235-------- 236To help make your Bitcoin Core installation more secure by making certain attacks impossible to 237exploit even if a vulnerability is found, binaries are hardened by default. 238This can be disabled with: 239 240Hardening Flags: 241 242 ./configure --enable-hardening 243 ./configure --disable-hardening 244 245 246Hardening enables the following features: 247* _Position Independent Executable_: Build position independent code to take advantage of Address Space Layout Randomization 248 offered by some kernels. Attackers who can cause execution of code at an arbitrary memory 249 location are thwarted if they don't know where anything useful is located. 250 The stack and heap are randomly located by default, but this allows the code section to be 251 randomly located as well. 252 253 On an AMD64 processor where a library was not compiled with -fPIC, this will cause an error 254 such as: "relocation R_X86_64_32 against `......' can not be used when making a shared object;" 255 256 To test that you have built PIE executable, install scanelf, part of paxutils, and use: 257 258 scanelf -e ./bitcoin 259 260 The output should contain: 261 262 TYPE 263 ET_DYN 264 265* _Non-executable Stack_: If the stack is executable then trivial stack-based buffer overflow exploits are possible if 266 vulnerable buffers are found. By default, Bitcoin Core should be built with a non-executable stack, 267 but if one of the libraries it uses asks for an executable stack or someone makes a mistake 268 and uses a compiler extension which requires an executable stack, it will silently build an 269 executable without the non-executable stack protection. 270 271 To verify that the stack is non-executable after compiling use: 272 `scanelf -e ./bitcoin` 273 274 The output should contain: 275 STK/REL/PTL 276 RW- R-- RW- 277 278 The STK RW- means that the stack is readable and writeable but not executable. 279 280Disable-wallet mode 281-------------------- 282When the intention is to run only a P2P node without a wallet, Bitcoin Core may be compiled in 283disable-wallet mode with: 284 285 ./configure --disable-wallet 286 287In this case there is no dependency on Berkeley DB 4.8 and SQLite. 288 289Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. 290 291Additional Configure Flags 292-------------------------- 293A list of additional configure flags can be displayed with: 294 295 ./configure --help 296 297 298Setup and Build Example: Arch Linux 299----------------------------------- 300This example lists the steps necessary to setup and build a command line only, non-wallet distribution of the latest changes on Arch Linux: 301 302 pacman -S git base-devel boost libevent python 303 git clone https://github.com/bitcoin/bitcoin.git 304 cd bitcoin/ 305 ./autogen.sh 306 ./configure --disable-wallet --without-gui --without-miniupnpc 307 make check 308 309Note: 310Enabling wallet support requires either compiling against a Berkeley DB newer than 4.8 (package `db`) using `--with-incompatible-bdb`, 311or building and depending on a local version of Berkeley DB 4.8. The readily available Arch Linux packages are currently built using 312`--with-incompatible-bdb` according to the [PKGBUILD](https://projects.archlinux.org/svntogit/community.git/tree/bitcoin/trunk/PKGBUILD). 313As mentioned above, when maintaining portability of the wallet between the standard Bitcoin Core distributions and independently built 314node software is desired, Berkeley DB 4.8 must be used. 315 316 317ARM Cross-compilation 318------------------- 319These steps can be performed on, for example, an Ubuntu VM. The depends system 320will also work on other Linux distributions, however the commands for 321installing the toolchain will be different. 322 323Make sure you install the build requirements mentioned above. 324Then, install the toolchain and curl: 325 326 sudo apt-get install g++-arm-linux-gnueabihf curl 327 328To build executables for ARM: 329 330 cd depends 331 make HOST=arm-linux-gnueabihf NO_QT=1 332 cd .. 333 ./autogen.sh 334 CONFIG_SITE=$PWD/depends/arm-linux-gnueabihf/share/config.site ./configure --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++ 335 make 336 337 338For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. 339