4 use File::Basename qw(&basename &dirname);
6 # List explicitly here the variables you want Configure to
7 # generate. Metaconfig only looks for shell variables, so you
8 # have to mention them as if they were shell variables, not
9 # %Config entries. Thus you write
11 # to ensure Configure will look for $Config{startperl}.
13 # This forces PL files to create target in same directory as PL file.
14 # This is so that make depend always knows where to find PL derivatives.
16 ($file = basename($0)) =~ s/\.PL$//;
18 if ($Config{'osname'} eq 'VMS' or
19 $Config{'osname'} eq 'OS2'); # "case-forgiving"
21 open OUT,">$file" or die "Can't create $file: $!";
23 print "Extracting $file (with variable substitutions)\n";
25 # In this section, perl variables will be expanded during extraction.
26 # You can use $Config{...} to use Configure variables.
28 print OUT <<"!GROK!THIS!";
30 eval 'exec perl -S \$0 "\$@"'
34 # In the following, perl variables are not expanded during extraction.
36 print OUT <<'!NO!SUBS!';
40 h2xs - convert .h C header files to Perl extensions
44 B<h2xs> [B<-AOPXcf>] [B<-v> version] [B<-n> module_name] [headerfile [extra_libraries]]
50 I<h2xs> builds a Perl extension from any C header file. The extension will
51 include functions which can be used to retrieve the value of any #define
52 statement which was in the C header.
54 The I<module_name> will be used for the name of the extension. If
55 module_name is not supplied then the name of the header file will be used,
56 with the first character capitalized.
58 If the extension might need extra libraries, they should be included
59 here. The extension Makefile.PL will take care of checking whether
60 the libraries actually exist and how they should be loaded.
61 The extra libraries should be specified in the form -lm -lposix, etc,
62 just as on the cc command line. By default, the Makefile.PL will
63 search through the library path determined by Configure. That path
64 can be augmented by including arguments of the form B<-L/another/library/path>
65 in the extra-libraries argument.
73 Omit all autoload facilities. This is the same as B<-c> but also removes the
74 S<C<require AutoLoader>> statement from the .pm file.
78 Allows a pre-existing extension directory to be overwritten.
82 Omit the autogenerated stub POD section.
86 Omit C<constant()> from the .xs file and corresponding specialised
87 C<AUTOLOAD> from the .pm file.
91 Allows an extension to be created for a header even if that header is
92 not found in /usr/include.
96 Print the usage, help and version for this h2xs and exit.
98 =item B<-n> I<module_name>
100 Specifies a name to be used for the extension, e.g., S<-n RPC::DCE>
102 =item B<-v> I<version>
104 Specify a version number for this extension. This version number is added
105 to the templates. The default is 0.01.
109 Omit the XS portion. Used to generate templates for a module which is not
117 # Default behavior, extension is Rusers
120 # Same, but extension is RUSERS
121 h2xs -n RUSERS rpcsvc/rusers
123 # Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h>
126 # Extension is ONC::RPC. Still finds <rpcsvc/rusers.h>
127 h2xs -n ONC::RPC rpcsvc/rusers
129 # Without constant() or AUTOLOAD
130 h2xs -c rpcsvc/rusers
132 # Creates templates for an extension named RPC
135 # Extension is ONC::RPC.
138 # Makefile.PL will look for library -lrpc in
139 # additional directory /opt/net/lib
140 h2xs rpcsvc/rusers -L/opt/net/lib -lrpc
145 No environment variables are used.
149 Larry Wall and others
153 L<perl>, L<perlxstut>, L<ExtUtils::MakeMaker>, and L<AutoLoader>.
157 The usual warnings if it can't read or write the files involved.
161 my( $H2XS_VERSION ) = '$Revision: 1.16 $' =~ /\$Revision:\s+([^\s]+)/;
162 my $TEMPLATE_VERSION = '0.01';
168 die "h2xs [-AOPXcfh] [-v version] [-n module_name] [headerfile [extra_libraries]]
169 version: $H2XS_VERSION
170 -f Force creation of the extension even if the C header does not exist.
171 -n Specify a name to use for the extension (recommended).
172 -c Omit the constant() function and specialised AUTOLOAD from the XS file.
173 -A Omit all autoloading facilities (implies -c).
174 -O Allow overwriting of a pre-existing extension directory.
175 -P Omit the stub POD section.
176 -X Omit the XS portion.
177 -v Specify a version number for this extension.
178 -h Display this help message
180 are any libraries that might be needed for loading the
181 extension, e.g. -lm would try to link in the math library.
186 getopts("AOPXcfhv:n:") || usage;
191 $TEMPLATE_VERSION = $opt_v;
193 $opt_c = 1 if $opt_A;
196 $extralibs = "@ARGV";
198 usage "Must supply header file or module name\n"
199 unless ($path_h or $opt_n);
204 if( $path_h =~ s#::#/#g && $opt_n ){
205 warn "Nesting of headerfile ignored with -n\n";
207 $path_h .= ".h" unless $path_h =~ /\.h$/;
208 $path_h = "/usr/include/$path_h" unless $path_h =~ m#^[./]#;
209 die "Can't find $path_h\n" if ( ! $opt_f && ! -f $path_h );
211 # Scan the header file (we should deal with nested header files)
212 # Record the names of simple #define constants into const_names
213 # Function prototypes are not (currently) processed.
214 open(CH, "<$path_h") || die "Can't open $path_h: $!\n";
216 if (/^#[ \t]*define\s+(\w+)\b\s*[^("]/) {
218 next if /^_.*_h_*$/i; # special case, but for what?
223 @const_names = sort keys %const_names;
227 $module = $opt_n || do {
236 (chdir 'ext', $ext = 'ext/') if -d 'ext';
238 if( $module =~ /::/ ){
240 @modparts = split(/::/,$module);
241 $modfname = $modparts[-1];
242 $modpname = join('/',@modparts);
247 $modfname = $modpname = $module;
252 warn "Overwriting existing $ext$modpname!!!\n" if -e $modpname;
254 die "Won't overwrite existing $ext$modpname\n" if -e $modpname;
259 mkdir("$modpath$_", 0777);
263 mkdir($modpname, 0777);
264 chdir($modpname) || die "Can't chdir $ext$modpname: $!\n";
266 if( ! $opt_X ){ # use XS, unless it was disabled
267 open(XS, ">$modfname.xs") || die "Can't create $ext$modpname/$modfname.xs: $!\n";
269 open(PM, ">$modfname.pm") || die "Can't create $ext$modpname/$modfname.pm: $!\n";
272 warn "Writing $ext$modpname/$modfname.pm\n";
280 if( $opt_X || $opt_c || $opt_A ){
281 # we won't have our own AUTOLOAD(), so won't have $AUTOLOAD
283 use vars qw($VERSION @ISA @EXPORT);
287 # we'll have an AUTOLOAD(), and it will have $AUTOLOAD and
291 use vars qw($VERSION @ISA @EXPORT $AUTOLOAD);
300 print PM <<"END" if ! $opt_X; # use DynaLoader, unless XS was disabled
304 # require autoloader if XS is disabled.
305 # if XS is enabled, require autoloader unless autoloading is disabled.
306 if( $opt_X || (! $opt_A) ){
312 if( $opt_X || ($opt_c && ! $opt_A) ){
313 # we won't have our own AUTOLOAD(), so we'll inherit it.
314 if( ! $opt_X ) { # use DynaLoader, unless XS was disabled
317 \@ISA = qw(Exporter AutoLoader DynaLoader);
323 \@ISA = qw(Exporter AutoLoader);
328 # 1) we have our own AUTOLOAD(), so don't need to inherit it.
330 # 2) we don't want autoloading mentioned.
331 if( ! $opt_X ){ # use DynaLoader, unless XS was disabled
334 \@ISA = qw(Exporter DynaLoader);
340 \@ISA = qw(Exporter);
346 # Items to export into callers namespace by default. Note: do not export
347 # names by default without a very good reason. Use EXPORT_OK instead.
348 # Do not simply export all your public functions/methods/constants.
352 \$VERSION = '$TEMPLATE_VERSION';
356 print PM <<"END" unless $opt_c or $opt_X;
358 # This AUTOLOAD is used to 'autoload' constants from the constant()
359 # XS function. If a constant is not found then control is passed
360 # to the AUTOLOAD in AutoLoader.
363 (\$constname = \$AUTOLOAD) =~ s/.*:://;
364 my \$val = constant(\$constname, \@_ ? \$_[0] : 0);
366 if (\$! =~ /Invalid/) {
367 \$AutoLoader::AUTOLOAD = \$AUTOLOAD;
368 goto &AutoLoader::AUTOLOAD;
371 croak "Your vendor has not defined $module macro \$constname";
374 eval "sub \$AUTOLOAD { \$val }";
380 if( ! $opt_X ){ # print bootstrap, unless XS is disabled
382 bootstrap $module \$VERSION;
386 if( $opt_P ){ # if POD is disabled
395 # Preloaded methods go here.
397 # Autoload methods go after $after, and are processed by the autosplit program.
403 $author = "A. U. Thor";
404 $email = 'a.u.thor@a.galaxy.far.far.away';
406 $pod = <<"END" unless $opt_P;
407 ## Below is the stub of documentation for your module. You better edit it!
411 #$module - Perl extension for blah blah blah
420 #Stub documentation for $module was created by h2xs. It looks like the
421 #author of the extension was negligent enough to leave the stub
437 $pod =~ s/^\#//gm unless $opt_P;
438 print PM $pod unless $opt_P;
443 if( ! $opt_X ){ # print XS, unless it is disabled
444 warn "Writing $ext$modpname/$modfname.xs\n";
460 $h =~ s#^/usr/include/##;
473 croak("$module::%s not implemented on this architecture", s);
486 my(@AZ, @az, @under);
488 foreach(@const_names){
489 @AZ = 'A' .. 'Z' if !@AZ && /^[A-Z]/;
490 @az = 'a' .. 'z' if !@az && /^[a-z]/;
491 @under = '_' if !@under && /^_/;
494 foreach $letter (@AZ, @az, @under) {
496 last if $letter eq 'a' && !@const_names;
498 print XS " case '$letter':\n";
500 while (substr($const_names[0],0,1) eq $letter) {
501 $name = shift(@const_names);
503 if (strEQ(name, "$name"))
528 # Now switch from C to XS by issuing the first MODULE declaration:
531 MODULE = $module PACKAGE = $module
535 # If a constant() function was written then output a corresponding
537 print XS <<"END" unless $opt_c;
549 warn "Writing $ext$modpname/Makefile.PL\n";
550 open(PL, ">Makefile.PL") || die "Can't create $ext$modpname/Makefile.PL: $!\n";
553 use ExtUtils::MakeMaker;
554 # See lib/ExtUtils/MakeMaker.pm for details of how to influence
555 # the contents of the Makefile that is written.
557 print PL "WriteMakefile(\n";
558 print PL " 'NAME' => '$module',\n";
559 print PL " 'VERSION_FROM' => '$modfname.pm', # finds \$VERSION\n";
560 if( ! $opt_X ){ # print C stuff, unless XS is disabled
561 print PL " 'LIBS' => ['$extralibs'], # e.g., '-lm' \n";
562 print PL " 'DEFINE' => '', # e.g., '-DHAVE_SOMETHING' \n";
563 print PL " 'INC' => '', # e.g., '-I/usr/include/other' \n";
566 close(PL) || die "Can't close $ext$modpname/Makefile.PL: $!\n";
568 warn "Writing $ext$modpname/test.pl\n";
569 open(EX, ">test.pl") || die "Can't create $ext$modpname/test.pl: $!\n";
571 # Before `make install' is performed this script should be runnable with
572 # `make test'. After `make install' it should work as `perl test.pl'
574 ######################### We start with some black magic to print on failure.
576 # Change 1..1 below to 1..last_test_to_print .
577 # (It may become useful if the test is moved to ./t subdirectory.)
579 BEGIN {print "1..1\n";}
580 END {print "not ok 1\n" unless $loaded;}
589 ######################### End of black magic.
591 # Insert your test code below (better if it prints "ok 13"
592 # (correspondingly "not ok 13") depending on the success of chunk 13
596 close(EX) || die "Can't close $ext$modpname/test.pl: $!\n";
598 warn "Writing $ext$modpname/Changes\n";
599 open(EX, ">Changes") || die "Can't create $ext$modpname/Changes: $!\n";
600 print EX "Revision history for Perl extension $module.\n\n";
601 print EX "$TEMPLATE_VERSION ",scalar localtime,"\n";
602 print EX "\t- original version; created by h2xs $H2XS_VERSION\n\n";
603 close(EX) || die "Can't close $ext$modpname/Changes: $!\n";
605 warn "Writing $ext$modpname/MANIFEST\n";
606 system '/bin/ls > MANIFEST' or system 'ls > MANIFEST';
609 close OUT or die "Can't close $file: $!";
610 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
611 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';