contrib/perl5/hints/README.hints

   1 =head1 NAME
   2
   3 README.hints
   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.com.
  13
  14 Hint file naming convention:   Each hint file name should have only
  15 one '.'.  (This is for portability to non-unix file systems.)  Names
  16 should also fit in <= 14 characters, for portability to older SVR3
  17 systems.  File names are of the form $osname_$osvers.sh, with all '.'
  18 changed to '_', and all characters (such as '/') that don't belong in
  19 Unix filenames omitted.
  20
  21 For example, consider Sun OS 4.1.3.  Configure determines $osname=sunos
  22 (all names are converted to lower case) and $osvers=4.1.3.  Configure
  23 will search for an appropriate hint file in the following order:
  24
  25         sunos_4_1_3.sh
  26         sunos_4_1.sh
  27         sunos_4.sh
  28         sunos.sh
  29
  30 If you need to create a hint file, please try to use as general a name
  31 as possible and include minor version differences inside case or test
  32 statements.  For example, for IRIX 6.X, we have the following hints
  33 files:
  34
  35         irix_6_0.sh
  36         irix_6_1.sh
  37         irix_6.sh
  38
  39 That is, 6.0 and 6.1 have their own special hints, but 6.2, 6.3, and
  40 up are all handled by the same irix_6.sh.  That way, we don't have to
  41 make a new hint file every time the IRIX O/S is upgraded.
  42
  43 If you need to test for specific minor version differences in your
  44 hints file, be sure to include a default choice.  (See aix.sh for one
  45 example.) That way, if you write a hint file for foonix 3.2, it might
  46 still work without any changes when foonix 3.3 is released.
  47
  48 Please also comment carefully on why the different hints are needed.
  49 That way, a future version of Configure may be able to automatically
  50 detect what is needed.
  51
  52 A glossary of config.sh variables is in the file Porting/Glossary.
  53
  54 =head1 Hint file tricks
  55
  56 =head2 Printing critical messages
  57
  58 [This is still experimental]
  59
  60 If you have a *REALLY* important message that the user ought to see at
  61 the end of the Configure run, you can store it in the file
  62 'config.msg'.  At the end of the Configure run, Configure will display
  63 the contents of this file.  Currently, the only place this is used is
  64 in Configure itself to warn about the need to set LD_LIBRARY_PATH if
  65 you are building a shared libperl.so.
  66
  67 To use this feature, just do something like the following
  68
  69         $cat <<EOM  | $tee -a ../config.msg >&4
  70
  71     This is a really important message.  Be sure to read it
  72     before you type 'make'.
  73     EOM
  74
  75 This message will appear on the screen as the hint file is being
  76 processed and again at the end of Configure.
  77
  78 Please use this sparingly.
  79
  80 =head2 Propagating variables to config.sh
  81
  82 Sometimes, you want an extra variable to appear in config.sh.  For
  83 example, if your system can't compile toke.c with the optimizer on,
  84 you can put
  85
  86     toke_cflags='optimize=""'
  87
  88 at the beginning of a line in your hints file.  Configure will then
  89 extract that variable and place it in your config.sh file.  Later,
  90 while compiling toke.c, the cflags shell script will eval $toke_cflags
  91 and hence compile toke.c without optimization.
  92
  93 Note that for this to work, the variable you want to propagate must
  94 appear in the first column of the hint file.  It is extracted by
  95 Configure with a simple sed script, so beware that surrounding case
  96 statements aren't any help.
  97
  98 By contrast, if you don't want Configure to propagate your temporary
  99 variable, simply indent it by a leading tab in your hint file.
 100
 101 For example, prior to 5.002, a bug in scope.c led to perl crashing
 102 when compiled with -O in AIX 4.1.1.  The following "obvious"
 103 workaround in hints/aix.sh wouldn't work as expected:
 104
 105     case "$osvers" in
 106         4.1.1)
 107     scope_cflags='optimize=""'
 108         ;;
 109     esac
 110
 111 because Configure doesn't parse the surrounding 'case' statement, it
 112 just blindly propagates any variable that starts in the first column.
 113 For this particular case, that's probably harmless anyway.
 114
 115 Three possible fixes are:
 116
 117 =over
 118
 119 =item 1
 120
 121 Create an aix_4_1_1.sh hint file that contains the scope_cflags
 122 line and then sources the regular aix hints file for the rest of
 123 the information.
 124
 125 =item 2
 126
 127 Do the following trick:
 128
 129     scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac'
 130
 131 Now when $scope_cflags is eval'd by the cflags shell script, the
 132 case statement is executed.  Of course writing scripts to be eval'd is
 133 tricky, especially if there is complex quoting.  Or,
 134
 135 =item 3
 136
 137 Write directly to Configure's temporary file UU/config.sh.
 138 You can do this with
 139
 140     case "$osvers" in
 141         4.1.1)
 142         echo "scope_cflags='optimize=\"\"'" >> UU/config.sh
 143         scope_cflags='optimize=""'
 144         ;;
 145     esac
 146
 147 Note you have to both write the definition to the temporary
 148 UU/config.sh file and set the variable to the appropriate value.
 149
 150 This is sneaky, but it works.  Still, if you need anything this
 151 complex, perhaps you should create the separate hint file for
 152 aix 4.1.1.
 153
 154 =back
 155
 156 =head2 Call-backs
 157
 158 =over 4
 159
 160 =item Warning
 161
 162 All of the following is experimental and subject to change.  But it
 163 probably won't change much. :-)
 164
 165 =item Compiler-related flags
 166
 167 The settings of some things, such as optimization flags, may depend on
 168 the particular compiler used.  For example, for ISC we have the
 169 following:
 170
 171     case "$cc" in
 172     *gcc*)  ccflags="$ccflags -posix"
 173             ldflags="$ldflags -posix"
 174             ;;
 175     *)      ccflags="$ccflags -Xp -D_POSIX_SOURCE"
 176             ldflags="$ldflags -Xp"
 177             ;;
 178     esac
 179
 180 However, the hints file is processed before the user is asked which
 181 compiler should be used.  Thus in order for these hints to be useful,
 182 the user must specify  sh Configure -Dcc=gcc on the command line, as
 183 advised by the INSTALL file.
 184
 185 For versions of perl later than 5.004_61, this problem can
 186 be circumvented by the use of "call-back units".  That is, the hints
 187 file can tuck this information away into a file UU/cc.cbu.  Then,
 188 after Configure prompts the user for the C compiler, it will load in
 189 and run the UU/cc.cbu "call-back" unit.  See hints/solaris_2.sh for an
 190 example.
 191
 192 =item Threading-related flags
 193
 194 Similarly, after Configure prompts the user about whether or not to
 195 compile Perl with threads, it will look for a "call-back" unit
 196 usethreads.cbu.  See hints/linux.sh for an example.
 197
 198 =item Future status
 199
 200 I hope this "call-back" scheme is simple enough to use but powerful
 201 enough to deal with most situations.  Still, there are certainly cases
 202 where it's not enough.  For example, for aix we actually change
 203 compilers if we are using threads.
 204
 205 I'd appreciate feedback on whether this is sufficiently general to be
 206 helpful, or whether we ought to simply continue to require folks to
 207 say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line.
 208
 209 =back
 210
 211 Have the appropriate amount of fun :-)
 212
 213     Andy Dougherty              doughera@lafcol.lafayette.edu