Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Inline(3)	      User Contributed Perl Documentation	     Inline(3)

NAME
       Inline -	Write Perl Subroutines in Other	Programming Languages

VERSION
       This document describes Inline version 0.86.

SYNOPSIS
	   use Inline C;

	   print "9 + 16 = ", add(9, 16), "\n";
	   print "9 - 16 = ", subtract(9, 16), "\n";

	   __END__
	   __C__
	   int add(int x, int y) {
	     return x +	y;
	   }

	   int subtract(int x, int y) {
	     return x -	y;
	   }

DESCRIPTION
       The Inline module allows	you to put source code from other programming
       languages directly "inline" in a	Perl script or module. The code	is
       automatically compiled as needed, and then loaded for immediate access
       from Perl.

       Inline saves you	from the hassle	of having to write and compile your
       own glue	code using facilities like XS or SWIG. Simply type the code
       where you want it and run your Perl as normal. All the hairy details
       are handled for you. The	compilation and	installation of	your code
       chunks all happen transparently;	all you	will notice is the delay of
       compilation on the first	run.

       The Inline code only gets compiled the first time you run it (or
       whenever	it is modified)	so you only take the performance hit once.
       Code that is Inlined into distributed modules (like on the CPAN)	will
       get compiled when the module is installed, so the end user will never
       notice the compilation time.

       Best of all, it works the same on both Unix and Microsoft Windows. See
       Inline- Support for support information.

   Why Inline?
       Do you want to know "Why	would I	use other languages in Perl?" or "Why
       should I	use Inline to do it?"? I'll try	to answer both.

       Why would I use other languages in Perl?
	   The most obvious reason is performance. For an interpreted
	   language, Perl is very fast.	Many people will say "Anything Perl
	   can do, C can do faster". (They never mention the development time
	   :-) Anyway, you may be able to remove a bottleneck in your Perl
	   code	by using another language, without having to write the entire
	   program in that language. This keeps	your overall development time
	   down, because you're	using Perl for all of the non-critical code.

	   Another reason is to	access functionality from existing API-s that
	   use the language. Some of this code may only	be available in	binary
	   form. But by	creating small subroutines in the native language, you
	   can "glue" existing libraries to your Perl. As a user of the	CPAN,
	   you know that code reuse is a good thing. So	why throw away those
	   Fortran libraries just yet?

	   If you are using Inline with	the C language,	then you can access
	   the full internals of Perl itself. This opens up the	floodgates to
	   both	extreme	power and peril.

	   Maybe the best reason is "Because you want to!". Diversity keeps
	   the world interesting. TMTOWTDI!

       Why should I use	Inline to do it?
	   There are already two major facilities for extending	Perl with C.
	   They	are XS and SWIG. Both are similar in their capabilities, at
	   least as far	as Perl	is concerned. And both of them are quite
	   difficult to	learn compared to Inline.

	   There is a big fat learning curve involved with setting up and
	   using the XS	environment. You need to get quite intimate with the
	   following docs:

	   o   perlxs

	   o   perlxstut

	   o   perlapi

	   o   perlguts

	   o   perlmod

	   o   h2xs

	   o   xsubpp

	   o   ExtUtils::MakeMaker

	   With	Inline you can be up and running in minutes. There is a	C
	   Cookbook with lots of short but complete programs that you can
	   extend to your real-life problems. No need to learn about the
	   complicated build process going on in the background. You don't
	   even	need to	compile	the code yourself. Inline takes	care of	every
	   last	detail except writing the C code.

	   Perl	programmers cannot be bothered with silly things like
	   compiling. "Tweak, Run, Tweak, Run" is our way of life. Inline does
	   all the dirty work for you.

	   Another advantage of	Inline is that you can use it directly in a
	   script. You can even	use it in a Perl one-liner. With XS and	SWIG,
	   you always set up an	entirely separate module. Even if you only
	   have	one or two functions. Inline makes easy	things easy, and hard
	   things possible. Just like Perl.

	   Finally, Inline supports several programming	languages (not just C
	   and C++). As	of this	writing, Inline	has support for	C, C++,	Java,
	   Python, Ruby, Tcl, Assembler, Basic,	Guile, Befunge,	Octave,	Awk,
	   BC, TT (Template Toolkit), WebChat and even PERL. New Inline
	   Language Support Modules (ILSMs) are	regularly being	added. See
	   Inline-API for details on how to create your	own ILSM.

