Module::Build::DistVersion - Copy version numbers to secondary locations
This document describes version 0.04 of Module::Build::DistVersion, released December 24, 2010.
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.
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
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.
distdir
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:
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.
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:
no_index
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.
./Build distdir changes=N
date
The release date as it appeared in Changes.
version
The distribution's version number.
It executes Module::Build's normal ACTION_distdir method.
ACTION_distdir
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.
=head1 VERSION
Module::Build::DistVersion overrides the following methods of Module::Build:
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.
In order to help ensure compatibility with future versions of Module::Build, all Module::Build::DistVersion-specific methods begin with DV_.
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.
DV_Template_config
EVAL_PERL
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).
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.
DV_pod_VERSION
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
notes
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:
dist
The distribution's name.
dist_version
The distribution's version.
module
The module's name (as determined by Module::Build::ModuleInfo).
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.)
$PM_FILES_REF
my $SAVE_STATS = DV_save_file_stats($FILENAME)
Constructs an object whose destructor will restore the current modification time and access permissions of $FILENAME.
$FILENAME
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.
stat
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)/.
/^This (?:section|document)/
TEMPLATE ERROR: %s
The specified error occurred during Template Toolkit processing. See the Template documentation for more information.
All files matching tools/*.tt are assumed to be templates for DV_process_templates.
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:
Used by the DV_pod_VERSION_template method.
DV_pod_VERSION_template
Used by the DV_new_Template method.
DV_new_Template
For example, to customize the Template configuration, you might use
my $builder = $class->new( ... notes => { DV_Template_config => { INTERPOLATE => 1, POST_CHOMP => 1 } }, );
Module::Build 0.28 or later, Template Toolkit 2, File::Spec, and Tie::File.
None reported.
No bugs have been reported.
Christopher J. Madsen <perl AT cjmweb.net>
<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
<bug-Module-Build-DistVersion AT rt.cpan.org>
You can follow or contribute to Module-Build-DistVersion's development at http://github.com/madsen/module-build-distversion.
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.
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.
To install Module::Build::DistVersion, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Build::DistVersion
CPAN shell
perl -MCPAN -e shell install Module::Build::DistVersion
For more information on module installation, please visit the detailed CPAN module installation guide.