diff --git a/Build.PL b/Build.PL index 11d0503..28e598a 100644 --- a/Build.PL +++ b/Build.PL @@ -38,10 +38,12 @@ my $builder = MyBuilder->new( 'IO::Zlib' => 0, 'LWP::Simple' => 0, 'Pod::Usage' => 0, + 'Pod::Markdown::Github' => 0, 'Test::More' => 0, 'YAML' => 0, 'File::Slurp' => 0, 'File::Temp' => 0, + 'FindBin' => 0, }, add_to_cleanup => [ 'CPAN-Mini-Inject-*', 't/local/WRITEREPO', 't/local/MYCPAN' ], diff --git a/MANIFEST b/MANIFEST index 9eb22d9..19ad55c 100644 --- a/MANIFEST +++ b/MANIFEST @@ -8,6 +8,7 @@ MANIFEST META.json META.yml README +README.md t/.mcpani/config t/.mcpani/config_with_whitespaces t/.mcpani/config_bad diff --git a/README.md b/README.md new file mode 100644 index 0000000..e4ac7e2 --- /dev/null +++ b/README.md @@ -0,0 +1,215 @@ +# NAME + +[CPAN::Mini::Inject](https://metacpan.org/pod/CPAN::Mini::Inject) - Inject modules into a [CPAN::Mini](https://metacpan.org/pod/CPAN::Mini) mirror. + +# VERSION + +Version 0.33 + +# Synopsis + +If you're not going to customize the way CPAN::Mini::Inject works you +probably want to look at the [mcpani](https://metacpan.org/pod/mcpani) command instead. + +```perl +use CPAN::Mini::Inject; + +$mcpi=CPAN::Mini::Inject->new; +$mcpi->parsecfg('t/.mcpani/config'); + +$mcpi->add( module => 'CPAN::Mini::Inject', + authorid => 'SSORICHE', + version => ' 0.01', + file => 'mymodules/CPAN-Mini-Inject-0.01.tar.gz' ) + +$mcpi->writelist; +$mcpi->update_mirror; +$mcpi->inject; +``` + +# DESCRIPTION + +[CPAN::Mini::Inject](https://metacpan.org/pod/CPAN::Mini::Inject) uses [CPAN::Mini](https://metacpan.org/pod/CPAN::Mini) to build or update a local CPAN mirror +then adds modules from your repository to it, allowing the inclusion +of private modules in a minimal CPAN mirror. + +# METHODS + +Each method in CPAN::Mini::Inject returns a CPAN::Mini::Inject object which +allows method chaining. For example: + +```perl +my $mcpi=CPAN::Mini::Inject->new; +$mcpi->parsecfg + ->update_mirror + ->inject; +``` + +A `CPAN::Mini::Inject` ISA [CPAN::Mini](https://metacpan.org/pod/CPAN::Mini). Refer to the +[documentation](https://metacpan.org/pod/CPAN::Mini) for that module for details of the interface +`CPAN::Mini::Inject` inherits from it. + +- `new` + + Create a new CPAN::Mini::Inject object. + +- `config_class( [CLASS] )` + + Returns the name of the class handling the configuration. + + With an argument, it sets the name of the class to handle + the config. To use that, you'll have to call it before you + load the configuration. + +- `config` + + Returns the configuration object. This object should be from + the class returned by `config_class` unless you've done something + weird. + +- `loadcfg( [FILENAME] )` + + This is a bridge to CPAN::Mini::Inject::Config's loadconfig. It sets the + filename for the configuration, or uses one of the defaults. + +- `parsecfg()` + + This is a bridge to CPAN::Mini::Inject::Config's parseconfig. + +- `site( [SITE] )` + + Returns the CPAN site that CPAN::Mini::Inject chose from the + list specified in the `remote` directive. + +- `testremote` + + Test each site listed in the remote parameter of the config file by performing + a get on each site in order for authors/01mailrc.txt.gz. The first site to + respond successfully is set as the instance variable site. + + ``` + print "$mcpi->{site}\n"; # ftp://ftp.cpan.org/pub/CPAN + ``` + + `testremote` accepts an optional parameter to enable verbose mode. + +- `update_mirror` + + This is a subclass of CPAN::Mini. + +- `add` + + Add a new module to the repository. The add method copies the module + file into the repository with the same structure as a CPAN site. For + example CPAN-Mini-Inject-0.01.tar.gz is copied to + MYCPAN/authors/id/S/SS/SSORICHE. add creates the required directory + structure below the repository. + + Packages found in the distribution will be added to the module list + (for example both `CPAN::Mini::Inject` and `CPAN::Mini::Inject::Config` + will be added to the `modules/02packages.details.txt.gz` file). + + Packages will be looked for in the `provides` key of the META file if present, + otherwise the files in the dist will be searched. + See [Dist::Metadata](https://metacpan.org/pod/Dist::Metadata) for more information. + + - module + + The name of the module to add. + The distribution file will be searched for modules + but you can specify the main one explicitly. + + - authorid + + CPAN author id. This does not have to be a real author id. + + - version + + The modules version number. + Module names and versions will be determined, + but you can specify one explicitly. + + - file + + The tar.gz of the module. + +### Example + +```perl +add( module => 'Module::Name', + authorid => 'AUTHOR', + version => 0.01, + file => './Module-Name-0.01.tar.gz' ); +``` + +- `added_modules` + + Returns a list of hash references describing the modules added by this instance. + Each hashref will contain `file`, `authorid`, and `modules`. + The `modules` entry is a hashref of module names and versions included in the `file`. + + The list is cumulative. + There will be one entry for each time ["add"](#add) was called. + + This functionality is mostly provided for the included [mcpani](https://metacpan.org/pod/mcpani) script + to be able to verbosely print all the modules added. + +- `inject` + + Insert modules from the repository into the local CPAN::Mini mirror. inject + copies each module into the appropriate directory in the CPAN::Mini mirror + and updates the CHECKSUMS file. + + Passing a value to `inject` enables verbose mode, which lists each module + as it's injected. + +- `updpackages` + + Update the CPAN::Mini mirror's modules/02packages.details.txt.gz with the + injected module information. + +- `updauthors` + + Update the CPAN::Mini mirror's authors/01mailrc.txt.gz with + stub information should the author not actually exist on CPAN + +- `readlist` + + Load the repository's modulelist. + +- `writelist` + + Write to the repository modulelist. + +# See Also + +[CPAN::Mini](https://metacpan.org/pod/CPAN::Mini) + +# Current Maintainer + +Christian Walde `` + +# Original Author + +Shawn Sorichetti, `` + +# Acknowledgements + +Special thanks to David Bartle, for bringing this module up +to date, and resolving the reported bugs. + +Thanks to Jozef Kutej for numerous patches. + +# Bugs + +Please report any bugs or feature requests to +`bug-cpan-mini-inject@rt.cpan.org`, or through the web interface at +[http://rt.cpan.org](http://rt.cpan.org). I will be notified, and then you'll automatically +be notified of progress on your bug as I make changes. + +# Copyright & License + +Copyright 2008-2009 Shawn Sorichetti, Andy Armstrong, All Rights Reserved. + +This program is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. diff --git a/inc/MyBuilder.pm b/inc/MyBuilder.pm index 301ce34..e25a11e 100644 --- a/inc/MyBuilder.pm +++ b/inc/MyBuilder.pm @@ -1,7 +1,14 @@ package MyBuilder; +use strict; use base qw( Module::Build ); +use FindBin; +use Cwd qw(realpath); +use File::Spec::Functions; + +use Pod::Markdown::Github; + sub create_build_script { my ( $self, @args ) = @_; $self->_auto_mm; @@ -85,4 +92,25 @@ sub ACTION_tidy { } } +sub ACTION_docs { + + my $self = shift; + + my $inject_pm = catfile($FindBin::Bin, "lib", "CPAN", "Mini", "Inject.pm"); + my $readme_md = catfile($FindBin::Bin, "README.md"); + + my $parser = Pod::Markdown::Github->new( perldoc_url_prefix => 'metacpan' ); + + open my $in_file, "<", $inject_pm or die "Failed to open '$inject_pm': $!\n"; + open my $out_file, ">", $readme_md or die "Failed to open '$readme_md': $!\n"; + + $parser->output_fh($out_file); + $parser->parse_file($in_file); + + close $out_file; + close $in_file; + + return $self->SUPER::ACTION_docs; +} + 1; diff --git a/lib/CPAN/Mini/Inject.pm b/lib/CPAN/Mini/Inject.pm index 6dd59cd..9de8207 100644 --- a/lib/CPAN/Mini/Inject.pm +++ b/lib/CPAN/Mini/Inject.pm @@ -18,7 +18,7 @@ use Dist::Metadata (); =head1 NAME -CPAN::Mini::Inject - Inject modules into a CPAN::Mini mirror. +L - Inject modules into a L mirror. =head1 VERSION @@ -50,7 +50,7 @@ probably want to look at the L command instead. =head1 DESCRIPTION -CPAN::Mini::Inject uses CPAN::Mini to build or update a local CPAN mirror +L uses L to build or update a local CPAN mirror then adds modules from your repository to it, allowing the inclusion of private modules in a minimal CPAN mirror. @@ -67,8 +67,11 @@ allows method chaining. For example: A C ISA L. Refer to the L for that module for details of the interface C inherits from it. +=cut -=head2 C +=over 4 + +=item C Create a new CPAN::Mini::Inject object. @@ -80,7 +83,7 @@ sub new { $_[0]; } -=head2 C<< config_class( [CLASS] ) >> +=item C<< config_class( [CLASS] ) >> Returns the name of the class handling the configuration. @@ -98,7 +101,7 @@ sub config_class { $self->{config_class}; } -=head2 C<< config >> +=item C<< config >> Returns the configuration object. This object should be from the class returned by C unless you've done something @@ -114,7 +117,7 @@ sub config { $self->{config}; } -=head2 C<< loadcfg( [FILENAME] ) >> +=item C<< loadcfg( [FILENAME] ) >> This is a bridge to CPAN::Mini::Inject::Config's loadconfig. It sets the @@ -134,7 +137,7 @@ sub loadcfg { return $self; } -=head2 C<< parsecfg() >> +=item C<< parsecfg() >> This is a bridge to CPAN::Mini::Inject::Config's parseconfig. @@ -152,7 +155,7 @@ sub parsecfg { return $self; } -=head2 C<< site( [SITE] ) >> +=item C<< site( [SITE] ) >> Returns the CPAN site that CPAN::Mini::Inject chose from the list specified in the C directive. @@ -168,7 +171,7 @@ sub site { $self->{site} || ''; } -=head2 C +=item C Test each site listed in the remote parameter of the config file by performing a get on each site in order for authors/01mailrc.txt.gz. The first site to @@ -207,7 +210,7 @@ sub testremote { return $self; } -=head2 C +=item C This is a subclass of CPAN::Mini. @@ -236,7 +239,7 @@ sub update_mirror { CPAN::Mini->update_mirror( %options ); } -=head2 C +=item C Add a new module to the repository. The add method copies the module file into the repository with the same structure as a CPAN site. For @@ -276,6 +279,8 @@ The tar.gz of the module. =back +=back + =head3 Example add( module => 'Module::Name', @@ -362,7 +367,9 @@ sub add { return $self; } -=head2 C +=over 4 + +=item C Returns a list of hash references describing the modules added by this instance. Each hashref will contain C, C, and C. @@ -381,7 +388,7 @@ sub added_modules { return @{ $self->{added_modules} ||= [] }; } -=head2 C +=item C Insert modules from the repository into the local CPAN::Mini mirror. inject copies each module into the appropriate directory in the CPAN::Mini mirror @@ -436,7 +443,7 @@ sub inject { return $self; } -=head2 C +=item C Update the CPAN::Mini mirror's modules/02packages.details.txt.gz with the injected module information. @@ -460,7 +467,7 @@ sub updpackages { $self->_writepkgs( [ sort values %packages ] ); } -=head2 C +=item C Update the CPAN::Mini mirror's authors/01mailrc.txt.gz with stub information should the author not actually exist on CPAN @@ -499,7 +506,7 @@ sub updauthors { } -=head2 C +=item C Load the repository's modulelist. @@ -529,7 +536,7 @@ sub readlist { return $self; } -=head2 C +=item C Write to the repository modulelist. @@ -709,6 +716,8 @@ sub _fmtdate { return "$date[0], $date[2] $date[1] $date[4] $date[3] GMT"; } +=back + =head1 See Also L