diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,7 +190,7 @@ - You will likely be re-writing git histories multiple times, which causes timestamp changes that require re-building a significant number of files. It's -highly recommended to install `ccache` (re-run ./configure if you install it +highly recommended to install `ccache` (re-run cmake if you install it later), as this will help cut your re-build times from several minutes to under a minute, in many cases. diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md --- a/doc/build-freebsd.md +++ b/doc/build-freebsd.md @@ -11,15 +11,34 @@ You will need the following dependencies, which can be installed as root via pkg: ```shell -pkg install autoconf automake boost-libs gmake libevent libtool openssl pkgconf +pkg install cmake libevent ninja openssl ``` +### Optional libraries + +To enable UPnP: +```shell +pkg install miniupnpc +``` +If not installed, UPnP support should be disabled by passing `-DENABLE_UPNP=OFF` to `cmake`. + +To enable ZeroMQ: +```shell +pkg install libzmq4 +``` +If not installed, ZeroMQ support should be disabled by passing `-BUILD_BITCOIN_ZMQ=OFF` to `cmake`. + In order to run the test suite (recommended), you will need to have Python 3 installed: ```shell pkg install python3 ``` +To run the ZeroMQ tests: +```shell +pkg install py36-pyzmq +``` + For the wallet (optional): ```shell @@ -31,28 +50,20 @@ ## Building Bitcoin ABC -**Important**: Use `gmake` (the non-GNU `make` will exit with an error): - With wallet: ```shell -./autogen.sh -./configure --with-gui=no \ - CXXFLAGS="-I/usr/local/include" \ - BDB_CFLAGS="-I/usr/local/include/db5" \ - BDB_LIBS="-L/usr/local/lib -ldb_cxx-5" +mkdir build +cd build +cmake -GNinja -DBUILD_BITCOIN_QT=OFF .. +ninja ``` Without wallet: ```shell -./autogen.sh -./configure --with-gui=no --disable-wallet -``` - -followed by: - -```shell -gmake # use -jX here for parallelism -gmake check # Run tests if Python 3 is available +mkdir build +cd build +cmake -GNinja -DBUILD_BITCOIN_QT=OFF -DBUILD_BITCOIN_WALLET=OFF .. +ninja ``` diff --git a/doc/build-osx.md b/doc/build-osx.md --- a/doc/build-osx.md +++ b/doc/build-osx.md @@ -21,11 +21,11 @@ Install dependencies: - brew install automake berkeley-db libtool boost miniupnpc openssl pkg-config protobuf python qt libevent qrencode + brew install berkeley-db boost cmake libevent miniupnpc ninja openssl protobuf python qrencode qt zeromq See [dependencies.md](dependencies.md) for a complete overview. -If you want to build the disk image with `make deploy` (.dmg / optional), you need RSVG: +If you want to build the disk image with `ninja osx-dmg` (.dmg / optional), you need RSVG: brew install librsvg @@ -41,32 +41,31 @@ 2. Build Bitcoin ABC: - Configure and build the headless Bitcoin ABC binaries as well as the GUI (if Qt is found). + Configure and build the headless Bitcoin ABC binaries as well as the GUI. - You can disable the GUI build by passing `--without-gui` to configure. + You can disable the GUI build by passing `-DBUILD_BITCOIN_QT=OFF` to cmake. It is recommended to create a build directory to build out-of-tree. - ./autogen.sh mkdir build cd build - ../configure - make + cmake -GNinja .. + ninja 3. It is recommended to build and run the unit tests: - make check + ninja check 4. You can also create a .dmg that contains the .app bundle (optional): - make deploy + ninja osx-dmg Disable-wallet mode -------------------- When the intention is to run only a P2P node without a wallet, Bitcoin ABC may be compiled in disable-wallet mode with: - ./configure --disable-wallet + cmake -GNinja .. -DBUILD_BITCOIN_WALLET=OFF Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. diff --git a/doc/build-unix.md b/doc/build-unix.md --- a/doc/build-unix.md +++ b/doc/build-unix.md @@ -4,16 +4,6 @@ (For FreeBSD specific instructions, see `build-freebsd.md` in this directory.) -Note ---------------------- -Always use absolute paths to configure and compile Bitcoin ABC 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 --------------------- @@ -22,15 +12,14 @@ It is recommended to create a build directory to build out-of-tree. ```bash -./autogen.sh mkdir build cd build -../configure -make -make install # optional +cmake -GNinja .. +ninja +ninja install # optional ``` -This will build bitcoin-qt as well, if the dependencies are met. +This will build bitcoin-qt as well. Dependencies --------------------- @@ -64,18 +53,35 @@ memory available when compiling Bitcoin ABC. 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" + cmake -GNinja .. -DCXXFLAGS="--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 python3 + sudo apt-get install bsdmainutils build-essential libssl-dev libevent-dev ninja-build python3 + +On Debian Buster (10) or Ubuntu 19.04 and later: + + sudo apt-get install cmake + +On previous Ubuntu versions, the `cmake` package is too old and needs to be installed from the Kitware APT repository: + + sudo apt-get install apt-transport-https ca-certificates gnupg software-properties-common wget + wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add - + +Add the repository corresponding to your version (see [instructions from Kitware](https://apt.kitware.com)). For Ubuntu Bionic (18.04): + + sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main' + +Then update the package list and install `cmake`: + + sudo apt update + sudo apt install cmake Options when installing required Boost library files: -1. On at least Ubuntu 14.04+ and Debian 7+ there are generic names for the +1. On at least Ubuntu 16.04+ and Debian 9+ there are generic names for the individual boost development packages, so the following can be used to only install necessary parts of boost: @@ -91,11 +97,11 @@ See the section "Disable-wallet mode" to build Bitcoin ABC without wallet. -Optional (see --with-miniupnpc and --enable-upnp-default): +Minipupnc dependencies (can be disabled by passing `-DENABLE_UPNP=OFF` on the cmake command line): sudo apt-get install libminiupnpc-dev -ZMQ dependencies (provides ZMQ API 4.x): +ZMQ dependencies (provides ZMQ API 4.x, can be disabled by passing `-BUILD_BITCOIN_ZMQ=OFF` on the cmake command line): sudo apt-get install libzmq3-dev @@ -104,34 +110,35 @@ If you want to build bitcoin-qt, make sure that the required packages for Qt development are installed. Qt 5 is necessary to build the GUI. -To build without GUI pass `--without-gui`. +To build without GUI pass `-DBUILD_BITCOIN_QT=OFF` on the cmake command line. To build with Qt 5 you need the following: sudo apt-get install libqt5gui5 libqt5core5a libqt5dbus5 qttools5-dev qttools5-dev-tools libprotobuf-dev protobuf-compiler -libqrencode (optional) can be installed with: +libqrencode dependencies (can be disabled by passing `-DENABLE_QRCODE=OFF` on the cmake command line): sudo apt-get install libqrencode-dev -Once these are installed, they will be found by configure and a bitcoin-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 libdb-devel libdb-cxx-devel python3 + sudo dnf install boost-devel cmake gcc-c++ libdb-cxx-devel libdb-devel libevent-devel ninja-build openssl-devel python3 -Optional: +Minipupnc dependencies (can be disabled by passing `-DENABLE_UPNP=OFF` on the cmake command line): sudo dnf install miniupnpc-devel +ZMQ dependencies (can be disabled by passing `-BUILD_BITCOIN_ZMQ=OFF` on the cmake command line): + + sudo dnf install zeromq-devel + To build with Qt 5 you need the following: sudo dnf install qt5-qttools-devel qt5-qtbase-devel protobuf-devel -libqrencode (optional) can be installed with: +libqrencode dependencies (can be disabled by passing `-DENABLE_QRCODE=OFF`): sudo dnf install qrencode-devel @@ -146,11 +153,10 @@ [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: +turned off by default. See the cmake 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 + ENABLE_UPNP Enable UPnP support (miniupnp required, default ON) + START_WITH_UPNP UPnP support turned on by default at runtime (default OFF) Boost ----- @@ -160,13 +166,7 @@ -------- To help make your Bitcoin ABC 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 - +This can be disabled by passing `-DENABLE_HARDENING=OFF`. Hardening enables the following features: * _Position Independent Executable_: Build position independent code to take advantage of Address Space Layout Randomization @@ -180,12 +180,12 @@ To test that you have built PIE executable, install scanelf, part of paxutils, and use: - scanelf -e ./bitcoin + scanelf -e ./bitcoin The output should contain: - TYPE - ET_DYN + TYPE + ET_DYN * _Non-executable Stack_: If the stack is executable then trivial stack-based buffer overflow exploits are possible if vulnerable buffers are found. By default, Bitcoin ABC should be built with a non-executable stack, @@ -194,60 +194,61 @@ executable without the non-executable stack protection. To verify that the stack is non-executable after compiling use: - `scanelf -e ./bitcoin` + + scanelf -e ./bitcoin The output should contain: - STK/REL/PTL - RW- R-- RW- - The STK RW- means that the stack is readable and writeable but not executable. + 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, Bitcoin ABC may be compiled in -disable-wallet mode with: - - ./configure --disable-wallet +disable-wallet mode by passing `-DBUILD_BITCOIN_WALLET=OFF` on the cmake command line. Mining is also possible in disable-wallet mode using the `getblocktemplate` RPC call. -Additional Configure Flags +Additional cmake options -------------------------- -A list of additional configure flags can be displayed with: - - ./configure --help - +A list of the cmake options and their current value can be displayed. +From the build subdirectory (see above), run `cmake -LH ..`. 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 + pacman -S boost cmake git libevent ninja python git clone https://github.com/Bitcoin-ABC/bitcoin-abc.git cd bitcoin-abc/ - ./autogen.sh - ./configure --disable-wallet --without-gui --without-miniupnpc - make check + mkdir build + cd build + cmake -GNinja .. -DBUILD_BITCOIN_WALLET=OFF -DBUILD_BITCOIN_QT=OFF -DENABLE_UPNP=OFF -DBUILD_BITCOIN_ZMQ=OFF + ninja ARM Cross-compilation ------------------- -These steps can be performed on, for example, an Ubuntu VM. The depends system +These steps can be performed on, for example, a Debian 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: +Make sure you install all the build requirements mentioned above. +Then, install the toolchain and some additional dependencies: - sudo apt-get install g++-arm-linux-gnueabihf curl + sudo apt-get install autoconf automake curl g++-arm-linux-gnueabihf gcc-arm-linux-gnueabihf gperf pkg-config To build executables for ARM: cd depends - make HOST=arm-linux-gnueabihf NO_QT=1 + make build-linux-arm cd .. - ./configure --prefix=$PWD/depends/arm-linux-gnueabihf --enable-glibc-back-compat --enable-reduce-exports LDFLAGS=-static-libstdc++ - make + mkdir build + cd build + cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/LinuxARM.cmake -DENABLE_GLIBC_BACK_COMPAT=ON -DENABLE_STATIC_LIBSTDCXX=ON + ninja For further documentation on the depends system see [README.md](../depends/README.md) in the depends directory. diff --git a/doc/build-windows.md b/doc/build-windows.md --- a/doc/build-windows.md +++ b/doc/build-windows.md @@ -5,7 +5,7 @@ The options known to work for building Bitcoin ABC on Windows are: -* On Linux, using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. Ubuntu Trusty 14.04 is recommended +* On Linux, using the [Mingw-w64](https://mingw-w64.org/doku.php) cross compiler tool chain. Debian Buster is recommended and is the platform used to build the Bitcoin ABC Windows release binaries. * On Windows, using [Windows Subsystem for Linux (WSL)](https://msdn.microsoft.com/commandline/wsl/about) and the Mingw-w64 cross compiler tool chain. @@ -26,7 +26,7 @@ environment. Within this environment you can cross compile for Windows without the need for a separate Linux VM or server. Note that while WSL can be installed with other Linux variants, such as OpenSUSE, the following instructions have only been -tested with Ubuntu. +tested with Ubuntu Bionic. This feature is not supported in versions of Windows prior to Windows 10 or on Windows Server SKUs. In addition, it is available [only for 64-bit versions of @@ -53,11 +53,7 @@ Cross-compilation for Ubuntu and Windows Subsystem for Linux ------------------------------------------------------------ -At the time of writing the Windows Subsystem for Linux installs Ubuntu Xenial 16.04. The Mingw-w64 package -for Ubuntu Xenial does not produce working executables for some of the Bitcoin ABC applications. -It is possible to build on Ubuntu Xenial by installing the cross compiler packages from Ubuntu Artful, see the steps below. -Building on Ubuntu Artful 17.10 has been verified to work. - +At the time of writing the Windows Subsystem for Linux installs Ubuntu Bionic 18.04. The steps below can be performed on Ubuntu (including in a VM) or WSL. The depends system will also work on other Linux distributions, however the commands for installing the toolchain will be different. @@ -66,7 +62,16 @@ sudo apt update sudo apt upgrade - sudo apt install build-essential libtool autotools-dev automake pkg-config bsdmainutils curl git + sudo apt install autoconf automake build-essential bsdmainutils curl git libboost-all-dev libevent-dec libssl-dev libtool ninja-build pkg-config python3 + +The cmake version packaged with Ubuntu Bionic is too old for building Building Bitcoin ABC. +To install the latest version: + + sudo apt-get install apt-transport-https ca-certificates gnupg software-properties-common wget + wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | sudo apt-key add - + sudo apt-add-repository 'deb https://apt.kitware.com/ubuntu/ bionic main' + sudo apt update + sudo apt install cmake A host toolchain (`build-essential`) is necessary because some dependency packages (such as `protobuf`) need to build host utilities that are used in the @@ -83,10 +88,6 @@ sudo apt install g++-mingw-w64-x86-64 -Ubuntu Trusty 14.04: - - No further steps required - Ubuntu Xenial 16.04 and Windows Subsystem for Linux [1](#footnote1),[2](#footnote2): sudo apt install software-properties-common @@ -94,15 +95,17 @@ sudo apt update sudo apt upgrade sudo update-alternatives --config x86_64-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. + sudo update-alternatives --config x86_64-w64-mingw32-gcc # Set the default mingw32 gcc compiler option to posix. -Ubuntu Artful 17.10 [2](#footnote2): +Ubuntu Artful 17.10 [2](#footnote2) and later, including Ubuntu Bionic on WSL: sudo update-alternatives --config x86_64-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. + sudo update-alternatives --config x86_64-w64-mingw32-gcc # Set the default mingw32 gcc compiler option to posix. Once the toolchain is installed the build steps are common: Note that for WSL the Bitcoin ABC source path MUST be somewhere in the default mount file system, for -example /usr/src/bitcoin-abc, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. +example /usr/src/bitcoin-abc, AND not under /mnt/d/. This means you cannot use a directory that is located directly on the host Windows file system to perform the build. Acquire the source in the usual way: @@ -113,11 +116,12 @@ PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var cd depends - make HOST=x86_64-w64-mingw32 + make build-win64 cd .. - ./autogen.sh # not required when building from tarball - CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/ --with-seeder=false # seeder not supported in Windows yet - make + mkdir build + cd build + cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/Win64.cmake -DBUILD_BITCOIN_SEEDER=OFF # seeder not supported in Windows yet + ninja ## Building for 32-bit Windows @@ -125,12 +129,13 @@ sudo apt install g++-mingw-w64-i686 mingw-w64-i686-dev -For Ubuntu Xenial 16.04, Ubuntu Artful 17.10 and Windows Subsystem for Linux [2](#footnote2): +For Ubuntu Xenial 16.04 and later, including Ubuntu Bionic on the Windows Subsystem for Linux [2](#footnote2): sudo update-alternatives --config i686-w64-mingw32-g++ # Set the default mingw32 g++ compiler option to posix. + sudo update-alternatives --config i686-w64-mingw32-gcc # Set the default mingw32 gcc compiler option to posix. Note that for WSL the Bitcoin ABC source path MUST be somewhere in the default mount file system, for -example /usr/src/bitcoin-abc, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail. +example /usr/src/bitcoin-abc, AND not under /mnt/d/. This means you cannot use a directory that located directly on the host Windows file system to perform the build. Acquire the source in the usual way: @@ -141,11 +146,12 @@ PATH=$(echo "$PATH" | sed -e 's/:\/mnt.*//g') # strip out problematic Windows %PATH% imported var cd depends - make HOST=i686-w64-mingw32 + make build-win32 cd .. - ./autogen.sh # not required when building from tarball - CONFIG_SITE=$PWD/depends/i686-w64-mingw32/share/config.site ./configure --prefix=/ --with-seeder=false # seeder not supported in Windows yet - make + mkdir build + cd build + cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/Win32.cmake -DBUILD_BITCOIN_SEEDER=OFF # seeder not supported in Windows yet + ninja ## Depends system @@ -159,7 +165,8 @@ as they appear in the release `.zip` archive. This can be done in the following way. This will install to `c:\workspace\bitcoin-abc`, for example: - make install DESTDIR=/mnt/c/workspace/bitcoin-abc + cmake -GNinja .. -DCMAKE_TOOLCHAIN_FILE=../cmake/platforms/Win32.cmake -DBUILD_BITCOIN_SEEDER=OFF -DCMAKE_INSTALL_PREFIX=/mnt/c/workspace/bitcoin-abc + ninja install Footnotes ---------