The InfoTaskForce Infocom Interpreter Compilation Guide
=======================================================
Copyright (c) 1992 InfoTaskForce


System-specific Compilation
---------------------------

The makefile distributed with the interpreter sources contains entries 
for the following compilers:

turboc		Compile the interpreter using either Turbo C, Turbo C++ 
		or Borland C++ on an IBM PC or compatable computer.

qc		Compile the interpreter using Microsoft C on an IBM PC 
		or compatable computer. This version excludes all 
		optimisation and invokes the "quick compile" option.

msc		Compile the interpreter using Microsoft C on an IBM PC 
		or compatable computer. This version invokes full 
		optimisation.

bsd_ansi	Compile the interpreter using the native C compiler on a 
		computer running BSD UNIX. This version uses ANSI 
		escape sequences to format screen output.

bsd_ansic	Compile the interpreter using the native C compiler on a 
		computer running BSD UNIX. This version uses ANSI 
		escape sequences to format screen output and for colour.

bsd_curses	Compile the interpreter using the native C compiler on a 
		computer running BSD UNIX. This version uses the UNIX 
		CURSES package to format screen output.

bsd		Compile the interpreter using the native C compiler on a 
		computer running BSD UNIX. This version uses the UNIX 
		TERMCAP package to format screen output.

sysv_ansi	Compile the interpreter using the native C compiler on a 
		computer running UNIX System V. This version uses ANSI 
		escape sequences to format screen output.

sysv_ansic	Compile the interpreter using the native C compiler on a 
		computer running UNIX System V. This version uses ANSI 
		escape sequences to format screen output and for colour.

sysv_curses	Compile the interpreter using the native C compiler on a 
		computer running UNIX System V. This version uses the 
		UNIX CURSES package to format screen output.

sysv_cursesc	Compile the interpreter using the native C compiler on a 
		computer running UNIX System V. This version uses the 
		UNIX CURSES package to format screen output and for colour.

sysv_termcap	Compile the interpreter using the native C compiler on a 
		computer running UNIX System V. This version uses the 
		UNIX TERMCAP package to format screen output.

sysv		Compile the interpreter using the native C compiler on a 
		computer running UNIX System V. This version uses the 
		UNIX TERMINFO package to format screen output.

Note that if the CURSES, TERMCAP or TERMINFO options are used, the terminal 
database on your system MUST contain the correct sequences for your 
terminal if the interpreter is to operate correctly. We have found many 
TERMCAP databases to be inaccurate or incomplete on many UNIX 
systems.



User-defined Compilation
------------------------

If none of the above options suit your system, you can roll your own 
makefile entry. The interpreter sources currently recognise the 
following compile time options (all in UPPERCASE) which can be 
invoked using the -D<macro> option of most C compilers. See the 
distribution makefile for examples of how they can be used.

ANSI_ESCAPE	Compile a version that uses ANSI ESCAPE 
		sequences for terminal output.

ANSI_COLOR	Compile a version that uses ANSI ESCAPE 
		sequences for coloured terminal output.

BSD		Compile on a BSD UNIX machine. (This also defines 
		"UNIX")

CHEAT		Include the routines for spying on Object movement.

CURSES		Compile a version that uses curses features for terminal 
		output. You may also have to include a curses library as 
		well.

CURSES_COLOR	Compile a version that uses curses features including colours
		for terminal output. You may also have to include a curses
		library as well. This only works for some SYSV versions of
		curses.

DEBUG		Compile a debug version of the interpreter. Compare 
		output produced with this option against a working debug 
		version when you suspect problems in the virtual machine 
		[this commonly produces error 21].

LSC		Compile on a Macintosh using LightSpeed C Version 2.01.

MSC		Compile on an MS-DOS machine using Microsoft C.

MSDOS		Compile on an MS-DOS machine.

SYS_V		Compile on a UNIX System V machine. (This also defines 
		"UNIX")

TERMCAP		Compile a version that uses termcap features for terminal 
		output. You may also have to include a termcap library as 
		well.

TERMINFO	Compile a version that uses terminfo features for terminal 
		output. You may also have to include a terminfo library as 
		well.

THINKC		Compile on a Macintosh using THINK C Version 4.0.

TURBOC		Compile on an MS-DOS machine using Borland C or Turbo C.

UNIX		Compile on a UNIX machine.



