1Inline(3)             User Contributed Perl Documentation            Inline(3)
2
3
4

NAME

6       Inline - Write Perl Subroutines in Other Programming Languages
7

VERSION

9       This document describes Inline version 0.86.
10

SYNOPSIS

12           use Inline C;
13
14           print "9 + 16 = ", add(9, 16), "\n";
15           print "9 - 16 = ", subtract(9, 16), "\n";
16
17           __END__
18           __C__
19           int add(int x, int y) {
20             return x + y;
21           }
22
23           int subtract(int x, int y) {
24             return x - y;
25           }
26

DESCRIPTION

28       The Inline module allows you to put source code from other programming
29       languages directly "inline" in a Perl script or module. The code is
30       automatically compiled as needed, and then loaded for immediate access
31       from Perl.
32
33       Inline saves you from the hassle of having to write and compile your
34       own glue code using facilities like XS or SWIG. Simply type the code
35       where you want it and run your Perl as normal. All the hairy details
36       are handled for you. The compilation and installation of your code
37       chunks all happen transparently; all you will notice is the delay of
38       compilation on the first run.
39
40       The Inline code only gets compiled the first time you run it (or
41       whenever it is modified) so you only take the performance hit once.
42       Code that is Inlined into distributed modules (like on the CPAN) will
43       get compiled when the module is installed, so the end user will never
44       notice the compilation time.
45
46       Best of all, it works the same on both Unix and Microsoft Windows. See
47       Inline- Support for support information.
48
49   Why Inline?
50       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
53       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
62           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
69           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
73           Maybe the best reason is "Because you want to!". Diversity keeps
74           the world interesting. TMTOWTDI!
75
76       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
82           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
86           •   perlxs
87
88           •   perlxstut
89
90           •   perlapi
91
92           •   perlguts
93
94           •   perlmod
95
96           •   h2xs
97
98           •   xsubpp
99
100           •   ExtUtils::MakeMaker
101
102           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
109           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
113           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
119           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

