1Glib::MakeHelper(3) User Contributed Perl Documentation Glib::MakeHelper(3)
2
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 %xspod_files = Glib::MakeHelper->do_pod_files (@xs_files);
13 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 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 LIST = Glib::MakeHelper->read_source_list_file ($filename)
46 Reads $filename, removes all comments (starting with "#") and
47 leading and trailing whitespace, and returns a list of all lines
48 that survived the treatment.
49 string = Glib::MakeHelper->get_configure_requires_yaml
51 (%module_to_version)
52 Generates YAML code that lists every module found in
53 %module_to_version under the "configure_requires" key. This can be
54 used with ExtUtils::MakeMaker's "EXTRA_META" parameter to specify
55 which modules are needed at Makefile.PL time.
56 This function is deprecated since ExtUtils::MakeMaker 6.46 removed
58 support for "EXTRA_META" in favor of the new keys "META_MERGE" and
59 "META_ADD".
60 string = Glib::MakeHelper->postamble_clean (@files)
62 Create and return the text of a realclean rule that cleans up after
63 much of the autogeneration performed by Glib-based modules.
64 Everything in @files will be deleted, too (it may be empty).
65 The reasoning behind using this instead of just having you use the
67 'clean' or 'realclean' keys is that this avoids you having to
68 remember to put Glib's stuff in your Makefile.PL's WriteMakefile
69 arguments.
70 string = Glib::MakeHelper->postamble_docs (@xs_files)
72 NOTE: this is The Old Way. see postamble_docs_full for The New
73 Way.
74 Create and return the text of Makefile rules to build documentation
76 from the XS files with Glib::ParseXSDoc and Glib::GenPod.
77 Use this in your MY::postamble to enable autogeneration of POD.
79 This updates dependencies with the list of pod names generated by
81 an earlier run of "do_pod_files".
82 There is a special Makefile variable POD_DEPENDS that should be set
84 to the list of files that need to be created before the doc.pl step
85 is run, include files.
86 There is also a variable BLIB_DONE which should be used as a
88 dependency anywhere a rule needs to be sure that a loadable and
89 working module resides in the blib directory before running.
90 string = Glib::MakeHelper->postamble_docs_full (...)
92 Create and return the text of Makefile rules to build documentation
93 from the XS files with Glib::ParseXSDoc and Glib::GenPod.
94 Use this in your MY::postamble to enable autogeneration of POD.
96 This updates dependencies with the list of pod names generated by
98 an earlier run of "do_pod_files".
99 There is a special Makefile variable POD_DEPENDS that should be set
101 to the list of files that need to be created before the doc.pl step
102 is run, include files.
103 There is also a variable BLIB_DONE which should be used as a
105 dependency anywhere a rule needs to be sure that a loadable and
106 working module resides in the blib directory before running.
107 The parameters are a list of key=>value pairs. You must specify at
109 minimum either DEPENDS or XS_FILES.
110 DEPENDS => ExtUtils::Depends object
112 Most gtk2-perl modules use ExtUtils::Depends to find headers,
113 typemaps, and other data from parent modules and to install
114 this data for child modules. We can find from this object the
115 list of XS files to scan for documentation, doctype mappings
116 for parent modules, and other goodies.
117 XS_FILES => \@xs_file_names
119 A list of xs files to scan for documentation. Ignored if
120 DEPENDS is used.
121 DOCTYPES => \@doctypes_file_names
123 List of filenames to pass to "Glib::GenPod::add_types". May be
124 omitted.
125 COPYRIGHT => string
127 POD text to be inserted in the 'COPYRIGHT' section of each
128 generated page. May be omitted.
129 COPYRIGHT_FROM => file name
131 The name of a file containing the POD to be inserted in the
132 'COPYRIGHT' section of each generated page. May be omitted.
133 NAME => extension name
135 The name of the extension, used to set the main mod for
136 Glib::GenPod (used in the generated see-also listings). May be
137 omitted in favor of the name held inside the ExtUtils::Depends
138 object. If DEPENDS is also specified, NAME wins.
139 string = Glib::MakeHelper->postamble_rpms (HASH)
141 Create and return the text of Makefile rules to manage building
142 RPMs. You'd put this in your Makefile.PL's MY::postamble.
143 HASH is a set of search and replace keys for the spec file. All
145 occurrences of @key@ in the spec file template
146 perl-$(DISTNAME).spec.in will be replaced with value. 'VERSION'
147 and 'SOURCE' are supplied for you. For example:
148 Glib::MakeHelper->postamble_rpms (
150 MYLIB => 2.0.0, # we can work with anything from this up
151 MYLIB_RUN => 2.3.1, # we are actually compiled against this one
152 PERL_GLIB => 1.01, # you must have this version of Glib
153 );
154 will replace @MYLIB@, @MYLIB_RUN@, and @PERL_GLIB@ in spec file.
156 See the build setups for Glib and Gtk2 for examples.
157 Note: This function just returns an empty string on Win32.
159 string = Glib::MakeHelper->postamble_precompiled_headers (@headers)
161 Create and return the text of Makefile rules for a
162 'precompiled-headers' target that precompiles @headers. If you
163 call this before you call "postamble_clean", all temporary files
164 will be removed by the 'realclean' target.
165
167 The MakeMaker distributed with perl 5.8.x generates makefiles with a
168 bug that causes object files to be created in the wrong directory.
169 There is an override inserted by this module under the name
170 MY::const_cccmd to fix this issue.
171
173 Ross McFarland <rwmcfa1 at neces dot com>
174 hacked up and documented by muppet.
176
178 Copyright 2003-2004, 2012 by the gtk2-perl team
179 This library is free software; you can redistribute it and/or modify it
181 under the terms of the Lesser General Public License (LGPL). For more
182 information, see http://www.fsf.org/licenses/lgpl.txt
183perl v5.38.0 2023-08-01 Glib::MakeHelper(3)