Commit | Line | Data |
aa689395 |
1 | =head1 NAME |
2 | |
e25f343d |
3 | Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl |
aa689395 |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | There is no simple synopsis, yet. |
8 | |
9 | =head1 DESCRIPTION |
10 | |
98dddfbd |
11 | This document attempts to begin to describe some of the considerations |
12 | involved in patching, porting, and maintaining perl. |
aa689395 |
13 | |
14 | This document is still under construction, and still subject to |
15 | significant changes. Still, I hope parts of it will be useful, |
16 | so I'm releasing it even though it's not done. |
17 | |
18 | For the most part, it's a collection of anecdotal information that |
19 | already assumes some familiarity with the Perl sources. I really need |
20 | an introductory section that describes the organization of the sources |
21 | and all the various auxiliary files that are part of the distribution. |
22 | |
23 | =head1 Where Do I Get Perl Sources and Related Material? |
24 | |
25 | The Comprehensive Perl Archive Network (or CPAN) is the place to go. |
26 | There are many mirrors, but the easiest thing to use is probably |
a93751fa |
27 | http://www.cpan.org/README.html , which automatically points you to a |
aa689395 |
28 | mirror site "close" to you. |
29 | |
30 | =head2 Perl5-porters mailing list |
31 | |
32 | The mailing list perl5-porters@perl.org |
33 | is the main group working with the development of perl. If you're |
34 | interested in all the latest developments, you should definitely |
35 | subscribe. The list is high volume, but generally has a |
36 | fairly low noise level. |
37 | |
38 | Subscribe by sending the message (in the body of your letter) |
39 | |
40 | subscribe perl5-porters |
41 | |
42 | to perl5-porters-request@perl.org . |
43 | |
fb73857a |
44 | Archives of the list are held at: |
45 | |
f38c94f4 |
46 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ |
fb73857a |
47 | |
aa689395 |
48 | =head1 How are Perl Releases Numbered? |
49 | |
f5a32c7f |
50 | Beginning with v5.6.0, even versions will stand for maintenance releases |
51 | and odd versions for development releases, i.e., v5.6.x for maintenance |
52 | releases, and v5.7.x for development releases. Before v5.6.0, subversions |
53 | _01 through _49 were reserved for bug-fix maintenance releases, and |
54 | subversions _50 through _99 for unstable development versions. |
7b5757d1 |
55 | |
f5a32c7f |
56 | For example, in v5.6.1, the revision number is 5, the version is 6, |
57 | and 1 is the subversion. |
aa689395 |
58 | |
f5a32c7f |
59 | For compatibility with the older numbering scheme the composite floating |
60 | point version number continues to be available as the magic variable $], |
76ba0908 |
61 | and amounts to C<$revision + $version/1000 + $subversion/100000>. This |
f5a32c7f |
62 | can still be used in comparisons. |
aa689395 |
63 | |
f5a32c7f |
64 | print "You've got an old perl\n" if $] < 5.005_03; |
aa689395 |
65 | |
f5a32c7f |
66 | In addition, the version is also available as a string in $^V. |
aa689395 |
67 | |
f5a32c7f |
68 | print "You've got a new perl\n" if $^V and $^V ge v5.6.0; |
7b5757d1 |
69 | |
f5a32c7f |
70 | You can also require particular version (or later) with: |
aa689395 |
71 | |
f5a32c7f |
72 | use 5.006; |
aa689395 |
73 | |
f5a32c7f |
74 | or using the new syntax available only from v5.6 onward: |
aa689395 |
75 | |
f5a32c7f |
76 | use v5.6.0; |
aa689395 |
77 | |
f5a32c7f |
78 | At some point in the future, we may need to decide what to call the |
79 | next big revision. In the .package file used by metaconfig to |
80 | generate Configure, there are two variables that might be relevant: |
81 | $baserev=5 and $package=perl5. |
aa689395 |
82 | |
f5a32c7f |
83 | Perl releases produced by the members of perl5-porters are usually |
e04b929a |
84 | available on CPAN in the F<src/5.0/maint> and F<src/5.0/devel> |
85 | directories. |
aa689395 |
86 | |
7b5757d1 |
87 | =head2 Maintenance and Development Subversions |
88 | |
f5a32c7f |
89 | The first rule of maintenance work is "First, do no harm." |
7b5757d1 |
90 | |
fb73857a |
91 | Trial releases of bug-fix maintenance releases are announced on |
92 | perl5-porters. Trial releases use the new subversion number (to avoid |
93 | testers installing it over the previous release) and include a 'local |
e04b929a |
94 | patch' entry in patchlevel.h. The distribution file contains the |
95 | string C<MAINT_TRIAL> to make clear that the file is not meant for |
96 | public consumption. |
fb73857a |
97 | |
e04b929a |
98 | In general, the names of official distribution files for the public |
f5a32c7f |
99 | always match the regular expression: |
e04b929a |
100 | |
f5a32c7f |
101 | ^perl\d+\.(\d+)\.\d+(-MAINT_TRIAL_\d+)\.tar\.gz$ |
e04b929a |
102 | |
f5a32c7f |
103 | C<$1> in the pattern is always an even number for maintenance |
104 | versions, and odd for developer releases. |
e04b929a |
105 | |
efc41c8e |
106 | In the past it has been observed that pumpkings tend to invent new |
e04b929a |
107 | naming conventions on the fly. If you are a pumpking, before you |
108 | invent a new name for any of the three types of perl distributions, |
109 | please inform the guys from the CPAN who are doing indexing and |
110 | provide the trees of symlinks and the like. They will have to know |
111 | I<in advance> what you decide. |
20f245af |
112 | |
aa689395 |
113 | =head2 Why is it called the patch pumpkin? |
114 | |
115 | Chip Salzenberg gets credit for that, with a nod to his cow orker, |
116 | David Croy. We had passed around various names (baton, token, hot |
117 | potato) but none caught on. Then, Chip asked: |
118 | |
119 | [begin quote] |
120 | |
121 | Who has the patch pumpkin? |
122 | |
123 | To explain: David Croy once told me once that at a previous job, |
124 | there was one tape drive and multiple systems that used it for backups. |
125 | But instead of some high-tech exclusion software, they used a low-tech |
126 | method to prevent multiple simultaneous backups: a stuffed pumpkin. |
127 | No one was allowed to make backups unless they had the "backup pumpkin". |
128 | |
129 | [end quote] |
130 | |
131 | The name has stuck. |
132 | |
a6968aa6 |
133 | =head1 Philosophical Issues in Patching and Porting Perl |
aa689395 |
134 | |
135 | There are no absolute rules, but there are some general guidelines I |
136 | have tried to follow as I apply patches to the perl sources. |
137 | (This section is still under construction.) |
138 | |
139 | =head2 Solve problems as generally as possible |
140 | |
7b5757d1 |
141 | Never implement a specific restricted solution to a problem when you |
142 | can solve the same problem in a more general, flexible way. |
143 | |
144 | For example, for dynamic loading to work on some SVR4 systems, we had |
145 | to build a shared libperl.so library. In order to build "FAT" binaries |
146 | on NeXT 4.0 systems, we had to build a special libperl library. Rather |
147 | than continuing to build a contorted nest of special cases, I |
148 | generalized the process of building libperl so that NeXT and SVR4 users |
149 | could still get their work done, but others could build a shared |
150 | libperl if they wanted to as well. |
aa689395 |
151 | |
a6968aa6 |
152 | Contain your changes carefully. Assume nothing about other operating |
153 | systems, not even closely related ones. Your changes must not affect |
154 | other platforms. |
155 | |
156 | Spy shamelessly on how similar patching or porting issues have been |
157 | settled elsewhere. |
158 | |
159 | If feasible, try to keep filenames 8.3-compliant to humor those poor |
160 | souls that get joy from running Perl under such dire limitations. |
9e371ce5 |
161 | There's a script, check83.pl, for keeping your nose 8.3-clean. |
efc41c8e |
162 | In a similar vein, do not create files or directories which differ only |
163 | in case (upper versus lower). |
a6968aa6 |
164 | |
aa689395 |
165 | =head2 Seek consensus on major changes |
166 | |
167 | If you are making big changes, don't do it in secret. Discuss the |
168 | ideas in advance on perl5-porters. |
169 | |
170 | =head2 Keep the documentation up-to-date |
171 | |
172 | If your changes may affect how users use perl, then check to be sure |
173 | that the documentation is in sync with your changes. Be sure to |
174 | check all the files F<pod/*.pod> and also the F<INSTALL> document. |
175 | |
176 | Consider writing the appropriate documentation first and then |
7b5757d1 |
177 | implementing your change to correspond to the documentation. |
aa689395 |
178 | |
179 | =head2 Avoid machine-specific #ifdef's |
180 | |
181 | To the extent reasonable, try to avoid machine-specific #ifdef's in |
182 | the sources. Instead, use feature-specific #ifdef's. The reason is |
183 | that the machine-specific #ifdef's may not be valid across major |
184 | releases of the operating system. Further, the feature-specific tests |
185 | may help out folks on another platform who have the same problem. |
186 | |
a6968aa6 |
187 | =head2 Machine-specific files |
188 | |
98dddfbd |
189 | =over 4 |
190 | |
191 | =item source code |
192 | |
a6968aa6 |
193 | If you have many machine-specific #defines or #includes, consider |
194 | creating an "osish.h" (os2ish.h, vmsish.h, and so on) and including |
195 | that in perl.h. If you have several machine-specific files (function |
196 | emulations, function stubs, build utility wrappers) you may create a |
197 | separate subdirectory (djgpp, win32) and put the files in there. |
98dddfbd |
198 | Remember to update C<MANIFEST> when you add files. |
a6968aa6 |
199 | |
ff935051 |
200 | If your system supports dynamic loading but none of the existing |
98dddfbd |
201 | methods at F<ext/DynaLoader/dl_*.xs> work for you, you must write |
202 | a new one. Study the existing ones to see what kind of interface |
203 | you must supply. |
204 | |
205 | =item build hints |
a6968aa6 |
206 | |
207 | There are two kinds of hints: hints for building Perl and hints for |
208 | extensions. The former live in the C<hints> subdirectory, the latter |
209 | in C<ext/*/hints> subdirectories. |
210 | |
211 | The top level hints are Bourne-shell scripts that set, modify and |
212 | unset appropriate Configure variables, based on the Configure command |
213 | line options and possibly existing config.sh and Policy.sh files from |
214 | previous Configure runs. |
215 | |
76ba0908 |
216 | The extension hints are written in Perl (by the time they are used |
a6968aa6 |
217 | miniperl has been built) and control the building of their respective |
218 | extensions. They can be used to for example manipulate compilation |
219 | and linking flags. |
220 | |
98dddfbd |
221 | =item build and installation Makefiles, scripts, and so forth |
222 | |
223 | Sometimes you will also need to tweak the Perl build and installation |
224 | procedure itself, like for example F<Makefile.SH> and F<installperl>. |
225 | Tread very carefully, even more than usual. Contain your changes |
226 | with utmost care. |
a6968aa6 |
227 | |
98dddfbd |
228 | =item test suite |
229 | |
230 | Many of the tests in C<t> subdirectory assume machine-specific things |
a6968aa6 |
231 | like existence of certain functions, something about filesystem |
232 | semantics, certain external utilities and their error messages. Use |
233 | the C<$^O> and the C<Config> module (which contains the results of the |
234 | Configure run, in effect the C<config.sh> converted to Perl) to either |
98dddfbd |
235 | skip (preferably not) or customize (preferable) the tests for your |
236 | platform. |
237 | |
238 | =item modules |
239 | |
240 | Certain standard modules may need updating if your operating system |
241 | sports for example a native filesystem naming. You may want to update |
242 | some or all of the modules File::Basename, File::Spec, File::Path, and |
243 | File::Copy to become aware of your native filesystem syntax and |
244 | peculiarities. |
245 | |
b972f109 |
246 | Remember to have a $VERSION in the modules. You can use the |
247 | Porting/checkVERSION.pl script for checking this. |
248 | |
98dddfbd |
249 | =item documentation |
250 | |
251 | If your operating system comes from outside UNIX you almost certainly |
252 | will have differences in the available operating system functionality |
253 | (missing system calls, different semantics, whatever). Please |
254 | document these at F<pod/perlport.pod>. If your operating system is |
255 | the first B<not> to have a system call also update the list of |
256 | "portability-bewares" at the beginning of F<pod/perlfunc.pod>. |
257 | |
258 | A file called F<README.youros> at the top level that explains things |
259 | like how to install perl at this platform, where to get any possibly |
260 | required additional software, and for example what test suite errors |
76ba0908 |
261 | to expect, is nice too. Such files are in the process of being written |
262 | in pod format and will eventually be renamed F<INSTALL.youros>. |
98dddfbd |
263 | |
264 | You may also want to write a separate F<.pod> file for your operating |
265 | system to tell about existing mailing lists, os-specific modules, |
266 | documentation, whatever. Please name these along the lines of |
267 | F<perl>I<youros>.pod. [unfinished: where to put this file (the pod/ |
268 | subdirectory, of course: but more importantly, which/what index files |
269 | should be updated?)] |
270 | |
271 | =back |
a6968aa6 |
272 | |
aa689395 |
273 | =head2 Allow for lots of testing |
274 | |
275 | We should never release a main version without testing it as a |
276 | subversion first. |
277 | |
6877a1cf |
278 | =head2 Test popular applications and modules. |
279 | |
280 | We should never release a main version without testing whether or not |
281 | it breaks various popular modules and applications. A partial list of |
282 | such things would include majordomo, metaconfig, apache, Tk, CGI, |
283 | libnet, and libwww, to name just a few. Of course it's quite possible |
284 | that some of those things will be just plain broken and need to be fixed, |
285 | but, in general, we ought to try to avoid breaking widely-installed |
286 | things. |
287 | |
98dddfbd |
288 | =head2 Automated generation of derivative files |
aa689395 |
289 | |
290 | The F<embed.h>, F<keywords.h>, F<opcode.h>, and F<perltoc.pod> files |
291 | are all automatically generated by perl scripts. In general, don't |
292 | patch these directly; patch the data files instead. |
293 | |
294 | F<Configure> and F<config_h.SH> are also automatically generated by |
295 | B<metaconfig>. In general, you should patch the metaconfig units |
a6968aa6 |
296 | instead of patching these files directly. However, very minor changes |
297 | to F<Configure> may be made in between major sync-ups with the |
298 | metaconfig units, which tends to be complicated operations. But be |
299 | careful, this can quickly spiral out of control. Running metaconfig |
300 | is not really hard. |
aa689395 |
301 | |
98dddfbd |
302 | Also F<Makefile> is automatically produced from F<Makefile.SH>. |
303 | In general, look out for all F<*.SH> files. |
304 | |
a8119d38 |
305 | Finally, the sample files in the F<Porting/> subdirectory are |
306 | generated automatically by the script F<U/mksample> included |
307 | with the metaconfig units. See L<"run metaconfig"> below for |
308 | information on obtaining the metaconfig units. |
309 | |
aa689395 |
310 | =head1 How to Make a Distribution |
311 | |
f6af4394 |
312 | This section has now been expanded and moved into its own file, |
313 | F<Porting/release_managers_guide.pod>. |
aa689395 |
314 | |
f6af4394 |
315 | I've kept some of the subsections here for now, as they don't direclty |
316 | eleate to building a release any more, but still contain what might be |
317 | useful information - DAPM 7/2009. |
05ff1fbb |
318 | |
aa689395 |
319 | =head2 run metaconfig |
320 | |
321 | If you need to make changes to Configure or config_h.SH, it may be best to |
322 | change the appropriate metaconfig units instead, and regenerate Configure. |
323 | |
324 | metaconfig -m |
325 | |
20f245af |
326 | will regenerate Configure and config_h.SH. Much more information |
327 | on obtaining and running metaconfig is in the F<U/README> file |
449b893f |
328 | that comes with Perl's metaconfig units. |
329 | |
330 | Since metaconfig is hard to change, running correction scripts after |
331 | this generation is sometimes needed. Configure gained complexity over |
332 | time, and the order in which config_h.SH is generated can cause havoc |
333 | when compiling perl. Therefor, you need to run Porting/config_h.pl |
334 | after that generation. All that and more is described in the README |
335 | files that come with the metaunits. |
336 | |
337 | Perl's metaconfig units should be available on CPAN. A set of units |
338 | that will work with perl5.9.x is in a file with a name similar to |
339 | F<mc_units-20070423.tgz> under http://www.cpan.org/authors/id/H/HM/HMBRAND/ . |
340 | The mc_units tar file should be unpacked in your main perl source directory. |
341 | Note: those units were for use with 5.9.x. There may have been changes since |
342 | then. Check for later versions or contact perl5-porters@perl.org to obtain a |
20f245af |
343 | pointer to the current version. |
aa689395 |
344 | |
449b893f |
345 | Alternatively, do consider if the F<*ish.h> files or the hint files might be |
346 | a better place for your changes. |
aa689395 |
347 | |
348 | =head2 MANIFEST |
349 | |
aa689395 |
350 | If you are using metaconfig to regenerate Configure, then you should note |
351 | that metaconfig actually uses MANIFEST.new, so you want to be sure |
352 | MANIFEST.new is up-to-date too. I haven't found the MANIFEST/MANIFEST.new |
353 | distinction particularly useful, but that's probably because I still haven't |
354 | learned how to use the full suite of tools in the dist distribution. |
355 | |
aa689395 |
356 | |
357 | =head2 Run Configure |
358 | |
359 | This will build a config.sh and config.h. You can skip this if you haven't |
693762b4 |
360 | changed Configure or config_h.SH at all. I use the following command |
aa689395 |
361 | |
693762b4 |
362 | sh Configure -Dprefix=/opt/perl -Doptimize=-O -Dusethreads \ |
363 | -Dcf_by='yourname' \ |
364 | -Dcf_email='yourname@yourhost.yourplace.com' \ |
365 | -Dperladmin='yourname@yourhost.yourplace.com' \ |
366 | -Dmydomain='.yourplace.com' \ |
367 | -Dmyhostname='yourhost' \ |
368 | -des |
aa689395 |
369 | |
693762b4 |
370 | =head2 Update Porting/config.sh and Porting/config_H |
dfe9444c |
371 | |
693762b4 |
372 | [XXX |
373 | This section needs revision. We're currently working on easing |
374 | the task of keeping the vms, win32, and plan9 config.sh info |
375 | up-to-date. The plan is to use keep up-to-date 'canned' config.sh |
376 | files in the appropriate subdirectories and then generate 'canned' |
377 | config.h files for vms, win32, etc. from the generic config.sh file. |
378 | This is to ease maintenance. When Configure gets updated, the parts |
379 | sometimes get scrambled around, and the changes in config_H can |
380 | sometimes be very hard to follow. config.sh, on the other hand, can |
381 | safely be sorted, so it's easy to track (typically very small) changes |
d7f8936a |
382 | to config.sh and then propagate them to a canned 'config.h' by any |
693762b4 |
383 | number of means, including a perl script in win32/ or carrying |
384 | config.sh and config_h.SH to a Unix system and running sh |
76ba0908 |
385 | config_h.SH.) Vms uses configure.com to generate its own config.sh |
386 | and config.h. If you want to add a new variable to config.sh check |
387 | with vms folk how to add it to configure.com too. |
693762b4 |
388 | XXX] |
389 | |
390 | The Porting/config.sh and Porting/config_H files are provided to |
391 | help those folks who can't run Configure. It is important to keep |
392 | them up-to-date. If you have changed config_h.SH, those changes must |
393 | be reflected in config_H as well. (The name config_H was chosen to |
394 | distinguish the file from config.h even on case-insensitive file systems.) |
395 | Simply edit the existing config_H file; keep the first few explanatory |
396 | lines and then copy your new config.h below. |
aa689395 |
397 | |
76ba0908 |
398 | It may also be necessary to update win32/config.?c, and |
aa689395 |
399 | plan9/config.plan9, though you should be quite careful in doing so if |
400 | you are not familiar with those systems. You might want to issue your |
401 | patch with a promise to quickly issue a follow-up that handles those |
402 | directories. |
403 | |
0de566d7 |
404 | =head2 make regen_perly |
aa689395 |
405 | |
d7f8936a |
406 | If perly.y has been edited, it is necessary to run this target to rebuild |
d21142e6 |
407 | perly.h, perly.act and perly.tab. In fact this target just runs the Perl |
408 | script regen_perly.pl. Note that perly.c is I<not> rebuilt; this is just a |
0de566d7 |
409 | plain static file now. |
aa689395 |
410 | |
0de566d7 |
411 | This target relies on you having Bison installed on your system. Running |
412 | the target will tell you if you haven't got the right version, and if so, |
413 | where to get the right one. Or if you prefer, you could hack |
414 | regen_perly.pl to work with your version of Bison. The important things |
415 | are that the regexes can still extract out the right chunks of the Bison |
d21142e6 |
416 | output into perly.act and perly.tab, and that the contents of those two |
0de566d7 |
417 | files, plus perly.h, are functionally equivalent to those produced by the |
418 | supported version of Bison. |
ebb99254 |
419 | |
0de566d7 |
420 | Note that in the old days, you had to do C<make run_byacc> instead. |
aa689395 |
421 | |
76ba0908 |
422 | =head2 make regen_all |
423 | |
1e2f36ef |
424 | This target takes care of the regen_headers target. |
425 | (It used to also call the regen_pods target, but that has been eliminated.) |
76ba0908 |
426 | |
aa689395 |
427 | =head2 make regen_headers |
428 | |
429 | The F<embed.h>, F<keywords.h>, and F<opcode.h> files are all automatically |
430 | generated by perl scripts. Since the user isn't guaranteed to have a |
431 | working perl, we can't require the user to generate them. Hence you have |
432 | to, if you're making a distribution. |
433 | |
434 | I used to include rules like the following in the makefile: |
435 | |
436 | # The following three header files are generated automatically |
437 | # The correct versions should be already supplied with the perl kit, |
438 | # in case you don't have perl or 'sh' available. |
439 | # The - is to ignore error return codes in case you have the source |
440 | # installed read-only or you don't have perl yet. |
441 | keywords.h: keywords.pl |
442 | @echo "Don't worry if this fails." |
443 | - perl keywords.pl |
444 | |
445 | |
7b5757d1 |
446 | However, I got B<lots> of mail consisting of people worrying because the |
aa689395 |
447 | command failed. I eventually decided that I would save myself time |
448 | and effort by manually running C<make regen_headers> myself rather |
449 | than answering all the questions and complaints about the failing |
450 | command. |
451 | |
3e3baf6d |
452 | =head2 global.sym, interp.sym and perlio.sym |
aa689395 |
453 | |
454 | Make sure these files are up-to-date. Read the comments in these |
455 | files and in perl_exp.SH to see what to do. |
456 | |
457 | =head2 Binary compatibility |
458 | |
459 | If you do change F<global.sym> or F<interp.sym>, think carefully about |
460 | what you are doing. To the extent reasonable, we'd like to maintain |
76ba0908 |
461 | source and binary compatibility with older releases of perl. That way, |
aa689395 |
462 | extensions built under one version of perl will continue to work with |
463 | new versions of perl. |
464 | |
465 | Of course, some incompatible changes may well be necessary. I'm just |
466 | suggesting that we not make any such changes without thinking carefully |
467 | about them first. If possible, we should provide |
468 | backwards-compatibility stubs. There's a lot of XS code out there. |
469 | Let's not force people to keep changing it. |
470 | |
d65aee78 |
471 | =head2 PPPort |
472 | |
0ff33da8 |
473 | F<ext/Devel-PPPort/PPPort.pm> needs to be synchronized to include all |
d65aee78 |
474 | new macros added to .h files (normally perl.h and XSUB.h, but others |
475 | as well). Since chances are that when a new macro is added the |
476 | committer will forget to update F<PPPort.pm>, it's the best to diff for |
477 | changes in .h files when making a new release and making sure that |
478 | F<PPPort.pm> contains them all. |
479 | |
480 | The pumpking can delegate the synchronization responsibility to anybody |
481 | else, but the release process is the only place where we can make sure |
482 | that no new macros fell through the cracks. |
483 | |
15839b60 |
484 | |
2a26e2f1 |
485 | =head2 Todo |
486 | |
efc41c8e |
487 | The F<pod/perltodo.pod> file contains a roughly-categorized unordered |
488 | list of aspects of Perl that could use enhancement, features that could |
489 | be added, areas that could be cleaned up, and so on. During your term |
490 | as pumpkin-holder, you will probably address some of these issues, and |
491 | perhaps identify others which, while you decide not to address them this |
492 | time around, may be tackled in the future. Update the file to reflect |
493 | the situation as it stands when you hand over the pumpkin. |
2a26e2f1 |
494 | |
495 | You might like, early in your pumpkin-holding career, to see if you |
d7f8936a |
496 | can find champions for particular issues on the to-do list: an issue |
2a26e2f1 |
497 | owned is an issue more likely to be resolved. |
498 | |
94655993 |
499 | There are also some more porting-specific L</Todo> items later in this |
c4f23d77 |
500 | file. |
501 | |
aa689395 |
502 | =head2 OS/2-specific updates |
503 | |
504 | In the os2 directory is F<diff.configure>, a set of OS/2-specific |
505 | diffs against B<Configure>. If you make changes to Configure, you may |
506 | want to consider regenerating this diff file to save trouble for the |
507 | OS/2 maintainer. |
508 | |
7b5757d1 |
509 | You can also consider the OS/2 diffs as reminders of portability |
510 | things that need to be fixed in Configure. |
511 | |
aa689395 |
512 | =head2 VMS-specific updates |
513 | |
76ba0908 |
514 | The Perl revision number appears as "perl5" in configure.com. |
515 | It is courteous to update that if necessary. |
aa689395 |
516 | |
3e3baf6d |
517 | |
aa689395 |
518 | =head2 Making a new patch |
519 | |
520 | I find the F<makepatch> utility quite handy for making patches. |
521 | You can obtain it from any CPAN archive under |
a93751fa |
522 | http://www.cpan.org/authors/Johan_Vromans/ . There are a couple |
3e3baf6d |
523 | of differences between my version and the standard one. I have mine do |
524 | a |
aa689395 |
525 | |
526 | # Print a reassuring "End of Patch" note so people won't |
527 | # wonder if their mailer truncated patches. |
528 | print "\n\nEnd of Patch.\n"; |
529 | |
3e3baf6d |
530 | at the end. That's because I used to get questions from people asking |
531 | if their mail was truncated. |
532 | |
533 | It also writes Index: lines which include the new directory prefix |
534 | (change Index: print, approx line 294 or 310 depending on the version, |
535 | to read: print PATCH ("Index: $newdir$new\n");). That helps patches |
536 | work with more POSIX conformant patch programs. |
aa689395 |
537 | |
538 | Here's how I generate a new patch. I'll use the hypothetical |
539 | 5.004_07 to 5.004_08 patch as an example. |
540 | |
541 | # unpack perl5.004_07/ |
542 | gzip -d -c perl5.004_07.tar.gz | tar -xof - |
543 | # unpack perl5.004_08/ |
544 | gzip -d -c perl5.004_08.tar.gz | tar -xof - |
545 | makepatch perl5.004_07 perl5.004_08 > perl5.004_08.pat |
546 | |
547 | Makepatch will automatically generate appropriate B<rm> commands to remove |
548 | deleted files. Unfortunately, it will not correctly set permissions |
549 | for newly created files, so you may have to do so manually. For example, |
550 | patch 5.003_04 created a new test F<t/op/gv.t> which needs to be executable, |
551 | so at the top of the patch, I inserted the following lines: |
552 | |
553 | # Make a new test |
554 | touch t/op/gv.t |
555 | chmod +x t/opt/gv.t |
556 | |
557 | Now, of course, my patch is now wrong because makepatch didn't know I |
558 | was going to do that command, and it patched against /dev/null. |
559 | |
560 | So, what I do is sort out all such shell commands that need to be in the |
561 | patch (including possible mv-ing of files, if needed) and put that in the |
562 | shell commands at the top of the patch. Next, I delete all the patch parts |
563 | of perl5.004_08.pat, leaving just the shell commands. Then, I do the |
564 | following: |
565 | |
7b5757d1 |
566 | cd perl5.004_07 |
567 | sh ../perl5.004_08.pat |
aa689395 |
568 | cd .. |
7b5757d1 |
569 | makepatch perl5.004_07 perl5.004_08 >> perl5.004_08.pat |
aa689395 |
570 | |
571 | (Note the append to preserve my shell commands.) |
572 | Now, my patch will line up with what the end users are going to do. |
573 | |
574 | =head2 Testing your patch |
575 | |
576 | It seems obvious, but be sure to test your patch. That is, verify that |
577 | it produces exactly the same thing as your full distribution. |
578 | |
7b5757d1 |
579 | rm -rf perl5.004_07 |
580 | gzip -d -c perl5.004_07.tar.gz | tar -xf - |
581 | cd perl5.004_07 |
582 | sh ../perl5.004_08.pat |
583 | patch -p1 -N < ../perl5.004_08.pat |
aa689395 |
584 | cd .. |
7b5757d1 |
585 | gdiff -r perl5.004_07 perl5.004_08 |
aa689395 |
586 | |
587 | where B<gdiff> is GNU diff. Other diff's may also do recursive checking. |
588 | |
589 | =head2 More testing |
590 | |
591 | Again, it's obvious, but you should test your new version as widely as you |
592 | can. You can be sure you'll hear about it quickly if your version doesn't |
593 | work on both ANSI and pre-ANSI compilers, and on common systems such as |
594 | SunOS 4.1.[34], Solaris, and Linux. |
595 | |
596 | If your changes include conditional code, try to test the different |
597 | branches as thoroughly as you can. For example, if your system |
598 | supports dynamic loading, you can also test static loading with |
599 | |
600 | sh Configure -Uusedl |
601 | |
602 | You can also hand-tweak your config.h to try out different #ifdef |
603 | branches. |
604 | |
d2560b70 |
605 | =head2 Other tests |
606 | |
00baac8f |
607 | =over 4 |
608 | |
93189314 |
609 | =item gcc -ansi -pedantic |
610 | |
611 | Configure -Dgccansipedantic [ -Dcc=gcc ] will enable (via the cflags script, |
612 | not $Config{ccflags}) the gcc strict ANSI C flags -ansi and -pedantic for |
613 | the compilation of the core files on platforms where it knows it can |
614 | do so (like Linux, see cflags.SH for the full list), and on some |
615 | platforms only one (Solaris can do only -pedantic, not -ansi). |
616 | The flag -DPERL_GCC_PEDANTIC also gets added, since gcc does not add |
617 | any internal cpp flag to signify that -pedantic is being used, as it |
618 | does for -ansi (__STRICT_ANSI__). |
619 | |
a0426075 |
620 | Note that the -ansi and -pedantic are enabled only for version 3 (and |
621 | later) of gcc, since even gcc version 2.95.4 finds lots of seemingly |
622 | false "value computed not used" errors from Perl. |
623 | |
93189314 |
624 | The -ansi and -pedantic are useful in catching at least the following |
625 | nonportable practices: |
626 | |
627 | =over 4 |
628 | |
629 | =item * |
630 | |
631 | gcc-specific extensions |
632 | |
633 | =item * |
634 | |
635 | lvalue casts |
636 | |
637 | =item * |
638 | |
639 | // C++ comments |
640 | |
641 | =item * |
642 | |
643 | enum trailing commas |
644 | |
645 | =back |
646 | |
647 | The -Dgccansipedantic should be used only when cleaning up the code, |
648 | not for production builds, since otherwise gcc cannot inline certain |
649 | things. |
650 | |
d2560b70 |
651 | =back |
652 | |
d33b2eba |
653 | =head1 Running Purify |
f5a32c7f |
654 | |
655 | Purify is a commercial tool that is helpful in identifying memory |
656 | overruns, wild pointers, memory leaks and other such badness. Perl |
657 | must be compiled in a specific way for optimal testing with Purify. |
658 | |
659 | Use the following commands to test perl with Purify: |
660 | |
661 | sh Configure -des -Doptimize=-g -Uusemymalloc -Dusemultiplicity \ |
662 | -Accflags=-DPURIFY |
663 | setenv PURIFYOPTIONS "-chain-length=25" |
664 | make all pureperl |
665 | cd t |
666 | ln -s ../pureperl perl |
365a6279 |
667 | setenv PERL_DESTRUCT_LEVEL 2 |
f5a32c7f |
668 | ./perl TEST |
669 | |
670 | Disabling Perl's malloc allows Purify to monitor allocations and leaks |
671 | more closely; using Perl's malloc will make Purify report most leaks |
672 | in the "potential" leaks category. Enabling the multiplicity option |
673 | allows perl to clean up thoroughly when the interpreter shuts down, which |
674 | reduces the number of bogus leak reports from Purify. The -DPURIFY |
675 | enables any Purify-specific debugging code in the sources. |
676 | |
677 | Purify outputs messages in "Viewer" windows by default. If you don't have |
678 | a windowing environment or if you simply want the Purify output to |
679 | unobtrusively go to a log file instead of to the interactive window, |
680 | use the following options instead: |
681 | |
682 | setenv PURIFYOPTIONS "-chain-length=25 -windows=no -log-file=perl.log \ |
683 | -append-logfile=yes" |
684 | |
685 | The only currently known leaks happen when there are compile-time errors |
686 | within eval or require. (Fixing these is non-trivial, unfortunately, but |
687 | they must be fixed eventually.) |
688 | |
b432a672 |
689 | =head1 Common Gotchas |
aa689395 |
690 | |
691 | =over 4 |
692 | |
aa689395 |
693 | =item Probably Prefer POSIX |
694 | |
695 | It's often the case that you'll need to choose whether to do |
696 | something the BSD-ish way or the POSIX-ish way. It's usually not |
697 | a big problem when the two systems use different names for similar |
698 | functions, such as memcmp() and bcmp(). The perl.h header file |
699 | handles these by appropriate #defines, selecting the POSIX mem*() |
700 | functions if available, but falling back on the b*() functions, if |
701 | need be. |
702 | |
703 | More serious is the case where some brilliant person decided to |
704 | use the same function name but give it a different meaning or |
705 | calling sequence :-). getpgrp() and setpgrp() come to mind. |
706 | These are a real problem on systems that aim for conformance to |
707 | one standard (e.g. POSIX), but still try to support the other way |
708 | of doing things (e.g. BSD). My general advice (still not really |
709 | implemented in the source) is to do something like the following. |
710 | Suppose there are two alternative versions, fooPOSIX() and |
711 | fooBSD(). |
712 | |
713 | #ifdef HAS_FOOPOSIX |
714 | /* use fooPOSIX(); */ |
715 | #else |
716 | # ifdef HAS_FOOBSD |
717 | /* try to emulate fooPOSIX() with fooBSD(); |
718 | perhaps with the following: */ |
719 | # define fooPOSIX fooBSD |
720 | # else |
721 | # /* Uh, oh. We have to supply our own. */ |
722 | # define fooPOSIX Perl_fooPOSIX |
723 | # endif |
724 | #endif |
725 | |
726 | =item Think positively |
727 | |
728 | If you need to add an #ifdef test, it is usually easier to follow if you |
729 | think positively, e.g. |
730 | |
731 | #ifdef HAS_NEATO_FEATURE |
732 | /* use neato feature */ |
733 | #else |
734 | /* use some fallback mechanism */ |
735 | #endif |
736 | |
737 | rather than the more impenetrable |
738 | |
739 | #ifndef MISSING_NEATO_FEATURE |
740 | /* Not missing it, so we must have it, so use it */ |
741 | #else |
742 | /* Are missing it, so fall back on something else. */ |
743 | #endif |
744 | |
745 | Of course for this toy example, there's not much difference. But when |
746 | the #ifdef's start spanning a couple of screen fulls, and the #else's |
747 | are marked something like |
748 | |
749 | #else /* !MISSING_NEATO_FEATURE */ |
750 | |
751 | I find it easy to get lost. |
752 | |
753 | =item Providing Missing Functions -- Problem |
754 | |
755 | Not all systems have all the neat functions you might want or need, so |
756 | you might decide to be helpful and provide an emulation. This is |
757 | sound in theory and very kind of you, but please be careful about what |
758 | you name the function. Let me use the C<pause()> function as an |
759 | illustration. |
760 | |
761 | Perl5.003 has the following in F<perl.h> |
762 | |
763 | #ifndef HAS_PAUSE |
764 | #define pause() sleep((32767<<16)+32767) |
765 | #endif |
766 | |
767 | Configure sets HAS_PAUSE if the system has the pause() function, so |
768 | this #define only kicks in if the pause() function is missing. |
769 | Nice idea, right? |
770 | |
771 | Unfortunately, some systems apparently have a prototype for pause() |
772 | in F<unistd.h>, but don't actually have the function in the library. |
773 | (Or maybe they do have it in a library we're not using.) |
774 | |
775 | Thus, the compiler sees something like |
776 | |
777 | extern int pause(void); |
778 | /* . . . */ |
779 | #define pause() sleep((32767<<16)+32767) |
780 | |
781 | and dies with an error message. (Some compilers don't mind this; |
782 | others apparently do.) |
783 | |
784 | To work around this, 5.003_03 and later have the following in perl.h: |
785 | |
786 | /* Some unistd.h's give a prototype for pause() even though |
787 | HAS_PAUSE ends up undefined. This causes the #define |
788 | below to be rejected by the compiler. Sigh. |
789 | */ |
790 | #ifdef HAS_PAUSE |
791 | # define Pause pause |
792 | #else |
793 | # define Pause() sleep((32767<<16)+32767) |
794 | #endif |
795 | |
796 | This works. |
797 | |
798 | The curious reader may wonder why I didn't do the following in |
799 | F<util.c> instead: |
800 | |
801 | #ifndef HAS_PAUSE |
802 | void pause() |
803 | { |
804 | sleep((32767<<16)+32767); |
805 | } |
806 | #endif |
807 | |
808 | That is, since the function is missing, just provide it. |
809 | Then things would probably be been alright, it would seem. |
810 | |
811 | Well, almost. It could be made to work. The problem arises from the |
812 | conflicting needs of dynamic loading and namespace protection. |
813 | |
814 | For dynamic loading to work on AIX (and VMS) we need to provide a list |
815 | of symbols to be exported. This is done by the script F<perl_exp.SH>, |
816 | which reads F<global.sym> and F<interp.sym>. Thus, the C<pause> |
817 | symbol would have to be added to F<global.sym> So far, so good. |
818 | |
819 | On the other hand, one of the goals of Perl5 is to make it easy to |
820 | either extend or embed perl and link it with other libraries. This |
821 | means we have to be careful to keep the visible namespace "clean". |
822 | That is, we don't want perl's global variables to conflict with |
823 | those in the other application library. Although this work is still |
824 | in progress, the way it is currently done is via the F<embed.h> file. |
825 | This file is built from the F<global.sym> and F<interp.sym> files, |
826 | since those files already list the globally visible symbols. If we |
827 | had added C<pause> to global.sym, then F<embed.h> would contain the |
828 | line |
829 | |
830 | #define pause Perl_pause |
831 | |
832 | and calls to C<pause> in the perl sources would now point to |
833 | C<Perl_pause>. Now, when B<ld> is run to build the F<perl> executable, |
834 | it will go looking for C<perl_pause>, which probably won't exist in any |
835 | of the standard libraries. Thus the build of perl will fail. |
836 | |
837 | Those systems where C<HAS_PAUSE> is not defined would be ok, however, |
838 | since they would get a C<Perl_pause> function in util.c. The rest of |
839 | the world would be in trouble. |
840 | |
841 | And yes, this scenario has happened. On SCO, the function C<chsize> |
842 | is available. (I think it's in F<-lx>, the Xenix compatibility |
843 | library.) Since the perl4 days (and possibly before), Perl has |
844 | included a C<chsize> function that gets called something akin to |
845 | |
846 | #ifndef HAS_CHSIZE |
847 | I32 chsize(fd, length) |
848 | /* . . . */ |
849 | #endif |
850 | |
851 | When 5.003 added |
852 | |
853 | #define chsize Perl_chsize |
854 | |
855 | to F<embed.h>, the compile started failing on SCO systems. |
856 | |
857 | The "fix" is to give the function a different name. The one |
858 | implemented in 5.003_05 isn't optimal, but here's what was done: |
859 | |
860 | #ifdef HAS_CHSIZE |
861 | # ifdef my_chsize /* Probably #defined to Perl_my_chsize in embed.h */ |
862 | # undef my_chsize |
863 | # endif |
864 | # define my_chsize chsize |
865 | #endif |
866 | |
867 | My explanatory comment in patch 5.003_05 said: |
868 | |
869 | Undef and then re-define my_chsize from Perl_my_chsize to |
870 | just plain chsize if this system HAS_CHSIZE. This probably only |
871 | applies to SCO. This shows the perils of having internal |
872 | functions with the same name as external library functions :-). |
873 | |
874 | Now, we can safely put C<my_chsize> in F<global.sym>, export it, and |
875 | hide it with F<embed.h>. |
876 | |
877 | To be consistent with what I did for C<pause>, I probably should have |
878 | called the new function C<Chsize>, rather than C<my_chsize>. |
879 | However, the perl sources are quite inconsistent on this (Consider |
880 | New, Mymalloc, and Myremalloc, to name just a few.) |
881 | |
882 | There is a problem with this fix, however, in that C<Perl_chsize> |
883 | was available as a F<libperl.a> library function in 5.003, but it |
884 | isn't available any more (as of 5.003_07). This means that we've |
885 | broken binary compatibility. This is not good. |
886 | |
887 | =item Providing missing functions -- some ideas |
888 | |
889 | We currently don't have a standard way of handling such missing |
890 | function names. Right now, I'm effectively thinking aloud about a |
891 | solution. Some day, I'll try to formally propose a solution. |
892 | |
893 | Part of the problem is that we want to have some functions listed as |
894 | exported but not have their names mangled by embed.h or possibly |
895 | conflict with names in standard system headers. We actually already |
896 | have such a list at the end of F<perl_exp.SH> (though that list is |
897 | out-of-date): |
898 | |
899 | # extra globals not included above. |
900 | cat <<END >> perl.exp |
901 | perl_init_ext |
902 | perl_init_fold |
903 | perl_init_i18nl14n |
904 | perl_alloc |
905 | perl_construct |
906 | perl_destruct |
907 | perl_free |
908 | perl_parse |
909 | perl_run |
910 | perl_get_sv |
911 | perl_get_av |
912 | perl_get_hv |
913 | perl_get_cv |
914 | perl_call_argv |
915 | perl_call_pv |
916 | perl_call_method |
917 | perl_call_sv |
918 | perl_requirepv |
919 | safecalloc |
920 | safemalloc |
921 | saferealloc |
922 | safefree |
923 | |
924 | This still needs much thought, but I'm inclined to think that one |
925 | possible solution is to prefix all such functions with C<perl_> in the |
926 | source and list them along with the other C<perl_*> functions in |
927 | F<perl_exp.SH>. |
928 | |
929 | Thus, for C<chsize>, we'd do something like the following: |
930 | |
931 | /* in perl.h */ |
932 | #ifdef HAS_CHSIZE |
933 | # define perl_chsize chsize |
934 | #endif |
935 | |
936 | then in some file (e.g. F<util.c> or F<doio.c>) do |
937 | |
938 | #ifndef HAS_CHSIZE |
939 | I32 perl_chsize(fd, length) |
940 | /* implement the function here . . . */ |
941 | #endif |
942 | |
943 | Alternatively, we could just always use C<chsize> everywhere and move |
944 | C<chsize> from F<global.sym> to the end of F<perl_exp.SH>. That would |
945 | probably be fine as long as our C<chsize> function agreed with all the |
946 | C<chsize> function prototypes in the various systems we'll be using. |
947 | As long as the prototypes in actual use don't vary that much, this is |
948 | probably a good alternative. (As a counter-example, note how Configure |
949 | and perl have to go through hoops to find and use get Malloc_t and |
950 | Free_t for C<malloc> and C<free>.) |
951 | |
952 | At the moment, this latter option is what I tend to prefer. |
953 | |
954 | =item All the world's a VAX |
955 | |
956 | Sorry, showing my age:-). Still, all the world is not BSD 4.[34], |
957 | SVR4, or POSIX. Be aware that SVR3-derived systems are still quite |
958 | common (do you have any idea how many systems run SCO?) If you don't |
959 | have a bunch of v7 manuals handy, the metaconfig units (by default |
960 | installed in F</usr/local/lib/dist/U>) are a good resource to look at |
961 | for portability. |
962 | |
963 | =back |
964 | |
965 | =head1 Miscellaneous Topics |
966 | |
967 | =head2 Autoconf |
968 | |
969 | Why does perl use a metaconfig-generated Configure script instead of an |
970 | autoconf-generated configure script? |
971 | |
972 | Metaconfig and autoconf are two tools with very similar purposes. |
973 | Metaconfig is actually the older of the two, and was originally written |
974 | by Larry Wall, while autoconf is probably now used in a wider variety of |
975 | packages. The autoconf info file discusses the history of autoconf and |
976 | how it came to be. The curious reader is referred there for further |
977 | information. |
978 | |
979 | Overall, both tools are quite good, I think, and the choice of which one |
980 | to use could be argued either way. In March, 1994, when I was just |
981 | starting to work on Configure support for Perl5, I considered both |
982 | autoconf and metaconfig, and eventually decided to use metaconfig for the |
983 | following reasons: |
984 | |
985 | =over 4 |
986 | |
987 | =item Compatibility with Perl4 |
988 | |
989 | Perl4 used metaconfig, so many of the #ifdef's were already set up for |
990 | metaconfig. Of course metaconfig had evolved some since Perl4's days, |
991 | but not so much that it posed any serious problems. |
992 | |
993 | =item Metaconfig worked for me |
994 | |
d1be9408 |
995 | My system at the time was Interactive 2.2, an SVR3.2/386 derivative that |
aa689395 |
996 | also had some POSIX support. Metaconfig-generated Configure scripts |
997 | worked fine for me on that system. On the other hand, autoconf-generated |
998 | scripts usually didn't. (They did come quite close, though, in some |
999 | cases.) At the time, I actually fetched a large number of GNU packages |
1000 | and checked. Not a single one configured and compiled correctly |
1001 | out-of-the-box with the system's cc compiler. |
1002 | |
1003 | =item Configure can be interactive |
1004 | |
1005 | With both autoconf and metaconfig, if the script works, everything is |
1006 | fine. However, one of my main problems with autoconf-generated scripts |
1007 | was that if it guessed wrong about something, it could be B<very> hard to |
1008 | go back and fix it. For example, autoconf always insisted on passing the |
1009 | -Xp flag to cc (to turn on POSIX behavior), even when that wasn't what I |
1010 | wanted or needed for that package. There was no way short of editing the |
1011 | configure script to turn this off. You couldn't just edit the resulting |
1012 | Makefile at the end because the -Xp flag influenced a number of other |
1013 | configure tests. |
1014 | |
1015 | Metaconfig's Configure scripts, on the other hand, can be interactive. |
1016 | Thus if Configure is guessing things incorrectly, you can go back and fix |
1017 | them. This isn't as important now as it was when we were actively |
1018 | developing Configure support for new features such as dynamic loading, |
1019 | but it's still useful occasionally. |
1020 | |
1021 | =item GPL |
1022 | |
1023 | At the time, autoconf-generated scripts were covered under the GNU Public |
1024 | License, and hence weren't suitable for inclusion with Perl, which has a |
1025 | different licensing policy. (Autoconf's licensing has since changed.) |
1026 | |
1027 | =item Modularity |
1028 | |
1029 | Metaconfig builds up Configure from a collection of discrete pieces |
1030 | called "units". You can override the standard behavior by supplying your |
1031 | own unit. With autoconf, you have to patch the standard files instead. |
1032 | I find the metaconfig "unit" method easier to work with. Others |
1033 | may find metaconfig's units clumsy to work with. |
1034 | |
1035 | =back |
1036 | |
aa689395 |
1037 | =head2 Why isn't there a directory to override Perl's library? |
1038 | |
1039 | Mainly because no one's gotten around to making one. Note that |
1040 | "making one" involves changing perl.c, Configure, config_h.SH (and |
1041 | associated files, see above), and I<documenting> it all in the |
1042 | INSTALL file. |
1043 | |
1044 | Apparently, most folks who want to override one of the standard library |
1045 | files simply do it by overwriting the standard library files. |
1046 | |
1047 | =head2 APPLLIB |
1048 | |
1049 | In the perl.c sources, you'll find an undocumented APPLLIB_EXP |
1050 | variable, sort of like PRIVLIB_EXP and ARCHLIB_EXP (which are |
1051 | documented in config_h.SH). Here's what APPLLIB_EXP is for, from |
1052 | a mail message from Larry: |
1053 | |
1054 | The main intent of APPLLIB_EXP is for folks who want to send out a |
1055 | version of Perl embedded in their product. They would set the symbol |
1056 | to be the name of the library containing the files needed to run or to |
1057 | support their particular application. This works at the "override" |
1058 | level to make sure they get their own versions of any library code that |
1059 | they absolutely must have configuration control over. |
1060 | |
1061 | As such, I don't see any conflict with a sysadmin using it for a |
1062 | override-ish sort of thing, when installing a generic Perl. It should |
1063 | probably have been named something to do with overriding though. Since |
1064 | it's undocumented we could still change it... :-) |
1065 | |
24f415b4 |
1066 | Given that it's already there, you can use it to override distribution modules. |
1067 | One way to do that is to add |
1068 | |
453a1e5f |
1069 | ccflags="$ccflags -DAPPLLIB_EXP=\"/my/override\"" |
24f415b4 |
1070 | |
1071 | to your config.over file. (You have to be particularly careful to get the |
453a1e5f |
1072 | double quotes in. APPLLIB_EXP must be a valid C string. It might |
1073 | actually be easier to just #define it yourself in perl.c.) |
24f415b4 |
1074 | |
1075 | Then perl.c will put /my/override ahead of ARCHLIB and PRIVLIB. Perl will |
1076 | also search architecture-specific and version-specific subdirectories of |
1077 | APPLLIB_EXP. |
aa689395 |
1078 | |
c4f23d77 |
1079 | =head2 Shared libperl.so location |
1080 | |
1081 | Why isn't the shared libperl.so installed in /usr/lib/ along |
1082 | with "all the other" shared libraries? Instead, it is installed |
1083 | in $archlib, which is typically something like |
1084 | |
1085 | /usr/local/lib/perl5/archname/5.00404 |
1086 | |
1087 | and is architecture- and version-specific. |
1088 | |
1089 | The basic reason why a shared libperl.so gets put in $archlib is so that |
1090 | you can have more than one version of perl on the system at the same time, |
1091 | and have each refer to its own libperl.so. |
1092 | |
1093 | Three examples might help. All of these work now; none would work if you |
1094 | put libperl.so in /usr/lib. |
1095 | |
1096 | =over |
1097 | |
1098 | =item 1. |
1099 | |
1100 | Suppose you want to have both threaded and non-threaded perl versions |
1101 | around. Configure will name both perl libraries "libperl.so" (so that |
1102 | you can link to them with -lperl). The perl binaries tell them apart |
1103 | by having looking in the appropriate $archlib directories. |
1104 | |
1105 | =item 2. |
1106 | |
1107 | Suppose you have perl5.004_04 installed and you want to try to compile |
1108 | it again, perhaps with different options or after applying a patch. |
1109 | If you already have libperl.so installed in /usr/lib/, then it may be |
1110 | either difficult or impossible to get ld.so to find the new libperl.so |
1111 | that you're trying to build. If, instead, libperl.so is tucked away in |
1112 | $archlib, then you can always just change $archlib in the current perl |
1113 | you're trying to build so that ld.so won't find your old libperl.so. |
1114 | (The INSTALL file suggests you do this when building a debugging perl.) |
1115 | |
1116 | =item 3. |
1117 | |
1118 | The shared perl library is not a "well-behaved" shared library with |
1119 | proper major and minor version numbers, so you can't necessarily |
1120 | have perl5.004_04 and perl5.004_05 installed simultaneously. Suppose |
1121 | perl5.004_04 were to install /usr/lib/libperl.so.4.4, and perl5.004_05 |
1122 | were to install /usr/lib/libperl.so.4.5. Now, when you try to run |
1123 | perl5.004_04, ld.so might try to load libperl.so.4.5, since it has |
1124 | the right "major version" number. If this works at all, it almost |
1125 | certainly defeats the reason for keeping perl5.004_04 around. Worse, |
1126 | with development subversions, you certaily can't guarantee that |
1127 | libperl.so.4.4 and libperl.so.4.55 will be compatible. |
1128 | |
1129 | Anyway, all this leads to quite obscure failures that are sure to drive |
1130 | casual users crazy. Even experienced users will get confused :-). Upon |
1131 | reflection, I'd say leave libperl.so in $archlib. |
1132 | |
94655993 |
1133 | =back |
1134 | |
1135 | =head2 Indentation style |
2032ff04 |
1136 | |
94655993 |
1137 | Over the years Perl has become a mishmash of |
2032ff04 |
1138 | various indentation styles, but the original "Larry style" can |
1139 | probably be restored with (GNU) indent somewhat like this: |
1140 | |
1141 | indent -kr -nce -psl -sc |
1142 | |
55c0ed8c |
1143 | A more ambitious solution would also specify a list of Perl specific |
1144 | types with -TSV -TAV -THV .. -TMAGIC -TPerlIO ... but that list would |
1145 | be quite ungainly. Also note that GNU indent also doesn't do aligning |
1146 | of consecutive assignments, which would truly wreck the layout in |
1147 | places like sv.c:Perl_sv_upgrade() or sv.c:Perl_clone_using(). |
1148 | Similarly nicely aligned &&s, ||s and ==s would not be respected. |
2032ff04 |
1149 | |
aa689395 |
1150 | =head1 Upload Your Work to CPAN |
1151 | |
1152 | You can upload your work to CPAN if you have a CPAN id. Check out |
a93751fa |
1153 | http://www.cpan.org/modules/04pause.html for information on |
aa689395 |
1154 | _PAUSE_, the Perl Author's Upload Server. |
1155 | |
1156 | I typically upload both the patch file, e.g. F<perl5.004_08.pat.gz> |
1157 | and the full tar file, e.g. F<perl5.004_08.tar.gz>. |
1158 | |
1159 | If you want your patch to appear in the F<src/5.0/unsupported> |
1160 | directory on CPAN, send e-mail to the CPAN master librarian. (Check |
a93751fa |
1161 | out http://www.cpan.org/CPAN.html ). |
aa689395 |
1162 | |
1163 | =head1 Help Save the World |
1164 | |
1165 | You should definitely announce your patch on the perl5-porters list. |
1166 | You should also consider announcing your patch on |
1167 | comp.lang.perl.announce, though you should make it quite clear that a |
1168 | subversion is not a production release, and be prepared to deal with |
1169 | people who will not read your disclaimer. |
1170 | |
1171 | =head1 Todo |
1172 | |
1173 | Here, in no particular order, are some Configure and build-related |
1174 | items that merit consideration. This list isn't exhaustive, it's just |
1175 | what I came up with off the top of my head. |
1176 | |
e25f343d |
1177 | =head2 Adding missing library functions to Perl |
1178 | |
1179 | The perl Configure script automatically determines which headers and |
1180 | functions you have available on your system and arranges for them to be |
1181 | included in the compilation and linking process. Occasionally, when porting |
1182 | perl to an operating system for the first time, you may find that the |
1183 | operating system is missing a key function. While perl may still build |
1184 | without this function, no perl program will be able to reference the missing |
1185 | function. You may be able to write the missing function yourself, or you |
1186 | may be able to find the missing function in the distribution files for |
1187 | another software package. In this case, you need to instruct the perl |
1188 | configure-and-build process to use your function. Perform these steps. |
1189 | |
1190 | =over 3 |
1191 | |
1192 | =item * |
1193 | |
2ecb232b |
1194 | Code and test the function you wish to add. Test it carefully; you will |
e25f343d |
1195 | have a much easier time debugging your code independently than when it is a |
1196 | part of perl. |
1197 | |
1198 | =item * |
1199 | |
1200 | Here is an implementation of the POSIX truncate function for an operating |
1201 | system (VOS) that does not supply one, but which does supply the ftruncate() |
1202 | function. |
1203 | |
1204 | /* Beginning of modification history */ |
1205 | /* Written 02-01-02 by Nick Ing-Simmons (nick@ing-simmons.net) */ |
1206 | /* End of modification history */ |
1207 | |
1208 | /* VOS doesn't supply a truncate function, so we build one up |
1209 | from the available POSIX functions. */ |
1210 | |
1211 | #include <fcntl.h> |
1212 | #include <sys/types.h> |
1213 | #include <unistd.h> |
1214 | |
1215 | int |
1216 | truncate(const char *path, off_t len) |
1217 | { |
1218 | int fd = open(path,O_WRONLY); |
1219 | int code = -1; |
1220 | if (fd >= 0) { |
1221 | code = ftruncate(fd,len); |
1222 | close(fd); |
1223 | } |
1224 | return code; |
1225 | } |
1226 | |
1227 | Place this file into a subdirectory that has the same name as the operating |
1228 | system. This file is named perl/vos/vos.c |
1229 | |
1230 | =item * |
1231 | |
1232 | If your operating system has a hints file (in perl/hints/XXX.sh for an |
1233 | operating system named XXX), then start with it. If your operating system |
1234 | has no hints file, then create one. You can use a hints file for a similar |
1235 | operating system, if one exists, as a template. |
1236 | |
1237 | =item * |
1238 | |
1239 | Add lines like the following to your hints file. The first line |
1240 | (d_truncate="define") instructs Configure that the truncate() function |
1241 | exists. The second line (archobjs="vos.o") instructs the makefiles that the |
1242 | perl executable depends on the existence of a file named "vos.o". (Make |
1243 | will automatically look for "vos.c" and compile it with the same options as |
1244 | the perl source code). The final line ("test -h...") adds a symbolic link |
1245 | to the top-level directory so that make can find vos.c. Of course, you |
1246 | should use your own operating system name for the source file of extensions, |
1247 | not "vos.c". |
1248 | |
1249 | # VOS does not have truncate() but we supply one in vos.c |
1250 | d_truncate="define" |
1251 | archobjs="vos.o" |
1252 | |
1253 | # Help gmake find vos.c |
1254 | test -h vos.c || ln -s vos/vos.c vos.c |
1255 | |
1256 | The hints file is a series of shell commands that are run in the top-level |
1257 | directory (the "perl" directory). Thus, these commands are simply executed |
1258 | by Configure at an appropriate place during its execution. |
1259 | |
1260 | =item * |
1261 | |
1262 | At this point, you can run the Configure script and rebuild perl. Carefully |
1263 | test the newly-built perl to ensure that normal paths, and error paths, |
1264 | behave as you expect. |
1265 | |
1266 | =back |
1267 | |
aa689395 |
1268 | =head2 Good ideas waiting for round tuits |
1269 | |
1270 | =over 4 |
1271 | |
c4f23d77 |
1272 | =item Configure -Dsrc=/blah/blah |
aa689395 |
1273 | |
1274 | We should be able to emulate B<configure --srcdir>. Tom Tromey |
1275 | tromey@creche.cygnus.com has submitted some patches to |
c4f23d77 |
1276 | the dist-users mailing list along these lines. They have been folded |
1277 | back into the main distribution, but various parts of the perl |
1278 | Configure/build/install process still assume src='.'. |
aa689395 |
1279 | |
1280 | =item Hint file fixes |
1281 | |
1282 | Various hint files work around Configure problems. We ought to fix |
1283 | Configure so that most of them aren't needed. |
1284 | |
1285 | =item Hint file information |
1286 | |
1287 | Some of the hint file information (particularly dynamic loading stuff) |
1288 | ought to be fed back into the main metaconfig distribution. |
1289 | |
1290 | =back |
1291 | |
1292 | =head2 Probably good ideas waiting for round tuits |
1293 | |
1294 | =over 4 |
1295 | |
1296 | =item GNU configure --options |
1297 | |
1298 | I've received sensible suggestions for --exec_prefix and other |
1299 | GNU configure --options. It's not always obvious exactly what is |
1300 | intended, but this merits investigation. |
1301 | |
1302 | =item make clean |
1303 | |
1304 | Currently, B<make clean> isn't all that useful, though |
1305 | B<make realclean> and B<make distclean> are. This needs a bit of |
1306 | thought and documentation before it gets cleaned up. |
1307 | |
1308 | =item Try gcc if cc fails |
1309 | |
1310 | Currently, we just give up. |
1311 | |
1312 | =item bypassing safe*alloc wrappers |
1313 | |
1314 | On some systems, it may be safe to call the system malloc directly |
1315 | without going through the util.c safe* layers. (Such systems would |
1316 | accept free(0), for example.) This might be a time-saver for systems |
1317 | that already have a good malloc. (Recent Linux libc's apparently have |
1318 | a nice malloc that is well-tuned for the system.) |
1319 | |
1320 | =back |
1321 | |
1322 | =head2 Vague possibilities |
1323 | |
1324 | =over 4 |
1325 | |
aa689395 |
1326 | =item gconvert replacement |
1327 | |
1328 | Maybe include a replacement function that doesn't lose data in rare |
1329 | cases of coercion between string and numerical values. |
1330 | |
aa689395 |
1331 | =item Improve makedepend |
1332 | |
1333 | The current makedepend process is clunky and annoyingly slow, but it |
1334 | works for most folks. Alas, it assumes that there is a filename |
1335 | $firstmakefile that the B<make> command will try to use before it uses |
1336 | F<Makefile>. Such may not be the case for all B<make> commands, |
1337 | particularly those on non-Unix systems. |
1338 | |
1339 | Probably some variant of the BSD F<.depend> file will be useful. |
1340 | We ought to check how other packages do this, if they do it at all. |
1341 | We could probably pre-generate the dependencies (with the exception of |
1342 | malloc.o, which could probably be determined at F<Makefile.SH> |
1343 | extraction time. |
1344 | |
1345 | =item GNU Makefile standard targets |
1346 | |
1347 | GNU software generally has standardized Makefile targets. Unless we |
1348 | have good reason to do otherwise, I see no reason not to support them. |
1349 | |
1350 | =item File locking |
1351 | |
1352 | Somehow, straighten out, document, and implement lockf(), flock(), |
76ba0908 |
1353 | and/or fcntl() file locking. It's a mess. See $d_fcntl_can_lock |
1354 | in recent config.sh files though. |
aa689395 |
1355 | |
1356 | =back |
1357 | |
4bb101f2 |
1358 | =head2 Copyright Issues |
1359 | |
1360 | The following is based on the consensus of a couple of IPR lawyers, |
1361 | but it is of course not a legally binding statement, just a common |
1362 | sense summary. |
1363 | |
1364 | =over 4 |
1365 | |
1366 | =item * |
1367 | |
1368 | Tacking on copyright statements is unnecessary to begin with because |
1369 | of the Berne convention. But assuming you want to go ahead... |
1370 | |
1371 | =item * |
1372 | |
1373 | The right form of a copyright statement is |
1374 | |
1375 | Copyright (C) Year, Year, ... by Someone |
1376 | |
1377 | The (C) is not required everywhere but it doesn't hurt and in certain |
1378 | jurisdictions it is required, so let's leave it in. (Yes, it's true |
1379 | that in some jurisdictions the "(C)" is not legally binding, one should |
1380 | use the true ringed-C. But we don't have that character available for |
1381 | Perl's source code.) |
1382 | |
1383 | The years must be listed out separately. Year-Year is not correct. |
1384 | Only the years when the piece has changed 'significantly' may be added. |
1385 | |
1386 | =item * |
1387 | |
1388 | One cannot give away one's copyright trivially. One can give one's |
1389 | copyright away by using public domain, but even that requires a little |
1390 | bit more than just saying 'this is in public domain'. (What it |
1391 | exactly requires depends on your jurisdiction.) But barring public |
1392 | domain, one cannot "transfer" one's copyright to another person or |
1393 | entity. In the context of software, it means that contributors cannot |
1394 | give away their copyright or "transfer" it to the "owner" of the software. |
1395 | |
1396 | Also remember that in many cases if you are employed by someone, |
1397 | your work may be copyrighted to your employer, even when you are |
1398 | contributing on your own time (this all depends on too many things |
1399 | to list here). But the bottom line is that you definitely can't give |
1400 | away a copyright you may not even have. |
1401 | |
1402 | What is possible, however, is that the software can simply state |
1403 | |
1404 | Copyright (C) Year, Year, ... by Someone and others |
1405 | |
1406 | and then list the "others" somewhere in the distribution. |
1407 | And this is exactly what Perl does. (The "somewhere" is |
1408 | AUTHORS and the Changes* files.) |
1409 | |
1410 | =item * |
1411 | |
1412 | Split files, merged files, and generated files are problematic. |
1413 | The rule of thumb: in split files, copy the copyright years of |
1414 | the original file to all the new files; in merged files make |
1415 | an union of the copyright years of all the old files; in generated |
1416 | files propagate the copyright years of the generating file(s). |
1417 | |
1418 | =item * |
1419 | |
1420 | The files of Perl source code distribution do carry a lot of |
1421 | copyrights, by various people. (There are many copyrights embedded in |
1422 | perl.c, for example.) The most straightforward thing for pumpkings to |
1423 | do is to simply update Larry's copyrights at the beginning of the |
1424 | *.[hcy], x2p/*.[hcy], *.pl, and README files, and leave all other |
1425 | copyrights alone. Doing more than that requires quite a bit of tracking. |
1426 | |
1427 | =back |
1428 | |
fb73857a |
1429 | =head1 AUTHORS |
aa689395 |
1430 | |
36816da2 |
1431 | Original author: Andy Dougherty doughera@lafayette.edu . |
fb73857a |
1432 | Additions by Chip Salzenberg chip@perl.com and |
1433 | Tim Bunce Tim.Bunce@ig.co.uk . |
aa689395 |
1434 | |
1435 | All opinions expressed herein are those of the authorZ<>(s). |
1436 | |
1437 | =head1 LAST MODIFIED |
1438 | |
1c05a96e |
1439 | 2009-07-08-01 Jesse Vincent |