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