home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / perl560.zip / hints / README.hints < prev    next >
Text File  |  1999-10-01  |  8KB  |  260 lines
  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. =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 Hint file tricks
  107.  
  108. =head2 Printing critical messages
  109.  
  110. [This is still experimental]
  111.  
  112. If you have a *REALLY* important message that the user ought to see at
  113. the end of the Configure run, you can store it in the file
  114. 'config.msg'.  At the end of the Configure run, Configure will display
  115. the contents of this file.  Currently, the only place this is used is
  116. in Configure itself to warn about the need to set LD_LIBRARY_PATH if
  117. you are building a shared libperl.so.
  118.  
  119. To use this feature, just do something like the following
  120.  
  121.     $cat <<EOM  | $tee -a ../config.msg >&4
  122.  
  123.     This is a really important message.  Be sure to read it
  124.     before you type 'make'.
  125.     EOM
  126.  
  127. This message will appear on the screen as the hint file is being
  128. processed and again at the end of Configure.
  129.  
  130. Please use this sparingly.
  131.  
  132. =head2 Propagating variables to config.sh
  133.  
  134. Sometimes, you want an extra variable to appear in config.sh.  For
  135. example, if your system can't compile toke.c with the optimizer on,
  136. you can put
  137.  
  138.     toke_cflags='optimize=""'
  139.  
  140. at the beginning of a line in your hints file.  Configure will then
  141. extract that variable and place it in your config.sh file.  Later,
  142. while compiling toke.c, the cflags shell script will eval $toke_cflags
  143. and hence compile toke.c without optimization.
  144.  
  145. Note that for this to work, the variable you want to propagate must
  146. appear in the first column of the hint file.  It is extracted by
  147. Configure with a simple sed script, so beware that surrounding case
  148. statements aren't any help.
  149.  
  150. By contrast, if you don't want Configure to propagate your temporary
  151. variable, simply indent it by a leading tab in your hint file.
  152.  
  153. For example, prior to 5.002, a bug in scope.c led to perl crashing
  154. when compiled with -O in AIX 4.1.1.  The following "obvious"
  155. workaround in hints/aix.sh wouldn't work as expected:
  156.  
  157.     case "$osvers" in
  158.     4.1.1)
  159.     scope_cflags='optimize=""'
  160.     ;;
  161.     esac
  162.  
  163. because Configure doesn't parse the surrounding 'case' statement, it
  164. just blindly propagates any variable that starts in the first column.
  165. For this particular case, that's probably harmless anyway.
  166.  
  167. Three possible fixes are:
  168.  
  169. =over
  170.  
  171. =item 1
  172.  
  173. Create an aix_4_1_1.sh hint file that contains the scope_cflags
  174. line and then sources the regular aix hints file for the rest of
  175. the information.
  176.  
  177. =item 2
  178.  
  179. Do the following trick:
  180.  
  181.     scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac'
  182.  
  183. Now when $scope_cflags is eval'd by the cflags shell script, the
  184. case statement is executed.  Of course writing scripts to be eval'd is
  185. tricky, especially if there is complex quoting.  Or,
  186.  
  187. =item 3
  188.  
  189. Write directly to Configure's temporary file UU/config.sh.
  190. You can do this with
  191.  
  192.     case "$osvers" in
  193.     4.1.1)
  194.     echo "scope_cflags='optimize=\"\"'" >> UU/config.sh
  195.     scope_cflags='optimize=""'
  196.     ;;
  197.     esac
  198.  
  199. Note you have to both write the definition to the temporary
  200. UU/config.sh file and set the variable to the appropriate value.
  201.  
  202. This is sneaky, but it works.  Still, if you need anything this
  203. complex, perhaps you should create the separate hint file for
  204. aix 4.1.1.
  205.  
  206. =back
  207.  
  208. =head2 Call-backs
  209.  
  210. =over 4
  211.  
  212. =item Warning
  213.  
  214. All of the following is experimental and subject to change.  But it
  215. probably won't change much. :-)
  216.  
  217. =item Compiler-related flags
  218.  
  219. The settings of some things, such as optimization flags, may depend on
  220. the particular compiler used.  For example, for ISC we have the
  221. following:
  222.  
  223.     case "$cc" in
  224.     *gcc*)  ccflags="$ccflags -posix"
  225.         ldflags="$ldflags -posix"
  226.         ;;
  227.     *)      ccflags="$ccflags -Xp -D_POSIX_SOURCE"
  228.         ldflags="$ldflags -Xp"
  229.         ;;
  230.     esac
  231.  
  232. However, the hints file is processed before the user is asked which
  233. compiler should be used.  Thus in order for these hints to be useful,
  234. the user must specify  sh Configure -Dcc=gcc on the command line, as
  235. advised by the INSTALL file.
  236.  
  237. For versions of perl later than 5.004_61, this problem can
  238. be circumvented by the use of "call-back units".  That is, the hints
  239. file can tuck this information away into a file UU/cc.cbu.  Then,
  240. after Configure prompts the user for the C compiler, it will load in
  241. and run the UU/cc.cbu "call-back" unit.  See hints/solaris_2.sh for an
  242. example.
  243.  
  244. =item Future status
  245.  
  246. I hope this "call-back" scheme is simple enough to use but powerful
  247. enough to deal with most situations.  Still, there are certainly cases
  248. where it's not enough.  For example, for aix we actually change
  249. compilers if we are using threads.
  250.  
  251. I'd appreciate feedback on whether this is sufficiently general to be
  252. helpful, or whether we ought to simply continue to require folks to
  253. say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line.
  254.  
  255. =back
  256.  
  257. Have the appropriate amount of fun :-)
  258.  
  259.     Andy Dougherty        doughera@lafayette.edu
  260.