perl-aol Code
Status: Beta
Brought to you by:
jwl
Menu
▾
▴
Tree [76ac2b] master / History
Read Me
PERL-AOL README FILE
-------- ------ ----
INSTALLATION
============
The perl-aol project attempts to merge perl and aolserver such that
aolserver can call perl scripts which can directly use the aolserver
API functions and data structures.
In this first release, it is -assumed- the user knows how to find and
follow build instructions for perl and aolserver. Some specific information
relative to this project:
perl
----
Summary: build perl-5.6.0 with USE_ITHREADS and MULTIPLICITY. Others
later; try and report if you're so inclined. Recommended to build to
install in a particular dir (/usr/local/perl-5.6.0); other dirs available
by you discovering what things to edit in the other pieces. Arrange
to run this perl by putting its bin dir first in your path.
The perl-aol glue code has been tested with perl-5.6.0 built with
"MULTIPLICITY" and "USE_ITHREADS". I'm presently hoping it
will also work with "MULTIPLICITY" and any of "PERL_IMPLICIT_CONTEXT",
old-style threads ("USE_THREADS") or perl interpreter as a C++ object
("PERL_OBJECT").
Again, however, it has only been -tested- with "MULTIPLICITY" and
"USE_ITHREADS".
Test with the others if you like, and let me know how it goes. No
guarantees :)
It is recommended you arrange to install the new perl into the dir
/usr/local/perl-5.6.0 so it doesn't disturb any other perl you may
have installed. The makefiles of the other pieces of this project
presently assume that place. Suggestions for changing this accepted
but placed on low priority.
Arrange to run this special perl (which is needed sometimes, for such
things as helping to build the other parts of this package) in your
posix-compatible shell by using the following environment variable
assignment:
export PATH=/usr/local/perl-5.6.0/bin:$PATH
This will cause this special perl to be found before any others that
may be installed.
You must edit the top-level makefile with either an unambiguous name
for perl (for example, in debian woody with the perl-5.6-thread pkg
installed, the perl binary is named perl-thread); or else you must
put the full path to your perl (which you must also do if you haven't
put the special perl in your path).
perl-config
-----------
Summary: perl-config is a perl script I wrote which encapsulates perl's
own ability to output information about how and where it was configured,
for the benefit of things to be built against it. N.B., the perl that runs
this script is the one for which the config information is output. Be
sure the perl that runs this script is the one you want, which is most
often the special perl you built for the perl-aol project. perl-config
and the dir /path/to/perl-aol/aolsvr-src/ should be owned by the
aolserver administrative user and maybe group. (see aolserver below)
It must be in perl-aol/ and can be run as:
/path/to/special/perl /path/to/perl-aol/perl-config <option>
where <option> is one of --cflags, --libs, --archdir or --includes.
It outputs command line options to a C compiler, or a pathname,
depending on its argument.
It's perfectly safe to give this a try. It writes no files nor changes
any resources.
aolserver
---------
Summary: Recommended version is aolserver-3.1 final, the first
version that allows module dirs outside aolserver source dir.
The glue module is called nsperl. Recommended to install in a
particular dir, other dirs available by you editing the top-
level makefile. The source dir also has a recommended place
(at least wrt the nsperl src). You should have a user called
aolserver (or maybe nsadmin) and you might have a group for
global web pages and scripts. The aolserver source code directory
and the install directory /usr/local/aolserver/ should be owned
by this user/group. When you build aolserver, you should build
and install when logged in as aolserver or nsadmin.
The recommended version of aolserver is the final version of 3.1.
Recent tests of version 3.2 final shows it works fine also.
Earlier versions were not prepared to have the source of 3rd-party
(and other external) modules located in arbitrary dirs.
You should be sure aolserver installs in /usr/local/aolserver
(this should be the value of PREFIX in the helper/include file
named .../aolserver3_1/include/Makefile.global). If you want a
different PREFIX than this, you have to edit the top level
makefile.
Because aolserver needs a user and maybe a group for itself,
you should become that user to make the dirs perl-aol/aolsvr-src
and /usr/local/aolserver. You should also become this user when
building and installing aolserver itself or any aolserver modules,
an example of which is nsperl, the module that aolserver calls
when a web user requests a perl script to be executed by the
server.
Should be able to:
make
make install
the perl Aolserver::* modules
--- ---- ------------ -------
Summary: You should find a directory Aolserver inside the main dir
perl-aol. Requires that aolserver and the special perl be properly
installed. The top-level makefile will build or install them.
These modules expose the aolserver API to perl, hence the includes
need to be in the expected place. This is done by installing aolserver
correctly. Some of the source files are used both within these modules
and in the nsperl module, so it can create the browser connectivity
data structure which is then made available to perl scripts in the
variable $Aolserver::Ns_Conn::theConn.
So far, the Aolserver module has the following submodules defined:
Ns_DString
Ns_Conn
Ns_Set
Ns_Request
Ns_DbHandle
with more coming. There are directories named for these modules inside
the Aolserver dir.
To get information about how to use them, you can use:
perldoc Aolserver::Ns_Set (or whichever one you want.)
aolserver module nsperl
--------- ------ ------
Summary: builds in a particular dir (at least wrt aolserver src),
needs mention in the config file so it loads on startup, perl
and the perl modules must be installed correctly (due to nsperl's
dependence upon some separately compiled type conversion functions)
The nsperl module is installed according to the settings of the
makefile perl-aol/aolsvr-src/aolserver3_1/include/Makefile.module.
You need to also let aolserver know in your configuration file
that it should load the nsperl module when it starts.
An example piece of a config file (yourserver.ini) reads:
[ns/server/yourserver/modules]
nssock=nssock.so
nslog=nslog.so
nscgi=nscgi.so
nscp=nscp.so
nsperl=nsperl.so <--- add this
:
:
[ns/server/yourserver/module/nsperl] <--- add this
binary=/usr/local/aolserver/bin/nsperl.so <--- and this
For newer releases of AOLserver using .tcl config files:
#
# Modules to load
#
ns_section "ns/server/${servername}/modules"
ns_param nssock ${bindir}/nssock${ext}
ns_param nslog ${bindir}/nslog${ext}
ns_param nsperl ${bindir}/nsperl${ext} <--- add this
...
and a quick check of the Makefile.module should confirm the place
the modules are installed is in /usr/local/aolserver/bin/.
Make sure the perl module sources (Aolserver::*) are installed
in the correct place. nsperl depends on source files in them.
(both the perl module sources and nsperl sources come with this
distribution, and are set up correctly, so unless you move them,
this should not be a problem.)
USING NSPERL
===== ======
Presently, the perl URL is hard-wired, to http://ser.ver:port/perl/.
Thus, perl scripts must go into a dir called perl inside the dir
designated by the config file as the page root. A typical tree might
look like:
/
|
|
|
-------------------------------------------
/ / / / / / / / /
usr bin | home
web ...........(note, this is ACS's home)
|
-------------------------------------------
/ / / / / / / /
server1 server2 server3
|
-------------------------------------------
/ / / / / /
| | | | | |
tcl bin users parameters www templates
| \..............(note, this is the
| page root of server3)
|
perl .........(note, you make this dir)
|
-------------------------------------------
/ / / / / /
| | | | | |
a.pl b.pl c.pl Ns_SetTest.perl (etc)
In this tree, you can see server3's page root in /web/server3/www.
Make a dir named perl inside that dir, and put your perl scripts
in it.
If you wanted to run, say, the a.pl script, you'd point a browser at
http://ser.ver/perl/a.pl
and if a.pl returns content (or just an ok) to the browser, it'll be
the connection will close properly.
There is a variable in the special perl which always holds this connection
object, through which you can communicate with the browser. The name of
this variable, is $Aolserver::Ns_Conn::theConn.
If you have more questions, please post them to the forum.
