module::package::tutorial(3pm) [debian man page]

Module::Package::Tutorial(3pm)				User Contributed Perl Documentation			    Module::Package::Tutorial(3pm)

NAME

       Module::Package::Tutorial - A Hands on Guide

INTRODUCTION

       Welcome to Module::Package. This tutorial is for people who want to package modules for CPAN, who want to make sure they are doing it the
       best they can, but who also want to spend more time working on their code than on becoming an expert packager. This tutorial is also for
       people who want to take their time and effort spent on packaging, and share new ideas and tricks with others.

       I'll start by taking a typical Makefile.PL written with Module::Install and show you how to turn this into various Module::Package
       configurations, eventually ending up with a single line Makefile.PL. Then I'll show you the ins and outs of making your own Module::Install
       plugin module to handle your common needs.

Makefile.PL 2.0
       I won't start with 1.0. Those days are long past. Here's what a typical Makefile.PL looks like these days.

	   use strict;
	   use inc::Module::Install;

	   name 	   'Foo-Bar';
	   all_from	   'lib/Foo/Bar.pm';
	   build_requires  'Test::More';

	   auto_include_deps;
	   sign;

	   WriteAll;

       ... This doc is a work in progress. Stay tuned ...

       Here's the the final version:

	   use Module::Package 'All:good';

AUTHOR

       Ingy doet Net <ingy@cpan.org>

COPYRIGHT AND LICENSE

       Copyright (c) 2011. Ingy doet Net.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

       See http://www.perl.com/perl/misc/Artistic.html

perl v5.14.2							    2011-06-07					    Module::Package::Tutorial(3pm)

Module::Package::Plugin(3pm)				User Contributed Perl Documentation			      Module::Package::Plugin(3pm)

SYNOPSIS

	   package Module::Package::Name;

	   package Module::Package::Name::flavor;
	   use Moo;
	   extends 'Module::Package::Plugin';

	   sub main {
	       my ($self) = @_;
	       $self->mi->some_module_install_author_plugin;
	       $self->mi->other_author_plugin;
	   }

	   1;

DESCRIPTION

       This module is the base class for Module::Package plugins.

EXAMPLE

       Take a look at the Module::Package::Ingy module, for a decent starting point example. That plugin module is actually used to package
       Module::Package itself.

API

       To create a Module::Package plugin you need to subclass Module::Package::Plugin and override the "main" method, and possibly other things.
       This section describes how that works.

       Makefile.PL processing happens in the following order:

	   - 'use inc::Module::Package...' is invoked
	   - $plugin->initial is called
	   - BEGIN blocks in Makefile.PL are run
	   - $plugin->main is called
	   - The body of Makefile.PL is run
	   - $plugin->final is called

   initial
       This method is call during the processing of 'use inc::Module::Package'. You probably don't need to subclass it. If you do you probably
       want to call the SUPER method.

       It runs the deps_list, if any and guesses the primary modules file path.

   main
       This is the method you must override. Do all the things you want. You can call "all_from", if you need to get sequencing right, otherwise
       it gets called by final(). Don't call "WriteAll", it get's called automatically in final().

   final
       This does all the things after the entire Makefile.PL body has run. You probably don't need to override it.

OPTIONS

       The following options are available for use from the Makefile.PL:

	   use Module::Package 'Foo:bar',
	       deps_list => 0|1,
	       install_bin => 0|1,
	       install_share => 0|1,
	       manifest_skip => 0|1,
	       requires_from => 0|1;

       These options can be used by any subclass of this module.

   deps_list
       Default is 1.

       This option tells Module::Package to generate a "author_requires" deps list, when you run the Makefile.PL. This list will go in the file
       "pkg/deps_list.pl" if that exists, or after a '__END__' statement in your Makefile.PL. If neither is available, a reminder will be warned
       (only when the author runs it).

       This list is important if you want people to be able to collaborate on your modules easily.

   install_bin
       Default is 1.

       All files in a "bin/" directory will be installed. It will call the "install_script" plugin for you. Set this option to 0 to disable it.

   install_share
       Default is 1.

       All files in a "share/" directory will be installed. It will call the "install_share" plugin for you. Set this option to 0 to disable it.

   manifest_skip
       Default is 1.

       This option will generate a sane MANIFEST.SKIP for you and delete it again when you run "make clean". You can add your own skips in the
       file called "pkg/manifest.skip". You almost certainly want this option on. Set to 0 if you are weird.

   requires_from
       Default is 1.

       This option will attempt to find all the requirements from the primary module.  If you make any of your own requires or requires_from
       calls, this option will do nothing.

perl v5.14.2							    2011-10-06					      Module::Package::Plugin(3pm)