1ExtUtils::Depends(3)  User Contributed Perl Documentation ExtUtils::Depends(3)
2
3
4

NAME

6       ExtUtils::Depends - Easily build XS extensions that depend on XS
7       extensions
8

SYNOPSIS

10               use ExtUtils::Depends;
11               $package = new ExtUtils::Depends ('pkg::name', 'base::package')
12               # set the flags and libraries to compile and link the module
13               $package->set_inc("-I/opt/blahblah");
14               $package->set_libs("-lmylib");
15               # add a .c and an .xs file to compile
16               $package->add_c('code.c');
17               $package->add_xs('module-code.xs');
18               # add the typemaps to use
19               $package->add_typemaps("typemap");
20               # install some extra data files and headers
21               $package->install (qw/foo.h data.txt/);
22               # save the info
23               $package->save_config('Files.pm');
24
25               WriteMakefile(
26                       'NAME' => 'Mymodule',
27                       $package->get_makefile_vars()
28               );
29

DESCRIPTION

31       This module tries to make it easy to build Perl extensions that use
32       functions and typemaps provided by other perl extensions. This means
33       that a perl extension is treated like a shared library that provides
34       also a C and an XS interface besides the perl one.
35
36       This works as long as the base extension is loaded with the RTLD_GLOBAL
37       flag (usually done with a
38
39               sub dl_load_flags {0x01}
40
41       in the main .pm file) if you need to use functions defined in the
42       module.
43
44       The basic scheme of operation is to collect information about a module
45       in the instance, and then store that data in the Perl library where it
46       may be retrieved later.  The object can also reformat this information
47       into the data structures required by ExtUtils::MakeMaker's
48       WriteMakefile function.
49
50       For information on how to make your module fit into this scheme, see
51       "hashref = ExtUtils::Depends::load (name)".
52
53       When creating a new Depends object, you give it a name, which is the
54       name of the module you are building.   You can also specify the names
55       of modules on which this module depends.  These dependencies will be
56       loaded automatically, and their typemaps, header files, etc merged with
57       your new object's stuff.  When you store the data for your object, the
58       list of dependencies are stored with it, so that another module
59       depending on your needn't know on exactly which modules yours depends.
60
61       For example:
62
63         Gtk2 depends on Glib
64
65         Gnome2::Canvas depends on Gtk2
66
67         ExtUtils::Depends->new ('Gnome2::Canvas', 'Gtk2');
68            this command automatically brings in all the stuff needed
69            for Glib, since Gtk2 depends on it.
70
71       When the configuration information is saved, it also includes a class
72       method called "Inline", inheritable by your module. This allows you in
73       your module to simply say at the top:
74
75         package Mymod;
76         use parent 'Mymod::Install::Files'; # to inherit 'Inline' method
77
78       And users of "Mymod" who want to write inline code (using Inline) will
79       simply be able to write:
80
81         use Inline with => 'Mymod';
82
83       And all the necessary header files, defines, and libraries will be
84       added for them.
85
86       The "Mymod::Install::Files" will also implement a "deps" method, which
87       will return a list of any modules that "Mymod" depends on - you will
88       not normally need to use this:
89
90         require Mymod::Install::Files;
91         @deps = Mymod::Install::Files->deps;
92

METHODS

94       $object = ExtUtils::Depends->new($name, @deps)
95           Create a new depends object named $name.  Any modules listed in
96           @deps (which may be empty) are added as dependencies and their
97           dependency information is loaded.  An exception is raised if any
98           dependency information cannot be loaded.
99
100       $depends->add_deps (@deps)
101           Add modules listed in @deps as dependencies.
102
103       (hashes) = $depends->get_deps
104           Fetch information on the dependencies of $depends as a hash of
105           hashes, which are dependency information indexed by module name.
106           See "load".
107
108       $depends->set_inc (@newinc)
109           Add strings to the includes or cflags variables.
110
111       $depends->set_libs (@newlibs)
112           Add strings to the libs (linker flags) variable.
113
114       $depends->add_pm (%pm_files)
115           Add files to the hash to be passed through
116           ExtUtils::WriteMakefile's PM key.
117
118       $depends->add_xs (@xs_files)
119           Add xs files to be compiled.
120
121       $depends->add_c (@c_files)
122           Add C files to be compiled.
123
124       $depends->add_typemaps (@typemaps)
125           Add typemap files to be used and installed.
126
127       $depends->add_headers (list)
128           No-op, for backward compatibility.
129
130       $depends->install (@files)
131           Install @files to the data directory for $depends.
132
133           This actually works by adding them to the hash of pm files that
134           gets passed through WriteMakefile's PM key.
135
136       $depends->save_config ($filename)
137           Save the important information from $depends to $filename, and set
138           it up to be installed as name::Install::Files.
139
140           Note: the actual value of $filename is unimportant so long as it
141           doesn't clash with any other local files. It will be installed as
142           name::Install::Files.
143
144       hash = $depends->get_makefile_vars
145           Return the information in $depends in a format digestible by
146           WriteMakefile.
147
148           This sets at least the following keys:
149
150                   INC
151                   LIBS
152                   TYPEMAPS
153                   PM
154
155           And these if there is data to fill them:
156
157                   clean
158                   OBJECT
159                   XS
160
161       hashref = ExtUtils::Depends::load (name)
162           Load and return dependency information for name.  Croaks if no such
163           information can be found.  The information is returned as an
164           anonymous hash containing these keys:
165
166           instpath
167               The absolute path to the data install directory for this
168               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

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 "bug-
216           ExtUtils-Depends at rt.cpan.org".
217
218       Gnome.org Bugzilla
219           Report bugs/feature requests to the 'gnome-perl' product (requires
220           login) <http://bugzilla.gnome.org/enter_bug.cgi?product=gnome-perl>
221
222       Patches that implement new features with test cases, and/or test cases
223       that exercise existing bugs are always welcome.
224
225       The Gtk-Perl mailing list is at "gtk-perl-list at gnome dot org".
226
227   Source Code
228       The source code to ExtUtils::Depends is available at the Gnome.org Git
229       repo (<https://git.gnome.org/browse/perl-ExtUtils-Depends/>).  Create
230       your own copy of the Git repo with:
231
232         git clone git://git.gnome.org/perl-ExtUtils-Depends (Git protocol)
233         git clone https://git.gnome.org/browse/perl-ExtUtils-Depends/ (HTTPS)
234

SEE ALSO

236       ExtUtils::MakeMaker.
237

AUTHOR

239       Paolo Molaro <lupus at debian dot org> wrote the original version for
240       Gtk-Perl.  muppet <scott at asofyet dot org> rewrote the innards for
241       version 0.2, borrowing liberally from Paolo's code.
242

MAINTAINER

244       The Gtk2 project, <http://gtk2-perl.sf.net>/"gtk-perl-list at gnome dot
245       org".
246

LICENSE

248       This library is free software; you may redistribute it and/or modify it
249       under the same terms as Perl itself.
250
251
252
253perl v5.28.1                      2019-04-09              ExtUtils::Depends(3)
Impressum