source: trunk/essentials/dev-lang/perl/pod/perlembed.pod

=head1 NAME

perlembed - how to embed perl in your C program

=head1 DESCRIPTION

=head2 PREAMBLE

Do you want to:

=over 5

=item B<Use C from Perl?>

Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.

=item B<Use a Unix program from Perl?>

Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.

=item B<Use Perl from Perl?>

Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require> 
and L<perlfunc/use>.

=item B<Use C from C?>

Rethink your design.

=item B<Use Perl from C?>

Read on...

=back

=head2 ROADMAP

=over 5

=item *

Compiling your C program

=item *

Adding a Perl interpreter to your C program

=item *

Calling a Perl subroutine from your C program

=item *

Evaluating a Perl statement from your C program

=item *

Performing Perl pattern matches and substitutions from your C program

=item *

Fiddling with the Perl stack from your C program

=item *

Maintaining a persistent interpreter

=item *

Maintaining multiple interpreter instances

=item *

Using Perl modules, which themselves use C libraries, from your C program

=item *

Embedding Perl under Win32

=back 

=head2 Compiling your C program

If you have trouble compiling the scripts in this documentation,
you're not alone.  The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
THE SAME WAY THAT YOUR PERL WAS COMPILED.  (Sorry for yelling.)

Also, every C program that uses Perl must link in the I<perl library>.
What's that, you ask?  Perl is itself written in C; the perl library
is the collection of compiled C programs that were used to create your
perl executable (I</usr/bin/perl> or equivalent).  (Corollary: you
can't use Perl from your C program unless Perl has been compiled on
your machine, or installed properly--that's why you shouldn't blithely
copy Perl executables from machine to machine without also copying the
I<lib> directory.)

When you use Perl from C, your C program will--usually--allocate,
"run", and deallocate a I<PerlInterpreter> object, which is defined by
the perl library.

