local-lib5/man/man3/ExtUtils::Depends.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "ExtUtils::Depends 3"
 127 .TH ExtUtils::Depends 3 "2009-07-04" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 ExtUtils::Depends \- Easily build XS extensions that depend on XS extensions
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 10
 137 \&        use ExtUtils::Depends;
 138 \&        $package = new ExtUtils::Depends (\*(Aqpkg::name\*(Aq, \*(Aqbase::package\*(Aq)
 139 \&        # set the flags and libraries to compile and link the module
 140 \&        $package\->set_inc("\-I/opt/blahblah");
 141 \&        $package\->set_libs("\-lmylib");
 142 \&        # add a .c and an .xs file to compile
 143 \&        $package\->add_c(\*(Aqcode.c\*(Aq);
 144 \&        $package\->add_xs(\*(Aqmodule\-code.xs\*(Aq);
 145 \&        # add the typemaps to use
 146 \&        $package\->add_typemaps("typemap");
 147 \&        # install some extra data files and headers
 148 \&        $package\->install (qw/foo.h data.txt/);
 149 \&        # save the info
 150 \&        $package\->save_config(\*(AqFiles.pm\*(Aq);
 151 \&
 152 \&        WriteMakefile(
 153 \&                \*(AqNAME\*(Aq => \*(AqMymodule\*(Aq,
 154 \&                $package\->get_makefile_vars()
 155 \&        );
 156 .Ve
 157 .SH "DESCRIPTION"
 158 .IX Header "DESCRIPTION"
 159 This module tries to make it easy to build Perl extensions that use
 160 functions and typemaps provided by other perl extensions. This means
 161 that a perl extension is treated like a shared library that provides
 162 also a C and an \s-1XS\s0 interface besides the perl one.
 163 .PP
 164 This works as long as the base extension is loaded with the \s-1RTLD_GLOBAL\s0
 165 flag (usually done with a
 166 .PP
 167 .Vb 1
 168 \&        sub dl_load_flags {0x01}
 169 .Ve
 170 .PP
 171 in the main .pm file) if you need to use functions defined in the module.
 172 .PP
 173 The basic scheme of operation is to collect information about a module
 174 in the instance, and then store that data in the Perl library where it
 175 may be retrieved later.  The object can also reformat this information
 176 into the data structures required by ExtUtils::MakeMaker's WriteMakefile
 177 function.
 178 .PP
 179 When creating a new Depends object, you give it a name, which is the name
 180 of the module you are building.   You can also specify the names of modules
 181 on which this module depends.  These dependencies will be loaded
 182 automatically, and their typemaps, header files, etc merged with your new
 183 object's stuff.  When you store the data for your object, the list of
 184 dependencies are stored with it, so that another module depending on your
 185 needn't know on exactly which modules yours depends.
 186 .PP
 187 For example:
 188 .PP
 189 .Vb 1
 190 \&  Gtk2 depends on Glib
 191 \&
 192 \&  Gnome2::Canvas depends on Gtk2
 193 \&
 194 \&  ExtUtils::Depends\->new (\*(AqGnome2::Canvas\*(Aq, \*(AqGtk2\*(Aq);
 195 \&     this command automatically brings in all the stuff needed
 196 \&     for Glib, since Gtk2 depends on it.
 197 .Ve
 198 .SH "METHODS"
 199 .IX Header "METHODS"
 200 .ie n .IP "$object = ExtUtils::Depends\->new($name, @deps)" 4
 201 .el .IP "\f(CW$object\fR = ExtUtils::Depends\->new($name, \f(CW@deps\fR)" 4
 202 .IX Item "$object = ExtUtils::Depends->new($name, @deps)"
 203 Create a new depends object named \fI\f(CI$name\fI\fR.  Any modules listed in \fI\f(CI@deps\fI\fR
 204 (which may be empty) are added as dependencies and their dependency
 205 information is loaded.  An exception is raised if any dependency information
 206 cannot be loaded.
 207 .ie n .IP "$depends\->add_deps (@deps)" 4
 208 .el .IP "\f(CW$depends\fR\->add_deps (@deps)" 4
 209 .IX Item "$depends->add_deps (@deps)"
 210 Add modules listed in \fI\f(CI@deps\fI\fR as dependencies.
 211 .ie n .IP "(hashes) = $depends\->get_deps" 4
 212 .el .IP "(hashes) = \f(CW$depends\fR\->get_deps" 4
 213 .IX Item "(hashes) = $depends->get_deps"
 214 Fetch information on the dependencies of \fI\f(CI$depends\fI\fR as a hash of hashes,
 215 which are dependency information indexed by module name.  See \f(CW\*(C`load\*(C'\fR.
 216 .ie n .IP "$depends\->set_inc (@newinc)" 4
 217 .el .IP "\f(CW$depends\fR\->set_inc (@newinc)" 4
 218 .IX Item "$depends->set_inc (@newinc)"
 219 Add strings to the includes or cflags variables.
 220 .ie n .IP "$depends\->set_libs (@newlibs)" 4
 221 .el .IP "\f(CW$depends\fR\->set_libs (@newlibs)" 4
 222 .IX Item "$depends->set_libs (@newlibs)"
 223 Add strings to the libs (linker flags) variable.
 224 .ie n .IP "$depends\->add_pm (%pm_files)" 4
 225 .el .IP "\f(CW$depends\fR\->add_pm (%pm_files)" 4
 226 .IX Item "$depends->add_pm (%pm_files)"
 227 Add files to the hash to be passed through ExtUtils::WriteMakefile's
 228 \&\s-1PM\s0 key.
 229 .ie n .IP "$depends\->add_xs (@xs_files)" 4
 230 .el .IP "\f(CW$depends\fR\->add_xs (@xs_files)" 4
 231 .IX Item "$depends->add_xs (@xs_files)"
 232 Add xs files to be compiled.
 233 .ie n .IP "$depends\->add_c (@c_files)" 4
 234 .el .IP "\f(CW$depends\fR\->add_c (@c_files)" 4
 235 .IX Item "$depends->add_c (@c_files)"
 236 Add C files to be compiled.
 237 .ie n .IP "$depends\->add_typemaps (@typemaps)" 4
 238 .el .IP "\f(CW$depends\fR\->add_typemaps (@typemaps)" 4
 239 .IX Item "$depends->add_typemaps (@typemaps)"
 240 Add typemap files to be used and installed.
 241 .ie n .IP "$depends\->add_headers (list)" 4
 242 .el .IP "\f(CW$depends\fR\->add_headers (list)" 4
 243 .IX Item "$depends->add_headers (list)"
 244 No-op, for backward compatibility.
 245 .ie n .IP "$depends\->install (@files)" 4
 246 .el .IP "\f(CW$depends\fR\->install (@files)" 4
 247 .IX Item "$depends->install (@files)"
 248 Install \fI\f(CI@files\fI\fR to the data directory for \fI\f(CI$depends\fI\fR.
 249 .Sp
 250 This actually works by adding them to the hash of pm files that gets
 251 passed through WriteMakefile's \s-1PM\s0 key.
 252 .ie n .IP "$depends\->save_config ($filename)" 4
 253 .el .IP "\f(CW$depends\fR\->save_config ($filename)" 4
 254 .IX Item "$depends->save_config ($filename)"
 255 Save the important information from \fI\f(CI$depends\fI\fR to \fI\f(CI$filename\fI\fR, and
 256 set it up to be installed as \fIname\fR::Install::Files.
 257 .Sp
 258 Note: the actual value of \fI\f(CI$filename\fI\fR seems to be irrelevant, but its
 259 usage is kept for backward compatibility.
 260 .ie n .IP "hash = $depends\->get_makefile_vars" 4
 261 .el .IP "hash = \f(CW$depends\fR\->get_makefile_vars" 4
 262 .IX Item "hash = $depends->get_makefile_vars"
 263 Return the information in \fI\f(CI$depends\fI\fR in a format digestible by
 264 WriteMakefile.
 265 .Sp
 266 This sets at least the following keys:
 267 .Sp
 268 .Vb 4
 269 \&        INC
 270 \&        LIBS
 271 \&        TYPEMAPS
 272 \&        PM
 273 .Ve
 274 .Sp
 275 And these if there is data to fill them:
 276 .Sp
 277 .Vb 3
 278 \&        clean
 279 \&        OBJECT
 280 \&        XS
 281 .Ve
 282 .IP "hashref = ExtUtils::Depends::load (name)" 4
 283 .IX Item "hashref = ExtUtils::Depends::load (name)"
 284 Load and return dependency information for \fIname\fR.  Croaks if no such
 285 information can be found.  The information is returned as an anonymous
 286 hash containing these keys:
 287 .RS 4
 288 .IP "instpath" 4
 289 .IX Item "instpath"
 290 The absolute path to the data install directory for this module.
 291 .IP "typemaps" 4
 292 .IX Item "typemaps"
 293 List of absolute pathnames for this module's typemap files.
 294 .IP "inc" 4
 295 .IX Item "inc"
 296 \&\s-1CFLAGS\s0 string for this module.
 297 .IP "libs" 4
 298 .IX Item "libs"
 299 \&\s-1LIBS\s0 string for this module.
 300 .IP "deps" 4
 301 .IX Item "deps"
 302 List of modules on which this one depends.  This key will not exist when
 303 loading files created by old versions of ExtUtils::Depends.
 304 .RE
 305 .RS 4
 306 .RE
 307 .ie n .IP "$depends\->load_deps" 4
 308 .el .IP "\f(CW$depends\fR\->load_deps" 4
 309 .IX Item "$depends->load_deps"
 310 Load \fI\f(CI$depends\fI\fR dependencies, by calling \f(CW\*(C`load\*(C'\fR on each dependency module.
 311 This is usually done for you, and should only be needed if you want to call
 312 \&\f(CW\*(C`get_deps\*(C'\fR after calling \f(CW\*(C`add_deps\*(C'\fR manually.
 313 .SH "BUGS"
 314 .IX Header "BUGS"
 315 Version 0.2 discards some of the more esoteric features provided by the
 316 older versions.  As they were completely undocumented, and this module
 317 has yet to reach 1.0, this may not exactly be a bug.
 318 .PP
 319 This module is tightly coupled to the ExtUtils::MakeMaker architecture.
 320 .SH "SEE ALSO"
 321 .IX Header "SEE ALSO"
 322 ExtUtils::MakeMaker.
 323 .SH "AUTHOR"
 324 .IX Header "AUTHOR"
 325 Paolo Molaro <lupus at debian dot org> wrote the original version for
 326 Gtk-Perl.  muppet <scott at asofyet dot org> rewrote the innards for
 327 version 0.2, borrowing liberally from Paolo's code.
 328 .SH "MAINTAINER"
 329 .IX Header "MAINTAINER"
 330 The Gtk2 project, http://gtk2\-perl.sf.net/
 331 .SH "LICENSE"
 332 .IX Header "LICENSE"
 333 This library is free software; you may redistribute it and/or modify it
 334 under the same terms as Perl itself.