USING THE INLINE.PM MODULE
       Inline is a little bit different	than most of the Perl modules that you
       are used	to. It doesn't import any functions into your namespace	and it
       doesn't have any	object oriented	methods. Its entire interface (with
       two minor exceptions) is	specified through the 'use Inline ...'
       command.

       This section will explain all of	the different ways to "use Inline". If
       you want	to begin using C with Inline immediately, see
       Inline::C-Cookbook.

   The Basics
       The most	basic form for using Inline is:

	   use Inline X	=> "X source code";

       where 'X' is one	of the supported Inline	programming languages. The
       second parameter	identifies the source code that	you want to bind to
       Perl. The source	code can be specified using any	of the following
       syntaxes:

       The DATA	Keyword.
	       use Inline Java => 'DATA';

	       # Perl code goes	here ...

	       __DATA__
	       __Java__
	       /* Java code goes here ... */

	   The easiest and most	visually clean way to specify your source code
	   in an Inline	Perl program is	to use the special "DATA" keyword.
	   This	tells Inline to	look for a special marker in your "DATA"
	   filehandle's	input stream. In this example the special marker is
	   "__Java__", which is	the programming	language surrounded by double
	   underscores.

	   In case you've forgotten, the "DATA"	pseudo file is comprised of
	   all the text	after the "__END__" or "__DATA__" section of your
	   program. If you're working outside the "main" package, you'd	best
	   use the "__DATA__" marker or	else Inline will not find your code.

	   Using this scheme keeps your	Perl code at the top, and all the ugly
	   Java	stuff down below where it belongs. This	is visually clean and
	   makes for more maintainable code. An	excellent side benefit is that
	   you don't have to escape any	characters like	you might in a Perl
	   string. The source code is verbatim.	 For these reasons, I prefer
	   this	method the most.

	   The only problem with this style is that since Perl can't read the
	   "DATA" filehandle until runtime, it obviously can't bind your
	   functions until runtime. The	net effect of this is that you can't
	   use your Inline functions as	barewords (without predeclaring	them)
	   because Perl	has no idea they exist during compile time.

       The FILE	and BELOW keywords.
	       use Inline::Files;
	       use Inline Java => 'file';

	       # Perl code goes	here ...

	       __JAVA__
	       /* Java code goes here ... */

	   This	is the newest method of	specifying your	source code. It	makes
	   use of the Perl module "Inline::Files" written by Damian Conway.
	   The basic style and meaning are the same as for the "DATA" keyword,
	   but there are a few syntactic and semantic twists.

	   First, you must say 'use Inline::Files' before you 'use Inline'
	   code	that needs those files.	The special '"DATA"' keyword is
	   replaced by either '"file"' or '"below"'. This allows for the bad
	   pun idiom of:

	       use Inline C => 'below';

	   You can omit	the "__DATA__" tag now.	Inline::Files is a source
	   filter that will remove these sections from your program before
	   Perl	compiles it. They are then available for Inline	to make	use
	   of. And since this can all be done at compile time, you don't have
	   to worry about the caveats of the 'DATA' keyword.

	   This	module has a couple small gotchas. Since Inline::Files only
	   recognizes file markers with	capital	letters, you must specify the
	   capital form	of your	language name. Also, there is a	startup	time
	   penalty for using a source code filter.

	   At this point Inline::Files is alpha	software and use of it is
	   experimental.  Inline's integration of this module is also
	   fledgling at	the time being.	One of things I	plan to	do with
	   Inline::Files is to get line	number info so when an extension
	   doesn't compile, the	error messages will point to the correct
	   source file and line	number.

	   My best advice is to	use Inline::Files for testing (especially as
	   support for it improves), but use DATA for production and
	   distributed/CPAN code.

       Strings
	       use Inline Java => <<'END';

	       /* Java code goes here ... */
	       END

	       # Perl code goes	here ...

	   You also just specify the source code as a single string. A handy
	   way to write	the string is to use Perl's "here document" style of
	   quoting. This is ok for small functions but can get unwieldy	in the
	   large. On the other hand, the string	variant	probably has the least
	   startup penalty and all functions are bound at compile time.

	   If you wish to put the string into a	scalar variable, please	be
	   aware that the "use"	statement is a compile time directive. As
	   such, all the variables it uses must	also be	set at compile time,
	   "before" the	'use Inline' statement.	 Here is one way to do it:

	       my $code;
	       BEGIN {
		   $code = <<END;

	       /* Java code goes here ... */
	       END
	       }
	       use Inline Java => $code;

	       # Perl code goes	here ...

       The bind() Function
	   An alternative to using the BEGIN block method is to	specify	the
	   source code at run time using the 'Inline->bind()' method. (This is
	   one of the interface	exceptions mentioned above) The	"bind()"
	   method takes	the same arguments as 'use Inline ...'.

	       my $code	= <<END;

	       /* Java code goes here ... */
	       END

	       Inline->bind(Java => $code);

	   You can think of "bind()" as	a way to "eval()" code in other
	   programming languages.

	   Although bind() is a	powerful feature, it is	not recommended	for
	   use in Inline based modules.	In fact, it won't work at all for
	   installable modules.	See instructions below for creating modules
	   with	Inline.

       Other Methods
	   The source code for Inline can also be specified as an external
	   filename, a reference to a subroutine that returns source code, or
	   a reference to an array that	contains lines of source code. (Note
	   that	if the external	source file is in the current directory	it
	   must	be specified with a leading '.'	- ie '.file.ext' instead of
	   simply 'file.ext'.) These methods are less frequently used but may
	   be useful in	some situations.

	   For instance, to load your C++ code from a file named the same as
	   your	perl module with a swapped file	extension, you can use:

	       use Inline CPP => (__FILE__ =~ s/\.pm$/.cpp/r);

       Shorthand
	   If you are using the	'DATA' or 'file' methods described above and
	   there are no	extra parameters, you can omit the keyword altogether.
	   For example:

	       use Inline 'Java';

	       # Perl code goes	here ...

	       __DATA__
	       __Java__
	       /* Java code goes here ... */

	   or

	       use Inline::Files;
	       use Inline 'Java';

	       # Perl code goes	here ...

	       __JAVA__
	       /* Java code goes here ... */

   More	about the DATA Section
       If you are writing a module, you	can also use the DATA section for POD
       and AutoLoader subroutines. Just	be sure	to put them before the first
       Inline marker. If you install the helper	module "Inline::Filters", you
       can even	use POD	inside your Inline code. You just have to specify a
       filter to strip it out.

       You can also specify multiple Inline sections, possibly in different
       programming languages. Here is another example:

	   # The module	Foo.pm
	   package Foo;
	   use AutoLoader;

	   use Inline C;
	   use Inline C	=> DATA	=> filters => 'Strip_POD';
	   use Inline Python;

	   1;

	   __DATA__

	   sub marine {
	       # This is an autoloaded subroutine
	   }

	   =head1 External subroutines

	   =cut

	   __C__
	   /* First C section */

	   __C__
	   /* Second C section */
	   =head1 My C Function

	   Some	POD doc.

	   =cut

	   __Python__
	   """A	Python Section"""

       An important thing to remember is that you need to have one "use	Inline
       Foo => 'DATA'" for each "__Foo__" marker, and they must be in the same
       order.  This allows you to apply	different configuration	options	to
       each section.

   Configuration Options
       Inline tries to do the right thing as often as possible.	But sometimes
       you may need to override	the default actions. This is easy to do.
       Simply list the Inline configuration options after the regular Inline
       parameters. All configuration options are specified as (key, value)
       pairs.

	   use Inline (C => 'DATA',
		       directory => './inline_dir',
		       libs => '-lfoo',
		       inc => '-I/foo/include',
		       prefix => 'XXX_',
		       warnings	=> 0,
		      );

       You can also specify the	configuration options on a separate Inline
       call like this:

	   use Inline (C => Config =>
		       directory => './inline_dir',
		       libs => '-lfoo',
		       inc => '-I/foo/include',
		       prefix => 'XXX_',
		       warnings	=> 0,
		      );
	   use Inline C	=> <<'END_OF_C_CODE';

       The special keyword 'Config' tells Inline that this is a	configuration-
       only call. No source code will be compiled or bound to Perl.

       If you want to specify global configuration options that	don't apply to
       a particular language, just leave the language out of the call. Like
       this:

	   use Inline Config =>	warnings => 0;

       The Config options are inherited	and additive. You can use as many
       Config calls as you want. And you can apply different options to
       different code sections.	When a source code section is passed in,
       Inline will apply whichever options have	been specified up to that
       point. Here is a	complex	configuration example:

	   use Inline (Config =>
		       directory => './inline_dir',
		      );
	   use Inline (C => Config =>
		       libs => '-lglobal',
		      );
	   use Inline (C => 'DATA',	    # First C Section
		       libs => ['-llocal1', '-llocal2'],
		      );
	   use Inline (Config =>
		       warnings	=> 0,
		      );
	   use Inline (Python => 'DATA',    # First Python Section
		       libs => '-lmypython1',
		      );
	   use Inline (C => 'DATA',	    # Second C Section
		       libs => [undef, '-llocal3'],
		      );

       The first "Config" applies to all subsequent calls. The second "Config"
       applies to all subsequent "C" sections (but not "Python"	sections). In
       the first "C" section, the external libraries "global", "local1"	and
       "local2"	are used. (Most	options	allow either string or array ref
       forms, and do the right thing.) The "Python" section does not use the
       "global"	library, but does use the same "DIRECTORY", and	has warnings
       turned off. The second "C" section only uses the	"local3" library.
       That's because a	value of "undef" resets	the additive behavior.

       The "directory" and "warnings" options are generic Inline options. All
       other options are language specific. To find out	what the "C" options
       do, see "Inline::C".

   On and Off
       If a particular config option has value options of 1 and	0, you can use
       the 'enable' and	'disable' modifiers. In	other words, this:

	   use Inline Config =>
		      force_build => 1,
		      clean_after_build	=> 0;

       could be	reworded as:

	   use Inline Config =>
		      enable =>	force_build =>
		      disable => clean_after_build;

   Playing 'with' Others
       Inline has a special configuration syntax that tells it to get more
       configuration options from other	Perl modules. Here is an example:

	   use Inline with => 'Event';

       This tells Inline to load the module "Event.pm" and ask it for
       configuration information. Since	"Event"	has a C	API of its own,	it can
       pass Inline all of the information it needs to be able to use "Event" C
       callbacks seamlessly.

       That means that you don't need to specify the typemaps, shared
       libraries, include files	and other information required to get this to
       work.

       You can specify a single	module or a list of them. Like:

	   use Inline with => qw(Event Foo Bar);

       Currently, modules that works with Inline include "Event", "PDL", and
       those that use "Alien::Build".

       In order	to make	your module work with Inline in	this way, your module
       needs to	provide	a class	method called "Inline" that takes an Inline
       language	as a parameter (e.g. "C"), and returns a reference to a	hash
       with configuration information that is acceptable to the	relevant ILSM.
       For C, see C Configuration Options. E.g.:

	   my $confighashref = Event->Inline('C'); # only supports C in	1.21
	   # hashref contains keys INC,	TYPEMAPS, MYEXTLIB, AUTO_INCLUDE, BOOT

       If your module uses ExtUtils::Depends version 0.400 or higher, your
       module only needs this:

	   package Module;
	   use autouse Module::Install::Files => qw(Inline);

   Inline Shortcuts
       Inline lets you set many	configuration options from the command line.
       These options are called	'shortcuts'. They can be very handy,
       especially when you only	want to	set the	options	temporarily, for say,
       debugging.

       For instance, to	get some general information about your	Inline code in
       the script "Foo.pl", use	the command:

	   perl	-MInline=info Foo.pl

       If you want to force your code to compile, even if its already done,
       use:

	   perl	-MInline=force Foo.pl

       If you want to do both, use:

	   perl	-MInline=info -MInline=force Foo.pl

       or better yet:

	   perl	-MInline=info,force Foo.pl

   The Inline 'directory'
       Inline needs a place to build your code and to install the results of
       the build. It uses a single directory named '.Inline/' under normal
       circumstances. If you create this directory in your home	directory, the
       current directory or in the directory where your	program	resides,
       Inline will find	and use	it. You	can also specify it in the environment
       variable	"PERL_INLINE_DIRECTORY"	or directly in your program, by	using
       the "directory" keyword option. If Inline cannot	find the directory in
       any of these places it will create a '_Inline/' directory in either
       your current directory or the directory where your script resides.

       One of the key factors to using Inline successfully, is understanding
       this directory. When developing code it is usually best to create this
       directory (or let Inline	do it) in your current directory. Remember
       that there is nothing sacred about this directory except	that it	holds
       your compiled code.  Feel free to delete	it at any time.	Inline will
       simply start from scratch and recompile your code on the	next run. If
       you have	several	programs that you want to force	to recompile, just
       delete your '.Inline/' directory.

       It is probably best to have a separate '.Inline/' directory for each
       project that you	are working on.	You may	want to	keep stable code in
       the <.Inline/> in your home directory. On multi-user systems, each user
       should have their own '.Inline/'	directories. It	could be a security
       risk to put the directory in a shared place like	"/tmp/".

   Debugging Inline Errors
       All programmers make mistakes. When you make a mistake with Inline,
       like writing bad	C code,	you'll get a big error report on your screen.
       This report tells you where to look to do the debugging.	Some languages
       may also	dump out the error messages generated from the build.

       When Inline needs to build something it creates a subdirectory under
       your "DIRECTORY/build/" directory. This is where	it writes all the
       components it needs to build your extension. Things like	XS files,
       Makefiles and output log	files.

       If everything goes OK, Inline will delete this subdirectory. If there
       is an error, Inline will	leave the directory intact and print its
       location.  The idea is that you are supposed to go into that directory
       and figure out what happened.

       Read the	doc for	your particular	Inline Language	Support	Module for
       more information.

   The 'config'	Registry File
       Inline keeps a cached file of all of the	Inline Language	Support
       Module's	meta data in a file called "config". This file can be found in
       your "directory"	directory. If the file does not	exist, Inline creates
       a new one. It will search your system for any module beginning with
       "Inline::". It will then	call that module's "register()"	method to get
       useful information for future invocations.

       Whenever	you add	a new ILSM, you	should delete this file	so that	Inline
       will auto-discover your newly installed language	module.	(This should
       no longer be necessary as of Inline-0.49.)

