From: Ilya Zakharevich Date: Wed, 4 Oct 2000 17:37:46 +0000 (-0400) Subject: Re: [PATCH 5.7.0] h2xs not documenting the created module X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b68ece06e2cf4b8e1f7a860c1625cd5817c8c80b;p=p5sagit%2Fp5-mst-13.2.git Re: [PATCH 5.7.0] h2xs not documenting the created module Message-ID: <20001004173746.A26697@monk.mps.ohio-state.edu> p4raw-id: //depot/perl@7145 --- diff --git a/utils/h2xs.PL b/utils/h2xs.PL index a5aa724..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 and +I, and you want the perl module be named as +C. 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. + +=item Copy C files + +Copy your header files and C files to this directory F. + +=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 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 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. @@ -1438,47 +1500,49 @@ sub accessor_docs { push @list, $item->[2]; } } - my $methods = (join '(...)>, C<', @list), '(...)'; - - return <<"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 = $buf->_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->_to_ptr()> - -Converts an object of type C<$name> to an object of type C<$ptrname>. - -=item C<$name->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 + 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_to_ptr()> +# +#Converts an object of type C<$name> to an object of type C<$ptrname>. +# +#=item C<$name-Enew()> +# +#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(). @@ -1636,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 ? '' : < ['$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 ? '' : < '\$(O_FILES)', # link all the C files too END } print PL ");\n";