diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlsource.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlsource.pod | 216 |
1 files changed, 216 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsource.pod b/Master/tlpkg/tlperl/lib/pods/perlsource.pod new file mode 100644 index 00000000000..94ceec00bd3 --- /dev/null +++ b/Master/tlpkg/tlperl/lib/pods/perlsource.pod @@ -0,0 +1,216 @@ +=encoding utf8 + +=for comment +Consistent formatting of this file is achieved with: + perl ./Porting/podtidy pod/perlsource.pod + +=head1 NAME + +perlsource - A guide to the Perl source tree + +=head1 DESCRIPTION + +This document describes the layout of the Perl source tree. If you're hacking +on the Perl core, this will help you find what you're looking for. + +=head1 FINDING YOUR WAY AROUND + +The Perl source tree is big. Here's some of the thing you'll find in it: + +=head2 C code + +The C source code and header files mostly live in the root of the source +tree. There are a few platform-specific directories which contain C code. In +addition, some of the modules shipped with Perl include C or XS code. + +See L<perlinterp> for more details on the files that make up the Perl +interpreter, as well as details on how it works. + +=head2 Core modules + +Modules shipped as part of the Perl core live in four subdirectories. Two of +these directories contain modules that live in the core, and two contain +modules that can also be released separately on CPAN. Modules which can be +released on cpan are known as "dual-life" modules. + +=over 4 + +=item * F<lib/> + +This directory contains pure-Perl modules which are only released as part of +the core. This directory contains I<all> of the modules and their tests, +unlike other core modules. + +=item * F<ext/> + +This directory contains XS-using modules which are only released as part of +the core. These modules generally have their F<Makefile.PL> and are laid out +more like a typical CPAN module. + +=item * F<dist/> + +This directory is for dual-life modules where the blead source is +canonical. Note that some modules in this directory may not yet have been +released separately on CPAN. + +=item * F<cpan/> + +This directory contains dual-life modules where the CPAN module is +canonical. Do not patch these modules directly! Changes to these modules +should be submitted to the maintainer of the CPAN module. Once those changes +are applied and released, the new version of the module will be incorporated +into the core. + +=back + +For some dual-life modules, it has not yet been determined if the CPAN version +or the blead source is canonical. Until that is done, those modules should be +in F<cpan/>. + +=head2 Tests + +The Perl core has an extensive test suite. If you add new tests (or new +modules with tests), you may need to update the F<t/TEST> file so that the +tests are run. + +=over 4 + +=item * Module tests + +Tests for core modules in the F<lib/> directory are right next to the module +itself. For example, we have F<lib/strict.pm> and F<lib/strict.t>. + +Tests for modules in F<ext/> and the dual-life modules are in F<t/> +subdirectories for each module, like a standard CPAN distribution. + +=item * F<t/base/> + +Tests for the absolute basic functionality of Perl. This includes C<if>, basic +file reads and writes, simple regexes, etc. These are run first in the test +suite and if any of them fail, something is I<really> broken. + +=item * F<t/cmd/> + +Tests for basic control structures, C<if/else>, C<while>, +subroutines, etc. + +=item * F<t/comp/> + +Tests for basic issues of how Perl parses and compiles itself. + +=item * F<t/io/> + +Tests for built-in IO functions, including command line arguments. + +=item * F<t/mro/> + +Tests for perl's method resolution order implementations (see L<mro>). + +=item * F<t/op/> + +Tests for perl's built in functions that don't fit into any of the +other directories. + +=item * F<t/re/> + +Tests for regex related functions or behaviour. (These used to live in +t/op). + +=item * F<t/run/> + +Tests for features of how perl actually runs, including exit codes and +handling of PERL* environment variables. + +=item * F<t/uni/> + +Tests for the core support of Unicode. + +=item * F<t/win32/> + +Windows-specific tests. + +=item * F<t/porting/> + +Tests the state of the source tree for various common errors. For example, it +tests that everyone who is listed in the git log has a corresponding entry in +the F<AUTHORS> file. + +=item * F<t/lib/> + +The old home for the module tests, you shouldn't put anything new in +here. There are still some bits and pieces hanging around in here that +need to be moved. Perhaps you could move them? Thanks! + +=item * F<t/x2p> + +A test suite for the s2p converter. + +=back + +=head2 Documentation + +All of the core documentation intended for end users lives in +F<pod/>. Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> +usually have their own documentation, either in the F<Module.pm> file or an +accompanying F<Module.pod> file. + +Finally, documentation intended for core Perl developers lives in the +F<Porting/> directory. + +=head2 Hacking toolks and documentation + +The F<Porting> directory contains a grab bag of code and documentation +intended to help porters work on Perl. Some of the highlights include: + +=over 4 + +=item * F<check*> + +These are scripts which will check the source things like ANSI C violations, +POD encoding issues, etc. + +=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm> + +These files contain information on who maintains which modules. Run C<perl +Porting/Maintainers -M Module::Name> to find out more information about a +dual-life module. + +=item * F<podtidy> + +Tidies a pod file. It's a good idea to run this on a pod file you've patched. + +=back + +=head2 Build system + +The Perl build system starts with the F<Configure> script in the root +directory. + +Platform-specific pieces of the build system also live in platform-specific +directories like F<win32/>, F<vms/>, etc. + +The F<Configure> script is ultimately responsible for generating a +F<Makefile>. + +The build system that Perl uses is called metaconfig. This system is +maintained separately from the Perl core. + +The metaconfig system has its own git repository. Please see its README file +in L<http://perl5.git.perl.org/metaconfig.git/> for more details. + +The F<Cross> directory contains various files related to cross-compiling +Perl. See F<Cross/README> for more details. + +=head2 F<AUTHORS> + +This file everyone who's contributed to Perl. If you submit a patch, you +should add your name to this file as part of the patch. + +=head2 F<MANIFEST> + +The F<MANIFEST> file in the root of the source tree contains a list of every +file in the Perl core, as well as a brief description of each file. + +You can get an overview of all the files with this command: + + % perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST |