summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod180
1 files changed, 180 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod b/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod
new file mode 100644
index 00000000000..8ad72649b1a
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/ExtUtils/MakeMaker/Tutorial.pod
@@ -0,0 +1,180 @@
+package ExtUtils::MakeMaker::Tutorial;
+
+our $VERSION = 0.02;
+
+
+=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.
+Its really not that hard.
+
+
+=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 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:
+
+ 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 program which loads
+ExtUtils::MakeMaker and runs the WriteMakefile() function to generate a
+Makefile.
+
+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
+
+File paths 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'.
+
+See L<ExtUtils::Manifest> for more details.
+
+
+=item lib/
+
+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 F<lib/Foo/Bar.pm>.
+
+
+=item t/
+
+Tests for your modules go here. Each test filename ends with a .t.
+So F<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. 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 file path found in the distribution (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::Install>, L<PAR>
+
+=cut
+
+1;