--- /dev/null
+=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<perl.porters-gw> 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<Configure>
+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<There's More Than One Way
+to Do It>, 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<perl5-porters@perl.org>. 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<ftp://ftp.gnu.org/pub/gnu/>), or use Johan Vromans' I<makepatch>
+(available from I<CPAN/authors/id/JV/>). 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<Porting/patching.pod> file in the Perl source distribution. Please
+patch against the latest B<development> 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<perlbug> which comes with
+Perl (if you can't get Perl to work, send mail to the address
+I<perlbug@perl.com> or I<perlbug@perl.org>). Reporting bugs through
+I<perlbug> feeds into the automated bug-tracking system, access to
+which is provided through the web at I<http://bugs.perl.org/>. 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<http://testers.cpan.org/>) are a group of
+volunteers who test CPAN modules on a variety of platforms. Perl Labs
+(I<http://labs.perl.org/>) 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<http://www.tpj.com/>) which explain how various parts of the Perl
+interpreter work. The C<perlguts> 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<perl.c> and see where it goes from there). A lot of the
+style of the Perl source is explained in the I<Porting/pumpkin.pod>
+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<perlrun> 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<perl5-porters-request@perl.org> with the
+body of your message reading I<subscribe>. To unsubscribe, either
+send mail to the same address with the body reading I<unsubscribe>, or
+send mail to I<perl5-porters-unsubscribe@perl.org>.
+
+=head1 AUTHOR
+
+This document was written by Nathan Torkington, and is maintained by
+the perl5-porters mailing list.
+
+=cut
projects / platform / upstream / perl.git / commitdiff