Name Module::Provision - Create Perl distributions with VCS and selectable toolchain Version This documents version v0.18.$Rev: 2 $ 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 with Git VCS mp dist Foo::Bar 'Optional one line abstract' # Add another module cd ~/Projects/Foo-Bar mp module Foo::Bat 'Optional one line abstract' # Add a program to the bin directory mp program bar-cli 'Optional one line abstract' # Add another test script mp test 11another-one.t # Edit the project master file mp -q edit_project # Regenerate meta data files mp metadata # Update the version numbers of the project files mp update_version 0.1 0.2 # Stateful setting of the current working branch mp set_branch # 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, with Git as the VCS, installs some hooks that mimic the RCS Revision keyword expansion On first use the directory ~/.module_provision 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). They can be overridden by the values in the configuration file ~/.module_provision/module_provision.json 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 The default builder used by the create distribution method can be changed from the command line or from the configuration file 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 -5 --pretty=format:"%h %ci %s" | \ cut -d" " -f1-3,5- | cut -c1-79' The default VCS used by the create distribution methods can be changed from the command line or from the configuration file The templates contain comment lines like: # @(#)Ident: Provision.pm 2013-04-15 13:52 pjf ; These are expanded automatically by Emacs using this Lisp code: (setq time-stamp-active t time-stamp-line-limit 10 time-stamp-format " %f %04y-%02m-%02d %02H:%02M %u " time-stamp-start "Ident:" time-stamp-time-zone "UTC" time-stamp-end ";") The alias: alias ident='ack "@\(#\)"' uses the App::Ack program to implement the old SYSV R4 "ident" command The templates for the project files dist.ini, Build.PL, and Makefile.PL contain the following comments which are interpreted by Emacs: # Local Variables: # mode: perl # eval: (load-project-state "[% appdir %]") # tab-title: [% project %] # tab-width: 3 # End: Perl mode is preferred over C-Perl mode since the former has better syntax highlighting. Tabs are expanded to three spaces. The "tab-title" variable is used by Yakuake::Sessions to set the tab title for the terminal emulator. The "load-project-state" Lisp looks like this: (defun load-project-state (state-file) "Recovers the TinyDesk state from file" (let ((session-path (concat "~/.emacs.d/config/state." state-file))) (if (file-exists-p session-path) (tinydesk-recover-state session-path) (message (concat "Not found: " state-file))))) It assumes that the TinyDesk state file containing the list of files to edit for the project has been saved in ~/.emacs.d/config/state.[% appdir %]. To work on a project; change directory to the working copy, edit the project file Build.PL with Emacs, this will load all of the other files in the project into separate buffers displaying each in the tab bar. This Lisp code will load TinyDesk and turn tab bar mode on whenever a Perl file is edited: (add-hook 'perl-mode-hook '(lambda () (require 'fic-mode) (turn-on-fic-mode) (diminish 'fic-mode nil) (require 'psvn) (require 'tinydesk) (tabbar-mode t) (require 'tinyperl) (diminish 'tinyperl-mode nil))) This Lisp code will do likewise when a dist.ini file is edited: (add-hook 'conf-windows-mode-hook '(lambda () (require 'tinydesk) (tabbar-mode t))) Configuration and Environment The configuration file defaults to ~/.module_provision/module_provision.json. All of the attributes listed in Module::Provision::Config can be set from the configuration file in addition to the attributes listed in Class::Usul::Config::Programs and Class::Usul::Config. A typical file looks like; { "author": " ", "author_email": "@example.com", "author_id": "", "base": "/home//Projects", "doc_title": "Perl", "editor": "emacs", "home_page": "http://www.example.com" } Creating logs and tmp directories in ~/.module_provision will cause the log and temporary files to use them instead of /tmp Extends Module::Provision::Base. Applies these traits; "AddingFiles", "CreatingDistributions", "Rendering", "UpdatingContent", and "VCS" This class defines no attributes Subroutines/Methods cpan_upload module-provision cpan_upload By default uploads the projects current distribution to CPAN delete_cpan_files module-provision delete_cpan_files v0.1.1 Deletes a specified version of the projects distributions from CPAN dist module-provision dist Foo::Bar <'Optional one line abstract'> Create a new distribution specified by the module name on the command line dump_stash module-provision dump_stash Dump the hash ref used to render a template edit_project module-provision -q edit_project Edit the project file (one of; dist.ini, Build.PL, or Makefile.PL) in the project directory. The editor defaults to "emacs" but can be set on the command line, e.g "-o editor=vim" metadata module-provision metadata Generates the distribution metadata files init_templates module-provision init_templates Initialise the .module_provision directory and create the index.json file module module-provision module Foo::Bat <'Optional one line abstract'> Creates a new module specified by the class name on the command line program module-provision program bar-cli <'Optional one line abstract'> Creates a new program specified by the program name on the command line prereq_diffs module-provision prereq_diffs Displays a report showing which pre-requisite modules should be added to, removed from, or updated in the project file prove module-provision prove Runs the projects tests set_branch module-provision set_branch Persistently sets the branch name used on this project. If "branch_name" is omitted defaults to the branch name appropriate for the VCS being used. Edits the currently selected editor's state file for the project to reflect the changing pathnames set_cpan_password module-provision set_cpan_password Sets the password used to connect to the PAUSE server. Once used the command line program "cpan-upload" will not work since it cannot decrypt the password in the configuration file ~/.pause show_tab_title module-provision -q show_tab_title Print the tab title for the current project. Can be used like this; alias ep='mp -q edit_project ; \ yakuake_session set_tab_title_for_project $(mp -q show_tab_title)' test module-provision test 11another-one.t Creates a new test specified by the test file name on the command line update_copyright_year module-provision update_copyright_year 2013 2014 Substitutes the existing copyright year for the new copyright year in all files in the MANIFEST update_version module-provision update_version 0.1 0.2 Substitutes the existing version number for the new version number in all files in the MANIFEST. Prompts for the major/minor and bump if the version numbers are not provided Diagnostics Add "-D" to command line to turn on debug output Dependencies Module::Provision::Base Module::Provision::TraitFor::AddingFiles Module::Provision::TraitFor::CreatingDistributions Module::Provision::TraitFor::Rendering Module::Provision::TraitFor::UpdatingContent Module::Provision::TraitFor::VCS Moo 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, "" 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