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