1=encoding utf8 2 3=for comment 4Consistent formatting of this file is achieved with: 5 perl ./Porting/podtidy pod/perlsource.pod 6 7=head1 NAME 8 9perlsource - A guide to the Perl source tree 10 11=head1 DESCRIPTION 12 13This document describes the layout of the Perl source tree. If you're 14hacking on the Perl core, this will help you find what you're looking 15for. 16 17=head1 FINDING YOUR WAY AROUND 18 19The Perl source tree is big. Here's some of the thing you'll find in 20it: 21 22=head2 C code 23 24The C source code and header files mostly live in the root of the 25source tree. There are a few platform-specific directories which 26contain C code. In addition, some of the modules shipped with Perl 27include C or XS code. 28 29See L<perlinterp> for more details on the files that make up the Perl 30interpreter, as well as details on how it works. 31 32=head2 Core modules 33 34Modules shipped as part of the Perl core live in four subdirectories. 35Two of these directories contain modules that live in the core, and two 36contain modules that can also be released separately on CPAN. Modules 37which can be released on cpan are known as "dual-life" modules. 38 39=over 4 40 41=item * F<lib/> 42 43This directory contains pure-Perl modules which are only released as 44part of the core. This directory contains I<all> of the modules and 45their tests, unlike other core modules. 46 47=item * F<ext/> 48 49Like F<lib/>, this directory contains modules which are only released 50as part of the core. Unlike F<lib/>, however, a module under F<ext/> 51generally has a CPAN-style directory- and file-layout and its own 52F<Makefile.PL>. There is no expectation that a module under F<ext/> 53will work with earlier versions of Perl 5. Hence, such a module may 54take full advantage of syntactical and other improvements in Perl 5 55blead. 56 57=item * F<dist/> 58 59This directory is for dual-life modules where the blead source is 60canonical. Note that some modules in this directory may not yet have 61been released separately on CPAN. Modules under F<dist/> should make 62an effort to work with earlier versions of Perl 5. 63 64=item * F<cpan/> 65 66This directory contains dual-life modules where the CPAN module is 67canonical. Do not patch these modules directly! Changes to these 68modules should be submitted to the maintainer of the CPAN module. Once 69those changes are applied and released, the new version of the module 70will be incorporated into the core. 71 72=back 73 74For some dual-life modules, it has not yet been determined if the CPAN 75version or the blead source is canonical. Until that is done, those 76modules should be in F<cpan/>. 77 78=head2 Tests 79 80The Perl core has an extensive test suite. If you add new tests (or new 81modules with tests), you may need to update the F<t/TEST> file so that 82the tests are run. 83 84=over 4 85 86=item * Module tests 87 88Tests for core modules in the F<lib/> directory are right next to the 89module itself. For example, we have F<lib/strict.pm> and 90F<lib/strict.t>. 91 92Tests for modules in F<ext/> and the dual-life modules are in F<t/> 93subdirectories for each module, like a standard CPAN distribution. 94 95=item * F<t/base/> 96 97Tests for the absolute basic functionality of Perl. This includes 98C<if>, basic file reads and writes, simple regexes, etc. These are run 99first in the test suite and if any of them fail, something is I<really> 100broken. 101 102=item * F<t/cmd/> 103 104Tests for basic control structures, C<if/else>, C<while>, subroutines, 105etc. 106 107=item * F<t/comp/> 108 109Tests for basic issues of how Perl parses and compiles itself. 110 111=item * F<t/io/> 112 113Tests for built-in IO functions, including command line arguments. 114 115=item * F<t/mro/> 116 117Tests for perl's method resolution order implementations (see L<mro>). 118 119=item * F<t/op/> 120 121Tests for perl's built in functions that don't fit into any of the 122other directories. 123 124=item * F<t/opbasic/> 125 126Tests for perl's built in functions which, like those in F<t/op/>, do 127not fit into any of the other directories, but which, in addition, 128cannot use F<t/test.pl>,as that program depends on functionality which 129the test file itself is testing. 130 131=item * F<t/re/> 132 133Tests for regex related functions or behaviour. (These used to live in 134t/op). 135 136=item * F<t/run/> 137 138Tests for features of how perl actually runs, including exit codes and 139handling of PERL* environment variables. 140 141=item * F<t/uni/> 142 143Tests for the core support of Unicode. 144 145=item * F<t/win32/> 146 147Windows-specific tests. 148 149=item * F<t/porting/> 150 151Tests the state of the source tree for various common errors. For 152example, it tests that everyone who is listed in the git log has a 153corresponding entry in the F<AUTHORS> file. 154 155=item * F<t/lib/> 156 157The old home for the module tests, you shouldn't put anything new in 158here. There are still some bits and pieces hanging around in here that 159need to be moved. Perhaps you could move them? Thanks! 160 161=item * F<t/x2p> 162 163A test suite for the s2p converter. 164 165=back 166 167=head2 Documentation 168 169All of the core documentation intended for end users lives in F<pod/>. 170Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> usually 171have their own documentation, either in the F<Module.pm> file or an 172accompanying F<Module.pod> file. 173 174Finally, documentation intended for core Perl developers lives in the 175F<Porting/> directory. 176 177=head2 Hacking tools and documentation 178 179The F<Porting> directory contains a grab bag of code and documentation 180intended to help porters work on Perl. Some of the highlights include: 181 182=over 4 183 184=item * F<check*> 185 186These are scripts which will check the source things like ANSI C 187violations, POD encoding issues, etc. 188 189=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm> 190 191These files contain information on who maintains which modules. Run 192C<perl Porting/Maintainers -M Module::Name> to find out more 193information about a dual-life module. 194 195=item * F<podtidy> 196 197Tidies a pod file. It's a good idea to run this on a pod file you've 198patched. 199 200=back 201 202=head2 Build system 203 204The Perl build system starts with the F<Configure> script in the root 205directory. 206 207Platform-specific pieces of the build system also live in 208platform-specific directories like F<win32/>, F<vms/>, etc. 209 210The F<Configure> script is ultimately responsible for generating a 211F<Makefile>. 212 213The build system that Perl uses is called metaconfig. This system is 214maintained separately from the Perl core. 215 216The metaconfig system has its own git repository. Please see its README 217file in L<http://perl5.git.perl.org/metaconfig.git/> for more details. 218 219The F<Cross> directory contains various files related to 220cross-compiling Perl. See F<Cross/README> for more details. 221 222=head2 F<AUTHORS> 223 224This file lists everyone who's contributed to Perl. If you submit a 225patch, you should add your name to this file as part of the patch. 226 227=head2 F<MANIFEST> 228 229The F<MANIFEST> file in the root of the source tree contains a list of 230every file in the Perl core, as well as a brief description of each 231file. 232 233You can get an overview of all the files with this command: 234 235 % perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST 236