Debian Codegraph @

upstream/mageia-cauldron/man1/perlsource.1

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