pod/perlsource.pod

   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