CONFIGURATION OPTIONS
       This section lists all of the generic Inline configuration options. For
       language	specific configuration,	see the	doc for	that language.

       "directory"
	   The "directory" config option is the	directory that Inline uses to
	   both	build and install an extension.

	   Normally Inline will	search in a bunch of known places for a
	   directory called '.Inline/'.	Failing	that, it will create a
	   directory called '_Inline/'

	   If you want to specify your own directory, use this configuration
	   option.

	   Note	that you must create the "directory" directory yourself.
	   Inline will not do it for you.

       "name"
	   You can use this option to set the name of your Inline extension
	   object module. For example:

	       use Inline C => 'DATA',
			  name => 'Foo::Bar';

	   would cause your C code to be compiled in to	the object:

	       lib/auto/Foo/Bar/Bar.so
	       lib/auto/Foo/Bar/Bar.inl

	   (The	.inl component contains	dependency information to make sure
	   the source code is in sync with the executable)

	   If you don't	use "name", Inline will	pick a name for	you based on
	   your	program	name or	package	name. In this case, Inline will	also
	   enable the "autoname" option	which mangles in a small piece of the
	   MD5 fingerprint into	your object name, to make it unique.

       "autoname"
	   This	option is enabled whenever the "name" parameter	is not
	   specified. To disable it say:

	       use Inline C => 'DATA',
			  disable => 'autoname';

	   "autoname" mangles in enough	of the MD5 fingerprint to make your
	   module name unique. Objects created with "autoname" will never get
	   replaced. That also means they will never get cleaned up
	   automatically.

	   "autoname" is very useful for small throw away scripts. For more
	   serious things, always use the "name" option.

       "version"
	   Specifies the version number	of the Inline extension	object.	It is
	   used	only for modules, and it must match the	global variable
	   $VERSION.  Additionally, this option	should used if (and only if) a
	   module is being set up to be	installed permanently into the Perl
	   sitelib tree	using Inline::MakeMaker	(NOT used by Inline::Module).
	   Inline will croak if	you use	it otherwise.

	   The presence	of the "version" parameter is the official way to let
	   Inline know that your code is an installable/installed module.
	   Inline will never generate an object	in the temporary cache
	   ("_Inline/" directory) if "version" is set. It will also never try
	   to recompile	a module that was installed into someone's Perl	site
	   tree.

	   So the basic	rule is	develop	without	"version", and deliver with
	   "version".

       "with"
	   "with" can also be used as a	configuration option instead of	using
	   the special 'with' syntax. Do this if you want to use different
	   sections of Inline code with	different modules. (Probably a very
	   rare	usage)

	       use Event;
	       use Inline C => DATA => with => 'Event';

	   Modules specified using the config form of "with" will not be
	   automatically required. You must "use" them yourself.

       "using"
	   You can override modules that get used by ILSMs with	the "using"
	   option. This	is typically used to override the default parser for
	   Inline::C, but might	be used	by any ILSM for	any purpose.

	       use Inline config => using => '::Parser::RecDescent';
	       use Inline C => '...';

	   This	would tell Inline::C to	use Inline::C::Parser::RecDescent.

       "global_load"
	   This	option is for compiled languages only. It tells	Inline to tell
	   DynaLoader to load an object	file in	such a way that	its symbols
	   can be dynamically resolved by other	object files. May not work on
	   all platforms. See the "global" shortcut below.

       "untaint"
	   You can use this option whenever you	use Perl's "-T"	switch,	for
	   taint checking. This	option tells Inline to blindly untaint all
	   tainted variables.  (This is	generally considered to	be an
	   appallingly insecure	thing to do, and not to	be recommended - but
	   the option is there for you to use if you want.  Please consider
	   using something other than Inline for scripts that need taint
	   checking.) It also turns on "safemode" by default. See the
	   "untaint" shortcut below. You will see warnings about blindly
	   untainting fields in	both %ENV and Inline objects. If you want to
	   silence these warnings, set the Config option "no_untaint_warn" =>
	   1. There can	be some	problems untainting Inline scripts where older
	   versions of Cwd, such as those that shipped with early versions of
	   perl-5.8 (and earlier), are installed. Updating Cwd will probably
	   solve these problems.

       safemode
	   Perform extra safety	checking, in an	attempt	to thwart malicious
	   code. This option cannot guarantee security,	but it does turn on
	   all the currently implemented checks. (Currently, the only
	   "currently implemented check" is to ensure that the "directory"
	   option has also been	used.)

	   There is a slight startup penalty by	using "safemode". Also,	using
	   "untaint" automatically turns this option on. If you	need your code
	   to start faster under "-T" (taint) checking,	you'll need to turn
	   this	option off manually.  Only do this if you are not worried
	   about security risks. See the "unsafe" shortcut below.

       "force_build"
	   Makes Inline	build (compile)	the source code	every time the program
	   is run.  The	default	is 0. See the "force" shortcut below.

       "build_noisy"
	   Tells ILSMs that they should	dump build messages to the terminal
	   rather than be silent about all the build details.

       "build_timers"
	   Tells ILSMs to print	timing information about how long each build
	   phase took.	Usually	requires "Time::HiRes".

       "clean_after_build"
	   Tells Inline	to clean up the	current	build area if the build	was
	   successful.	Sometimes you want to "disable"	this for debugging.
	   Default is 1. See the "noclean" shortcut below.

       "clean_build_area"
	   Tells Inline	to clean up the	old build areas	within the entire
	   Inline "directory". Default is 0. See the "clean" shortcut below.

       "print_info"
	   Tells Inline	to print various information about the source code.
	   Default is 0.  See the "info" shortcut below.

       "print_version"
	   Tells Inline	to print version info about itself. Default is 0. See
	   the "version" shortcut below.

       "reportbug"
	   Puts	Inline into 'reportbug'	mode, which is what you	want if	you
	   desire to report a bug.

       "rewrite_config_file"
	   Default is 0, but setting "rewrite_config_file => 1"	will mean that
	   the existing	configuration file in the Inline "directory" will be
	   overwritten.	 (This is useful if the	existing config	file is	not up
	   to date as regards supported	languages.)

       "warnings"
	   This	option tells Inline whether to print certain warnings. Default
	   is 1.

INLINE CONFIGURATION SHORTCUTS
       This is a list of all the shortcut configuration	options	currently
       available for Inline. Specify them from the command line	when running
       Inline scripts.

	   perl	-MInline=noclean inline_script.pl

       or

	   perl	-MInline=info,force,noclean inline_script.pl

       You can specify multiple	shortcuts separated by commas. They are	not
       case sensitive. You can also specify shortcuts inside the Inline
       program like this:

	   use Inline 'info', 'force', 'noclean';

       NOTE: If	a 'use Inline' statement is used to set	shortcuts, it can not
       be
	     used for additional purposes.

       "clean"
	   Tells Inline	to remove any build directories	that may be lying
	   around in your build	area. Normally these directories get removed
	   immediately after a successful build. Exceptions are	when the build
	   fails, or when you use the "noclean"	or "reportbug" options.

       "force"
	   Forces the code to be recompiled, even if everything	is up to date.

       "global"
	   Turns on the	"global_load" option.

       "info"
	   This	is a very useful option	when you want to know what's going on
	   under the hood. It tells Inline to print helpful information	to
	   "STDERR". Among the things that get printed is a list of which
	   Inline functions were successfully bound to Perl.

       "noclean"
	   Tells Inline	to leave the build files after compiling.

       "noisy"
	   Use the "build_noisy" option	to print messages during a build.

       "reportbug"
	   Puts	Inline into "reportbug"	mode, which does special processing
	   when	you want to report a bug. "reportbug" also automatically
	   forces a build, and doesn't clean up	afterwards. This is so that
	   you can tar and mail	the build directory to me. "reportbug" will
	   print exact instructions on what to do.  Please read	and follow
	   them	carefully.

	   NOTE: "reportbug" informs you to use	the tar	command. If your
	   system does not
		 have tar, please use the equivalent "zip" command.

       "safe"
	   Turns "safemode" on.	"untaint" will turn this on automatically.
	   While this mode performs extra security checking, it	does not
	   guarantee safety.

       "site_install"
	   This	parameter used to be used for creating installable Inline
	   modules. It has been	removed	from Inline altogether and replaced
	   with	a much simpler and more	powerful mechanism,
	   "Inline::MakeMaker".	See the	section	below on how to	create modules
	   with	Inline.

       "_testing"
	   Used	internally by Ct09parser.t and Ct10callback.t(in the Inline::C
	   test	suite).	Setting	this option with Inline::C will	mean that
	   files named "parser_id" and "void_test" are created in the
	   "./Inline_test" directory, creating that directory if it doesn't
	   already exist. The files (but not the "./Inline_test	directory")
	   are cleaned up by calling "Inline::C::_testing_cleanup()". Also
	   used	by "t/06rewrite_config.t" to trigger a warning.

       "timers"
	   Turn	on "build_timers" to get extra diagnostic info about builds.

       "unsafe"
	   Turns "safemode" off. Use this in combination with "untaint"	for
	   slightly faster startup time	under "-T". Only use this if you are
	   sure	the environment	is safe.

       "untaint"
	   Turn	the "untaint" option on. Used with "-T"	switch.	In terms of
	   secure practices, this is definitely	not a recommended way of
	   dealing with	taint checking,	but it's the only option currently
	   available with Inline. Use it at your own risk.

       "version"
	   Tells Inline	to report its release version.

