Installation

The bulk of this chapter deals with the installation of the web-based interpreter, JACL. The console-based interpreter, TACL, can be run from the command line in any directory, although you may find it convenient to move it from jacl-1.5/bin to a directory in you PATH, such as /usr/bin. By default, TACL will first look for a configuration file in the current directory, then in /etc if none is found. Under Unix this configuration file is called tacl.conf, under MS-DOS it is called tacl.cfg. For more information on the tacl.conf file, see the chapter on Internals.

Before the JACL interpreter can be successfully used with an Apache server, the mod_fastcgi module must the installed and configured. There are many different ways to install both the Apache server and the mod_fastcgi module, all of which are detailed in their accompioning documentation. To help you on your way, however, this chapter details one possible configuration to give you some idea of what is involved.

The Apache Server

The Apache Server accepts all HTTP requests from the clients and serves the output of your JACL program back in the form of HTML pages. Without it only limited local use of the interpreter is possible. My preferred installation of Apache is from source. The source code for the latest version of Apache can be obtained from the Apache website. Once you have downloaded the tar file, extract it into the directory where you would like the Apache source is to live. The most common directory for this is /usr/local/src/. Below is a quote from the Apache INSTALL document supplied with the source code. It details the quickest and easiest method possible of getting an Apache source distribution up and running. The following four commands must be executed as root from the Apache source directory:

  1. Overview for the impatient
     --------------------------

     $ ./configure --prefix=PREFIX
     $ make
     $ make install
     $ PREFIX/bin/apachectl start

     NOTE: PREFIX is not the literal string "PREFIX". Instead, use the Unix
           filesystem path under which Apache should be installed. This is 
           usually something like "/usr/local/apache". 

In the first step configure is run. In addition to the --prefix option, two extras are also required if the mod_fastcgi module to later be installed using DSO. Presuming you wish to install Apache into /usr/local/apache, the full install process would be:

     $ ./configure --prefix=/usr/local/apache --enable-rule=SHARED_CORE --enable-module=so
     $ make
     $ make install
     $ usr/local/apache/bin/apachectl start

The final line actually starts the Apache server. The apachectl script can also be passed the parameter restart or stop to do the obvious things.

FastCGI

FastCGI is a system for interfacing a web server with an external binary program, in this case the JACL interpreter. With normal CGI, a program is started to handle each individual request. The program executes, produces some output then terminates. Depending on the startup time of the specific program this can be an extemely inefficient process. With FastCGI, programs are run once, then wait in a loop processing requests as they are made. This suits programs such as the JACL interpreter perfectly as it has a fair amount of processing to do when a game is first run, yet very little for an individual move made by a player. Below is a quote from the mod_fastcgi INSTALL document detailing the process for compiling and installing mod_fastcgi using DSO:

  1. From the mod_fastcgi directory, compile the module.

       $ cd 
           $ apxs -o mod_fastcgi.so -c *.c

  2. Install the module.

           $ apxs -i -a -n fastcgi mod_fastcgi.so

     This should create an entry in httpd.conf that looks like this:

       LoadModule fastcgi_module  /mod_fastcgi.so

     Note that if there's a ClearModuleList directive after new entry,
     you'll have to either move the LoadModule after the ClearModuleList
     or add:

           AddModule mod_fastcgi.c

This process is fairly straight forward. The only real point of note is that the program apxs may not be in your path. If your Apache Server is installed from a standard source distribution and placed in the location used above, apxs can be found in /usr/local/apache/bin/. You will also need to restart the Apache server using the command:

     usr/local/apache/bin/apachectl restart

The above steps simply compile the Apache module mod_fastcgi.so, place it in /usr/local/apache/libexec then add a single line to the httpd.conf. An Intel binary for mod_fastcgi.so is included in the directory /usr/local/jacl-1.5/bin. FastCGI can also be installed by copying this file to /usr/local/apache/libexec addding the LoadModule line to httpd.conf manually (see below).

To configure FastCGI, you must edit the file /usr/local/apache/conf/httpd.conf. The following lines are all that are required for mod_fastcgi to function correctly:

     LoadModule fastcgi_module     libexec/mod_fastcgi.so

     ScriptAlias /fastcgi-bin/ "/usr/local/apache/fastcgi-bin/"

     <Location /fastcgi-bin>
             SetHandler fastcgi-script
             Options ExecCGI
     </Location>

The first line should be added automatically when the module is installed and simply loads the module when the Apache server is started. The next line creates a script alias of /fastcgi-bin that points to the directory /usr/local/apache/fastcgi-bin. This directory must be created and the user that the Apache server runs as must have read and execute premissions to this directory. You may also wish to set the script alias /fastcgi-bin to point to the directory /usr/local/jacl-1.5/games/ where two sample games reside. The final block says that any scripts accessed within the /usr/local/apache/fastcgi-bin directory are to be handled by mod_fastcgi and that the execution of CGI scripts is permitted. As you have probably guessed, this is directory where all your JACL games will be placed.

The JACL Interpreter

Installation of the JACL Interpreter is quite simple — most of the hard work has been done in the previous steps. Start by untaring the file jacl-1.5.tgz in the directory /usr/local. This is achieved using the following command:

     tar -xzvf jacl-1.5.tgz

This first line of each JACL program will tell the operating system that the program is a script that must be interpreted by the jacl executable, and should look like the following:

     #!/usr/local/jacl-1.5/bin/jacl

This line is ignored by the JACL Interpreter itself, as the hash symbol indicates it is a comment. If you have installed the JACL Interpreter in a different location, or are using a different version, you should alter this line accordingly.

Next, the file jacl.conf must be moved from /usr/local/jacl-1.5/ to /etc. This file contains several configuration details. The most imortant directive in this file is bookmarks. This specifies the directory that all persistant data will be written to. By default this is specified in jacl.conf as /usr/local/jacl-1.5/bookmarks. It is important to ensure that the user the Apache server runs as has read and write permissions to this directory and the directory /usr/local/jacl-1.5/log. For more information on the jacl.conf file, see the chapter on Internals.

Finally, in the directory /usr/local/jacl-1.5/games/ you will find two JACL programs: tutorial.jacl and grail.jacl. Copy these files to /usr/local/apache/fastcgi-bin and ensure they are executable by the user the Apache server runs as. Now restart the Apache server with the command:

   /usr/local/apache/bin/apachectl restart