Inside Bitcoin
Opening the selected file…
Inside Bitcoin
Opening the selected file…
The code behind the network, with room to understand it.
Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.
251///252/// ... Description ...253///254bool function2(int arg1, const char *arg2)255```257Not picked up by Doxygen:258```c++259//260// ... Description ...261//262```264Also not picked up by Doxygen:265```c++266/*267* ... Description ...268*/269```271A full list of comment syntaxes picked up by Doxygen can be found at https://www.doxygen.nl/manual/docblocks.html,272but the above styles are favored.274Recommendations:276- Avoid duplicating type and input/output information in function277descriptions.279- Use backticks (``) to refer to `argument` names in function and280parameter descriptions.282- Backticks aren't required when referring to functions Doxygen already knows283about; it will build hyperlinks for these automatically. See284https://www.doxygen.nl/manual/autolink.html for complete info.286- Avoid linking to external documentation; links can break.288- Javadoc and all valid Doxygen comments are stripped from Doxygen source code289previews (`STRIP_CODE_COMMENTS = YES` in [Doxyfile.in](/doc/Doxyfile.in)). If290you want a comment to be preserved, it must instead use `//` or `/* */`.292### Generating Documentation294Assuming the build directory is named `build`,295the documentation can be generated with `cmake --build build --target docs`.296The resulting files will be located in `build/doc/doxygen/html`;297open `index.html` in that directory to view the homepage.299Before building the `docs` target, you'll need to install these dependencies:301Linux: `sudo apt install doxygen graphviz`303MacOS: `brew install doxygen graphviz`305## Coding Style (Python)307Refer to [/test/functional/README.md#style-guidelines](/test/functional/README.md#style-guidelines).309## Development tips and tricks311### Compiling for debugging313When using the default build configuration by running `cmake -B build`, the314`-DCMAKE_BUILD_TYPE` is set to `RelWithDebInfo`. This option adds debug symbols315but also performs some compiler optimizations that may make debugging trickier316as the code may not correspond directly to the source.318If you need to build exclusively for debugging, set the `-DCMAKE_BUILD_TYPE`319to `Debug` (i.e. `-DCMAKE_BUILD_TYPE=Debug`). You can always check the cmake320build options of an existing build with `ccmake build`.322### debug.log324If the code is behaving strangely, take a look in the `debug.log` file in the data directory;325error and debugging messages are written there.327Debug logging can be enabled on startup with the `-debug` and `-loglevel`328configuration options and toggled while bitcoind is running with the `logging`329RPC. For instance, launching bitcoind with `-debug` or `-debug=1` will turn on330all log categories and `-loglevel=trace` will turn on all log severity levels.332The Qt code routes `qDebug()` output to `debug.log` under category "qt": run with `-debug=qt`333to see it.335### Signet, testnet, and regtest modes337If you are testing multi-machine code that needs to operate across the internet,338you can run with either the `-signet` or the `-testnet4` config option to test339with "play bitcoins" on a test network.341If you are testing something that can run on one machine, run with the342`-regtest` option. In regression test mode, blocks can be created on demand;343see [test/functional/](/test/functional) for tests that run in `-regtest` mode.345### DEBUG_LOCKORDER347Bitcoin Core is a multi-threaded application, and deadlocks or other348multi-threading bugs can be very difficult to track down. The `-DCMAKE_BUILD_TYPE=Debug`349build option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts350run-time checks to keep track of which locks are held and adds warnings to the351`debug.log` file if inconsistencies are detected.353### DEBUG_LOCKCONTENTION355Defining `DEBUG_LOCKCONTENTION` adds a "lock" logging category to the logging356RPC that, when enabled, logs the location and duration of each lock contention357to the `debug.log` file.359The `-DCMAKE_BUILD_TYPE=Debug` build option adds `-DDEBUG_LOCKCONTENTION` to the360compiler flags. You may also enable it manually by building with `-DDEBUG_LOCKCONTENTION`361added to your CPPFLAGS, i.e. `-DAPPEND_CPPFLAGS="-DDEBUG_LOCKCONTENTION"`.363You can then use the `-debug=lock` configuration option at bitcoind startup or364`bitcoin-cli logging '["lock"]'` at runtime to turn on lock contention logging.365It can be toggled off again with `bitcoin-cli logging [] '["lock"]'`.367### Assertions and Checks369The util file `src/util/check.h` offers helpers to protect against coding and370internal logic bugs. They must never be used to validate user, network or any371other input.373* `assert` or `Assert` should be used to document assumptions when any374violation would mean that it is not safe to continue program execution. The375code is always compiled with assertions enabled.376- For example, a nullptr dereference or any other logic bug in validation377code means the program code is faulty and must terminate immediately.378* `CHECK_NONFATAL` should be used for recoverable internal logic bugs. On379failure, it will throw an exception, which can be caught to recover from the380error.381- For example, a nullptr dereference or any other logic bug in RPC code382means that the RPC code is faulty and cannot be executed. However, the383logic bug can be shown to the user and the program can continue to run.384* `Assume` should be used to document assumptions when program execution can385safely continue even if the assumption is violated. In debug builds it386behaves like `Assert`/`assert` to notify developers and testers about387nonfatal errors. In production it doesn't warn or log anything, though the388expression is always evaluated. However, if the compiler can prove that389an expression inside `Assume` is side-effect-free, it may optimize the call away,390skipping its evaluation in production. This enables a lower-cost way of391making explicit statements about the code, aiding review.392- For example it can be assumed that a variable is only initialized once,393but a failed assumption does not result in a fatal bug. A failed394assumption may or may not result in a slightly degraded user experience,395but it is safe to continue program execution.397### Compiling for test coverage399#### Using LCOV401LCOV can be used to generate a test coverage report based upon `ctest`402execution. LCOV must be installed on your system (e.g. the `lcov` package403on Debian/Ubuntu).405To enable LCOV report generation during test runs:407```shell408cmake -B build -DCMAKE_BUILD_TYPE=Coverage409cmake --build build410cmake -P build/Coverage.cmake412# A coverage report will now be accessible at `./build/test_bitcoin.coverage/index.html`,413# which covers unit tests, and `./build/total.coverage/index.html`, which covers414# unit and functional tests.415```417Additional LCOV options can be specified using `LCOV_OPTS`, but may be dependent418on the version of LCOV. For example, when using LCOV `2.x`, branch coverage can be419enabled by setting `LCOV_OPTS="--rc branch_coverage=1"`:421```422cmake -DLCOV_OPTS="--rc branch_coverage=1" -P build/Coverage.cmake423```425To enable test parallelism:426```427cmake -DJOBS=$(nproc) -P build/Coverage.cmake428```430#### Using LLVM/Clang toolchain432The following generates a coverage report for unit tests and functional tests.434Configure the build with the following flags:436> Consider building with a clean state using `rm -rf build`438```shell439# MacOS may instead require `-DCMAKE_C_COMPILER="$(brew --prefix llvm)/bin/clang" -DCMAKE_CXX_COMPILER="$(brew --prefix llvm)/bin/clang++"`440cmake -B build -DCMAKE_C_COMPILER="clang" \441-DCMAKE_CXX_COMPILER="clang++" \442-DAPPEND_CFLAGS="-fprofile-instr-generate -fcoverage-mapping" \443-DAPPEND_CXXFLAGS="-fprofile-instr-generate -fcoverage-mapping" \444-DAPPEND_LDFLAGS="-fprofile-instr-generate -fcoverage-mapping"445cmake --build build # Append "-j N" here for N parallel jobs.446```448Generating the raw profile data based on `ctest` and functional tests execution:450```shell451# Create directory for raw profile data452mkdir -p build/raw_profile_data454# Run tests to generate profiles455LLVM_PROFILE_FILE="$(pwd)/build/raw_profile_data/%m_%p.profraw" ctest --test-dir build # Append "-j N" here for N parallel jobs.456LLVM_PROFILE_FILE="$(pwd)/build/raw_profile_data/%m_%p.profraw" build/test/functional/test_runner.py # Append "-j N" here for N parallel jobs458# Merge all the raw profile data into a single file459find build/raw_profile_data -name "*.profraw" > build/raw_profile_data_files.txt460llvm-profdata merge -f build/raw_profile_data_files.txt -o build/coverage.profdata461```463> **Note:** The "counter mismatch" warning can be safely ignored, though it can be resolved by updating to Clang 19.464> The warning occurs due to version mismatches but doesn't affect the coverage report generation.466Generating the coverage report:468```shell469llvm-cov show \470--object=build/bin/test_bitcoin \471--object=build/bin/bitcoind \472-Xdemangler=llvm-cxxfilt \473--instr-profile=build/coverage.profdata \474--ignore-filename-regex="src/crc32c/|src/leveldb/|src/minisketch/|src/secp256k1/|src/test/" \475--format=html \476--show-instantiation-summary \477--show-line-counts-or-regions \478--show-expansions \479--output-dir=build/coverage_report \480--project-title="Bitcoin Core Coverage Report"481```483> **Note:** The "functions have mismatched data" warning can be safely ignored, the coverage report will still be generated correctly despite this warning.484> This warning occurs due to profdata mismatch created during the merge process for shared libraries.486The generated coverage report can be accessed at `build/coverage_report/index.html`.488#### Compiling for Fuzz Coverage490```shell491cmake -B build \492-DCMAKE_C_COMPILER="clang" \493-DCMAKE_CXX_COMPILER="clang++" \494-DCMAKE_C_FLAGS="-fprofile-instr-generate -fcoverage-mapping" \495-DCMAKE_CXX_FLAGS="-fprofile-instr-generate -fcoverage-mapping" \496-DBUILD_FOR_FUZZING=ON497cmake --build build # Append "-j N" here for N parallel jobs.498```500Running fuzz tests with one or more targets
Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.
Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.