doc/build-unix.md

   1 UNIX BUILD NOTES
   2 ====================
   3 Some notes on how to build Bitcoin in Unix.
   4
   5 (for OpenBSD specific instructions, see [build-openbsd.md](build-openbsd.md))
   6
   7 Note
   8 ---------------------
   9 Always use absolute paths to configure and compile bitcoin and the dependencies,
  10 for example, when specifying the the path of the dependency:
  11
  12         ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX
  13
  14 Here BDB_PREFIX must absolute path - it is defined using $(pwd) which ensures
  15 the usage of the absolute path.
  16
  17 To Build
  18 ---------------------
  19
  20 ```bash
  21 ./autogen.sh
  22 ./configure
  23 make
  24 make install # optional
  25 ```
  26
  27 This will build bitcoin-qt as well if the dependencies are met.
  28
  29 Dependencies
  30 ---------------------
  31
  32 These dependencies are required:
  33
  34  Library     | Purpose          | Description
  35  ------------|------------------|----------------------
  36  libssl      | Crypto           | Random Number Generation, Elliptic Curve Cryptography
  37  libboost    | Utility          | Library for threading, data structures, etc
  38  libevent    | Networking       | OS independent asynchronous networking
  39
  40 Optional dependencies:
  41
  42  Library     | Purpose          | Description
  43  ------------|------------------|----------------------
  44  miniupnpc   | UPnP Support     | Firewall-jumping support
  45  libdb4.8    | Berkeley DB      | Wallet storage (only needed when wallet enabled)
  46  qt          | GUI              | GUI toolkit (only needed when GUI enabled)
  47  protobuf    | Payments in GUI  | Data interchange format used for payment protocol (only needed when GUI enabled)
  48  libqrencode | QR codes in GUI  | Optional for generating QR codes (only needed when GUI enabled)
  49  libzmq3     | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.x)
  50
  51 For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*.
  52
  53 System requirements
  54 --------------------
  55
  56 C++ compilers are memory-hungry. It is recommended to have at least 1 GB of
  57 memory available when compiling Bitcoin Core. With 512MB of memory or less
  58 compilation will take much longer due to swap thrashing.
  59
  60 Dependency Build Instructions: Ubuntu & Debian
  61 ----------------------------------------------
  62 Build requirements:
  63
  64         sudo apt-get install build-essential libtool autotools-dev autoconf pkg-config libssl-dev libevent-dev
  65
  66 For Ubuntu 12.04 and later or Debian 7 and later libboost-all-dev has to be installed:
  67
  68         sudo apt-get install libboost-all-dev
  69
  70  db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin).
  71  You can add the repository using the following command:
  72
  73         sudo add-apt-repository ppa:bitcoin/bitcoin
  74         sudo apt-get update
  75
  76  Ubuntu 12.04 and later have packages for libdb5.1-dev and libdb5.1++-dev,
  77  but using these will break binary wallet compatibility, and is not recommended.
  78
  79 For other Debian & Ubuntu (with ppa):
  80
  81         sudo apt-get install libdb4.8-dev libdb4.8++-dev
  82
  83 Optional:
  84
  85         sudo apt-get install libminiupnpc-dev (see --with-miniupnpc and --enable-upnp-default)
  86
  87 ZMQ dependencies:
  88
  89         sudo apt-get install libzmq3-dev (provides ZMQ API 4.x)
  90
  91
  92 Dependencies for the GUI: Ubuntu & Debian
  93 -----------------------------------------
  94
  95 If you want to build Bitcoin-Qt, make sure that the required packages for Qt development
  96 are installed. Either Qt 4 or Qt 5 are necessary to build the GUI.
  97 If both Qt 4 and Qt 5 are installed, Qt 4 will be used. Pass `--with-gui=qt5` to configure to choose Qt5.
  98 To build without GUI pass `--without-gui`.
  99
 100 To build with Qt 4 you need the following:
 101
 102     sudo apt-get install libqt4-dev libprotobuf-dev protobuf-compiler
 103
 104 For Qt 5 you need the following:
 105
 106     sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler
 107
 108 libqrencode (optional) can be installed with:
 109
 110     sudo apt-get install libqrencode-dev
 111
 112 Once these are installed, they will be found by configure and a bitcoin-qt executable will be
 113 built by default.
 114
 115 Notes
 116 -----
 117 The release is built with GCC and then "strip bitcoind" to strip the debug
 118 symbols, which reduces the executable size by about 90%.
 119
 120
 121 miniupnpc
 122 ---------
 123
 124 [miniupnpc](http://miniupnp.free.fr/) may be used for UPnP port mapping.  It can be downloaded from [here](
 125 http://miniupnp.tuxfamily.org/files/).  UPnP support is compiled in and
 126 turned off by default.  See the configure options for upnp behavior desired:
 127
 128         --without-miniupnpc      No UPnP support miniupnp not required
 129         --disable-upnp-default   (the default) UPnP support turned off by default at runtime
 130         --enable-upnp-default    UPnP support turned on by default at runtime
 131
 132 To build:
 133
 134         tar -xzvf miniupnpc-1.6.tar.gz
 135         cd miniupnpc-1.6
 136         make
 137         sudo su
 138         make install
 139
 140
 141 Berkeley DB
 142 -----------
 143 It is recommended to use Berkeley DB 4.8. If you have to build it yourself:
 144
 145 ```bash
 146 BITCOIN_ROOT=$(pwd)
 147
 148 # Pick some path to install BDB to, here we create a directory within the bitcoin directory
 149 BDB_PREFIX="${BITCOIN_ROOT}/db4"
 150 mkdir -p $BDB_PREFIX
 151
 152 # Fetch the source and verify that it is not tampered with
 153 wget 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz'
 154 echo '12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef  db-4.8.30.NC.tar.gz' | sha256sum -c
 155 # -> db-4.8.30.NC.tar.gz: OK
 156 tar -xzvf db-4.8.30.NC.tar.gz
 157
 158 # Build the library and install to our prefix
 159 cd db-4.8.30.NC/build_unix/
 160 #  Note: Do a static build so that it can be embedded into the executable, instead of having to find a .so at runtime
 161 ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX
 162 make install
 163
 164 # Configure Bitcoin Core to use our own-built instance of BDB
 165 cd $BITCOIN_ROOT
 166 ./autogen.sh
 167 ./configure LDFLAGS="-L${BDB_PREFIX}/lib/" CPPFLAGS="-I${BDB_PREFIX}/include/" # (other args...)
 168 ```
 169
 170 **Note**: You only need Berkeley DB if the wallet is enabled (see the section *Disable-Wallet mode* below).
 171
 172 Boost
 173 -----
 174 If you need to build Boost yourself:
 175
 176         sudo su
 177         ./bootstrap.sh
 178         ./bjam install
 179
 180
 181 Security
 182 --------
 183 To help make your bitcoin installation more secure by making certain attacks impossible to
 184 exploit even if a vulnerability is found, binaries are hardened by default.
 185 This can be disabled with:
 186
 187 Hardening Flags:
 188
 189         ./configure --enable-hardening
 190         ./configure --disable-hardening
 191
 192
 193 Hardening enables the following features:
 194
 195 * Position Independent Executable
 196     Build position independent code to take advantage of Address Space Layout Randomization
 197     offered by some kernels. Attackers who can cause execution of code at an arbitrary memory
 198     location are thwarted if they don't know where anything useful is located.
 199     The stack and heap are randomly located by default but this allows the code section to be
 200     randomly located as well.
 201
 202     On an AMD64 processor where a library was not compiled with -fPIC, this will cause an error
 203     such as: "relocation R_X86_64_32 against `......' can not be used when making a shared object;"
 204
 205     To test that you have built PIE executable, install scanelf, part of paxutils, and use:
 206
 207         scanelf -e ./bitcoin
 208
 209     The output should contain:
 210      TYPE
 211     ET_DYN
 212
 213 * Non-executable Stack
 214     If the stack is executable then trivial stack based buffer overflow exploits are possible if
 215     vulnerable buffers are found. By default, bitcoin should be built with a non-executable stack
 216     but if one of the libraries it uses asks for an executable stack or someone makes a mistake
 217     and uses a compiler extension which requires an executable stack, it will silently build an
 218     executable without the non-executable stack protection.
 219
 220     To verify that the stack is non-executable after compiling use:
 221     `scanelf -e ./bitcoin`
 222
 223     the output should contain:
 224         STK/REL/PTL
 225         RW- R-- RW-
 226
 227     The STK RW- means that the stack is readable and writeable but not executable.
 228
 229 Disable-wallet mode
 230 --------------------
 231 When the intention is to run only a P2P node without a wallet, bitcoin may be compiled in
 232 disable-wallet mode with:
 233
 234     ./configure --disable-wallet
 235
 236 In this case there is no dependency on Berkeley DB 4.8.
 237
 238 Mining is also possible in disable-wallet mode, but only using the `getblocktemplate` RPC
 239 call not `getwork`.