APDL Public Domain 1

home *** CD-ROM | disk | FTP | other *** search

/ APDL Public Domain 1 / APDL_PD1A.iso / program / language / gofer / Sources / original / Readme < prev

Wrap

Text File | 1993-02-12 | 16.4 KB | 401 lines

------------------------------------------------------------------------------- This directory contains the source for Gofer 2.28, including both the interpreter and compiler. The following give brief instructions for installing the system from these sources. More detailed instructions for specific machines are given below. You will need a directory which is available to all Gofer users on your system to store prelude files etc. You can choose this to be whatever you like. I'll just call it $GOFLIB here. On Unix systems, I usually use /usr/local/lib/Gofer or a subdirectory of my home directory, Gofer/lib. On DOS systems, I suggest C:\GOFER\LIB. 1) Unpack the sources in a temporary directory. Copy all of the .prelude files (these will be .PRE files under DOS) to $GOFLIB. 2) Edit the file prelude.h to select a particular machine type. All but one of the machine names should be #define'd as 0. Set the #define for the machine on which you wish to compile Gofer to 1. If appropriate, edit the Makefile as necessary to suit your system. If you plan to install the Gofer compiler, edit the file cmachine.c so that the symbol GOFC_INCLUDE is set to a string containing the pathname $GOFLIB/gofc.h -- you will see that my two suggested settings are already set as defaults. Specific details for particular machine/configurations are given below. 3) Build the system (on a Unix system, this usually means just typing `make' and going to get a cup of something to drink ...) If you modify parser.y, you will need a version of yacc to create a suitable new version of parser.c. I've had reports that the Gofer grammar doesn't work correctly if you use either GNU bison or Berkeley Yacc (both have a common ancestor so it's not too surprising). If you have any doubts, make sure that you use the parser.c file supplied with the source rather than letting a local version of yacc create a new one for you. The easiest way to do this is probably to edit the makefile to leave out the construction of parser.c. 4) If you are going to use the Gofer compiler: Assuming a successful build, copy the files prelude.h and gofc.h to $GOFLIB and edit the file gofc.h, replacing #include "prelude.h" with something like #include "$GOFLIB/prelude.h" -- don't actually enter the string "$GOFLIB/prelude" here, you're meant to replace $GOFLIB by whatever directory name you chose at the beginning of this process. You will also need to copy the file runtime.o (or runtime.obj, depending on your system) into $GOFLIB. 5) You're all set. In practice, you'll want to move the gofer and gofc binaries to somewhere sensible (probably into $GOFLIB on a unix system, modifying the scripts in the scripts subdirectory to point to the appropriate executables and prelude files). And you may want to clean off any remaining object code files too ... I've probably left something out here. Please let me know if you have any trouble or spot anything that I've left out. --------------------- GNU READLINE (or equivalent) Gofer can be compiled to make use of the GNU readline library. I tried this using the readline library provided by GNU bash 1.12, although I've found that, for my simple purposes, the editline library posted in alt.sources works as well, and is a fraction of the size. See the Makefile for more details. --------------------- TURBO C version 1.5 on a PC with MSDOS: Set #define TURBOC 1 and the rest to 0 in prelude.h. Use the supplied project files gofer.prj and gofc.prj to generate the interpreter and compiler respectively. Before starting the compilation, make sure that you set the following command line options (all of this is intended to be carried out from within the IDE): Medium model, stack check ON, Merge duplicate strings, Jump optimization ON, Possibly incorrect assignment warning off. Select project gofer.prj and make. Select project gofc.prj and make. In order to make the runtime library and use the compiler, I suggest creating a batch file GTCC.BAT containing: tcc -O -ms -IC:\TURBOC\INCLUDE -LC:\TURBOC\LIB %1 %2 %3 %4 %5 %6 %7 then use this to build the runtime system: gtcc -c runtime.c and compile programs using: gofc prog.gs gtcc prog.c runtime.obj Since the PC has a fairly limited amount of memory, you may find that you need to compile a new version of the Gofer system without floating point support (or you may need to select a markscan garbage collector in place of the default twospace collector). --------------------- BORLAND C++ version 3.1 on a PC with MSDOS: Set #define BCC 1 and the rest to 0 in prelude.h. You will need to remove the project files gofer.prj and gofc.prj supplied with the Gofer source and rebuild your own project files from within the IDE. The project file for the interpreter should contain the files: gofer.c, input.c, static.c, type.c, compiler.c, machine.c, storage.c, output.c and builtin.c. The project file for the compiler should contain the files: gofc.c, input.c, static.c, type.c, compiler.c, cmachine.c, storage.c and cbuiltin.c. (output.c is not required). Before starting the compilation, make sure that you set the following command line options (all of this is intended to be carried out from within the IDE): Medium model, stack check ON, Merge duplicate strings, No debugging information in object files, no standard stack frames, fastest code (or smallest, if memory is tight), source debugging - none, possibly incorrect assignment warning off. If you have a 386 machine or a floating point coprocessor, you will find a small benefit in setting the relevant compiler options to make use of these features too. In order to make the runtime library and use the compiler, I suggest creating a batch file BTCC.BAT containing: Bcc -O -ms -IC:\BORLANDC\INCLUDE -LC:\BORLANDC\LIB %1 %2 %3 %4 %5 %6 %7 then use this to build the runtime system: btcc -c runtime.c and compile programs using: gofc prog.gs btcc prog.c runtime.obj Since the PC has a fairly limited amount of memory, you may find that you need to compile a new version of the Gofer system without floating point support (or you may need to select a markscan garbage collector in place of the default twospace collector). --------------------- DJGPP 1.09 on MSDOS: DJGPP is a DOS port of the GNU C compiler produced by DJ Delorie. It requires a 386 or better, but gives you much better opportunities to make use of the resources that such machines provide. Much larger heaps can be used, and the 32 bit code produced by DJGPP runs a lot faster than the versions produced by TURBO C or BORLAND C, even on the same machine! DJGPP depends on the use of a DOS extender, go32. A modified version of go32 has been produced which supports signals, allowing the Gofer interpreter to recover from a program interrupt (i.e. pressing ^C during an evaluation). The original version of go32 was written by DJ Delorie. Rami El Charif has modified go32 to handle signals, essential for any serious work with Gofer. Thanks Rami! Instructions for building the modified go32 and compiling Gofer with DJGPP 1.09 are included in the readme file in the go32sgof.zip archive in the standard Gofer distribution. --------------------- NEXT versions: Set #define NEXTSTEP 1 and the rest to 0 in prelude.h. Edit the Makefile to set the C compiler (defined by the macro CC) to cc. (If you would prefer to use the current GNU C compiler i.e. gcc 2.x and have this installed on your system, choose #define NEXTGCC 1 instead of NEXTSTEP and set CC to gcc). Run the make command to build gofer, gofc and runtime.o. --------------------- SUNOS versions: Set #define SUNOS 1 and the rest to 0 in prelude.h. Edit the Makefile as necessary. I tried this on a Sun 4 using gcc, but I think it should also work on Sun 3, and with cc ... If your site has both Sun3 and Sun4 machines, the following script may be of use: #!/bin/sh GOFER=/usr/local/lib/Gofer/prelude export GOFER if (sparc) then exec /usr/local/lib/Gofer/gofer4 $* elif (m68k) then exec /usr/local/lib/Gofer/gofer3 $* else echo I dont know how to start Gofer on your machine fi --------------------- IBM OS/2 2.0 using EMX GCC: Set #define OS2 1 and the rest to 0 in prelude.h. The tweaks to prelude.h to get this working with OS/2 were sent to me by Bryan Scattergood this morning; this is a last-minute update. Thanks Bryan! --------------------- System V release 4 using GCC2.2: Set #define SVR4 1 and the rest to 0 in prelude.h. As in the case of OS/2, I received patches for SVR4 this morning from Bryan Scattergood. Thanks again Bryan! --------------------- HP systems: Set #define HPUX 1 and the rest to 0 in prelude.h. I've had patches for HP machines from a number of people including Tom Lane, Dipankar Gupta, Rodney Brown and Jeroen Fokker and I've tried to work these into the source for 2.28. There were occasional discrepancies between the sets of patches that I received so I sometimes had to take a `majority vote'; perhaps they were for slightly different machines? Anyway, I hope that Gofer will compile on HP machines using these settings -- or at least be easy to patch to make it run correctly if not. Thanks for the patches everyone! It has now been verified that the HPUX patch version will at least compile correctly on HP series 400 workstations (68040 CPU) running HP-UX 8.0 with gcc, thanks to Kurt Olender! --------------------- DECstation 5000 running Ultrix 4.2 (MIPS R3000 CPU) with GCC2.3.3: Set #define ULTRIX 1 and the rest to 0 in prelude.h. Thanks to Kurt Olender for the patches! --------------------- IBM AIX on RS/6000 using GCC: Set #define AIX 1 and the rest to 0 in prelude.h. Thanks (again) to Kurt Olender for the patches! --------------------- Minix 68K: Set #define MINIX68K 1 and the rest to 0 in prelude.h. Rainer Orth sent me sent me some patches to make Gofer 2.23 compile and run under Minix 68k using the GNU C compiler, I believe. I have tried to make the same changes to the latest version, but I have not verified that they work. Some small changes may be needed -- please let me know if you try it. Thanks Rainer! --------------------- Linux with gcc: Set #define LINUX 1 and the rest to 0 in prelude.h. Ray Bellis sent me some patches to make Gofer 2.23 compile and run under Linux using the GNU C compiler. I have tried to make the same changes to the latest version, but I have not verified that they work. Some small changes may be needed -- please let me know if you try it. And thanks, Ray! --------------------- Acorn DesktopC and RISCOS2 or 3: Set #define RISCOS 1 and the rest to 0 in prelude.h. Use the file AcornMake to build the Gofer system. Thanks to Bryan Scattergood for the patches to make Gofer compile and run under RISCOS! --------------------- Amiga: Set #define AMIGA 1 and the rest to 0 in prelude.h. Compile using gcc 2.2.2. Thanks to Luc and Mark Duponcheel for their help in getting this to work. One small problem remains that ^C interrupts do not currently work. I believe this can be solved by setting an appropriate value for the #define allowBreak() macro in prelude.h, but I am not sure what definition should be used. --------------------- DEC Alpha with OSF/1: Set #define ALPHA 1 and the rest to 0 in prelude.h Briefly, I tried compiling Gofer on a 64 bit DEC Alpha with a preliminary version of OSF/1. I didn't spend long, but it seems that it is probably safest to compile without using any optimization. Furthermore, only the interpreter can be used at the current time and integers are restricted to 32 bit quantities. I may do something to change this one day, but it is not a high priority. Essentially, what needs to be done is to redefine the Int type as a synonym (i.e. typedef) for long and to replace all appropriate uses of %d in prinf strings with %ld. --------------------- OTHER PLATFORMS: Gofer has been tested on other platforms and most of the code is fairly standard. The code does however make certain assumptions about the system on which Gofer will be used. These are summarised below as an aid to those interested in porting Gofer to other systems: 1) For the benefit of Garbage collection from the C stack, all function parameters and local variables are expected to have sizes which are a multiple of sizeof(Int) (defined in prelude.h). In other words, you should check that: sizeof(FloatImpType) % sizeof(Int) == 0 sizeof(String) % sizeof(Int) == 0 sizeof(Char) % sizeof(Int) == 0 sizeof(Long) % sizeof(Int) == 0 sizeof(Unsigned) % sizeof(Int) == 0 (These types are defined in prelude.h and storage.h) 2) Study the comments and settings in prelude.h in order to find out how other ports of Gofer have been produced. 3) The words local and far are used to access non-standard extensions in Turbo C to allow the Gofer system to overcome some of the limitations of the PC's segmented architecture. These should be #defined to empty strings on most other machines with a flat address space. 4) The current version of the garbage collector in the Gofer interpreter uses the C call stack as an array of Cell values to find temporary variables that point into the heap. This is a well-known technique often described as `conservative garbage collection' but the implementation in C is inherently non-portable. Surprisingly enough though, for almost all of the machines supported, you can make some simple assumptions and get things to work quite nicely. The RISCOS code is one example where things are very different. But for the most part, you can treat the C stack as an array of Cell values. As the program runs the size of the stack changes and you need to know the extent of the array. The first element pushed onto the stack is pretty much fixed, so it is the position of the stack pointer that determines how big the stack is. On many machines, the stack grows downwards. I have yet to come across a machine where the stack grows upwards, but I have heard that this happens on some HP systems. Here is the way to deal with this in the current version of the code. In machdep.c, you will find a function gcCStack() which traverses the stack. To make things easier, there are three macros: #define StackGrowsDown ... #define StackGrowsUp ... #define GuessDirection ... The first two describe the way to mark the stack on a machine in which the stack grows either up or down respectively. The third tries to guess which way to do things by comparing two pointers. Strictly speaking, this comparison probably doesn't fall under the definition of standard C so it may not be portable. The current usage of these functions is as follows: #if HPUX GuessDirection; #else StackGrowsDown; #endif Change as necessary to suit your machine (and please let me know so that I can update the source). Almost all of the machine dependencies in the code for Gofer are contained in the header file "prelude.h", and the program file "machdep.c". These files contain definitions for both the TURBOC and UNIX versions described above and should be a useful guide. I regret that I do not have time to write more substantial notes for porting Gofer at the present time. I will however be happy to offer advice and answer other questions if you want to contact me in person at the email address below. If you do successfully complete a port for another machine, please let me know what changes are necessary. I know that it isn't always possible, but if you can, please try to restrict changes to the prelude.h and machdep.c files. --------------------- NOTE: if Gofer starts behaving unexpectedly, try recompiling without full compiler optimisation and see if the problem still occurs. If so, please get in touch with me, giving me as much information about the problem as possible, and I'll try and sort it out for you. If you find a bug which you fix yourself, please send me details so that I can pass the fix onto to other users of Gofer. If gofc starts behaving unexpectedly, try running the same code through the interpreter. jones-mark@cs.yale.edu -------------------------------------------------------------------------------