local-lib5/man/man3/ExtUtils::MakeMaker::Tutorial.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ExtUtils::MakeMaker::Tutorial 3"
 132 .TH ExtUtils::MakeMaker::Tutorial 3 "2009-07-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 ExtUtils::MakeMaker::Tutorial \- Writing a module with MakeMaker
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    use ExtUtils::MakeMaker;
 139 .Ve
 140 .PP
 141 .Vb 4
 142 \&    WriteMakefile(
 143 \&        NAME            => 'Your::Module',
 144 \&        VERSION_FROM    => 'lib/Your/Module.pm'
 145 \&    );
 146 .Ve
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 This is a short tutorial on writing a simple module with MakeMaker.
 150 Its really not that hard.
 151 .Sh "The Mantra"
 152 .IX Subsection "The Mantra"
 153 MakeMaker modules are installed using this simple mantra
 154 .PP
 155 .Vb 4
 156 \&        perl Makefile.PL
 157 \&        make
 158 \&        make test
 159 \&        make install
 160 .Ve
 161 .PP
 162 There are lots more commands and options, but the above will do it.
 163 .Sh "The Layout"
 164 .IX Subsection "The Layout"
 165 The basic files in a module look something like this.
 166 .PP
 167 .Vb 3
 168 \&        Makefile.PL
 169 \&        MANIFEST
 170 \&        lib/Your/Module.pm
 171 .Ve
 172 .PP
 173 That's all that's strictly necessary.  There's additional files you might
 174 want:
 175 .PP
 176 .Vb 8
 177 \&        lib/Your/Other/Module.pm
 178 \&        t/some_test.t
 179 \&        t/some_other_test.t
 180 \&        Changes
 181 \&        README
 182 \&        INSTALL
 183 \&        MANIFEST.SKIP
 184 \&        bin/some_program
 185 .Ve
 186 .IP "Makefile.PL" 4
 187 .IX Item "Makefile.PL"
 188 When you run Makefile.PL, it makes a Makefile.  That's the whole point of
 189 MakeMaker.  The Makefile.PL is a simple program which loads
 190 ExtUtils::MakeMaker and runs the \fIWriteMakefile()\fR function to generate a
 191 Makefile.
 192 .Sp
 193 Here's an example of what you need for a simple module:
 194 .Sp
 195 .Vb 1
 196 \&    use ExtUtils::MakeMaker;
 197 .Ve
 198 .Sp
 199 .Vb 4
 200 \&    WriteMakefile(
 201 \&        NAME            => 'Your::Module',
 202 \&        VERSION_FROM    => 'lib/Your/Module.pm'
 203 \&    );
 204 .Ve
 205 .Sp
 206 \&\s-1NAME\s0 is the top-level namespace of your module.  \s-1VERSION_FROM\s0 is the file
 207 which contains the \f(CW$VERSION\fR variable for the entire distribution.  Typically
 208 this is the same as your top-level module.
 209 .IP "\s-1MANIFEST\s0" 4
 210 .IX Item "MANIFEST"
 211 A simple listing of all the files in your distribution.
 212 .Sp
 213 .Vb 3
 214 \&        Makefile.PL
 215 \&        MANIFEST
 216 \&        lib/Your/Module.pm
 217 .Ve
 218 .Sp
 219 File paths in a \s-1MANIFEST\s0 always use Unix conventions (ie. /) even if you're
 220 not on Unix.
 221 .Sp
 222 You can write this by hand or generate it with 'make manifest'.
 223 .Sp
 224 See ExtUtils::Manifest for more details.
 225 .IP "lib/" 4
 226 .IX Item "lib/"
 227 This is the directory where your .pm and .pod files you wish to have
 228 installed go.  They are layed out according to namespace.  So Foo::Bar
 229 is \fIlib/Foo/Bar.pm\fR.
 230 .IP "t/" 4
 231 .IX Item "t/"
 232 Tests for your modules go here.  Each test filename ends with a .t.
 233 So \fIt/foo.t\fR/  'make test' will run these tests.  The directory is flat,
 234 you cannot, for example, have t/foo/bar.t run by 'make test'.
 235 .Sp
 236 Tests are run from the top level of your distribution.  So inside a test
 237 you would refer to ./lib to enter the lib directory, for example.
 238 .IP "Changes" 4
 239 .IX Item "Changes"
 240 A log of changes you've made to this module.  The layout is free\-form.
 241 Here's an example:
 242 .Sp
 243 .Vb 3
 244 \&    1.01 Fri Apr 11 00:21:25 PDT 2003
 245 \&        \- thing() does some stuff now
 246 \&        \- fixed the wiggy bug in withit()
 247 .Ve
 248 .Sp
 249 .Vb 2
 250 \&    1.00 Mon Apr  7 00:57:15 PDT 2003
 251 \&        \- "Rain of Frogs" now supported
 252 .Ve
 253 .IP "\s-1README\s0" 4
 254 .IX Item "README"
 255 A short description of your module, what it does, why someone would use it
 256 and its limitations.  \s-1CPAN\s0 automatically pulls your \s-1README\s0 file out of
 257 the archive and makes it available to \s-1CPAN\s0 users, it is the first thing
 258 they will read to decide if your module is right for them.
 259 .IP "\s-1INSTALL\s0" 4
 260 .IX Item "INSTALL"
 261 Instructions on how to install your module along with any dependencies.
 262 Suggested information to include here:
 263 .Sp
 264 .Vb 3
 265 \&    any extra modules required for use
 266 \&    the minimum version of Perl required
 267 \&    if only works on certain operating systems
 268 .Ve
 269 .IP "\s-1MANIFEST\s0.SKIP" 4
 270 .IX Item "MANIFEST.SKIP"
 271 A file full of regular expressions to exclude when using 'make
 272 manifest' to generate the \s-1MANIFEST\s0.  These regular expressions
 273 are checked against each file path found in the distribution (so
 274 you're matching against \*(L"t/foo.t\*(R" not \*(L"foo.t\*(R").
 275 .Sp
 276 Here's a sample:
 277 .Sp
 278 .Vb 3
 279 \&    ~$          # ignore emacs and vim backup files
 280 \&    .bak$       # ignore manual backups
 281 \&    \e#          # ignore CVS old revision files and emacs temp files
 282 .Ve
 283 .Sp
 284 Since # can be used for comments, # must be escaped.
 285 .Sp
 286 MakeMaker comes with a default \s-1MANIFEST\s0.SKIP to avoid things like
 287 version control directories and backup files.  Specifying your own
 288 will override this default.
 289 .IP "bin/" 4
 290 .IX Item "bin/"
 291 .SH "SEE ALSO"
 292 .IX Header "SEE ALSO"
 293 perlmodstyle gives stylistic help writing a module.
 294 .PP
 295 perlnewmod gives more information about how to write a module.
 296 .PP
 297 There are modules to help you through the process of writing a module:
 298 ExtUtils::ModuleMaker, Module::Install, \s-1PAR\s0