Installation

The latest version of the JACL package can be found at http://jacl.sourceforge.net/download.html. Untar the JACL package into your desired location. This will create the directory jacl-1.13 and several subdirectories.

Compilation

The src directory contains the C source code to the three JACL interpreters. Also included is the source to CGIHTML, a required library written by Eugene Kim. In order to compile the JACL interpreters you will require certain other libraries to also be available on your system:
Interpreter Required Libraries
jacl Readline and History, available from http://tiswww.case.edu/php/chet/readline/rltop.html, or as the Debian packages:
libreadline5 libreadline5-dev readline-common

cgijacl No special libraries are required to compile cgijacl, however a POSIX compliant system is needed. Compilation under Microsoft Windows requires the installation of Cygwin first.
fcgijacl FastCGI, available from http://www.fastcgi.com/index.html, or as the Debian packages:
libfcgi-dev libfci0c2

Interpreter	Required Libraries
jacl	Readline and History, available from http://tiswww.case.edu/php/chet/readline/rltop.html, or as the Debian packages: libreadline5 libreadline5-dev readline-common
cgijacl	No special libraries are required to compile cgijacl, however a POSIX compliant system is needed. Compilation under Microsoft Windows requires the installation of Cygwin first.
fcgijacl	FastCGI, available from http://www.fastcgi.com/index.html, or as the Debian packages: libfcgi-dev libfci0c2

To compile all three JACL interpreters and have their executable binaries copied into the bin subdirectory, simply change to the src subdirectory and type:

make install

The cgijacl and fcgijacl interpreters also have support for the German language. To change the language from English to German, you will need to edit the file language.h. Locate the section below and comment out the #define for English and uncomment the one for German:

/* NATIVE_LANGUAGE options: ENGLISH or GERMAN */

#define ENGLISH     1
#define GERMAN      2

/* #define NATIVE_LANGUAGE ENGLISH */
#define NATIVE_LANGUAGE GERMAN

In its default mode, the cgijacl interpreter will check the time stamp of the game file before each move to see if it has been modified. This feature is useful while developing a new game to save you the effort of stopping and restarting the interpreter before testing a new piece of code. If you would prefer the interpreter not to make this check in order to slightly increase performance while playing a completed, game you will need to edit the file webjacl.h. Locate the section below and comment out the #define for WJ_DEVSERVER and uncomment the one for WJ_PRODSERVER.

/* WJ_SERVERTYPE options: WJ_DEVSERVER, WJ_PRODSERVER */

#define WJ_SERVERTYPE WJ_DEVSERVER
/* #define WJ_SERVERTYPE WJ_PRODSERVER */

If you do not specify a port on the command line when starting a game using cgijacl the game will be made available on the default port. As distributed, cgijacl uses 8080 as the default port. To change this default port you will need to edit the file webjacl.h. Locate the section below and edit the port number to the port you would like cgijacl to use by default.

/* The default port to use if a -p command line option
   is not given at startup */

#define WJ_DEFAULT_PORT 8080

Once you have made any of the above changes you will need to recompile the interpreter using the make command.

After you have run make install, the bin directory will contain:

jacl, the text-only console version of the game interpreter.
cgijacl, the all-in-one game interpreter and web server.
fcgi_jacl, the game interpreter compiled with FastCGI for use with an appropriately configured webserver such as Apache and mod_fastcgi. See below for details on Using JACL with FastCGI and Apache
build-media-file, an awk script for generating .media files from game files. See the section on HTML and HTTP for more information.

In the games directory you will find several JACL games. A JACL game consists of one or more .jacl files and an optional .media file that maps resource URLs accessed from within your games to the corresponding files. If a JACL game consists of more than one .jacl file, the other file will be one of the library files from the include directory.

Inside the games directory you will also find a temp directory. This is the directory where the interpreter will create the .processed files and game state files. A .processed file is a concatenation of a main game file and all other files included from that file. They are created by the interpreter when the game is first run.
Under Unix, the user the JACL interpreter is run as must have write permissions to the temp directory.

The include directory is found inside the games directory. In the include directory you will find the follow files: verbs.library, the main interactive fiction library; frame.jacl, a skeleton program used as a starting point when writing a new piece of interactive fiction.

In the guide directory you will find this documentation.

In the quizzes directory you will find a small Perl script and several template JACL files for generating a quiz program from a list of questions and answers, along with a sample quiz. See the README file in that directory for more information.

Configuration

