Fix overloading via inherited autoloaded functions
[p5sagit/p5-mst-13.2.git] / pod / perlxstut.pod
index 85a8c71..0ad1b10 100644 (file)
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlXStut - Tutorial for XSUB's
+perlXStut - Tutorial for XSUBs
 
 =head1 DESCRIPTION
 
@@ -10,8 +10,8 @@ L<perlxs>.
 
 This tutorial starts with very simple examples and becomes more complex,
 with each new example adding new features.  Certain concepts may not be
-completely explained until later in the tutorial in order to slowly ease
-the reader into building extensions.
+completely explained until later in the tutorial to ease the
+reader slowly into building extensions.
 
 =head2 VERSION CAVEAT
 
@@ -25,21 +25,21 @@ features were added to Perl 5.
 
 =item *
 
-In versions of 5.002 prior to the gamma version, the test script in Example
-1 will not function properly.  You need to change the "use lib" line to
-read:
+In versions of Perl 5.002 prior to the gamma version, the test script
+in Example 1 will not function properly.  You need to change the "use
+lib" line to read:
 
        use lib './blib';
 
 =item *
 
-In versions of 5.002 prior to version beta 3, then the line in the .xs file
+In versions of Perl 5.002 prior to version beta 3, the line in the .xs file
 about "PROTOTYPES: DISABLE" will cause a compiler error.  Simply remove that
 line from the file.
 
 =item *
 
-In versions of 5.002 prior to version 5.002b1h, the test.pl file was not
+In versions of Perl 5.002 prior to version 5.002b1h, the test.pl file was not
 automatically created by h2xs.  This means that you cannot say "make test"
 to run the test script.  You will need to add the following line before the
 "use extension" statement:
@@ -63,7 +63,7 @@ Some systems may have installed Perl version 5 as "perl5".
 =head2 DYNAMIC VERSUS STATIC
 
 It is commonly thought that if a system does not have the capability to
-dynamically load a library, you cannot build XSUB's.  This is incorrect.
+load a library dynamically, you cannot build XSUBs.  This is incorrect.
 You I<can> build them, but you must link the XSUB's subroutines with the
 rest of Perl, creating a new executable.  This situation is similar to
 Perl 4.
@@ -201,7 +201,7 @@ Now we run the script and we should see the following output:
 =head2 EXAMPLE 2
 
 Now let's add to our extension a subroutine that will take a single argument
-and return 0 if the argument is even, 1 if the argument is odd.
+and return 1 if the argument is even, 0 if the argument is odd.
 
 Add the following to the end of Mytest.xs:
 
@@ -227,7 +227,7 @@ Now re-run make to rebuild our new shared library.
 Now perform the same steps as before, generating a Makefile from the
 Makefile.PL file, and running make.
 
-In order to test that our extension works, we now need to look at the
+To test that our extension works, we now need to look at the
 file test.pl.  This file is set up to imitate the same kind of testing
 structure that Perl itself has.  Within the test script, you perform a
 number of tests to confirm the behavior of the extension, printing "ok"
@@ -261,7 +261,8 @@ h2xs creates a number of files in the extension directory.  The file
 Makefile.PL is a perl script which will generate a true Makefile to build
 the extension.  We'll take a closer look at it later.
 
-The files <extension>.pm and <extension>.xs contain the meat of the extension.
+The files E<lt>extensionE<gt>.pm and E<lt>extensionE<gt>.xs contain the meat
+of the extension.
 The .xs file holds the C routines that make up the extension.  The .pm file
 contains routines that tell Perl how to load your extension.
 
@@ -445,7 +446,7 @@ section on the argument stack.
 =head2 WARNING
 
 In general, it's not a good idea to write extensions that modify their input
-parameters, as in Example 3.  However, in order to better accomodate calling
+parameters, as in Example 3.  However, to accommodate better calling
 pre-existing C routines, which often do modify their input parameters,
 this behavior is tolerated.  The next example will show how to do this.
 
