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