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