USING THE INLINE.PM MODULE

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
133       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
137   The Basics
138       The most basic form for using Inline is:
139
140           use Inline X => "X source code";
141
142       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
147       The DATA Keyword.
148               use Inline Java => 'DATA';
149
150               # Perl code goes here ...
151
152               __DATA__
153               __Java__
154               /* Java code goes here ... */
155
156           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
163           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
168           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
175           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
181       The FILE and BELOW keywords.
182               use Inline::Files;
183               use Inline Java => 'file';
184
185               # Perl code goes here ...
186
187               __JAVA__
188               /* Java code goes here ... */
189
190           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
195           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
200               use Inline C => 'below';
201
202           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
208           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
213           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
220           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
224       Strings
225               use Inline Java => <<'END';
226
227               /* Java code goes here ... */
228               END
229
230               # Perl code goes here ...
231
232           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
238           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
243               my $code;
244               BEGIN {
245                   $code = <<END;
246
247               /* Java code goes here ... */
248               END
249               }
250               use Inline Java => $code;
251
252               # Perl code goes here ...
253
254       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
260               my $code = <<END;
261
262               /* Java code goes here ... */
263               END
264
265               Inline->bind(Java => $code);
266
267           You can think of "bind()" as a way to "eval()" code in other
268           programming languages.
269
270           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
275       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
284           For instance, to load your C++ code from a file named the same as
285           your perl module with a swapped file extension, you can use:
286
287               use Inline CPP => (__FILE__ =~ s/\.pm$/.cpp/r);
288
289       Shorthand
290           If you are using the 'DATA' or 'file' methods described above and
291           there are no extra parameters, you can omit the keyword altogether.
292           For example:
293
294               use Inline 'Java';
295
296               # Perl code goes here ...
297
298               __DATA__
299               __Java__
300               /* Java code goes here ... */
301
302           or
303
304               use Inline::Files;
305               use Inline 'Java';
306
307               # Perl code goes here ...
308
309               __JAVA__
310               /* Java code goes here ... */
311
312   More about the DATA Section
313       If you are writing a module, you can also use the DATA section for POD
314       and AutoLoader subroutines. Just be sure to put them before the first
315       Inline marker. If you install the helper module "Inline::Filters", you
316       can even use POD inside your Inline code. You just have to specify a
317       filter to strip it out.
318
319       You can also specify multiple Inline sections, possibly in different
320       programming languages. Here is another example:
321
322           # The module Foo.pm
323           package Foo;
324           use AutoLoader;
325
326           use Inline C;
327           use Inline C => DATA => filters => 'Strip_POD';
328           use Inline Python;
329
330           1;
331
332           __DATA__
333
334           sub marine {
335               # This is an autoloaded subroutine
336           }
337
338           =head1 External subroutines
339
340           =cut
341
342           __C__
343           /* First C section */
344
345           __C__
346           /* Second C section */
347           =head1 My C Function
348
349           Some POD doc.
350
351           =cut
352
353           __Python__
354           """A Python Section"""
355
356       An important thing to remember is that you need to have one "use Inline
357       Foo => 'DATA'" for each "__Foo__" marker, and they must be in the same
358       order.  This allows you to apply different configuration options to
359       each section.
360
361   Configuration Options
362       Inline tries to do the right thing as often as possible. But sometimes
363       you may need to override the default actions. This is easy to do.
364       Simply list the Inline configuration options after the regular Inline
365       parameters. All configuration options are specified as (key, value)
366       pairs.
367
368           use Inline (C => 'DATA',
369                       directory => './inline_dir',
370                       libs => '-lfoo',
371                       inc => '-I/foo/include',
372                       prefix => 'XXX_',
373                       warnings => 0,
374                      );
375
376       You can also specify the configuration options on a separate Inline
377       call like this:
378
379           use Inline (C => Config =>
380                       directory => './inline_dir',
381                       libs => '-lfoo',
382                       inc => '-I/foo/include',
383                       prefix => 'XXX_',
384                       warnings => 0,
385                      );
386           use Inline C => <<'END_OF_C_CODE';
387
388       The special keyword 'Config' tells Inline that this is a configuration-
389       only call. No source code will be compiled or bound to Perl.
390
391       If you want to specify global configuration options that don't apply to
392       a particular language, just leave the language out of the call. Like
393       this:
394
395           use Inline Config => warnings => 0;
396
397       The Config options are inherited and additive. You can use as many
398       Config calls as you want. And you can apply different options to
399       different code sections. When a source code section is passed in,
400       Inline will apply whichever options have been specified up to that
401       point. Here is a complex configuration example:
402
403           use Inline (Config =>
404                       directory => './inline_dir',
405                      );
406           use Inline (C => Config =>
407                       libs => '-lglobal',
408                      );
409           use Inline (C => 'DATA',         # First C Section
410                       libs => ['-llocal1', '-llocal2'],
411                      );
412           use Inline (Config =>
413                       warnings => 0,
414                      );
415           use Inline (Python => 'DATA',    # First Python Section
416                       libs => '-lmypython1',
417                      );
418           use Inline (C => 'DATA',         # Second C Section
419                       libs => [undef, '-llocal3'],
420                      );
421
422       The first "Config" applies to all subsequent calls. The second "Config"
423       applies to all subsequent "C" sections (but not "Python" sections). In
424       the first "C" section, the external libraries "global", "local1" and
425       "local2" are used. (Most options allow either string or array ref
426       forms, and do the right thing.) The "Python" section does not use the
427       "global" library, but does use the same "DIRECTORY", and has warnings
428       turned off. The second "C" section only uses the "local3" library.
429       That's because a value of "undef" resets the additive behavior.
430
431       The "directory" and "warnings" options are generic Inline options. All
432       other options are language specific. To find out what the "C" options
433       do, see "Inline::C".
434
435   On and Off
436       If a particular config option has value options of 1 and 0, you can use
437       the 'enable' and 'disable' modifiers. In other words, this:
438
439           use Inline Config =>
440                      force_build => 1,
441                      clean_after_build => 0;
442
443       could be reworded as:
444
445           use Inline Config =>
446                      enable => force_build =>
447                      disable => clean_after_build;
448
449   Playing 'with' Others
450       Inline has a special configuration syntax that tells it to get more
451       configuration options from other Perl modules. Here is an example:
452
453           use Inline with => 'Event';
454
455       This tells Inline to load the module "Event.pm" and ask it for
456       configuration information. Since "Event" has a C API of its own, it can
457       pass Inline all of the information it needs to be able to use "Event" C
458       callbacks seamlessly.
459
460       That means that you don't need to specify the typemaps, shared
461       libraries, include files and other information required to get this to
462       work.
463
464       You can specify a single module or a list of them. Like:
465
466           use Inline with => qw(Event Foo Bar);
467
468       Currently, modules that works with Inline include "Event", "PDL", and
469       those that use "Alien::Build".
470
471       In order to make your module work with Inline in this way, your module
472       needs to provide a class method called "Inline" that takes an Inline
473       language as a parameter (e.g. "C"), and returns a reference to a hash
474       with configuration information that is acceptable to the relevant ILSM.
475       For C, see C Configuration Options. E.g.:
476
477           my $confighashref = Event->Inline('C'); # only supports C in 1.21
478           # hashref contains keys INC, TYPEMAPS, MYEXTLIB, AUTO_INCLUDE, BOOT
479
480       If your module uses ExtUtils::Depends version 0.400 or higher, your
481       module only needs this:
482
483           package Module;
484           use autouse Module::Install::Files => qw(Inline);
485
486   Inline Shortcuts
487       Inline lets you set many configuration options from the command line.
488       These options are called 'shortcuts'. They can be very handy,
489       especially when you only want to set the options temporarily, for say,
490       debugging.
491
492       For instance, to get some general information about your Inline code in
493       the script "Foo.pl", use the command:
494
495           perl -MInline=info Foo.pl
496
497       If you want to force your code to compile, even if its already done,
498       use:
499
500           perl -MInline=force Foo.pl
501
502       If you want to do both, use:
503
504           perl -MInline=info -MInline=force Foo.pl
505
506       or better yet:
507
508           perl -MInline=info,force Foo.pl
509
510   The Inline 'directory'
511       Inline needs a place to build your code and to install the results of
512       the build. It uses a single directory named '.Inline/' under normal
513       circumstances. If you create this directory in your home directory, the
514       current directory or in the directory where your program resides,
515       Inline will find and use it. You can also specify it in the environment
516       variable "PERL_INLINE_DIRECTORY" or directly in your program, by using
517       the "directory" keyword option. If Inline cannot find the directory in
518       any of these places it will create a '_Inline/' directory in either
519       your current directory or the directory where your script resides.
520
521       One of the key factors to using Inline successfully, is understanding
522       this directory. When developing code it is usually best to create this
523       directory (or let Inline do it) in your current directory. Remember
524       that there is nothing sacred about this directory except that it holds
525       your compiled code.  Feel free to delete it at any time. Inline will
526       simply start from scratch and recompile your code on the next run. If
527       you have several programs that you want to force to recompile, just
528       delete your '.Inline/' directory.
529
530       It is probably best to have a separate '.Inline/' directory for each
531       project that you are working on. You may want to keep stable code in
532       the <.Inline/> in your home directory. On multi-user systems, each user
533       should have their own '.Inline/' directories. It could be a security
534       risk to put the directory in a shared place like "/tmp/".
535
536   Debugging Inline Errors
537       All programmers make mistakes. When you make a mistake with Inline,
538       like writing bad C code, you'll get a big error report on your screen.
539       This report tells you where to look to do the debugging. Some languages
540       may also dump out the error messages generated from the build.
541
542       When Inline needs to build something it creates a subdirectory under
543       your "DIRECTORY/build/" directory. This is where it writes all the
544       components it needs to build your extension. Things like XS files,
545       Makefiles and output log files.
546
547       If everything goes OK, Inline will delete this subdirectory. If there
548       is an error, Inline will leave the directory intact and print its
549       location.  The idea is that you are supposed to go into that directory
550       and figure out what happened.
551
552       Read the doc for your particular Inline Language Support Module for
553       more information.
554
555   The 'config' Registry File
556       Inline keeps a cached file of all of the Inline Language Support
557       Module's meta data in a file called "config". This file can be found in
558       your "directory" directory. If the file does not exist, Inline creates
559       a new one. It will search your system for any module beginning with
560       "Inline::". It will then call that module's "register()" method to get
561       useful information for future invocations.
562
563       Whenever you add a new ILSM, you should delete this file so that Inline
564       will auto-discover your newly installed language module. (This should
565       no longer be necessary as of Inline-0.49.)
566

