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