doc/build-unix.md

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