This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Locale-related pod patches, take 2
[perl5.git] / pod / perlembed.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
cb1a09d0 3perlembed - how to embed perl in your C program
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
cb1a09d0
AD
7=head2 PREAMBLE
8
9Do you want to:
10
11=over 5
12
96dbc785 13=item B<Use C from Perl?>
cb1a09d0
AD
14
15Read L<perlcall> and L<perlxs>.
16
96dbc785 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
55497cff
PP
23Read about C<do> and C<eval> in L<perlfunc/do> and L<perlfunc/eval> and C<use>
24and C<require> in L<perlmod> and L<perlfunc/require>, L<perlfunc/use>.
cb1a09d0 25
96dbc785 26=item B<Use C from C?>
cb1a09d0
AD
27
28Rethink your design.
29
96dbc785 30=item B<Use Perl from C?>
cb1a09d0
AD
31
32Read on...
33
34=back
35
36=head2 ROADMAP
37
38L<Compiling your C program>
39
96dbc785 40There's one example in each of the six sections:
cb1a09d0
AD
41
42L<Adding a Perl interpreter to your C program>
43
44L<Calling a Perl subroutine from your C program>
45
46L<Evaluating a Perl statement from your C program>
47
48L<Performing Perl pattern matches and substitutions from your C program>
49
50L<Fiddling with the Perl stack from your C program>
51
96dbc785
PP
52L<Using Perl modules, which themselves use C libraries, from your C program>
53
cb1a09d0
AD
54This documentation is UNIX specific.
55
56=head2 Compiling your C program
57
96dbc785 58Every C program that uses Perl must link in the I<perl library>.
cb1a09d0
AD
59
60What's that, you ask? Perl is itself written in C; the perl library
61is the collection of compiled C programs that were used to create your
62perl executable (I</usr/bin/perl> or equivalent). (Corollary: you
63can't use Perl from your C program unless Perl has been compiled on
64your machine, or installed properly--that's why you shouldn't blithely
65copy Perl executables from machine to machine without also copying the
66I<lib> directory.)
67
68Your C program will--usually--allocate, "run", and deallocate a
96dbc785 69I<PerlInterpreter> object, which is defined in the perl library.
cb1a09d0
AD
70
71If your copy of Perl is recent enough to contain this documentation
72(5.002 or later), then the perl library (and I<EXTERN.h> and
73I<perl.h>, which you'll also need) will
74reside in a directory resembling this:
75
76 /usr/local/lib/perl5/your_architecture_here/CORE
77
78or perhaps just
79
80 /usr/local/lib/perl5/CORE
81
82or maybe something like
83
84 /usr/opt/perl5/CORE
85
86Execute this statement for a hint about where to find CORE:
87
96dbc785 88 perl -MConfig -e 'print $Config{archlib}'
cb1a09d0
AD
89
90Here's how you might compile the example in the next section,
91L<Adding a Perl interpreter to your C program>,
92on a DEC Alpha running the OSF operating system:
93
96dbc785 94 % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
cb1a09d0
AD
95 -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
96
97You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.) and
98library directory (I</usr/local/lib/...>) for your machine. If your
99compiler complains that certain functions are undefined, or that it
100can't locate I<-lperl>, then you need to change the path following the
101-L. If it complains that it can't find I<EXTERN.h> or I<perl.h>, you need
96dbc785 102to change the path following the -I.
cb1a09d0
AD
103
104You may have to add extra libraries as well. Which ones?
96dbc785
PP
105Perhaps those printed by
106
107 perl -MConfig -e 'print $Config{libs}'
108
109We strongly recommend you use the B<ExtUtils::Embed> module to determine
110all of this information for you:
111
112 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
113
114
115If the B<ExtUtils::Embed> module is not part of your perl kit's
116distribution you can retrieve it from:
117http://www.perl.com/cgi-bin/cpan_mod?module=ExtUtils::Embed.
cb1a09d0 118
cb1a09d0
AD
119
120=head2 Adding a Perl interpreter to your C program
121
122In a sense, perl (the C program) is a good example of embedding Perl
123(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
124from the source distribution. Here's a bastardized, non-portable version of
125I<miniperlmain.c> containing the essentials of embedding:
126
127 #include <stdio.h>
128 #include <EXTERN.h> /* from the Perl distribution */
129 #include <perl.h> /* from the Perl distribution */
96dbc785 130
cb1a09d0 131 static PerlInterpreter *my_perl; /*** The Perl interpreter ***/
96dbc785 132
c07a80fd 133 int main(int argc, char **argv, char **env)
cb1a09d0
AD
134 {
135 my_perl = perl_alloc();
136 perl_construct(my_perl);
96dbc785 137 perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
cb1a09d0
AD
138 perl_run(my_perl);
139 perl_destruct(my_perl);
140 perl_free(my_perl);
141 }
142
96dbc785
PP
143Note that we do not use the C<env> pointer here or in any of the
144following examples.
5f05dabc 145Normally handed to C<perl_parse> as its final argument,
96dbc785
PP
146we hand it a B<NULL> instead, in which case the current environment
147is used.
148
cb1a09d0
AD
149Now compile this program (I'll call it I<interp.c>) into an executable:
150
96dbc785 151 % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
cb1a09d0
AD
152
153After a successful compilation, you'll be able to use I<interp> just
154like perl itself:
155
156 % interp
157 print "Pretty Good Perl \n";
158 print "10890 - 9801 is ", 10890 - 9801;
159 <CTRL-D>
160 Pretty Good Perl
161 10890 - 9801 is 1089
162
163or
164
165 % interp -e 'printf("%x", 3735928559)'
166 deadbeef
167
168You can also read and execute Perl statements from a file while in the
169midst of your C program, by placing the filename in I<argv[1]> before
96dbc785 170calling I<perl_run()>.
cb1a09d0
AD
171
172=head2 Calling a Perl subroutine from your C program
173
174To call individual Perl subroutines, you'll need to remove the call to
175I<perl_run()> and replace it with a call to I<perl_call_argv()>.
176
177That's shown below, in a program I'll call I<showtime.c>.
178
179 #include <stdio.h>
180 #include <EXTERN.h>
96dbc785
PP
181 #include <perl.h>
182
183 static PerlInterpreter *my_perl;
184
c07a80fd 185 int main(int argc, char **argv, char **env)
cb1a09d0
AD
186 {
187 my_perl = perl_alloc();
188 perl_construct(my_perl);
96dbc785
PP
189
190 perl_parse(my_perl, NULL, argc, argv, NULL);
191
cb1a09d0
AD
192 /*** This replaces perl_run() ***/
193 perl_call_argv("showtime", G_DISCARD | G_NOARGS, argv);
194 perl_destruct(my_perl);
195 perl_free(my_perl);
196 }
197
198where I<showtime> is a Perl subroutine that takes no arguments (that's the
96dbc785 199I<G_NOARGS>) and for which I'll ignore the return value (that's the
cb1a09d0
AD
200I<G_DISCARD>). Those flags, and others, are discussed in L<perlcall>.
201
202I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
203
204 print "I shan't be printed.";
96dbc785 205
cb1a09d0
AD
206 sub showtime {
207 print time;
208 }
209
210Simple enough. Now compile and run:
211
96dbc785
PP
212 % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
213
cb1a09d0
AD
214 % showtime showtime.pl
215 818284590
216
217yielding the number of seconds that elapsed between January 1, 1970
218(the beginning of the UNIX epoch), and the moment I began writing this
219sentence.
220
221If you want to pass some arguments to the Perl subroutine, or
222you want to access the return value, you'll need to manipulate the
96dbc785 223Perl stack, demonstrated in the last section of this document:
cb1a09d0
AD
224L<Fiddling with the Perl stack from your C program>
225
226=head2 Evaluating a Perl statement from your C program
227
228NOTE: This section, and the next, employ some very brittle techniques
184e9718 229for evaluating strings of Perl code. Perl 5.002 contains some nifty
cb1a09d0
AD
230features that enable A Better Way (such as with L<perlguts/perl_eval_sv>).
231Look for updates to this document soon.
232
96dbc785 233One way to evaluate a Perl string is to define a function (we'll call
cb1a09d0
AD
234ours I<perl_eval()>) that wraps around Perl's L<perlfunc/eval>.
235
236Arguably, this is the only routine you'll ever need to execute
237snippets of Perl code from within your C program. Your string can be
238as long as you wish; it can contain multiple statements; it can
55497cff 239use L<perlfunc/require> or L<perlfunc/do> to include external Perl
96dbc785 240files.
cb1a09d0 241
96dbc785
PP
242Our I<perl_eval()> lets us evaluate individual Perl strings, and then
243extract variables for coercion into C types. The following program,
cb1a09d0
AD
244I<string.c>, executes three Perl strings, extracting an C<int> from
245the first, a C<float> from the second, and a C<char *> from the third.
246
247 #include <stdio.h>
248 #include <EXTERN.h>
249 #include <perl.h>
96dbc785 250
cb1a09d0 251 static PerlInterpreter *my_perl;
96dbc785 252
cb1a09d0
AD
253 int perl_eval(char *string)
254 {
255 char *argv[2];
256 argv[0] = string;
257 argv[1] = NULL;
258 perl_call_argv("_eval_", 0, argv);
259 }
96dbc785 260
c07a80fd 261 main (int argc, char **argv, char **env)
cb1a09d0
AD
262 {
263 char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
264 STRLEN length;
96dbc785 265
cb1a09d0
AD
266 my_perl = perl_alloc();
267 perl_construct( my_perl );
96dbc785
PP
268
269 perl_parse(my_perl, NULL, 3, embedding, NULL);
270
cb1a09d0
AD
271 /** Treat $a as an integer **/
272 perl_eval("$a = 3; $a **= 2");
273 printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
96dbc785 274
cb1a09d0
AD
275 /** Treat $a as a float **/
276 perl_eval("$a = 3.14; $a **= 2");
277 printf("a = %f\n", SvNV(perl_get_sv("a", FALSE)));
96dbc785 278
cb1a09d0
AD
279 /** Treat $a as a string **/
280 perl_eval("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a); ");
281 printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), length));
96dbc785 282
cb1a09d0
AD
283 perl_destruct(my_perl);
284 perl_free(my_perl);
285 }
286
287All of those strange functions with I<sv> in their names help convert Perl scalars to C types. They're described in L<perlguts>.
288
289If you compile and run I<string.c>, you'll see the results of using
290I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
291I<SvPV()> to create a string:
292
293 a = 9
294 a = 9.859600
295 a = Just Another Perl Hacker
296
297
298=head2 Performing Perl pattern matches and substitutions from your C program
299
300Our I<perl_eval()> lets us evaluate strings of Perl code, so we can
301define some functions that use it to "specialize" in matches and
302substitutions: I<match()>, I<substitute()>, and I<matches()>.
303
96dbc785 304 char match(char *string, char *pattern);
cb1a09d0 305
5f05dabc 306Given a string and a pattern (e.g., "m/clasp/" or "/\b\w*\b/", which in
cb1a09d0
AD
307your program might be represented as C<"/\\b\\w*\\b/">),
308returns 1 if the string matches the pattern and 0 otherwise.
309
310
311 int substitute(char *string[], char *pattern);
312
5f05dabc 313Given a pointer to a string and an "=~" operation (e.g., "s/bob/robert/g" or
cb1a09d0
AD
314"tr[A-Z][a-z]"), modifies the string according to the operation,
315returning the number of substitutions made.
316
317 int matches(char *string, char *pattern, char **matches[]);
318
319Given a string, a pattern, and a pointer to an empty array of strings,
320evaluates C<$string =~ $pattern> in an array context, and fills in
96dbc785 321I<matches> with the array elements (allocating memory as it does so),
cb1a09d0
AD
322returning the number of matches found.
323
96dbc785
PP
324Here's a sample program, I<match.c>, that uses all three (long lines have
325been wrapped here):
cb1a09d0
AD
326
327 #include <stdio.h>
328 #include <EXTERN.h>
329 #include <perl.h>
cb1a09d0 330 static PerlInterpreter *my_perl;
96dbc785 331 int perl_eval(char *string)
cb1a09d0
AD
332 {
333 char *argv[2];
334 argv[0] = string;
335 argv[1] = NULL;
336 perl_call_argv("_eval_", 0, argv);
337 }
cb1a09d0 338 /** match(string, pattern)
96dbc785
PP
339 **
340 ** Used for matches in a scalar context.
341 **
342 ** Returns 1 if the match was successful; 0 otherwise.
343 **/
344 char match(char *string, char *pattern)
cb1a09d0
AD
345 {
346 char *command;
347 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
96dbc785
PP
348 sprintf(command, "$string = '%s'; $return = $string =~ %s",
349 string, pattern);
cb1a09d0
AD
350 perl_eval(command);
351 free(command);
352 return SvIV(perl_get_sv("return", FALSE));
353 }
cb1a09d0 354 /** substitute(string, pattern)
96dbc785
PP
355 **
356 ** Used for =~ operations that modify their left-hand side (s/// and tr///)
357 **
358 ** Returns the number of successful matches, and
359 ** modifies the input string if there were any.
360 **/
361 int substitute(char *string[], char *pattern)
cb1a09d0
AD
362 {
363 char *command;
364 STRLEN length;
365 command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
96dbc785
PP
366 sprintf(command, "$string = '%s'; $ret = ($string =~ %s)",
367 *string, pattern);
368 perl_eval(command);
369 free(command);
370 *string = SvPV(perl_get_sv("string", FALSE), length);
371 return SvIV(perl_get_sv("ret", FALSE));
cb1a09d0 372 }
cb1a09d0 373 /** matches(string, pattern, matches)
96dbc785
PP
374 **
375 ** Used for matches in an array context.
376 **
377 ** Returns the number of matches,
378 ** and fills in **matches with the matching substrings (allocates memory!)
379 **/
380 int matches(char *string, char *pattern, char **match_list[])
cb1a09d0
AD
381 {
382 char *command;
383 SV *current_match;
384 AV *array;
385 I32 num_matches;
386 STRLEN length;
387 int i;
cb1a09d0 388 command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
96dbc785
PP
389 sprintf(command, "$string = '%s'; @array = ($string =~ %s)",
390 string, pattern);
cb1a09d0
AD
391 perl_eval(command);
392 free(command);
393 array = perl_get_av("array", FALSE);
394 num_matches = av_len(array) + 1; /** assume $[ is 0 **/
96dbc785
PP
395 *match_list = (char **) malloc(sizeof(char *) * num_matches);
396 for (i = 0; i <= num_matches; i++) {
cb1a09d0 397 current_match = av_shift(array);
96dbc785 398 (*match_list)[i] = SvPV(current_match, length);
cb1a09d0
AD
399 }
400 return num_matches;
401 }
c07a80fd 402 main (int argc, char **argv, char **env)
cb1a09d0
AD
403 {
404 char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
96dbc785 405 char *text, **match_list;
cb1a09d0
AD
406 int num_matches, i;
407 int j;
cb1a09d0
AD
408 my_perl = perl_alloc();
409 perl_construct( my_perl );
96dbc785 410 perl_parse(my_perl, NULL, 3, embedding, NULL);
cb1a09d0 411 text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
96dbc785
PP
412 sprintf(text, "%s", "When he is at a convenience store and the bill \
413 comes to some amount like 76 cents, Maynard is aware that there is \
414 something he *should* do, something that will enable him to get back \
415 a quarter, but he has no idea *what*. He fumbles through his red \
416 squeezey changepurse and gives the boy three extra pennies with his \
417 dollar, hoping that he might luck into the correct amount. The boy \
418 gives him back two of his own pennies and then the big shiny quarter \
419 that is his prize. -RICHH");
420 if (match(text, "m/quarter/")) /** Does text contain 'quarter'? **/
421 printf("match: Text contains the word 'quarter'.\n\n");
422 else
423 printf("match: Text doesn't contain the word 'quarter'.\n\n");
424 if (match(text, "m/eighth/")) /** Does text contain 'eighth'? **/
425 printf("match: Text contains the word 'eighth'.\n\n");
426 else
427 printf("match: Text doesn't contain the word 'eighth'.\n\n");
428 /** Match all occurrences of /wi../ **/
429 num_matches = matches(text, "m/(wi..)/g", &match_list);
430 printf("matches: m/(wi..)/g found %d matches...\n", num_matches);
431 for (i = 0; i < num_matches; i++)
432 printf("match: %s\n", match_list[i]);
cb1a09d0
AD
433 printf("\n");
434 for (i = 0; i < num_matches; i++) {
96dbc785 435 free(match_list[i]);
cb1a09d0 436 }
96dbc785
PP
437 free(match_list);
438 /** Remove all vowels from text **/
439 num_matches = substitute(&text, "s/[aeiou]//gi");
cb1a09d0 440 if (num_matches) {
96dbc785
PP
441 printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
442 num_matches);
cb1a09d0
AD
443 printf("Now text is: %s\n\n", text);
444 }
96dbc785
PP
445 /** Attempt a substitution **/
446 if (!substitute(&text, "s/Perl/C/")) {
447 printf("substitute: s/Perl/C...No substitution made.\n\n");
cb1a09d0 448 }
cb1a09d0 449 free(text);
cb1a09d0
AD
450 perl_destruct(my_perl);
451 perl_free(my_perl);
452 }
453
96dbc785 454which produces the output (again, long lines have been wrapped here)
cb1a09d0
AD
455
456 perl_match: Text contains the word 'quarter'.
96dbc785 457
cb1a09d0 458 perl_match: Text doesn't contain the word 'eighth'.
96dbc785 459
cb1a09d0
AD
460 perl_matches: m/(wi..)/g found 2 matches...
461 match: will
462 match: with
96dbc785 463
cb1a09d0 464 perl_substitute: s/[aeiou]//gi...139 substitutions made.
96dbc785
PP
465 Now text is: Whn h s t cnvnnc str nd th bll cms t sm mnt lk 76 cnts,
466 Mynrd s wr tht thr s smthng h *shld* d, smthng tht wll nbl hm t gt bck
467 qrtr, bt h hs n d *wht*. H fmbls thrgh hs rd sqzy chngprs nd gvs th by
468 thr xtr pnns wth hs dllr, hpng tht h mght lck nt th crrct mnt. Th by gvs
469 hm bck tw f hs wn pnns nd thn th bg shny qrtr tht s hs prz. -RCHH
470
cb1a09d0 471 perl_substitute: s/Perl/C...No substitution made.
96dbc785 472
cb1a09d0
AD
473=head2 Fiddling with the Perl stack from your C program
474
475When trying to explain stacks, most computer science textbooks mumble
476something about spring-loaded columns of cafeteria plates: the last
477thing you pushed on the stack is the first thing you pop off. That'll
478do for our purposes: your C program will push some arguments onto "the Perl
479stack", shut its eyes while some magic happens, and then pop the
480results--the return value of your Perl subroutine--off the stack.
96dbc785 481
cb1a09d0
AD
482First you'll need to know how to convert between C types and Perl
483types, with newSViv() and sv_setnv() and newAV() and all their
484friends. They're described in L<perlguts>.
485
486Then you'll need to know how to manipulate the Perl stack. That's
487described in L<perlcall>.
488
96dbc785 489Once you've understood those, embedding Perl in C is easy.
cb1a09d0 490
5f05dabc 491Because C has no built-in function for integer exponentiation, let's
cb1a09d0 492make Perl's ** operator available to it (this is less useful than it
5f05dabc 493sounds, because Perl implements ** with C's I<pow()> function). First
cb1a09d0
AD
494I'll create a stub exponentiation function in I<power.pl>:
495
496 sub expo {
497 my ($a, $b) = @_;
498 return $a ** $b;
499 }
500
501Now I'll create a C program, I<power.c>, with a function
502I<PerlPower()> that contains all the perlguts necessary to push the
503two arguments into I<expo()> and to pop the return value out. Take a
504deep breath...
505
506 #include <stdio.h>
507 #include <EXTERN.h>
508 #include <perl.h>
96dbc785 509
cb1a09d0 510 static PerlInterpreter *my_perl;
96dbc785 511
cb1a09d0
AD
512 static void
513 PerlPower(int a, int b)
514 {
515 dSP; /* initialize stack pointer */
516 ENTER; /* everything created after here */
517 SAVETMPS; /* ...is a temporary variable. */
518 PUSHMARK(sp); /* remember the stack pointer */
519 XPUSHs(sv_2mortal(newSViv(a))); /* push the base onto the stack */
520 XPUSHs(sv_2mortal(newSViv(b))); /* push the exponent onto stack */
521 PUTBACK; /* make local stack pointer global */
522 perl_call_pv("expo", G_SCALAR); /* call the function */
523 SPAGAIN; /* refresh stack pointer */
524 /* pop the return value from stack */
525 printf ("%d to the %dth power is %d.\n", a, b, POPi);
96dbc785 526 PUTBACK;
cb1a09d0
AD
527 FREETMPS; /* free that return value */
528 LEAVE; /* ...and the XPUSHed "mortal" args.*/
529 }
96dbc785
PP
530
531 int main (int argc, char **argv, char **env)
cb1a09d0
AD
532 {
533 char *my_argv[2];
96dbc785 534
cb1a09d0
AD
535 my_perl = perl_alloc();
536 perl_construct( my_perl );
96dbc785 537
cb1a09d0
AD
538 my_argv[1] = (char *) malloc(10);
539 sprintf(my_argv[1], "power.pl");
96dbc785
PP
540
541 perl_parse(my_perl, NULL, argc, my_argv, NULL);
542
cb1a09d0 543 PerlPower(3, 4); /*** Compute 3 ** 4 ***/
96dbc785 544
cb1a09d0
AD
545 perl_destruct(my_perl);
546 perl_free(my_perl);
547 }
96dbc785 548
cb1a09d0
AD
549
550
551Compile and run:
552
96dbc785
PP
553 % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
554
555 % power
cb1a09d0
AD
556 3 to the 4th power is 81.
557
96dbc785
PP
558=head2 Using Perl modules, which themselves use C libraries, from your C program
559
560If you've played with the examples above and tried to embed a script
561that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
562this probably happened:
563
564
565 Can't load module Socket, dynamic loading not available in this perl.
566 (You may need to build a new perl executable which either supports
567 dynamic loading or has the Socket module statically linked into it.)
568
569
570What's wrong?
571
572Your interpreter doesn't know how to communicate with these extensions
573on its own. A little glue will help. Up until now you've been
574calling I<perl_parse()>, handing it NULL for the second argument:
575
576 perl_parse(my_perl, NULL, argc, my_argv, NULL);
577
578That's where the glue code can be inserted to create the initial contact between
579Perl and linked C/C++ routines. Let's take a look some pieces of I<perlmain.c>
580to see how Perl does this:
581
582
583 #ifdef __cplusplus
584 # define EXTERN_C extern "C"
585 #else
586 # define EXTERN_C extern
587 #endif
588
589 static void xs_init _((void));
590
591 EXTERN_C void boot_DynaLoader _((CV* cv));
592 EXTERN_C void boot_Socket _((CV* cv));
593
594
595 EXTERN_C void
596 xs_init()
597 {
598 char *file = __FILE__;
599 /* DynaLoader is a special case */
600 newXS("DynaLoader::boot_DynaLoader", boot_DynaLoader, file);
601 newXS("Socket::bootstrap", boot_Socket, file);
602 }
603
604Simply put: for each extension linked with your Perl executable
605(determined during its initial configuration on your
606computer or when adding a new extension),
607a Perl subroutine is created to incorporate the extension's
608routines. Normally, that subroutine is named
609I<Module::bootstrap()> and is invoked when you say I<use Module>. In
610turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
611counterpart for each of the extension's XSUBs. Don't worry about this
612part; leave that to the I<xsubpp> and extension authors. If your
613extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
614for you on the fly. In fact, if you have a working DynaLoader then there
5f05dabc 615is rarely any need to link in any other extensions statically.
96dbc785
PP
616
617
618Once you have this code, slap it into the second argument of I<perl_parse()>:
619
620
621 perl_parse(my_perl, xs_init, argc, my_argv, NULL);
622
623
624Then compile:
625
626 % cc -o interp interp.c `perl -MExtUtils::Embed -e ldopts`
627
628 % interp
629 use Socket;
630 use SomeDynamicallyLoadedModule;
631
632 print "Now I can use extensions!\n"'
633
634B<ExtUtils::Embed> can also automate writing the I<xs_init> glue code.
635
636 % perl -MExtUtils::Embed -e xsinit -o perlxsi.c
637 % cc -c perlxsi.c `perl -MExtUtils::Embed -e ccopts`
638 % cc -c interp.c `perl -MExtUtils::Embed -e ccopts`
639 % cc -o interp perlxsi.o interp.o `perl -MExtUtils::Embed -e ldopts`
640
641Consult L<perlxs> and L<perlguts> for more details.
642
643
cb1a09d0
AD
644=head1 MORAL
645
646You can sometimes I<write faster code> in C, but
5f05dabc 647you can always I<write code faster> in Perl. Because you can use
cb1a09d0
AD
648each from the other, combine them as you wish.
649
650
651=head1 AUTHOR
652
96dbc785
PP
653Jon Orwant F<E<lt>orwant@media.mit.eduE<gt>>,
654co-authored by Doug MacEachern F<E<lt>dougm@osf.orgE<gt>>,
655with contributions from
656Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya
657Zakharevich.
cb1a09d0 658
96dbc785 659June 17, 1996
cb1a09d0 660
96dbc785 661Some of this material is excerpted from my book: I<Perl 5 Interactive>,
cb1a09d0
AD
662Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
663courtesy of Waite Group Press.