In perl.git, the branch blead has been updated <http://perl5.git.perl.org/perl.git/commitdiff/d0a3d6d981209bcd0d361ffd9b151631c4acbfa1?hp=02cbdfef7144c28c70b7a7dd188e1cd8912b19a1>
- Log ----------------------------------------------------------------- commit d0a3d6d981209bcd0d361ffd9b151631c4acbfa1 Author: Dave Rolsky <[email protected]> Date: Tue Mar 13 11:37:33 2012 -0500 Run podtidy on perlsource.pod M pod/perlsource.pod commit dde1c085b98418e83ca77e219ed1f77f858c5f34 Author: Dave Rolsky <[email protected]> Date: Tue Mar 13 11:37:18 2012 -0500 Add a missing word to perlsource.pod M pod/perlsource.pod ----------------------------------------------------------------------- Summary of changes: pod/perlsource.pod | 119 +++++++++++++++++++++++++++------------------------ 1 files changed, 63 insertions(+), 56 deletions(-) diff --git a/pod/perlsource.pod b/pod/perlsource.pod index 71057e1..16252eb 100644 --- a/pod/perlsource.pod +++ b/pod/perlsource.pod @@ -10,89 +10,94 @@ perlsource - A guide to the Perl source tree =head1 DESCRIPTION -This document describes the layout of the Perl source tree. If you're hacking -on the Perl core, this will help you find what you're looking for. +This document describes the layout of the Perl source tree. If you're +hacking on the Perl core, this will help you find what you're looking +for. =head1 FINDING YOUR WAY AROUND -The Perl source tree is big. Here's some of the thing you'll find in it: +The Perl source tree is big. Here's some of the thing you'll find in +it: =head2 C code -The C source code and header files mostly live in the root of the source -tree. There are a few platform-specific directories which contain C code. In -addition, some of the modules shipped with Perl include C or XS code. +The C source code and header files mostly live in the root of the +source tree. There are a few platform-specific directories which +contain C code. In addition, some of the modules shipped with Perl +include C or XS code. See L<perlinterp> for more details on the files that make up the Perl interpreter, as well as details on how it works. =head2 Core modules -Modules shipped as part of the Perl core live in four subdirectories. Two of -these directories contain modules that live in the core, and two contain -modules that can also be released separately on CPAN. Modules which can be -released on cpan are known as "dual-life" modules. +Modules shipped as part of the Perl core live in four subdirectories. +Two of these directories contain modules that live in the core, and two +contain modules that can also be released separately on CPAN. Modules +which can be released on cpan are known as "dual-life" modules. =over 4 =item * F<lib/> -This directory contains pure-Perl modules which are only released as part of -the core. This directory contains I<all> of the modules and their tests, -unlike other core modules. +This directory contains pure-Perl modules which are only released as +part of the core. This directory contains I<all> of the modules and +their tests, unlike other core modules. =item * F<ext/> -This directory contains XS-using modules which are only released as part of -the core. These modules generally have their F<Makefile.PL> and are laid out -more like a typical CPAN module. +This directory contains XS-using modules which are only released as +part of the core. These modules generally have their F<Makefile.PL> and +are laid out more like a typical CPAN module. =item * F<dist/> This directory is for dual-life modules where the blead source is -canonical. Note that some modules in this directory may not yet have been -released separately on CPAN. +canonical. Note that some modules in this directory may not yet have +been released separately on CPAN. =item * F<cpan/> This directory contains dual-life modules where the CPAN module is -canonical. Do not patch these modules directly! Changes to these modules -should be submitted to the maintainer of the CPAN module. Once those changes -are applied and released, the new version of the module will be incorporated -into the core. +canonical. Do not patch these modules directly! Changes to these +modules should be submitted to the maintainer of the CPAN module. Once +those changes are applied and released, the new version of the module +will be incorporated into the core. =back -For some dual-life modules, it has not yet been determined if the CPAN version -or the blead source is canonical. Until that is done, those modules should be -in F<cpan/>. +For some dual-life modules, it has not yet been determined if the CPAN +version or the blead source is canonical. Until that is done, those +modules should be in F<cpan/>. =head2 Tests The Perl core has an extensive test suite. If you add new tests (or new -modules with tests), you may need to update the F<t/TEST> file so that the -tests are run. +modules with tests), you may need to update the F<t/TEST> file so that +the tests are run. =over 4 =item * Module tests -Tests for core modules in the F<lib/> directory are right next to the module -itself. For example, we have F<lib/strict.pm> and F<lib/strict.t>. +Tests for core modules in the F<lib/> directory are right next to the +module itself. For example, we have F<lib/strict.pm> and +F<lib/strict.t>. Tests for modules in F<ext/> and the dual-life modules are in F<t/> subdirectories for each module, like a standard CPAN distribution. =item * F<t/base/> -Tests for the absolute basic functionality of Perl. This includes C<if>, basic -file reads and writes, simple regexes, etc. These are run first in the test -suite and if any of them fail, something is I<really> broken. +Tests for the absolute basic functionality of Perl. This includes +C<if>, basic file reads and writes, simple regexes, etc. These are run +first in the test suite and if any of them fail, something is I<really> +broken. =item * F<t/cmd/> -Tests for basic control structures, C<if/else>, C<while>, -subroutines, etc. +Tests for basic control structures, C<if/else>, C<while>, subroutines, +etc. =item * F<t/comp/> @@ -131,9 +136,9 @@ Windows-specific tests. =item * F<t/porting/> -Tests the state of the source tree for various common errors. For example, it -tests that everyone who is listed in the git log has a corresponding entry in -the F<AUTHORS> file. +Tests the state of the source tree for various common errors. For +example, it tests that everyone who is listed in the git log has a +corresponding entry in the F<AUTHORS> file. =item * F<t/lib/> @@ -149,9 +154,9 @@ A test suite for the s2p converter. =head2 Documentation -All of the core documentation intended for end users lives in -F<pod/>. Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> -usually have their own documentation, either in the F<Module.pm> file or an +All of the core documentation intended for end users lives in F<pod/>. +Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> usually +have their own documentation, either in the F<Module.pm> file or an accompanying F<Module.pod> file. Finally, documentation intended for core Perl developers lives in the @@ -166,18 +171,19 @@ intended to help porters work on Perl. Some of the highlights include: =item * F<check*> -These are scripts which will check the source things like ANSI C violations, -POD encoding issues, etc. +These are scripts which will check the source things like ANSI C +violations, POD encoding issues, etc. =item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm> -These files contain information on who maintains which modules. Run C<perl -Porting/Maintainers -M Module::Name> to find out more information about a -dual-life module. +These files contain information on who maintains which modules. Run +C<perl Porting/Maintainers -M Module::Name> to find out more +information about a dual-life module. =item * F<podtidy> -Tidies a pod file. It's a good idea to run this on a pod file you've patched. +Tidies a pod file. It's a good idea to run this on a pod file you've +patched. =back @@ -186,8 +192,8 @@ Tidies a pod file. It's a good idea to run this on a pod file you've patched. The Perl build system starts with the F<Configure> script in the root directory. -Platform-specific pieces of the build system also live in platform-specific -directories like F<win32/>, F<vms/>, etc. +Platform-specific pieces of the build system also live in +platform-specific directories like F<win32/>, F<vms/>, etc. The F<Configure> script is ultimately responsible for generating a F<Makefile>. @@ -195,21 +201,22 @@ F<Makefile>. The build system that Perl uses is called metaconfig. This system is maintained separately from the Perl core. -The metaconfig system has its own git repository. Please see its README file -in L<http://perl5.git.perl.org/metaconfig.git/> for more details. +The metaconfig system has its own git repository. Please see its README +file in L<http://perl5.git.perl.org/metaconfig.git/> for more details. -The F<Cross> directory contains various files related to cross-compiling -Perl. See F<Cross/README> for more details. +The F<Cross> directory contains various files related to +cross-compiling Perl. See F<Cross/README> for more details. =head2 F<AUTHORS> -This file everyone who's contributed to Perl. If you submit a patch, you -should add your name to this file as part of the patch. +This file lists everyone who's contributed to Perl. If you submit a +patch, you should add your name to this file as part of the patch. =head2 F<MANIFEST> -The F<MANIFEST> file in the root of the source tree contains a list of every -file in the Perl core, as well as a brief description of each file. +The F<MANIFEST> file in the root of the source tree contains a list of +every file in the Perl core, as well as a brief description of each +file. You can get an overview of all the files with this command: -- Perl5 Master Repository
