lib/ExtUtils/MakeMaker/Tutorial.pod

   1 package ExtUtils::MakeMaker::Tutorial;
   2
   3 use vars qw($VERSION);
   4 $VERSION = 0.01;
   5
   6
   7 =head1 NAME
   8
   9 ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
  10
  11 =head1 SYNOPSIS
  12
  13     use ExtUtils::MakeMaker;
  14
  15     WriteMakefile(
  16         NAME            => 'Your::Module',
  17         VERSION_FROM    => 'lib/Your/Module.pm'
  18     );
  19
  20 =head1 DESCRIPTION
  21
  22 This is a short tutorial on writing a simple module with MakeMaker.
  23 Its really not that hard.
  24
  25
  26 =head2 The Mantra
  27
  28 MakeMaker modules are installed using this simple mantra
  29
  30         perl Makefile.PL
  31         make
  32         make test
  33         make install
  34
  35 There are lots more commands and options, but the above will do it.
  36
  37
  38 =head2 The Layout
  39
  40 The basic files in a module look something like this.
  41
  42         Makefile.PL
  43         MANIFEST
  44         lib/Your/Module.pm
  45
  46 That's all that's strictly necessary.  There's additional files you might
  47 want:
  48
  49         lib/Your/Other/Module.pm
  50         t/some_test.t
  51         t/some_other_test.t
  52         Changes
  53         README
  54         INSTALL
  55         MANIFEST.SKIP
  56         bin/some_program
  57
  58 =over 4
  59
  60 =item Makefile.PL
  61
  62 When you run Makefile.PL, it makes a Makefile.  That's the whole point of
  63 MakeMaker.  The Makefile.PL is a simple module which loads
  64 ExtUtils::MakeMaker and runs the WriteMakefile() function with a few
  65 simple arguments.
  66
  67 Here's an example of what you need for a simple module:
  68
  69     use ExtUtils::MakeMaker;
  70
  71     WriteMakefile(
  72         NAME            => 'Your::Module',
  73         VERSION_FROM    => 'lib/Your/Module.pm'
  74     );
  75
  76 NAME is the top-level namespace of your module.  VERSION_FROM is the file
  77 which contains the $VERSION variable for the entire distribution.  Typically
  78 this is the same as your top-level module.
  79
  80
  81 =item MANIFEST
  82
  83 A simple listing of all the files in your distribution.
  84
  85         Makefile.PL
  86         MANIFEST
  87         lib/Your/Module.pm
  88
  89 Filepaths in a MANIFEST always use Unix conventions (ie. /) even if you're
  90 not on Unix.
  91
  92 You can write this by hand or generate it with 'make manifest'.
  93
  94
  95 =item lib/
  96
  97 This is the directory where your .pm and .pod files you wish to have
  98 installed go.  They are layed out according to namespace.  So Foo::Bar
  99 is lib/Foo/Bar.pm.
 100
 101
 102 =item t/
 103
 104 Tests for your modules go here.  Each test filename ends with a .t.
 105 So t/foo.t.  'make test' will run these tests.  The directory is flat,
 106 you cannot, for example, have t/foo/bar.t run by 'make test'.
 107
 108 Tests are run from the top level of your distribution.  So inside a test
 109 you would refer to ./lib to enter the lib directory, for example.
 110
 111
 112 =item Changes
 113
 114 A log of changes you've made to this module.  The layout is free-form.
 115 Here's an example:
 116
 117     1.01 Fri Apr 11 00:21:25 PDT 2003
 118         - thing() does some stuff now
 119         - fixed the wiggy bug in withit()
 120
 121     1.00 Mon Apr  7 00:57:15 PDT 2003
 122         - "Rain of Frogs" now supported
 123
 124
 125 =item README
 126
 127 A short description of your module, what it does, why someone would use it
 128 and its limitations.  CPAN automatically pulls your README file out of
 129 the archive and makes it available to CPAN users, it is the first thing
 130 they will read to decide if your module is right for them.
 131
 132
 133 =item INSTALL
 134
 135 Instructions on how to install your module along with any dependencies.
 136 Suggested information to include here:
 137
 138     any extra modules required for use
 139     the minimum version of Perl required
 140     if only works on certain operating systems
 141
 142
 143 =item MANIFEST.SKIP
 144
 145 A file full of regular expressions to exclude when using 'make
 146 manifest' to generate the MANIFEST.  These regular expressions
 147 are checked against each filepath found in the distrubtion (so
 148 you're matching against "t/foo.t" not "foo.t").
 149
 150 Here's a sample:
 151
 152     ~$          # ignore emacs and vim backup files
 153     .bak$       # ignore manual backups
 154     \#          # ignore CVS old revision files and emacs temp files
 155
 156 Since # can be used for comments, # must be escaped.
 157
 158 MakeMaker comes with a default MANIFEST.SKIP to avoid things like
 159 version control directories and backup files.  Specifying your own
 160 will override this default.
 161
 162
 163 =item bin/
 164
 165
 166 =back
 167
 168 =head1 SEE ALSO
 169
 170 L<perlmodstyle> gives stylistic help writing a module.
 171
 172 L<perlnewmod> gives more information about how to write a module.
 173
 174 There are modules to help you through the process of writing a module:
 175 L<ExtUtils::ModuleMaker>, L<Module::Setup>, L<CPAN::MakeMaker>
 176
 177 =cut
 178
 179 1;