1PERLXSTUT(1)           Perl Programmers Reference Guide           PERLXSTUT(1)
2
3
4

NAME

6       perlXStut - Tutorial for writing XSUBs
7

DESCRIPTION

9       This tutorial will educate the reader on the steps involved in creating
10       a Perl extension.  The reader is assumed to have access to perlguts,
11       perlapi and perlxs.
12
13       This tutorial starts with very simple examples and becomes more
14       complex, with each new example adding new features.  Certain concepts
15       may not be completely explained until later in the tutorial in order to
16       slowly ease the reader into building extensions.
17
18       This tutorial was written from a Unix point of view.  Where I know them
19       to be otherwise different for other platforms (e.g. Win32), I will list
20       them.  If you find something that was missed, please let me know.
21

SPECIAL NOTES

23   make
24       This tutorial assumes that the make program that Perl is configured to
25       use is called "make".  Instead of running "make" in the examples that
26       follow, you may have to substitute whatever make program Perl has been
27       configured to use.  Running perl -V:make should tell you what it is.
28
29   Version caveat
30       When writing a Perl extension for general consumption, one should
31       expect that the extension will be used with versions of Perl different
32       from the version available on your machine.  Since you are reading this
33       document, the version of Perl on your machine is probably 5.005 or
34       later, but the users of your extension may have more ancient versions.
35
36       To understand what kinds of incompatibilities one may expect, and in
37       the rare case that the version of Perl on your machine is older than
38       this document, see the section on "Troubleshooting these Examples" for
39       more information.
40
41       If your extension uses some features of Perl which are not available on
42       older releases of Perl, your users would appreciate an early meaningful
43       warning.  You would probably put this information into the README file,
44       but nowadays installation of extensions may be performed automatically,
45       guided by CPAN.pm module or other tools.
46
47       In MakeMaker-based installations, Makefile.PL provides the earliest
48       opportunity to perform version checks.  One can put something like this
49       in Makefile.PL for this purpose:
50
51           eval { require 5.007 }
52               or die <<EOD;
53           ############
54           ### This module uses frobnication framework which is not available before
55           ### version 5.007 of Perl.  Upgrade your Perl before installing Kara::Mba.
56           ############
57           EOD
58
59   Dynamic Loading versus Static Loading
60       It is commonly thought that if a system does not have the capability to
61       dynamically load a library, you cannot build XSUBs.  This is incorrect.
62       You can build them, but you must link the XSUBs subroutines with the
63       rest of Perl, creating a new executable.  This situation is similar to
64       Perl 4.
65
66       This tutorial can still be used on such a system.  The XSUB build
67       mechanism will check the system and build a dynamically-loadable
68       library if possible, or else a static library and then, optionally, a
69       new statically-linked executable with that static library linked in.
70
71       Should you wish to build a statically-linked executable on a system
72       which can dynamically load libraries, you may, in all the following
73       examples, where the command ""make"" with no arguments is executed, run
74       the command ""make perl"" instead.
75
76       If you have generated such a statically-linked executable by choice,
77       then instead of saying ""make test"", you should say ""make
78       test_static"".  On systems that cannot build dynamically-loadable
79       libraries at all, simply saying ""make test"" is sufficient.
80

TUTORIAL