@@ -489,12 +490,13 @@ And finally create a file Makefile.PL that looks like this:
        use ExtUtils::MakeMaker;
        $Verbose = 1;
        WriteMakefile(
-           'NAME' => 'Mytest2::mylib',
-           'clean'     => {'FILES' => 'libmylib.a'},
+           NAME      => 'Mytest2::mylib',
+           SKIP      => [qw(all static static_lib dynamic dynamic_lib)],
+           clean     => {'FILES' => 'libmylib$(LIB_EXT)'},
        );
 
 
-       sub MY::postamble {
+       sub MY::top_targets {
                '
        all :: static
 
@@ -532,7 +534,8 @@ and a new replacement subroutine too:
        }
 
 (Note: Most makes will require that there be a tab character that indents
-the line "cd mylib && $(MAKE)".)
+the line "cd mylib && $(MAKE)", similarly for the Makefile in the
+subdirectory.)
 
 Let's also fix the MANIFEST file so that it accurately reflects the contents
 of our extension.  The single line that says "mylib" should be replaced by
@@ -576,7 +579,7 @@ and add the following lines to the end of the script:
        print &Mytest2::foo(1, 2, "0.0") == 7 ? "ok 3\n" : "not ok 3\n";
        print abs(&Mytest2::foo(0, 0, "-3.4") - 0.6) <= 0.01 ? "ok 4\n" : "not ok 4\n";
 
-(When dealing with floating-point comparisons, it is often useful to not check
+(When dealing with floating-point comparisons, it is often useful not to check
 for equality, but rather the difference being below a certain epsilon factor,
 0.01 in this case)
 
@@ -606,7 +609,7 @@ C<constant> routine.
 
 The .pm file has exported the name TESTVAL in the @EXPORT array.  This
 could lead to name clashes.  A good rule of thumb is that if the #define
-is only going to be used by the C routines themselves, and not by the user,
+is going to be used by only the C routines themselves, and not by the user,
 they should be removed from the @EXPORT array.  Alternately, if you don't
 mind using the "fully qualified name" of a variable, you could remove most
 or all of the items in the @EXPORT array.
@@ -619,12 +622,12 @@ processed at all by h2xs.  There is no good solution to this right now.
 =back
 
 We've also told Perl about the library that we built in the mylib
-subdirectory.  That required only the addition of the MYEXTLIB variable
+subdirectory.  That required the addition of only the MYEXTLIB variable
 to the WriteMakefile call and the replacement of the postamble subroutine
 to cd into the subdirectory and run make.  The Makefile.PL for the
 library is a bit more complicated, but not excessively so.  Again we
 replaced the postamble subroutine to insert our own code.  This code
-simply specified that the library to be created here was a static
+specified simply that the library to be created here was a static
 archive (as opposed to a dynamically loadable library) and provided the
 commands to build it.
 
@@ -684,7 +687,7 @@ usually 0.  The "ST" is actually a macro that points to the n'th argument
 on the argument stack.  ST(0) is thus the first argument passed to the
 XSUB, ST(1) is the second argument, and so on.
 
-When you list the arguments to the XSUB in the .xs file, that tell xsubpp
+When you list the arguments to the XSUB in the .xs file, that tells xsubpp
 which argument corresponds to which of the argument stack (i.e., the first
 one listed is the first argument, and so on).  You invite disaster if you
 do not list them in the same order as the function expects them.
@@ -695,7 +698,7 @@ Sometimes you might want to provide some extra methods or subroutines
 to assist in making the interface between Perl and your extension simpler
 or easier to understand.  These routines should live in the .pm file.
 Whether they are automatically loaded when the extension itself is loaded
-or only loaded when called depends on where in the .pm file the subroutine
+or loaded only when called depends on where in the .pm file the subroutine
 definition is placed.
 
 =head2 DOCUMENTING YOUR EXTENSION
@@ -726,7 +729,7 @@ and L<perlpod>.
 
 =head2 Author
 
-Jeff Okamoto <okamoto@corp.hp.com>
+Jeff Okamoto E<lt>F<okamoto@corp.hp.com>E<gt>
 
 Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig,
 and Tim Bunce.