/ 
Pinto-Common-0.040_002
/ Pinto::Manual

NAME

Pinto::Manual - What Pinto is, and how to use it

VERSION

version 0.040_002

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. Distribution archives 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 custom repositories of distribution archives. These repositories can contain any distribution archives you like, and can be used with the standard CPAN toolchain.

PRIOR ART

The idea of a custom repository 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 custom 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 local distribution archives and pulling archives from other repositories. It also provides reports about the repository and its contents.

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 supports most of the operations supported by pinto-admin.

TERMINOLOGY

Before going any further, I should stop and spell out the terminology that I'm going to use.

Archive

An "archive" is the file that developers ship, which contains all their application/library code, test cases, build scripts etc. Conversely, the archive is the file that users must fetch to install the application/library. Sometimes I also refer to these as "distributions".

Package

A "package" is something inside a distribution archive that provides some unit of functionality. In Perl, packages are declared with the package keyword. Some folks call these "modules" but I try to avoid that term because it is overloaded.

Prerequisite

A "prerequisite" is a package that must be installed for the sake of another distribution archive. Sometimes I call these "dependencies".

CONCEPTS

Stack

All CPAN-like repositories have an index which maps the latest version of each package to the archive that contains it. But usually, there is only one such index. With Pinto, there can be many indexes. Each of

Pin

...

PINTO BASICS

PULLING DISTRIBUTIONS FROM THE CPAN

ADDING YOUR OWN DISTRIBUTIONS

PATCHING A CPAN DISTRIBUTION

ADVANCED PINTO

CREATING STACKS

WORKING WITH STACKS

MANAGING CHANGE

PINTO AND THE DEVELOPMENT CYCLE

PINTO AND TEAMS

PINTO AND DEPLOYMENT

PINTO AND VERSION CONTROL SYSTEMS

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.