From: Gurusamy Sarathy Date: Sun, 10 Oct 1999 23:48:07 +0000 (+0000) Subject: add perlhack.pod from Nathan Torkington X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e8cd7eae0498ecc1fd3801fe31604cd970a11dd7;p=p5sagit%2Fp5-mst-13.2.git add perlhack.pod from Nathan Torkington p4raw-id: //depot/perl@4340 --- diff --git a/MANIFEST b/MANIFEST index b8b0056..dd81a70 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1029,6 +1029,7 @@ pod/perlfaq9.pod Frequently Asked Questions, Part 9 pod/perlform.pod Format info pod/perlfunc.pod Function info pod/perlguts.pod Internals info +pod/perlhack.pod Perl hackers guide pod/perlhist.pod Perl history info pod/perlipc.pod IPC info pod/perllexwarn.pod Lexical Warnings info diff --git a/pod/Makefile b/pod/Makefile index 8a96236..a4b405c 100644 --- a/pod/Makefile +++ b/pod/Makefile @@ -61,6 +61,7 @@ POD = \ perlcall.pod \ perlcompile.pod \ perltodo.pod \ + perlhack.pod \ perlhist.pod \ perlfaq.pod \ perlfaq1.pod \ @@ -121,6 +122,7 @@ MAN = \ perlcall.man \ perlcompile.man \ perltodo.man \ + perlhack.man \ perlhist.man \ perlfaq.man \ perlfaq1.man \ @@ -181,6 +183,7 @@ HTML = \ perlcall.html \ perlcompile.html \ perltodo.html \ + perlhack.html \ perlhist.html \ perlfaq.html \ perlfaq1.html \ @@ -241,6 +244,7 @@ TEX = \ perlcall.tex \ perlcompile.tex \ perltodo.tex \ + perlhack.tex \ perlhist.tex \ perlfaq.tex \ perlfaq1.tex \ diff --git a/pod/perl.pod b/pod/perl.pod index abf3a7b..6e3921e 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -69,6 +69,7 @@ sections: perlcall Perl calling conventions from C perltodo Perl things to do + perlhack Perl hackers guide perlhist Perl history records (If you're intending to read these straight through for the first time, diff --git a/pod/perlhack.pod b/pod/perlhack.pod new file mode 100644 index 0000000..12a5f9c --- /dev/null +++ b/pod/perlhack.pod @@ -0,0 +1,268 @@ +=head1 NAME + +perlhack - How to hack at the Perl internals + +=head1 DESCRIPTION + +This document attempts to explain how Perl development takes place, +and ends with some suggestions for people wanting to become bona fide +porters. + +The perl5-porters mailing list is where the Perl standard distribution +is maintained and developed. The list can get anywhere from 10 to 150 +messages a day, depending on the heatedness of the debate. Most days +there are two or three patches, extensions, features, or bugs being +discussed at a time. + +A searchable archive of the list is at: + + http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ + +The list is also archived under the usenet group name +C at: + + http://www.deja.com/ + +List subscribers (the porters themselves) come in several flavours. +Some are quiet curious lurkers, who rarely pitch in and instead watch +the ongoing development to ensure they're forewarned of new changes or +features in Perl. Some are representatives of vendors, who are there +to make sure that Perl continues to compile and work on their +platforms. Some patch any reported bug that they know how to fix, +some are actively patching their pet area (threads, Win32, the regexp +engine), while others seem to do nothing but complain. In other +words, it's your usual mix of technical people. + +Over this group of porters presides Larry Wall. He has the final word +in what does and does not change in the Perl language. Various releases +of Perl are shepherded by a ``pumpking'', a porter responsible for +gathering patches, deciding on a patch-by-patch feature-by-feature +basis what will and will not go into the release. For instance, +Gurusamy Sarathy is the pumpking for the 5.6 release of Perl. + +In addition, various people are pumpkings for different things. For +instance, Andy Dougherty and Jarkko Hietaniemi share the I +pumpkin, and Tom Christiansen is the documentation pumpking. + +Larry sees Perl development along the lines of the US government: +there's the Legislature (the porters), the Executive branch (the +pumpkings), and the Supreme Court (Larry). The legislature can +discuss and submit patches to the executive branch all they like, but +the executive branch is free to veto them. Rarely, the Supreme Court +will side with the executive branch over the legislature, or the +legislature over the executive branch. Mostly, however, the +legislature and the executive branch are supposed to get along and +work out their differences without impeachment or court cases. + +You might sometimes see reference to Rule 1 and Rule 2. Larry's power +as Supreme Court is expressed in The Rules: + +=over 4 + +=item 1 + +Larry is always by definition right about how Perl should behave. +This means he has final veto power on the core functionality. + +=item 2 + +Larry is allowed to change his mind about any matter at a later date, +regardless of whether he previously invoked Rule 1. + +=back + +Got that? Larry is always right, even when he was wrong. It's rare +to see either Rule exercised, but they are often alluded to. + +New features and extensions to the language are contentious, because +the criteria used by the pumpkings, Larry, and other porters to decide +which features should be implemented and incorporated are not codified +in a few small design goals as with some other languages. Instead, +the heuristics are flexible and often difficult to fathom. Here is +one person's list, roughly in decreasing order of importance, of +heuristics that new features have to be weighed against: + +=over 4 + +=item Does concept match the general goals of Perl? + +These haven't been written anywhere in stone, but one approximation +is: + + 1. Keep it fast, simple, and useful. + 2. Keep features/concepts as orthogonal as possible. + 3. No arbitrary limits (platforms, data sizes, cultures). + 4. Keep it open and exciting to use/patch/advocate Perl everywhere. + 5. Either assimilate new technologies, or build bridges to them. + +=item Where is the implementation? + +All the talk in the world is useless without an implementation. In +almost every case, the person or people who argue for a new feature +will be expected to be the ones who implement it. Porters capable +of coding new features have their own agendas, and are not available +to implement your (possibly good) idea. + +=item Backwards compatibility + +It's a cardinal sin to break existing Perl programs. New warnings are +contentious--some say that a program that emits warnings is not +broken, while others say it is. Adding keywords has the potential to +break programs, changing the meaning of existing token sequences or +functions might break programs. + +=item Could it be a module instead? + +Perl 5 has extension mechanisms, modules and XS, specifically to avoid +the need to keep changing the Perl interpreter. You can write modules +that export functions, you can give those functions prototypes so they +can be called like built-in functions, you can even write XS code to +mess with the runtime data structures of the Perl interpreter if you +want to implement really complicated things. If it can be done in a +module instead of in the core, it's highly unlikely to be added. + +=item Is the feature generic enough? + +Is this something that only the submitter wants added to the language, +or would it be broadly useful? Sometimes, instead of adding a feature +with a tight focus, the porters might decide to wait until someone +implements the more generalized feature. For instance, instead of +implementing a ``delayed evaluation'' feature, the porters are waiting +for a macro system that would permit delayed evaluation and much more. + +=item Does it potentially introduce new bugs? + +Radical rewrites of large chunks of the Perl interpreter have the +potential to introduce new bugs. The smaller and more localized the +change, the better. + +=item Does it preclude other desirable features? + +A patch is likely to be rejected if it closes off future avenues of +development. For instance, a patch that placed a true and final +interpretation on prototypes is likely to be rejected because there +are still options for the future of prototypes that haven't been +addressed. + +=item Is the implementation robust? + +Good patches (tight code, complete, correct) stand more chance of +going in. Sloppy or incorrect patches might be placed on the back +burner until the pumpking has time to fix, or might be discarded +altogether without further notice. + +=item Is the implementation generic enough to be portable? + +The worst patches make use of a system-specific features. It's highly +unlikely that nonportable additions to the Perl language will be +accepted. + +=item Is there enough documentation? + +Patches without documentation are probably ill-thought out or +incomplete. Nothing can be added without documentation, so submitting +a patch for the appropriate manpages as well as the source code is +always a good idea. If appropriate, patches should add to the test +suite as well. + +=item Is there another way to do it? + +Larry said ``Although the Perl Slogan is I, I hesitate to make 10 ways to do something''. This is a +tricky heuristic to navigate, though--one man's essential addition is +another man's pointless cruft. + +=item Does it create too much work? + +Work for the pumpking, work for Perl programmers, work for module +authors, ... Perl is supposed to be easy. + +=back + +If you're on the list, you might hear the word ``core'' bandied +around. It refers to the standard distribution. ``Hacking on the +core'' means you're changing the C source code to the Perl +interpreter. ``A core module'' is one that ships with Perl. + +The source code to the Perl interpreter, in its different versions, is +kept in a repository managed by a revision control system (which is +currently the Perforce program, see http://perforce.com/). The +pumpkings and a few others have access to the repository to check in +changes. Periodically the pumpking for the development version of Perl +will release a new version, so the rest of the porters can see what's +changed. Plans are underway for a repository viewer, and for +anonymous CVS access to the latest versions. + +Always submit patches to I. This lets other +porters review your patch, which catches a surprising number of errors +in patches. Either use the diff program (available in source code form +from I), or use Johan Vromans' I +(available from I). Unified diffs are preferred, +but context diffs are ok too. Do not send RCS-style diffs or diffs +without context lines. More information is given in the +I file in the Perl source distribution. Please +patch against the latest B version (e.g., if you're fixing +a bug in the 5.005 track, patch against the latest 5.005_5x version). +Only patches that survive the heat of the development branch get +applied to maintenance versions. + +Your patch should update the documentation and test suite. + +To report a bug in Perl, use the program I which comes with +Perl (if you can't get Perl to work, send mail to the address +I or I). Reporting bugs through +I feeds into the automated bug-tracking system, access to +which is provided through the web at I. It +often pays to check the archives of the perl5-porters mailing list to +see whether the bug you're reporting has been reported before, and if +so whether it was considered a bug. See above for the location of +the searchable archives. + +The CPAN testers (I) are a group of +volunteers who test CPAN modules on a variety of platforms. Perl Labs +(I) automatically tests modules and Perl source +releases on platforms and gives feedback to the CPAN testers mailing +list. Both efforts welcome volunteers. + +To become an active and patching Perl porter, you'll need to learn how +Perl works on the inside. Chip Salzenberg, a pumpking, has written +articles on Perl internals for The Perl Journal +(I) which explain how various parts of the Perl +interpreter work. The C manpage explains the internal data +structures. And, of course, the C source code (sometimes sparsely +commented, sometimes commented well) is a great place to start (begin +with C and see where it goes from there). A lot of the +style of the Perl source is explained in the I +file in the source distribution. + +It is essential that you be comfortable using a good debugger +(e.g. gdb, dbx) before you can patch perl. Stepping through perl +as it executes a script is perhaps the best (if sometimes tedious) +way to gain a precise understanding of the overall architecture of +the language. + +If you build a version of the Perl interpreter with C<-DDEBUGGING>, +Perl's B<-D> commandline flag will cause copious debugging information +to be emitted (see the C manpage). If you build a version of +Perl with compiler debugging information (e.g. with the C compiler's +C<-g> option instead of C<-O>) then you can step through the execution +of the interpreter with your favourite C symbolic debugger, setting +breakpoints on particular functions. + +It's a good idea to read and lurk for a while before chipping in. +That way you'll get to see the dynamic of the conversations, learn the +personalities of the players, and hopefully be better prepared to make +a useful contribution when do you speak up. + +If after all this you still think you want to join the perl5-porters +mailing list, send mail to I with the +body of your message reading I. To unsubscribe, either +send mail to the same address with the body reading I, or +send mail to I. + +=head1 AUTHOR + +This document was written by Nathan Torkington, and is maintained by +the perl5-porters mailing list. + +=cut diff --git a/pod/roffitall b/pod/roffitall index bcf5864..9c9daeb 100644 --- a/pod/roffitall +++ b/pod/roffitall @@ -70,6 +70,7 @@ toroff=` $mandir/perlcall.1 \ $mandir/perlcompile.1 \ $mandir/perltodo.1 \ + $mandir/perlhack.1 \ $mandir/perlhist.1 \ $mandir/perldelta.1 \ $mandir/perl5004delta.1 \