CPR(3)							User Contributed Perl Documentation						    CPR(3)

NAME

       Inline::CPR - C Perl Run. Embed Perl in C, ala Inline

SYNOPSIS

	   #!/usr/local/bin/cpr

	   int main(void) {

	       printf("Hello World, I'm running under Perl version %s
",
		      CPR_eval("use Config; $Config{version}")
		     );

	       return 0;
	   }

DESCRIPTION

       Is it C? Is it Perl? It's neither, it's both. It's CPR!

       CPR (C Perl Run) is a "new language" that looks like C. You don't need to compile it. You just run it, much like Perl. As an added bonus,
       you'll get access to the full internals of Perl via the CPR API.

       The idea is that you just put a CPR hashbang at the top of your C program and run it like a script. The CPR interpreter will run your C
       code under Perl.

       If your 'hash' doesn't 'bang', you can run your program like this:

	   cpr synopsis.cpr

How does it work?
       To understand CPR, you need to understand the Perl module, "Inline.pm". Inline lets you write Perl subroutines in other languages, like C.
       CPR is a natural extension of this.

       The CPR interpreter ("/usr/local/bin/cpr") is a small binary program which performs a bootstrap process that goes like this:

       - The "cpr" interpreter "exec"s "perl" and tells it to run the script "/usr/local/bin/cpr.pl".

       - The name of your CPR program is passed to "cpr.pl".

       - "cpr.pl" loads your CPR source code and uses "Inline::CPR" to compile it and bind your "main()" function to Perl.

       - Then "cpr.pl" simply invokes the "main()" function and you're off and running.

Notes on Usage
       1.  The CPR tools will get installed in the same directory as the "perl" binary on your system. (I just used "/usr/local/bin/" as an
	   example)

       2.  If you installed "Inline::CPR" by hand, the "make" command will have created the file './examples/synopsis.cpr'. This is a sample CPR
	   program that you can try running. It's the same as the SYNOPSIS example above, except that the hashbang will point to your newly
	   installed CPR interpreter.

       3.  Although Inline::CPR is a module, it is only used to support the "cpr" interpreter program. You don't ever actually "use" it in a Perl
	   script.

       4.  You must have a "main()" function in your CPR program. This is what "cpr" binds to.

       5.  The "cpr" interpreter internally changes your function "main()" to "cpr_main()". Otherwise it would conflict with Perl's "main()"
	   function.

       6.  The first time you run a CPR program it will seem to "hang" for several seconds. This is normal. The C code is being compiled.
	   Experienced Inline users will be familiar with this. (Since your compiled code is cached to disk, subsequent runs will be fast)

       7.  CPR builds and caches your compiled CPR code in the directory './.cpr/'.

       8.  CPR will return (to the system) whatever integer value your "main()" function returns.

       9.  You don't need to "#include" most of the standard header files. These are automatically included by Inline::CPR.

       10. CPR will work with Perl 5.005 and higher. The CPR API will be made to work with those versions. (Maybe even with Perl6)

The CPR API
       The CPR API is just a set of C macros that you can use to access the internals of Perl5. You can also use the Perl5 API. See "perldoc
       perlapi".

       The main focus of CPR will be to develop a wrapper API around the current Perl5 one. It will be more consistent, flexible and easy to use.

       Since it should be well thought out, I have currently only implemented one function: CPR_eval. But you should be able to do quite a bit
       with just that one.

   CPR_eval()
       Eval a string (char*) in Perl and return the result as a string.

	   const char* CPR_eval(char*);

Why?
       Several reasons, (none great).

       1.  It's a cute Perl trick. After explaining CPR to an uninitiated friend, he said "My head feels like it's been wrapped around a brick".
	   That should be reason enough :)

       2.  A dead simple way to embed Perl into C. You're not really embedding Perl into C. Your C is being embedded seamlessly into Perl. But
	   since you never see the Perl, you can just think of it the first way.

       3.  A mechanism for designing a new Perl5 API. The current one is very adhoc. Some macros come from XS and others from the P5P. There's a
	   lot of room for improvement. Also, with Perl6 looming, finding a wrapper API for Perl5 that might possibly be upwards compatible, is at
	   least worth considering.

       4.  Inline::CPR is a good example of how a CPAN module can be used to build and install a binary program. It is interesting to note that
	   the C program "cpr.c" is actually generated by the Perl script "cpr.plc" at "make" time.

       Even if there is no "real world" use for the CPR language, it is at least an easy-to-use tool for playing around with the internals of
       Perl5. The more "regular people" there are playing in the guts, the more useful we'll be for helping improve our language.

LIMITATIONS

       1.  CPR only binds to a "main()" function with a signature of:

	       int main(void);

	   It will not yet bind to:

	       int main(int argc, char* argv[]);

	   and friends.

       2.  There is currently no way to specify configuration options. This will be added soon. Then you'll be able to link in shared libraries
	   and such.

       3.  Does not yet support MSWin32.

MAILING LIST

       The mailing list for "Inline.pm" and related projects is: inline@perl.org

       To subscribe, send a message to inline-subscribe@perl.org

AUTHOR

       Brian Ingerson <INGY@cpan.org>

COPYRIGHT

       Copyright (c) 2001, Brian Ingerson. All Rights Reserved.

       This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License.

       (see http://www.perl.com/perl/misc/Artistic.html)

perl v5.12.1							    2001-06-10								    CPR(3)