vendor/perl5/5.005.02

1 files changed, 213 insertions, 0 deletions

diff --git a/contrib/perl5/hints/README.hints b/contrib/perl5/hints/README.hints
new file mode 100644
index 0000000000000..e36bd6d1dd9ee
--- /dev/null
+++ b/contrib/perl5/hints/README.hints
@@ -0,0 +1,213 @@
+=head1 NAME
+
+README.hints
+
+=head1 DESCRIPTION
+
+These files are used by Configure to set things which Configure either
+can't or doesn't guess properly.  Most of these hint files have been
+tested with at least some version of perl5, but some are still left
+over from perl4.
+
+Please send any problems or suggested changes to perlbug@perl.com.
+
+Hint file naming convention:   Each hint file name should have only
+one '.'.  (This is for portability to non-unix file systems.)  Names
+should also fit in <= 14 characters, for portability to older SVR3
+systems.  File names are of the form $osname_$osvers.sh, with all '.'
+changed to '_', and all characters (such as '/') that don't belong in
+Unix filenames omitted.
+
+For example, consider Sun OS 4.1.3.  Configure determines $osname=sunos
+(all names are converted to lower case) and $osvers=4.1.3.  Configure
+will search for an appropriate hint file in the following order:
+
+	sunos_4_1_3.sh
+	sunos_4_1.sh
+	sunos_4.sh
+	sunos.sh
+
+If you need to create a hint file, please try to use as general a name
+as possible and include minor version differences inside case or test
+statements.  For example, for IRIX 6.X, we have the following hints
+files:
+
+	irix_6_0.sh
+	irix_6_1.sh
+	irix_6.sh
+
+That is, 6.0 and 6.1 have their own special hints, but 6.2, 6.3, and
+up are all handled by the same irix_6.sh.  That way, we don't have to
+make a new hint file every time the IRIX O/S is upgraded.
+
+If you need to test for specific minor version differences in your
+hints file, be sure to include a default choice.  (See aix.sh for one
+example.) That way, if you write a hint file for foonix 3.2, it might
+still work without any changes when foonix 3.3 is released.
+
+Please also comment carefully on why the different hints are needed.
+That way, a future version of Configure may be able to automatically
+detect what is needed.
+
+A glossary of config.sh variables is in the file Porting/Glossary.
+
+=head1 Hint file tricks
+
+=head2 Printing critical messages
+
+[This is still experimental]
+
+If you have a *REALLY* important message that the user ought to see at
+the end of the Configure run, you can store it in the file
+'config.msg'.  At the end of the Configure run, Configure will display
+the contents of this file.  Currently, the only place this is used is
+in Configure itself to warn about the need to set LD_LIBRARY_PATH if
+you are building a shared libperl.so.
+
+To use this feature, just do something like the following
+
+	$cat <<EOM  | $tee -a ../config.msg >&4
+
+    This is a really important message.  Be sure to read it
+    before you type 'make'.
+    EOM
+
+This message will appear on the screen as the hint file is being
+processed and again at the end of Configure.
+
+Please use this sparingly.
+
+=head2 Propagating variables to config.sh
+
+Sometimes, you want an extra variable to appear in config.sh.  For
+example, if your system can't compile toke.c with the optimizer on,
+you can put
+
+    toke_cflags='optimize=""'
+
+at the beginning of a line in your hints file.  Configure will then
+extract that variable and place it in your config.sh file.  Later,
+while compiling toke.c, the cflags shell script will eval $toke_cflags
+and hence compile toke.c without optimization.
+
+Note that for this to work, the variable you want to propagate must
+appear in the first column of the hint file.  It is extracted by
+Configure with a simple sed script, so beware that surrounding case
+statements aren't any help.
+
+By contrast, if you don't want Configure to propagate your temporary
+variable, simply indent it by a leading tab in your hint file.
+
+For example, prior to 5.002, a bug in scope.c led to perl crashing
+when compiled with -O in AIX 4.1.1.  The following "obvious"
+workaround in hints/aix.sh wouldn't work as expected:
+
+    case "$osvers" in
+	4.1.1)
+    scope_cflags='optimize=""'
+	;;
+    esac
+
+because Configure doesn't parse the surrounding 'case' statement, it
+just blindly propagates any variable that starts in the first column.
+For this particular case, that's probably harmless anyway.
+
+Three possible fixes are:
+
+=over
+
+=item 1
+
+Create an aix_4_1_1.sh hint file that contains the scope_cflags
+line and then sources the regular aix hints file for the rest of
+the information.
+
+=item 2
+
+Do the following trick:
+
+    scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac'
+
+Now when $scope_cflags is eval'd by the cflags shell script, the
+case statement is executed.  Of course writing scripts to be eval'd is
+tricky, especially if there is complex quoting.  Or,
+
+=item 3
+
+Write directly to Configure's temporary file UU/config.sh.
+You can do this with
+
+    case "$osvers" in
+	4.1.1)
+	echo "scope_cflags='optimize=\"\"'" >> UU/config.sh
+	scope_cflags='optimize=""'
+	;;
+    esac
+
+Note you have to both write the definition to the temporary
+UU/config.sh file and set the variable to the appropriate value.
+
+This is sneaky, but it works.  Still, if you need anything this
+complex, perhaps you should create the separate hint file for
+aix 4.1.1.
+
+=back
+
+=head2 Call-backs
+
+=over 4
+
+=item Warning
+
+All of the following is experimental and subject to change.  But it
+probably won't change much. :-)
+
+=item Compiler-related flags
+
+The settings of some things, such as optimization flags, may depend on
+the particular compiler used.  For example, for ISC we have the
+following:
+
+    case "$cc" in
+    *gcc*)  ccflags="$ccflags -posix"
+	    ldflags="$ldflags -posix"
+	    ;;
+    *)      ccflags="$ccflags -Xp -D_POSIX_SOURCE"
+	    ldflags="$ldflags -Xp"
+	    ;;
+    esac
+
+However, the hints file is processed before the user is asked which
+compiler should be used.  Thus in order for these hints to be useful,
+the user must specify  sh Configure -Dcc=gcc on the command line, as
+advised by the INSTALL file.
+
+For versions of perl later than 5.004_61, this problem can
+be circumvented by the use of "call-back units".  That is, the hints
+file can tuck this information away into a file UU/cc.cbu.  Then,
+after Configure prompts the user for the C compiler, it will load in
+and run the UU/cc.cbu "call-back" unit.  See hints/solaris_2.sh for an
+example.
+
+=item Threading-related flags
+
+Similarly, after Configure prompts the user about whether or not to
+compile Perl with threads, it will look for a "call-back" unit
+usethreads.cbu.  See hints/linux.sh for an example.
+
+=item Future status
+
+I hope this "call-back" scheme is simple enough to use but powerful
+enough to deal with most situations.  Still, there are certainly cases
+where it's not enough.  For example, for aix we actually change
+compilers if we are using threads.
+
+I'd appreciate feedback on whether this is sufficiently general to be
+helpful, or whether we ought to simply continue to require folks to
+say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line.
+
+=back
+
+Have the appropriate amount of fun :-)
+
+    Andy Dougherty		doughera@lafcol.lafayette.edu