perlhacktips.pod - update ASan section

Addresses #16910 plus other minor updates.

1 files changed, 22 insertions, 11 deletions

diff --git a/pod/perlhacktips.pod b/pod/perlhacktips.pod
index f648977855..99caf25311 100644
--- a/pod/perlhacktips.pod
+++ b/pod/perlhacktips.pod
@@ -1269,19 +1269,24 @@ To get valgrind and for more information see
 
 =head2 AddressSanitizer
 
-AddressSanitizer is a clang and gcc extension, included in clang since
-v3.1 and gcc since v4.8.  It checks illegal heap pointers, global
-pointers, stack pointers and use after free errors, and is fast enough
-that you can easily compile your debugging or optimized perl with it.
-It does not check memory leaks though.  AddressSanitizer is available
-for Linux, Mac OS X and soon on Windows.
+AddressSanitizer ("ASan") consists of a compiler instrumentation module
+and a run-time C<malloc> library. AddressSanitizer is available for
+Linux, Mac OS X and Windows. Specifically, it has been included in clang
+since v3.1, gcc since v4.8, and Visual Studio 2019 since v16.1. It checks
+for unsafe memory usage, such as use after free and buffer overflow
+conditions, and is fast enough that you can easily compile your
+debugging or optimized perl with it. Modern versions of ASan check for
+memory leaks by default on most platforms, otherwise (e.g. x86_64 OS X)
+this feature can be enabled via C<ASAN_OPTIONS=detect_leaks=1>.
+
 
 To build perl with AddressSanitizer, your Configure invocation should
 look like:
 
     sh Configure -des -Dcc=clang \
-       -Accflags=-faddress-sanitizer -Aldflags=-faddress-sanitizer \
-       -Alddlflags=-shared\ -faddress-sanitizer
+       -Accflags=-fsanitize=address -Aldflags=-fsanitize=address \
+       -Alddlflags=-shared\ -fsanitize=address \
+       -fsanitize-blacklist=`pwd`/asan_ignore
 
 where these arguments mean:
 
@@ -1292,21 +1297,27 @@ where these arguments mean:
 This should be replaced by the full path to your clang executable if it
 is not in your path.
 
-=item * -Accflags=-faddress-sanitizer
+=item * -Accflags=-fsanitize=address
 
 Compile perl and extensions sources with AddressSanitizer.
 
-=item * -Aldflags=-faddress-sanitizer
+=item * -Aldflags=-fsanitize=address
 
 Link the perl executable with AddressSanitizer.
 
-=item * -Alddlflags=-shared\ -faddress-sanitizer
+=item * -Alddlflags=-shared\ -fsanitize=address
 
 Link dynamic extensions with AddressSanitizer.  You must manually
 specify C<-shared> because using C<-Alddlflags=-shared> will prevent
 Configure from setting a default value for C<lddlflags>, which usually
 contains C<-shared> (at least on Linux).
 
+=item * -fsanitize-blacklist=`pwd`/asan_ignore
+
+AddressSanitizer will ignore functions listed in the C<asan_ignore>
+file. (This file should contain a short explanation of why each of
+the functions is listed.)
+
 =back
 
 See also