{
    "mode": "man",
    "parameter": "PERLSOURCE",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/PERLSOURCE/1/json",
    "generated": "2026-06-14T12:59:57Z",
    "sections": {
        "NAME": {
            "content": "perlsource - A guide to the Perl source tree\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This document describes the layout of the Perl source tree. If you're hacking on the Perl\ncore, this will help you find what you're looking for.\n",
            "subsections": []
        },
        "FINDING YOUR WAY AROUND": {
            "content": "The Perl source tree is big. Here's some of the thing you'll find in it:\n",
            "subsections": [
                {
                    "name": "C code",
                    "content": "The C source code and header files mostly live in the root of the source tree. There are a\nfew platform-specific directories which contain C code. In addition, some of the modules\nshipped with Perl include C or XS code.\n\nSee perlinterp for more details on the files that make up the Perl interpreter, as well as\ndetails on how it works.\n"
                },
                {
                    "name": "Core modules",
                    "content": "Modules shipped as part of the Perl core live in four subdirectories.  Two of these\ndirectories contain modules that live in the core, and two contain modules that can also be\nreleased separately on CPAN. Modules which can be released on cpan are known as \"dual-life\"\nmodules.\n\n•   lib/\n\nThis directory contains pure-Perl modules which are only released as part of the core.\nThis directory contains all of the modules and their tests, unlike other core modules.\n\n•   ext/\n\nLike lib/, this directory contains modules which are only released as part of the core.\nUnlike lib/, however, a module under ext/ generally has a CPAN-style directory- and file-\nlayout and its own Makefile.PL.  There is no expectation that a module under ext/ will\nwork with earlier versions of Perl 5.  Hence, such a module may take full advantage of\nsyntactical and other improvements in Perl 5 blead.\n\n•   dist/\n\nThis directory is for dual-life modules where the blead source is canonical. Note that\nsome modules in this directory may not yet have been released separately on CPAN.\nModules under dist/ should make an effort to work with earlier versions of Perl 5.\n\n•   cpan/\n\nThis directory contains dual-life modules where the CPAN module is canonical. Do not\npatch these modules directly! Changes to these modules should be submitted to the\nmaintainer of the CPAN module. Once those changes are applied and released, the new\nversion of the module will be incorporated into the core.\n\nFor some dual-life modules, it has not yet been determined if the CPAN version or the blead\nsource is canonical. Until that is done, those modules should be in cpan/.\n"
                },
                {
                    "name": "Tests",
                    "content": "The Perl core has an extensive test suite. If you add new tests (or new modules with tests),\nyou may need to update the t/TEST file so that the tests are run.\n\n•   Module tests\n\nTests for core modules in the lib/ directory are right next to the module itself. For\nexample, we have lib/strict.pm and lib/strict.t.\n\nTests for modules in ext/ and the dual-life modules are in t/ subdirectories for each\nmodule, like a standard CPAN distribution.\n\n•   t/base/\n\nTests for the absolute basic functionality of Perl. This includes \"if\", basic file reads\nand writes, simple regexes, etc. These are run first in the test suite and if any of them\nfail, something is really broken.\n\n•   t/cmd/\n\nTests for basic control structures, \"if\"/\"else\", \"while\", subroutines, etc.\n\n•   t/comp/\n\nTests for basic issues of how Perl parses and compiles itself.\n\n•   t/io/\n\nTests for built-in IO functions, including command line arguments.\n\n•   t/mro/\n\nTests for perl's method resolution order implementations (see mro).\n\n•   t/op/\n\nTests for perl's built in functions that don't fit into any of the other directories.\n\n•   t/opbasic/\n\nTests for perl's built in functions which, like those in t/op/, do not fit into any of\nthe other directories, but which, in addition, cannot use t/test.pl,as that program\ndepends on functionality which the test file itself is testing.\n\n•   t/re/\n\nTests for regex related functions or behaviour. (These used to live in t/op).\n\n•   t/run/\n\nTests for features of how perl actually runs, including exit codes and handling of PERL*\nenvironment variables.\n\n•   t/uni/\n\nTests for the core support of Unicode.\n\n•   t/win32/\n\nWindows-specific tests.\n\n•   t/porting/\n\nTests the state of the source tree for various common errors. For example, it tests that\neveryone who is listed in the git log has a corresponding entry in the AUTHORS file.\n\n•   t/lib/\n\nThe old home for the module tests, you shouldn't put anything new in here. There are\nstill some bits and pieces hanging around in here that need to be moved. Perhaps you\ncould move them?  Thanks!\n"
                },
                {
                    "name": "Documentation",
                    "content": "All of the core documentation intended for end users lives in pod/.  Individual modules in\nlib/, ext/, dist/, and cpan/ usually have their own documentation, either in the Module.pm\nfile or an accompanying Module.pod file.\n\nFinally, documentation intended for core Perl developers lives in the Porting/ directory.\n"
                },
                {
                    "name": "Hacking tools and documentation",
                    "content": "The Porting directory contains a grab bag of code and documentation intended to help porters\nwork on Perl. Some of the highlights include:\n\n•   check*\n\nThese are scripts which will check the source things like ANSI C violations, POD encoding\nissues, etc.\n\n•   Maintainers, Maintainers.pl, and Maintainers.pm\n\nThese files contain information on who maintains which modules. Run \"perl\nPorting/Maintainers -M Module::Name\" to find out more information about a dual-life\nmodule.\n\n•   podtidy\n\nTidies a pod file. It's a good idea to run this on a pod file you've patched.\n"
                },
                {
                    "name": "Build system",
                    "content": "The Perl build system on *nix-like systems starts with the Configure script in the root\ndirectory.\n\nPlatform-specific pieces of the build system also live in platform-specific directories like\nwin32/, vms/, etc.  Windows and VMS have their own Configure-like scripts, in their\nrespective directories.\n\nThe Configure script (or a platform-specific similar script) is ultimately responsible for\ngenerating a Makefile from Makefile.SH.\n\nThe build system that Perl uses is called metaconfig. This system is maintained separately\nfrom the Perl core, and knows about the platform-specific Configure-like scripts, as well as\nConfigure itself.\n\nThe metaconfig system has its own git repository. Please see its README file in\n<https://github.com/Perl/metaconfig> for more details.\n\nThe Cross directory contains various files related to cross-compiling Perl. See Cross/README\nfor more details.\n\nAUTHORS\nThis file lists everyone who's contributed to Perl. If you submit a patch, you should add\nyour name to this file as part of the patch.\n\nMANIFEST\nThe MANIFEST file in the root of the source tree contains a list of every file in the Perl\ncore, as well as a brief description of each file.\n\nYou can get an overview of all the files with this command:\n\n% perl -lne 'print if /^[^\\/]+\\.[ch]\\s+/' MANIFEST\n\n\n\nperl v5.34.0                                 2025-07-25                                PERLSOURCE(1)"
                }
            ]
        }
    },
    "summary": "perlsource - A guide to the Perl source tree",
    "flags": [],
    "examples": [],
    "see_also": []
}