=item B<Use C from Perl?>
-Read L<perlxs>, L<perlxstut> and L<h2xs>.
+Read L<perlxstut>, L<perlxs>, L<h2xs>, and L<perlguts>.
=item B<Use a Unix program from Perl?>
=item B<Use Perl from Perl?>
-Read about do(), eval(), require(), and use() in L<perlfunc>.
+Read about L<perlfunc/do> and L<perlfunc/eval> and L<perlfunc/require>
+and L<perlfunc/use>.
=item B<Use C from C?>
=head2 ROADMAP
-Compiling your C program
+L<Compiling your C program>
-There's one example in each of the nine sections:
+L<Adding a Perl interpreter to your C program>
-=over 4
+L<Calling a Perl subroutine from your C program>
-=item *
+L<Evaluating a Perl statement from your C program>
-Adding a Perl interpreter to your C program
+L<Performing Perl pattern matches and substitutions from your C program>
-=item *
+L<Fiddling with the Perl stack from your C program>
-Calling a Perl subroutine from your C program
+L<Maintaining a persistent interpreter>
-=item *
+L<Maintaining multiple interpreter instances>
-Evaluating a Perl statement from your C program
+L<Using Perl modules, which themselves use C libraries, from your C program>
-=item *
+L<Embedding Perl under Win32>
-Performing Perl pattern matches and substitutions from your C program
-
-=item *
-
-Fiddling with the Perl stack from your C program
-
-=item *
-
-Maintaining a persistent interpreter
-
-=item *
-
-Maintaining multiple interpreter instances
-
-=item *
-
-Using Perl modules, which themselves use C libraries, from your C program
-
-=item *
-
-Embedding Perl under Win32
-
-=back
+=back
=head2 Compiling your C program
perl -MConfig -e 'print $Config{archlib}'
Here's how you'd compile the example in the next section,
-Adding a Perl interpreter to your C program, on my Linux box:
+L<Adding a Perl interpreter to your C program>, on my Linux box:
% gcc -O2 -Dbool=char -DHAS_BOOL -I/usr/local/include
-I/usr/local/lib/perl5/i586-linux/5.003/CORE
-L/usr/local/lib/perl5/i586-linux/5.003/CORE
-o interp interp.c -lperl -lm
-(That's all one line.) On my DEC Alpha running 5.003_05, the incantation
-is a bit different:
+(That's all one line.) On my DEC Alpha running old 5.003_05, the
+incantation is a bit different:
% cc -O2 -Olimit 2900 -DSTANDARD_C -I/usr/local/include
-I/usr/local/lib/perl5/alpha-dec_osf/5.00305/CORE
In a sense, perl (the C program) is a good example of embedding Perl
(the language), so I'll demonstrate embedding with I<miniperlmain.c>,
-from the source distribution. Here's a bastardized, nonportable
+included in the source distribution. Here's a bastardized, nonportable
version of I<miniperlmain.c> containing the essentials of embedding:
#include <EXTERN.h> /* from the Perl distribution */
You can also read and execute Perl statements from a file while in the
midst of your C program, by placing the filename in I<argv[1]> before
-calling I<perl_run()>.
+calling I<perl_run>.
=head2 Calling a Perl subroutine from your C program
To call individual Perl subroutines, you can use any of the B<perl_call_*>
functions documented in L<perlcall>.
-In this example we'll use perl_call_argv().
+In this example we'll use C<perl_call_argv>.
That's shown below, in a program I'll call I<showtime.c>.
strings to the C<NULL>-terminated C<args> list passed to
I<perl_call_argv>. For other data types, or to examine return values,
you'll need to manipulate the Perl stack. That's demonstrated in the
-last section of this document: Fiddling with the Perl stack from
-your C program.
+last section of this document: L<Fiddling with the Perl stack from
+your C program>.
=head2 Evaluating a Perl statement from your C program
Perl provides two API functions to evaluate pieces of Perl code.
-These are perl_eval_sv() and perl_eval_pv().
+These are L<perlguts/perl_eval_sv> and L<perlguts/perl_eval_pv>.
Arguably, these are the only routines you'll ever need to execute
-snippets of Perl code from within your C program. Your code can be
-as long as you wish; it can contain multiple statements; it can employ
-use(), require(), and do() to include external Perl files.
+snippets of Perl code from within your C program. Your code can be as
+long as you wish; it can contain multiple statements; it can employ
+L<perlfunc/use>, L<perlfunc/require>, and L<perlfunc/do> to
+include external Perl files.
-perl_eval_pv() lets us evaluate individual Perl strings, and then
+I<perl_eval_pv> lets us evaluate individual Perl strings, and then
extract variables for coercion into C types. The following program,
I<string.c>, executes three Perl strings, extracting an C<int> from
the first, a C<float> from the second, and a C<char *> from the third.
In the example above, we've created a global variable to temporarily
store the computed value of our eval'd expression. It is also
possible and in most cases a better strategy to fetch the return value
-from perl_eval_pv() instead. Example:
+from I<perl_eval_pv()> instead. Example:
...
SV *val = perl_eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE);
=head2 Performing Perl pattern matches and substitutions from your C program
-The I<perl_eval_sv()> function lets us evaluate chunks of Perl code, so we can
+The I<perl_eval_sv()> function lets us evaluate strings of Perl code, so we can
define some functions that use it to "specialize" in matches and
substitutions: I<match()>, I<substitute()>, and I<matches()>.
- char match(SV *string, char *pattern);
+ I32 match(SV *string, char *pattern);
Given a string and a pattern (e.g., C<m/clasp/> or C</\b\w*\b/>, which
in your C program might appear as "/\\b\\w*\\b/"), match()
One way to avoid namespace collisions in this scenario is to translate
the filename into a guaranteed-unique package name, and then compile
-the code into that package using eval(). In the example
+the code into that package using L<perlfunc/eval>. In the example
below, each file will only be compiled once. Or, the application
might choose to clean out the symbol table associated with the file
-after it's no longer needed. Using perl_call_argv(), We'll
+after it's no longer needed. Using L<perlcall/perl_call_argv>, We'll
call the subroutine C<Embed::Persistent::eval_file> which lives in the
file C<persistent.pl> and pass the filename and boolean cleanup/cache
flag as arguments.
add some logic that keeps track of the process size, or restarts
itself after a certain number of requests, to ensure that memory
consumption is minimized. You'll also want to scope your variables
-with my() whenever possible.
+with L<perlfunc/my> whenever possible.
package Embed::Persistent;
=head1 Embedding Perl under Win32
-At the time of this writing, there are two versions of Perl which run
-under Win32. Interfacing to Activeware's Perl library is quite
-different from the examples in this documentation, as significant
-changes were made to the internal Perl API. However, it is possible
-to embed Activeware's Perl runtime, see the Perl for Win32 FAQ:
-http://www.perl.com/perl/faq/win32/Perl_for_Win32_FAQ.html
+At the time of this writing (5.004), there are two versions of Perl
+which run under Win32. (The two versions are merging in 5.005.)
+Interfacing to ActiveState's Perl library is quite different from the
+examples in this documentation, as significant changes were made to
+the internal Perl API. However, it is possible to embed ActiveState's
+Perl runtime. For details, see the Perl for Win32 FAQ at
+http://www.perl.com/perl/faq/win32/Perl_for_Win32_FAQ.html.
With the "official" Perl version 5.004 or higher, all the examples
-within this documentation will compile and run untouched, although,
+within this documentation will compile and run untouched, although
the build process is slightly different between Unix and Win32.
-For starters, backticks don't work under the Win32 native command shell!
+For starters, backticks don't work under the Win32 native command shell.
The ExtUtils::Embed kit on CPAN ships with a script called
B<genmake>, which generates a simple makefile to build a program from
-a single C source file. It can be used like so:
+a single C source file. It can be used like this:
C:\ExtUtils-Embed\eg> perl genmake interp.c
C:\ExtUtils-Embed\eg> nmake
C:\ExtUtils-Embed\eg> interp -e "print qq{I'm embedded in Win32!\n}"
-You may wish to use a more robust environment such as the MS Developer
-stdio. In this case, to generate perlxsi.c run:
+You may wish to use a more robust environment such as the Microsoft
+Developer Studio. In this case, run this to generate perlxsi.c:
perl -MExtUtils::Embed -e xsinit
-Create a new project, Insert -> Files into Project: perlxsi.c, perl.lib,
-and your own source files, e.g. interp.c. Typically you'll find
-perl.lib in B<C:\perl\lib\CORE>, if not, you should see the B<CORE>
-directory relative to C<perl -V:archlib>.
-The studio will also need this path so it knows where to find Perl
-include files. This path can be added via the Tools -> Options ->
-Directories menu. Finnally, select Build -> Build interp.exe and
-you're ready to go!
+Create a new project and Insert -> Files into Project: perlxsi.c,
+perl.lib, and your own source files, e.g. interp.c. Typically you'll
+find perl.lib in B<C:\perl\lib\CORE>, if not, you should see the
+B<CORE> directory relative to C<perl -V:archlib>. The studio will
+also need this path so it knows where to find Perl include files.
+This path can be added via the Tools -> Options -> Directories menu.
+Finally, select Build -> Build interp.exe and you're ready to go.
=head1 MORAL
=head1 AUTHOR
-Jon Orwant and <F<orwant@tpj.com>> and Doug MacEachern <F<dougm@osf.org>>,
-with small contributions from Tim Bunce, Tom Christiansen, Hallvard Furuseth,
-Dov Grobgeld, and Ilya Zakharevich.
-
-Check out Doug's article on embedding in Volume 1, Issue 4 of The Perl
-Journal. Info about TPJ is available from http://tpj.com.
+Jon Orwant <F<orwant@tpj.com>> and Doug MacEachern
+<F<dougm@osf.org>>, with small contributions from Tim Bunce, Tom
+Christiansen, Guy Decoux, Hallvard Furuseth, Dov Grobgeld, and Ilya
+Zakharevich.
-July 17, 1997
+Doug MacEachern has an article on embedding in Volume 1, Issue 4 of
+The Perl Journal (http://tpj.com). Doug is also the developer of the
+most widely-used Perl embedding: the mod_perl system
+(perl.apache.org), which embeds Perl in the Apache web server.
+Oracle, Binary Evolution, ActiveState, and Ben Sugars's nsapi_perl
+have used this model for Oracle, Netscape and Internet Information
+Server Perl plugins.
-Some of this material is excerpted from Jon Orwant's book: I<Perl 5
-Interactive>, Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
-courtesy of Waite Group Press.
+July 22, 1998
=head1 COPYRIGHT
-Copyright (C) 1995, 1996, 1997 Doug MacEachern and Jon Orwant. All
+Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
Rights Reserved.
-Although destined for release with the standard Perl distribution,
-this document is not public domain, nor is any of Perl and its
-documentation. Permission is granted to freely distribute verbatim
-copies of this document provided that no modifications outside of
-formatting be made, and that this notice remain intact. You are
-permitted and encouraged to use its code and derivatives thereof in
-your own source code for fun or for profit as you see fit.
+Permission is granted to make and distribute verbatim copies of this
+documentation provided the copyright notice and this permission notice are
+preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+documentation under the conditions for verbatim copying, provided also
+that they are marked clearly as modified versions, that the authors'
+names and title are unchanged (though subtitles and additional
+authors' names may be added), and that the entire resulting derived
+work is distributed under the terms of a permission notice identical
+to this one.
+
+Permission is granted to copy and distribute translations of this
+documentation into another language, under the above conditions for
+modified versions.
projects / platform / upstream / perl.git / commitdiff