NAME Pinto - Perl archive repository manager VERSION version 0.001 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". ATTRIBUTES config Returns the Pinto::Config object for this Pinto. You must provide one through the constructor. remote_index Returns the Pinto::Index that represents our copy of the 02packages file from a CPAN mirror (or possibly another Pinto repository). This index will include the latest versions of all the packages on the mirror. local_index Returns the Pinto::Index that represents the 02packages file for your local packages. This index will include only those packages that you've locally added to the repository. master_index Returns the Pinto::Index that is the logical combination of packages from both the remote and local indexes. See the "RULES" section below for information on how the indexes are combined. METHODS create() Creates a new empty repoistory. update(remote => 'http://cpan-mirror') Populates your repository with the latest version of all packages found on the CPAN mirror. Your locally added packages will always override those on the mirror. add(author => 'YOUR_ID', file => 'YourDist.tar.gz') Adds your own Perl archive to the repository. This could be a proprietary or personal archive, or it could be a patched version of an archive from a CPAN mirror. See the "RULES" section for information about how your archives are combined with those from the CPAN mirror. remove(author => 'YOUR_ID', package => 'Some::Package') Removes packages from the local index. When a package is removed, all other packages that were contained in the same archive are also removed. You can only remove a package if you are the author of that package. clean() Deletes any archives in the repository that are not currently represented in the master index. You will usually want to run this after performing an "update", "add", or "remove" operation. list() Prints a listing of all the packages and archives in the master index. This is basically what the 02packages file looks like. verify() Prints a listing of all the archives that are in the master index, but are not present in the repository. This is usually a sign that things have gone wrong. 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 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* "Foo". But they'll never be able to get "Bar". If this rule were not in place, someone could pull "Bar" from the repository, which would overwrite the version of "Foo" that you wanted them to have. This situation is probably rare, but it can happen if you add a locally patched version of a mirrored archive, but the mirrored archive later includes additional packages. 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". "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 remote 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.