NAME
Pinto::Manual - What Pinto is, and how to use it
VERSION
version 0.037
DESCRIPTION
This document is an overview of the Pinto tool suite, and a general guide for using Pinto in the real world. It is a work-in-progress, so feel free to send suggestions to the author.
GOALS
Pinto has two primary goals. First, Pinto seeks to address the problem of instability in the CPAN mirrors. Distributions are constantly added and removed from the CPAN, so if you use it to build a system or application, you may not get the same result twice. Second, Pinto seeks to enable developers to use the CPAN toolchain for building, testing, and dependency management of their own local software, even if they never plan to release it to the CPAN.
Pinto accomplishes these goals by providing a suite of tools for creating and managing your own CPAN-like repositories. These repositories can contain any distributions you like, and can be used with the standard CPAN toolchain.
PRIOR ART
The idea of a private CPAN is not new. Randal Schwartz presented the idea back in 2002. Subsequently, modules like CPAN::Site and CPAN::Mini were released. More recently, OrePAN and MyCPAN::App::DPAN have emerged as well.
Over the last few years, I personally used various combinations of those modules to create private CPAN repositories at several organizations. But they always required some wrapping and/or glue to make them usable in the development cycle. And none of them seemed to be designed for extension.
I wanted a suite of tools that would work out-of-the-box, and would accommodate a fairly wide range of use cases. Hence, Pinto was born.
COMPONENTS
The Pinto suite consists of a core set of libraries and three command line utilities. Each of these utilities ships in a separate distribution, so you don't have to install the whole kit if you're only going to use a subset of the Pinto suite. However, you can install Task::Pinto if you'd like to get everything in one shot.
pinto-admin
pinto-admin is a utility for creating and managing a Pinto repository. It supports the core operations of adding and removing local distributions, as well as mirroring and importing foreign distributions from other repositories.
pinto-server
pinto-server provides a web service interface to your Pinto repository. This allows multiple (possibly remote) developers to manage a central repository. pinto-server also functions as the backend server to installer clients like cpan, cpanp, and cpanm.
pinto-remote
pinto-remote is a utility for interacting with a remote Pinto repository (via pinto-server). It provides a subset of the operations supported by pinto-admin.
USE CASES
All use cases revolve around the basic functions of adding and removing distributions from the repository, but there are differences in how you select and obtain those distributions. I have used Pinto (or can imagine using it) in the following scenarios:
SNAPSHOT OF CPAN MIRROR
You can use Pinto to create a stable snapshot of a CPAN mirror. This can easily be done with the mirror command.
$> pinto-admin -r /my/cpan create
$> pinto-admin -r /my/cpan mirrorThis creates a repository that contains the latest versions of all packages on the CPAN (this may take several hours the first time you do it). Now, when you point your installer client at /my/cpan you can now build your dependency stack and get the same result over and over.
UPGRADING THE ENTIRE SNAPSHOT
Any time you want to upgrade to the latest version of all your dependencies, you can run the mirror command again (it will be much faster now). But let's suppose that the new Foo-2.0 package breaks your application. You can remove its distribution by using the remove command like so:
$> pinto-admin -r /my/cpan remove A/AU/AUTHOR/Foo-2.0.tar.gzNow, when you build your dependency stack, you'll get Foo-1.0 (or whatever version you had before), and all your other dependencies will be the latest ones available.
UPGRADING SELECTED PACKAGES
Suppose you just want to upgrade package Bar to version 3.0, which was just released to the CPAN. You can do that with the import command like this:
$> pinto-admin -r /my/cpan import Bar-3.0This will bring version 3.0 of package Bar into your repository, plus any additional dependencies that it requires.
ADDING YOUR OWN DISTRIBUTIONS
If you package your application into one or more CPAN-style distributions, then you can also put your own code in the Pinto repository with the add command:
$> pinto-admin -r /my/cpan add /path/to/My-Dist-1.4.tar.gzPinto will index your distribution (just like PAUSE) and add it to the repository. By default, Pinto will also import all the dependencies that you've declared in your distribution.
Once again, you can point your installer client at /my/cpan to install your distribution, and it will unwind and install all the dependencies for you, using the Pinto repository as the source.
PATCHING A CPAN DISTRIBUTION
Let's suppose that your application depends on Plack, and you've found a critical bug in it. For whatever reason, the author of Plack can't or won't fix the bug and you decide to patch the code yourself. So after you've downloaded the distribution (or perhaps made a copy of the one in your repository), patched the code and packaged it back up, you can add it to your repository with the add command:
$> pinto-admin -r /my/cpan add ~/tmp/Plack-0.89-PATCHED.tar.gzThis is called adding a "local" distribution. The packages in a local distribution are always considered newer than the same package in a "foreign" distribution. So when clients request the "Plack" package from your repository, they will always get your patched version, even if the repository contains a foreign version with a higher version number.
Eventually, the author of Plack finally fixes that bug and releases a new distribution. You can pull that distribution into your repository (and the latest version of all the other distributions) by running the mirror command. Finally, you can remove your patched version with the remove command:
$> pinto-admin -r /my/cpan remove Plack-0.89-PATCHED.tar.gzClients requesting the "Plack" package will no longer get your patched version, but will get the latest version that was pulled from the CPAN instead.
PINTO AND THE DEVELOPMENT CYCLE
Even though *the* CPAN has been around for many years, the concept of using CPAN-like infrastructure for private development is still relatively novel. So for many folks (including me), it isn't immediately clear how to incorporate Pinto with the development cycle.
The following describes several usage scenarios for Pinto. Some come from my own experience, but some are just theoretical. If you are using Pinto (or some other variety of private CPAN) in other ways, please let me know so that I can document it here.
USAGE STRATEGIES
Given the above use cases, I see four basic strategies for using Pinto, although I'm sure folks will probably come up with others...
Local Distributions Only
The first strategy is to use Pinto purely as a repository for local distributions. These distributions could be private or public, or a mix of both. But the repository contains only the distributions that you explicitly add to it.
Snapshots Of The Public CPAN
The second strategy is to use Pinto as snapshot of the public CPAN. In this strategy, your repository contains the current version of every package indexed on a public CPAN, as-of the time you made the snapshot. You may choose to periodically update the snapshot.
CPAN Plus Local Distributions
The third strategy is to combine a snapshot of the public CPAN with your own local distributions. In this scenario, your Pinto repository contains all of the CPAN distributions plus your local ones, and your local ones always take precedence over those you got from the public CPAN.
Project-specific Repository
The fourth (and probably most useful) strategy is to start with an empty Pinto repository and organically add your local distributions and import their dependencies as the project evolves over time. This keeps your repository small and focused.
PINTO AND TEAMS
PINTO AND DEPLOYMENT
PINTO AND VERSION CONTROL SYSTEMS
One of the major motivations behind Pinto was to integrate with version control systems (VCS). Changing dependencies are a frequent cause of application failure (either in development or, gasp, in production). So it is natural to want a mechanism to rollback your dependencies to a "known-good-state". This is a natural fit for VCS.
Pinto integrates with VCS by committing (and optionally tagging) changes to your repository. Pinto does not provide any direct mechanism for branching/merging/reverting your VCS. Nor does Pinto know which revision of your repository is the "right" one. It is still up to you to figure that out. But since everything Pinto does is always in your VCS, you should have everything you need to solve those problems.
PINTO AND OTHER PACKAGING SYSTEMS
PINTO AND OTHER CPAN TOOLS
EXTENDING PINTO
FUTURE PLANS
AUTHOR
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Imaginative Software Systems.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.