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\n",
               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 execs 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

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)
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.
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.
You must have a main() function in your CPR program. This is what cpr binds to.
The cpr interpreter internally changes your function main() to cpr_main(). Otherwise it would conflict with Perl's main() function.
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)
CPR builds and caches your compiled CPR code in the directory './.cpr/'.
CPR will return (to the system) whatever integer value your main() function returns.
You don't need to #include most of the standard header files. These are automatically included by Inline::CPR.
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).

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 :)
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.
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.
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

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.
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.
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

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)

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