Update build documentation (#2323)

Only describe how to build based on the depends system
This commit is contained in:
Alexander Block 2018-09-28 09:55:46 +02:00 committed by UdjinM6
parent bd8c54d12e
commit d7e5f02eac
5 changed files with 240 additions and 340 deletions

95
doc/build-cross.md Normal file
View File

@ -0,0 +1,95 @@
Cross-compiliation of Dash Core
===============================
Dash Core can be cross-compiled on Linux to all other supported host systems. This is done by changing
the `HOST` parameter when building the dependencies and then specifying another `--prefix` directory when building Dash.
The following instructions are only tested on Debian Stretch and Ubuntu Bionic.
MacOSX Cross-compilation
------------------------
Cross-compiling to MacOSX requires a few additional packages to be installed:
```bash
$ sudo apt-get install python3-setuptools libcap-dev zlib1g-dev libbz2-dev
```
Additionally, the Mac OSX SDK must be downloaded and extracted manually:
```bash
$ mkdir -p depends/sdk-sources
$ mkdir -p depends/SDKs
$ curl https://bitcoincore.org/depends-sources/sdks/MacOSX10.11.sdk.tar.gz -o depends/sdk-sources/MacOSX10.11.sdk.tar.gz
$ tar -C depends/SDKs -xf depends/sdk-sources/MacOSX10.11.sdk.tar.gz
```
When building the dependencies, as described in [build-generic](build-generic.md), use
```bash
$ make HOST=x86_64-apple-darwin11 -j4
```
When building Dash Core, use
```bash
$ ./configure --prefix `pwd`/depends/x86_64-apple-darwin11
```
Windows 64bit/32bit Cross-compilation
-------------------------------
Cross-compiling to Windows requires a few additional packages to be installed:
```bash
$ sudo apt-get install nsis wine wine64 bc
```
For Windows 64bit, install :
```bash
$ sudo apt-get install g++-mingw-w64-x86-64
$ # Required to enable C++ threading libraries (e.g. std::thread)
$ sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
$ sudo update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
```
For Windows 32bit, install:
```bash
$ sudo apt-get install g++-mingw-w64-i686
$ # Required to enable C++ threading libraries (e.g. std::thread)
$ sudo update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
$ sudo update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix
```
When building the dependencies, as described in [build-generic](build-generic.md), use
```bash
$ make HOST=x86_64-w64-mingw32 -j4
```
When building Dash Core, use
```bash
$ ./configure --prefix `pwd`/depends/x86_64-w64-mingw32
```
These commands will build for Windows 64bit. If you want to compile for 32bit,
replace `x86_64-w64-mingw32` with `i686-w64-mingw32`.
ARM-Linux Cross-compilation
-------------------
Cross-compiling to ARM-Linux requires a few additional packages to be installed:
```bash
$ sudo apt-get install g++-arm-linux-gnueabihf
```
When building the dependencies, as described in [build-generic](build-generic.md), use
```bash
$ make HOST=arm-linux-gnueabihf -j4
```
When building Dash Core, use
```bash
$ ./configure --prefix `pwd`/depends/arm-linux-gnueabihf
```

79
doc/build-generic.md Normal file
View File

@ -0,0 +1,79 @@
GENERIC BUILD NOTES
====================
Some notes on how to build Dash Core based on the [depends](../depends/README.md) build system.
Note on old build instructions
------------------------------
In the past, the build documentation contained instructions on how to build Dash with system-wide installed dependencies
like BerkeleyDB 4.8, boost and Qt. Building this way is considered deprecated and only building with the `depends` prefix
is supported today.
Required build tools and environment
------------------------------------
Building the dependencies and Dash Core requires some essential build tools to be installed before. Please see
[build-unix](build-unix.md), [build-osx](build-osx.md) and [build-windows](build-windows.md) for details.
Building dependencies
---------------------
Dash inherited the `depends` folder from Bitcoin, which contains all dependencies required to build Dash. These
dependencies must be built before Dash can actually be built. To do so, perform the following:
```bash
$ cd depends
$ make -j4 # Choose a good -j value, depending on the number of CPU cores available
$ cd ..
```
This will download and build all dependencies required to build Dash Core. Caching of build results will ensure that only
the packages are rebuilt which have changed since the last depends build.
It is required to re-run the above commands from time to time when dependencies have been updated or added. If this is
not done, build failures might occur when building Dash.
Please read the [depends](../depends/README.md) documentation for more details on supported hosts and configuration
options. If no host is specified (as in the above example) when calling `make`, the depends system will default to your
local host system.
Building Dash Core
---------------------
```bash
$ ./autogen.sh
$ ./configure --prefix `pwd`/depends/<host>
$ make
$ make install # optional
```
Please replace `<host>` with your local system's `host-platform-triplet`. The following triplets are usually valid:
- `i686-pc-linux-gnu` for Linux32
- `x86_64-pc-linux-gnu` for Linux64
- `i686-w64-mingw32` for Win32
- `x86_64-w64-mingw32` for Win64
- `x86_64-apple-darwin11` for MacOSX
- `arm-linux-gnueabihf` for Linux ARM 32 bit
- `aarch64-linux-gnu` for Linux ARM 64 bit
If you want to cross-compile for another platform, choose the appropriate `<host>` and make sure to build the
dependencies with the same host before.
ccache
------
The depends system also contains [ccache](https://ccache.samba.org/), which caches build results on source->object
level. `./configure` of Dash Core will autodetect the presence of ccache and enable use of it. To disable ccache, use
`./configure --prefix=<prefix> --disable-ccache`.
The default maximum cache size is 5G, which might not be enough to cache multiple builds when switching Git branches
very often. It is advised to increase the maximum cache size:
```bash
$ ./depends/<host>/bin/ccache -M20G
```
Additional Configure Flags
--------------------------
A list of additional configure flags can be displayed with:
```bash
./configure --help
```

View File

@ -13,42 +13,22 @@ When the popup appears, click `Install`.
Then install [Homebrew](https://brew.sh).
Dependencies
----------------------
Base build dependencies
-----------------------
brew install automake berkeley-db4 libtool boost --c++11 miniupnpc openssl pkg-config protobuf qt libevent
```bash
brew install automake libtool --c++11 pkg-config
```
If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG
```bash
brew install librsvg
```
brew install librsvg
Building
--------
NOTE: Building with Qt4 is still supported, however, doing so could result in a broken UI. Therefore, building with Qt5 is recommended.
Build Dash Core
------------------------
1. Clone the Dash Core source code and cd into `dash`
git clone https://github.com/dashpay/dash
cd dash
2. Build Dash Core:
Configure and build the headless dash binaries as well as the GUI (if Qt is found).
You can disable the GUI build by passing `--without-gui` to configure.
./autogen.sh
./configure
make
3. It is recommended to build and run the unit tests:
make check
4. You can also create a .dmg that contains the .app bundle (optional):
make deploy
Follow the instructions in [build-generic](build-generic.md)
Running
-------
@ -90,10 +70,3 @@ Uncheck everything except Qt Creator during the installation process.
8. Select the default "Desktop" kit and select "Clang (x86 64bit in /usr/bin)" as compiler
9. Select LLDB as debugger (you might need to set the path to your installation)
10. Start debugging with Qt Creator
Notes
-----
* Tested on OS X 10.8 through 10.12 on 64-bit Intel processors only.
* Building with downloaded Qt binaries is not officially supported. See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714)

View File

@ -4,204 +4,39 @@ Some notes on how to build Dash Core in Unix.
(for OpenBSD specific instructions, see [build-openbsd.md](build-openbsd.md))
Note
---------------------
Always use absolute paths to configure and compile Dash Core and the dependencies,
for example, when specifying the path of the dependency:
Base build dependencies
-----------------------
Building the dependencies and Dash Core requires some essential build tools and libraries to be installed before.
../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
---------------------
Run the following commands to install required packages:
#####Debian/Ubuntu:
```bash
./autogen.sh
./configure
make
make install # optional
$ sudo apt-get install curl build-essential libtool autotools-dev automake pkg-config python3 bsdmainutils cmake
```
This will build dash-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
libdb4.8 | 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 Dash 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.
**For Ubuntu only:** db4.8 packages are available [here](https://launchpad.net/~bitcoin/+archive/bitcoin).
You can add the repository and install using the following commands:
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:bitcoin/bitcoin
sudo apt-get update
sudo apt-get install libdb4.8-dev libdb4.8++-dev
Ubuntu and Debian have their own libdb-dev and libdb++-dev packages, but these will install
BerkeleyDB 5.1 or later, which break binary wallet compatibility with the distributed executables which
are based on BerkeleyDB 4.8. If you do not care about wallet compatibility,
pass `--with-incompatible-bdb` to configure.
See the section "Disable-wallet mode" to build Dash 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 Dash-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 dash-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 dashd" 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 4.8. If you have to build it yourself:
#####Fedora:
```bash
DASH_ROOT=$(pwd)
# Pick some path to install BDB to, here we create a directory within the dash directory
BDB_PREFIX="${DASH_ROOT}/db4"
mkdir -p $BDB_PREFIX
# Fetch the source and verify that it is not tampered with
wget 'http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz'
echo '12edc0df75bf9abd7f82f821795bcee50f42cb2e5f76a6a281b85732798364ef db-4.8.30.NC.tar.gz' | sha256sum -c
# -> db-4.8.30.NC.tar.gz: OK
tar -xzvf db-4.8.30.NC.tar.gz
# Build the library and install to our prefix
cd db-4.8.30.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 Dash Core to use our own-built instance of BDB
cd $DASH_ROOT
./autogen.sh
./configure LDFLAGS="-L${BDB_PREFIX}/lib/" CPPFLAGS="-I${BDB_PREFIX}/include/" # (other args...)
$ sudo dnf install gcc-c++ libtool make autoconf automake python3 cmake
```
**Note**: You only need Berkeley DB if the wallet is enabled (see the section *Disable-Wallet mode* below).
#####Arch Linux
```bash
$ pacman -S base-devel python3 cmake
```
Boost
-----
If you need to build Boost yourself:
#####FreeBSD/OpenBSD
```bash
pkg_add gmake cmake libtool
pkg_add autoconf # (select highest version, e.g. 2.69)
pkg_add automake # (select highest version, e.g. 1.15)
pkg_add python # (select highest version, e.g. 3.5)
```
sudo su
./bootstrap.sh
./bjam install
Building
--------
Follow the instructions in [build-generic](build-generic.md)
Security
--------
@ -211,8 +46,8 @@ This can be disabled with:
Hardening Flags:
./configure --enable-hardening
./configure --disable-hardening
./configure --prefix=<prefix> --enable-hardening
./configure --prefix=<prefix> --disable-hardening
Hardening enables the following features:
@ -257,7 +92,7 @@ Disable-wallet mode
When the intention is to run only a P2P node without a wallet, Dash Core may be compiled in
disable-wallet mode with:
./configure --disable-wallet
./configure --prefix=<prefix> --disable-wallet
In this case there is no dependency on Berkeley DB 4.8.
@ -270,78 +105,40 @@ 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/dashpay/dash.git
cd dash/
./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 Dash 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)
(TODO, this is untested, please report if it works and if changes to this documentation are needed)
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 Dash 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
Building on FreeBSD is basically the same as on Linux based systems, with the difference that you have to use `gmake`
instead of `make`.
*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`.
Building on OpenBSD
-------------------
(TODO, this is untested, please report if it works and if changes to this documentation are needed)
(TODO, clang might also be an option. Old documentation reported it to to not work due to linking errors, but we're building all dependencies now as part of the depends system, so this might have changed)
Building on OpenBSD might require installation of a newer GCC version. If needed, do this with:
```bash
$ pkg_add g++ # (select newest 6.x version)
```
This compiler will not overwrite the system compiler, it will be installed as `egcc` and `eg++` in `/usr/local/bin`.
Add `CC=egcc CXX=eg++ CPP=ecpp` to the dependencies build and the Dash Core build:
```bash
$ cd depends
$ make CC=egcc CXX=eg++ CPP=ecpp # do not use -jX, this is broken
$ cd ..
$ export AUTOCONF_VERSION=2.69 # replace this with the autoconf version that you installed
$ export AUTOMAKE_VERSION=1.15 # replace this with the automake version that you installed
$ ./autogen.sh
$ ./configure --prefix=<prefix> CC=egcc CXX=eg++ CPP=ecpp
$ gmake # do not use -jX, this is broken
```

View File

@ -47,51 +47,7 @@ recommended but it is possible to compile the 32-bit version.
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.
First, install the general dependencies:
sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl
A host toolchain (`build-essential`) is necessary because some dependency
packages (such as `protobuf`) need to build host utilities that are used in the
build process.
## Building for 64-bit Windows
To build executables for Windows 64-bit, install the following dependencies:
sudo apt-get install g++-mingw-w64-x86-64 mingw-w64-x86-64-dev
Then build using:
cd depends
make HOST=x86_64-w64-mingw32
cd ..
./autogen.sh # not required when building from tarball
CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/
make
## Building for 32-bit Windows
To build executables for Windows 32-bit, install the following dependencies:
sudo apt-get install g++-mingw-w64-i686 mingw-w64-i686-dev
Then build using:
cd depends
make HOST=i686-w64-mingw32
cd ..
./autogen.sh # not required when building from tarball
CONFIG_SITE=$PWD/depends/i686-w64-mingw32/share/config.site ./configure --prefix=/
make
## Depends system
For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory.
Follow the instructions for Windows in [build-cross](build-cross.md)
Installation
-------------