Name

Module::Provision - Create Perl distributions with VCS and selectable toolchain

Version

This documents version v0.3.$Rev: 44 $ of Module::Provision

Synopsis

   # To reduce typing define a shell alias
   alias mp='module_provision --base ~/Projects'

   # Create a new distribution in your Projects directory
   mp dist Foo::Bar

   # Add another module
   cd ~/Projects/Foo-Bar
   mp module Foo::Bat

   # Add a program to the bin directory
   mp program foo-cli

   # Add another test script
   mp test 11another-one.t

   # Command line help
   mp -? | -H | -h [sub-command] | list_methods | dump_self

Description

Module::Provision is used to create a skeletal CPAN distribution, including basic builder scripts, tests, documentation, and module code. It creates a VCS repository and, in the Git case, installs some hooks that mimic the RCS Revision keyword expansion

On first use the directory ~/.code_templates is created and populated with templates and an index file index.json. The author name, id, and email are derived from the system (the environment variables AUTHOR and EMAIL take precedence) and stored in the author, author_id, and author_email files

If the default builder (MB) is used, then the project file Build.PL loads inc::Bob which instantiates an inline subclass of Module::Build. The code for the subclass is in inc::SubClass. The file inc::CPANTesting allows for fine grained control over which tests are run by which CPAN Testing smokers

If the Git VCS is used precommit and commit-msg hooks are installed. The precommit hook will expand the RCS Revision keyword in files on the master branch if the file .distribution_name.rev exists in the parent of the working tree. The precommit hook will also update the version number and date/time stamp in the change log (Changes). The commit-msg hook will extract the first comment line from the change log and use it as the commit message header. The remainder of the commit message (if any) is used as the commit message body. This means that so long as one detail line is added to the change log no other commit message text is required. The following makes for a suitable git log alias:

   alias gl='git log -10 --pretty=format:"%h %ci %s"'

Configuration and Environment

Defines the following list of attributes which can be set from the command line;

base

The directory which will contain the new project. Defaults to the users home directory

branch

The name of the initial branch to create. Defaults to master for Git and trunk for SVN

builder

Which of the three build systems to use. Defaults to MB, which is Module::Build. Can be DZ for Dist::Zilla or MI for Module::Install

force

Overwrite the output files if they already exist

license

The name of the license used on the project. Defaults to perl

novcs

Do not create or use a VCS. Defaults to FALSE. Used by the test script

perms

Permissions used to create files. Defaults to 644. Directories and programs have the execute bit turned on if the corresponding read bit is on

project

The class name of the new project. Should be the first extra argument on the command line

repository

Name of the directory containing the SVN repository. Defaults to repository

templates

Location of the code templates in the users home directory. Defaults to .code_templates

vcs

The version control system to use. Defaults to git, can be svn

Subroutines/Methods

The following methods constitute the public API

create_directories

   $self->create_directories( $args );

Creates the required directories for the new distribution

dist

   $exit_code = $self->dist;

Create a new distribution specified by the module name on the command line

init_templates

   $exit_code = $self->init_templates;

Initialise the .code_templates directory and create the index.json file

module

   $exit_code = $self->module;

Creates a new module specified by the class name on the command line

post_hook

   $self->post_hook( $args );

Runs after the new distribution has been created

pre_hook

   $args = $self->pre_hook( {} );

Runs before the new distribution is created

program

   $exit_code = $self->program;

Creates a new program specified by the program name on the command line

render_templates

   $self->render_templates( $args );

Renders the list of templates in <$args-templates>> be repeatedly calling calling Template passing in the stash

test

   $exit_code = $self->test;

Creates a new test specified by the test file name on the command line

Diagnostics

Add -D to command line to turn on debug output

Dependencies

Class::Usul

Date::Format

File::DataClass

File::ShareDir

Module::Metadata

Perl::Version

Pod::Markdown

Template

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

There are no known bugs in this module. Please report problems to http://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Provision. Source code is on Github git://github.com/pjfl/Module-Provision.git. Patches and pull requests are welcome

Acknowledgements

Larry Wall - For the Perl programming language

Module::Starter - For some of the documentation and tests

Author

Peter Flanigan, <pjfl@cpan.org>

License and Copyright

Copyright (c) 2013 Peter Flanigan. All rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE

cpanm Module::Provision

perl -MCPAN -e shell
install Module::Provision