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