home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / language / scm / !Scm / docs / README < prev    next >
Encoding:
Text File  |  1994-04-03  |  14.9 KB  |  457 lines
  1. This directory contains the distribution of scm4e.  Scm conforms to
  2. Revised^4 Report on the Algorithmic Language Scheme and the IEEE P1178
  3. specification.  Scm runs under VMS, MS-DOS, OS2, MacOS, Amiga,
  4. Atari-ST, NOS/VE, Unix and similar systems.
  5.  
  6. The author can be reached at jaffer@ai.mit.edu or
  7. Aubrey Jaffer, 84 Pleasant St., Wakefield MA 01880.
  8.  
  9.                    MANIFEST
  10.  
  11.   `README' is this file.  It contains a MANIFEST, INSTALLATION
  12.     INSTRUCTIONS, hints for EDITING SCHEME CODE, and a TROUBLE
  13.     SHOOTING GUIDE.
  14.   `COPYING' details the LACK OF WARRANTY for scm and the conditions
  15.     for distributing scm.
  16.   `scm.1' is the unix style man page in nroff format.
  17.   `scm.doc' is the text man page generated from scm.1.
  18.   `QUICKREF' is a Quick Reference card for IEEE and R4RS.
  19.   `MANUAL' details feature support and enhancements to Scheme and
  20.     contains a SCHEME BIBLIOGRAPHY.
  21.   `ChangeLog' documents changes to the scm.
  22.   `code.doc' describes the internal representations and algorithms.
  23.     Also describes how to modify scm.
  24.  
  25.   `test.scm' is Scheme code which tests conformance with Scheme
  26.     specifications.
  27.   `example.scm' is Scheme code from Revised^4 Report on the
  28.     Algorithmic Language Scheme which uses inexact numbers.
  29.   `pi.scm' is Scheme code for computing digits of pi [type (pi 100 5)]
  30.     which can be used to test the performance of scm against
  31.     compiled C code [cc -o pi pi.c;time pi 100 5].
  32.   `pi.c' is C code for computing digits of pi.
  33.  
  34.   `makefile.unix' is for building scm using the `make'program.
  35.   `makefile.msc' is for building scm on IBM PC using Microsoft C.
  36.   `makefile.qc' is for building scm on IBM PC using Microsoft QuickC.
  37.   `makefile.bor' is for building scm on IBM PC using Borland C.
  38.   `makefile.tur' is for building scm on IBM PC using Turbo C.
  39.   `makefile.wcc' is for building scm on IBM PC using Watcom C.
  40.   `makefile.djg' is for building scm on i386 IBM PC using DJGPP
  41.     (Gnu CC ported to MSDOS).
  42.   `makefile.emx' is for building scm on i386 IBM PC using EMX port
  43.     of Gnu CC to OS/2. 
  44.   `makefile.ast' is for building scm on a ATARI-ST using Gnu CC.
  45.   `makefile.prj' is the project file for scm on a ATARI-ST using Turbo C.
  46.   `makefile.aztec' is for building scm on AMIGA using
  47.     Aztec C 5.2a.
  48.   `makefile.acorn' is for building scm on an Acorn Achimedes using Huw
  49.     Rogers free unix function call library.
  50.   `dmakefile' is for building scm on AMIGA using DICE C.
  51.   `compile.amiga' is for compiling scm on AMIGA.
  52.   `link.amiga' is for linking scm on AMIGA.
  53.   `VMSBUILD.COM' is the command file for building scm on a VMS
  54.     machine.
  55.   `VMSGCC.COM' is the command file for building scm using GCC on a
  56.     VMS machine.
  57.   `setjump.mar' provides setjmp and longjmp which do not use $unwind
  58.     utility on VMS.
  59.   `setjump.s' provides setjmp and longjmp for the Cray YMP.
  60.  
  61.   `Init.scm' is Scheme initialization code.
  62.   `Transcen.scm' has Scheme code for inexact builtin procedures.
  63.   `Link.scm' has Scheme code for compiling and dynamic linking.
  64.   `scmfig.h' is a C include file containing system dependent definitions.
  65.   `patchlvl.h is the patchlevel of this release.
  66.   `setjump.h' is an include file dealing with continuations, stacks,
  67.     and memory allocation.
  68.   `scm.h' has the data type and external definitions of scm.
  69.  
  70.   `scm.c' has the top level and interrupt code.
  71.   `time.c' has functions dealing with time.
  72.   `repl.c' has error, read-eval-print loop, read, write and load code.
  73.   `scl.c' has the code for utility functions which are not part of the
  74.     IEEE Scheme spec or which are required for non-integer
  75.     arithmetic.
  76.   `eval.c' has the evaluator, apply, map, and foreach.
  77.   `sys.c' has the code for call-with-current-continuation, opening and
  78.     closing files, storage allocation and garbage collection.
  79.   `subr.c' has all the rest of functions.
  80.   `sc2.c' has code for procedures from R2RS and R3RS not in R4RS.
  81.   `unif.c' has code for uniform vectors.
  82.   `rgx.c' has code for string regular expression match.
  83.   `crs.c' has code for interactive terminal control.
  84.   `split.scm' sets up CURSCM (SCM with crs.c) so that input, output,
  85.     and diagnostic output are each directed to separate windows.
  86.  
  87.               INSTALLATION INSTRUCTIONS
  88.  
  89. If scm is already built (compiled) skip to secton INSTALL.
  90.  
  91. These #defines should be checked before compilation.  The first 2 can
  92. be defined either in the Makefile or scmfig.h.  See scmfig.h for more
  93. information.
  94.  
  95. Makefile    scmfig.h    note
  96. ------      ----    --------
  97. -DIMPLINIT  IMPLINIT    directory and pathname where Init.scm will
  98.             reside.
  99. -DFLOATS    FLOATS    support for inexact numerical types.  On unix
  100.             systems, FLOATS is automatically handled by
  101.             makefile.unix.
  102. -DENGNOT    ENGNOT    for engineering notation instead of scientific
  103.             notation.
  104.  
  105. DEST            directory where `make install' will put the
  106.             executable.  Unix only.
  107. MANDEST            directory where `make install' will put the
  108.             unix style manual page.  Unix only.
  109.  
  110. These #defines are automatically generated by various preprocessors.
  111. Scm uses them to find include files and the proper names for system
  112. functions.  If a define for your system type is missing on your
  113. system, put -Dflag in the Makefile or #define flag in scmfig.h.
  114.  
  115. define        note
  116. ------        --------
  117. AZTEC_C        Aztec_C 5.2a
  118. _DCC        Dice C on AMIGA
  119. __GNUC__    Gnu CC (and DJGPP)
  120. __EMX__        Gnu C port (gcc/emx 0.8e) to OS/2 2.0
  121. MWC        Mark Williams C on COHERENT
  122. _QC        Microsoft QuickC
  123. __STDC__    ANSI C compliant
  124. __TURBOC__    Turbo C and Borland C
  125. __WATCOMC__    Watcom C on MSDOS
  126. __ZTC__        Zortech C
  127.  
  128. _AIX        AIX operating system
  129. AMIGA        SAS/C 5.10 on AMIGA
  130. atarist        ATARI-ST under Gnu CC
  131. GNUDOS        DJGPP (obsolete in version 1.08)
  132. __GO32__    DJGPP (future?)
  133. hpux        HP-UX
  134. linux        Linux
  135. MCH_AMIGA    Aztec_c 5.2a on AMIGA
  136. MSDOS        Microsoft C 5.10 and 6.00A
  137. __MSDOS__    Turbo C, Borland C, and DJGPP
  138. nosve        Control Data NOS/VE
  139. SVR2        System V Revision 2.
  140. THINK_C        developement environment for the Macintosh
  141. ultrix        VAX with ULTRIX operating system.
  142. unix        most Unix and similar systems and DJGPP (!?)
  143. __unix__    Gnu CC and DJGPP
  144. _UNICOS        Cray operating system
  145. vms        (and VMS) VAX-11 C under VMS.
  146.  
  147. hp9000s800    HP RISC processor
  148. __i386__    DJGPP
  149. i386        DJGPP
  150. MULTIMAX    Encore computer
  151. pyr        Pyramid 9810 processor
  152. sparc        SPARC processor
  153. sequent        Sequent computer
  154. tahoe        CCI Tahoe processor
  155.  
  156.                   TO COMPILE
  157.  
  158. under UNIX and similar systems:
  159.   From: bos@scrg.cs.tcd.ie
  160.   New build and install scripts using GNU autoconf are available from
  161.   scmconfig.tar.gz in the distribution directories.  See README.unix
  162.   in scmconfig.tar.gz for further instructions.
  163.  
  164.   Alternatively:
  165.       cp makefile.unix Makefile
  166.   Edit Makefile to change CFLAGS, LIBS, and especially IMPLINIT.  If
  167.   you are compiling under HP-UX, see comments in Makefile (fscm.o).
  168.       make scm
  169.  
  170.   Once you have built scm (using either method) test it:
  171.       make check
  172.  
  173. under VMS:
  174.   Edit SCMFIG.H to set desired options and IMPLINIT.
  175.   Execute VMSBUILD.COM or VMSGCC.COM (for Gnu C compiler).
  176.       @VMSBUILD
  177.   Test scm
  178.       run scm
  179.       (load "test.scm")
  180.       (test-sc4)
  181.       (test-cont)
  182.       (test-inexact)
  183.  
  184. under MSDOS:
  185.   Copy the appropriate makefile to MAKEFILE:
  186.     MAKEFILE.MSC for Microsoft C,
  187.     MAKEFILE.BOR for Borland C,
  188.     MAKEFILE.TUR for Turbo C,
  189.     MAKEFILE.QC for Quick C, or
  190.     MAKEFILE.DJG for DJGPP (GCC port to i386 MSDOS).
  191.       COPY MAKEFILE.xxx MAKEFILE
  192.   Edit MAKEFILE to set desired options and IMPLINIT.
  193.       MAKE
  194.   Test scm
  195.       SCM  (GO32 SCM for DJGPP)
  196.       (load "test.scm")
  197.       (test-sc4)
  198.       (test-cont)
  199.       (test-inexact)
  200.  
  201. under OS/2 2.0
  202.   from: soravi@Athena.MIT.EDU
  203.   use *EMX* port of GNU C/C++ to OS/2 2.0 (ftp from hobbes.nmsu.edu).
  204.   Use makefile.unix.  Remove unix specific dir names.
  205.   Remove IMPLINIT from Makefile as pre-processor will not take "" as
  206.     part of "-DIMPLINIT" macro. (this is a bug with *EMX* ver 0.8d)
  207.   Remove the DFLAGS macro.
  208.   Specify all shell variables ie
  209.     SCM_INIT_PATH
  210.     SCHEME_LIBRARY_PATH
  211.     HOME
  212.   prior to running the executable.
  213.  
  214. under Think C 4.0 (or 4.1):
  215.   Edit Scmfig.H to set desired options and IMPLINIT.
  216.   from Yasuaki Honda // honda@csl.SONY.co.jp:
  217.   Make a project and add source files repl.c, time.c, scm.c, subr.c,
  218.   sys.c, eval.c, scl.c, sc2.c, and unif.c to it.
  219.   Add libraries MacTraps, unix, ANSI to the project.
  220.   The project should be segmented in the following way:
  221.     ----------
  222.     repl.c
  223.     scm.c
  224.     subr.c
  225.     sys.c
  226.     sc2.c
  227.     unif.c
  228.     time.c
  229.     ----------
  230.     MacTraps
  231.     unix
  232.     ----------
  233.     ANSI
  234.     ----------
  235.     eval.c
  236.     ----------
  237.     scl.c
  238.     ----------
  239.   Choose 'Set Project Type' from 'Project' menu.
  240.     Choose Application from radio buttons.
  241.     Set Partition size to 600K. (The default 384K is not enough).
  242.  
  243. under Aztec C 5.2a on AMIGA:
  244.   Edit makefile.aztec to set desired options and IMPLINIT.
  245.     make
  246.  
  247. under SAS/C 5.10 on AMIGA:
  248.   Edit compile.amiga to set desired options and IMPLINIT.
  249.     compile.amiga
  250.  
  251.                    INSTALL
  252.  
  253. under UNIX:
  254.  
  255.   Edit Makefile to have appropriate destinations for scm and scm.1,
  256.   DEST and MANDEST respectively.
  257.  
  258.       make install
  259.  
  260.   If IMPLINIT is not correctly defined in Makefile or scmfig.h then
  261.   you will need to define the environment variable SCM_INIT_PATH to be
  262.   the full pathname of Init.scm.  In a csh init file (.cshrc) this is
  263.   done by:
  264.       setenv SCM_INIT_PATH /usr/src/scm/Init.scm
  265.   In a .profile file this should be:
  266.       SCM_INIT_PATH=/usr/src/scm/Init.scm; export SCM_INIT_PATH
  267.  
  268.   Define the environment variable SCHEME_LIBRARY_PATH to be the full
  269.   pathname of the Scheme Library directory if you have one.  In a csh
  270.   init file (.cshrc) this is done by
  271.       setenv SCHEME_LIBRARY_PATH /usr/lib/scheme/
  272.   In a .profile file this should be:
  273.       SCHEME_LIBRARY_PATH=/usr/lib/scheme/; export SCHEME_LIBRARY_PATH
  274.  
  275. under VMS:
  276.  
  277.   Put SCM.EXE, INIT.SCM, and COPYING someplace.  INIT.SCM and COPYING
  278.   need to be in the same directory.  Either put SCM.EXE in a
  279.   SYS$SYSTEM directory or, in your LOGIN.COM file, define the symbol
  280.   SCHEME to be "$" appended to the full pathname of SCM.EXE.  For
  281.   example:
  282.       SCHEME == "$DKB100:[AGJ.SCM]SCM.EXE"
  283.  
  284.   In your LOGIN.COM file define the environment SCM_INIT_PATH to be
  285.   the full pathname of INIT.SCM.  For example:
  286.       DEFINE SCM_INIT_PATH DKB100:[AGJ.SCM]INIT.SCM
  287.   Define SCHEME_LIBRARY_PATH to be the pathname of the Scheme Library
  288.   if you have one.  For example:
  289.       DEFINE SCHEME_LIBRARY_PATH DKB100:[AGJ.SLIB]
  290.  
  291. under MSDOS:
  292.  
  293.   If you are using DJGPP do:
  294.       STRIP SCM.32
  295.       COPY /B C:\DJGPP\BIN\STUB.EXE+SCM.32 SCM.EXE
  296.  
  297.   Put SCM.EXE, INIT.SCM, and COPYING someplace.  INIT.SCM and COPYING
  298.   need to be in the same directory.  SCM.EXE needs to be in your
  299.   search path.
  300.  
  301.   In AUTOEXEC.BAT define the environment variable SCM_INIT_PATH to be
  302.   the full pathname of INIT.SCM.  For example:
  303.       SET SCM_INIT_PATH=G:\AGJ\SCM\INIT.SCM
  304.  
  305.   In AUTOEXEC.BAT define the environment variable SCHEME_LIBRARY_PATH
  306.   to be the full pathname of the Scheme Library directory if you have
  307.   one.  For example:
  308.       SET SCHEME_LIBRARY_PATH=G:\AGJ\SLIB\
  309.  
  310.              EDITING SCHEME CODE
  311.  
  312. under Gnu Emacs:
  313.   Editing of Scheme code is supported by emacs.  Buffers holding files
  314.   ending in .scm are automatically put into scheme-mode.  However, the
  315.   run-scheme (`xscheme.el') which comes included with Gnu Emacs will
  316.   work only with MIT Cscheme.
  317.  
  318.   If your Emacs can run a process in a buffer you can use the
  319.   run-scheme command with SCM when you get the emacs packages
  320.   `cmuscheme.el' and `comint.el'.  Otherwise, see "under other
  321.   systems" below.
  322.  
  323. under Epsilon (MSDOS):
  324.   There is lisp (and scheme) mode available by use of the package
  325.   `LISP.E'.  It offers several different indentation formats.  With
  326.   this package, buffers holding files ending in .L, .LSP, .S, and .SCM
  327.   (my modification) are automatically put into lisp-mode.
  328.  
  329.   It is possible to run a process in a buffer under Epsilon.  With
  330.   Epsilon 5.0 the command line options -e512 -m0 are neccessary to
  331.   manage RAM properly.  One can also call out to the editor from SCM
  332.   if RAM is at a premium; See "under other systems" below.
  333.  
  334. under other systems:
  335.   Define the environment variable "EDITOR" to be the name of the
  336.   editor you use.  The SCM procedure (ed arg1 ...) will then invoke
  337.   that editor and return to SCM when you exit the editor.  I find the
  338.   following definition very convenient:
  339.  
  340.   (define (e) (ed "work.scm") (load "work.scm"))
  341.  
  342.   Invoking (e) will then put me into the editor with the file I am
  343.   working on and load this file after I have changed it.
  344.  
  345.                TROUBLE SHOOTING
  346.  
  347.         Compiling:
  348.  
  349. FILE    ERROR or WARNING            HOW TO FIX
  350.  
  351. *.c    include file not found            Correct status of
  352.                         STDC_HEADERS
  353.  
  354.                         fix #include statement
  355.                         or add #define for
  356.                         system type to scmfig.h
  357.  
  358. scm.c    assignment between incompatible types    change SIGRETTYPE in scm.c
  359.  
  360. time.c    CLK_TCK redefined            incompatablility
  361.                         between <stdlib.h> and
  362.                         <sys/types.h>.  remove
  363.                         STDC_HEADERS in scmfig.h
  364.  
  365.                         edit <sys/types.h> to
  366.                         remove incompatability.
  367.                         
  368. sys.c    statement not reached            ignore
  369.     constant in conditional expression    ignore
  370.  
  371. sys.c: `???' undeclared, outside of functions    #undef STDC_HEADERS
  372.                         in scmfig.h
  373.  
  374. scl.c    syntax error                define system type in
  375.                         scmfig.h and scl.c (softtype)
  376.  
  377.         Linking:
  378.  
  379. ERROR or WARNING            HOW TO FIX
  380.  
  381. _sin etc. missing.            uncomment LIBS in makefile
  382.  
  383.         Running:
  384.  
  385. PROBLEM                    HOW TO FIX
  386.  
  387. Opening message and then machine    Change memory model option
  388. crashes.                to C compiler (or makefile).
  389.  
  390.                     Make sure sizet definition is
  391.                     correct in scmfig.h
  392.  
  393.                     Reduce size of HEAP_SEG_SIZE
  394.                     in setjump.h
  395.  
  396. Input hangs                #define NOSETBUF
  397.  
  398. ERROR: Could not allocate ...        Check sizet definition.
  399.  
  400.                     Get more memory.
  401.  
  402.                     Don't try to run as subproccess
  403.  
  404. ... in scmfig.h and recompile scm    Do it and recompile files.
  405.  
  406. ERROR: Init.scm not found        Assign correct IMPLINIT in
  407.                     makefile or scmfig.h or
  408.                     define environment variable
  409.                     SCM_INIT_PATH to be the full
  410.                     pathname of Init.scm (see
  411.                     INSTALLATION instructions).
  412.  
  413. WARNING: require.scm not found        define environment variable
  414.                     SCHEME_LIBRARY_PATH to be the
  415.                     full pathname of the scheme
  416.                     library or change
  417.                     library-vicinity in Init.scm
  418.                     to point to library or remove.
  419.  
  420.                     Make sure library-vicinity has
  421.                     a trailing file separator
  422.                     (like / or \).
  423.  
  424.         Testing: (load "test.scm") or (load "pi.scm") (pi 100 5)
  425.  
  426. Runs some and then machine crashes.    See above under machine
  427.                     crashes.
  428.  
  429. Runs some and then ERROR: ...        Remove optimization option
  430. (after a GC has happened)        to C compiler and recompile.
  431.  
  432.                     #define SHORT_ALIGN in scmfig.h
  433.  
  434. Some symbol names print incorrectly.    Change memory model option
  435.                     to C compiler (or makefile).
  436.  
  437.                     Check that HEAP_SEG_SIZE fits
  438.                     within sizet.
  439.  
  440.                     Increase size of HEAP_SEG_SIZE
  441.                     (or INIT_HEAP_SIZE if it is
  442.                     smaller than HEAP_SEG_SIZE).
  443.  
  444. ERROR: Rogue pointer in Heap.        See above under machine
  445.                     crashes.
  446.  
  447. Newlines don't appear correctly in    Check file mode (define OPEN_...
  448. output files.                in Init.scm
  449.  
  450. Spaces or control characters appear    Check character defines in
  451. in symbol names                scmfig.h
  452.  
  453. Negative numbers turn positive.        Check SRS in scmfig.h
  454.  
  455. VMS: Couldn't unwind stack        #define CHEAP_CONTIUATIONS
  456. VAX: botched longjmp            in scmfig.h
  457.