Pinto::Manual - What Pinto is, and how to use it
version 0.038
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.
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.
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.
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 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 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 is a utility for interacting with a remote Pinto repository (via pinto-server). It provides a subset of the operations supported by pinto-admin.
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:
You can use Pinto to create a stable snapshot of a CPAN mirror. This can easily be done with the mirror command.
mirror
$> pinto-admin -r /my/cpan create $> pinto-admin -r /my/cpan mirror
This 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.
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:
Foo-2.0
remove
$> pinto-admin -r /my/cpan remove A/AU/AUTHOR/Foo-2.0.tar.gz
Now, 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.
Foo-1.0
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:
import
$> pinto-admin -r /my/cpan import Bar-3.0
This will bring version 3.0 of package Bar into your repository, plus any additional dependencies that it requires.
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:
add
$> pinto-admin -r /my/cpan add /path/to/My-Dist-1.4.tar.gz
Pinto 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.
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.gz
This 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.gz
Clients requesting the "Plack" package will no longer get your patched version, but will get the latest version that was pulled from the CPAN instead.
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.
Given the above use cases, I see four basic strategies for using Pinto, although I'm sure folks will probably come up with others...
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.
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.
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.
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.
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.
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
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.
To install Pinto::Common, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Pinto::Common
CPAN shell
perl -MCPAN -e shell install Pinto::Common
For more information on module installation, please visit the detailed CPAN module installation guide.