Advanced user-specified Compilation
-----------------------------------

If none of the above options suit your system's setup, the interpreter 
can be customised as described in this section.

The interpreter has been deliberately written in a way that makes 
it easy to customise to a particular operating environment. There are 
only three files which make assumptions about the compiler through 
which these sources are run.

Firstly, the file infocom.h makes the following assumptions:

*	A variable of type char occupies exactly one byte.
*	A variable of type short occupies exactly two bytes.
*	A variable of type long occupies exactly four bytes.
*	The compiler supports the signed and unsigned qualifiers for 
	each of the above types.
*	Unsigned char elements of structures are aligned on byte 
	boundaries ( not on word or long word boundaries ).

If any of these assumptions are false, the infocom.h file may 
require modification to the type definitions of "byte", "word", 
"longword", "object" and "header". We do not anticipate that such 
modifications will be required to this file.

The other two files are machine.h and io.c - these files contain 
all the interface macros and functions required by the C compiler. 
These are the only two files (apart from perhaps the makefile) which 
should be modified by the user.

The interpreter performs all interface functions via macros which 
are defined in machine.h. Depending on which machine the interpreter 
is being compiled for, these macros contain the name of a machine 
specific routine in io.c to perform that task for a given environment. 
For example, the interpreter performs all printing to stdout using the 
PUT_CHAR () macro. If we then compile the interpreter for Microsoft C 
on a PC, the makefile #defines MSC which, in turn #defines PUT_CHAR 
to the msc_putchar routine in io.c. On the otherhand, if we compile for 
Turbo C on the PC, the makefile #defines TURBOC which, in turn 
#defines PUT_CHAR to the tc_putchar routine in io.c.

The following is a list of the compiler customisation variables 
defined in machine.h:

INTERPRETER	Interpreter Number - indicates the type of the target 
		machine. By default, this is set to APPLE_2E. See 
		infocom.h for other possibilities, although it doesn't 
		make much difference (except in Beyond Zork, where 
		this value is used to determine whether or not an 
		alternative graphics character set is avaliable for 
		drawing the map - the APPLE_2E has no such 
		character set).

MODE_BITS	The bits to set in the "mode_bits" byte of the game 
		file header to indicate target system capabilities. If 
		underlining is available, this should be set to 
		UNDERLINE, otherwise it should be set to 0.

SCREEN_WIDTH	Default number of Characters per Screen Line. This 
		is used if the screen line width cannot be determined 
		dynamically at run time.

SCREEN_HEIGHT	Default number of Screen Lines. This is used if the 
		number of screen lines cannot be determined 
		dynamically at run time.

READ_STRING	String used by fopen to open a file in read binary 
		mode - usually "r" or "rb".

WRITE_STRING	String used by fopen to open a file in write binary 
		mode - usually "w" or "wb".

APPEND_STRING	String used by fopen to open a file in append text 
		mode - usually "a".

Void		Defines the "void" type. If a pre-ANSI compiler is 
		being used which does not know about the void type, 
		use the int type instead.

HUGE		Used in the type definition of pointers. This is 
		included for MSDOS and other Intel 80x86 C Compilers 
		with segment based memory models. Omit it for 
		"normal" machines.

MALLOC(s)	Macro to invoke the memory allocation routine. Note 
		that this macro may be used to allocate more than 64 
		Kbytes of memory and hence takes an unsigned long 
		as an arguement and returns a pointer to the 
		allocated block of memory. For example, in UNIX,

			#define	MALLOC(s)	malloc(s)

		See machine.h for more complex examples. If your 
		compiler only has a malloc routine which takes an 
		unsigned int as an argument, this macro should 
		contain the name of your own malloc function which 
		should be placed in io.c - care must be taken if you 
		write your own malloc since the interpreter assumes 
		that the memory block it asks for is contiguous, so if 
		you allocate a number of smaller blocks to get a 
		larger one you MUST check that all the blocks are 
		contiguous, otherwise malloc should fail with a null 
		pointer.

FREE(p)		Macro to invoke the memory deallocation routine, 
		where "p" is the pointer returned by the MALLOC(s) 
		macro. This macro returns a void. For example,

			#define	FREE(p)	free((void *)p)

main		Name of the initial C procedure (LSC only - omit it 
		for all other machines).

