mirror of
https://github.com/bitcoin/bitcoin.git
synced 2024-11-19 01:42:58 +01:00
doc: Update for CMake-based build system
Co-authored-by: Lőrinc <pap.lorinc@gmail.com> Co-authored-by: pablomartin4btc <pablomartin4btc@gmail.com>
This commit is contained in:
Hennadii Stepanov
parent
9730288a0c
commit
6ce50fd9d0
@ -48,7 +48,7 @@ lots of money.
|
||||
|
||||
Developers are strongly encouraged to write [unit tests](src/test/README.md) for new code, and to
|
||||
submit new unit tests for old code. Unit tests can be compiled and run
|
||||
(assuming they weren't disabled in configure) with: `make check`. Further details on running
|
||||
(assuming they weren't disabled during the generation of the build system) with: `ctest`. Further details on running
|
||||
and extending unit tests can be found in [/src/test/README.md](/src/test/README.md).
|
||||
|
||||
There are also [regression and integration tests](/test), written
|
||||
|
||||
@ -261,6 +261,7 @@ details.
|
||||
|
||||
- `guix` build commands as in `guix shell --cores="$JOBS"`
|
||||
- `make` as in `make --jobs="$JOBS"`
|
||||
- `cmake` as in `cmake --build build -j "$JOBS"`
|
||||
- `xargs` as in `xargs -P"$JOBS"`
|
||||
|
||||
See [here](#controlling-the-number-of-threads-used-by-guix-build-commands) for
|
||||
|
||||
@ -12,17 +12,13 @@ For example:
|
||||
|
||||
make HOST=x86_64-w64-mingw32 -j4
|
||||
|
||||
**Bitcoin Core's `configure` script by default will ignore the depends output.** In
|
||||
**When configuring Bitcoin Core, CMake by default will ignore the depends output.** In
|
||||
order for it to pick up libraries, tools, and settings from the depends build,
|
||||
you must set the `CONFIG_SITE` environment variable to point to a `config.site` settings file.
|
||||
Make sure that `CONFIG_SITE` is an absolute path.
|
||||
In the above example, a file named `depends/x86_64-w64-mingw32/share/config.site` will be
|
||||
created. To use it during compilation:
|
||||
you must specify the toolchain file.
|
||||
In the above example, a file named `depends/x86_64-w64-mingw32/toolchain.cmake` will be
|
||||
created. To use it during configuring Bitcoin Core:
|
||||
|
||||
CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure
|
||||
|
||||
The default install prefix when using `config.site` is `--prefix=depends/<host-platform-triplet>`,
|
||||
so depends build outputs will be installed in that location.
|
||||
cmake -B build --toolchain depends/x86_64-w64-mingw32/toolchain.cmake
|
||||
|
||||
Common `host-platform-triplet`s for cross compilation are:
|
||||
|
||||
@ -90,9 +86,13 @@ For linux S390X cross compilation:
|
||||
|
||||
pkg install bash
|
||||
|
||||
### Install the required dependencies: NetBSD
|
||||
|
||||
pkgin install bash gmake
|
||||
|
||||
### Install the required dependencies: OpenBSD
|
||||
|
||||
pkg_add bash gtar
|
||||
pkg_add bash gmake gtar
|
||||
|
||||
### Dependency Options
|
||||
|
||||
@ -125,8 +125,8 @@ The following can be set when running make: `make FOO=bar`
|
||||
- `LTO`: Enable options needed for LTO. Does not add `-flto` related options to *FLAGS.
|
||||
- `NO_HARDEN=1`: Don't use hardening options when building packages
|
||||
|
||||
If some packages are not built, for example `make NO_WALLET=1`, the appropriate
|
||||
options will be passed to bitcoin's configure. In this case, `--disable-wallet`.
|
||||
If some packages are not built, for example `make NO_WALLET=1`, the appropriate CMake cache
|
||||
variables will be set when generating the Bitcoin Core buildsystem. In this case, `-DENABLE_WALLET=OFF`.
|
||||
|
||||
### Additional targets
|
||||
|
||||
|
||||
@ -41,7 +41,7 @@ The following are developer notes on how to build Bitcoin Core on your native pl
|
||||
- [Dependencies](dependencies.md)
|
||||
- [macOS Build Notes](build-osx.md)
|
||||
- [Unix Build Notes](build-unix.md)
|
||||
- [Windows Build Notes](build-windows.md)
|
||||
- [Windows Build Notes](build-windows-msvc.md)
|
||||
- [FreeBSD Build Notes](build-freebsd.md)
|
||||
- [OpenBSD Build Notes](build-openbsd.md)
|
||||
- [NetBSD Build Notes](build-netbsd.md)
|
||||
|
||||
@ -8,16 +8,17 @@ thread queue, wallet balance.
|
||||
Running
|
||||
---------------------
|
||||
|
||||
For benchmarking, you only need to compile `bitcoin_bench`. The bench runner
|
||||
warns if you configure with `--enable-debug`, but consider if building without
|
||||
For benchmarking, you only need to compile `bench_bitcoin`. The bench runner
|
||||
warns if you configure with `-DCMAKE_BUILD_TYPE=Debug`, but consider if building without
|
||||
it will impact the benchmark(s) you are interested in by unlatching log printers
|
||||
and lock analysis.
|
||||
|
||||
make -C src bitcoin_bench
|
||||
cmake -B build -DBUILD_BENCH=ON
|
||||
cmake --build build -t bench_bitcoin
|
||||
|
||||
After compiling bitcoin-core, the benchmarks can be run with:
|
||||
|
||||
src/bench/bench_bitcoin
|
||||
build/src/bench/bench_bitcoin
|
||||
|
||||
The output will look similar to:
|
||||
```
|
||||
@ -39,7 +40,7 @@ The output will look similar to:
|
||||
Help
|
||||
---------------------
|
||||
|
||||
src/bench/bench_bitcoin -?
|
||||
build/src/bench/bench_bitcoin -?
|
||||
|
||||
To print the various options, like listing the benchmarks without running them
|
||||
or using a regex filter to only run certain benchmarks.
|
||||
|
||||
@ -10,8 +10,7 @@ This guide describes how to build bitcoind, command-line utilities, and GUI on F
|
||||
Run the following as root to install the base dependencies for building.
|
||||
|
||||
```bash
|
||||
pkg install autoconf automake boost-libs git gmake libevent libtool pkgconf
|
||||
|
||||
pkg install boost-libs cmake git libevent pkgconf
|
||||
```
|
||||
|
||||
See [dependencies.md](dependencies.md) for a complete overview.
|
||||
@ -41,7 +40,8 @@ BerkeleyDB is only required if legacy wallet support is required.
|
||||
It is required to use Berkeley DB 4.8. You **cannot** use the BerkeleyDB library
|
||||
from ports. However, you can build DB 4.8 yourself [using depends](/depends).
|
||||
|
||||
```
|
||||
```bash
|
||||
pkg install gmake
|
||||
gmake -C depends NO_BOOST=1 NO_LIBEVENT=1 NO_QT=1 NO_SQLITE=1 NO_NATPMP=1 NO_UPNP=1 NO_ZMQ=1 NO_USDT=1
|
||||
```
|
||||
|
||||
@ -64,17 +64,23 @@ sh/bash: export BDB_PREFIX=[path displayed above]
|
||||
#### GUI Dependencies
|
||||
###### Qt5
|
||||
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install the necessary parts of Qt. Skip if you don't intend to use the GUI.
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install
|
||||
the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI.
|
||||
|
||||
```bash
|
||||
pkg install qt5-buildtools qt5-core qt5-gui qt5-linguisttools qt5-testlib qt5-widgets
|
||||
```
|
||||
|
||||
###### libqrencode
|
||||
|
||||
The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `libqrencode`. Skip if not using the GUI or don't want QR code functionality.
|
||||
The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run:
|
||||
|
||||
```bash
|
||||
pkg install libqrencode
|
||||
```
|
||||
|
||||
Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI.
|
||||
|
||||
---
|
||||
|
||||
#### Notifications
|
||||
@ -101,33 +107,28 @@ pkg install python3 databases/py-sqlite3
|
||||
There are many ways to configure Bitcoin Core, here are a few common examples:
|
||||
|
||||
##### Descriptor Wallet and GUI:
|
||||
This explicitly enables the GUI and disables legacy wallet support, assuming `sqlite` and `qt` are installed.
|
||||
This disables legacy wallet support and enables the GUI, assuming `sqlite` and `qt` are installed.
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure --without-bdb --with-gui=yes MAKE=gmake
|
||||
cmake -B build -DWITH_BDB=OFF -DBUILD_GUI=ON
|
||||
```
|
||||
|
||||
Run `cmake -B build -LH` to see the full list of available options.
|
||||
|
||||
##### Descriptor & Legacy Wallet. No GUI:
|
||||
This enables support for both wallet types and disables the GUI, assuming
|
||||
This enables support for both wallet types, assuming
|
||||
`sqlite3` and `db4` are both installed.
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure --with-gui=no \
|
||||
BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \
|
||||
BDB_CFLAGS="-I${BDB_PREFIX}/include" \
|
||||
MAKE=gmake
|
||||
cmake -B build -DBerkeleyDB_INCLUDE_DIR:PATH="${BDB_PREFIX}/include"
|
||||
```
|
||||
|
||||
##### No Wallet or GUI
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure --without-wallet --with-gui=no MAKE=gmake
|
||||
cmake -B build -DENABLE_WALLET=OFF
|
||||
```
|
||||
|
||||
### 2. Compile
|
||||
**Important**: Use `gmake` (the non-GNU `make` will exit with an error).
|
||||
|
||||
```bash
|
||||
gmake # use "-j N" for N parallel jobs
|
||||
gmake check # Run tests if Python 3 is available
|
||||
cmake --build build # Use "-j N" for N parallel jobs.
|
||||
ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
|
||||
```
|
||||
|
||||
@ -12,8 +12,7 @@ Install the required dependencies the usual way you [install software on NetBSD]
|
||||
The example commands below use `pkgin`.
|
||||
|
||||
```bash
|
||||
pkgin install autoconf automake libtool pkg-config git gmake boost-headers libevent
|
||||
|
||||
pkgin install git cmake pkg-config boost-headers libevent
|
||||
```
|
||||
|
||||
NetBSD currently ships with an older version of `gcc` than is needed to build. You should upgrade your `gcc` and then pass this new version to the configure script.
|
||||
@ -25,10 +24,10 @@ pkgin install gcc12
|
||||
|
||||
Then, when configuring, pass the following:
|
||||
```bash
|
||||
./configure
|
||||
cmake -B build
|
||||
...
|
||||
CC="/usr/pkg/gcc12/bin/gcc" \
|
||||
CXX="/usr/pkg/gcc12/bin/g++" \
|
||||
-DCMAKE_C_COMPILER="/usr/pkg/gcc12/bin/gcc" \
|
||||
-DCMAKE_CXX_COMPILER="/usr/pkg/gcc12/bin/g++" \
|
||||
...
|
||||
```
|
||||
|
||||
@ -65,19 +64,26 @@ pkgin install db4
|
||||
```
|
||||
|
||||
#### GUI Dependencies
|
||||
###### Qt5
|
||||
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, Qt 5 is required.
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install
|
||||
the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI.
|
||||
|
||||
```bash
|
||||
pkgin install qt5-qtbase qt5-qttools
|
||||
```
|
||||
|
||||
The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `qrencode`.
|
||||
###### libqrencode
|
||||
|
||||
The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run:
|
||||
|
||||
```bash
|
||||
pkgin install qrencode
|
||||
```
|
||||
|
||||
Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI.
|
||||
|
||||
|
||||
#### Test Suite Dependencies
|
||||
|
||||
There is an included test suite that is useful for testing code changes when developing.
|
||||
@ -89,28 +95,22 @@ pkgin install python39
|
||||
|
||||
### Building Bitcoin Core
|
||||
|
||||
**Note**: Use `gmake` (the non-GNU `make` will exit with an error).
|
||||
|
||||
|
||||
### 1. Configuration
|
||||
|
||||
There are many ways to configure Bitcoin Core. Here is an example that
|
||||
explicitly disables the wallet and GUI:
|
||||
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure --without-wallet --with-gui=no \
|
||||
CPPFLAGS="-I/usr/pkg/include" \
|
||||
MAKE=gmake
|
||||
cmake -B build -DENABLE_WALLET=OFF -DBUILD_GUI=OFF
|
||||
```
|
||||
|
||||
For a full list of configuration options, see the output of `./configure --help`
|
||||
Run `cmake -B build -LH` to see the full list of available options.
|
||||
|
||||
### 2. Compile
|
||||
|
||||
Build and run the tests:
|
||||
|
||||
```bash
|
||||
gmake # use "-j N" here for N parallel jobs
|
||||
gmake check # Run tests if Python 3 is available
|
||||
cmake --build build # Use "-j N" for N parallel jobs.
|
||||
ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
|
||||
```
|
||||
|
||||
@ -10,9 +10,7 @@ This guide describes how to build bitcoind, command-line utilities, and GUI on O
|
||||
Run the following as root to install the base dependencies for building.
|
||||
|
||||
```bash
|
||||
pkg_add bash git gmake libevent libtool boost
|
||||
# Select the newest version of the following packages:
|
||||
pkg_add autoconf automake python
|
||||
pkg_add git cmake boost libevent
|
||||
```
|
||||
|
||||
See [dependencies.md](dependencies.md) for a complete overview.
|
||||
@ -31,7 +29,7 @@ It is not necessary to build wallet functionality to run either `bitcoind` or `b
|
||||
|
||||
###### Descriptor Wallet Support
|
||||
|
||||
`sqlite3` is required to support [descriptor wallets](descriptors.md).
|
||||
SQLite is required to support [descriptor wallets](descriptors.md).
|
||||
|
||||
``` bash
|
||||
pkg_add sqlite3
|
||||
@ -48,19 +46,20 @@ Refer to [depends/README.md](/depends/README.md) for detailed instructions.
|
||||
```bash
|
||||
gmake -C depends NO_BOOST=1 NO_LIBEVENT=1 NO_QT=1 NO_SQLITE=1 NO_NATPMP=1 NO_UPNP=1 NO_ZMQ=1 NO_USDT=1
|
||||
...
|
||||
to: /path/to/bitcoin/depends/x86_64-unknown-openbsd
|
||||
to: /path/to/bitcoin/depends/*-unknown-openbsd*
|
||||
```
|
||||
|
||||
Then set `BDB_PREFIX`:
|
||||
|
||||
```bash
|
||||
export BDB_PREFIX="/path/to/bitcoin/depends/x86_64-unknown-openbsd"
|
||||
export BDB_PREFIX="[path displayed above]"
|
||||
```
|
||||
|
||||
#### GUI Dependencies
|
||||
###### Qt5
|
||||
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, Qt 5 is required.
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install
|
||||
the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI.
|
||||
|
||||
```bash
|
||||
pkg_add qtbase qttools
|
||||
@ -68,10 +67,14 @@ pkg_add qtbase qttools
|
||||
|
||||
###### libqrencode
|
||||
|
||||
The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `libqrencode`. Skip if not using the GUI or don't want QR code functionality.
|
||||
The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run:
|
||||
|
||||
```bash
|
||||
pkg_add libqrencode
|
||||
```
|
||||
|
||||
Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI.
|
||||
|
||||
---
|
||||
|
||||
#### Notifications
|
||||
@ -82,47 +85,41 @@ Bitcoin Core can provide notifications via ZeroMQ. If the package is installed,
|
||||
pkg_add zeromq
|
||||
```
|
||||
|
||||
## Building Bitcoin Core
|
||||
#### Test Suite Dependencies
|
||||
There is an included test suite that is useful for testing code changes when developing.
|
||||
To run the test suite (recommended), you will need to have Python 3 installed:
|
||||
|
||||
**Important**: Use `gmake` (the non-GNU `make` will exit with an error).
|
||||
|
||||
Preparation:
|
||||
```bash
|
||||
|
||||
# Adapt the following for the version you installed (major.minor only):
|
||||
export AUTOCONF_VERSION=2.71
|
||||
export AUTOMAKE_VERSION=1.16
|
||||
|
||||
./autogen.sh
|
||||
pkg_add install python # Select the newest version of the package.
|
||||
```
|
||||
|
||||
## Building Bitcoin Core
|
||||
|
||||
### 1. Configuration
|
||||
|
||||
There are many ways to configure Bitcoin Core, here are a few common examples:
|
||||
|
||||
##### Descriptor Wallet and GUI:
|
||||
This enables the GUI and descriptor wallet support, assuming `sqlite` and `qt5` are installed.
|
||||
This enables descriptor wallet support and the GUI, assuming SQLite and Qt 5 are installed.
|
||||
|
||||
```bash
|
||||
./configure MAKE=gmake
|
||||
cmake -B build -DWITH_SQLITE=ON -DBUILD_GUI=ON
|
||||
```
|
||||
|
||||
Run `cmake -B build -LH` to see the full list of available options.
|
||||
|
||||
##### Descriptor & Legacy Wallet. No GUI:
|
||||
This enables support for both wallet types and disables the GUI:
|
||||
This enables support for both wallet types:
|
||||
|
||||
```bash
|
||||
./configure --with-gui=no \
|
||||
BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \
|
||||
BDB_CFLAGS="-I${BDB_PREFIX}/include" \
|
||||
MAKE=gmake
|
||||
cmake -B build -DBerkeleyDB_INCLUDE_DIR:PATH="${BDB_PREFIX}/include"
|
||||
```
|
||||
|
||||
### 2. Compile
|
||||
**Important**: Use `gmake` (the non-GNU `make` will exit with an error).
|
||||
|
||||
```bash
|
||||
gmake # use "-j N" for N parallel jobs
|
||||
gmake check # Run tests if Python 3 is available
|
||||
cmake --build build # Use "-j N" for N parallel jobs.
|
||||
ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
|
||||
```
|
||||
|
||||
## Resource limits
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# macOS Build Guide
|
||||
|
||||
**Updated for MacOS [11.2](https://www.apple.com/macos/big-sur/)**
|
||||
**Updated for MacOS [14.4](https://www.apple.com/macos/sonoma/)**
|
||||
|
||||
This guide describes how to build bitcoind, command-line utilities, and GUI on macOS
|
||||
|
||||
@ -48,7 +48,7 @@ See [dependencies.md](dependencies.md) for a complete overview.
|
||||
To install, run the following from your terminal:
|
||||
|
||||
``` bash
|
||||
brew install automake libtool boost pkg-config libevent
|
||||
brew install cmake boost pkg-config libevent
|
||||
```
|
||||
|
||||
For macOS 11 (Big Sur) and 12 (Monterey) you need to install a more recent version of llvm.
|
||||
@ -102,9 +102,8 @@ brew install berkeley-db@4
|
||||
|
||||
###### Qt
|
||||
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework.
|
||||
To compile the GUI, we need to install `qt@5`.
|
||||
Skip if you don't intend to use the GUI.
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install
|
||||
the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI.
|
||||
|
||||
``` bash
|
||||
brew install qt@5
|
||||
@ -113,14 +112,16 @@ brew install qt@5
|
||||
Note: Building with Qt binaries downloaded from the Qt website is not officially supported.
|
||||
See the notes in [#7714](https://github.com/bitcoin/bitcoin/issues/7714).
|
||||
|
||||
###### qrencode
|
||||
###### libqrencode
|
||||
|
||||
The GUI can encode addresses in a QR Code. To build in QR support for the GUI, install `qrencode`.
|
||||
Skip if not using the GUI or don't want QR code functionality.
|
||||
The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run:
|
||||
|
||||
``` bash
|
||||
brew install qrencode
|
||||
```
|
||||
|
||||
Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI.
|
||||
|
||||
---
|
||||
|
||||
#### Port Mapping Dependencies
|
||||
@ -177,7 +178,7 @@ brew install python
|
||||
|
||||
#### Deploy Dependencies
|
||||
|
||||
You can deploy a `.zip` containing the Bitcoin Core application using `make deploy`.
|
||||
You can [deploy](#3-deploy-optional) a `.zip` containing the Bitcoin Core application.
|
||||
It is required that you have `python` installed.
|
||||
|
||||
## Building Bitcoin Core
|
||||
@ -188,32 +189,25 @@ There are many ways to configure Bitcoin Core, here are a few common examples:
|
||||
|
||||
##### Wallet (BDB + SQlite) Support, No GUI:
|
||||
|
||||
If `berkeley-db@4` is installed, then legacy wallet support will be built.
|
||||
If `sqlite` is installed, then descriptor wallet support will also be built.
|
||||
Additionally, this explicitly disables the GUI.
|
||||
If `berkeley-db@4` or `sqlite` are not installed, this will throw an error.
|
||||
|
||||
``` bash
|
||||
./autogen.sh
|
||||
./configure --with-gui=no
|
||||
cmake -B build -DWITH_BDB=ON
|
||||
```
|
||||
|
||||
##### Wallet (only SQlite) and GUI Support:
|
||||
|
||||
This explicitly enables the GUI and disables legacy wallet support.
|
||||
If `qt` is not installed, this will throw an error.
|
||||
If `sqlite` is installed then descriptor wallet functionality will be built.
|
||||
If `sqlite` is not installed, then wallet functionality will be disabled.
|
||||
This enables the GUI.
|
||||
If `sqlite` or `qt` are not installed, this will throw an error.
|
||||
|
||||
``` bash
|
||||
./autogen.sh
|
||||
./configure --without-bdb --with-gui=yes
|
||||
cmake -B build -DBUILD_GUI=ON
|
||||
```
|
||||
|
||||
##### No Wallet or GUI
|
||||
|
||||
``` bash
|
||||
./autogen.sh
|
||||
./configure --without-wallet --with-gui=no
|
||||
cmake -B build -DENABLE_WALLET=OFF
|
||||
```
|
||||
|
||||
##### Further Configuration
|
||||
@ -222,7 +216,7 @@ You may want to dig deeper into the configuration options to achieve your desire
|
||||
Examine the output of the following command for a full list of configuration options:
|
||||
|
||||
``` bash
|
||||
./configure -help
|
||||
cmake -B build -LH
|
||||
```
|
||||
|
||||
### 2. Compile
|
||||
@ -231,8 +225,8 @@ After configuration, you are ready to compile.
|
||||
Run the following in your terminal to compile Bitcoin Core:
|
||||
|
||||
``` bash
|
||||
make # use "-j N" here for N parallel jobs
|
||||
make check # Run tests if Python 3 is available
|
||||
cmake --build build # Use "-j N" here for N parallel jobs.
|
||||
ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
|
||||
```
|
||||
|
||||
### 3. Deploy (optional)
|
||||
@ -240,7 +234,7 @@ make check # Run tests if Python 3 is available
|
||||
You can also create a `.zip` containing the `.app` bundle by running the following command:
|
||||
|
||||
``` bash
|
||||
make deploy
|
||||
cmake --build build --target deploy
|
||||
```
|
||||
|
||||
## Running Bitcoin Core
|
||||
@ -276,8 +270,8 @@ tail -f $HOME/Library/Application\ Support/Bitcoin/debug.log
|
||||
## Other commands:
|
||||
|
||||
```shell
|
||||
./src/bitcoind -daemon # Starts the bitcoin daemon.
|
||||
./src/bitcoin-cli --help # Outputs a list of command-line options.
|
||||
./src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running.
|
||||
./src/qt/bitcoin-qt -server # Starts the bitcoin-qt server mode, allows bitcoin-cli control
|
||||
./build/src/bitcoind -daemon # Starts the bitcoin daemon.
|
||||
./build/src/bitcoin-cli --help # Outputs a list of command-line options.
|
||||
./build/src/bitcoin-cli help # Outputs a list of RPC commands when the daemon is running.
|
||||
./build/src/qt/bitcoin-qt -server # Starts the bitcoin-qt server mode, allows bitcoin-cli control
|
||||
```
|
||||
|
||||
@ -8,10 +8,9 @@ To Build
|
||||
---------------------
|
||||
|
||||
```bash
|
||||
./autogen.sh
|
||||
./configure
|
||||
make # use "-j N" for N parallel jobs
|
||||
make install # optional
|
||||
cmake -B build
|
||||
cmake --build build # use "-j N" for N parallel jobs
|
||||
cmake --install build # optional
|
||||
```
|
||||
|
||||
See below for instructions on how to [install the dependencies on popular Linux
|
||||
@ -22,19 +21,20 @@ distributions](#linux-distribution-specific-instructions), or the
|
||||
|
||||
C++ compilers are memory-hungry. It is recommended to have at least 1.5 GB of
|
||||
memory available when compiling Bitcoin Core. On systems with less, gcc can be
|
||||
tuned to conserve memory with additional CXXFLAGS:
|
||||
tuned to conserve memory with additional `CMAKE_CXX_FLAGS`:
|
||||
|
||||
|
||||
./configure CXXFLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"
|
||||
cmake -B build -DCMAKE_CXX_FLAGS="--param ggc-min-expand=1 --param ggc-min-heapsize=32768"
|
||||
|
||||
Alternatively, or in addition, debugging information can be skipped for compilation. The default compile flags are
|
||||
`-g -O2`, and can be changed with:
|
||||
Alternatively, or in addition, debugging information can be skipped for compilation.
|
||||
For the default build type `RelWithDebInfo`, the default compile flags are
|
||||
`-O2 -g`, and can be changed with:
|
||||
|
||||
./configure CXXFLAGS="-g0"
|
||||
cmake -B build -DCMAKE_CXX_FLAGS_RELWITHDEBINFO="-O2 -g0"
|
||||
|
||||
Finally, clang (often less resource hungry) can be used instead of gcc, which is used by default:
|
||||
|
||||
./configure CXX=clang++ CC=clang
|
||||
cmake -B build -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_CC_COMPILER=clang
|
||||
|
||||
## Linux Distribution Specific Instructions
|
||||
|
||||
@ -44,7 +44,7 @@ Finally, clang (often less resource hungry) can be used instead of gcc, which is
|
||||
|
||||
Build requirements:
|
||||
|
||||
sudo apt-get install build-essential libtool autotools-dev automake pkg-config bsdmainutils python3
|
||||
sudo apt-get install build-essential cmake pkg-config bsdmainutils python3
|
||||
|
||||
Now, you can either build from self-compiled [depends](#dependencies) or install the required dependencies:
|
||||
|
||||
@ -56,12 +56,11 @@ SQLite is required for the descriptor wallet:
|
||||
|
||||
Berkeley DB is only required for the legacy wallet. Ubuntu and Debian have their own `libdb-dev` and `libdb++-dev` packages,
|
||||
but these will install Berkeley DB 5.3 or later. This will 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. Otherwise, you can build Berkeley DB [yourself](#berkeley-db).
|
||||
executables, which are based on BerkeleyDB 4.8. Otherwise, you can build Berkeley DB [yourself](#berkeley-db).
|
||||
|
||||
To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode)
|
||||
|
||||
Optional port mapping libraries (see: `--with-miniupnpc` and `--with-natpmp`):
|
||||
Optional port mapping libraries (see: `-DWITH_MINIUPNPC=ON` and `-DWITH_NATPMP=ON`):
|
||||
|
||||
sudo apt install libminiupnpc-dev libnatpmp-dev
|
||||
|
||||
@ -75,11 +74,8 @@ User-Space, Statically Defined Tracing (USDT) dependencies:
|
||||
|
||||
GUI dependencies:
|
||||
|
||||
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 with Qt 5 you need the following:
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install
|
||||
the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI.
|
||||
|
||||
sudo apt-get install qtbase5-dev qttools5-dev qttools5-dev-tools
|
||||
|
||||
@ -87,12 +83,11 @@ Additionally, to support Wayland protocol for modern desktop environments:
|
||||
|
||||
sudo apt install qtwayland5
|
||||
|
||||
libqrencode (optional) can be installed with:
|
||||
The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run:
|
||||
|
||||
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.
|
||||
Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI.
|
||||
|
||||
|
||||
### Fedora
|
||||
@ -118,7 +113,7 @@ pass `--with-incompatible-bdb` to configure. Otherwise, you can build Berkeley D
|
||||
|
||||
To build Bitcoin Core without wallet, see [*Disable-wallet mode*](#disable-wallet-mode)
|
||||
|
||||
Optional port mapping libraries (see: `--with-miniupnpc` and `--with-natpmp`):
|
||||
Optional port mapping libraries (see: `-DWITH_MINIUPNPC=ON` and `-DWITH_NATPMP=ON`):
|
||||
|
||||
sudo dnf install miniupnpc-devel libnatpmp-devel
|
||||
|
||||
@ -132,11 +127,8 @@ User-Space, Statically Defined Tracing (USDT) dependencies:
|
||||
|
||||
GUI dependencies:
|
||||
|
||||
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 with Qt 5 you need the following:
|
||||
Bitcoin Core includes a GUI built with the cross-platform Qt Framework. To compile the GUI, we need to install
|
||||
the necessary parts of Qt, the libqrencode and pass `-DBUILD_GUI=ON`. Skip if you don't intend to use the GUI.
|
||||
|
||||
sudo dnf install qt5-qttools-devel qt5-qtbase-devel
|
||||
|
||||
@ -144,12 +136,11 @@ Additionally, to support Wayland protocol for modern desktop environments:
|
||||
|
||||
sudo dnf install qt5-qtwayland
|
||||
|
||||
libqrencode (optional) can be installed with:
|
||||
The GUI will be able to encode addresses in QR codes unless this feature is explicitly disabled. To install libqrencode, run:
|
||||
|
||||
sudo dnf install qrencode-devel
|
||||
|
||||
Once these are installed, they will be found by configure and a bitcoin-qt executable will be
|
||||
built by default.
|
||||
Otherwise, if you don't need QR encoding support, use the `-DWITH_QRENCODE=OFF` option to disable this feature in order to compile the GUI.
|
||||
|
||||
## Dependencies
|
||||
|
||||
@ -171,9 +162,7 @@ and configure using the following:
|
||||
```bash
|
||||
export BDB_PREFIX="/path/to/bitcoin/depends/x86_64-pc-linux-gnu"
|
||||
|
||||
./configure \
|
||||
BDB_LIBS="-L${BDB_PREFIX}/lib -ldb_cxx-4.8" \
|
||||
BDB_CFLAGS="-I${BDB_PREFIX}/include"
|
||||
cmake -B build -DBerkeleyDB_INCLUDE_DIR:PATH="${BDB_PREFIX}/include"
|
||||
```
|
||||
|
||||
**Note**: Make sure that `BDB_PREFIX` is an absolute path.
|
||||
@ -185,7 +174,7 @@ Disable-wallet mode
|
||||
When the intention is to only run a P2P node, without a wallet, Bitcoin Core can
|
||||
be compiled in disable-wallet mode with:
|
||||
|
||||
./configure --disable-wallet
|
||||
cmake -B build -DENABLE_WALLET=OFF
|
||||
|
||||
In this case there is no dependency on SQLite or Berkeley DB.
|
||||
|
||||
@ -195,19 +184,19 @@ Additional Configure Flags
|
||||
--------------------------
|
||||
A list of additional configure flags can be displayed with:
|
||||
|
||||
./configure --help
|
||||
cmake -B build -LH
|
||||
|
||||
|
||||
Setup and Build Example: Arch Linux
|
||||
-----------------------------------
|
||||
This example lists the steps necessary to setup and build a command line only distribution of the latest changes on Arch Linux:
|
||||
|
||||
pacman --sync --needed autoconf automake boost gcc git libevent libtool make pkgconf python sqlite
|
||||
pacman --sync --needed cmake boost gcc git libevent make pkgconf python sqlite
|
||||
git clone https://github.com/bitcoin/bitcoin.git
|
||||
cd bitcoin/
|
||||
./autogen.sh
|
||||
./configure
|
||||
make check
|
||||
./src/bitcoind
|
||||
cmake -B build
|
||||
cmake --build build
|
||||
ctest --test-dir build
|
||||
./build/src/bitcoind
|
||||
|
||||
If you intend to work with legacy Berkeley DB wallets, see [Berkeley DB](#berkeley-db) section.
|
||||
|
||||
82
doc/build-windows-msvc.md
Normal file
82
doc/build-windows-msvc.md
Normal file
@ -0,0 +1,82 @@
|
||||
# Windows / MSVC Build Guide
|
||||
|
||||
This guide describes how to build bitcoind, command-line utilities, and GUI on Windows using Micsrosoft Visual Studio.
|
||||
|
||||
For cross-compiling options, please see [`build-windows.md`](./build-windows.md).
|
||||
|
||||
## Preparation
|
||||
|
||||
### 1. Visual Studio
|
||||
|
||||
This guide relies on using CMake and vcpkg package manager provided with the Visual Studio installation.
|
||||
Here are requirements for the Visual Studio installation:
|
||||
1. Minimum required version: Visual Studio 2022 version 17.6.
|
||||
2. Installed components:
|
||||
- The "Desktop development with C++" workload.
|
||||
|
||||
The commands in this guide should be executed in "Developer PowerShell for VS 2022" or "Developer Command Prompt for VS 2022".
|
||||
The former is assumed hereinafter.
|
||||
|
||||
### 2. Git
|
||||
|
||||
Download and install [Git for Windows](https://git-scm.com/download/win). Once installed, Git is available from PowerShell or the Command Prompt.
|
||||
|
||||
### 3. Clone Bitcoin Repository
|
||||
|
||||
Clone the Bitcoin Core repository to a directory. All build scripts and commands will run from this directory.
|
||||
```
|
||||
git clone https://github.com/bitcoin/bitcoin.git
|
||||
```
|
||||
|
||||
|
||||
## Triplets and Presets
|
||||
|
||||
The Bitcoin Core project supports the following vcpkg triplets:
|
||||
- `x64-windows` (both CRT and library linkage is dynamic)
|
||||
- `x64-windows-static` (both CRT and library linkage is static)
|
||||
|
||||
To facilitate build process, the Bitcoin Core project provides presets, which are used in this guide.
|
||||
|
||||
Available presets can be listed as follows:
|
||||
```
|
||||
cmake --list-presets
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
CMake will put the resulting object files, libraries, and executables into a dedicated build directory.
|
||||
|
||||
In following istructions, the "Debug" configuration can be specified instead of the "Release" one.
|
||||
|
||||
### 4. Building with Dynamic Linking with GUI
|
||||
|
||||
```
|
||||
cmake -B build --preset vs2022 -DBUILD_GUI=ON # It might take a while if the vcpkg binary cache is unpopulated or invalidated.
|
||||
cmake --build build --config Release # Use "-j N" for N parallel jobs.
|
||||
ctest --test-dir build --build-config Release # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
|
||||
```
|
||||
|
||||
### 5. Building with Static Linking without GUI
|
||||
|
||||
```
|
||||
cmake -B build --preset vs2022-static # It might take a while if the vcpkg binary cache is unpopulated or invalidated.
|
||||
cmake --build build --config Release # Use "-j N" for N parallel jobs.
|
||||
ctest --test-dir build --build-config Release # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
|
||||
cmake --install build --config Release # Optional.
|
||||
```
|
||||
|
||||
## Performance Notes
|
||||
|
||||
### 6. vcpkg Manifest Default Features
|
||||
|
||||
One can skip vcpkg manifest default features to speedup the configuration step.
|
||||
For example, the following invocation will skip all features except for "wallet" and "tests" and their dependencies:
|
||||
```
|
||||
cmake -B build --preset vs2022 -DVCPKG_MANIFEST_NO_DEFAULT_FEATURES=ON -DVCPKG_MANIFEST_FEATURES="wallet;tests" -DBUILD_GUI=OFF
|
||||
```
|
||||
|
||||
Available features are listed in the [`vcpkg.json`](/vcpkg.json) file.
|
||||
|
||||
### 7. Antivirus Software
|
||||
|
||||
To improve the build process performance, one might add the Bitcoin repository directory to the Microsoft Defender Antivirus exclusions.
|
||||
@ -7,7 +7,7 @@ The options known to work for building Bitcoin Core on Windows are:
|
||||
|
||||
* On Linux, using the [Mingw-w64](https://www.mingw-w64.org/) cross compiler tool chain.
|
||||
* On Windows, using [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/about) and Mingw-w64.
|
||||
* On Windows, using [Microsoft Visual Studio](https://visualstudio.microsoft.com). See [README.md](/build_msvc/README.md).
|
||||
* On Windows, using [Microsoft Visual Studio](https://visualstudio.microsoft.com). See [`build-windows-msvc.md`](./build-windows-msvc.md).
|
||||
|
||||
Other options which may work, but which have not been extensively tested are (please contribute instructions):
|
||||
|
||||
@ -32,14 +32,14 @@ First, install the general dependencies:
|
||||
|
||||
sudo apt update
|
||||
sudo apt upgrade
|
||||
sudo apt install build-essential libtool autotools-dev automake pkg-config bsdmainutils cmake curl git
|
||||
sudo apt install cmake curl g++ git make pkg-config
|
||||
|
||||
A host toolchain (`build-essential`) is necessary because some dependency
|
||||
A host toolchain (`g++`) is necessary because some dependency
|
||||
packages need to build host utilities that are used in the build process.
|
||||
|
||||
See [dependencies.md](dependencies.md) for a complete overview.
|
||||
|
||||
If you want to build the windows installer with `make deploy` you need [NSIS](https://nsis.sourceforge.io/Main_Page):
|
||||
If you want to build the Windows installer using the `deploy` build target, you will need [NSIS](https://nsis.sourceforge.io/Main_Page):
|
||||
|
||||
sudo apt install nsis
|
||||
|
||||
@ -62,21 +62,12 @@ Note that for WSL the Bitcoin Core source path MUST be somewhere in the default
|
||||
example /usr/src/bitcoin, AND not under /mnt/d/. If this is not the case the dependency autoconf scripts will fail.
|
||||
This means you cannot use a directory that is located directly on the host Windows file system to perform the build.
|
||||
|
||||
Additional WSL Note: WSL support for [launching Win32 applications](https://learn.microsoft.com/en-us/archive/blogs/wsl/windows-and-ubuntu-interoperability#launching-win32-applications-from-within-wsl)
|
||||
results in `Autoconf` configure scripts being able to execute Windows Portable Executable files. This can cause
|
||||
unexpected behaviour during the build, such as Win32 error dialogs for missing libraries. The recommended approach
|
||||
is to temporarily disable WSL support for Win32 applications.
|
||||
|
||||
Build using:
|
||||
|
||||
sudo bash -c "echo 0 > /proc/sys/fs/binfmt_misc/status" # Disable WSL support for Win32 applications.
|
||||
cd depends
|
||||
make HOST=x86_64-w64-mingw32
|
||||
cd ..
|
||||
./autogen.sh
|
||||
CONFIG_SITE=$PWD/depends/x86_64-w64-mingw32/share/config.site ./configure --prefix=/
|
||||
make # use "-j N" for N parallel jobs
|
||||
sudo bash -c "echo 1 > /proc/sys/fs/binfmt_misc/status" # Enable WSL support for Win32 applications.
|
||||
gmake -C depends HOST=x86_64-w64-mingw32 # Use "-j N" for N parallel jobs.
|
||||
cmake -B build --toolchain depends/x86_64-w64-mingw32/toolchain.cmake
|
||||
cmake --build build # Use "-j N" for N parallel jobs.
|
||||
ctest --test-dir build # Use "-j N" for N parallel tests. Some tests are disabled if Python 3 is not available.
|
||||
|
||||
## Depends system
|
||||
|
||||
@ -90,8 +81,8 @@ executables to a directory on the Windows drive in the same directory structure
|
||||
as they appear in the release `.zip` archive. This can be done in the following
|
||||
way. This will install to `c:\workspace\bitcoin`, for example:
|
||||
|
||||
make install DESTDIR=/mnt/c/workspace/bitcoin
|
||||
cmake --install build --prefix /mnt/c/workspace/bitcoin
|
||||
|
||||
You can also create an installer using:
|
||||
|
||||
make deploy
|
||||
cmake --build build --target deploy
|
||||
|
||||
@ -7,12 +7,15 @@ To quickly get started fuzzing Bitcoin Core using [libFuzzer](https://llvm.org/d
|
||||
```sh
|
||||
$ git clone https://github.com/bitcoin/bitcoin
|
||||
$ cd bitcoin/
|
||||
$ ./autogen.sh
|
||||
$ CC=clang CXX=clang++ ./configure --enable-fuzz --with-sanitizers=address,fuzzer,undefined
|
||||
$ cmake -B build_fuzz \
|
||||
-DCMAKE_C_COMPILER="clang" \
|
||||
-DCMAKE_CXX_COMPILER="clang++" \
|
||||
-DBUILD_FOR_FUZZING=ON \
|
||||
-DSANITIZERS=undefined,address,fuzzer
|
||||
# macOS users: If you have problem with this step then make sure to read "macOS hints for
|
||||
# libFuzzer" on https://github.com/bitcoin/bitcoin/blob/master/doc/fuzzing.md#macos-hints-for-libfuzzer
|
||||
$ make
|
||||
$ FUZZ=process_message src/test/fuzz/fuzz
|
||||
$ cmake --build build_fuzz
|
||||
$ FUZZ=process_message build_fuzz/src/test/fuzz/fuzz
|
||||
# abort fuzzing using ctrl-c
|
||||
```
|
||||
|
||||
@ -33,7 +36,7 @@ If you specify a corpus directory then any new coverage increasing inputs will b
|
||||
|
||||
```sh
|
||||
$ mkdir -p process_message-seeded-from-thin-air/
|
||||
$ FUZZ=process_message src/test/fuzz/fuzz process_message-seeded-from-thin-air/
|
||||
$ FUZZ=process_message build_fuzz/src/test/fuzz/fuzz process_message-seeded-from-thin-air/
|
||||
INFO: Seed: 840522292
|
||||
INFO: Loaded 1 modules (424174 inline 8-bit counters): 424174 [0x55e121ef9ab8, 0x55e121f613a6),
|
||||
INFO: Loaded 1 PC tables (424174 PCs): 424174 [0x55e121f613a8,0x55e1225da288),
|
||||
@ -77,7 +80,7 @@ of the test. Just make sure to use double-dash to distinguish them from the
|
||||
fuzzer's own arguments:
|
||||
|
||||
```sh
|
||||
$ FUZZ=address_deserialize_v2 src/test/fuzz/fuzz -runs=1 fuzz_seed_corpus/address_deserialize_v2 --checkaddrman=5 --printtoconsole=1
|
||||
$ FUZZ=address_deserialize_v2 build_fuzz/src/test/fuzz/fuzz -runs=1 fuzz_seed_corpus/address_deserialize_v2 --checkaddrman=5 --printtoconsole=1
|
||||
```
|
||||
|
||||
## Fuzzing corpora
|
||||
@ -88,7 +91,7 @@ To fuzz `process_message` using the [`bitcoin-core/qa-assets`](https://github.co
|
||||
|
||||
```sh
|
||||
$ git clone https://github.com/bitcoin-core/qa-assets
|
||||
$ FUZZ=process_message src/test/fuzz/fuzz qa-assets/fuzz_seed_corpus/process_message/
|
||||
$ FUZZ=process_message build_fuzz/src/test/fuzz/fuzz qa-assets/fuzz_seed_corpus/process_message/
|
||||
INFO: Seed: 1346407872
|
||||
INFO: Loaded 1 modules (424174 inline 8-bit counters): 424174 [0x55d8a9004ab8, 0x55d8a906c3a6),
|
||||
INFO: Loaded 1 PC tables (424174 PCs): 424174 [0x55d8a906c3a8,0x55d8a96e5288),
|
||||
@ -101,7 +104,15 @@ INFO: seed corpus: files: 991 min: 1b max: 1858b total: 288291b rss: 150Mb
|
||||
|
||||
## Run without sanitizers for increased throughput
|
||||
|
||||
Fuzzing on a harness compiled with `--with-sanitizers=address,fuzzer,undefined` is good for finding bugs. However, the very slow execution even under libFuzzer will limit the ability to find new coverage. A good approach is to perform occasional long runs without the additional bug-detectors (configure `--with-sanitizers=fuzzer`) and then merge new inputs into a corpus as described in the qa-assets repo (https://github.com/bitcoin-core/qa-assets/blob/main/.github/PULL_REQUEST_TEMPLATE.md). Patience is useful; even with improved throughput, libFuzzer may need days and 10s of millions of executions to reach deep/hard targets.
|
||||
Fuzzing on a harness compiled with `-DSANITIZERS=address,fuzzer,undefined` is
|
||||
good for finding bugs. However, the very slow execution even under libFuzzer
|
||||
will limit the ability to find new coverage. A good approach is to perform
|
||||
occasional long runs without the additional bug-detectors (just
|
||||
`-DSANITIZERS=fuzzer`) and then merge new inputs into a corpus as described in
|
||||
the qa-assets repo
|
||||
(https://github.com/bitcoin-core/qa-assets/blob/main/.github/PULL_REQUEST_TEMPLATE.md).
|
||||
Patience is useful; even with improved throughput, libFuzzer may need days and
|
||||
10s of millions of executions to reach deep/hard targets.
|
||||
|
||||
## Reproduce a fuzzer crash reported by the CI
|
||||
|
||||
@ -112,7 +123,7 @@ Fuzzing on a harness compiled with `--with-sanitizers=address,fuzzer,undefined`
|
||||
more slowly with sanitizers enabled, but a crash should be reproducible very
|
||||
quickly from a crash case)
|
||||
- run the fuzzer with the case number appended to the seed corpus path:
|
||||
`FUZZ=process_message src/test/fuzz/fuzz
|
||||
`FUZZ=process_message build_fuzz/src/test/fuzz/fuzz
|
||||
qa-assets/fuzz_seed_corpus/process_message/1bc91feec9fc00b107d97dc225a9f2cdaa078eb6`
|
||||
|
||||
## Submit improved coverage
|
||||
@ -131,10 +142,15 @@ You may also need to take care of giving the correct path for `clang` and
|
||||
`clang++`, like `CC=/path/to/clang CXX=/path/to/clang++` if the non-systems
|
||||
`clang` does not come first in your path.
|
||||
|
||||
Full configure that was tested on macOS with `brew` installed `llvm`:
|
||||
Full configuration step that was tested on macOS with `brew` installed `llvm`:
|
||||
|
||||
```sh
|
||||
./configure --enable-fuzz --with-sanitizers=fuzzer,address,undefined CC=$(brew --prefix llvm)/bin/clang CXX=$(brew --prefix llvm)/bin/clang++
|
||||
$ cmake -B build_fuzz \
|
||||
-DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" \
|
||||
-DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++" \
|
||||
-DBUILD_FOR_FUZZING=ON \
|
||||
-DSANITIZERS=undefined,address,fuzzer \
|
||||
-DAPPEND_LDFLAGS=-Wl,-no_warn_duplicate_libraries
|
||||
```
|
||||
|
||||
Read the [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) for more information. This [libFuzzer tutorial](https://github.com/google/fuzzing/blob/master/tutorial/libFuzzerTutorial.md) might also be of interest.
|
||||
@ -150,16 +166,18 @@ $ git clone https://github.com/bitcoin/bitcoin
|
||||
$ cd bitcoin/
|
||||
$ git clone https://github.com/AFLplusplus/AFLplusplus
|
||||
$ make -C AFLplusplus/ source-only
|
||||
$ ./autogen.sh
|
||||
# If afl-clang-lto is not available, see
|
||||
# https://github.com/AFLplusplus/AFLplusplus#a-selecting-the-best-afl-compiler-for-instrumenting-the-target
|
||||
$ CC=$(pwd)/AFLplusplus/afl-clang-lto CXX=$(pwd)/AFLplusplus/afl-clang-lto++ ./configure --enable-fuzz
|
||||
$ make
|
||||
# For macOS you may need to ignore x86 compilation checks when running "make". If so,
|
||||
# try compiling using: AFL_NO_X86=1 make
|
||||
$ cmake -B build_fuzz \
|
||||
-DCMAKE_C_COMPILER="$(pwd)/AFLplusplus/afl-clang-lto" \
|
||||
-DCMAKE_CXX_COMPILER="$(pwd)/AFLplusplus/afl-clang-lto++" \
|
||||
-DBUILD_FOR_FUZZING=ON
|
||||
$ cmake --build build_fuzz
|
||||
# For macOS you may need to ignore x86 compilation checks when running "cmake --build". If so,
|
||||
# try compiling using: AFL_NO_X86=1 cmake --build build_fuzz
|
||||
$ mkdir -p inputs/ outputs/
|
||||
$ echo A > inputs/thin-air-input
|
||||
$ FUZZ=bech32 AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- src/test/fuzz/fuzz
|
||||
$ FUZZ=bech32 ./AFLplusplus/afl-fuzz -i inputs/ -o outputs/ -- build_fuzz/src/test/fuzz/fuzz
|
||||
# You may have to change a few kernel parameters to test optimally - afl-fuzz
|
||||
# will print an error and suggestion if so.
|
||||
```
|
||||
@ -175,15 +193,18 @@ To quickly get started fuzzing Bitcoin Core using [Honggfuzz](https://github.com
|
||||
```sh
|
||||
$ git clone https://github.com/bitcoin/bitcoin
|
||||
$ cd bitcoin/
|
||||
$ ./autogen.sh
|
||||
$ git clone https://github.com/google/honggfuzz
|
||||
$ cd honggfuzz/
|
||||
$ make
|
||||
$ cd ..
|
||||
$ CC=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang CXX=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++ ./configure --enable-fuzz --with-sanitizers=address,undefined
|
||||
$ make
|
||||
$ cmake -B build_fuzz \
|
||||
-DCMAKE_C_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang" \
|
||||
-DCMAKE_CXX_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++" \
|
||||
-DBUILD_FOR_FUZZING=ON \
|
||||
-DSANITIZERS=address,undefined
|
||||
$ cmake --build build_fuzz
|
||||
$ mkdir -p inputs/
|
||||
$ FUZZ=process_message honggfuzz/honggfuzz -i inputs/ -- src/test/fuzz/fuzz
|
||||
$ FUZZ=process_message ./honggfuzz/honggfuzz -i inputs/ -- build_fuzz/src/test/fuzz/fuzz
|
||||
```
|
||||
|
||||
Read the [Honggfuzz documentation](https://github.com/google/honggfuzz/blob/master/docs/USAGE.md) for more information.
|
||||
@ -204,15 +225,10 @@ $ mkdir bitcoin-honggfuzz-p2p/
|
||||
$ cd bitcoin-honggfuzz-p2p/
|
||||
$ git clone https://github.com/bitcoin/bitcoin
|
||||
$ cd bitcoin/
|
||||
$ ./autogen.sh
|
||||
$ git clone https://github.com/google/honggfuzz
|
||||
$ cd honggfuzz/
|
||||
$ make
|
||||
$ cd ..
|
||||
$ CC=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang \
|
||||
CXX=$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++ \
|
||||
./configure --disable-wallet --with-gui=no \
|
||||
--with-sanitizers=address,undefined
|
||||
$ git apply << "EOF"
|
||||
diff --git a/src/compat/compat.h b/src/compat/compat.h
|
||||
index 8195bceaec..cce2b31ff0 100644
|
||||
@ -254,11 +270,17 @@ index 7601a6ea84..702d0f56ce 100644
|
||||
SanitizeString(msg.m_type), msg.m_message_size,
|
||||
HexStr(Span{hash}.first(CMessageHeader::CHECKSUM_SIZE)),
|
||||
EOF
|
||||
$ make -C src/ bitcoind
|
||||
$ cmake -B build_fuzz \
|
||||
-DCMAKE_C_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang" \
|
||||
-DCMAKE_CXX_COMPILER="$(pwd)/honggfuzz/hfuzz_cc/hfuzz-clang++" \
|
||||
-DENABLE_WALLET=OFF \
|
||||
-DBUILD_GUI=OFF \
|
||||
-DSANITIZERS=address,undefined
|
||||
$ cmake --build build_fuzz --target bitcoind
|
||||
$ mkdir -p inputs/
|
||||
$ honggfuzz/honggfuzz --exit_upon_crash --quiet --timeout 4 -n 1 -Q \
|
||||
$ ./honggfuzz/honggfuzz --exit_upon_crash --quiet --timeout 4 -n 1 -Q \
|
||||
-E HFND_TCP_PORT=18444 -f inputs/ -- \
|
||||
src/bitcoind -regtest -discover=0 -dns=0 -dnsseed=0 -listenonion=0 \
|
||||
build_fuzz/src/bitcoind -regtest -discover=0 -dns=0 -dnsseed=0 -listenonion=0 \
|
||||
-nodebuglogfile -bind=127.0.0.1:18444 -logthreadnames \
|
||||
-debug
|
||||
```
|
||||
@ -298,11 +320,9 @@ $ cd Eclipser
|
||||
$ git checkout v1.x
|
||||
$ make
|
||||
$ cd ..
|
||||
$ ./autogen.sh
|
||||
$ ./configure --enable-fuzz
|
||||
$ make
|
||||
$ cmake -B build_fuzz -DBUILD_FOR_FUZZING=ON
|
||||
$ mkdir -p outputs/
|
||||
$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p src/test/fuzz/fuzz -t 36000 -o outputs --src stdin
|
||||
$ FUZZ=bech32 dotnet ./Eclipser/build/Eclipser.dll fuzz -p build_fuzz/src/test/fuzz/fuzz -t 36000 -o outputs --src stdin
|
||||
```
|
||||
|
||||
This will perform 10 hours of fuzzing.
|
||||
@ -320,7 +340,7 @@ Fuzzing with Eclipser will likely be much more effective if using an existing co
|
||||
|
||||
```sh
|
||||
$ git clone https://github.com/bitcoin-core/qa-assets
|
||||
$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p src/test/fuzz/fuzz -t 36000 -i qa-assets/fuzz_seed_corpus/bech32 outputs --src stdin
|
||||
$ FUZZ=bech32 dotnet Eclipser/build/Eclipser.dll fuzz -p build_fuzz/src/test/fuzz/fuzz -t 36000 -i qa-assets/fuzz_seed_corpus/bech32 outputs --src stdin
|
||||
```
|
||||
|
||||
Note that fuzzing with Eclipser on certain targets (those that create 'full nodes', e.g. `process_message*`) will,
|
||||
|
||||
@ -6,8 +6,8 @@ Table of Contents
|
||||
|
||||
* [General](#general)
|
||||
* [Cache compilations with `ccache`](#cache-compilations-with-ccache)
|
||||
* [Disable features with `./configure`](#disable-features-with-configure)
|
||||
* [Make use of your threads with `make -j`](#make-use-of-your-threads-with-make--j)
|
||||
* [Disable features when generating the build system](#disable-features-when-generating-the-build-system)
|
||||
* [Make use of your threads with `-j`](#make-use-of-your-threads-with--j)
|
||||
* [Only build what you need](#only-build-what-you-need)
|
||||
* [Compile on multiple machines](#compile-on-multiple-machines)
|
||||
* [Multiple working directories with `git worktrees`](#multiple-working-directories-with-git-worktrees)
|
||||
@ -31,7 +31,7 @@ The easiest way to faster compile times is to cache compiles. `ccache` is a way
|
||||
|
||||
> ccache is a compiler cache. It speeds up recompilation by caching the result of previous compilations and detecting when the same compilation is being done again. Supported languages are C, C++, Objective-C and Objective-C++.
|
||||
|
||||
Install `ccache` through your distribution's package manager, and run `./configure` with your normal flags to pick it up.
|
||||
Install `ccache` through your distribution's package manager, and run `cmake -B build` with your normal configuration options to pick it up.
|
||||
|
||||
To use ccache for all your C/C++ projects, follow the symlinks method [here](https://ccache.dev/manual/latest.html#_run_modes) to set it up.
|
||||
|
||||
@ -46,38 +46,32 @@ Note: base_dir is required for ccache to share cached compiles of the same file
|
||||
|
||||
You _must not_ set base_dir to "/", or anywhere that contains system headers (according to the ccache docs).
|
||||
|
||||
### Disable features with `./configure`
|
||||
### Disable features when generating the build system
|
||||
|
||||
After running `./autogen.sh`, which generates the `./configure` file, use `./configure --help` to identify features that you can disable to save on compilation time. A few common flags:
|
||||
During the generation of the build system only essential build options are enabled by default to save on compilation time.
|
||||
|
||||
Run `cmake -B build -LH` to see the full list of available options. GUI tools, such as `ccmake` and `cmake-gui`, can be also helpful.
|
||||
|
||||
If you do need the wallet enabled (`-DENABLE_WALLET=ON`), it is common for devs to use your system bdb version for the wallet, so you don't have to find a copy of bdb 4.8. Wallets from such a build will be incompatible with any release binary (and vice versa), so use with caution on mainnet.
|
||||
|
||||
### Make use of your threads with `-j`
|
||||
|
||||
If you have multiple threads on your machine, you can utilize all of them with:
|
||||
|
||||
```sh
|
||||
--without-miniupnpc
|
||||
--without-natpmp
|
||||
--disable-bench
|
||||
--disable-wallet
|
||||
--without-gui
|
||||
```
|
||||
|
||||
If you do need the wallet enabled, it is common for devs to add `--with-incompatible-bdb`. This uses your system bdb version for the wallet, so you don't have to find a copy of bdb 4.8. Wallets from such a build will be incompatible with any release binary (and vice versa), so use with caution on mainnet.
|
||||
|
||||
### Make use of your threads with `make -j`
|
||||
|
||||
If you have multiple threads on your machine, you can tell `make` to utilize all of them with:
|
||||
|
||||
```sh
|
||||
make -j"$(($(nproc)+1))"
|
||||
cmake --build build -j "$(($(nproc)+1))"
|
||||
```
|
||||
|
||||
### Only build what you need
|
||||
|
||||
When rebuilding during development, note that running `make`, without giving a target, will do a lot of work you probably don't need. It will build the GUI (unless you've disabled it) and all the tests (which take much longer to build than the app does).
|
||||
When rebuilding during development, note that running `cmake --build build`, without giving a target, will do a lot of work you probably don't need. It will build the GUI (if you've enabled it) and all the tests (which take much longer to build than the app does).
|
||||
|
||||
Obviously, it is important to build and run the tests at appropriate times -- but when you just want a quick compile to check your work, consider picking one or a set of build targets relevant to what you're working on, e.g.:
|
||||
|
||||
```sh
|
||||
make src/bitcoind src/bitcoin-cli
|
||||
make src/qt/bitcoin-qt
|
||||
make -C src bitcoin_bench
|
||||
cmake --build build --target bitcoind bitcoin-cli
|
||||
cmake --build build --target bitcoin-qt
|
||||
cmake --build build --target bench_bitcoin
|
||||
```
|
||||
|
||||
(You can and should combine this with `-j`, as above, for a parallel build.)
|
||||
@ -110,9 +104,9 @@ To squash in `git commit --fixup` commits without rebasing over an updated maste
|
||||
git rebase -i --autosquash "$(git merge-base master HEAD)"
|
||||
```
|
||||
|
||||
To execute `make check` on every commit since last diverged from master, but without rebasing over an updated master, we can do the following:
|
||||
To execute `cmake --build build && ctest --test-dir build` on every commit since last diverged from master, but without rebasing over an updated master, we can do the following:
|
||||
```sh
|
||||
git rebase -i --exec "make check" "$(git merge-base master HEAD)"
|
||||
git rebase -i --exec "cmake --build build && ctest --test-dir build" "$(git merge-base master HEAD)"
|
||||
```
|
||||
|
||||
-----
|
||||
|
||||
@ -5,14 +5,14 @@ Release Process
|
||||
|
||||
### Before every release candidate
|
||||
|
||||
* Update release candidate version in `configure.ac` (`CLIENT_VERSION_RC`).
|
||||
* Update release candidate version in `CMakeLists.txt` (`CLIENT_VERSION_RC`).
|
||||
* Update manpages (after rebuilding the binaries), see [gen-manpages.py](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-manpagespy).
|
||||
* Update bitcoin.conf and commit changes if they exist, see [gen-bitcoin-conf.sh](https://github.com/bitcoin/bitcoin/blob/master/contrib/devtools/README.md#gen-bitcoin-confsh).
|
||||
|
||||
### Before every major and minor release
|
||||
|
||||
* Update [bips.md](bips.md) to account for changes since the last release.
|
||||
* Update version in `configure.ac` (don't forget to set `CLIENT_VERSION_RC` to `0`).
|
||||
* Update version in `CMakeLists.txt` (don't forget to set `CLIENT_VERSION_RC` to `0`).
|
||||
* Update manpages (see previous section)
|
||||
* Write release notes (see "Write the release notes" below) in doc/release-notes.md. If necessary,
|
||||
archive the previous release notes as doc/release-notes/release-notes-${VERSION}.md.
|
||||
@ -20,8 +20,8 @@ Release Process
|
||||
### Before every major release
|
||||
|
||||
* On both the master branch and the new release branch:
|
||||
- update `CLIENT_VERSION_MAJOR` in [`configure.ac`](../configure.ac)
|
||||
* On the new release branch in [`configure.ac`](../configure.ac)(see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)):
|
||||
- update `CLIENT_VERSION_MAJOR` in [`CMakeLists.txt`](../CMakeLists.txt)
|
||||
* On the new release branch in [`CMakeLists.txt`](../CMakeLists.txt)(see [this commit](https://github.com/bitcoin/bitcoin/commit/742f7dd)):
|
||||
- set `CLIENT_VERSION_MINOR` to `0`
|
||||
- set `CLIENT_VERSION_BUILD` to `0`
|
||||
- set `CLIENT_VERSION_IS_RELEASE` to `true`
|
||||
|
||||
@ -4,7 +4,7 @@ The current precise version for Qt 5 is specified in [qt.mk](/depends/packages/q
|
||||
|
||||
## Compile and run
|
||||
|
||||
See build instructions: [Unix](/doc/build-unix.md), [macOS](/doc/build-osx.md), [Windows](/doc/build-windows.md), [FreeBSD](/doc/build-freebsd.md), [NetBSD](/doc/build-netbsd.md), [OpenBSD](/doc/build-openbsd.md)
|
||||
See build instructions: [Unix](/doc/build-unix.md), [macOS](/doc/build-osx.md), [Windows](/doc/build-windows-msvc.md), [FreeBSD](/doc/build-freebsd.md), [NetBSD](/doc/build-netbsd.md), [OpenBSD](/doc/build-openbsd.md)
|
||||
|
||||
When following your systems build instructions, make sure to install the `Qt` dependencies.
|
||||
|
||||
|
||||
@ -12,22 +12,23 @@ that runs all of the unit tests. The main source file for the test library is fo
|
||||
|
||||
### Compiling/running unit tests
|
||||
|
||||
Unit tests will be automatically compiled if dependencies were met in `./configure`
|
||||
Unit tests will be automatically compiled if dependencies were met
|
||||
during the generation of the Bitcoin Core build system
|
||||
and tests weren't explicitly disabled.
|
||||
|
||||
After configuring, they can be run with `make check`, which includes unit tests from
|
||||
subtrees, or `make && make -C src check-unit` for just the unit tests.
|
||||
Assuming the build directory is named `build`, the unit tests can be run
|
||||
with `ctests --test-dir build`, which includes unit tests from subtrees.
|
||||
|
||||
To run the unit tests manually, launch `src/test/test_bitcoin`. To recompile
|
||||
after a test file was modified, run `make` and then run the test again. If you
|
||||
modify a non-test file, use `make -C src/test` to recompile only what's needed
|
||||
To run the unit tests manually, launch `build/src/test/test_bitcoin`. To recompile
|
||||
after a test file was modified, run `cmake --build build` and then run the test again. If you
|
||||
modify a non-test file, use `cmake --build build --target test_bitcoin` to recompile only what's needed
|
||||
to run the unit tests.
|
||||
|
||||
To add more unit tests, add `BOOST_AUTO_TEST_CASE` functions to the existing
|
||||
.cpp files in the `test/` directory or add new .cpp files that
|
||||
implement new `BOOST_AUTO_TEST_SUITE` sections.
|
||||
|
||||
To run the GUI unit tests manually, launch `src/qt/test/test_bitcoin-qt`
|
||||
To run the GUI unit tests manually, launch `build/src/qt/test/test_bitcoin-qt`
|
||||
|
||||
To add more GUI unit tests, add them to the `src/qt/test/` directory and
|
||||
the `src/qt/test/test_main.cpp` file.
|
||||
@ -38,7 +39,7 @@ the `src/qt/test/test_main.cpp` file.
|
||||
For example, to run just the `getarg_tests` suite of tests:
|
||||
|
||||
```bash
|
||||
test_bitcoin --log_level=all --run_test=getarg_tests
|
||||
build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests
|
||||
```
|
||||
|
||||
`log_level` controls the verbosity of the test framework, which logs when a
|
||||
@ -48,7 +49,7 @@ test case is entered, for example.
|
||||
`bitcoind`. Use `--` to separate these sets of arguments:
|
||||
|
||||
```bash
|
||||
test_bitcoin --log_level=all --run_test=getarg_tests -- -printtoconsole=1
|
||||
build/src/test/test_bitcoin --log_level=all --run_test=getarg_tests -- -printtoconsole=1
|
||||
```
|
||||
|
||||
The `-printtoconsole=1` after the two dashes sends debug logging, which
|
||||
@ -58,7 +59,7 @@ standard terminal output.
|
||||
... or to run just the doubledash test:
|
||||
|
||||
```bash
|
||||
test_bitcoin --run_test=getarg_tests/doubledash
|
||||
build/src/test/test_bitcoin --run_test=getarg_tests/doubledash
|
||||
```
|
||||
|
||||
`test_bitcoin` creates a temporary working (data) directory with a randomly
|
||||
@ -81,7 +82,7 @@ what the test wrote to `debug.log` after it completes, for example.
|
||||
so no leftover state is used.)
|
||||
|
||||
```bash
|
||||
$ test_bitcoin --run_test=getarg_tests/doubledash -- -testdatadir=/somewhere/mydatadir
|
||||
$ build/src/test/test_bitcoin --run_test=getarg_tests/doubledash -- -testdatadir=/somewhere/mydatadir
|
||||
Test directory (will not be deleted): "/somewhere/mydatadir/test_common_Bitcoin Core/getarg_tests/doubledash/datadir
|
||||
Running 1 test case...
|
||||
|
||||
@ -100,8 +101,9 @@ Run `test_bitcoin --help` for the full list of tests.
|
||||
|
||||
### Adding test cases
|
||||
|
||||
To add a new unit test file to our test suite you need
|
||||
to add the file to `src/Makefile.test.include`. The pattern is to create
|
||||
To add a new unit test file to our test suite, you need
|
||||
to add the file to either `src/test/CMakeLists.txt` or
|
||||
`src/wallet/test/CMakeLists.txt` for wallet-related tests. The pattern is to create
|
||||
one test file for each class or source file for which you want to create
|
||||
unit tests. The file naming convention is `<source_filename>_tests.cpp`
|
||||
and such files should wrap their tests in a test suite
|
||||
@ -110,7 +112,8 @@ see `uint256_tests.cpp`.
|
||||
|
||||
### Logging and debugging in unit tests
|
||||
|
||||
`make check` will write to a log file `foo_tests.cpp.log` and display this file
|
||||
`ctest --test-dir build` will write to a log file `build/Testing/Temporary/LastTest.log`. You can
|
||||
additionaly use the `--output-on-failure` option to display logs of the failed tests automatically
|
||||
on failure. For running individual tests verbosely, refer to the section
|
||||
[above](#running-individual-tests).
|
||||
|
||||
@ -121,13 +124,13 @@ For debugging you can launch the `test_bitcoin` executable with `gdb` or `lldb`
|
||||
start debugging, just like you would with any other program:
|
||||
|
||||
```bash
|
||||
gdb src/test/test_bitcoin
|
||||
gdb build/src/test/test_bitcoin
|
||||
```
|
||||
|
||||
#### Segmentation faults
|
||||
|
||||
If you hit a segmentation fault during a test run, you can diagnose where the fault
|
||||
is happening by running `gdb ./src/test/test_bitcoin` and then using the `bt` command
|
||||
is happening by running `gdb ./build/src/test/test_bitcoin` and then using the `bt` command
|
||||
within gdb.
|
||||
|
||||
Another tool that can be used to resolve segmentation faults is
|
||||
@ -145,7 +148,7 @@ Running the tests and hitting a segmentation fault should now produce a file cal
|
||||
|
||||
You can then explore the core dump using
|
||||
```bash
|
||||
gdb src/test/test_bitcoin core
|
||||
gdb build/src/test/test_bitcoin core
|
||||
|
||||
(gbd) bt # produce a backtrace for where a segfault occurred
|
||||
```
|
||||
|
||||
@ -13,13 +13,15 @@ interfaces.
|
||||
- [util](/test/util) which tests the utilities (bitcoin-util, bitcoin-tx, ...).
|
||||
- [lint](/test/lint/) which perform various static analysis checks.
|
||||
|
||||
The util tests are run as part of `make check` target. The fuzz tests, functional
|
||||
The util tests are run as part of `ctest` invocation. The fuzz tests, functional
|
||||
tests and lint scripts can be run as explained in the sections below.
|
||||
|
||||
# Running tests locally
|
||||
|
||||
Before tests can be run locally, Bitcoin Core must be built. See the [building instructions](/doc#building) for help.
|
||||
|
||||
The following examples assume that the build directory is named `build`.
|
||||
|
||||
## Fuzz tests
|
||||
|
||||
See [/doc/fuzzing.md](/doc/fuzzing.md)
|
||||
@ -45,19 +47,19 @@ set PYTHONUTF8=1
|
||||
Individual tests can be run by directly calling the test script, e.g.:
|
||||
|
||||
```
|
||||
test/functional/feature_rbf.py
|
||||
build/test/functional/feature_rbf.py
|
||||
```
|
||||
|
||||
or can be run through the test_runner harness, eg:
|
||||
|
||||
```
|
||||
test/functional/test_runner.py feature_rbf.py
|
||||
build/test/functional/test_runner.py feature_rbf.py
|
||||
```
|
||||
|
||||
You can run any combination (incl. duplicates) of tests by calling:
|
||||
|
||||
```
|
||||
test/functional/test_runner.py <testname1> <testname2> <testname3> ...
|
||||
build/test/functional/test_runner.py <testname1> <testname2> <testname3> ...
|
||||
```
|
||||
|
||||
Wildcard test names can be passed, if the paths are coherent and the test runner
|
||||
@ -65,34 +67,34 @@ is called from a `bash` shell or similar that does the globbing. For example,
|
||||
to run all the wallet tests:
|
||||
|
||||
```
|
||||
test/functional/test_runner.py test/functional/wallet*
|
||||
functional/test_runner.py functional/wallet* (called from the test/ directory)
|
||||
test_runner.py wallet* (called from the test/functional/ directory)
|
||||
build/test/functional/test_runner.py test/functional/wallet*
|
||||
functional/test_runner.py functional/wallet* # (called from the build/test/ directory)
|
||||
test_runner.py wallet* # (called from the build/test/functional/ directory)
|
||||
```
|
||||
|
||||
but not
|
||||
|
||||
```
|
||||
test/functional/test_runner.py wallet*
|
||||
build/test/functional/test_runner.py wallet*
|
||||
```
|
||||
|
||||
Combinations of wildcards can be passed:
|
||||
|
||||
```
|
||||
test/functional/test_runner.py ./test/functional/tool* test/functional/mempool*
|
||||
build/test/functional/test_runner.py ./test/functional/tool* test/functional/mempool*
|
||||
test_runner.py tool* mempool*
|
||||
```
|
||||
|
||||
Run the regression test suite with:
|
||||
|
||||
```
|
||||
test/functional/test_runner.py
|
||||
build/test/functional/test_runner.py
|
||||
```
|
||||
|
||||
Run all possible tests with
|
||||
|
||||
```
|
||||
test/functional/test_runner.py --extended
|
||||
build/test/functional/test_runner.py --extended
|
||||
```
|
||||
|
||||
In order to run backwards compatibility tests, first run:
|
||||
@ -107,7 +109,7 @@ By default, up to 4 tests will be run in parallel by test_runner. To specify
|
||||
how many jobs to run, append `--jobs=n`
|
||||
|
||||
The individual tests and the test_runner harness have many command-line
|
||||
options. Run `test/functional/test_runner.py -h` to see them all.
|
||||
options. Run `build/test/functional/test_runner.py -h` to see them all.
|
||||
|
||||
#### Speed up test runs with a RAM disk
|
||||
|
||||
@ -130,7 +132,7 @@ For example running the test suite with `--jobs=100` might need a 4 GiB RAM disk
|
||||
To use, run the test suite specifying the RAM disk as the `cachedir` and `tmpdir`:
|
||||
|
||||
```bash
|
||||
test/functional/test_runner.py --cachedir=/mnt/tmp/cache --tmpdir=/mnt/tmp
|
||||
build/test/functional/test_runner.py --cachedir=/mnt/tmp/cache --tmpdir=/mnt/tmp
|
||||
```
|
||||
|
||||
Once finished with the tests and the disk, and to free the RAM, simply unmount the disk:
|
||||
@ -151,7 +153,7 @@ Configure the RAM disk size, expressed as the number of blocks, at the end of th
|
||||
(`4096 MiB * 2048 blocks/MiB = 8388608 blocks` for 4 GiB). To run the tests using the RAM disk:
|
||||
|
||||
```bash
|
||||
test/functional/test_runner.py --cachedir=/Volumes/ramdisk/cache --tmpdir=/Volumes/ramdisk/tmp
|
||||
build/test/functional/test_runner.py --cachedir=/Volumes/ramdisk/cache --tmpdir=/Volumes/ramdisk/tmp
|
||||
```
|
||||
|
||||
To unmount:
|
||||
@ -193,14 +195,14 @@ pkill -9 bitcoind
|
||||
##### Data directory cache
|
||||
|
||||
A pre-mined blockchain with 200 blocks is generated the first time a
|
||||
functional test is run and is stored in test/cache. This speeds up
|
||||
functional test is run and is stored in build/test/cache. This speeds up
|
||||
test startup times since new blockchains don't need to be generated for
|
||||
each test. However, the cache may get into a bad state, in which case
|
||||
tests will fail. If this happens, remove the cache directory (and make
|
||||
sure bitcoind processes are stopped as above):
|
||||
|
||||
```bash
|
||||
rm -rf test/cache
|
||||
rm -rf build/test/cache
|
||||
killall bitcoind
|
||||
```
|
||||
|
||||
@ -236,7 +238,7 @@ aggregate log by running the `combine_logs.py` script. The output can be plain
|
||||
text, colorized text or html. For example:
|
||||
|
||||
```
|
||||
test/functional/combine_logs.py -c <test data directory> | less -r
|
||||
build/test/functional/combine_logs.py -c <test data directory> | less -r
|
||||
```
|
||||
|
||||
will pipe the colorized logs from the test into less.
|
||||
@ -297,7 +299,7 @@ See this link for considerations: https://www.kernel.org/doc/Documentation/secur
|
||||
|
||||
Often while debugging RPC calls in functional tests, the test might time out before the
|
||||
process can return a response. Use `--timeout-factor 0` to disable all RPC timeouts for that particular
|
||||
functional test. Ex: `test/functional/wallet_hd.py --timeout-factor 0`.
|
||||
functional test. Ex: `build/test/functional/wallet_hd.py --timeout-factor 0`.
|
||||
|
||||
##### Profiling
|
||||
|
||||
@ -321,7 +323,7 @@ For ways to generate more granular profiles, see the README in
|
||||
|
||||
### Util tests
|
||||
|
||||
Util tests can be run locally by running `test/util/test_runner.py`.
|
||||
Util tests can be run locally by running `build/test/util/test_runner.py`.
|
||||
Use the `-v` option for verbose output.
|
||||
|
||||
### Lint tests
|
||||
|
||||
Loading…
Reference in New Issue
Block a user