# Perl 5 from source: what the blead branch actually builds

> The Perl/perl5 repository is the interpreter's own C source: build system, core language and pod documentation, not the modules Perl programs lean on. Its README hands you 3 commands and a home directory prefix, and explains almost nothing about the flags inside them.

**Perl/perl5** — 🐪 The Perl programming language

- Repository: https://github.com/Perl/perl5
- Website: https://dev.perl.org/perl5/
- Stars: 2,349 · Forks: 649
- Language: Perl
- License: NOASSERTION
- Published: 2026-10-13 · Updated: 2026-10-13 · Language: en
- Canonical page: https://hysenlabs.com/projects/perl-perl5

## One tree, two audiences: running Perl and changing it

Perl began as a language for text manipulation and now carries system administration, web development, network programming and GUI development. What sits in this repository is not that story but the Perl 5 interpreter C source itself, on its default branch blead, carrying the topics cpan, hacktoberfest, perl and perl5.

Two audiences read this tree for opposite reasons. A team that only needs to run Perl code gains nothing from it, because a modern operating system already installs an interpreter. Someone who needs to change the language, add a builtin, or work out why one build handles a regular expression differently from another has nowhere else to look. The modules Perl programs lean on are third-party and live outside this repository, so the boundary here is narrow: core language, build system, pod documentation.

## Practical ahead of elegant as a written design target

Perl writes down its own design target as practical rather than beautiful, glossing that as easy to use, efficient and complete instead of tiny, elegant and minimal. Language documentation rarely states that plainly, and it changes how the rest of this tree reads. A practical target licenses breadth, which is why one interpreter carries both procedural and object-oriented code and keeps text handling in the builtins rather than in something you install afterwards. Breadth like that has a bill, and the same README calls Perl a large and complex system used for everything from knitting to rocket science.

## Configure and Makefile.SH build perl without a plain Makefile

The top level ships no plain Makefile. It carries Configure, Makefile.SH, Policy_sh.SH, EXTERN.h, INTERN.h and a Cross directory, and the documented build begins with you running Configure yourself.

```bash
./Configure -des -Dprefix=$HOME/localperl
make test
make install
```

Those 3 commands configure and compile the Perl 5 interpreter for your platform, run the regression tests, and install perl into a subdirectory named localperl inside your home directory. 2 details in that sequence decide what you end up with. The regression suite sits between compiling and installing, so a failing test stops you before the binary lands. The prefix points inside your home, which means the documented path never needs root and never writes to system directories. Porting, MANIFEST, MANIFEST.SKIP, Changes and TestInit.pm sit beside those build files, so the tree brings its own packaging and test scaffolding. Once a perl is on your PATH, the first thing the README tells you to run is a documentation tool, and what you should see is the language index for that build:

```bash
perldoc perl
```

## Twenty-nine README files, four of them translations

The top level carries 29 named README files, and their suffixes map where Perl actually has to build. aix, amiga, android, bs2000, cygwin, freebsd, haiku, hpux, hurd, irix, linux, macosx, openbsd, os2, os390, os400, plan9, qnx, riscos, solaris, synology, tru64, vms, vos and win32 are ports. README.cn, README.jp, README.ko and README.tw are not ports at all: they are translations, and a skim of that file list misses how they sit inside a platform pile.

Read the two lists together and the shape of the support cost appears. A Synology NAS, an os400 target, Haiku and vos are filed beside linux and macosx, and the README itself says only that hints exist for a wide variety of platforms, some more common than others. Twenty-five targets to keep building is the price of a language that runs everywhere, and it is why the README points you at the platform file for your own machine before anything else.

## Cloning blead compiles a branch tip with no version pin

The default branch is blead, so a clone gives you the tip of that branch at the moment you clone it, and the documented build commands compile exactly that. The same README warns that the code was current when it was made available, that the language keeps changing, and that a more recent version may fix the bug you hit or add the feature you wanted, then points at a CPAN mirror for the latest version of perl.

That tension is the decision you actually face. Building this branch means compiling the current state of a moving trunk and owning whatever it does to your programs. Taking source from a mirror such as https://www.cpan.org/src/ means a tarball of one point in that history, compiled the same way.

The instructions never name a version to pin to, so two people who both followed them can end up with different interpreters and each blame the other. The most recent recorded push is dated 2026-09-28, and pod/perldelta.pod is where the README sends you for a discussion of what changed.

