NAME
DistGen - Creates simple distributions for testing.
SYNOPSIS
use DistGen;
# create distribution and prepare to test
my $dist = DistGen->new(name => 'Foo::Bar');
$dist->chdir_in;
# change distribution files
$dist->add_file('t/some_test.t', $contents);
$dist->change_file('MANIFEST.SKIP', $new_contents);
$dist->remove_file('t/some_test.t');
$dist->regen;
# undo changes and clean up extraneous files
$dist->revert;
$dist->clean;
# exercise the command-line interface
$dist->run_build_pl();
$dist->run_build('test');
# start over as a new distribution
$dist->reset( name => 'Foo::Bar', xs => 1 );
$dist->chdir_in;USAGE
A DistGen object manages a set of files in a distribution directory.
The new() constructor initializes the object and creates an empty directory for the distribution. It does not create files or chdir into the directory. The reset() method re-initializes the object in a new directory with new parameters. It also does not create files or change the current directory.
Some methods only define the target state of the distribution. They do not make any changes to the filesystem:
add_file
change_file
change_build_pl
remove_file
revertOther methods then change the filesystem to match the target state of the distribution:
clean
regen
removeOther methods are provided for a convenience during testing. The most important is the one to enter the distribution directory:
chdir_inAdditional methods portably encapsulate running Build.PL and Build:
run_build_pl
run_buildAPI
Constructors
new()
Create a new object and an empty directory to hold the distribution's files. If no dir option is provided, it defaults to MBTest->tmpdir, which sets a different temp directory for Perl core testing and CPAN testing.
The new method does not write any files -- see "regen()" below.
my $dist = DistGen->new(
name => 'Foo::Bar',
version => '0.01',
license => 'perl',
dir => MBTest->tmpdir,
xs => 1,
no_manifest => 0,
);The parameters are as follows.
- name
-
The name of the module this distribution represents. The default is 'Simple'. This should be a "Foo::Bar" (module) name, not a "Foo-Bar" dist name.
- version
-
The version string that will be set. (E.g.
our $VERSION = 0.01) Note -- to put this value in quotes, add those to the string.version => q{'0.01_01'} - license
-
The license string that will be set in Build.PL. Defaults to 'perl'.
- dir
-
The (parent) directory in which to create the distribution directory. The distribution will be created under this according to
distdirparameter below. Defaults to a temporary directory.$dist = DistGen->new( dir => '/tmp/MB-test' ); $dist->regen; # distribution files have been created in /tmp/MB-test/Simple - distdir
-
The name of the distribution directory to create. Defaults to the dist form of
name, e.g. 'Foo-Bar' ifnameis 'Foo::Bar'. - xs
-
If true, generates an XS based module.
- no_manifest
-
If true,
regen()will not create a MANIFEST file.
The following files are added as part of the default distribution:
Build.PL
lib/Simple.pm # based on name parameter
t/basic.tIf an XS module is generated, Simple.pm and basic.t are different and the following files are also added:
typemap
lib/Simple.xs # based on name parameterreset()
The reset method re-initializes the object as if it were generated from a fresh call to new. It takes the same optional parameters as new.
$dist->reset( name => 'Foo::Bar', xs => 0 );Adding and editing files
Note that $filename should always be specified with unix-style paths, and are relative to the distribution root directory, e.g. lib/Module.pm.
No changes are made to the filesystem until the distribution is regenerated.
add_file()
Add a $filename containing $content to the distribution.
$dist->add_file( $filename, $content );change_file()
Changes the contents of $filename to $content. No action is performed until the distribution is regenerated.
$dist->change_file( $filename, $content );change_build_pl()
A wrapper around change_file specifically for setting Build.PL. Instead of file $content, it takes a hash-ref of Module::Build constructor arguments:
$dist->change_build_pl(
{
module_name => $dist->name,
dist_version => '3.14159265',
license => 'perl',
create_readme => 1,
}
);get_file
Retrieves the target contents of $filename.
$content = $dist->get_file( $filename );remove_file()
Removes $filename from the distribution.
$dist->remove_file( $filename );revert()
Returns the object to its initial state, or given a $filename it returns that file to its initial state if it is one of the built-in files.
$dist->revert;
$dist->revert($filename);Changing the distribution directory
These methods immediately affect the filesystem.
regen()
Regenerate all missing or changed files. Also deletes any files flagged for removal with remove_file().
$dist->regen(clean => 1);If the optional clean argument is given, it also calls clean. These can also be chained like this, instead:
$dist->clean->regen;clean()
Removes any files that are not part of the distribution.
$dist->clean;remove()
Changes back to the original directory and removes the distribution directory (but not the temporary directory set during new()).
$dist = DistGen->new->chdir->regen;
# ... do some testing ...
$dist->remove->chdir_in->regen;
# ... do more testing ...This is like a more aggressive form of clean. Generally, calling clean and regen should be sufficient.
Changing directories
chdir_in
Change directory into the dist root.
$dist->chdir_in;chdir_original
Returns to whatever directory you were in before chdir_in() (regardless of the cwd.)
$dist->chdir_original;Command-line helpers
These use Module::Build->run_perl_script() to ensure that Build.PL or Build are run in a separate process using the current perl interpreter. (Module::Build is loaded on demand). They also ensure appropriate naming for operating systems that require a suffix for Build.
run_build_pl
Runs Build.PL using the current perl interpreter. Any arguments are passed on the command line.
$dist->run_build_pl('--quiet');run_build
Runs Build using the current perl interpreter. Any arguments are passed on the command line.
$dist->run_build(qw/test --verbose/);Properties
name()
Returns the name of the distribution.
$dist->name: # e.g. Foo::Bardirname()
Returns the directory where the distribution is created.
$dist->dirname; # e.g. t/_tmp/SimpleFunctions
undent()
Removes leading whitespace from a multi-line string according to the amount of whitespace on the first line.
my $string = undent(" foo(\n bar => 'baz'\n )");
$string eq "foo(
bar => 'baz'
)";