+=head1 NAME
+
+README.hints - hint files used by Configure
+
+=head1 DESCRIPTION
+
These files are used by Configure to set things which Configure either
-can't or doesn't guess properly. Many of these hints files are from
-perl4. They may or may not work with perl5, but they are probably a
-good starting point.
-
-The following hints files have been tested with at least some version
-of perl5 and are probably reasonably close to being correct:
-
-aix.sh
-aux.sh
-bsdos.sh
-dec_osf.sh
-dgux.sh
-esix4.sh
-freebsd.sh
-hpux_9.sh
-irix_4.sh
-irix_5.sh
-irix_6.sh
-irix_6_2.sh
-isc.sh
-linux.sh
-machten_2.sh
-machten.sh
-ncr_tower.sh
-netbsd.sh
-next_3_2.sh
-sco_3.sh
-solaris_2.sh
-sunos_4_1.sh
-svr4.sh
-titanos.sh
-ultrix_4.sh
-unicos.sh
-utekv.sh
-
-The following hints files have not been tested with perl5:
-
-3b1.sh
-altos486.sh
-apollo.sh
-dnix.sh
-dynix.sh
-fps.sh
-genix.sh
-greenhills.sh
-i386.sh
-isc_2.sh
-mips.sh
-mpc.sh
-opus.sh
-sco_2_3_0.sh
-sco_2_3_1.sh
-sco_2_3_2.sh
-sco_2_3_3.sh
-sco_2_3_4.sh
-stellar.sh
-sunos_4_0.sh
-ti1500.sh
-unisysdynix.sh
-uts.sh
+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.org.
+
+=head1 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 Setting variables
+
+=head2 Optimizer
+
+If you want to set a variable, try to allow for Configure command-line
+overrides. For example, suppose you think the default optimizer
+setting to be -O2 for a particular platform. You should allow for
+command line overrides with something like
+
+ case "$optimize" in
+ '') optimize='-O2' ;;
+ esac
+
+or, if your system has a decent test(1) command,
+
+ test -z "$optimize" && optimize='-O2'
+
+This allows the user to select a different optimization level, e.g.
+-O6 or -g.
+
+=head2 Compiler and Linker flags
+
+If you want to set $ccflags or $ldflags, you should append to the existing
+value to allow Configure command-line settings, e.g. use
+
+ ccflags="$ccflags -DANOTHER_OPTION_I_NEED"
+
+so that the user can do something like
+
+ sh Configure -Dccflags='FIX_NEGATIVE_ZERO'
+
+and have the FIX_NEGATIVE_ZERO value preserved by the hints file.
+
+=head2 Libraries
+
+Configure will attempt to use the libraries listed in the variable
+$libswanted. If necessary, you should remove broken libraries from
+that list, or add additional libraries to that list. You should
+*not* simply set $libs -- that ignores the possibilities of local
+variations. For example, a setting of libs='-lgdbm -lm -lc' would
+fail if another user were to try to compile Perl on a system without
+GDBM but with Berkeley DB. See hints/dec_osf.sh and hints/solaris_2.sh
+for examples.
+
+=head2 Other
+
+In general, try to avoid hard-wiring something that Configure will
+figure out anyway. Also try to allow for Configure command-line
+overrides.
+
+=head1 Working around compiler bugs
+
+Occasionally, the root cause of a bug in perl turns out to be due to a bug
+in the compiler. Often, changing the compilation options (particularly the
+optimization level) can work around the bug. However, if you try to do
+this on the command line, you will be changing the compilation options for
+every component of perl, which can really hurt perl's performance.
+Instead, consider placing a test case into the hints directory to detect
+whether the compiler bug is present, and add logic to the hints file to
+take a specific and appropriate action
+
+=head2 Test-case conventions
+
+Test cases should be named "tNNN.c", where NNN is the next unused sequence
+number. The test case must be executable and should display a message
+containing the word "fails" when the compiler bug is present. It should
+display the word "works" with the compiler bug is not present. The test
+cases should be liberally commented and may be used by any hints file that
+needs them. See the first hints file (t001.c) for an example.
+
+=head2 Hint file processing
+
+The hint file must define a call-back unit (see below) that will compile,
+link, and run the test case, and then check for the presence of the string
+"fails" in the output. If it finds this string, it sets a special variable
+to specify the compilation option(s) for the specific perl source file that
+is affected by the bug.
+
+The special variable is named "XXX_cflags" where "XXX" is the name of
+the source file (without the ".c" suffix). The value of this variable
+is the string "optimize=YYY", where "YYY" is the compilation option
+necessary to work around the bug. The default value of this variable
+is "-O" (letter O), which specifies that the C compiler should compile
+the source program at the default optimization level. If you can
+avoid the compiler bug by disabling optimization, just reset the
+"optimize" variable to the null string. Sometimes a bug is present at
+a higher optimization level (say, O3) and not present at a lower
+optimization level (say, O1). In this case, you should specify the
+highest optimization level at which the bug is not present, so that
+you will retain as many of the benefits of code optimization as
+possible.
+
+For example, if the pp_pack.c source file must be compiled at
+optimization level 0 to work around a problem on a particular
+platform, one of the statements
+
+ pp_pack_cflags="optimize=-O0" or
+ pp_pack_cflags="optimize="
+
+will do the trick, since level 0 is equivalent to no optimization.
+(In case your printer or display device does not distinguish the
+letter O from the digit 0, that is the letter O followed by the digit
+0). You can specify any compiler option or set of options here, not
+just optimizer options. These options are appended to the list of all
+other compiler options, so you should be able to override almost any
+compiler option prepared by Configure. (Obviously this depends on how
+the compiler treats conflicting options, but most seem to go with the
+last value specified on the command line).
+
+You should also allow for the XXX_cflags variable to be overridden on the
+command line.
+
+See the vos.sh hints file for an extended example of these techniques.
+
+=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 Compiler-related flags
+
+The settings of some things, such as optimization flags, may depend on
+the particular compiler used. For example, consider 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. Some callbacks exist for other variables than cc, such as for
+uselongdouble. At the present time, these callbacks are only called if the
+variable in question is defined; however, this may change, so the scheme in
+hints/solaris_2.sh of checking to see if uselongdouble is defined is a good
+idea.
+
+=item Call status
+
+Call-backs are only called always, even if the value for the call-back is
+uset: UU/usethreads.cbu is called when Configure is about to deal with
+threads. All created call-backs from hints should thus check the status
+of the variable, and act upon it.
+
+=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@lafayette.edu (author)
+ Paul Green paul.green@stratus.com (compiler bugs)
https://perl5.git.perl.org / perl5.git / blobdiff