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

=back

Have the appropriate amount of fun :-)

    Andy Dougherty		doughera@lafayette.edu