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