diff options
Diffstat (limited to 'doc/developer-notes.md')
| -rw-r--r-- | doc/developer-notes.md | 92 |
1 files changed, 52 insertions, 40 deletions
diff --git a/doc/developer-notes.md b/doc/developer-notes.md index d9d5b392c5..952dbc77a0 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -214,14 +214,14 @@ int main() To run clang-tidy on Ubuntu/Debian, install the dependencies: ```sh -apt install clang-tidy bear clang +apt install clang-tidy clang ``` -Then, pass clang as compiler to configure, and use bear to produce the `compile_commands.json`: +Configure with clang as the compiler: ```sh -./autogen.sh && ./configure CC=clang CXX=clang++ -make clean && bear --config src/.bear-tidy-config -- make -j $(nproc) +cmake -B build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_EXPORT_COMPILE_COMMANDS=ON +cmake --build build -j $(nproc) ``` The output is denoised of errors from external dependencies. @@ -229,13 +229,13 @@ The output is denoised of errors from external dependencies. To run clang-tidy on all source files: ```sh -( cd ./src/ && run-clang-tidy -j $(nproc) ) +( cd ./src/ && run-clang-tidy -p ../build -j $(nproc) ) ``` To run clang-tidy on the changed source lines: ```sh -git diff | ( cd ./src/ && clang-tidy-diff -p2 -j $(nproc) ) +git diff | ( cd ./src/ && clang-tidy-diff -p2 -path ../build -j $(nproc) ) ``` Coding Style (Python) @@ -338,11 +338,12 @@ Recommendations: ### Generating Documentation -The documentation can be generated with `make docs` and cleaned up with `make -clean-docs`. The resulting files are located in `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 running `make docs`, you'll need to install these dependencies: +Before building the `docs` target, you'll need to install these dependencies: Linux: `sudo apt install doxygen graphviz` @@ -353,8 +354,14 @@ Development tips and tricks ### Compiling for debugging -Run configure with `--enable-debug` to add additional compiler flags that -produce better debugging builds. +When using the default build configuration by running `cmake -B build`, the +`-DCMAKE_BUILD_TYPE` is set to `RelWithDebInfo`. This option adds debug symbols +but also performs some compiler optimizations that may make debugging trickier +as the code may not correspond directly to the source. + +If you need to build exclusively for debugging, set the `-DCMAKE_BUILD_TYPE` +to `Debug` (i.e. `-DCMAKE_BUILD_TYPE=Debug`). You can always check the cmake +build options of an existing build with `ccmake build`. ### Show sources in debugging @@ -411,8 +418,8 @@ see [test/functional/](/test/functional) for tests that run in `-regtest` mode. ### DEBUG_LOCKORDER Bitcoin Core is a multi-threaded application, and deadlocks or other -multi-threading bugs can be very difficult to track down. The `--enable-debug` -configure option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts +multi-threading bugs can be very difficult to track down. The `-DCMAKE_BUILD_TYPE=Debug` +build option adds `-DDEBUG_LOCKORDER` to the compiler flags. This inserts run-time checks to keep track of which locks are held and adds warnings to the `debug.log` file if inconsistencies are detected. @@ -422,9 +429,8 @@ Defining `DEBUG_LOCKCONTENTION` adds a "lock" logging category to the logging RPC that, when enabled, logs the location and duration of each lock contention to the `debug.log` file. -The `--enable-debug` configure option adds `-DDEBUG_LOCKCONTENTION` to the -compiler flags. You may also enable it manually for a non-debug build by running -configure with `-DDEBUG_LOCKCONTENTION` added to your CPPFLAGS, +The `-DCMAKE_BUILD_TYPE=Debug` build option adds `-DDEBUG_LOCKCONTENTION` to the +compiler flags. You may also enable it manually by building with `-DDEBUG_LOCKCONTENTION` added to your CPPFLAGS, i.e. `CPPFLAGS="-DDEBUG_LOCKCONTENTION"`, then build and run bitcoind. You can then use the `-debug=lock` configuration option at bitcoind startup or @@ -467,34 +473,43 @@ 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 -LCOV can be used to generate a test coverage report based upon `make check` +LCOV can be used to generate a test coverage report based upon `ctest` execution. LCOV must be installed on your system (e.g. the `lcov` package on Debian/Ubuntu). To enable LCOV report generation during test runs: ```shell -./configure --enable-lcov -make -make cov +cmake -B build -DCMAKE_BUILD_TYPE=Coverage +cmake --build build +cmake -P build/Coverage.cmake -# A coverage report will now be accessible at `./test_bitcoin.coverage/index.html`, -# which covers unit tests, and `./total.coverage/index.html`, which covers +# A coverage report will now be accessible at `./build/test_bitcoin.coverage/index.html`, +# which covers unit tests, and `./build/total.coverage/index.html`, which covers # unit and functional tests. ``` -Additional LCOV options can be specified using `LCOV_OPTS`, but may be dependant +Additional LCOV options can be specified using `LCOV_OPTS`, but may be dependent on the version of LCOV. For example, when using LCOV `2.x`, branch coverage can be -enabled by setting `LCOV_OPTS="--rc branch_coverage=1"`, when configuring. +enabled by setting `LCOV_OPTS="--rc branch_coverage=1"`: + +``` +cmake -DLCOV_OPTS="--rc branch_coverage=1" -P build/Coverage.cmake +``` + +To enable test parallelism: +``` +cmake -DJOBS=$(nproc) -P build/Coverage.cmake +``` ### Performance profiling with perf @@ -545,7 +560,7 @@ See the functional test documentation for how to invoke perf within tests. Bitcoin Core can be compiled with various "sanitizers" enabled, which add instrumentation for issues regarding things like memory safety, thread race conditions, or undefined behavior. This is controlled with the -`--with-sanitizers` configure flag, which should be a comma separated list of +`-DSANITIZERS` cmake build flag, which should be a comma separated list of sanitizers to enable. The sanitizer list should correspond to supported `-fsanitize=` options in your compiler. These sanitizers have runtime overhead, so they are most useful when testing changes or producing debugging builds. @@ -554,16 +569,16 @@ Some examples: ```bash # Enable both the address sanitizer and the undefined behavior sanitizer -./configure --with-sanitizers=address,undefined +cmake -B build -DSANITIZERS=address,undefined # Enable the thread sanitizer -./configure --with-sanitizers=thread +cmake -B build -DSANITIZERS=thread ``` If you are compiling with GCC you will typically need to install corresponding "san" libraries to actually compile with these flags, e.g. libasan for the address sanitizer, libtsan for the thread sanitizer, and libubsan for the -undefined sanitizer. If you are missing required libraries, the configure script +undefined sanitizer. If you are missing required libraries, the build will fail with a linker error when testing the sanitizer flags. The test suite should pass cleanly with the `thread` and `undefined` sanitizers. You @@ -579,7 +594,7 @@ See the CI config for more examples, and upstream documentation for more informa about any additional options. Not all sanitizer options can be enabled at the same time, e.g. trying to build -with `--with-sanitizers=address,thread` will fail in the configure script as +with `-DSANITIZERS=address,thread` will fail in the build as these sanitizers are mutually incompatible. Refer to your compiler manual to learn more about these options and which sanitizers are supported by your compiler. @@ -593,7 +608,6 @@ Additional resources: * [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) * [GCC Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html) * [Google Sanitizers Wiki](https://github.com/google/sanitizers/wiki) - * [Issue #12691: Enable -fsanitize flags in Travis](https://github.com/bitcoin/bitcoin/issues/12691) Locking/mutex usage notes ------------------------- @@ -604,7 +618,7 @@ The code is multi-threaded and uses mutexes and the Deadlocks due to inconsistent lock ordering (thread 1 locks `cs_main` and then `cs_wallet`, while thread 2 locks them in the opposite order: result, deadlock as each waits for the other to release its lock) are a problem. Compile with -`-DDEBUG_LOCKORDER` (or use `--enable-debug`) to get lock order inconsistencies +`-DDEBUG_LOCKORDER` (or use `-DCMAKE_BUILD_TYPE=Debug`) to get lock order inconsistencies reported in the `debug.log` file. Re-architecting the core code so there are better-defined interfaces @@ -732,8 +746,6 @@ logging messages. They should be used as follows: useful for debugging and can reasonably be enabled on a production system (that has sufficient free storage space). They will be logged if the program is started with `-debug=category` or `-debug=1`. - Note that `LogPrint(BCLog::CATEGORY, fmt, params...)` is a deprecated - alias for `LogDebug`. - `LogInfo(fmt, params...)` should only be used rarely, e.g. for startup messages or for infrequent and important events such as a new block tip @@ -1049,8 +1061,8 @@ bool Chainstate::PreciousBlock(BlockValidationState& state, CBlockIndex* pindex) ``` - Build and run tests with `-DDEBUG_LOCKORDER` to verify that no potential - deadlocks are introduced. As of 0.12, this is defined by default when - configuring with `--enable-debug`. + deadlocks are introduced. This is defined by default when + building with `-DCMAKE_BUILD_TYPE=Debug`. - When using `LOCK`/`TRY_LOCK` be aware that the lock exists in the context of the current scope, so surround the statement and the code that needs the lock |