NAME

Module::Build::DistVersion - Copy version numbers to secondary locations

VERSION

This document describes version 0.04 of Module::Build::DistVersion, released December 24, 2010.

WARNING

This module is deprecated. Dist::Zilla provides a much more flexible way to transform your distribution's files at release time. Dist::Zilla::Plugin::TemplateCJM is the replacement for this module, although it uses a different template syntax.

You can see an example of converting a dist from Module::Build::DistVersion to Dist::Zilla at http://github.com/madsen/module-build-distversion.

SYNOPSIS

In Build.PL:

use Module::Build;
eval 'use Module::Build::DistVersion;';
my $class = ($@ ? Module::Build->subclass(code => q{
    sub ACTION_distdir {
      print STDERR <<"END";
\a\a\a\n
This module uses Module::Build::DistVersion to automatically copy
version numbers to the appropriate places.  You might want to install
that and re-run Build.PL if you intend to create a distribution.
\n
END
      (shift @_)->SUPER::ACTION_distdir(@_);
    } })
             : 'Module::Build::DistVersion'); # if we found it
my $builder = $class->new(...);
$builder->create_build_script();

or, if you need to subclass Module::Build for other reasons:

package My_Custom_Build_Package;
use Module::Build ();
BEGIN {
  eval q{ use base 'Module::Build::DistVersion'; };
  eval q{ use base 'Module::Build'; } if $@;
  die $@ if $@;
}
sub ACTION_distdir
{
  my $self = shift @_;
  print STDERR <<"END" unless $self->isa('Module::Build::DistVersion');
\a\a\a\n
This module uses Module::Build::DistVersion to automatically copy
version numbers to the appropriate places.  You might want to install
that and re-run Build.PL if you intend to create a distribution.
\n
END
  $self->SUPER::ACTION_distdir(@_);
} # end ACTION_distdir

DESCRIPTION

Module::Build::DistVersion is a subclass of Module::Build. It modifies the distdir action to collect the version number and release date from the official locations and distribute them to the other places they should appear.

Only the module maintainer (who creates distribution files and uploads them to CPAN) needs to install Module::Build::DistVersion. Users who simply want to install the module only need to have the normal Module::Build installed.

When the distdir action is executed, Module::Build::DistVersion does the following:

1. It opens the Changes file, and finds the first version listed. The line must begin with the version number, and everything after the version number is considered to be the release date. The version number from Changes must match Module::Build's idea of the distribution version, or the process stops here with an error.

