"Fossies" - the Fresh Open Source Software Archive

Member "perl-5.32.1/hints/README.hints" (18 Dec 2020, 11964 Bytes) of package /linux/misc/perl-5.32.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

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