This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlhacktips.pod - update ASan section
authorRichard Leach <richardleach@users.noreply.github.com>
Tue, 2 Jun 2020 20:33:47 +0000 (21:33 +0100)
committerKarl Williamson <khw@cpan.org>
Tue, 2 Jun 2020 22:00:58 +0000 (16:00 -0600)
Addresses #16910 plus other minor updates.

pod/perlhacktips.pod

index f648977..99caf25 100644 (file)
@@ -1269,19 +1269,24 @@ To get valgrind and for more information see
 
 =head2 AddressSanitizer
 
 
 =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 \
 
 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:
 
 
 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.
 
 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.
 
 
 Compile perl and extensions sources with AddressSanitizer.
 
-=item * -Aldflags=-faddress-sanitizer
+=item * -Aldflags=-fsanitize=address
 
 Link the perl executable with AddressSanitizer.
 
 
 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).
 
 
 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
 =back
 
 See also