home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / u_man / cat1 / h2xs.z / h2xs
Encoding:
Text File  |  2002-10-03  |  7.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4. HHHH2222XXXXSSSS((((1111))))                                                                HHHH2222XXXXSSSS((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      h2xs - convert .h C header files to Perl extensions
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      hhhh2222xxxxssss [----AAAAOOOOPPPPXXXXccccddddffff] [----vvvv version] [----nnnn module_name] [----pppp prefix] [----ssss sub]
  13.      [headerfile ... [extra_libraries]]
  14.  
  15.      hhhh2222xxxxssss ----hhhh
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      _h_2_x_s builds a Perl extension from C header files.  The extension will
  19.      include functions which can be used to retrieve the value of any #define
  20.      statement which was in the C header files.
  21.  
  22.      The _m_o_d_u_l_e__n_a_m_e will be used for the name of the extension.  If
  23.      module_name is not supplied then the name of the first header file will
  24.      be used, with the first character capitalized.
  25.  
  26.      If the extension might need extra libraries, they should be included
  27.      here.  The extension Makefile.PL will take care of checking whether the
  28.      libraries actually exist and how they should be loaded.  The extra
  29.      libraries should be specified in the form -lm -lposix, etc, just as on
  30.      the cc command line.  By default, the Makefile.PL will search through the
  31.      library path determined by Configure.  That path can be augmented by
  32.      including arguments of the form ----LLLL////aaaannnnooootttthhhheeeerrrr////lllliiiibbbbrrrraaaarrrryyyy////ppppaaaatttthhhh in the extra-
  33.      libraries argument.
  34.  
  35. OOOOPPPPTTTTIIIIOOOONNNNSSSS
  36.      ----AAAA   Omit all autoload facilities.  This is the same as ----cccc but also
  37.           removes the require AutoLoader statement from the .pm file.
  38.  
  39.      ----FFFF   Additional flags to specify to C preprocessor when scanning header
  40.           for function declarations. Should not be used without ----xxxx.
  41.  
  42.      ----OOOO   Allows a pre-existing extension directory to be overwritten.
  43.  
  44.      ----PPPP   Omit the autogenerated stub POD section.
  45.  
  46.      ----XXXX   Omit the XS portion.  Used to generate templates for a module which
  47.           is not XS-based.
  48.  
  49.      ----cccc   Omit constant() from the .xs file and corresponding specialised
  50.           AUTOLOAD from the .pm file.
  51.  
  52.      ----dddd   Turn on debugging messages.
  53.  
  54.      ----ffff   Allows an extension to be created for a header even if that header
  55.           is not found in /usr/include.
  56.  
  57.      ----hhhh   Print the usage, help and version for this h2xs and exit.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. HHHH2222XXXXSSSS((((1111))))                                                                HHHH2222XXXXSSSS((((1111))))
  71.  
  72.  
  73.  
  74.      ----nnnn _m_o_d_u_l_e__n_a_m_e
  75.           Specifies a name to be used for the extension, e.g., -n RPC::DCE
  76.  
  77.      ----pppp _p_r_e_f_i_x
  78.           Specify a prefix which should be removed from the Perl function
  79.           names, e.g., -p sec_rgy_ This sets up the XS PPPPRRRREEEEFFFFIIIIXXXX keyword and
  80.           removes the prefix from functions that are autoloaded via the
  81.           constant() mechansim.
  82.  
  83.      ----ssss _s_u_b_1,_s_u_b_2
  84.           Create a perl subroutine for the specified macros rather than
  85.           autoload with the _c_o_n_s_t_a_n_t() subroutine.  These macros are assumed
  86.           to have a return type of cccchhhhaaaarrrr ****, e.g.,
  87.           -s sec_rgy_wildcard_name,sec_rgy_wildcard_sid.
  88.  
  89.      ----vvvv _v_e_r_s_i_o_n
  90.           Specify a version number for this extension.  This version number is
  91.           added to the templates.  The default is 0.01.
  92.  
  93.      ----xxxx   Automatically generate XSUBs basing on function declarations in the
  94.           header file.  The package C::Scan should be installed. If this
  95.           option is specified, the name of the header file may look like
  96.           NAME1,NAME2. In this case NAME1 is used instead of the specified
  97.           string, but XSUBs are emitted only for the declarations included
  98.           from file NAME2.
  99.  
  100.           Note that some types of arguments/return-values for functions may
  101.           result in XSUB-declarations/typemap-entries which need hand-editing.
  102.           Such may be objects which cannot be converted from/to a pointer
  103.           (like long long), pointers to functions, or arrays.
  104.  
  105. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  106.              # Default behavior, extension is Rusers
  107.              h2xs rpcsvc/rusers
  108.  
  109.              # Same, but extension is RUSERS
  110.              h2xs -n RUSERS rpcsvc/rusers
  111.  
  112.              # Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h>
  113.              h2xs rpcsvc::rusers
  114.  
  115.              # Extension is ONC::RPC.  Still finds <rpcsvc/rusers.h>
  116.              h2xs -n ONC::RPC rpcsvc/rusers
  117.  
  118.              # Without constant() or AUTOLOAD
  119.              h2xs -c rpcsvc/rusers
  120.  
  121.              # Creates templates for an extension named RPC
  122.              h2xs -cfn RPC
  123.  
  124.              # Extension is ONC::RPC.
  125.              h2xs -cfn ONC::RPC
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. HHHH2222XXXXSSSS((((1111))))                                                                HHHH2222XXXXSSSS((((1111))))
  137.  
  138.  
  139.  
  140.              # Makefile.PL will look for library -lrpc in
  141.              # additional directory /opt/net/lib
  142.              h2xs rpcsvc/rusers -L/opt/net/lib -lrpc
  143.  
  144.              # Extension is DCE::rgynbase
  145.              # prefix "sec_rgy_" is dropped from perl function names
  146.              h2xs -n DCE::rgynbase -p sec_rgy_ dce/rgynbase
  147.  
  148.              # Extension is DCE::rgynbase
  149.              # prefix "sec_rgy_" is dropped from perl function names
  150.              # subroutines are created for sec_rgy_wildcard_name and sec_rgy_wildcard_sid
  151.              h2xs -n DCE::rgynbase -p sec_rgy_ \
  152.              -s sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase
  153.  
  154.              # Make XS without defines in perl.h, but with function declarations
  155.              # visible from perl.h. Name of the extension is perl1.
  156.              # When scanning perl.h, define -DEXT=extern -DdEXT= -DINIT(x)=
  157.              # Extra backslashes below because the string is passed to shell.
  158.              # Note that a directory with perl header files would
  159.              #  be added automatically to include path.
  160.              h2xs -xAn perl1 -F "-DEXT=extern -DdEXT= -DINIT\(x\)=" perl.h
  161.  
  162.              # Same with function declaration in proto.h as visible from perl.h.
  163.              h2xs -xAn perl2 perl.h,proto.h
  164.  
  165.  
  166. EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT
  167.      No environment variables are used.
  168.  
  169. AAAAUUUUTTTTHHHHOOOORRRR
  170.      Larry Wall and others
  171.  
  172. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  173.      the _p_e_r_l manpage, the _p_e_r_l_x_s_t_u_t manpage, the _E_x_t_U_t_i_l_s::_M_a_k_e_M_a_k_e_r manpage,
  174.      and the _A_u_t_o_L_o_a_d_e_r manpage.
  175.  
  176. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  177.      The usual warnings if it cannot read or write the files involved.
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. HHHH2222XXXXSSSS((((1111))))                                                                HHHH2222XXXXSSSS((((1111))))
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.                                                                         PPPPaaaaggggeeee 4444
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.