README.hints
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.
[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.
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:
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.
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,
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.
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.
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.
Have the appropriate amount of fun :-)
Andy Dougherty doughera@lafcol.lafayette.edu
If rather than formatting bugs, you encounter substantive content errors in these documents, such as mistakes in the explanations or code, please use the perlbug utility included with the Perl distribution.