diff options
Diffstat (limited to 'contrib/perl5/hints/README.hints')
| -rw-r--r-- | contrib/perl5/hints/README.hints | 259 |
1 files changed, 0 insertions, 259 deletions
diff --git a/contrib/perl5/hints/README.hints b/contrib/perl5/hints/README.hints deleted file mode 100644 index 0666771..0000000 --- a/contrib/perl5/hints/README.hints +++ /dev/null @@ -1,259 +0,0 @@ -=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 |
