X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=hints%2FREADME.hints;h=f55ded9800520cb26a646e57cb142fbc2f4675a3;hb=c372d929e82a56503fe8b3b070d05d130fc3d0d9;hp=015e1c12c235aea1a7b8af16545033ab2ae7eb56;hpb=b691c02f8c79b7bac4a606da95849c0c7bcae239;p=p5sagit%2Fp5-mst-13.2.git diff --git a/hints/README.hints b/hints/README.hints index 015e1c1..f55ded9 100644 --- a/hints/README.hints +++ b/hints/README.hints @@ -9,9 +9,11 @@ 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. +Please send any problems or suggested changes to perlbug@perl.org. -Hint file naming convention: Each hint file name should have only +=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 '.' @@ -51,6 +53,120 @@ 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 @@ -157,16 +273,10 @@ aix 4.1.1. =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: +the particular compiler used. For example, consider the following: case "$cc" in *gcc*) ccflags="$ccflags -posix" @@ -187,7 +297,18 @@ 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. +example. Some callbacks exist for other variables than cc, such as for +uselongdouble. At the present time, these callbacks are only called if the +variable in question is defined; however, this may change, so the scheme in +hints/solaris_2.sh of checking to see if uselongdouble is defined is a good +idea. + +=item Call status + +Call-backs are only called always, even if the value for the call-back is +uset: UU/usethreads.cbu is called when Configure is about to deal with +threads. All created call-backs from hints should thus check the status +of the variable, and act upon it. =item Future status @@ -204,4 +325,5 @@ say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line. Have the appropriate amount of fun :-) - Andy Dougherty doughera@lafcol.lafayette.edu + Andy Dougherty doughera@lafayette.edu (author) + Paul Green paul.green@stratus.com (compiler bugs)