Commit 27540be5 authored by Paul Eggert's avatar Paul Eggert

Improve UBSan discussion in etc/DEBUG

* etc/DEBUG: Improve -gdwarf-N documentation.
Go into more detail about UndefinedBehaviorSanitizer.
parent b8e7be28
Pipeline #1414 passed with stage
in 49 minutes and 20 seconds
...@@ -181,10 +181,10 @@ Good luck! ...@@ -181,10 +181,10 @@ Good luck!
** When you are trying to analyze failed assertions or backtraces, it ** When you are trying to analyze failed assertions or backtraces, it
is essential to compile Emacs with flags suitable for debugging. is essential to compile Emacs with flags suitable for debugging.
With GCC 4.8 or later, you can invoke 'make' with CFLAGS="-O0 -g3". Although CFLAGS="-O0 -g3" often suffices with modern compilers,
With older GCC, you can use CFLAGS="-O0 -g3 -gdwarf-4", replacing "4" you may benefit further by using CFLAGS="-O0 -g3 -gdwarf-4", replacing
by the highest version of DWARF that your compiler supports; "4" by the highest version of DWARF that your compiler supports;
with non-GCC compilers, "-O0 -g3" may be the best you can do. this is especially important for GCC versions older than 4.8.
With GCC and higher optimization levels such as -O2, the With GCC and higher optimization levels such as -O2, the
-fno-omit-frame-pointer and -fno-crossjumping options are often -fno-omit-frame-pointer and -fno-crossjumping options are often
essential. The latter prevents GCC from using the same abort call for essential. The latter prevents GCC from using the same abort call for
...@@ -917,13 +917,26 @@ setting the new-console option before running Emacs under GDB: ...@@ -917,13 +917,26 @@ setting the new-console option before running Emacs under GDB:
** Running Emacs with undefined-behavior sanitization ** Running Emacs with undefined-behavior sanitization
Building Emacs with undefined-behavior sanitization can help debug Building Emacs with undefined-behavior sanitization can help find
integer overflow and other undefined behavior in C code. To use several kinds of low-level problems in C code, including:
UndefinedBehaviorSanitizer with GCC and similar compilers, append
'-fsanitize=undefined' to CFLAGS, either when running 'configure' or
running 'make'. For example:
./configure CFLAGS='-O0 -g3 -fsanitize=undefined' * Out-of-bounds access of many (but not all) arrays.
* Signed integer overflow, e.g., (INT_MAX + 1).
* Integer shifts by a negative or wider-than-word value.
* Misaligned pointers and pointer overflow.
* Loading a bool or enum value that is out of range for its type.
* Passing NULL to or returning NULL from a function requiring nonnull.
* Passing a size larger than the corresponding array to memcmp etc.
* Passing invalid values to some builtin functions, e.g., __builtin_clz (0).
* Reaching __builtin_unreachable calls (in Emacs, 'eassume' failure).
To use UndefinedBehaviorSanitizer with GCC and similar compilers,
append '-fsanitize=undefined' to CFLAGS, either when running
'configure' or running 'make'. When supported, you can also specify
'bound-strict' and 'float-cast-overflow'. For example:
./configure \
CFLAGS='-O0 -g3 -fsanitize=undefined,bounds-strict,float-cast-overflow'
You may need to append '-static-libubsan' to CFLAGS if your version of You may need to append '-static-libubsan' to CFLAGS if your version of
GCC is installed in an unusual location. GCC is installed in an unusual location.
...@@ -940,9 +953,10 @@ program. ...@@ -940,9 +953,10 @@ program.
** Running Emacs with address sanitization ** Running Emacs with address sanitization
Building Emacs with address sanitization can help debug memory-use Building Emacs with address sanitization can help debug memory-use
problems. To use AddressSanitizer with GCC and similar compilers, problems, such as freeing the same object twice. To use
append '-fsanitize=address' to CFLAGS, either when running 'configure' AddressSanitizer with GCC and similar compilers, append
or running 'make'. Configure, build and run Emacs with '-fsanitize=address' to CFLAGS, either when running 'configure' or
running 'make'. Configure, build and run Emacs with
ASAN_OPTIONS='detect_leaks=0' in the environment to suppress ASAN_OPTIONS='detect_leaks=0' in the environment to suppress
diagnostics of minor memory leaks in Emacs. For example: diagnostics of minor memory leaks in Emacs. For example:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment