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