home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _d5f4151053a7e860ec2ba2028da3055d < prev    next >
Text File  |  2000-03-23  |  10KB  |  218 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#@export">@EXPORT</A></LI>
  26.     <LI><A HREF="#functions">FUNCTIONS</A></LI>
  27.     <LI><A HREF="#examples">EXAMPLES</A></LI>
  28.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  29.     <LI><A HREF="#author">AUTHOR</A></LI>
  30. </UL>
  31. <!-- INDEX END -->
  32.  
  33. <HR>
  34. <P>
  35. <H1><A NAME="name">NAME</A></H1>
  36. <P>ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications</P>
  37. <P>
  38. <HR>
  39. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  40. <UL>
  41. <LI>Linux</LI>
  42. <LI>Solaris</LI>
  43. <LI>Windows</LI>
  44. </UL>
  45. <HR>
  46. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  47. <PRE>
  48.  perl -MExtUtils::Embed -e xsinit 
  49.  perl -MExtUtils::Embed -e ldopts</PRE>
  50. <P>
  51. <HR>
  52. <H1><A NAME="description">DESCRIPTION</A></H1>
  53. <P>ExtUtils::Embed provides utility functions for embedding a Perl interpreter
  54. and extensions in your C/C++ applications.  
  55. Typically, an application <STRONG>Makefile</STRONG> will invoke ExtUtils::Embed
  56. functions while building your application.</P>
  57. <P>
  58. <HR>
  59. <H1><A NAME="@export">@EXPORT</A></H1>
  60. <P>ExtUtils::Embed exports the following functions:</P>
  61. <P>xsinit(), ldopts(), ccopts(), perl_inc(), ccflags(), 
  62. ccdlflags(), xsi_header(), xsi_protos(), <A HREF="#item_xsi_body"><CODE>xsi_body()</CODE></A></P>
  63. <P>
  64. <HR>
  65. <H1><A NAME="functions">FUNCTIONS</A></H1>
  66. <DL>
  67. <DT><STRONG><A NAME="item_xsinit"><CODE>xsinit()</CODE></A></STRONG><BR>
  68. <DD>
  69. Generate C/C++ code for the XS initializer function.
  70. <P>When invoked as <CODE>`perl -MExtUtils::Embed -e xsinit --`</CODE>
  71. the following options are recognized:</P>
  72. <P><STRONG>-o</STRONG> <output filename> (Defaults to <STRONG>perlxsi.c</STRONG>)</P>
  73. <P><STRONG>-o STDOUT</STRONG> will print to STDOUT.</P>
  74. <P><STRONG>-std</STRONG> (Write code for extensions that are linked with the current Perl.)</P>
  75. <P>Any additional arguments are expected to be names of modules
  76. to generate code for.</P>
  77. <P>When invoked with parameters the following are accepted and optional:</P>
  78. <P><A HREF="#item_xsinit"><CODE>xsinit($filename,$std,[@modules])</CODE></A></P>
  79. <P>Where,</P>
  80. <P><STRONG>$filename</STRONG> is equivalent to the <STRONG>-o</STRONG> option.</P>
  81. <P><STRONG>$std</STRONG> is boolean, equivalent to the <STRONG>-std</STRONG> option.</P>
  82. <P><STRONG>[@modules]</STRONG> is an array ref, same as additional arguments mentioned above.</P>
  83. <P></P>
  84. <DT><STRONG><A NAME="item_Examples">Examples</A></STRONG><BR>
  85. <DD>
  86. <PRE>
  87.  perl -MExtUtils::Embed -e xsinit -- -o xsinit.c Socket</PRE>
  88. <P>This will generate code with an <STRONG>xs_init</STRONG> function that glues the perl <STRONG>Socket::bootstrap</STRONG> function 
  89. to the C <STRONG>boot_Socket</STRONG> function and writes it to a file named <EM>xsinit.c</EM>.</P>
  90. <P>Note that <STRONG>DynaLoader</STRONG> is a special case where it must call <STRONG>boot_DynaLoader</STRONG> directly.</P>
  91. <PRE>
  92.  perl -MExtUtils::Embed -e xsinit</PRE>
  93. <P>This will generate code for linking with <STRONG>DynaLoader</STRONG> and 
  94. each static extension found in <STRONG>$Config{static_ext}</STRONG>.
  95. The code is written to the default file name <STRONG>perlxsi.c</STRONG>.</P>
  96. <PRE>
  97.  perl -MExtUtils::Embed -e xsinit -- -o xsinit.c -std DBI DBD::Oracle</PRE>
  98. <P>Here, code is written for all the currently linked extensions along with code
  99. for <STRONG>DBI</STRONG> and <STRONG>DBD::Oracle</STRONG>.</P>
  100. <P>If you have a working <STRONG>DynaLoader</STRONG> then there is rarely any need to statically link in any 
  101. other extensions.</P>
  102. <DT><STRONG><A NAME="item_ldopts"><CODE>ldopts()</CODE></A></STRONG><BR>
  103. <DD>
  104. Output arguments for linking the Perl library and extensions to your
  105. application.
  106. <P>When invoked as <CODE>`perl -MExtUtils::Embed -e ldopts --`</CODE>
  107. the following options are recognized:</P>
  108. <P><STRONG>-std</STRONG></P>
  109. <P>Output arguments for linking the Perl library and any extensions linked
  110. with the current Perl.</P>
  111. <P><STRONG>-I</STRONG> <path1:path2></P>
  112. <P>Search path for ModuleName.a archives.  
  113. Default path is <STRONG>@INC</STRONG>.
  114. Library archives are expected to be found as 
  115. <STRONG>/some/path/auto/ModuleName/ModuleName.a</STRONG>
  116. For example, when looking for <STRONG>Socket.a</STRONG> relative to a search path, 
  117. we should find <STRONG>auto/Socket/Socket.a</STRONG></P>
  118. <P>When looking for <STRONG>DBD::Oracle</STRONG> relative to a search path,
  119. we should find <STRONG>auto/DBD/Oracle/Oracle.a</STRONG></P>
  120. <P>Keep in mind that you can always supply <STRONG>/my/own/path/ModuleName.a</STRONG>
  121. as an additional linker argument.</P>
  122. <P><STRONG>--</STRONG>  <list of linker args></P>
  123. <P>Additional linker arguments to be considered.</P>
  124. <P>Any additional arguments found before the <STRONG>--</STRONG> token 
  125. are expected to be names of modules to generate code for.</P>
  126. <P>When invoked with parameters the following are accepted and optional:</P>
  127. <P><A HREF="#item_ldopts"><CODE>ldopts($std,[@modules],[@link_args],$path)</CODE></A></P>
  128. <P>Where:</P>
  129. <P><STRONG>$std</STRONG> is boolean, equivalent to the <STRONG>-std</STRONG> option.</P>
  130. <P><STRONG>[@modules]</STRONG> is equivalent to additional arguments found before the <STRONG>--</STRONG> token.</P>
  131. <P><STRONG>[@link_args]</STRONG> is equivalent to arguments found after the <STRONG>--</STRONG> token.</P>
  132. <P><STRONG>$path</STRONG> is equivalent to the <STRONG>-I</STRONG> option.</P>
  133. <P>In addition, when ldopts is called with parameters, it will return the argument string
  134. rather than print it to STDOUT.</P>
  135. <P></P>
  136. <DT><STRONG>Examples</STRONG><BR>
  137. <DD>
  138. <PRE>
  139.  perl -MExtUtils::Embed -e ldopts</PRE>
  140. <P>This will print arguments for linking with <STRONG>libperl.a</STRONG>, <STRONG>DynaLoader</STRONG> and 
  141. extensions found in <STRONG>$Config{static_ext}</STRONG>.  This includes libraries
  142. found in <STRONG>$Config{libs}</STRONG> and the first ModuleName.a library
  143. for each extension that is found by searching <STRONG>@INC</STRONG> or the path 
  144. specified by the <STRONG>-I</STRONG> option.  
  145. In addition, when ModuleName.a is found, additional linker arguments
  146. are picked up from the <STRONG>extralibs.ld</STRONG> file in the same directory.</P>
  147. <PRE>
  148.  perl -MExtUtils::Embed -e ldopts -- -std Socket</PRE>
  149. <P>This will do the same as the above example, along with printing additional arguments for linking with the <STRONG>Socket</STRONG> extension.</P>
  150. <PRE>
  151.  perl -MExtUtils::Embed -e ldopts -- DynaLoader</PRE>
  152. <P>This will print arguments for linking with just the <STRONG>DynaLoader</STRONG> extension
  153. and <STRONG>libperl.a</STRONG>.</P>
  154. <PRE>
  155.  perl -MExtUtils::Embed -e ldopts -- -std Msql -- -L/usr/msql/lib -lmsql</PRE>
  156. <P>Any arguments after the second '--' token are additional linker
  157. arguments that will be examined for potential conflict.  If there is no
  158. conflict, the additional arguments will be part of the output.</P>
  159. <DT><STRONG><A NAME="item_perl_inc"><CODE>perl_inc()</CODE></A></STRONG><BR>
  160. <DD>
  161. For including perl header files this function simply prints:
  162. <PRE>
  163.  -I$Config{archlibexp}/CORE</PRE>
  164. <P>So, rather than having to say:</P>
  165. <PRE>
  166.  perl -MConfig -e 'print "-I$Config{archlibexp}/CORE"'</PRE>
  167. <P>Just say:</P>
  168. <PRE>
  169.  perl -MExtUtils::Embed -e perl_inc</PRE>
  170. <P></P>
  171. <DT><STRONG><A NAME="item_ccflags">ccflags(), <CODE>ccdlflags()</CODE></A></STRONG><BR>
  172. <DD>
  173. These functions simply print $Config{ccflags} and $Config{ccdlflags}
  174. <P></P>
  175. <DT><STRONG><A NAME="item_ccopts"><CODE>ccopts()</CODE></A></STRONG><BR>
  176. <DD>
  177. This function combines perl_inc(), <A HREF="#item_ccflags"><CODE>ccflags()</CODE></A> and <CODE>ccdlflags()</CODE> into one.
  178. <P></P>
  179. <DT><STRONG><A NAME="item_xsi_header"><CODE>xsi_header()</CODE></A></STRONG><BR>
  180. <DD>
  181. This function simply returns a string defining the same <STRONG>EXTERN_C</STRONG> macro as
  182. <STRONG>perlmain.c</STRONG> along with #including <STRONG>perl.h</STRONG> and <STRONG>EXTERN.h</STRONG>.
  183. <P></P>
  184. <DT><STRONG><A NAME="item_xsi_protos"><CODE>xsi_protos(@modules)</CODE></A></STRONG><BR>
  185. <DD>
  186. This function returns a string of <STRONG>boot_$ModuleName</STRONG> prototypes for each @modules.
  187. <P></P>
  188. <DT><STRONG><A NAME="item_xsi_body"><CODE>xsi_body(@modules)</CODE></A></STRONG><BR>
  189. <DD>
  190. This function returns a string of calls to <STRONG>newXS()</STRONG> that glue the module <STRONG>bootstrap</STRONG>
  191. function to <STRONG>boot_ModuleName</STRONG> for each @modules.
  192. <P><STRONG>xsinit()</STRONG> uses the xsi_* functions to generate most of it's code.</P>
  193. <P></P></DL>
  194. <P>
  195. <HR>
  196. <H1><A NAME="examples">EXAMPLES</A></H1>
  197. <P>For examples on how to use <STRONG>ExtUtils::Embed</STRONG> for building C/C++ applications
  198. with embedded perl, see the eg/ directory and <A HREF="../../lib/Pod/perlembed.html">the perlembed manpage</A>.</P>
  199. <P>
  200. <HR>
  201. <H1><A NAME="see also">SEE ALSO</A></H1>
  202. <P><A HREF="../../lib/Pod/perlembed.html">the perlembed manpage</A></P>
  203. <P>
  204. <HR>
  205. <H1><A NAME="author">AUTHOR</A></H1>
  206. <P>Doug MacEachern <<EM><A HREF="mailto:dougm@osf.org">dougm@osf.org</A></EM>></P>
  207. <P>Based on ideas from Tim Bunce <<EM><A HREF="mailto:Tim.Bunce@ig.co.uk">Tim.Bunce@ig.co.uk</A></EM>> and
  208. <STRONG>minimod.pl</STRONG> by Andreas Koenig <<EM><A HREF="mailto:k@anna.in-berlin.de">k@anna.in-berlin.de</A></EM>> and Tim Bunce.</P>
  209. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  210. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  211. <STRONG><P CLASS=block> ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications</P></STRONG>
  212. </TD></TR>
  213. </TABLE>
  214.  
  215. </BODY>
  216.  
  217. </HTML>
  218.