/ 
ExtUtils-ModuleMaker-0.31229
River stage one • 3 direct dependents • 4 total dependents
/ ExtUtils::ModuleMaker

NAME

ExtUtils::ModuleMaker - Better than h2xs, for creating all the parts of modules

SYNOPSIS

use ExtUtils::ModuleMaker;
#die "You really don't want to use ModuleMaker again for this module."

my $MOD = ExtUtils::ModuleMaker->new
            (
              NAME => 'Sample::Module',
            );
$MOD->complete_build ();

DESCRIPTION

This module is a replacement for h2xs. It can be called from a Modulefile.PL similar to calling MakeMaker from Makefile.PL.

See also: the 'modulemaker' program, which is included with this package, that simplifies the process for casual module builders; the vast majority of lazy Perl programmers.

INSTALLATION

perl Makefile.PL
make
make test
make install

On windows machines use nmake rather than make. If you would like to test the scripts without a real installation you can replace Makefile.PL with Fakefile.PL to install in a temporaty place.

USAGE

BUGS

SUPPORT

Send email to modulemaker@PlatypiVentures.com.

AUTHOR

R. Geoffrey Avery
CPAN ID: RGEOFFREY
modulemaker@PlatypiVentures.com
http://www.PlatypiVentures.com/perl/modules/ModuleMaker.shtml

COPYRIGHT

Copyright (c) 2001-20022 R. Geoffrey Avery. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

modulemaker, perlnewmod, h2xs, ExtUtils::MakeMaker

PUBLIC METHODS

Each public function/method is described here. These are how you should interact with this module.

new

Usage     : 
Purpose   : Creates an object for modules
Returns   : the module object
Argument  : A hash with the information for the new module(s)
Throws    : 
Comments  :

See Also :

NAME

The only required feature. This is the name of the primary module (with '::' separators if needed). Will also support the older style separator "'" like the module D'Oh.

ABSTRACT

A short description of the module, this will be passed on to MakeMaker through Makefile.PL. CPAN likes to use this feature to describe the module.

VERSION

A real number to be the version number. Do not use Linux style numbering with multiple dots like 2.4.24. For alpha releases include an underscore to the right of the dot like 0.31_21. (Default is 0.01)

LICENSE

Which license to include in the Copyright section. You can choose one of the standard licenses by including 'perl', 'gpl', 'artistic', and 18 others approved by opensource.org. The default is to choose the 'perl' flavor which is to share it "under the same terms as Perl itself".

Other licenses can be added by individual module authors to ExtUtils::ModuleMaker::Licenses::Local to keep your company lawyers happy.

Some licenses include placeholders that will be replaced with AUTHOR information.

AUTHOR

A hash containing information about the author to pass on to all the necessary places in the files.

NAME

Name of the author.

EMAIL

Email address of the author.

CPANID

The CPANID of the author. If this is omited, then the line will not be added to the documentation.

WEBSITE

The personal or organizational website of the author.

ORGANIZATION

Company or group owning the module.

EXTRA_MODULES

An array of hashes that each contain values for additional modules in the distribution. As with the primary module only NAME is required and primary module values will be used if no value is given here.

Each extra module will be created in the correct relative place in the lib directory, but no extra supporting documents, like README or Changes.

This is one major improvement over the earlier h2xs as you can now build multi-module packages.

COMPACT

For a module named "Foo::Bar::Baz" creates a base directory named "Foo-Bar-Baz" instead of Foo/Bar/Baz. (Default off)

VERBOSE

Prints messages as it creates directories, writes files, etc. (Default off)

INTERACTIVE

Suppresses 'die' when something goes wrong. Should only be used by interactive scripts like modulemaker. (Default off)

PERMISSIONS

Used to create new directories. (Default is 0755, group and world can not write)

USAGE_MESSAGE

Message given when the module 'die's. Scripts should set this to the same string it would print if the user asked for help (often with a -h flag).

NEED_POD

Include POD section in modules. (Default is on)

NEED_NEW_METHOD

Include a simple 'new' method in the object oriented module. (Default is on)

CHANGES_IN_POD

Don't include a 'Changes' file and add a HISTORY section to the POD. (Default is off).

default_values

Usage     : $self->default_values ()
Purpose   : Defaults for 'new'.
Returns   : A hash of defaults as the basis for 'new'.
Argument  : n/a
Throws    : n/a
Comments  :

See Also :

verify_values

Usage     : $self->verify_values ()
Purpose   : Verify module values are valid and complete.
Returns   : Error message if there is a problem
Argument  : n/a
Throws    : Will die with a death_message if errors and not interactive.
Comments  :

