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