Merge bitcoin#30741: doc: update documentation and scripts related to build directories

6a68343 doc: Prepend 'build/' to binary paths under 'src/' in docs (Lőrinc)
91b3bc2 doc: Update documentation generation example in developer-notes.md (Lőrinc)

Pull request description:

  In [the other readmes](https://github.com/bitcoin/bitcoin/blob/6ce50fd9d0ae6850d54bf883e7a7c1bcb6912c5c/src/test/README.md?plain=1#L19) we've provided a default build directory instead, unified the `developer-notes.md` to specify it explicitly.

  In the next commit I've used this default to go over each reference to our binaries and changed their in-source references to the build directory.
  Some of these changes were in example outputs - I haven't validated that the outputs are still the same.
  I haven't modified the build folders in the devtools.

ACKs for top commit:
  maflcko:
    review ACK 6a68343
  pablomartin4btc:
    ACK 6a68343
  fanquake:
    ACK 6a68343 - we still need to followup with other scripts/devtools, and likely unify what we are doing in some way, but this is an improvement.

Tree-SHA512: 905d9c68cafe1e405e98d6aa089d7a36a34c9e03403df5c67ac2c9a98cfa54a0305b647cb92247dcb9f49e9b509a8ba88367392b95618c67059684c67b6c36fb

Author: fanquake

contrib/tracing/README.md

@@ -82,7 +82,7 @@ about the connection. Peers can be selected individually to view recent P2P
 messages.
 
 ```
-$ python3 contrib/tracing/p2p_monitor.py ./src/bitcoind
+$ python3 contrib/tracing/p2p_monitor.py ./build/src/bitcoind
 ```
 
 Lists selectable peers and traffic and connection information.
@@ -150,7 +150,7 @@ lost. BCC prints: `Possibly lost 2 samples` on lost messages.
 
 
 ```
-$ python3 contrib/tracing/log_raw_p2p_msgs.py ./src/bitcoind
+$ python3 contrib/tracing/log_raw_p2p_msgs.py ./build/src/bitcoind
 ```
 
 ```
@@ -188,7 +188,7 @@ In a different terminal, starting Bitcoin Core in SigNet mode and with
 re-indexing enabled.
 
 ```
-$ ./src/bitcoind -signet -reindex
+$ ./build/src/bitcoind -signet -reindex
 ```
 
 This produces the following output.
@@ -241,7 +241,7 @@ A BCC Python script to log the UTXO cache flushes. Based on the
 `utxocache:flush` tracepoint.
 
 ```bash
-$ python3 contrib/tracing/log_utxocache_flush.py ./src/bitcoind
+$ python3 contrib/tracing/log_utxocache_flush.py ./build/src/bitcoind
 ```
 
 ```
@@ -300,7 +300,7 @@ comprising a timestamp along with all event data available via the event's
 tracepoint.
 
 ```console
-$ python3 contrib/tracing/mempool_monitor.py ./src/bitcoind
+$ python3 contrib/tracing/mempool_monitor.py ./build/src/bitcoind
 ```
 
 ```

contrib/tracing/connectblock_benchmark.bt

@@ -16,7 +16,7 @@
 
   This script requires a 'bitcoind' binary compiled with eBPF support and the
   'validation:block_connected' USDT. By default, it's assumed that 'bitcoind' is
-  located in './src/bitcoind'. This can be modified in the script below.
+  located in './build/src/bitcoind'. This can be modified in the script below.
 
   EXAMPLES:
 
@@ -67,7 +67,7 @@ BEGIN
   connected block is between the start and end height (or the end height is
   unset).
 */
-usdt:./src/bitcoind:validation:block_connected /arg1 >= $1 && (arg1 <= $2 || $2 == 0 )/
+usdt:./build/src/bitcoind:validation:block_connected /arg1 >= $1 && (arg1 <= $2 || $2 == 0 )/
 {
   $height = arg1;
   $transactions = arg2;
@@ -102,7 +102,7 @@ usdt:./src/bitcoind:validation:block_connected /arg1 >= $1 && (arg1 <= $2 || $2
   blocks where the time it took to connect the block is above the
   <logging threshold in ms>.
 */
-usdt:./src/bitcoind:validation:block_connected / (uint64) arg5 / 1000> $3 /
+usdt:./build/src/bitcoind:validation:block_connected / (uint64) arg5 / 1000> $3 /
 {
   $hash = arg0;
   $height = (int32) arg1;

contrib/tracing/log_p2p_traffic.bt

@@ -5,7 +5,7 @@ BEGIN
   printf("Logging P2P traffic\n")
 }
 
-usdt:./src/bitcoind:net:inbound_message
+usdt:./build/src/bitcoind:net:inbound_message
 {
   $peer_id = (int64) arg0;
   $peer_addr = str(arg1);
@@ -15,7 +15,7 @@ usdt:./src/bitcoind:net:inbound_message
   printf("inbound '%s' msg from peer %d (%s, %s) with %d bytes\n", $msg_type, $peer_id, $peer_type, $peer_addr, $msg_len);
 }
 
-usdt:./src/bitcoind:net:outbound_message
+usdt:./build/src/bitcoind:net:outbound_message
 {
   $peer_id = (int64) arg0;
   $peer_addr = str(arg1);

contrib/tracing/log_utxos.bt

@@ -8,7 +8,7 @@
 
   This script requires a 'bitcoind' binary compiled with eBPF support and the
   'utxocache' tracepoints. By default, it's assumed that 'bitcoind' is
-  located in './src/bitcoind'. This can be modified in the script below.
+  located in './build/src/bitcoind'. This can be modified in the script below.
 
   NOTE: requires bpftrace v0.12.0 or above.
 */
@@ -22,7 +22,7 @@ BEGIN
 /*
   Attaches to the 'utxocache:add' tracepoint and prints additions to the UTXO set cache.
 */
-usdt:./src/bitcoind:utxocache:add
+usdt:./build/src/bitcoind:utxocache:add
 {
   $txid = arg0;
   $index = (uint32)arg1;
@@ -44,7 +44,7 @@ usdt:./src/bitcoind:utxocache:add
 /*
   Attaches to the 'utxocache:spent' tracepoint and prints spents from the UTXO set cache.
 */
-usdt:./src/bitcoind:utxocache:spent
+usdt:./build/src/bitcoind:utxocache:spent
 {
   $txid = arg0;
   $index = (uint32)arg1;
@@ -66,7 +66,7 @@ usdt:./src/bitcoind:utxocache:spent
 /*
   Attaches to the 'utxocache:uncache' tracepoint and uncache UTXOs from the UTXO set cache.
 */
-usdt:./src/bitcoind:utxocache:uncache
+usdt:./build/src/bitcoind:utxocache:uncache
 {
   $txid = arg0;
   $index = (uint32)arg1;

contrib/valgrind.supp

@@ -2,14 +2,14 @@
 # dependencies that cannot be fixed in-tree.
 #
 # Example use:
-# $ valgrind --suppressions=contrib/valgrind.supp src/test/test_bitcoin
+# $ valgrind --suppressions=contrib/valgrind.supp build/src/test/test_bitcoin
 # $ valgrind --suppressions=contrib/valgrind.supp --leak-check=full \
-#       --show-leak-kinds=all src/test/test_bitcoin
+#       --show-leak-kinds=all build/src/test/test_bitcoin
 #
 # To create suppressions for found issues, use the --gen-suppressions=all option:
 # $ valgrind --suppressions=contrib/valgrind.supp --leak-check=full \
 #       --show-leak-kinds=all --gen-suppressions=all --show-reachable=yes \
-#       --error-limit=no src/test/test_bitcoin
+#       --error-limit=no build/src/test/test_bitcoin
 #
 # Note that suppressions may depend on OS and/or library versions.
 # Tested on:

doc/developer-notes.md

@@ -338,9 +338,10 @@ Recommendations:
 
 ### Generating Documentation
 
-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.
+Assuming the build directory is named `build`,
+the documentation can be generated with `cmake --build build --target docs`.
+The resulting files will be located in `build/doc/doxygen/html`;
+open `index.html` in that directory to view the homepage.
 
 Before building the `docs` target, you'll need to install these dependencies:
 
@@ -467,11 +468,11 @@ which includes known Valgrind warnings in our dependencies that cannot be fixed
 in-tree. Example use:
 
 ```shell
-$ valgrind --suppressions=contrib/valgrind.supp src/test/test_bitcoin
+$ valgrind --suppressions=contrib/valgrind.supp build/src/test/test_bitcoin
 $ valgrind --suppressions=contrib/valgrind.supp --leak-check=full \
-      --show-leak-kinds=all src/test/test_bitcoin --log_level=test_suite
-$ valgrind -v --leak-check=full src/bitcoind -printtoconsole
-$ ./test/functional/test_runner.py --valgrind
+      --show-leak-kinds=all build/src/test/test_bitcoin --log_level=test_suite
+$ valgrind -v --leak-check=full build/src/bitcoind -printtoconsole
+$ ./build/test/functional/test_runner.py --valgrind
 ```
 
 ### Compiling for test coverage

doc/multisig-tutorial.md

@@ -9,7 +9,7 @@ This tutorial uses [jq](https://github.com/stedolan/jq) JSON processor to proces
 Before starting this tutorial, start the bitcoin node on the signet network.
 
 ```bash
-./src/bitcoind -signet -daemon
+./build/src/bitcoind -signet -daemon
 ```
 
 This tutorial also uses the default WPKH derivation path to get the xpubs and does not conform to [BIP 45](https://github.com/bitcoin/bips/blob/master/bip-0045.mediawiki) or [BIP 87](https://github.com/bitcoin/bips/blob/master/bip-0087.mediawiki).
@@ -27,7 +27,7 @@ These three wallets should not be used directly for privacy reasons (public key
 ```bash
 for ((n=1;n<=3;n++))
 do
- ./src/bitcoin-cli -signet createwallet "participant_${n}"
+ ./build/src/bitcoin-cli -signet createwallet "participant_${n}"
 done
 ```
 
@@ -47,9 +47,9 @@ declare -A xpubs
 
 for ((n=1;n<=3;n++))
 do
- xpubs["internal_xpub_${n}"]=$(./src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/1/*"))][0] | .desc' | grep -Po '(?<=\().*(?=\))')
+ xpubs["internal_xpub_${n}"]=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/1/*"))][0] | .desc' | grep -Po '(?<=\().*(?=\))')
 
- xpubs["external_xpub_${n}"]=$(./src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/0/*") )][0] | .desc' | grep -Po '(?<=\().*(?=\))')
+ xpubs["external_xpub_${n}"]=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_${n}" listdescriptors | jq '.descriptors | [.[] | select(.desc | startswith("wpkh") and contains("/0/*") )][0] | .desc' | grep -Po '(?<=\().*(?=\))')
 done
 ```
 
@@ -71,8 +71,8 @@ Define the external and internal multisig descriptors, add the checksum and then
 external_desc="wsh(sortedmulti(2,${xpubs["external_xpub_1"]},${xpubs["external_xpub_2"]},${xpubs["external_xpub_3"]}))"
 internal_desc="wsh(sortedmulti(2,${xpubs["internal_xpub_1"]},${xpubs["internal_xpub_2"]},${xpubs["internal_xpub_3"]}))"
 
-external_desc_sum=$(./src/bitcoin-cli -signet getdescriptorinfo $external_desc | jq '.descriptor')
-internal_desc_sum=$(./src/bitcoin-cli -signet getdescriptorinfo $internal_desc | jq '.descriptor')
+external_desc_sum=$(./build/src/bitcoin-cli -signet getdescriptorinfo $external_desc | jq '.descriptor')
+internal_desc_sum=$(./build/src/bitcoin-cli -signet getdescriptorinfo $internal_desc | jq '.descriptor')
 
 multisig_ext_desc="{\"desc\": $external_desc_sum, \"active\": true, \"internal\": false, \"timestamp\": \"now\"}"
 multisig_int_desc="{\"desc\": $internal_desc_sum, \"active\": true, \"internal\": true, \"timestamp\": \"now\"}"
@@ -94,7 +94,7 @@ There are other fields that can be added to the descriptors:
 * `internal`: Indicates whether matching outputs should be treated as something other than incoming payments (e.g. change).
 * `timestamp`: Sets the time from which to start rescanning the blockchain for the descriptor, in UNIX epoch time.
 
-Documentation for these and other parameters can be found by typing `./src/bitcoin-cli help importdescriptors`.
+Documentation for these and other parameters can be found by typing `./build/src/bitcoin-cli help importdescriptors`.
 
 `multisig_desc` concatenates external and internal descriptors in a JSON array and then it will be used to create the multisig wallet.
 
@@ -107,17 +107,17 @@ Then import the descriptors created in the previous step using the `importdescri
 After that, `getwalletinfo` can be used to check if the wallet was created successfully.
 
 ```bash
-./src/bitcoin-cli -signet -named createwallet wallet_name="multisig_wallet_01" disable_private_keys=true blank=true
+./build/src/bitcoin-cli -signet -named createwallet wallet_name="multisig_wallet_01" disable_private_keys=true blank=true
 
-./src/bitcoin-cli  -signet -rpcwallet="multisig_wallet_01" importdescriptors "$multisig_desc"
+./build/src/bitcoin-cli  -signet -rpcwallet="multisig_wallet_01" importdescriptors "$multisig_desc"
 
-./src/bitcoin-cli  -signet -rpcwallet="multisig_wallet_01" getwalletinfo
+./build/src/bitcoin-cli  -signet -rpcwallet="multisig_wallet_01" getwalletinfo
 ```
 
 Once the wallets have already been created and this tutorial needs to be repeated or resumed, it is not necessary to recreate them, just load them with the command below:
 
 ```bash
-for ((n=1;n<=3;n++)); do ./src/bitcoin-cli -signet loadwallet "participant_${n}"; done
+for ((n=1;n<=3;n++)); do ./build/src/bitcoin-cli -signet loadwallet "participant_${n}"; done
 ```
 
 ### 1.4 Fund the wallet
@@ -131,9 +131,9 @@ The url used by the script can also be accessed directly. At time of writing, th
 Coins received by the wallet must have at least 1 confirmation before they can be spent. It is necessary to wait for a new block to be mined before continuing.
 
 ```bash
-receiving_address=$(./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getnewaddress)
+receiving_address=$(./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getnewaddress)
 
-./contrib/signet/getcoins.py -c ./src/bitcoin-cli -a $receiving_address
+./contrib/signet/getcoins.py -c ./build/src/bitcoin-cli -a $receiving_address
 ```
 
 To copy the receiving address onto the clipboard, use the following command. This can be useful when getting coins via the signet faucet mentioned above.
@@ -145,7 +145,7 @@ echo -n "$receiving_address" | xclip -sel clip
 The `getbalances` RPC may be used to check the balance. Coins with `trusted` status can be spent.
 
 ```bash
-./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalances
+./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalances
 ```
 
 ### 1.5 Create a PSBT
@@ -161,13 +161,13 @@ For simplicity, the destination address is taken from the `participant_1` wallet
 The `walletcreatefundedpsbt` RPC is used to create and fund a transaction in the PSBT format. It is the first step in creating the PSBT.
 
 ```bash
-balance=$(./src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalance)
+balance=$(./build/src/bitcoin-cli -signet -rpcwallet="multisig_wallet_01" getbalance)
 
 amount=$(echo "$balance * 0.8" | bc -l | sed -e 's/^\./0./' -e 's/^-\./-0./')
 
-destination_addr=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" getnewaddress)
+destination_addr=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_1" getnewaddress)
 
-funded_psbt=$(./src/bitcoin-cli -signet -named -rpcwallet="multisig_wallet_01" walletcreatefundedpsbt outputs="{\"$destination_addr\": $amount}" | jq -r '.psbt')
+funded_psbt=$(./build/src/bitcoin-cli -signet -named -rpcwallet="multisig_wallet_01" walletcreatefundedpsbt outputs="{\"$destination_addr\": $amount}" | jq -r '.psbt')
 ```
 
 There is also the `createpsbt` RPC, which serves the same purpose, but it has no access to the wallet or to the UTXO set. It is functionally the same as `createrawtransaction` and just drops the raw transaction into an otherwise blank PSBT. [[source](https://bitcointalk.org/index.php?topic=5131043.msg50573609#msg50573609)] In most cases, `walletcreatefundedpsbt` solves the problem.
@@ -181,9 +181,9 @@ Optionally, the PSBT can be decoded to a JSON format using `decodepsbt` RPC.
 The `analyzepsbt` RPC analyzes and provides information about the current status of a PSBT and its inputs, e.g. missing signatures.
 
 ```bash
-./src/bitcoin-cli -signet decodepsbt $funded_psbt
+./build/src/bitcoin-cli -signet decodepsbt $funded_psbt
 
-./src/bitcoin-cli -signet analyzepsbt $funded_psbt
+./build/src/bitcoin-cli -signet analyzepsbt $funded_psbt
 ```
 
 ### 1.7 Update the PSBT
@@ -193,17 +193,17 @@ In the code above, two PSBTs are created. One signed by `participant_1` wallet a
 The `walletprocesspsbt` is used by the wallet to sign a PSBT.
 
 ```bash
-psbt_1=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq '.psbt')
+psbt_1=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq '.psbt')
 
