aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authormerge-script <fanquake@gmail.com>2024-08-28 10:51:24 +0100
committermerge-script <fanquake@gmail.com>2024-08-28 10:51:24 +0100
commit338bc2cd261ba3daf7fb494f8cb4a534762e292c (patch)
tree3c0cc3176fe2531f59d280071bc87c4778bc56d7 /doc
parent80f00cafdeef0600fa1a5e906686720786c2336c (diff)
parent41051290ab3b6c36312cec26a27f787cea9961b4 (diff)
Merge bitcoin/bitcoin#30454: build: Introduce CMake-based build system
41051290ab3b6c36312cec26a27f787cea9961b4 cmake: Ignore build subdirectories within source directory (Hennadii Stepanov) 6ce50fd9d0ae6850d54bf883e7a7c1bcb6912c5c doc: Update for CMake-based build system (Hennadii Stepanov) 9730288a0cd3f33021ef00fb2d95e5216d10ab61 ci: Migrate CI scripts to CMake (Hennadii Stepanov) c360837ca5c91c9878ae8088bb5482e96fd87c96 cmake, lint: Adjust `lint_includes_build_config` (Hennadii Stepanov) 3885441ee0d35a40904995ede68120fea471dde7 cmake: Add presets for native Windows builds (Hennadii Stepanov) 7681746b20dd58e7d3e6d2852f07fb876383a133 cmake: Add vcpkg manifest file (Hennadii Stepanov) 8b6f1c4353836bae6aa683cbc65251165bd031ba cmake: Add `Coverage` and `CoverageFuzz` scripts (Hennadii Stepanov) 65bdbc1ff23b0a817f4d9a4682e6f630c9bbdd59 cmake: Add `docs` build target (Hennadii Stepanov) fb75ebbc33557ddd56f505100ad3631a0028eb86 cmake: Add compiler diagnostic flags (Hennadii Stepanov) e821f0a37a026fa0480c7f6f6c938da7c77e0d52 cmake: Migrate Guix build scripts to CMake (Hennadii Stepanov) 747adb6ffe9b06d476fc5eaebbaf9a62b91a78c5 cmake: Add `Maintenance` module (Hennadii Stepanov) 1f60b30df0cb58a7381a1bfbd6d34f002232e862 cmake: Add `APPEND_{CPP,C,CXX,LD}FLAGS` cache variables (Hennadii Stepanov) 2b43c45b13ad00cfd9928a03da8a480977724cb1 cmake: Add `AddWindowsResources` module (Hennadii Stepanov) 973a3b0c5dcbf6b3fd155b2dda4c2e94a0b0ee5f cmake: Implement `install` build target (Hennadii Stepanov) 84ac35cfd4dfa6f235f6e5a00b571846358f45ce cmake: Add cross-compiling support (Hennadii Stepanov) 0d01c228a7d39bb4918b5cb9f6db25cb8c30567a build: Generate `toolchain.cmake` in depends (Hennadii Stepanov) 91a799247dc5e4627e6b2f221669c8ff9238bc8d depends: Add host-specific `cmake_system_version` variables (Hennadii Stepanov) 9b31209b4caaa02b3044acd2375a7f595cdbd520 depends: Rename `cmake_system` -> `cmake_system_name` (Hennadii Stepanov) 4a5208a81d5bfeef270c64d48dce3444d6d03511 Revert "build, qt: Do not install *.prl files" (Hennadii Stepanov) 6522af62af1c3a6e2525bfffdb2295751b6fa49b depends: Amend handling flags environment variables (Hennadii Stepanov) 90cec4d251a541adfc5953e24dc01840a8cb4af2 cmake: Add `MULTIPROCESS` option (Hennadii Stepanov) bb1a450dcb111746869547c8b538b5d2472cf8e6 cmake: Build `bitcoin-chainstate` executable (Hennadii Stepanov) aed38ea58cbde068fe12b5299b246b4e3649a09c cmake: Build `bitcoinkernel` library (Hennadii Stepanov) 975d67369b8f3a33a21fd7618c299c0ec138292c cmake: Build `test_bitcoin-qt` executable (Hennadii Stepanov) 10fcc668a3430b72eaf7effc83f00cedeb27c7dc cmake: Add `WITH_DBUS` option (Hennadii Stepanov) 5bb5a4bc75a523e30eab561763927252ce105c4d cmake: Add `libqrencode` optional package support (Hennadii Stepanov) 57a6e2ef4abbfd2b12ee6489366bc6609bead263 cmake: Build `bitcoin-qt` executable (Hennadii Stepanov) 30f642952cb5bf39479bdbe467b3950f0d09324a cmake: Add `WERROR` option (Hennadii Stepanov) c98d4a4c341e524348d0342e145d439816a44c83 cmake: Add `REDUCE_EXPORTS` option (Hennadii Stepanov) a01cb6e63ff3940f0773b37e2fe1e148f17acad9 cmake: Add `HARDENING` option (Hennadii Stepanov) a8a2e364acf55bbe18404ab21f852d52257bcb6d cmake: Add Python-based tests (Hennadii Stepanov) 3d853795707c5a1828dcd09c1f68bb07dee472cd cmake: Add fuzzing options (Hennadii Stepanov) 908530e312a3d4561f9c1feeb2a76ce899f21c68 cmake: Add `SANITIZERS` option (Hennadii Stepanov) 8bb0e85631e7c1bee16e136454b2466776be1d65 cmake: Build `bench_bitcoin` executable (Hennadii Stepanov) 801735163a81650619a6c9587e8f1df9ee182694 cmake: Add external signer support (Hennadii Stepanov) 353e0c9e9679864a777e17c1bb7c6ba8b6eac96d cmake: Add `systemtap-sdt` optional package support (Hennadii Stepanov) d2fda82b4954f4af7e7d340cf42b9cb34d96cde1 cmake: Add `libzmq` optional package support (Hennadii Stepanov) ae7b39a0e106d798b6e9cc03ee783d9081e41480 cmake: Add `libminiupnpc` optional package support (Hennadii Stepanov) 6480e1dcdb03f43ce3d0aad96b8668d017d11750 cmake: Add `libnatpmp` optional package support (Hennadii Stepanov) e73e9304a11af65f9b086460ff349f9f700709ce cmake: Build `bitcoin-util` executable (Hennadii Stepanov) 027c6d7caa0355c35b00f2689eddccc3d1227aef cmake: Build `bitcoin-tx` executable (Hennadii Stepanov) d10c5c34c3d899db8bcff47ac8c6ba396a6da4b6 cmake: Add wallet functionality (Hennadii Stepanov) ab2e99b0d95714e16a7d1a1313d7da938b0485cb cmake: Create test suite for `ctest` (Hennadii Stepanov) 959370bd76d30ced34208db45fb4fd097fbad31b cmake: Build `test_bitcoin` executable (Hennadii Stepanov) b27bf9700dbbfa9a0243815f78c8b62abe78d8bc cmake: Build `bitcoin-cli` executable (Hennadii Stepanov) a9813df826c885b1609e55a83d87cd9cbc90adfd cmake: Build `bitcoind` executable (Hennadii Stepanov) 97829ce2d5a8dc3b0307b5d57c6686b96b7cf850 cmake: Add `FindLibevent` module (Hennadii Stepanov) 3118e40c6157c8ab9e264518d1065d2b0fc07795 cmake: Build `bitcoin_consensus` library (Hennadii Stepanov) 809a2f192903145f88f30bc10d3cf1ab9ed06881 cmake: Build `bitcoin_util` static library (Hennadii Stepanov) 0a9a521a704ca8a27124c1498a86e87ad46d4c34 cmake: Build `bitcoin_crypto` library (Hennadii Stepanov) 958971f476a29cb5bb76f3ae80ae968317ca1930 cmake: Build `univalue` static library (Hennadii Stepanov) 752747fda801f2c0ecce91c96bcc9ef93e27462b cmake: Generate `obj/build.h` header (Hennadii Stepanov) 1f0a78edf3cd2c24236ac512acf420eb9ed86ab3 cmake: Build `minisketch` static library (Hennadii Stepanov) 12bfbc81540f037c95e7796ae0b9f05ce3fb1b4a cmake: Build `leveldb` static library (Hennadii Stepanov) 51985c5304dfc52bd45f505b3115989637d79ff5 cmake: Build `crc32c` static library (Hennadii Stepanov) db7a198f29c62c5f762eaa25d1d83c57e2f1e211 cmake: Build `secp256k1` subtree (Hennadii Stepanov) dbb7ed14e8562439238eec70b202c50f172e3def cmake: Add `ccache` support (Hennadii Stepanov) cedfdf6c72535d0797a271c6bb9d84c4b406a8ea cmake: Redefine/adjust per-configuration flags (Hennadii Stepanov) b6b5e732c8b49a2cc14f34ac72b2189389c6b27d cmake: Add global compiler and linker flags (Hennadii Stepanov) f98327931bd0b5d90678ddd1770e9862266b396e cmake: Add `TryAppendLinkerFlag` module (Hennadii Stepanov) 4a0af29697b62d32af6f60d3ec70cd2ed4d7243c cmake: Add `TryAppendCXXFlags` module (Hennadii Stepanov) 35cffc497d8db3cf3eee35c1513e3435558f056b cmake: Add POSIX threads support (Hennadii Stepanov) fd72d00ffe34c84e292b305f6797201040d31a72 cmake: Add position independent code support (Hennadii Stepanov) 07069e2bb0bbdacf16cf34efd3a33390de030217 cmake: Add introspection module (Hennadii Stepanov) 27d687fc1f6aceaed7725e1e904a093ead68d6e6 cmake: Add `config/bitcoin-config.h` support (Hennadii Stepanov) fe5cdace5ffba46fb7981efb816621962d3873e3 cmake: Print compiler and linker flags in summary (Hennadii Stepanov) 70683884c5fd78dbf7816434464e6511b9d4e486 cmake: Introduce interface libraries to encapsulate common flags (Hennadii Stepanov) a2317e27b7fb86df4e32cd1674c06e09cb808248 cmake: Add root `CMakeLists.txt` file (Hennadii Stepanov) Pull request description: This PR introduces a new CMake-based build system, which is a drop-in replacement for the current Autotools-based build system. ML announcement: https://groups.google.com/g/bitcoindev/c/hgKkfQWzrTo As discussed during the recent CoreDev meetup in April, the switch from Autotools to CMake is intended to happen as soon as possible after branching 28.x off, which means that 29.0 will be built using CMake. This PR branch is essentially the [staging branch](https://github.com/hebasto/bitcoin/tree/cmake-staging), with every change reviewed and tested by a group of contributors, including (in alphabetical order): - [**achow101**](https://github.com/achow101) - [**fanquake**](https://github.com/fanquake) - [**maflcko**](https://github.com/maflcko) - [**m3dwards**](https://github.com/m3dwards) - [**pablomartin4btc**](https://github.com/pablomartin4btc) - [**real-or-random**](https://github.com/real-or-random) - [**ryanofsky**](https://github.com/ryanofsky) - [**sipsorcery**](https://github.com/sipsorcery) - [**TheCharlatan**](https://github.com/TheCharlatan) - [**theStack**](https://github.com/theStack) - [**theuni**](https://github.com/theuni) - [**vasild**](https://github.com/vasild) Reviewing in a separate staging repo was suggested in https://github.com/bitcoin/bitcoin/pull/27060#issuecomment-1431798320. The accompanying changes to the OSS-Fuzz project are available in https://github.com/hebasto/oss-fuzz/pull/8. Please refer to the [build options parity table](https://gist.github.com/hebasto/2ef97d3a726bfce08ded9df07f7dab5e). The "auto" value is no longer available; non-default values must be specified explicitly. Additionally, the new default values have been chosen to suit the everyday build experience for the majority of developers. System requirements for using the CMake-based build system: - CMake >= 3.22 (if not available in your system's repository, it can be downloaded from https://cmake.org/download/) - a build tool of your choice: - any Make (GNU Make is no longer a requirement); GNU Make is still required to build depends - Ninja (https://ninja-build.org/) - MSBuild - Xcode A note for Windows users: The default installation of the latest version of MSVC 17.10.4 includes both CMake 3.28.3 and the vcpkg package manager). --- We, the build system developers, kindly ask reviewers to refrain from making suggestions that are not directly related to the migration process or can be implemented separately. Bugs in the scripts and errors in the updated documentation should be the focus of this PR. Please be advised that comments not aligned with this PR's goal may be ignored. Thank you all for your understanding. ACKs for top commit: maflcko: review ACK 41051290ab3b6c36312cec26a27f787cea9961b4 🐥 sipsorcery: ACK 41051290ab3b6c36312cec26a27f787cea9961b4. vasild: ACK 41051290ab3b6c36312cec26a27f787cea9961b4 TheCharlatan: ACK 41051290ab3b6c36312cec26a27f787cea9961b4 pablomartin4btc: tACK 41051290ab3b6c36312cec26a27f787cea9961b4 i-am-yuvi: tACK [`4105129`](https://github.com/bitcoin/bitcoin/commit/41051290ab3b6c36312cec26a27f787cea9961b4) theuni: ACK 41051290ab3b6c36312cec26a27f787cea9961b4. fanquake: ACK 41051290ab3b6c36312cec26a27f787cea9961b4 Tree-SHA512: 6c1445054436c6c00ad63bfa0f19d64091a2b25c9bd694f85bf2218ac358ffb774d6c000685b3ca1e9b50401babed989fa2a0694b774c211d226bfd1944c9b39
Diffstat (limited to 'doc')
-rw-r--r--doc/CMakeLists.txt25
-rw-r--r--doc/Doxyfile.in2
-rw-r--r--doc/README.md2
-rw-r--r--doc/benchmarking.md11
-rw-r--r--doc/build-freebsd.md45
-rw-r--r--doc/build-netbsd.md34
-rw-r--r--doc/build-openbsd.md53
-rw-r--r--doc/build-osx.md54
-rw-r--r--doc/build-unix.md71
-rw-r--r--doc/build-windows-msvc.md82
-rw-r--r--doc/build-windows.md31
-rw-r--r--doc/developer-notes.md29
-rw-r--r--doc/fuzzing.md88
-rw-r--r--doc/productivity.md38
-rw-r--r--doc/release-process.md8
15 files changed, 338 insertions, 235 deletions
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
new file mode 100644
index 0000000000..61a7653e4a
--- /dev/null
+++ b/doc/CMakeLists.txt
@@ -0,0 +1,25 @@
+# Copyright (c) 2024-present The Bitcoin Core developers
+# Distributed under the MIT software license, see the accompanying
+# file COPYING or https://opensource.org/license/mit/.
+
+find_package(Doxygen COMPONENTS dot)
+
+if(DOXYGEN_FOUND)
+ set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+ configure_file(Doxyfile.in ${doxyfile})
+
+ # In CMake 3.27, The FindDoxygen module's doxygen_add_docs()
+ # command gained a CONFIG_FILE option to specify a custom doxygen
+ # configuration file.
+ # TODO: Consider using it.
+ add_custom_target(docs
+ COMMAND Doxygen::doxygen ${doxyfile}
+ WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+ COMMENT "Generating developer documentation"
+ VERBATIM USES_TERMINAL
+ )
+else()
+ add_custom_target(docs
+ COMMAND ${CMAKE_COMMAND} -E echo "Error: Doxygen not found"
+ )
+endif()
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index d8fd46d1c7..ccaf31170a 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -58,7 +58,7 @@ PROJECT_LOGO = doc/bitcoin_logo_doxygen.png
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
-OUTPUT_DIRECTORY = doc/doxygen
+OUTPUT_DIRECTORY = @PROJECT_BINARY_DIR@/doc/doxygen
# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and
diff --git a/doc/README.md b/doc/README.md
index 74a85b04e6..7f5db1b5bf 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -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)
diff --git a/doc/benchmarking.md b/doc/benchmarking.md
index 84d5f2c444..c6dc75dc5c 100644
--- a/doc/benchmarking.md
+++ b/doc/benchmarking.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.
diff --git a/doc/build-freebsd.md b/doc/build-freebsd.md
index bf86a0ee4b..fba5a17e9a 100644
--- a/doc/build-freebsd.md
+++ b/doc/build-freebsd.md
@@ -10,15 +10,14 @@ 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.
### 2. Clone Bitcoin Repo
Now that `git` and all the required dependencies are installed, let's clone the Bitcoin Core repository to a directory. All build scripts and commands will run from this directory.
-``` bash
+```bash
git clone https://github.com/bitcoin/bitcoin.git
```
@@ -31,7 +30,7 @@ It is not necessary to build wallet functionality to run either `bitcoind` or `b
`sqlite3` is required to support [descriptor wallets](descriptors.md).
Skip if you don't intend to use descriptor wallets.
-``` bash
+```bash
pkg install sqlite3
```
@@ -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
+```bash
+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.
```
diff --git a/doc/build-netbsd.md b/doc/build-netbsd.md
index 5f54fd6d9a..63bfbd61db 100644
--- a/doc/build-netbsd.md
+++ b/doc/build-netbsd.md
@@ -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.
```
diff --git a/doc/build-openbsd.md b/doc/build-openbsd.md
index 0fba281dc1..32129aadf3 100644
--- a/doc/build-openbsd.md
+++ b/doc/build-openbsd.md
@@ -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
-
-**Important**: Use `gmake` (the non-GNU `make` will exit with an error).
+#### 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:
-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
diff --git a/doc/build-osx.md b/doc/build-osx.md
index 20c92ab7a4..161ba395b0 100644
--- a/doc/build-osx.md
+++ b/doc/build-osx.md
@@ -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
```
diff --git a/doc/build-unix.md b/doc/build-unix.md
index de54fb4eeb..45433a32b3 100644
--- a/doc/build-unix.md
+++ b/doc/build-unix.md
@@ -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.
diff --git a/doc/build-windows-msvc.md b/doc/build-windows-msvc.md
new file mode 100644
index 0000000000..ec839724dd
--- /dev/null
+++ b/doc/build-windows-msvc.md
@@ -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.
diff --git a/doc/build-windows.md b/doc/build-windows.md
index 1217f10c1b..2d47d120e3 100644
--- a/doc/build-windows.md
+++ b/doc/build-windows.md
@@ -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
@@ -50,7 +50,7 @@ Acquire the source in the usual way:
## Building for 64-bit Windows
-The first step is to install the mingw-w64 cross-compilation tool chain:
+The first step is to install the mingw-w64 cross-compilation toolchain:
```sh
sudo apt install g++-mingw-w64-x86-64-posix
@@ -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
diff --git a/doc/developer-notes.md b/doc/developer-notes.md
index 0445921026..3066aabe60 100644
--- a/doc/developer-notes.md
+++ b/doc/developer-notes.md
@@ -338,11 +338,11 @@ Recommendations:
### Generating Documentation
-The documentation can be generated with `make docs` and cleaned up with `make
-clean-docs`. The resulting files are located in `doc/doxygen/html`; open
+The documentation can be generated with `cmake --build <build_dir> --target docs`.
+The resulting files are located in `<build_dir>/doc/doxygen/html`; open
`index.html` in that directory to view the homepage.
-Before running `make docs`, you'll need to install these dependencies:
+Before building the `docs` target, you'll need to install these dependencies:
Linux: `sudo apt install doxygen graphviz`
@@ -476,25 +476,34 @@ $ ./test/functional/test_runner.py --valgrind
### Compiling for test coverage
-LCOV can be used to generate a test coverage report based upon `make check`
+LCOV can be used to generate a test coverage report based upon `ctest`
execution. LCOV must be installed on your system (e.g. the `lcov` package
on Debian/Ubuntu).
To enable LCOV report generation during test runs:
```shell
-./configure --enable-lcov
-make
-make cov
+cmake -B build -DCMAKE_BUILD_TYPE=Coverage
+cmake --build build
+cmake -P build/Coverage.cmake
-# A coverage report will now be accessible at `./test_bitcoin.coverage/index.html`,
-# which covers unit tests, and `./total.coverage/index.html`, which covers
+# A coverage report will now be accessible at `./build/test_bitcoin.coverage/index.html`,
+# which covers unit tests, and `./build/total.coverage/index.html`, which covers
# unit and functional tests.
```
Additional LCOV options can be specified using `LCOV_OPTS`, but may be dependent
on the version of LCOV. For example, when using LCOV `2.x`, branch coverage can be
-enabled by setting `LCOV_OPTS="--rc branch_coverage=1"`, when configuring.
+enabled by setting `LCOV_OPTS="--rc branch_coverage=1"`:
+
+```
+cmake -DLCOV_OPTS="--rc branch_coverage=1" -P build/Coverage.cmake
+```
+
+To enable test parallelism:
+```
+cmake -DJOBS=$(nproc) -P build/Coverage.cmake
+```
### Performance profiling with perf
diff --git a/doc/fuzzing.md b/doc/fuzzing.md
index c9fb918c8f..ffc6a04964 100644
--- a/doc/fuzzing.md
+++ b/doc/fuzzing.md
@@ -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,
diff --git a/doc/productivity.md b/doc/productivity.md
index 323d86f7b8..f025b4bf6e 100644
--- a/doc/productivity.md
+++ b/doc/productivity.md
@@ -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.
-```sh
---without-miniupnpc
---without-natpmp
---disable-bench
---disable-wallet
---without-gui
-```
+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, 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.
+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 `make -j`
+### Make use of your threads with `-j`
-If you have multiple threads on your machine, you can tell `make` to utilize all of them with:
+If you have multiple threads on your machine, you can 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)"
```
-----
diff --git a/doc/release-process.md b/doc/release-process.md
index fa2c53eb0c..aeaed8d68c 100644
--- a/doc/release-process.md
+++ b/doc/release-process.md
@@ -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`