perl/hints/README.hints

=head1 NAME

README.hints

=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.

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
Unix filenames omitted.

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:

        sunos_4_1_3.sh
        sunos_4_1.sh
        sunos_4.sh
        sunos.sh

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.  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.

=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@lafayette.edu (author)
    Paul Green                  paul.green@stratus.com (compiler bugs)
Revision:	1.1
Committed:	Thu Jun 30 14:27:07 2005 UTC (21 years, 3 months ago) by root
Branch:	MAIN
CVS Tags:	PERL-5-8-7, HEAD
Branch point for:	PERL
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.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.org.
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 Working around compiler bugs
107
108			Occasionally, the root cause of a bug in perl turns out to be due to a bug
109			in the compiler. Often, changing the compilation options (particularly the
110			optimization level) can work around the bug. However, if you try to do
111			this on the command line, you will be changing the compilation options for
112			every component of perl, which can really hurt perl's performance.
113			Instead, consider placing a test case into the hints directory to detect
114			whether the compiler bug is present, and add logic to the hints file to
115			take a specific and appropriate action
116
117			=head2 Test-case conventions
118
119			Test cases should be named "tNNN.c", where NNN is the next unused sequence
120			number. The test case must be executable and should display a message
121			containing the word "fails" when the compiler bug is present. It should
122			display the word "works" with the compiler bug is not present. The test
123			cases should be liberally commented and may be used by any hints file that
124			needs them. See the first hints file (t001.c) for an example.
125
126			=head2 Hint file processing
127
128			The hint file must define a call-back unit (see below) that will compile,
129			link, and run the test case, and then check for the presence of the string
130			"fails" in the output. If it finds this string, it sets a special variable
131			to specify the compilation option(s) for the specific perl source file that
132			is affected by the bug.
133
134			The special variable is named "XXX_cflags" where "XXX" is the name of
135			the source file (without the ".c" suffix). The value of this variable
136			is the string "optimize=YYY", where "YYY" is the compilation option
137			necessary to work around the bug. The default value of this variable
138			is "-O" (letter O), which specifies that the C compiler should compile
139			the source program at the default optimization level. If you can
140			avoid the compiler bug by disabling optimization, just reset the
141			"optimize" variable to the null string. Sometimes a bug is present at
142			a higher optimization level (say, O3) and not present at a lower
143			optimization level (say, O1). In this case, you should specify the
144			highest optimization level at which the bug is not present, so that
145			you will retain as many of the benefits of code optimization as
146			possible.
147
148			For example, if the pp_pack.c source file must be compiled at
149			optimization level 0 to work around a problem on a particular
150			platform, one of the statements
151
152			pp_pack_cflags="optimize=-O0" or
153			pp_pack_cflags="optimize="
154
155			will do the trick, since level 0 is equivalent to no optimization.
156			(In case your printer or display device does not distinguish the
157			letter O from the digit 0, that is the letter O followed by the digit
158			0). You can specify any compiler option or set of options here, not
159			just optimizer options. These options are appended to the list of all
160			other compiler options, so you should be able to override almost any
161			compiler option prepared by Configure. (Obviously this depends on how
162			the compiler treats conflicting options, but most seem to go with the
163			last value specified on the command line).
164
165			You should also allow for the XXX_cflags variable to be overridden on the
166			command line.
167
168			See the vos.sh hints file for an extended example of these techniques.
169
170			=head1 Hint file tricks
171
172			=head2 Printing critical messages
173
174			[This is still experimental]
175
176			If you have a REALLY important message that the user ought to see at
177			the end of the Configure run, you can store it in the file
178			'config.msg'. At the end of the Configure run, Configure will display
179			the contents of this file. Currently, the only place this is used is
180			in Configure itself to warn about the need to set LD_LIBRARY_PATH if
181			you are building a shared libperl.so.
182
183			To use this feature, just do something like the following
184
185			$cat <<EOM \| $tee -a ../config.msg >&4
186
187			This is a really important message. Be sure to read it
188			before you type 'make'.
189			EOM
190
191			This message will appear on the screen as the hint file is being
192			processed and again at the end of Configure.
193
194			Please use this sparingly.
195
196			=head2 Propagating variables to config.sh
197
198			Sometimes, you want an extra variable to appear in config.sh. For
199			example, if your system can't compile toke.c with the optimizer on,
200			you can put
201
202			toke_cflags='optimize=""'
203
204			at the beginning of a line in your hints file. Configure will then
205			extract that variable and place it in your config.sh file. Later,
206			while compiling toke.c, the cflags shell script will eval $toke_cflags
207			and hence compile toke.c without optimization.
208
209			Note that for this to work, the variable you want to propagate must
210			appear in the first column of the hint file. It is extracted by
211			Configure with a simple sed script, so beware that surrounding case
212			statements aren't any help.
213
214			By contrast, if you don't want Configure to propagate your temporary
215			variable, simply indent it by a leading tab in your hint file.
216
217			For example, prior to 5.002, a bug in scope.c led to perl crashing
218			when compiled with -O in AIX 4.1.1. The following "obvious"
219			workaround in hints/aix.sh wouldn't work as expected:
220
221			case "$osvers" in
222			4.1.1)
223			scope_cflags='optimize=""'
224			;;
225			esac
226
227			because Configure doesn't parse the surrounding 'case' statement, it
228			just blindly propagates any variable that starts in the first column.
229			For this particular case, that's probably harmless anyway.
230
231			Three possible fixes are:
232
233			=over
234
235			=item 1
236
237			Create an aix_4_1_1.sh hint file that contains the scope_cflags
238			line and then sources the regular aix hints file for the rest of
239			the information.
240
241			=item 2
242
243			Do the following trick:
244
245			scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac'
246
247			Now when $scope_cflags is eval'd by the cflags shell script, the
248			case statement is executed. Of course writing scripts to be eval'd is
249			tricky, especially if there is complex quoting. Or,
250
251			=item 3
252
253			Write directly to Configure's temporary file UU/config.sh.
254			You can do this with
255
256			case "$osvers" in
257			4.1.1)
258			echo "scope_cflags='optimize=\"\"'" >> UU/config.sh
259			scope_cflags='optimize=""'
260			;;
261			esac
262
263			Note you have to both write the definition to the temporary
264			UU/config.sh file and set the variable to the appropriate value.
265
266			This is sneaky, but it works. Still, if you need anything this
267			complex, perhaps you should create the separate hint file for
268			aix 4.1.1.
269
270			=back
271
272			=head2 Call-backs
273
274			=over 4
275
276			=item Compiler-related flags
277
278			The settings of some things, such as optimization flags, may depend on
279			the particular compiler used. For example, consider the following:
280
281			case "$cc" in
282			gcc) ccflags="$ccflags -posix"
283			ldflags="$ldflags -posix"
284			;;
285			*) ccflags="$ccflags -Xp -D_POSIX_SOURCE"
286			ldflags="$ldflags -Xp"
287			;;
288			esac
289
290			However, the hints file is processed before the user is asked which
291			compiler should be used. Thus in order for these hints to be useful,
292			the user must specify sh Configure -Dcc=gcc on the command line, as
293			advised by the INSTALL file.
294
295			For versions of perl later than 5.004_61, this problem can
296			be circumvented by the use of "call-back units". That is, the hints
297			file can tuck this information away into a file UU/cc.cbu. Then,
298			after Configure prompts the user for the C compiler, it will load in
299			and run the UU/cc.cbu "call-back" unit. See hints/solaris_2.sh for an
300			example. Some callbacks exist for other variables than cc, such as for
301			uselongdouble. At the present time, these callbacks are only called if the
302			variable in question is defined; however, this may change, so the scheme in
303			hints/solaris_2.sh of checking to see if uselongdouble is defined is a good
304			idea.
305
306			=item Call status
307
308			Call-backs are only called always, even if the value for the call-back is
309			uset: UU/usethreads.cbu is called when Configure is about to deal with
310			threads. All created call-backs from hints should thus check the status
311			of the variable, and act upon it.
312
313			=item Future status
314
315			I hope this "call-back" scheme is simple enough to use but powerful
316			enough to deal with most situations. Still, there are certainly cases
317			where it's not enough. For example, for aix we actually change
318			compilers if we are using threads.
319
320			I'd appreciate feedback on whether this is sufficiently general to be
321			helpful, or whether we ought to simply continue to require folks to
322			say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line.
323
324			=back
325
326			Have the appropriate amount of fun :-)
327
328			Andy Dougherty doughera@lafayette.edu (author)
329			Paul Green paul.green@stratus.com (compiler bugs)