=head1 USER MANUAL

This is the L<CPAN::Packager> users manual. 

=head1 DESCRIPTION

cpan-packager creates RPM and Deb packages of CPAN distributions. Given a
module name, cpan-packager will automatically analyze dependencies, download,
build, test, provision, and install packages.

=head1 CONFIGURATION

The configuration file is YAML-based and is comprised of two main sections, the
"global" section, and the "modules" section. The configuration schema is
defined in: CPAN::Packager::Config::Schema

=head2 The "global" configuration section.

This section defines common configuration entities.

=over 4

=item * B<cpan_mirrors>

Accepts one or more CPAN mirror arguments. These mirrors are used to retrieve
the module(s) being packaged in addition to their dependencies. For example,
a local CPAN::Mini mirror, or a "real" mirror may be referenced:

=over 4

=item * B<file:///home/dann/minicpan/>

=item * B<http://cpan.pair.com/>

=item * B<ftp://cpan.pair.com/pub/CPAN/>

=back

An example configuration section for "cpan_mirrors" may look like:

 ---
 global:
   cpan_mirrors:
     - http://ftp.funet.fi/pub/languages/perl/CPAN/
     - file:///home/dann/minicpan

=item * B<fix_package_depends>

TODO

=over 4

=item * B<from>

TODO

=item * B<to>

TODO

=back

=item * B<no_depends>

TODO

=over 4

=item * B<module>

TODO

=back

=item * B<skip_name_resolve_modules>

TODO

=over 4

=item * B<module>

TODO

=back

=item * B<fix_module_name>

TODO

=over 4

=item * B<from>

TODO

=item * B<to>

TODO

=back

=back

=head2 The "modules" configuration section

This section defines module-specific configuration entities.

=over 4

=item * B<module>

Specifies the module to which this configuration applies. For example:
Test::Reporter.

=item * B<no_depends>

Forcefully removes module dependencies.

=over 4

=item * B<module>

Given module is removed from the dependency list of the package being built.
For example: Test::Reporter.

=back

=item * B<depends>

Forcefully adds module dependencies.

=over 4

=item * B<module>

Given module is added to the dependency list of the package being built.
For example: Test::Reporter.

=back

=item * B<skip_test>

Causes "make test" to be skipped for given module. This is useful when you
don't want a module's failing tests to prevent the module from being built
and installed.

=item * B<force_build>

TODO

=item * B<custom>

TODO

=over 4

=item * B<tgz_path>

TODO

=item * B<src_dir>

TODO

=item * B<version>

TODO

=item * B<dist_name>

TODO

=item * B<patches>

TODO

=back

=item * B<version>

TODO

=item * B<release>

This specifies the release of the package itself (not the module that's being
packaged). This is most commonly used when you want to re-package the same
version of a given module. You may want to do this, for example, if the
original packaging was somehow in error, or perhaps if you want to adjust the
package's metadata.

=item * B<pkg_name>

Ordinarilly, a module like, for example, Test::Reporter would be given a
package name of perl-Test-Reporter (RPM) or libtest-reporter-perl (Deb), by
default. However, if for some reason you need to define your own package name,
this option will allow you to do just that. This can be useful in conjunction
with the "obsoletes" option, if you need to forcefully "override" an existing
"identical" package on the system.

=item * B<epoch>

This option specifies the epoch of a package. This is primarily useful in the
situation where, for example, RPM's version comparison algorithm isn't doing
what you expect. Bumping the epoch integer up will force RPM to consider the
package as being newer even if it would ordinarily consider it being older,
version-wise.

=item * B<obsoletes>

Accepts multiple "package" arguments. Causes the package being built to
obsolete the given packages.

=over 4

=item * B<package>

In the case of RPM, an example package argument may be: perl-Compress-Zlib.
For example, since the IO-Compress distribution superceeds and deprecates the
Compress-Zlib distribution, the configuration section for the IO::Compress
module may obsolete the perl-Compress-Zlib package, as above.

=back

=back

=head1 MISCELLANEOUS

=head2 Using cpan-packager with minicpan

You may use CPAN::Packager with minicpan. First, establish your local minicpan
mirror:

 minicpan -r http://ftp.funet.fi/pub/languages/perl/CPAN/ -l ~/minicpan

Then, just set the path to your local minicpan mirror in your configuration file:

 ---
 global:
   cpan_mirrors:
     - file:///home/dann/minicpan

=head2 Applying patches to tarballs for RPM builds

Write the module's configuration as such:

  - module: Acme
    custom:
      tgz_path: ~/.cpanpackager/custom_module/Acme-1.11111.tar.gz
      patches: 
        - ~/.cpanpackager/custom_module/acme_test.patch
      dist_name: Acme
      version: 1.11111

The patch should, for example, look like:

    --- Acme-1.11111/t/acme.t.orig	2010-01-26 22:26:51.000000000 +0900
    +++ Acme-1.11111/t/acme.t	2010-01-26 22:26:39.000000000 +0900
    @@ -1,8 +1,10 @@
     use lib 't', 'lib';
     use strict;
     use warnings;
    -use Test::More tests => 2;
    +use Test::More tests => 3;
     use Acme;
     
     ok(acme->is_acme);
     ok(acme->is_perfect);
    +ok 1;
 
=head2 Specify installation location (optional)

It is possible for a CPAN::Packager user to explicitly specify installation
locations for a distribution's libraries, documentation, man pages, binaries,
and scripts. Setting both of the below environment variables, for example, will
accomplish this.

 PERL_MM_OPT="INSTALLVENDORMAN1DIR=/usr/local/share/man/man1
 INSTALLVENDORMAN3DIR=/usr/local/share/man/man3
 INSTALLVENDORBIN=/usr/local/bin INSTALLVENDORSCRIPT=/usr/local/bin"

 PERL_MB_OPT="--config installvendorman1dir=/usr/local/share/man/man1
 --config installvendorman3dir=/usr/local/share/man/man3 --config
 installvendorbin=/usr/local/bin --config installvendorscript=/usr/local/bin"

Additionally, for RPMs, you may specify the directory in which non-man
documentation (Changes, README, etc) are installed via adding an entry
to your ~/.rpmmacros file:

%_defaultdocdir /usr/local/share/doc

=head2 Additional setup for debian users

Copy conf/debian/rules* to the ~/.dh-make-perl directory. Otherwise, you may
experience conflicts. For example: perllocal.pod.

=head1 ENVIRONMENT VARIABLES

Environment variable C<CPAN_PACKAGER_TEST_LIVE> can be used to execute live
tests. 

Environment variable C<CPAN_PACKAGER_ENABLE_DUMP> can be used to dump
variables.

=head1 BUGS

Please report any bugs or feature requests to this project's GitHub repository at:

http://github.com/dann/p5-cpan-packager/issues

Thank you!

=head1 AUTHOR

Takatoshi Kitano E<lt>kitano.tk@gmail.comE<gt>

=cut
