"Fossies" - the Fresh Open Source Software Archive

Member "scm/README" (16 Feb 2020, 43799 Bytes) of package /linux/privat/scm-5f3.zip:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 5f2_vs_5f3.

    1 This directory contains the distribution of scm5f3.  SCM conforms to
    2 Revised^5 Report on the Algorithmic Language Scheme and the IEEE P1178
    3 specification.  SCM runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2,
    4 NOS/VE, Unicos, VMS, Unix and similar systems.  SCM supports the SLIB
    5 Scheme library; both SCM and SLIB are GNU packages.
    7                <http://people.csail.mit.edu/jaffer/SCM>
    9 1 Manifest
   10 ==========
   12 '.gdbinit'       provides commands for debugging SCM with GDB
   15 'ChangeLog'      changes to SCM.
   16 'Idiffer.scm'    Linear-space O(PN) sequence comparison.
   17 'Iedline.scm'    Gnu readline input editing.
   18 'Init.scm'       Scheme initialization.
   19 'Link.scm'       Dynamic link/loading.
   20 'Macro.scm'      Supports Syntax-Rules Macros.
   21 'Makefile'       builds SCMLIT using the 'make' program.
   22 'QUICKREF'       Quick Reference card for R4RS and IEEE Scheme.
   23 'README'         contains a MANIFEST, INSTALLATION INSTRUCTIONS, hints
   24                  for EDITING SCHEME CODE, and a TROUBLE SHOOTING GUIDE.
   25 'Transcen.scm'   inexact builtin procedures.
   26 'bench.scm'      computes and records performance statistics of pi.scm.
   27 'build.bat'      invokes build.scm for MS-DOS
   28 'build.scm'      database for compiling and linking new SCM programs.
   29 'byte.c'         strings as bytes.
   30 'bytenumb.c'     Byte-number conversions.
   31 'compile.scm'    Hobbit compilation to C.
   32 'continue-ia64.S'replaces make_root_continuation(),
   33                  make_continuation(), and dynthrow() in continue.c
   34 'continue.c'     continuations.
   35 'continue.h'     continuations.
   36 'crs.c'          interactive terminal control.
   37 'debug.c'        debugging, printing code.
   38 'differ.c'       Linear-space O(PN) sequence comparison.
   39 'dynl.c'         dynamically load object files.
   40 'ecrt0.c'        discover the start of initialized data space
   41                  dynamically at runtime.
   42 'edline.c'       Gnu readline input editing (get
   43                  ftp.sys.toronto.edu:/pub/rc/editline.shar).
   44 'eval.c'         evaluator, apply, map, and foreach.
   45 'example.scm'    example from R4RS which uses inexact numbers.
   46 'fdl.texi'       GNU Free Documentation License.
   47 'findexec.c'     find the executable file function.
   48 'get-contoffset-ia64.c'makes contoffset-ia64.S for inclusion by
   49                  continue-ia64.S
   50 'gmalloc.c'      Gnu malloc(); used for unexec.
   51 'gsubr.c'        make_gsubr for arbitrary (< 11) arguments to C
   52                  functions.
   53 'ioext.c'        system calls in common between PC compilers and unix.
   54 'lastfile.c'     find the point in data space between data and
   55                  libraries.
   56 'macosx-config.h'Included by unexmacosx.c and lastfile.c.
   57 'mkimpcat.scm'   build SCM-specific catalog for SLIB.
   58 'patchlvl.h'     patchlevel of this release.
   59 'pi.c'           computes digits of pi [cc -o pi pi.c;time pi 100 5].
   60 'pi.scm'         computes digits of pi [type (pi 100 5)].  Test
   61                  performance against pi.c.
   62 'posix.c'        posix library interface.
   63 'pre-crt0.c'     loaded before crt0.o on machines which do not remap
   64                  part of the data space into text space in unexec.
   65 'r4rstest.scm'   tests conformance with Scheme specifications.
   66 'ramap.c'        array mapping
   67 'record.c'       proposed 'Record' user definable datatypes.
   68 'repl.c'         error, read-eval-print loop, read, write and load.
   69 'rgx.c'          string regular expression match.
   70 'rope.c'         C interface functions.
   71 'sc2.c'          procedures from R2RS and R3RS not in R4RS.
   72 'scl.c'          inexact arithmetic
   73 'scm.1'          unix style man page.
   74 'scm.c'          initialization, interrupts, and non-IEEE utility
   75                  functions.
   76 'scm.doc'        man page generated from scm.1.
   77 'scm.h'          data type and external definitions of SCM.
   78 'scm.texi'       SCM installation and use.
   79 'scmfig.h'       contains system dependent definitions.
   80 'scmmain.c'      initialization, interrupts, and non-IEEE utility
   81                  functions.
   82 'script.c'       utilities for running as '#!'  script.
   83 'setjump.h'      continuations, stacks, and memory allocation.
   84 'setjump.mar'    provides setjump and longjump which do not use $unwind
   85                  utility on VMS.
   86 'setjump.s'      provides setjump and longjump for the Cray YMP.
   87 'socket.c'       BSD socket interface.
   88 'split.scm'      example use of crs.c.  Input, output, and diagnostic
   89                  output directed to separate windows.
   90 'subr.c'         the rest of IEEE functions.
   91 'sys.c'          call-with-current-continuation, opening and closing
   92                  files, storage allocation and garbage collection.
   93 'time.c'         functions dealing with time.
   94 'ugsetjump.s'    provides setjump and longjump which work on Ultrix
   95                  VAX.
   96 'unexalpha.c'    Convert a running program into an Alpha executable
   97                  file.
   98 'unexec.c'       Convert a running program into an executable file.
   99 'unexelf.c'      Convert a running ELF program into an executable file.
  100 'unexhp9k800.c'  Convert a running HP-UX program into an executable
  101                  file.
  102 'unexmacosx.c'   Convert a running program into an executable file
  103                  under MacOS X.
  104 'unexsgi.c'      Convert a running program into an IRIX executable
  105                  file.
  106 'unexsunos4.c'   Convert a running program into an executable file.
  107 'unif.c'         uniform vectors.
  108 'unix.c'         non-posix system calls on unix systems.
  111 File: scm-5f3.info,  Node: Distributions,  Next: GNU configure and make,  Prev: Installing SCM,  Up: Installing SCM
  113 2.1 Distributions
  114 =================
  116 The SCM homepage contains links to precompiled binaries and source
  117 distributions.
  119 Downloads and instructions for installing the precompiled binaries are
  120 at <http://people.csail.mit.edu/jaffer/SCM#QuickStart>.
  122 If there is no precompiled binary for your platform, you may be able to
  123 build from the source distribution.  The rest of these instructions deal
  124 with building and installing SCM and SLIB from sources.
  126 Download (both SCM and SLIB of) either the last release or current
  127 development snapshot from
  128 <http://people.csail.mit.edu/jaffer/SCM#BuildFromSource>.
  130 Unzip both the SCM and SLIB zips.  For example, if you are working in
  131 '/usr/local/src/', this will create directories '/usr/local/src/scm/'
  132 and '/usr/local/src/slib/'.
  136 File: scm-5f3.info,  Node: GNU configure and make,  Next: Building SCM,  Prev: Distributions,  Up: Installing SCM
  138 2.2 GNU configure and make
  139 ==========================
  141 'scm/configure' and 'slib/configure' are Shell scripts which create the
  142 files 'scm/config.status' and 'slib/config.status' on Unix and MinGW
  143 systems.
  145 The 'config.status' files are used (included) by the Makefile to control
  146 where the packages will be installed by 'make install'.  With GNU shell
  147 (bash) and utilities, the following commands should build and install
  148 SCM and SLIB:
  150      bash$ (cd slib; ./configure --prefix=/usr/local/)
  151      bash$ (cd scm
  152      > ./configure --prefix=/usr/local/
  153      > make scmlit
  154      > sudo make all
  155      > sudo make install)
  156      bash$ (cd slib; sudo make install)
  158 If the install commands worked, skip to *note Testing::.
  160 If 'configure' doesn't work on your system, make 'scm/config.status' and
  161 'slib/config.status' be empty files.
  163 For additional help on using the 'configure' script, run
  164 './configure --help'.
  166 'make all' will attempt to create a dumped executable (*note Saving
  167 Executable Images::), which has very small startup latency.  If that
  168 fails, it will try to compile an ordinary 'scm' executable.
  170 Note that the compilation output may contain error messages; be
  171 concerned only if the 'make install' transcripts contain errors.
  173 'sudo' runs the command after it as user "root".  On recent GNU/Linux
  174 systems, dumping requires that 'make all' be run as user root; hence the
  175 use of 'sudo'.
  177 'make install' requires root privileges if you are installing to
  178 standard Unix locations as specified to (or defaulted by) './configure'.
  179 Note that this is independent of whether you did 'sudo make all' or
  180 'make all'.
  182 * Menu:
  184 * Making scmlit::
  185 * Makefile targets::
  189 File: scm-5f3.info,  Node: Making scmlit,  Next: Makefile targets,  Prev: GNU configure and make,  Up: GNU configure and make
  191 2.2.1 Making scmlit
  192 -------------------
  194 The SCM distribution 'Makefile' contains rules for making "scmlit", a
  195 "bare-bones" version of SCM sufficient for running 'build'.  'build' is
  196 a Scheme program used to compile (or create scripts to compile) full
  197 featured versions of SCM (*note Building SCM::).  To create scmlit, run
  198 'make scmlit' in the 'scm/' directory.
  200 Makefiles are not portable to the majority of platforms.  If you need to
  201 compile SCM without 'scmlit', there are several ways to proceed:
  203    * Use the build (http://people.csail.mit.edu/jaffer/buildscm.html)
  204      web page to create custom batch scripts for compiling SCM.
  206    * Use SCM on a different platform to run 'build' to create a script
  207      to build SCM;
  209    * Use another implementation of Scheme to run 'build' to create a
  210      script to build SCM;
  212    * Create your own script or 'Makefile'.
  214 Finding SLIB
  215 ------------
  217 If you didn't create scmlit using 'make scmlit', then you must create a
  218 file named 'scm/require.scm'.  For most installations, 'scm/require.scm'
  219 can just be copied from 'scm/requires.scm', which is part of the SCM
  220 distribution.
  222 If, when executing 'scmlit' or 'scm', you get a message like:
  224      ERROR: "LOAD couldn't find file " "/usr/local/src/scm/require"
  226 then create a file 'require.scm' in the SCM "implementation-vicinity"
  227 (this is the same directory as where the file 'Init5f2.scm' is).
  228 'require.scm' should have the contents:
  230      (define (library-vicinity) "/usr/local/lib/slib/")
  232 where the pathname string '/usr/local/lib/slib/' is to be replaced by
  233 the pathname into which you unzipped (or installed) SLIB.
  235 Alternatively, you can set the (shell) environment variable
  236 'SCHEME_LIBRARY_PATH' to the pathname of the SLIB directory (*note
  237 SCHEME_LIBRARY_PATH: SCM Variables.).  If set, this environment variable
  238 overrides 'scm/require.scm'.
  240 Absolute pathnames are recommended here; if you use a relative pathname,
  241 SLIB can get confused when the working directory is changed (*note
  242 chmod: I/O-Extensions.).  The way to specify a relative pathname is to
  243 append it to the implementation-vicinity, which is absolute:
  245      (define library-vicinity
  246        (let ((lv (string-append (implementation-vicinity) "../slib/")))
  247          (lambda () lv)))
  251 File: scm-5f3.info,  Node: Makefile targets,  Prev: Making scmlit,  Up: GNU configure and make
  253 2.2.2 Makefile targets
  254 ----------------------
  256 Each of the following four 'make' targets creates an executable named
  257 'scm'.  Each target takes its build options from a file with an '.opt'
  258 suffix.  If that options file doesn't exist, making that target will
  259 create the file with the '-F' features: cautious, bignums, arrays,
  260 inexact, engineering-notation, and dynamic-linking.  Once that '.opt'
  261 file exists, you can edit it to your taste and it will be preserved.
  263 'make scm4'
  264      Produces a R4RS executable named 'scm' lacking hygienic macros (but
  265      with defmacro).  The build options are taken from 'scm4.opt'.  If
  266      build or the executable fails, try removing 'dynamic-linking' from
  267      'scm4.opt'.
  269 'make scm5'
  270      R5RS; like 'make scm4' but with '-F macro'.  The build options are
  271      taken from 'scm5.opt'.  If build or the executable fails, try
  272      removing 'dynamic-linking' from 'scm5.opt'.
  274 'make dscm4'
  275      Produces a R4RS executable named 'udscm4', which it starts and
  276      dumps to a low startup latency executable named 'scm'.  The build
  277      options are taken from 'udscm4.opt'.
  279      If the build fails, then 'build scm4' instead.  If the dumped
  280      executable fails to run, then send me a bug report (and use
  281      'build scm4' until the problem with dump is corrected).
  283 'make dscm5'
  284      Like 'make dscm4' but with '-F macro'.  The build options are taken
  285      from 'udscm5.opt'.
  287      If the build fails, then 'build scm5' instead.  If the dumped
  288      executable fails to run, then send me a bug report (and use
  289      'build scm5' until the problem with dump is corrected).
  291 If the above builds fail because of '-F dynamic-linking', then (because
  292 they can't be dynamically linked) you will likely want to add some other
  293 features to the build's '.opt' file.  See the '-F' build option in *note
  294 Build Options::.
  296 If dynamic-linking is working, then you will likely want to compile most
  297 of the modules as "DLL"s.  The build options for compiling DLLs are in
  298 'dlls.opt'.
  300 'make x.so'
  301      The 'Xlib' module; *note SCM Language X Interface: (Xlibscm)Top.
  303 'make myturtle'
  304      Creates a DLL named 'turtlegr.so' which is a simple graphics API.
  306 'make wbscm.so'
  307      The 'wb' module; *note B-tree database implementation: (wb)Top.
  308      Compiling this requires that wb source be in a peer directory to
  309      scm.
  311 'make dlls'
  312      Compiles all the distributed library modules, but not 'wbscm.so'.
  313      Many of the module compiles are recursively invoked in such a way
  314      that failure of one (which could be due to a system library not
  315      being installed) doesn't cause the top-level 'make dlls' to fail.
  316      If 'make dlls' fails as a whole, it is time to submit a bug report
  317      (*note Reporting Problems::).
  321 File: scm-5f3.info,  Node: Building SCM,  Next: Saving Executable Images,  Prev: GNU configure and make,  Up: Installing SCM
  323 2.3 Building SCM
  324 ================
  326 The file "build" loads the file "build.scm", which constructs a
  327 relational database of how to compile and link SCM executables.
  328 'build.scm' has information for the platforms which SCM has been ported
  329 to (of which I have been notified).  Some of this information is old,
  330 incorrect, or incomplete.  Send corrections and additions to
  331 agj@alum.mit.edu.
  333 * Menu:
  335 * Invoking Build::
  336 * Build Options::               build -help
  337 * Compiling and Linking Custom Files::
  341 File: scm-5f3.info,  Node: Invoking Build,  Next: Build Options,  Prev: Building SCM,  Up: Building SCM
  343 2.3.1 Invoking Build
  344 --------------------
  346 This section teaches how to use 'build', a Scheme program for creating
  347 compilation scripts to produce SCM executables and library modules.  The
  348 options accepted by 'build' are documented in *note Build Options::.
  350 Use the _any_ method if you encounter problems with the other two
  351 methods (MS-DOS, Unix).
  353 MS-DOS
  354      From the SCM source directory, type 'build' followed by up to 9
  355      command line arguments.
  357 Unix
  358      From the SCM source directory, type './build' followed by command
  359      line arguments.
  361 _any_
  362      From the SCM source directory, start 'scm' or 'scmlit' and type
  363      '(load "build")'.  Alternatively, start 'scm' or 'scmlit' with the
  364      command line argument '-ilbuild'.  This method will also work for
  365      MS-DOS and Unix.
  367      After loading various SLIB modules, the program will print:
  369           type (b "build <command-line>") to build
  370           type (b*) to enter build command loop
  372      The 'b*' procedure enters into a "build shell" where you can enter
  373      commands (with or without the 'build').  Blank lines are ignored.
  374      To create a build script with all defaults type 'build'.
  376      If the build-shell encouters an error, you can reenter the
  377      build-shell by typing '(b*)'.  To exit scm type '(quit)'.
  379 Here is a transcript of an interactive (b*) build-shell.
  381      bash$ scmlit
  382      SCM version 5e7, Copyright (C) 1990-2006 Free Software Foundation.
  383      SCM comes with ABSOLUTELY NO WARRANTY; for details type `(terms)'.
  384      This is free software, and you are welcome to redistribute it
  385      under certain conditions; type `(terms)' for details.
  386      > (load "build")
  387      ;loading build
  388      ;  loading /home/jaffer/slib/getparam
  389      ;    loading /home/jaffer/slib/coerce
  390      ...
  391      ;  done loading build.scm
  392      type (b "build <command-line>") to build
  393      type (b*) to enter build command loop
  394      ;done loading build
  395      #<unspecified>
  396      > (b*)
  397      ;loading /home/jaffer/slib/comparse
  398      ;done loading /home/jaffer/slib/comparse.scm
  399      build> -t exe
  400      #! /bin/sh
  401      # unix (linux) script created by SLIB/batch Wed Oct 26 17:14:23 2011
  402      # [-p linux]
  403      # ================ Write file with C defines
  404      rm -f scmflags.h
  405      echo '#define IMPLINIT "Init5e7.scm"'>>scmflags.h
  406      echo '#define BIGNUMS'>>scmflags.h
  407      echo '#define FLOATS'>>scmflags.h
  408      echo '#define ARRAYS'>>scmflags.h
  409      # ================ Compile C source files
  410      gcc -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c
  411      # ================ Link C object files
  412      gcc -rdynamic -o scm continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o -lm -lc
  413      "scm"
  414      build> -t exe -w myscript.sh
  415      "scm"
  416      build> (quit)
  418 No compilation was done.  The '-t exe' command shows the compile script.
  419 The '-t exe -w myscript.sh' line creates a file 'myscript.sh' containing
  420 the compile script.  To actually compile and link it, type
  421 './myscript.sh'.
  423 Invoking build without the '-F' option will build or create a shell
  424 script with the 'arrays', 'inexact', and 'bignums' options as defaults.
  425 Invoking 'build' with '-F lit -o scmlit' will make a script for
  426 compiling 'scmlit'.
  428      bash$ ./build
  429      -|
  430      #! /bin/sh
  431      # unix (linux) script created by SLIB/batch
  432      # ================ Write file with C defines
  433      rm -f scmflags.h
  434      echo '#define IMPLINIT "Init5f2.scm"'>>scmflags.h
  435      echo '#define BIGNUMS'>>scmflags.h
  436      echo '#define FLOATS'>>scmflags.h
  437      echo '#define ARRAYS'>>scmflags.h
  438      # ================ Compile C source files
  439      gcc -O2 -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c
  440      # ================ Link C object files
  441      gcc -rdynamic -o scm continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o -lm -lc
  443 To cross compile for another platform, invoke build with the '-p' or
  444 '--platform=' option.  This will create a script for the platform named
  445 in the '-p' or '--platform=' option.
  447      bash$ ./build -o scmlit -p darwin -F lit
  448      -|
  449      #! /bin/sh
  450      # unix (darwin) script created by SLIB/batch
  451      # ================ Write file with C defines
  452      rm -f scmflags.h
  453      echo '#define IMPLINIT "Init5f2.scm"'>>scmflags.h
  454      # ================ Compile C source files
  455      cc -O3 -c continue.c scm.c scmmain.c findexec.c script.c time.c repl.c scl.c eval.c sys.c subr.c debug.c unif.c rope.c
  456      # ================ Link C object files
  457      mv -f scmlit scmlit~
  458      cc -o scmlit continue.o scm.o scmmain.o findexec.o script.o time.o repl.o scl.o eval.o sys.o subr.o debug.o unif.o rope.o
  462 File: scm-5f3.info,  Node: Build Options,  Next: Compiling and Linking Custom Files,  Prev: Invoking Build,  Up: Building SCM
  464 2.3.2 Build Options
  465 -------------------
  467 The options to "build" specify what, where, and how to build a SCM
  468 program or dynamically linked module.  These options are unrelated to
  469 the SCM command line options.
  471  -- Build Option: -p PLATFORM-NAME
  472  -- Build Option: ---platform=PLATFORM-NAME
  473      specifies that the compilation should be for a
  474      computer/operating-system combination called PLATFORM-NAME.  _Note_
  475      The case of PLATFORM-NAME is distinguised.  The current
  476      PLATFORM-NAMEs are all lower-case.
  478      The platforms defined by table "platform" in 'build.scm' are:
  479      Table: platform
  480      name              processor         operating-system  compiler
  481      #f                processor-family  operating-system  #f
  482      symbol            processor-family  operating-system  symbol
  483      symbol            symbol            symbol            symbol
  484      ================= ================= ================= =================
  485      *unknown*         *unknown*         unix              cc
  486      acorn-unixlib     acorn             *unknown*         cc
  487      aix               powerpc           aix               cc
  488      alpha-elf         alpha             unix              cc
  489      alpha-linux       alpha             linux             gcc
  490      amiga-aztec       m68000            amiga             cc
  491      amiga-dice-c      m68000            amiga             dcc
  492      amiga-gcc         m68000            amiga             gcc
  493      amiga-sas         m68000            amiga             lc
  494      atari-st-gcc      m68000            atari-st          gcc
  495      atari-st-turbo-c  m68000            atari-st          tcc
  496      borland-c         i8086             ms-dos            bcc
  497      darwin            powerpc           unix              cc
  498      djgpp             i386              ms-dos            gcc
  499      freebsd           *unknown*         unix              cc
  500      gcc               *unknown*         unix              gcc
  501      gnu-win32         i386              unix              gcc
  502      highc             i386              ms-dos            hc386
  503      hp-ux             hp-risc           hp-ux             cc
  504      irix              mips              irix              gcc
  505      linux             *unknown*         linux             gcc
  506      linux-aout        i386              linux             gcc
  507      linux-ia64        ia64              linux             gcc
  508      microsoft-c       i8086             ms-dos            cl
  509      microsoft-c-nt    i386              ms-dos            cl
  510      microsoft-quick-c i8086             ms-dos            qcl
  511      ms-dos            i8086             ms-dos            cc
  512      netbsd            *unknown*         unix              gcc
  513      openbsd           *unknown*         unix              gcc
  514      os/2-cset         i386              os/2              icc
  515      os/2-emx          i386              os/2              gcc
  516      osf1              alpha             unix              cc
  517      plan9-8           i386              plan9             8c
  518      sunos             sparc             sunos             cc
  519      svr4              *unknown*         unix              cc
  520      svr4-gcc-sun-ld   sparc             sunos             gcc
  521      turbo-c           i8086             ms-dos            tcc
  522      unicos            cray              unicos            cc
  523      unix              *unknown*         unix              cc
  524      vms               vax               vms               cc
  525      vms-gcc           vax               vms               gcc
  526      watcom-9.0        i386              ms-dos            wcc386p
  528  -- Build Option: -f PATHNAME
  529      specifies that the build options contained in PATHNAME be spliced
  530      into the argument list at this point.  The use of option files can
  531      separate functional features from platform-specific ones.
  533      The 'Makefile' calls out builds with the options in '.opt' files:
  535      'dlls.opt'
  536           Options for Makefile targets dlls, myturtle, and x.so.
  537      'gdb.opt'
  538           Options for udgdbscm and gdbscm.
  539      'libscm.opt'
  540           Options for libscm.a.
  541      'pg.opt'
  542           Options for pgscm, which instruments C functions.
  543      'udscm4.opt'
  544           Options for targets udscm4 and dscm4 (scm).
  545      'udscm5.opt'
  546           Options for targets udscm5 and dscm5 (scm).
  548      The Makefile creates options files it depends on only if they do
  549      not already exist.
  551  -- Build Option: -o FILENAME
  552  -- Build Option: ---outname=FILENAME
  553      specifies that the compilation should produce an executable or
  554      object name of FILENAME.  The default is 'scm'.  Executable
  555      suffixes will be added if neccessary, e.g.  'scm' => 'scm.exe'.
  557  -- Build Option: -l LIBNAME ...
  558  -- Build Option: ---libraries=LIBNAME
  559      specifies that the LIBNAME should be linked with the executable
  560      produced.  If compile flags or include directories ('-I') are
  561      needed, they are automatically supplied for compilations.  The 'c'
  562      library is always included.  SCM "features" specify any libraries
  563      they need; so you shouldn't need this option often.
  565  -- Build Option: -D DEFINITION ...
  566  -- Build Option: ---defines=DEFINITION
  567      specifies that the DEFINITION should be made in any C source
  568      compilations.  If compile flags or include directories ('-I') are
  569      needed, they are automatically supplied for compilations.  SCM
  570      "features" specify any flags they need; so you shouldn't need this
  571      option often.
  573  -- Build Option: ---compiler-options=FLAG
  574      specifies that that FLAG will be put on compiler command-lines.
  576  -- Build Option: ---linker-options=FLAG
  577      specifies that that FLAG will be put on linker command-lines.
  579  -- Build Option: -s PATHNAME
  580  -- Build Option: ---scheme-initial=PATHNAME
  581      specifies that PATHNAME should be the default location of the SCM
  582      initialization file 'Init5f2.scm'.  SCM tries several likely
  583      locations before resorting to PATHNAME (*note File-System
  584      Habitat::).  If not specified, the current directory (where build
  585      is building) is used.
  587  -- Build Option: -c PATHNAME ...
  588  -- Build Option: ---c-source-files=PATHNAME
  589      specifies that the C source files PATHNAME ... are to be compiled.
  591  -- Build Option: -j PATHNAME ...
  592  -- Build Option: ---object-files=PATHNAME
  593      specifies that the object files PATHNAME ... are to be linked.
  595  -- Build Option: -i CALL ...
  596  -- Build Option: ---initialization=CALL
  597      specifies that the C functions CALL ... are to be invoked during
  598      initialization.
  600  -- Build Option: -t BUILD-WHAT
  601  -- Build Option: ---type=BUILD-WHAT
  602      specifies in general terms what sort of thing to build.  The
  603      choices are:
  604      'exe'
  605           executable program.
  606      'lib'
  607           library module.
  608      'dlls'
  609           archived dynamically linked library object files.
  610      'dll'
  611           dynamically linked library object file.
  613      The default is to build an executable.
  615  -- Build Option: -h BATCH-SYNTAX
  616  -- Build Option: --batch-dialect=BATCH-SYNTAX
  617      specifies how to build.  The default is to create a batch file for
  618      the host system.  The SLIB file 'batch.scm' knows how to create
  619      batch files for:
  620         * unix
  621         * dos
  622         * vms
  623         * amigaos (was amigados)
  624         * system
  626           This option executes the compilation and linking commands
  627           through the use of the 'system' procedure.
  628         * *unknown*
  630           This option outputs Scheme code.
  632  -- Build Option: -w BATCH-FILENAME
  633  -- Build Option: --script-name=BATCH-FILENAME
  634      specifies where to write the build script.  The default is to
  635      display it on '(current-output-port)'.
  637  -- Build Option: -F FEATURE ...
  638  -- Build Option: ---features=FEATURE
  639      specifies to build the given features into the executable.  The
  640      defined features are:
  642      "array"
  643           Alias for ARRAYS
  645      "array-for-each"
  646           array-map!  and array-for-each (arrays must also be featured).
  648      "arrays"
  649           Use if you want arrays, uniform-arrays and uniform-vectors.
  651      "bignums"
  652           Large precision integers.
  654      "byte"
  655           Treating strings as byte-vectors.
  657      "byte-number"
  658           Byte/number conversions
  660      "careful-interrupt-masking"
  661           Define this for extra checking of interrupt masking and some
  662           simple checks for proper use of malloc and free.  This is for
  663           debugging C code in 'sys.c', 'eval.c', 'repl.c' and makes the
  664           interpreter several times slower than usual.
  666      "cautious"
  667           Normally, the number of arguments arguments to interpreted
  668           closures (from LAMBDA) are checked if the function part of a
  669           form is not a symbol or only the first time the form is
  670           executed if the function part is a symbol.  defining
  671           'reckless' disables any checking.  If you want to have SCM
  672           always check the number of arguments to interpreted closures
  673           define feature 'cautious'.
  675      "cheap-continuations"
  676           If you only need straight stack continuations, executables
  677           compile with this feature will run faster and use less storage
  678           than not having it.  Machines with unusual stacks _need_ this.
  679           Also, if you incorporate new C code into scm which uses VMS
  680           system services or library routines (which need to unwind the
  681           stack in an ordrly manner) you may need to use this feature.
  683      "compiled-closure"
  684           Use if you want to use compiled closures.
  686      "curses"
  687           For the "curses" screen management package.
  689      "debug"
  690           Turns on the features 'cautious' and
  691           'careful-interrupt-masking'; uses '-g' flags for debugging SCM
  692           source code.
  694      "differ"
  695           Sequence comparison
  697      "dont-memoize-locals"
  698           SCM normally converts references to local variables to ILOCs,
  699           which make programs run faster.  If SCM is badly broken, try
  700           using this option to disable the MEMOIZE_LOCALS feature.
  702      "dump"
  703           Convert a running scheme program into an executable file.
  705      "dynamic-linking"
  706           Be able to load compiled files while running.
  708      "edit-line"
  709           interface to the editline or GNU readline library.
  711      "engineering-notation"
  712           Use if you want floats to display in engineering notation
  713           (exponents always multiples of 3) instead of scientific
  714           notation.
  716      "generalized-c-arguments"
  717           'make_gsubr' for arbitrary (< 11) arguments to C functions.
  719      "i/o-extensions"
  720           Commonly available I/O extensions: "exec", line I/O, file
  721           positioning, file delete and rename, and directory functions.
  723      "inexact"
  724           Use if you want floating point numbers.
  726      "lit"
  727           Lightweight - no features
  729      "macro"
  730           C level support for hygienic and referentially transparent
  731           macros (syntax-rules macros).
  733      "mysql"
  734           Client connections to the mysql databases.
  736      "no-heap-shrink"
  737           Use if you want segments of unused heap to not be freed up
  738           after garbage collection.  This may increase time in GC for
  739           *very* large working sets.
  741      "none"
  742           No features
  744      "posix"
  745           Posix functions available on all "Unix-like" systems.  fork
  746           and process functions, user and group IDs, file permissions,
  747           and "link".
  749      "reckless"
  750           If your scheme code runs without any errors you can disable
  751           almost all error checking by compiling all files with
  752           'reckless'.
  754      "record"
  755           The Record package provides a facility for user to define
  756           their own record data types.  See SLIB for documentation.
  758      "regex"
  759           String regular expression matching.
  761      "rev2-procedures"
  762           These procedures were specified in the 'Revised^2 Report on
  763           Scheme' but not in 'R4RS'.
  765      "sicp"
  766           Use if you want to run code from:
  768           Harold Abelson and Gerald Jay Sussman with Julie Sussman.
  769           'Structure and Interpretation of Computer Programs.' The MIT
  770           Press, Cambridge, Massachusetts, USA, 1985.
  772           Differences from R5RS are:
  773              * (eq?  '() '#f)
  774              * (define a 25) returns the symbol a.
  775              * (set!  a 36) returns 36.
  777      "single-precision-only"
  778           Use if you want all inexact real numbers to be single
  779           precision.  This only has an effect if SINGLES is also defined
  780           (which is the default).  This does not affect complex numbers.
  782      "socket"
  783           BSD "socket" interface.  Socket addr functions require
  784           inexacts or bignums for 32-bit precision.
  786      "tick-interrupts"
  787           Use if you want the ticks and ticks-interrupt functions.
  789      "turtlegr"
  790           "Turtle" graphics calls for both Borland-C and X11 from
  791           sjm@ee.tut.fi.
  793      "unix"
  794           Those unix features which have not made it into the Posix
  795           specs: nice, acct, lstat, readlink, symlink, mknod and sync.
  797      "wb"
  798           WB database with relational wrapper.
  800      "wb-no-threads"
  801           no-comment
  803      "windows"
  804           Microsoft Windows executable.
  806      "x"
  807           Alias for Xlib feature.
  809      "xlib"
  810           Interface to Xlib graphics routines.
  814 File: scm-5f3.info,  Node: Saving Executable Images,  Next: Installation,  Prev: Building SCM,  Up: Installing SCM
  816 2.4 Saving Executable Images
  817 ============================
  819 In SCM, the ability to save running program images is called "dump"
  820 (*note Dump::).  In order to make 'dump' available to SCM, build with
  821 feature 'dump'.  'dump'ed executables are compatible with dynamic
  822 linking.
  824 Most of the code for "dump" is taken from 'emacs-19.34/src/unex*.c'.  No
  825 modifications to the emacs source code were required to use 'unexelf.c'.
  826 Dump has not been ported to all platforms.  If 'unexec.c' or 'unexelf.c'
  827 don't work for you, try using the appropriate 'unex*.c' file from emacs.
  829 The 'dscm4' and 'dscm5' targets in the SCM 'Makefile' save images from
  830 'udscm4' and 'udscm5' executables respectively.
  832 "Address space layout randomization" interferes with 'dump'.  Here are
  833 the fixes for various operating-systems:
  835 Fedora-Core-1
  836      Remove the '#' from the line '#SETARCH = setarch i386' in the
  837      'Makefile'.
  839 Fedora-Core-3
  840      <http://jamesthornton.com/writing/emacs-compile.html> [For FC3]
  841      combreloc has become the default for recent GNU ld, which breaks
  842      the unexec/undump on all versions of both Emacs and XEmacs...
  844      Override by adding the following to 'udscm5.opt':
  845      '--linker-options="-z nocombreloc"'
  847 Linux Kernels later than 2.6.11
  848 <http://www.opensubscriber.com/message/emacs-devel@gnu.org/1007118.html>
  849      mentions the "exec-shield" feature.  Kernels later than 2.6.11 must
  850      do (as root):
  852           echo 0 > /proc/sys/kernel/randomize_va_space
  854      before dumping.  'Makefile' has this 'randomize_va_space' stuffing
  855      scripted for targets 'dscm4' and 'dscm5'.  You must either set
  856      'randomize_va_space' to 0 or run as root to dump.
  858 OS-X 10.6
  860 <http://developer.apple.com/library/mac/#documentation/Darwin/Reference/Manpages/man1/dyld.1.html>
  861      The dynamic linker uses the following environment variables.  They
  862      affect any program that uses the dynamic linker.
  864      DYLD_NO_PIE
  866      Causes dyld to not randomize the load addresses of images in a
  867      process where the main executable was built position independent.
  868      This can be helpful when trying to reproduce and debug a problem in
  869      a PIE.
  873 File: scm-5f3.info,  Node: Installation,  Next: Troubleshooting and Testing,  Prev: Saving Executable Images,  Up: Installing SCM
  875 2.5 Installation
  876 ================
  878 Once 'scmlit', 'scm', and 'dlls' have been built, these commands will
  879 install them to the locations specified when you ran './configure':
  881      bash$ (cd scm; make install)
  882      bash$ (cd slib; make install)
  884 Note that installation to system directories (like '/usr/bin/') will
  885 require that those commands be run as root:
  887      bash$ (cd scm; sudo make install)
  888      bash$ (cd slib; sudo make install)
  892 File: scm-5f3.info,  Node: Problems Compiling,  Next: Problems Linking,  Prev: Troubleshooting and Testing,  Up: Troubleshooting and Testing
  894 2.6.1 Problems Compiling
  895 ------------------------
  897 FILE    PROBLEM / MESSAGE                HOW TO FIX
  898 *.c     include file not found.          Correct the status of
  899                                          STDC_HEADERS in scmfig.h.
  900                                          fix #include statement or add
  901                                          #define for system type to
  902                                          scmfig.h.
  903 *.c     Function should return a         Ignore.
  904         value.
  905         Parameter is never used.
  906         Condition is always false.
  907         Unreachable code in function.
  908 scm.c   assignment between               Change SIGRETTYPE in scm.c.
  909         incompatible types.
  910 time.c  CLK_TCK redefined.               incompatablility between
  911                                          <stdlib.h> and <sys/types.h>.
  912                                          Remove STDC_HEADERS in
  913                                          scmfig.h.
  914                                          Edit <sys/types.h> to remove
  915                                          incompatability.
  916 subr.c  Possibly incorrect assignment    Ignore.
  917         in function lgcd.
  918 sys.c   statement not reached.           Ignore.
  919         constant in conditional
  920         expression.
  921 sys.c   undeclared, outside of           #undef STDC_HEADERS in
  922         functions.                       scmfig.h.
  923 scl.c   syntax error.                    #define SYSTNAME to your
  924                                          system type in scl.c
  925                                          (softtype).
  929 File: scm-5f3.info,  Node: Problems Linking,  Next: Testing,  Prev: Problems Compiling,  Up: Troubleshooting and Testing
  931 2.6.2 Problems Linking
  932 ----------------------
  934 PROBLEM                              HOW TO FIX
  935 _sin etc.  missing.                  Uncomment LIBS in makefile.
  939 File: scm-5f3.info,  Node: Problems Starting,  Next: Problems Running,  Prev: Testing,  Up: Troubleshooting and Testing
  941 2.6.4 Problems Starting
  942 -----------------------
  944 PROBLEM                              HOW TO FIX
  945 /bin/bash: scm: program not found    Is 'scm' in a '$PATH' directory?
  946 /bin/bash: /usr/local/bin/scm:       'chmod +x /usr/local/bin/scm'
  947 Permission denied
  948 Opening message and then machine     Change memory model option to C
  949 crashes.                             compiler (or makefile).
  950                                      Make sure sizet definition is
  951                                      correct in scmfig.h.
  952                                      Reduce the size of HEAP_SEG_SIZE
  953                                      in setjump.h.
  954 Input hangs.                         #define NOSETBUF
  955 ERROR: heap: need larger initial.    Increase initial heap allocation
  956                                      using -a<kb> or INIT_HEAP_SIZE.
  957 ERROR: Could not allocate.           Check sizet definition.
  958                                      Use 32 bit compiler mode.
  959                                      Don't try to run as subproccess.
  960 remove <FLAG> in scmfig.h and        Do so and recompile files.
  961 recompile scm.
  962 add <FLAG> in scmfig.h and
  963 recompile scm.
  964 ERROR: Init5f2.scm not found.        Assign correct IMPLINIT in
  965                                      makefile or scmfig.h.
  966                                      Define environment variable
  967                                      SCM_INIT_PATH to be the full
  968                                      pathname of Init5f2.scm.
  969 WARNING: require.scm not found.      Define environment variable
  970                                      SCHEME_LIBRARY_PATH to be the full
  971                                      pathname of the scheme library
  972                                      [SLIB].
  973                                      Change library-vicinity in
  974                                      Init5f2.scm to point to library or
  975                                      remove.
  976                                      Make sure the value of
  977                                      (library-vicinity) has a trailing
  978                                      file separator (like / or \).
  982 File: scm-5f3.info,  Node: Problems Running,  Next: Reporting Problems,  Prev: Problems Starting,  Up: Troubleshooting and Testing
  984 2.6.5 Problems Running
  985 ----------------------
  987 PROBLEM                              HOW TO FIX
  988 Runs some and then machine           See above under machine crashes.
  989 crashes.
  990 Runs some and then ERROR: ...        Remove optimization option to C
  991 (after a GC has happened).           compiler and recompile.
  992                                      #define SHORT_ALIGN in 'scmfig.h'.
  993 Some symbol names print              Change memory model option to C
  994 incorrectly.                         compiler (or makefile).
  995                                      Check that HEAP_SEG_SIZE fits
  996                                      within sizet.
  997                                      Increase size of HEAP_SEG_SIZE (or
  998                                      INIT_HEAP_SIZE if it is smaller
  999                                      than HEAP_SEG_SIZE).
 1000 ERROR: Rogue pointer in Heap.        See above under machine crashes.
 1001 Newlines don't appear correctly in   Check file mode (define OPEN_...
 1002 output files.                        in 'Init5f2.scm').
 1003 Spaces or control characters         Check character defines in
 1004 appear in symbol names.              'scmfig.h'.
 1005 Negative numbers turn positive.      Check SRS in 'scmfig.h'.
 1006 ;ERROR: bignum: numerical overflow   Increase NUMDIGS_MAX in 'scmfig.h'
 1007                                      and recompile.
 1008 VMS: Couldn't unwind stack.          #define CHEAP_CONTINUATIONS in
 1009                                      'scmfig.h'.
 1010 VAX: botched longjmp.
 1014 File: scm-5f3.info,  Node: Reporting Problems,  Prev: Problems Running,  Up: Troubleshooting and Testing
 1016 2.6.6 Reporting Problems
 1017 ------------------------
 1019 Reported problems and solutions are grouped under Compiling, Linking,
 1020 Running, and Testing.  If you don't find your problem listed there, you
 1021 can send a bug report to 'agj@alum.mit.edu' or 'scm-discuss@gnu.org'.
 1022 The bug report should include:
 1024   1. The version of SCM (printed when SCM is invoked with no arguments).
 1025   2. The type of computer you are using.
 1026   3. The name and version of your computer's operating system.
 1027   4. The values of the environment variables 'SCM_INIT_PATH' and
 1029   5. The name and version of your C compiler.
 1030   6. If you are using an executable from a distribution, the name,
 1031      vendor, and date of that distribution.  In this case, corresponding
 1032      with the vendor is recommended.
 1036 File: scm-5f3.info,  Node: Editing Scheme Code,  Next: Debugging Scheme Code,  Prev: SCM Session,  Up: Operational Features
 1038 3.7 Editing Scheme Code
 1039 =======================
 1041  -- Function: ed arg1 ...
 1042      The value of the environment variable 'EDITOR' (or just 'ed' if it
 1043      isn't defined) is invoked as a command with arguments ARG1 ....
 1044  -- Function: ed filename
 1045      If SCM is compiled under VMS 'ed' will invoke the editor with a
 1046      single the single argument FILENAME.
 1048 Gnu Emacs:
 1049      Editing of Scheme code is supported by emacs.  Buffers holding
 1050      files ending in .scm are automatically put into scheme-mode.
 1052      If your Emacs can run a process in a buffer you can use the Emacs
 1053      command 'M-x run-scheme' with SCM. Otherwise, use the emacs command
 1054      'M-x suspend-emacs'; or see "other systems" below.
 1056 Epsilon (MS-DOS):
 1057      There is lisp (and scheme) mode available by use of the package
 1058      'LISP.E'.  It offers several different indentation formats.  With
 1059      this package, buffers holding files ending in '.L', '.LSP', '.S',
 1060      and '.SCM' (my modification) are automatically put into lisp-mode.
 1062      It is possible to run a process in a buffer under Epsilon.  With
 1063      Epsilon 5.0 the command line options '-e512 -m0' are neccessary to
 1064      manage RAM properly.  It has been reported that when compiling SCM
 1065      with Turbo C, you need to '#define NOSETBUF' for proper operation
 1066      in a process buffer with Epsilon 5.0.
 1068      One can also call out to an editor from SCM if RAM is at a premium;
 1069      See "under other systems" below.
 1071 other systems:
 1072      Define the environment variable 'EDITOR' to be the name of the
 1073      editing program you use.  The SCM procedure '(ed arg1 ...)' will
 1074      invoke your editor and return to SCM when you exit the editor.  The
 1075      following definition is convenient:
 1077           (define (e) (ed "work.scm") (load "work.scm"))
 1079      Typing '(e)' will invoke the editor with the file of interest.
 1080      After editing, the modified file will be loaded.