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 | ||
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 |