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