344 lines
12 KiB
Markdown
344 lines
12 KiB
Markdown
UNIX BUILD NOTES
|
|
====================
|
|
Some notes on how to build Dogecoin Core in Unix.
|
|
|
|
(for OpenBSD specific instructions, see [build-openbsd.md](build-openbsd.md))
|
|
|
|
Note
|
|
---------------------
|
|
Always use absolute paths to configure and compile Dogecoin and the dependencies,
|
|
for example, when specifying the path of the dependency:
|
|
|
|
../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX
|
|
|
|
Here BDB_PREFIX must be an absolute path - it is defined using $(pwd) which ensures
|
|
the usage of the absolute path.
|
|
|
|
To Build
|
|
---------------------
|
|
|
|
```bash
|
|
./autogen.sh
|
|
./configure
|
|
make
|
|
make install # optional
|
|
```
|
|
|
|
This will build Dogecoin-Qt as well if the dependencies are met.
|
|
|
|
Dependencies
|
|
---------------------
|
|
|
|
These dependencies are required:
|
|
|
|
Library | Purpose | Description
|
|
------------|------------------|----------------------
|
|
libssl | Crypto | Random Number Generation, Elliptic Curve Cryptography
|
|
libboost | Utility | Library for threading, data structures, etc
|
|
libevent | Networking | OS independent asynchronous networking
|
|
|
|
Optional dependencies:
|
|
|
|
Library | Purpose | Description
|
|
------------|------------------|----------------------
|
|
miniupnpc | UPnP Support | Firewall-jumping support
|
|
libdb5.1 | Berkeley DB | Wallet storage (only needed when wallet enabled)
|
|
qt | GUI | GUI toolkit (only needed when GUI enabled)
|
|
protobuf | Payments in GUI | Data interchange format used for payment protocol (only needed when GUI enabled)
|
|
libqrencode | QR codes in GUI | Optional for generating QR codes (only needed when GUI enabled)
|
|
univalue | Utility | JSON parsing and encoding (bundled version will be used unless --with-system-univalue passed to configure)
|
|
libzmq3 | ZMQ notification | Optional, allows generating ZMQ notifications (requires ZMQ version >= 4.x)
|
|
|
|
For the versions used in the release, see [release-process.md](release-process.md) under *Fetch and build inputs*.
|
|
|
|
Memory Requirements
|
|
--------------------
|
|
|
|
C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of
|
|
memory available when compiling Dogecoin Core. On systems with less, gcc can be
|
|
tuned to conserve memory with additional CXXFLAGS:
|
|
|
|
./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"
|
|
|
|
Dependency Build Instructions: Ubuntu & Debian
|
|
----------------------------------------------
|
|
Build requirements:
|
|
|
|
sudo apt-get install build-essential libtool autotools-dev automake pkg-config libssl-dev libevent-dev bsdmainutils
|
|
|
|
Options when installing required Boost library files:
|
|
|
|
1. On at least Ubuntu 14.04+ and Debian 7+ there are generic names for the
|
|
individual boost development packages, so the following can be used to only
|
|
install necessary parts of boost:
|
|
|
|
sudo apt-get install libboost-system-dev libboost-filesystem-dev libboost-chrono-dev libboost-program-options-dev libboost-test-dev libboost-thread-dev
|
|
|
|
2. If that doesn't work, you can install all boost development packages with:
|
|
|
|
sudo apt-get install libboost-all-dev
|
|
|
|
BerkeleyDB is required for the wallet.
|
|
|
|
sudo apt-get install libdb5.1-dev libdb5.1++-dev
|
|
|
|
Note that if you have Berkeley DB 4.8 packages installed (i.e. for other
|
|
wallet software), they are incompatible with the packages for 5.1. You
|
|
will have to manually download 5.1 from
|
|
http://download.oracle.com/berkeley-db/db-5.1.29.NC.tar.gz and compile
|
|
it, install it to /usr/local where the configure script should locate it
|
|
automatically.
|
|
|
|
|
|
See the section "Disable-wallet mode" to build Dogecoin Core without wallet.
|
|
|
|
Optional (see --with-miniupnpc and --enable-upnp-default):
|
|
|
|
sudo apt-get install libminiupnpc-dev
|
|
|
|
ZMQ dependencies (provides ZMQ API 4.x):
|
|
|
|
sudo apt-get install libzmq3-dev
|
|
|
|
Dependencies for the GUI: Ubuntu & Debian
|
|
-----------------------------------------
|
|
|
|
If you want to build Dogecoin-Qt, make sure that the required packages for Qt development
|
|
are installed. Either Qt 5 or Qt 4 are necessary to build the GUI.
|
|
If both Qt 4 and Qt 5 are installed, Qt 5 will be used. Pass `--with-gui=qt4` to configure to choose Qt4.
|
|
To build without GUI pass `--without-gui`.
|
|
|
|
To build with Qt 5 (recommended) you need the following:
|
|
|
|
sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler
|
|
|
|
Alternatively, to build with Qt 4 you need the following:
|
|
|
|
sudo apt-get install libqt4-dev libprotobuf-dev protobuf-compiler
|
|
|
|
libqrencode (optional) can be installed with:
|
|
|
|
sudo apt-get install libqrencode-dev
|
|
|
|
Once these are installed, they will be found by configure and a dogecoin-qt executable will be
|
|
built by default.
|
|
|
|
Dependency Build Instructions: Fedora
|
|
-------------------------------------
|
|
Build requirements:
|
|
|
|
sudo dnf install gcc-c++ libtool make autoconf automake openssl-devel libevent-devel boost-devel libdb4-devel libdb4-cxx-devel
|
|
|
|
Optional:
|
|
|
|
sudo dnf install miniupnpc-devel
|
|
|
|
To build with Qt 5 (recommended) you need the following:
|
|
|
|
sudo dnf install qt5-qttools-devel qt5-qtbase-devel protobuf-devel
|
|
|
|
libqrencode (optional) can be installed with:
|
|
|
|
sudo dnf install qrencode-devel
|
|
|
|
Notes
|
|
-----
|
|
The release is built with GCC and then "strip dogecoind" to strip the debug
|
|
symbols, which reduces the executable size by about 90%.
|
|
|
|
|
|
miniupnpc
|
|
---------
|
|
|
|
[miniupnpc](http://miniupnp.free.fr/) may be used for UPnP port mapping. It can be downloaded from [here](
|
|
http://miniupnp.tuxfamily.org/files/). UPnP support is compiled in and
|
|
turned off by default. See the configure options for upnp behavior desired:
|
|
|
|
--without-miniupnpc No UPnP support miniupnp not required
|
|
--disable-upnp-default (the default) UPnP support turned off by default at runtime
|
|
--enable-upnp-default UPnP support turned on by default at runtime
|
|
|
|
|
|
Berkeley DB
|
|
-----------
|
|
It is recommended to use Berkeley DB 5.1. If you have to build it yourself:
|
|
|
|
```bash
|
|
BITCOIN_ROOT=$(pwd)
|
|
|
|
# Pick some path to install BDB to, here we create a directory within the dogecoin directory
|
|
BDB_PREFIX="${BITCOIN_ROOT}/db5"
|
|
mkdir -p $BDB_PREFIX
|
|
|
|
# Fetch the source and verify that it is not tampered with
|
|
wget 'http://download.oracle.com/berkeley-db/db-5.1.29.NC.tar.gz'
|
|
echo '08238e59736d1aacdd47cfb8e68684c695516c37f4fbe1b8267dde58dc3a576c db-5.1.29.NC.tar.gz' | sha256sum -c
|
|
# -> db-5.1.29.NC.tar.gz: OK
|
|
tar -xzvf db-5.1.29.NC.tar.gz
|
|
|
|
# Build the library and install to our prefix
|
|
cd db-5.1.29.NC/build_unix/
|
|
# Note: Do a static build so that it can be embedded into the executable, instead of having to find a .so at runtime
|
|
../dist/configure --enable-cxx --disable-shared --with-pic --prefix=$BDB_PREFIX
|
|
make install
|
|
|
|
# Configure Dogecoin Core to use our own-built instance of BDB
|
|
cd $BITCOIN_ROOT
|
|
./autogen.sh
|
|
./configure LDFLAGS="-L${BDB_PREFIX}/lib/" CPPFLAGS="-I${BDB_PREFIX}/include/" # (other args...)
|
|
```
|
|
|
|
**Note**: You only need Berkeley DB if the wallet is enabled (see the section *Disable-Wallet mode* below).
|
|
|
|
Boost
|
|
-----
|
|
If you need to build Boost yourself:
|
|
|
|
sudo su
|
|
./bootstrap.sh
|
|
./bjam install
|
|
|
|
|
|
Security
|
|
--------
|
|
To help make your Dogecoin installation more secure by making certain attacks impossible to
|
|
exploit even if a vulnerability is found, binaries are hardened by default.
|
|
This can be disabled with:
|
|
|
|
Hardening Flags:
|
|
|
|
./configure --enable-hardening
|
|
./configure --disable-hardening
|
|
|
|
|
|
Hardening enables the following features:
|
|
|
|
* Position Independent Executable
|
|
Build position independent code to take advantage of Address Space Layout Randomization
|
|
offered by some kernels. Attackers who can cause execution of code at an arbitrary memory
|
|
location are thwarted if they don't know where anything useful is located.
|
|
The stack and heap are randomly located by default but this allows the code section to be
|
|
randomly located as well.
|
|
|
|
On an AMD64 processor where a library was not compiled with -fPIC, this will cause an error
|
|
such as: "relocation R_X86_64_32 against `......' can not be used when making a shared object;"
|
|
|
|
To test that you have built PIE executable, install scanelf, part of paxutils, and use:
|
|
|
|
scanelf -e ./dogecoin
|
|
|
|
The output should contain:
|
|
|
|
TYPE
|
|
ET_DYN
|
|
|
|
* Non-executable Stack
|
|
If the stack is executable, trivial stack-based buffer overflow exploits are possible if
|
|
vulnerable buffers are found. By default, Dogecoin should be built with a non-executable stack,
|
|
but if one of the libraries it uses asks for an executable stack or someone makes a mistake
|
|
and uses a compiler extension which requires an executable stack, it will silently build an
|
|
executable without the non-executable stack protection.
|
|
|
|
To verify that the stack is non-executable after compiling, use:
|
|
`scanelf -e ./dogecoin`
|
|
|
|
the output should contain:
|
|
STK/REL/PTL
|
|
RW- R-- RW-
|
|
|
|
The STK RW- means that the stack is readable and writeable, but not executable.
|
|
|
|
Disable-wallet mode
|
|
--------------------
|
|
When the intention is to run only a P2P node without a wallet, Dogecoin may be compiled in
|
|
disable-wallet mode with:
|
|
|
|
./configure --disable-wallet
|
|
|
|
In this case there is no dependency on Berkeley DB 4.8.
|
|
|
|
Mining is also possible in disable-wallet mode, but only using the `getblocktemplate` RPC
|
|
call, not `getwork`.
|
|
|
|
Additional Configure Flags
|
|
--------------------------
|
|
A list of additional configure flags can be displayed with:
|
|
|
|
./configure --help
|
|
|
|
|
|
Setup and Build Example: Arch Linux
|
|
-----------------------------------
|
|
This example lists the steps necessary to setup and build a command line only, non-wallet distribution of the latest changes on Arch Linux:
|
|
|
|
pacman -S git base-devel boost libevent python
|
|
git clone https://github.com/bitcoin/bitcoin.git
|
|
cd bitcoin/
|
|
./autogen.sh
|
|
./configure --disable-wallet --without-gui --without-miniupnpc
|
|
make check
|
|
|
|
Note:
|
|
Enabling wallet support requires either compiling against a Berkeley DB newer than 4.8 (package `db`) using `--with-incompatible-bdb`,
|
|
or building and depending on a local version of Berkeley DB 4.8. The readily available Arch Linux packages are currently built using
|
|
`--with-incompatible-bdb` according to the [PKGBUILD](https://projects.archlinux.org/svntogit/community.git/tree/bitcoin/trunk/PKGBUILD).
|
|
As mentioned above, when maintaining portability of the wallet between the standard Dogecoin Core distributions and independently built
|
|
node software is desired, Berkeley DB 4.8 must be used.
|
|
|
|
|
|
ARM Cross-compilation
|
|
-------------------
|
|
These steps can be performed on, for example, an Ubuntu VM. The depends system
|
|
will also work on other Linux distributions, however the commands for
|
|
installing the toolchain will be different.
|
|
|
|
Make sure you install the build requirements mentioned above.
|
|
Then, install the toolchain and curl:
|
|
|
|
sudo apt-get install g++-arm-linux-gnueabihf curl
|
|
|
|
To build executables for ARM:
|
|
|
|
cd depends
|
|
make HOST=arm-linux-gnueabihf NO_QT=1
|
|
cd ..
|
|
./configure --prefix=$PWD/depends/arm-linux-gnueabihf --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++
|
|
make
|
|
|
|
|
|
For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory.
|
|
|
|
Building on FreeBSD
|
|
--------------------
|
|
|
|
(Updated as of FreeBSD 11.0)
|
|
|
|
Clang is installed by default as `cc` compiler, this makes it easier to get
|
|
started than on [OpenBSD](build-openbsd.md). Installing dependencies:
|
|
|
|
pkg install autoconf automake libtool pkgconf
|
|
pkg install boost-libs openssl libevent
|
|
pkg install gmake
|
|
|
|
You need to use GNU make (`gmake`) instead of `make`.
|
|
(`libressl` instead of `openssl` will also work)
|
|
|
|
For the wallet (optional):
|
|
|
|
pkg install db5
|
|
|
|
This will give a warning "configure: WARNING: Found Berkeley DB other
|
|
than 4.8; wallets opened by this build will not be portable!", but as FreeBSD never
|
|
had a binary release, this may not matter. If backwards compatibility
|
|
with 4.8-built Dogecoin Core is needed follow the steps under "Berkeley DB" above.
|
|
|
|
Then build using:
|
|
|
|
./autogen.sh
|
|
./configure --with-incompatible-bdb BDB_CFLAGS="-I/usr/local/include/db5" BDB_LIBS="-L/usr/local/lib -ldb_cxx-5"
|
|
gmake
|
|
|
|
*Note on debugging*: The version of `gdb` installed by default is [ancient and considered harmful](https://wiki.freebsd.org/GdbRetirement).
|
|
It is not suitable for debugging a multi-threaded C++ program, not even for getting backtraces. Please install the package `gdb` and
|
|
use the versioned gdb command e.g. `gdb7111`.
|