CPAN::Local::Manual - How to assemble your custom repository
version 0.010
CPAN::Local is a rerepository management library inspired by Dist::Zilla, 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 "SEE ALSO" 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:
and standalone roles:
These are described in detail below.
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.
Prune is run after "Gather" and removies items from the list produced by "Gather". Plugins that implement this role might remove duplicates, fileter by distribution name or author, check for failing tests, check upload permissions, etc.
Inject is where distrubtion tarballs are actually copied to the respective author directory in the local repo.
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.
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.
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.
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.)
Cleanup is executed by the `clean` command, which removes all orphaned distributions from the repository. Plugins that implement the "Gather" 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.
The following plugins currently come with the main CPAN::Local distribution:
Injects a distribution into the respective author directory in the local repo.
Creates or updates 01mailrc.txt.
Creates or updates 02packages.details.txt.
Creates an empty 03modlist.data.
Removes duplicate distribution (i.e. when different Gather plugins request the same distribution more than once).
Repository settings are kept in a file named cpanlocal.ini in the root of the repository. See CPAN::Local::Plugin::DistroList (shipped separately) for an usage example.
cpanlocal.ini
Read and write 00whois.xml, 01mailrc.txt, 02packages.details.txt, and 03modlist.data
Read 06perms.txt
Write mirror.yml and mirror.json
Read and write RECENT-XX.json files
Read MIRRORED.BY
Read find-ls
Read and write checksums
Add a distribution tarball to a local mirror
Mirror a file from a remote repo
Parse a distribution filename
Read a distribution META file
Use regular expressions to find distribution name, version, and provided packages
Use PPI to find a distribution's dependencies
Execute Makefile.PL/Build.PL to find a distribution's dependencies
Build a dummy repo for testing
Build a dummy repo and serve it over http
Traverse distributions in a repo
Other libraries for building private CPANs
Peter Shangov <pshangov@yahoo.com>
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.
To install CPAN::Local, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CPAN::Local
CPAN shell
perl -MCPAN -e shell install CPAN::Local
For more information on module installation, please visit the detailed CPAN module installation guide.