X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=hints%2FREADME.hints;h=f55ded9800520cb26a646e57cb142fbc2f4675a3;hb=c372d929e82a56503fe8b3b070d05d130fc3d0d9;hp=5f23b29c2cbdb3d3ed4af2b1911c6caba574dc2e;hpb=146174a91a192983720a158796dc066226ad0e55;p=p5sagit%2Fp5-mst-13.2.git diff --git a/hints/README.hints b/hints/README.hints index 5f23b29..f55ded9 100644 --- a/hints/README.hints +++ b/hints/README.hints @@ -9,7 +9,7 @@ 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. =head1 Hint file naming convention. @@ -103,6 +103,70 @@ 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 @@ -209,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" @@ -239,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 @@ -256,4 +325,5 @@ say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line. Have the appropriate amount of fun :-) - Andy Dougherty doughera@lafayette.edu + Andy Dougherty doughera@lafayette.edu (author) + Paul Green paul.green@stratus.com (compiler bugs)