+=head1 NAME
+
+README.hints - hint files used by Configure
+
+=head1 DESCRIPTION
+
These files are used by Configure to set things which Configure either
can't or doesn't guess properly. Most of these hint files have been
tested with at least some version of perl5, but some are still left
-over from perl4. I would appreciate hearing about any problems
-or suggested changes.
+over from perl4.
-Hint file naming convention: Each hint file name should have only
-one '.'. (This is for portability to non-unix filesystems.) Names
+Please send any problems or suggested changes to perlbug@perl.org.
+
+=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 '.'
-changed to '_', and all characters such as '/' that don't belong in
+changed to '_', and all characters (such as '/') that don't belong in
Unix filenames omitted.
-For example, consider SunOS 4.1.3. Configure determines $osname=sunos
+For example, consider Sun OS 4.1.3. Configure determines $osname=sunos
(all names are converted to lower case) and $osvers=4.1.3. Configure
will search for an appropriate hint file in the following order:
If you need to create a hint file, please try to use as general a name
as possible and include minor version differences inside case or test
-statements. Be sure also to include a default choice. (See
-aix.sh for one example.) That way, if you write a hint file for
-foonix 3.2, it might still work without any changes when foonix 3.3 is
-released.
+statements. For example, for IRIX 6.X, we have the following hints
+files:
+
+ irix_6_0.sh
+ irix_6_1.sh
+ irix_6.sh
+
+That is, 6.0 and 6.1 have their own special hints, but 6.2, 6.3, and
+up are all handled by the same irix_6.sh. That way, we don't have to
+make a new hint file every time the IRIX O/S is upgraded.
+
+If you need to test for specific minor version differences in your
+hints file, be sure to include a default choice. (See aix.sh for one
+example.) That way, if you write a hint file for foonix 3.2, it might
+still work without any changes when foonix 3.3 is released.
Please also comment carefully on why the different hints are needed.
That way, a future version of Configure may be able to automatically
-detect what is needed. A glossary of config.sh variables is in the
-file Porting/Glossary.
+detect what is needed.
+
+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
+
+[This is still experimental]
+
+If you have a *REALLY* important message that the user ought to see at
+the end of the Configure run, you can store it in the file
+'config.msg'. At the end of the Configure run, Configure will display
+the contents of this file. Currently, the only place this is used is
+in Configure itself to warn about the need to set LD_LIBRARY_PATH if
+you are building a shared libperl.so.
+
+To use this feature, just do something like the following
+
+ $cat <<EOM | $tee -a ../config.msg >&4
+
+ This is a really important message. Be sure to read it
+ before you type 'make'.
+ EOM
+
+This message will appear on the screen as the hint file is being
+processed and again at the end of Configure.
+
+Please use this sparingly.
+
+=head2 Propagating variables to config.sh
+
+Sometimes, you want an extra variable to appear in config.sh. For
+example, if your system can't compile toke.c with the optimizer on,
+you can put
+
+ toke_cflags='optimize=""'
+
+at the beginning of a line in your hints file. Configure will then
+extract that variable and place it in your config.sh file. Later,
+while compiling toke.c, the cflags shell script will eval $toke_cflags
+and hence compile toke.c without optimization.
+
+Note that for this to work, the variable you want to propagate must
+appear in the first column of the hint file. It is extracted by
+Configure with a simple sed script, so beware that surrounding case
+statements aren't any help.
+
+By contrast, if you don't want Configure to propagate your temporary
+variable, simply indent it by a leading tab in your hint file.
+
+For example, prior to 5.002, a bug in scope.c led to perl crashing
+when compiled with -O in AIX 4.1.1. The following "obvious"
+workaround in hints/aix.sh wouldn't work as expected:
+
+ case "$osvers" in
+ 4.1.1)
+ scope_cflags='optimize=""'
+ ;;
+ esac
+
+because Configure doesn't parse the surrounding 'case' statement, it
+just blindly propagates any variable that starts in the first column.
+For this particular case, that's probably harmless anyway.
+
+Three possible fixes are:
+
+=over
+
+=item 1
+
+Create an aix_4_1_1.sh hint file that contains the scope_cflags
+line and then sources the regular aix hints file for the rest of
+the information.
+
+=item 2
+
+Do the following trick:
+
+ scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac'
+
+Now when $scope_cflags is eval'd by the cflags shell script, the
+case statement is executed. Of course writing scripts to be eval'd is
+tricky, especially if there is complex quoting. Or,
+
+=item 3
+
+Write directly to Configure's temporary file UU/config.sh.
+You can do this with
+
+ case "$osvers" in
+ 4.1.1)
+ echo "scope_cflags='optimize=\"\"'" >> UU/config.sh
+ scope_cflags='optimize=""'
+ ;;
+ esac
+
+Note you have to both write the definition to the temporary
+UU/config.sh file and set the variable to the appropriate value.
+
+This is sneaky, but it works. Still, if you need anything this
+complex, perhaps you should create the separate hint file for
+aix 4.1.1.
+
+=back
+
+=head2 Call-backs
+
+=over 4
+
+=item Compiler-related flags
+
+The settings of some things, such as optimization flags, may depend on
+the particular compiler used. For example, consider the following:
+
+ case "$cc" in
+ *gcc*) ccflags="$ccflags -posix"
+ ldflags="$ldflags -posix"
+ ;;
+ *) ccflags="$ccflags -Xp -D_POSIX_SOURCE"
+ ldflags="$ldflags -Xp"
+ ;;
+ esac
+
+However, the hints file is processed before the user is asked which
+compiler should be used. Thus in order for these hints to be useful,
+the user must specify sh Configure -Dcc=gcc on the command line, as
+advised by the INSTALL file.
+
+For versions of perl later than 5.004_61, this problem can
+be circumvented by the use of "call-back units". That is, the hints
+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. 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 Call status
+
+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
+
+I hope this "call-back" scheme is simple enough to use but powerful
+enough to deal with most situations. Still, there are certainly cases
+where it's not enough. For example, for aix we actually change
+compilers if we are using threads.
+
+I'd appreciate feedback on whether this is sufficiently general to be
+helpful, or whether we ought to simply continue to require folks to
+say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line.
+
+=back
Have the appropriate amount of fun :-)
- Andy Dougherty doughera@lafcol.lafayette.edu
- Dept. of Physics
- Lafayette College, Easton PA 18042
+ Andy Dougherty doughera@lafayette.edu (author)
+ Paul Green paul.green@stratus.com (compiler bugs)
https://perl5.git.perl.org / perl5.git / blobdiff