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