-psbt_2=$(./src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $funded_psbt | jq '.psbt')
+psbt_2=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $funded_psbt | jq '.psbt')
 ```
 
 ### 1.8 Combine the PSBT
 
 The PSBT, if signed separately by the co-signers, must be combined into one transaction before being finalized. This is done by `combinepsbt` RPC.
 
 ```bash
-combined_psbt=$(./src/bitcoin-cli -signet combinepsbt "[$psbt_1, $psbt_2]")
+combined_psbt=$(./build/src/bitcoin-cli -signet combinepsbt "[$psbt_1, $psbt_2]")
 ```
 
 There is an RPC called `joinpsbts`, but it has a different purpose than `combinepsbt`. `joinpsbts` joins the inputs from multiple distinct PSBTs into one PSBT.
@@ -217,9 +217,9 @@ The `finalizepsbt` RPC is used to produce a network serialized transaction which
 It checks that all inputs have complete scriptSigs and scriptWitnesses and, if so, encodes them into network serialized transactions.
 
 ```bash
-finalized_psbt_hex=$(./src/bitcoin-cli -signet finalizepsbt $combined_psbt | jq -r '.hex')
+finalized_psbt_hex=$(./build/src/bitcoin-cli -signet finalizepsbt $combined_psbt | jq -r '.hex')
 
-./src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex
+./build/src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex
 ```
 
 ### 1.10 Alternative Workflow (PSBT sequential signatures)
@@ -229,11 +229,11 @@ Instead of each wallet signing the original PSBT and combining them later, the w
 After that, the rest of the process is the same: the PSBT is finalized and transmitted to the network.
 
 ```bash
-psbt_1=$(./src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq -r '.psbt')
+psbt_1=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_1" walletprocesspsbt $funded_psbt | jq -r '.psbt')
 
-psbt_2=$(./src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $psbt_1 | jq -r '.psbt')
+psbt_2=$(./build/src/bitcoin-cli -signet -rpcwallet="participant_2" walletprocesspsbt $psbt_1 | jq -r '.psbt')
 
-finalized_psbt_hex=$(./src/bitcoin-cli -signet finalizepsbt $psbt_2 | jq -r '.hex')
+finalized_psbt_hex=$(./build/src/bitcoin-cli -signet finalizepsbt $psbt_2 | jq -r '.hex')
 
-./src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex
+./build/src/bitcoin-cli -signet sendrawtransaction $finalized_psbt_hex
 ```