## The install command explains none of its own flags

Read that install command closely and you find a gap before you compile anything. Nothing in the README unpacks the flags inside it: -des is never explained, -Dprefix is only demonstrated, and anyone who wants a customized build is handed to the INSTALL file instead. The shortest documented route to a working perl is also the least explained one.

The gap runs the other way too. No instruction covers removing the tree that lands in your home directory, and no upgrade or rollback step appears anywhere in the README. A build you dislike leaves you picking a different prefix or a different branch, never an uninstall.

Documentation quality here is uneven in a specific way. Language documentation is strong: perldoc perl opens it, pod/perlintro.pod introduces the language, pod/perldelta.pod covers what changed and pod/perlbook.pod points at the published books. Build documentation is thin by comparison, and thin exactly where an unfamiliar platform needs it.

## Where a broken build is meant to be reported

When something fails, the project hands you a filing cabinet instead of an answer. The INSTALL file holds the detailed build instructions, the platform README for your target holds the hints, and the GitHub issue tracker at https://github.com/Perl/perl5/issues takes reports once the documentation is exhausted. For a simple patch to the perl source there is a SUPER QUICK PATCH GUIDE inside pod/perlhack.pod.

The top level also holds CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md and AI_POLICY.md, and not one of those 4 files is described anywhere in the README, so what they ask of a contributor is something you open and read yourself.

For a newcomer the ordering is the trap. Installation comes first in the README, the regression suite is folded into that install, and every hard case is deferred to a file whose name you are expected to already know.

## Building your own perl against a packaged one

The alternative here is not a competing interpreter project. It is the perl your operating system already packages, or a source tarball from a CPAN mirror such as https://www.cpan.org/src/. The difference in approach is who compiles the code and where the binary lands: a packaged perl is built and updated by your distribution vendor, while a self-built one sits in a subdirectory of your home under your own account, with every flag and test result yours to interpret.

Two interpreters on one machine is the hazard worth planning around. Which perl your PATH resolves is outside anything this repository documents, so check it before you install modules into it.

Licensing travels with that build. Two options come with it, the GNU General Public License at version 1 or any later version, or the Artistic License, and the author's own reading of that choice is narrower than those labels: no Perl script falls under the GNU General Public License unless you put it there yourself, and object code linked with perl stays outside it as long as it adds only definitions of subroutines and variables.

## Conclusion

Perl belongs to teams whose production code already runs it, and to anyone who means to change the language itself. A project that merely needs an interpreter should use the perl its operating system packages instead of compiling one. Before adopting a build from this tree, read INSTALL for your target, unpack the flags hidden in the documented Configure command, and confirm the CPAN modules you rely on match the interpreter you compiled. Build it, run make test, and read pod/perldelta.pod before you trust a single module.

## FAQ

### How do I build Perl from the Perl/perl5 repository?

The README gives 3 commands: ./Configure -des -Dprefix=$HOME/localperl, then make test, then make install. That compiles perl for your platform, runs the regression tests, and installs into a subdirectory named localperl in your home directory. The flags inside that command are not unpacked there.

### Which version of Perl do I get if I clone Perl/perl5?

The tip of the default branch blead, because that is the branch the repository ships and the documented commands compile whatever is checked out. The README warns that the code was current when it was made available and sends you to a CPAN mirror for the latest version of perl.

### Where is the Perl documentation once Perl is installed?

Run perldoc perl. The README also points at pod/perlintro.pod for an introduction to the language, pod/perldelta.pod for the important changes, and pod/perlbook.pod for the list of published books.

### How do I report a Perl bug or send a small patch?

Bugs go to the GitHub issue tracker at https://github.com/Perl/perl5/issues after the documentation is exhausted. For a simple patch to the perl source, the README points at the SUPER QUICK PATCH GUIDE inside pod/perlhack.pod.

### Does Perl's GPL option put my own scripts under the GPL?

Not in the author's own interpretation, which the README spells out. Its licensing section says no Perl script falls under the GNU General Public License unless you explicitly place it there, and that object code linked with perl does not automatically fall under it either.

## Sources

- [Issues](https://github.com/Perl/perl5/issues)
- [Perl/perl5 on GitHub](https://github.com/Perl/perl5)
- [Project website](https://dev.perl.org/perl5/)
- [README](https://github.com/Perl/perl5/blob/blead/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/perl-perl5