CONFIGURATION OPTIONS

568       This section lists all of the generic Inline configuration options. For
569       language specific configuration, see the doc for that language.
570
571       "directory"
572           The "directory" config option is the directory that Inline uses to
573           both build and install an extension.
574
575           Normally Inline will search in a bunch of known places for a
576           directory called '.Inline/'. Failing that, it will create a
577           directory called '_Inline/'
578
579           If you want to specify your own directory, use this configuration
580           option.
581
582           Note that you must create the "directory" directory yourself.
583           Inline will not do it for you.
584
585       "name"
586           You can use this option to set the name of your Inline extension
587           object module. For example:
588
589               use Inline C => 'DATA',
590                          name => 'Foo::Bar';
591
592           would cause your C code to be compiled in to the object:
593
594               lib/auto/Foo/Bar/Bar.so
595               lib/auto/Foo/Bar/Bar.inl
596
597           (The .inl component contains dependency information to make sure
598           the source code is in sync with the executable)
599
600           If you don't use "name", Inline will pick a name for you based on
601           your program name or package name. In this case, Inline will also
602           enable the "autoname" option which mangles in a small piece of the
603           MD5 fingerprint into your object name, to make it unique.
604
605       "autoname"
606           This option is enabled whenever the "name" parameter is not
607           specified. To disable it say:
608
609               use Inline C => 'DATA',
610                          disable => 'autoname';
611
612           "autoname" mangles in enough of the MD5 fingerprint to make your
613           module name unique. Objects created with "autoname" will never get
614           replaced. That also means they will never get cleaned up
615           automatically.
616
617           "autoname" is very useful for small throw away scripts. For more
618           serious things, always use the "name" option.
619
620       "version"
621           Specifies the version number of the Inline extension object. It is
622           used only for modules, and it must match the global variable
623           $VERSION.  Additionally, this option should used if (and only if) a
624           module is being set up to be installed permanently into the Perl
625           sitelib tree using Inline::MakeMaker (NOT used by Inline::Module).
626           Inline will croak if you use it otherwise.
627
628           The presence of the "version" parameter is the official way to let
629           Inline know that your code is an installable/installed module.
630           Inline will never generate an object in the temporary cache
631           ("_Inline/" directory) if "version" is set. It will also never try
632           to recompile a module that was installed into someone's Perl site
633           tree.
634
635           So the basic rule is develop without "version", and deliver with
636           "version".
637
638       "with"
639           "with" can also be used as a configuration option instead of using
640           the special 'with' syntax. Do this if you want to use different
641           sections of Inline code with different modules. (Probably a very
642           rare usage)
643
644               use Event;
645               use Inline C => DATA => with => 'Event';
646
647           Modules specified using the config form of "with" will not be
648           automatically required. You must "use" them yourself.
649
650       "using"
651           You can override modules that get used by ILSMs with the "using"
652           option. This is typically used to override the default parser for
653           Inline::C, but might be used by any ILSM for any purpose.
654
655               use Inline config => using => '::Parser::RecDescent';
656               use Inline C => '...';
657
658           This would tell Inline::C to use Inline::C::Parser::RecDescent.
659
660       "global_load"
661           This option is for compiled languages only. It tells Inline to tell
662           DynaLoader to load an object file in such a way that its symbols
663           can be dynamically resolved by other object files. May not work on
664           all platforms. See the "global" shortcut below.
665
666       "untaint"
667           You can use this option whenever you use Perl's "-T" switch, for
668           taint checking. This option tells Inline to blindly untaint all
669           tainted variables.  (This is generally considered to be an
670           appallingly insecure thing to do, and not to be recommended - but
671           the option is there for you to use if you want.  Please consider
672           using something other than Inline for scripts that need taint
673           checking.) It also turns on "safemode" by default. See the
674           "untaint" shortcut below. You will see warnings about blindly
675           untainting fields in both %ENV and Inline objects. If you want to
676           silence these warnings, set the Config option "no_untaint_warn" =>
677           1. There can be some problems untainting Inline scripts where older
678           versions of Cwd, such as those that shipped with early versions of
679           perl-5.8 (and earlier), are installed. Updating Cwd will probably
680           solve these problems.
681
682       safemode
683           Perform extra safety checking, in an attempt to thwart malicious
684           code. This option cannot guarantee security, but it does turn on
685           all the currently implemented checks. (Currently, the only
686           "currently implemented check" is to ensure that the "directory"
687           option has also been used.)
688
689           There is a slight startup penalty by using "safemode". Also, using
690           "untaint" automatically turns this option on. If you need your code
691           to start faster under "-T" (taint) checking, you'll need to turn
692           this option off manually.  Only do this if you are not worried
693           about security risks. See the "unsafe" shortcut below.
694
695       "force_build"
696           Makes Inline build (compile) the source code every time the program
697           is run.  The default is 0. See the "force" shortcut below.
698
699       "build_noisy"
700           Tells ILSMs that they should dump build messages to the terminal
701           rather than be silent about all the build details.
702
703       "build_timers"
704           Tells ILSMs to print timing information about how long each build
705           phase took.  Usually requires "Time::HiRes".
706
707       "clean_after_build"
708           Tells Inline to clean up the current build area if the build was
709           successful.  Sometimes you want to "disable" this for debugging.
710           Default is 1. See the "noclean" shortcut below.
711
712       "clean_build_area"
713           Tells Inline to clean up the old build areas within the entire
714           Inline "directory". Default is 0. See the "clean" shortcut below.
715
716       "print_info"
717           Tells Inline to print various information about the source code.
718           Default is 0.  See the "info" shortcut below.
719
720       "print_version"
721           Tells Inline to print version info about itself. Default is 0. See
722           the "version" shortcut below.
723
724       "reportbug"
725           Puts Inline into 'reportbug' mode, which is what you want if you
726           desire to report a bug.
727
728       "rewrite_config_file"
729           Default is 0, but setting "rewrite_config_file => 1" will mean that
730           the existing configuration file in the Inline "directory" will be
731           overwritten.  (This is useful if the existing config file is not up
732           to date as regards supported languages.)
733
734       "warnings"
735           This option tells Inline whether to print certain warnings. Default
736           is 1.
737

