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