This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clarify distinction between contents of dist/ and ext/.
[perl5.git] / pod / perlsource.pod
CommitLineData
04c692a8
DR
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
d0a3d6d9
DR
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.
04c692a8
DR
16
17=head1 FINDING YOUR WAY AROUND
18
d0a3d6d9
DR
19The Perl source tree is big. Here's some of the thing you'll find in
20it:
04c692a8
DR
21
22=head2 C code
23
d0a3d6d9
DR
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.
04c692a8
DR
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
d0a3d6d9
DR
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.
04c692a8
DR
38
39=over 4
40
41=item * F<lib/>
42
d0a3d6d9
DR
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.
04c692a8
DR
46
47=item * F<ext/>
48
259799cf
JK
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.
04c692a8
DR
56
57=item * F<dist/>
58
59This directory is for dual-life modules where the blead source is
d0a3d6d9 60canonical. Note that some modules in this directory may not yet have
259799cf
JK
61been released separately on CPAN. Modules under F<dist/> should make
62an effort to work with earlier versions of Perl 5.
04c692a8
DR
63
64=item * F<cpan/>
65
66This directory contains dual-life modules where the CPAN module is
d0a3d6d9
DR
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.
04c692a8
DR
71
72=back
73
d0a3d6d9
DR
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/>.
04c692a8
DR
77
78=head2 Tests
79
80The Perl core has an extensive test suite. If you add new tests (or new
d0a3d6d9
DR
81modules with tests), you may need to update the F<t/TEST> file so that
82the tests are run.
04c692a8
DR
83
84=over 4
85
86=item * Module tests
87
d0a3d6d9
DR
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>.
04c692a8
DR
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
d0a3d6d9
DR
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.
04c692a8
DR
101
102=item * F<t/cmd/>
103
d0a3d6d9
DR
104Tests for basic control structures, C<if/else>, C<while>, subroutines,
105etc.
04c692a8
DR
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
bb52f720
JK
124=item * F<t/opbasic/>
125
259799cf
JK
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.
bb52f720 130
04c692a8
DR
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
d0a3d6d9
DR
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.
04c692a8
DR
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
d0a3d6d9
DR
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
04c692a8
DR
172accompanying F<Module.pod> file.
173
174Finally, documentation intended for core Perl developers lives in the
175F<Porting/> directory.
176
2d947516 177=head2 Hacking tools and documentation
04c692a8
DR
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
d0a3d6d9
DR
186These are scripts which will check the source things like ANSI C
187violations, POD encoding issues, etc.
04c692a8
DR
188
189=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm>
190
d0a3d6d9
DR
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.
04c692a8
DR
194
195=item * F<podtidy>
196
d0a3d6d9
DR
197Tidies a pod file. It's a good idea to run this on a pod file you've
198patched.
04c692a8
DR
199
200=back
201
202=head2 Build system
203
204The Perl build system starts with the F<Configure> script in the root
205directory.
206
d0a3d6d9
DR
207Platform-specific pieces of the build system also live in
208platform-specific directories like F<win32/>, F<vms/>, etc.
04c692a8
DR
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
d0a3d6d9
DR
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.
04c692a8 218
d0a3d6d9
DR
219The F<Cross> directory contains various files related to
220cross-compiling Perl. See F<Cross/README> for more details.
04c692a8
DR
221
222=head2 F<AUTHORS>
223
d0a3d6d9
DR
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.
04c692a8
DR
226
227=head2 F<MANIFEST>
228
d0a3d6d9
DR
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.
04c692a8
DR
232
233You can get an overview of all the files with this command:
234
235 % perl -lne 'print if /^[^\/]+\.[ch]\s+/' MANIFEST