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


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

I'm afraid the current installation process is somewhat boneheaded.
Basically this is because nsapi_perl integrates two very different
systems: Perl and the Netscape web server.  Each has likely been built
with its own peculiar compilation and linking options unique to the
build environment.

For Perl it's fairly easy to find what options were used to build it
using the Config.pm module.  Unfortunately I have found that those
options do not necessarily work for building NSAPI functions.  The
problem is especially acute during the linking stage.

The end result is that before building, you must look at the
Makefile.PL found in this directory and manually set the correct set
of compilation and linking options.  If there is a conflict, for
instance if the Perl linking command is different from the NSAPI
linking command, I recommend using the option that works for NSAPI.

Makefile.PL will write two Makefiles.  One Makefile builds the
nsapi_perl.so shared object that slurps Perl into Netscape.  The other
Makefile builds the Perl extension modules that represent the Perl
version of the NSAPI programming environment.  Once the Makefiles have
been generated, each component is built and installed separately.

Enough introduction.  Here are the details

Steps
-----

1.  Edit the Makefile.PL found in this directory.

    In this file are configuration variable setting the compilation
    and linking options for your environment.  You will also find
    variables specifying. the location of your Netscape server.  In
    Makefile.PL whenever you see something like

         $foo = $Config{foo};

    it means that Makefile.PL will use the same value for 'foo' as was
    used when compiling perl.  If you don't think this value will be
    acceptable, just change it to

         $foo = '/some/hard-coded/value/here';

2.  perl ./Makefile.PL

    This will 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.

3.  cd ./nsapi; make

    This will (or should) build a shared object file called
    nsapi_perl.so.  This is the shared object that the Netscape server
    links to at run and is responsible for slurping Perl into
    Netscape.

4.  cd ../perl/lib/Netscape; make

    This will (or should) build the Perl extension modules that you
    will use when doing NSAPI programming in Perl.

5.  cd ../../../nsapi; make install

    This will install the nsapi_perl.so and nsapi_perl.conf files in a
    directory that you specified in Makefile.PL.  It will also echo to
    your screen the lines you will need to add to your server
    obj.conf file to enable Perl (if you miss these lines, don't
    worry, I'll explain them later in this document.)

6.  cd ../perl/lib/Netscape; make install

    This will install the Perl extension modules in the standard
    location for Perl extensions on your system.

7.  Edit your Netscape server obj.conf file.

    The following lines will need to be added to your Netscape server
    obj.conf file.
        Init fn=load-modules shlib=$ns_inst_dir/nsapi_perl.so funcs=nsapi_perl_init,nsapi_perl_handler
        Init fn=nsapi_perl_init conf=$ns_inst_dir/nsapi_perl.conf
    The value of $ns_inst_dir is that as specified in Makefile.PL.

    The first line tells the Netscape server to link to the named
    shared object at runtime.  The second line tells the server to run
    the function called nsapi_perl_init (found in nsapi_perl.so) at
    server startup.  This function creates a perl interpreter which
    then parses and runs the nsapi_perl.conf configuration file

8. 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 conjuction 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.

-If someone can write a Makefile.PL that will automatically deduce (or
at least suggest) all the right compilation and linking options for
any target platform, you will be the subject of great praise in the
CREDITS file.  (The preceding was a blatant request for assistance
from the Perl community).

-nsapi_perl *should* work on a Win32 system that has previously built
Perl and can run NSAPI.  Obviously however, the preceding
installation instructions are painfully Unix-centric.  If you are a
Win32 user, at this time I can only suggest you roll your own.  If you
are successful please send me (bsugars@canoe.ca) an email letting me
know what you had to do.  You will then be the subject of *great*
praise in the CREDITS file.

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