| 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 |
|