Skip to content

Latest commit

 

History

History
184 lines (128 loc) · 6.63 KB

distributions.pod

File metadata and controls

184 lines (128 loc) · 6.63 KB

Distributions

The easiest way to manage software configuration, building, packaging, testing, and installation is to follow the CPAN's distribution conventions. A distribution is a collection of metadata and one or more modules (modules) which forms a single redistributable, testable, and installable unit.

These guidelines--how to package a distribution, how to resolve its dependencies, where to install software, how to verify that it works, how to display documentation, how to manage a repository--have all arisen from the rough consensus of thousands of contributors working on tens of thousands of projects. A distribution built to CPAN standards can be tested on several versions of Perl 5 on several different hardware platforms within a few hours of its uploading, with errors reported automatically to authors--all without human intervention.

You may choose never to release any of your code as public CPAN distributions, but you can use CPAN tools and conventions to manage even private code. The Perl community has built amazing infrastructure; why not take advantage of it?

Attributes of a Distribution

Besides one or more modules, a distribution includes several other files and directories:

  • Build.PL or Makefile.PL, a driver program used to configure, build, test, bundle, and install the distribution.

  • MANIFEST, a list of all files contained in the distribution. This helps tools verify that a bundle is complete.

  • META.yml and/or META.json, a file containing metadata about the distribution and its dependencies.

  • README, a description of the distribution, its intent, and its copyright and licensing information.

  • lib/, the directory containing Perl modules.

  • t/, a directory containing test files.

  • Changes, a log of every change to the distribution.

A well-formed distribution must contain a unique name and single version number (often taken from its primary module). Any distribution you download from the public CPAN should conform to these standards. The public CPANTS service (http://cpants.perl.org/) evaluates each uploaded distribution against packaging guidelines and conventions and recommends improvements. Following the CPANTS guidelines doesn't mean the code works, but it does mean that the CPAN packaging tools should understand the distribution.

CPAN Tools for Managing Distributions

The Perl 5 core includes several tools to install, develop, and manage your own distributions:

  • CPAN.pm is the official CPAN client; CPANPLUS is an alternative. They are largely equivalent. While by default these clients install distributions from the public CPAN, you can point them to your own repository instead of or in addition to the public repository.

  • Module::Build is a pure-Perl tool suite for configuring, building, installing, and testing distributions. It works with Build.PL files.

  • ExtUtils::MakeMaker is a legacy tool which Module::Build intends to replace. It is still in wide use, though it is in maintenance mode and receives only critical bug fixes. It works with Makefile.PL files.

  • Test::More (testing) is the basic and most widely used testing module used to write automated tests for Perl software.

  • Test::Harness and prove (running_tests) run tests and interpret and report their results.

In addition, several non-core CPAN modules make your life easier as a developer:

  • App::cpanminus is a configuration-free CPAN client. It handles the most common cases, uses little memory, and works quickly.

  • App::perlbrew helps you to manage multiple installations of Perl 5. Install new versions of Perl 5 for testing or production, or to isolate applications and their dependencies.

  • CPAN::Mini and the cpanmini command allow you to create your own (private) mirror of the public CPAN. You can inject your own distributions into this repository and manage which versions of the public modules are available in your organization.

  • Dist::Zilla automates away common distribution tasks tasks. While it uses either Module::Build or ExtUtils::MakeMaker, it can replace your use of them directly. See http://dzil.org/ for an interactive tutorial.

  • Test::Reporter allows you to report the results of running the automated test suites of distributions you install, giving their authors more data on any failures.

Designing Distributions

The process of designing a distribution could fill a book (see Sam Tregar's Writing Perl Modules for CPAN), but a few design principles will help you. Start with a utility such as Module::Starter or Dist::Zilla. The initial cost of learning the configuration and rules may seem like a steep investment, but the benefit of having everything set up the right way (and in the case of Dist::Zilla, never going out of date) relieves you of much tedious bookkeeping.

Then consider several rules:

  • Each distribution needs a single, well-defined purpose. That purpose may even include gathering several related distributions into a single installable bundle. Decomposing your software into individual distributions allows you to manage their dependencies appropriately and to respect their encapsulation.

  • Each distribution needs a single version number. Version numbers must always increase. The semantic version policy (http://semver.org/) is sane and compatible with the Perl 5 approach.

  • Each distribution requires a well-defined API. A comprehensive automated test suite can verify that you maintain this API across versions. If you use a local CPAN mirror to install your own distributions, you can re-use the CPAN infrastructure for testing distributions and their dependencies. You get easy access to integration testing across reusable components.

  • Automate your distribution tests and make them repeatable and valuable. The CPAN infrastructure supports automated test reporting. Use it!

  • Present an effective and simple interface. Avoid the use of global symbols and default exports; allow people to use only what they need. Do not pollute their namespaces.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 3:

A non-empty Z<>

Around line 55:

Deleting unknown formatting code U<>

Around line 133:

Deleting unknown formatting code U<>

Around line 167:

Deleting unknown formatting code U<>