INLINE CONFIGURATION SHORTCUTS

739       This is a list of all the shortcut configuration options currently
740       available for Inline. Specify them from the command line when running
741       Inline scripts.
742
743           perl -MInline=noclean inline_script.pl
744
745       or
746
747           perl -MInline=info,force,noclean inline_script.pl
748
749       You can specify multiple shortcuts separated by commas. They are not
750       case sensitive. You can also specify shortcuts inside the Inline
751       program like this:
752
753           use Inline 'info', 'force', 'noclean';
754
755       NOTE: If a 'use Inline' statement is used to set shortcuts, it can not
756       be
757             used for additional purposes.
758
759       "clean"
760           Tells Inline to remove any build directories that may be lying
761           around in your build area. Normally these directories get removed
762           immediately after a successful build. Exceptions are when the build
763           fails, or when you use the "noclean" or "reportbug" options.
764
765       "force"
766           Forces the code to be recompiled, even if everything is up to date.
767
768       "global"
769           Turns on the "global_load" option.
770
771       "info"
772           This is a very useful option when you want to know what's going on
773           under the hood. It tells Inline to print helpful information to
774           "STDERR". Among the things that get printed is a list of which
775           Inline functions were successfully bound to Perl.
776
777       "noclean"
778           Tells Inline to leave the build files after compiling.
779
780       "noisy"
781           Use the "build_noisy" option to print messages during a build.
782
783       "reportbug"
784           Puts Inline into "reportbug" mode, which does special processing
785           when you want to report a bug. "reportbug" also automatically
786           forces a build, and doesn't clean up afterwards. This is so that
787           you can tar and mail the build directory to me. "reportbug" will
788           print exact instructions on what to do.  Please read and follow
789           them carefully.
790
791           NOTE: "reportbug" informs you to use the tar command. If your
792           system does not
793                 have tar, please use the equivalent "zip" command.
794
795       "safe"
796           Turns "safemode" on. "untaint" will turn this on automatically.
797           While this mode performs extra security checking, it does not
798           guarantee safety.
799
800       "site_install"
801           This parameter used to be used for creating installable Inline
802           modules. It has been removed from Inline altogether and replaced
803           with a much simpler and more powerful mechanism,
804           "Inline::MakeMaker". See the section below on how to create modules
805           with Inline.
806
807       "_testing"
808           Used internally by Ct09parser.t and Ct10callback.t(in the Inline::C
809           test suite). Setting this option with Inline::C will mean that
810           files named "parser_id" and "void_test" are created in the
811           "./Inline_test" directory, creating that directory if it doesn't
812           already exist. The files (but not the "./Inline_test directory")
813           are cleaned up by calling "Inline::C::_testing_cleanup()". Also
814           used by "t/06rewrite_config.t" to trigger a warning.
815
816       "timers"
817           Turn on "build_timers" to get extra diagnostic info about builds.
818
819       "unsafe"
820           Turns "safemode" off. Use this in combination with "untaint" for
821           slightly faster startup time under "-T". Only use this if you are
822           sure the environment is safe.
823
824       "untaint"
825           Turn the "untaint" option on. Used with "-T" switch. In terms of
826           secure practices, this is definitely not a recommended way of
827           dealing with taint checking, but it's the only option currently
828           available with Inline. Use it at your own risk.
829
830       "version"
831           Tells Inline to report its release version.
832

