NAME
CPAN::Local::Manual - How to assemble your custom repository
VERSION
version 0.010
INTRODUCTION
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:
- Gather
- Prune
- Inject
- Index
- Finalise
and standalone roles:
- Initialise
- Remove
- Cleanup
These are described in detail below.
ROLES
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.
Prune
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
Inject is where distrubtion tarballs are actually copied to the respective author directory in the local repo.
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.
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.
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.
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.)
Cleanup
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.
BUNDLED PLUGINS
The following plugins currently come with the main CPAN::Local distribution:
- Inject
-
Injects a distribution into the respective author directory in the local repo.
- MailRc
-
Creates or updates 01mailrc.txt.
- PackagesDetails
-
Creates or updates 02packages.details.txt.
- ModList
-
Creates an empty 03modlist.data.
- Duplicates
-
Removes duplicate distribution (i.e. when different Gather plugins request the same distribution more than once).
CONFIGURATION FILE
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.
USEFUL MODULES FOR PLUGIN AUTHORS
Index files
- CPAN::Index::API
-
Read and write 00whois.xml, 01mailrc.txt, 02packages.details.txt, and 03modlist.data
- PAUSE::Permissions
-
Read 06perms.txt
- CPAN::Indexer::Mirror
-
Write mirror.yml and mirror.json
- File::Rsync::Mirror::Recentfile
-
Read and write RECENT-XX.json files
- Parse::CPAN::MirroredBy
-
Read MIRRORED.BY
- Parse::CPAN::Distributions
-
Read find-ls
- CPAN::Checksums
-
Read and write checksums
Populating a repository
- CPAN::Inject
-
Add a distribution tarball to a local mirror
- CPAN::Cache
-
Mirror a file from a remote repo
Distribution metadata
- CPAN::DistnameInfo
-
Parse a distribution filename
- Dist::Metadata
-
Read a distribution META file
- CPAN::ParseDistribution
-
Use regular expressions to find distribution name, version, and provided packages
- Perl::PrereqScanner
-
Use PPI to find a distribution's dependencies
- Module::Depends::Intrusive
-
Execute Makefile.PL/Build.PL to find a distribution's dependencies
Testing
- CPAN::Faker
-
Build a dummy repo for testing
- CPAN::Faker::HTTPD
-
Build a dummy repo and serve it over http
Miscellaneous
- CPAN::Visitor
-
Traverse distributions in a repo
SEE ALSO
Other libraries for building private CPANs
AUTHOR
Peter Shangov <pshangov@yahoo.com>
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.