home *** CD-ROM | disk | FTP | other *** search
/ Dream 44 / Amiga_Dream_44.iso / RiscPc / programmation / scm4e2.arc / !Scm / docs / README < prev    next >
Text File  |  1994-11-21  |  18KB  |  509 lines
  1. This directory contains the distribution of scm4e2.  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' is for building scmlit using the `make'program.
  35.   `build.scm' is a program for compiling and linking new SCM programs.
  36.   `ccnfigdb.scm' is the database used by "build.scm" which describes
  37.     C-compilers SCM has been ported to.
  38.   `setjump.mar' provides setjmp and longjmp which do not use $unwind
  39.     utility on VMS.
  40.   `setjump.s' provides setjmp and longjmp for the Cray YMP.
  41.  
  42.   `Init.scm' is Scheme initialization code.
  43.   `Transcen.scm' has Scheme code for inexact builtin procedures.
  44.   `Link.scm' has Scheme code for compiling and dynamic linking.
  45.   `scmfig.h' is a C include file containing system dependent definitions.
  46.   `patchlvl.h is the patchlevel of this release.
  47.   `setjump.h' is an include file dealing with continuations, stacks,
  48.     and memory allocation.
  49.   `scm.h' has the data type and external definitions of scm.
  50.  
  51.   `scm.c' has the top level and interrupt code.
  52.   `time.c' has functions dealing with time.
  53.   `repl.c' has error, read-eval-print loop, read, write and load code.
  54.   `scl.c' has the code for utility functions which are not part of the
  55.     IEEE Scheme spec or which are required for non-integer
  56.     arithmetic.
  57.   `eval.c' has the evaluator, apply, map, and foreach.
  58.   `sys.c' has the code for call-with-current-continuation, opening and
  59.     closing files, storage allocation and garbage collection.
  60.   `subr.c' has all the rest of functions.
  61.   `sc2.c' has code for procedures from R2RS and R3RS not in R4RS.
  62.   `dynl.c' has c code for dynamically loading object files.
  63.   `unif.c' has code for uniform vectors.
  64.   `rgx.c' has code for string regular expression match.
  65.   `crs.c' has code for interactive terminal control.
  66.   `split.scm' sets up CURSCM (SCM with crs.c) so that input, output,
  67.     and diagnostic output are each directed to separate windows.
  68.   `record.c' has code for proposed "Record" user definable datatypes.
  69.   `gsubr.c' has make_gsubr for arbitrary (< 11) arguments to C functions.
  70.  
  71.   `ioext.c' has code for system calls in common between PC compilers and unix.
  72.   `posix.c' has code for posix library interface.
  73.   `unix.c' has code for non-posix system calls on unix systems.
  74.   `socket.c' has code for socket interface.
  75.  
  76.                  SLIB
  77.  
  78. Although SLIB is not neccessary to run SCM, I strongly suggest you
  79. obtain and install it.  Bug reports about running SCM without SLIB
  80. have very low priority.  SLIB is available from the same sites as SCM:
  81.   altdorf.ai.mit.edu:archive/scm/slib2a2.tar.gz
  82.   prep.ai.mit.edu:pub/gnu/jacal/slib2a2.tar.gz
  83.   ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a2.tar.gz
  84.   ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2a2.tar.gz
  85.  
  86.               INSTALLATION INSTRUCTIONS
  87.  
  88. These #defines should be checked before compilation.  Those with
  89. entries in the scmfig.h column can be defined either in the Makefile
  90. or scmfig.h.  See scmfig.h for more information.
  91.  
  92. Makefile    scmfig.h    note
  93. --------    --------    --------
  94. bindir            directory where `make install' will put the
  95.             executable.  Unix only.
  96. man1dir            directory where `make install' will put the
  97.             unix style manual page.  Unix only.
  98.  
  99. -DIMPLINIT  IMPLINIT    directory and pathname where Init.scm will
  100.             reside.
  101. -DFLOATS    FLOATS    support for inexact numerical types.  On unix
  102.             systems, FLOATS is automatically handled by
  103.             makefile.unix.
  104. -DENGNOT    ENGNOT    for engineering notation instead of scientific
  105.             notation.
  106. -DSUN_DL    SUN_DL    configures code in "dynl.c" to dynamic link
  107.             using the SUN dynamic linking library "dl".
  108. -DDLD        DLD        configures code in "dynl.c" to dynamic link
  109.             using the "dld" library.  You will need to get
  110.             the DLD libaray (see below).
  111.  
  112.     Notes about dynamic linking:
  113.  
  114. Dynamic linking has not been ported to all platforms.
  115. Operating systems in the BSD family (a.out binary format) can usually
  116. be ported to DLD.  The "dl" library (SUN_DL above) was a proposed
  117. POSIX standard and may be available on other machines with COFF binary
  118. format.  There are notes about porting to MSWindows and finishing the
  119. port to VMS in scm/code.doc.  The HP-UX port is complete but doesn't
  120. work on the machine available to me; shl_findsym doesn't.
  121.  
  122. DLD is a library package of C functions that performs "dynamic link
  123. editing" on Linux, VAX (Ultrix), Sun 3 (SunOS 3.4 and 4.0),
  124. SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and Atari ST.  It
  125. is available from:
  126. altdorf.ai.mit.edu:archive/scm/dld-3.2.4.src.tar.gz
  127. prep.ai.mit.edu:/pub/gnu/jacal/dld-3.2.4.src.tar.gz
  128. ftp.cs.indiana.edu:/pub/scheme-repository/imp/scm-support/dld-3.2.4.src.tar.gz
  129. tsx-11.mit.edu:/pub/linux/sources/libs/dld-src-3.2.4.tar.gz
  130. tsx-11.mit.edu:/pub/linux/binaries/libs/dld-bin-3.2.4.tar.gz (binaries)
  131.  
  132. These notes about using libdl on SunOS are from gcc.info:
  133.  
  134.   On a Sun, linking using GNU CC fails to find a shared library and
  135.   reports that the library doesn't exist at all.
  136.  
  137.   This happens if you are using the GNU linker, because it does only
  138.   static linking and looks only for unshared libraries.  If you have
  139.   a shared library with no unshared counterpart, the GNU linker
  140.   won't find anything.
  141.  
  142.   We hope to make a linker which supports Sun shared libraries, but
  143.   please don't ask when it will be finished--we don't know.
  144.  
  145.   Sun forgot to include a static version of `libdl.a' with some
  146.   versions of SunOS (mainly 4.1).  This results in undefined symbols
  147.   when linking static binaries (that is, if you use `-static').  If
  148.   you see undefined symbols `_dlclose', `_dlsym' or `_dlopen' when
  149.   linking, compile and link against the file `mit/util/misc/dlsym.c'
  150.   from the MIT version of X windows.
  151.  
  152.     Automatic Processor Defines:
  153.  
  154. These #defines are automatically generated by various preprocessors.
  155. Scm uses them to find include files and the proper names for system
  156. functions.  If a define for your system type is missing on your
  157. system, put -Dflag in the Makefile or #define flag in scmfig.h.
  158.  
  159. define        note
  160. ------        --------
  161. AZTEC_C        Aztec_C 5.2a
  162. _DCC        Dice C on AMIGA
  163. __GNUC__    Gnu CC (and DJGPP)
  164. __EMX__        Gnu C port (gcc/emx 0.8e) to OS/2 2.0
  165. __HIGHC__    MetaWare High C
  166. MWC        Mark Williams C on COHERENT
  167. _QC        Microsoft QuickC
  168. __STDC__    ANSI C compliant
  169. __TURBOC__    Turbo C and Borland C
  170. __WATCOMC__    Watcom C on MSDOS
  171. __ZTC__        Zortech C
  172.  
  173. _AIX        AIX operating system
  174. AMIGA        SAS/C 5.10 on AMIGA
  175. atarist        ATARI-ST under Gnu CC
  176. GNUDOS        DJGPP (obsolete in version 1.08)
  177. __GO32__    DJGPP (future?)
  178. hpux        HP-UX
  179. linux        Linux
  180. MCH_AMIGA    Aztec_c 5.2a on AMIGA
  181. MSDOS        Microsoft C 5.10 and 6.00A
  182. __MSDOS__    Turbo C, Borland C, and DJGPP
  183. nosve        Control Data NOS/VE
  184. SVR2        System V Revision 2.
  185. THINK_C        developement environment for the Macintosh
  186. ultrix        VAX with ULTRIX operating system.
  187. unix        most Unix and similar systems and DJGPP (!?)
  188. __unix__    Gnu CC and DJGPP
  189. _UNICOS        Cray operating system
  190. _Windows    Borland C 3.1 compiling for Windows
  191. vms        (and VMS) VAX-11 C under VMS.
  192.  
  193. hp9000s800    HP RISC processor
  194. __i386__    DJGPP
  195. i386        DJGPP
  196. MULTIMAX    Encore computer
  197. pyr        Pyramid 9810 processor
  198. sparc        SPARC processor
  199. sequent        Sequent computer
  200. tahoe        CCI Tahoe processor
  201.  
  202.                   TO COMPILE
  203.  
  204. under UNIX and similar systems:
  205.   From: bos@scrg.cs.tcd.ie
  206.   Build and install scripts using GNU autoconf are available from
  207.   scmconfig.tar.gz in the distribution directories.  See README.unix
  208.   in scmconfig.tar.gz for further instructions.
  209.  
  210.   Alternatively:
  211.   Edit Makefile to change CFLAGS, LIBS, and especially IMPLINIT.
  212.       make scmlit
  213.  
  214.   Once you have built scm (using either method) test it:
  215.       make checklit
  216.   or  make check
  217.  
  218. under VMS:
  219.   Edit SCMFIG.H to set desired options and IMPLINIT.
  220.   Execute VMSBUILD.COM or VMSGCC.COM (for Gnu C compiler).
  221.       @VMSBUILD
  222.   Test scm
  223.       run scm
  224.       (load "test.scm")
  225.       (test-sc4)
  226.       (test-cont)
  227.       (test-inexact)
  228.  
  229. under Think C 4.0 (or 4.1):
  230.   Edit Scmfig.H to set desired options and IMPLINIT.
  231.   from Yasuaki Honda // honda@csl.SONY.co.jp:
  232.   Make a project and add source files repl.c, time.c, scm.c, subr.c,
  233.   sys.c, eval.c, scl.c, sc2.c, and unif.c to it.
  234.   Add libraries MacTraps, unix, ANSI to the project.
  235.   The project should be segmented in the following way:
  236.     ----------
  237.     repl.c
  238.     scm.c
  239.     subr.c
  240.     sys.c
  241.     sc2.c
  242.     unif.c
  243.     time.c
  244.     ----------
  245.     MacTraps
  246.     unix
  247.     ----------
  248.     ANSI
  249.     ----------
  250.     eval.c
  251.     ----------
  252.     scl.c
  253.     ----------
  254.   Choose 'Set Project Type' from 'Project' menu.
  255.     Choose Application from radio buttons.
  256.     Set Partition size to 600K. (The default 384K is not enough).
  257.  
  258.                    INSTALL
  259.  
  260. under UNIX:
  261.  
  262.   Edit Makefile to have appropriate destinations for scm and scm.1,
  263.   bindir and man1dir respectively.
  264.  
  265.       make install
  266.  
  267.   If IMPLINIT is not correctly defined in Makefile or scmfig.h then
  268.   you will need to define the environment variable SCM_INIT_PATH to be
  269.   the full pathname of Init.scm.  In a csh init file (.cshrc) this is
  270.   done by:
  271.       setenv SCM_INIT_PATH /usr/src/scm/Init.scm
  272.   In a .profile file this should be:
  273.       SCM_INIT_PATH=/usr/src/scm/Init.scm; export SCM_INIT_PATH
  274.  
  275.   Define the environment variable SCHEME_LIBRARY_PATH to be the full
  276.   pathname of the Scheme Library directory if you have one.  In a csh
  277.   init file (.cshrc) this is done by
  278.       setenv SCHEME_LIBRARY_PATH /usr/lib/scheme/
  279.   In a .profile file this should be:
  280.       SCHEME_LIBRARY_PATH=/usr/lib/scheme/; export SCHEME_LIBRARY_PATH
  281.  
  282. under VMS:
  283.  
  284.   Put SCM.EXE, INIT.SCM, and COPYING someplace.  INIT.SCM and COPYING
  285.   need to be in the same directory.  Either put SCM.EXE in a
  286.   SYS$SYSTEM directory or, in your LOGIN.COM file, define the symbol
  287.   SCHEME to be "$" appended to the full pathname of SCM.EXE.  For
  288.   example:
  289.       SCHEME == "$DKB100:[AGJ.SCM]SCM.EXE"
  290.  
  291.   In your LOGIN.COM file define the environment SCM_INIT_PATH to be
  292.   the full pathname of INIT.SCM.  For example:
  293.       DEFINE SCM_INIT_PATH DKB100:[AGJ.SCM]INIT.SCM
  294.   Define SCHEME_LIBRARY_PATH to be the pathname of the Scheme Library
  295.   if you have one.  For example:
  296.       DEFINE SCHEME_LIBRARY_PATH DKB100:[AGJ.SLIB]
  297.  
  298. under MSDOS:
  299.  
  300.   If you are using DJGPP do:
  301.       STRIP SCM.32
  302.       COPY /B C:\DJGPP\BIN\STUB.EXE+SCM.32 SCM.EXE
  303.  
  304.   Put SCM.EXE, INIT.SCM, and COPYING someplace.  INIT.SCM and COPYING
  305.   need to be in the same directory.  SCM.EXE needs to be in your
  306.   search path.
  307.  
  308.   In AUTOEXEC.BAT define the environment variable SCM_INIT_PATH to be
  309.   the full pathname of INIT.SCM.  For example:
  310.       SET SCM_INIT_PATH=G:\AGJ\SCM\INIT.SCM
  311.  
  312.   In AUTOEXEC.BAT define the environment variable SCHEME_LIBRARY_PATH
  313.   to be the full pathname of the Scheme Library directory if you have
  314.   one.  For example:
  315.       SET SCHEME_LIBRARY_PATH=G:\AGJ\SLIB\
  316.  
  317.              EDITING SCHEME CODE
  318.  
  319. under Gnu Emacs:
  320.   Editing of Scheme code is supported by emacs.  Buffers holding files
  321.   ending in .scm are automatically put into scheme-mode.
  322.  
  323.   If your Emacs can run a process in a buffer you can use the Emacs
  324.   command M-x run-scheme with SCM.  However, the run-scheme
  325.   (`xscheme.el') which comes included with Gnu Emacs 18 will work only
  326.   with MIT Cscheme.  If you are using Emacs 18 get the emacs packages
  327.   `cmuscheme.el' and `comint.el' from the ftp directory
  328.     altdorf.ai.mit.edu:archive/scheme-editor-packages/;
  329.   They are already standard in Emacs 19.
  330.   
  331.   If your Emacs can not run a process in a buffer, see "under other
  332.   systems" below.
  333.  
  334. under Epsilon (MSDOS):
  335.   There is lisp (and scheme) mode available by use of the package
  336.   `LISP.E'.  It offers several different indentation formats.  With
  337.   this package, buffers holding files ending in .L, .LSP, .S, and .SCM
  338.   (my modification) are automatically put into lisp-mode.
  339.  
  340.   It is possible to run a process in a buffer under Epsilon.  With
  341.   Epsilon 5.0 the command line options -e512 -m0 are neccessary to
  342.   manage RAM properly.  It has been reported that when compiling SCM
  343.   with Turbo C, you need to `#define NOSETBUF' for proper operation in
  344.   a process buffer with Epsilon 5.0.
  345.  
  346.   One can also call out to the editor from SCM if RAM is at a premium;
  347.   See "under other systems" below.
  348.  
  349. under other systems:
  350.   Define the environment variable "EDITOR" to be the name of the
  351.   editor you use.  The SCM procedure (ed arg1 ...) will then invoke
  352.   that editor and return to SCM when you exit the editor.  I find the
  353.   following definition very convenient:
  354.  
  355.   (define (e) (ed "work.scm") (load "work.scm"))
  356.  
  357.   Invoking (e) will then put me into the editor with the file I am
  358.   working on and load this file after I have changed it.
  359.  
  360.                TROUBLE SHOOTING
  361.  
  362. Reported problems and solutions are grouped under "Compiling",
  363. "Linking", "Running", and "Testing".  If you don't find your problem
  364. listed here, please send a bug report to <jaffer@ai.mit.edu> or
  365. <bug-scm@scrg.cs.tcd.ie>.  The bug report should include:
  366.  
  367.  * The version of SCM (printed when SCM is invoked with no arguments).
  368.  
  369.  * The type of computer you are using.
  370.  
  371.  * The name and version of your computer's operating system.
  372.  
  373.  * The values of the environment variables SCM_INIT_PATH and
  374.    SCHEME_LIBRARY_PATH.
  375.  
  376.  * The name and version of your C compiler.
  377.  
  378.  * If you are using an executable from a distribution, the name,
  379.    vendor, and date of that distribution.  In this case,
  380.    corresponding with the vendor is recommended.
  381.  
  382.  
  383.         Compiling:
  384.  
  385. FILE    ERROR or WARNING            HOW TO FIX
  386.  
  387. *.c    include file not found            Correct status of
  388.                         STDC_HEADERS
  389.  
  390.                         fix #include statement
  391.                         or add #define for
  392.                         system type to scmfig.h
  393.  
  394. scm.c    assignment between incompatible types    change SIGRETTYPE in scm.c
  395.  
  396. time.c    CLK_TCK redefined            incompatablility
  397.                         between <stdlib.h> and
  398.                         <sys/types.h>.  remove
  399.                         STDC_HEADERS in scmfig.h
  400.  
  401.                         edit <sys/types.h> to
  402.                         remove incompatability.
  403.                         
  404. sys.c    statement not reached            ignore
  405.     constant in conditional expression    ignore
  406.  
  407. sys.c: `???' undeclared, outside of functions    #undef STDC_HEADERS
  408.                         in scmfig.h
  409.  
  410. scl.c    syntax error                define system type in
  411.                         scmfig.h and scl.c (softtype)
  412.  
  413.         Linking:
  414.  
  415. ERROR or WARNING            HOW TO FIX
  416.  
  417. _sin etc. missing.            uncomment LIBS in makefile
  418.  
  419.         Running:
  420.  
  421. PROBLEM                    HOW TO FIX
  422.  
  423. Opening message and then machine    Change memory model option
  424. crashes.                to C compiler (or makefile).
  425.  
  426.                     Make sure sizet definition is
  427.                     correct in scmfig.h
  428.  
  429.                     Reduce size of HEAP_SEG_SIZE
  430.                     in setjump.h
  431.  
  432. Input hangs                #define NOSETBUF
  433.  
  434. ERROR: heap: need larger initial    Need to increase the initial
  435.                     heap allocation using
  436.                     -a<kbytes> or INIT_HEAP_SIZE.
  437.  
  438. ERROR: Could not allocate ...        Check sizet definition.
  439.  
  440.                     Get more memory.
  441.  
  442.                     Don't try to run as subproccess
  443.  
  444. ... in scmfig.h and recompile scm    Do it and recompile files.
  445.  
  446. ERROR: Init.scm not found        Assign correct IMPLINIT in
  447.                     makefile or scmfig.h or
  448.                     define environment variable
  449.                     SCM_INIT_PATH to be the full
  450.                     pathname of Init.scm (see
  451.                     INSTALLATION instructions).
  452.  
  453. WARNING: require.scm not found        define environment variable
  454.                     SCHEME_LIBRARY_PATH to be the
  455.                     full pathname of the scheme
  456.                     library SLIB or change
  457.                     library-vicinity in Init.scm
  458.                     to point to library or remove.
  459.                     See section SLIB above.
  460.  
  461.                     Make sure library-vicinity has
  462.                     a trailing file separator
  463.                     (like / or \).
  464.  
  465.         Testing: (load "test.scm") or (load "pi.scm") (pi 100 5)
  466.  
  467. Runs some and then machine crashes.    See above under machine
  468.                     crashes.
  469.  
  470. Runs some and then ERROR: ...        Remove optimization option
  471. (after a GC has happened)        to C compiler and recompile.
  472.  
  473.                     #define SHORT_ALIGN in scmfig.h
  474.  
  475. Some symbol names print incorrectly.    Change memory model option
  476.                     to C compiler (or makefile).
  477.  
  478.                     Check that HEAP_SEG_SIZE fits
  479.                     within sizet.
  480.  
  481.                     Increase size of HEAP_SEG_SIZE
  482.                     (or INIT_HEAP_SIZE if it is
  483.                     smaller than HEAP_SEG_SIZE).
  484.  
  485. ERROR: Rogue pointer in Heap.        See above under machine
  486.                     crashes.
  487.  
  488. Newlines don't appear correctly in    Check file mode (define OPEN_...
  489. output files.                in Init.scm
  490.  
  491. Spaces or control characters appear    Check character defines in
  492. in symbol names                scmfig.h
  493.  
  494. Negative numbers turn positive.        Check SRS in scmfig.h
  495.  
  496. VMS: Couldn't unwind stack        #define CHEAP_CONTIUATIONS
  497. VAX: botched longjmp            in scmfig.h
  498.  
  499. Sparc(SUN-4) heap is growing out of control:
  500.  
  501.     You are experiencing a GC problem peculiar to the Sparc.  The
  502.     problem is that SCM doesn't know how to clear register
  503.     windows.  Every location which is not reused still gets marked
  504.     at GC time.  This causes lots of stuff which should be
  505.     collected to not be.  This will be a problem with any
  506.     "conservative" GC until we find what instruction will clear
  507.     the register windows.  This problem is exacerbated by using
  508.     lots of call-with-current-continuations.
  509.