WRITING MODULES WITH INLINE

834       The current preferred way to author CPAN modules with Inline is to use
835       Inline::Module (distributed separately). Inline ships with
836       Inline::MakeMaker, which helps you set up a Makefile.PL that invokes
837       Inline at install time to compile all the code before it gets
838       installed, but the resulting module still depends on Inline and the
839       language support module like Inline::C. In order to avoid this
840       dependency, what you really want to do is convert your distribution to
841       plain XS before uploading it to CPAN. Inline::Module fills that role,
842       and also integrates well with more modern authoring tools.
843
844       See Inline::Module for details on that approach, or continue reading
845       below for the older Inline::MakeMaker technique.
846
847       Let's say that you wanted to write a module called "Math::Simple".
848       Start by using the following command:
849
850           h2xs -PAXn Math::Simple
851
852       This will generate a bunch of files that form a skeleton of what you
853       need for a distributable module. (Read the h2xs manpage to find out
854       what the options do) Next, modify the "Simple.pm" file to look like
855       this:
856
857           package Math::Simple;
858           $VERSION = '1.23';
859
860           use base 'Exporter';
861           @EXPORT_OK = qw(add subtract);
862           use strict;
863
864           use Inline C => 'DATA',
865                      version => '1.23',
866                      name => 'Math::Simple';
867
868           # The following Inline->init() call is optional - see below for more info.
869           #Inline->init();
870
871           1;
872
873           __DATA__
874
875           =pod
876
877           =cut
878
879           __C__
880           int add(int x, int y) {
881             return x + y;
882           }
883
884           int subtract(int x, int y) {
885             return x - y;
886           }
887
888       The important things to note here are that you must specify a "name"
889       and "version" parameter. The "name" must match your module's package
890       name. The "version" parameter must match your module's $VERSION
891       variable and they must be considered valid by "version::parse".
892
893       NOTE: These are Inline's sanity checks to make sure you know what
894       you're doing
895             before uploading your code to CPAN. They insure that once the
896       module has
897             been installed on someone's system, the module would not get
898             automatically recompiled for any reason. This makes Inline based
899       modules
900             work in exactly the same manner as XS based ones.
901
902       Finally, you need to modify the Makefile.PL. Simply change:
903
904           use ExtUtils::MakeMaker;
905
906       to
907
908           use Inline::MakeMaker;
909
910       And, in order that the module build work correctly in the cpan shell,
911       add the following directive to the Makefile.PL's WriteMakefile():
912
913           CONFIGURE_REQUIRES  =>  {
914               'Inline::MakeMaker'     => 0.45,
915               'ExtUtils::MakeMaker'   => 6.52,
916           },
917
918       This "CONFIGURE_REQUIRES" directive ensures that the cpan shell will
919       install Inline on the user's machine (if it's not already present)
920       before building your Inline-based module. Specifying of
921       "ExtUtils::MakeMaker => 6.52," is optional, and can be omitted if you
922       like. It ensures only that some harmless warnings relating to the
923       "CONFIGURE_REQUIRES" directive won't be emitted during the building of
924       the module. It also means, of course, that ExtUtils::Makemaker will
925       first be updated on the user's machine unless the user already has
926       version 6.52 or later.
927
928       If the "Inline->init();" is not done then, having installed
929       Math::Simple, a warning that "One or more DATA sections were not
930       processed by Inline" will appear when (and only when) Math::Simple is
931       loaded by a "require call. It's a harmless warning - and if you're
932       prepared to live with it, then there's no need to make the
933       "Inline->init();" call.
934
935       When the person installing "Math::Simple" does a ""make"", the
936       generated Makefile will invoke Inline in such a way that the C code
937       will be compiled and the executable code will be placed into the
938       "./blib" directory. Then when a ""make install"" is done, the module
939       will be copied into the appropriate Perl sitelib directory (which is
940       where an installed module should go).
941
942       Now all you need to do is:
943
944           perl Makefile.PL
945           make dist
946
947       That will generate the file "Math-Simple-0.20.tar.gz" which is a
948       distributable package. (It will also generate some harmless warnings in
949       relation to "CONFIGURE_REQUIRES" unless the version of your
950       ExtUtils::MakeMaker is 6.52 or later.) That's all there is to it.
951
952       IMPORTANT NOTE: Although the above steps will produce a workable
953       module, you still have a few more responsibilities as a budding new
954       CPAN author. You need to write lots of documentation and write lots of
955       tests. Take a look at some of the better CPAN modules for ideas on
956       creating a killer test harness.  Actually, don't listen to me, go read
957       these:
958
959       •   perldoc perlnewmod
960
961       •   <http://www.cpan.org/modules/04pause.html>
962
963       •   <http://www.cpan.org/modules/00modlist.long.html>
964

