@@ -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+
264306Locking/mutex usage notes
265307-------------------------
266308
0 commit comments