WRITING	MODULES	WITH INLINE
       The current preferred way to author CPAN	modules	with Inline is to use
       Inline::Module (distributed separately).	Inline ships with
       Inline::MakeMaker, which	helps you set up a Makefile.PL that invokes
       Inline at install time to compile all the code before it	gets
       installed, but the resulting module still depends on Inline and the
       language	support	module like Inline::C. In order	to avoid this
       dependency, what	you really want	to do is convert your distribution to
       plain XS	before uploading it to CPAN. Inline::Module fills that role,
       and also	integrates well	with more modern authoring tools.

       See Inline::Module for details on that approach,	or continue reading
       below for the older Inline::MakeMaker technique.

       Let's say that you wanted to write a module called "Math::Simple".
       Start by	using the following command:

	   h2xs	-PAXn Math::Simple

       This will generate a bunch of files that	form a skeleton	of what	you
       need for	a distributable	module.	(Read the h2xs manpage to find out
       what the	options	do) Next, modify the "Simple.pm" file to look like
       this:

	   package Math::Simple;
	   $VERSION = '1.23';

	   use base 'Exporter';
	   @EXPORT_OK =	qw(add subtract);
	   use strict;

	   use Inline C	=> 'DATA',
		      version => '1.23',
		      name => 'Math::Simple';

	   # The following Inline->init() call is optional - see below for more	info.
	   #Inline->init();

	   1;

	   __DATA__

	   =pod

	   =cut

	   __C__
	   int add(int x, int y) {
	     return x +	y;
	   }

	   int subtract(int x, int y) {
	     return x -	y;
	   }

       The important things to note here are that you must specify a "name"
       and "version" parameter.	The "name" must	match your module's package
       name. The "version" parameter must match	your module's $VERSION
       variable	and they must be considered valid by "version::parse".

       NOTE: These are Inline's	sanity checks to make sure you know what
       you're doing
	     before uploading your code	to CPAN. They insure that once the
       module has
	     been installed on someone's system, the module would not get
	     automatically recompiled for any reason. This makes Inline	based
       modules
	     work in exactly the same manner as	XS based ones.

       Finally,	you need to modify the Makefile.PL. Simply change:

	   use ExtUtils::MakeMaker;

       to

	   use Inline::MakeMaker;

       And, in order that the module build work	correctly in the cpan shell,
       add the following directive to the Makefile.PL's	WriteMakefile():

	   CONFIGURE_REQUIRES  =>  {
	       'Inline::MakeMaker'     => 0.45,
	       'ExtUtils::MakeMaker'   => 6.52,
	   },

       This "CONFIGURE_REQUIRES" directive ensures that	the cpan shell will
       install Inline on the user's machine (if	it's not already present)
       before building your Inline-based module. Specifying of
       "ExtUtils::MakeMaker => 6.52," is optional, and can be omitted if you
       like. It	ensures	only that some harmless	warnings relating to the
       "CONFIGURE_REQUIRES" directive won't be emitted during the building of
       the module. It also means, of course, that ExtUtils::Makemaker will
       first be	updated	on the user's machine unless the user already has
       version 6.52 or later.

       If the "Inline->init();"	is not done then, having installed
       Math::Simple, a warning that "One or more DATA sections were not
       processed by Inline" will appear	when (and only when) Math::Simple is
       loaded by a "require call. It's a harmless warning - and	if you're
       prepared	to live	with it, then there's no need to make the
       "Inline->init();" call.

       When the	person installing "Math::Simple" does a	""make"", the
       generated Makefile will invoke Inline in	such a way that	the C code
       will be compiled	and the	executable code	will be	placed into the
       "./blib"	directory. Then	when a ""make install""	is done, the module
       will be copied into the appropriate Perl	sitelib	directory (which is
       where an	installed module should	go).

       Now all you need	to do is:

	   perl	Makefile.PL
	   make	dist

       That will generate the file "Math-Simple-0.20.tar.gz" which is a
       distributable package. (It will also generate some harmless warnings in
       relation	to "CONFIGURE_REQUIRES"	unless the version of your
       ExtUtils::MakeMaker is 6.52 or later.) That's all there is to it.

       IMPORTANT NOTE: Although	the above steps	will produce a workable
       module, you still have a	few more responsibilities as a budding new
       CPAN author. You	need to	write lots of documentation and	write lots of
       tests. Take a look at some of the better	CPAN modules for ideas on
       creating	a killer test harness.	Actually, don't	listen to me, go read
       these:

       o   perldoc perlnewmod

       o   <http://www.cpan.org/modules/04pause.html>

       o   <http://www.cpan.org/modules/00modlist.long.html>

