[gcc r13-4569] docs: Suggest options to improve ASAN stack traces

[gcc r13-4569] docs: Suggest options to improve ASAN stack traces

[Marek Polacek]

https://gcc.gnu.org/g:6a07798c6bc602c355a546057187169f79872696

commit r13-4569-g6a07798c6bc602c355a546057187169f79872696
Author: Marek Polacek <polacek@redhat.com>
Date:   Wed Dec 7 15:27:27 2022 -0500

    docs: Suggest options to improve ASAN stack traces
    
    I got a complaint that while Clang docs suggest options that improve
    the quality of the backtraces ASAN prints (cf.
    <https://clang.llvm.org/docs/AddressSanitizer.html#usage>), our docs
    don't say anything to that effect.  This patch amends that with a new
    paragraph.  (It deliberately doesn't mention -fno-omit-frame-pointer.)
    
    gcc/ChangeLog:
    
            * doc/invoke.texi (-fsanitize=address): Suggest options to improve
            stack traces.

Diff:
---
 gcc/doc/invoke.texi | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 726392409b6..3f2512ce16a 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -16510,6 +16510,16 @@ The option cannot be combined with @option{-fsanitize=thread} or
 @option{-fsanitize=hwaddress}.  Note that the only target
 @option{-fsanitize=hwaddress} is currently supported on is AArch64.
 
+To get more accurate stack traces, it is possible to use options such as
+@option{-O0}, @option{-O1}, or @option{-Og} (which, for instance, prevent
+most function inlining), @option{-fno-optimize-sibling-calls} (which prevents
+optimizing sibling and tail recursive calls; this option is implicit for
+@option{-O0}, @option{-O1}, or @option{-Og}), or @option{-fno-ipa-icf} (which
+disables Identical Code Folding for functions).  Since multiple runs of the
+program may yield backtraces with different addresses due to ASLR (Address
+Space Layout Randomization), it may be desirable to turn ASLR off.  On Linux,
+this can be achieved with @samp{setarch `uname -m` -R ./prog}.
+
 @item -fsanitize=kernel-address
 @opindex fsanitize=kernel-address
 Enable AddressSanitizer for Linux kernel.