ExtUtils::MakeMaker 6.10_03 -> 6.10_04

[p5sagit/p5-mst-13.2.git] / lib / ExtUtils / MakeMaker / Tutorial.pod

diff --git a/lib/ExtUtils/MakeMaker/Tutorial.pod b/lib/ExtUtils/MakeMaker/Tutorial.pod
index bbc794a..b25e1bb 100644 (file)
--- a/lib/ExtUtils/MakeMaker/Tutorial.pod
+++ b/lib/ExtUtils/MakeMaker/Tutorial.pod
@@ -20,6 +20,8 @@ ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
 =head1 DESCRIPTION
 
 This is a short tutorial on writing a simple module with MakeMaker.
+Its really not that hard.
+
 
 =head2 The Mantra
 
@@ -32,16 +34,17 @@ MakeMaker modules are installed using this simple mantra
 
 There are lots more commands and options, but the above will do it.
 
+
 =head2 The Layout
 
-The basic layout of a module looks something like this.
+The basic files in a module look something like this.
 
         Makefile.PL
         MANIFEST
         lib/Your/Module.pm
 
 That's all that's strictly necessary.  There's additional files you might
-want to add:
+want:
 
         lib/Your/Other/Module.pm
         t/some_test.t
@@ -83,11 +86,17 @@ A simple listing of all the files in your distribution.
         MANIFEST
         lib/Your/Module.pm
 
+Filepaths in a MANIFEST always use Unix conventions (ie. /) even if you're
+not on Unix.
+
+You can write this by hand or generate it with 'make manifest'.
+
 
 =item lib/
 
-This is the directory where your .pm files go.  They are layed out
-according to namespace.  So Foo::Bar is lib/Foo/Bar.pm.
+This is the directory where your .pm and .pod files you wish to have
+installed go.  They are layed out according to namespace.  So Foo::Bar
+is lib/Foo/Bar.pm.
 
 
 =item t/
@@ -96,26 +105,72 @@ Tests for your modules go here.  Each test filename ends with a .t.
 So t/foo.t.  'make test' will run these tests.  The directory is flat,
 you cannot, for example, have t/foo/bar.t run by 'make test'.
 
+Tests are run from the top level of your distribution.  So inside a test
+you would refer to ./lib to enter the lib directory, for example.
+
 
 =item Changes
 
-A log of changes you've made to this module.
+A log of changes you've made to this module.  The layout is free-form.
+Here's an example:
+
+    1.01 Fri Apr 11 00:21:25 PDT 2003
+        - thing() does some stuff now
+        - fixed the wiggy bug in withit()
+
+    1.00 Mon Apr  7 00:57:15 PDT 2003
+        - "Rain of Frogs" now supported
 
 
 =item README
 
+A short description of your module, what it does, why someone would use it
+and its limitations.  CPAN automatically pulls your README file out of
+the archive and makes it available to CPAN users, it is the first thing
+they will read to decide if your module is right for them.
+
+
 =item INSTALL
 
+Instructions on how to install your module along with any dependencies.
+Suggested information to include here:
+
+    any extra modules required for use
+    the minimum version of Perl required
+    if only works on certain operating systems
+
+
 =item MANIFEST.SKIP
 
+A file full of regular expressions to exclude when using 'make
+manifest' to generate the MANIFEST.  These regular expressions
+are checked against each filepath found in the distrubtion (so
+you're matching against "t/foo.t" not "foo.t").
+
+Here's a sample:
+
+    ~$          # ignore emacs and vim backup files
+    .bak$       # ignore manual backups
+    \#          # ignore CVS old revision files and emacs temp files
+
+Since # can be used for comments, # must be escaped.
+
+MakeMaker comes with a default MANIFEST.SKIP to avoid things like
+version control directories and backup files.  Specifying your own
+will override this default.
+
+
 =item bin/
 
+
 =back
 
 =head1 SEE ALSO
 
 L<perlmodstyle> gives stylistic help writing a module.
 
+L<perlnewmod> gives more information about how to write a module.
+
 There are modules to help you through the process of writing a module:
 L<ExtUtils::ModuleMaker>, L<Module::Setup>, L<CPAN::MakeMaker>