ExtUtils::MakeMaker::Tutorial(3p) Perl Programmers Reference Guide #

ExtUtils::MakeMaker::Tutorial(3p) Perl Programmers Reference Guide

NNAAMMEE #

 ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker

SSYYNNOOPPSSIISS #

     use ExtUtils::MakeMaker;

     WriteMakefile(
         NAME            => 'Your::Module',
         VERSION_FROM    => 'lib/Your/Module.pm'
     );

DDEESSCCRRIIPPTTIIOONN #

 This is a short tutorial on writing a simple module with MakeMaker.  It's
 really not that hard.

TThhee MMaannttrraa 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.

TThhee LLaayyoouutt 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

 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 WWrriitteeMMaakkeeffiillee(()) 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.

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 ExtUtils::Manifest for more details.

 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 _l_i_b_/_F_o_o_/_B_a_r_._p_m.

 t/  Tests for your modules go here.  Each test filename ends with a .t.
     So _t_/_f_o_o_._t  'make test' will run these tests.

     Typically, the _t_/ test directory is flat, with all test files located
     directly within it. However, you can nest tests within
     subdirectories, for example:

         t/foo/subdir_test.t

     To do this, you need to inform "WriteMakeFile()" in your _M_a_k_e_f_i_l_e_._P_L
     file in the following fashion:

         test => {TESTS => 't/*.t t/*/*.t'}

     That will run all tests in _t_/, as well as all tests in all
     subdirectories that reside under _t_/. You can nest as deeply as makes
     sense for your project.  Simply add another entry in the test
     location string. For example, to test:

         t/foo/bar/subdir_test.t

     You would use the following "test" directive:

         test => {TESTS => 't/*.t t/*/*/*.t'}

     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:

         test => {TESTS => 't/*.t t/*/*.t t/*/*/*.t'}

     You don't need to specify wildcards if you only want to test within
     specific subdirectories. The following example will only run tests in
     _t_/_f_o_o:

         test => {TESTS => 't/foo/*.t'}

     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.

 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

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.

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

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.

 bin/

SSEEEE AALLSSOO #

 perlmodstyle gives stylistic help writing a module.

 perlnewmod gives more information about how to write a module.

 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

perl v5.36.3 2023-02-15 ExtUtils::MakeMaker::Tutorial(3p)