| 1 |
NAME |
| 2 |
|
| 3 |
Inline - Write Perl Subroutines in Other Programming Languages |
| 4 |
|
| 5 |
VERSION |
| 6 |
|
| 7 |
This document describes Inline version 0.87. |
| 8 |
|
| 9 |
SYNOPSIS |
| 10 |
|
| 11 |
use Inline C; |
| 12 |
|
| 13 |
print "9 + 16 = ", add(9, 16), "\n"; |
| 14 |
print "9 - 16 = ", subtract(9, 16), "\n"; |
| 15 |
|
| 16 |
__END__ |
| 17 |
__C__ |
| 18 |
int add(int x, int y) { |
| 19 |
return x + y; |
| 20 |
} |
| 21 |
|
| 22 |
int subtract(int x, int y) { |
| 23 |
return x - y; |
| 24 |
} |
| 25 |
|
| 26 |
DESCRIPTION |
| 27 |
|
| 28 |
The Inline module allows you to put source code from other programming |
| 29 |
languages directly "inline" in a Perl script or module. The code is |
| 30 |
automatically compiled as needed, and then loaded for immediate access |
| 31 |
from Perl. |
| 32 |
|
| 33 |
Inline saves you from the hassle of having to write and compile your |
| 34 |
own glue code using facilities like XS or SWIG. Simply type the code |
| 35 |
where you want it and run your Perl as normal. All the hairy details |
| 36 |
are handled for you. The compilation and installation of your code |
| 37 |
chunks all happen transparently; all you will notice is the delay of |
| 38 |
compilation on the first run. |
| 39 |
|
| 40 |
The Inline code only gets compiled the first time you run it (or |
| 41 |
whenever it is modified) so you only take the performance hit once. |
| 42 |
Code that is Inlined into distributed modules (like on the CPAN) will |
| 43 |
get compiled when the module is installed, so the end user will never |
| 44 |
notice the compilation time. |
| 45 |
|
| 46 |
Best of all, it works the same on both Unix and Microsoft Windows. See |
| 47 |
Inline-Support for support information. |
| 48 |
|
| 49 |
Why Inline? |
| 50 |
|
| 51 |
Do you want to know "Why would I use other languages in Perl?" or "Why |
| 52 |
should I use Inline to do it?"? I'll try to answer both. |
| 53 |
|
| 54 |
Why would I use other languages in Perl? |
| 55 |
|
| 56 |
The most obvious reason is performance. For an interpreted language, |
| 57 |
Perl is very fast. Many people will say "Anything Perl can do, C can |
| 58 |
do faster". (They never mention the development time :-) Anyway, you |
| 59 |
may be able to remove a bottleneck in your Perl code by using another |
| 60 |
language, without having to write the entire program in that |
| 61 |
language. This keeps your overall development time down, because |
| 62 |
you're using Perl for all of the non-critical code. |
| 63 |
|
| 64 |
Another reason is to access functionality from existing API-s that |
| 65 |
use the language. Some of this code may only be available in binary |
| 66 |
form. But by creating small subroutines in the native language, you |
| 67 |
can "glue" existing libraries to your Perl. As a user of the CPAN, |
| 68 |
you know that code reuse is a good thing. So why throw away those |
| 69 |
Fortran libraries just yet? |
| 70 |
|
| 71 |
If you are using Inline with the C language, then you can access the |
| 72 |
full internals of Perl itself. This opens up the floodgates to both |
| 73 |
extreme power and peril. |
| 74 |
|
| 75 |
Maybe the best reason is "Because you want to!". Diversity keeps the |
| 76 |
world interesting. TMTOWTDI! |
| 77 |
|
| 78 |
Why should I use Inline to do it? |
| 79 |
|
| 80 |
There are already two major facilities for extending Perl with C. |
| 81 |
They are XS and SWIG. Both are similar in their capabilities, at |
| 82 |
least as far as Perl is concerned. And both of them are quite |
| 83 |
difficult to learn compared to Inline. |
| 84 |
|
| 85 |
There is a big fat learning curve involved with setting up and using |
| 86 |
the XS environment. You need to get quite intimate with the following |
| 87 |
docs: |
| 88 |
|
| 89 |
* perlxs |
| 90 |
|
| 91 |
* perlxstut |
| 92 |
|
| 93 |
* perlapi |
| 94 |
|
| 95 |
* perlguts |
| 96 |
|
| 97 |
* perlmod |
| 98 |
|
| 99 |
* h2xs |
| 100 |
|
| 101 |
* xsubpp |
| 102 |
|
| 103 |
* ExtUtils::MakeMaker |
| 104 |
|
| 105 |
With Inline you can be up and running in minutes. There is a C |
| 106 |
Cookbook with lots of short but complete programs that you can extend |
| 107 |
to your real-life problems. No need to learn about the complicated |
| 108 |
build process going on in the background. You don't even need to |
| 109 |
compile the code yourself. Inline takes care of every last detail |
| 110 |
except writing the C code. |
| 111 |
|
| 112 |
Perl programmers cannot be bothered with silly things like compiling. |
| 113 |
"Tweak, Run, Tweak, Run" is our way of life. Inline does all the |
| 114 |
dirty work for you. |
| 115 |
|
| 116 |
Another advantage of Inline is that you can use it directly in a |
| 117 |
script. You can even use it in a Perl one-liner. With XS and SWIG, |
| 118 |
you always set up an entirely separate module. Even if you only have |
| 119 |
one or two functions. Inline makes easy things easy, and hard things |
| 120 |
possible. Just like Perl. |
| 121 |
|
| 122 |
Finally, Inline supports several programming languages (not just C |
| 123 |
and C++). As of this writing, Inline has support for C, C++, Java, |
| 124 |
Python, Ruby, Tcl, Assembler, Basic, Guile, Befunge, Octave, Awk, BC, |
| 125 |
TT (Template Toolkit), WebChat and even PERL. New Inline Language |
| 126 |
Support Modules (ILSMs) are regularly being added. See Inline-API for |
| 127 |
details on how to create your own ILSM. |
| 128 |
|
| 129 |
USING THE INLINE.PM MODULE |
| 130 |
|
| 131 |
Inline is a little bit different than most of the Perl modules that you |
| 132 |
are used to. It doesn't import any functions into your namespace and it |
| 133 |
doesn't have any object oriented methods. Its entire interface (with |
| 134 |
two minor exceptions) is specified through the 'use Inline ...' |
| 135 |
command. |
| 136 |
|
| 137 |
This section will explain all of the different ways to use Inline. If |
| 138 |
you want to begin using C with Inline immediately, see |
| 139 |
Inline::C-Cookbook. |
| 140 |
|
| 141 |
The Basics |
| 142 |
|
| 143 |
The most basic form for using Inline is: |
| 144 |
|
| 145 |
use Inline X => "X source code"; |
| 146 |
|
| 147 |
where 'X' is one of the supported Inline programming languages. The |
| 148 |
second parameter identifies the source code that you want to bind to |
| 149 |
Perl. The source code can be specified using any of the following |
| 150 |
syntaxes: |
| 151 |
|
| 152 |
The DATA Keyword. |
| 153 |
|
| 154 |
use Inline Java => 'DATA'; |
| 155 |
|
| 156 |
# Perl code goes here ... |
| 157 |
|
| 158 |
__DATA__ |
| 159 |
__Java__ |
| 160 |
/* Java code goes here ... */ |
| 161 |
|
| 162 |
The easiest and most visually clean way to specify your source code |
| 163 |
in an Inline Perl program is to use the special DATA keyword. This |
| 164 |
tells Inline to look for a special marker in your DATA filehandle's |
| 165 |
input stream. In this example the special marker is __Java__, which |
| 166 |
is the programming language surrounded by double underscores. |
| 167 |
|
| 168 |
In case you've forgotten, the DATA pseudo file is comprised of all |
| 169 |
the text after the __END__ or __DATA__ section of your program. If |
| 170 |
you're working outside the main package, you'd best use the __DATA__ |
| 171 |
marker or else Inline will not find your code. |
| 172 |
|
| 173 |
Using this scheme keeps your Perl code at the top, and all the ugly |
| 174 |
Java stuff down below where it belongs. This is visually clean and |
| 175 |
makes for more maintainable code. An excellent side benefit is that |
| 176 |
you don't have to escape any characters like you might in a Perl |
| 177 |
string. The source code is verbatim. For these reasons, I prefer this |
| 178 |
method the most. |
| 179 |
|
| 180 |
The only problem with this style is that since Perl can't read the |
| 181 |
DATA filehandle until runtime, it obviously can't bind your functions |
| 182 |
until runtime. The net effect of this is that you can't use your |
| 183 |
Inline functions as barewords (without predeclaring them) because |
| 184 |
Perl has no idea they exist during compile time. |
| 185 |
|
| 186 |
The FILE and BELOW keywords. |
| 187 |
|
| 188 |
use Inline::Files; |
| 189 |
use Inline Java => 'file'; |
| 190 |
|
| 191 |
# Perl code goes here ... |
| 192 |
|
| 193 |
__JAVA__ |
| 194 |
/* Java code goes here ... */ |
| 195 |
|
| 196 |
This is the newest method of specifying your source code. It makes |
| 197 |
use of the Perl module Inline::Files written by Damian Conway. The |
| 198 |
basic style and meaning are the same as for the DATA keyword, but |
| 199 |
there are a few syntactic and semantic twists. |
| 200 |
|
| 201 |
First, you must say 'use Inline::Files' before you 'use Inline' code |
| 202 |
that needs those files. The special 'DATA' keyword is replaced by |
| 203 |
either 'file' or 'below'. This allows for the bad pun idiom of: |
| 204 |
|
| 205 |
use Inline C => 'below'; |
| 206 |
|
| 207 |
You can omit the __DATA__ tag now. Inline::Files is a source filter |
| 208 |
that will remove these sections from your program before Perl |
| 209 |
compiles it. They are then available for Inline to make use of. And |
| 210 |
since this can all be done at compile time, you don't have to worry |
| 211 |
about the caveats of the 'DATA' keyword. |
| 212 |
|
| 213 |
This module has a couple small gotchas. Since Inline::Files only |
| 214 |
recognizes file markers with capital letters, you must specify the |
| 215 |
capital form of your language name. Also, there is a startup time |
| 216 |
penalty for using a source code filter. |
| 217 |
|
| 218 |
At this point Inline::Files is alpha software and use of it is |
| 219 |
experimental. Inline's integration of this module is also fledgling |
| 220 |
at the time being. One of things I plan to do with Inline::Files is |
| 221 |
to get line number info so when an extension doesn't compile, the |
| 222 |
error messages will point to the correct source file and line number. |
| 223 |
|
| 224 |
My best advice is to use Inline::Files for testing (especially as |
| 225 |
support for it improves), but use DATA for production and |
| 226 |
distributed/CPAN code. |
| 227 |
|
| 228 |
Strings |
| 229 |
|
| 230 |
use Inline Java => <<'END'; |
| 231 |
|
| 232 |
/* Java code goes here ... */ |
| 233 |
END |
| 234 |
|
| 235 |
# Perl code goes here ... |
| 236 |
|
| 237 |
You also just specify the source code as a single string. A handy way |
| 238 |
to write the string is to use Perl's "here document" style of |
| 239 |
quoting. This is ok for small functions but can get unwieldy in the |
| 240 |
large. On the other hand, the string variant probably has the least |
| 241 |
startup penalty and all functions are bound at compile time. |
| 242 |
|
| 243 |
If you wish to put the string into a scalar variable, please be aware |
| 244 |
that the use statement is a compile time directive. As such, all the |
| 245 |
variables it uses must also be set at compile time, before the 'use |
| 246 |
Inline' statement. Here is one way to do it: |
| 247 |
|
| 248 |
my $code; |
| 249 |
BEGIN { |
| 250 |
$code = <<END; |
| 251 |
|
| 252 |
/* Java code goes here ... */ |
| 253 |
END |
| 254 |
} |
| 255 |
use Inline Java => $code; |
| 256 |
|
| 257 |
# Perl code goes here ... |
| 258 |
|
| 259 |
The bind() Function |
| 260 |
|
| 261 |
An alternative to using the BEGIN block method is to specify the |
| 262 |
source code at run time using the 'Inline->bind()' method. (This is |
| 263 |
one of the interface exceptions mentioned above) The bind() method |
| 264 |
takes the same arguments as 'use Inline ...'. |
| 265 |
|
| 266 |
my $code = <<END; |
| 267 |
|
| 268 |
/* Java code goes here ... */ |
| 269 |
END |
| 270 |
|
| 271 |
Inline->bind(Java => $code); |
| 272 |
|
| 273 |
You can think of bind() as a way to eval() code in other programming |
| 274 |
languages. |
| 275 |
|
| 276 |
Although bind() is a powerful feature, it is not recommended for use |
| 277 |
in Inline based modules. In fact, it won't work at all for |
| 278 |
installable modules. See instructions below for creating modules with |
| 279 |
Inline. |
| 280 |
|
| 281 |
Other Methods |
| 282 |
|
| 283 |
The source code for Inline can also be specified as an external |
| 284 |
filename, a reference to a subroutine that returns source code, or a |
| 285 |
reference to an array that contains lines of source code. (Note that |
| 286 |
if the external source file is in the current directory it must be |
| 287 |
specified with a leading '.' - ie '.file.ext' instead of simply |
| 288 |
'file.ext'.) These methods are less frequently used but may be useful |
| 289 |
in some situations. |
| 290 |
|
| 291 |
For instance, to load your C++ code from a file named the same as |
| 292 |
your perl module with a swapped file extension, you can use: |
| 293 |
|
| 294 |
use Inline CPP => (__FILE__ =~ s/\.pm$/.cpp/r); |
| 295 |
|
| 296 |
Shorthand |
| 297 |
|
| 298 |
If you are using the 'DATA' or 'file' methods described above and |
| 299 |
there are no extra parameters, you can omit the keyword altogether. |
| 300 |
For example: |
| 301 |
|
| 302 |
use Inline 'Java'; |
| 303 |
|
| 304 |
# Perl code goes here ... |
| 305 |
|
| 306 |
__DATA__ |
| 307 |
__Java__ |
| 308 |
/* Java code goes here ... */ |
| 309 |
|
| 310 |
or |
| 311 |
|
| 312 |
use Inline::Files; |
| 313 |
use Inline 'Java'; |
| 314 |
|
| 315 |
# Perl code goes here ... |
| 316 |
|
| 317 |
__JAVA__ |
| 318 |
/* Java code goes here ... */ |
| 319 |
|
| 320 |
More about the DATA Section |
| 321 |
|
| 322 |
If you are writing a module, you can also use the DATA section for POD |
| 323 |
and AutoLoader subroutines. Just be sure to put them before the first |
| 324 |
Inline marker. If you install the helper module Inline::Filters, you |
| 325 |
can even use POD inside your Inline code. You just have to specify a |
| 326 |
filter to strip it out. |
| 327 |
|
| 328 |
You can also specify multiple Inline sections, possibly in different |
| 329 |
programming languages. Here is another example: |
| 330 |
|
| 331 |
# The module Foo.pm |
| 332 |
package Foo; |
| 333 |
use AutoLoader; |
| 334 |
|
| 335 |
use Inline C; |
| 336 |
use Inline C => DATA => filters => 'Strip_POD'; |
| 337 |
use Inline Python; |
| 338 |
|
| 339 |
1; |
| 340 |
|
| 341 |
__DATA__ |
| 342 |
|
| 343 |
sub marine { |
| 344 |
# This is an autoloaded subroutine |
| 345 |
} |
| 346 |
|
| 347 |
=head1 External subroutines |
| 348 |
|
| 349 |
=cut |
| 350 |
|
| 351 |
__C__ |
| 352 |
/* First C section */ |
| 353 |
|
| 354 |
__C__ |
| 355 |
/* Second C section */ |
| 356 |
=head1 My C Function |
| 357 |
|
| 358 |
Some POD doc. |
| 359 |
|
| 360 |
=cut |
| 361 |
|
| 362 |
__Python__ |
| 363 |
"""A Python Section""" |
| 364 |
|
| 365 |
An important thing to remember is that you need to have one use Inline |
| 366 |
Foo=> 'DATA' for each __Foo__ marker, and they must be in the same |
| 367 |
order. This allows you to apply different configuration options to each |
| 368 |
section. |
| 369 |
|
| 370 |
Configuration Options |
| 371 |
|
| 372 |
Inline tries to do the right thing as often as possible. But sometimes |
| 373 |
you may need to override the default actions. This is easy to do. |
| 374 |
Simply list the Inline configuration options after the regular Inline |
| 375 |
parameters. All configuration options are specified as (key, value) |
| 376 |
pairs. |
| 377 |
|
| 378 |
use Inline (C => 'DATA', |
| 379 |
directory => './inline_dir', |
| 380 |
libs => '-lfoo', |
| 381 |
inc => '-I/foo/include', |
| 382 |
prefix => 'XXX_', |
| 383 |
warnings => 0, |
| 384 |
); |
| 385 |
|
| 386 |
You can also specify the configuration options on a separate Inline |
| 387 |
call like this: |
| 388 |
|
| 389 |
use Inline (C => Config => |
| 390 |
directory => './inline_dir', |
| 391 |
libs => '-lfoo', |
| 392 |
inc => '-I/foo/include', |
| 393 |
prefix => 'XXX_', |
| 394 |
warnings => 0, |
| 395 |
); |
| 396 |
use Inline C => <<'END_OF_C_CODE'; |
| 397 |
|
| 398 |
The special keyword 'Config' tells Inline that this is a |
| 399 |
configuration-only call. No source code will be compiled or bound to |
| 400 |
Perl. |
| 401 |
|
| 402 |
If you want to specify global configuration options that don't apply to |
| 403 |
a particular language, just leave the language out of the call. Like |
| 404 |
this: |
| 405 |
|
| 406 |
use Inline Config => warnings => 0; |
| 407 |
|
| 408 |
The Config options are inherited and additive. You can use as many |
| 409 |
Config calls as you want. And you can apply different options to |
| 410 |
different code sections. When a source code section is passed in, |
| 411 |
Inline will apply whichever options have been specified up to that |
| 412 |
point. Here is a complex configuration example: |
| 413 |
|
| 414 |
use Inline (Config => |
| 415 |
directory => './inline_dir', |
| 416 |
); |
| 417 |
use Inline (C => Config => |
| 418 |
libs => '-lglobal', |
| 419 |
); |
| 420 |
use Inline (C => 'DATA', # First C Section |
| 421 |
libs => ['-llocal1', '-llocal2'], |
| 422 |
); |
| 423 |
use Inline (Config => |
| 424 |
warnings => 0, |
| 425 |
); |
| 426 |
use Inline (Python => 'DATA', # First Python Section |
| 427 |
libs => '-lmypython1', |
| 428 |
); |
| 429 |
use Inline (C => 'DATA', # Second C Section |
| 430 |
libs => [undef, '-llocal3'], |
| 431 |
); |
| 432 |
|
| 433 |
The first Config applies to all subsequent calls. The second Config |
| 434 |
applies to all subsequent C sections (but not Python sections). In the |
| 435 |
first C section, the external libraries global, local1 and local2 are |
| 436 |
used. (Most options allow either string or array ref forms, and do the |
| 437 |
right thing.) The Python section does not use the global library, but |
| 438 |
does use the same DIRECTORY, and has warnings turned off. The second C |
| 439 |
section only uses the local3 library. That's because a value of undef |
| 440 |
resets the additive behavior. |
| 441 |
|
| 442 |
The directory and warnings options are generic Inline options. All |
| 443 |
other options are language specific. To find out what the C options do, |
| 444 |
see Inline::C. |
| 445 |
|
| 446 |
On and Off |
| 447 |
|
| 448 |
If a particular config option has value options of 1 and 0, you can use |
| 449 |
the 'enable' and 'disable' modifiers. In other words, this: |
| 450 |
|
| 451 |
use Inline Config => |
| 452 |
force_build => 1, |
| 453 |
clean_after_build => 0; |
| 454 |
|
| 455 |
could be reworded as: |
| 456 |
|
| 457 |
use Inline Config => |
| 458 |
enable => force_build => |
| 459 |
disable => clean_after_build; |
| 460 |
|
| 461 |
Playing 'with' Others |
| 462 |
|
| 463 |
Inline has a special configuration syntax that tells it to get more |
| 464 |
configuration options from other Perl modules. Here is an example: |
| 465 |
|
| 466 |
use Inline with => 'Event'; |
| 467 |
|
| 468 |
This tells Inline to load the module Event.pm and ask it for |
| 469 |
configuration information. Since Event has a C API of its own, it can |
| 470 |
pass Inline all of the information it needs to be able to use Event C |
| 471 |
callbacks seamlessly. |
| 472 |
|
| 473 |
That means that you don't need to specify the typemaps, shared |
| 474 |
libraries, include files and other information required to get this to |
| 475 |
work. |
| 476 |
|
| 477 |
You can specify a single module or a list of them. Like: |
| 478 |
|
| 479 |
use Inline with => qw(Event Foo Bar); |
| 480 |
|
| 481 |
Currently, modules that works with Inline include Event, PDL, and those |
| 482 |
that use Alien::Build. |
| 483 |
|
| 484 |
In order to make your module work with Inline in this way, your module |
| 485 |
needs to provide a class method called Inline that takes an Inline |
| 486 |
language as a parameter (e.g. "C"), and returns a reference to a hash |
| 487 |
with configuration information that is acceptable to the relevant ILSM. |
| 488 |
For C, see C Configuration Options. E.g.: |
| 489 |
|
| 490 |
my $confighashref = Event->Inline('C'); # only supports C in 1.21 |
| 491 |
# hashref contains keys INC, TYPEMAPS, MYEXTLIB, AUTO_INCLUDE, BOOT |
| 492 |
|
| 493 |
If your module uses ExtUtils::Depends version 0.400 or higher, your |
| 494 |
module only needs this: |
| 495 |
|
| 496 |
package Module; |
| 497 |
use autouse Module::Install::Files => qw(Inline); |
| 498 |
|
| 499 |
Inline Shortcuts |
| 500 |
|
| 501 |
Inline lets you set many configuration options from the command line. |
| 502 |
These options are called 'shortcuts'. They can be very handy, |
| 503 |
especially when you only want to set the options temporarily, for say, |
| 504 |
debugging. |
| 505 |
|
| 506 |
For instance, to get some general information about your Inline code in |
| 507 |
the script Foo.pl, use the command: |
| 508 |
|
| 509 |
perl -MInline=info Foo.pl |
| 510 |
|
| 511 |
If you want to force your code to compile, even if its already done, |
| 512 |
use: |
| 513 |
|
| 514 |
perl -MInline=force Foo.pl |
| 515 |
|
| 516 |
If you want to do both, use: |
| 517 |
|
| 518 |
perl -MInline=info -MInline=force Foo.pl |
| 519 |
|
| 520 |
or better yet: |
| 521 |
|
| 522 |
perl -MInline=info,force Foo.pl |
| 523 |
|
| 524 |
The Inline 'directory' |
| 525 |
|
| 526 |
Inline needs a place to build your code and to install the results of |
| 527 |
the build. It uses a single directory named '.Inline/' under normal |
| 528 |
circumstances. If you create this directory in your home directory, the |
| 529 |
current directory or in the directory where your program resides, |
| 530 |
Inline will find and use it. You can also specify it in the environment |
| 531 |
variable PERL_INLINE_DIRECTORY or directly in your program, by using |
| 532 |
the directory keyword option. If Inline cannot find the directory in |
| 533 |
any of these places it will create a '_Inline/' directory in either |
| 534 |
your current directory or the directory where your script resides. |
| 535 |
|
| 536 |
One of the key factors to using Inline successfully, is understanding |
| 537 |
this directory. When developing code it is usually best to create this |
| 538 |
directory (or let Inline do it) in your current directory. Remember |
| 539 |
that there is nothing sacred about this directory except that it holds |
| 540 |
your compiled code. Feel free to delete it at any time. Inline will |
| 541 |
simply start from scratch and recompile your code on the next run. If |
| 542 |
you have several programs that you want to force to recompile, just |
| 543 |
delete your '.Inline/' directory. |
| 544 |
|
| 545 |
It is probably best to have a separate '.Inline/' directory for each |
| 546 |
project that you are working on. You may want to keep stable code in |
| 547 |
the <.Inline/> in your home directory. On multi-user systems, each user |
| 548 |
should have their own '.Inline/' directories. It could be a security |
| 549 |
risk to put the directory in a shared place like /tmp/. |
| 550 |
|
| 551 |
Debugging Inline Errors |
| 552 |
|
| 553 |
All programmers make mistakes. When you make a mistake with Inline, |
| 554 |
like writing bad C code, you'll get a big error report on your screen. |
| 555 |
This report tells you where to look to do the debugging. Some languages |
| 556 |
may also dump out the error messages generated from the build. |
| 557 |
|
| 558 |
When Inline needs to build something it creates a subdirectory under |
| 559 |
your DIRECTORY/build/ directory. This is where it writes all the |
| 560 |
components it needs to build your extension. Things like XS files, |
| 561 |
Makefiles and output log files. |
| 562 |
|
| 563 |
If everything goes OK, Inline will delete this subdirectory. If there |
| 564 |
is an error, Inline will leave the directory intact and print its |
| 565 |
location. The idea is that you are supposed to go into that directory |
| 566 |
and figure out what happened. |
| 567 |
|
| 568 |
Read the doc for your particular Inline Language Support Module for |
| 569 |
more information. |
| 570 |
|
| 571 |
The 'config' Registry File |
| 572 |
|
| 573 |
Inline keeps a cached file of all of the Inline Language Support |
| 574 |
Module's meta data in a file called config. This file can be found in |
| 575 |
your directory directory. If the file does not exist, Inline creates a |
| 576 |
new one. It will search your system for any module beginning with |
| 577 |
Inline::. It will then call that module's register() method to get |
| 578 |
useful information for future invocations. |
| 579 |
|
| 580 |
Whenever you add a new ILSM, you should delete this file so that Inline |
| 581 |
will auto-discover your newly installed language module. (This should |
| 582 |
no longer be necessary as of Inline-0.49.) |
| 583 |
|
| 584 |
CONFIGURATION OPTIONS |
| 585 |
|
| 586 |
This section lists all of the generic Inline configuration options. For |
| 587 |
language specific configuration, see the doc for that language. |
| 588 |
|
| 589 |
directory |
| 590 |
|
| 591 |
The directory config option is the directory that Inline uses to both |
| 592 |
build and install an extension. |
| 593 |
|
| 594 |
Normally Inline will search in a bunch of known places for a |
| 595 |
directory called '.Inline/'. Failing that, it will create a directory |
| 596 |
called '_Inline/' |
| 597 |
|
| 598 |
If you want to specify your own directory, use this configuration |
| 599 |
option. |
| 600 |
|
| 601 |
Note that you must create the directory directory yourself. Inline |
| 602 |
will not do it for you. |
| 603 |
|
| 604 |
name |
| 605 |
|
| 606 |
You can use this option to set the name of your Inline extension |
| 607 |
object module. For example: |
| 608 |
|
| 609 |
use Inline C => 'DATA', |
| 610 |
name => 'Foo::Bar'; |
| 611 |
|
| 612 |
would cause your C code to be compiled in to the object: |
| 613 |
|
| 614 |
lib/auto/Foo/Bar/Bar.so |
| 615 |
lib/auto/Foo/Bar/Bar.inl |
| 616 |
|
| 617 |
(The .inl component contains dependency information to make sure the |
| 618 |
source code is in sync with the executable) |
| 619 |
|
| 620 |
If you don't use name, Inline will pick a name for you based on your |
| 621 |
program name or package name. In this case, Inline will also enable |
| 622 |
the autoname option which mangles in a small piece of the MD5 |
| 623 |
fingerprint into your object name, to make it unique. |
| 624 |
|
| 625 |
autoname |
| 626 |
|
| 627 |
This option is enabled whenever the name parameter is not specified. |
| 628 |
To disable it say: |
| 629 |
|
| 630 |
use Inline C => 'DATA', |
| 631 |
disable => 'autoname'; |
| 632 |
|
| 633 |
autoname mangles in enough of the MD5 fingerprint to make your module |
| 634 |
name unique. Objects created with autoname will never get replaced. |
| 635 |
That also means they will never get cleaned up automatically. |
| 636 |
|
| 637 |
autoname is very useful for small throw away scripts. For more |
| 638 |
serious things, always use the name option. |
| 639 |
|
| 640 |
version |
| 641 |
|
| 642 |
Specifies the version number of the Inline extension object. It is |
| 643 |
used only for modules, and it must match the global variable |
| 644 |
$VERSION. Additionally, this option should used if (and only if) a |
| 645 |
module is being set up to be installed permanently into the Perl |
| 646 |
sitelib tree using Inline::MakeMaker (NOT used by Inline::Module). |
| 647 |
Inline will croak if you use it otherwise. |
| 648 |
|
| 649 |
The presence of the version parameter is the official way to let |
| 650 |
Inline know that your code is an installable/installed module. Inline |
| 651 |
will never generate an object in the temporary cache (_Inline/ |
| 652 |
directory) if version is set. It will also never try to recompile a |
| 653 |
module that was installed into someone's Perl site tree. |
| 654 |
|
| 655 |
So the basic rule is develop without version, and deliver with |
| 656 |
version. |
| 657 |
|
| 658 |
with |
| 659 |
|
| 660 |
with can also be used as a configuration option instead of using the |
| 661 |
special 'with' syntax. Do this if you want to use different sections |
| 662 |
of Inline code with different modules. (Probably a very rare usage) |
| 663 |
|
| 664 |
use Event; |
| 665 |
use Inline C => DATA => with => 'Event'; |
| 666 |
|
| 667 |
Modules specified using the config form of with will not be |
| 668 |
automatically required. You must use them yourself. |
| 669 |
|
| 670 |
using |
| 671 |
|
| 672 |
You can override modules that get used by ILSMs with the using |
| 673 |
option. This is typically used to override the default parser for |
| 674 |
Inline::C, but might be used by any ILSM for any purpose. |
| 675 |
|
| 676 |
use Inline config => using => '::Parser::RecDescent'; |
| 677 |
use Inline C => '...'; |
| 678 |
|
| 679 |
This would tell Inline::C to use Inline::C::Parser::RecDescent. |
| 680 |
|
| 681 |
global_load |
| 682 |
|
| 683 |
This option is for compiled languages only. It tells Inline to tell |
| 684 |
DynaLoader to load an object file in such a way that its symbols can |
| 685 |
be dynamically resolved by other object files. May not work on all |
| 686 |
platforms. See the global shortcut below. |
| 687 |
|
| 688 |
untaint |
| 689 |
|
| 690 |
You can use this option whenever you use Perl's -T switch, for taint |
| 691 |
checking. This option tells Inline to blindly untaint all tainted |
| 692 |
variables. (This is generally considered to be an appallingly |
| 693 |
insecure thing to do, and not to be recommended - but the option is |
| 694 |
there for you to use if you want. Please consider using something |
| 695 |
other than Inline for scripts that need taint checking.) It also |
| 696 |
turns on safemode by default. See the untaint shortcut below. You |
| 697 |
will see warnings about blindly untainting fields in both %ENV and |
| 698 |
Inline objects. If you want to silence these warnings, set the Config |
| 699 |
option no_untaint_warn => 1. There can be some problems untainting |
| 700 |
Inline scripts where older versions of Cwd, such as those that |
| 701 |
shipped with early versions of perl-5.8 (and earlier), are installed. |
| 702 |
Updating Cwd will probably solve these problems. |
| 703 |
|
| 704 |
safemode |
| 705 |
|
| 706 |
Perform extra safety checking, in an attempt to thwart malicious |
| 707 |
code. This option cannot guarantee security, but it does turn on all |
| 708 |
the currently implemented checks. (Currently, the only "currently |
| 709 |
implemented check" is to ensure that the directory option has also |
| 710 |
been used.) |
| 711 |
|
| 712 |
There is a slight startup penalty by using safemode. Also, using |
| 713 |
untaint automatically turns this option on. If you need your code to |
| 714 |
start faster under -T (taint) checking, you'll need to turn this |
| 715 |
option off manually. Only do this if you are not worried about |
| 716 |
security risks. See the unsafe shortcut below. |
| 717 |
|
| 718 |
force_build |
| 719 |
|
| 720 |
Makes Inline build (compile) the source code every time the program |
| 721 |
is run. The default is 0. See the force shortcut below. |
| 722 |
|
| 723 |
build_noisy |
| 724 |
|
| 725 |
Tells ILSMs that they should dump build messages to the terminal |
| 726 |
rather than be silent about all the build details. |
| 727 |
|
| 728 |
build_timers |
| 729 |
|
| 730 |
Tells ILSMs to print timing information about how long each build |
| 731 |
phase took. Usually requires Time::HiRes. |
| 732 |
|
| 733 |
clean_after_build |
| 734 |
|
| 735 |
Tells Inline to clean up the current build area if the build was |
| 736 |
successful. Sometimes you want to disable this for debugging. Default |
| 737 |
is 1. See the noclean shortcut below. |
| 738 |
|
| 739 |
clean_build_area |
| 740 |
|
| 741 |
Tells Inline to clean up the old build areas within the entire Inline |
| 742 |
directory. Default is 0. See the clean shortcut below. |
| 743 |
|
| 744 |
print_info |
| 745 |
|
| 746 |
Tells Inline to print various information about the source code. |
| 747 |
Default is 0. See the info shortcut below. |
| 748 |
|
| 749 |
print_version |
| 750 |
|
| 751 |
Tells Inline to print version info about itself. Default is 0. See |
| 752 |
the version shortcut below. |
| 753 |
|
| 754 |
reportbug |
| 755 |
|
| 756 |
Puts Inline into 'reportbug' mode, which is what you want if you |
| 757 |
desire to report a bug. |
| 758 |
|
| 759 |
rewrite_config_file |
| 760 |
|
| 761 |
Default is 0, but setting rewrite_config_file => 1 will mean that the |
| 762 |
existing configuration file in the Inline directory will be |
| 763 |
overwritten. (This is useful if the existing config file is not up to |
| 764 |
date as regards supported languages.) |
| 765 |
|
| 766 |
warnings |
| 767 |
|
| 768 |
This option tells Inline whether to print certain warnings. Default |
| 769 |
is 1. |
| 770 |
|
| 771 |
INLINE CONFIGURATION SHORTCUTS |
| 772 |
|
| 773 |
This is a list of all the shortcut configuration options currently |
| 774 |
available for Inline. Specify them from the command line when running |
| 775 |
Inline scripts. |
| 776 |
|
| 777 |
perl -MInline=noclean inline_script.pl |
| 778 |
|
| 779 |
or |
| 780 |
|
| 781 |
perl -MInline=info,force,noclean inline_script.pl |
| 782 |
|
| 783 |
You can specify multiple shortcuts separated by commas. They are not |
| 784 |
case sensitive. You can also specify shortcuts inside the Inline |
| 785 |
program like this: |
| 786 |
|
| 787 |
use Inline 'info', 'force', 'noclean'; |
| 788 |
|
| 789 |
NOTE: If a 'use Inline' statement is used to set shortcuts, it can not |
| 790 |
be used for additional purposes. |
| 791 |
|
| 792 |
clean |
| 793 |
|
| 794 |
Tells Inline to remove any build directories that may be lying around |
| 795 |
in your build area. Normally these directories get removed |
| 796 |
immediately after a successful build. Exceptions are when the build |
| 797 |
fails, or when you use the noclean or reportbug options. |
| 798 |
|
| 799 |
force |
| 800 |
|
| 801 |
Forces the code to be recompiled, even if everything is up to date. |
| 802 |
|
| 803 |
global |
| 804 |
|
| 805 |
Turns on the global_load option. |
| 806 |
|
| 807 |
info |
| 808 |
|
| 809 |
This is a very useful option when you want to know what's going on |
| 810 |
under the hood. It tells Inline to print helpful information to |
| 811 |
STDERR. Among the things that get printed is a list of which Inline |
| 812 |
functions were successfully bound to Perl. |
| 813 |
|
| 814 |
noclean |
| 815 |
|
| 816 |
Tells Inline to leave the build files after compiling. |
| 817 |
|
| 818 |
noisy |
| 819 |
|
| 820 |
Use the build_noisy option to print messages during a build. |
| 821 |
|
| 822 |
reportbug |
| 823 |
|
| 824 |
Puts Inline into reportbug mode, which does special processing when |
| 825 |
you want to report a bug. reportbug also automatically forces a |
| 826 |
build, and doesn't clean up afterwards. This is so that you can tar |
| 827 |
and mail the build directory to me. reportbug will print exact |
| 828 |
instructions on what to do. Please read and follow them carefully. |
| 829 |
|
| 830 |
NOTE: reportbug informs you to use the tar command. If your system |
| 831 |
does not have tar, please use the equivalent zip command. |
| 832 |
|
| 833 |
safe |
| 834 |
|
| 835 |
Turns safemode on. untaint will turn this on automatically. While |
| 836 |
this mode performs extra security checking, it does not guarantee |
| 837 |
safety. |
| 838 |
|
| 839 |
site_install |
| 840 |
|
| 841 |
This parameter used to be used for creating installable Inline |
| 842 |
modules. It has been removed from Inline altogether and replaced with |
| 843 |
a much simpler and more powerful mechanism, Inline::MakeMaker. See |
| 844 |
the section below on how to create modules with Inline. |
| 845 |
|
| 846 |
_testing |
| 847 |
|
| 848 |
Used internally by Ct09parser.t and Ct10callback.t(in the Inline::C |
| 849 |
test suite). Setting this option with Inline::C will mean that files |
| 850 |
named parser_id and void_test are created in the ./Inline_test |
| 851 |
directory, creating that directory if it doesn't already exist. The |
| 852 |
files (but not the ./Inline_test directory) are cleaned up by calling |
| 853 |
Inline::C::_testing_cleanup(). Also used by t/06rewrite_config.t to |
| 854 |
trigger a warning. |
| 855 |
|
| 856 |
timers |
| 857 |
|
| 858 |
Turn on build_timers to get extra diagnostic info about builds. |
| 859 |
|
| 860 |
unsafe |
| 861 |
|
| 862 |
Turns safemode off. Use this in combination with untaint for slightly |
| 863 |
faster startup time under -T. Only use this if you are sure the |
| 864 |
environment is safe. |
| 865 |
|
| 866 |
untaint |
| 867 |
|
| 868 |
Turn the untaint option on. Used with -T switch. In terms of secure |
| 869 |
practices, this is definitely not a recommended way of dealing with |
| 870 |
taint checking, but it's the only option currently available with |
| 871 |
Inline. Use it at your own risk. |
| 872 |
|
| 873 |
version |
| 874 |
|
| 875 |
Tells Inline to report its release version. |
| 876 |
|
| 877 |
WRITING MODULES WITH INLINE |
| 878 |
|
| 879 |
The current preferred way to author CPAN modules with Inline is to use |
| 880 |
Inline::Module (distributed separately). Inline ships with |
| 881 |
Inline::MakeMaker, which helps you set up a Makefile.PL that invokes |
| 882 |
Inline at install time to compile all the code before it gets |
| 883 |
installed, but the resulting module still depends on Inline and the |
| 884 |
language support module like Inline::C. In order to avoid this |
| 885 |
dependency, what you really want to do is convert your distribution to |
| 886 |
plain XS before uploading it to CPAN. Inline::Module fills that role, |
| 887 |
and also integrates well with more modern authoring tools. |
| 888 |
|
| 889 |
See Inline::Module for details on that approach, or continue reading |
| 890 |
below for the older Inline::MakeMaker technique. |
| 891 |
|
| 892 |
Let's say that you wanted to write a module called Math::Simple. Start |
| 893 |
by using the following command: |
| 894 |
|
| 895 |
h2xs -PAXn Math::Simple |
| 896 |
|
| 897 |
This will generate a bunch of files that form a skeleton of what you |
| 898 |
need for a distributable module. (Read the h2xs manpage to find out |
| 899 |
what the options do) Next, modify the Simple.pm file to look like this: |
| 900 |
|
| 901 |
package Math::Simple; |
| 902 |
$VERSION = '1.23'; |
| 903 |
|
| 904 |
use base 'Exporter'; |
| 905 |
@EXPORT_OK = qw(add subtract); |
| 906 |
use strict; |
| 907 |
|
| 908 |
use Inline C => 'DATA', |
| 909 |
version => '1.23', |
| 910 |
name => 'Math::Simple'; |
| 911 |
|
| 912 |
# The following Inline->init() call is optional - see below for more info. |
| 913 |
#Inline->init(); |
| 914 |
|
| 915 |
1; |
| 916 |
|
| 917 |
__DATA__ |
| 918 |
|
| 919 |
=pod |
| 920 |
|
| 921 |
=cut |
| 922 |
|
| 923 |
__C__ |
| 924 |
int add(int x, int y) { |
| 925 |
return x + y; |
| 926 |
} |
| 927 |
|
| 928 |
int subtract(int x, int y) { |
| 929 |
return x - y; |
| 930 |
} |
| 931 |
|
| 932 |
The important things to note here are that you must specify a name and |
| 933 |
version parameter. The name must match your module's package name. The |
| 934 |
version parameter must match your module's $VERSION variable and they |
| 935 |
must be considered valid by version::parse. |
| 936 |
|
| 937 |
NOTE: These are Inline's sanity checks to make sure you know what |
| 938 |
you're doing before uploading your code to CPAN. They insure that once |
| 939 |
the module has been installed on someone's system, the module would not |
| 940 |
get automatically recompiled for any reason. This makes Inline based |
| 941 |
modules work in exactly the same manner as XS based ones. |
| 942 |
|
| 943 |
Finally, you need to modify the Makefile.PL. Simply change: |
| 944 |
|
| 945 |
use ExtUtils::MakeMaker; |
| 946 |
|
| 947 |
to |
| 948 |
|
| 949 |
use Inline::MakeMaker; |
| 950 |
|
| 951 |
And, in order that the module build work correctly in the cpan shell, |
| 952 |
add the following directive to the Makefile.PL's WriteMakefile(): |
| 953 |
|
| 954 |
CONFIGURE_REQUIRES => { |
| 955 |
'Inline::MakeMaker' => 0.45, |
| 956 |
'ExtUtils::MakeMaker' => 6.52, |
| 957 |
}, |
| 958 |
|
| 959 |
This CONFIGURE_REQUIRES directive ensures that the cpan shell will |
| 960 |
install Inline on the user's machine (if it's not already present) |
| 961 |
before building your Inline-based module. Specifying of |
| 962 |
"ExtUtils::MakeMaker => 6.52," is optional, and can be omitted if you |
| 963 |
like. It ensures only that some harmless warnings relating to the |
| 964 |
CONFIGURE_REQUIRES directive won't be emitted during the building of |
| 965 |
the module. It also means, of course, that ExtUtils::Makemaker will |
| 966 |
first be updated on the user's machine unless the user already has |
| 967 |
version 6.52 or later. |
| 968 |
|
| 969 |
If the "Inline->init();" is not done then, having installed |
| 970 |
Math::Simple, a warning that "One or more DATA sections were not |
| 971 |
processed by Inline" will appear when (and only when) Math::Simple is |
| 972 |
loaded by a "require call. It's a harmless warning - and if you're |
| 973 |
prepared to live with it, then there's no need to make the |
| 974 |
"Inline->init();" call. |
| 975 |
|
| 976 |
When the person installing Math::Simple does a "make", the generated |
| 977 |
Makefile will invoke Inline in such a way that the C code will be |
| 978 |
compiled and the executable code will be placed into the ./blib |
| 979 |
directory. Then when a "make install" is done, the module will be |
| 980 |
copied into the appropriate Perl sitelib directory (which is where an |
| 981 |
installed module should go). |
| 982 |
|
| 983 |
Now all you need to do is: |
| 984 |
|
| 985 |
perl Makefile.PL |
| 986 |
make dist |
| 987 |
|
| 988 |
That will generate the file Math-Simple-0.20.tar.gz which is a |
| 989 |
distributable package. (It will also generate some harmless warnings in |
| 990 |
relation to CONFIGURE_REQUIRES unless the version of your |
| 991 |
ExtUtils::MakeMaker is 6.52 or later.) That's all there is to it. |
| 992 |
|
| 993 |
IMPORTANT NOTE: Although the above steps will produce a workable |
| 994 |
module, you still have a few more responsibilities as a budding new |
| 995 |
CPAN author. You need to write lots of documentation and write lots of |
| 996 |
tests. Take a look at some of the better CPAN modules for ideas on |
| 997 |
creating a killer test harness. Actually, don't listen to me, go read |
| 998 |
these: |
| 999 |
|
| 1000 |
* perldoc perlnewmod |
| 1001 |
|
| 1002 |
* http://www.cpan.org/modules/04pause.html |
| 1003 |
|
| 1004 |
* http://www.cpan.org/modules/00modlist.long.html |
| 1005 |
|
| 1006 |
HOW INLINE WORKS |
| 1007 |
|
| 1008 |
In reality, Inline just automates everything you would need to do if |
| 1009 |
you were going to do it by hand (using XS, etc). |
| 1010 |
|
| 1011 |
Inline performs the following steps: |
| 1012 |
|
| 1013 |
* Receive the Source Code |
| 1014 |
|
| 1015 |
Inline gets the source code from your script or module with a |
| 1016 |
statements like the following: |
| 1017 |
|
| 1018 |
use Inline C => "Source-Code"; |
| 1019 |
|
| 1020 |
or |
| 1021 |
|
| 1022 |
use Inline; |
| 1023 |
bind Inline C => "Source-Code"; |
| 1024 |
|
| 1025 |
where C is the programming language of the source code, and |
| 1026 |
Source-Code is a string, a file name, an array reference, or the |
| 1027 |
special 'DATA' keyword. |
| 1028 |
|
| 1029 |
Since Inline is coded in a "use" statement, everything is done during |
| 1030 |
Perl's compile time. If anything needs to be done that will affect |
| 1031 |
the Source-Code, it needs to be done in a BEGIN block that is before |
| 1032 |
the "useInline ..." statement. If you really need to specify code to |
| 1033 |
Inline at runtime, you can use the bind() method. |
| 1034 |
|
| 1035 |
Source code that is stowed in the 'DATA' section of your code, is |
| 1036 |
read in by an INIT subroutine in Inline. That's because the DATA |
| 1037 |
filehandle is not available at compile time. |
| 1038 |
|
| 1039 |
* Check if the Source Code has been Built |
| 1040 |
|
| 1041 |
Inline only needs to build the source code if it has not yet been |
| 1042 |
built. It accomplishes this seemingly magical task in an extremely |
| 1043 |
simple and straightforward manner. It runs the source text through |
| 1044 |
the Digest::MD5 module to produce a 128-bit "fingerprint" which is |
| 1045 |
virtually unique. The fingerprint along with a bunch of other |
| 1046 |
contingency information is stored in a .inl file that sits next to |
| 1047 |
your executable object. For instance, the C code from a script called |
| 1048 |
example.pl might create these files: |
| 1049 |
|
| 1050 |
example_pl_3a9a.so |
| 1051 |
example_pl_3a9a.inl |
| 1052 |
|
| 1053 |
If all the contingency information matches the values stored in the |
| 1054 |
.inl file, then proceed to step 8. (No compilation is necessary) |
| 1055 |
|
| 1056 |
* Find a Place to Build and Install |
| 1057 |
|
| 1058 |
At this point Inline knows it needs to build the source code. The |
| 1059 |
first thing to figure out is where to create the great big mess |
| 1060 |
associated with compilation, and where to put the object when it's |
| 1061 |
done. |
| 1062 |
|
| 1063 |
By default Inline will try to build and install under the first place |
| 1064 |
that meets one of the following conditions: |
| 1065 |
|
| 1066 |
1. The DIRECTORY= config option; if specified |
| 1067 |
|
| 1068 |
2. The PERL_INLINE_DIRECTORY environment variable; if set |
| 1069 |
|
| 1070 |
3. .Inline/ (in current directory); if exists and $PWD != $HOME |
| 1071 |
|
| 1072 |
4. bin.Inline (in directory of your script); if exists |
| 1073 |
|
| 1074 |
5. ~/.Inline/ - if exists |
| 1075 |
|
| 1076 |
6. ./_Inline/ - if exists |
| 1077 |
|
| 1078 |
7. bin/_Inline - if exists |
| 1079 |
|
| 1080 |
8. Create ./_Inline/ - if possible |
| 1081 |
|
| 1082 |
9. Create bin/_Inline/ - if possible |
| 1083 |
|
| 1084 |
Failing that, Inline will croak. This is rare and easily remedied by |
| 1085 |
just making a directory that Inline will use. |
| 1086 |
|
| 1087 |
If the PERL_INSTALL_ROOT Environment Variable has been set, you will |
| 1088 |
need to make special provision for that if the 'make install' phase |
| 1089 |
of your Inline scripts are to succeed. |
| 1090 |
|
| 1091 |
If the module option is being compiled for permanent installation, |
| 1092 |
then Inline will only use ./_Inline/ to build in, and the |
| 1093 |
$Config{installsitearch} directory to install the executable in. This |
| 1094 |
action is caused by Inline::MakeMaker, and is intended to be used in |
| 1095 |
modules that are to be distributed on the CPAN, so that they get |
| 1096 |
installed in the proper place. |
| 1097 |
|
| 1098 |
* Parse the Source for Semantic Cues |
| 1099 |
|
| 1100 |
Inline::C uses the module Parse::RecDescent to parse through your |
| 1101 |
chunks of C source code and look for things that it can create |
| 1102 |
run-time bindings to. In C it looks for all of the function |
| 1103 |
definitions and breaks them down into names and data types. These |
| 1104 |
elements are used to correctly bind the C function to a Perl |
| 1105 |
subroutine. Other Inline languages like Python and Java actually use |
| 1106 |
the python and javac modules to parse the Inline code. |
| 1107 |
|
| 1108 |
* Create the Build Environment |
| 1109 |
|
| 1110 |
Now Inline can take all of the gathered information and create an |
| 1111 |
environment to build your source code into an executable. Without |
| 1112 |
going into all the details, it just creates the appropriate |
| 1113 |
directories, creates the appropriate source files including an XS |
| 1114 |
file (for C) and a Makefile.PL. |
| 1115 |
|
| 1116 |
* Build the Code and Install the Executable |
| 1117 |
|
| 1118 |
The planets are in alignment. Now for the easy part. Inline just does |
| 1119 |
what you would do to install a module. "`perl Makefile.PL && make && |
| 1120 |
make test && make install>". If something goes awry, Inline will |
| 1121 |
croak with a message indicating where to look for more info. |
| 1122 |
|
| 1123 |
* Tidy Up |
| 1124 |
|
| 1125 |
By default, Inline will remove all of the mess created by the build |
| 1126 |
process, assuming that everything worked. If the build fails, Inline |
| 1127 |
will leave everything intact, so that you can debug your errors. |
| 1128 |
Setting the noclean shortcut option will also stop Inline from |
| 1129 |
cleaning up. |
| 1130 |
|
| 1131 |
* DynaLoad the Executable |
| 1132 |
|
| 1133 |
For C (and C++), Inline uses the DynaLoader::bootstrap method to pull |
| 1134 |
your external module into Perl space. Now you can call all of your |
| 1135 |
external functions like Perl subroutines. |
| 1136 |
|
| 1137 |
Other languages like Python and Java, provide their own loaders. |
| 1138 |
|
| 1139 |
SEE ALSO |
| 1140 |
|
| 1141 |
For information about using Inline with C see Inline::C. |
| 1142 |
|
| 1143 |
For sample programs using Inline with C see Inline::C-Cookbook. |
| 1144 |
|
| 1145 |
For "Formerly Answered Questions" about Inline, see Inline-FAQ. |
| 1146 |
|
| 1147 |
For information on supported languages and platforms see |
| 1148 |
Inline-Support. |
| 1149 |
|
| 1150 |
For information on writing your own Inline Language Support Module, see |
| 1151 |
Inline-API. |
| 1152 |
|
| 1153 |
Inline's mailing list is [email protected] |
| 1154 |
|
| 1155 |
To subscribe, send email to [email protected] |
| 1156 |
|
| 1157 |
BUGS AND DEFICIENCIES |
| 1158 |
|
| 1159 |
When reporting a bug, please do the following: |
| 1160 |
|
| 1161 |
* Put "use Inline 'reportbug';" at the top of your code, or use the |
| 1162 |
command line option "perl -MInline=reportbug ...". |
| 1163 |
|
| 1164 |
* Run your code. |
| 1165 |
|
| 1166 |
* Follow the printed directions. |
| 1167 |
|
| 1168 |
AUTHOR |
| 1169 |
|
| 1170 |
Ingy döt Net <[email protected]> |
| 1171 |
|
| 1172 |
Sisyphus <[email protected]> fixed some bugs and is current |
| 1173 |
co-maintainer. |
| 1174 |
|
| 1175 |
COPYRIGHT |
| 1176 |
|
| 1177 |
* Copyright 2000-2019. Ingy döt Net. |
| 1178 |
|
| 1179 |
* Copyright 2008, 2010-2014. Sisyphus. |
| 1180 |
|
| 1181 |
This program is free software; you can redistribute it and/or modify it |
| 1182 |
under the same terms as Perl itself. |
| 1183 |
|
| 1184 |
See http://www.perl.com/perl/misc/Artistic.html |
| 1185 |
|