HOW INLINE WORKS

966       In reality, Inline just automates everything you would need to do if
967       you were going to do it by hand (using XS, etc).
968
969       Inline performs the following steps:
970
971       •   Receive the Source Code
972
973           Inline gets the source code from your script or module with a
974           statements like the following:
975
976               use Inline C => "Source-Code";
977
978           or
979
980               use Inline;
981               bind Inline C => "Source-Code";
982
983           where "C" is the programming language of the source code, and
984           "Source- Code" is a string, a file name, an array reference, or the
985           special 'DATA' keyword.
986
987           Since Inline is coded in a ""use"" statement, everything is done
988           during Perl's compile time. If anything needs to be done that will
989           affect the "Source- Code", it needs to be done in a "BEGIN" block
990           that is before the ""use Inline ..."" statement. If you really need
991           to specify code to Inline at runtime, you can use the "bind()"
992           method.
993
994           Source code that is stowed in the 'DATA' section of your code, is
995           read in by an "INIT" subroutine in Inline. That's because the
996           "DATA" filehandle is not available at compile time.
997
998       •   Check if the Source Code has been Built
999
1000           Inline only needs to build the source code if it has not yet been
1001           built. It accomplishes this seemingly magical task in an extremely
1002           simple and straightforward manner. It runs the source text through
1003           the "Digest::MD5" module to produce a 128-bit "fingerprint" which
1004           is virtually unique. The fingerprint along with a bunch of other
1005           contingency information is stored in a ".inl" file that sits next
1006           to your executable object. For instance, the "C" code from a script
1007           called "example.pl" might create these files:
1008
1009               example_pl_3a9a.so
1010               example_pl_3a9a.inl
1011
1012           If all the contingency information matches the values stored in the
1013           ".inl" file, then proceed to step 8. (No compilation is necessary)
1014
1015       •   Find a Place to Build and Install
1016
1017           At this point Inline knows it needs to build the source code. The
1018           first thing to figure out is where to create the great big mess
1019           associated with compilation, and where to put the object when it's
1020           done.
1021
1022           By default Inline will try to build and install under the first
1023           place that meets one of the following conditions:
1024
1025           1.  The DIRECTORY= config option; if specified
1026
1027           2.  The "PERL_INLINE_DIRECTORY" environment variable; if set
1028
1029           3.  ".Inline/" (in current directory); if exists and "$PWD !=
1030               $HOME"
1031
1032           4.  bin.Inline (in directory of your script); if exists
1033
1034           5.  "~/.Inline/" - if exists
1035
1036           6.  "./_Inline/" - if exists
1037
1038           7.  "bin/_Inline" - if exists
1039
1040           8.  Create "./_Inline/" - if possible
1041
1042           9.  Create "bin/_Inline/" - if possible
1043
1044           Failing that, Inline will croak. This is rare and easily remedied
1045           by just making a directory that Inline will use.
1046
1047           If the "PERL_INSTALL_ROOT" Environment Variable has been set, you
1048           will need to make special provision for that if the 'make install'
1049           phase of your Inline scripts are to succeed.
1050
1051           If the module option is being compiled for permanent installation,
1052           then Inline will only use "./_Inline/" to build in, and the
1053           $Config{installsitearch} directory to install the executable in.
1054           This action is caused by Inline::MakeMaker, and is intended to be
1055           used in modules that are to be distributed on the CPAN, so that
1056           they get installed in the proper place.
1057
1058       •   Parse the Source for Semantic Cues
1059
1060           Inline::C uses the module "Parse::RecDescent" to parse through your
1061           chunks of C source code and look for things that it can create run-
1062           time bindings to. In "C" it looks for all of the function
1063           definitions and breaks them down into names and data types. These
1064           elements are used to correctly bind the "C" function to a "Perl"
1065           subroutine. Other Inline languages like Python and Java actually
1066           use the "python" and "javac" modules to parse the Inline code.
1067
1068       •   Create the Build Environment
1069
1070           Now Inline can take all of the gathered information and create an
1071           environment to build your source code into an executable. Without
1072           going into all the details, it just creates the appropriate
1073           directories, creates the appropriate source files including an XS
1074           file (for C) and a "Makefile.PL".
1075
1076       •   Build the Code and Install the Executable
1077
1078           The planets are in alignment. Now for the easy part. Inline just
1079           does what you would do to install a module. "`perl Makefile.PL &&
1080           make && make test && make install>". If something goes awry, Inline
1081           will croak with a message indicating where to look for more info.
1082
1083       •   Tidy Up
1084
1085           By default, Inline will remove all of the mess created by the build
1086           process, assuming that everything worked. If the build fails,
1087           Inline will leave everything intact, so that you can debug your
1088           errors. Setting the "noclean" shortcut option will also stop Inline
1089           from cleaning up.
1090
1091       •   DynaLoad the Executable
1092
1093           For C (and C++), Inline uses the "DynaLoader::bootstrap" method to
1094           pull your external module into "Perl" space. Now you can call all
1095           of your external functions like Perl subroutines.
1096
1097           Other languages like Python and Java, provide their own loaders.
1098

