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 ($^O eq 'VMS' or $^O eq 'os2'); # "case-forgiving"
20 open OUT,">$file" or die "Can't create $file: $!";
22 print "Extracting $file (with variable substitutions)\n";
24 # In this section, perl variables will be expanded during extraction.
25 # You can use $Config{...} to use Configure variables.
27 print OUT <<"!GROK!THIS!";
29 eval 'exec perl -S \$0 "\$@"'
33 # In the following, perl variables are not expanded during extraction.
35 print OUT <<'!NO!SUBS!';
39 h2xs - convert .h C header files to Perl extensions
43 B<h2xs> [B<-AOPXcf>] [B<-v> version] [B<-n> module_name] [headerfile [extra_libraries]]
49 I<h2xs> builds a Perl extension from any C header file. The extension will
50 include functions which can be used to retrieve the value of any #define
51 statement which was in the C header.
53 The I<module_name> will be used for the name of the extension. If
54 module_name is not supplied then the name of the header file will be used,
55 with the first character capitalized.
57 If the extension might need extra libraries, they should be included
58 here. The extension Makefile.PL will take care of checking whether
59 the libraries actually exist and how they should be loaded.
60 The extra libraries should be specified in the form -lm -lposix, etc,
61 just as on the cc command line. By default, the Makefile.PL will
62 search through the library path determined by Configure. That path
63 can be augmented by including arguments of the form B<-L/another/library/path>
64 in the extra-libraries argument.
72 Omit all autoload facilities. This is the same as B<-c> but also removes the
73 S<C<require AutoLoader>> statement from the .pm file.
77 Allows a pre-existing extension directory to be overwritten.
81 Omit the autogenerated stub POD section.
85 Omit C<constant()> from the .xs file and corresponding specialised
86 C<AUTOLOAD> from the .pm file.
90 Allows an extension to be created for a header even if that header is
91 not found in /usr/include.
95 Print the usage, help and version for this h2xs and exit.
97 =item B<-n> I<module_name>
99 Specifies a name to be used for the extension, e.g., S<-n RPC::DCE>
101 =item B<-v> I<version>
103 Specify a version number for this extension. This version number is added
104 to the templates. The default is 0.01.
108 Omit the XS portion. Used to generate templates for a module which is not
116 # Default behavior, extension is Rusers
119 # Same, but extension is RUSERS
120 h2xs -n RUSERS rpcsvc/rusers
122 # Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h>
125 # Extension is ONC::RPC. Still finds <rpcsvc/rusers.h>
126 h2xs -n ONC::RPC rpcsvc/rusers
128 # Without constant() or AUTOLOAD
129 h2xs -c rpcsvc/rusers
131 # Creates templates for an extension named RPC
134 # Extension is ONC::RPC.
137 # Makefile.PL will look for library -lrpc in
138 # additional directory /opt/net/lib
139 h2xs rpcsvc/rusers -L/opt/net/lib -lrpc
144 No environment variables are used.
148 Larry Wall and others
152 L<perl>, L<perlxstut>, L<ExtUtils::MakeMaker>, and L<AutoLoader>.
156 The usual warnings if it can't read or write the files involved.
160 my( $H2XS_VERSION ) = '$Revision: 1.1.1.1 $' =~ /\$Revision:\s+([^\s]+)/;
161 my $TEMPLATE_VERSION = '0.01';
167 die "h2xs [-AOPXcfh] [-v version] [-n module_name] [headerfile [extra_libraries]]
168 version: $H2XS_VERSION
169 -f Force creation of the extension even if the C header does not exist.
170 -n Specify a name to use for the extension (recommended).
171 -c Omit the constant() function and specialised AUTOLOAD from the XS file.
172 -A Omit all autoloading facilities (implies -c).
173 -O Allow overwriting of a pre-existing extension directory.
174 -P Omit the stub POD section.
175 -X Omit the XS portion.
176 -v Specify a version number for this extension.
177 -h Display this help message
179 are any libraries that might be needed for loading the
180 extension, e.g. -lm would try to link in the math library.
185 getopts("AOPXcfhv:n:") || usage;
190 $TEMPLATE_VERSION = $opt_v;
192 $opt_c = 1 if $opt_A;
195 $extralibs = "@ARGV";
197 usage "Must supply header file or module name\n"
198 unless ($path_h or $opt_n);
203 if( $path_h =~ s#::#/#g && $opt_n ){
204 warn "Nesting of headerfile ignored with -n\n";
206 $path_h .= ".h" unless $path_h =~ /\.h$/;
207 $path_h = "/usr/include/$path_h" unless $path_h =~ m#^[./]#;
208 die "Can't find $path_h\n" if ( ! $opt_f && ! -f $path_h );
210 # Scan the header file (we should deal with nested header files)
211 # Record the names of simple #define constants into const_names
212 # Function prototypes are not (currently) processed.
213 open(CH, "<$path_h") || die "Can't open $path_h: $!\n";
215 if (/^#[ \t]*define\s+(\w+)\b\s*[^("]/) {
217 next if /^_.*_h_*$/i; # special case, but for what?
222 @const_names = sort keys %const_names;
226 $module = $opt_n || do {
235 (chdir 'ext', $ext = 'ext/') if -d 'ext';
237 if( $module =~ /::/ ){
239 @modparts = split(/::/,$module);
240 $modfname = $modparts[-1];
241 $modpname = join('/',@modparts);
246 $modfname = $modpname = $module;
251 warn "Overwriting existing $ext$modpname!!!\n" if -e $modpname;
253 die "Won't overwrite existing $ext$modpname\n" if -e $modpname;
258 mkdir("$modpath$_", 0777);
262 mkdir($modpname, 0777);
263 chdir($modpname) || die "Can't chdir $ext$modpname: $!\n";
265 if( ! $opt_X ){ # use XS, unless it was disabled
266 open(XS, ">$modfname.xs") || die "Can't create $ext$modpname/$modfname.xs: $!\n";
268 open(PM, ">$modfname.pm") || die "Can't create $ext$modpname/$modfname.pm: $!\n";
271 warn "Writing $ext$modpname/$modfname.pm\n";
279 if( $opt_X || $opt_c || $opt_A ){
280 # we won't have our own AUTOLOAD(), so won't have $AUTOLOAD
282 use vars qw($VERSION @ISA @EXPORT);
286 # we'll have an AUTOLOAD(), and it will have $AUTOLOAD and
290 use vars qw($VERSION @ISA @EXPORT $AUTOLOAD);
299 print PM <<"END" if ! $opt_X; # use DynaLoader, unless XS was disabled
303 # require autoloader if XS is disabled.
304 # if XS is enabled, require autoloader unless autoloading is disabled.
305 if( $opt_X || (! $opt_A) ){
311 if( $opt_X || ($opt_c && ! $opt_A) ){
312 # we won't have our own AUTOLOAD(), so we'll inherit it.
313 if( ! $opt_X ) { # use DynaLoader, unless XS was disabled
316 \@ISA = qw(Exporter AutoLoader DynaLoader);
322 \@ISA = qw(Exporter AutoLoader);
327 # 1) we have our own AUTOLOAD(), so don't need to inherit it.
329 # 2) we don't want autoloading mentioned.
330 if( ! $opt_X ){ # use DynaLoader, unless XS was disabled
333 \@ISA = qw(Exporter DynaLoader);
339 \@ISA = qw(Exporter);
345 # Items to export into callers namespace by default. Note: do not export
346 # names by default without a very good reason. Use EXPORT_OK instead.
347 # Do not simply export all your public functions/methods/constants.
351 \$VERSION = '$TEMPLATE_VERSION';
355 print PM <<"END" unless $opt_c or $opt_X;
357 # This AUTOLOAD is used to 'autoload' constants from the constant()
358 # XS function. If a constant is not found then control is passed
359 # to the AUTOLOAD in AutoLoader.
362 (\$constname = \$AUTOLOAD) =~ s/.*:://;
363 my \$val = constant(\$constname, \@_ ? \$_[0] : 0);
365 if (\$! =~ /Invalid/) {
366 \$AutoLoader::AUTOLOAD = \$AUTOLOAD;
367 goto &AutoLoader::AUTOLOAD;
370 croak "Your vendor has not defined $module macro \$constname";
373 eval "sub \$AUTOLOAD { \$val }";
379 if( ! $opt_X ){ # print bootstrap, unless XS is disabled
381 bootstrap $module \$VERSION;
385 if( $opt_P ){ # if POD is disabled
394 # Preloaded methods go here.
396 # Autoload methods go after $after, and are processed by the autosplit program.
402 $author = "A. U. Thor";
403 $email = 'a.u.thor@a.galaxy.far.far.away';
405 $pod = <<"END" unless $opt_P;
406 ## Below is the stub of documentation for your module. You better edit it!
410 #$module - Perl extension for blah blah blah
419 #Stub documentation for $module was created by h2xs. It looks like the
420 #author of the extension was negligent enough to leave the stub
436 $pod =~ s/^\#//gm unless $opt_P;
437 print PM $pod unless $opt_P;
442 if( ! $opt_X ){ # print XS, unless it is disabled
443 warn "Writing $ext$modpname/$modfname.xs\n";
459 $h =~ s#^/usr/include/##;
472 croak("$module::%s not implemented on this architecture", s);
485 my(@AZ, @az, @under);
487 foreach(@const_names){
488 @AZ = 'A' .. 'Z' if !@AZ && /^[A-Z]/;
489 @az = 'a' .. 'z' if !@az && /^[a-z]/;
490 @under = '_' if !@under && /^_/;
493 foreach $letter (@AZ, @az, @under) {
495 last if $letter eq 'a' && !@const_names;
497 print XS " case '$letter':\n";
499 while (substr($const_names[0],0,1) eq $letter) {
500 $name = shift(@const_names);
502 if (strEQ(name, "$name"))
527 # Now switch from C to XS by issuing the first MODULE declaration:
530 MODULE = $module PACKAGE = $module
534 # If a constant() function was written then output a corresponding
536 print XS <<"END" unless $opt_c;
548 warn "Writing $ext$modpname/Makefile.PL\n";
549 open(PL, ">Makefile.PL") || die "Can't create $ext$modpname/Makefile.PL: $!\n";
552 use ExtUtils::MakeMaker;
553 # See lib/ExtUtils/MakeMaker.pm for details of how to influence
554 # the contents of the Makefile that is written.
556 print PL "WriteMakefile(\n";
557 print PL " 'NAME' => '$module',\n";
558 print PL " 'VERSION_FROM' => '$modfname.pm', # finds \$VERSION\n";
559 if( ! $opt_X ){ # print C stuff, unless XS is disabled
560 print PL " 'LIBS' => ['$extralibs'], # e.g., '-lm' \n";
561 print PL " 'DEFINE' => '', # e.g., '-DHAVE_SOMETHING' \n";
562 print PL " 'INC' => '', # e.g., '-I/usr/include/other' \n";
565 close(PL) || die "Can't close $ext$modpname/Makefile.PL: $!\n";
567 warn "Writing $ext$modpname/test.pl\n";
568 open(EX, ">test.pl") || die "Can't create $ext$modpname/test.pl: $!\n";
570 # Before `make install' is performed this script should be runnable with
571 # `make test'. After `make install' it should work as `perl test.pl'
573 ######################### We start with some black magic to print on failure.
575 # Change 1..1 below to 1..last_test_to_print .
576 # (It may become useful if the test is moved to ./t subdirectory.)
578 BEGIN { $| = 1; print "1..1\n"; }
579 END {print "not ok 1\n" unless $loaded;}
588 ######################### End of black magic.
590 # Insert your test code below (better if it prints "ok 13"
591 # (correspondingly "not ok 13") depending on the success of chunk 13
595 close(EX) || die "Can't close $ext$modpname/test.pl: $!\n";
597 warn "Writing $ext$modpname/Changes\n";
598 open(EX, ">Changes") || die "Can't create $ext$modpname/Changes: $!\n";
599 print EX "Revision history for Perl extension $module.\n\n";
600 print EX "$TEMPLATE_VERSION ",scalar localtime,"\n";
601 print EX "\t- original version; created by h2xs $H2XS_VERSION\n\n";
602 close(EX) || die "Can't close $ext$modpname/Changes: $!\n";
604 warn "Writing $ext$modpname/MANIFEST\n";
605 open(MANI,'>MANIFEST') or die "Can't create MANIFEST: $!";
608 eval {opendir(D,'.');};
609 unless ($@) { @files = readdir(D); closedir(D); }
611 if (!@files) { @files = map {chomp && $_} `ls`; }
612 print MANI join("\n",@files);
616 close OUT or die "Can't close $file: $!";
617 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
618 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';