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