5.002 beta 1

If you're adventurous, have a look at

    ftp://ftp.sems.com/pub/outgoing/perl5.0/perl5.002beta1.tar.gz

Many thanks to Andy for doing the integration.

Obviously, if you consult the bugs database, you'll note there are
still plenty of buglets that need fixing, and several enhancements that
I've intended to put in still haven't made it in (Hi, Tim and Ilya).
But I think it'll be pretty stable.  And you can start to fiddle around
with prototypes (which are, of course, still totally undocumented).

Packrats, don't worry too much about readvertising this widely.
Nowadays we're on a T1 here, so our bandwidth is okay.

Have the appropriate amount of jollity.

Larry

1 files changed, 529 insertions, 0 deletions

diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod
new file mode 100644
index 0000000000..484f49dfc3
--- /dev/null
+++ b/pod/perlxstut.pod
@@ -0,0 +1,529 @@
+=head1 NAME
+
+perlXStut - Tutorial for XSUB's
+
+=head1 DESCRIPTION
+
+This tutorial will educate the reader on the steps involved in creating
+a Perl 5 extension.  The reader is assumed to have access to L<perlguts> and
+L<perlxs>.
+
+This tutorial starts with very simple examples and becomes more complex,
+bringing in more features that are available.  Thus, certain statements
+towards the beginning may be incomplete.  The reader is encouraged to
+read the entire document before lambasting the author about apparent
+mistakes.
+
+This tutorial is still under construction.  Constructive comments
+are welcome.
+
+=head1 EXAMPLE 1
+
+Our first extension will be very simple.  When we call the routine in the
+extension, it will print out a well-known message and terminate.
+
+Run "h2xs -A -n Test1".  This creates a directory named Test1, possibly under
+ext/ if it exists in the current working directory.  Four files will be
+created in the Test1 dir: MANIFEST, Makefile.PL, Test1.pm, Test1.xs.
+
+The MANIFEST file should contain the names of the four files created.
+
+The file Makefile.PL should look something like this:
+
+	use ExtUtils::MakeMaker;
+	# See lib/ExtUtils/MakeMaker.pm for details of how to influence
+	# the contents of the Makefile that is written.
+	WriteMakefile(
+	    'NAME'      => 'Test1',
+	    'VERSION'   => '0.1',
+	    'LIBS'      => [''],   # e.g., '-lm'
+	    'DEFINE'    => '',     # e.g., '-DHAVE_SOMETHING'
+	    'INC'       => '',     # e.g., '-I/usr/include/other'
+	);
+
+The file Test1.pm should look something like this:
+
+	package Test1;
+	
+	require Exporter;
+	require DynaLoader;
+	
+	@ISA = qw(Exporter DynaLoader);
+	# Items to export into callers namespace by default. Note: do not export
+	# names by default without a very good reason. Use EXPORT_OK instead.
+	# Do not simply export all your public functions/methods/constants.
+	@EXPORT = qw(
+	
+	);
+	bootstrap Test1;
+	
+	# Preloaded methods go here.
+	
+	# Autoload methods go after __END__, and are processed by the autosplit program.
+	
+	1;
+	__END__
+
+And the Test1.xs file should look something like this:
+
+	#include "EXTERN.h"
+	#include "perl.h"
+	#include "XSUB.h"
+	
+	MODULE = Test1		PACKAGE = Test1
+
+Let's edit the .xs file by adding this to the end of the file:
+
+	void
+	hello()
+	
+		CODE:
+		printf("Hello, world!\n");
+
+Now we'll run "perl Makefile.PL".  This will create a real Makefile,
+which make needs.  It's output looks something like:
+
+	% perl Makefile.PL
+	Checking if your kit is complete...
+	Looks good
+	Writing Makefile for Test1
+	%
+
+Now, running make will produce output that looks something like this:
+
+	% make
+	mkdir ./blib
+	mkdir ./blib/auto
+	mkdir ./blib/auto/Test1
+		perl xsubpp -typemap typemap Test1.xs >Test1.tc && mv Test1.tc Test1.c
+		cc -c Test1.c
+	Running Mkbootstrap for Test1 ()
+		chmod 644 Test1.bs
+		LD_RUN_PATH="" ld -o ./blib/auto/Test1/Test1.sl -b Test1.o
+		chmod 755 ./blib/auto/Test1/Test1.sl
+		cp Test1.bs ./blib/auto/Test1/Test1.bs
+		chmod 644 ./blib/auto/Test1/Test1.bs
+		cp Test1.pm ./blib/Test1.pm
+		chmod 644 ./blib/Test1.pm
+
+Now we'll create a test script, test1.pl in the Test1 directory.  It should
+look like this:
+
+	#! /usr/local/bin/perl
+	
+	BEGIN { unshift(@INC, "./blib") }
+	
+	use Test1;
+	
+	Test1::hello();
+
+Now we run the script and we should see the following output:
+
+	% perl test1.pl
+	Hello, world!
+	%
+
+=head1 EXAMPLE 2
+
+Now let's create a simple extension that will take a single argument and
+return 0 if the argument is even, 1 if the argument is odd.
+
+Run "h2xs -A -n Test2".  This will create a Test2 directory with a file
+Test2.xs underneath it.  Add the following to the end of the XS file:
+
+	int
+	is_even(input)
+		int	input
+	
+		CODE:
+		RETVAL = input % 2;
+	
+		OUTPUT:
+		RETVAL
+
+(Note that the line after the declaration of is_even is indented one tab
+stop.  Although there is a tab between "int" and "input", this can be any
+amount of white space.  Also notice that there is no semi-colon following
+the "declaration" of the variable input)
+
+Now perform the same steps before, generating a Makefile from the
+Makefile.PL file, and running make.
+
+Our test file test2.pl will now look like:
+
+	BEGIN { unshift(@INC, "./blib"); }
+	
+	use Test2;
+	
+	$a = &Test2::is_even(2);
+	$b = &Test2::is_even(3);
+	
+	print "\$a is $a, \$b is $b\n";
+
+The output should look like:
+
+	% perl test2.pl
+	$a is 0, $b is 1
+	%
+
+=head1 WHAT HAS GONE ON?
+
+The program h2xs is the starting point for creating extensions.  In later
+examples, we'll see how we can use h2xs to read header files and generate
+templates to connect to C routines.
+
+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 .xs file holds the C routines that make up the extension.  The .pm file
+contains routines that tells Perl how to load your extension.
+
+Generating the invoking the Makefile created a directory blib in the current
+working directory.  This directory will contain the shared library that we
+will build.  Once we have tested it, we can install it into its final location.
+
+Finally, our test scripts do two important things.  First of all, they place
+the directory "blib" at the head of the @INC array.  Placing this inside a
+BEGIN block assures us that Perl will look in the blib directory hierarchy
+before looking in the system directories.  This could be important if you are
+upgrading an already-existing extension and do not want to disturb the system
+version until you are ready to install it.
+
+Second, the test scripts tell Perl to C<use extension;>.  When Perl sees this,
+it searches for a .pm file of the same name in the various directories kept
+in the @INC array.  If it cannot be found, perl will die with an error that
+will look something like:
+
+	Can't locate Test2.pm in @INC at ./test2.pl line 5.
+	BEGIN failed--compilation aborted at ./test2.pl line 5.
+
+The .pm file tells perl that it will need the Exporter and Dynamic Loader
+extensions.  It then sets the @ISA array, which is used for looking up
+methods that might not exist in the current package, and finally tells perl
+to bootstrap the module.  Perl will call its dynamic loader routine and load
+the shared library.
+
+The @EXPORT array in the .pm file tells Perl which of the extension's
+routines should be placed into the calling package's namespace.  In our two
+examples so far, we have not modified the @EXPORT array, so our test
+scripts must call the routines by their complete name (e.g., Test1::hello).
+If we placed the name of the routine in the @EXPORT array, so that the
+.pm file looked like:
+
+	@EXPORT = qw( hello );
+
+Then the hello routine would also be callable from the "main" package.
+We could therefore change test1.pl to look like:
+
+	#! /usr/local/bin/perl
+	
+	BEGIN { unshift(@INC, "./blib") }
+	
+	use Test1;
+	
+	hello();
+
+And we would get the same output, "Hello, world!".
+
+Most of the time you do not want to export the names of your extension's
+subroutines, because they might accidentally clash with other subroutines
+from other extensions or from the calling program itself.
+
+=head1 EXAMPLE 3
+
+Our third extension will take one argument as its input, round off that
+value, and set the argument to the rounded value.
+
+Run "h2xs -A -n Test3".  This will create a Test3 directory with a file
+Test3.xs underneath it.  Add the following to the end of the XS file:
+
+	void
+	round(arg)
+		double  arg
+	
+		CODE:
+		if (arg > 0.0) {
+			arg = floor(arg + 0.5);
+		} else if (arg < 0.0) {
+			arg = ceil(arg - 0.5);
+		} else {
+			arg = 0.0;
+		}
+		OUTPUT:
+		arg
+
+Edit the file Makefile.PL so that the corresponding line looks like this:
+
+	'LIBS'      => ['-lm'],   # e.g., '-lm'
+
+Generate the Makefile and run make.  The test script test3.pl looks like:
+
+	#! /usr/local/bin/perl
+	
+	BEGIN { unshift(@INC, "./blib"); }
+	
+	use Test3;
+	
+	foreach $i (-1.4, -0.5, 0.0, 0.4, 0.5) {
+		$j = $i;
+		&Test3::round($j);
+		print "Rounding $i results in $j\n";
+	}
+	
+	print STDERR "Trying to round a constant -- ";
+	&Test3::round(2.0);
+
+Notice the output from trying to send a constant in to the routine.  Perl
+reports:
+
+	Modification of a read-only value attempted at ./test3.pl line 15.
+
+Perl won't let you change the value of two to, say, three, unlike a FORTRAN
+compiler from long, long ago!
+
+=head1 WHAT'S NEW HERE?
+
+Two things are new here.  First, we've made some changes to Makefile.PL.
+In this case, we've specified an extra library to link in, in this case the
+math library, libm.  We'll talk later about how to write XSUBs that can call
+every routine in a library.
+
+Second, the value of the function is being passed back not as the function's
+return value, but through the same variable that was passed into the function.
+
+=head1 INPUT AND OUTPUT PARAMETERS
+
+You specify the parameters that will be passed into the XSUB just after you
+declare the function return value and name.  The list of parameters looks
+very C-like, but the lines must be indented by a tab stop, and each line
+may not have an ending semi-colon.
+
+The list of output parameters occurs after the OUTPUT: directive.  The use
+of RETVAL tells Perl that you wish to send this value back as the return
+value of the XSUB function.  Otherwise, you specify which variables used
+in the XSUB function should be placed into the respective Perl variables
+passed in.
+
+=head1 THE XSUBPP COMPILER
+
+The compiler xsubpp takes the XS code in the .xs file and converts it into
+C code, placing it in a file whose suffix is .c.  The C code created makes
+heavy use of the C functions within Perl.
+
+=head1 THE TYPEMAP FILE
+
+The xsubpp compiler uses rules to convert from Perl's data types (scalar,
+array, etc.) to C's data types (int, char *, etc.).  These rules are stored
+in the typemap file ($PERLLIB/ExtUtils/typemap).  This file is split into
+three parts.
+
+The first part attempts to map various C data types to a coded flag, which
+has some correspondence with the various Perl types.  The second part contains
+C code which xsubpp uses for input parameters.  The third part contains C
+code which xsubpp uses for output parameters.  We'll talk more about the
+C code later.
+
+Let's now take a look at the .c file created for the Test3 extension.
+
+	/*
+	 * This file was generated automatically by xsubpp version 1.9 from the 
+	 * contents of Test3.xs. Don't edit this file, edit Test3.xs instead.
+	 *
+	 *	ANY CHANGES MADE HERE WILL BE LOST! 
+	 *
+	 */
+
+	#include "EXTERN.h"
+	#include "perl.h"
+	#include "XSUB.h"
+	
+	
+	XS(XS_Test3_round)
+	{
+	    dXSARGS;
+	    if (items != 1) {
+		croak("Usage: Test3::round(arg)");
+	    }
+	    {
+		double	arg = (double)SvNV(ST(0)); /* XXXXX */
+
+		if (arg > 0.0) {
+			arg = floor(arg + 0.5);
+		} else if (arg < 0.0) {
+			arg = ceil(arg - 0.5);
+		}
+	
+		sv_setnv(ST(0), (double)arg); /* XXXXX */
+	    }
+	    XSRETURN(1);
+	}
+	
+	XS(boot_Test3)
+	{
+	    dXSARGS;
+	    char* file = __FILE__;
+	
+	    newXS("Test3::round", XS_Test3_round, file);
+	    ST(0) = &sv_yes;
+	    XSRETURN(1);
+	}
+
+Notice the two lines marked with "XXXXX".  If you check the first section of
+the typemap file, you'll see that doubles are of type T_DOUBLE.  In the
+INPUT section, an argument that is T_DOUBLE is assigned to the variable
+arg by calling the routine SvNV on something, then casting it to double,
+then assigned to the variable arg.  Similarly, in the OUTPUT section,
+once arg has its final value, it is passed to the sv_setnv function to
+be passed back to the calling subroutine.  These two functions are explained
+in perlguts; we'll talk more later about what that "ST(0)" means in the
+section on the argument stack.
+
+=head1 WARNING
+
+In general, it's not agood idea to write extensions that modify their input
+parameters, as in Example 3.  However, in order to better accomodate calling
+pre-existing C routines, which often do modify their input parameters,
+this behavior is tolerated.  The next example will show to do this.
+
+=head1 EXAMPLE 4
+
+We'll now show how we can call routines in libraries, such as the curses
+screen handling package, or a DBM module like GDBM.  Each of these libraries
+has a header file from which we will generate an XS template that we'll then
+fine-tune.
+
+Rather than attempt to find a library that exists on all systems, we'll
+first create our own C library, then create an XSUB to it.
+
+Let's create the files libtest4.h and libtest4.c as follows:
+
+	/* libtest4.h */
+
+	#define TESTVAL	4
+
+	extern int	test4(int, long, const char*);
+
+	/* libtest4.c */
+	
+	#include <stdlib.h>
+	#include "./libtest4.h"
+	
+	int
+	test4(a, b, c)
+	int		a;
+	long		b;
+	const char *	c;
+	{
+		return (a + b + atof(c) + TESTVAL);
+	}
+
+Now let's compile it into a library.  Since we'll be eventually using this
+archive to create a shared library, be sure to use the correct flags to
+generate position-independent code.  In HP-UX, that's:
+
+	% cc -Aa -D_HPUX_SOURCE -c +z libtest4.c
+	% ar cr libtest4.a libtest4.o
+
+Now let's move the libtest4.h and libtest.a files into a sub-directory under
+/tmp, so we don't interfere with anything.
+
+	% mkdir /tmp/test4
+	% mkdir /tmp/test4/include
+	% mkdir /tmp/test4/lib
+	% cp libtest4.h /tmp/test4/include
+	% cp libtest4.a /tmp/test4/lib
+
+Okay, now that we have a header file and a library, let's begin actually
+writing the extension.
+
+Run "h2xs -n Test4 /tmp/test4/include/libtest4.h" (notice we are no longer
+specifying -A as an argument).  This will create a Test4 directory with a file
+Test4.xs underneath it.  If we look at it now, we'll see some interesting
+things have been added to the various files.
+
+=over 2
+
+=item *
+
+In the .xs file, there's now a #include declaration with the full path to
+the libtest4.h header file.
+
+=item *
+
+There's now some new C code that's been added to the .xs file.  The purpose
+of the C<constant> routine is to make the values that are #define'd in the
+header file available to the Perl script by calling C<&main::TESTVAL>.
+There's also some XS code to allow calls to the C<constant> routine.
+
+=item *
+
+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,
+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.
+
+=back
+
+Let's now add a definition for the routine in our library.  Add the following
+code to the end of the .xs file:
+
+	int
+	test4(a,b,c)
+	int             a
+	long            b
+	const char *    c
+
+Now we also need to create a typemap file because the default Perl doesn't
+currently support the const char * type.  Create a file called typemap and
+place the following in it:
+
+	const char *	T_PV
+
+Now we must tell our Makefile template where our new library is.  Edit the
+Makefile.PL and change the following line:
+
+	'LIBS'      => ['-ltest4 -L/tmp/test4'],   # e.g., '-lm'
+
+This specifies that we want the library test4 linked into our XSUB, and that
+it should also look in the directory /tmp/test4.
+
+Let's also change the following line in the Makefile.PL to this:
+
+	'INC'       => '-I/tmp/test/include',     # e.g., '-I/usr/include/other'
+
+and also change the #include in test4.xs to be:
+
+	#include <libtest4.h>
+
+Now we don't have to specify the absolute path of the header file in the
+.xs file, relying on the Makefile to tell the compiler where to find the
+header files.  This is generally considered a Good Thing.
+
+Okay, let's create the Makefile, and run make.  You can ignore a message that
+may look like:
+
+	Warning (non-fatal): No library found for -ltest4
+
+If you forgot to create the typemap file, you might see output that looks
+like this:
+
+	Error: 'const char *' not in typemap in test4.xs, line 102
+
+This error means that you have used a C datatype that xsubpp doesn't know
+how to convert between Perl and C.  You'll have to create a typemap file to 
+tell xsubpp how to do the conversions.
+
+=head1 Author
+
+Jeff Okamoto
+
+=head1 Last Changed
+
+1995/11/20
+
+Jeff Okamoto 
+F<E<lt>okamoto@hpcc123.corp.hp.comE<gt>>