Commit | Line | Data |
---|---|---|
693762b4 AD |
1 | =head1 NAME |
2 | ||
3 | README.hints | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
a0d0e21e | 7 | These files are used by Configure to set things which Configure either |
b19cab98 | 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 | |
693762b4 AD |
10 | over from perl4. |
11 | ||
7f2de2d2 | 12 | Please send any problems or suggested changes to perlbug@perl.org. |
a0d0e21e | 13 | |
c22e42be AD |
14 | =head1 Hint file naming convention. |
15 | ||
16 | Each hint file name should have only | |
693762b4 | 17 | one '.'. (This is for portability to non-unix file systems.) Names |
b19cab98 | 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 '.' | |
693762b4 | 20 | changed to '_', and all characters (such as '/') that don't belong in |
b19cab98 | 21 | Unix filenames omitted. |
a0d0e21e | 22 | |
693762b4 | 23 | For 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 |
25 | will 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 | 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 | |
693762b4 AD |
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. | |
b19cab98 | 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 | |
693762b4 AD |
52 | detect what is needed. |
53 | ||
54 | A glossary of config.sh variables is in the file Porting/Glossary. | |
55 | ||
c22e42be AD |
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 | ||
693762b4 AD |
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 | ||
693762b4 AD |
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 | |
b19cab98 | 256 | |
257 | Have the appropriate amount of fun :-) | |
258 | ||
c22e42be | 259 | Andy Dougherty doughera@lafayette.edu |