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