See Also :

PRIVATE METHODS

Each private function/method is described here. These methods and functions are considered private and are intended for internal use by this module. They are not considered part of the public interface and are described here for documentation purposes.

If you choose to make a subclass of this module to customize ModuleMaker for your environment you may need to replace some or all of these functions to get what you need. But as a general rule programs should not be using them directly.

sample_function

Usage     : How to use this function/method
Purpose   : What it does
Returns   : What it returns
Argument  : What it wants to know
Throws    : Exceptions and other anomolies
Comments  : This is a sample subroutine header.
          : It is polite to include more pod and fewer comments.

See Also :

Create_Base_Directory

Usage     : 
Purpose   :
            Create the directory where all the files will be created.
Returns   :
            $DIR = directory name where the files will live
Argument  :
            $package_name = name of module separated by '::'
Throws    : 
Comments  :

See Also : Check_Dir

Check_Dir

Usage     :
            Check_Dir ($dir, $MODE);
Purpose   :
            Creates a directory with the correct mode if needed.
Returns   : n/a
Argument  :
            $dir = directory name
            $MODE = mode of directory (e.g. 0777, 0755)
Throws    : 
Comments  :

See Also :

Block_Begin

Usage     : $self->Block_Begin ()
Purpose   : Build part of a module pm file
Returns   : Part of the file being built
Argument  : $module: pointer to the module being built, for the primary
                     module it is a pointer to $self
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

Block_Begin_BareBones

Usage     : $self->Block_Begin_BareBones ()
Purpose   : Build part of a module pm file
Returns   : Part of the file being built
Argument  : $module: pointer to the module being built, for the primary
                     module it is a pointer to $self
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

Block_New_Method

Usage     : $self->Block_New_Method ()
Purpose   : Build part of a module pm file
Returns   : Part of the file being built
Argument  : $module: pointer to the module being built, for the primary
                     module it is a pointer to $self
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

Block_Module_Header

Usage     : $self->Block_Module_Header ()
Purpose   : Build part of a module pm file
Returns   : Part of the file being built
Argument  : $module: pointer to the module being built, for the primary
                     module it is a pointer to $self
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

Block_Subroutine_Header

Usage     : $self->Block_Subroutine_Header ()
Purpose   : Build part of a module pm file
Returns   : Part of the file being built
Argument  : $module: pointer to the module being built, for the primary
                     module it is a pointer to $self
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

Block_Final_One

Usage     : $self->Block_Final_One ()
Purpose   : Make module return a true value
Returns   : Part of the file being built
Argument  : $module: pointer to the module being built, for the primary
                     module it is a pointer to $self
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

FileText_README

Usage     : $self->FileText_README ()
Purpose   : Build a supporting file
Returns   : Text of the file being built
Argument  : n/a
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

FileText_Changes

Usage     : $self->FileText_Changes ()
Purpose   : Build a supporting file
Returns   : Text of the file being built
Argument  : $only_in_pod:  True value to get only a HISTORY section for POD
                           False value to get whole Changes file
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

FileText_ToDo

Usage     : $self->FileText_ToDo ()
Purpose   : Build a supporting file
Returns   : Text of the file being built
Argument  : n/a
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

FileText_Makefile

Usage     : $self->FileText_Makefile ()
Purpose   : Build a supporting file
Returns   : Text of the file being built
Argument  : n/a
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass

See Also :

FileText_Test

Usage     : $self->FileText_Test ()
Purpose   : Build a supporting file
Returns   : Text of the file being built
Argument  : n/a
Throws    : n/a
Comments  : This method is a likely candidate for alteration in a subclass
            Will make a test with or without a checking for method new.

See Also :

Quick_Module

Usage     :
            perl -MExtUtils::ModuleMaker -e "Quick_Module ('Sample::Module')"
or
            use ExtUtils::ModuleMaker;
            Quick_Module ('Sample::Module');

Purpose   : Creates a Module.pm with supporing files
Returns   : n/a
Argument  : A name for the module, like 'Module' or 'Sample::Module'
Throws    : 
Comments  : More closely mimics h2xs behavior than Generate_Module_Files.
          : Included to allow simple creation from a command line.
          : This function is deprecated and will disappear forever soon.

See Also : Generate_Module_Files

Generate_Module_Files

Usage     : How to use this function/method
Purpose   : Creates one or more modules with supporing files
Returns   : n/a
Argument  : A hash with the information for the new module(s)
Throws    : 
Comments  : This function is deprecated and will disappear forever soon.