The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dist-Zilla-6.007
River stage three • 655 direct dependents • 710 total dependents
184 ++
/ Dist::Zilla::Plugin::PkgVersion

NAME

Dist::Zilla::Plugin::PkgVersion - add a $VERSION to your packages

VERSION

version 6.007

SYNOPSIS

in dist.ini

  [PkgVersion]

DESCRIPTION

This plugin will add lines like the following to each package in each Perl module or program (more or less) within the distribution:

  $MyModule::VERSION = '0.001';

or

  { our $VERSION = '0.001'; }

...where 0.001 is the version of the dist, and MyModule is the name of the package being given a version. (In other words, it always uses fully-qualified names to assign versions.)

It will skip any package declaration that includes a newline between the package keyword and the package name, like:

  package
    Foo::Bar;

This sort of declaration is also ignored by the CPAN toolchain, and is typically used when doing monkey patching or other tricky things.

ATTRIBUTES

die_on_existing_version

If true, then when PkgVersion sees an existing $VERSION assignment, it will throw an exception rather than skip the file. This attribute defaults to false.

die_on_line_insertion

By default, PkgVersion looks for a blank line after each package statement. If it finds one, it inserts the $VERSION assignment on that line. If it doesn't, it will insert a new line, which means the shipped copy of the module will have different line numbers (off by one) than the source. If die_on_line_insertion is true, PkgVersion will raise an exception rather than insert a new line.

use_package

This option, if true, will not insert an assignment to $VERSION but will replace the existing package declaration with one that includes a version like:

  package Module::Name 0.001;

use_our

The idea here was to insert { our $VERSION = '0.001'; } instead of $Module::Name::VERSION = '0.001';. It turns out that this causes problems with some analyzers. Use of this feature is deprecated.

Something else will replace it in the future.

use_begin

If true, the version assignment is wrapped in a BEGIN block. This may help in rare cases, such as when DynaLoader has to be called at BEGIN time, and requires VERSION. This option should be needed rarely.

Also note that assigning to $VERSION before the module has finished compiling can lead to confused behavior with attempts to determine whether a module was successfully loaded on perl v5.8.

finder

This is the name of a FileFinder for finding modules to edit. The default value is :InstallModules and :ExecFiles; this option can be used more than once.

Other predefined finders are listed in "default_finders" in Dist::Zilla::Role::FileFinderUser. You can define your own with the [FileFinder::ByName] and [FileFinder::Filter] plugins.

SEE ALSO

Core Dist::Zilla plugins: PodVersion, AutoVersion, NextRelease.

Other Dist::Zilla plugins: OurPkgVersion inserts version numbers using our $VERSION = '...'; and without changing line numbers

AUTHOR

Ricardo SIGNES 😏 <rjbs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Ricardo SIGNES.

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