Add fallback to tmpfile for use in cases where user's relying on
[p5sagit/p5-mst-13.2.git] / hints / README.hints
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.com.
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 Hint file tricks
107
108 =head2 Printing critical messages
109
110 [This is still experimental]
111
112 If you have a *REALLY* important message that the user ought to see at
113 the end of the Configure run, you can store it in the file
114 'config.msg'.  At the end of the Configure run, Configure will display
115 the contents of this file.  Currently, the only place this is used is
116 in Configure itself to warn about the need to set LD_LIBRARY_PATH if
117 you are building a shared libperl.so.
118
119 To use this feature, just do something like the following
120
121         $cat <<EOM  | $tee -a ../config.msg >&4
122
123     This is a really important message.  Be sure to read it
124     before you type 'make'.
125     EOM
126
127 This message will appear on the screen as the hint file is being
128 processed and again at the end of Configure.
129
130 Please use this sparingly.
131
132 =head2 Propagating variables to config.sh
133
134 Sometimes, you want an extra variable to appear in config.sh.  For
135 example, if your system can't compile toke.c with the optimizer on,
136 you can put
137
138     toke_cflags='optimize=""'
139
140 at the beginning of a line in your hints file.  Configure will then
141 extract that variable and place it in your config.sh file.  Later,
142 while compiling toke.c, the cflags shell script will eval $toke_cflags
143 and hence compile toke.c without optimization.
144
145 Note that for this to work, the variable you want to propagate must
146 appear in the first column of the hint file.  It is extracted by
147 Configure with a simple sed script, so beware that surrounding case
148 statements aren't any help.
149
150 By contrast, if you don't want Configure to propagate your temporary
151 variable, simply indent it by a leading tab in your hint file.
152
153 For example, prior to 5.002, a bug in scope.c led to perl crashing
154 when compiled with -O in AIX 4.1.1.  The following "obvious"
155 workaround in hints/aix.sh wouldn't work as expected:
156
157     case "$osvers" in
158         4.1.1)
159     scope_cflags='optimize=""'
160         ;;
161     esac
162
163 because Configure doesn't parse the surrounding 'case' statement, it
164 just blindly propagates any variable that starts in the first column.
165 For this particular case, that's probably harmless anyway.
166
167 Three possible fixes are:
168
169 =over
170
171 =item 1
172
173 Create an aix_4_1_1.sh hint file that contains the scope_cflags
174 line and then sources the regular aix hints file for the rest of
175 the information.
176
177 =item 2
178
179 Do the following trick:
180
181     scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac'
182
183 Now when $scope_cflags is eval'd by the cflags shell script, the
184 case statement is executed.  Of course writing scripts to be eval'd is
185 tricky, especially if there is complex quoting.  Or,
186
187 =item 3
188
189 Write directly to Configure's temporary file UU/config.sh.
190 You can do this with
191
192     case "$osvers" in
193         4.1.1)
194         echo "scope_cflags='optimize=\"\"'" >> UU/config.sh
195         scope_cflags='optimize=""'
196         ;;
197     esac
198
199 Note you have to both write the definition to the temporary
200 UU/config.sh file and set the variable to the appropriate value.
201
202 This is sneaky, but it works.  Still, if you need anything this
203 complex, perhaps you should create the separate hint file for
204 aix 4.1.1.
205
206 =back
207
208 =head2 Call-backs
209
210 =over 4
211
212 =item Warning
213
214 All of the following is experimental and subject to change.  But it
215 probably won't change much. :-)
216
217 =item Compiler-related flags
218
219 The settings of some things, such as optimization flags, may depend on
220 the particular compiler used.  For example, for ISC we have the
221 following:
222
223     case "$cc" in
224     *gcc*)  ccflags="$ccflags -posix"
225             ldflags="$ldflags -posix"
226             ;;
227     *)      ccflags="$ccflags -Xp -D_POSIX_SOURCE"
228             ldflags="$ldflags -Xp"
229             ;;
230     esac
231
232 However, the hints file is processed before the user is asked which
233 compiler should be used.  Thus in order for these hints to be useful,
234 the user must specify  sh Configure -Dcc=gcc on the command line, as
235 advised by the INSTALL file.
236
237 For versions of perl later than 5.004_61, this problem can
238 be circumvented by the use of "call-back units".  That is, the hints
239 file can tuck this information away into a file UU/cc.cbu.  Then,
240 after Configure prompts the user for the C compiler, it will load in
241 and run the UU/cc.cbu "call-back" unit.  See hints/solaris_2.sh for an
242 example.
243
244 =item Future status
245
246 I hope this "call-back" scheme is simple enough to use but powerful
247 enough to deal with most situations.  Still, there are certainly cases
248 where it's not enough.  For example, for aix we actually change
249 compilers if we are using threads.
250
251 I'd appreciate feedback on whether this is sufficiently general to be
252 helpful, or whether we ought to simply continue to require folks to
253 say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line.
254
255 =back
256
257 Have the appropriate amount of fun :-)
258
259     Andy Dougherty              doughera@lafayette.edu