This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
support for list assignment to pseudohashes (from John Tobey
[perl5.git] / pod / perlembed.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
cb1a09d0 3perlembed - how to embed perl in your C program
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
cb1a09d0
AD
7=head2 PREAMBLE
8
9Do you want to:
10
11=over 5
12
96dbc785 13=item B<Use C from Perl?>
cb1a09d0 14
4929bf7b 15Read L<perlxstut>, L<perlxs>, L<h2xs>, L<perlguts>, and L<perlapi>.
cb1a09d0 16
54310121 17=item B<Use a Unix program from Perl?>
cb1a09d0 18
5f05dabc 19Read about back-quotes and about C<system> and C<exec> in L<perlfunc>.
cb1a09d0 20
96dbc785 21=item B<Use Perl from Perl?>
cb1a09d0 22
e010571f
GS
23Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
24and L<perlfunc/use>.
cb1a09d0 25
96dbc785 26=item B<Use C from C?>
cb1a09d0
AD
27
28Rethink your design.
29
96dbc785 30=item B<Use Perl from C?>
cb1a09d0
AD
31
32Read on...
33
34=back
35
36=head2 ROADMAP
37
707102d0
GS
38=over 5
39
e010571f 40L<Compiling your C program>
cb1a09d0 41
e010571f 42L<Adding a Perl interpreter to your C program>
cb1a09d0 43
e010571f 44L<Calling a Perl subroutine from your C program>
cb1a09d0 45
e010571f 46L<Evaluating a Perl statement from your C program>
cb1a09d0 47
e010571f 48L<Performing Perl pattern matches and substitutions from your C program>
cb1a09d0 49
e010571f 50L<Fiddling with the Perl stack from your C program>
cb1a09d0 51
e010571f 52L<Maintaining a persistent interpreter>
cb1a09d0 53
e010571f 54L<Maintaining multiple interpreter instances>
a6006777 55
e010571f 56L<Using Perl modules, which themselves use C libraries, from your C program>
8ebc5c01 57
e010571f 58L<Embedding Perl under Win32>
96dbc785 59
e010571f 60=back
cb1a09d0
AD
61
62=head2 Compiling your C program
63
8a7dc658
JO
64If you have trouble compiling the scripts in this documentation,
65you're not alone. The cardinal rule: COMPILE THE PROGRAMS IN EXACTLY
66THE SAME WAY THAT YOUR PERL WAS COMPILED. (Sorry for yelling.)
cb1a09d0 67
8a7dc658 68Also, every C program that uses Perl must link in the I<perl library>.
cb1a09d0
AD
69What's that, you ask? Perl is itself written in C; the perl library
70is the collection of compiled C programs that were used to create your
71perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
72can't use Perl from your C program unless Perl has been compiled on
73your machine, or installed properly--that's why you shouldn't blithely
74copy Perl executables from machine to machine without also copying the
75I<lib> directory.)
76
8a7dc658
JO
77When you use Perl from C, your C program will--usually--allocate,
78"run", and deallocate a I<PerlInterpreter> object, which is defined by
79the perl library.
cb1a09d0
AD
80
81If your copy of Perl is recent enough to contain this documentation
a6006777 82(version 5.002 or later), then the perl library (and I<EXTERN.h> and
8a7dc658
JO
83I<perl.h>, which you'll also need) will reside in a directory
84that looks like this:
cb1a09d0
AD
85
86 /usr/local/lib/perl5/your_architecture_here/CORE
87
88or perhaps just
89
90 /usr/local/lib/perl5/CORE
91
92or maybe something like
93
94 /usr/opt/perl5/CORE
95
96Execute this statement for a hint about where to find CORE:
97
96dbc785 98 perl -MConfig -e 'print $Config{archlib}'
cb1a09d0 99
54310121 100Here's how you'd compile the example in the next section,
e010571f 101L<Adding a Perl interpreter to your C program>, on my Linux box:
cb1a09d0 102
54310121 103 % gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
8a7dc658 104 -I/usr/local/lib/perl5/i586-linux/5.003/CORE
54310121 105 -L/usr/local/lib/perl5/i586-linux/5.003/CORE
8a7dc658 106 -o interp interp.c -lperl -lm
cb1a09d0 107
e010571f
GS
108(That's all one line.) On my DEC Alpha running old 5.003_05, the
109incantation is a bit different:
8a7dc658 110
54310121
PP
111 % cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
112 -I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
113 -L/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE -L/usr/local/lib
8a7dc658
JO
114 -D__LANGUAGE_C__ -D_NO_PROTO -o interp interp.c -lperl -lm
115
116How can you figure out what to add? Assuming your Perl is post-5.001,
117execute a C<perl -V> command and pay special attention to the "cc" and
54310121 118"ccflags" information.
8a7dc658 119
54310121 120You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) for
8a7dc658 121your machine: C<perl -MConfig -e 'print $Config{cc}'> will tell you what
54310121 122to use.
8a7dc658
JO
123
124You'll also have to choose the appropriate library directory
125(I</usr/local/lib/...>) for your machine. If your compiler complains
126that certain functions are undefined, or that it can't locate
127I<-lperl>, then you need to change the path following the C<-L>. If it
128complains that it can't find I<EXTERN.h> and I<perl.h>, you need to
129change the path following the C<-I>.
cb1a09d0
AD
130
131You may have to add extra libraries as well. Which ones?
96dbc785
PP
132Perhaps those printed by
133
134 perl -MConfig -e 'print $Config{libs}'
135
54310121 136Provided your perl binary was properly configured and installed the
8a7dc658
JO
137B<ExtUtils::Embed> module will determine all of this information for
138you:
96dbc785
PP
139
140 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
141
8a7dc658
JO
142If the B<ExtUtils::Embed> module isn't part of your Perl distribution,
143you can retrieve it from
be94a901 144http://www.perl.com/perl/CPAN/modules/by-module/ExtUtils/. (If
8a7dc658
JO
145this documentation came from your Perl distribution, then you're
146running 5.004 or better and you already have it.)
96dbc785 147
8a7dc658 148The B<ExtUtils::Embed> kit on CPAN also contains all source code for
54310121 149the examples in this document, tests, additional examples and other
8a7dc658 150information you may find useful.
cb1a09d0
AD
151
152=head2 Adding a Perl interpreter to your C program
153
154In a sense, perl (the C program) is a good example of embedding Perl
155(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
e010571f 156included in the source distribution. Here's a bastardized, nonportable
8a7dc658 157version of I<miniperlmain.c> containing the essentials of embedding:
cb1a09d0 158
cb1a09d0
AD
159 #include <EXTERN.h> /* from the Perl distribution */
160 #include <perl.h> /* from the Perl distribution */
96dbc785 161
cb1a09d0 162 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
96dbc785 163
c07a80fd 164 int main(int argc, char **argv, char **env)
cb1a09d0
AD
165 {
166 my_perl = perl_alloc();
167 perl_construct(my_perl);
96dbc785 168 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
cb1a09d0
AD
169 perl_run(my_perl);
170 perl_destruct(my_perl);
171 perl_free(my_perl);
172 }
173
8a7dc658
JO
174Notice that we don't use the C<env> pointer. Normally handed to
175C<perl_parse> as its final argument, C<env> here is replaced by
176C<NULL>, which means that the current environment will be used.
96dbc785 177
cb1a09d0
AD
178Now compile this program (I'll call it I<interp.c>) into an executable:
179
96dbc785 180 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
cb1a09d0
AD
181
182After a successful compilation, you'll be able to use I<interp> just
183like perl itself:
184
185 % interp
186 print "Pretty Good Perl \n";
187 print "10890 - 9801 is ", 10890 - 9801;
188 <CTRL-D>
189 Pretty Good Perl
190 10890 - 9801 is 1089
191
192or
193
194 % interp -e 'printf("%x", 3735928559)'
195 deadbeef
196
197You can also read and execute Perl statements from a file while in the
198midst of your C program, by placing the filename in I<argv[1]> before
e010571f 199calling I<perl_run>.
cb1a09d0
AD
200
201=head2 Calling a Perl subroutine from your C program
202
4929bf7b 203To call individual Perl subroutines, you can use any of the B<call_*>
7b8d334a 204functions documented in L<perlcall>.
4929bf7b 205In this example we'll use C<call_argv>.
cb1a09d0
AD
206
207That's shown below, in a program I'll call I<showtime.c>.
208
cb1a09d0 209 #include <EXTERN.h>
96dbc785
PP
210 #include <perl.h>
211
212 static PerlInterpreter *my_perl;
213
c07a80fd 214 int main(int argc, char **argv, char **env)
cb1a09d0 215 {
8ebc5c01 216 char *args[] = { NULL };
cb1a09d0
AD
217 my_perl = perl_alloc();
218 perl_construct(my_perl);
96dbc785
PP
219
220 perl_parse(my_perl, NULL, argc, argv, NULL);
221
8ebc5c01
PP
222 /*** skipping perl_run() ***/
223
4929bf7b 224 call_argv("showtime", G_DISCARD | G_NOARGS, args);
8ebc5c01 225
cb1a09d0
AD
226 perl_destruct(my_perl);
227 perl_free(my_perl);
228 }
229
230where I<showtime> is a Perl subroutine that takes no arguments (that's the
96dbc785 231I<G_NOARGS>) and for which I'll ignore the return value (that's the
cb1a09d0
AD
232I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
233
234I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
235
236 print "I shan't be printed.";
96dbc785 237
cb1a09d0
AD
238 sub showtime {
239 print time;
240 }
241
242Simple enough. Now compile and run:
243
96dbc785
PP
244 % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
245
cb1a09d0
AD
246 % showtime showtime.pl
247 818284590
248
249yielding the number of seconds that elapsed between January 1, 1970
8a7dc658 250(the beginning of the Unix epoch), and the moment I began writing this
cb1a09d0
AD
251sentence.
252
8a7dc658
JO
253In this particular case we don't have to call I<perl_run>, but in
254general it's considered good practice to ensure proper initialization
255of library code, including execution of all object C<DESTROY> methods
256and package C<END {}> blocks.
8ebc5c01 257
8a7dc658
JO
258If you want to pass arguments to the Perl subroutine, you can add
259strings to the C<NULL>-terminated C<args> list passed to
4929bf7b 260I<call_argv>. For other data types, or to examine return values,
8a7dc658 261you'll need to manipulate the Perl stack. That's demonstrated in the
e010571f
GS
262last section of this document: L<Fiddling with the Perl stack from
263your C program>.
cb1a09d0
AD
264
265=head2 Evaluating a Perl statement from your C program
266
137443ea 267Perl provides two API functions to evaluate pieces of Perl code.
4929bf7b 268These are L<perlapi/eval_sv> and L<perlapi/eval_pv>.
137443ea
PP
269
270Arguably, these are the only routines you'll ever need to execute
e010571f
GS
271snippets of Perl code from within your C program. Your code can be as
272long as you wish; it can contain multiple statements; it can employ
273L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
274include external Perl files.
cb1a09d0 275
4929bf7b 276I<eval_pv> lets us evaluate individual Perl strings, and then
96dbc785 277extract variables for coercion into C types. The following program,
cb1a09d0
AD
278I<string.c>, executes three Perl strings, extracting an C<int> from
279the first, a C<float> from the second, and a C<char *> from the third.
280
cb1a09d0
AD
281 #include <EXTERN.h>
282 #include <perl.h>
137443ea 283
cb1a09d0 284 static PerlInterpreter *my_perl;
137443ea 285
c07a80fd 286 main (int argc, char **argv, char **env)
cb1a09d0 287 {
2d8e6c8d 288 STRLEN n_a;
137443ea
PP
289 char *embedding[] = { "", "-e", "0" };
290
291 my_perl = perl_alloc();
292 perl_construct( my_perl );
293
294 perl_parse(my_perl, NULL, 3, embedding, NULL);
295 perl_run(my_perl);
296
297 /** Treat $a as an integer **/
4929bf7b
GS
298 eval_pv("$a = 3; $a **= 2", TRUE);
299 printf("a = %d\n", SvIV(get_sv("a", FALSE)));
137443ea
PP
300
301 /** Treat $a as a float **/
4929bf7b
GS
302 eval_pv("$a = 3.14; $a **= 2", TRUE);
303 printf("a = %f\n", SvNV(get_sv("a", FALSE)));
137443ea
PP
304
305 /** Treat $a as a string **/
4929bf7b
GS
306 eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE);
307 printf("a = %s\n", SvPV(get_sv("a", FALSE), n_a));
137443ea
PP
308
309 perl_destruct(my_perl);
310 perl_free(my_perl);
cb1a09d0
AD
311 }
312
4929bf7b 313All 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>.
cb1a09d0
AD
314
315If you compile and run I<string.c>, you'll see the results of using
316I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
317I<SvPV()> to create a string:
318
319 a = 9
320 a = 9.859600
321 a = Just Another Perl Hacker
322
8f183262
DM
323In the example above, we've created a global variable to temporarily
324store the computed value of our eval'd expression. It is also
325possible and in most cases a better strategy to fetch the return value
4929bf7b 326from I<eval_pv()> instead. Example:
8f183262 327
8f183262 328 ...
2d8e6c8d 329 STRLEN n_a;
4929bf7b 330 SV *val = eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
2d8e6c8d 331 printf("%s\n", SvPV(val,n_a));
8f183262
DM
332 ...
333
334This way, we avoid namespace pollution by not creating global
335variables and we've simplified our code as well.
cb1a09d0
AD
336
337=head2 Performing Perl pattern matches and substitutions from your C program
338
4929bf7b 339The I<eval_sv()> function lets us evaluate strings of Perl code, so we can
cb1a09d0
AD
340define some functions that use it to "specialize" in matches and
341substitutions: I<match()>, I<substitute()>, and I<matches()>.
342
e010571f 343 I32 match(SV *string, char *pattern);
cb1a09d0 344
8a7dc658
JO
345Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
346in your C program might appear as "/\\b\\w*\\b/"), match()
cb1a09d0
AD
347returns 1 if the string matches the pattern and 0 otherwise.
348
1f05cdcd 349 int substitute(SV **string, char *pattern);
cb1a09d0 350
1f05cdcd 351Given a pointer to an C<SV> and an C<=~> operation (e.g.,
8a7dc658 352C<s/bob/robert/g> or C<tr[A-Z][a-z]>), substitute() modifies the string
1f05cdcd 353within the C<AV> at according to the operation, returning the number of substitutions
8a7dc658 354made.
cb1a09d0 355
1f05cdcd 356 int matches(SV *string, char *pattern, AV **matches);
cb1a09d0 357
1f05cdcd 358Given an C<SV>, a pattern, and a pointer to an empty C<AV>,
8a7dc658 359matches() evaluates C<$string =~ $pattern> in an array context, and
1f05cdcd 360fills in I<matches> with the array elements, returning the number of matches found.
cb1a09d0 361
96dbc785
PP
362Here's a sample program, I<match.c>, that uses all three (long lines have
363been wrapped here):
cb1a09d0 364
1f05cdcd
DM
365 #include <EXTERN.h>
366 #include <perl.h>
367
4929bf7b
GS
368 /** my_eval_sv(code, error_check)
369 ** kinda like eval_sv(),
1f05cdcd
DM
370 ** but we pop the return value off the stack
371 **/
4929bf7b 372 SV* my_eval_sv(SV *sv, I32 croak_on_error)
1f05cdcd
DM
373 {
374 dSP;
375 SV* retval;
2d8e6c8d 376 STRLEN n_a;
1f05cdcd 377
924508f0 378 PUSHMARK(SP);
4929bf7b 379 eval_sv(sv, G_SCALAR);
1f05cdcd
DM
380
381 SPAGAIN;
382 retval = POPs;
383 PUTBACK;
384
9cde0e7f 385 if (croak_on_error && SvTRUE(ERRSV))
2d8e6c8d 386 croak(SvPVx(ERRSV, n_a));
1f05cdcd
DM
387
388 return retval;
389 }
390
391 /** match(string, pattern)
392 **
393 ** Used for matches in a scalar context.
394 **
395 ** Returns 1 if the match was successful; 0 otherwise.
396 **/
397
398 I32 match(SV *string, char *pattern)
399 {
8c52afec 400 SV *command = NEWSV(1099, 0), *retval;
2d8e6c8d 401 STRLEN n_a;
1f05cdcd
DM
402
403 sv_setpvf(command, "my $string = '%s'; $string =~ %s",
2d8e6c8d 404 SvPV(string,n_a), pattern);
1f05cdcd 405
4929bf7b 406 retval = my_eval_sv(command, TRUE);
1f05cdcd
DM
407 SvREFCNT_dec(command);
408
409 return SvIV(retval);
410 }
411
412 /** substitute(string, pattern)
413 **
414 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
415 **
416 ** Returns the number of successful matches, and
417 ** modifies the input string if there were any.
418 **/
419
420 I32 substitute(SV **string, char *pattern)
421 {
8c52afec 422 SV *command = NEWSV(1099, 0), *retval;
2d8e6c8d 423 STRLEN n_a;
1f05cdcd
DM
424
425 sv_setpvf(command, "$string = '%s'; ($string =~ %s)",
2d8e6c8d 426 SvPV(*string,n_a), pattern);
1f05cdcd 427
4929bf7b 428 retval = my_eval_sv(command, TRUE);
1f05cdcd
DM
429 SvREFCNT_dec(command);
430
4929bf7b 431 *string = get_sv("string", FALSE);
1f05cdcd
DM
432 return SvIV(retval);
433 }
434
435 /** matches(string, pattern, matches)
436 **
437 ** Used for matches in an array context.
438 **
439 ** Returns the number of matches,
440 ** and fills in **matches with the matching substrings
441 **/
442
443 I32 matches(SV *string, char *pattern, AV **match_list)
444 {
8c52afec 445 SV *command = NEWSV(1099, 0);
cb1a09d0 446 I32 num_matches;
2d8e6c8d 447 STRLEN n_a;
1f05cdcd
DM
448
449 sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)",
2d8e6c8d 450 SvPV(string,n_a), pattern);
1f05cdcd 451
4929bf7b 452 my_eval_sv(command, TRUE);
1f05cdcd
DM
453 SvREFCNT_dec(command);
454
4929bf7b 455 *match_list = get_av("array", FALSE);
1f05cdcd
DM
456 num_matches = av_len(*match_list) + 1; /** assume $[ is 0 **/
457
cb1a09d0 458 return num_matches;
1f05cdcd
DM
459 }
460
461 main (int argc, char **argv, char **env)
462 {
463 PerlInterpreter *my_perl = perl_alloc();
a6006777 464 char *embedding[] = { "", "-e", "0" };
1f05cdcd
DM
465 AV *match_list;
466 I32 num_matches, i;
8c52afec 467 SV *text = NEWSV(1099,0);
2d8e6c8d 468 STRLEN n_a;
1f05cdcd
DM
469
470 perl_construct(my_perl);
96dbc785 471 perl_parse(my_perl, NULL, 3, embedding, NULL);
1f05cdcd
DM
472
473 sv_setpv(text, "When he is at a convenience store and the bill comes to some amount like 76 cents, Maynard is aware that there is something he *should* do, something that will enable him to get back a quarter, but he has no idea *what*. He fumbles through his red squeezey changepurse and gives the boy three extra pennies with his dollar, hoping that he might luck into the correct amount. The boy gives him back two of his own pennies and then the big shiny quarter that is his prize. -RICHH");
474
96dbc785 475 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
1f05cdcd 476 printf("match: Text contains the word 'quarter'.\n\n");
96dbc785 477 else
1f05cdcd
DM
478 printf("match: Text doesn't contain the word 'quarter'.\n\n");
479
96dbc785 480 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
1f05cdcd 481 printf("match: Text contains the word 'eighth'.\n\n");
96dbc785 482 else
1f05cdcd
DM
483 printf("match: Text doesn't contain the word 'eighth'.\n\n");
484
96dbc785
PP
485 /** Match all occurrences of /wi../ **/
486 num_matches = matches(text, "m/(wi..)/g", &match_list);
487 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
1f05cdcd 488
96dbc785 489 for (i = 0; i < num_matches; i++)
2d8e6c8d 490 printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),n_a));
cb1a09d0 491 printf("\n");
1f05cdcd 492
96dbc785
PP
493 /** Remove all vowels from text **/
494 num_matches = substitute(&text, "s/[aeiou]//gi");
cb1a09d0 495 if (num_matches) {
1f05cdcd
DM
496 printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
497 num_matches);
2d8e6c8d 498 printf("Now text is: %s\n\n", SvPV(text,n_a));
cb1a09d0 499 }
1f05cdcd 500
96dbc785
PP
501 /** Attempt a substitution **/
502 if (!substitute(&text, "s/Perl/C/")) {
1f05cdcd 503 printf("substitute: s/Perl/C...No substitution made.\n\n");
cb1a09d0 504 }
1f05cdcd
DM
505
506 SvREFCNT_dec(text);
9cde0e7f 507 PL_perl_destruct_level = 1;
cb1a09d0
AD
508 perl_destruct(my_perl);
509 perl_free(my_perl);
1f05cdcd 510 }
cb1a09d0 511
96dbc785 512which produces the output (again, long lines have been wrapped here)
cb1a09d0 513
8a7dc658 514 match: Text contains the word 'quarter'.
96dbc785 515
8a7dc658 516 match: Text doesn't contain the word 'eighth'.
96dbc785 517
8a7dc658 518 matches: m/(wi..)/g found 2 matches...
cb1a09d0
AD
519 match: will
520 match: with
96dbc785 521
8a7dc658 522 substitute: s/[aeiou]//gi...139 substitutions made.
54310121 523 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
96dbc785
PP
524 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
525 qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
526 thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
527 hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
528
8a7dc658 529 substitute: s/Perl/C...No substitution made.
96dbc785 530
cb1a09d0
AD
531=head2 Fiddling with the Perl stack from your C program
532
533When trying to explain stacks, most computer science textbooks mumble
534something about spring-loaded columns of cafeteria plates: the last
535thing you pushed on the stack is the first thing you pop off. That'll
536do for our purposes: your C program will push some arguments onto "the Perl
537stack", shut its eyes while some magic happens, and then pop the
538results--the return value of your Perl subroutine--off the stack.
96dbc785 539
cb1a09d0
AD
540First you'll need to know how to convert between C types and Perl
541types, with newSViv() and sv_setnv() and newAV() and all their
4929bf7b 542friends. They're described in L<perlguts> and L<perlapi>.
cb1a09d0
AD
543
544Then you'll need to know how to manipulate the Perl stack. That's
545described in L<perlcall>.
546
96dbc785 547Once you've understood those, embedding Perl in C is easy.
cb1a09d0 548
54310121 549Because C has no builtin function for integer exponentiation, let's
cb1a09d0 550make Perl's ** operator available to it (this is less useful than it
5f05dabc 551sounds, because Perl implements ** with C's I<pow()> function). First
cb1a09d0
AD
552I'll create a stub exponentiation function in I<power.pl>:
553
554 sub expo {
555 my ($a, $b) = @_;
556 return $a ** $b;
557 }
558
559Now I'll create a C program, I<power.c>, with a function
560I<PerlPower()> that contains all the perlguts necessary to push the
561two arguments into I<expo()> and to pop the return value out. Take a
562deep breath...
563
cb1a09d0
AD
564 #include <EXTERN.h>
565 #include <perl.h>
96dbc785 566
cb1a09d0 567 static PerlInterpreter *my_perl;
96dbc785 568
cb1a09d0
AD
569 static void
570 PerlPower(int a, int b)
571 {
572 dSP; /* initialize stack pointer */
573 ENTER; /* everything created after here */
574 SAVETMPS; /* ...is a temporary variable. */
924508f0 575 PUSHMARK(SP); /* remember the stack pointer */
cb1a09d0
AD
576 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
577 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
578 PUTBACK; /* make local stack pointer global */
4929bf7b 579 call_pv("expo", G_SCALAR); /* call the function */
cb1a09d0
AD
580 SPAGAIN; /* refresh stack pointer */
581 /* pop the return value from stack */
582 printf ("%d to the %dth power is %d.\n", a, b, POPi);
96dbc785 583 PUTBACK;
cb1a09d0
AD
584 FREETMPS; /* free that return value */
585 LEAVE; /* ...and the XPUSHed "mortal" args.*/
586 }
96dbc785
PP
587
588 int main (int argc, char **argv, char **env)
cb1a09d0 589 {
95b76e31 590 char *my_argv[] = { "", "power.pl" };
96dbc785 591
cb1a09d0
AD
592 my_perl = perl_alloc();
593 perl_construct( my_perl );
96dbc785 594
95b76e31 595 perl_parse(my_perl, NULL, 2, my_argv, (char **)NULL);
8ebc5c01 596 perl_run(my_perl);
96dbc785 597
cb1a09d0 598 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
96dbc785 599
cb1a09d0
AD
600 perl_destruct(my_perl);
601 perl_free(my_perl);
602 }
96dbc785 603
cb1a09d0
AD
604
605
606Compile and run:
607
96dbc785
PP
608 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
609
610 % power
cb1a09d0
AD
611 3 to the 4th power is 81.
612
a6006777
PP
613=head2 Maintaining a persistent interpreter
614
8a7dc658
JO
615When developing interactive and/or potentially long-running
616applications, it's a good idea to maintain a persistent interpreter
617rather than allocating and constructing a new interpreter multiple
618times. The major reason is speed: since Perl will only be loaded into
54310121 619memory once.
8a7dc658
JO
620
621However, you have to be more cautious with namespace and variable
622scoping when using a persistent interpreter. In previous examples
623we've been using global variables in the default package C<main>. We
624knew exactly what code would be run, and assumed we could avoid
625variable collisions and outrageous symbol table growth.
626
627Let's say your application is a server that will occasionally run Perl
628code from some arbitrary file. Your server has no way of knowing what
629code it's going to run. Very dangerous.
630
631If the file is pulled in by C<perl_parse()>, compiled into a newly
632constructed interpreter, and subsequently cleaned out with
633C<perl_destruct()> afterwards, you're shielded from most namespace
634troubles.
635
636One way to avoid namespace collisions in this scenario is to translate
637the filename into a guaranteed-unique package name, and then compile
e010571f 638the code into that package using L<perlfunc/eval>. In the example
8a7dc658
JO
639below, each file will only be compiled once. Or, the application
640might choose to clean out the symbol table associated with the file
4929bf7b 641after it's no longer needed. Using L<perlapi/call_argv>, We'll
8a7dc658
JO
642call the subroutine C<Embed::Persistent::eval_file> which lives in the
643file C<persistent.pl> and pass the filename and boolean cleanup/cache
a6006777
PP
644flag as arguments.
645
8a7dc658
JO
646Note that the process will continue to grow for each file that it
647uses. In addition, there might be C<AUTOLOAD>ed subroutines and other
648conditions that cause Perl's symbol table to grow. You might want to
649add some logic that keeps track of the process size, or restarts
650itself after a certain number of requests, to ensure that memory
651consumption is minimized. You'll also want to scope your variables
e010571f 652with L<perlfunc/my> whenever possible.
a6006777 653
54310121 654
a6006777
PP
655 package Embed::Persistent;
656 #persistent.pl
54310121 657
a6006777 658 use strict;
77ca0c92 659 our %Cache;
1ee082b7 660 use Symbol qw(delete_package);
54310121 661
a6006777
PP
662 sub valid_package_name {
663 my($string) = @_;
664 $string =~ s/([^A-Za-z0-9\/])/sprintf("_%2x",unpack("C",$1))/eg;
665 # second pass only for words starting with a digit
666 $string =~ s|/(\d)|sprintf("/_%2x",unpack("C",$1))|eg;
54310121 667
a6006777
PP
668 # Dress it up as a real package name
669 $string =~ s|/|::|g;
670 return "Embed" . $string;
671 }
54310121 672
a6006777
PP
673 sub eval_file {
674 my($filename, $delete) = @_;
675 my $package = valid_package_name($filename);
676 my $mtime = -M $filename;
677 if(defined $Cache{$package}{mtime}
678 &&
54310121 679 $Cache{$package}{mtime} <= $mtime)
a6006777 680 {
54310121 681 # we have compiled this subroutine already,
8ebc5c01
PP
682 # it has not been updated on disk, nothing left to do
683 print STDERR "already compiled $package->handler\n";
a6006777
PP
684 }
685 else {
8ebc5c01
PP
686 local *FH;
687 open FH, $filename or die "open '$filename' $!";
688 local($/) = undef;
689 my $sub = <FH>;
690 close FH;
54310121 691
8ebc5c01
PP
692 #wrap the code into a subroutine inside our unique package
693 my $eval = qq{package $package; sub handler { $sub; }};
694 {
695 # hide our variables within this block
696 my($filename,$mtime,$package,$sub);
697 eval $eval;
698 }
699 die $@ if $@;
54310121 700
8ebc5c01
PP
701 #cache it unless we're cleaning out each time
702 $Cache{$package}{mtime} = $mtime unless $delete;
a6006777 703 }
54310121 704
a6006777
PP
705 eval {$package->handler;};
706 die $@ if $@;
54310121 707
a6006777 708 delete_package($package) if $delete;
54310121 709
a6006777
PP
710 #take a look if you want
711 #print Devel::Symdump->rnew($package)->as_string, $/;
712 }
54310121 713
a6006777 714 1;
54310121 715
a6006777
PP
716 __END__
717
718 /* persistent.c */
54310121
PP
719 #include <EXTERN.h>
720 #include <perl.h>
721
a6006777
PP
722 /* 1 = clean out filename's symbol table after each request, 0 = don't */
723 #ifndef DO_CLEAN
724 #define DO_CLEAN 0
725 #endif
54310121 726
a6006777 727 static PerlInterpreter *perl = NULL;
54310121 728
a6006777
PP
729 int
730 main(int argc, char **argv, char **env)
731 {
732 char *embedding[] = { "", "persistent.pl" };
733 char *args[] = { "", DO_CLEAN, NULL };
734 char filename [1024];
735 int exitstatus = 0;
2d8e6c8d 736 STRLEN n_a;
54310121 737
a6006777 738 if((perl = perl_alloc()) == NULL) {
8ebc5c01
PP
739 fprintf(stderr, "no memory!");
740 exit(1);
a6006777 741 }
54310121
PP
742 perl_construct(perl);
743
a6006777 744 exitstatus = perl_parse(perl, NULL, 2, embedding, NULL);
54310121
PP
745
746 if(!exitstatus) {
8ebc5c01 747 exitstatus = perl_run(perl);
54310121 748
8ebc5c01 749 while(printf("Enter file name: ") && gets(filename)) {
54310121 750
8ebc5c01
PP
751 /* call the subroutine, passing it the filename as an argument */
752 args[0] = filename;
4929bf7b 753 call_argv("Embed::Persistent::eval_file",
8ebc5c01 754 G_DISCARD | G_EVAL, args);
54310121 755
8ebc5c01 756 /* check $@ */
9cde0e7f 757 if(SvTRUE(ERRSV))
2d8e6c8d 758 fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,n_a));
8ebc5c01 759 }
a6006777 760 }
54310121 761
9cde0e7f 762 PL_perl_destruct_level = 0;
54310121
PP
763 perl_destruct(perl);
764 perl_free(perl);
a6006777
PP
765 exit(exitstatus);
766 }
767
a6006777
PP
768Now compile:
769
54310121 770 % cc -o persistent persistent.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
a6006777
PP
771
772Here's a example script file:
773
774 #test.pl
775 my $string = "hello";
776 foo($string);
777
778 sub foo {
779 print "foo says: @_\n";
780 }
781
782Now run:
783
784 % persistent
785 Enter file name: test.pl
786 foo says: hello
787 Enter file name: test.pl
788 already compiled Embed::test_2epl->handler
789 foo says: hello
790 Enter file name: ^C
791
8ebc5c01
PP
792=head2 Maintaining multiple interpreter instances
793
8a7dc658
JO
794Some rare applications will need to create more than one interpreter
795during a session. Such an application might sporadically decide to
54310121 796release any resources associated with the interpreter.
8a7dc658
JO
797
798The program must take care to ensure that this takes place I<before>
799the next interpreter is constructed. By default, the global variable
9cde0e7f 800C<PL_perl_destruct_level> is set to C<0>, since extra cleaning isn't
8a7dc658
JO
801needed when a program has only one interpreter.
802
9cde0e7f 803Setting C<PL_perl_destruct_level> to C<1> makes everything squeaky clean:
8a7dc658 804
9cde0e7f 805 PL_perl_destruct_level = 1;
8ebc5c01 806
8ebc5c01
PP
807 while(1) {
808 ...
9cde0e7f 809 /* reset global variables here with PL_perl_destruct_level = 1 */
54310121 810 perl_construct(my_perl);
8ebc5c01
PP
811 ...
812 /* clean and reset _everything_ during perl_destruct */
54310121
PP
813 perl_destruct(my_perl);
814 perl_free(my_perl);
8ebc5c01
PP
815 ...
816 /* let's go do it again! */
817 }
818
54310121
PP
819When I<perl_destruct()> is called, the interpreter's syntax parse tree
820and symbol tables are cleaned up, and global variables are reset.
8ebc5c01 821
8a7dc658
JO
822Now suppose we have more than one interpreter instance running at the
823same time. This is feasible, but only if you used the
824C<-DMULTIPLICITY> flag when building Perl. By default, that sets
9cde0e7f 825C<PL_perl_destruct_level> to C<1>.
8ebc5c01
PP
826
827Let's give it a try:
828
829
830 #include <EXTERN.h>
8a7dc658 831 #include <perl.h>
8ebc5c01
PP
832
833 /* we're going to embed two interpreters */
834 /* we're going to embed two interpreters */
835
8ebc5c01
PP
836 #define SAY_HELLO "-e", "print qq(Hi, I'm $^X\n)"
837
8ebc5c01
PP
838 int main(int argc, char **argv, char **env)
839 {
54310121 840 PerlInterpreter
8ebc5c01 841 *one_perl = perl_alloc(),
54310121 842 *two_perl = perl_alloc();
8ebc5c01
PP
843 char *one_args[] = { "one_perl", SAY_HELLO };
844 char *two_args[] = { "two_perl", SAY_HELLO };
845
846 perl_construct(one_perl);
847 perl_construct(two_perl);
848
849 perl_parse(one_perl, NULL, 3, one_args, (char **)NULL);
850 perl_parse(two_perl, NULL, 3, two_args, (char **)NULL);
851
852 perl_run(one_perl);
853 perl_run(two_perl);
854
855 perl_destruct(one_perl);
856 perl_destruct(two_perl);
857
858 perl_free(one_perl);
859 perl_free(two_perl);
860 }
861
862
863Compile as usual:
864
865 % cc -o multiplicity multiplicity.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
866
867Run it, Run it:
868
869 % multiplicity
870 Hi, I'm one_perl
871 Hi, I'm two_perl
872
96dbc785
PP
873=head2 Using Perl modules, which themselves use C libraries, from your C program
874
875If you've played with the examples above and tried to embed a script
876that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
877this probably happened:
878
879
880 Can't load module Socket, dynamic loading not available in this perl.
881 (You may need to build a new perl executable which either supports
882 dynamic loading or has the Socket module statically linked into it.)
883
884
885What's wrong?
886
887Your interpreter doesn't know how to communicate with these extensions
888on its own. A little glue will help. Up until now you've been
889calling I<perl_parse()>, handing it NULL for the second argument:
890
891 perl_parse(my_perl, NULL, argc, my_argv, NULL);
892
893That's where the glue code can be inserted to create the initial contact between
894Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
895to see how Perl does this:
896
897
898 #ifdef __cplusplus
899 # define EXTERN_C extern "C"
900 #else
901 # define EXTERN_C extern
902 #endif
903
20ce7b12 904 static void xs_init (void);
96dbc785 905
20ce7b12
GS
906 EXTERN_C void boot_DynaLoader (CV* cv);
907 EXTERN_C void boot_Socket (CV* cv);
96dbc785
PP
908
909
910 EXTERN_C void
911 xs_init()
912 {
913 char *file = __FILE__;
914 /* DynaLoader is a special case */
915 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
916 newXS("Socket::bootstrap", boot_Socket, file);
917 }
918
919Simply put: for each extension linked with your Perl executable
920(determined during its initial configuration on your
921computer or when adding a new extension),
922a Perl subroutine is created to incorporate the extension's
923routines. Normally, that subroutine is named
924I<Module::bootstrap()> and is invoked when you say I<use Module>. In
925turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
926counterpart for each of the extension's XSUBs. Don't worry about this
927part; leave that to the I<xsubpp> and extension authors. If your
928extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
929for you on the fly. In fact, if you have a working DynaLoader then there
5f05dabc 930is rarely any need to link in any other extensions statically.
96dbc785
PP
931
932
933Once you have this code, slap it into the second argument of I<perl_parse()>:
934
935
936 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
937
938
939Then compile:
940
8a7dc658 941 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
96dbc785
PP
942
943 % interp
944 use Socket;
945 use SomeDynamicallyLoadedModule;
946
947 print "Now I can use extensions!\n"'
948
949B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
950
8a7dc658 951 % perl -MExtUtils::Embed -e xsinit -- -o perlxsi.c
96dbc785
PP
952 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
953 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
8a7dc658 954 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
96dbc785 955
4929bf7b 956Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
96dbc785 957
53f52f58
DM
958=head1 Embedding Perl under Win32
959
e010571f
GS
960At the time of this writing (5.004), there are two versions of Perl
961which run under Win32. (The two versions are merging in 5.005.)
962Interfacing to ActiveState's Perl library is quite different from the
963examples in this documentation, as significant changes were made to
964the internal Perl API. However, it is possible to embed ActiveState's
965Perl runtime. For details, see the Perl for Win32 FAQ at
be94a901 966http://www.perl.com/CPAN/doc/FAQs/win32/perlwin32faq.html.
53f52f58
DM
967
968With the "official" Perl version 5.004 or higher, all the examples
e010571f 969within this documentation will compile and run untouched, although
53f52f58
DM
970the build process is slightly different between Unix and Win32.
971
e010571f 972For starters, backticks don't work under the Win32 native command shell.
53f52f58
DM
973The ExtUtils::Embed kit on CPAN ships with a script called
974B<genmake>, which generates a simple makefile to build a program from
e010571f 975a single C source file. It can be used like this:
53f52f58
DM
976
977 C:\ExtUtils-Embed\eg> perl genmake interp.c
978 C:\ExtUtils-Embed\eg> nmake
979 C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"
980
e010571f
GS
981You may wish to use a more robust environment such as the Microsoft
982Developer Studio. In this case, run this to generate perlxsi.c:
53f52f58
DM
983
984 perl -MExtUtils::Embed -e xsinit
985
e010571f
GS
986Create a new project and Insert -> Files into Project: perlxsi.c,
987perl.lib, and your own source files, e.g. interp.c. Typically you'll
988find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the
989B<CORE> directory relative to C<perl -V:archlib>. The studio will
990also need this path so it knows where to find Perl include files.
991This path can be added via the Tools -> Options -> Directories menu.
992Finally, select Build -> Build interp.exe and you're ready to go.
96dbc785 993
cb1a09d0
AD
994=head1 MORAL
995
996You can sometimes I<write faster code> in C, but
5f05dabc 997you can always I<write code faster> in Perl. Because you can use
cb1a09d0
AD
998each from the other, combine them as you wish.
999
1000
1001=head1 AUTHOR
1002
e010571f
GS
1003Jon Orwant <F<orwant@tpj.com>> and Doug MacEachern
1004<F<dougm@osf.org>>, with small contributions from Tim Bunce, Tom
1005Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
1006Zakharevich.
cb1a09d0 1007
e010571f
GS
1008Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
1009The Perl Journal (http://tpj.com). Doug is also the developer of the
1010most widely-used Perl embedding: the mod_perl system
1011(perl.apache.org), which embeds Perl in the Apache web server.
1012Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
1013have used this model for Oracle, Netscape and Internet Information
1014Server Perl plugins.
cb1a09d0 1015
e010571f 1016July 22, 1998
8a7dc658
JO
1017
1018=head1 COPYRIGHT
1019
e010571f 1020Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
8a7dc658
JO
1021Rights Reserved.
1022
e010571f
GS
1023Permission is granted to make and distribute verbatim copies of this
1024documentation provided the copyright notice and this permission notice are
1025preserved on all copies.
1026
1027Permission is granted to copy and distribute modified versions of this
1028documentation under the conditions for verbatim copying, provided also
1029that they are marked clearly as modified versions, that the authors'
1030names and title are unchanged (though subtitles and additional
1031authors' names may be added), and that the entire resulting derived
1032work is distributed under the terms of a permission notice identical
1033to this one.
1034
1035Permission is granted to copy and distribute translations of this
1036documentation into another language, under the above conditions for
1037modified versions.