HOW INLINE WORKS
       In reality, Inline just automates everything you	would need to do if
       you were	going to do it by hand (using XS, etc).

       Inline performs the following steps:

       o   Receive the Source Code

	   Inline gets the source code from your script	or module with a
	   statements like the following:

	       use Inline C => "Source-Code";

	   or

	       use Inline;
	       bind Inline C =>	"Source-Code";

	   where "C" is	the programming	language of the	source code, and
	   "Source- Code" is a string, a file name, an array reference,	or the
	   special 'DATA' keyword.

	   Since Inline	is coded in a ""use"" statement, everything is done
	   during Perl's compile time. If anything needs to be done that will
	   affect the "Source- Code", it needs to be done in a "BEGIN" block
	   that	is before the ""use Inline ..."" statement. If you really need
	   to specify code to Inline at	runtime, you can use the "bind()"
	   method.

	   Source code that is stowed in the 'DATA' section of your code, is
	   read	in by an "INIT"	subroutine in Inline. That's because the
	   "DATA" filehandle is	not available at compile time.

       o   Check if the	Source Code has	been Built

	   Inline only needs to	build the source code if it has	not yet	been
	   built. It accomplishes this seemingly magical task in an extremely
	   simple and straightforward manner. It runs the source text through
	   the "Digest::MD5" module to produce a 128-bit "fingerprint" which
	   is virtually	unique.	The fingerprint	along with a bunch of other
	   contingency information is stored in	a ".inl" file that sits	next
	   to your executable object. For instance, the	"C" code from a	script
	   called "example.pl" might create these files:

	       example_pl_3a9a.so
	       example_pl_3a9a.inl

	   If all the contingency information matches the values stored	in the
	   ".inl" file,	then proceed to	step 8.	(No compilation	is necessary)

       o   Find	a Place	to Build and Install

	   At this point Inline	knows it needs to build	the source code. The
	   first thing to figure out is	where to create	the great big mess
	   associated with compilation,	and where to put the object when it's
	   done.

	   By default Inline will try to build and install under the first
	   place that meets one	of the following conditions:

	   1.  The DIRECTORY= config option; if	specified

	   2.  The "PERL_INLINE_DIRECTORY" environment variable; if set

	   3.  ".Inline/" (in current directory); if exists and	"$PWD !=
	       $HOME"

	   4.  bin.Inline (in directory	of your	script); if exists

	   5.  "~/.Inline/" - if exists

	   6.  "./_Inline/" - if exists

	   7.  "bin/_Inline" - if exists

	   8.  Create "./_Inline/" - if	possible

	   9.  Create "bin/_Inline/" - if possible

	   Failing that, Inline	will croak. This is rare and easily remedied
	   by just making a directory that Inline will use.

	   If the "PERL_INSTALL_ROOT" Environment Variable has been set, you
	   will	need to	make special provision for that	if the 'make install'
	   phase of your Inline	scripts	are to succeed.

	   If the module option	is being compiled for permanent	installation,
	   then	Inline will only use "./_Inline/" to build in, and the
	   $Config{installsitearch} directory to install the executable	in.
	   This	action is caused by Inline::MakeMaker, and is intended to be
	   used	in modules that	are to be distributed on the CPAN, so that
	   they	get installed in the proper place.

       o   Parse the Source for	Semantic Cues

	   Inline::C uses the module "Parse::RecDescent" to parse through your
	   chunks of C source code and look for	things that it can create run-
	   time	bindings to. In	"C" it looks for all of	the function
	   definitions and breaks them down into names and data	types. These
	   elements are	used to	correctly bind the "C" function	to a "Perl"
	   subroutine. Other Inline languages like Python and Java actually
	   use the "python" and	"javac"	modules	to parse the Inline code.

       o   Create the Build Environment

	   Now Inline can take all of the gathered information and create an
	   environment to build	your source code into an executable. Without
	   going into all the details, it just creates the appropriate
	   directories,	creates	the appropriate	source files including an XS
	   file	(for C)	and a "Makefile.PL".

       o   Build the Code and Install the Executable

	   The planets are in alignment. Now for the easy part.	Inline just
	   does	what you would do to install a module. "`perl Makefile.PL &&
	   make	&& make	test &&	make install>".	If something goes awry,	Inline
	   will	croak with a message indicating	where to look for more info.

       o   Tidy	Up

	   By default, Inline will remove all of the mess created by the build
	   process, assuming that everything worked. If	the build fails,
	   Inline will leave everything	intact,	so that	you can	debug your
	   errors. Setting the "noclean" shortcut option will also stop	Inline
	   from	cleaning up.

       o   DynaLoad the	Executable

	   For C (and C++), Inline uses	the "DynaLoader::bootstrap" method to
	   pull	your external module into "Perl" space.	Now you	can call all
	   of your external functions like Perl	subroutines.

	   Other languages like	Python and Java, provide their own loaders.

