From cd97905ebc564b8b095099a28d1d5437951927c4 Mon Sep 17 00:00:00 2001 From: Ryan Ofsky Date: Fri, 17 Jan 2025 11:44:46 -0500 Subject: [PATCH 1/5] cmake: Move internal binaries from bin/ to libexec/ This change moves binaries that are not typically invoked directly by users from the `bin/` directory to the `libexec/` directory in CMake installs and binary releases. The goal is to simplify the contents of `bin/` for end users while still making all binaries available when needed. After this change, the binaries remaining in `bin/` are: - bitcoin - bitcoin-cli - bitcoind - bitcoin-qt - bitcoin-tx - bitcoin-util - bitcoin-wallet And the binaries that are moved to `libexec/` are: - bench_bitcoin - bitcoin-chainstate(*) - bitcoin-gui(***) - bitcoin-node(***) - test_bitcoin(**) - test_bitcoin-qt (*) bitcoin-chainstate was previously missing an install rule and was actually not installed even when it was enabled. (**) test_bitcoin is the only libexec/ binary that is currently included in bitcoin binary releases. The others are only installed when building from source with relevant cmake options enabled. (***) bitcoin-node and bitcoin-gui are not currently built by default or included in binary releases but both of these changes are planned and implemented in #31802 --- ci/test/03_test_script.sh | 2 +- cmake/module/InstallBinaryComponent.cmake | 15 ++++++++++----- contrib/guix/libexec/codesign.sh | 2 +- contrib/macdeploy/detached-sig-create.sh | 2 +- src/CMakeLists.txt | 3 ++- src/bench/CMakeLists.txt | 2 +- src/qt/CMakeLists.txt | 2 +- src/qt/test/CMakeLists.txt | 2 +- src/test/CMakeLists.txt | 2 +- 9 files changed, 19 insertions(+), 13 deletions(-) diff --git a/ci/test/03_test_script.sh b/ci/test/03_test_script.sh index 3394c50b8bd..d836a9efa7d 100755 --- a/ci/test/03_test_script.sh +++ b/ci/test/03_test_script.sh @@ -145,7 +145,7 @@ if [ "$RUN_UNIT_TESTS" = "true" ]; then fi if [ "$RUN_UNIT_TESTS_SEQUENTIAL" = "true" ]; then - DIR_UNIT_TEST_DATA="${DIR_UNIT_TEST_DATA}" LD_LIBRARY_PATH="${DEPENDS_DIR}/${HOST}/lib" "${BASE_OUTDIR}"/bin/test_bitcoin --catch_system_errors=no -l test_suite + DIR_UNIT_TEST_DATA="${DIR_UNIT_TEST_DATA}" LD_LIBRARY_PATH="${DEPENDS_DIR}/${HOST}/lib" "${BASE_BUILD_DIR}"/bin/test_bitcoin --catch_system_errors=no -l test_suite fi if [ "$RUN_FUNCTIONAL_TESTS" = "true" ]; then diff --git a/cmake/module/InstallBinaryComponent.cmake b/cmake/module/InstallBinaryComponent.cmake index c7b2ed9ae6a..42bcd88efb4 100644 --- a/cmake/module/InstallBinaryComponent.cmake +++ b/cmake/module/InstallBinaryComponent.cmake @@ -7,14 +7,19 @@ include(GNUInstallDirs) function(install_binary_component component) cmake_parse_arguments(PARSE_ARGV 1 - IC # prefix - "HAS_MANPAGE" # options - "" # one_value_keywords - "" # multi_value_keywords + IC # prefix + "HAS_MANPAGE;INTERNAL" # options + "" # one_value_keywords + "" # multi_value_keywords ) set(target_name ${component}) + if(IC_INTERNAL) + set(runtime_dest ${CMAKE_INSTALL_LIBEXECDIR}) + else() + set(runtime_dest ${CMAKE_INSTALL_BINDIR}) + endif() install(TARGETS ${target_name} - RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR} + RUNTIME DESTINATION ${runtime_dest} COMPONENT ${component} ) if(INSTALL_MAN AND IC_HAS_MANPAGE) diff --git a/contrib/guix/libexec/codesign.sh b/contrib/guix/libexec/codesign.sh index 3a729371114..fe86065350e 100755 --- a/contrib/guix/libexec/codesign.sh +++ b/contrib/guix/libexec/codesign.sh @@ -110,7 +110,7 @@ mkdir -p "$DISTSRC" # Apply detached codesignatures (in-place) signapple apply dist/Bitcoin-Qt.app codesignatures/osx/"${HOST}"/dist/Bitcoin-Qt.app - find "${DISTNAME}" -wholename "*/bin/*" -type f | while read -r bin + find "${DISTNAME}" \( -wholename "*/bin/*" -o -wholename "*/libexec/*" \) -type f | while read -r bin do signapple apply "${bin}" "codesignatures/osx/${HOST}/${bin}.${ARCH}sign" done diff --git a/contrib/macdeploy/detached-sig-create.sh b/contrib/macdeploy/detached-sig-create.sh index 89094403b7f..b558784eff2 100755 --- a/contrib/macdeploy/detached-sig-create.sh +++ b/contrib/macdeploy/detached-sig-create.sh @@ -44,7 +44,7 @@ ${SIGNAPPLE} apply "${UNSIGNED_BUNDLE}" "${OUTROOT}/${BUNDLE_ROOT}/${BUNDLE_NAME ${SIGNAPPLE} notarize --detach "${OUTROOT}/${BUNDLE_ROOT}" --passphrase "${api_key_pass}" "$2" "$3" "${UNSIGNED_BUNDLE}" # Sign each binary -find . -maxdepth 3 -wholename "*/bin/*" -type f -exec realpath --relative-to=. {} \; | while read -r bin +find . -maxdepth 3 \( -wholename "*/bin/*" -o -wholename "*/libexec/*" \) -type f -exec realpath --relative-to=. {} \; | while read -r bin do bin_dir=$(dirname "${bin}") bin_name=$(basename "${bin}") diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 96a6790e612..eb8612c4285 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -367,7 +367,7 @@ if(ENABLE_IPC AND BUILD_DAEMON) bitcoin_ipc $ ) - install_binary_component(bitcoin-node) + install_binary_component(bitcoin-node INTERNAL) endif() if(ENABLE_IPC AND BUILD_TESTS) @@ -469,6 +469,7 @@ if(BUILD_UTIL_CHAINSTATE) core_interface bitcoinkernel ) + install_binary_component(bitcoin-chainstate INTERNAL) endif() diff --git a/src/bench/CMakeLists.txt b/src/bench/CMakeLists.txt index 905187fbb00..0168589a6a0 100644 --- a/src/bench/CMakeLists.txt +++ b/src/bench/CMakeLists.txt @@ -83,4 +83,4 @@ add_test(NAME bench_sanity_check COMMAND bench_bitcoin -sanity-check ) -install_binary_component(bench_bitcoin) +install_binary_component(bench_bitcoin INTERNAL) diff --git a/src/qt/CMakeLists.txt b/src/qt/CMakeLists.txt index 6c853cbf2f8..ed7d9a49511 100644 --- a/src/qt/CMakeLists.txt +++ b/src/qt/CMakeLists.txt @@ -282,7 +282,7 @@ if(ENABLE_IPC) bitcoin_ipc ) import_plugins(bitcoin-gui) - install_binary_component(bitcoin-gui) + install_binary_component(bitcoin-gui INTERNAL) if(WIN32) set_target_properties(bitcoin-gui PROPERTIES WIN32_EXECUTABLE TRUE) endif() diff --git a/src/qt/test/CMakeLists.txt b/src/qt/test/CMakeLists.txt index cbfb144596b..8fe4ea68e26 100644 --- a/src/qt/test/CMakeLists.txt +++ b/src/qt/test/CMakeLists.txt @@ -45,4 +45,4 @@ if(WIN32 AND VCPKG_TARGET_TRIPLET) ) endif() -install_binary_component(test_bitcoin-qt) +install_binary_component(test_bitcoin-qt INTERNAL) diff --git a/src/test/CMakeLists.txt b/src/test/CMakeLists.txt index 6ce33621af8..6f00e2f2258 100644 --- a/src/test/CMakeLists.txt +++ b/src/test/CMakeLists.txt @@ -213,4 +213,4 @@ endfunction() add_all_test_targets() -install_binary_component(test_bitcoin) +install_binary_component(test_bitcoin INTERNAL) From 94ffd01a0294afbe045f1b17a77e4a3caf21e674 Mon Sep 17 00:00:00 2001 From: Ryan Ofsky Date: Wed, 9 Apr 2025 18:04:03 -0400 Subject: [PATCH 2/5] doc: Add release notes describing libexec/ binaries --- doc/release-notes-31375-31679.md | 24 ++++++++++++++++++++++++ doc/release-notes-31375.md | 11 ----------- 2 files changed, 24 insertions(+), 11 deletions(-) create mode 100644 doc/release-notes-31375-31679.md delete mode 100644 doc/release-notes-31375.md diff --git a/doc/release-notes-31375-31679.md b/doc/release-notes-31375-31679.md new file mode 100644 index 00000000000..7f6b0667a69 --- /dev/null +++ b/doc/release-notes-31375-31679.md @@ -0,0 +1,24 @@ +New command line interface +-------------------------- + +A new `bitcoin` command line tool has been added to make features more +discoverable and convenient to use. The `bitcoin` tool just calls other +executables and does not implement any functionality on its own. Specifically +`bitcoin node` is a synonym for `bitcoind`, `bitcoin gui` is a synonym for +`bitcoin-qt`, and `bitcoin rpc` is a synonym for `bitcoin-cli -named`. Other +commands and options can be listed with `bitcoin help`. The new tool does not +replace other tools, so existing commands should continue working and there are +no plans to deprecate them. + +Install changes +--------------- + +The `test_bitcoin` executable is now located in `libexec/` rather than `bin/`. +It can still be executed directly, or accessed through the new `bitcoin` command +line tool as `bitcoin test`. + +Other executables which are only part of source releases and not built by +default: `test_bitcoin-qt`, `bench_bitcoin`, `bitcoin-chainstate`, +`bitcoin-node`, and `bitcoin-gui` are also now installed in `libexec/` +instead of `bin/` and can be accessed through the `bitcoin` command line tool. +See `bitcoin help` output for details. diff --git a/doc/release-notes-31375.md b/doc/release-notes-31375.md deleted file mode 100644 index e1e7f5c0afb..00000000000 --- a/doc/release-notes-31375.md +++ /dev/null @@ -1,11 +0,0 @@ -New command line interface --------------------------- - -A new `bitcoin` command line tool has been added to make features more -discoverable and convenient to use. The `bitcoin` tool just calls other -executables and does not implement any functionality on its own. Specifically -`bitcoin node` is a synonym for `bitcoind`, `bitcoin gui` is a synonym for -`bitcoin-qt`, and `bitcoin rpc` is a synonym for `bitcoin-cli -named`. Other -commands and options can be listed with `bitcoin help`. The new tool does not -replace other tools, so all existing commands should continue working and there -are no plans to deprecate them. From c810b168b89dc07017e9feaec1a8746a449a60b1 Mon Sep 17 00:00:00 2001 From: Ryan Ofsky Date: Mon, 14 Apr 2025 09:29:04 -0400 Subject: [PATCH 3/5] doc: Add description of installed files to files.md --- doc/files.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/doc/files.md b/doc/files.md index 1b93ab797d1..6d2faa4c8f2 100644 --- a/doc/files.md +++ b/doc/files.md @@ -16,7 +16,7 @@ - [Berkeley DB database based wallets](#berkeley-db-database-based-wallets) -- [Notes](#notes) +- [Installed Files](#installed-files) ## Data directory location @@ -123,8 +123,40 @@ Subdirectory | File(s) | Description `./` | `wallet.dat` | Personal wallet (a BDB database) with keys and transactions `./` | `.walletlock` | BDB wallet lock file -## Notes +### Notes 1. The `/` (slash, U+002F) is used as the platform-independent path component separator in this document. 2. `NNNNN` matches `[0-9]{5}` regex. + +## Installed Files + +This table describes the files installed by Bitcoin Core across different platforms. + +| **Path** | **Description** | +|------------------------------------------------------------|-----------------------------------------------------------------------------| +| [README.md](README.md) or [readme.txt](README_windows.txt) | Project information and instructions | +| bitcoin.conf | [Generated](../contrib/devtools/gen-bitcoin-conf.sh) configuration file | +| bin/bitcoin | Command-line tool for interacting with Bitcoin. Calls other binaries below. | +| bin/bitcoin-cli | Tool for making node and wallet RPC calls. | +| bin/bitcoin-qt | Bitcoin node and wallet GUI | +| bin/bitcoin-tx | Tool for creating and modifying transactions | +| bin/bitcoin-util | Miscellaneous utilities | +| bin/bitcoin-wallet | Bitcoin wallet tool | +| bin/bitcoind | Bitcoin node and wallet daemon | +| *lib/libbitcoinkernel.so* | Shared library containing core consensus and validation code | +| *lib/pkgconfig/libbitcoinkernel.pc* | Pkg-config metadata for linking to `libbitcoinkernel` | +| *libexec/bench_bitcoin* | Benchmarking tool for measuring node performance | +| *libexec/bitcoin-chainstate* | Tool to validate and connect blocks | +| *libexec/bitcoin-gui* | IPC-enabled alternative to `bitcoin-qt` | +| *libexec/bitcoin-node* | IPC-enabled alternative to `bitcoind` | +| libexec/test_bitcoin | Unit test binary | +| *libexec/test_bitcoin-qt* | GUI-specific unit tests | +| share/man/man1/ | Man pages for command-line tools like `bitcoin-cli`, `bitcoind`, and others | +| share/rpcauth/ | Documentation and scripts for RPC authentication setup | + +### Notes + +- *Italicized* files are only installed in source builds if relevant CMake options are enabled. They are not included in binary releases. +- README and bitcoin.conf files are included in binary releases but not installed in source builds. +- On Windows, binaries have a `.exe` suffix (e.g., `bitcoin-cli.exe`). From f5cf0b1ccc8fd426135809a8a4becdae2d797bb5 Mon Sep 17 00:00:00 2001 From: Ryan Ofsky Date: Thu, 3 Jul 2025 17:03:00 -0400 Subject: [PATCH 4/5] bitcoin wrapper: improve help output Try to make extra commands more obvious based on a suggestion from Sjors: https://github.com/bitcoin/bitcoin/pull/31679#issuecomment-2922787970i When `bitcoin` is invoked with no arguments, still show short help output, but now explicitly state that more commands are available and `bitcoin help` will list them. Also: - Get rid of -a/--all option. Just show all commands when `bitcoin help` or `bitcoin --help` is used. It maybe a helpful to add an option like this if more commands are added in the future, but right now there are not very many. - Just show name of executable, not full path of executable in help output. This can be a little easier to read if the path is long. --- src/bitcoin.cpp | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/src/bitcoin.cpp b/src/bitcoin.cpp index 65776513941..c3278274153 100644 --- a/src/bitcoin.cpp +++ b/src/bitcoin.cpp @@ -23,7 +23,7 @@ Options: -m, --multiprocess Run multiprocess binaries bitcoin-node, bitcoin-gui. -M, --monolithic Run monolithic binaries bitcoind, bitcoin-qt. (Default behavior) -v, --version Show version information - -h, --help Show this help message + -h, --help Show full help message Commands: gui [ARGS] Start GUI, equivalent to running 'bitcoin-qt [ARGS]' or 'bitcoin-gui [ARGS]'. @@ -31,10 +31,10 @@ Commands: rpc [ARGS] Call RPC method, equivalent to running 'bitcoin-cli -named [ARGS]'. wallet [ARGS] Call wallet command, equivalent to running 'bitcoin-wallet [ARGS]'. tx [ARGS] Manipulate hex-encoded transactions, equivalent to running 'bitcoin-tx [ARGS]'. - help [-a] Show this help message. Include -a or --all to show additional commands. + help Show full help message. )"; -static constexpr auto HELP_EXTRA = R"( +static constexpr auto HELP_FULL = R"( Additional less commonly used commands: bench [ARGS] Run bench command, equivalent to running 'bench_bitcoin [ARGS]'. chainstate [ARGS] Run bitcoin kernel chainstate util, equivalent to running 'bitcoin-chainstate [ARGS]'. @@ -42,11 +42,14 @@ Additional less commonly used commands: test-gui [ARGS] Run GUI unit tests, equivalent to running 'test_bitcoin-qt [ARGS]'. )"; +static constexpr auto HELP_SHORT = R"( +Run '%s help' to see additional commands (e.g. for testing and debugging). +)"; + struct CommandLine { bool use_multiprocess{false}; bool show_version{false}; bool show_help{false}; - bool show_help_all{false}; std::string_view command; std::vector args; }; @@ -63,11 +66,17 @@ int main(int argc, char* argv[]) return EXIT_SUCCESS; } + std::string exe_name{fs::PathToString(fs::PathFromString(argv[0]).filename())}; std::vector args; if (cmd.show_help || cmd.command.empty()) { - tfm::format(std::cout, HELP_USAGE, argv[0]); - if (cmd.show_help_all) tfm::format(std::cout, HELP_EXTRA); - return cmd.show_help ? EXIT_SUCCESS : EXIT_FAILURE; + tfm::format(std::cout, HELP_USAGE, exe_name); + if (cmd.show_help) { + tfm::format(std::cout, HELP_FULL); + return EXIT_SUCCESS; + } else { + tfm::format(std::cout, HELP_SHORT, exe_name); + return EXIT_FAILURE; + } } else if (cmd.command == "gui") { args.emplace_back(cmd.use_multiprocess ? "bitcoin-gui" : "bitcoin-qt"); } else if (cmd.command == "node") { @@ -125,8 +134,6 @@ CommandLine ParseCommandLine(int argc, char* argv[]) cmd.show_version = true; } else if (arg == "-h" || arg == "--help" || arg == "help") { cmd.show_help = true; - } else if (cmd.show_help && (arg == "-a" || arg == "--all")) { - cmd.show_help_all = true; } else if (arg.starts_with("-")) { throw std::runtime_error(strprintf("Unknown option: %s", arg)); } else if (!arg.empty()) { From f49840dd902cd9b14b6aadb431b16a4aeb719c3f Mon Sep 17 00:00:00 2001 From: Ryan Ofsky Date: Fri, 4 Jul 2025 11:06:30 -0400 Subject: [PATCH 5/5] doc: Fix typo in files.md Suggested by l0rinc https://github.com/bitcoin/bitcoin/pull/31679#discussion_r2185083314 --- doc/files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/files.md b/doc/files.md index 6d2faa4c8f2..90d804471e1 100644 --- a/doc/files.md +++ b/doc/files.md @@ -83,7 +83,7 @@ Wallets are SQLite databases. 3. A wallet database path can be specified with the `-wallet` option. -4. `wallet.dat` files must not be shared across different node instances, as that can result in key-reuse and double-spends due the lack of synchronization between instances. +4. `wallet.dat` files must not be shared across different node instances, as that can result in key-reuse and double-spends due to the lack of synchronization between instances. 5. Any copy or backup of the wallet should be done through a `backupwallet` call in order to update and lock the wallet, preventing any file corruption caused by updates during the copy.