=head1 NAME
-README.hints
+README.hints - hint files used by Configure
=head1 DESCRIPTION
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.
-Hint file naming convention: Each hint file name should have only
+=head1 Hint file naming convention.
+
+Each hint file name should have only
one '.'. (This is for portability to non-unix file systems.) Names
should also fit in <= 14 characters, for portability to older SVR3
systems. File names are of the form $osname_$osvers.sh, with all '.'
A glossary of config.sh variables is in the file Porting/Glossary.
+=head1 Setting variables
+
+=head2 Optimizer
+
+If you want to set a variable, try to allow for Configure command-line
+overrides. For example, suppose you think the default optimizer
+setting to be -O2 for a particular platform. You should allow for
+command line overrides with something like
+
+ case "$optimize" in
+ '') optimize='-O2' ;;
+ esac
+
+or, if your system has a decent test(1) command,
+
+ test -z "$optimize" && optimize='-O2'
+
+This allows the user to select a different optimization level, e.g.
+-O6 or -g.
+
+=head2 Compiler and Linker flags
+
+If you want to set $ccflags or $ldflags, you should append to the existing
+value to allow Configure command-line settings, e.g. use
+
+ ccflags="$ccflags -DANOTHER_OPTION_I_NEED"
+
+so that the user can do something like
+
+ sh Configure -Dccflags='FIX_NEGATIVE_ZERO'
+
+and have the FIX_NEGATIVE_ZERO value preserved by the hints file.
+
+=head2 Libraries
+
+Configure will attempt to use the libraries listed in the variable
+$libswanted. If necessary, you should remove broken libraries from
+that list, or add additional libraries to that list. You should
+*not* simply set $libs -- that ignores the possibilities of local
+variations. For example, a setting of libs='-lgdbm -lm -lc' would
+fail if another user were to try to compile Perl on a system without
+GDBM but with Berkeley DB. See hints/dec_osf.sh and hints/solaris_2.sh
+for examples.
+
+=head2 Other
+
+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
=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"
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 Threading-related flags
+=item Call status
-Similarly, after Configure prompts the user about whether or not to
-compile Perl with threads, it will look for a "call-back" unit
-usethreads.cbu. See hints/linux.sh for an example.
+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
Have the appropriate amount of fun :-)
- Andy Dougherty doughera@lafcol.lafayette.edu
+ Andy Dougherty doughera@lafayette.edu (author)
+ Paul Green paul.green@stratus.com (compiler bugs)
https://perl5.git.perl.org / perl5.git / blobdiff