diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlsource.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlsource.pod | 223 |
1 files changed, 0 insertions, 223 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlsource.pod b/Master/tlpkg/tlperl/lib/pods/perlsource.pod deleted file mode 100644 index 16252eb3f07..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlsource.pod +++ /dev/null @@ -1,223 +0,0 @@ -=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 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 |