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