summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlsource.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlsource.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlsource.pod216
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