Commit | Line | Data |
---|---|---|
479d2113 MS |
1 | package ExtUtils::MakeMaker::Tutorial; |
2 | ||
3 | use vars qw($VERSION); | |
4 | $VERSION = 0.01; | |
5 | ||
6 | ||
7 | =head1 NAME | |
8 | ||
9 | ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | use ExtUtils::MakeMaker; | |
14 | ||
15 | WriteMakefile( | |
16 | NAME => 'Your::Module', | |
17 | VERSION_FROM => 'lib/Your/Module.pm' | |
18 | ); | |
19 | ||
20 | =head1 DESCRIPTION | |
21 | ||
22 | This is a short tutorial on writing a simple module with MakeMaker. | |
23 | ||
24 | =head2 The Mantra | |
25 | ||
26 | MakeMaker modules are installed using this simple mantra | |
27 | ||
28 | perl Makefile.PL | |
29 | make | |
30 | make test | |
31 | make install | |
32 | ||
33 | There are lots more commands and options, but the above will do it. | |
34 | ||
35 | =head2 The Layout | |
36 | ||
37 | The basic layout of a module looks something like this. | |
38 | ||
39 | Makefile.PL | |
40 | MANIFEST | |
41 | lib/Your/Module.pm | |
42 | ||
43 | That's all that's strictly necessary. There's additional files you might | |
44 | want to add: | |
45 | ||
46 | lib/Your/Other/Module.pm | |
47 | t/some_test.t | |
48 | t/some_other_test.t | |
49 | Changes | |
50 | README | |
51 | INSTALL | |
52 | MANIFEST.SKIP | |
53 | bin/some_program | |
54 | ||
55 | =over 4 | |
56 | ||
57 | =item Makefile.PL | |
58 | ||
59 | When you run Makefile.PL, it makes a Makefile. That's the whole point of | |
60 | MakeMaker. The Makefile.PL is a simple module which loads | |
61 | ExtUtils::MakeMaker and runs the WriteMakefile() function with a few | |
62 | simple arguments. | |
63 | ||
64 | Here's an example of what you need for a simple module: | |
65 | ||
66 | use ExtUtils::MakeMaker; | |
67 | ||
68 | WriteMakefile( | |
69 | NAME => 'Your::Module', | |
70 | VERSION_FROM => 'lib/Your/Module.pm' | |
71 | ); | |
72 | ||
73 | NAME is the top-level namespace of your module. VERSION_FROM is the file | |
74 | which contains the $VERSION variable for the entire distribution. Typically | |
75 | this is the same as your top-level module. | |
76 | ||
77 | ||
78 | =item MANIFEST | |
79 | ||
80 | A simple listing of all the files in your distribution. | |
81 | ||
82 | Makefile.PL | |
83 | MANIFEST | |
84 | lib/Your/Module.pm | |
85 | ||
86 | ||
87 | =item lib/ | |
88 | ||
89 | This is the directory where your .pm files go. They are layed out | |
90 | according to namespace. So Foo::Bar is lib/Foo/Bar.pm. | |
91 | ||
92 | ||
93 | =item t/ | |
94 | ||
95 | Tests for your modules go here. Each test filename ends with a .t. | |
96 | So t/foo.t. 'make test' will run these tests. The directory is flat, | |
97 | you cannot, for example, have t/foo/bar.t run by 'make test'. | |
98 | ||
99 | ||
100 | =item Changes | |
101 | ||
102 | A log of changes you've made to this module. | |
103 | ||
104 | ||
105 | =item README | |
106 | ||
107 | =item INSTALL | |
108 | ||
109 | =item MANIFEST.SKIP | |
110 | ||
111 | =item bin/ | |
112 | ||
113 | =back | |
114 | ||
115 | =head1 SEE ALSO | |
116 | ||
117 | L<perlmodstyle> gives stylistic help writing a module. | |
118 | ||
119 | There are modules to help you through the process of writing a module: | |
120 | L<ExtUtils::ModuleMaker>, L<Module::Setup>, L<CPAN::MakeMaker> | |
121 | ||
122 | =cut | |
123 | ||
124 | 1; |