
	T3X README


	1)  README

	####################             *         T is a compiler for a
	#             %%%%%%%%%% *      *    minimum procedural language
	########   #########%%%   *    *     called T. T3X is a compiler
	       #   #      %%%      *  *    for a superset of T version 3
	       #   #     %%%        **                    (T3 eXtended).
	       #   #       %%%%     **
	       #   #          %%   *  *
	       #   #          %%  *    *                   Copyright (C)
	       #####  %%%   %%%  *      *                      1996-2000
	                %%%%%            *                   Nils M Holm


	2)  U R L

	The latest version of the T3X compiler can be found at

		http://www.t3x.org/
	or
		http://www.homepages.de/home/nmh/


	3)  SUMMARY

	T3X is a very basic procedural language. Its syntax is a cross
	between Pascal and BCPL, but it is smaller and simpler.
	Originally, T has been designed to provide a portable notation
	for algorithms, but meanwhile it has become a useful allround
	language.
	Unlike many popular languages like C++ and Java, it does not
	provide a very abstract and complex environment to achieve
	portability, but only a set of very basic operations and builtin
	routines which may be easily implemented on a variety of
	different platforms.
	T3X programs are very portable since their compiler is simple
	and easy to port. Algorithms in T are readable because the
	language is small and has clean syntactic and semantic rules.

	The T compilers are all written in T themselves. The source
	code of the complete T3X translator (the part which translates
	T3X into bytecode), for example, has a size of less than 1700
	lines where definitions of low-level procedures like copying
	and comparing strings are already included.


	4)  A T3X LANGUAGE SUMMARY

	o  Object types: (ordinal) Variables, Vectors, Byte
		vectors, Strings, packed Strings, Tables,
		Constants, Structures.

	o  Vectors are first class objects. The 'table' syntax
		is used to define -- even nested -- vector
		literals. 'Dynamic tables' allow the computation
		of table members at run time.

	o  Procedures have fixed numbers of arguments. Argument
		counts are checked in procedure calls. Variadic
		procedures may be implemented using dynamic
		tables.

	o  Procedure applications are call by value. Vectors
		and strings are passed by reference (by passing
		their addresses by value).

	o  There are no data types. Variables are machine word
		locations, Constants are values, Vectors are
		constant addresses, tables and strings are
		statically initialized vectors.

	o  A procedure-like interface to runtime engines and
		libraries is provided.

	o  Procedure pointers allow indirect calls.

	o  Conditional expressions and short-circuit boolean
		operators exist.

	o  Flow control statements include IF, IE/ELSE branches,
		and FOR and WHILE loops.

	o  Standard procedures for performing basic I/O operations
	   are provided.


	5)  T3X COMPILER FEATURES

	o  Platform independant bytecode (T->Tcode) compiler.

	o  Very simple and portable Tcode interpreter (in C).

	o  Portable Tcode optimizer for all platforms.

	o  A preprocessor in the style of CPP.

	o  Predefined includable routines for fully buffered I/O
		and dynamic memory menagement.

	o  A Tcode disassembler.

	o  A code generator generator for defining new backends.

	o  Native code generators (Tcode->386(GAS), Tcode->8086
		(TASM,MASM,S86), Tcode->C(generic)).

	o  Runtime libraries for DOS, FreeBSD, and Plan9.


	6)  SYSTEM REQUIREMENTS

	In any case, a C compiler for building the Tcode interpreter
	is required. The code is very simple and portable, so any
	Unix C compiler (either K&R or ANSI) should suffice.
	Nothing else is required to make the bytecode part of the
	compiler work. (Since R5-5, a DOS executable of the Tcode
	interpreter TXX is contained in the build/ directory.)

	There exist some sets of extension procedures, for example
	for controlling video terminals and drawing vector grapgics.
	These extensions are not portable.

	System		Terminal I/O	Graphics/Mouse
	------		------------	--------------
	FreeBSD		Yes		Yes (+)
	Plan9		n/a		Yes
	DOS,TCC		Yes		Yes (*)
	DOS,S86		Yes		No
	Generic		No		No

	+ Requires X11
	* Requires VGA

	Currently, native code generators exist for FreeBSD(GAS-386),
	Plan9(*C), and DOS(MASM,TASM,S86).

	In fact, the 386-version will work on many systems supporting
	the 386 version of GAS, the GNU assembler (DOS on 386 PCs,
	OS/2, Linux, ...).
	However, the graphics and TTY extensions probably will not
	work on unsupported systems.


	7)  CONTENTS OF THE T3X PACKAGE

	build/
		The build directory contains everything which is
		required to boostrap the compiler:

		o  A DOS EXE style binary of TXX.
		o  A Tcode image of the T3X->Tcode translator.
		o  A Makefile for building the initial code
			generator.
		o  A Driver for the bootstrapping compiler.

	compiler/
		This directory contains the source code to the
		following programs:

		o  txtrn, the T3X->Tcode translator.
		o  txopt[b], Tcode optimizers.
		o  txpp, a cpp-like preprocessor.
		o  txx, a Tcode runtime interpreter (C).
		o  ux, a Tcode disassembler.
		o  txinfo, a Tcode examination tool.

	doc/
		These documents are currently available.
		All documents are in HTML 3.2 format.

		o  T3X -- A Minimum Procedural Language
			(Programmer's Manual).
		o  The T3X Quick Reference.
		o  The Tcode Reference Manual.
		o  The Preprocessor Reference Manual.
		o  A manual describing the VIO and GRAPHICS
			extensions.

	etxx/
		The extended Tcode interpreter for FreeBSD, DOS,
		and Plan9 providing primitives for video terminal
		control and device-independent vector graphics.

		o  ETXX source code
		o  Include files with INTERFACE for the ETXX
		   routines.
		o  Full documentation in HTML 3.2.
		o  Example programs.

	examples/
		Some harmless example programs.

	inc/
		This directory contains some extensions which
		may be included via TXPP:

		o  Dynamic memory management.
		o  Fully buffered I/O streams.

	native/
		This directory contains the sources to the
		code generator generator and the definition files
		for the existing backends.
		Currently, these environments are supported:

		o  386-based Unix with GAS-i386. libc.a required.
		o  DOS-based systems with MASM/LINK, TASM/TLINK.
		o  DOS-based systems with S86 and SLD.
		o  Unix-based systems with S86 and SLD provide a
			cross development platform for DOS.

	s86kit/
		The source codes to the complete S86 (cross)
		development environment (in T3X). The tools
		contained in this archive may be used to create
		DOS executables on any system with native code
		support.


	8)  GETTING STARTED

	If you want to build and install the compiler, you should
	read the file INSTALL.DOC.

	After successful installation, just type `tx -h' to get
	a brief summary of the compiler options.

	The file doc/t3x-user.html contains the T3X manual.

	The file doc/t3x-ref.html contains the T3X quick reference.

	There are some simple examples in the examples/ directory.
	There are some more advanced examples in the compiler/
	directory. :-)

	A BNF description of the T3X language can be found in
	compiler/tx.bnf.

	If you want to write a new native code backend for T3X,
	check the 386 definition file cg386 in the native/
	directory and the document 'native/cgdesc.doc'.
	The Tcode reference manual in doc/ may be useful, too.


	9)  MODIFYING T3X

	Of course, you may modify any part of the T3X compiler to
	your hearts content. When distributing modified copies of
	T3X, however, please add a notice describing your changes
	and how to contact you. I will not answer questions about
	modified copies.
	The terms expressed in the file LICENSE also apply to
	modified copies of the T3X package.

	People who would like to port T3X to new platforms are
	welcome to do so. Please contact me before starting a
	port, because me or someone else may be working at it
	already.


	10) CONTACTING ME

	If you have bug reports, comments, suggestions, or if you
	should get *really stuck* while installing T3X, feel free
	to send me a message:

		nmh@t3x.org

	Or, if you do not have access to the Usenet/Internet:

		Nils M Holm
		Robert-Bosch-Str. 2
		69502 Hemsbach
		Germany

