ExtUtils::MakeMaker 6.03 -> 6.06_05ish

Message-ID: <20030331104257.GB15327@windhund.schwern.org>

p4raw-id: //depot/perl@19099

3 files changed, 363 insertions, 0 deletions

diff --git a/lib/ExtUtils/MakeMaker/FAQ.pod b/lib/ExtUtils/MakeMaker/FAQ.pod
new file mode 100644
index 0000000000..6d7ba70202
--- /dev/null
+++ b/lib/ExtUtils/MakeMaker/FAQ.pod
@@ -0,0 +1,199 @@
+package ExtUtils::MakeMaker::FAQ;
+
+our $VERSION = '0.02';
+
+1;
+__END__
+
+=head1 NAME
+
+ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About MakeMaker
+
+=head1 DESCRIPTION
+
+FAQs, tricks and tips for C<ExtUtils::MakeMaker>.
+
+=head2 Philosophy and History
+
+=over 4
+
+=item Why not just use <insert other build config tool here>?
+
+Why did MakeMaker reinvent the build configuration wheel?  Why not
+just use autoconf or automake or ppm or Ant or ...
+
+There are many reasons, but the major one is cross-platform
+compatibility.
+
+Perl is one of the most ported pieces of software ever.  It works on
+operating systems I've never even heard of (see perlport for details).
+It needs a build tool that can work on all those platforms and with
+any wacky C compilers they might have.
+
+No such build tool existed at the time and I only know of one now
+(Module::Build).
+
+
+=item What's Module::Build and how does it relate to MakeMaker?
+
+Module::Build is a project by Ken Williams to supplant MakeMaker.
+Its primary advantages are:
+
+=over 8
+
+=item * pure perl.  no make, no shell commands
+
+=item * easier to customize
+
+=item * cleaner internals
+
+=item * less cruft
+
+=back
+
+Module::Build is the official heir apparent to MakeMaker and we
+encourage people to work on M::B rather than spending time improving
+MakeMaker.
+
+=back
+
+=head2 XS
+
+=over 4
+
+=item How do I make two or more XS files coexist in the same directory?
+
+Sometimes you need to have two and more XS files in the same package.
+One way to go is to put them into separate directories, but sometimes
+this is not the most suitable solution. The following technique allows
+you to put two (and more) XS files in the same directory.
+
+Let's assume that we have a package C<Cool::Foo>, which includes
+C<Cool::Foo> and C<Cool::Bar> modules each having a separate XS
+file. First we use the following I<Makefile.PL>:
+
+  use ExtUtils::MakeMaker;
+
+  WriteMakefile(
+      NAME		=> 'Cool::Foo',
+      VERSION_FROM	=> 'Foo.pm',
+      OBJECT              => q/$(O_FILES)/,
+      # ... other attrs ...
+  );
+
+Notice the C<OBJECT> attribute. MakeMaker generates the following
+variables in I<Makefile>:
+
+  # Handy lists of source code files:
+  XS_FILES= Bar.xs \
+  	Foo.xs
+  C_FILES = Bar.c \
+  	Foo.c
+  O_FILES = Bar.o \
+  	Foo.o
+
+Therefore we can use the C<O_FILES> variable to tell MakeMaker to use
+these objects into the shared library.
+
+That's pretty much it. Now write I<Foo.pm> and I<Foo.xs>, I<Bar.pm>
+and I<Bar.xs>, where I<Foo.pm> bootstraps the shared library and
+I<Bar.pm> simply loading I<Foo.pm>.
+
+The only issue left is to how to bootstrap I<Bar.xs>. This is done
+from I<Foo.xs>:
+
+  MODULE = Cool::Foo PACKAGE = Cool::Foo
+
+  BOOT:
+  # boot the second XS file
+  boot_Cool__Bar(aTHX_ cv);
+
+If you have more than two files, this is the place where you should
+boot extra XS files from.
+
+The following four files sum up all the details discussed so far.
+
+  Foo.pm:
+  -------
+  package Cool::Foo;
+
+  require DynaLoader;
+
+  our @ISA = qw(DynaLoader);
+  our $VERSION = '0.01';
+  bootstrap Cool::Foo $VERSION;
+
+  1;
+
+  Bar.pm:
+  -------
+  package Cool::Bar;
+
+  use Cool::Foo; # bootstraps Bar.xs
+
+  1;
+
+  Foo.xs:
+  -------
+  #include "EXTERN.h"
+  #include "perl.h"
+  #include "XSUB.h"
+
+  MODULE = Cool::Foo  PACKAGE = Cool::Foo
+
+  BOOT:
+  # boot the second XS file
+  boot_Cool__Bar(aTHX_ cv);
+
+  MODULE = Cool::Foo  PACKAGE = Cool::Foo  PREFIX = cool_foo_
+
+  void
+  cool_foo_perl_rules()
+
+      CODE:
+      fprintf(stderr, "Cool::Foo says: Perl Rules\n");
+
+  Bar.xs:
+  -------
+  #include "EXTERN.h"
+  #include "perl.h"
+  #include "XSUB.h"
+
+  MODULE = Cool::Bar  PACKAGE = Cool::Bar PREFIX = cool_bar_
+
+  void
+  cool_bar_perl_rules()
+
+      CODE:
+      fprintf(stderr, "Cool::Bar says: Perl Rules\n");
+
+And of course a very basic test:
+
+  test.pl:
+  --------
+  use Test;
+  BEGIN { plan tests => 1 };
+  use Cool::Foo;
+  use Cool::Bar;
+  Cool::Foo::perl_rules();
+  Cool::Bar::perl_rules();
+  ok 1;
+
+This tip has been brought to you by Nick Ing-Simmons and Stas Bekman.
+
+=back
+
+=head1 PATCHING
+
+If you have a question you'd like to see added to the FAQ (whether or
+not you have the answer) please send it to makemaker@perl.org.
+
+=head1 AUTHOR
+
+The denizens of makemaker@perl.org.
+
+=head1 SEE ALSO
+
+L<ExtUtils::MakeMaker>
+
+=cut
diff --git a/lib/ExtUtils/MakeMaker/Tutorial.pod b/lib/ExtUtils/MakeMaker/Tutorial.pod
new file mode 100644
index 0000000000..bbc794a687
--- /dev/null
+++ b/lib/ExtUtils/MakeMaker/Tutorial.pod
@@ -0,0 +1,124 @@
+package ExtUtils::MakeMaker::Tutorial;
+
+use vars qw($VERSION);
+$VERSION = 0.01;
+
+
+=head1 NAME
+
+ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
+
+=head1 SYNOPSIS
+
+    use ExtUtils::MakeMaker;
+
+    WriteMakefile(
+        NAME            => 'Your::Module',
+        VERSION_FROM    => 'lib/Your/Module.pm'
+    );
+
+=head1 DESCRIPTION
+
+This is a short tutorial on writing a simple module with MakeMaker.
+
+=head2 The Mantra
+
+MakeMaker modules are installed using this simple mantra
+
+        perl Makefile.PL
+        make
+        make test
+        make install
+
+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.
+
+        Makefile.PL
+        MANIFEST
+        lib/Your/Module.pm
+
+That's all that's strictly necessary.  There's additional files you might
+want to add:
+
+        lib/Your/Other/Module.pm
+        t/some_test.t
+        t/some_other_test.t
+        Changes
+        README
+        INSTALL
+        MANIFEST.SKIP
+        bin/some_program
+
+=over 4
+
+=item Makefile.PL
+
+When you run Makefile.PL, it makes a Makefile.  That's the whole point of
+MakeMaker.  The Makefile.PL is a simple module which loads
+ExtUtils::MakeMaker and runs the WriteMakefile() function with a few
+simple arguments.
+
+Here's an example of what you need for a simple module:
+
+    use ExtUtils::MakeMaker;
+
+    WriteMakefile(
+        NAME            => 'Your::Module',
+        VERSION_FROM    => 'lib/Your/Module.pm'
+    );
+
+NAME is the top-level namespace of your module.  VERSION_FROM is the file
+which contains the $VERSION variable for the entire distribution.  Typically
+this is the same as your top-level module.
+
+
+=item MANIFEST
+
+A simple listing of all the files in your distribution.
+
+        Makefile.PL
+        MANIFEST
+        lib/Your/Module.pm
+
+
+=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.
+
+
+=item t/
+
+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'.
+
+
+=item Changes
+
+A log of changes you've made to this module.
+
+
+=item README
+
+=item INSTALL
+
+=item MANIFEST.SKIP
+
+=item bin/
+
+=back
+
+=head1 SEE ALSO
+
+L<perlmodstyle> gives stylistic help writing a module.
+
+There are modules to help you through the process of writing a module:
+L<ExtUtils::ModuleMaker>, L<Module::Setup>, L<CPAN::MakeMaker>
+
+=cut
+
+1;
diff --git a/lib/ExtUtils/MakeMaker/vmsish.pm b/lib/ExtUtils/MakeMaker/vmsish.pm
new file mode 100644
index 0000000000..5380ba569a
--- /dev/null
+++ b/lib/ExtUtils/MakeMaker/vmsish.pm
@@ -0,0 +1,40 @@
+package ExtUtils::MakeMaker::vmsish;
+
+use vars qw($VERSION);
+$VERSION = 0.01;
+
+my $IsVMS = $^O eq 'VMS';
+
+require vmsish if $IsVMS;
+
+
+sub import {
+    return unless $IsVMS;
+
+    shift;
+    unshift @_, 'vmsish';
+
+    goto &vmsish::import;
+}
+
+1;
+
+
+=head1 NAME
+
+ExtUtils::MakeMaker::vmsish - Platform agnostic vmsish.pm
+
+=head1 SYNOPSIS
+
+  use just like vmsish.pm
+
+=head1 DESCRIPTION
+
+Until 5.8.0, vmsish.pm is only installed on VMS.  This means any code
+which has 'use vmsish' in it won't even compile outside VMS.  This
+makes ExtUtils::MM_VMS very hard to test.
+
+ExtUtils::MakeMaker::vmsish is just a very thin wrapper around vmsish
+which works just like it on VMS and everywhere else it does nothing.
+
+=cut