notes about -DPERL_POLLUTE

p4raw-id: //depot/perl@2392

4 files changed, 76 insertions, 8 deletions

diff --git a/INSTALL b/INSTALL
index fe47668600..734483f3c3 100644
--- a/INSTALL
+++ b/INSTALL
@@ -26,6 +26,13 @@ For information on what's new in this release, see the
 pod/perldelta.pod file.  For more detailed information about specific
 changes, see the Changes file.
 
+IMPORTANT NOTE:  5.005_53 and later releases do not export unadorned
+global symbols anymore.  This means most CPAN modules probably won't
+build under this release without adding '-DPERL_POLLUTE' to ccflags
+in config.sh.  This is not the default because we want the modules
+to get fixed *before* the 5.006 release.  pod/perldelta.pod contains
+additional notes about this.
+
 =head1 DESCRIPTION
 
 This document is written in pod format as an easy way to indicate its
@@ -62,7 +69,8 @@ The standard extensions supplied with Perl will be handled automatically.
 
 In a related issue, old extensions may possibly be affected by the
 changes in the Perl language in the current release.  Please see
-pod/perldelta.pod for a description of what's changed.
+pod/perldelta.pod (and pod/perl500Xdelta.pod) for a description of
+what's changed.
 
 =head1 WARNING:  This version requires a compiler that supports ANSI C.
 
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 7cd721b549..d4fe20f299 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perldelta - what's new for perl5.006
+perldelta - what's new for perl5.006 (as of 5.005_54)
 
 =head1 DESCRIPTION
 
@@ -8,20 +8,64 @@ This document describes differences between the 5.005 release and this one.
 
 =head1 Incompatible Changes
 
+=head2 Perl Source Incompatibilities
+
+None known at this time.
+
+=head2 C Source Incompatibilities
+
+=over 4
+
+=item C<PERL_POLLUTE>
+
+Release 5.005 grandfathered old global symbol names by providing preprocessor
+macros for extension source compatibility.  As of release 5.006, these
+preprocessor definitions are not available by default.  You need to explicitly
+compile perl with C<-DPERL_POLLUTE> in order to get these definitions.
+
+=item C<PL_na> and C<dTHR> Issues
+
+The C<PL_na> global is now thread local, so a C<dTHR> declaration is needed
+in the scope in which it appears.  XSUBs should handle this automatically,
+but if you have used C<PL_na> in support functions, you either need to
+change the C<PL_na> to a local variable (which is recommended), or put in
+a C<dTHR>.
+
+=back
+
+=head2 Binary Incompatibilities
+
+This release is not binary compatible with the 5.005 release and its
+maintenance versions.
+
 =head1 Core Changes
 
+Todo.
+
 =head1 Supported Platforms
 
+Todo.
+
 =head1 Modules and Pragmata
 
+Todo.
+
 =head1 Utility Changes
 
+Todo.
+
 =head1 Documentation Changes
 
+Todo.
+
 =head1 New Diagnostics
 
+Todo.
+
 =head1 Obsolete Diagnostics
 
+Todo.
+
 =head1 BUGS
 
 If you find what you think is a bug, you might check the headers of
diff --git a/win32/Makefile b/win32/Makefile
index 231f6dc0c4..40df75acb4 100644
--- a/win32/Makefile
+++ b/win32/Makefile
@@ -124,6 +124,17 @@ CCINCDIR	= $(CCHOME)\include
 CCLIBDIR	= $(CCHOME)\lib
 
 #
+# additional compiler flags can be specified here.
+#
+# Adding -DPERL_POLLUTE enables support for old symbols, at the expense of
+# extreme pollution. You most probably want this if you're compiling modules
+# from CPAN, or other such serious uses of this experimental perl release.
+# We don't enable this by default because we want the modules to get fixed
+# instead of clinging to shortcuts like this one.
+#
+#BUILDOPT	= -DPERL_POLLUTE
+
+#
 # specify space-separated list of extra directories to look for libraries
 #
 EXTRALIBDIRS	=
@@ -165,9 +176,6 @@ USE_THREADS	= undef
 USE_MULTI	= undef
 !ENDIF
 
-#BUILDOPT	= -DPERL_GLOBAL_STRUCT
-# -DUSE_PERLIO -D__STDC__=1 -DUSE_SFIO -DI_SFIO -I\sfio97\include
-
 !IF "$(PROCESSOR_ARCHITECTURE)" == ""
 PROCESSOR_ARCHITECTURE	= x86
 !ENDIF
diff --git a/win32/makefile.mk b/win32/makefile.mk
index 8df1abb972..3eedf1edb2 100644
--- a/win32/makefile.mk
+++ b/win32/makefile.mk
@@ -136,6 +136,17 @@ CCINCDIR	*= $(CCHOME)\include
 CCLIBDIR	*= $(CCHOME)\lib
 
 #
+# additional compiler flags can be specified here.
+#
+# Adding -DPERL_POLLUTE enables support for old symbols, at the expense of
+# extreme pollution. You most probably want this if you're compiling modules
+# from CPAN, or other such serious uses of this experimental perl release.
+# We don't enable this by default because we want the modules to get fixed
+# instead of clinging to shortcuts like this one.
+#
+#BUILDOPT	*= -DPERL_POLLUTE
+
+#
 # specify space-separated list of extra directories to look for libraries
 #
 EXTRALIBDIRS	*=
@@ -176,9 +187,6 @@ PERL_MALLOC	*= undef
 USE_THREADS	*= undef
 USE_MULTI	*= undef
 
-#BUILDOPT	*= -DPERL_GLOBAL_STRUCT
-# -DUSE_PERLIO -D__STDC__=1 -DUSE_SFIO -DI_SFIO -I\sfio97\include
-
 .IMPORT .IGNORE : PROCESSOR_ARCHITECTURE
 
 PROCESSOR_ARCHITECTURE *= x86