Debian Codegraph @

upstream/debian-unstable/man1/perlsource.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLSOURCE 1"
58 .TH PERLSOURCE 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlsource \- A guide to the Perl source tree
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 This document describes the layout of the Perl source tree. If you're
68 hacking on the Perl core, this will help you find what you're looking
69 for.
70 .SH "FINDING YOUR WAY AROUND"
71 .IX Header "FINDING YOUR WAY AROUND"
72 The Perl source tree is big. Here's some of the thing you'll find in
73 it:
74 .SS "C code"
75 .IX Subsection "C code"
76 The C source code and header files mostly live in the root of the
77 source tree. There are a few platform-specific directories which
78 contain C code. In addition, some of the modules shipped with Perl
79 include C or XS code.
80 .PP
81 See perlinterp for more details on the files that make up the Perl
82 interpreter, as well as details on how it works.
83 .SS "Core modules"
84 .IX Subsection "Core modules"
85 Modules shipped as part of the Perl core live in four subdirectories.
86 Two of these directories contain modules that live in the core, and two
87 contain modules that can also be released separately on CPAN. Modules
88 which can be released on cpan are known as "dual-life" modules.
89 .IP \(bu 4
90 \&\fIlib/\fR
91 .Sp
92 This directory contains pure-Perl modules which are only released as
93 part of the core. This directory contains \fIall\fR of the modules and
94 their tests, unlike other core modules.
95 .IP \(bu 4
96 \&\fIext/\fR
97 .Sp
98 Like \fIlib/\fR, this directory contains modules which are only released
99 as part of the core. Unlike \fIlib/\fR, however, a module under \fIext/\fR
100 generally has a CPAN-style directory\- and file-layout and its own
101 \&\fIMakefile.PL\fR. There is no expectation that a module under \fIext/\fR
102 will work with earlier versions of Perl 5. Hence, such a module may
103 take full advantage of syntactical and other improvements in Perl 5
104 blead.
105 .IP \(bu 4
106 \&\fIdist/\fR
107 .Sp
108 This directory is for dual-life modules where the blead source is
109 canonical. Note that some modules in this directory may not yet have
110 been released separately on CPAN. Modules under \fIdist/\fR should make
111 an effort to work with earlier versions of Perl 5.
112 .IP \(bu 4
113 \&\fIcpan/\fR
114 .Sp
115 This directory contains dual-life modules where the CPAN module is
116 canonical. Do not patch these modules directly! Changes to these
117 modules should be submitted to the maintainer of the CPAN module. Once
118 those changes are applied and released, the new version of the module
119 will be incorporated into the core.
120 .PP
121 For some dual-life modules, it has not yet been determined if the CPAN
122 version or the blead source is canonical. Until that is done, those
123 modules should be in \fIcpan/\fR.
124 .SS Tests
125 .IX Subsection "Tests"
126 The Perl core has an extensive test suite. If you add new tests (or new
127 modules with tests), you may need to update the \fIt/TEST\fR file so that
128 the tests are run.
129 .IP \(bu 4
130 Module tests
131 .Sp
132 Tests for core modules in the \fIlib/\fR directory are right next to the
133 module itself. For example, we have \fIlib/strict.pm\fR and
134 \&\fIlib/strict.t\fR.
135 .Sp
136 Tests for modules in \fIext/\fR and the dual-life modules are in \fIt/\fR
137 subdirectories for each module, like a standard CPAN distribution.
138 .IP \(bu 4
139 \&\fIt/base/\fR
140 .Sp
141 Tests for the absolute basic functionality of Perl. This includes
142 \&\f(CW\*(C`if\*(C'\fR, basic file reads and writes, simple regexes, etc. These are run
143 first in the test suite and if any of them fail, something is \fIreally\fR
144 broken.
145 .IP \(bu 4
146 \&\fIt/cmd/\fR
147 .Sp
148 Tests for basic control structures, \f(CW\*(C`if\*(C'\fR/\f(CW\*(C`else\*(C'\fR, \f(CW\*(C`while\*(C'\fR, subroutines,
149 etc.
150 .IP \(bu 4
151 \&\fIt/comp/\fR
152 .Sp
153 Tests for basic issues of how Perl parses and compiles itself.
154 .IP \(bu 4
155 \&\fIt/io/\fR
156 .Sp
157 Tests for built-in IO functions, including command line arguments.
158 .IP \(bu 4
159 \&\fIt/mro/\fR
160 .Sp
161 Tests for perl's method resolution order implementations (see mro).
162 .IP \(bu 4
163 \&\fIt/op/\fR
164 .Sp
165 Tests for perl's built in functions that don't fit into any of the
166 other directories.
167 .IP \(bu 4
168 \&\fIt/opbasic/\fR
169 .Sp
170 Tests for perl's built in functions which, like those in \fIt/op/\fR, do
171 not fit into any of the other directories, but which, in addition,
172 cannot use \fIt/test.pl\fR,as that program depends on functionality which
173 the test file itself is testing.
174 .IP \(bu 4
175 \&\fIt/re/\fR
176 .Sp
177 Tests for regex related functions or behaviour. (These used to live in
178 t/op).
179 .IP \(bu 4
180 \&\fIt/run/\fR
181 .Sp
182 Tests for features of how perl actually runs, including exit codes and
183 handling of PERL* environment variables.
184 .IP \(bu 4
185 \&\fIt/uni/\fR
186 .Sp
187 Tests for the core support of Unicode.
188 .IP \(bu 4
189 \&\fIt/win32/\fR
190 .Sp
191 Windows-specific tests.
192 .IP \(bu 4
193 \&\fIt/porting/\fR
194 .Sp
195 Tests the state of the source tree for various common errors. For
196 example, it tests that everyone who is listed in the git log has a
197 corresponding entry in the \fIAUTHORS\fR file.
198 .IP \(bu 4
199 \&\fIt/lib/\fR
200 .Sp
201 The old home for the module tests, you shouldn't put anything new in
202 here. There are still some bits and pieces hanging around in here that
203 need to be moved. Perhaps you could move them? Thanks!
204 .SS Documentation
205 .IX Subsection "Documentation"
206 All of the core documentation intended for end users lives in \fIpod/\fR.
207 Individual modules in \fIlib/\fR, \fIext/\fR, \fIdist/\fR, and \fIcpan/\fR usually
208 have their own documentation, either in the \fIModule.pm\fR file or an
209 accompanying \fIModule.pod\fR file.
210 .PP
211 Finally, documentation intended for core Perl developers lives in the
212 \&\fIPorting/\fR directory.
213 .SS "Hacking tools and documentation"
214 .IX Subsection "Hacking tools and documentation"
215 The \fIPorting\fR directory contains a grab bag of code and documentation
216 intended to help porters work on Perl. Some of the highlights include:
217 .IP \(bu 4
218 \&\fIcheck*\fR
219 .Sp
220 These are scripts which will check the source things like ANSI C
221 violations, POD encoding issues, etc.
222 .IP \(bu 4
223 \&\fIMaintainers\fR, \fIMaintainers.pl\fR, and \fIMaintainers.pm\fR
224 .Sp
225 These files contain information on who maintains which modules. Run
226 \&\f(CW\*(C`perl Porting/Maintainers \-M Module::Name\*(C'\fR to find out more
227 information about a dual-life module.
228 .IP \(bu 4
229 \&\fIpodtidy\fR
230 .Sp
231 Tidies a pod file. It's a good idea to run this on a pod file you've
232 patched.
233 .SS "Build system"
234 .IX Subsection "Build system"
235 The Perl build system on *nix\-like systems starts with the \fIConfigure\fR
236 script in the root directory.
237 .PP
238 Platform-specific pieces of the build system also live in
239 platform-specific directories like \fIwin32/\fR, \fIvms/\fR, etc.
240 Windows and VMS have their own Configure-like scripts, in their
241 respective directories.
242 .PP
243 The \fIConfigure\fR script (or a platform-specific similar script) is
244 ultimately responsible for generating a \fIMakefile\fR from \fIMakefile.SH\fR.
245 .PP
246 The build system that Perl uses is called metaconfig. This system is
247 maintained separately from the Perl core, and knows about the
248 platform-specific Configure-like scripts, as well as \fIConfigure\fR
249 itself.
250 .PP
251 The metaconfig system has its own git repository. Please see its README
252 file in <https://github.com/Perl/metaconfig> for more details.
253 .PP
254 The \fICross\fR directory contains various files related to
255 cross-compiling Perl. See \fICross/README\fR for more details.
256 .SS \fIAUTHORS\fP
257 .IX Subsection "AUTHORS"
258 This file lists everyone who's contributed to Perl. If you submit a
259 patch, you should add your name to this file as part of the patch.
260 .SS \fIMANIFEST\fP
261 .IX Subsection "MANIFEST"
262 The \fIMANIFEST\fR file in the root of the source tree contains a list of
263 every file in the Perl core, as well as a brief description of each
264 file.
265 .PP
266 You can get an overview of all the files with this command:
267 .PP
268 .Vb 1
269 \& % perl \-lne \*(Aqprint if /^[^\e/]+\e.[ch]\es+/\*(Aq MANIFEST
270 .Ve