82       Now let's go on with the show!
83
84   EXAMPLE 1
85       Our first extension will be very simple.  When we call the routine in
86       the extension, it will print out a well-known message and return.
87
88       Run ""h2xs -A -n Mytest"".  This creates a directory named Mytest,
89       possibly under ext/ if that directory exists in the current working
90       directory.  Several files will be created under the Mytest dir,
91       including MANIFEST, Makefile.PL, lib/Mytest.pm, Mytest.xs, t/Mytest.t,
92       and Changes.
93
94       The MANIFEST file contains the names of all the files just created in
95       the Mytest directory.
96
97       The file Makefile.PL should look something like this:
98
99           use ExtUtils::MakeMaker;
100           # See lib/ExtUtils/MakeMaker.pm for details of how to influence
101           # the contents of the Makefile that is written.
102           WriteMakefile(
103               NAME         => 'Mytest',
104               VERSION_FROM => 'Mytest.pm', # finds $VERSION
105               LIBS         => [''],   # e.g., '-lm'
106               DEFINE       => '',     # e.g., '-DHAVE_SOMETHING'
107               INC          => '',     # e.g., '-I/usr/include/other'
108           );
109
110       The file Mytest.pm should start with something like this:
111
112           package Mytest;
113
114           use 5.008008;
115           use strict;
116           use warnings;
117
118           require Exporter;
119
120           our @ISA = qw(Exporter);
121           our %EXPORT_TAGS = ( 'all' => [ qw(
122
123           ) ] );
124
125           our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
126
127           our @EXPORT = qw(
128
129           );
130
131           our $VERSION = '0.01';
132
133           require XSLoader;
134           XSLoader::load('Mytest', $VERSION);
135
136           # Preloaded methods go here.
137
138           1;
139           __END__
140           # Below is the stub of documentation for your module. You better edit it!
141
142       The rest of the .pm file contains sample code for providing
143       documentation for the extension.
144
145       Finally, the Mytest.xs file should look something like this:
146
147           #include "EXTERN.h"
148           #include "perl.h"
149           #include "XSUB.h"
150
151           #include "ppport.h"
152
153           MODULE = Mytest             PACKAGE = Mytest
154
155       Let's edit the .xs file by adding this to the end of the file:
156
157           void
158           hello()
159               CODE:
160                   printf("Hello, world!\n");
161
162       It is okay for the lines starting at the "CODE:" line to not be
163       indented.  However, for readability purposes, it is suggested that you
164       indent CODE: one level and the lines following one more level.
165
166       Now we'll run ""perl Makefile.PL"".  This will create a real Makefile,
167       which make needs.  Its output looks something like:
168
169           % perl Makefile.PL
170           Checking if your kit is complete...
171           Looks good
172           Writing Makefile for Mytest
173           %
174
175       Now, running make will produce output that looks something like this
176       (some long lines have been shortened for clarity and some extraneous
177       lines have been deleted):
178
179           % make
180           cp lib/Mytest.pm blib/lib/Mytest.pm
181           perl xsubpp  -typemap typemap  Mytest.xs > Mytest.xsc && mv Mytest.xsc Mytest.c
182           Please specify prototyping behavior for Mytest.xs (see perlxs manual)
183           cc -c     Mytest.c
184           Running Mkbootstrap for Mytest ()
185           chmod 644 Mytest.bs
186           rm -f blib/arch/auto/Mytest/Mytest.so
187           cc  -shared -L/usr/local/lib Mytest.o  -o blib/arch/auto/Mytest/Mytest.so   \
188                       \
189
190           chmod 755 blib/arch/auto/Mytest/Mytest.so
191           cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
192           chmod 644 blib/arch/auto/Mytest/Mytest.bs
193           Manifying blib/man3/Mytest.3pm
194           %
195
196       You can safely ignore the line about "prototyping behavior" - it is
197       explained in "The PROTOTYPES: Keyword" in perlxs.
198
199       If you are on a Win32 system, and the build process fails with linker
200       errors for functions in the C library, check if your Perl is configured
201       to use PerlCRT (running perl -V:libc should show you if this is the
202       case).  If Perl is configured to use PerlCRT, you have to make sure
203       PerlCRT.lib is copied to the same location that msvcrt.lib lives in, so
204       that the compiler can find it on its own.  msvcrt.lib is usually found
205       in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib).
206
207       Perl has its own special way of easily writing test scripts, but for
208       this example only, we'll create our own test script.  Create a file
209       called hello that looks like this:
210
211           #! /opt/perl5/bin/perl
212
213           use ExtUtils::testlib;
214
215           use Mytest;
216
217           Mytest::hello();
218
219       Now we make the script executable ("chmod +x hello"), run the script
220       and we should see the following output:
221
222           % ./hello
223           Hello, world!
224           %
225
226   EXAMPLE 2
227       Now let's add to our extension a subroutine that will take a single
228       numeric argument as input and return 0 if the number is even or 1 if
229       the number is odd.
230
231       Add the following to the end of Mytest.xs:
232
233           int
234           is_even(input)
235                   int input
236               CODE:
237                   RETVAL = (input % 2 == 0);
238               OUTPUT:
239                   RETVAL
240
241       There does not need to be whitespace at the start of the ""int input""
242       line, but it is useful for improving readability.  Placing a semi-colon
243       at the end of that line is also optional.  Any amount and kind of
244       whitespace may be placed between the ""int"" and ""input"".
245
246       Now re-run make to rebuild our new shared library.
247
248       Now perform the same steps as before, generating a Makefile from the
249       Makefile.PL file, and running make.
250
251       In order to test that our extension works, we now need to look at the
252       file Mytest.t.  This file is set up to imitate the same kind of testing
253       structure that Perl itself has.  Within the test script, you perform a
254       number of tests to confirm the behavior of the extension, printing "ok"
255       when the test is correct, "not ok" when it is not.
256
257           use Test::More tests => 4;
258           BEGIN { use_ok('Mytest') };
259
260           #########################
261
262           # Insert your test code below, the Test::More module is use()ed here so read
263           # its man page ( perldoc Test::More ) for help writing this test script.
264
265           is(&Mytest::is_even(0), 1);
266           is(&Mytest::is_even(1), 0);
267           is(&Mytest::is_even(2), 1);
268
269       We will be calling the test script through the command ""make test"".
270       You should see output that looks something like this:
271
272           %make test
273           PERL_DL_NONLAZY=1 /usr/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
274           t/Mytest....ok
275           All tests successful.
276           Files=1, Tests=4,  0 wallclock secs ( 0.03 cusr +  0.00 csys =  0.03 CPU)
277           %
278
279   What has gone on?
280       The program h2xs is the starting point for creating extensions.  In
281       later examples we'll see how we can use h2xs to read header files and
282       generate templates to connect to C routines.
283
284       h2xs creates a number of files in the extension directory.  The file
285       Makefile.PL is a perl script which will generate a true Makefile to
286       build the extension.  We'll take a closer look at it later.
287
288       The .pm and .xs files contain the meat of the extension.  The .xs file
289       holds the C routines that make up the extension.  The .pm file contains
290       routines that tell Perl how to load your extension.
291
292       Generating the Makefile and running "make" created a directory called
293       blib (which stands for "build library") in the current working
294       directory.  This directory will contain the shared library that we will
295       build.  Once we have tested it, we can install it into its final
296       location.
297
298       Invoking the test script via ""make test"" did something very
299       important.  It invoked perl with all those "-I" arguments so that it
300       could find the various files that are part of the extension.  It is
301       very important that while you are still testing extensions that you use
302       ""make test"".  If you try to run the test script all by itself, you
303       will get a fatal error.  Another reason it is important to use ""make
304       test"" to run your test script is that if you are testing an upgrade to
305       an already-existing version, using ""make test"" ensures that you will
306       test your new extension, not the already-existing version.
307
308       When Perl sees a "use extension;", it searches for a file with the same
309       name as the "use"'d extension that has a .pm suffix.  If that file
310       cannot be found, Perl dies with a fatal error.  The default search path
311       is contained in the @INC array.
312
313       In our case, Mytest.pm tells perl that it will need the Exporter and
314       Dynamic Loader extensions.  It then sets the @ISA and @EXPORT arrays
315       and the $VERSION scalar; finally it tells perl to bootstrap the module.
316       Perl will call its dynamic loader routine (if there is one) and load
317       the shared library.
318
319       The two arrays @ISA and @EXPORT are very important.  The @ISA array
320       contains a list of other packages in which to search for methods (or
321       subroutines) that do not exist in the current package.  This is usually
322       only important for object-oriented extensions (which we will talk about
323       much later), and so usually doesn't need to be modified.
324
325       The @EXPORT array tells Perl which of the extension's variables and
326       subroutines should be placed into the calling package's namespace.
327       Because you don't know if the user has already used your variable and
328       subroutine names, it's vitally important to carefully select what to
329       export.  Do not export method or variable names by default without a
330       good reason.
331
332       As a general rule, if the module is trying to be object-oriented then
333       don't export anything.  If it's just a collection of functions and
334       variables, then you can export them via another array, called
335       @EXPORT_OK.  This array does not automatically place its subroutine and
336       variable names into the namespace unless the user specifically requests
337       that this be done.
338
339       See perlmod for more information.
340
341       The $VERSION variable is used to ensure that the .pm file and the
342       shared library are "in sync" with each other.  Any time you make
343       changes to the .pm or .xs files, you should increment the value of this
344       variable.
345
346   Writing good test scripts
347       The importance of writing good test scripts cannot be over-emphasized.
348       You should closely follow the "ok/not ok" style that Perl itself uses,
349       so that it is very easy and unambiguous to determine the outcome of
350       each test case.  When you find and fix a bug, make sure you add a test
351       case for it.
352
353       By running ""make test"", you ensure that your Mytest.t script runs and
354       uses the correct version of your extension.  If you have many test
355       cases, save your test files in the "t" directory and use the suffix
356       ".t".  When you run ""make test"", all of these test files will be
357       executed.
358
359   EXAMPLE 3
360       Our third extension will take one argument as its input, round off that
361       value, and set the argument to the rounded value.
362
363       Add the following to the end of Mytest.xs:
364
365               void
366               round(arg)
367                       double  arg
368                   CODE:
369                       if (arg > 0.0) {
370                               arg = floor(arg + 0.5);
371                       } else if (arg < 0.0) {
372                               arg = ceil(arg - 0.5);
373                       } else {
374                               arg = 0.0;
375                       }
376                   OUTPUT:
377                       arg
378
379       Edit the Makefile.PL file so that the corresponding line looks like
380       this:
381
382               'LIBS'      => ['-lm'],   # e.g., '-lm'
383
384       Generate the Makefile and run make.  Change the test number in Mytest.t
385       to "9" and add the following tests:
386
387               $i = -1.5; &Mytest::round($i); is( $i, -2.0 );
388               $i = -1.1; &Mytest::round($i); is( $i, -1.0 );
389               $i = 0.0; &Mytest::round($i);  is( $i,  0.0 );
390               $i = 0.5; &Mytest::round($i);  is( $i,  1.0 );
391               $i = 1.2; &Mytest::round($i);  is( $i,  1.0 );
392
393       Running ""make test"" should now print out that all nine tests are
394       okay.
395
396       Notice that in these new test cases, the argument passed to round was a
397       scalar variable.  You might be wondering if you can round a constant or
398       literal.  To see what happens, temporarily add the following line to
399       Mytest.t:
400
401               &Mytest::round(3);
402
403       Run ""make test"" and notice that Perl dies with a fatal error.  Perl
404       won't let you change the value of constants!
405
406   What's new here?
407       ·   We've made some changes to Makefile.PL.  In this case, we've
408           specified an extra library to be linked into the extension's shared
409           library, the math library libm in this case.  We'll talk later
410           about how to write XSUBs that can call every routine in a library.
411
412       ·   The value of the function is not being passed back as the
413           function's return value, but by changing the value of the variable
414           that was passed into the function.  You might have guessed that
415           when you saw that the return value of round is of type "void".
416
417   Input and Output Parameters
418       You specify the parameters that will be passed into the XSUB on the
419       line(s) after you declare the function's return value and name.  Each
420       input parameter line starts with optional whitespace, and may have an
421       optional terminating semicolon.
422
423       The list of output parameters occurs at the very end of the function,
424       just after the OUTPUT: directive.  The use of RETVAL tells Perl that
425       you wish to send this value back as the return value of the XSUB
426       function.  In Example 3, we wanted the "return value" placed in the
427       original variable which we passed in, so we listed it (and not RETVAL)
428       in the OUTPUT: section.
429
430   The XSUBPP Program
431       The xsubpp program takes the XS code in the .xs file and translates it
432       into C code, placing it in a file whose suffix is .c.  The C code
433       created makes heavy use of the C functions within Perl.
434
435   The TYPEMAP file
436       The xsubpp program uses rules to convert from Perl's data types
437       (scalar, array, etc.) to C's data types (int, char, etc.).  These rules
438       are stored in the typemap file ($PERLLIB/ExtUtils/typemap).  This file
439       is split into three parts.
440
441       The first section maps various C data types to a name, which
442       corresponds somewhat with the various Perl types.  The second section
443       contains C code which xsubpp uses to handle input parameters.  The
444       third section contains C code which xsubpp uses to handle output
445       parameters.
446
447       Let's take a look at a portion of the .c file created for our
448       extension.  The file name is Mytest.c:
449
450               XS(XS_Mytest_round)
451               {
452                   dXSARGS;
453                   if (items != 1)
454                       Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
455               PERL_UNUSED_VAR(cv); /* -W */
456                   {
457                       double  arg = (double)SvNV(ST(0));      /* XXXXX */
458                       if (arg > 0.0) {
459                               arg = floor(arg + 0.5);
460                       } else if (arg < 0.0) {
461                               arg = ceil(arg - 0.5);
462                       } else {
463                               arg = 0.0;
464                       }
465                       sv_setnv(ST(0), (double)arg);   /* XXXXX */
466               SvSETMAGIC(ST(0));
467                   }
468                   XSRETURN_EMPTY;
469               }
470
471       Notice the two lines commented with "XXXXX".  If you check the first
472       section of the typemap file, you'll see that doubles are of type
473       T_DOUBLE.  In the INPUT section, an argument that is T_DOUBLE is
474       assigned to the variable arg by calling the routine SvNV on something,
475       then casting it to double, then assigned to the variable arg.
476       Similarly, in the OUTPUT section, once arg has its final value, it is
477       passed to the sv_setnv function to be passed back to the calling
478       subroutine.  These two functions are explained in perlguts; we'll talk
479       more later about what that "ST(0)" means in the section on the argument
480       stack.
481
482   Warning about Output Arguments
483       In general, it's not a good idea to write extensions that modify their
484       input parameters, as in Example 3.  Instead, you should probably return
485       multiple values in an array and let the caller handle them (we'll do
486       this in a later example).  However, in order to better accommodate
487       calling pre-existing C routines, which often do modify their input
488       parameters, this behavior is tolerated.
489
490   EXAMPLE 4
491       In this example, we'll now begin to write XSUBs that will interact with
492       pre-defined C libraries.  To begin with, we will build a small library
493       of our own, then let h2xs write our .pm and .xs files for us.
494
495       Create a new directory called Mytest2 at the same level as the
496       directory Mytest.  In the Mytest2 directory, create another directory
497       called mylib, and cd into that directory.
498
499       Here we'll create some files that will generate a test library.  These
500       will include a C source file and a header file.  We'll also create a
501       Makefile.PL in this directory.  Then we'll make sure that running make
502       at the Mytest2 level will automatically run this Makefile.PL file and
503       the resulting Makefile.
504
505       In the mylib directory, create a file mylib.h that looks like this:
506
507               #define TESTVAL 4
508
509               extern double   foo(int, long, const char*);
510
511       Also create a file mylib.c that looks like this:
512
513               #include <stdlib.h>
514               #include "./mylib.h"
515
516               double
517               foo(int a, long b, const char *c)
518               {
519                       return (a + b + atof(c) + TESTVAL);
520               }
521
522       And finally create a file Makefile.PL that looks like this:
523
524               use ExtUtils::MakeMaker;
525               $Verbose = 1;
526               WriteMakefile(
527                   NAME   => 'Mytest2::mylib',
528                   SKIP   => [qw(all static static_lib dynamic dynamic_lib)],
529                   clean  => {'FILES' => 'libmylib$(LIB_EXT)'},
530               );
531
532
533               sub MY::top_targets {
534                       '
535               all :: static
536
537               pure_all :: static
538
539               static ::       libmylib$(LIB_EXT)
540
541               libmylib$(LIB_EXT): $(O_FILES)
542                       $(AR) cr libmylib$(LIB_EXT) $(O_FILES)
543                       $(RANLIB) libmylib$(LIB_EXT)
544
545               ';
546               }
547
548       Make sure you use a tab and not spaces on the lines beginning with
549       "$(AR)" and "$(RANLIB)".  Make will not function properly if you use
550       spaces.  It has also been reported that the "cr" argument to $(AR) is
551       unnecessary on Win32 systems.
552
553       We will now create the main top-level Mytest2 files.  Change to the
554       directory above Mytest2 and run the following command:
555
556               % h2xs -O -n Mytest2 ./Mytest2/mylib/mylib.h
557
558       This will print out a warning about overwriting Mytest2, but that's
559       okay.  Our files are stored in Mytest2/mylib, and will be untouched.
560
561       The normal Makefile.PL that h2xs generates doesn't know about the mylib
562       directory.  We need to tell it that there is a subdirectory and that we
563       will be generating a library in it.  Let's add the argument MYEXTLIB to
564       the WriteMakefile call so that it looks like this:
565
566               WriteMakefile(
567                   'NAME'      => 'Mytest2',
568                   'VERSION_FROM' => 'Mytest2.pm', # finds $VERSION
569                   'LIBS'      => [''],   # e.g., '-lm'
570                   'DEFINE'    => '',     # e.g., '-DHAVE_SOMETHING'
571                   'INC'       => '',     # e.g., '-I/usr/include/other'
572                   'MYEXTLIB' => 'mylib/libmylib$(LIB_EXT)',
573               );
574
575       and then at the end add a subroutine (which will override the pre-
576       existing subroutine).  Remember to use a tab character to indent the
577       line beginning with "cd"!
578
579               sub MY::postamble {
580               '
581               $(MYEXTLIB): mylib/Makefile
582                       cd mylib && $(MAKE) $(PASSTHRU)
583               ';
584               }
585
586       Let's also fix the MANIFEST file so that it accurately reflects the
587       contents of our extension.  The single line that says "mylib" should be
588       replaced by the following three lines:
589
590               mylib/Makefile.PL
591               mylib/mylib.c
592               mylib/mylib.h
593
594       To keep our namespace nice and unpolluted, edit the .pm file and change
595       the variable @EXPORT to @EXPORT_OK.  Finally, in the .xs file, edit the
596       #include line to read:
597
598               #include "mylib/mylib.h"
599
600       And also add the following function definition to the end of the .xs
601       file:
602
603               double
604               foo(a,b,c)
605                       int             a
606                       long            b
607                       const char *    c
608                   OUTPUT:
609                       RETVAL
610
611       Now we also need to create a typemap file because the default Perl
612       doesn't currently support the const char * type.  Create a file called
613       typemap in the Mytest2 directory and place the following in it:
614
615               const char *    T_PV
616
617       Now run perl on the top-level Makefile.PL.  Notice that it also created
618       a Makefile in the mylib directory.  Run make and watch that it does cd
619       into the mylib directory and run make in there as well.
620
621       Now edit the Mytest2.t script and change the number of tests to "4",
622       and add the following lines to the end of the script:
623
624               is( &Mytest2::foo(1, 2, "Hello, world!"), 7 );
625               is( &Mytest2::foo(1, 2, "0.0"), 7 );
626               ok( abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 );
627
628       (When dealing with floating-point comparisons, it is best to not check
629       for equality, but rather that the difference between the expected and
630       actual result is below a certain amount (called epsilon) which is 0.01
631       in this case)
632
633       Run ""make test"" and all should be well. There are some warnings on
634       missing tests for the Mytest2::mylib extension, but you can ignore
635       them.
636
637   What has happened here?
638       Unlike previous examples, we've now run h2xs on a real include file.
639       This has caused some extra goodies to appear in both the .pm and .xs
640       files.
641
642       ·   In the .xs file, there's now a #include directive with the absolute
643           path to the mylib.h header file.  We changed this to a relative
644           path so that we could move the extension directory if we wanted to.
645
646       ·   There's now some new C code that's been added to the .xs file.  The
647           purpose of the "constant" routine is to make the values that are
648           #define'd in the header file accessible by the Perl script (by
649           calling either "TESTVAL" or &Mytest2::TESTVAL).  There's also some
650           XS code to allow calls to the "constant" routine.
651
652       ·   The .pm file originally exported the name "TESTVAL" in the @EXPORT
653           array.  This could lead to name clashes.  A good rule of thumb is
654           that if the #define is only going to be used by the C routines
655           themselves, and not by the user, they should be removed from the
656           @EXPORT array.  Alternately, if you don't mind using the "fully
657           qualified name" of a variable, you could move most or all of the
658           items from the @EXPORT array into the @EXPORT_OK array.
659
660       ·   If our include file had contained #include directives, these would
661           not have been processed by h2xs.  There is no good solution to this
662           right now.
663
664       ·   We've also told Perl about the library that we built in the mylib
665           subdirectory.  That required only the addition of the "MYEXTLIB"
666           variable to the WriteMakefile call and the replacement of the
667           postamble subroutine to cd into the subdirectory and run make.  The
668           Makefile.PL for the library is a bit more complicated, but not
669           excessively so.  Again we replaced the postamble subroutine to
670           insert our own code.  This code simply specified that the library
671           to be created here was a static archive library (as opposed to a
672           dynamically loadable library) and provided the commands to build
673           it.
674
675   Anatomy of .xs file
676       The .xs file of "EXAMPLE 4" contained some new elements.  To understand
677       the meaning of these elements, pay attention to the line which reads
678
679               MODULE = Mytest2                PACKAGE = Mytest2
680
681       Anything before this line is plain C code which describes which headers
682       to include, and defines some convenience functions.  No translations
683       are performed on this part, apart from having embedded POD
684       documentation skipped over (see perlpod) it goes into the generated
685       output C file as is.
686
687       Anything after this line is the description of XSUB functions.  These
688       descriptions are translated by xsubpp into C code which implements
689       these functions using Perl calling conventions, and which makes these
690       functions visible from Perl interpreter.
691
692       Pay a special attention to the function "constant".  This name appears
693       twice in the generated .xs file: once in the first part, as a static C
694       function, then another time in the second part, when an XSUB interface
695       to this static C function is defined.
696
697       This is quite typical for .xs files: usually the .xs file provides an
698       interface to an existing C function.  Then this C function is defined
699       somewhere (either in an external library, or in the first part of .xs
700       file), and a Perl interface to this function (i.e. "Perl glue") is
701       described in the second part of .xs file.  The situation in "EXAMPLE
702       1", "EXAMPLE 2", and "EXAMPLE 3", when all the work is done inside the
703       "Perl glue", is somewhat of an exception rather than the rule.
704
705   Getting the fat out of XSUBs
706       In "EXAMPLE 4" the second part of .xs file contained the following
707       description of an XSUB:
708
709               double
710               foo(a,b,c)
711                       int             a
712                       long            b
713                       const char *    c
714                   OUTPUT:
715                       RETVAL
716
717       Note that in contrast with "EXAMPLE 1", "EXAMPLE 2" and "EXAMPLE 3",
718       this description does not contain the actual code for what is done is
719       done during a call to Perl function foo().  To understand what is going
720       on here, one can add a CODE section to this XSUB:
721
722               double
723               foo(a,b,c)
724                       int             a
725                       long            b
726                       const char *    c
727                   CODE:
728                       RETVAL = foo(a,b,c);
729                   OUTPUT:
730                       RETVAL
731
732       However, these two XSUBs provide almost identical generated C code:
733       xsubpp compiler is smart enough to figure out the "CODE:" section from
734       the first two lines of the description of XSUB.  What about "OUTPUT:"
735       section?  In fact, that is absolutely the same!  The "OUTPUT:" section
736       can be removed as well, as far as "CODE:" section or "PPCODE:" section
737       is not specified: xsubpp can see that it needs to generate a function
738       call section, and will autogenerate the OUTPUT section too.  Thus one
739       can shortcut the XSUB to become:
740
741               double
742               foo(a,b,c)
743                       int             a
744                       long            b
745                       const char *    c
746
747       Can we do the same with an XSUB
748
749               int
750               is_even(input)
751                       int     input
752                   CODE:
753                       RETVAL = (input % 2 == 0);
754                   OUTPUT:
755                       RETVAL
756
757       of "EXAMPLE 2"?  To do this, one needs to define a C function "int
758       is_even(int input)".  As we saw in "Anatomy of .xs file", a proper
759       place for this definition is in the first part of .xs file.  In fact a
760       C function
761
762               int
763               is_even(int arg)
764               {
765                       return (arg % 2 == 0);
766               }
767
768       is probably overkill for this.  Something as simple as a "#define" will
769       do too:
770
771               #define is_even(arg)    ((arg) % 2 == 0)
772
773       After having this in the first part of .xs file, the "Perl glue" part
774       becomes as simple as
775
776               int
777               is_even(input)
778                       int     input
779
780       This technique of separation of the glue part from the workhorse part
781       has obvious tradeoffs: if you want to change a Perl interface, you need
782       to change two places in your code.  However, it removes a lot of
783       clutter, and makes the workhorse part independent from idiosyncrasies
784       of Perl calling convention.  (In fact, there is nothing Perl-specific
785       in the above description, a different version of xsubpp might have
786       translated this to TCL glue or Python glue as well.)
787
788   More about XSUB arguments
789       With the completion of Example 4, we now have an easy way to simulate
790       some real-life libraries whose interfaces may not be the cleanest in
791       the world.  We shall now continue with a discussion of the arguments
792       passed to the xsubpp compiler.
793
794       When you specify arguments to routines in the .xs file, you are really
795       passing three pieces of information for each argument listed.  The
796       first piece is the order of that argument relative to the others
797       (first, second, etc).  The second is the type of argument, and consists
798       of the type declaration of the argument (e.g., int, char*, etc).  The
799       third piece is the calling convention for the argument in the call to
800       the library function.
801
802       While Perl passes arguments to functions by reference, C passes
803       arguments by value; to implement a C function which modifies data of
804       one of the "arguments", the actual argument of this C function would be
805       a pointer to the data.  Thus two C functions with declarations
806
807               int string_length(char *s);
808               int upper_case_char(char *cp);
809
810       may have completely different semantics: the first one may inspect an
811       array of chars pointed by s, and the second one may immediately
812       dereference "cp" and manipulate *cp only (using the return value as,
813       say, a success indicator).  From Perl one would use these functions in
814       a completely different manner.
815
816       One conveys this info to xsubpp by replacing "*" before the argument by
817       "&".  "&" means that the argument should be passed to a library
818       function by its address.  The above two function may be XSUB-ified as
819
820               int
821               string_length(s)
822                       char *  s
823
824               int
825               upper_case_char(cp)
826                       char    &cp
827
828       For example, consider:
829
830               int
831               foo(a,b)
832                       char    &a
833                       char *  b
834
835       The first Perl argument to this function would be treated as a char and
836       assigned to the variable a, and its address would be passed into the
837       function foo.  The second Perl argument would be treated as a string
838       pointer and assigned to the variable b.  The value of b would be passed
839       into the function foo.  The actual call to the function foo that xsubpp
840       generates would look like this:
841
842               foo(&a, b);
843
844       xsubpp will parse the following function argument lists identically:
845
846               char    &a
847               char&a
848               char    & a
849
850       However, to help ease understanding, it is suggested that you place a
851       "&" next to the variable name and away from the variable type), and
852       place a "*" near the variable type, but away from the variable name (as
853       in the call to foo above).  By doing so, it is easy to understand
854       exactly what will be passed to the C function; it will be whatever is
855       in the "last column".
856
857       You should take great pains to try to pass the function the type of
858       variable it wants, when possible.  It will save you a lot of trouble in
859       the long run.
860
861   The Argument Stack
862       If we look at any of the C code generated by any of the examples except
863       example 1, you will notice a number of references to ST(n), where n is
864       usually 0.  "ST" is actually a macro that points to the n'th argument
865       on the argument stack.  ST(0) is thus the first argument on the stack
866       and therefore the first argument passed to the XSUB, ST(1) is the
867       second argument, and so on.
868
869       When you list the arguments to the XSUB in the .xs file, that tells
870       xsubpp which argument corresponds to which of the argument stack (i.e.,
871       the first one listed is the first argument, and so on).  You invite
872       disaster if you do not list them in the same order as the function
873       expects them.
874
875       The actual values on the argument stack are pointers to the values
876       passed in.  When an argument is listed as being an OUTPUT value, its
877       corresponding value on the stack (i.e., ST(0) if it was the first
878       argument) is changed.  You can verify this by looking at the C code
879       generated for Example 3.  The code for the round() XSUB routine
880       contains lines that look like this:
881
882               double  arg = (double)SvNV(ST(0));
883               /* Round the contents of the variable arg */
884               sv_setnv(ST(0), (double)arg);
885
886       The arg variable is initially set by taking the value from ST(0), then
887       is stored back into ST(0) at the end of the routine.
888
889       XSUBs are also allowed to return lists, not just scalars.  This must be
890       done by manipulating stack values ST(0), ST(1), etc, in a subtly
891       different way.  See perlxs for details.
892
893       XSUBs are also allowed to avoid automatic conversion of Perl function
894       arguments to C function arguments.  See perlxs for details.  Some
895       people prefer manual conversion by inspecting ST(i) even in the cases
896       when automatic conversion will do, arguing that this makes the logic of
897       an XSUB call clearer.  Compare with "Getting the fat out of XSUBs" for
898       a similar tradeoff of a complete separation of "Perl glue" and
899       "workhorse" parts of an XSUB.
900
901       While experts may argue about these idioms, a novice to Perl guts may
902       prefer a way which is as little Perl-guts-specific as possible, meaning
903       automatic conversion and automatic call generation, as in "Getting the
904       fat out of XSUBs".  This approach has the additional benefit of
905       protecting the XSUB writer from future changes to the Perl API.
906
907   Extending your Extension
908       Sometimes you might want to provide some extra methods or subroutines
909       to assist in making the interface between Perl and your extension
910       simpler or easier to understand.  These routines should live in the .pm
911       file.  Whether they are automatically loaded when the extension itself
912       is loaded or only loaded when called depends on where in the .pm file
913       the subroutine definition is placed.  You can also consult AutoLoader
914       for an alternate way to store and load your extra subroutines.
915
916   Documenting your Extension
917       There is absolutely no excuse for not documenting your extension.
918       Documentation belongs in the .pm file.  This file will be fed to
919       pod2man, and the embedded documentation will be converted to the
920       manpage format, then placed in the blib directory.  It will be copied
921       to Perl's manpage directory when the extension is installed.
922
923       You may intersperse documentation and Perl code within the .pm file.
924       In fact, if you want to use method autoloading, you must do this, as
925       the comment inside the .pm file explains.
926
927       See perlpod for more information about the pod format.
928
929   Installing your Extension
930       Once your extension is complete and passes all its tests, installing it
931       is quite simple: you simply run "make install".  You will either need
932       to have write permission into the directories where Perl is installed,
933       or ask your system administrator to run the make for you.
934
935       Alternately, you can specify the exact directory to place the
936       extension's files by placing a "PREFIX=/destination/directory" after
937       the make install.  (or in between the make and install if you have a
938       brain-dead version of make).  This can be very useful if you are
939       building an extension that will eventually be distributed to multiple
940       systems.  You can then just archive the files in the destination
941       directory and distribute them to your destination systems.
942
943   EXAMPLE 5
944       In this example, we'll do some more work with the argument stack.  The
945       previous examples have all returned only a single value.  We'll now
946       create an extension that returns an array.
947
948       This extension is very Unix-oriented (struct statfs and the statfs
949       system call).  If you are not running on a Unix system, you can
950       substitute for statfs any other function that returns multiple values,
951       you can hard-code values to be returned to the caller (although this
952       will be a bit harder to test the error case), or you can simply not do
953       this example.  If you change the XSUB, be sure to fix the test cases to
954       match the changes.
955
956       Return to the Mytest directory and add the following code to the end of
957       Mytest.xs:
958
959               void
960               statfs(path)
961                       char *  path
962                   INIT:
963                       int i;
964                       struct statfs buf;
965
966                   PPCODE:
967                       i = statfs(path, &buf);
968                       if (i == 0) {
969                               XPUSHs(sv_2mortal(newSVnv(buf.f_bavail)));
970                               XPUSHs(sv_2mortal(newSVnv(buf.f_bfree)));
971                               XPUSHs(sv_2mortal(newSVnv(buf.f_blocks)));
972                               XPUSHs(sv_2mortal(newSVnv(buf.f_bsize)));
973                               XPUSHs(sv_2mortal(newSVnv(buf.f_ffree)));
974                               XPUSHs(sv_2mortal(newSVnv(buf.f_files)));
975                               XPUSHs(sv_2mortal(newSVnv(buf.f_type)));
976                       } else {
977                               XPUSHs(sv_2mortal(newSVnv(errno)));
978                       }
979
980       You'll also need to add the following code to the top of the .xs file,
981       just after the include of "XSUB.h":
982
983               #include <sys/vfs.h>
984
985       Also add the following code segment to Mytest.t while incrementing the
986       "9" tests to "11":
987
988               @a = &Mytest::statfs("/blech");
989               ok( scalar(@a) == 1 && $a[0] == 2 );
990               @a = &Mytest::statfs("/");
991               is( scalar(@a), 7 );
992
993   New Things in this Example
994       This example added quite a few new concepts.  We'll take them one at a
995       time.
996
997       ·   The INIT: directive contains code that will be placed immediately
998           after the argument stack is decoded.  C does not allow variable
999           declarations at arbitrary locations inside a function, so this is
1000           usually the best way to declare local variables needed by the XSUB.
1001           (Alternatively, one could put the whole "PPCODE:" section into
1002           braces, and put these declarations on top.)
1003
1004       ·   This routine also returns a different number of arguments depending
1005           on the success or failure of the call to statfs.  If there is an
1006           error, the error number is returned as a single-element array.  If
1007           the call is successful, then a 9-element array is returned.  Since
1008           only one argument is passed into this function, we need room on the
1009           stack to hold the 9 values which may be returned.
1010
1011           We do this by using the PPCODE: directive, rather than the CODE:
1012           directive.  This tells xsubpp that we will be managing the return
1013           values that will be put on the argument stack by ourselves.
1014
1015       ·   When we want to place values to be returned to the caller onto the
1016           stack, we use the series of macros that begin with "XPUSH".  There
1017           are five different versions, for placing integers, unsigned
1018           integers, doubles, strings, and Perl scalars on the stack.  In our
1019           example, we placed a Perl scalar onto the stack.  (In fact this is
1020           the only macro which can be used to return multiple values.)
1021
1022           The XPUSH* macros will automatically extend the return stack to
1023           prevent it from being overrun.  You push values onto the stack in
1024           the order you want them seen by the calling program.
1025
1026       ·   The values pushed onto the return stack of the XSUB are actually
1027           mortal SV's.  They are made mortal so that once the values are
1028           copied by the calling program, the SV's that held the returned
1029           values can be deallocated.  If they were not mortal, then they
1030           would continue to exist after the XSUB routine returned, but would
1031           not be accessible.  This is a memory leak.
1032
1033       ·   If we were interested in performance, not in code compactness, in
1034           the success branch we would not use "XPUSHs" macros, but "PUSHs"
1035           macros, and would pre-extend the stack before pushing the return
1036           values:
1037
1038                   EXTEND(SP, 7);
1039
1040           The tradeoff is that one needs to calculate the number of return
1041           values in advance (though overextending the stack will not
1042           typically hurt anything but memory consumption).
1043
1044           Similarly, in the failure branch we could use "PUSHs" without
1045           extending the stack: the Perl function reference comes to an XSUB
1046           on the stack, thus the stack is always large enough to take one
1047           return value.
1048
1049   EXAMPLE 6
1050       In this example, we will accept a reference to an array as an input
1051       parameter, and return a reference to an array of hashes.  This will
1052       demonstrate manipulation of complex Perl data types from an XSUB.
1053
1054       This extension is somewhat contrived.  It is based on the code in the
1055       previous example.  It calls the statfs function multiple times,
1056       accepting a reference to an array of filenames as input, and returning
1057       a reference to an array of hashes containing the data for each of the
1058       filesystems.
1059
1060       Return to the Mytest directory and add the following code to the end of
1061       Mytest.xs:
1062
1063           SV *
1064           multi_statfs(paths)
1065                   SV * paths
1066               INIT:
1067                   AV * results;
1068                   I32 numpaths = 0;
1069                   int i, n;
1070                   struct statfs buf;
1071
1072                   if ((!SvROK(paths))
1073                       || (SvTYPE(SvRV(paths)) != SVt_PVAV)
1074                       || ((numpaths = av_len((AV *)SvRV(paths))) < 0))
1075                   {
1076                       XSRETURN_UNDEF;
1077                   }
1078                   results = (AV *)sv_2mortal((SV *)newAV());
1079               CODE:
1080                   for (n = 0; n <= numpaths; n++) {
1081                       HV * rh;
1082                       STRLEN l;
1083                       char * fn = SvPV(*av_fetch((AV *)SvRV(paths), n, 0), l);
1084
1085                       i = statfs(fn, &buf);
1086                       if (i != 0) {
1087                           av_push(results, newSVnv(errno));
1088                           continue;
1089                       }
1090
1091                       rh = (HV *)sv_2mortal((SV *)newHV());
1092
1093                       hv_store(rh, "f_bavail", 8, newSVnv(buf.f_bavail), 0);
1094                       hv_store(rh, "f_bfree",  7, newSVnv(buf.f_bfree),  0);
1095                       hv_store(rh, "f_blocks", 8, newSVnv(buf.f_blocks), 0);
1096                       hv_store(rh, "f_bsize",  7, newSVnv(buf.f_bsize),  0);
1097                       hv_store(rh, "f_ffree",  7, newSVnv(buf.f_ffree),  0);
1098                       hv_store(rh, "f_files",  7, newSVnv(buf.f_files),  0);
1099                       hv_store(rh, "f_type",   6, newSVnv(buf.f_type),   0);
1100
1101                       av_push(results, newRV((SV *)rh));
1102                   }
1103                   RETVAL = newRV((SV *)results);
1104               OUTPUT:
1105                   RETVAL
1106
1107       And add the following code to Mytest.t, while incrementing the "11"
1108       tests to "13":
1109
1110               $results = Mytest::multi_statfs([ '/', '/blech' ]);
1111               ok( ref $results->[0]) );
1112               ok( ! ref $results->[1] );
1113
1114   New Things in this Example
1115       There are a number of new concepts introduced here, described below:
1116
1117       ·   This function does not use a typemap.  Instead, we declare it as
1118           accepting one SV* (scalar) parameter, and returning an SV* value,
1119           and we take care of populating these scalars within the code.
1120           Because we are only returning one value, we don't need a "PPCODE:"
1121           directive - instead, we use "CODE:" and "OUTPUT:" directives.
1122
1123       ·   When dealing with references, it is important to handle them with
1124           caution.  The "INIT:" block first checks that "SvROK" returns true,
1125           which indicates that paths is a valid reference.  It then verifies
1126           that the object referenced by paths is an array, using "SvRV" to
1127           dereference paths, and "SvTYPE" to discover its type.  As an added
1128           test, it checks that the array referenced by paths is non-empty,
1129           using the "av_len" function (which returns -1 if the array is
1130           empty).  The XSRETURN_UNDEF macro is used to abort the XSUB and
1131           return the undefined value whenever all three of these conditions
1132           are not met.
1133
1134       ·   We manipulate several arrays in this XSUB.  Note that an array is
1135           represented internally by an AV* pointer.  The functions and macros
1136           for manipulating arrays are similar to the functions in Perl:
1137           "av_len" returns the highest index in an AV*, much like $#array;
1138           "av_fetch" fetches a single scalar value from an array, given its
1139           index; "av_push" pushes a scalar value onto the end of the array,
1140           automatically extending the array as necessary.
1141
1142           Specifically, we read pathnames one at a time from the input array,
1143           and store the results in an output array (results) in the same
1144           order.  If statfs fails, the element pushed onto the return array
1145           is the value of errno after the failure.  If statfs succeeds,
1146           though, the value pushed onto the return array is a reference to a
1147           hash containing some of the information in the statfs structure.
1148
1149           As with the return stack, it would be possible (and a small
1150           performance win) to pre-extend the return array before pushing data
1151           into it, since we know how many elements we will return:
1152
1153                   av_extend(results, numpaths);
1154
1155       ·   We are performing only one hash operation in this function, which
1156           is storing a new scalar under a key using "hv_store".  A hash is
1157           represented by an HV* pointer.  Like arrays, the functions for
1158           manipulating hashes from an XSUB mirror the functionality available
1159           from Perl.  See perlguts and perlapi for details.
1160
1161       ·   To create a reference, we use the "newRV" function.  Note that you
1162           can cast an AV* or an HV* to type SV* in this case (and many
1163           others).  This allows you to take references to arrays, hashes and
1164           scalars with the same function.  Conversely, the "SvRV" function
1165           always returns an SV*, which may need to be cast to the appropriate
1166           type if it is something other than a scalar (check with "SvTYPE").
1167
1168       ·   At this point, xsubpp is doing very little work - the differences
1169           between Mytest.xs and Mytest.c are minimal.
1170
1171   EXAMPLE 7 (Coming Soon)
1172       XPUSH args AND set RETVAL AND assign return value to array
1173
1174   EXAMPLE 8 (Coming Soon)
1175       Setting $!
1176
1177   EXAMPLE 9 Passing open files to XSes
1178       You would think passing files to an XS is difficult, with all the
1179       typeglobs and stuff. Well, it isn't.
1180
1181       Suppose that for some strange reason we need a wrapper around the
1182       standard C library function "fputs()". This is all we need:
1183
1184               #define PERLIO_NOT_STDIO 0
1185               #include "EXTERN.h"
1186               #include "perl.h"
1187               #include "XSUB.h"
1188
1189               #include <stdio.h>
1190
1191               int
1192               fputs(s, stream)
1193                       char *          s
1194                       FILE *          stream
1195
1196       The real work is done in the standard typemap.
1197
1198       But you loose all the fine stuff done by the perlio layers. This calls
1199       the stdio function "fputs()", which knows nothing about them.
1200
1201       The standard typemap offers three variants of PerlIO *: "InputStream"
1202       (T_IN), "InOutStream" (T_INOUT) and "OutputStream" (T_OUT). A bare
1203       "PerlIO *" is considered a T_INOUT. If it matters in your code (see
1204       below for why it might) #define or typedef one of the specific names
1205       and use that as the argument or result type in your XS file.
1206
1207       The standard typemap does not contain PerlIO * before perl 5.7, but it
1208       has the three stream variants. Using a PerlIO * directly is not
1209       backwards compatible unless you provide your own typemap.
1210
1211       For streams coming from perl the main difference is that "OutputStream"
1212       will get the output PerlIO * - which may make a difference on a socket.
1213       Like in our example...
1214
1215       For streams being handed to perl a new file handle is created (i.e. a
1216       reference to a new glob) and associated with the PerlIO * provided. If
1217       the read/write state of the PerlIO * is not correct then you may get
1218       errors or warnings from when the file handle is used.  So if you opened
1219       the PerlIO * as "w" it should really be an "OutputStream" if open as
1220       "r" it should be an "InputStream".
1221
1222       Now, suppose you want to use perlio layers in your XS. We'll use the
1223       perlio "PerlIO_puts()" function as an example.
1224
1225       In the C part of the XS file (above the first MODULE line) you have
1226
1227               #define OutputStream    PerlIO *
1228           or
1229               typedef PerlIO *        OutputStream;
1230
1231       And this is the XS code:
1232
1233               int
1234               perlioputs(s, stream)
1235                       char *          s
1236                       OutputStream    stream
1237               CODE:
1238                       RETVAL = PerlIO_puts(stream, s);
1239               OUTPUT:
1240                       RETVAL
1241
1242       We have to use a "CODE" section because "PerlIO_puts()" has the
1243       arguments reversed compared to "fputs()", and we want to keep the
1244       arguments the same.
1245
1246       Wanting to explore this thoroughly, we want to use the stdio "fputs()"
1247       on a PerlIO *. This means we have to ask the perlio system for a stdio
1248       "FILE *":
1249
1250               int
1251               perliofputs(s, stream)
1252                       char *          s
1253                       OutputStream    stream
1254               PREINIT:
1255                       FILE *fp = PerlIO_findFILE(stream);
1256               CODE:
1257                       if (fp != (FILE*) 0) {
1258                               RETVAL = fputs(s, fp);
1259                       } else {
1260                               RETVAL = -1;
1261                       }
1262               OUTPUT:
1263                       RETVAL
1264
1265       Note: "PerlIO_findFILE()" will search the layers for a stdio layer. If
1266       it can't find one, it will call "PerlIO_exportFILE()" to generate a new
1267       stdio "FILE". Please only call "PerlIO_exportFILE()" if you want a new
1268       "FILE". It will generate one on each call and push a new stdio layer.
1269       So don't call it repeatedly on the same file. "PerlIO()"_findFILE will
1270       retrieve the stdio layer once it has been generated by
1271       "PerlIO_exportFILE()".
1272
1273       This applies to the perlio system only. For versions before 5.7,
1274       "PerlIO_exportFILE()" is equivalent to "PerlIO_findFILE()".
1275
1276   Troubleshooting these Examples
1277       As mentioned at the top of this document, if you are having problems
1278       with these example extensions, you might see if any of these help you.
1279
1280       ·   In versions of 5.002 prior to the gamma version, the test script in
1281           Example 1 will not function properly.  You need to change the "use
1282           lib" line to read:
1283
1284                   use lib './blib';
1285
1286       ·   In versions of 5.002 prior to version 5.002b1h, the test.pl file
1287           was not automatically created by h2xs.  This means that you cannot
1288           say "make test" to run the test script.  You will need to add the
1289           following line before the "use extension" statement:
1290
1291                   use lib './blib';
1292
1293       ·   In versions 5.000 and 5.001, instead of using the above line, you
1294           will need to use the following line:
1295
1296                   BEGIN { unshift(@INC, "./blib") }
1297
1298       ·   This document assumes that the executable named "perl" is Perl
1299           version 5.  Some systems may have installed Perl version 5 as
1300           "perl5".
1301

See also

1303       For more information, consult perlguts, perlapi, perlxs, perlmod, and
1304       perlpod.
1305

Author

1307       Jeff Okamoto <okamoto@corp.hp.com>
1308
1309       Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas
1310       Koenig, and Tim Bunce.
1311
1312       PerlIO material contributed by Lupe Christoph, with some clarification
1313       by Nick Ing-Simmons.
1314
1315       Changes for h2xs as of Perl 5.8.x by Renee Baecker
1316
1317   Last Changed
1318       2007/10/11
1319
1320
1321
1322perl v5.12.4                      2011-06-07                      PERLXSTUT(1)
Impressum