From 0b4ca5d72510f46ce6c2b849332a8f70eb14c69b Mon Sep 17 00:00:00 2001 From: Ryan Ofsky Date: Sun, 26 Jan 2025 13:12:23 -0500 Subject: [PATCH] doc: Update documentation to explain BUILD_MULTIPROCESS --- doc/design/libraries.md | 2 +- doc/developer-notes.md | 3 +++ doc/multiprocess.md | 16 ++++++++++++---- 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/doc/design/libraries.md b/doc/design/libraries.md index 24185bf4776..341094fe6ff 100644 --- a/doc/design/libraries.md +++ b/doc/design/libraries.md @@ -8,7 +8,7 @@ | *libbitcoin_crypto* | Hardware-optimized functions for data encryption, hashing, message authentication, and key derivation. | | *libbitcoin_kernel* | Consensus engine and support library used for validation by *libbitcoin_node*. | | *libbitcoinqt* | GUI functionality used by *bitcoin-qt* and *bitcoin-gui* executables. | -| *libbitcoin_ipc* | IPC functionality used by *bitcoin-node*, *bitcoin-wallet*, *bitcoin-gui* executables to communicate when [`-DWITH_MULTIPROCESS=ON`](multiprocess.md) is used. | +| *libbitcoin_ipc* | IPC functionality used by *bitcoin-node*, *bitcoin-wallet*, *bitcoin-gui* executables to communicate when [`-DBUILD_MULTIPROCESS=ON`](multiprocess.md) is used. | | *libbitcoin_node* | P2P and RPC server functionality used by *bitcoind* and *bitcoin-qt* executables. | | *libbitcoin_util* | Home for common functionality shared by different executables and libraries. Similar to *libbitcoin_common*, but lower-level (see [Dependencies](#dependencies)). | | *libbitcoin_wallet* | Wallet functionality used by *bitcoind* and *bitcoin-wallet* executables. | diff --git a/doc/developer-notes.md b/doc/developer-notes.md index 37e594e7628..d7b683973ce 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -1232,6 +1232,9 @@ Current subtrees include: - src/minisketch - Upstream at https://github.com/sipa/minisketch ; maintained by Core contributors. +- src/ipc/libmultiprocess + - Upstream at https://github.com/chaincodelabs/libmultiprocess ; maintained by Core contributors. + Upgrading LevelDB --------------------- diff --git a/doc/multiprocess.md b/doc/multiprocess.md index 1757296eed6..24fcde708b8 100644 --- a/doc/multiprocess.md +++ b/doc/multiprocess.md @@ -4,7 +4,7 @@ _This document describes usage of the multiprocess feature. For design informati ## Build Option -On Unix systems, the `-DWITH_MULTIPROCESS=ON` build option can be passed to build the supplemental `bitcoin-node` and `bitcoin-gui` multiprocess executables. +The `-DBUILD_MULTIPROCESS=ON` build option, supported on Unix systems, can be passed to build the supplemental `bitcoin-node` and `bitcoin-gui` multiprocess executables. ## Debugging @@ -12,7 +12,11 @@ The `-debug=ipc` command line option can be used to see requests and responses b ## Installation -The multiprocess feature requires [Cap'n Proto](https://capnproto.org/) and [libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) as dependencies. A simple way to get started using it without installing these dependencies manually is to use the [depends system](../depends) with the `MULTIPROCESS=1` [dependency option](../depends#dependency-options) passed to make: +The multiprocess feature requires [Cap'n Proto](https://capnproto.org/) as an external dependency, which is available from most package managers. See [build-unix.md](build-unix.md) and [build-osx.md](build-osx.md) for information about installing dependencies. + +### Depends installation + +Alternately the [depends system](../depends) can be used to avoid need to install dependencies. A simple way to get started is to pass the `MULTIPROCESS=1` [dependency option](../depends#dependency-options) to make: ``` cd @@ -25,9 +29,13 @@ build/src/bitcoin-node -regtest -printtoconsole -debug=ipc BITCOIND=$(pwd)/build/src/bitcoin-node build/test/functional/test_runner.py ``` -The `cmake` build will pick up settings and library locations from the depends directory, so there is no need to pass `-DWITH_MULTIPROCESS=ON` as a separate flag when using the depends system (it's controlled by the `MULTIPROCESS=1` option). +The `cmake` build will pick up settings and library locations from the depends directory, so there is no need to pass `-DBUILD_MULTIPROCESS=ON` as a separate flag when using the depends system (it's controlled by the `MULTIPROCESS=1` option). -Alternately, you can install [Cap'n Proto](https://capnproto.org/) and [libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) packages on your system, and just run `cmake -B build -DWITH_MULTIPROCESS=ON` without using the depends system. The `cmake` build will be able to locate the installed packages via [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/). See [Installation](https://github.com/chaincodelabs/libmultiprocess/blob/master/doc/install.md) section of the libmultiprocess readme for install steps. See [build-unix.md](build-unix.md) and [build-osx.md](build-osx.md) for information about installing dependencies in general. +### External libmultiprocess installation + +Optionally, when not using depends, the [libmultiprocess](https://github.com/chaincodelabs/libmultiprocess) library can be installed as an external dependency. This can enabled with the `-DWITH_LIBMULTIPROCESS=ON` option, which is off by default. When it is disabled, the libmultiprocess sources in ../src/ipc/libmultiprocess are used instead. See [Installation](https://github.com/chaincodelabs/libmultiprocess/blob/master/doc/install.md) section of the libmultiprocess documentation for install steps. + +Installing libmultiprocess externally is only necessary when cross-compiling (to provide a code generation binary that can run on the native system). It can also be useful when developing changes meant to be submitted upstream. ## Usage