ExtUtils::MakeMaker 6.10_03 -> 6.10_04

Message-ID: <20030523091046.GB11662@windhund.schwern.org>

p4raw-id: //depot/perl@19594

3 files changed, 141 insertions, 6 deletions

diff --git a/lib/ExtUtils/MakeMaker/FAQ.pod b/lib/ExtUtils/MakeMaker/FAQ.pod
index 3e0489de33..38c50cef04 100644
--- a/lib/ExtUtils/MakeMaker/FAQ.pod
+++ b/lib/ExtUtils/MakeMaker/FAQ.pod
@@ -1,6 +1,6 @@
 package ExtUtils::MakeMaker::FAQ;
 
-our $VERSION = '0.02';
+(our $VERSION) = sprintf "%03d", q$Revision: 1.6 $ =~ /Revision:\s+(\S+)/;
 
 1;
 __END__
@@ -57,6 +57,47 @@ MakeMaker.
 
 =back
 
+=head2 Module Writing
+
+=over 4
+
+=item How do I keep my $VERSION up to date without resetting it manually?
+
+Often you want to manually set the $VERSION in the main module
+distribution because this is the version that everybody sees on CPAN
+and maybe you want to customize it a bit.  But for all the other
+modules in your dist, $VERSION is really just bookkeeping and all that's
+important is it goes up every time the module is changed.  Doing this
+by hand is a pain and you often forget.
+
+Simplest way to do it automatically is to use your version control
+system's revision number (you are using version control, right?).
+
+In CVS and RCS you use $Revision: 1.6 $ writing it like so:
+
+    $VERSION = sprintf "%d.%03d", q$Revision: 1.6 $ =~ /(\d+)/g;
+
+On your next check in, $Revision: 1.6 $ will magically be expanded to contain
+the current revision #.
+
+    $VERSION = sprintf "%d.%03d", q$Revision: 1.6 $ =~ /(\d+)/g;
+
+Every time the file is checked in the $Revision: 1.6 $ will be updated,
+updating your $VERSION.
+
+In CVS version 1.9 is followed by 1.10.  Since CPAN compares version
+numbers numerically we use a sprintf() to convert 1.9 to 1.009 and
+1.10 to 1.010 which compare properly.
+
+If branches are involved (ie. $Revision: 1.5.3.4) its a little more
+complicated.
+
+    # must be all on one line or MakeMaker will get confused.
+    $VERSION = do { my @r = (q$Revision: 1.6 $ =~ /\d+/g); sprintf "%d."."%03d" x $#r, @r };
+
+
+=back
+
 =head2 XS
 
 =over 4
diff --git a/lib/ExtUtils/MakeMaker/Tutorial.pod b/lib/ExtUtils/MakeMaker/Tutorial.pod
index bbc794a687..b25e1bb2be 100644
--- 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>
 
diff --git a/lib/ExtUtils/MakeMaker/bytes.pm b/lib/ExtUtils/MakeMaker/bytes.pm
new file mode 100644
index 0000000000..7b7e854420
--- /dev/null
+++ b/lib/ExtUtils/MakeMaker/bytes.pm
@@ -0,0 +1,39 @@
+package ExtUtils::MakeMaker::bytes;
+
+use vars qw($VERSION);
+$VERSION = 0.01;
+
+my $Have_Bytes = eval q{require bytes; 1;};
+
+sub import {
+    return unless $Have_Bytes;
+
+    shift;
+    unshift @_, 'bytes';
+
+    goto &bytes::import;
+}
+
+1;
+
+
+=head1 NAME
+
+ExtUtils::MakeMaker::bytes - Version agnostic bytes.pm
+
+=head1 SYNOPSIS
+
+  use just like bytes.pm
+
+=head1 DESCRIPTION
+
+bytes.pm was introduced with 5.6.  This means any code which has 'use
+bytes' in it won't even compile on 5.5.X.  Since bytes is a lexical
+pragma and must be used at compile time we can't simply wrap it in
+a BEGIN { eval 'use bytes' } block.
+
+ExtUtils::MakeMaker::bytes is just a very thin wrapper around bytes
+which works just like it when bytes.pm exists and everywhere else it
+does nothing.
+
+=cut