hints/README.hints

   1 =head1 NAME
   2
   3 README.hints - hint files used by Configure
   4
   5 =head1 DESCRIPTION
   6
   7 These files are used by Configure to set things which Configure either
   8 can't or doesn't guess properly.  Most of these hint files have been
   9 tested with at least some version of perl5, but some are still left
  10 over from perl4.
  11
  12 Please send any problems or suggested changes to perlbug@perl.org.
  13
  14 =head1 Hint file naming convention.
  15
  16 Each hint file name should have only
  17 one '.'.  (This is for portability to non-unix file systems.)  Names
  18 should also fit in <= 14 characters, for portability to older SVR3
  19 systems.  File names are of the form $osname_$osvers.sh, with all '.'
  20 changed to '_', and all characters (such as '/') that don't belong in
  21 Unix filenames omitted.
  22
  23 For example, consider Sun OS 4.1.3.  Configure determines $osname=sunos
  24 (all names are converted to lower case) and $osvers=4.1.3.  Configure
  25 will search for an appropriate hint file in the following order:
  26
  27         sunos_4_1_3.sh
  28         sunos_4_1.sh
  29         sunos_4.sh
  30         sunos.sh
  31
  32 If you need to create a hint file, please try to use as general a name
  33 as possible and include minor version differences inside case or test
  34 statements.  For example, for IRIX 6.X, we have the following hints
  35 files:
  36
  37         irix_6_0.sh
  38         irix_6_1.sh
  39         irix_6.sh
  40
  41 That is, 6.0 and 6.1 have their own special hints, but 6.2, 6.3, and
  42 up are all handled by the same irix_6.sh.  That way, we don't have to
  43 make a new hint file every time the IRIX O/S is upgraded.
  44
  45 If you need to test for specific minor version differences in your
  46 hints file, be sure to include a default choice.  (See aix.sh for one
  47 example.) That way, if you write a hint file for foonix 3.2, it might
  48 still work without any changes when foonix 3.3 is released.
  49
  50 Please also comment carefully on why the different hints are needed.
  51 That way, a future version of Configure may be able to automatically
  52 detect what is needed.
  53
  54 A glossary of config.sh variables is in the file Porting/Glossary.
  55
  56 =head1 Setting variables
  57
  58 =head2 Optimizer
  59
  60 If you want to set a variable, try to allow for Configure command-line
  61 overrides.  For example, suppose you think the default optimizer
  62 setting to be -O2 for a particular platform.  You should allow for
  63 command line overrides with something like
  64
  65         case "$optimize" in
  66         '') optimize='-O2' ;;
  67         esac
  68
  69 or, if your system has a decent test(1) command,
  70
  71         test -z "$optimize" && optimize='-O2'
  72
  73 This allows the user to select a different optimization level, e.g.
  74 -O6 or -g.
  75
  76 =head2 Compiler and Linker flags
  77
  78 If you want to set $ccflags or $ldflags, you should append to the existing
  79 value to allow Configure command-line settings, e.g. use
  80
  81         ccflags="$ccflags -DANOTHER_OPTION_I_NEED"
  82
  83 so that the user can do something like
  84
  85         sh Configure -Dccflags='FIX_NEGATIVE_ZERO'
  86
  87 and have the FIX_NEGATIVE_ZERO value preserved by the hints file.
  88
  89 =head2 Libraries
  90
  91 Configure will attempt to use the libraries listed in the variable
  92 $libswanted.  If necessary, you should remove broken libraries from
  93 that list, or add additional libraries to that list.  You should
  94 *not* simply set $libs -- that ignores the possibilities of local
  95 variations.  For example, a setting of libs='-lgdbm -lm -lc' would
  96 fail if another user were to try to compile Perl on a system without
  97 GDBM but with Berkeley DB.  See hints/dec_osf.sh and hints/solaris_2.sh
  98 for examples.
  99
 100 =head2 Other
 101
 102 In general, try to avoid hard-wiring something that Configure will
 103 figure out anyway.  Also try to allow for Configure command-line
 104 overrides.
 105
 106 =head1 Working around compiler bugs
 107
 108 Occasionally, the root cause of a bug in perl turns out to be due to a bug
 109 in the compiler.  Often, changing the compilation options (particularly the
 110 optimization level) can work around the bug.  However, if you try to do
 111 this on the command line, you will be changing the compilation options for
 112 every component of perl, which can really hurt perl's performance.
 113 Instead, consider placing a test case into the hints directory to detect
 114 whether the compiler bug is present, and add logic to the hints file to
 115 take a specific and appropriate action
 116
 117 =head2 Test-case conventions
 118
 119 Test cases should be named "tNNN.c", where NNN is the next unused sequence
 120 number.  The test case must be executable and should display a message
 121 containing the word "fails" when the compiler bug is present.  It should
 122 display the word "works" with the compiler bug is not present.  The test
 123 cases should be liberally commented and may be used by any hints file that
 124 needs them.  See the first hints file (t001.c) for an example.
 125
 126 =head2 Hint file processing
 127
 128 The hint file must define a call-back unit (see below) that will compile,
 129 link, and run the test case, and then check for the presence of the string
 130 "fails" in the output.  If it finds this string, it sets a special variable
 131 to specify the compilation option(s) for the specific perl source file that
 132 is affected by the bug.
 133
 134 The special variable is named "XXX_cflags" where "XXX" is the name of
 135 the source file (without the ".c" suffix).  The value of this variable
 136 is the string "optimize=YYY", where "YYY" is the compilation option
 137 necessary to work around the bug.  The default value of this variable
 138 is "-O" (letter O), which specifies that the C compiler should compile
 139 the source program at the default optimization level.  If you can
 140 avoid the compiler bug by disabling optimization, just reset the
 141 "optimize" variable to the null string.  Sometimes a bug is present at
 142 a higher optimization level (say, O3) and not present at a lower
 143 optimization level (say, O1).  In this case, you should specify the
 144 highest optimization level at which the bug is not present, so that
 145 you will retain as many of the benefits of code optimization as
 146 possible.
 147
 148 For example, if the pp_pack.c source file must be compiled at
 149 optimization level 0 to work around a problem on a particular
 150 platform, one of the statements
 151
 152         pp_pack_cflags="optimize=-O0"   or
 153         pp_pack_cflags="optimize="
 154
 155 will do the trick, since level 0 is equivalent to no optimization.
 156 (In case your printer or display device does not distinguish the
 157 letter O from the digit 0, that is the letter O followed by the digit
 158 0).  You can specify any compiler option or set of options here, not
 159 just optimizer options.  These options are appended to the list of all
 160 other compiler options, so you should be able to override almost any
 161 compiler option prepared by Configure.  (Obviously this depends on how
 162 the compiler treats conflicting options, but most seem to go with the
 163 last value specified on the command line).
 164
 165 You should also allow for the XXX_cflags variable to be overridden on the
 166 command line.
 167
 168 See the vos.sh hints file for an extended example of these techniques.
 169
 170 =head1 Hint file tricks
 171
 172 =head2 Printing critical messages
 173
 174 [This is still experimental]
 175
 176 If you have a *REALLY* important message that the user ought to see at
 177 the end of the Configure run, you can store it in the file
 178 'config.msg'.  At the end of the Configure run, Configure will display
 179 the contents of this file.  Currently, the only place this is used is
 180 in Configure itself to warn about the need to set LD_LIBRARY_PATH if
 181 you are building a shared libperl.so.
 182
 183 To use this feature, just do something like the following
 184
 185         $cat <<EOM  | $tee -a ../config.msg >&4
 186
 187     This is a really important message.  Be sure to read it
 188     before you type 'make'.
 189     EOM
 190
 191 This message will appear on the screen as the hint file is being
 192 processed and again at the end of Configure.
 193
 194 Please use this sparingly.
 195
 196 =head2 Propagating variables to config.sh
 197
 198 Sometimes, you want an extra variable to appear in config.sh.  For
 199 example, if your system can't compile toke.c with the optimizer on,
 200 you can put
 201
 202     toke_cflags='optimize=""'
 203
 204 at the beginning of a line in your hints file.  Configure will then
 205 extract that variable and place it in your config.sh file.  Later,
 206 while compiling toke.c, the cflags shell script will eval $toke_cflags
 207 and hence compile toke.c without optimization.
 208
 209 Note that for this to work, the variable you want to propagate must
 210 appear in the first column of the hint file.  It is extracted by
 211 Configure with a simple sed script, so beware that surrounding case
 212 statements aren't any help.
 213
 214 By contrast, if you don't want Configure to propagate your temporary
 215 variable, simply indent it by a leading tab in your hint file.
 216
 217 For example, prior to 5.002, a bug in scope.c led to perl crashing
 218 when compiled with -O in AIX 4.1.1.  The following "obvious"
 219 workaround in hints/aix.sh wouldn't work as expected:
 220
 221     case "$osvers" in
 222         4.1.1)
 223     scope_cflags='optimize=""'
 224         ;;
 225     esac
 226
 227 because Configure doesn't parse the surrounding 'case' statement, it
 228 just blindly propagates any variable that starts in the first column.
 229 For this particular case, that's probably harmless anyway.
 230
 231 Three possible fixes are:
 232
 233 =over
 234
 235 =item 1
 236
 237 Create an aix_4_1_1.sh hint file that contains the scope_cflags
 238 line and then sources the regular aix hints file for the rest of
 239 the information.
 240
 241 =item 2
 242
 243 Do the following trick:
 244
 245     scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac'
 246
 247 Now when $scope_cflags is eval'd by the cflags shell script, the
 248 case statement is executed.  Of course writing scripts to be eval'd is
 249 tricky, especially if there is complex quoting.  Or,
 250
 251 =item 3
 252
 253 Write directly to Configure's temporary file UU/config.sh.
 254 You can do this with
 255
 256     case "$osvers" in
 257         4.1.1)
 258         echo "scope_cflags='optimize=\"\"'" >> UU/config.sh
 259         scope_cflags='optimize=""'
 260         ;;
 261     esac
 262
 263 Note you have to both write the definition to the temporary
 264 UU/config.sh file and set the variable to the appropriate value.
 265
 266 This is sneaky, but it works.  Still, if you need anything this
 267 complex, perhaps you should create the separate hint file for
 268 aix 4.1.1.
 269
 270 =back
 271
 272 =head2 Call-backs
 273
 274 =over 4
 275
 276 =item Compiler-related flags
 277
 278 The settings of some things, such as optimization flags, may depend on
 279 the particular compiler used.  For example, consider the following:
 280
 281     case "$cc" in
 282     *gcc*)  ccflags="$ccflags -posix"
 283             ldflags="$ldflags -posix"
 284             ;;
 285     *)      ccflags="$ccflags -Xp -D_POSIX_SOURCE"
 286             ldflags="$ldflags -Xp"
 287             ;;
 288     esac
 289
 290 However, the hints file is processed before the user is asked which
 291 compiler should be used.  Thus in order for these hints to be useful,
 292 the user must specify  sh Configure -Dcc=gcc on the command line, as
 293 advised by the INSTALL file.
 294
 295 For versions of perl later than 5.004_61, this problem can
 296 be circumvented by the use of "call-back units".  That is, the hints
 297 file can tuck this information away into a file UU/cc.cbu.  Then,
 298 after Configure prompts the user for the C compiler, it will load in
 299 and run the UU/cc.cbu "call-back" unit.  See hints/solaris_2.sh for an
 300 example. Some callbacks exist for other variables than cc, such as for
 301 uselongdouble. At the present time, these callbacks are only called if the
 302 variable in question is defined; however, this may change, so the scheme in
 303 hints/solaris_2.sh of checking to see if uselongdouble is defined is a good
 304 idea.
 305
 306 =item Call status
 307
 308 Call-backs are only called always, even if the value for the call-back is
 309 uset: UU/usethreads.cbu is called when Configure is about to deal with
 310 threads. All created call-backs from hints should thus check the status
 311 of the variable, and act upon it.
 312
 313 =item Future status
 314
 315 I hope this "call-back" scheme is simple enough to use but powerful
 316 enough to deal with most situations.  Still, there are certainly cases
 317 where it's not enough.  For example, for aix we actually change
 318 compilers if we are using threads.
 319
 320 I'd appreciate feedback on whether this is sufficiently general to be
 321 helpful, or whether we ought to simply continue to require folks to
 322 say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line.
 323
 324 =back
 325
 326 Have the appropriate amount of fun :-)
 327
 328     Andy Dougherty              doughera@lafayette.edu (author)
 329     Paul Green                  paul.green@stratus.com (compiler bugs)