Debian Codegraph @

README

raw
1 NAME
2 ExtUtils::Depends - Easily build XS extensions that depend on XS
3 extensions
4
5 SYNOPSIS
6 use ExtUtils::Depends;
7 $package = new ExtUtils::Depends ('pkg::name', 'base::package')
8 # set the flags and libraries to compile and link the module
9 $package->set_inc("-I/opt/blahblah");
10 $package->set_libs("-lmylib");
11 # add a .c and an .xs file to compile
12 $package->add_c('code.c');
13 $package->add_xs('module-code.xs');
14 # add the typemaps to use
15 $package->add_typemaps("typemap");
16 # install some extra data files and headers
17 $package->install (qw/foo.h data.txt/);
18 # save the info
19 $package->save_config('Files.pm');
20
21 WriteMakefile(
22 'NAME' => 'Mymodule',
23 $package->get_makefile_vars()
24 );
25
26 DESCRIPTION
27 This module tries to make it easy to build Perl extensions that use
28 functions and typemaps provided by other perl extensions. This means
29 that a perl extension is treated like a shared library that provides
30 also a C and an XS interface besides the perl one.
31
32 This works as long as the base (or "producing") extension is loaded with
33 the "RTLD_GLOBAL" flag (usually done with a
34
35 sub dl_load_flags {0x01}
36
37 in the main .pm file) if you need to use functions defined in the
38 module. That "producing" extension will also need to tell
39 ExtUtils::MakeMaker the specific functions to export, with arguments to
40 "WriteMakefile" like:
41
42 FUNCLIST => [qw(function_name)],
43 DL_FUNCS => { 'Extension::Name' => [] },
44
45 The basic scheme of operation is to collect information about a module
46 in the instance, and then store that data in the Perl library where it
47 may be retrieved later. The object can also reformat this information
48 into the data structures required by ExtUtils::MakeMaker's WriteMakefile
49 function.
50
51 For information on how to make your module fit into this scheme, see
52 "hashref = ExtUtils::Depends::load (name)".
53
54 When creating a new Depends object, you give it a name, which is the
55 name of the module you are building. You can also specify the names of
56 modules on which this module depends. These dependencies will be loaded
57 automatically, and their typemaps, header files, etc merged with your
58 new object's stuff. When you store the data for your object, the list of
59 dependencies are stored with it, so that another module depending on
60 your needn't know on exactly which modules yours depends.
61
62 For example:
63
64 Gtk2 depends on Glib
65
66 Gnome2::Canvas depends on Gtk2
67
68 ExtUtils::Depends->new ('Gnome2::Canvas', 'Gtk2');
69 this command automatically brings in all the stuff needed
70 for Glib, since Gtk2 depends on it.
71
72 When the configuration information is saved, it also includes a class
73 method called "Inline", inheritable by your module. This allows you in
74 your module to simply say at the top:
75
76 package Mymod;
77 use parent 'Mymod::Install::Files'; # to inherit 'Inline' method
78
79 And users of "Mymod" who want to write inline code (using Inline) will
80 simply be able to write:
81
82 use Inline with => 'Mymod';
83
84 And all the necessary header files, defines, and libraries will be added
85 for them.
86
87 The "Mymod::Install::Files" will also implement a "deps" method, which
88 will return a list of any modules that "Mymod" depends on - you will not
89 normally need to use this:
90
91 require Mymod::Install::Files;
92 @deps = Mymod::Install::Files->deps;
93
94 METHODS
95 $object = ExtUtils::Depends->new($name, @deps)
96 Create a new depends object named *$name*. Any modules listed in
97 *@deps* (which may be empty) are added as dependencies and their
98 dependency information is loaded. An exception is raised if any
99 dependency information cannot be loaded.
100
101 $depends->add_deps (@deps)
102 Add modules listed in *@deps* as dependencies.
103
104 (hashes) = $depends->get_deps
105 Fetch information on the dependencies of *$depends* as a hash of
106 hashes, which are dependency information indexed by module name. See
107 "load".
108
109 $depends->set_inc (@newinc)
110 Add strings to the includes or cflags variables.
111
112 $depends->set_libs (@newlibs)
113 Add strings to the libs (linker flags) variable.
114
115 $depends->add_pm (%pm_files)
116 Add files to the hash to be passed through ExtUtils::WriteMakefile's
117 PM key.
118
119 $depends->add_xs (@xs_files)
120 Add xs files to be compiled.
121
122 $depends->add_c (@c_files)
123 Add C files to be compiled.
124
125 $depends->add_typemaps (@typemaps)
126 Add typemap files to be used and installed.
127
128 $depends->add_headers (list)
129 No-op, for backward compatibility.
130
131 $depends->install (@files)
132 Install *@files* to the data directory for *$depends*.
133
134 This actually works by adding them to the hash of pm files that gets
135 passed through WriteMakefile's PM key.
136
137 $depends->save_config ($filename)
138 Save the important information from *$depends* to *$filename*, and
139 set it up to be installed as *name*::Install::Files.
140
141 Note: the actual value of *$filename* is unimportant so long as it
142 doesn't clash with any other local files. It will be installed as
143 *name*::Install::Files.
144
145 hash = $depends->get_makefile_vars
146 Return the information in *$depends* in a format digestible by
147 WriteMakefile.
148
149 This sets at least the following keys:
150
151 INC
152 LIBS
153 TYPEMAPS
154 PM
155
156 And these if there is data to fill them:
157
158 clean
159 OBJECT
160 XS
161
162 hashref = ExtUtils::Depends::load (name)
163 Load and return dependency information for *name*. Croaks if no such
164 information can be found. The information is returned as an
165 anonymous hash containing these keys:
166
167 instpath
168 The absolute path to the data install directory for this module.
169
170 typemaps
171 List of absolute pathnames for this module's typemap files.
172
173 inc CFLAGS string for this module.
174
175 libs
176 LIBS string for this module.
177
178 deps
179 List of modules on which this one depends. This key will not
180 exist when loading files created by old versions of
181 ExtUtils::Depends.
182
183 If you want to make module *name* support this, you must provide a
184 module *name*::Install::Files, which on loading will implement the
185 following class methods:
186
187 $hashref = name::Install::Files->Inline('C');
188 # hash to contain any necessary TYPEMAPS (array-ref), LIBS, INC
189 @deps = name::Install::Files->deps;
190 # any modules on which "name" depends
191
192 An easy way to achieve this is to use the method
193 "$depends->save_config ($filename)", but your package may have
194 different facilities already.
195
196 $depends->load_deps
197 Load *$depends* dependencies, by calling "load" on each dependency
198 module. This is usually done for you, and should only be needed if
199 you want to call "get_deps" after calling "add_deps" manually.
200
201 SUPPORT
202 Bugs/Feature Requests
203 Version 0.2 discards some of the more esoteric features provided by the
204 older versions. As they were completely undocumented, and this module
205 has yet to reach 1.0, this may not exactly be a bug.
206
207 This module is tightly coupled to the ExtUtils::MakeMaker architecture.
208
209 You can submit new bugs/feature requests by using one of two bug
210 trackers (below).
211
212 CPAN Request Tracker
213 You can submit bugs/feature requests via the web by going to
214 <https://rt.cpan.org/Public/Bug/Report.html?Queue=ExtUtils-Depends>
215 (requires PAUSE ID or Bitcard), or by sending an e-mail to
216 "bug-ExtUtils-Depends at rt.cpan.org".
217
218 Gnome.org Bugtracker
219 Report bugs/feature requests to 'perl-extutils-depends' (requires
220 login)
221 <https://gitlab.gnome.org/GNOME/perl-extutils-depends/-/issues/>
222
223 Patches that implement new features with test cases, and/or test cases
224 that exercise existing bugs are always welcome.
225
226 The Gtk-Perl support forum is at
227 <https://discourse.gnome.org/tags/c/platform/language-bindings/11/perl>
228
229 Source Code
230 The source code to ExtUtils::Depends is available at the Gnome.org Git
231 repo (<https://gitlab.gnome.org/GNOME/perl-extutils-depends>). Create
232 your own copy of the Git repo with:
233
234 git clone git://git.gnome.org/perl-ExtUtils-Depends (Git protocol)
235 git clone https://git.gnome.org/browse/perl-ExtUtils-Depends/ (HTTPS)
236
237 SEE ALSO
238 ExtUtils::MakeMaker.
239
240 AUTHOR
241 Paolo Molaro <lupus at debian dot org> wrote the original version for
242 Gtk-Perl. muppet <scott at asofyet dot org> rewrote the innards for
243 version 0.2, borrowing liberally from Paolo's code.
244
245 MAINTAINER
246 The Gtk2 project, <http://gtk2-perl.sf.net>/"gtk-perl-list at gnome dot
247 org".
248
249 LICENSE
250 This library is free software; you may redistribute it and/or modify it
251 under the same terms as Perl itself.
252