diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 568 |
1 files changed, 282 insertions, 286 deletions
@@ -1,93 +1,96 @@ -This directory contains the distribution of scm5c3. Scm conforms to +This directory contains the distribution of scm5d2. Scm conforms to Revised^5 Report on the Algorithmic Language Scheme and the IEEE P1178 -specification. Scm runs under VMS, MS-DOS, OS2, MacOS, Amiga, -Atari-ST, NOS/VE, Unix and similar systems. - -This file consists mainly of excerpts from "scm.info", the result of -compiling (with makeinfo) "scm.texi" to `info' form. In case of -conflicts with "scm.info", consult "scm.info". - -The author can be reached at <jaffer@ai.mit.edu> - - MANIFEST - - `README' is this file. It contains a MANIFEST, INSTALLATION - INSTRUCTIONS, hints for EDITING SCHEME CODE, and a TROUBLE - SHOOTING GUIDE. - `COPYING' details the LACK OF WARRANTY for scm and the conditions - for distributing scm. - `scm.1' is the unix style man page in nroff format. - `scm.doc' is the text man page generated from scm.1. - `QUICKREF' is a Quick Reference card for IEEE and R4RS. - `scm.texi' details feature support and enhancements to Scheme and - contains a SCHEME BIBLIOGRAPHY. - `ChangeLog' documents changes to the scm. - - `r4rstest.scm' is Scheme code which tests conformance with Scheme - specifications. - `example.scm' is Scheme code from Revised^4 Report on the - Algorithmic Language Scheme which uses inexact numbers. - `pi.scm' is Scheme code for computing digits of pi [type (pi 100 5)] - which can be used to test the performance of scm against - compiled C code [cc -o pi pi.c;time pi 100 5]. - `pi.c' is C code for computing digits of pi. - `bench.scm' is Scheme code for computing and recording speed of - "pi.scm". - - `Makefile' is for building scmlit using the `make' program. - `build.scm' creates a database and program for compiling and linking - new SCM executables, libraries, and dlls. - `build.bat' invokes build.scm on MS-DOS platforms. - `mkimpcat.scm' build SCM-specific catalog for SLIB. - `disarm.scm' disables file opening and modifications. - `.gdbinit' provides commands for debugging SCM with GDB. - `setjump.mar' provides setjump and longjump which do not use $unwind - utility on VMS. - `ugsetjump.s' provides setjump and longjump which work on Ultrix VAX. - `setjump.s' provides setjump and longjump for the Cray YMP. - - `Init5c2.scm' is Scheme initialization code. - `Transcen.scm' has Scheme code for inexact builtin procedures. - `Link.scm' has Scheme code for compiling and dynamic linking. - `scmfig.h' is a C include file containing system dependent definitions. - `patchlvl.h is the patchlevel of this release. - `continue.c' code for continuations. - `continue.h' data types and external functions for continuations. - `setjump.h' is an include file dealing with continuations, stacks, - and memory allocation. - `scm.h' has the data type and external definitions of scm. - - `scm.c' has the top level and interrupt code. - `findexec.c' has code to find the executable file. - `time.c' has functions dealing with time. - `repl.c' has error, read-eval-print loop, read, write and load code. - `scl.c' has the code for utility functions which are not part of the - IEEE Scheme spec or which are required for non-integer - arithmetic. - `eval.c' has the evaluator, apply, map, and foreach. - `sys.c' has the code for opening and closing files, storage - allocation and garbage collection. - `rope.c' has C interface functions. - `subr.c' has all the rest of functions. - `sc2.c' has code for procedures from R2RS and R3RS not in R4RS. - `dynl.c' has c code for dynamically loading object files. - `unif.c' has code for uniform vectors. - `rgx.c' has code for string regular expression match. - `crs.c' has code for interactive terminal control. - `split.scm' sets up CURSCM (SCM with crs.c) so that input, output, - and diagnostic output are each directed to separate windows. - `edline.c' Gnu readline input editing - (get ftp.sys.toronto.edu:/pub/rc/editline.shar). - `Iedline.scm' Gnu readline input editing. - `record.c' has code for proposed "Record" user definable datatypes. - `gsubr.c' has make_gsubr for arbitrary (< 11) arguments to C functions. - - `ioext.c' has code for system calls in common between PC compilers and unix. - `posix.c' has code for posix library interface. - `unix.c' has code for non-posix system calls on unix systems. - `socket.c' has code for socket interface. - - SLIB +specification. SCM runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2, +NOS/VE, Unicos, VMS, Unix and similar systems. + + `http://swissnet.ai.mit.edu/~jaffer/SCM.html' + +Manifest +======== + +`.gdbinit' provides commands for debugging SCM with GDB +`COPYING' details the LACK OF WARRANTY for SCM and the conditions + for distributing SCM. +`ChangeLog' changes to SCM. +`Iedline.scm' Gnu readline input editing. +`Init.scm' Scheme initialization. +`Link.scm' compiles and dynamically links. +`Macro.scm' Supports Syntax-Rules Macros. +`Makefile' builds SCMLIT using the `make' program. +`QUICKREF' Quick Reference card for R4RS and IEEE Scheme. +`README' contains a MANIFEST, INSTALLATION INSTRUCTIONS, hints + for EDITING SCHEME CODE, and a TROUBLE SHOOTING GUIDE. +`Transcen.scm' inexact builtin procedures. +`bench.scm' computes and records performance statistics of pi.scm. +`build.bat' invokes build.scm for MS-DOS +`build.scm' database for compiling and linking new SCM programs. +`continue.c' continuations. +`continue.h' continuations. +`crs.c' interactive terminal control. +`dynl.c' dynamically load object files. +`ecrt0.c' discover the start of initialized data space + dynamically at runtime. +`edline.c' Gnu readline input editing (get + ftp.sys.toronto.edu:/pub/rc/editline.shar). +`eval.c' evaluator, apply, map, and foreach. +`example.scm' example from R4RS which uses inexact numbers. +`findexec.c' find the executable file function. +`gmalloc.c' Gnu malloc(); used for unexec. +`gsubr.c' make_gsubr for arbitrary (< 11) arguments to C + functions. +`ioext.c' system calls in common between PC compilers and unix. +`mkimpcat.scm' build SCM-specific catalog for SLIB. +`patchlvl.h' patchlevel of this release. +`pi.c' computes digits of pi [cc -o pi pi.c;time pi 100 5]. +`pi.scm' computes digits of pi [type (pi 100 5)]. Test + performance against pi.c. +`posix.c' posix library interface. +`pre-crt0.c' loaded before crt0.o on machines which do not remap + part of the data space into text space in unexec. +`r4rstest.scm' tests conformance with Scheme specifications. +`ramap.c' array mapping +`record.c' proposed `Record' user definable datatypes. +`repl.c' error, read-eval-print loop, read, write and load. +`rgx.c' string regular expression match. +`rope.c' C interface functions. +`sc2.c' procedures from R2RS and R3RS not in R4RS. +`scl.c' inexact arithmetic +`scm.1' unix style man page. +`scm.c' initialization, interrupts, and non-IEEE utility + functions. +`scm.doc' man page generated from scm.1. +`scm.h' data type and external definitions of SCM. +`scm.texi' SCM installation and use. +`scmfig.h' contains system dependent definitions. +`scmmain.c' initialization, interrupts, and non-IEEE utility + functions. +`script.c' utilities for running as `#!' script. +`setjump.h' continuations, stacks, and memory allocation. +`setjump.mar' provides setjump and longjump which do not use $unwind + utility on VMS. +`setjump.s' provides setjump and longjump for the Cray YMP. +`socket.c' BSD socket interface. +`split.scm' example use of crs.c. Input, output, and diagnostic + output directed to separate windows. +`subr.c' the rest of IEEE functions. +`sys.c' call-with-current-continuation, opening and closing + files, storage allocation and garbage collection. +`time.c' functions dealing with time. +`ugsetjump.s' provides setjump and longjump which work on Ultrix VAX. +`unexalpha.c' Convert a running program into an Alpha executable file. +`unexec.c' Convert a running program into an executable file. +`unexelf.c' Convert a running ELF program into an executable file. +`unexhp9k800.c' Convert a running HP-UX program into an executable file. +`unexsgi.c' Convert a running program into an IRIX executable file. +`unexsunos4.c' Convert a running program into an executable file. +`unif.c' uniform vectors. +`unix.c' non-posix system calls on unix systems. + + +File: scm.info, Node: SLIB, Next: Building SCM, Prev: Making SCM, Up: Installing SCM + +SLIB +==== [SLIB] is a portable Scheme library meant to provide compatibility and utility functions for all standard Scheme implementations. Although @@ -95,18 +98,19 @@ SLIB is not *neccessary* to run SCM, I strongly suggest you obtain and install it. Bug reports about running SCM without SLIB have very low priority. SLIB is available from the same sites as SCM: - * swissnet.ai.mit.edu:pub/scm/slib2c3.tar.gz - * prep.ai.mit.edu:pub/gnu/jacal/slib2c3.tar.gz - * ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c3.tar.gz - * ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c3.tar.gz + * swissnet.ai.mit.edu:/pub/scm/slib2c7.tar.gz -Unpack SLIB (`tar xzf slib2c3.tar.gz' or `unzip -ao slib2c3.zip') in an + * ftp.gnu.org:/pub/gnu/jacal/slib2c7.tar.gz + + * ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c7.tar.gz + +Unpack SLIB (`tar xzf slib2c7.tar.gz' or `unzip -ao slib2c7.zip') in an appropriate directory for your system; both `tar' and `unzip' will create the directory `slib'. Then create a file `require.scm' in the SCM "implementation-vicinity" -(this is the same directory as where the file `Init.scm' is installed). -`require.scm' should have the contents: +(this is the same directory as where the file `Init5d2.scm' is +installed). `require.scm' should have the contents: (define (library-vicinity) "/usr/local/lib/slib/") (load (in-vicinity (library-vicinity) "require")) @@ -128,16 +132,21 @@ Alternatively, you can set the (shell) environment variable SCHEME_LIBRARY_PATH: SCM Variables.). If set, the environment variable overrides `require.scm'. Again, absolute pathnames are recommended. - MAKING SCM + + +File: scm.info, Node: Making SCM, Next: SLIB, Prev: Installing SCM, Up: Installing SCM + +Making SCM +========== The SCM distribution has "Makefile" which contains rules for making "scmlit", a "bare-bones" version of SCM sufficient for running `build.scm'. `build.scm' is used to compile (or create scripts to compile) full featured versions. -Makefiles are not portable to the majority of platforms. If -`Makefile' works for you, good; If not, I don't want to hear about it. -If you need to compile SCM without build.scm, there are several ways to +Makefiles are not portable to the majority of platforms. If `Makefile' +works for you, good; If not, I don't want to hear about it. If you +need to compile SCM without build.scm, there are several ways to proceed: * Use SCM on a different platform to run `build.scm' to create a @@ -148,8 +157,8 @@ proceed: * Create your own script or `Makefile'. - * Buy a SCM executable from jaffer@ai.mit.edu. See the end of - `ANNOUNCE' in the distribution for details. + * Buy a SCM executable from jaffer @ ai.mit.edu. See the end of the + `ANNOUNCE' file in the distribution for details. * Use scmconfig (From: bos@scrg.cs.tcd.ie): @@ -161,51 +170,31 @@ proceed: I am moving it to the OLD subdirectory until someone submits an update. - Making SCM with Think C 4.0 or 4.1 - -Note: These instructions need to be uptdated for scm5c3. If Think C -can be called using system(), then SCM can be built using build.scm. - - Edit Scmfig.H to set desired options and IMPLINIT. - from Yasuaki Honda // honda@csl.SONY.co.jp: - Make a project and add source files repl.c, time.c, scm.c, subr.c, - sys.c, eval.c, scl.c, sc2.c, and unif.c to it. - Add libraries MacTraps, unix, ANSI to the project. - The project should be segmented in the following way: - ---------- - repl.c - scm.c - subr.c - sys.c - sc2.c - unif.c - time.c - ---------- - MacTraps - unix - ---------- - ANSI - ---------- - eval.c - ---------- - scl.c - ---------- - Choose 'Set Project Type' from 'Project' menu. - Choose Application from radio buttons. - Set Partition size to 600K. (The default 384K is not enough). - - EDITING SCHEME CODE + + +File: scm.info, Node: Editing Scheme Code, Next: Debugging Scheme Code, Prev: SCM Session, Up: Operational Features + +Editing Scheme Code +=================== + + - Function: ed ARG1 ... + The value of the environment variable `EDITOR' (or just `ed' if it + isn't defined) is invoked as a command with arguments ARG1 .... + + - Function: ed FILENAME + If SCM is compiled under VMS `ed' will invoke the editor with a + single the single argument FILENAME. Gnu Emacs: Editing of Scheme code is supported by emacs. Buffers holding files ending in .scm are automatically put into scheme-mode. EMACS for MS-DOS and MS-Windows systems is available (free) from: - * http://simtel.coast.net/SimTel/gnu/demacs.html + `http://simtel.coast.net/SimTel/gnu/demacs.html' If your Emacs can run a process in a buffer you can use the Emacs - command `M-x run-scheme' with SCM. Otherwise, use the emacs - command `M-x suspend-emacs'; or see "other systems" below. +command `M-x run-scheme' with SCM. Otherwise, use the emacs command +`M-x suspend-emacs'; or see "other systems" below. Epsilon (MS-DOS): There is lisp (and scheme) mode available by use of the package @@ -224,7 +213,7 @@ Epsilon (MS-DOS): other systems: Define the environment variable `EDITOR' to be the name of the - editing program you use. The SCM procedure `(ed arg1 ...)' will + editing program you use. The SCM procedure `(ed arg1 ...)' will invoke your editor and return to SCM when you exit the editor. The following definition is convenient: @@ -233,152 +222,159 @@ other systems: Typing `(e)' will invoke the editor with the file of interest. After editing, the modified file will be loaded. - TROUBLE SHOOTING - -Reported problems and solutions are grouped under "Compiling", -"Linking", "Running", and "Testing". If you don't find your problem -listed here, you can send a bug report to <jaffer@ai.mit.edu>. The -bug report should include: - - * The version of SCM (printed when SCM is invoked with no arguments). - - * The type of computer you are using. - - * The name and version of your computer's operating system. - - * The values of the environment variables SCM_INIT_PATH and - SCHEME_LIBRARY_PATH. - - * The name and version of your C compiler. - - * If you are using an executable from a distribution, the name, - vendor, and date of that distribution. In this case, - corresponding with the vendor is recommended. - - - Compiling: - -FILE ERROR or WARNING HOW TO FIX - -*.c include file not found Correct status of - STDC_HEADERS - - fix #include statement - or add #define for - system type to scmfig.h - -scm.c assignment between incompatible types change SIGRETTYPE in scm.c - -time.c CLK_TCK redefined incompatablility - between <stdlib.h> and - <sys/types.h>. remove - STDC_HEADERS in scmfig.h - - edit <sys/types.h> to - remove incompatability. - -sys.c statement not reached ignore - constant in conditional expression ignore - -sys.c: `???' undeclared, outside of functions #undef STDC_HEADERS - in scmfig.h - -scl.c syntax error define system type in - scmfig.h and scl.c (softtype) - - Linking: - -ERROR or WARNING HOW TO FIX - -_sin etc. missing. uncomment LIBS in makefile - - Running: - -PROBLEM HOW TO FIX - -Opening message and then machine Change memory model option -crashes. to C compiler (or makefile). - - Make sure sizet definition is - correct in scmfig.h - - Reduce size of HEAP_SEG_SIZE - in setjump.h - -Input hangs #define NOSETBUF - -ERROR: heap: need larger initial Need to increase the initial - heap allocation using - -a<kbytes> or INIT_HEAP_SIZE. - -ERROR: Could not allocate ... Check sizet definition. - - Get more memory. - - Don't try to run as subproccess - -... in scmfig.h and recompile scm Do it and recompile files. - -ERROR: Init.scm not found Assign correct IMPLINIT in - makefile or scmfig.h or - define environment variable - SCM_INIT_PATH to be the full - pathname of Init.scm (see - INSTALLATION instructions). - -WARNING: require.scm not found define environment variable - SCHEME_LIBRARY_PATH to be the - full pathname of the scheme - library SLIB or change - library-vicinity in Init.scm - to point to library or remove. - See section SLIB above. - - Make sure library-vicinity has - a trailing file separator - (like / or \). - - Testing: (load "r4rstest.scm") or (load "pi.scm") (pi 100 5) - -Runs some and then machine crashes. See above under machine - crashes. - -Runs some and then ERROR: ... Remove optimization option -(after a GC has happened) to C compiler and recompile. - - #define SHORT_ALIGN in scmfig.h - -Some symbol names print incorrectly. Change memory model option - to C compiler (or makefile). - - Check that HEAP_SEG_SIZE fits - within sizet. - - Increase size of HEAP_SEG_SIZE - (or INIT_HEAP_SIZE if it is - smaller than HEAP_SEG_SIZE). - -ERROR: Rogue pointer in Heap. See above under machine - crashes. - -Newlines don't appear correctly in Check file mode (define OPEN_... -output files. in Init.scm - -Spaces or control characters appear Check character defines in -in symbol names scmfig.h - -Negative numbers turn positive. Check SRS in scmfig.h -VMS: Couldn't unwind stack #define CHEAP_CONTIUATIONS -VAX: botched longjmp in scmfig.h -Sparc(SUN-4) heap is growing out of control: +File: scm.info, Node: Problems Compiling, Next: Problems Linking, Prev: Automatic C Preprocessor Definitions, Up: Installing SCM + +Problems Compiling +================== + +FILE PROBLEM / MESSAGE HOW TO FIX +*.c include file not found. Correct the status of + STDC_HEADERS in scmfig.h. + fix #include statement or add + #define for system type to + scmfig.h. +*.c Function should return a value. Ignore. + Parameter is never used. + Condition is always false. + Unreachable code in function. +scm.c assignment between incompatible Change SIGRETTYPE in scm.c. + types. +time.c CLK_TCK redefined. incompatablility between + <stdlib.h> and <sys/types.h>. + Remove STDC_HEADERS in scmfig.h. + Edit <sys/types.h> to remove + incompatability. +subr.c Possibly incorrect assignment Ignore. + in function lgcd. +sys.c statement not reached. Ignore. + constant in conditional + expression. +sys.c undeclared, outside of #undef STDC_HEADERS in scmfig.h. + functions. +scl.c syntax error. #define SYSTNAME to your system + type in scl.c (softtype). + + + +File: scm.info, Node: Problems Linking, Next: Problems Running, Prev: Problems Compiling, Up: Installing SCM + +Problems Linking +================ + +PROBLEM HOW TO FIX +_sin etc. missing. Uncomment LIBS in makefile. + + + +File: scm.info, Node: Problems Running, Next: Testing, Prev: Problems Linking, Up: Installing SCM + +Problems Running +================ + +PROBLEM HOW TO FIX +Opening message and then machine Change memory model option to C +crashes. compiler (or makefile). + Make sure sizet definition is + correct in scmfig.h. + Reduce the size of HEAP_SEG_SIZE in + setjump.h. +Input hangs. #define NOSETBUF +ERROR: heap: need larger initial. Increase initial heap allocation + using -a<kb> or INIT_HEAP_SIZE. +ERROR: Could not allocate. Check sizet definition. + Use 32 bit compiler mode. + Don't try to run as subproccess. +remove <FLAG> in scmfig.h and Do so and recompile files. +recompile scm. +add <FLAG> in scmfig.h and +recompile scm. +ERROR: Init5d2.scm not found. Assign correct IMPLINIT in makefile + or scmfig.h. + Define environment variable + SCM_INIT_PATH to be the full + pathname of Init5d2.scm. +WARNING: require.scm not found. Define environment variable + SCHEME_LIBRARY_PATH to be the full + pathname of the scheme library + [SLIB]. + Change library-vicinity in + Init5d2.scm to point to library or + remove. + Make sure the value of + (library-vicinity) has a trailing + file separator (like / or \). + + + +File: scm.info, Node: Testing, Next: Reporting Problems, Prev: Problems Running, Up: Installing SCM + +Testing +======= + +Loading `r4rstest.scm' in the distribution will run an [R4RS] +conformance test on `scm'. + + > (load "r4rstest.scm") + -| + ;loading "r4rstest.scm" + SECTION(2 1) + SECTION(3 4) + #<primitive-procedure boolean?> + #<primitive-procedure char?> + #<primitive-procedure null?> + #<primitive-procedure number?> + ... + +Loading `pi.scm' in the distribution will enable you to compute digits +of pi. + + > (load "pi") + ;loading "pi" + ;done loading "pi.scm" + ;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other + #<unspecified> + > (pi 100 5) + 00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 + 37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 + 70679 + ;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other + #<unspecified> + +Loading `bench.scm' will compute and display performance statistics of +SCM running `pi.scm'. `make bench' or `make benchlit' appends the +performance report to the file `BenchLog', facilitating tracking +effects of changes to SCM on performance. + +PROBLEM HOW TO FIX +Runs some and then machine crashes. See above under machine crashes. +Runs some and then ERROR: ... Remove optimization option to C +(after a GC has happened). compiler and recompile. + #define SHORT_ALIGN in `scmfig.h'. +Some symbol names print incorrectly. Change memory model option to C + compiler (or makefile). + Check that HEAP_SEG_SIZE fits + within sizet. + Increase size of HEAP_SEG_SIZE (or + INIT_HEAP_SIZE if it is smaller + than HEAP_SEG_SIZE). +ERROR: Rogue pointer in Heap. See above under machine crashes. +Newlines don't appear correctly in Check file mode (define OPEN_... in +output files. `Init5d2.scm'). +Spaces or control characters appear Check character defines in +in symbol names. `scmfig.h'. +Negative numbers turn positive. Check SRS in `scmfig.h'. +VMS: Couldn't unwind stack. #define CHEAP_CONTIUATIONS in + `scmfig.h'. +VAX: botched longjmp. + +Sparc(SUN-4) heap is growing out of control + You are experiencing a GC problem peculiar to the Sparc. The + problem is that SCM doesn't know how to clear register windows. + Every location which is not reused still gets marked at GC time. + This causes lots of stuff which should be collected to not be. + This will be a problem with any *conservative* GC until we find + what instruction will clear the register windows. This problem is + exacerbated by using lots of call-with-current-continuations. - You are experiencing a GC problem peculiar to the Sparc. The - problem is that SCM doesn't know how to clear register - windows. Every location which is not reused still gets marked - at GC time. This causes lots of stuff which should be - collected to not be. This will be a problem with any - "conservative" GC until we find what instruction will clear - the register windows. This problem is exacerbated by using - lots of call-with-current-continuations. |