If your copy of Perl is recent enough to contain this documentation
(version 5.002 or later), then the perl library (and I<EXTERN.h> and
I<perl.h>, which you'll also need) will reside in a directory
that looks like this:

    /usr/local/lib/perl5/your_architecture_here/CORE

or perhaps just

    /usr/local/lib/perl5/CORE

or maybe something like

    /usr/opt/perl5/CORE

Execute this statement for a hint about where to find CORE:

    perl -MConfig -e 'print $Config{archlib}'

Here's how you'd compile the example in the next section,
L<Adding a Perl interpreter to your C program>, on my Linux box:

    % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
    -I/usr/local/lib/perl5/i586-linux/5.003/CORE
    -L/usr/local/lib/perl5/i586-linux/5.003/CORE
    -o interp interp.c -lperl -lm

(That's all one line.)  On my DEC Alpha running old 5.003_05, the 
incantation is a bit different:

    % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
    -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
    -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
    -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm

How can you figure out what to add?  Assuming your Perl is post-5.001,
execute a C<perl -V> command and pay special attention to the "cc" and
"ccflags" information.

You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what
to use.

You'll also have to choose the appropriate library directory
(I</usr/local/lib/...>) for your machine.  If your compiler complains
that certain functions are undefined, or that it can't locate
I<-lperl>, then you need to change the path following the C<-L>.  If it
complains that it can't find I<EXTERN.h> and I<perl.h>, you need to
change the path following the C<-I>.

You may have to add extra libraries as well.  Which ones?
Perhaps those printed by

   perl -MConfig -e 'print $Config{libs}'

Provided your perl binary was properly configured and installed the
B<ExtUtils::Embed> module will determine all of this information for
you:

   % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
you can retrieve it from
http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/
(If this documentation came from your Perl distribution, then you're
running 5.004 or better and you already have it.)

The B<ExtUtils::Embed> kit on CPAN also contains all source code for
the examples in this document, tests, additional examples and other
information you may find useful.

=head2 Adding a Perl interpreter to your C program

In a sense, perl (the C program) is a good example of embedding Perl
(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
included in the source distribution.  Here's a bastardized, nonportable
version of I<miniperlmain.c> containing the essentials of embedding:

    #include <EXTERN.h>               /* from the Perl distribution     */
    #include <perl.h>                 /* from the Perl distribution     */

    static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/

    int main(int argc, char **argv, char **env)
    {
        PERL_SYS_INIT3(&argc,&argv,&env);
        my_perl = perl_alloc();
        perl_construct(my_perl);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
        perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
        perl_run(my_perl);
        perl_destruct(my_perl);
        perl_free(my_perl);
        PERL_SYS_TERM();
    }

Notice that we don't use the C<env> pointer.  Normally handed to
C<perl_parse> as its final argument, C<env> here is replaced by
C<NULL>, which means that the current environment will be used.  The macros
PERL_SYS_INIT3() and PERL_SYS_TERM() provide system-specific tune up 
of the C runtime environment necessary to run Perl interpreters; since
PERL_SYS_INIT3() may change C<env>, it may be more appropriate to provide
C<env> as an argument to perl_parse().

Now compile this program (I'll call it I<interp.c>) into an executable:

    % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

After a successful compilation, you'll be able to use I<interp> just
like perl itself:

    % interp
    print "Pretty Good Perl \n";
    print "10890 - 9801 is ", 10890 - 9801;
    <CTRL-D>
    Pretty Good Perl
    10890 - 9801 is 1089

or

    % interp -e 'printf("%x", 3735928559)'
    deadbeef

You can also read and execute Perl statements from a file while in the
midst of your C program, by placing the filename in I<argv[1]> before
calling I<perl_run>.

=head2 Calling a Perl subroutine from your C program

To call individual Perl subroutines, you can use any of the B<call_*>
functions documented in L<perlcall>.
In this example we'll use C<call_argv>.

That's shown below, in a program I'll call I<showtime.c>.

    #include <EXTERN.h>
    #include <perl.h>

    static PerlInterpreter *my_perl;

    int main(int argc, char **argv, char **env)
    {
        char *args[] = { NULL };
        PERL_SYS_INIT3(&argc,&argv,&env);
        my_perl = perl_alloc();
        perl_construct(my_perl);

        perl_parse(my_perl, NULL, argc, argv, NULL);
        PL_exit_flags |= PERL_EXIT_DESTRUCT_END;

        /*** skipping perl_run() ***/

        call_argv("showtime", G_DISCARD | G_NOARGS, args);

        perl_destruct(my_perl);
        perl_free(my_perl);
        PERL_SYS_TERM();
    }

where I<showtime> is a Perl subroutine that takes no arguments (that's the
I<G_NOARGS>) and for which I'll ignore the return value (that's the
I<G_DISCARD>).  Those flags, and others, are discussed in L<perlcall>.

I'll define the I<showtime> subroutine in a file called I<showtime.pl>:

    print "I shan't be printed.";

    sub showtime {
        print time;
    }

Simple enough.  Now compile and run:

    % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`

    % showtime showtime.pl
    818284590

yielding the number of seconds that elapsed between January 1, 1970
(the beginning of the Unix epoch), and the moment I began writing this
sentence.

In this particular case we don't have to call I<perl_run>, as we set 
the PL_exit_flag PERL_EXIT_DESTRUCT_END which executes END blocks in
perl_destruct.

If you want to pass arguments to the Perl subroutine, you can add
strings to the C<NULL>-terminated C<args> list passed to
I<call_argv>.  For other data types, or to examine return values,
you'll need to manipulate the Perl stack.  That's demonstrated in
L<Fiddling with the Perl stack from your C program>.

=head2 Evaluating a Perl statement from your C program

Perl provides two API functions to evaluate pieces of Perl code.
These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.

Arguably, these are the only routines you'll ever need to execute
snippets of Perl code from within your C program.  Your code can be as
long as you wish; it can contain multiple statements; it can employ
L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
include external Perl files.

I<eval_pv> lets us evaluate individual Perl strings, and then
extract variables for coercion into C types.  The following program,
I<string.c>, executes three Perl strings, extracting an C<int> from
the first, a C<float> from the second, and a C<char *> from the third.

   #include <EXTERN.h>
   #include <perl.h>

   static PerlInterpreter *my_perl;

   main (int argc, char **argv, char **env)
   {
       STRLEN n_a;
       char *embedding[] = { "", "-e", "0" };

       PERL_SYS_INIT3(&argc,&argv,&env);
       my_perl = perl_alloc();
       perl_construct( my_perl );

       perl_parse(my_perl, NULL, 3, embedding, NULL);
       PL_exit_flags |= PERL_EXIT_DESTRUCT_END;
       perl_run(my_perl);

       /** Treat $a as an integer **/
       eval_pv("$a = 3; $a **= 2", TRUE);
       printf("a = %d\n", SvIV(get_sv("a", FALSE)));

       /** Treat $a as a float **/
       eval_pv("$a = 3.14; $a **= 2", TRUE);
       printf("a = %f\n", SvNV(get_sv("a", FALSE)));

       /** Treat $a as a string **/
       eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
       printf("a = %s\n", SvPV(get_sv("a", FALSE), n_a));

       perl_destruct(my_perl);
       perl_free(my_perl);
       PERL_SYS_TERM();
   }

All of those strange functions with I<sv> in their names help convert Perl scalars to C types.  They're described in L<perlguts> and L<perlapi>.

If you compile and run I<string.c>, you'll see the results of using
I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
I<SvPV()> to create a string:

   a = 9
   a = 9.859600
   a = Just Another Perl Hacker

In the example above, we've created a global variable to temporarily
store the computed value of our eval'd expression.  It is also
possible and in most cases a better strategy to fetch the return value
from I<eval_pv()> instead.  Example:

   ...
   STRLEN n_a;
   SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
   printf("%s\n", SvPV(val,n_a));
   ...

This way, we avoid namespace pollution by not creating global
variables and we've simplified our code as well.

=head2 Performing Perl pattern matches and substitutions from your C program

The I<eval_sv()> function lets us evaluate strings of Perl code, so we can
define some functions that use it to "specialize" in matches and
substitutions: I<match()>, I<substitute()>, and I<matches()>.

   I32 match(SV *string, char *pattern);

Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
in your C program might appear as "/\\b\\w*\\b/"), match()
returns 1 if the string matches the pattern and 0 otherwise.

   int substitute(SV **string, char *pattern);

Given a pointer to an C<SV> and an C<=~> operation (e.g.,
C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
within the C<SV> as according to the operation, returning the number of substitutions
made.

   int matches(SV *string, char *pattern, AV **matches);

Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
matches() evaluates C<$string =~ $pattern> in a list context, and
fills in I<matches> with the array elements, returning the number of matches found.

Here's a sample program, I<match.c>, that uses all three (long lines have
been wrapped here):

 #include <EXTERN.h>
 #include <perl.h>

 static PerlInterpreter *my_perl;

 /** my_eval_sv(code, error_check)
 ** kinda like eval_sv(), 
 ** but we pop the return value off the stack 
 **/
 SV* my_eval_sv(SV *sv, I32 croak_on_error)
 {
     dSP;
     SV* retval;
     STRLEN n_a;

     PUSHMARK(SP);
     eval_sv(sv, G_SCALAR);

     SPAGAIN;
     retval = POPs;
     PUTBACK;

     if (croak_on_error && SvTRUE(ERRSV))
        croak(SvPVx(ERRSV, n_a));

     return retval;
 }

 /** match(string, pattern)
 **
 ** Used for matches in a scalar context.
 **
 ** Returns 1 if the match was successful; 0 otherwise.
 **/

 I32 match(SV *string, char *pattern)
 {
     SV *command = NEWSV(1099, 0), *retval;
     STRLEN n_a;

     sv_setpvf(command, "my $string = '%s'; $string =~ %s",
              SvPV(string,n_a), pattern);

     retval = my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     return SvIV(retval);
 }

 /** substitute(string, pattern)
 **
 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
 **
 ** Returns the number of successful matches, and
 ** modifies the input string if there were any.
 **/

 I32 substitute(SV **string, char *pattern)
 {
     SV *command = NEWSV(1099, 0), *retval;
     STRLEN n_a;

     sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
              SvPV(*string,n_a), pattern);

     retval = my_eval_sv(command, TRUE);
     SvREFCNT_dec(command);

     *string = get_sv("string", FALSE);
     return SvIV(retval);
 }