MAKEPERLMOD(1)

NAME
makeperlmod - Perl program for creating new modules with ExtUtils::ModuleMaker::TT

VERSION
version 0.94

SYNOPSIS
 makeperlmod [ -c config_file ] mode_option [argument] [-e extra_info ]

DESCRIPTION
This program is a front-end to ExtUtils::ModuleMaker::TT. It supports:

•   reading/writing a configuration file

•   generating a directory of default templates

•   building new distribution directories

•   creating new .pm and .t files within an existing distribution directory

•   printing a skeleton method to STDOUT

OPTIONS

  Mode Options
One of the following mode options is required and only one may be used.

-d [CONFIG] or --defaults [CONFIG]
    Writes out default options from ExtUtils::ModuleMaker to the given file in "Apache" config format. Use to create a new base for a custom config file. CONFIG is either a short configuration name or an absolute path to a file. A default value is used if CONFIG is not given. See "CONFIGURATION FILES" below for details. This option prints the location of the config file on completion.

-l [CONFIG] or --locate_config [CONFIG]
    Prints the location of the named config file, or the default if CONFIG is not given. Helpful for finding the right config file to edit. See "CONFIGURATION FILES" below for details.

-t DIRECTORY or --templates DIRECTORY
    Creates DIRECTORY if it doesn't exist and write all default templates as separate files in that directory for subsequent user customization (Add a TEMPLATE_DIR option with DIRECTORY to your custom config file to use this as a custom template directory)

-n MODULE::NAME or --newdist MODULE::NAME
    Creates a skeleton distribution for MODULE::NAME. Directory name will be determined by the COMPACT option set in the config file

-m MODULE::NAME or --module MODULE::NAME
    Creates a new .pm and corresponding .t file in an existing distribution. Must be called from within an existing distribution tree, though not necessarily at the top level. I.e., can be called from lib/Sample/Module and will still place files correctly

-s METHOD_NAME or --subroutine METHOD_NAME
    Prints to STDOUT a skeleton for a single method. Most useful when called from within an editor to insert code. See EXAMPLES.

-V or --version
    Prints version information and current configuration settings (either default or from a -c option)

-h or -? or --help
    Prints usage information

  Additional Options

-c CONFIG or --config CONFIG
    Specifies an alternate configuration file to use in place of the default one

-e EXTRA or --extra EXTRA
    Defines an additional module (for -n and -m modes) or method (for -s mode) to be created. May be used more than once to define multiple extras

CONFIGURATION FILES

  Overview
makeperlmod has a multi-level configuration system. Options that control creation of a skeleton distribution are processed as follows, with each subsequent source extending or overriding the previous one:

1. Built-in defaults to ExtUtils::ModuleMaker
2. Defaults specified in an ExtUtils::ModuleMaker::Personal::Defaults file
3. makeperlmod built-in defaults (COMPACT style and ExtUtils::ModuleMaker::TT as the ALT_BUILD)
4. makeperlmod config file, either the default one or one specified on the command line with the "--config" option

This preserves maximum flexibility and compatibility with the personal defaults system in ExtUtils::ModuleMaker. makeperlmod allows one or more additional configuration files to customize those defaults for special purposes.

Generally, static information like AUTHOR should probably go in the ExtUtils::ModuleMaker::Personal::Defaults file. TEMPLATE_DIR could go in the makeperlmod config files to allow for different templates to be used for different projects.

  Config file locations
The directory for config files is located in an operating system-specific fashion using Config::Find. For example, this is typically "~/.makeperlmod/" on Unix-based systems or something in a "makeperlmod" directory located somewhere under "C:\Documents and Settings\Username\" on MSWin32.

If no config file is specified, the default is 'default.conf'. Short config names are found in the operating system specific directory with a '.conf' extension. If an absolute file pathname is given, that is used directly. 'makeperlmod -l CONFIG' will always show how a given CONFIG option is interpreted by makeperlmod. For example, on Linux:

 $ makeperlmod -l
 /home/david/.makeperlmod/default.conf

 $ makeperlmod -l default
 /home/david/.makeperlmod/default.conf

 $ makeperlmod -l freelance
 /home/david/.makeperlmod/freelance.conf

 $ makeperlmod -l /etc/makeperlmod/corp/std.conf
 /etc/makeperlmod/corp/std.conf

EXAMPLES
Create a custom configuration file

    makeperlmod -d

Create a custom template directory

    makeperlmod -t ~/.makeperlmod.templates

Edit the custom configuration file. Set AUTHOR and other defaults as desired. Set TEMPLATE_DIR to the templates directory (e.g. ~/.makeperlmod.templates ) to use your own custom templates in place of the defaults.

Create a new distribution

    makeperlmod -n Sample::Module::Foo

Create a new distribution with an extra module

    makeperlmod -n Sample::Module::Foo -e Sample::Module::Bar

From within the new distribution, add another .pm

    cd Sample-Module-Foo/lib/Sample/Module
    makeperlmod -m Sample::Module::Baz

From within an editor, insert a new subroutine skeleton. E.g. from within vi,

    :r! makeperlmod -s sample_method

Or insert several subroutines

    :r! makeperlmod -s sample_method -e method2 -e method3

SEE ALSO
See ExtUtils::ModuleMaker and ExtUtils::ModuleMaker::TT for more details.

AUTHOR
David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by David Golden.

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