TIME_FUNCTION	Macro to invoke the standard library time function 
		which is used to seed the random number generator. 
		This macro itself takes no arguements and assumes 
		that the returned value is a long. Thus if your 
		standard time function requires arguements, these 
		must also be included in the macro. For example,

			#define	TIME_FUNCTION	time((long *)0)

		If such a function is not available, the following will 
		suffice:
			#define	TIME_FUNCTION	-1L

ONE_SECOND	The value used by "TIME_FUNCTION" to indicate the 
		passing of one second of real time.

INIT_SIGNAL	Routine to perform any special initialisation for signal 
		trapping routines.

SIGNAL_QUIT	Routine to perform any signal cleanup and/or 
		handling. An integer is passed to this routine to 
		specify  the action required.

INIT_IO		Routine to perform any special initialisation for the 
		I/O routines.

EXIT_IO		Routine to restore any I/O modes when the program 
		exits.

PUT_CHAR	Routine to send a character to "stdout".

GOTO_XY		Routine to move the cursor to a given screen 
		position.

GET_X		Routine to get the cursor's x-coordinate.

GET_Y		Routine to get the cursor's y-coordinate.

USE_WINDOW	Routine used to set a screen window's scroll region.

GET_CH		Routine to get a character from "stdin" without echo.

KBD_HIT		Routine to detect whether there is a character 
		waiting to be read from "stdin".

ERASE_TO_EOLN	Routine to Erase the current Screen Line.

ERASE_WINDOW	Routine to Erase several consecutive Screen Lines.

SAVE_CURSOR	Routine to Save the Current Cursor Position.

RESTORE_CURSOR	Routine to Restore the Current Cursor Position.

RCFILE		String containing name of initialization file.


In summary, to install a custom set of interface routines, insert 
something like the following into machine.h:

#ifdef	MY_OPERATING_SYSTEM

#include	<my.h>

#define	INTERPRETER	APPLE_2E
#define	MODE_BITS	UNDERLINE
#define	SCREEN_WIDTH	80
#define	SCREEN_HEIGHT	24
#define	READ_STRING	"rb"
#define	WRITE_STRING	"wb"
#define	APPEND_STRING	"a"

#define	TIME_FUNCTION	my_time((long *)0)
#define	ONE_SECOND	1
#define	INIT_SIGNAL	my_signal_init
#define	SIGNAL_QUIT	my_signal_quit

extern int	my_get_x () ;
extern int	my_get_y () ;

#define	Void		void
#define	HUGE
#define	MALLOC(s)	malloc(s)
#define	FREE(p)		free((void *)p)

#define	INIT_IO		my_init_io
#define	EXIT_IO		my_exit_io
#define	PUT_CHAR	my_putchar
#define	GOTO_XY		my_goto_xy
#define	GET_X		my_get_x
#define	GET_Y		my_get_y
#define	USE_WINDOW	my_use_window
#define	GET_CH		my_getch
#define	KBD_HIT		my_kbd_hit
#define	ERASE_TO_EOLN	my_erase_to_eoln
#define	ERASE_WINDOW	my_erase_window
#define	SAVE_CURSOR	my_save_cursor
#define	RESTORE_CURSOR	my_restore_cursor
#define	RCFILE		"infocom.rc"

#endif	/* MY_OPERATING_SYSTEM */

With a corresponding entries in io.c:

#ifdef	MY_OPERATING_SYSTEM

/*
**	My Signal Trapping Routine.
*/

Void
my_signal_init ( sig_action )
int		sig_action ;
{
	/*
	**	Initialise signals ...
	*/
}

Void
my_signal_quit ( sig_action )
int		sig_action ;
{
	switch ( sig_action )
	{
		case SOMETHING:
		default:
			/*
			**	Handle signal ...
			*/
	}
}

/*
**	My I/O Routines.
*/

Void
my_init_io ()
{
	extern int	screen_height ;
		
	/*
	**	Initialise my I/O variables ...
	*/

	GOTO_XY ( 0,screen_height - 1 ) ;
}

Void
my_exit_io ()
{
	/*
	**	Clean up the I/O before quitting ...
	*/
}

