Skip to content

Commit 9631f46

Browse files
committed
[doc] add sanitizers documentation in developer-notes.md
Coming straight from btc@6feb46c3721605f6ae54d7e635a06f82cd7c1449
1 parent 70a0ace commit 9631f46

File tree

1 file changed

+42
-0
lines changed

1 file changed

+42
-0
lines changed

doc/developer-notes.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,48 @@ make cov
261261
# A coverage report will now be accessible at `./test_pivx.coverage/index.html`.
262262
```
263263

264+
**Sanitizers**
265+
Bitcoin can be compiled with various "sanitizers" enabled, which add
266+
instrumentation for issues regarding things like memory safety, thread race
267+
conditions, or undefined behavior. This is controlled with the
268+
`--with-sanitizers` configure flag, which should be a comma separated list of
269+
sanitizers to enable. The sanitizer list should correspond to supported
270+
`-fsanitize=` options in your compiler. These sanitizers have runtime overhead,
271+
so they are most useful when testing changes or producing debugging builds.
272+
Some examples:
273+
```bash
274+
# Enable both the address sanitizer and the undefined behavior sanitizer
275+
./configure --with-sanitizers=address,undefined
276+
# Enable the thread sanitizer
277+
./configure --with-sanitizers=thread
278+
```
279+
If you are compiling with GCC you will typically need to install corresponding
280+
"san" libraries to actually compile with these flags, e.g. libasan for the
281+
address sanitizer, libtsan for the thread sanitizer, and libubsan for the
282+
undefined sanitizer. If you are missing required libraries, the configure script
283+
will fail with a linker error when testing the sanitizer flags.
284+
The test suite should pass cleanly with the `thread` and `undefined` sanitizers,
285+
but there are a number of known problems when using the `address` sanitizer. The
286+
address sanitizer is known to fail in
287+
[sha256_sse4::Transform](/src/crypto/sha256_sse4.cpp) which makes it unusable
288+
unless you also use `--disable-asm` when running configure. We would like to fix
289+
sanitizer issues, so please send pull requests if you can fix any errors found
290+
by the address sanitizer (or any other sanitizer).
291+
Not all sanitizer options can be enabled at the same time, e.g. trying to build
292+
with `--with-sanitizers=address,thread` will fail in the configure script as
293+
these sanitizers are mutually incompatible. Refer to your compiler manual to
294+
learn more about these options and which sanitizers are supported by your
295+
compiler.
296+
Additional resources:
297+
* [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html)
298+
* [LeakSanitizer](https://clang.llvm.org/docs/LeakSanitizer.html)
299+
* [MemorySanitizer](https://clang.llvm.org/docs/MemorySanitizer.html)
300+
* [ThreadSanitizer](https://clang.llvm.org/docs/ThreadSanitizer.html)
301+
* [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html)
302+
* [GCC Instrumentation Options](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html)
303+
* [Google Sanitizers Wiki](https://github.com/google/sanitizers/wiki)
304+
* [Issue #12691: Enable -fsanitize flags in Travis](https://github.com/bitcoin/bitcoin/issues/12691)
305+
264306
Locking/mutex usage notes
265307
-------------------------
266308

0 commit comments

Comments
 (0)