diff options
Diffstat (limited to 'doc/developer-notes.md')
| -rw-r--r-- | doc/developer-notes.md | 43 |
1 files changed, 26 insertions, 17 deletions
diff --git a/doc/developer-notes.md b/doc/developer-notes.md index d41543ab1c..791c049a4a 100644 --- a/doc/developer-notes.md +++ b/doc/developer-notes.md @@ -111,8 +111,8 @@ code. - `static_assert` is preferred over `assert` where possible. Generally; compile-time checking is preferred over run-time checking. - Use a named cast or functional cast, not a C-Style cast. When casting between integer types, use functional casts such as `int(x)` or `int{x}` - instead of `(int) x`. When casting between more complex types, use static_cast. - Use reinterpret_cast and const_cast as appropriate. + instead of `(int) x`. When casting between more complex types, use `static_cast`. + Use `reinterpret_cast` and `const_cast` as appropriate. For function calls a namespace should be specified explicitly, unless such functions have been declared within it. Otherwise, [argument-dependent lookup](https://en.cppreference.com/w/cpp/language/adl), also known as ADL, could be @@ -218,10 +218,11 @@ Then, pass clang as compiler to configure, and use bear to produce the `compile_ ```sh ./autogen.sh && ./configure CC=clang CXX=clang++ -make clean && bear make -j $(nproc) # For bear 2.x -make clean && bear -- make -j $(nproc) # For bear 3.x +make clean && bear --config src/.bear-tidy-config -- make -j $(nproc) ``` +The output is denoised of errors from external dependencies. + To run clang-tidy on all source files: ```sh @@ -487,7 +488,9 @@ To enable LCOV report generation during test runs: make make cov -# A coverage report will now be accessible at `./test_bitcoin.coverage/index.html`. +# A coverage report will now be accessible at `./test_bitcoin.coverage/index.html`, +# which covers unit tests, and `./total.coverage/index.html`, which covers +# unit and functional tests. ``` ### Performance profiling with perf @@ -560,8 +563,19 @@ address sanitizer, libtsan for the thread sanitizer, and libubsan for the undefined sanitizer. If you are missing required libraries, the configure script will fail with a linker error when testing the sanitizer flags. -The test suite should pass cleanly with the `thread` and `undefined` sanitizers, -but there are a number of known problems when using the `address` sanitizer. The +The test suite should pass cleanly with the `thread` and `undefined` sanitizers. You +may need to use a suppressions file, see `test/sanitizer_suppressions`. They may be +used as follows: +```bash +export LSAN_OPTIONS="suppressions=$(pwd)/test/sanitizer_suppressions/lsan" +export TSAN_OPTIONS="suppressions=$(pwd)/test/sanitizer_suppressions/tsan:halt_on_error=1:second_deadlock_stack=1" +export UBSAN_OPTIONS="suppressions=$(pwd)/test/sanitizer_suppressions/ubsan:print_stacktrace=1:halt_on_error=1:report_error_type=1" +``` + +See the CI config for more examples, and upstream documentation for more information +about any additional options. + +There are a number of known problems when using the `address` sanitizer. The address sanitizer is known to fail in [sha256_sse4::Transform](/src/crypto/sha256_sse4.cpp) which makes it unusable unless you also use `--disable-asm` when running configure. We would like to fix @@ -609,8 +623,9 @@ Threads : Started from `main()` in `bitcoind.cpp`. Responsible for starting up and shutting down the application. -- [ThreadImport (`b-loadblk`)](https://doxygen.bitcoincore.org/namespacenode.html#ab4305679079866f0f420f7dbf278381d) - : Loads blocks from `blk*.dat` files or `-loadblock=<file>` on startup. +- [Init load (`b-initload`)](https://doxygen.bitcoincore.org/namespacenode.html#ab4305679079866f0f420f7dbf278381d) + : Performs various loading tasks that are part of init but shouldn't block the node from being started: external block import, + reindex, reindex-chainstate, main chain activation, spawn indexes background sync threads and mempool load. - [CCheckQueue::Loop (`b-scriptch.x`)](https://doxygen.bitcoincore.org/class_c_check_queue.html#a6e7fa51d3a25e7cb65446d4b50e6a987) : Parallel script validation threads for transactions in blocks. @@ -726,12 +741,6 @@ Common misconceptions are clarified in those sections: - Passing (non-)fundamental types in the [C++ Core Guideline](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-conventional). -- Assertions should not have side-effects. - - - *Rationale*: Even though the source code is set to refuse to compile - with assertions disabled, having side-effects in assertions is unexpected and - makes the code harder to understand. - - If you use the `.h`, you must link the `.cpp`. - *Rationale*: Include files define the interface for the code in implementation files. Including one but @@ -846,12 +855,12 @@ Strings and formatting buffer overflows, and surprises with `\0` characters. Also, some C string manipulations tend to act differently depending on platform, or even the user locale. -- Use `ParseInt32`, `ParseInt64`, `ParseUInt32`, `ParseUInt64`, `ParseDouble` from `utilstrencodings.h` for number parsing. +- Use `ToIntegral` from [`strencodings.h`](/src/util/strencodings.h) for number parsing. In legacy code you might also find `ParseInt*` family of functions, `ParseDouble` or `LocaleIndependentAtoi`. - *Rationale*: These functions do overflow checking and avoid pesky locale issues. - Avoid using locale dependent functions if possible. You can use the provided - [`lint-locale-dependence.sh`](/test/lint/lint-locale-dependence.sh) + [`lint-locale-dependence.py`](/test/lint/lint-locale-dependence.py) to check for accidental use of locale dependent functions. - *Rationale*: Unnecessary locale dependence can cause bugs that are very tricky to isolate and fix. |