SEE ALSO

1100       For information about using Inline with C see Inline::C.
1101
1102       For sample programs using Inline with C see Inline::C-Cookbook.
1103
1104       For "Formerly Answered Questions" about Inline, see Inline-FAQ.
1105
1106       For information on supported languages and platforms see Inline-
1107       Support.
1108
1109       For information on writing your own Inline Language Support Module, see
1110       Inline-API.
1111
1112       Inline's mailing list is inline@perl.org
1113
1114       To subscribe, send email to inline-subscribe@perl.org
1115

BUGS AND DEFICIENCIES

1117       When reporting a bug, please do the following:
1118
1119       •   Put "use Inline 'reportbug';" at the top of your code, or use the
1120           command line option "perl -MInline=reportbug ...".
1121
1122       •   Run your code.
1123
1124       •   Follow the printed directions.
1125

AUTHOR

1127       Ingy döt Net <ingy@cpan.org>
1128
1129       Sisyphus <sisyphus@cpan.org> fixed some bugs and is current co-
1130       maintainer.
1131
1133       •   Copyright 2000-2019. Ingy döt Net.
1134
1135       •   Copyright 2008, 2010-2014. Sisyphus.
1136
1137       This program is free software; you can redistribute it and/or modify it
1138       under the same terms as Perl itself.
1139
1140       See <http://www.perl.com/perl/misc/Artistic.html>
1141
1142
1143
1144perl v5.34.0                      2022-01-21                         Inline(3)
Impressum