Commit | Line | Data |
---|---|---|
86530b38 AT |
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 |