X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=utils%2Fh2xs.PL;h=44b9ac888fe7965eafa08a8728e896ee2d7e89ba;hb=22d4bb9ccb8701e68f9243547d7e3a3c55f70908;hp=2885c6f5ee284f2de1ad88c13c37b57212bf8886;hpb=4b19af017623bfa3bb72bb164598a517f586e0d3;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/utils/h2xs.PL b/utils/h2xs.PL
index 2885c6f..44b9ac8 100644
--- a/utils/h2xs.PL
+++ b/utils/h2xs.PL
@@ -260,6 +260,68 @@ are using to run h2xs will have no effect.
 	# 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.
@@ -905,6 +967,7 @@ my $exp_doc = <<EOD;
 #None by default.
 #
 EOD
+
 if (@const_names and not $opt_P) {
   $exp_doc .= <<EOD;
 #=head2 Exportable constants
@@ -913,21 +976,31 @@ if (@const_names and not $opt_P) {
 #
 EOD
 }
+
 if (defined $fdecls and @$fdecls and not $opt_P) {
   $exp_doc .= <<EOD;
 #=head2 Exportable functions
 #
 EOD
+
 #  $exp_doc .= <<EOD if $opt_p;
 #When accessing these functions from Perl, prefix C<$opt_p> should be removed.
 #
-EOD
+#EOD
   $exp_doc .= <<EOD;
 #  @{[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!
 #
@@ -947,7 +1020,7 @@ my $pod = <<"END" unless $opt_P;
 #unedited.
 #
 #Blah blah blah.
-$exp_doc$revhist
+$exp_doc$meth_doc$revhist
 #=head1 AUTHOR
 #
 #$author, $email
@@ -1406,6 +1479,72 @@ EOF
   }
 }
 
+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.
@@ -1561,10 +1700,26 @@ WriteMakefile(
 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";