NAME Pinto - Perl archive repository manager VERSION version 0.004 DESCRIPTION You probably want to look at the documentation for pinto. This is a private module (for now) and the interface is subject to change. So the API documentation is purely for my own reference. But this document does explain what Pinto does and why it exists, so feel free to read on anyway. This is a work in progress. Comments, criticisms, and suggestions are always welcome. Feel free to contact "thaljef@cpan.org". METHODS create() Creates a new empty repository. mirror() Populates your repository with the latest version of all packages found on the CPAN mirror. Your locally added packages will always mask those pulled from the mirror. add(file => 'YourDist.tar.gz', author => 'SOMEONE') remove(package => 'Some::Package', author => 'SOMEONE') clean() list() verify() TERMINOLOGY Some of the terms around CPAN are frequently misused. So for the purpose of this document, I am going to define some terms. I am not saying that these are necessarily the "correct" definitions, but this is what I mean when I use them. package A "package" is the name that appears in a "package" statement. This is what PAUSE indexes, and this is what you usually ask cpan or cpanm to install for you. module A "module" is the name that appears in a "use" or (sometimes) "require" statement, and it always corresponds to a physical file somewhere. A module usually contains only one package, and the name of the module usually matches the name of the package. But sometimes, a module may contain many packages with completely arbitrary names. archive An "archive" is a collection of Perl modules that have been packaged in a particular structure. This is what you get when you run ""make dist"" or "./Build dist". Archives may come from a "mirror", or you may create your own. An archive is the "A" in "CPAN". repository A "repository" is a collection of archives that are organized in a particular structure, and having an index describing which packages are contained in each archive. This is where cpan and cpanm get the packages from. mirror A "mirror" is a copy of a public CPAN repository (e.g. http://cpan.perl.org). Every "mirror" is a "repository", but not every "repository" is a "mirror". RULES There are certain rules that govern how the indexes are managed. These rules are intended to ensure that folks pulling packages from your repository will always get the *right* packages (according to my definitionof "right"). Also, the rules attempt to make Pinto behave somewhat like PAUSE does. A local package always masks a mirrored package, and all other packages that are in the same archive with the mirrored package. This rule is key, so pay attention. If the CPAN mirror has an archive that contains both "Foo" and "Bar" packages, and you add your own archive that contains "Foo" package, then both the "Foo" and "Bar" mirroed packages will be removed from your index. This ensures that anyone pulling packages from your repository will always get *your* version of "Foo". But as a result, they'll never be able to get "Bar". You can never add an archive with the same name twice. Most archive-building tools will put some kind of version number in the name of the archive, so this is rarely a problem. Only the original author of a local package can add a newer version of it. Ownership is given on a first-come basis, just like PAUSE. So if "SALLY" is the first author to add local package "Foo::Bar" to the repository, then only "SALLY" can ever add that package again. Only the original author of a local package can remove it. Just like when adding new versions of a local package, only the original author can remove it. WHY IS IT CALLED "Pinto" The term "CPAN" is heavily overloaded. In some contexts, it means the CPAN module or the cpan utility. In other contexts, it means a mirror like or a site like . I wanted to avoid confusion, so I picked a name that has no connection to "CPAN" at all. "Pinto" is a nickname that I sometimes call my son, Wesley. TODO Enable plugins for visiting and filtering Implement Pinto::Store::Git Fix my Moose abuses Consider storing indexes in a DB, instead of files Automatically fetch dependecies when adding *VERY COOL* New command for listing conflicts between local and mirrored index Make file/directory permissions configurable Refine terminology: consider "distribution" instead of "archive" Need more error checking and logging Lots of tests to write THANKS Randal Schwartz - for pioneering the first mini CPAN back in 2002 Ricardo Signes - for creating CPAN::Mini, which inspired much of Pinto Shawn Sorichetti & Christian Walde - for creating CPAN::Mini::Inject SUPPORT Perldoc You can find documentation for this module with the perldoc command. perldoc Pinto Websites The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources. * Search CPAN The default CPAN search engine, useful to view POD in HTML format. * RT: CPAN's Bug Tracker The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN. * CPAN Ratings The CPAN Ratings is a website that allows community ratings and reviews of Perl modules. * CPAN Testers The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions. * CPAN Testers Matrix The CPAN Testers Matrix is a website that provides a visual way to determine what Perls/platforms PASSed for a distribution. * CPAN Testers Dependencies The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution. Bugs / Feature Requests Please report any bugs or feature requests by email to "bug-pinto at rt.cpan.org", or through the web interface at . You will be automatically notified of any progress on the request by the system. Source Code git clone https://github.com/thaljef/Pinto AUTHOR Jeffrey Ryan Thalhammer 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.