# PODNAME: CPAN::Local::Manual # ABSTRACT: How to assemble your custom repository __END__ =pod =head1 NAME CPAN::Local::Manual - How to assemble your custom repository =head1 VERSION version 0.010 =head1 INTRODUCTION CPAN::Local is a rerepository management library inspired by L, and focused on extensibility and DIY. It provides almost nothing out of the box, assumes as little as possible about what your use cases are, and mandates as little as possibles about how you should handle them. This makes it an ideal solutions when you have custom requirements and need fine-grained control over how your repository is populated. This software is still experimental and does not have all the features that one may expect. If you needly mostly standard functionality and do not care much about customization, check L below for a list of alternatives. CPAN::Local is built around roles and plugins. Roles represent different stages of the repository management process, while plugins implement these roles in order to get executed at those stages. A configuration file is used to specify which plugins should be enabled for a specific repository. There are two types of roles: those that run as part of the update process: =over =item Gather =item Prune =item Inject =item Index =item Finalise =back and standalone roles: =over =item Initialise =item Remove =item Cleanup =back These are described in detail below. =head1 ROLES =head2 Gather Gather is run at the beginning of the update process, and its purpose is to collect the list of distributions that need to be added to the repository. Plugins that implement this role might for example fetch recently updated distributions from a public CPAN mirror, apply patches and rebuild distributions from CPAN, fetch private distributions from a local path, etc. =head2 Prune Prune is run after L and removies items from the list produced by L. Plugins that implement this role might remove duplicates, fileter by distribution name or author, check for failing tests, check upload permissions, etc. =head2 Inject Inject is where distrubtion tarballs are actually copied to the respective author directory in the local repo. =head2 Index The Index stage comes after all distributions are already available in the repo, and this is when the varioius index files (or wherever the indices are stored) should get updated. =head2 Finalise The Finalise stage is executed last in the update process, and it expects the repository to be fully updated and in a consistent state. It can be used to execute any post-update actions that do not alter the state of the repo itself - i.e. sent a notification, commit to an uderlying version control system, trigger a CI run, etc. =head2 Initialise Initialise is run when creating a new repository. Plugins that implement any of the above roles should use Initialise to make sure that any resources that they require exist. It is useful for things such as creating a sceleton directory structure, creating an empty database, creating emtpy index files, or initializing a version control system. =head2 Remove Romeve is executed by the `remove` command, which requests the removal of an individual distribution from the repository. Plugins that know how to add a distribution to the repo should also know how to remove it (i.e. from the file system, from the indices, etc.) =head2 Cleanup Cleanup is executed by the `clean` command, which removes all orphaned distributions from the repository. Plugins that implement the L role should be able to report which distributions they care for, so that ones that no plugin needs anymore can be deleted. NOTE: The `clean` command is not implemented yet. =head1 BUNDLED PLUGINS The following plugins currently come with the main CPAN::Local distribution: =over =item Inject Injects a distribution into the respective author directory in the local repo. =item MailRc Creates or updates 01mailrc.txt. =item PackagesDetails Creates or updates 02packages.details.txt. =item ModList Creates an empty 03modlist.data. =item Duplicates Removes duplicate distribution (i.e. when different Gather plugins request the same distribution more than once). =back =head1 CONFIGURATION FILE Repository settings are kept in a file named C in the root of the repository. See L (shipped separately) for an usage example. =head1 USEFUL MODULES FOR PLUGIN AUTHORS =head2 Index files =over =item L Read and write 00whois.xml, 01mailrc.txt, 02packages.details.txt, and 03modlist.data =item L Read 06perms.txt =item L Write mirror.yml and mirror.json =item L Read and write RECENT-XX.json files =item L Read MIRRORED.BY =item L Read find-ls =item L Read and write checksums =back =head2 Populating a repository =over =item L Add a distribution tarball to a local mirror =item L Mirror a file from a remote repo =back =head2 Distribution metadata =over =item L Parse a distribution filename =item L Read a distribution META file =item L Use regular expressions to find distribution name, version, and provided packages =item L Use PPI to find a distribution's dependencies =item L Execute Makefile.PL/Build.PL to find a distribution's dependencies =back =head2 Testing =over =item L Build a dummy repo for testing =item L Build a dummy repo and serve it over http =back =head2 Miscellaneous =over =item L Traverse distributions in a repo =back =head1 SEE ALSO Other libraries for building private CPANs =over =item L and L =item L =item L =item L =item L =back =head1 AUTHOR Peter Shangov =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2012 by Venda, Inc.. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =cut