doc: Update for CMake-based build system

hebasto · Jul 31, 2024 · 80073c7 · 80073c7
1 parent 22ced04
commit 80073c7
Show file tree

Hide file tree

Showing 12 changed files with 238 additions and 168 deletions.
diff --git a/depends/README.md b/depends/README.md
@@ -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
 

diff --git 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/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
 ```
 
@@ -101,33 +101,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
@@ -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++" \
     ...
 ```
 
@@ -89,28 +88,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
@@ -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,13 +46,13 @@ 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
@@ -82,47 +80,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
@@ -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.
@@ -177,7 +177,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
@@ -190,30 +190,26 @@ There are many ways to configure Bitcoin Core, here are a few common examples:
 
 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.
 
 ``` bash
-./autogen.sh
-./configure --with-gui=no
+cmake -B build
 ```
 
 ##### Wallet (only SQlite) and GUI Support:
 
-This explicitly enables the GUI and disables legacy wallet support.
+This 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.
 
 ``` bash
-./autogen.sh
-./configure --without-bdb --with-gui=yes
+cmake -B build -DWITH_BDB=OFF -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 +218,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,16 +227,16 @@ 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)
 
 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 +272,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
 ```