232 lines
6.7 KiB
Plaintext
232 lines
6.7 KiB
Plaintext
=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/>
|
|
|
|
Like F<lib/>, this directory contains modules which are only released
|
|
as part of the core. Unlike F<lib/>, however, a module under F<ext/>
|
|
generally has a CPAN-style directory- and file-layout and its own
|
|
F<Makefile.PL>. There is no expectation that a module under F<ext/>
|
|
will work with earlier versions of Perl 5. Hence, such a module may
|
|
take full advantage of syntactical and other improvements in Perl 5
|
|
blead.
|
|
|
|
=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. Modules under F<dist/> should make
|
|
an effort to work with earlier versions of Perl 5.
|
|
|
|
=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>/C<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/opbasic/>
|
|
|
|
Tests for perl's built in functions which, like those in F<t/op/>, do
|
|
not fit into any of the other directories, but which, in addition,
|
|
cannot use F<t/test.pl>,as that program depends on functionality which
|
|
the test file itself is testing.
|
|
|
|
=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!
|
|
|
|
=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 tools 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 lists 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
|