source: vendor/perl/5.8.8/hints/README.hints@ 3609

=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 [email protected].

=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,