diff options
Diffstat (limited to 'hints/README.hints')
| -rw-r--r-- | hints/README.hints | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/hints/README.hints b/hints/README.hints new file mode 100644 index 0000000000..1d0f35cccd --- /dev/null +++ b/hints/README.hints @@ -0,0 +1,318 @@ +=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 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, +link, and run the test case, and then check for the presence of the string +"fails" in the output. If it finds this string, it sets a special variable +to specify the compilation option(s) for the specific perl source file that +is affected by the bug. + +The special variable is named "XXX_cflags" where "XXX" is the name of +the source file (without the ".c" suffix). The value of this variable +is the string "optimize=YYY", where "YYY" is the compilation option +necessary to work around the bug. The default value of this variable +is "-O" (letter O), which specifies that the C compiler should compile +the source program at the default optimization level. If you can +avoid the compiler bug by disabling optimization, just reset the +"optimize" variable to the null string. Sometimes a bug is present at +a higher optimization level (say, O3) and not present at a lower +optimization level (say, O1). In this case, you should specify the +highest optimization level at which the bug is not present, so that +you will retain as many of the benefits of code optimization as +possible. + +For example, if the pp_pack.c source file must be compiled at +optimization level 0 to work around a problem on a particular +platform, one of the statements + + pp_pack_cflags="optimize=-O0" or + pp_pack_cflags="optimize=" + +will do the trick, since level 0 is equivalent to no optimization. +(In case your printer or display device does not distinguish the +letter O from the digit 0, that is the letter O followed by the digit +0). You can specify any compiler option or set of options here, not +just optimizer options. These options are appended to the list of all +other compiler options, so you should be able to override almost any +compiler option prepared by Configure. (Obviously this depends on how +the compiler treats conflicting options, but most seem to go with the +last value specified on the command line). + +You should also allow for the XXX_cflags variable to be overridden on the +command line. + +See the vos.sh hints file for an extended example of these techniques. + +=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 Compiler-related flags + +The settings of some things, such as optimization flags, may depend on +the particular compiler used. For example, consider 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 (author) + Paul Green paul.green@stratus.com (compiler bugs) |