Celestin Apprentice 2

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

/ Celestin Apprentice 2 / Apprentice-Release2.iso / Tools / Languages / MacGofer 0.22d / MacGofer Sources / Readme < prev next >

Wrap

Text File | 1994-01-06 | 21.4 KB | 516 lines | [TEXT/MPS ]

------------------------------------------------------------------------------- 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. In particular, make sure that the CC macro is set to the name of the compiler you will be using (this is usually either `cc' for the standard C compiler on a system or `gcc' for the GNU C compiler). 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. Remember that double quote characters (") and backslashes (\) must be escaped by a leading backslash. For example: "\"/usr/local/lib/Gofer/gofc.h\"" might be used on Unix machine, "\"\C:\\GOFER\\GOFC\\GOFC.H\"" might be approp. for a DOS machine. 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.h" 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 ... IMPORTANT: If you plan to use the shell scripts provided to operate the Gofer compiler and you have a choice of C compilers on your system (e.g. GNU gcc and a vendor-supplied cc) make sure that the C compiler mentioned in the script gofcc is the same C compiler used (in the Makefile) to compile runtime.c. In a similar way, make sure that the version of gofc.h used to compile runtime.c has the same settings as the version of gofc.h that you put in $GOFLIB. (This is only likely to be relevant if you install an alternative garbage collector or change the setting on ARGCHECK.) I've probably left something out here. Please let me know if you have any trouble or spot anything that you think I should have mentioned! --------------------- 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). --------------------- Zortech C++ v3.0 for IBM PC (>=386) Set #define ZTC 1 and the rest to 0 in prelude.h. Compile using the makefile supplied as Makefile.ztc. Thanks to John Lazenby for the patches to get this to work! --------------------- 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. Thanks to Bryan Scattergood for sending the patches to get this working! --------------------- System V release 4 using GCC2.2: Set #define SVR4 1 and the rest to 0 in prelude.h. Thanks to Bryan Scattergood for sending the patches to get this working! --------------------- SCO Unix 3.2.4: Set #define SVR4 1 and the rest to 0 in prelude.h. Compile using gcc 2.2.2. Thanks to Rodney Brown! --------------------- Silicon Graphics with Irix: Set #define SVR4 1 and the rest to 0 in prelude.h. Set the makefile to use cc. If you are running on a machine with a MIPS R4000 CPU, you might also like to add -mips2 to CFLAGS (this should not be used if you want backward compatibility with machines based on the MIPS R3000 CPU). I think you can probably build Gofer using gcc but I haven't had the opportunity to try that myself. --------------------- 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! Gofer 2.28 has also been built on an H.P. Series 700 machine running HP-UX 8.07. Gofer does not work if it is compiled using gcc (2.3.3). Use the HP C compiler (cc) in ANSI mode. A guide to setting the macro definitions in the Makefile: CC = cc CFLAGS = -Aa -D_HPUX_SOURCE LDFLAGS = -lm OPTFLAGS = +O3 OPT1 = +O1 Thanks to Dave Sherratt for this information! --------------------- 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! This release of Gofer includes a slight modification, brought to my notice by Jerry Prothero, which should also make it possible to compile Gofer using DEC's own cc compiler instead of gcc. Thanks Jerry! --------------------- 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! Since 2.28 was first distributed I've had feedback from two people that have compiled Gofer to run on Linux. Bambang Prastowo wrote to let me know that Gofer compiled without modifications (other than setting #define LINUX 1). Eak Khoon reported that it was neccessary to comment out the #define const at the beginning of prelude.h and change prototypes in prelude.h to: extern *getenv Args((const char *)); extern system Args((const char *)); extern atof Args((const char *)); This may be due to the use of slightly different compilers or versions of Linux. In any case, it should be fairly straightforward to build Gofer to run under Linux. --------------------- 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. Frederek Althoff has investigated this problem and believes that there may be a problem with the signal handling in the current version of gcc on the Amiga. Frederek has written a C program, included in the main distribution as amigaint.c, to try and help out. In his words: `` All you have to do is start the program from an other shell with the process-id of gofer. To get this id, you have to use a program called "Status" (similar to "ps"). That's all. You might add this program to your distribution? This will `help' until the ^C-problem is fixed''. Thanks Frederek! --------------------- 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. --------------------- MIPS RC6280(BSDenvironment on OS2.2): SONY machine(NWS-3870, BSD4.3- based OS NEWS OS4.2R, Mips-made risk chip): Set #define MIPS 1 and the rest to 0 in prelude.h. The patches for this version of Gofer were sent to me by Hiroyuki Matsuda ... thanks! I only hope that I have correctly incorporated them into the main distribution! --------------------- 386bsd: A 386bsd version of Gofer has been put together by Viren Shah. It sounds like a rather complicated process, so I'll just quote the instructions that Viren sent me ... I haven't tried this myself: | I used the SUNOS mode (i did try the linux mode, but that crashed | repeatedly and no amount of hacking could fix it) and the following | are the changes made by me in order to install it: | | 1.> Copied malloc.h from /usr/include/g++ to current directory, namely | /usr/local/Gofer/src . | 2.> edited Makefile : | CFLAGS : -I. -I/usr/src/sys.386bsd/sys -I/usr/include/g++ | 3.> edited gofc.c to comment out #include <sys/stat.h> | 4.> copied time.h from /usr/src/include to current directory | 5.> edited Makefile : | for .gs files the compile command is now : | $(CC) $(CFLAGS) $(OPTFLAGS) $*.c runtime.o -o $* $(LDFLAGS) | 6.> edited goferc script to include the -I option for the gcc compiler | | Most of the above changes (not that they are very many) are probably | due to system specific problems, but I have no way of determining | that since I do not know anyone else installing Gofer on 386bsd. --------------------- 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 -------------------------------------------------------------------------------