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