# This forces PL files to create target in same directory as PL file.
# This is so that make depend always knows where to find PL derivatives.
-$origdir = cwd;
+my $origdir = cwd;
chdir dirname($0);
-$file = basename($0, '.PL');
+my $file = basename($0, '.PL');
$file .= '.com' if $^O eq 'VMS';
open OUT,">$file" or die "Can't create $file: $!";
=head1 SYNOPSIS
-B<h2xs> [B<-ACOPXcdf>] [B<-v> version] [B<-n> module_name] [B<-p> prefix] [B<-s> sub] [headerfile ... [extra_libraries]]
+B<h2xs> [B<-ACOPXacdfkmx>] [B<-F> addflags] [B<-M> fmask] [B<-n> module_name] [B<-o> tmask] [B<-p> prefix] [B<-s> subs] [B<-v> version] [headerfile ... [extra_libraries]]
B<h2xs> B<-h>
Omits creation of the F<Changes> file, and adds a HISTORY section to
the POD template.
-=item B<-F>
+=item B<-F> I<addflags>
Additional flags to specify to C preprocessor when scanning header for
function declarations. Should not be used without B<-x>.
pointer (like C<long long>), pointers to functions, or arrays. See
also the section on L<LIMITATIONS of B<-x>>.
+=item B<-b> I<version>
+
+Generates a .pm file which is backwards compatible with the specified
+perl version.
+
+For versions < 5.6.0, the changes are.
+ - no use of 'our' (uses 'use vars' instead)
+ - no 'use warnings'
+
+Specifying a compatibility version higher than the version of perl you
+are using to run h2xs will have no effect.
+
=back
=head1 EXAMPLES
# Same but treat SV* etc as "opaque" types
h2xs -o '^[S]V \*$' -M '^av_' -xAn perl2 perl.h,proto.h
+=head2 Extension based on F<.h> and F<.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 accessable in Perl? The example below
+assumes that the header files are F<interface_simple.h> and
+I<interface_hairy.h>, and you want the perl module be named as
+C<Ext::Ension>. If you need some preprocessor directives and/or
+linking with external libraries, see the flags C<-F>, C<-L> and C<-l>
+in L<"OPTIONS">.
+
+=over
+
+=item Find the directory name
+
+Start with a dummy run of h2xs:
+
+ h2xs -Afn Ext::Ension
+
+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 F<Ext/Ension>.
+
+=item Copy C files
+
+Copy your header files and C files to this directory F<Ext/Ension>.
+
+=item Create the extension
+
+Run h2xs, overwriting older autogenerated files:
+
+ h2xs -Oxan Ext::Ension interface_simple.h interface_hairy.h
+
+h2xs looks for header files I<after> changing to the extension
+directory, so it will find your header files OK.
+
+=item Archive and test
+
+As usual, run
+
+ cd Ext/Ension
+ perl Makefile.PL
+ make dist
+ make
+ make test
+
+=item Hints
+
+It is important to do C<make dist> as early as possible. This way you
+can easily merge(1) your changes to autogenerated files if you decide
+to edit your C<.h> files and rerun h2xs.
+
+Do not forget to edit the documentation in the generated F<.pm> file.
+
+Consider the autogenerated files as skeletons only, you may invent
+better interfaces than what h2xs could guess.
+
+Consider this section as a guideline only, some other options of h2xs
+may better suit your needs.
+
+=back
+
=head1 ENVIRONMENT
No environment variables are used.
my( $H2XS_VERSION ) = ' $Revision: 1.20 $ ' =~ /\$Revision:\s+([^\s]+)/;
my $TEMPLATE_VERSION = '0.01';
my @ARGS = @ARGV;
+my $compat_version = $];
use Getopt::Std;
sub usage{
warn "@_\n" if @_;
- die "h2xs [-ACOPXcdfh] [-v version] [-n module_name] [-p prefix] [-s subs] [headerfile [extra_libraries]]
+ die "h2xs [-ACOPXacdfhkmx] [-F addflags] [-M fmask] [-n module_name] [-o tmask] [-p prefix] [-s subs] [-v version] [headerfile [extra_libraries]]
version: $H2XS_VERSION
-A Omit all autoloading facilities (implies -c).
-C Omit creating the Changes file, add HISTORY heading to stub POD.
-s Create subroutines for specified macros.
-v Specify a version number for this extension.
-x Autogenerate XSUBs using C::Scan.
+ -b Specify a perl version to be backwards compatibile with
extra_libraries
are any libraries that might be needed for loading the
extension, e.g. -lm would try to link in the math library.
}
-getopts("ACF:M:OPXacdfhkmn:o:p:s:v:x") || usage;
+getopts("ACF:M:OPXacdfhkmn:o:p:s:v:xb:") || usage;
use vars qw($opt_A $opt_C $opt_F $opt_M $opt_O $opt_P $opt_X $opt_a $opt_c $opt_d
- $opt_f $opt_h $opt_k $opt_m $opt_n $opt_o $opt_p $opt_s $opt_v $opt_x);
+ $opt_f $opt_h $opt_k $opt_m $opt_n $opt_o $opt_p $opt_s $opt_v $opt_x
+ $opt_b);
usage if $opt_h;
+if( $opt_b ){
+ usage "You cannot use -b and -m at the same time.\n" if ($opt_b && $opt_m);
+ $opt_b =~ /^\d+\.\d+\.\d+/ ||
+ usage "You must provide the backwards compatibility version in X.Y.Z form. " .
+ "(i.e. 5.5.0)\n";
+ my ($maj,$min,$sub) = split(/\./,$opt_b,3);
+ $compat_version = sprintf("%d.%03d%02d",$maj,$min,$sub);
+}
+
if( $opt_v ){
$TEMPLATE_VERSION = $opt_v;
}
$" = "\n\t";
warn "Writing $ext$modpname/$modfname.pm\n";
+if ( $compat_version < 5.006 ) {
print PM <<"END";
package $module;
-require 5.005_62;
+use $compat_version;
+use strict;
+END
+}
+else {
+print PM <<"END";
+package $module;
+
+use 5.006;
use strict;
use warnings;
END
+}
unless( $opt_X || $opt_c || $opt_A ){
# we'll have an AUTOLOAD(), and it will have $AUTOLOAD and
}
}
+if ( $compat_version < 5.006 ) {
+ if ( $opt_X || $opt_c || $opt_A ) {
+ print PM 'use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);';
+ } else {
+ print PM 'use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $AUTOLOAD);';
+ }
+}
+
# Determine @ISA.
my $myISA = 'our @ISA = qw(Exporter'; # We seem to always want this.
$myISA .= ' DynaLoader' unless $opt_X; # no XS
$myISA .= ');';
+$myISA =~ s/^our // if $compat_version < 5.006;
+
print PM "\n$myISA\n\n";
my @exported_names = (@const_names, @fnames_no_prefix, map '$'.$_, @vdecls);
-print PM<<"END";
+my $tmp=<<"END";
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
END
+$tmp =~ s/^our //mg if $compat_version < 5.006;
+print PM $tmp;
+
if (@vdecls) {
printf PM "our(@{[ join ', ', map '$'.$_, @vdecls ]});\n\n";
}
+
+$tmp = ( $compat_version < 5.006 ? "" : "our \$AUTOLOAD;" );
print PM <<"END" unless $opt_c or $opt_X;
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
# to the AUTOLOAD in AutoLoader.
my \$constname;
- our \$AUTOLOAD;
+ $tmp
(\$constname = \$AUTOLOAD) =~ s/.*:://;
croak "&$module::constant not defined" if \$constname eq 'constant';
my \$val = constant(\$constname, \@_ ? \$_[0] : 0);
my $revhist = '';
$revhist = <<EOT if $opt_C;
-
-=head1 HISTORY
-
-=over 8
-
-=item $TEMPLATE_VERSION
-
-Original version; created by h2xs $H2XS_VERSION with options
-
- @ARGS
-
-=back
-
+#
+#=head1 HISTORY
+#
+#=over 8
+#
+#=item $TEMPLATE_VERSION
+#
+#Original version; created by h2xs $H2XS_VERSION with options
+#
+# @ARGS
+#
+#=back
+#
EOT
my $exp_doc = <<EOD;
-
-=head2 EXPORT
-
-None by default.
-
+#
+#=head2 EXPORT
+#
+#None by default.
+#
EOD
+
if (@const_names and not $opt_P) {
$exp_doc .= <<EOD;
-=head2 Exportable constants
-
- @{[join "\n ", @const_names]}
-
+#=head2 Exportable constants
+#
+# @{[join "\n ", @const_names]}
+#
EOD
}
+
if (defined $fdecls and @$fdecls and not $opt_P) {
$exp_doc .= <<EOD;
-=head2 Exportable functions
-
+#=head2 Exportable functions
+#
EOD
- $exp_doc .= <<EOD if $opt_p;
-When accessing these functions from Perl, prefix C<$opt_p> should be removed.
-EOD
+# $exp_doc .= <<EOD if $opt_p;
+#When accessing these functions from Perl, prefix C<$opt_p> should be removed.
+#
+#EOD
$exp_doc .= <<EOD;
- @{[join "\n ", @known_fnames{@fnames}]}
-
+# @{[join "\n ", @known_fnames{@fnames}]}
+#
EOD
}
+my $meth_doc = '';
+
+if ($opt_x && $opt_a) {
+ my($name, $struct);
+ $meth_doc .= accessor_docs($name, $struct)
+ while ($name, $struct) = each %structs;
+}
+
my $pod = <<"END" unless $opt_P;
## Below is stub documentation for your module. You better edit it!
#
#unedited.
#
#Blah blah blah.
-#$exp_doc$revhist
+$exp_doc$meth_doc$revhist
#=head1 AUTHOR
#
#$author, $email
#
#=head1 SEE ALSO
#
-#perl(1).
+#L<perl>.
#
#=cut
END
}
}
+sub accessor_docs {
+ my($name, $struct) = @_;
+ return unless defined $struct && $name !~ /\s|_ANON/;
+ $name = normalize_type($name);
+ my $ptrname = $name . 'Ptr';
+ my @items = @$struct;
+ my @list;
+ while (@items) {
+ my $item = shift @items;
+ if ($item->[0] =~ /_ANON/) {
+ if (defined $item->[2]) {
+ push @items, map [
+ @$_[0, 1], "$item->[2]_$_->[2]", "$item->[2].$_->[2]",
+ ], @{ $structs{$item->[0]} };
+ } else {
+ push @items, @{ $structs{$item->[0]} };
+ }
+ } else {
+ push @list, $item->[2];
+ }
+ }
+ my $methods = (join '(...)>, C<', @list) . '(...)';
+
+ my $pod = <<"EOF";
+#
+#=head2 Object and class methods for C<$name>/C<$ptrname>
+#
+#The principal Perl representation of a C object of type C<$name> is an
+#object of class C<$ptrname> which is a reference to an integer
+#representation of a C pointer. To create such an object, one may use
+#a combination
+#
+# my \$buffer = $name->new();
+# my \$obj = \$buffer->_to_ptr();
+#
+#This exersizes the following two methods, and an additional class
+#C<$name>, the internal representation of which is a reference to a
+#packed string with the C structure. Keep in mind that \$buffer should
+#better survive longer than \$obj.
+#
+#=over
+#
+#=item C<\$object_of_type_$name-E<gt>_to_ptr()>
+#
+#Converts an object of type C<$name> to an object of type C<$ptrname>.
+#
+#=item C<$name-E<gt>new()>
+#
+#Creates an empty object of type C<$name>. The corresponding packed
+#string is zeroed out.
+#
+#=item C<$methods>
+#
+#return the current value of the corresponding element if called
+#without additional arguments. Set the element to the supplied value
+#(and return the new value) if called with an additional argument.
+#
+#Applicable to objects of type C<$ptrname>.
+#
+#=back
+#
+EOF
+ $pod =~ s/^\#//gm;
+ return $pod;
+}
+
# Should be called before any actual call to normalize_type().
sub get_typemap {
# We do not want to read ./typemap by obvios reasons.
END
if (!$opt_X) { # print C stuff, unless XS is disabled
$opt_F = '' unless defined $opt_F;
+ my $I = (((glob '*.h') || (glob '*.hh')) ? '-I.' : '');
+ my $Ihelp = ($I ? '-I. ' : '');
+ my $Icomment = ($I ? '' : <<EOC);
+ # Insert -I. if you add *.h files later:
+EOC
+
print PL <<END;
'LIBS' => ['$extralibs'], # e.g., '-lm'
'DEFINE' => '$opt_F', # e.g., '-DHAVE_SOMETHING'
- 'INC' => '', # e.g., '-I/usr/include/other'
+$Icomment 'INC' => '$I', # e.g., '$Ihelp-I/usr/include/other'
+END
+
+ my $C = grep $_ ne "$modfname.c", (glob '*.c'), (glob '*.cc'), (glob '*.C');
+ my $Cpre = ($C ? '' : '# ');
+ my $Ccomment = ($C ? '' : <<EOC);
+ # Un-comment this if you add C files to link with later:
+EOC
+
+ print PL <<END;
+$Ccomment $Cpre\'OBJECT' => '\$(O_FILES)', # link all the C files too
END
}
print PL ");\n";
projects / p5sagit/p5-mst-13.2.git / blobdiff