The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Module-Build-0.4234
River stage five • 4643 direct dependents • 18190 total dependents
/ DistGen

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
revert

Other methods then change the filesystem to match the target state of the distribution:


            

              
              
clean
regen
remove

Other methods are provided for a convenience during testing. The most important is the one to enter the distribution directory:


            

              
              
chdir_in

Additional methods portably encapsulate running Build.PL and Build:


            

              
              
run_build_pl
run_build

API

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 distdir parameter 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' if name is '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.t

If 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 parameter

reset()

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::Bar

dirname()

Returns the directory where the distribution is created.


            

              
              
$dist->dirname; # e.g. t/_tmp/Simple

Functions

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'
)";