----------------------------------------------------------------------
   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.20.


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. If you
successfully install nsapi_perl please let me know so that you can be
kept up-to-date with changes and bug fixes.

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.

Installation should be relatively straight-forward on Solaris and NT
systems.  It should also be possible on other Unix systems where Perl
has been compiled and which have working Netscape servers.  However,
on non-Solaris Unixes the install process might need some hand-holding.

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.


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 other words, 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 multi-threaded
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
Perl library.  Steve Nielsen ([email protected]) is working on
integrating the new threaded Perl with nsapi_perl.  Stay tuned.

In the meantime, you can use nsapi_perl with a multi-threaded server
(because the Perl hooks are enclosed in critical sections) but you do
so at your own since if Perl hangs your whole server will freeze
(because the Perl hooks are enclosed in critical sections).


Notes
-----

If you have any questions, comments, concerns, or criticisms please
let me (Ben Sugars, [email protected]) 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.


Acknowledgments
----------------

My sincere gratitude goes out to

   Steve Nielsen <[email protected]> for many invaluable
   patches and for providing Win32 support.

   Olivier Dehon <[email protected]> net_read() patches, and
   other enhancements to Netscape::Server.pm.

   Other people who have tried and tested nsapi_perl, especially Danny
   Sadinoff <[email protected]> and Craig Riter <[email protected]>.


-Ben Sugars
<[email protected]>
February 12, 1998

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.