Module::DevAid - tools to aid perl module developers

This describes version 0.24 of Module::DevAid.

  use Module::DevAid;

  my $da = Module::DevAid->new(
	dist_name => 'My::Module',
	modules => qw(lib/My/Module.pm lib/My/Module/Other.pm),
	scripts => qw(scripts/myscript),
	gen_readme => 1,
	gen_todo => 1,
	);

    $da->generate_readme_file();

Module (and script) to aid with development, by helping (and testing) auto-building of certain files, and with the steps needed in building and committing a release.

At this point this only uses the darcs or svk revision systems.

Takes a project description, either through the command line options, or via a project config file, which defaults to 'mod_devaid.conf' in the current directory.

Features:

• generates a README file from POD
• generates a TODO file from a devtodo .todo file
• auto-updates a Changes file from the revision-control system's change log.
• auto-changes version-id in module and script files
• does all of the above and tags commits for a release

    my $da = new(%args)

Create a new object. This first reads from the default config file (see config_read) and the defaults from there can be overridden with the following arguments:

changes_file => filename

Name of the Changes file to be generated. (default: Changes)

commit_todo => 1

Should we commit the TODO file we generated? If true, then will attempt to do a darcs commit on the generated TODO file. This needs to be an option because some setups need the TODO file (as well as the .todo file) to be under revision control, and others don't. (see gen_todo) (default: false)

dist_name => string

The distribution name of the project, such as the name of the module My::Module.

gen_readme => 1

Should we generate a README file? (see pod_file)

gen_todo => 1

Should we generate a TODO file? If true, the TODO file will be generated from a .todo file of the kind created by the devtodo program. (see todo_file)

modules => qw(lib/My/Module.pm)

The module files in the project. Must have their path relative to the top directory of the project.

old_version_file => filename

The file which will hold the previous version (gets updated on version_bump). (see version_file) (default: old_version.txt)

pod_file => filename

The file which contains the POD from which the README file should be generated. If not defined, defaults to the first module in the modules list.

If gen_readme is true, the README file will be generated from select sections of the pod_file file. The important ones are NAME, DESCRIPTION, INSTALLATION, REQUIRES and AUTHOR.

readme_file => filename

Name of the README file to be generated. (default: README)

version_bump_code => code reference

    my $vsub = sub {
	my $version = shift;

	# code to update files
	...
    };

    version_bump_code => $vsub

Reference to a function which will perform custom actions to automatically change the version-id. The default actions go through the modules and scripts and update anything matching a standard VERSION-setting string, and which matches a 'This describes version' string. This subroutine is for doing anything additional or different.

This is given one argument, the version string.

version_bump_files

The list of files altered by the version_bump_code, so that all the version changes can be committed at the same time. This is needed because some tests require the test files to have the version-id in them, and therefore all version commits should be done at the same time, otherwise the tests will fail, and the commits won't work.

scripts => qw(scripts/myscript)

The script files in the project. Must have their path relative to the top directory of the project.

todo_file => filename

Name of the TODO file to be generated. (default: TODO)

version_file => filename

The file from which to take the version. The version should be in the form of a standard VERSION id: number.number on a line by itself. Optionally, it can be number.number followed by a general id, for example 2.03_rc1 (default: version.txt)

version_control => string

Which version-control system is being used. The options are 'darcs' and 'svk'. (default: darcs) The version control system is used for listing and committing changes.

Set the configuration from a config file. This is called for the default config when "new" is invoked, so there's no need to call this unless you want to use an additional config file.

The information about a project can be given in a config file, which defaults to 'mod_devaid.conf' in the current directory. If you want to use a different file, set the MOD_DEVAID_CONF environment variable, and the module will use that.

The options which can be set in the config file are exactly the same as those which can be set in new.

The options are set with a 'option = value' setup. Blank lines are ignored.

For example:

    dist_name = My::Module
    modules = lib/My/Module.pm lib/My/Module/Other.pm
    gen_readme = 1

Use with CAUTION.

This defines additional code which can be used for the automatic update of version numbers in files. It has to be defined all on one line, and basically be a subroutine definition, like so:

version_bump_code = sub { my $version = shift; # code to update files ... };

The list of files altered by the version_bump_code, so that all the version changes can be committed at the same time. This is needed because some tests require the test files to have the version-id in them, and therefore all version commits should be done at the same time, otherwise the tests will fail, and the commits won't work.

Do a release, using darcs as the revision control system.

Automate the update of the version, taken from version_file and old_version_file

Get the content which would be put in a TODO file generated using devtodo .todo file in project directory.

Returns a string.

Generate TODO file using devtodo .todo file in project directory. Uses get_todo_content().

Generate README content from PoD in module. Only uses selected sections, rather than the whole thing. Returns a string.

Generate README file from PoD in module. (uses get_readme_content)

Get the changes committed since the last release. Generate a more compact format than the default.

Get the contents of what the new changes file should be. Takes version and old_version id strings as arguments. (uses get_new_changes) Returns a string.

Get the version-id of the previous release from old_version_file

Get the version-id of the up-and-coming release from version_file

These are documented for the developer only, and are not meant to be used by the outside.

Get the changes committed to darcs since the last release. Generate a more compact format than the darcs changes default.

Get the changes committed to svk since the last release. Generate a more compact format than the svk changes default.

Called by do_release. Overwrites the changes file and commits the change. (uses get_changes_content)

Called by do_release. Tags the release.

    Getopt::Long
    Pod::Usage
    Data::Dumper
    Test::More

perl(1).

To install this module, run the following commands:

    perl Build.PL
    ./Build
    ./Build test
    ./Build install

Please report any bugs or feature requests to the author.

    Kathryn Andersen (RUBYKAT)
    perlkat AT katspace dot com
    http://www.katspace.com

Copyright (c) 2004-2007 by Kathryn Andersen

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