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>/C<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=back 162 163=head2 Documentation 164 165All of the core documentation intended for end users lives in F<pod/>. 166Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> usually 167have their own documentation, either in the F<Module.pm> file or an 168accompanying F<Module.pod> file. 169 170Finally, documentation intended for core Perl developers lives in the 171F<Porting/> directory. 172 173=head2 Hacking tools and documentation 174 175The F<Porting> directory contains a grab bag of code and documentation 176intended to help porters work on Perl. Some of the highlights include: 177 178=over 4 179 180=item * F<check*> 181 182These are scripts which will check the source things like ANSI C 183violations, POD encoding issues, etc. 184 185=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm> 186 187These files contain information on who maintains which modules. Run 188C<perl Porting/Maintainers -M Module::Name> to find out more 189information about a dual-life module. 190 191=item * F<podtidy> 192 193Tidies a pod file. It's a good idea to run this on a pod file you've 194patched. 195 196=back 197 198=head2 Build system 199 200The Perl build system on *nix-like systems starts with the F<Configure> 201script in the root directory. 202 203Platform-specific pieces of the build system also live in 204platform-specific directories like F<win32/>, F<vms/>, etc. 205Windows and VMS have their own Configure-like scripts, in their 206respective directories. 207 208The F<Configure> script (or a platform-specific similar script) is 209ultimately responsible for generating a F<Makefile> from F<Makefile.SH>. 210 211The build system that Perl uses is called metaconfig. This system is 212maintained separately from the Perl core, and knows about the 213platform-specific Configure-like scripts, as well as F<Configure> 214itself. 215 216The metaconfig system has its own git repository. Please see its README 217file in L<https://github.com/Perl/metaconfig> 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