diff options
Diffstat (limited to 'upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl')
| -rw-r--r-- | upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl b/upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl new file mode 100644 index 00000000..a1ab0bc6 --- /dev/null +++ b/upstream/archlinux/man3/ExtUtils::MakeMaker::Tutorial.3perl @@ -0,0 +1,266 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" 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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'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 >0, 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. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "ExtUtils::MakeMaker::Tutorial 3perl" +.TH ExtUtils::MakeMaker::Tutorial 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" 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 \fBWriteMakefile()\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 +NAME is the top-level namespace of your module. VERSION_FROM 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 MANIFEST 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 MANIFEST 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. +.Sp +Typically, the \fIt/\fR test directory is flat, with all test files located +directly within it. However, you can nest tests within subdirectories, for +example: +.Sp +.Vb 1 +\& t/foo/subdir_test.t +.Ve +.Sp +To do this, you need to inform \f(CWWriteMakefile()\fR in your \fIMakefile.PL\fR file +in the following fashion: +.Sp +.Vb 1 +\& test => {TESTS => \*(Aqt/*.t t/*/*.t\*(Aq} +.Ve +.Sp +That will run all tests in \fIt/\fR, as well as all tests in all subdirectories +that reside under \fIt/\fR. You can nest as deeply as makes sense for your project. +Simply add another entry in the test location string. For example, to test: +.Sp +.Vb 1 +\& t/foo/bar/subdir_test.t +.Ve +.Sp +You would use the following \f(CW\*(C`test\*(C'\fR directive: +.Sp +.Vb 1 +\& test => {TESTS => \*(Aqt/*.t t/*/*/*.t\*(Aq} +.Ve +.Sp +Note that in the above example, tests in the first subdirectory will not be +run. To run all tests in the intermediary subdirectory preceding the one +the test files are in, you need to explicitly note it: +.Sp +.Vb 1 +\& test => {TESTS => \*(Aqt/*.t t/*/*.t t/*/*/*.t\*(Aq} +.Ve +.Sp +You don't need to specify wildcards if you only want to test within specific +subdirectories. The following example will only run tests in \fIt/foo\fR: +.Sp +.Vb 1 +\& test => {TESTS => \*(Aqt/foo/*.t\*(Aq} +.Ve +.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 README 4 +.IX 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. +.IP INSTALL 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 MANIFEST.SKIP 4 +.IX 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"). +.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 MANIFEST.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::Starter, Minilla::Tutorial, +Dist::Milla::Tutorial, Dist::Zilla::Starter |