FORTH(??) UNKNOWN SECTION OF THE MANUAL FORTH(??) NAME forth - Forth interpreter/compiler forth - Forth dynamic loader files.exe - Binary for Unix version of forth stand.exe - Binary for Standalone version of forth SYNOPSIS forth [ binary-file ] [ -v ] [ file ] [ - ] [ -s 'string of forth commands' ] ... DESCRIPTION _F_o_r_t_h is the Sun Forth interpreter/compiler which executes programs in the Forth language. Forth is an interactive programming language with a stack-oriented, reverse-polish syntax. It is extensible; programs are written by defining new subroutines ("words" in Forth jargon) which have equal status with system-supplied words. Words must be defined in terms of already-existing words. As a word is defined, it is incrementally compiled and added to the Forth system. A Forth word is executed simply by typing its name. The Sun Forth implementation allows new words to be compiled either from the keyboard or from Unix files. The command line optionally specifies the name of the forth binary file (which must have a ".exe" suffix) to start with, and a list of other files to compile. If no ".exe" file is specified, a default file is used. The default file is named _f_i_l_e_s._e_x_e. The environment variable FPATH is consulted to find a list of directories in which to look for _f_i_l_e_s._e_x_e. /_u_s_r/_l_o_c_a_l/_l_i_b/_f_o_r_t_h/_f_i_l_e_s._e_x_e is the forth binary file which contains the Forth-83 Standard words and a lot of utilities, including a "Standard I/O"-like interface to the Unix file system. Once the desired files have been com- piled, the system can (but does not have to) take further input from the keyboard. At any time, a binary image of the state of the forth system may be saved. This new image (".exe" file) may be later used as the starting binary file for further invocations of forth. The program /_u_s_r/_l_o_c_a_l/_f_o_r_t_h is really just a dynamic loader for the Forth environment. It serves two purposes: 1) to provide the forth binary code with access to Unix system calls and library routines 2) to concatenate the list of files which serve as the input stream to the forth system. Stand-alone programs are compiled under Unix. The forth system then writes out an "a.out" format file that can be booted to run stand-alone. The stand-alone program runs in supervisor state and has access to all the hardware resources of the Sun Workstation. When compiling a stand- alone program, the binary file _s_t_a_n_d._e_x_e is used as a start- ing point instead of _f_o_r_t_h._e_x_e. _S_t_a_n_d._e_x_e includes Sun Release 3.0B Last change: 11 April 1985 1 FORTH(??) UNKNOWN SECTION OF THE MANUAL FORTH(??) precompiled words to access the hardware and to do console I/O via the Sun ROM monitor. The forth word which writes a stand-alone "a.out" format image is _s_a_v_e-_s_t_a_n_d. While _s_t_a_n_d._e_x_e is compiling the stand-alone program, it does its I/O using the normal Unix facilities. The ROM mon- itor routines are not used until the "a.out" format image is booted stand-alone. When the system is running stand-alone, the interactive features are still available. The system may be further extended by typing in new forth words from the keyboard. There are several hundred Forth words in this system, com- parable to the number of library routines available to a C program. Thus it is impractical to list them all in this manual page. The SEE ALSO section lists references which describe the Forth language and the various libraries of Forth words available in the Sun Forth implementation. OPTIONS The following options are interpreted by _f_o_r_t_h. -v Verbose: causes forth to print the name of each file as it is being compiled by the forth system. This is useful in debugging if a large list of files is being used. It helps locate the file in which a compilation error occurred. -s 'string of forth commands' When this option is encountered, the next command line argument is passed directly to the forth system as a command to execute. Unless the string consists of a single word, it must be quoted. This is usu- ally used in makefiles to tell the forth system to write out an image of itself. The argument to -s needs to be quoted unless it consists of a single Forth word. A typical use is -s '"" test.exe save-forth' which would case a file "test.exe" to be written. - Whenever a minus sign by itself is encountered, input is taken from the standard input. This may occur more than once in the command list. If no files are specified, the standard input is automati- cally used. ENVIRONMENT The environment variable FPATH is used to determine this list of directories to search for the forth binary image. It is also used within Forth to determine which directories to search during a PATH-OPEN , PATH-LOAD , or REQUIRES com- mand. Sun Release 3.0B Last change: 11 April 1985 2 FORTH(??) UNKNOWN SECTION OF THE MANUAL FORTH(??) Here is how you might want to set FPATH from inside a .login file: setenv FPATH .:$HOME/forth:/usr/local/lib/forth This specifies that the current directory is to be searched first, followed by the users private forth directory, fol- lowed by the system forth library. EXAMPLES To start the standard forth system interactively: forth To start the forth system, and compile a stand-alone diag- nostic from the file "test.f", saving a stand-alone bootable file in stand.test, and copying the result to a server called venus, from where it may be booted over the ethernet: forth stand.exe test.f -s' " stand.test" save-stand' rcp stand.test venus:/pub/stand FILES files.exe forth binary image /usr/local/lib/forth/files.exe The usual forth image for Unix /usr/local/lib/forth/stand.exe The image for compiling stand-alone programs. /usr/local/forth The dynamic loader /usr/local/lib/forth/* Library packages SEE ALSO FORTH Tutorial (in forth/doc/tutorial.doc) Roll Your Own (Hardware Diagnostics, That Is) (in forth/doc/intro.doc) Mastering Forth, by Martin Tracy and Anita Anderson Starting Forth, by Leo Brodie net.lang.forth on the Usenet is read by many knowledgeable Forth enthusiasts, so it is a good source of information. forth/doc contains many documentation files describing vari- ous aspect of the Sun Forth system. DIAGNOSTICS If the forth interpreter encounters a word that hasn't been defined yet, it will print the name of the word followed by a question mark and the name of the last word that was com- piled. The compilation will then proceed, so you will get a Sun Release 3.0B Last change: 11 April 1985 3 FORTH(??) UNKNOWN SECTION OF THE MANUAL FORTH(??) fairly-complete list of all such errors. BUGS Sometimes the system will core dump after it has found a whole lot of of undefined words. This isn't too bad, since you have to fix the undefined problems anyway before your program will work, but it would be nicer if it didn't core dump. It is possible to crash the Forth system from the keyboard, causing a core dump. This is because the system does not try very hard to protect you from yourself. One easy way to crash the system is to store random stuff into addresses below HERE.n This does not cause Unix to crash; it usually just causes the Forth process to go away. It is usually pos- sible to restart a crashed stand-alone forth system from the ROM monitor by typing >g10004 The documentation should be better organized. It is currently somewhat fragmented, in keeping with the Unix tradition. Sun Release 3.0B Last change: 11 April 1985 4