diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/h2xs.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/h2xs.1 | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/h2xs.1 b/upstream/mageia-cauldron/man1/h2xs.1 new file mode 100644 index 00000000..aebd24b0 --- /dev/null +++ b/upstream/mageia-cauldron/man1/h2xs.1 @@ -0,0 +1,482 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "H2XS 1" +.TH H2XS 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +h2xs \- convert .h C header files to Perl extensions +.SH SYNOPSIS +.IX Header "SYNOPSIS" +\&\fBh2xs\fR [\fBOPTIONS\fR ...] [headerfile ... [extra_libraries]] +.PP +\&\fBh2xs\fR \fB\-h\fR|\fB\-?\fR|\fB\-\-help\fR +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fIh2xs\fR builds a Perl extension from C header files. The extension +will include functions which can be used to retrieve the value of any +#define statement which was in the C header files. +.PP +The \fImodule_name\fR will be used for the name of the extension. If +module_name is not supplied then the name of the first header file +will be used, with the first character capitalized. +.PP +If the extension might need extra libraries, they should be included +here. The extension Makefile.PL will take care of checking whether +the libraries actually exist and how they should be loaded. The extra +libraries should be specified in the form \-lm \-lposix, etc, just as on +the cc command line. By default, the Makefile.PL will search through +the library path determined by Configure. That path can be augmented +by including arguments of the form \fB\-L/another/library/path\fR in the +extra-libraries argument. +.PP +In spite of its name, \fIh2xs\fR may also be used to create a skeleton pure +Perl module. See the \fB\-X\fR option. +.SH OPTIONS +.IX Header "OPTIONS" +.IP "\fB\-A\fR, \fB\-\-omit\-autoload\fR" 5 +.IX Item "-A, --omit-autoload" +Omit all autoload facilities. This is the same as \fB\-c\fR but also +removes the \f(CW\*(C`use\ AutoLoader\*(C'\fR statement from the .pm file. +.IP "\fB\-B\fR, \fB\-\-beta\-version\fR" 5 +.IX Item "-B, --beta-version" +Use an alpha/beta style version number. Causes version number to +be "0.00_01" unless \fB\-v\fR is specified. +.IP "\fB\-C\fR, \fB\-\-omit\-changes\fR" 5 +.IX Item "-C, --omit-changes" +Omits creation of the \fIChanges\fR file, and adds a HISTORY section to +the POD template. +.IP "\fB\-F\fR, \fB\-\-cpp\-flags\fR=\fIaddflags\fR" 5 +.IX Item "-F, --cpp-flags=addflags" +Additional flags to specify to C preprocessor when scanning header for +function declarations. Writes these options in the generated \fIMakefile.PL\fR +too. +.IP "\fB\-M\fR, \fB\-\-func\-mask\fR=\fIregular expression\fR" 5 +.IX Item "-M, --func-mask=regular expression" +selects functions/macros to process. +.IP "\fB\-O\fR, \fB\-\-overwrite\-ok\fR" 5 +.IX Item "-O, --overwrite-ok" +Allows a pre-existing extension directory to be overwritten. +.IP "\fB\-P\fR, \fB\-\-omit\-pod\fR" 5 +.IX Item "-P, --omit-pod" +Omit the autogenerated stub POD section. +.IP "\fB\-X\fR, \fB\-\-omit\-XS\fR" 5 +.IX Item "-X, --omit-XS" +Omit the XS portion. Used to generate a skeleton pure Perl module. +\&\f(CW\*(C`\-c\*(C'\fR and \f(CW\*(C`\-f\*(C'\fR are implicitly enabled. +.IP "\fB\-a\fR, \fB\-\-gen\-accessors\fR" 5 +.IX Item "-a, --gen-accessors" +Generate an accessor method for each element of structs and unions. The +generated methods are named after the element name; will return the current +value of the element if called without additional arguments; and will set +the element to the supplied value (and return the new value) if called with +an additional argument. Embedded structures and unions are returned as a +pointer rather than the complete structure, to facilitate chained calls. +.Sp +These methods all apply to the Ptr type for the structure; additionally +two methods are constructed for the structure type itself, \f(CW\*(C`_to_ptr\*(C'\fR +which returns a Ptr type pointing to the same structure, and a \f(CW\*(C`new\*(C'\fR +method to construct and return a new structure, initialised to zeroes. +.IP "\fB\-b\fR, \fB\-\-compat\-version\fR=\fIversion\fR" 5 +.IX Item "-b, --compat-version=version" +Generates a .pm file which is backwards compatible with the specified +perl version. +.Sp +For versions < 5.6.0, the changes are. + \- no use of 'our' (uses 'use vars' instead) + \- no 'use warnings' +.Sp +Specifying a compatibility version higher than the version of perl you +are using to run h2xs will have no effect. If unspecified h2xs will default +to compatibility with the version of perl you are using to run h2xs. +.IP "\fB\-c\fR, \fB\-\-omit\-constant\fR" 5 +.IX Item "-c, --omit-constant" +Omit \f(CWconstant()\fR from the .xs file and corresponding specialised +\&\f(CW\*(C`AUTOLOAD\*(C'\fR from the .pm file. +.IP "\fB\-d\fR, \fB\-\-debugging\fR" 5 +.IX Item "-d, --debugging" +Turn on debugging messages. +.IP "\fB\-e\fR, \fB\-\-omit\-enums\fR=[\fIregular expression\fR]" 5 +.IX Item "-e, --omit-enums=[regular expression]" +If \fIregular expression\fR is not given, skip all constants that are defined in +a C enumeration. Otherwise skip only those constants that are defined in an +enum whose name matches \fIregular expression\fR. +.Sp +Since \fIregular expression\fR is optional, make sure that this switch is followed +by at least one other switch if you omit \fIregular expression\fR and have some +pending arguments such as header-file names. This is ok: +.Sp +.Vb 1 +\& h2xs \-e \-n Module::Foo foo.h +.Ve +.Sp +This is not ok: +.Sp +.Vb 1 +\& h2xs \-n Module::Foo \-e foo.h +.Ve +.Sp +In the latter, foo.h is taken as \fIregular expression\fR. +.IP "\fB\-f\fR, \fB\-\-force\fR" 5 +.IX Item "-f, --force" +Allows an extension to be created for a header even if that header is +not found in standard include directories. +.IP "\fB\-g\fR, \fB\-\-global\fR" 5 +.IX Item "-g, --global" +Include code for safely storing static data in the .xs file. +Extensions that do no make use of static data can ignore this option. +.IP "\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR" 5 +.IX Item "-h, -?, --help" +Print the usage, help and version for this h2xs and exit. +.IP "\fB\-k\fR, \fB\-\-omit\-const\-func\fR" 5 +.IX Item "-k, --omit-const-func" +For function arguments declared as \f(CW\*(C`const\*(C'\fR, omit the const attribute in the +generated XS code. +.IP "\fB\-m\fR, \fB\-\-gen\-tied\-var\fR" 5 +.IX Item "-m, --gen-tied-var" +\&\fBExperimental\fR: for each variable declared in the header file(s), declare +a perl variable of the same name magically tied to the C variable. +.IP "\fB\-n\fR, \fB\-\-name\fR=\fImodule_name\fR" 5 +.IX Item "-n, --name=module_name" +Specifies a name to be used for the extension, e.g., \-n\ RPC::DCE +.IP "\fB\-o\fR, \fB\-\-opaque\-re\fR=\fIregular expression\fR" 5 +.IX Item "-o, --opaque-re=regular expression" +Use "opaque" data type for the C types matched by the regular +expression, even if these types are \f(CW\*(C`typedef\*(C'\fR\-equivalent to types +from typemaps. Should not be used without \fB\-x\fR. +.Sp +This may be useful since, say, types which are \f(CW\*(C`typedef\*(C'\fR\-equivalent +to integers may represent OS-related handles, and one may want to work +with these handles in OO-way, as in \f(CW\*(C`$handle\->do_something()\*(C'\fR. +Use \f(CW\*(C`\-o .\*(C'\fR if you want to handle all the \f(CW\*(C`typedef\*(C'\fRed types as opaque +types. +.Sp +The type-to-match is whitewashed (except for commas, which have no +whitespace before them, and multiple \f(CW\*(C`*\*(C'\fR which have no whitespace +between them). +.IP "\fB\-p\fR, \fB\-\-remove\-prefix\fR=\fIprefix\fR" 5 +.IX Item "-p, --remove-prefix=prefix" +Specify a prefix which should be removed from the Perl function names, +e.g., \-p\ sec_rgy_ This sets up the XS \fBPREFIX\fR keyword and removes +the prefix from functions that are autoloaded via the \f(CWconstant()\fR +mechanism. +.IP "\fB\-s\fR, \fB\-\-const\-subs\fR=\fIsub1,sub2\fR" 5 +.IX Item "-s, --const-subs=sub1,sub2" +Create a perl subroutine for the specified macros rather than autoload +with the \fBconstant()\fR subroutine. These macros are assumed to have a +return type of \fBchar *\fR, e.g., +\&\-s\ sec_rgy_wildcard_name,sec_rgy_wildcard_sid. +.IP "\fB\-t\fR, \fB\-\-default\-type\fR=\fItype\fR" 5 +.IX Item "-t, --default-type=type" +Specify the internal type that the \fBconstant()\fR mechanism uses for macros. +The default is IV (signed integer). Currently all macros found during the +header scanning process will be assumed to have this type. Future versions +of \f(CW\*(C`h2xs\*(C'\fR may gain the ability to make educated guesses. +.IP \fB\-\-use\-new\-tests\fR 5 +.IX Item "--use-new-tests" +When \fB\-\-compat\-version\fR (\fB\-b\fR) is present the generated tests will use +\&\f(CW\*(C`Test::More\*(C'\fR rather than \f(CW\*(C`Test\*(C'\fR which is the default for versions before +5.6.2. \f(CW\*(C`Test::More\*(C'\fR will be added to PREREQ_PM in the generated +\&\f(CW\*(C`Makefile.PL\*(C'\fR. +.IP \fB\-\-use\-old\-tests\fR 5 +.IX Item "--use-old-tests" +Will force the generation of test code that uses the older \f(CW\*(C`Test\*(C'\fR module. +.IP \fB\-\-skip\-exporter\fR 5 +.IX Item "--skip-exporter" +Do not use \f(CW\*(C`Exporter\*(C'\fR and/or export any symbol. +.IP \fB\-\-skip\-ppport\fR 5 +.IX Item "--skip-ppport" +Do not use \f(CW\*(C`Devel::PPPort\*(C'\fR: no portability to older version. +.IP \fB\-\-skip\-autoloader\fR 5 +.IX Item "--skip-autoloader" +Do not use the module \f(CW\*(C`AutoLoader\*(C'\fR; but keep the \fBconstant()\fR function +and \f(CW\*(C`sub AUTOLOAD\*(C'\fR for constants. +.IP \fB\-\-skip\-strict\fR 5 +.IX Item "--skip-strict" +Do not use the pragma \f(CW\*(C`strict\*(C'\fR. +.IP \fB\-\-skip\-warnings\fR 5 +.IX Item "--skip-warnings" +Do not use the pragma \f(CW\*(C`warnings\*(C'\fR. +.IP "\fB\-v\fR, \fB\-\-version\fR=\fIversion\fR" 5 +.IX Item "-v, --version=version" +Specify a version number for this extension. This version number is added +to the templates. The default is 0.01, or 0.00_01 if \f(CW\*(C`\-B\*(C'\fR is specified. +The version specified should be numeric. +.IP "\fB\-x\fR, \fB\-\-autogen\-xsubs\fR" 5 +.IX Item "-x, --autogen-xsubs" +Automatically generate XSUBs basing on function declarations in the +header file. The package \f(CW\*(C`C::Scan\*(C'\fR should be installed. If this +option is specified, the name of the header file may look like +\&\f(CW\*(C`NAME1,NAME2\*(C'\fR. In this case NAME1 is used instead of the specified +string, but XSUBs are emitted only for the declarations included from +file NAME2. +.Sp +Note that some types of arguments/return\-values for functions may +result in XSUB\-declarations/typemap\-entries which need +hand-editing. Such may be objects which cannot be converted from/to a +pointer (like \f(CW\*(C`long long\*(C'\fR), pointers to functions, or arrays. See +also the section on "LIMITATIONS of \fB\-x\fR". +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 2 +\& # Default behavior, extension is Rusers +\& h2xs rpcsvc/rusers +\& +\& # Same, but extension is RUSERS +\& h2xs \-n RUSERS rpcsvc/rusers +\& +\& # Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h> +\& h2xs rpcsvc::rusers +\& +\& # Extension is ONC::RPC. Still finds <rpcsvc/rusers.h> +\& h2xs \-n ONC::RPC rpcsvc/rusers +\& +\& # Without constant() or AUTOLOAD +\& h2xs \-c rpcsvc/rusers +\& +\& # Creates templates for an extension named RPC +\& h2xs \-cfn RPC +\& +\& # Extension is ONC::RPC. +\& h2xs \-cfn ONC::RPC +\& +\& # Extension is a pure Perl module with no XS code. +\& h2xs \-X My::Module +\& +\& # Extension is Lib::Foo which works at least with Perl5.005_03. +\& # Constants are created for all #defines and enums h2xs can find +\& # in foo.h. +\& h2xs \-b 5.5.3 \-n Lib::Foo foo.h +\& +\& # Extension is Lib::Foo which works at least with Perl5.005_03. +\& # Constants are created for all #defines but only for enums +\& # whose names do not start with \*(Aqbar_\*(Aq. +\& h2xs \-b 5.5.3 \-e \*(Aq^bar_\*(Aq \-n Lib::Foo foo.h +\& +\& # Makefile.PL will look for library \-lrpc in +\& # additional directory /opt/net/lib +\& h2xs rpcsvc/rusers \-L/opt/net/lib \-lrpc +\& +\& # Extension is DCE::rgynbase +\& # prefix "sec_rgy_" is dropped from perl function names +\& h2xs \-n DCE::rgynbase \-p sec_rgy_ dce/rgynbase +\& +\& # Extension is DCE::rgynbase +\& # prefix "sec_rgy_" is dropped from perl function names +\& # subroutines are created for sec_rgy_wildcard_name and +\& # sec_rgy_wildcard_sid +\& h2xs \-n DCE::rgynbase \-p sec_rgy_ \e +\& \-s sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase +\& +\& # Make XS without defines in perl.h, but with function declarations +\& # visible from perl.h. Name of the extension is perl1. +\& # When scanning perl.h, define \-DEXT=extern \-DdEXT= \-DINIT(x)= +\& # Extra backslashes below because the string is passed to shell. +\& # Note that a directory with perl header files would +\& # be added automatically to include path. +\& h2xs \-xAn perl1 \-F "\-DEXT=extern \-DdEXT= \-DINIT\e(x\e)=" perl.h +\& +\& # Same with function declaration in proto.h as visible from perl.h. +\& h2xs \-xAn perl2 perl.h,proto.h +\& +\& # Same but select only functions which match /^av_/ +\& h2xs \-M \*(Aq^av_\*(Aq \-xAn perl2 perl.h,proto.h +\& +\& # Same but treat SV* etc as "opaque" types +\& h2xs \-o \*(Aq^[S]V \e*$\*(Aq \-M \*(Aq^av_\*(Aq \-xAn perl2 perl.h,proto.h +.Ve +.SS "Extension based on \fI.h\fP and \fI.c\fP files" +.IX Subsection "Extension based on .h and .c files" +Suppose that you have some C files implementing some functionality, +and the corresponding header files. How to create an extension which +makes this functionality accessible in Perl? The example below +assumes that the header files are \fIinterface_simple.h\fR and +\&\fIinterface_hairy.h\fR, and you want the perl module be named as +\&\f(CW\*(C`Ext::Ension\*(C'\fR. If you need some preprocessor directives and/or +linking with external libraries, see the flags \f(CW\*(C`\-F\*(C'\fR, \f(CW\*(C`\-L\*(C'\fR and \f(CW\*(C`\-l\*(C'\fR +in "OPTIONS". +.IP "Find the directory name" 4 +.IX Item "Find the directory name" +Start with a dummy run of h2xs: +.Sp +.Vb 1 +\& h2xs \-Afn Ext::Ension +.Ve +.Sp +The only purpose of this step is to create the needed directories, and +let you know the names of these directories. From the output you can +see that the directory for the extension is \fIExt/Ension\fR. +.IP "Copy C files" 4 +.IX Item "Copy C files" +Copy your header files and C files to this directory \fIExt/Ension\fR. +.IP "Create the extension" 4 +.IX Item "Create the extension" +Run h2xs, overwriting older autogenerated files: +.Sp +.Vb 1 +\& h2xs \-Oxan Ext::Ension interface_simple.h interface_hairy.h +.Ve +.Sp +h2xs looks for header files \fIafter\fR changing to the extension +directory, so it will find your header files OK. +.IP "Archive and test" 4 +.IX Item "Archive and test" +As usual, run +.Sp +.Vb 5 +\& cd Ext/Ension +\& perl Makefile.PL +\& make dist +\& make +\& make test +.Ve +.IP Hints 4 +.IX Item "Hints" +It is important to do \f(CW\*(C`make dist\*(C'\fR as early as possible. This way you +can easily \fBmerge\fR\|(1) your changes to autogenerated files if you decide +to edit your \f(CW\*(C`.h\*(C'\fR files and rerun h2xs. +.Sp +Do not forget to edit the documentation in the generated \fI.pm\fR file. +.Sp +Consider the autogenerated files as skeletons only, you may invent +better interfaces than what h2xs could guess. +.Sp +Consider this section as a guideline only, some other options of h2xs +may better suit your needs. +.SH ENVIRONMENT +.IX Header "ENVIRONMENT" +No environment variables are used. +.SH AUTHOR +.IX Header "AUTHOR" +Larry Wall and others +.SH "SEE ALSO" +.IX Header "SEE ALSO" +perl, perlxstut, ExtUtils::MakeMaker, and AutoLoader. +.SH DIAGNOSTICS +.IX Header "DIAGNOSTICS" +The usual warnings if it cannot read or write the files involved. +.SH "LIMITATIONS of \fB\-x\fP" +.IX Header "LIMITATIONS of -x" +\&\fIh2xs\fR would not distinguish whether an argument to a C function +which is of the form, say, \f(CW\*(C`int *\*(C'\fR, is an input, output, or +input/output parameter. In particular, argument declarations of the +form +.PP +.Vb 3 +\& int +\& foo(n) +\& int *n +.Ve +.PP +should be better rewritten as +.PP +.Vb 3 +\& int +\& foo(n) +\& int &n +.Ve +.PP +if \f(CW\*(C`n\*(C'\fR is an input parameter. +.PP +Additionally, \fIh2xs\fR has no facilities to intuit that a function +.PP +.Vb 4 +\& int +\& foo(addr,l) +\& char *addr +\& int l +.Ve +.PP +takes a pair of address and length of data at this address, so it is better +to rewrite this function as +.PP +.Vb 11 +\& int +\& foo(sv) +\& SV *addr +\& PREINIT: +\& STRLEN len; +\& char *s; +\& CODE: +\& s = SvPV(sv,len); +\& RETVAL = foo(s, len); +\& OUTPUT: +\& RETVAL +.Ve +.PP +or alternately +.PP +.Vb 5 +\& static int +\& my_foo(SV *sv) +\& { +\& STRLEN len; +\& char *s = SvPV(sv,len); +\& +\& return foo(s, len); +\& } +\& +\& MODULE = foo PACKAGE = foo PREFIX = my_ +\& +\& int +\& foo(sv) +\& SV *sv +.Ve +.PP +See perlxs and perlxstut for additional details. |