1MakeHelper(3) User Contributed Perl Documentation MakeHelper(3)
2
3
4
6 Glib::MakeHelper - Makefile.PL utilities for Glib-based extensions
7
9 eval "use Glib::MakeHelper; 1"
10 or complain_that_glib_is_too_old_and_die();
11
12 %xspod_files = Glib::MakeHelper->do_pod_files (@xs_files);
13
14 package MY;
15 sub postamble {
16 return Glib::MakeHelper->postamble_clean ()
17 . Glib::MakeHelper->postamble_docs (@main::xs_files)
18 . Glib::MakeHelper->postamble_rpms (
19 MYLIB => $build_reqs{MyLib},
20 );
21 }
22
24 The Makefile.PL for your typical Glib-based module is huge and hairy,
25 thanks to all the crazy hoops you have to jump through to get things
26 right. This module wraps up some of the more intense and error-prone
27 bits to reduce the amount of copied code and potential for errors.
28
30 HASH = Glib::MakeHelper->do_pod_files (@xs_files)
31 Scan the @xs_files and return a hash describing the pod files that
32 will be created. This is in the format wanted by WriteMakefile().
33 If @ARGV contains the string "disable-apidoc" an empty list will be
34 returned and thus no apidoc pod will be generated speeding up the
35 build process.
36
37 LIST = Glib::MakeHelper->select_files_by_version ($stem, $major,
38 $minor)
39 Returns a list of all files that match "$stem-\d+\.\d+" and for
40 which the first number is bigger than $major and the second number
41 is bigger than $minor. If $minor is odd, it will be incremented by
42 one so that the version number of an upcoming stable release can be
43 used during development as well.
44
45 LIST = Glib::MakeHelper->read_source_list_file ($filename)
46 Reads $filename, removes all comments (starting with "#") and lead‐
47 ing and trailing whitespace, and returns a list of all lines that
48 survived the treatment.
49
50 string = Glib::MakeHelper->postamble_clean (@files)
51 Create and return the text of a realclean rule that cleans up after
52 much of the autogeneration performed by Glib-based modules. Every‐
53 thing in @files will be deleted, too (it may be empty).
54
55 The reasoning behind using this instead of just having you use the
56 'clean' or 'realclean' keys is that this avoids you having to
57 remember to put Glib's stuff in your Makefile.PL's WriteMakefile
58 arguments.
59
60 string = Glib::MakeHelper->postamble_docs (@xs_files)
61 NOTE: this is The Old Way. see postamble_docs_full for The New
62 Way.
63
64 Create and return the text of Makefile rules to build documentation
65 from the XS files with Glib::ParseXSDoc and Glib::GenPod.
66
67 Use this in your MY::postamble to enable autogeneration of POD.
68
69 This updates dependencies with the list of pod names generated by
70 an earlier run of "do_pod_files".
71
72 There is a special Makefile variable POD_DEPENDS that should be set
73 to the list of files that need to be created before the doc.pl step
74 is run, include files.
75
76 There is also a variable BLIB_DONE which should be used as a depen‐
77 dency anywhere a rule needs to be sure that a loadable and working
78 module resides in the blib directory before running.
79
80 string = Glib::MakeHelper->postamble_docs_full (...)
81 Create and return the text of Makefile rules to build documentation
82 from the XS files with Glib::ParseXSDoc and Glib::GenPod.
83
84 Use this in your MY::postamble to enable autogeneration of POD.
85
86 This updates dependencies with the list of pod names generated by
87 an earlier run of "do_pod_files".
88
89 There is a special Makefile variable POD_DEPENDS that should be set
90 to the list of files that need to be created before the doc.pl step
91 is run, include files.
92
93 There is also a variable BLIB_DONE which should be used as a depen‐
94 dancy anywhere a rule needs to be sure that a loadable and working
95 module resides in the blib directory before running.
96
97 The parameters are a list of key=>value pairs. You must specify at
98 minimum either DEPENDS or XS_FILES.
99
100 DEPENDS => ExtUtils::Depends object
101 Most gtk2-perl modules use ExtUtils::Depends to find headers,
102 typemaps, and other data from parent modules and to install
103 this data for child modules. We can find from this object the
104 list of XS files to scan for documentation, doctype mappings
105 for parent modules, and other goodies.
106
107 XS_FILES => \@xs_file_names
108 A list of xs files to scan for documentation. Ignored if
109 DEPENDS is used.
110
111 DOCTYPES => \@doctypes_file_names
112 List of filenames to pass to "Glib::GenPod::add_types". May be
113 omitted.
114
115 COPYRIGHT => string
116 POD text to be inserted in the 'COPYRIGHT' section of each gen‐
117 erated page. May be omitted.
118
119 COPYRIGHT_FROM => file name
120 The name of a file containing the POD to be inserted in the
121 'COPYRIGHT' section of each generated page. May be omitted.
122
123 NAME => extension name
124 The name of the extension, used to set $Glib::GenPod::MAIN_MOD
125 (used in the generated see-also listings). May be omitted in
126 favor of the name held inside the ExtUtils::Depends object. If
127 DEPENDS is also specified, NAME wins.
128
129 string = Glib::MakeHelper->postamble_rpms (HASH)
130 Create and return the text of Makefile rules to manage building
131 RPMs. You'd put this in your Makefile.PL's MY::postamble.
132
133 HASH is a set of search and replace keys for the spec file. All
134 occurences of @key@ in the spec file template perl-$(DIST‐
135 NAME).spec.in will be replaced with value. 'VERSION' and 'SOURCE'
136 are supplied for you. For example:
137
138 Glib::MakeHelper->postamble_rpms (
139 MYLIB => 2.0.0, # we can work with anything from this up
140 MYLIB_RUN => 2.3.1, # we are actually compiled against this one
141 PERL_GLIB => 1.01, # you must have this version of Glib
142 );
143
144 will replace @MYLIB@, @MYLIB_RUN@, and @PERL_GLIB@ in spec file.
145 See the build setups for Glib and Gtk2 for examples.
146
147 Note: This function just returns an empty string on Win32.
148
150 The MakeMaker distributed with perl 5.8.x generates makefiles with a
151 bug that causes object files to be created in the wrong directory.
152 There is an override inserted by this module under the name
153 MY::const_cccmd to fix this issue.
154
156 Ross McFarland <rwmcfa1 at neces dot com>
157
158 hacked up and documented by muppet.
159
161 Copyright 2003-2004 by the gtk2-perl team
162
163 This library is free software; you can redistribute it and/or modify it
164 under the terms of the Lesser General Public License (LGPL). For more
165 information, see http://www.fsf.org/licenses/lgpl.txt
166
167
168
169perl v5.8.8 2007-02-26 MakeHelper(3)