260 lines
8.0 KiB
Plaintext
260 lines
8.0 KiB
Plaintext
=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.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 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 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
|