In the etc directory you will find the files jacl.conf, used by the jacl interpreter, and cgijacl.conf, used by the cgijacl and fcgijacl interpreters. These are the main configuration files for the interpreters and allow you to override several default settings. In a configuration file, any text between a hash (#) or a semicolon (;) and the end of the line is considered a comment. As the jacl interpreter is configured differently to the cgijacl and fcgijacl interpreters we will look at the two separately.

jacl

When the jacl interpreter starts it will first look for its configuration file in the current directory. If this does not exist it will look for it in the etc directory that is at the same level as the games directory. In other words, from the directory the game file being run is in, it will look for ../etc/jacl.conf. If no configuration file is found there either, default values will be used.

The configuration file for jacl may contain any of the following lines:
Directive Description Default
columns Integer Sets the screen width to be used for word wrapping 79
lines Integer Sets the screen depth to be used for displaying [MORE] prompts. 23
include Directory This indicates the directory to look in to find any file specified in a #include preprocessor directive. A directory called include beneath the directory the game file is stored in. If an included file is not found in this directory, the directory the game file is stored in is searched.
temp Directory This indicates the directory to store the processed version of the game file. A directory called temp beneath the directory the game file is stored in. If this directory does not exist, the .processed file will be created in the same directory as the game file.
notify This indicates that notification should given of any score increase with a message such as:
[YOUR SCORE JUST WENT UP BY 10 POINTS]
Score notification is turned off.
debug Displays a message indicating the name of each function as it is executed and returned to. Debugging mode is turned off.
echo Echos the last command typed to the screen. This is useful when performing testing by piping a series of commands from a file to the interpreter. Command echo is turned off.
noansi Prevents ANSI escape codes from being used to control screen display. Answer codes are used.
nospaced Prevents a blank line from being displayed between each item description. Blank lines are displayed.
nostatus Prevents the status line from being displayed at the top of the screen. The status line is also disabled if the noansi directive is present. The status line is displayed.
nodelay Prevents the delay option being activated from code within a game. The delay option can be activated by game code.

Directive	Description	Default
columns Integer	Sets the screen width to be used for word wrapping	79
lines Integer	Sets the screen depth to be used for displaying [MORE] prompts.	23
include Directory	This indicates the directory to look in to find any file specified in a #include preprocessor directive.	A directory called include beneath the directory the game file is stored in. If an included file is not found in this directory, the directory the game file is stored in is searched.
temp Directory	This indicates the directory to store the processed version of the game file.	A directory called temp beneath the directory the game file is stored in. If this directory does not exist, the .processed file will be created in the same directory as the game file.
notify	This indicates that notification should given of any score increase with a message such as: [YOUR SCORE JUST WENT UP BY 10 POINTS]	Score notification is turned off.
debug	Displays a message indicating the name of each function as it is executed and returned to.	Debugging mode is turned off.
echo	Echos the last command typed to the screen. This is useful when performing testing by piping a series of commands from a file to the interpreter.	Command echo is turned off.
noansi	Prevents ANSI escape codes from being used to control screen display.	Answer codes are used.
nospaced	Prevents a blank line from being displayed between each item description.	Blank lines are displayed.
nostatus	Prevents the status line from being displayed at the top of the screen. The status line is also disabled if the noansi directive is present.	The status line is displayed.
nodelay	Prevents the delay option being activated from code within a game.	The delay option can be activated by game code.

Below is an example jacl configuration file:

# "jacl.conf"
# JACL interpreter configuration file.

temp           "/usr/local/jacl-1.13/game/temp/"
include        "/usr/local/jacl-1.13/games/include/" 
notify
#noansi
#debug
#nostatus
#nospaced
#echo

cgijacl and fcgijacl

When the cgijacl and fcgijacl interpreters start they will first look for their configuration file in the current directory. If this does not exist they will look for it in the etc directory that is at the same level as the games directory. In other words, from the directory the game file being run is in, the jacl interpreter will look for ../etc/cgijacl.conf. If neither of these files is found, the cgijacl or fcgijacl interpreters will also look for the file /etc/cgijacl.conf.

The configuration files for cgijacl and fcgijacl may contain any of the following lines:
Directive Description Default
access_log FileName This indicates the file that should be used to log all moves made while playing. If a directory is specified with the trailing forward slash, the file name jacl_access.log is appended to the supplied directory. ../log/jacl_access.log (from the location of the game file)
error_log FileName This indicates the file that should be used to log all errors that occur while JACL programs are running. If a directory is specified with the trailing forward slash, the file name jacl_error.log is appended to the supplied directory. ../log/jacl_error.log (from the location of the game file)
include Directory This indicates the directory to look in to find any file specified in a #include preprocessor directive. A directory called include beneath the directory the game file is stored in. If an included file is not found in this directory, the directory the game file is stored in is searched.
temp Directory This indicates the directory to store the processed version of the game file. A directory called temp beneath the directory the game file is stored in. If this directory does not exist, the .processed file will be created in the same directory as the game file.
notify This indicates that notification should be given of any score increase with a message such as:
[YOUR SCORE JUST WENT UP BY 10 POINTS]
Score notification is turned off.
debug Logs a message to jacl_error.log indicating the name of each function as it is executed and returned to. Debugging mode is turned off.

Directive	Description	Default
access_log FileName	This indicates the file that should be used to log all moves made while playing. If a directory is specified with the trailing forward slash, the file name jacl_access.log is appended to the supplied directory.	../log/jacl_access.log (from the location of the game file)
error_log FileName	This indicates the file that should be used to log all errors that occur while JACL programs are running. If a directory is specified with the trailing forward slash, the file name jacl_error.log is appended to the supplied directory.	../log/jacl_error.log (from the location of the game file)
include Directory	This indicates the directory to look in to find any file specified in a #include preprocessor directive.	A directory called include beneath the directory the game file is stored in. If an included file is not found in this directory, the directory the game file is stored in is searched.
temp Directory	This indicates the directory to store the processed version of the game file.	A directory called temp beneath the directory the game file is stored in. If this directory does not exist, the .processed file will be created in the same directory as the game file.
notify	This indicates that notification should be given of any score increase with a message such as: [YOUR SCORE JUST WENT UP BY 10 POINTS]	Score notification is turned off.
debug	Logs a message to jacl_error.log indicating the name of each function as it is executed and returned to.	Debugging mode is turned off.

Below is an example cgijacl configuration file:

# "cgijacl.conf"
# CGIJACL interpreter configuration file.

error_log      "/usr/local/jacl-1.13/log/"
access_log     "/usr/local/jacl-1.13/log/access.log" 
temp           "/var/tmp/"
notify
#include       "/usr/local/jacl-1.13/games/include/"
#debug

Playing the Sample Games

Once you have compiled the JACL intrepreters, try running one of the provided games by changing to the bin directory and typing the command:

./cgijacl ../games/blackjack.jacl

This command will start the JACL interpreter on the default port of 8080, resulting in the following output:

JACL Interpreter v1.13.0
WebJACL: Registered 8 media.
WebJACL: No port number specified (-p ), using default port 8080.
WebJACL server configured on WOPR:8080

To play this game, open your favourite web browser and navigate to the URL http://localhost:8080. When you do so, you should see something like the screen below. If not, see the section on Trouble Shooting.

To play this same game from the console, try the following command from the bin directory:

./jacl ../games/blackjack.jacl

Using JACL with FastCGI and Apache

While the cgijacl interpreter is able to respond to HTTP requests internally, the fcgijacl interpreter is designed to be used with a FastCGI-enabled webserver such as Apache. The cgijacl interpreter is very easy to use and is ideal for developing a new game or allowing a small number of users to play your completed games. The fcgijacl interpreter, when used with a production-quality web server such as Apache, is probably better choice for situations where a high level of traffic is expected.

Before the fcgijacl 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 respective documentation. mod_fastcgi is available from http://freshmeat.net/projects/mod_fastcgi or as the Debian package:

libapache2-mod-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.

Once mod_fastcgi is installed, Apache requires a file called fastcgi.load in your mods-enabled directory that contains the line:

LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so

To configure FastCGI, you must edit the file fastcgi.conf in your mods-enabled directory to read:

<IfModule mod_fastcgi.c>
  AddHandler fastcgi-script .fcgi

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

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

  FastCgiIpcDir /var/lib/apache2/fastcgi
</IfModule>

This configuration creates a script alias of /fastcgi-bin that points to the directory /usr/local/fastcgi-bin. This directory must be created so that the user that the Apache server runs as has read and execute premissions to it. A script alias is a way of mapping URLs to directories on your file system. The above script alias says that any resource being accessed using a URL starting with /fastcgi-bin should be looked for in the directory /usr/local/fastcgi-bin.

The location 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. You may alternatively wish to set a script alias like /fastcgi-jacl to point to the directory /usr/local/jacl-1.13/games/ or wherever your JACL games reside.

The images directory beneath the games directory of your JACL distribution will need to be copied to the Apache document root. The sample games are designed to read the images from /images when played with fcgijacl. It is necessary to load images from somewhere beneath the document root as Apache attempts to run any resource accessed from beneath /fastcgi-bin as a FastCGI script, which the images are not.

Next, the file cgijacl.conf must be moved from jacl-1.13/etc to /etc. This file contains several configuration details, the most imortant directive for fcgijacl is temp. This specifies the directory that all persistant data will be written to. By default this is specified in cgijacl.conf as /usr/local/jacl-1.13/games/temp. It is important to ensure that the user the Apache server runs as has read and write permissions to whichever directory you specify by using a command such as:

chmod 777 /usr/local/jacl-1.13/games/temp

Regardless of where you locate your JACL games, you will need to edit the first line of each game to point to the fcgijacl interpreter. For example:

#!/usr/local/jacl-1.13/bin/fcgijacl

The below line will appear in the Apache error log if the first line of the game points to the interpreter in the wrong location. The line can be misleading as it is not the file grail.jacl that cannot be found but the interpreter binary it is attempting to run itself using.

FastCGI: can't start server "/usr/local/fastcgi-bin/grail.jacl" (pid 2539), exec
le() failed: No such file or directory

Once you have finished configuring JACL and Apache, start Apache and open the following URL from your browser: http://localhost/fastcgi-bin/tutorial.jacl. If all has gone well, you should see the title page for this game. If not, try looking in Apache's error_log and /usr/local/jacl-1.13/log/jacl_error.log.