SEE ALSO
       For information about using Inline with C see Inline::C.

       For sample programs using Inline	with C see Inline::C-Cookbook.

       For "Formerly Answered Questions" about Inline, see Inline-FAQ.

       For information on supported languages and platforms see	Inline-
       Support.

       For information on writing your own Inline Language Support Module, see
       Inline-API.

       Inline's	mailing	list is	inline@perl.org

       To subscribe, send email	to inline-subscribe@perl.org

BUGS AND DEFICIENCIES
       When reporting a	bug, please do the following:

       o   Put "use Inline 'reportbug';" at the	top of your code, or use the
	   command line	option "perl -MInline=reportbug	...".

       o   Run your code.

       o   Follow the printed directions.

AUTHOR
       Ingy dA<paragraph>t Net <ingy@cpan.org>

       Sisyphus	<sisyphus@cpan.org> fixed some bugs and	is current co-
       maintainer.

COPYRIGHT
       o   Copyright 2000-2019.	Ingy dA<paragraph>t Net.

       o   Copyright 2008, 2010-2014. Sisyphus.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       See <http://www.perl.com/perl/misc/Artistic.html>

perl v5.32.1			  2020-01-09			     Inline(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | USING THE INLINE.PM MODULE | CONFIGURATION OPTIONS | INLINE CONFIGURATION SHORTCUTS | WRITING MODULES WITH INLINE | HOW INLINE WORKS | SEE ALSO | BUGS AND DEFICIENCIES | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Inline&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help