This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlsource: Better document Configure
[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
f185f654 104Tests for basic control structures, C<if>/C<else>, C<while>, subroutines,
d0a3d6d9 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
04c692a8
DR
161=back
162
163=head2 Documentation
164
d0a3d6d9
DR
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
04c692a8
DR
168accompanying F<Module.pod> file.
169
170Finally, documentation intended for core Perl developers lives in the
171F<Porting/> directory.
172
2d947516 173=head2 Hacking tools and documentation
04c692a8
DR
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
d0a3d6d9
DR
182These are scripts which will check the source things like ANSI C
183violations, POD encoding issues, etc.
04c692a8
DR
184
185=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm>
186
d0a3d6d9
DR
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.
04c692a8
DR
190
191=item * F<podtidy>
192
d0a3d6d9
DR
193Tidies a pod file. It's a good idea to run this on a pod file you've
194patched.
04c692a8
DR
195
196=back
197
198=head2 Build system
199
80acf91d
KW
200The Perl build system on *nix-like systems starts with the F<Configure>
201script in the root directory.
04c692a8 202
d0a3d6d9
DR
203Platform-specific pieces of the build system also live in
204platform-specific directories like F<win32/>, F<vms/>, etc.
80acf91d
KW
205Windows and VMS have their own Configure-like scripts, in their
206respective directories.
04c692a8 207
80acf91d
KW
208The F<Configure> script (or a platform-specific similar script) is
209ultimately responsible for generating a F<Makefile> from F<Makefile.SH>.
04c692a8
DR
210
211The build system that Perl uses is called metaconfig. This system is
80acf91d
KW
212maintained separately from the Perl core, and knows about the
213platform-specific Configure-like scripts, as well as F<Configure>
214itself.
04c692a8 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