1Module::Starter::PBP(3)User Contributed Perl DocumentatioMnodule::Starter::PBP(3)
2
3
4
6 Module::Starter::PBP - Create a module as recommended in "Perl Best
7 Practices"
8
10 This document describes Module::Starter::PBP version 0.0.3
11
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
21 # Then on the command-line...
22
23 > module-starter --module=Your::New::Module
24
25
26 # Or, if you're lazy and happy to go with
27 # the recommendations in "Perl Best Practices"...
28
29 > perl -MModule::Starter::PBP=setup
30
32 This module implements a simple approach to creating modules and their
33 support files, based on the Module::Starter approach. Module::Starter
34 needs to be installed before this module can be used.
35
36 When used as a Module::Starter plugin, this module allows you to
37 specify a simple directory of templates which are filled in with
38 module-specific information, and thereafter form the basis of your new
39 module.
40
41 The default templates that this module initially provides are based on
42 the recommendations in the book "Perl Best Practices".
43
45 Thsi module simply acts as a plugin for Module::Starter. So it uses the
46 same command-line interface as that module.
47
48 The template files it is to use are specified in your Module::Starter
49 "config" file, by adding a "template_dir" configuration variable that
50 gives the full path name of the directory in which you want to put the
51 templates.
52
53 The easiest way to set up this "config" file, the associated directory,
54 and the necessary template files is to type:
55
56 > perl -MModule::Starter::PBP=setup
57
58 on the command line. You will then be asked for your name, email
59 address, and the full path name of the directory where you want to keep
60 the templates, after which they will be created and installed.
61
62 Then you can create a new module by typing:
63
64 > module-starter --module=Your::New::Module
65
66 Template format
67 The templates are plain files named:
68
69 Build.PL
70 Makefile.PL
71 README
72 Changes
73 Module.pm
74 t/whatever_you_like.t
75
76 The "Module.pm" file is the template for the ".pm" file for your
77 module. Any files in the "t/" subdirectory become the templates for the
78 testing files of your module. All the remaining files are templates for
79 the ditribution files of the same names.
80
81 In those files, the following placeholders are replaced by the
82 appropriate information specific to the file:
83
84 <AUTHOR>
85 The nominated author. Taken from the "author" setting in your
86 Module::Starter "config" file.
87
88 <BUILD INSTRUCTIONS>
89 Makefile or Module::Build instructions. Computed automatically
90 according to the "builder" setting in your Module::Starter "config"
91 file.
92
93 <DATE>
94 The current date (as returned by "localtime"). Computed
95 automagically
96
97 <DISTRO>
98 The name of the complete module distribution. Computed
99 automatically from the name of the module.
100
101 <EMAIL>
102 Where to send feedback. Taken from the "email" setting in your
103 Module::Starter "config" file.
104
105 <LICENSE>
106 The licence under which the module is released. Taken from the
107 "license" setting in your Module::Starter "config" file.
108
109 <MAIN MODULE>
110 The name of the main module of the distribution.
111
112 <MAIN PM FILE>
113 The name of the ".pm" file for the main module.
114
115 <MODULE NAME>
116 The name of the current module being created within the
117 distribution.
118
119 <RT NAME>
120 The name to use for bug reports to the RT system. That is:
121
122 Please report any bugs or feature requests to
123 bug-<RT NAME>@rt.cpan.org>
124
125 <YEAR>
126 The current year. Computed automatically
127
129 "Can't find directory that holds Module::Starter::PBP templates"
130 You did not tell Module::Starter::PBP where your templates are
131 stored. You need a 'template_dir' specification. Typically this
132 would go in your ~/.module-starter/config file. Something like:
133
134 template_dir: /users/you/.module-starter/Templates
135
136 "Can't access Module::Starter::PBP template directory"
137 You specified a 'template_dir', but the path didn't lead to a
138 readable directory.
139
140 "The template: %s isn't in the template directory (%s)"
141 One of the required templates:
142
143 was missing from the template directory you specified.
144
145 "The template: %s isn't readable in the template directory (%s)"
146 One of the templates in the template directory you specified was
147 not readable.
148
149 "Unknown placeholder <%s> in %s"
150 One of the templates in the template directory contained a
151 replacement item that wasn't a known piece of information.
152
154 See the documentation for "Module::Starter" and "module-starter".
155
157 Requires the "Module::Starter" module.
158
160 None reported.
161
163 No bugs have been reported.
164
165 Please report any bugs or feature requests to
166 "bug-module-starter-pbp@rt.cpan.org", or through the web interface at
167 <http://rt.cpan.org>.
168
170 Damian Conway "<DCONWAY@cpan.org>"
171
173 Copyright (c) 2005, Damian Conway "<DCONWAY@cpan.org>". All rights
174 reserved.
175
176 This module is free software; you can redistribute it and/or modify it
177 under the same terms as Perl itself.
178
180 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
181 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
182 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
183 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
184 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
185 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
186 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
187 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
188 NECESSARY SERVICING, REPAIR, OR CORRECTION.
189
190 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
191 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
192 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
193 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
194 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
195 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
196 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
197 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
198 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
199 DAMAGES.
200
201
202
203perl v5.28.1 2006-02-17 Module::Starter::PBP(3)