mirror of https://github.com/bitcoin/bitcoin.git synced 2025-11-15 16:38:23 +01:00

Files

merge-script 2bb06bcaf2 Merge bitcoin/bitcoin#31679 : cmake: Install internal binaries to <prefix>/libexec/

f49840dd90 doc: Fix typo in files.md (Ryan Ofsky)
f5cf0b1ccc bitcoin wrapper: improve help output (Ryan Ofsky)
c810b168b8 doc: Add description of installed files to files.md (Ryan Ofsky)
94ffd01a02 doc: Add release notes describing libexec/ binaries (Ryan Ofsky)
cd97905ebc cmake: Move internal binaries from bin/ to libexec/ (Ryan Ofsky)

Pull request description:

  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 of the PR is to introduce a distinction between internal and external binaries so starting with #31802, we can use IPC to implement features in new binaries without adding those binaries to the CLI. The change also helps reduce clutter in `bin/`, making it easier for users to identify useful tools to run. Summary of changes:

  - For **source builds** (i.e. developer builds) — There are no changes.
  - For **source installs** (i.e. `cmake --install` result) — `test_bitcoin`, `test_bitcoin-qt`, and `bench_bitcoin` are installed in `${CMAKE_PREFIX_PATH}/libexec` instead of `${CMAKE_PREFIX_PATH}/bin`, so they are no longer on the system `PATH`. However, they can still be invoked from the `libexec/` directory, or from the CLI as `bitcoin test`, `bitcoin test-gui`, and `bitcoin bench`, respectively.
  - For **binary releases** — Since `test_bitcoin` is the only test binary enabled in releases, the only change is moving `test_bitcoin` from `bin/` to `libexec/`.

  <details><summary>Details</summary>
  <p>

   The table below shows the install location of each binary after this change, and the availability of each binary.

  | Binary               | Location     | Availability         | Change                        |
  |----------------------|--------------|----------------------|-------------------------------|
  | `bitcoin`            | `bin/`       | 📦 Binary release (since #31375) | Unchanged                     |
  | `bitcoin-cli`        | `bin/`       | 📦 Binary release     | Unchanged                     |
  | `bitcoind`           | `bin/`       | 📦 Binary release     | Unchanged                     |
  | `bitcoin-qt`         | `bin/`       | 📦 Binary release     | Unchanged                     |
  | `bitcoin-tx`         | `bin/`       | 📦 Binary release     | Unchanged                     |
  | `bitcoin-util`       | `bin/`       | 📦 Binary release     | Unchanged                     |
  | `bitcoin-wallet`     | `bin/`       | 📦 Binary release     | Unchanged                     |
  | `bench_bitcoin`      | `libexec/`   | 🛠 Source build only  | Moved from `bin/`             |
  | `bitcoin-chainstate` | `libexec/`   | 🛠 Source build only  | Newly installed (was built)   |
  | `bitcoin-gui`        | `libexec/`   | 🛠 Source build only (until #31802) | Moved from `bin/`             |
  | `bitcoin-node`       | `libexec/`   | 🛠 Source build only (until #31802) | Moved from `bin/`             |
  | `test_bitcoin`       | `libexec/`    | 📦 Binary release     | Moved from `bin/`             |
  | `test_bitcoin-qt`    | `libexec/`   | 🛠 Source build only  | Moved from `bin/`             |

  </p>
  </details>

  ---

  This PR is part of the [process separation project](https://github.com/bitcoin/bitcoin/issues/28722).

ACKs for top commit:
  l0rinc:
    re-ACK f49840dd90
  Sjors:
    re-ACK f49840dd90
  achow101:
    ACK f49840dd90
  janb84:
    re ACK f49840dd90
  BrandonOdiwuor:
    Tested ACK f49840dd90
  hodlinator:
    re-ACK f49840dd90
  willcl-ark:
    utACK f49840dd90

Tree-SHA512: 858a2e1a53db11ee3c5c759bfdeea566f242b9ce5e8a898fa435222e41662b8184577c0dc2c4c058294b4de41d8cb3ba3e5d24c748c280efa4a3f84e3ec4344d

2025-08-07 14:53:26 +01:00

13 KiB

Raw Blame History

Bitcoin Core file system

Contents

Data directory location
Data directory layout
Multi-wallet environment
- SQLite database based wallets
GUI settings
Legacy subdirectories and files
- Berkeley DB database based wallets
Installed Files

Data directory location

The data directory is the default location where the Bitcoin Core files are stored.

The default data directory paths for supported platforms are:

Platform	Data directory path
Linux	`$HOME/.bitcoin/`
macOS	`$HOME/Library/Application Support/Bitcoin/`
Windows	`%LOCALAPPDATA%\Bitcoin\` ^[1]

A custom data directory path can be specified with the -datadir option.
All content of the data directory, except for bitcoin.conf file, is chain-specific. This means the actual data directory paths for non-mainnet cases differ:

Chain option	Data directory path
`-chain=main` (default)	path_to_datadir`/`
`-chain=test` or `-testnet`	path_to_datadir`/testnet3/`
`-chain=testnet4` or `-testnet4`	path_to_datadir`/testnet4/`
`-chain=signet` or `-signet`	path_to_datadir`/signet/`
`-chain=regtest` or `-regtest`	path_to_datadir`/regtest/`

Data directory layout

Subdirectory	File(s)	Description
`blocks/`		Blocks directory; can be specified by `-blocksdir` option (except for `blocks/index/`)
`blocks/index/`	LevelDB database	Block index; `-blocksdir` option does not affect this path
`blocks/`	`blkNNNNN.dat`^[2]	Actual Bitcoin blocks (dumped in network format, 128 MiB per file)
`blocks/`	`revNNNNN.dat`^[2]	Block undo data (custom format)
`blocks/`	`xor.dat`	Rolling XOR pattern for block and undo data files
`chainstate/`	LevelDB database	Blockchain state (a compact representation of all currently unspent transaction outputs (UTXOs) and metadata about the transactions they are from)
`indexes/txindex/`	LevelDB database	Transaction index; optional, used if `-txindex=1`
`indexes/blockfilter/basic/db/`	LevelDB database	Blockfilter index LevelDB database for the basic filtertype; optional, used if `-blockfilterindex=basic`
`indexes/blockfilter/basic/`	`fltrNNNNN.dat`^[2]	Blockfilter index filters for the basic filtertype; optional, used if `-blockfilterindex=basic`
`indexes/coinstats/db/`	LevelDB database	Coinstats index; optional, used if `-coinstatsindex=1`
`wallets/`		Contains wallets; can be specified by `-walletdir` option; if `wallets/` subdirectory does not exist, wallets reside in the data directory
`./`	`anchors.dat`	Anchor IP address database, created on shutdown and deleted at startup. Anchors are last known outgoing block-relay-only peers that are tried to re-connect to on startup
`./`	`banlist.json`	Stores the addresses/subnets of banned nodes.
`./`	`bitcoin.conf`	User-defined configuration settings for `bitcoind` or `bitcoin-qt`. File is not written to by the software and must be created manually. Path can be specified by `-conf` option
`./`	`bitcoind.pid`	Stores the process ID (PID) of `bitcoind` or `bitcoin-qt` while running; created at start and deleted on shutdown; can be specified by `-pid` option
`./`	`debug.log`	Contains debug information and general logging generated by `bitcoind` or `bitcoin-qt`; can be specified by `-debuglogfile` option
`./`	`fee_estimates.dat`	Stores statistics used to estimate minimum transaction fees required for confirmation
`./`	`guisettings.ini.bak`	Backup of former GUI settings after `-resetguisettings` option is used
`./`	`ip_asn.map`	IP addresses to Autonomous System Numbers (ASNs) mapping used for bucketing of the peers; path can be specified with the `-asmap` option
`./`	`mempool.dat`	Dump of the mempool's transactions
`./`	`onion_v3_private_key`	Cached Tor onion service private key for `-listenonion` option
`./`	`i2p_private_key`	Private key that corresponds to our I2P address. When `-i2psam=` is specified the contents of this file is used to identify ourselves for making outgoing connections to I2P peers and possibly accepting incoming ones. Automatically generated if it does not exist.
`./`	`peers.dat`	Peer IP address database (custom format)
`./`	`settings.json`	Read-write settings set through GUI or RPC interfaces, augmenting manual settings from bitcoin.conf. File is created automatically if read-write settings storage is not disabled with `-nosettings` option. Path can be specified with `-settings` option
`./`	`.cookie`	Session RPC authentication cookie; if used, created at start and deleted on shutdown; can be specified by `-rpccookiefile` option
`./`	`.lock`	Data directory lock file

Multi-wallet environment

Wallets are SQLite databases.

Each user-defined wallet named "wallet_name" resides in the wallets/wallet_name/ subdirectory.
The default (unnamed) wallet resides in wallets/ subdirectory; if the latter does not exist, the wallet resides in the data directory.
A wallet database path can be specified with the -wallet option.
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.
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.

SQLite database based wallets

Subdirectory	File	Description
`./`	`wallet.dat`	Personal wallet (a SQLite database) with keys and transactions
`./`	`wallet.dat-journal`	SQLite Rollback Journal file for `wallet.dat`. Usually created at start and deleted on shutdown. A user must keep it as safe as the `wallet.dat` file.

GUI settings

bitcoin-qt uses QSettings class; this implies platform-specific locations where application settings are stored.

Legacy subdirectories and files

These subdirectories and files are no longer used by Bitcoin Core:

Path	Description	Repository notes
`banlist.dat`	Stores the addresses/subnets of banned nodes; superseded by `banlist.json` in 22.0 and completely ignored in 23.0	PR #20966, PR #22570
`blktree/`	Blockchain index; replaced by `blocks/index/` in 0.8.0	PR #2231, `8fdc94cc`
`coins/`	Unspent transaction output database; replaced by `chainstate/` in 0.8.0	PR #2231, `8fdc94cc`
`blkindex.dat`	Blockchain index BDB database; replaced by {`chainstate/`, `blocks/index/`, `blocks/revNNNNN.dat`^[2]} in 0.8.0	PR #1677
`blk000?.dat`	Block data (custom format, 2 GiB per file); replaced by `blocks/blkNNNNN.dat`^[2] in 0.8.0	PR #1677
`addr.dat`	Peer IP address BDB database; replaced by `peers.dat` in 0.7.0	PR #1198, `928d3a01`
`onion_private_key`	Cached Tor onion service private key for `-listenonion` option. Was used for Tor v2 services; replaced by `onion_v3_private_key` in 0.21.0	PR #19954

Berkeley DB database based wallets

Subdirectory	File(s)	Description
`database/`	BDB logging files	Part of BDB environment; created at start and deleted on shutdown; a user must keep it as safe as personal wallet `wallet.dat`
`./`	`db.log`	BDB error file
`./`	`wallet.dat`	Personal wallet (a BDB database) with keys and transactions
`./`	`.walletlock`	BDB wallet lock file

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 or readme.txt	Project information and instructions
bitcoin.conf	Generated 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).

13 KiB Raw Blame History

Bitcoin Core file system

Data directory location

Data directory layout

Multi-wallet environment

SQLite database based wallets

GUI settings

Legacy subdirectories and files

Berkeley DB database based wallets

Notes

Installed Files

Notes

13 KiB

Raw Blame History