Edit File: ExtUtils::MakeMaker::Tutorial.3pm
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" ======================================================================== .\" .IX Title "ExtUtils::MakeMaker::Tutorial 3" .TH ExtUtils::MakeMaker::Tutorial 3 "2014-12-02" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" ExtUtils::MakeMaker::Tutorial \- Writing a module with MakeMaker .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use ExtUtils::MakeMaker; \& \& WriteMakefile( \& NAME => \*(AqYour::Module\*(Aq, \& VERSION_FROM => \*(Aqlib/Your/Module.pm\*(Aq \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a short tutorial on writing a simple module with MakeMaker. It's really not that hard. .SS "The Mantra" .IX Subsection "The Mantra" MakeMaker modules are installed using this simple mantra .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .PP There are lots more commands and options, but the above will do it. .SS "The Layout" .IX Subsection "The Layout" The basic files in a module look something like this. .PP .Vb 3 \& Makefile.PL \& MANIFEST \& lib/Your/Module.pm .Ve .PP That's all that's strictly necessary. There's additional files you might want: .PP .Vb 8 \& lib/Your/Other/Module.pm \& t/some_test.t \& t/some_other_test.t \& Changes \& README \& INSTALL \& MANIFEST.SKIP \& bin/some_program .Ve .IP "Makefile.PL" 4 .IX 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 \fIWriteMakefile()\fR function to generate a Makefile. .Sp Here's an example of what you need for a simple module: .Sp .Vb 1 \& use ExtUtils::MakeMaker; \& \& WriteMakefile( \& NAME => \*(AqYour::Module\*(Aq, \& VERSION_FROM => \*(Aqlib/Your/Module.pm\*(Aq \& ); .Ve .Sp \&\s-1NAME\s0 is the top-level namespace of your module. \s-1VERSION_FROM\s0 is the file which contains the \f(CW$VERSION\fR variable for the entire distribution. Typically this is the same as your top-level module. .IP "\s-1MANIFEST\s0" 4 .IX Item "MANIFEST" A simple listing of all the files in your distribution. .Sp .Vb 3 \& Makefile.PL \& MANIFEST \& lib/Your/Module.pm .Ve .Sp File paths in a \s-1MANIFEST\s0 always use Unix conventions (ie. /) even if you're not on Unix. .Sp You can write this by hand or generate it with 'make manifest'. .Sp See ExtUtils::Manifest for more details. .IP "lib/" 4 .IX Item "lib/" This is the directory where the .pm and .pod files you wish to have installed go. They are laid out according to namespace. So Foo::Bar is \fIlib/Foo/Bar.pm\fR. .IP "t/" 4 .IX Item "t/" Tests for your modules go here. Each test filename ends with a .t. So \fIt/foo.t\fR/ 'make test' will run these tests. The directory is flat, you cannot, for example, have t/foo/bar.t run by 'make test'. .Sp 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. .IP "Changes" 4 .IX Item "Changes" A log of changes you've made to this module. The layout is free-form. Here's an example: .Sp .Vb 3 \& 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 .Ve .IP "\s-1README\s0" 4 .IX Item "README" A short description of your module, what it does, why someone would use it and its limitations. \s-1CPAN\s0 automatically pulls your \s-1README\s0 file out of the archive and makes it available to \s-1CPAN\s0 users, it is the first thing they will read to decide if your module is right for them. .IP "\s-1INSTALL\s0" 4 .IX Item "INSTALL" Instructions on how to install your module along with any dependencies. Suggested information to include here: .Sp .Vb 3 \& any extra modules required for use \& the minimum version of Perl required \& if only works on certain operating systems .Ve .IP "\s-1MANIFEST\s0.SKIP" 4 .IX Item "MANIFEST.SKIP" A file full of regular expressions to exclude when using 'make manifest' to generate the \s-1MANIFEST\s0. These regular expressions are checked against each file path found in the distribution (so you're matching against \*(L"t/foo.t\*(R" not \*(L"foo.t\*(R"). .Sp Here's a sample: .Sp .Vb 3 \& ~$ # ignore emacs and vim backup files \& .bak$ # ignore manual backups \& \e# # ignore CVS old revision files and emacs temp files .Ve .Sp Since # can be used for comments, # must be escaped. .Sp MakeMaker comes with a default \s-1MANIFEST\s0.SKIP to avoid things like version control directories and backup files. Specifying your own will override this default. .IP "bin/" 4 .IX Item "bin/" .SH "SEE ALSO" .IX Header "SEE ALSO" perlmodstyle gives stylistic help writing a module. .PP perlnewmod gives more information about how to write a module. .PP There are modules to help you through the process of writing a module: ExtUtils::ModuleMaker, Module::Install, \s-1PAR\s0
Back to File Manager