Commit | Line | Data |
693762b4 |
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 |
10 | over from perl4. |
11 | |
12 | Please send any problems or suggested changes to perlbug@perl.com. |
a0d0e21e |
13 | |
b19cab98 |
14 | Hint file naming convention: Each hint file name should have only |
693762b4 |
15 | one '.'. (This is for portability to non-unix file systems.) Names |
b19cab98 |
16 | should also fit in <= 14 characters, for portability to older SVR3 |
17 | systems. File names are of the form $osname_$osvers.sh, with all '.' |
693762b4 |
18 | changed to '_', and all characters (such as '/') that don't belong in |
b19cab98 |
19 | Unix filenames omitted. |
a0d0e21e |
20 | |
693762b4 |
21 | For example, consider Sun OS 4.1.3. Configure determines $osname=sunos |
b19cab98 |
22 | (all names are converted to lower case) and $osvers=4.1.3. Configure |
23 | will search for an appropriate hint file in the following order: |
a0d0e21e |
24 | |
b19cab98 |
25 | sunos_4_1_3.sh |
26 | sunos_4_1.sh |
27 | sunos_4.sh |
28 | sunos.sh |
a0d0e21e |
29 | |
b19cab98 |
30 | If you need to create a hint file, please try to use as general a name |
31 | as possible and include minor version differences inside case or test |
693762b4 |
32 | statements. For example, for IRIX 6.X, we have the following hints |
33 | files: |
34 | |
35 | irix_6_0.sh |
36 | irix_6_1.sh |
37 | irix_6.sh |
38 | |
39 | That is, 6.0 and 6.1 have their own special hints, but 6.2, 6.3, and |
40 | up are all handled by the same irix_6.sh. That way, we don't have to |
41 | make a new hint file every time the IRIX O/S is upgraded. |
42 | |
43 | If you need to test for specific minor version differences in your |
44 | hints file, be sure to include a default choice. (See aix.sh for one |
45 | example.) That way, if you write a hint file for foonix 3.2, it might |
46 | still work without any changes when foonix 3.3 is released. |
b19cab98 |
47 | |
48 | Please also comment carefully on why the different hints are needed. |
49 | That way, a future version of Configure may be able to automatically |
693762b4 |
50 | detect what is needed. |
51 | |
52 | A glossary of config.sh variables is in the file Porting/Glossary. |
53 | |
54 | =head1 Hint file tricks |
55 | |
56 | =head2 Printing critical messages |
57 | |
58 | [This is still experimental] |
59 | |
60 | If you have a *REALLY* important message that the user ought to see at |
61 | the end of the Configure run, you can store it in the file |
62 | 'config.msg'. At the end of the Configure run, Configure will display |
63 | the contents of this file. Currently, the only place this is used is |
64 | in Configure itself to warn about the need to set LD_LIBRARY_PATH if |
65 | you are building a shared libperl.so. |
66 | |
67 | To use this feature, just do something like the following |
68 | |
69 | $cat <<EOM | $tee -a ../config.msg >&4 |
70 | |
71 | This is a really important message. Be sure to read it |
72 | before you type 'make'. |
73 | EOM |
74 | |
75 | This message will appear on the screen as the hint file is being |
76 | processed and again at the end of Configure. |
77 | |
78 | Please use this sparingly. |
79 | |
80 | =head2 Propagating variables to config.sh |
81 | |
82 | Sometimes, you want an extra variable to appear in config.sh. For |
83 | example, if your system can't compile toke.c with the optimizer on, |
84 | you can put |
85 | |
86 | toke_cflags='optimize=""' |
87 | |
88 | at the beginning of a line in your hints file. Configure will then |
89 | extract that variable and place it in your config.sh file. Later, |
90 | while compiling toke.c, the cflags shell script will eval $toke_cflags |
91 | and hence compile toke.c without optimization. |
92 | |
93 | Note that for this to work, the variable you want to propagate must |
94 | appear in the first column of the hint file. It is extracted by |
95 | Configure with a simple sed script, so beware that surrounding case |
96 | statements aren't any help. |
97 | |
98 | By contrast, if you don't want Configure to propagate your temporary |
99 | variable, simply indent it by a leading tab in your hint file. |
100 | |
101 | For example, prior to 5.002, a bug in scope.c led to perl crashing |
102 | when compiled with -O in AIX 4.1.1. The following "obvious" |
103 | workaround in hints/aix.sh wouldn't work as expected: |
104 | |
105 | case "$osvers" in |
106 | 4.1.1) |
107 | scope_cflags='optimize=""' |
108 | ;; |
109 | esac |
110 | |
111 | because Configure doesn't parse the surrounding 'case' statement, it |
112 | just blindly propagates any variable that starts in the first column. |
113 | For this particular case, that's probably harmless anyway. |
114 | |
115 | Three possible fixes are: |
116 | |
117 | =over |
118 | |
119 | =item 1 |
120 | |
121 | Create an aix_4_1_1.sh hint file that contains the scope_cflags |
122 | line and then sources the regular aix hints file for the rest of |
123 | the information. |
124 | |
125 | =item 2 |
126 | |
127 | Do the following trick: |
128 | |
129 | scope_cflags='case "$osvers" in 4.1*) optimize=" ";; esac' |
130 | |
131 | Now when $scope_cflags is eval'd by the cflags shell script, the |
132 | case statement is executed. Of course writing scripts to be eval'd is |
133 | tricky, especially if there is complex quoting. Or, |
134 | |
135 | =item 3 |
136 | |
137 | Write directly to Configure's temporary file UU/config.sh. |
138 | You can do this with |
139 | |
140 | case "$osvers" in |
141 | 4.1.1) |
142 | echo "scope_cflags='optimize=\"\"'" >> UU/config.sh |
143 | scope_cflags='optimize=""' |
144 | ;; |
145 | esac |
146 | |
147 | Note you have to both write the definition to the temporary |
148 | UU/config.sh file and set the variable to the appropriate value. |
149 | |
150 | This is sneaky, but it works. Still, if you need anything this |
151 | complex, perhaps you should create the separate hint file for |
152 | aix 4.1.1. |
153 | |
154 | =back |
155 | |
156 | =head2 Call-backs |
157 | |
158 | =over 4 |
159 | |
160 | =item Warning |
161 | |
162 | All of the following is experimental and subject to change. But it |
163 | probably won't change much. :-) |
164 | |
165 | =item Compiler-related flags |
166 | |
167 | The settings of some things, such as optimization flags, may depend on |
168 | the particular compiler used. For example, for ISC we have the |
169 | following: |
170 | |
171 | case "$cc" in |
172 | *gcc*) ccflags="$ccflags -posix" |
173 | ldflags="$ldflags -posix" |
174 | ;; |
175 | *) ccflags="$ccflags -Xp -D_POSIX_SOURCE" |
176 | ldflags="$ldflags -Xp" |
177 | ;; |
178 | esac |
179 | |
180 | However, the hints file is processed before the user is asked which |
181 | compiler should be used. Thus in order for these hints to be useful, |
182 | the user must specify sh Configure -Dcc=gcc on the command line, as |
183 | advised by the INSTALL file. |
184 | |
185 | For versions of perl later than 5.004_61, this problem can |
186 | be circumvented by the use of "call-back units". That is, the hints |
187 | file can tuck this information away into a file UU/cc.cbu. Then, |
188 | after Configure prompts the user for the C compiler, it will load in |
189 | and run the UU/cc.cbu "call-back" unit. See hints/solaris_2.sh for an |
190 | example. |
191 | |
192 | =item Threading-related flags |
193 | |
194 | Similarly, after Configure prompts the user about whether or not to |
195 | compile Perl with threads, it will look for a "call-back" unit |
196 | usethreads.cbu. See hints/linux.sh for an example. |
197 | |
198 | =item Future status |
199 | |
200 | I hope this "call-back" scheme is simple enough to use but powerful |
201 | enough to deal with most situations. Still, there are certainly cases |
202 | where it's not enough. For example, for aix we actually change |
203 | compilers if we are using threads. |
204 | |
205 | I'd appreciate feedback on whether this is sufficiently general to be |
206 | helpful, or whether we ought to simply continue to require folks to |
207 | say things like "sh Configure -Dcc=gcc -Dusethreads" on the command line. |
208 | |
209 | =back |
b19cab98 |
210 | |
211 | Have the appropriate amount of fun :-) |
212 | |
213 | Andy Dougherty doughera@lafcol.lafayette.edu |