++ed by:
1 non-PAUSE user
Author image Johan Vromans


module-setup - Generate boilerplate files for a new module


    module-setup --author="A.U.Thor" --email=a.u.thor@example.com Foo::Bar


module-setup is a boilerplate generator for new Perl modules.

Why, yet another one?

All existing boilerplate generators suit many users, but abhor others. They can do too much, or too little, or use conventions that not everyone agrees with.

module-setup uses a set of customisable templates so everyone can tailor it to whatever needs may arise. Its design goal is to be extremely simple for unexperienced users, while still being useful for more advanced module writing.



Specifies the name of the author of the module.

If this option is not given, the name will be taken from the system account information.

This option can be preset in an optional configuration file.


Specifies the email address of the author of the module.

This option can be preset in an optional configuration file.


Specifies the CPAN id of the author of the module.

If this option is not given, the id will be inferred from the email address if possible.

This option can be preset in an optional configuration file.


Specifies the GitHub id of the author of the module. Optional.

This option can be preset in an optional configuration file.


Specifies the set of templates to use for this module. See "TEMPLATES". Default set is default.

This option can be preset in an optional configuration file.


Specifies a command to execute after creating the boilerplate files. The command will be executed in the distribution directory using the system shell. This can be used to postprocess the created files, set up a git repository, and so on.

This option can occur multiple times, all commands will be executed. This option can be preset in an optional configuration file.


Initialises an empty git repository after creating the boilerplate files.

This is a shortcut for --postcmd="git init".


Specifies the name of the new module to be created.

Alternatively, the module name can also be specified as a command line argument, e.g.

    module-setup Foo::Bar

Specifies the name of an alternate config file to be loaded. See "CONFIG FILES".

Note that the config file is processed at the point it appears on the command line, possibly overwriting values already specified.


Installs the default set of templates to the local disk, suitable for tailoring to one's needs. No further processing is done.

The templates are installed in subdirectory templates/default under the current directory, and will be used instead of the built-in templates for subsequent runs of module-setup in the same directory.

You can move the templates to the config location if you want to use them for other module projects.


Shows a help message, and exits.


Shows verbose information during the process.


Some information can be preset in a config file. This is particulary useful for global information that is not likely to change, like the author's name and email address.

module-setup tries to find a config file in two locations. First it tries $HOME/.config/module-setup/config, if this is missing, it tries $HOME/.module-setup/config.

The config file should contain settings like:

    name = A.U. Thor
    email: a.u.thor@example.com
    cpanid = thorax
    template = default
    postcmd = git init

Empty lines and lines starting with ; or # are ignored.


module-setup creates the distribution directory and populates it with boilerplate files. The name of the distribution directory is the same as the name of the module, with all :: replaced with -. E.g., the directory name for module Foo::Bar would be Foo-Bar.

After creating this directory, module-setup copies all files from the templates directory into the distribution directory.

The source directory for the templates can be selected with a --template option or template setting in the config file. For example, if the selected template set is modstart, then the following locations are tried:


The default template set is named default. If no suitable templates can be found in any of the locations, a default set is provided by module-setup.

Variable substitution

While copying the templates, variable substitution is performed on the contents. Variables can be specified in the templates in Template Toolkit notation, e.g.,

    ... in some text the occurrence of [% foobar %] will be replaced ...

In the above example, [% foobar %] will be replaced with the value of the variable foobar. If there is no value available, a warning will be given and the substitution is not done.

The following variables are currently supported:


The name of the author, e.g., A.U. Thor.


The author's email address, e.g., a.u.thor@example.com,


The author's CPAN id, e.g., THORAX.


The author's GitHub id, e.g., Thorax.


The name of the module to be created, e.g., Foo::Bar.


The initial version of the module, e.g., 0.01.


The distribution name for the module, e.g., Foo-Bar.


Same, but all lowercase. E.g., foo-bar.


The file name for the module, e.g., Foo/Bar.pm.


The license for this module. Defaults to perl_5,


The current year, for copyrights and such. E.g., 2013.


The minimal version of perl required for this module. Defaults to 5.008.

Default templates

The default set of templates consists of the following files:


Note that the filename _Module.pm is magic, this template will be copied under the filename of the new module.


Johan Vromans, <jv at cpan.org>


Please report any bugs or feature requests to bug-app-module-setup at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Module-Setup. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc module-setup

You can also look for information at:


David Golden, for giving me the final incentive to write this module.

Sawyer X, for writing Module::Starter where I borrowed many ideas from.


Copyright 2013,2018 Johan Vromans, all rights reserved.

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