Avoid reference to undefined name: stderr does not exist, sys.stderr does
[bitcoinplatinum.git] / doc / build-unix.md
blobb7eae2a630ad1acca937121b4def7e382256f283
1 UNIX BUILD NOTES
2 ====================
3 Some notes on how to build Bitcoin Core in Unix.
5 (for OpenBSD specific instructions, see [build-openbsd.md](build-openbsd.md))
7 Note
8 ---------------------
9 Always use absolute paths to configure and compile bitcoin and the dependencies,
10 for example, when specifying the path of the dependency:
12         ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX
14 Here BDB_PREFIX must be an absolute path - it is defined using $(pwd) which ensures
15 the usage of the absolute path.
17 To Build
18 ---------------------
20 ```bash
21 ./autogen.sh
22 ./configure
23 make
24 make install # optional
25 ```
27 This will build bitcoin-qt as well if the dependencies are met.
29 Dependencies
30 ---------------------
32 These dependencies are required:
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
40 Optional dependencies:
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  univalue    | Utility          | JSON parsing and encoding (bundled version will be used unless --with-system-univalue passed to configure)
50  libzmq3     | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.x)
52 For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*.
54 Memory Requirements
55 --------------------
57 C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of
58 memory available when compiling Bitcoin Core. On systems with less, gcc can be
59 tuned to conserve memory with additional CXXFLAGS:
62     ./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"
64 Dependency Build Instructions: Ubuntu & Debian
65 ----------------------------------------------
66 Build requirements:
68     sudo apt-get install build-essential libtool autotools-dev automake pkg-config libssl-dev libevent-dev bsdmainutils
70 Options when installing required Boost library files:
72 1. On at least Ubuntu 14.04+ and Debian 7+ there are generic names for the
73 individual boost development packages, so the following can be used to only
74 install necessary parts of boost:
76         sudo apt-get install libboost-system-dev libboost-filesystem-dev libboost-chrono-dev libboost-program-options-dev libboost-test-dev libboost-thread-dev
78 2. If that doesn't work, you can install all boost development packages with:
80         sudo apt-get install libboost-all-dev
82 BerkeleyDB is required for the wallet.
84 **For Ubuntu only:** db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin).
85 You can add the repository and install using the following commands:
87     sudo apt-get install software-properties-common
88     sudo add-apt-repository ppa:bitcoin/bitcoin
89     sudo apt-get update
90     sudo apt-get install libdb4.8-dev libdb4.8++-dev
92 Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install
93 BerkeleyDB 5.1 or later, which break binary wallet compatibility with the distributed executables which
94 are based on BerkeleyDB 4.8. If you do not care about wallet compatibility,
95 pass `--with-incompatible-bdb` to configure.
97 See the section "Disable-wallet mode" to build Bitcoin Core without wallet.
99 Optional (see --with-miniupnpc and --enable-upnp-default):
101     sudo apt-get install libminiupnpc-dev
103 ZMQ dependencies (provides ZMQ API 4.x):
105     sudo apt-get install libzmq3-dev
107 Dependencies for the GUI: Ubuntu & Debian
108 -----------------------------------------
110 If you want to build Bitcoin-Qt, make sure that the required packages for Qt development
111 are installed. Either Qt 5 or Qt 4 are necessary to build the GUI.
112 If both Qt 4 and Qt 5 are installed, Qt 5 will be used. Pass `--with-gui=qt4` to configure to choose Qt4.
113 To build without GUI pass `--without-gui`.
115 To build with Qt 5 (recommended) you need the following:
117     sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler
119 Alternatively, to build with Qt 4 you need the following:
121     sudo apt-get install libqt4-dev libprotobuf-dev protobuf-compiler
123 libqrencode (optional) can be installed with:
125     sudo apt-get install libqrencode-dev
127 Once these are installed, they will be found by configure and a bitcoin-qt executable will be
128 built by default.
130 Dependency Build Instructions: Fedora
131 -------------------------------------
132 Build requirements:
134     sudo dnf install gcc-c++ libtool make autoconf automake openssl-devel libevent-devel boost-devel libdb4-devel libdb4-cxx-devel
136 Optional:
138     sudo dnf install miniupnpc-devel
140 To build with Qt 5 (recommended) you need the following:
142     sudo dnf install qt5-qttools-devel qt5-qtbase-devel protobuf-devel
144 libqrencode (optional) can be installed with:
146     sudo dnf install qrencode-devel
148 Notes
149 -----
150 The release is built with GCC and then "strip bitcoind" to strip the debug
151 symbols, which reduces the executable size by about 90%.
154 miniupnpc
155 ---------
157 [miniupnpc](http://miniupnp.free.fr/) may be used for UPnP port mapping.  It can be downloaded from [here](
158 http://miniupnp.tuxfamily.org/files/).  UPnP support is compiled in and
159 turned off by default.  See the configure options for upnp behavior desired:
161         --without-miniupnpc      No UPnP support miniupnp not required
162         --disable-upnp-default   (the default) UPnP support turned off by default at runtime
163         --enable-upnp-default    UPnP support turned on by default at runtime
166 Berkeley DB
167 -----------
168 It is recommended to use Berkeley DB 4.8. If you have to build it yourself:
170 ```bash
171 BITCOIN_ROOT=$(pwd)
173 # Pick some path to install BDB to, here we create a directory within the bitcoin directory
174 BDB_PREFIX="${BITCOIN_ROOT}/db4"
175 mkdir -p $BDB_PREFIX
177 # Fetch the source and verify that it is not tampered with
178 wget 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz'
179 echo '12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef  db-4.8.30.NC.tar.gz' | sha256sum -c
180 # -> db-4.8.30.NC.tar.gz: OK
181 tar -xzvf db-4.8.30.NC.tar.gz
183 # Build the library and install to our prefix
184 cd db-4.8.30.NC/build_unix/
185 #  Note: Do a static build so that it can be embedded into the executable, instead of having to find a .so at runtime
186 ../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX
187 make install
189 # Configure Bitcoin Core to use our own-built instance of BDB
190 cd $BITCOIN_ROOT
191 ./autogen.sh
192 ./configure LDFLAGS="-L${BDB_PREFIX}/lib/" CPPFLAGS="-I${BDB_PREFIX}/include/" # (other args...)
195 **Note**: You only need Berkeley DB if the wallet is enabled (see the section *Disable-Wallet mode* below).
197 Boost
198 -----
199 If you need to build Boost yourself:
201         sudo su
202         ./bootstrap.sh
203         ./bjam install
206 Security
207 --------
208 To help make your bitcoin installation more secure by making certain attacks impossible to
209 exploit even if a vulnerability is found, binaries are hardened by default.
210 This can be disabled with:
212 Hardening Flags:
214         ./configure --enable-hardening
215         ./configure --disable-hardening
218 Hardening enables the following features:
220 * Position Independent Executable
221     Build position independent code to take advantage of Address Space Layout Randomization
222     offered by some kernels. Attackers who can cause execution of code at an arbitrary memory
223     location are thwarted if they don't know where anything useful is located.
224     The stack and heap are randomly located by default but this allows the code section to be
225     randomly located as well.
227     On an AMD64 processor where a library was not compiled with -fPIC, this will cause an error
228     such as: "relocation R_X86_64_32 against `......' can not be used when making a shared object;"
230     To test that you have built PIE executable, install scanelf, part of paxutils, and use:
232         scanelf -e ./bitcoin
234     The output should contain:
236      TYPE
237     ET_DYN
239 * Non-executable Stack
240     If the stack is executable then trivial stack based buffer overflow exploits are possible if
241     vulnerable buffers are found. By default, bitcoin should be built with a non-executable stack
242     but if one of the libraries it uses asks for an executable stack or someone makes a mistake
243     and uses a compiler extension which requires an executable stack, it will silently build an
244     executable without the non-executable stack protection.
246     To verify that the stack is non-executable after compiling use:
247     `scanelf -e ./bitcoin`
249     the output should contain:
250         STK/REL/PTL
251         RW- R-- RW-
253     The STK RW- means that the stack is readable and writeable but not executable.
255 Disable-wallet mode
256 --------------------
257 When the intention is to run only a P2P node without a wallet, bitcoin may be compiled in
258 disable-wallet mode with:
260     ./configure --disable-wallet
262 In this case there is no dependency on Berkeley DB 4.8.
264 Mining is also possible in disable-wallet mode, but only using the `getblocktemplate` RPC
265 call not `getwork`.
267 Additional Configure Flags
268 --------------------------
269 A list of additional configure flags can be displayed with:
271     ./configure --help
274 Setup and Build Example: Arch Linux
275 -----------------------------------
276 This example lists the steps necessary to setup and build a command line only, non-wallet distribution of the latest changes on Arch Linux:
278     pacman -S git base-devel boost libevent python
279     git clone https://github.com/bitcoin/bitcoin.git
280     cd bitcoin/
281     ./autogen.sh
282     ./configure --disable-wallet --without-gui --without-miniupnpc
283     make check
285 Note:
286 Enabling wallet support requires either compiling against a Berkeley DB newer than 4.8 (package `db`) using `--with-incompatible-bdb`,
287 or building and depending on a local version of Berkeley DB 4.8. The readily available Arch Linux packages are currently built using
288 `--with-incompatible-bdb` according to the [PKGBUILD](https://projects.archlinux.org/svntogit/community.git/tree/bitcoin/trunk/PKGBUILD).
289 As mentioned above, when maintaining portability of the wallet between the standard Bitcoin Core distributions and independently built
290 node software is desired, Berkeley DB 4.8 must be used.
293 ARM Cross-compilation
294 -------------------
295 These steps can be performed on, for example, an Ubuntu VM. The depends system
296 will also work on other Linux distributions, however the commands for
297 installing the toolchain will be different.
299 Make sure you install the build requirements mentioned above.
300 Then, install the toolchain and curl:
302     sudo apt-get install g++-arm-linux-gnueabihf curl
304 To build executables for ARM:
306     cd depends
307     make HOST=arm-linux-gnueabihf NO_QT=1
308     cd ..
309     ./configure --prefix=$PWD/depends/arm-linux-gnueabihf --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++
310     make
313 For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory.
315 Building on FreeBSD
316 --------------------
318 (Updated as of FreeBSD 11.0)
320 Clang is installed by default as `cc` compiler, this makes it easier to get
321 started than on [OpenBSD](build-openbsd.md). Installing dependencies:
323     pkg install autoconf automake libtool pkgconf
324     pkg install boost-libs openssl libevent
325     pkg install gmake
327 You need to use GNU make (`gmake`) instead of `make`.
328 (`libressl` instead of `openssl` will also work)
330 For the wallet (optional):
332     pkg install db5
334 This will give a warning "configure: WARNING: Found Berkeley DB other
335 than 4.8; wallets opened by this build will not be portable!", but as FreeBSD never
336 had a binary release, this may not matter. If backwards compatibility
337 with 4.8-built Bitcoin Core is needed follow the steps under "Berkeley DB" above.
339 Then build using:
341     ./autogen.sh
342     ./configure --with-incompatible-bdb BDB_CFLAGS="-I/usr/local/include/db5" BDB_LIBS="-L/usr/local/lib -ldb_cxx-5"
343     gmake
345 *Note on debugging*: The version of `gdb` installed by default is [ancient and considered harmful](https://wiki.freebsd.org/GdbRetirement).
346 It is not suitable for debugging a multi-threaded C++ program, not even for getting backtraces. Please install the package `gdb` and
347 use the versioned gdb command e.g. `gdb7111`.