1Module::Starter::PBP(3)User Contributed Perl DocumentatioMnodule::Starter::PBP(3)
2
3
4

NAME

6       Module::Starter::PBP - Create a module as recommended in "Perl Best
7       Practices"
8

VERSION

10       This document describes Module::Starter::PBP version 0.0.3
11

SYNOPSIS

13           # In your  ~/.module-starter/config file...
14
15           author:  <Your Name>
16           email:   <your@email.addr>
17           plugins: Module::Starter::PBP
18           template_dir: </some/absolute/path/name>
19
20           # Then on the command-line...
21
22           > module-starter --module=Your::New::Module
23
24           # Or, if you're lazy and happy to go with
25           # the recommendations in "Perl Best Practices"...
26
27           > perl -MModule::Starter::PBP=setup
28

DESCRIPTION

30       This module implements a simple approach to creating modules and their
31       support files, based on the Module::Starter approach. Module::Starter
32       needs to be installed before this module can be used.
33
34       When used as a Module::Starter plugin, this module allows you to spec‐
35       ify a simple directory of templates which are filled in with module-
36       specific information, and thereafter form the basis of your new module.
37
38       The default templates that this module initially provides are based on
39       the recommendations in the book "Perl Best Practices".
40

INTERFACE

42       Thsi module simply acts as a plugin for Module::Starter. So it uses the
43       same command-line interface as that module.
44
45       The template files it is to use are specified in your Module::Starter
46       "config" file, by adding a "template_dir" configuration variable that
47       gives the full path name of the directory in which you want to put the
48       templates.
49
50       The easiest way to set up this "config" file, the associated directory,
51       and the necessary template files is to type:
52
53           > perl -MModule::Starter::PBP=setup
54
55       on the command line. You will then be asked for your name, email
56       address, and the full path name of the directory where you want to keep
57       the templates, after which they will be created and installed.
58
59       Then you can create a new module by typing:
60
61           > module-starter --module=Your::New::Module
62
63       Template format
64
65       The templates are plain files named:
66
67               Build.PL
68               Makefile.PL
69               README
70               Changes
71               Module.pm
72               t/whatever_you_like.t
73
74       The "Module.pm" file is the template for the ".pm" file for your mod‐
75       ule. Any files in the "t/" subdirectory become the templates for the
76       testing files of your module. All the remaining files are templates for
77       the ditribution files of the same names.
78
79       In those files, the following placeholders are replaced by the appro‐
80       priate information specific to the file:
81
82       <AUTHOR>
83           The nominated author. Taken from the "author" setting in your Mod‐
84           ule::Starter "config" file.
85
86       <BUILD INSTRUCTIONS>
87           Makefile or Module::Build instructions. Computed automatically
88           according to the "builder" setting in your Module::Starter "config"
89           file.
90
91       <DATE>
92           The current date (as returned by "localtime"). Computed automagi‐
93           cally
94
95       <DISTRO>
96           The name of the complete module distribution. Computed automati‐
97           cally from the name of the module.
98
99       <EMAIL>
100           Where to send feedback. Taken from the "email" setting in your Mod‐
101           ule::Starter "config" file.
102
103       <LICENSE>
104           The licence under which the module is released. Taken from the
105           "license" setting in your Module::Starter "config" file.
106
107       <MAIN MODULE>
108           The name of the main module of the distribution.
109
110       <MAIN PM FILE>
111           The name of the ".pm" file for the main module.
112
113       <MODULE NAME>
114           The name of the current module being created within the distribu‐
115           tion.
116
117       <RT NAME>
118           The name to use for bug reports to the RT system.  That is:
119
120               Please report any bugs or feature requests to
121               bug-<RT NAME>@rt.cpan.org>
122
123       <YEAR>
124           The current year. Computed automatically
125

DIAGNOSTICS

127       "Can't find directory that holds Module::Starter::PBP templates"
128           You did not tell Module::Starter::PBP where your templates are
129           stored.  You need a 'template_dir' specification. Typically this
130           would go in your ~/.module-starter/config file. Something like:
131
132               template_dir: /users/you/.module-starter/Templates
133
134       "Can't access Module::Starter::PBP template directory"
135           You specified a 'template_dir', but the path didn't lead to a read‐
136           able directory.
137
138       "The template: %s isn't in the template directory (%s)"
139           One of the required templates:
140
141           was missing from the template directory you specified.
142
143       "The template: %s isn't readable in the template directory (%s)"
144           One of the templates in the template directory you specified was
145           not readable.
146
147       "Unknown placeholder <%s> in %s"
148           One of the templates in the template directory contained a replace‐
149           ment item that wasn't a known piece of information.
150

CONFIGURATION AND ENVIRONMENT

152       See the documentation for "Module::Starter" and "module-starter".
153

DEPENDENCIES

155       Requires the "Module::Starter" module.
156

INCOMPATIBILITIES

158       None reported.
159

BUGS AND LIMITATIONS

161       No bugs have been reported.
162
163       Please report any bugs or feature requests to "bug-mod‐
164       ule-starter-pbp@rt.cpan.org", or through the web interface at
165       <http://rt.cpan.org>.
166

AUTHOR

168       Damian Conway  "<DCONWAY@cpan.org>"
169

171       Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
172       reserved.
173
174       This module is free software; you can redistribute it and/or modify it
175       under the same terms as Perl itself.
176

DISCLAIMER OF WARRANTY

178       BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
179       FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
180       WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
181       PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
182       EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
183       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
184       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
185       YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
186       NECESSARY SERVICING, REPAIR, OR CORRECTION.
187
188       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
189       WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
190       REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
191       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CON‐
192       SEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFT‐
193       WARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
194       INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
195       THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER
196       OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
197
198
199
200perl v5.8.8                       2006-02-17           Module::Starter::PBP(3)
Impressum