Cwd::fastcwd in File::Find
[perl.git] / pod / perlembed.pod
1 =head1 NAME
2
3 perlembed - how to embed perl in your C program
4
5 =head1 DESCRIPTION
6
7 =head2 PREAMBLE
8
9 Do you want to:
10
11 =over 5
12
13 =item B<Use C from Perl?>
14
15 Read L<perlcall> and L<perlxs>.
16
17 =item B<Use a UNIX program from Perl?>
18
19 Read about backquotes and L<perlfunc/system> and L<perlfunc/exec>.
20
21 =item B<Use Perl from Perl?>
22
23 Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlmod/use>
24 and L<perlmod/require>.
25
26 =item B<Use C from C?>
27
28 Rethink your design.
29
30 =item B<Use Perl from C?>
31
32 Read on...
33
34 =back
35
36 =head2 ROADMAP
37
38 L<Compiling your C program>
39
40 There's one example in each of the six sections:
41
42 L<Adding a Perl interpreter to your C program>
43
44 L<Calling a Perl subroutine from your C program>
45
46 L<Evaluating a Perl statement from your C program>
47
48 L<Performing Perl pattern matches and substitutions from your C program>
49
50 L<Fiddling with the Perl stack from your C program>
51
52 L<Using Perl modules, which themselves use C libraries, from your C program>
53
54 This documentation is UNIX specific.
55
56 =head2 Compiling your C program
57
58 Every C program that uses Perl must link in the I<perl library>.
59
60 What's that, you ask?  Perl is itself written in C; the perl library
61 is the collection of compiled C programs that were used to create your
62 perl executable (I</usr/bin/perl> or equivalent).  (Corollary: you
63 can't use Perl from your C program unless Perl has been compiled on
64 your machine, or installed properly--that's why you shouldn't blithely
65 copy Perl executables from machine to machine without also copying the
66 I<lib> directory.)
67
68 Your C program will--usually--allocate, "run", and deallocate a
69 I<PerlInterpreter> object, which is defined in the perl library.
70
71 If 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
73 I<perl.h>, which you'll also need) will
74 reside in a directory resembling this:
75
76     /usr/local/lib/perl5/your_architecture_here/CORE
77
78 or perhaps just
79
80     /usr/local/lib/perl5/CORE
81
82 or maybe something like
83
84     /usr/opt/perl5/CORE
85
86 Execute this statement for a hint about where to find CORE:
87
88     perl -MConfig -e 'print $Config{archlib}'
89
90 Here's how you might compile the example in the next section,
91 L<Adding a Perl interpreter to your C program>,
92 on a DEC Alpha running the OSF operating system:
93
94     % cc -o interp interp.c -L/usr/local/lib/perl5/alpha-dec_osf/CORE
95     -I/usr/local/lib/perl5/alpha-dec_osf/CORE -lperl -lm
96
97 You'll have to choose the appropriate compiler (I<cc>, I<gcc>, et al.)  and
98 library directory (I</usr/local/lib/...>)  for your machine.  If your
99 compiler complains that certain functions are undefined, or that it
100 can'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
102 to change the path following the -I.
103
104 You may have to add extra libraries as well.  Which ones?
105 Perhaps those printed by
106
107    perl -MConfig -e 'print $Config{libs}'
108
109 We strongly recommend you use the B<ExtUtils::Embed> module to determine 
110 all of this information for you:
111
112    % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
113
114
115 If the B<ExtUtils::Embed> module is not part of your perl kit's
116 distribution you can retrieve it from:
117 http://www.perl.com/cgi-bin/cpan_mod?module=ExtUtils::Embed.
118
119
120 =head2 Adding a Perl interpreter to your C program
121
122 In 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>,
124 from the source distribution.  Here's a bastardized, non-portable version of
125 I<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     */
130
131     static PerlInterpreter *my_perl;  /***    The Perl interpreter    ***/
132
133     int main(int argc, char **argv, char **env)
134     {
135         my_perl = perl_alloc();
136         perl_construct(my_perl);
137         perl_parse(my_perl, NULL, argc, argv, (char **)NULL);
138         perl_run(my_perl);
139         perl_destruct(my_perl);
140         perl_free(my_perl);
141     }
142
143 Note that we do not use the C<env> pointer here or in any of the
144 following examples.
145 Normally handed to C<perl_parse> as it's final argument,
146 we hand it a B<NULL> instead, in which case the current environment
147 is used.
148
149 Now compile this program (I'll call it I<interp.c>) into an executable:
150
151     % cc -o interp interp.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
152
153 After a successful compilation, you'll be able to use I<interp> just
154 like 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
163 or
164
165     % interp -e 'printf("%x", 3735928559)'
166     deadbeef
167
168 You can also read and execute Perl statements from a file while in the
169 midst of your C program, by placing the filename in I<argv[1]> before
170 calling I<perl_run()>.
171
172 =head2 Calling a Perl subroutine from your C program
173
174 To call individual Perl subroutines, you'll need to remove the call to
175 I<perl_run()> and replace it with a call to I<perl_call_argv()>.
176
177 That's shown below, in a program I'll call I<showtime.c>.
178
179     #include <stdio.h>
180     #include <EXTERN.h>
181     #include <perl.h>
182
183     static PerlInterpreter *my_perl;
184
185     int main(int argc, char **argv, char **env)
186     {
187         my_perl = perl_alloc();
188         perl_construct(my_perl);
189
190         perl_parse(my_perl, NULL, argc, argv, NULL);
191
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
198 where I<showtime> is a Perl subroutine that takes no arguments (that's the
199 I<G_NOARGS>) and for which I'll ignore the return value (that's the
200 I<G_DISCARD>).  Those flags, and others, are discussed in L<perlcall>.
201
202 I'll define the I<showtime> subroutine in a file called I<showtime.pl>:
203
204     print "I shan't be printed.";
205
206     sub showtime {
207         print time;
208     }
209
210 Simple enough.  Now compile and run:
211
212     % cc -o showtime showtime.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
213
214     % showtime showtime.pl
215     818284590
216
217 yielding the number of seconds that elapsed between January 1, 1970
218 (the beginning of the UNIX epoch), and the moment I began writing this
219 sentence.
220
221 If you want to pass some arguments to the Perl subroutine, or
222 you want to access the return value, you'll need to manipulate the
223 Perl stack, demonstrated in the last section of this document:
224 L<Fiddling with the Perl stack from your C program>
225
226 =head2 Evaluating a Perl statement from your C program
227
228 NOTE: This section, and the next, employ some very brittle techniques
229 for evaluting strings of Perl code.  Perl 5.002 contains some nifty
230 features that enable A Better Way (such as with L<perlguts/perl_eval_sv>).
231 Look for updates to this document soon.
232
233 One way to evaluate a Perl string is to define a function (we'll call
234 ours I<perl_eval()>) that wraps around Perl's L<perlfunc/eval>.
235
236 Arguably, this is the only routine you'll ever need to execute
237 snippets of Perl code from within your C program.  Your string can be
238 as long as you wish; it can contain multiple statements; it can
239 use L<perlmod/require> or L<perlfunc/do> to include external Perl
240 files.
241
242 Our I<perl_eval()> lets us evaluate individual Perl strings, and then
243 extract variables for coercion into C types.  The following program,
244 I<string.c>, executes three Perl strings, extracting an C<int> from
245 the 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>
250
251    static PerlInterpreter *my_perl;
252
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    }
260
261    main (int argc, char **argv, char **env)
262    {
263      char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
264      STRLEN length;
265
266      my_perl = perl_alloc();
267      perl_construct( my_perl );
268
269      perl_parse(my_perl, NULL, 3, embedding, NULL);
270
271                                        /** Treat $a as an integer **/
272      perl_eval("$a = 3; $a **= 2");
273      printf("a = %d\n", SvIV(perl_get_sv("a", FALSE)));
274
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)));
278
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));
282
283      perl_destruct(my_perl);
284      perl_free(my_perl);
285    }
286
287 All of those strange functions with I<sv> in their names help convert Perl scalars to C types.  They're described in L<perlguts>.
288
289 If you compile and run I<string.c>, you'll see the results of using
290 I<SvIV()> to create an C<int>, I<SvNV()> to create a C<float>, and
291 I<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
300 Our I<perl_eval()> lets us evaluate strings of Perl code, so we can
301 define some functions that use it to "specialize" in matches and
302 substitutions: I<match()>, I<substitute()>, and I<matches()>.
303
304    char match(char *string, char *pattern);
305
306 Given a string and a pattern (e.g. "m/clasp/" or "/\b\w*\b/", which in
307 your program might be represented as C<"/\\b\\w*\\b/">),
308 returns 1 if the string matches the pattern and 0 otherwise.
309
310
311    int substitute(char *string[], char *pattern);
312
313 Given a pointer to a string and an "=~" operation (e.g. "s/bob/robert/g" or
314 "tr[A-Z][a-z]"), modifies the string according to the operation,
315 returning the number of substitutions made.
316
317    int matches(char *string, char *pattern, char **matches[]);
318
319 Given a string, a pattern, and a pointer to an empty array of strings,
320 evaluates C<$string =~ $pattern> in an array context, and fills in
321 I<matches> with the array elements (allocating memory as it does so),
322 returning the number of matches found.
323
324 Here's a sample program, I<match.c>, that uses all three (long lines have
325 been wrapped here):
326
327    #include <stdio.h>
328    #include <EXTERN.h>
329    #include <perl.h>
330    static PerlInterpreter *my_perl;
331    int perl_eval(char *string)
332    {
333      char *argv[2];
334      argv[0] = string;
335      argv[1] = NULL;
336      perl_call_argv("_eval_", 0, argv);
337    }
338    /** match(string, pattern)
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)
345    {
346      char *command;
347      command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 37);
348      sprintf(command, "$string = '%s'; $return = $string =~ %s",
349           string, pattern);
350      perl_eval(command);
351      free(command);
352      return SvIV(perl_get_sv("return", FALSE));
353    }
354    /** substitute(string, pattern)
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)
362    {
363      char *command;
364      STRLEN length;
365      command = malloc(sizeof(char) * strlen(*string) + strlen(pattern) + 35);
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));
372    }
373    /** matches(string, pattern, matches)
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[])
381    {
382      char *command;
383      SV *current_match;
384      AV *array;
385      I32 num_matches;
386      STRLEN length;
387      int i;
388      command = malloc(sizeof(char) * strlen(string) + strlen(pattern) + 38);
389      sprintf(command, "$string = '%s'; @array = ($string =~ %s)",
390           string, pattern);
391      perl_eval(command);
392      free(command);
393      array = perl_get_av("array", FALSE);
394      num_matches = av_len(array) + 1; /** assume $[ is 0 **/
395      *match_list = (char **) malloc(sizeof(char *) * num_matches);
396      for (i = 0; i <= num_matches; i++) {
397        current_match = av_shift(array);
398        (*match_list)[i] = SvPV(current_match, length);
399      }
400      return num_matches;
401    }
402    main (int argc, char **argv, char **env)
403    {
404      char *embedding[] = { "", "-e", "sub _eval_ { eval $_[0] }" };
405      char *text, **match_list;
406      int num_matches, i;
407      int j;
408      my_perl = perl_alloc();
409      perl_construct( my_perl );
410      perl_parse(my_perl, NULL, 3, embedding, NULL);
411      text = (char *) malloc(sizeof(char) * 486); /** A long string follows! **/
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]);
433      printf("\n");
434      for (i = 0; i < num_matches; i++) {
435        free(match_list[i]);
436      }
437      free(match_list);
438      /** Remove all vowels from text **/
439      num_matches = substitute(&text, "s/[aeiou]//gi");
440      if (num_matches) {
441        printf("substitute: s/[aeiou]//gi...%d substitutions made.\n",
442            num_matches);
443        printf("Now text is: %s\n\n", text);
444      }
445      /** Attempt a substitution **/
446      if (!substitute(&text, "s/Perl/C/")) {
447        printf("substitute: s/Perl/C...No substitution made.\n\n");
448      }
449      free(text);
450      perl_destruct(my_perl);
451      perl_free(my_perl);
452    }
453
454 which produces the output (again, long lines have been wrapped here)
455
456    perl_match: Text contains the word 'quarter'.
457
458    perl_match: Text doesn't contain the word 'eighth'.
459
460    perl_matches: m/(wi..)/g found 2 matches...
461    match: will
462    match: with
463
464    perl_substitute: s/[aeiou]//gi...139 substitutions made.
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
471    perl_substitute: s/Perl/C...No substitution made.
472
473 =head2 Fiddling with the Perl stack from your C program
474
475 When trying to explain stacks, most computer science textbooks mumble
476 something about spring-loaded columns of cafeteria plates: the last
477 thing you pushed on the stack is the first thing you pop off.  That'll
478 do for our purposes: your C program will push some arguments onto "the Perl
479 stack", shut its eyes while some magic happens, and then pop the
480 results--the return value of your Perl subroutine--off the stack.
481
482 First you'll need to know how to convert between C types and Perl
483 types, with newSViv() and sv_setnv() and newAV() and all their
484 friends.  They're described in L<perlguts>.
485
486 Then you'll need to know how to manipulate the Perl stack.  That's
487 described in L<perlcall>.
488
489 Once you've understood those, embedding Perl in C is easy.
490
491 Since C has no built-in function for integer exponentiation, let's
492 make Perl's ** operator available to it (this is less useful than it
493 sounds, since Perl implements ** with C's I<pow()> function).  First
494 I'll create a stub exponentiation function in I<power.pl>:
495
496     sub expo {
497         my ($a, $b) = @_;
498         return $a ** $b;
499     }
500
501 Now I'll create a C program, I<power.c>, with a function
502 I<PerlPower()> that contains all the perlguts necessary to push the
503 two arguments into I<expo()> and to pop the return value out.  Take a
504 deep breath...
505
506     #include <stdio.h>
507     #include <EXTERN.h>
508     #include <perl.h>
509
510     static PerlInterpreter *my_perl;
511
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);
526       PUTBACK;
527       FREETMPS;                       /* free that return value        */
528       LEAVE;                       /* ...and the XPUSHed "mortal" args.*/
529     }
530
531     int main (int argc, char **argv, char **env)
532     {
533       char *my_argv[2];
534
535       my_perl = perl_alloc();
536       perl_construct( my_perl );
537
538       my_argv[1] = (char *) malloc(10);
539       sprintf(my_argv[1], "power.pl");
540
541       perl_parse(my_perl, NULL, argc, my_argv, NULL);
542
543       PerlPower(3, 4);                      /*** Compute 3 ** 4 ***/
544
545       perl_destruct(my_perl);
546       perl_free(my_perl);
547     }
548
549
550
551 Compile and run:
552
553     % cc -o power power.c `perl -MExtUtils::Embed -e ccopts -e ldopts`
554
555     % power
556     3 to the 4th power is 81.
557
558 =head2 Using Perl modules, which themselves use C libraries, from your C program
559
560 If you've played with the examples above and tried to embed a script
561 that I<use()>s a Perl module (such as I<Socket>) which itself uses a C or C++ library,
562 this 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
570 What's wrong?
571
572 Your interpreter doesn't know how to communicate with these extensions
573 on its own.  A little glue will help.  Up until now you've been
574 calling I<perl_parse()>, handing it NULL for the second argument:
575
576  perl_parse(my_perl, NULL, argc, my_argv, NULL);
577
578 That's where the glue code can be inserted to create the initial contact between
579 Perl and linked C/C++ routines.  Let's take a look some pieces of I<perlmain.c>
580 to 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
604 Simply put: for each extension linked with your Perl executable
605 (determined during its initial configuration on your
606 computer or when adding a new extension),
607 a Perl subroutine is created to incorporate the extension's
608 routines.  Normally, that subroutine is named
609 I<Module::bootstrap()> and is invoked when you say I<use Module>.  In
610 turn, this hooks into an XSUB, I<boot_Module>, which creates a Perl
611 counterpart for each of the extension's XSUBs.  Don't worry about this
612 part; leave that to the I<xsubpp> and extension authors.  If your
613 extension is dynamically loaded, DynaLoader creates I<Module::bootstrap()>
614 for you on the fly.  In fact, if you have a working DynaLoader then there
615 is rarely any need to statically link in any other extensions.
616
617
618 Once 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
624 Then 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
634 B<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
641 Consult L<perlxs> and L<perlguts> for more details.
642
643
644 =head1 MORAL
645
646 You can sometimes I<write faster code> in C, but
647 you can always I<write code faster> in Perl.  Since you can use
648 each from the other, combine them as you wish.
649
650
651 =head1 AUTHOR
652
653 Jon Orwant F<E<lt>orwant@media.mit.eduE<gt>>, 
654 co-authored by Doug MacEachern F<E<lt>dougm@osf.orgE<gt>>, 
655 with contributions from
656 Tim Bunce, Tom Christiansen, Dov Grobgeld, and Ilya
657 Zakharevich.
658
659 June 17, 1996
660
661 Some of this material is excerpted from my book: I<Perl 5 Interactive>,
662 Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
663 courtesy of Waite Group Press.