----------------------------------------------------------------------
    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 ***

INSTALL file for nsapi_perl version 0.21.


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

Building nsapi_perl should be relatively straight-forward on Solaris
and NT.  Thanks to Steve Nielsen for contributing a Makefile.PL that
smoothes the Win32 install considerably.

You should be able to install nsapi_perl on Unix platforms other than
Solaris, but it may require some mucking with the install process.  If
you succeed, please let me (Ben Sugars, bsugars@canoe.ca) know so that
I can incorporate any changes you had to make in the next release.

The basic idea is to run a Makefile.PL Perl script that will generate
two additional Makefile.PL perl scripts.  One Makefile.PL builds the
nsapi_perl.so shared object that slurps Perl into Netscape.  The other
Makefile.PL builds the Perl extension modules that represent the Perl
version of the NSAPI programming environment.  Once the Makefile.PL
Perl scripts have been generated, each component is compiled and
installed separately.

Enough introduction.  Here are the details

Steps
-----

(The following commands assume Unix-ness.  Of course, if you're on NT
your path separator will be \ )

1.  perl ./Makefile.PL

    This will ask you some questions regarding the location of your
    Netscape server, NSAPI compilation options, and so on.  It will
    then proceed to create two Makefiles.  One will be in ./nsapi,
    where the NSAPI code that slurps Perl into Netscape lives.  The
    other will be created in ./perl/lib/Netscape where the Perl
    extension module code lives.  I recommend examining each Makefile
    to see if the compilation and linking options look right.

2.  cd ./nsapi
    perl Makefile.PL
    make
    make install

    These commands will (or should) compile, link, and install an
    NSAPI shared object that the server can link to at runtime to
    slurp Perl into Netscape.

4.  cd ../perl/lib/Netscape
    perl Makefile.PL
    make
    make install

    These command will (or should) compile and install a set of Perl
    extension modules (in the Netscape::* hierarchy) that will be used
    by any Perl modules you write or use for nsapi_perl.

5.  Edit your server config files so that Netscape knows about
    nsapi_perl.

    The following lines will need to be added to your Netscape server
    obj.conf file.
        Init fn=load-modules
             shlib=$plugin_dir/nsapi_perl.so
             funcs=nsapi_perl_init,nsapi_perl_handler
        Init fn=nsapi_perl_init
             init-script=$plugin_dir/nsapi_perl_init.pl
    The value of $plugin_dir where the NSAPI shared object has been
    installed.  This location is determined when running the top-level
    Makefile.PL from step 1.

6. Try running your server.

    Start your server the usual way.  You should see a message like
        nsapi_perl_init: loaded a perl version 5.00401 interpreter

    If you see something like this, congratulations!  You have
    embedded Perl in Netscape.

The next thing to do is start to actually *use* your embedded Perl
interpreter.  To do this see the nsapi_perl pod documentation file.


Notes
-----

-If you successfully build nsapi_perl please send me (Ben Sugars,
bsugars@canoe.ca) an email letting me know what you had to do.  That
way I can start to build up a hints file that may make life easier for
the next person building on your platform.  You will also receive a
prominent position in the CREDITS file.

-If you have trouble building nsapi_perl please send me (Ben Sugars,
bsugars@canoe.ca) an email to let me know.  I'll do my best to help.
My immediate goal for nsapi_perl is to make the install process easier
and cross-platform.  The more we learn about what it takes to build on
different systems, the better.

-Problems seem to occur when using nsapi_perl in conjunction with a
Perl that:
     -has not been compiled to use the shared libperl.so;
     -has been compiled to have binary compatibility with 5.003.
If your Perl uses only the static libperl.a and/or has binary
compatibility with 5.003 you could have problems.  At this time the
only workaround seems to be recompiling Perl so that it agrees with
nsapi_perl.  In other words, your Perl should be compiled to use
libperl.so and it should *not* have binary compatibility with 5.003.

-Ben Sugars
<bsugars@canoe.ca>
February 12, 1998
