[Summary view] [Print] [Text view]

   1  package ExtUtils::MakeMaker::Tutorial;
   2  
   3  use vars qw($VERSION);
   4  $VERSION = 0.02;
   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 program which loads
  64  ExtUtils::MakeMaker and runs the WriteMakefile() function to generate a
  65  Makefile.
  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  File paths 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  See L<ExtUtils::Manifest> for more details.
  95  
  96  
  97  =item lib/
  98  
  99  This is the directory where your .pm and .pod files you wish to have
 100  installed go.  They are layed out according to namespace.  So Foo::Bar
 101  is F<lib/Foo/Bar.pm>.
 102  
 103  
 104  =item t/
 105  
 106  Tests for your modules go here.  Each test filename ends with a .t.
 107  So F<t/foo.t>/  'make test' will run these tests.  The directory is flat,
 108  you cannot, for example, have t/foo/bar.t run by 'make test'.
 109  
 110  Tests are run from the top level of your distribution.  So inside a test
 111  you would refer to ./lib to enter the lib directory, for example.
 112  
 113  
 114  =item Changes
 115  
 116  A log of changes you've made to this module.  The layout is free-form.
 117  Here's an example:
 118  
 119      1.01 Fri Apr 11 00:21:25 PDT 2003
 120          - thing() does some stuff now
 121          - fixed the wiggy bug in withit()
 122  
 123      1.00 Mon Apr  7 00:57:15 PDT 2003
 124          - "Rain of Frogs" now supported
 125  
 126  
 127  =item README
 128  
 129  A short description of your module, what it does, why someone would use it
 130  and its limitations.  CPAN automatically pulls your README file out of
 131  the archive and makes it available to CPAN users, it is the first thing
 132  they will read to decide if your module is right for them.
 133  
 134  
 135  =item INSTALL
 136  
 137  Instructions on how to install your module along with any dependencies.
 138  Suggested information to include here:
 139  
 140      any extra modules required for use
 141      the minimum version of Perl required
 142      if only works on certain operating systems
 143  
 144  
 145  =item MANIFEST.SKIP
 146  
 147  A file full of regular expressions to exclude when using 'make
 148  manifest' to generate the MANIFEST.  These regular expressions
 149  are checked against each file path found in the distribution (so
 150  you're matching against "t/foo.t" not "foo.t").
 151  
 152  Here's a sample:
 153  
 154      ~$          # ignore emacs and vim backup files
 155      .bak$       # ignore manual backups
 156      \#          # ignore CVS old revision files and emacs temp files
 157  
 158  Since # can be used for comments, # must be escaped.
 159  
 160  MakeMaker comes with a default MANIFEST.SKIP to avoid things like
 161  version control directories and backup files.  Specifying your own
 162  will override this default.
 163  
 164  
 165  =item bin/
 166  
 167  
 168  =back
 169  
 170  =head1 SEE ALSO
 171  
 172  L<perlmodstyle> gives stylistic help writing a module.
 173  
 174  L<perlnewmod> gives more information about how to write a module.
 175  
 176  There are modules to help you through the process of writing a module:
 177  L<ExtUtils::ModuleMaker>, L<Module::Install>, L<PAR>
 178  
 179  =cut
 180  
 181  1;