This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Added new flag (--use-xsloader) to use XSLoader when in backward
[perl5.git] / utils / h2xs.PL
1 #!/usr/local/bin/perl
2
3 use Config;
4 use File::Basename qw(&basename &dirname);
5 use Cwd;
6
7 # List explicitly here the variables you want Configure to
8 # generate.  Metaconfig only looks for shell variables, so you
9 # have to mention them as if they were shell variables, not
10 # %Config entries.  Thus you write
11 #  $startperl
12 # to ensure Configure will look for $Config{startperl}.
13
14 # This forces PL files to create target in same directory as PL file.
15 # This is so that make depend always knows where to find PL derivatives.
16 my $origdir = cwd;
17 chdir dirname($0);
18 my $file = basename($0, '.PL');
19 $file .= '.com' if $^O eq 'VMS';
20
21 open OUT,">$file" or die "Can't create $file: $!";
22
23 print "Extracting $file (with variable substitutions)\n";
24
25 # In this section, perl variables will be expanded during extraction.
26 # You can use $Config{...} to use Configure variables.
27
28 print OUT <<"!GROK!THIS!";
29 $Config{startperl}
30     eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
31         if \$running_under_some_shell;
32 !GROK!THIS!
33
34 # In the following, perl variables are not expanded during extraction.
35
36 print OUT <<'!NO!SUBS!';
37
38 use warnings;
39
40 =head1 NAME
41
42 h2xs - convert .h C header files to Perl extensions
43
44 =head1 SYNOPSIS
45
46 B<h2xs> [B<OPTIONS> ...] [headerfile ... [extra_libraries]]
47
48 B<h2xs> B<-h>|B<-?>|B<--help>
49
50 =head1 DESCRIPTION
51
52 I<h2xs> builds a Perl extension from C header files.  The extension
53 will include functions which can be used to retrieve the value of any
54 #define statement which was in the C header files.
55
56 The I<module_name> will be used for the name of the extension.  If
57 module_name is not supplied then the name of the first header file
58 will be used, with the first character capitalized.
59
60 If the extension might need extra libraries, they should be included
61 here.  The extension Makefile.PL will take care of checking whether
62 the libraries actually exist and how they should be loaded.  The extra
63 libraries should be specified in the form -lm -lposix, etc, just as on
64 the cc command line.  By default, the Makefile.PL will search through
65 the library path determined by Configure.  That path can be augmented
66 by including arguments of the form B<-L/another/library/path> in the
67 extra-libraries argument.
68
69 =head1 OPTIONS
70
71 =over 5
72
73 =item B<-A>, B<--omit-autoload>
74
75 Omit all autoload facilities.  This is the same as B<-c> but also
76 removes the S<C<use AutoLoader>> statement from the .pm file.
77
78 =item B<-B>, B<--beta-version>
79
80 Use an alpha/beta style version number.  Causes version number to
81 be "0.00_01" unless B<-v> is specified.
82
83 =item B<-C>, B<--omit-changes>
84
85 Omits creation of the F<Changes> file, and adds a HISTORY section to
86 the POD template.
87
88 =item B<-F>, B<--cpp-flags>=I<addflags>
89
90 Additional flags to specify to C preprocessor when scanning header for
91 function declarations.  Writes these options in the generated F<Makefile.PL>
92 too.
93
94 =item B<-M>, B<--func-mask>=I<regular expression>
95
96 selects functions/macros to process.
97
98 =item B<-O>, B<--overwrite-ok>
99
100 Allows a pre-existing extension directory to be overwritten.
101
102 =item B<-P>, B<--omit-pod>
103
104 Omit the autogenerated stub POD section.
105
106 =item B<-X>, B<--omit-XS>
107
108 Omit the XS portion.  Used to generate templates for a module which is not
109 XS-based.  C<-c> and C<-f> are implicitly enabled.
110
111 =item B<-a>, B<--gen-accessors>
112
113 Generate an accessor method for each element of structs and unions. The
114 generated methods are named after the element name; will return the current
115 value of the element if called without additional arguments; and will set
116 the element to the supplied value (and return the new value) if called with
117 an additional argument. Embedded structures and unions are returned as a
118 pointer rather than the complete structure, to facilitate chained calls.
119
120 These methods all apply to the Ptr type for the structure; additionally
121 two methods are constructed for the structure type itself, C<_to_ptr>
122 which returns a Ptr type pointing to the same structure, and a C<new>
123 method to construct and return a new structure, initialised to zeroes.
124
125 =item B<-b>, B<--compat-version>=I<version>
126
127 Generates a .pm file which is backwards compatible with the specified
128 perl version.
129
130 For versions < 5.6.0, the changes are.
131     - no use of 'our' (uses 'use vars' instead)
132     - no 'use warnings'
133
134 Specifying a compatibility version higher than the version of perl you
135 are using to run h2xs will have no effect.  If unspecified h2xs will default
136 to compatibility with the version of perl you are using to run h2xs.
137
138 =item B<-c>, B<--omit-constant>
139
140 Omit C<constant()> from the .xs file and corresponding specialised
141 C<AUTOLOAD> from the .pm file.
142
143 =item B<-d>, B<--debugging>
144
145 Turn on debugging messages.
146
147 =item B<-e>, B<--omit-enums>=[I<regular expression>]
148
149 If I<regular expression> is not given, skip all constants that are defined in
150 a C enumeration. Otherwise skip only those constants that are defined in an
151 enum whose name matches I<regular expression>.
152
153 Since I<regular expression> is optional, make sure that this switch is followed
154 by at least one other switch if you omit I<regular expression> and have some
155 pending arguments such as header-file names. This is ok:
156
157     h2xs -e -n Module::Foo foo.h
158
159 This is not ok:
160
161     h2xs -n Module::Foo -e foo.h
162
163 In the latter, foo.h is taken as I<regular expression>.
164
165 =item B<-f>, B<--force>
166
167 Allows an extension to be created for a header even if that header is
168 not found in standard include directories.
169
170 =item B<-g>, B<--global>
171
172 Include code for safely storing static data in the .xs file.
173 Extensions that do no make use of static data can ignore this option.
174
175 =item B<-h>, B<-?>, B<--help>
176
177 Print the usage, help and version for this h2xs and exit.
178
179 =item B<-k>, B<--omit-const-func>
180
181 For function arguments declared as C<const>, omit the const attribute in the
182 generated XS code.
183
184 =item B<-m>, B<--gen-tied-var>
185
186 B<Experimental>: for each variable declared in the header file(s), declare
187 a perl variable of the same name magically tied to the C variable.
188
189 =item B<-n>, B<--name>=I<module_name>
190
191 Specifies a name to be used for the extension, e.g., S<-n RPC::DCE>
192
193 =item B<-o>, B<--opaque-re>=I<regular expression>
194
195 Use "opaque" data type for the C types matched by the regular
196 expression, even if these types are C<typedef>-equivalent to types
197 from typemaps.  Should not be used without B<-x>.
198
199 This may be useful since, say, types which are C<typedef>-equivalent
200 to integers may represent OS-related handles, and one may want to work
201 with these handles in OO-way, as in C<$handle-E<gt>do_something()>.
202 Use C<-o .> if you want to handle all the C<typedef>ed types as opaque
203 types.
204
205 The type-to-match is whitewashed (except for commas, which have no
206 whitespace before them, and multiple C<*> which have no whitespace
207 between them).
208
209 =item B<-p>, B<--remove-prefix>=I<prefix>
210
211 Specify a prefix which should be removed from the Perl function names,
212 e.g., S<-p sec_rgy_> This sets up the XS B<PREFIX> keyword and removes
213 the prefix from functions that are autoloaded via the C<constant()>
214 mechanism.
215
216 =item B<-s>, B<--const-subs>=I<sub1,sub2>
217
218 Create a perl subroutine for the specified macros rather than autoload
219 with the constant() subroutine.  These macros are assumed to have a
220 return type of B<char *>, e.g.,
221 S<-s sec_rgy_wildcard_name,sec_rgy_wildcard_sid>.
222
223 =item B<-t>, B<--default-type>=I<type>
224
225 Specify the internal type that the constant() mechanism uses for macros.
226 The default is IV (signed integer).  Currently all macros found during the
227 header scanning process will be assumed to have this type.  Future versions
228 of C<h2xs> may gain the ability to make educated guesses.
229
230 =item B<--use-new-tests>
231
232 When B<--compat-version> (B<-b>) is present the generated tests will use
233 C<Test::More> rather than C<Test> which is the default for versions before
234 5.7.2 .   C<Test::More> will be added to PREREQ_PM in the generated
235 C<Makefile.PL>.
236
237 =item B<--use-old-tests>
238
239 Will force the generation of test code that uses the older C<Test> module.
240
241 =item B<--skip-exporter>
242
243 Do not use C<Exporter> and/or export any symbol.
244
245 =item B<--skip-ppport>
246
247 Do not use C<Devel::PPPort>: no portability to older version.
248
249 =item B<--skip-autoloader>
250
251 Do not use the module C<AutoLoader>; but keep the constant() function
252 and C<sub AUTOLOAD> for constants.
253
254 =item B<--skip-strict>
255
256 Do not use the pragma C<strict>.
257
258 =item B<--skip-warnings>
259
260 Do not use the pragma C<warnings>.
261
262 =item B<-v>, B<--version>=I<version>
263
264 Specify a version number for this extension.  This version number is added
265 to the templates.  The default is 0.01, or 0.00_01 if C<-B> is specified.
266 The version specified should be numeric.
267
268 =item B<-x>, B<--autogen-xsubs>
269
270 Automatically generate XSUBs basing on function declarations in the
271 header file.  The package C<C::Scan> should be installed. If this
272 option is specified, the name of the header file may look like
273 C<NAME1,NAME2>. In this case NAME1 is used instead of the specified
274 string, but XSUBs are emitted only for the declarations included from
275 file NAME2.
276
277 Note that some types of arguments/return-values for functions may
278 result in XSUB-declarations/typemap-entries which need
279 hand-editing. Such may be objects which cannot be converted from/to a
280 pointer (like C<long long>), pointers to functions, or arrays.  See
281 also the section on L<LIMITATIONS of B<-x>>.
282
283 =back
284
285 =head1 EXAMPLES
286
287
288     # Default behavior, extension is Rusers
289     h2xs rpcsvc/rusers
290
291     # Same, but extension is RUSERS
292     h2xs -n RUSERS rpcsvc/rusers
293
294     # Extension is rpcsvc::rusers. Still finds <rpcsvc/rusers.h>
295     h2xs rpcsvc::rusers
296
297     # Extension is ONC::RPC.  Still finds <rpcsvc/rusers.h>
298     h2xs -n ONC::RPC rpcsvc/rusers
299
300     # Without constant() or AUTOLOAD
301     h2xs -c rpcsvc/rusers
302
303     # Creates templates for an extension named RPC
304     h2xs -cfn RPC
305
306     # Extension is ONC::RPC.
307     h2xs -cfn ONC::RPC
308
309     # Extension is Lib::Foo which works at least with Perl5.005_03.
310     # Constants are created for all #defines and enums h2xs can find
311     # in foo.h.
312     h2xs -b 5.5.3 -n Lib::Foo foo.h
313
314     # Extension is Lib::Foo which works at least with Perl5.005_03.
315     # Constants are created for all #defines but only for enums
316     # whose names do not start with 'bar_'.
317     h2xs -b 5.5.3 -e '^bar_' -n Lib::Foo foo.h
318
319     # Makefile.PL will look for library -lrpc in
320     # additional directory /opt/net/lib
321     h2xs rpcsvc/rusers -L/opt/net/lib -lrpc
322
323     # Extension is DCE::rgynbase
324     # prefix "sec_rgy_" is dropped from perl function names
325     h2xs -n DCE::rgynbase -p sec_rgy_ dce/rgynbase
326
327     # Extension is DCE::rgynbase
328     # prefix "sec_rgy_" is dropped from perl function names
329     # subroutines are created for sec_rgy_wildcard_name and
330     # sec_rgy_wildcard_sid
331     h2xs -n DCE::rgynbase -p sec_rgy_ \
332     -s sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase
333
334     # Make XS without defines in perl.h, but with function declarations
335     # visible from perl.h. Name of the extension is perl1.
336     # When scanning perl.h, define -DEXT=extern -DdEXT= -DINIT(x)=
337     # Extra backslashes below because the string is passed to shell.
338     # Note that a directory with perl header files would
339     #  be added automatically to include path.
340     h2xs -xAn perl1 -F "-DEXT=extern -DdEXT= -DINIT\(x\)=" perl.h
341
342     # Same with function declaration in proto.h as visible from perl.h.
343     h2xs -xAn perl2 perl.h,proto.h
344
345     # Same but select only functions which match /^av_/
346     h2xs -M '^av_' -xAn perl2 perl.h,proto.h
347
348     # Same but treat SV* etc as "opaque" types
349     h2xs -o '^[S]V \*$' -M '^av_' -xAn perl2 perl.h,proto.h
350
351 =head2 Extension based on F<.h> and F<.c> files
352
353 Suppose that you have some C files implementing some functionality,
354 and the corresponding header files.  How to create an extension which
355 makes this functionality accessible in Perl?  The example below
356 assumes that the header files are F<interface_simple.h> and
357 I<interface_hairy.h>, and you want the perl module be named as
358 C<Ext::Ension>.  If you need some preprocessor directives and/or
359 linking with external libraries, see the flags C<-F>, C<-L> and C<-l>
360 in L<"OPTIONS">.
361
362 =over
363
364 =item Find the directory name
365
366 Start with a dummy run of h2xs:
367
368   h2xs -Afn Ext::Ension
369
370 The only purpose of this step is to create the needed directories, and
371 let you know the names of these directories.  From the output you can
372 see that the directory for the extension is F<Ext/Ension>.
373
374 =item Copy C files
375
376 Copy your header files and C files to this directory F<Ext/Ension>.
377
378 =item Create the extension
379
380 Run h2xs, overwriting older autogenerated files:
381
382   h2xs -Oxan Ext::Ension interface_simple.h interface_hairy.h
383
384 h2xs looks for header files I<after> changing to the extension
385 directory, so it will find your header files OK.
386
387 =item Archive and test
388
389 As usual, run
390
391   cd Ext/Ension
392   perl Makefile.PL
393   make dist
394   make
395   make test
396
397 =item Hints
398
399 It is important to do C<make dist> as early as possible.  This way you
400 can easily merge(1) your changes to autogenerated files if you decide
401 to edit your C<.h> files and rerun h2xs.
402
403 Do not forget to edit the documentation in the generated F<.pm> file.
404
405 Consider the autogenerated files as skeletons only, you may invent
406 better interfaces than what h2xs could guess.
407
408 Consider this section as a guideline only, some other options of h2xs
409 may better suit your needs.
410
411 =back
412
413 =head1 ENVIRONMENT
414
415 No environment variables are used.
416
417 =head1 AUTHOR
418
419 Larry Wall and others
420
421 =head1 SEE ALSO
422
423 L<perl>, L<perlxstut>, L<ExtUtils::MakeMaker>, and L<AutoLoader>.
424
425 =head1 DIAGNOSTICS
426
427 The usual warnings if it cannot read or write the files involved.
428
429 =head1 LIMITATIONS of B<-x>
430
431 F<h2xs> would not distinguish whether an argument to a C function
432 which is of the form, say, C<int *>, is an input, output, or
433 input/output parameter.  In particular, argument declarations of the
434 form
435
436     int
437     foo(n)
438         int *n
439
440 should be better rewritten as
441
442     int
443     foo(n)
444         int &n
445
446 if C<n> is an input parameter.
447
448 Additionally, F<h2xs> has no facilities to intuit that a function
449
450    int
451    foo(addr,l)
452         char *addr
453         int   l
454
455 takes a pair of address and length of data at this address, so it is better
456 to rewrite this function as
457
458     int
459     foo(sv)
460             SV *addr
461         PREINIT:
462             STRLEN len;
463             char *s;
464         CODE:
465             s = SvPV(sv,len);
466             RETVAL = foo(s, len);
467         OUTPUT:
468             RETVAL
469
470 or alternately
471
472     static int
473     my_foo(SV *sv)
474     {
475         STRLEN len;
476         char *s = SvPV(sv,len);
477
478         return foo(s, len);
479     }
480
481     MODULE = foo        PACKAGE = foo   PREFIX = my_
482
483     int
484     foo(sv)
485         SV *sv
486
487 See L<perlxs> and L<perlxstut> for additional details.
488
489 =cut
490
491 # ' # Grr
492 use strict;
493
494
495 my( $H2XS_VERSION ) = ' $Revision: 1.23 $ ' =~ /\$Revision:\s+([^\s]+)/;
496 my $TEMPLATE_VERSION = '0.01';
497 my @ARGS = @ARGV;
498 my $compat_version = $];
499
500 use Getopt::Long;
501 use Config;
502 use Text::Wrap;
503 $Text::Wrap::huge = 'overflow';
504 $Text::Wrap::columns = 80;
505 use ExtUtils::Constant qw (WriteConstants WriteMakefileSnippet autoload);
506 use File::Compare;
507 use File::Path;
508
509 sub usage {
510     warn "@_\n" if @_;
511     die <<EOFUSAGE;
512 h2xs [OPTIONS ... ] [headerfile [extra_libraries]]
513 version: $H2XS_VERSION
514 OPTIONS:
515     -A, --omit-autoload   Omit all autoloading facilities (implies -c).
516     -B, --beta-version    Use beta \$VERSION of 0.00_01 (ignored if -v).
517     -C, --omit-changes    Omit creating the Changes file, add HISTORY heading
518                           to stub POD.
519     -F, --cpp-flags       Additional flags for C preprocessor/compile.
520     -M, --func-mask       Mask to select C functions/macros
521                           (default is select all).
522     -O, --overwrite-ok    Allow overwriting of a pre-existing extension directory.
523     -P, --omit-pod        Omit the stub POD section.
524     -X, --omit-XS         Omit the XS portion (implies both -c and -f).
525     -a, --gen-accessors   Generate get/set accessors for struct and union members
526                           (used with -x).
527     -b, --compat-version  Specify a perl version to be backwards compatibile with.
528     -c, --omit-constant   Omit the constant() function and specialised AUTOLOAD
529                           from the XS file.
530     -d, --debugging       Turn on debugging messages.
531     -e, --omit-enums      Omit constants from enums in the constant() function.
532                           If a pattern is given, only the matching enums are
533                           ignored.
534     -f, --force           Force creation of the extension even if the C header
535                           does not exist.
536     -g, --global          Include code for safely storing static data in the .xs file.
537     -h, -?, --help        Display this help message.
538     -k, --omit-const-func Omit 'const' attribute on function arguments
539                           (used with -x).
540     -m, --gen-tied-var    Generate tied variables for access to declared
541                           variables.
542     -n, --name            Specify a name to use for the extension (recommended).
543     -o, --opaque-re       Regular expression for \"opaque\" types.
544     -p, --remove-prefix   Specify a prefix which should be removed from the
545                           Perl function names.
546     -s, --const-subs      Create subroutines for specified macros.
547     -t, --default-type    Default type for autoloaded constants (default is IV).
548         --use-new-tests   Use Test::More in backward compatible modules.
549         --use-old-tests   Use the module Test rather than Test::More.
550         --skip-exporter   Do not export symbols.
551         --skip-ppport     Do not use portability layer.
552         --skip-autoloader Do not use the module C<AutoLoader>.
553         --skip-strict     Do not use the pragma C<strict>.
554         --skip-warnings   Do not use the pragma C<warnings>.
555     -v, --version         Specify a version number for this extension.
556     -x, --autogen-xsubs   Autogenerate XSUBs using C::Scan.
557         --use-xsloader    Use XSLoader in backward compatible modules (ignored
558                           when used with -X).
559
560 extra_libraries
561          are any libraries that might be needed for loading the
562          extension, e.g. -lm would try to link in the math library.
563 EOFUSAGE
564 }
565
566 my ($opt_A,
567     $opt_B,
568     $opt_C,
569     $opt_F,
570     $opt_M,
571     $opt_O,
572     $opt_P,
573     $opt_X,
574     $opt_a,
575     $opt_c,
576     $opt_d,
577     $opt_e,
578     $opt_f,
579     $opt_g,
580     $opt_h,
581     $opt_k,
582     $opt_m,
583     $opt_n,
584     $opt_o,
585     $opt_p,
586     $opt_s,
587     $opt_v,
588     $opt_x,
589     $opt_b,
590     $opt_t,
591     $new_test,
592     $old_test,
593     $skip_exporter,
594     $skip_ppport,
595     $skip_autoloader,
596     $skip_strict,
597     $skip_warnings,
598     $use_xsloader
599    );
600
601 Getopt::Long::Configure('bundling');
602 Getopt::Long::Configure('pass_through');
603
604 my %options = (
605                 'omit-autoload|A'    => \$opt_A,
606                 'beta-version|B'     => \$opt_B,
607                 'omit-changes|C'     => \$opt_C,
608                 'cpp-flags|F=s'      => \$opt_F,
609                 'func-mask|M=s'      => \$opt_M,
610                 'overwrite_ok|O'     => \$opt_O,
611                 'omit-pod|P'         => \$opt_P,
612                 'omit-XS|X'          => \$opt_X,
613                 'gen-accessors|a'    => \$opt_a,
614                 'compat-version|b=s' => \$opt_b,
615                 'omit-constant|c'    => \$opt_c,
616                 'debugging|d'        => \$opt_d,
617                 'omit-enums|e:s'     => \$opt_e,
618                 'force|f'            => \$opt_f,
619                 'global|g'           => \$opt_g,
620                 'help|h|?'           => \$opt_h,
621                 'omit-const-func|k'  => \$opt_k,
622                 'gen-tied-var|m'     => \$opt_m,
623                 'name|n=s'           => \$opt_n,
624                 'opaque-re|o=s'      => \$opt_o,
625                 'remove-prefix|p=s'  => \$opt_p,
626                 'const-subs|s=s'     => \$opt_s,
627                 'default-type|t=s'   => \$opt_t,
628                 'version|v=s'        => \$opt_v,
629                 'autogen-xsubs|x'    => \$opt_x,
630                 'use-new-tests'      => \$new_test,
631                 'use-old-tests'      => \$old_test,
632                 'skip-exporter'      => \$skip_exporter,
633                 'skip-ppport'        => \$skip_ppport,
634                 'skip-autoloader'    => \$skip_autoloader,
635                 'skip-warnings'      => \$skip_warnings,
636                 'skip-strict'        => \$skip_strict,
637                 'use-xsloader'       => \$use_xsloader,
638               );
639
640 GetOptions(%options) || usage;
641
642 usage if $opt_h;
643
644 if( $opt_b ){
645     usage "You cannot use -b and -m at the same time.\n" if ($opt_b && $opt_m);
646     $opt_b =~ /^v?(\d+)\.(\d+)\.(\d+)/ ||
647     usage "You must provide the backwards compatibility version in X.Y.Z form. "
648           .  "(i.e. 5.5.0)\n";
649     my ($maj,$min,$sub) = ($1,$2,$3);
650     if ($maj < 5 || ($maj == 5 && $min < 6)) {
651         $compat_version =
652             $sub ? sprintf("%d.%03d%02d",$maj,$min,$sub) :
653                    sprintf("%d.%03d",    $maj,$min);
654     } else {
655         $compat_version =
656             $sub ? sprintf("%d.%03d%03d",$maj,$min,$sub) :
657                    sprintf("%d.%03d",    $maj,$min);
658     }
659 } else {
660     my ($maj,$min,$sub) = $compat_version =~ /(\d+)\.(\d\d\d)(\d*)/;
661     $sub ||= 0;
662     warn sprintf <<'EOF', $maj,$min,$sub;
663 Defaulting to backwards compatibility with perl %d.%d.%d
664 If you intend this module to be compatible with earlier perl versions, please
665 specify a minimum perl version with the -b option.
666
667 EOF
668 }
669
670 if( $opt_B ){
671     $TEMPLATE_VERSION = '0.00_01';
672 }
673
674 if( $opt_v ){
675         $TEMPLATE_VERSION = $opt_v;
676
677     # check if it is numeric
678     my $temp_version = $TEMPLATE_VERSION;
679     my $beta_version = $temp_version =~ s/(\d)_(\d\d)/$1$2/;
680     my $notnum;
681     {
682         local $SIG{__WARN__} = sub { $notnum = 1 };
683         use warnings 'numeric';
684         $temp_version = 0+$temp_version;
685     }
686
687     if ($notnum) {
688         my $module = $opt_n || 'Your::Module';
689         warn <<"EOF";
690 You have specified a non-numeric version.  Unless you supply an
691 appropriate VERSION class method, users may not be able to specify a
692 minimum required version with C<use $module versionnum>.
693
694 EOF
695     }
696     else {
697         $opt_B = $beta_version;
698     }
699 }
700
701 # -A implies -c.
702 $skip_autoloader = $opt_c = 1 if $opt_A;
703
704 # -X implies -c and -f
705 $opt_c = $opt_f = 1 if $opt_X;
706
707 $opt_t ||= 'IV';
708
709 my %const_xsub;
710 %const_xsub = map { $_,1 } split(/,+/, $opt_s) if $opt_s;
711
712 my $extralibs = '';
713
714 my @path_h;
715
716 while (my $arg = shift) {
717     if ($arg =~ /^-l/i) {
718         $extralibs .= "$arg ";
719         next;
720     }
721     last if $extralibs;
722     push(@path_h, $arg);
723 }
724
725 usage "Must supply header file or module name\n"
726         unless (@path_h or $opt_n);
727
728 my $fmask;
729 my $tmask;
730
731 $fmask = qr{$opt_M} if defined $opt_M;
732 $tmask = qr{$opt_o} if defined $opt_o;
733 my $tmask_all = $tmask && $opt_o eq '.';
734
735 if ($opt_x) {
736   eval {require C::Scan; 1}
737     or die <<EOD;
738 C::Scan required if you use -x option.
739 To install C::Scan, execute
740    perl -MCPAN -e "install C::Scan"
741 EOD
742   unless ($tmask_all) {
743     $C::Scan::VERSION >= 0.70
744       or die <<EOD;
745 C::Scan v. 0.70 or later required unless you use -o . option.
746 You have version $C::Scan::VERSION installed as $INC{'C/Scan.pm'}.
747 To install C::Scan, execute
748    perl -MCPAN -e "install C::Scan"
749 EOD
750   }
751   if (($opt_m || $opt_a) && $C::Scan::VERSION < 0.73) {
752     die <<EOD;
753 C::Scan v. 0.73 or later required to use -m or -a options.
754 You have version $C::Scan::VERSION installed as $INC{'C/Scan.pm'}.
755 To install C::Scan, execute
756    perl -MCPAN -e "install C::Scan"
757 EOD
758   }
759 }
760 elsif ($opt_o or $opt_F) {
761   warn <<EOD if $opt_o;
762 Option -o does not make sense without -x.
763 EOD
764   warn <<EOD if $opt_F and $opt_X ;
765 Option -F does not make sense with -X.
766 EOD
767 }
768
769 my @path_h_ini = @path_h;
770 my ($name, %fullpath, %prefix, %seen_define, %prefixless, %const_names);
771
772 my $module = $opt_n;
773
774 if( @path_h ){
775     use File::Spec;
776     my @paths;
777     my $pre_sub_tri_graphs = 1;
778     if ($^O eq 'VMS') {  # Consider overrides of default location
779       # XXXX This is not equivalent to what the older version did:
780       #         it was looking at $hadsys header-file per header-file...
781       my($hadsys) = grep s!^sys/!!i , @path_h;
782       @paths = qw( Sys$Library VAXC$Include );
783       push @paths, ($hadsys ? 'GNU_CC_Include[vms]' : 'GNU_CC_Include[000000]');
784       push @paths, qw( DECC$Library_Include DECC$System_Include );
785     }
786     else {
787       @paths = (File::Spec->curdir(), $Config{usrinc},
788                 (split ' ', $Config{locincpth}), '/usr/include');
789     }
790     foreach my $path_h (@path_h) {
791         $name ||= $path_h;
792     $module ||= do {
793       $name =~ s/\.h$//;
794       if ( $name !~ /::/ ) {
795         $name =~ s#^.*/##;
796         $name = "\u$name";
797       }
798       $name;
799     };
800
801     if( $path_h =~ s#::#/#g && $opt_n ){
802         warn "Nesting of headerfile ignored with -n\n";
803     }
804     $path_h .= ".h" unless $path_h =~ /\.h$/;
805     my $fullpath = $path_h;
806     $path_h =~ s/,.*$// if $opt_x;
807     $fullpath{$path_h} = $fullpath;
808
809     # Minor trickery: we can't chdir() before we processed the headers
810     # (so know the name of the extension), but the header may be in the
811     # extension directory...
812     my $tmp_path_h = $path_h;
813     my $rel_path_h = $path_h;
814     my @dirs = @paths;
815     if (not -f $path_h) {
816       my $found;
817       for my $dir (@paths) {
818         $found++, last
819           if -f ($path_h = File::Spec->catfile($dir, $tmp_path_h));
820       }
821       if ($found) {
822         $rel_path_h = $path_h;
823         $fullpath{$path_h} = $fullpath;
824       } else {
825         (my $epath = $module) =~ s,::,/,g;
826         $epath = File::Spec->catdir('ext', $epath) if -d 'ext';
827         $rel_path_h = File::Spec->catfile($epath, $tmp_path_h);
828         $path_h = $tmp_path_h;  # Used during -x
829         push @dirs, $epath;
830       }
831     }
832
833     if (!$opt_c) {
834       die "Can't find $tmp_path_h in @dirs\n"
835         if ( ! $opt_f && ! -f "$rel_path_h" );
836       # Scan the header file (we should deal with nested header files)
837       # Record the names of simple #define constants into const_names
838             # Function prototypes are processed below.
839       open(CH, "<$rel_path_h") || die "Can't open $rel_path_h: $!\n";
840     defines:
841       while (<CH>) {
842         if ($pre_sub_tri_graphs) {
843             # Preprocess all tri-graphs
844             # including things stuck in quoted string constants.
845             s/\?\?=/#/g;                         # | ??=|  #|
846             s/\?\?\!/|/g;                        # | ??!|  ||
847             s/\?\?'/^/g;                         # | ??'|  ^|
848             s/\?\?\(/[/g;                        # | ??(|  [|
849             s/\?\?\)/]/g;                        # | ??)|  ]|
850             s/\?\?\-/~/g;                        # | ??-|  ~|
851             s/\?\?\//\\/g;                       # | ??/|  \|
852             s/\?\?</{/g;                         # | ??<|  {|
853             s/\?\?>/}/g;                         # | ??>|  }|
854         }
855         if (/^[ \t]*#[ \t]*define\s+([\$\w]+)\b(?!\()\s*(?=[^"\s])(.*)/) {
856             my $def = $1;
857             my $rest = $2;
858             $rest =~ s!/\*.*?(\*/|\n)|//.*!!g; # Remove comments
859             $rest =~ s/^\s+//;
860             $rest =~ s/\s+$//;
861             # Cannot do: (-1) and ((LHANDLE)3) are OK:
862             #print("Skip non-wordy $def => $rest\n"),
863             #  next defines if $rest =~ /[^\w\$]/;
864             if ($rest =~ /"/) {
865               print("Skip stringy $def => $rest\n") if $opt_d;
866               next defines;
867             }
868             print "Matched $_ ($def)\n" if $opt_d;
869             $seen_define{$def} = $rest;
870             $_ = $def;
871             next if /^_.*_h_*$/i; # special case, but for what?
872             if (defined $opt_p) {
873               if (!/^$opt_p(\d)/) {
874                 ++$prefix{$_} if s/^$opt_p//;
875               }
876               else {
877                 warn "can't remove $opt_p prefix from '$_'!\n";
878               }
879             }
880             $prefixless{$def} = $_;
881             if (!$fmask or /$fmask/) {
882                 print "... Passes mask of -M.\n" if $opt_d and $fmask;
883                 $const_names{$_}++;
884             }
885           }
886       }
887       if (defined $opt_e and !$opt_e) {
888         close(CH);
889       }
890       else {
891         # Work from miniperl too - on "normal" systems
892         my $SEEK_SET = eval 'use Fcntl qw/SEEK_SET/; SEEK_SET' or 0;
893         seek CH, 0, $SEEK_SET;
894         my $src = do { local $/; <CH> };
895         close CH;
896         no warnings 'uninitialized';
897
898         # Remove C and C++ comments
899         $src =~ s#/\*[^*]*\*+([^/*][^*]*\*+)*/|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#$2#gs;
900
901         while ($src =~ /\benum\s*([\w_]*)\s*\{\s([^}]+)\}/gsc) {
902             my ($enum_name, $enum_body) = ($1, $2);
903             # skip enums matching $opt_e
904             next if $opt_e && $enum_name =~ /$opt_e/;
905             my $val = 0;
906             for my $item (split /,/, $enum_body) {
907                 my ($key, $declared_val) = $item =~ /(\w+)\s*(?:=\s*(.*))?/;
908                 $val = defined($declared_val) && length($declared_val) ? $declared_val : 1 + $val;
909                 $seen_define{$key} = $val;
910                 $const_names{$key}++;
911             }
912         } # while (...)
913       } # if (!defined $opt_e or $opt_e)
914     }
915     }
916 }
917
918 # Save current directory so that C::Scan can use it
919 my $cwd = File::Spec->rel2abs( File::Spec->curdir );
920
921 # As Ilya suggested, use a name that contains - and then it can't clash with
922 # the names of any packages. A directory 'fallback' will clash with any
923 # new pragmata down the fallback:: tree, but that seems unlikely.
924 my $constscfname = 'const-c.inc';
925 my $constsxsfname = 'const-xs.inc';
926 my $fallbackdirname = 'fallback';
927
928 my $ext = chdir 'ext' ? 'ext/' : '';
929
930 my @modparts  = split(/::/,$module);
931 my $modpname  = join('-', @modparts);
932 my $modfname  = pop @modparts;
933 my $modpmdir  = join '/', 'lib', @modparts;
934 my $modpmname = join '/', $modpmdir, $modfname.'.pm';
935
936 if ($opt_O) {
937         warn "Overwriting existing $ext$modpname!!!\n" if -e $modpname;
938 }
939 else {
940         die "Won't overwrite existing $ext$modpname\n" if -e $modpname;
941 }
942 -d "$modpname"   || mkpath([$modpname], 0, 0775);
943 chdir($modpname) || die "Can't chdir $ext$modpname: $!\n";
944
945 my %types_seen;
946 my %std_types;
947 my $fdecls = [];
948 my $fdecls_parsed = [];
949 my $typedef_rex;
950 my %typedefs_pre;
951 my %known_fnames;
952 my %structs;
953
954 my @fnames;
955 my @fnames_no_prefix;
956 my %vdecl_hash;
957 my @vdecls;
958
959 if( ! $opt_X ){  # use XS, unless it was disabled
960   unless ($skip_ppport) {
961     require Devel::PPPort;
962     warn "Writing $ext$modpname/ppport.h\n";
963     Devel::PPPort::WriteFile('ppport.h')
964         || die "Can't create $ext$modpname/ppport.h: $!\n";
965   }
966   open(XS, ">$modfname.xs") || die "Can't create $ext$modpname/$modfname.xs: $!\n";
967   if ($opt_x) {
968     warn "Scanning typemaps...\n";
969     get_typemap();
970     my @td;
971     my @good_td;
972     my $addflags = $opt_F || '';
973
974     foreach my $filename (@path_h) {
975       my $c;
976       my $filter;
977
978       if ($fullpath{$filename} =~ /,/) {
979         $filename = $`;
980         $filter = $';
981       }
982       warn "Scanning $filename for functions...\n";
983       my @styles = $Config{gccversion} ? qw(C++ C9X GNU) : qw(C++ C9X);
984       $c = new C::Scan 'filename' => $filename, 'filename_filter' => $filter,
985         'add_cppflags' => $addflags, 'c_styles' => \@styles;
986       $c->set('includeDirs' => ["$Config::Config{archlib}/CORE", $cwd]);
987
988       $c->get('keywords')->{'__restrict'} = 1;
989
990       push @$fdecls_parsed, @{ $c->get('parsed_fdecls') };
991       push(@$fdecls, @{$c->get('fdecls')});
992
993       push @td, @{$c->get('typedefs_maybe')};
994       if ($opt_a) {
995         my $structs = $c->get('typedef_structs');
996         @structs{keys %$structs} = values %$structs;
997       }
998
999       if ($opt_m) {
1000         %vdecl_hash = %{ $c->get('vdecl_hash') };
1001         @vdecls = sort keys %vdecl_hash;
1002         for (local $_ = 0; $_ < @vdecls; ++$_) {
1003           my $var = $vdecls[$_];
1004           my($type, $post) = @{ $vdecl_hash{$var} };
1005           if (defined $post) {
1006             warn "Can't handle variable '$type $var $post', skipping.\n";
1007             splice @vdecls, $_, 1;
1008             redo;
1009           }
1010           $type = normalize_type($type);
1011           $vdecl_hash{$var} = $type;
1012         }
1013       }
1014
1015       unless ($tmask_all) {
1016         warn "Scanning $filename for typedefs...\n";
1017         my $td = $c->get('typedef_hash');
1018         # eval {require 'dumpvar.pl'; ::dumpValue($td)} or warn $@ if $opt_d;
1019         my @f_good_td = grep $td->{$_}[1] eq '', keys %$td;
1020         push @good_td, @f_good_td;
1021         @typedefs_pre{@f_good_td}  = map $_->[0], @$td{@f_good_td};
1022       }
1023     }
1024     { local $" = '|';
1025       $typedef_rex = qr(\b(?<!struct )(?:@good_td)\b) if @good_td;
1026     }
1027     %known_fnames = map @$_[1,3], @$fdecls_parsed; # [1,3] is NAME, FULLTEXT
1028     if ($fmask) {
1029       my @good;
1030       for my $i (0..$#$fdecls_parsed) {
1031         next unless $fdecls_parsed->[$i][1] =~ /$fmask/; # [1] is NAME
1032         push @good, $i;
1033         print "... Function $fdecls_parsed->[$i][1] passes -M mask.\n"
1034           if $opt_d;
1035       }
1036       $fdecls = [@$fdecls[@good]];
1037       $fdecls_parsed = [@$fdecls_parsed[@good]];
1038     }
1039     @fnames = sort map $_->[1], @$fdecls_parsed; # 1 is NAME
1040     # Sort declarations:
1041     {
1042       my %h = map( ($_->[1], $_), @$fdecls_parsed);
1043       $fdecls_parsed = [ @h{@fnames} ];
1044     }
1045     @fnames_no_prefix = @fnames;
1046     @fnames_no_prefix
1047       = sort map { ++$prefix{$_} if s/^$opt_p(?!\d)//; $_ } @fnames_no_prefix
1048          if defined $opt_p;
1049     # Remove macros which expand to typedefs
1050     print "Typedefs are @td.\n" if $opt_d;
1051     my %td = map {($_, $_)} @td;
1052     # Add some other possible but meaningless values for macros
1053     for my $k (qw(char double float int long short unsigned signed void)) {
1054       $td{"$_$k"} = "$_$k" for ('', 'signed ', 'unsigned ');
1055     }
1056     # eval {require 'dumpvar.pl'; ::dumpValue( [\@td, \%td] ); 1} or warn $@;
1057     my $n = 0;
1058     my %bad_macs;
1059     while (keys %td > $n) {
1060       $n = keys %td;
1061       my ($k, $v);
1062       while (($k, $v) = each %seen_define) {
1063         # print("found '$k'=>'$v'\n"),
1064         $bad_macs{$k} = $td{$k} = $td{$v} if exists $td{$v};
1065       }
1066     }
1067     # Now %bad_macs contains names of bad macros
1068     for my $k (keys %bad_macs) {
1069       delete $const_names{$prefixless{$k}};
1070       print "Ignoring macro $k which expands to a typedef name '$bad_macs{$k}'\n" if $opt_d;
1071     }
1072   }
1073 }
1074 my @const_names = sort keys %const_names;
1075
1076 -d $modpmdir || mkpath([$modpmdir], 0, 0775);
1077 open(PM, ">$modpmname") || die "Can't create $ext$modpname/$modpmname: $!\n";
1078
1079 $" = "\n\t";
1080 warn "Writing $ext$modpname/$modpmname\n";
1081
1082 print PM <<"END";
1083 package $module;
1084
1085 use $compat_version;
1086 END
1087
1088 print PM <<"END" unless $skip_strict;
1089 use strict;
1090 END
1091
1092 print PM "use warnings;\n" unless $skip_warnings or $compat_version < 5.006;
1093
1094 unless( $opt_X || $opt_c || $opt_A ){
1095         # we'll have an AUTOLOAD(), and it will have $AUTOLOAD and
1096         # will want Carp.
1097         print PM <<'END';
1098 use Carp;
1099 END
1100 }
1101
1102 print PM <<'END' unless $skip_exporter;
1103
1104 require Exporter;
1105 END
1106
1107 my $use_Dyna = (not $opt_X and $compat_version < 5.006 and not $use_xsloader);
1108 print PM <<"END" if $use_Dyna;  # use DynaLoader, unless XS was disabled
1109 require DynaLoader;
1110 END
1111
1112
1113 # Are we using AutoLoader or not?
1114 unless ($skip_autoloader) { # no autoloader whatsoever.
1115         unless ($opt_c) { # we're doing the AUTOLOAD
1116                 print PM "use AutoLoader;\n";
1117         }
1118         else {
1119                 print PM "use AutoLoader qw(AUTOLOAD);\n"
1120         }
1121 }
1122
1123 if ( $compat_version < 5.006 ) {
1124     my $vars = '$VERSION @ISA';
1125     $vars .= ' @EXPORT @EXPORT_OK %EXPORT_TAGS' unless $skip_exporter;
1126     $vars .= ' $AUTOLOAD' unless $opt_X || $opt_c || $opt_A;
1127     $vars .= ' $XS_VERSION' if $opt_B && !$opt_X;
1128     print PM "use vars qw($vars);";
1129 }
1130
1131 # Determine @ISA.
1132 my @modISA;
1133 push @modISA, 'Exporter'        unless $skip_exporter;
1134 push @modISA, 'DynaLoader'      if $use_Dyna;  # no XS
1135 my $myISA = "our \@ISA = qw(@modISA);";
1136 $myISA =~ s/^our // if $compat_version < 5.006;
1137
1138 print PM "\n$myISA\n\n";
1139
1140 my @exported_names = (@const_names, @fnames_no_prefix, map '$'.$_, @vdecls);
1141
1142 my $tmp='';
1143 $tmp .= <<"END" unless $skip_exporter;
1144 # Items to export into callers namespace by default. Note: do not export
1145 # names by default without a very good reason. Use EXPORT_OK instead.
1146 # Do not simply export all your public functions/methods/constants.
1147
1148 # This allows declaration       use $module ':all';
1149 # If you do not need this, moving things directly into \@EXPORT or \@EXPORT_OK
1150 # will save memory.
1151 our %EXPORT_TAGS = ( 'all' => [ qw(
1152         @exported_names
1153 ) ] );
1154
1155 our \@EXPORT_OK = ( \@{ \$EXPORT_TAGS{'all'} } );
1156
1157 our \@EXPORT = qw(
1158         @const_names
1159 );
1160
1161 END
1162
1163 $tmp .= "our \$VERSION = '$TEMPLATE_VERSION';\n";
1164 if ($opt_B) {
1165     $tmp .= "our \$XS_VERSION = \$VERSION;\n" unless $opt_X;
1166     $tmp .= "\$VERSION = eval \$VERSION;  # see L<perlmodstyle>\n";
1167 }
1168 $tmp .= "\n";
1169
1170 $tmp =~ s/^our //mg if $compat_version < 5.006;
1171 print PM $tmp;
1172
1173 if (@vdecls) {
1174     printf PM "our(@{[ join ', ', map '$'.$_, @vdecls ]});\n\n";
1175 }
1176
1177
1178 print PM autoload ($module, $compat_version) unless $opt_c or $opt_X;
1179
1180 if( ! $opt_X ){ # print bootstrap, unless XS is disabled
1181   if ($use_Dyna) {
1182         $tmp = <<"END";
1183 bootstrap $module \$VERSION;
1184 END
1185   } else {
1186         $tmp = <<"END";
1187 require XSLoader;
1188 XSLoader::load('$module', \$VERSION);
1189 END
1190   }
1191   $tmp =~ s:\$VERSION:\$XS_VERSION:g if $opt_B;
1192   print PM $tmp;
1193 }
1194
1195 # tying the variables can happen only after bootstrap
1196 if (@vdecls) {
1197     printf PM <<END;
1198 {
1199 @{[ join "\n", map "    _tievar_$_(\$$_);", @vdecls ]}
1200 }
1201
1202 END
1203 }
1204
1205 my $after;
1206 if( $opt_P ){ # if POD is disabled
1207         $after = '__END__';
1208 }
1209 else {
1210         $after = '=cut';
1211 }
1212
1213 print PM <<"END";
1214
1215 # Preloaded methods go here.
1216 END
1217
1218 print PM <<"END" unless $opt_A;
1219
1220 # Autoload methods go after $after, and are processed by the autosplit program.
1221 END
1222
1223 print PM <<"END";
1224
1225 1;
1226 __END__
1227 END
1228
1229 my ($email,$author,$licence);
1230
1231 eval {
1232        my $username;
1233        ($username,$author) = (getpwuid($>))[0,6];
1234        if (defined $username && defined $author) {
1235            $author =~ s/,.*$//; # in case of sub fields
1236            my $domain = $Config{'mydomain'};
1237            $domain =~ s/^\.//;
1238            $email = "$username\@$domain";
1239        }
1240      };
1241
1242 $author ||= "A. U. Thor";
1243 $email  ||= 'a.u.thor@a.galaxy.far.far.away';
1244
1245 $licence = sprintf << "DEFAULT", $^V;
1246 Copyright (C) ${\(1900 + (localtime) [5])} by $author
1247
1248 This library is free software; you can redistribute it and/or modify
1249 it under the same terms as Perl itself, either Perl version %vd or,
1250 at your option, any later version of Perl 5 you may have available.
1251 DEFAULT
1252
1253 my $revhist = '';
1254 $revhist = <<EOT if $opt_C;
1255 #
1256 #=head1 HISTORY
1257 #
1258 #=over 8
1259 #
1260 #=item $TEMPLATE_VERSION
1261 #
1262 #Original version; created by h2xs $H2XS_VERSION with options
1263 #
1264 #  @ARGS
1265 #
1266 #=back
1267 #
1268 EOT
1269
1270 my $exp_doc = $skip_exporter ? '' : <<EOD;
1271 #
1272 #=head2 EXPORT
1273 #
1274 #None by default.
1275 #
1276 EOD
1277
1278 if (@const_names and not $opt_P) {
1279   $exp_doc .= <<EOD unless $skip_exporter;
1280 #=head2 Exportable constants
1281 #
1282 #  @{[join "\n  ", @const_names]}
1283 #
1284 EOD
1285 }
1286
1287 if (defined $fdecls and @$fdecls and not $opt_P) {
1288   $exp_doc .= <<EOD unless $skip_exporter;
1289 #=head2 Exportable functions
1290 #
1291 EOD
1292
1293 #  $exp_doc .= <<EOD if $opt_p;
1294 #When accessing these functions from Perl, prefix C<$opt_p> should be removed.
1295 #
1296 #EOD
1297   $exp_doc .= <<EOD unless $skip_exporter;
1298 #  @{[join "\n  ", @known_fnames{@fnames}]}
1299 #
1300 EOD
1301 }
1302
1303 my $meth_doc = '';
1304
1305 if ($opt_x && $opt_a) {
1306   my($name, $struct);
1307   $meth_doc .= accessor_docs($name, $struct)
1308     while ($name, $struct) = each %structs;
1309 }
1310
1311 # Prefix the default licence with hash symbols.
1312 # Is this just cargo cult - it seems that the first thing that happens to this
1313 # block is that all the hashes are then s///g out.
1314 my $licence_hash = $licence;
1315 $licence_hash =~ s/^/#/gm;
1316
1317 my $pod;
1318 $pod = <<"END" unless $opt_P;
1319 ## Below is stub documentation for your module. You'd better edit it!
1320 #
1321 #=head1 NAME
1322 #
1323 #$module - Perl extension for blah blah blah
1324 #
1325 #=head1 SYNOPSIS
1326 #
1327 #  use $module;
1328 #  blah blah blah
1329 #
1330 #=head1 DESCRIPTION
1331 #
1332 #Stub documentation for $module, created by h2xs. It looks like the
1333 #author of the extension was negligent enough to leave the stub
1334 #unedited.
1335 #
1336 #Blah blah blah.
1337 $exp_doc$meth_doc$revhist
1338 #
1339 #=head1 SEE ALSO
1340 #
1341 #Mention other useful documentation such as the documentation of
1342 #related modules or operating system documentation (such as man pages
1343 #in UNIX), or any relevant external documentation such as RFCs or
1344 #standards.
1345 #
1346 #If you have a mailing list set up for your module, mention it here.
1347 #
1348 #If you have a web site set up for your module, mention it here.
1349 #
1350 #=head1 AUTHOR
1351 #
1352 #$author, E<lt>${email}E<gt>
1353 #
1354 #=head1 COPYRIGHT AND LICENSE
1355 #
1356 $licence_hash
1357 #
1358 #=cut
1359 END
1360
1361 $pod =~ s/^\#//gm unless $opt_P;
1362 print PM $pod unless $opt_P;
1363
1364 close PM;
1365
1366
1367 if( ! $opt_X ){ # print XS, unless it is disabled
1368 warn "Writing $ext$modpname/$modfname.xs\n";
1369
1370 print XS <<"END";
1371 #include "EXTERN.h"
1372 #include "perl.h"
1373 #include "XSUB.h"
1374
1375 END
1376
1377 print XS <<"END" unless $skip_ppport;
1378 #include "ppport.h"
1379
1380 END
1381
1382 if( @path_h ){
1383     foreach my $path_h (@path_h_ini) {
1384         my($h) = $path_h;
1385         $h =~ s#^/usr/include/##;
1386         if ($^O eq 'VMS') { $h =~ s#.*vms\]#sys/# or $h =~ s#.*[:>\]]##; }
1387         print XS qq{#include <$h>\n};
1388     }
1389     print XS "\n";
1390 }
1391
1392 print XS <<"END" if $opt_g;
1393
1394 /* Global Data */
1395
1396 #define MY_CXT_KEY "${module}::_guts" XS_VERSION
1397
1398 typedef struct {
1399     /* Put Global Data in here */
1400     int dummy;          /* you can access this elsewhere as MY_CXT.dummy */
1401 } my_cxt_t;
1402
1403 START_MY_CXT
1404
1405 END
1406
1407 my %pointer_typedefs;
1408 my %struct_typedefs;
1409
1410 sub td_is_pointer {
1411   my $type = shift;
1412   my $out = $pointer_typedefs{$type};
1413   return $out if defined $out;
1414   my $otype = $type;
1415   $out = ($type =~ /\*$/);
1416   # This converts only the guys which do not have trailing part in the typedef
1417   if (not $out
1418       and $typedef_rex and $type =~ s/($typedef_rex)/$typedefs_pre{$1}/go) {
1419     $type = normalize_type($type);
1420     print "Is-Pointer: Type mutation via typedefs: $otype ==> $type\n"
1421       if $opt_d;
1422     $out = td_is_pointer($type);
1423   }
1424   return ($pointer_typedefs{$otype} = $out);
1425 }
1426
1427 sub td_is_struct {
1428   my $type = shift;
1429   my $out = $struct_typedefs{$type};
1430   return $out if defined $out;
1431   my $otype = $type;
1432   $out = ($type =~ /^(struct|union)\b/) && !td_is_pointer($type);
1433   # This converts only the guys which do not have trailing part in the typedef
1434   if (not $out
1435       and $typedef_rex and $type =~ s/($typedef_rex)/$typedefs_pre{$1}/go) {
1436     $type = normalize_type($type);
1437     print "Is-Struct: Type mutation via typedefs: $otype ==> $type\n"
1438       if $opt_d;
1439     $out = td_is_struct($type);
1440   }
1441   return ($struct_typedefs{$otype} = $out);
1442 }
1443
1444 print_tievar_subs(\*XS, $_, $vdecl_hash{$_}) for @vdecls;
1445
1446 if( ! $opt_c ) {
1447   # We write the "sample" files used when this module is built by perl without
1448   # ExtUtils::Constant.
1449   # h2xs will later check that these are the same as those generated by the
1450   # code embedded into Makefile.PL
1451   unless (-d $fallbackdirname) {
1452     mkdir "$fallbackdirname" or die "Cannot mkdir $fallbackdirname: $!\n";
1453   }
1454   warn "Writing $ext$modpname/$fallbackdirname/$constscfname\n";
1455   warn "Writing $ext$modpname/$fallbackdirname/$constsxsfname\n";
1456   my $cfallback = File::Spec->catfile($fallbackdirname, $constscfname);
1457   my $xsfallback = File::Spec->catfile($fallbackdirname, $constsxsfname);
1458   WriteConstants ( C_FILE =>       $cfallback,
1459                    XS_FILE =>      $xsfallback,
1460                    DEFAULT_TYPE => $opt_t,
1461                    NAME =>         $module,
1462                    NAMES =>        \@const_names,
1463                  );
1464   print XS "#include \"$constscfname\"\n";
1465 }
1466
1467
1468 my $prefix = defined $opt_p ? "PREFIX = $opt_p" : '';
1469
1470 # Now switch from C to XS by issuing the first MODULE declaration:
1471 print XS <<"END";
1472
1473 MODULE = $module                PACKAGE = $module               $prefix
1474
1475 END
1476
1477 # If a constant() function was #included then output a corresponding
1478 # XS declaration:
1479 print XS "INCLUDE: $constsxsfname\n" unless $opt_c;
1480
1481 print XS <<"END" if $opt_g;
1482
1483 BOOT:
1484 {
1485     MY_CXT_INIT;
1486     /* If any of the fields in the my_cxt_t struct need
1487        to be initialised, do it here.
1488      */
1489 }
1490
1491 END
1492
1493 foreach (sort keys %const_xsub) {
1494     print XS <<"END";
1495 char *
1496 $_()
1497
1498     CODE:
1499 #ifdef $_
1500         RETVAL = $_;
1501 #else
1502         croak("Your vendor has not defined the $module macro $_");
1503 #endif
1504
1505     OUTPUT:
1506         RETVAL
1507
1508 END
1509 }
1510
1511 my %seen_decl;
1512 my %typemap;
1513
1514 sub print_decl {
1515   my $fh = shift;
1516   my $decl = shift;
1517   my ($type, $name, $args) = @$decl;
1518   return if $seen_decl{$name}++; # Need to do the same for docs as well?
1519
1520   my @argnames = map {$_->[1]} @$args;
1521   my @argtypes = map { normalize_type( $_->[0], 1 ) } @$args;
1522   if ($opt_k) {
1523     s/^\s*const\b\s*// for @argtypes;
1524   }
1525   my @argarrays = map { $_->[4] || '' } @$args;
1526   my $numargs = @$args;
1527   if ($numargs and $argtypes[-1] eq '...') {
1528     $numargs--;
1529     $argnames[-1] = '...';
1530   }
1531   local $" = ', ';
1532   $type = normalize_type($type, 1);
1533
1534   print $fh <<"EOP";
1535
1536 $type
1537 $name(@argnames)
1538 EOP
1539
1540   for my $arg (0 .. $numargs - 1) {
1541     print $fh <<"EOP";
1542         $argtypes[$arg] $argnames[$arg]$argarrays[$arg]
1543 EOP
1544   }
1545 }
1546
1547 sub print_tievar_subs {
1548   my($fh, $name, $type) = @_;
1549   print $fh <<END;
1550 I32
1551 _get_$name(IV index, SV *sv) {
1552     dSP;
1553     PUSHMARK(SP);
1554     XPUSHs(sv);
1555     PUTBACK;
1556     (void)call_pv("$module\::_get_$name", G_DISCARD);
1557     return (I32)0;
1558 }
1559
1560 I32
1561 _set_$name(IV index, SV *sv) {
1562     dSP;
1563     PUSHMARK(SP);
1564     XPUSHs(sv);
1565     PUTBACK;
1566     (void)call_pv("$module\::_set_$name", G_DISCARD);
1567     return (I32)0;
1568 }
1569
1570 END
1571 }
1572
1573 sub print_tievar_xsubs {
1574   my($fh, $name, $type) = @_;
1575   print $fh <<END;
1576 void
1577 _tievar_$name(sv)
1578         SV* sv
1579     PREINIT:
1580         struct ufuncs uf;
1581     CODE:
1582         uf.uf_val = &_get_$name;
1583         uf.uf_set = &_set_$name;
1584         uf.uf_index = (IV)&_get_$name;
1585         sv_magic(sv, 0, 'U', (char*)&uf, sizeof(uf));
1586
1587 void
1588 _get_$name(THIS)
1589         $type THIS = NO_INIT
1590     CODE:
1591         THIS = $name;
1592     OUTPUT:
1593         SETMAGIC: DISABLE
1594         THIS
1595
1596 void
1597 _set_$name(THIS)
1598         $type THIS
1599     CODE:
1600         $name = THIS;
1601
1602 END
1603 }
1604
1605 sub print_accessors {
1606   my($fh, $name, $struct) = @_;
1607   return unless defined $struct && $name !~ /\s|_ANON/;
1608   $name = normalize_type($name);
1609   my $ptrname = normalize_type("$name *");
1610   print $fh <<"EOF";
1611
1612 MODULE = $module                PACKAGE = ${name}               $prefix
1613
1614 $name *
1615 _to_ptr(THIS)
1616         $name THIS = NO_INIT
1617     PROTOTYPE: \$
1618     CODE:
1619         if (sv_derived_from(ST(0), "$name")) {
1620             STRLEN len;
1621             char *s = SvPV((SV*)SvRV(ST(0)), len);
1622             if (len != sizeof(THIS))
1623                 croak("Size \%d of packed data != expected \%d",
1624                         len, sizeof(THIS));
1625             RETVAL = ($name *)s;
1626         }
1627         else
1628             croak("THIS is not of type $name");
1629     OUTPUT:
1630         RETVAL
1631
1632 $name
1633 new(CLASS)
1634         char *CLASS = NO_INIT
1635     PROTOTYPE: \$
1636     CODE:
1637         Zero((void*)&RETVAL, sizeof(RETVAL), char);
1638     OUTPUT:
1639         RETVAL
1640
1641 MODULE = $module                PACKAGE = ${name}Ptr            $prefix
1642
1643 EOF
1644   my @items = @$struct;
1645   while (@items) {
1646     my $item = shift @items;
1647     if ($item->[0] =~ /_ANON/) {
1648       if (defined $item->[2]) {
1649         push @items, map [
1650           @$_[0, 1], "$item->[2]_$_->[2]", "$item->[2].$_->[2]",
1651         ], @{ $structs{$item->[0]} };
1652       } else {
1653         push @items, @{ $structs{$item->[0]} };
1654       }
1655     } else {
1656       my $type = normalize_type($item->[0]);
1657       my $ttype = $structs{$type} ? normalize_type("$type *") : $type;
1658       print $fh <<"EOF";
1659 $ttype
1660 $item->[2](THIS, __value = NO_INIT)
1661         $ptrname THIS
1662         $type __value
1663     PROTOTYPE: \$;\$
1664     CODE:
1665         if (items > 1)
1666             THIS->$item->[-1] = __value;
1667         RETVAL = @{[
1668             $type eq $ttype ? "THIS->$item->[-1]" : "&(THIS->$item->[-1])"
1669         ]};
1670     OUTPUT:
1671         RETVAL
1672
1673 EOF
1674     }
1675   }
1676 }
1677
1678 sub accessor_docs {
1679   my($name, $struct) = @_;
1680   return unless defined $struct && $name !~ /\s|_ANON/;
1681   $name = normalize_type($name);
1682   my $ptrname = $name . 'Ptr';
1683   my @items = @$struct;
1684   my @list;
1685   while (@items) {
1686     my $item = shift @items;
1687     if ($item->[0] =~ /_ANON/) {
1688       if (defined $item->[2]) {
1689         push @items, map [
1690           @$_[0, 1], "$item->[2]_$_->[2]", "$item->[2].$_->[2]",
1691         ], @{ $structs{$item->[0]} };
1692       } else {
1693         push @items, @{ $structs{$item->[0]} };
1694       }
1695     } else {
1696       push @list, $item->[2];
1697     }
1698   }
1699   my $methods = (join '(...)>, C<', @list) . '(...)';
1700
1701   my $pod = <<"EOF";
1702 #
1703 #=head2 Object and class methods for C<$name>/C<$ptrname>
1704 #
1705 #The principal Perl representation of a C object of type C<$name> is an
1706 #object of class C<$ptrname> which is a reference to an integer
1707 #representation of a C pointer.  To create such an object, one may use
1708 #a combination
1709 #
1710 #  my \$buffer = $name->new();
1711 #  my \$obj = \$buffer->_to_ptr();
1712 #
1713 #This exersizes the following two methods, and an additional class
1714 #C<$name>, the internal representation of which is a reference to a
1715 #packed string with the C structure.  Keep in mind that \$buffer should
1716 #better survive longer than \$obj.
1717 #
1718 #=over
1719 #
1720 #=item C<\$object_of_type_$name-E<gt>_to_ptr()>
1721 #
1722 #Converts an object of type C<$name> to an object of type C<$ptrname>.
1723 #
1724 #=item C<$name-E<gt>new()>
1725 #
1726 #Creates an empty object of type C<$name>.  The corresponding packed
1727 #string is zeroed out.
1728 #
1729 #=item C<$methods>
1730 #
1731 #return the current value of the corresponding element if called
1732 #without additional arguments.  Set the element to the supplied value
1733 #(and return the new value) if called with an additional argument.
1734 #
1735 #Applicable to objects of type C<$ptrname>.
1736 #
1737 #=back
1738 #
1739 EOF
1740   $pod =~ s/^\#//gm;
1741   return $pod;
1742 }
1743
1744 # Should be called before any actual call to normalize_type().
1745 sub get_typemap {
1746   # We do not want to read ./typemap by obvios reasons.
1747   my @tm =  qw(../../../typemap ../../typemap ../typemap);
1748   my $stdtypemap =  "$Config::Config{privlib}/ExtUtils/typemap";
1749   unshift @tm, $stdtypemap;
1750   my $proto_re = "[" . quotemeta('\$%&*@;') . "]" ;
1751
1752   # Start with useful default values
1753   $typemap{float} = 'T_NV';
1754
1755   foreach my $typemap (@tm) {
1756     next unless -e $typemap ;
1757     # skip directories, binary files etc.
1758     warn " Scanning $typemap\n";
1759     warn("Warning: ignoring non-text typemap file '$typemap'\n"), next
1760       unless -T $typemap ;
1761     open(TYPEMAP, $typemap)
1762       or warn ("Warning: could not open typemap file '$typemap': $!\n"), next;
1763     my $mode = 'Typemap';
1764     while (<TYPEMAP>) {
1765       next if /^\s*\#/;
1766       if (/^INPUT\s*$/)   { $mode = 'Input'; next; }
1767       elsif (/^OUTPUT\s*$/)  { $mode = 'Output'; next; }
1768       elsif (/^TYPEMAP\s*$/) { $mode = 'Typemap'; next; }
1769       elsif ($mode eq 'Typemap') {
1770         next if /^\s*($|\#)/ ;
1771         my ($type, $image);
1772         if ( ($type, $image) =
1773              /^\s*(.*?\S)\s+(\S+)\s*($proto_re*)\s*$/o
1774              # This may reference undefined functions:
1775              and not ($image eq 'T_PACKED' and $typemap eq $stdtypemap)) {
1776           $typemap{normalize_type($type)} = $image;
1777         }
1778       }
1779     }
1780     close(TYPEMAP) or die "Cannot close $typemap: $!";
1781   }
1782   %std_types = %types_seen;
1783   %types_seen = ();
1784 }
1785
1786
1787 sub normalize_type {            # Second arg: do not strip const's before \*
1788   my $type = shift;
1789   my $do_keep_deep_const = shift;
1790   # If $do_keep_deep_const this is heuristical only
1791   my $keep_deep_const = ($do_keep_deep_const ? '\b(?![^(,)]*\*)' : '');
1792   my $ignore_mods
1793     = "(?:\\b(?:(?:__const__|const)$keep_deep_const|static|inline|__inline__)\\b\\s*)*";
1794   if ($do_keep_deep_const) {    # Keep different compiled /RExen/o separately!
1795     $type =~ s/$ignore_mods//go;
1796   }
1797   else {
1798     $type =~ s/$ignore_mods//go;
1799   }
1800   $type =~ s/([^\s\w])/ $1 /g;
1801   $type =~ s/\s+$//;
1802   $type =~ s/^\s+//;
1803   $type =~ s/\s+/ /g;
1804   $type =~ s/\* (?=\*)/*/g;
1805   $type =~ s/\. \. \./.../g;
1806   $type =~ s/ ,/,/g;
1807   $types_seen{$type}++
1808     unless $type eq '...' or $type eq 'void' or $std_types{$type};
1809   $type;
1810 }
1811
1812 my $need_opaque;
1813
1814 sub assign_typemap_entry {
1815   my $type = shift;
1816   my $otype = $type;
1817   my $entry;
1818   if ($tmask and $type =~ /$tmask/) {
1819     print "Type $type matches -o mask\n" if $opt_d;
1820     $entry = (td_is_struct($type) ? "T_OPAQUE_STRUCT" : "T_PTROBJ");
1821   }
1822   elsif ($typedef_rex and $type =~ s/($typedef_rex)/$typedefs_pre{$1}/go) {
1823     $type = normalize_type $type;
1824     print "Type mutation via typedefs: $otype ==> $type\n" if $opt_d;
1825     $entry = assign_typemap_entry($type);
1826   }
1827   # XXX good do better if our UV happens to be long long
1828   return "T_NV" if $type =~ /^(unsigned\s+)?long\s+(long|double)\z/;
1829   $entry ||= $typemap{$otype}
1830     || (td_is_struct($type) ? "T_OPAQUE_STRUCT" : "T_PTROBJ");
1831   $typemap{$otype} = $entry;
1832   $need_opaque = 1 if $entry eq "T_OPAQUE_STRUCT";
1833   return $entry;
1834 }
1835
1836 for (@vdecls) {
1837   print_tievar_xsubs(\*XS, $_, $vdecl_hash{$_});
1838 }
1839
1840 if ($opt_x) {
1841   for my $decl (@$fdecls_parsed) { print_decl(\*XS, $decl) }
1842   if ($opt_a) {
1843     while (my($name, $struct) = each %structs) {
1844       print_accessors(\*XS, $name, $struct);
1845     }
1846   }
1847 }
1848
1849 close XS;
1850
1851 if (%types_seen) {
1852   my $type;
1853   warn "Writing $ext$modpname/typemap\n";
1854   open TM, ">typemap" or die "Cannot open typemap file for write: $!";
1855
1856   for $type (sort keys %types_seen) {
1857     my $entry = assign_typemap_entry $type;
1858     print TM $type, "\t" x (5 - int((length $type)/8)), "\t$entry\n"
1859   }
1860
1861   print TM <<'EOP' if $need_opaque; # Older Perls do not have correct entry
1862 #############################################################################
1863 INPUT
1864 T_OPAQUE_STRUCT
1865         if (sv_derived_from($arg, \"${ntype}\")) {
1866             STRLEN len;
1867             char  *s = SvPV((SV*)SvRV($arg), len);
1868
1869             if (len != sizeof($var))
1870                 croak(\"Size %d of packed data != expected %d\",
1871                         len, sizeof($var));
1872             $var = *($type *)s;
1873         }
1874         else
1875             croak(\"$var is not of type ${ntype}\")
1876 #############################################################################
1877 OUTPUT
1878 T_OPAQUE_STRUCT
1879         sv_setref_pvn($arg, \"${ntype}\", (char *)&$var, sizeof($var));
1880 EOP
1881
1882   close TM or die "Cannot close typemap file for write: $!";
1883 }
1884
1885 } # if( ! $opt_X )
1886
1887 warn "Writing $ext$modpname/Makefile.PL\n";
1888 open(PL, ">Makefile.PL") || die "Can't create $ext$modpname/Makefile.PL: $!\n";
1889
1890 my $prereq_pm = '';
1891
1892 if ( $compat_version < 5.00702 and $new_test )
1893 {
1894   $prereq_pm .= q%'Test::More'  =>  0, %;
1895 }
1896
1897 if ( $compat_version < 5.00600 and !$opt_X and $use_xsloader)
1898 {
1899   $prereq_pm .= q%'XSLoader'  =>  0, %;
1900 }
1901
1902 print PL <<"END";
1903 use $compat_version;
1904 use ExtUtils::MakeMaker;
1905 # See lib/ExtUtils/MakeMaker.pm for details of how to influence
1906 # the contents of the Makefile that is written.
1907 WriteMakefile(
1908     NAME              => '$module',
1909     VERSION_FROM      => '$modpmname', # finds \$VERSION
1910     PREREQ_PM         => {$prereq_pm}, # e.g., Module::Name => 1.1
1911     (\$] >= 5.005 ?     ## Add these new keywords supported since 5.005
1912       (ABSTRACT_FROM  => '$modpmname', # retrieve abstract from module
1913        AUTHOR         => '$author <$email>') : ()),
1914 END
1915 if (!$opt_X) { # print C stuff, unless XS is disabled
1916   $opt_F = '' unless defined $opt_F;
1917   my $I = (((glob '*.h') || (glob '*.hh')) ? '-I.' : '');
1918   my $Ihelp = ($I ? '-I. ' : '');
1919   my $Icomment = ($I ? '' : <<EOC);
1920         # Insert -I. if you add *.h files later:
1921 EOC
1922
1923   print PL <<END;
1924     LIBS              => ['$extralibs'], # e.g., '-lm'
1925     DEFINE            => '$opt_F', # e.g., '-DHAVE_SOMETHING'
1926 $Icomment    INC               => '$I', # e.g., '${Ihelp}-I/usr/include/other'
1927 END
1928
1929   my $C = grep {$_ ne "$modfname.c"}
1930     (glob '*.c'), (glob '*.cc'), (glob '*.C');
1931   my $Cpre = ($C ? '' : '# ');
1932   my $Ccomment = ($C ? '' : <<EOC);
1933         # Un-comment this if you add C files to link with later:
1934 EOC
1935
1936   print PL <<END;
1937 $Ccomment    ${Cpre}OBJECT            => '\$(O_FILES)', # link all the C files too
1938 END
1939 } # ' # Grr
1940 print PL ");\n";
1941 if (!$opt_c) {
1942   my $generate_code =
1943     WriteMakefileSnippet ( C_FILE =>       $constscfname,
1944                            XS_FILE =>      $constsxsfname,
1945                            DEFAULT_TYPE => $opt_t,
1946                            NAME =>         $module,
1947                            NAMES =>        \@const_names,
1948                  );
1949   print PL <<"END";
1950 if  (eval {require ExtUtils::Constant; 1}) {
1951   # If you edit these definitions to change the constants used by this module,
1952   # you will need to use the generated $constscfname and $constsxsfname
1953   # files to replace their "fallback" counterparts before distributing your
1954   # changes.
1955 $generate_code
1956 }
1957 else {
1958   use File::Copy;
1959   use File::Spec;
1960   foreach my \$file ('$constscfname', '$constsxsfname') {
1961     my \$fallback = File::Spec->catfile('$fallbackdirname', \$file);
1962     copy (\$fallback, \$file) or die "Can't copy \$fallback to \$file: \$!";
1963   }
1964 }
1965 END
1966
1967   eval $generate_code;
1968   if ($@) {
1969     warn <<"EOM";
1970 Attempting to test constant code in $ext$modpname/Makefile.PL:
1971 $generate_code
1972 __END__
1973 gave unexpected error $@
1974 Please report the circumstances of this bug in h2xs version $H2XS_VERSION
1975 using the perlbug script.
1976 EOM
1977   } else {
1978     my $fail;
1979
1980     foreach my $file ($constscfname, $constsxsfname) {
1981       my $fallback = File::Spec->catfile($fallbackdirname, $file);
1982       if (compare($file, $fallback)) {
1983         warn << "EOM";
1984 Files "$ext$modpname/$fallbackdirname/$file" and "$ext$modpname/$file" differ.
1985 EOM
1986         $fail++;
1987       }
1988     }
1989     if ($fail) {
1990       warn fill ('','', <<"EOM") . "\n";
1991 It appears that the code in $ext$modpname/Makefile.PL does not autogenerate
1992 the files $ext$modpname/$constscfname and $ext$modpname/$constsxsfname
1993 correctly.
1994
1995 Please report the circumstances of this bug in h2xs version $H2XS_VERSION
1996 using the perlbug script.
1997 EOM
1998     } else {
1999       unlink $constscfname, $constsxsfname;
2000     }
2001   }
2002 }
2003 close(PL) || die "Can't close $ext$modpname/Makefile.PL: $!\n";
2004
2005 # Create a simple README since this is a CPAN requirement
2006 # and it doesnt hurt to have one
2007 warn "Writing $ext$modpname/README\n";
2008 open(RM, ">README") || die "Can't create $ext$modpname/README:$!\n";
2009 my $thisyear = (gmtime)[5] + 1900;
2010 my $rmhead = "$modpname version $TEMPLATE_VERSION";
2011 my $rmheadeq = "=" x length($rmhead);
2012
2013 my $rm_prereq;
2014
2015 if ( $compat_version < 5.00702 and $new_test )
2016 {
2017    $rm_prereq = 'Test::More';
2018 }
2019 else
2020 {
2021    $rm_prereq = 'blah blah blah';
2022 }
2023
2024 print RM <<_RMEND_;
2025 $rmhead
2026 $rmheadeq
2027
2028 The README is used to introduce the module and provide instructions on
2029 how to install the module, any machine dependencies it may have (for
2030 example C compilers and installed libraries) and any other information
2031 that should be provided before the module is installed.
2032
2033 A README file is required for CPAN modules since CPAN extracts the
2034 README file from a module distribution so that people browsing the
2035 archive can use it get an idea of the modules uses. It is usually a
2036 good idea to provide version information here so that people can
2037 decide whether fixes for the module are worth downloading.
2038
2039 INSTALLATION
2040
2041 To install this module type the following:
2042
2043    perl Makefile.PL
2044    make
2045    make test
2046    make install
2047
2048 DEPENDENCIES
2049
2050 This module requires these other modules and libraries:
2051
2052   $rm_prereq
2053
2054 COPYRIGHT AND LICENCE
2055
2056 Put the correct copyright and licence information here.
2057
2058 $licence
2059
2060 _RMEND_
2061 close(RM) || die "Can't close $ext$modpname/README: $!\n";
2062
2063 my $testdir  = "t";
2064 my $testfile = "$testdir/$modpname.t";
2065 unless (-d "$testdir") {
2066   mkdir "$testdir" or die "Cannot mkdir $testdir: $!\n";
2067 }
2068 warn "Writing $ext$modpname/$testfile\n";
2069 my $tests = @const_names ? 2 : 1;
2070
2071 open EX, ">$testfile" or die "Can't create $ext$modpname/$testfile: $!\n";
2072
2073 print EX <<_END_;
2074 # Before `make install' is performed this script should be runnable with
2075 # `make test'. After `make install' it should work as `perl $modpname.t'
2076
2077 #########################
2078
2079 # change 'tests => $tests' to 'tests => last_test_to_print';
2080
2081 _END_
2082
2083 my $test_mod = 'Test::More';
2084
2085 if ( $old_test or ($compat_version < 5.007 and not $new_test ))
2086 {
2087   my $test_mod = 'Test';
2088
2089   print EX <<_END_;
2090 use Test;
2091 BEGIN { plan tests => $tests };
2092 use $module;
2093 ok(1); # If we made it this far, we're ok.
2094
2095 _END_
2096
2097    if (@const_names) {
2098      my $const_names = join " ", @const_names;
2099      print EX <<'_END_';
2100
2101 my $fail;
2102 foreach my $constname (qw(
2103 _END_
2104
2105      print EX wrap ("\t", "\t", $const_names);
2106      print EX (")) {\n");
2107
2108      print EX <<_END_;
2109   next if (eval "my \\\$a = \$constname; 1");
2110   if (\$\@ =~ /^Your vendor has not defined $module macro \$constname/) {
2111     print "# pass: \$\@";
2112   } else {
2113     print "# fail: \$\@";
2114     \$fail = 1;
2115   }
2116 }
2117 if (\$fail) {
2118   print "not ok 2\\n";
2119 } else {
2120   print "ok 2\\n";
2121 }
2122
2123 _END_
2124   }
2125 }
2126 else
2127 {
2128   print EX <<_END_;
2129 use Test::More tests => $tests;
2130 BEGIN { use_ok('$module') };
2131
2132 _END_
2133
2134    if (@const_names) {
2135      my $const_names = join " ", @const_names;
2136      print EX <<'_END_';
2137
2138 my $fail = 0;
2139 foreach my $constname (qw(
2140 _END_
2141
2142      print EX wrap ("\t", "\t", $const_names);
2143      print EX (")) {\n");
2144
2145      print EX <<_END_;
2146   next if (eval "my \\\$a = \$constname; 1");
2147   if (\$\@ =~ /^Your vendor has not defined $module macro \$constname/) {
2148     print "# pass: \$\@";
2149   } else {
2150     print "# fail: \$\@";
2151     \$fail = 1;
2152   }
2153
2154 }
2155
2156 ok( \$fail == 0 , 'Constants' );
2157 _END_
2158   }
2159 }
2160
2161 print EX <<_END_;
2162 #########################
2163
2164 # Insert your test code below, the $test_mod module is use()ed here so read
2165 # its man page ( perldoc $test_mod ) for help writing this test script.
2166
2167 _END_
2168
2169 close(EX) || die "Can't close $ext$modpname/$testfile: $!\n";
2170
2171 unless ($opt_C) {
2172   warn "Writing $ext$modpname/Changes\n";
2173   $" = ' ';
2174   open(EX, ">Changes") || die "Can't create $ext$modpname/Changes: $!\n";
2175   @ARGS = map {/[\s\"\'\`\$*?^|&<>\[\]\{\}\(\)]/ ? "'$_'" : $_} @ARGS;
2176   print EX <<EOP;
2177 Revision history for Perl extension $module.
2178
2179 $TEMPLATE_VERSION  @{[scalar localtime]}
2180 \t- original version; created by h2xs $H2XS_VERSION with options
2181 \t\t@ARGS
2182
2183 EOP
2184   close(EX) || die "Can't close $ext$modpname/Changes: $!\n";
2185 }
2186
2187 warn "Writing $ext$modpname/MANIFEST\n";
2188 open(MANI,'>MANIFEST') or die "Can't create MANIFEST: $!";
2189 my @files = grep { -f } (<*>, <t/*>, <$fallbackdirname/*>, <$modpmdir/*>);
2190 if (!@files) {
2191   eval {opendir(D,'.');};
2192   unless ($@) { @files = readdir(D); closedir(D); }
2193 }
2194 if (!@files) { @files = map {chomp && $_} `ls`; }
2195 if ($^O eq 'VMS') {
2196   foreach (@files) {
2197     # Clip trailing '.' for portability -- non-VMS OSs don't expect it
2198     s%\.$%%;
2199     # Fix up for case-sensitive file systems
2200     s/$modfname/$modfname/i && next;
2201     $_ = "\U$_" if $_ eq 'manifest' or $_ eq 'changes';
2202     $_ = 'Makefile.PL' if $_ eq 'makefile.pl';
2203   }
2204 }
2205 print MANI join("\n",@files), "\n";
2206 close MANI;
2207 !NO!SUBS!
2208
2209 close OUT or die "Can't close $file: $!";
2210 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
2211 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
2212 chdir $origdir;