Void
my_putchar ( c )
char	c ;
{
	extern boolean	enable_screen ;

	switch ( c )
	{
		case 1:
			/*
			**	Set Normal Text Mode.
			*/

			break ;
		case 2:
			/*
			**	Set Inverse Text Mode.
			*/

			break ;
		case 3:
			/*
			**	Set Bold Text Mode.
			*/

			break ;
		case 4:
			/*
			**	Unused.
			*/

			break ;
		case 5:
			/*
			**	Set Underline Text Mode.
			*/

			break ;
		case 0:
			c = ' ' ;

			/*
			**	Fall Through ...
			*/

		default:
			if ( enable_screen )
				putchar ( c ) ;
			break ;
	}
}

Void
my_goto_xy ( x,y )
int		x,y ;
{
	/*
	**	Move the cursor to (x,y) ...
	**	The top-left corner of the screen has coordinates (0,0).
	*/
}

int
my_get_x ()
{
	/*
	**	The left-most character position is position 0.
	*/

	return ( cursor's_current_x_position ) ;
}

int
my_get_y ()
{
	/*
	**	The top screen line is 0.
	*/

	return ( cursor's_current_y_position ) ;
}

/*
**	The Enhanced Windowing Default I/O Functions.
*/

Void
my_use_window ( the_window )
word	the_window ;
{
	switch ( the_window )
	{
		case WINDOW_0:
			/*
			** Use the Lower Window ...
			*/

			break ;
		case WINDOW_1:
			/*
			** Use the Upper Window ...
			*/

			break ;
		case FULL_SCREEN:
			/*
			** Use the entire screen ...
			*/

			break ;
	}
}

Void
my_erase_window ( top_of_window,bottom_of_window )
word	top_of_window ;
word	bottom_of_window ;
{
	extern int		screen_width ;
	extern word		top_screen_line ;

	/*
	**	Erase Screen from the line specified by "top_of_window"
	**	to the line ABOVE that specified by "bottom_of_window".
	**	Leave Cursor at the top, left-hand corner of the erased window.
	**	The top screen line is line 0.
	*/

	word	i ;

	for ( i = bottom_of_window ; i > top_of_window ; i-- )
	{
		GOTO_XY ( 0,i-1 ) ;
		my_erase_to_eoln () ;
	}
}

int		saved_cursor_x ;
int		saved_cursor_y ;

Void
my_save_cursor ()
{
	extern int	saved_cursor_x ;
	extern int	saved_cursor_y ;

	saved_cursor_x = GET_X () ;
	saved_cursor_y = GET_Y () ;
}

Void
my_restore_cursor ()
{
	extern int	saved_cursor_x ;
	extern int	saved_cursor_y ;

	GOTO_XY ( saved_cursor_x,saved_cursor_y ) ;
}

/*
**	The PLUS Series Default I/O Functions.
*/

Void
my_erase_to_eoln ()
{
	/*
	**	The characters at the cursor and to the right are erased.
	**	The cursor itself is not moved.
	*/

	extern int	screen_width ;
	int			saved_x_posn ;
	int			saved_y_posn ;
	int			i ;

	saved_x_posn = GET_X () ;
	saved_y_posn = GET_Y () ;
	for ( i = saved_x_posn ; i < screen_width ; i++ )
		out_char ( ' ' ) ;
	GOTO_XY ( saved_x_posn,saved_y_posn ) ;
}

int
my_kbd_hit ()
{
	if ( a_key_is_being_pressed )
		return ( TRUE ) ;
	else
		return ( FALSE ) ;
}

int
my_getch ()
{
	if ( a_key_is_being_pressed )
		return ( the_ascii_value_of_the_key ) ;
	else
		return ( EOF ) ;
}

#endif	/* MY_OPERATING_SYSTEM */


Notes.
------

MS-DOS

The object room tree option uses recursive code, and hence is stack-intensive.
If compiling for MS-DOS then the memory allocated for stack must be increased
to 8k or more (the standard stack of 2K is adequate for normal game execution
and all other options).

Termcap

We have found that TERMCAP emulation on many TERMINFO systems is seriously
deficient, escape sequences that are supported in TERMINFO simply are
not supported for TERMCAP. When compiling for a TERMINFO system use the
TERMINFO option rather than TERMCAP. The TERMCAP option does actually seems
to work OK if all required terminal features are available. And finally, if
you are compiling for MS-DOS then Microsoft C will produce a slightly more
functional executable than Borland C (video paging has not been implemented
for Borland C).