Skip to content

Latest commit

 

History

History
169 lines (121 loc) · 6.73 KB

distributions.pod

File metadata and controls

169 lines (121 loc) · 6.73 KB

Distributions

A distribution is a collection of one or more modules (modules) which forms a single redistributable, testable, and installable unit. Effectively it's a collection of module and metadata.

The easiest way to manage software configuration, building, distribution, testing, and installation even within your organization is to create distributions compatible with the CPAN. The conventions of the CPAN--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.

In particular, the copious amount of testing and reporting and dependency checking achieved by CPAN developers exceeds the available information and quality of work in any other language community. 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--all without human intervention.

You may never choose to release any of your code as public CPAN distributions, but you can reuse existing CPAN tools and designs as possible. The combination of intelligent defaults and customizability are likely to meet your specific needs.

Attributes of a Distribution

A distribution obviously includes one or more modules. It also includes several other files and directories:

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

  • MANIFEST, a list of all files contained in the distribution. This helps packaging tools produce an entire tarball and helps to verify that recipients of the tarball have all of the necessary files.

  • META.yml, 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.

Additionally, a well-formed distribution must contain a unique name and single version number (often taken from its primary module). Any well-formed distribution you download from the public CPAN should conform to these standards. (The CPANTS service evaluates the kwaliteeQuality is difficult to measure with heuristics. Kwalitee is the automatable relative of quality. of all CPAN distributions and recommends improvements to make them easier to install and to manage.)

CPAN Tools for Managing Distributions

The Perl 5 core includes several tools to manage distributions--not just installing them from the CPAN, but developing and managing your own:

  • CPAN.pm is the official CPAN client. While by default it installs distributions from the public CPAN, you can point it to your own repository instead of or in addition to the public repository.

  • CPANPLUS is an alternate CPAN client with a different design approach. It does some things better than CPAN.pm, but they are largely equivalent at this point. Use whichever you prefer.

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

  • ExtUtils::MakeMaker is an older, legacy tool which Module::Build intends to replace. It is still in wide use, though it is in maintenance mode and receives only the most critical bugfixes. It works with the Makefile.PL file mentioned earlier.

  • 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) are the tools used to run tests and to interpret and report their results.

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

  • App::cpanminus is a new utility which provides almost configuration-free use of the public CPAN. It fulfills 90% of your needs to find and install modules.

  • 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 is a toolkit for managing distributions by automating away common tasks. It can replace the use of Module::Build or ExtUtils::MakeMaker in many cases.

  • 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 from the CPAN. 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 should have a single, well-defined purpose. That purpose may be to process a particular type of data file or to gather together several related distributions into a single installable bundle. Decomposing your software into individual bundles 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 should have 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. Managing software effectively requires you to know when it works and how it fails if it fails.

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

local CPAN repository? - too advanced? Nice to discuss, if there's space

POD ERRORS

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

Around line 3:

A non-empty Z<>

Around line 60:

Deleting unknown formatting code N<>

Around line 144:

Deleting unknown formatting code U<>

Around line 169:

=end for without matching =begin. (Stack: [empty])