2. It reads each file matching tools/*.tt and processes it with Template Toolkit. Each template file produces a file in the main directory. For example, tools/README.tt produces README. Any number of templates may be present. If you ship the tools directory with your module (and I recommend you do), you should tell CPAN not to index it by including no_index in your Build.PL parameters:

   meta_merge => { no_index => { directory => ['tools'] } },

   Each template may use the following variables:

   changes

   The changes in the current release. This is a string containing all lines in Changes following the version/release date line up to (but not including) the next line that begins with a non-whitespace character (or end-of-file).

   You can include the changes from more than one release by using ./Build distdir changes=N (where N is the number of releases you want to list). This is useful when you make a major release immediately followed by a bugfix release.

   date

   The release date as it appeared in Changes.

   version

   The distribution's version number.

3. It executes Module::Build's normal ACTION_distdir method.

4. It finds each .pm file in the distdir's lib directory. For each file, it finds the =head1 VERSION line and replaces the first non-blank line following it. The replacement text comes from running Template Toolkit on the string returned by the DV_pod_VERSION_template method. See that method for details.

INTERFACE

Overriden Module::Build methods

Module::Build::DistVersion overrides the following methods of Module::Build:

ACTION_distdir

Operates as explained under "DESCRIPTION".

do_create_makefile_pl

Module::Build::Compat produces a Makefile.PL that requires the current build class. This override hides Module::Build::DistVersion from Module::Build::Compat, so the generated Makefile.PL will require only Module::Build.

If you subclass Module::Build::DistVersion, you may need to copy this method to your subclass.

New methods in Module::Build::DistVersion

In order to help ensure compatibility with future versions of Module::Build, all Module::Build::DistVersion-specific methods begin with DV_.

$TT = $builder->DV_new_Template()

Creates a new Template object. First, it calls Module::Build's notes method with the key DV_Template_config. If that key is defined, its value must be a hash reference containing the Template configuration. Otherwise, it uses the default configuration, which enables EVAL_PERL and POST_CHOMP.

($RELEASE_DATE, $CHANGES) = $builder->DV_check_Changes()

Extract information from Changes as described in step 1.

$builder->DV_process_templates($RELEASE_DATE, $CHANGES)

Process tools/*.tt as described in step 2.

$builder->DV_update_pod_versions($RELEASE_DATE)

Update VERSION sections as described in step 4.

$builder->DV_update_pod_version($FILENAME, $TT, $TEMPLATE, $DATA_REF)

Update a single module's VERSION section (used by DV_update_pod_versions).

$builder->DV_pod_VERSION_template($PM_FILES_REF)

Returns the template for a module's version section. First, it calls Module::Build's notes method with the key DV_pod_VERSION. If that key is defined, its value is the template.

If the Build.PL hasn't specified a custom template in notes, it returns the default template. This depends on whether the distribution has multiple .pm files: either

This document describes version [%version%] of [%module%], released [%date%].

or

This document describes version [%version%] of [%module%], released [%date%] as part of [%dist%] version [%dist_version%].

The template may use the following variables:

date

The release date as it appeared in Changes.

dist

The distribution's name.

dist_version

The distribution's version.

module

The module's name (as determined by Module::Build::ModuleInfo).

version

The module's version number (as determined by Module::Build::ModuleInfo).

($PM_FILES_REF is an array reference containing the list of .pm files to be processed.)

Normal subroutines

my $SAVE_STATS = DV_save_file_stats($FILENAME)

Constructs an object whose destructor will restore the current modification time and access permissions of $FILENAME.

DIAGNOSTICS

ERROR: Can't find any versions in Changes

We couldn't find anything that looked like a version line in Changes.

ERROR: Can't find version in %s

Module::Build::ModuleInfo couldn't find a version number in the specified file.

ERROR: Can't open %s: %s

The specified file couldn't be opened. The value of $! is included.

ERROR: Can't open %s to determine version: %s

Module::Build::ModuleInfo couldn't open the specified file. The value of $! is included.

ERROR: Can't stat %s: %s

We couldn't stat the specified file. The value of $! is included.

ERROR: Changes begins with version %s, expected version %s

The Changes file didn't begin with the version that Module::Build is creating a distribution for.

ERROR: Changes contains no history for version %s

We found the correct version in Changes, but there weren't any lines following it to describe what the changes are.

ERROR: %s has no VERSION section

We couldn't find a =head1 VERSION line in the specified file.

ERROR: %s: Unexpected line %s

We found a =head1 VERSION section in the specified file, but the next non-blank line didn't match /^This (?:section|document)/.

TEMPLATE ERROR: %s

The specified error occurred during Template Toolkit processing. See the Template documentation for more information.

CONFIGURATION AND ENVIRONMENT

All files matching tools/*.tt are assumed to be templates for DV_process_templates.

Each .pm file in lib should have a VERSION section like this:

=head1 VERSION

This section is filled in by C<Build distdir>.

Some settings can be customized by using Module::Build's notes feature. All keys beginning with DV_ are reserved by Module::Build::DistVersion. The currently implemented keys are:

DV_pod_VERSION

Used by the DV_pod_VERSION_template method.

DV_Template_config

Used by the DV_new_Template method.

For example, to customize the Template configuration, you might use

my $builder = $class->new(
  ...
  notes => { DV_Template_config => {
               INTERPOLATE => 1, POST_CHOMP => 1
           } },
);

DEPENDENCIES

Module::Build 0.28 or later, Template Toolkit 2, File::Spec, and Tie::File.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-Module-Build-DistVersion AT rt.cpan.org>, or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Module-Build-DistVersion

You can follow or contribute to Module-Build-DistVersion's development at http://github.com/madsen/module-build-distversion.

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Christopher J. Madsen.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

cpanm Module::Build::DistVersion

perl -MCPAN -e shell
install Module::Build::DistVersion