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