----------------------------------------------------------------------
    This is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.
 
    This software is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
    along with this software. If not, write to the Free Software
    Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
----------------------------------------------------------------------

	*** This is alpha software -- use at your own risks ***

README for nsapi_perl version 0.15


Introduction
------------

nsapi_perl is provides a mechanism to embed a Perl interpreter in a
Netscape web server (in the tradition of mod_perl for the Apache
server).  This allows one to program to the Netscape Server API
(NSAPI) in Perl rather than in C.


Installation
------------

See the file INSTALL for complete installation instructions.

The prerequisites are
        -Perl version 5.004 or more recent.
        -A Netscape web server.  Should work with almost any Netscape
        server that supports NSAPI programming.

At this point in time the installation process requires some
hand-holding.  This is because nsapi_perl integrates two potentially
very different systems: Perl and the Netscape server.  Each system has,
in all likelihood, been built in a very different manner.  Worse yet,
since the Netscape server is pre-compiled, you will not be able to
re-build it as mod_perl does Apache.

Nevertheless, installation should be relatively straight-forward on
any system where Perl has been compiled and which has a working
Netscape server.

Please see the paragraph in the 'Notes' section of INSTALL regarding
the use of the static libperl.a and Perls that have binary
compatibility with 5.003.

The installation process is Unix-centric.  If you are reading this on
a Win32 system, I encourage you to adapt the installation process to
work and send me (Ben Sugars, bsugars@canoe.ca) an email detailing the
changes.


Further Reading
---------------

Once you have installed nsapi_perl the following pod documents will
provide further direction:

        -perldoc nsapi_perl - a general overview of how to configure
        nsapi_perl plus a couple of examples of how to use it.  Start
        here.

        -perldoc Netscape::Server - describes a module that provides
        the framework upon which the Perl interface to NSAPI works.

        -perldoc Netscape::Server::Session - describes a class which
        you'll use when writing nsapi_perl subroutines.

        -perldoc Netscape::Server::Request - another class which your
        subroutines will use.

        -perldoc Netscape::Registry - this module lets you run perl
        CGI scripts unmodified from within the httpd process itself.
        This offers a large performance boost.


Issues, Bugs and Wishes
-----------------------

See the file TO_DO for a complete wish list.  You are encouraged to try
to address issues identified in TO_DO yourself.  My only request is
that you let me know what you have done so that you can get the proper
credit for it.

Here are the major issues at this time:

The installation process needs to be improved.  Ideally it should be
able to detect what the correct combination of compilation and linking
options for your system are and go from there.

Extension modules that use dynamic loading of C code remain
problematic.  For me, they only work if the module's shared library
contains a runpath to the shared perl library.  In otherwords, for
module Foo, an ldd on Foo.so needs to so
        libperl.so =>    /lib/perl5/sun4-solaris/5.00401/CORE/libperl.so
or something like that.

Threading.  Grrrr.  Netscape *used* to let you run their
multithreaded servers as multiprocess single-threaded servers if you
wanted to.  The 3.x line doesn't let you do this, AFAIK.  So, we need
a thread-safe libperl.so.  I know this is being worked on, but in the
meantime, does anyone know if the libperl.so with 5.004 is OK to use?


Notes
-----

The whole system is at this time still very much alpha.  It may crash
servers.  The programming interface may also change in the future too.

If you have any questions, comments, concerns, or criticisms please
let me (Ben Sugars, bsugars@canoe.ca) know.  I'll do my best to
respond.

If you find and fix a bug, please let me know so that everyone can
benefit and so that you get the proper credit.

Contributors wanted!  Please have a look at the file called TO_DO for
some suggestions.  In particular, any module that uses nsapi_perl is a
candidate for inclusion in the distribution and its author will be
loudly acknowledged.


-Ben Sugars
<bsugars@canoe.ca>
January 8, 1997