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
  24 =head2 The Mantra
  25
  26 MakeMaker modules are installed using this simple mantra
  27
  28         perl Makefile.PL
  29         make
  30         make test
  31         make install
  32
  33 There are lots more commands and options, but the above will do it.
  34
  35 =head2 The Layout
  36
  37 The basic layout of a module looks something like this.
  38
  39         Makefile.PL
  40         MANIFEST
  41         lib/Your/Module.pm
  42
  43 That's all that's strictly necessary.  There's additional files you might
  44 want to add:
  45
  46         lib/Your/Other/Module.pm
  47         t/some_test.t
  48         t/some_other_test.t
  49         Changes
  50         README
  51         INSTALL
  52         MANIFEST.SKIP
  53         bin/some_program
  54
  55 =over 4
  56
  57 =item Makefile.PL
  58
  59 When you run Makefile.PL, it makes a Makefile.  That's the whole point of
  60 MakeMaker.  The Makefile.PL is a simple module which loads
  61 ExtUtils::MakeMaker and runs the WriteMakefile() function with a few
  62 simple arguments.
  63
  64 Here's an example of what you need for a simple module:
  65
  66     use ExtUtils::MakeMaker;
  67
  68     WriteMakefile(
  69         NAME            => 'Your::Module',
  70         VERSION_FROM    => 'lib/Your/Module.pm'
  71     );
  72
  73 NAME is the top-level namespace of your module.  VERSION_FROM is the file
  74 which contains the $VERSION variable for the entire distribution.  Typically
  75 this is the same as your top-level module.
  76
  77
  78 =item MANIFEST
  79
  80 A simple listing of all the files in your distribution.
  81
  82         Makefile.PL
  83         MANIFEST
  84         lib/Your/Module.pm
  85
  86
  87 =item lib/
  88
  89 This is the directory where your .pm files go.  They are layed out
  90 according to namespace.  So Foo::Bar is lib/Foo/Bar.pm.
  91
  92
  93 =item t/
  94
  95 Tests for your modules go here.  Each test filename ends with a .t.
  96 So t/foo.t.  'make test' will run these tests.  The directory is flat,
  97 you cannot, for example, have t/foo/bar.t run by 'make test'.
  98
  99
 100 =item Changes
 101
 102 A log of changes you've made to this module.
 103
 104
 105 =item README
 106
 107 =item INSTALL
 108
 109 =item MANIFEST.SKIP
 110
 111 =item bin/
 112
 113 =back
 114
 115 =head1 SEE ALSO
 116
 117 L<perlmodstyle> gives stylistic help writing a module.
 118
 119 There are modules to help you through the process of writing a module:
 120 L<ExtUtils::ModuleMaker>, L<Module::Setup>, L<CPAN::MakeMaker>
 121
 122 =cut
 123
 124 1;