1Glib::MakeHelper(3)   User Contributed Perl Documentation  Glib::MakeHelper(3)
2
3
4

NAME

6       Glib::MakeHelper - Makefile.PL utilities for Glib-based extensions
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

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
47           leading and trailing whitespace, and returns a list of all lines
48           that survived the treatment.
49
50       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
57           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
61       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
66           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
71       string = Glib::MakeHelper->postamble_docs (@xs_files)
72           NOTE: this is The Old Way.  see postamble_docs_full for The New
73           Way.
74
75           Create and return the text of Makefile rules to build documentation
76           from the XS files with Glib::ParseXSDoc and Glib::GenPod.
77
78           Use this in your MY::postamble to enable autogeneration of POD.
79
80           This updates dependencies with the list of pod names generated by
81           an earlier run of "do_pod_files".
82
83           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
87           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
91       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
95           Use this in your MY::postamble to enable autogeneration of POD.
96
97           This updates dependencies with the list of pod names generated by
98           an earlier run of "do_pod_files".
99
100           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
104           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
108           The parameters are a list of key=>value pairs.  You must specify at
109           minimum either DEPENDS or XS_FILES.
110
111           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
118           XS_FILES => \@xs_file_names
119               A list of xs files to scan for documentation.  Ignored if
120               DEPENDS is used.
121
122           DOCTYPES => \@doctypes_file_names
123               List of filenames to pass to "Glib::GenPod::add_types".  May be
124               omitted.
125
126           COPYRIGHT => string
127               POD text to be inserted in the 'COPYRIGHT' section of each
128               generated page.  May be omitted.
129
130           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
134           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
140       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
144           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
149            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
155           will replace @MYLIB@, @MYLIB_RUN@, and @PERL_GLIB@ in spec file.
156           See the build setups for Glib and Gtk2 for examples.
157
158           Note: This function just returns an empty string on Win32.
159
160       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

NOTICE

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

AUTHOR

173       Ross McFarland <rwmcfa1 at neces dot com>
174
175       hacked up and documented by muppet.
176
178       Copyright 2003-2004, 2012 by the gtk2-perl team
179
180       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
183
184
185
186perl v5.38.0                      2023-08-01               Glib::MakeHelper(3)
Impressum