Author: dagolden
Date: Sat Aug 15 05:13:48 2009
New Revision: 13197
Modified:
Module-Build/trunk/t/lib/DistGen.pm
Module-Build/trunk/t/metadata2.t
Log:
tweaked DistGen and expanded its documentation
Modified: Module-Build/trunk/t/lib/DistGen.pm
==============================================================================
--- Module-Build/trunk/t/lib/DistGen.pm (original)
+++ Module-Build/trunk/t/lib/DistGen.pm Sat Aug 15 05:13:48 2009
@@ -79,7 +79,7 @@
$options{dir} ||= Cwd::cwd();
my %data = (
- skip_manifest => 0,
+ no_manifest => 0,
xs => 0,
%options,
);
@@ -333,7 +333,7 @@
}
my $manifest = File::Spec->catfile( $dist_dirname, 'MANIFEST' );
- unless ( $self->{skip_manifest} ) {
+ unless ( $self->{no_manifest} ) {
if ( -e $manifest ) {
1 while unlink( $manifest );
}
@@ -502,20 +502,50 @@
use DistGen;
- my $dist = DistGen->new(dir => $tmp);
- ...
+ # create distribution and prepare to test
+ my $dist = DistGen->new(name => 'Foo::Bar', dir => $tmp);
+ $dist->regen;
+ $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;
- chdir($dist->dirname) or
- die "Cannot chdir to '@{[$dist->dirname]}': $!";
- ...
+ # clean up extraneous files
$dist->clean;
- ...
- chdir($cwd) or die "cannot return to $cwd";
+
+ # finish testing and clean up
+ $dist->chdir_original;
$dist->remove;
+=head1 USAGE
+
+A DistGen object manages a set of files in a distribution directory.
+
+The constructor and some methods only define the target state of the
+distribution. They do B<not> make any changes to the filesystem:
+
+ new
+ add_file
+ change_file
+ change_build_pl
+ remove_file
+
+Other methods then change the filesystem to match the target state of
+the distribution (or to remove it entirely):
+
+ regen
+ clean
+ remove
+
+Other methods are provided for a convenience during testing. The
+most important are ones that manage the current directory:
+
+ chdir_in
+ chdir_original
+
=head1 API
=head2 Constructor
@@ -526,9 +556,10 @@
my $tmp = MBTest->tmpdir;
my $dist = DistGen->new(
- name => 'Foo::Bar',
- dir => $tmp,
- xs => 1,
+ name => 'Foo::Bar',
+ dir => $tmp,
+ xs => 1,
+ no_manifest => 0,
);
The parameters are as follows.
@@ -551,33 +582,84 @@
If true, generates an XS based module.
+=item no_manifest
+
+If true, C<regen()> will not create a MANIFEST file.
+
=back
-=head2 Manipulating the Distribution
+The following files are added as part of the default distribution:
-These methods immediately affect the filesystem.
+ Build.PL
+ lib/Simple.pm # based on name parameter
+ t/basic.t
-=head3 regen()
+If an XS module is generated, Simple.pm and basic.t are different and
+the following files are also added:
-Regenerate all missing or changed files.
+ typemap
+ lib/Simple.xs # based on name parameter
- $dist->regen(clean => 1);
+=head2 Adding and editing files
-If the optional C<clean> argument is given, it also removes any
-extraneous files that do not belong to the distribution.
+Note that C<$filename> should always be specified with unix-style paths,
+and are relative to the distribution root directory, e.g. C<lib/Module.pm>.
-=head2 chdir_in
+No changes are made to the filesystem until the distribution is regenerated.
-Change directory into the dist root.
+=head3 add_file()
- $dist->chdir_in;
+Add a $filename containing $content to the distribution.
-=head2 chdir_original
+ $dist->add_file( $filename, $content );
-Returns to whatever directory you were in before chdir_in() (regardless
-of the cwd.)
+=head3 change_file()
- $dist->chdir_original;
+Changes the contents of $filename to $content. No action is performed
+until the distribution is regenerated.
+
+ $dist->change_file( $filename, $content );
+
+=head3 change_build_pl()
+
+A wrapper around change_file specifically for setting Build.PL. Instead
+of file C<$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,
+ }
+ );
+
+=head3 get_file
+
+Retrieves the target contents of C<$filename>.
+
+ $content = $dist->get_file( $filename );
+
+=head3 remove_file()
+
+Removes C<$filename> from the distribution.
+
+ $dist->remove_file( $filename );
+
+=head2 Changing the distribution directory
+
+These methods immediately affect the filesystem.
+
+=head3 regen()
+
+Regenerate all missing or changed files. Also deletes any files
+flagged for removal with remove_file().
+
+ $dist->regen(clean => 1);
+
+If the optional C<clean> argument is given, it also removes any
+extraneous files that do not belong to the distribution.
=head3 clean()
@@ -602,31 +684,20 @@
Removes the entire distribution directory.
-=head2 Editing Files
-
-Note that C<$filename> should always be specified with unix-style paths,
-and are relative to the distribution root directory, e.g. C<lib/Module.pm>.
+=head2 Changing directories
-No filesystem action is performed until the distribution is regenerated.
+=head3 chdir_in
-=head3 add_file()
-
-Add a $filename containing $content to the distribution.
-
- $dist->add_file( $filename, $content );
-
-=head3 remove_file()
-
-Removes C<$filename> from the distribution.
+Change directory into the dist root.
- $dist->remove_file( $filename );
+ $dist->chdir_in;
-=head3 change_file()
+=head3 chdir_original
-Changes the contents of $filename to $content. No action is performed
-until the distribution is regenerated.
+Returns to whatever directory you were in before chdir_in() (regardless
+of the cwd.)
- $dist->change_file( $filename, $content );
+ $dist->chdir_original;
=head2 Properties
@@ -634,6 +705,8 @@
Returns the name of the distribution.
+ $dist->name: # e.g. Foo::Bar
+
=head3 dirname()
Returns the directory where the distribution is created.
Modified: Module-Build/trunk/t/metadata2.t
==============================================================================
--- Module-Build/trunk/t/metadata2.t (original)
+++ Module-Build/trunk/t/metadata2.t Sat Aug 15 05:13:48 2009
@@ -19,7 +19,7 @@
skip( 'YAML_support feature is not enabled', 4 )
unless Module::Build::ConfigData->feature('YAML_support');
- my $dist = DistGen->new( dir => $tmp, skip_manifest => 1 );
+ my $dist = DistGen->new( dir => $tmp, no_manifest => 1 );
$dist->regen;
$dist->chdir_in;
