\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename scm.info @settitle scm @include version.txi @setchapternewpage on @c Choices for setchapternewpage are {on,off,odd}. @paragraphindent 0 @defcodeindex ft @syncodeindex ft tp @c %**end of header @copying @noindent This manual is for SCM (version @value{SCMVERSION}, @value{SCMDATE}), an implementation of the algorithmic language Scheme. @noindent Copyright @copyright{} 1990-2007 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License.'' @end quotation @end copying @dircategory The Algorithmic Language Scheme @direntry * SCM: (scm). A Scheme interpreter. @end direntry @iftex @finalout @c DL: lose the egregious vertical whitespace, esp. around examples @c but paras in @defun-like things don't have parindent @parskip 4pt plus 1pt @end iftex @titlepage @title SCM @subtitle Scheme Implementation @subtitle Version @value{SCMVERSION} @author Aubrey Jaffer @page @vskip 0pt plus 1filll @insertcopying @end titlepage @contents @ifnottex @node Top, Overview, (dir), (dir) @top SCM @insertcopying @menu * Overview:: * Installing SCM:: How to * Operational Features:: * The Language:: Reference. * Packages:: Optional Capabilities. * The Implementation:: How it works. * Index:: @end menu @end ifnottex @node Overview, Installing SCM, Top, Top @chapter Overview @noindent SCM is a portable Scheme implementation written in C. SCM provides a machine independent platform for [JACAL], a symbolic algebra system. SCM supports and requires the SLIB Scheme library. SCM, SLIB, and JACAL are GNU projects. @iftex @noindent The most recent information about SCM can be found on SCM's @dfn{WWW} home page: @ifset html @end ifset @center @url{http://people.csail.mit.edu/jaffer/SCM} @ifset html @end ifset @end iftex @menu * SCM Features:: * SCM Authors:: * Copying:: * Bibliography:: @end menu @node SCM Features, SCM Authors, Overview, Overview @section Features @itemize @bullet @item Conforms to Revised^5 Report on the Algorithmic Language Scheme [R5RS] and the [IEEE] P1178 specification. @item Support for [SICP], [R2RS], [R3RS], and [R5RS] scheme code. @item Runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2, NOS/VE, Unicos, VMS, Unix and similar systems. Supports ASCII and EBCDIC character sets. @item Is fully documented in @TeX{}info form, allowing documentation to be generated in info, @TeX{}, html, nroff, and troff formats. @item Supports inexact real and complex numbers, 30 bit immediate integers and large precision integers. @item Many Common Lisp functions: @code{logand}, @code{logor}, @code{logxor}, @code{lognot}, @code{ash}, @code{logcount}, @code{integer-length}, @code{bit-extract}, @code{defmacro}, @code{macroexpand}, @code{macroexpand1}, @code{gentemp}, @code{defvar}, @code{force-output}, @code{software-type}, @code{get-decoded-time}, @code{get-internal-run-time}, @code{get-internal-real-time}, @code{delete-file}, @code{rename-file}, @code{copy-tree}, @code{acons}, and @code{eval}. @item @code{Char-code-limit}, @code{most-positive-fixnum}, @code{most-negative-fixnum}, @code{and internal-time-units-per-second} constants. @code{slib:features} and @code{*load-pathname*} variables. @item Arrays and bit-vectors. String ports and software emulation ports. I/O extensions providing ANSI C and POSIX.1 facilities. @item Interfaces to standard libraries including REGEX string regular expression matching and the CURSES screen management package. @item Available add-on packages including an interactive debugger, database, X-window graphics, BGI graphics, Motif, and Open-Windows packages. @item The Hobbit compiler and dynamic linking of compiled modules. @item User definable responses to interrupts and errors, Process-syncronization primitives. Setable levels of monitoring and timing information printed interactively (the @code{verbose} function). @code{Restart}, @code{quit}, and @code{exec}. @end itemize @node SCM Authors, Copying, SCM Features, Overview @section Authors @table @b @item Aubrey Jaffer (agj@@alum.mit.edu) Most of SCM. @item Radey Shouman Arrays, @code{gsubr}s, compiled closures, records, Ecache, syntax-rules macros, and @dfn{safeport}s. @item Jerry D. Hedden Real and Complex functions. Fast mixed type arithmetics. @item Hugh Secker-Walker Syntax checking and memoization of special forms by evaluator. Storage allocation strategy and parameters. @item George Carrette @dfn{Siod}, written by George Carrette, was the starting point for SCM. The major innovations taken from Siod are the evaluator's use of the C-stack and being able to garbage collect off the C-stack (@pxref{Garbage Collection}). @end table @noindent There are many other contributors to SCM. They are acknowledged in the file @file{ChangeLog}, a log of changes that have been made to scm. @node Copying, Bibliography, SCM Authors, Overview @section Copyright @noindent Authors have assigned their SCM copyrights to: @sp 1 @center Free Software Foundation, Inc. @center 59 Temple Place, Suite 330, Boston, MA 02111, USA @menu * The SCM License:: * SIOD copyright:: * GNU Free Documentation License:: Copying this Manual @end menu @node The SCM License, SIOD copyright, Copying, Copying @subsection The SCM License This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see @url{http://www.gnu.org/licenses/}. @node SIOD copyright, GNU Free Documentation License, The SCM License, Copying @subsection SIOD copyright @sp 1 @center COPYRIGHT @copyright{} 1989 BY @center PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS. @center ALL RIGHTS RESERVED @noindent Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Paradigm Associates Inc not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. @noindent PARADIGM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL PARADIGM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. @noindent gjc@@paradigm.com @flushright Phone: 617-492-6079 @end flushright @flushleft Paradigm Associates Inc 29 Putnam Ave, Suite 6 Cambridge, MA 02138 @end flushleft @node GNU Free Documentation License, , SIOD copyright, Copying @subsection GNU Free Documentation License @include fdl.texi @node Bibliography, , Copying, Overview @section Bibliography @table @asis @item [IEEE] @cindex IEEE @cite{IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming Language.} IEEE, New York, 1991. @item [R4RS] @cindex R4RS William Clinger and Jonathan Rees, Editors. @ifset html @end ifset Revised(4) Report on the Algorithmic Language Scheme. @ifset html @end ifset @cite{ACM Lisp Pointers} Volume IV, Number 3 (July-September 1991), pp. 1-55. @ifinfo @ref{Top, , , r4rs, Revised(4) Report on the Algorithmic Language Scheme}. @end ifinfo @item [R5RS] @cindex R5RS Richard Kelsey and William Clinger and Jonathan (Rees, editors) @ifset html @end ifset Revised(5) Report on the Algorithmic Language Scheme. @ifset html @end ifset @cite{Higher-Order and Symbolic Computation} Volume 11, Number 1 (1998), pp. 7-105, and @cite{ACM SIGPLAN Notices} 33(9), September 1998. @ifinfo @ref{Top, , , r5rs, Revised(5) Report on the Algorithmic Language Scheme}. @end ifinfo @item [Exrename] @cindex Exrename William Clinger @ifset html @end ifset Hygienic Macros Through Explicit Renaming @ifset html @end ifset @cite{Lisp Pointers} Volume IV, Number 4 (December 1991), pp 17-23. @item [SICP] @cindex SICP Harold Abelson and Gerald Jay Sussman with Julie Sussman. @cite{Structure and Interpretation of Computer Programs.} MIT Press, Cambridge, 1985. @item [Simply] @cindex Simply Brian Harvey and Matthew Wright. @ifset html @end ifset @cite{Simply Scheme: Introducing Computer Science} @ifset html @end ifset MIT Press, 1994 ISBN 0-262-08226-8 @item [SchemePrimer] @cindex SchemePrimer 犬飼大(Dai Inukai) @ifset html @end ifset @cite{入門Scheme} @ifset html @end ifset 1999年12月初版 ISBN4-87966-954-7 @c @item [GUILE] @c @cindex GUILE @c Free Software Foundation @c @ifset html @c @c @end ifset @c Guile: Project GNU's extension language @c @ifset html @c @c @end ifset @item [SLIB] @cindex SLIB Todd R. Eigenschink, Dave Love, and Aubrey Jaffer. @ifset html @end ifset SLIB, The Portable Scheme Library. @ifset html @end ifset Version 2c8, June 2000. @ifinfo @ref{Top, , , slib, SLIB}. @end ifinfo @item [JACAL] @cindex JACAL Aubrey Jaffer. @ifset html @end ifset JACAL Symbolic Mathematics System. @ifset html @end ifset Version 1b0, Sep 1999. @ifinfo @ref{Top, , , jacal, JACAL}. @end ifinfo @end table @table @file @item scm.texi @itemx scm.info Documentation of @code{scm} extensions (beyond Scheme standards). Documentation on the internal representation and how to extend or include @code{scm} in other programs. @item Xlibscm.texi @itemx Xlibscm.info Documentation of the Xlib - SCM Language X Interface. @end table @node Installing SCM, Operational Features, Overview, Top @chapter Installing SCM SCM runs on a wide variety of platforms. ``Distributions'' is the starting point for all platforms. The process described in ``GNU configure and make'' will work on most Unix and GNU/Linux platforms. If it works for you, then you may skip the later sections of ``Installing SCM''. @menu * Distributions:: Source and Binaries * GNU configure and make:: For Unix and GNU/Linux * Building SCM:: * Saving Executable Images:: For Faster Startup * Installation:: * Troubleshooting and Testing:: @end menu @node Distributions, GNU configure and make, Installing SCM, Installing SCM @section Distributions @noindent The SCM homepage contains links to precompiled binaries and source distributions. @noindent Downloads and instructions for installing the precompiled binaries are at @uref{http://people.csail.mit.edu/jaffer/SCM#QuickStart}. @noindent If there is no precompiled binary for your platform, you may be able to build from the source distribution. The rest of these instructions deal with building and installing SCM and SLIB from sources. @noindent Download (both SCM and SLIB of) either the last release or current development snapshot from @uref{http://people.csail.mit.edu/jaffer/SCM#BuildFromSource}. @noindent Unzip both the SCM and SLIB zips. For example, if you are working in @file{/usr/local/src/}, this will create directories @file{/usr/local/src/scm/} and @file{/usr/local/src/slib/}. @node GNU configure and make, Building SCM, Distributions, Installing SCM @section GNU configure and make @file{scm/configure} and @file{slib/configure} are Shell scripts which create the files @file{scm/config.status} and @file{slib/config.status} on Unix and MinGW systems. The @file{config.status} files are used (included) by the Makefile to control where the packages will be installed by @code{make install}. With GNU shell (bash) and utilities, the following commands should build and install SCM and SLIB: @example bash$ (cd slib; ./configure --prefix=/usr/local/) bash$ (cd scm > ./configure --prefix=/usr/local/ > make scmlit > sudo make all > sudo make install) bash$ (cd slib; sudo make install) @end example If the install commands worked, skip to @ref{Testing}. If @file{configure} doesn't work on your system, make @file{scm/config.status} and @file{slib/config.status} be empty files. For additional help on using the @file{configure} script, run @w{@samp{./configure --help}}. @samp{make all} will attempt to create a dumped executable (@pxref{Saving Executable Images}), which has very small startup latency. If that fails, it will try to compile an ordinary @samp{scm} executable. Note that the compilation output may contain error messages; be concerned only if the @samp{make install} transcripts contain errors. @samp{sudo} runs the command after it as user @dfn{root}. On recent GNU/Linux systems, dumping requires that @samp{make all} be run as user root; hence the use of @samp{sudo}. @samp{make install} requires root privileges if you are installing to standard Unix locations as specified to (or defaulted by) @samp{./configure}. Note that this is independent of whether you did @w{@samp{sudo make all}} or @w{@samp{make all}}. @menu * Making scmlit:: * Makefile targets:: @end menu @node Making scmlit, Makefile targets, GNU configure and make, GNU configure and make @subsection Making scmlit @noindent The SCM distribution @file{Makefile} contains rules for making @dfn{scmlit}, a ``bare-bones'' version of SCM sufficient for running @file{build}. @file{build} is a Scheme program used to compile (or create scripts to compile) full featured versions of SCM (@pxref{Building SCM}). To create scmlit, run @w{@samp{make scmlit}} in the @file{scm/} directory. @noindent Makefiles are not portable to the majority of platforms. If you need to compile SCM without @samp{scmlit}, there are several ways to proceed: @itemize @bullet @item Use the @uref{http://people.csail.mit.edu/jaffer/buildscm.html, build} web page to create custom batch scripts for compiling SCM. @item Use SCM on a different platform to run @file{build} to create a script to build SCM; @item Use another implementation of Scheme to run @file{build} to create a script to build SCM; @item Create your own script or @file{Makefile}. @end itemize @subheading Finding SLIB If you didn't create scmlit using @samp{make scmlit}, then you must create a file named @file{scm/require.scm}. For most installations, @file{scm/require.scm} can just be copied from @file{scm/requires.scm}, which is part of the SCM distribution. @noindent If, when executing @samp{scmlit} or @samp{scm}, you get a message like: @example ERROR: "LOAD couldn't find file " "/usr/local/src/scm/require" @end example @noindent then create a file @file{require.scm} in the SCM @dfn{implementation-vicinity} (this is the same directory as where the file @file{Init@value{SCMVERSION}.scm} is). @file{require.scm} should have the contents: @example (define (library-vicinity) "/usr/local/lib/slib/") @end example @noindent where the pathname string @file{/usr/local/lib/slib/} is to be replaced by the pathname into which you unzipped (or installed) SLIB. @noindent Alternatively, you can set the (shell) environment variable @code{SCHEME_LIBRARY_PATH} to the pathname of the SLIB directory (@pxref{SCM Variables, SCHEME_LIBRARY_PATH, Environment Variables}). If set, this environment variable overrides @file{scm/require.scm}. @noindent Absolute pathnames are recommended here; if you use a relative pathname, SLIB can get confused when the working directory is changed (@pxref{I/O-Extensions, chmod}). The way to specify a relative pathname is to append it to the implementation-vicinity, which is absolute: @example (define library-vicinity (let ((lv (string-append (implementation-vicinity) "../slib/"))) (lambda () lv))) @end example @node Makefile targets, , Making scmlit, GNU configure and make @subsection Makefile targets Each of the following four @samp{make} targets creates an executable named @file{scm}. Each target takes its build options from a file with an @samp{.opt} suffix. If that options file doesn't exist, making that target will create the file with the @samp{-F} features: cautious, bignums, arrays, inexact, engineering-notation, and dynamic-linking. Once that @samp{.opt} file exists, you can edit it to your taste and it will be preserved. @table @code @item make scm4 Produces a R4RS executable named @file{scm} lacking hygienic macros (but with defmacro). The build options are taken from @file{scm4.opt}. If build or the executable fails, try removing @samp{dynamic-linking} from @file{scm4.opt}. @item make scm5 R5RS; like @samp{make scm4} but with @samp{-F macro}. The build options are taken from @file{scm5.opt}. If build or the executable fails, try removing @samp{dynamic-linking} from @file{scm5.opt}. @item make dscm4 Produces a R4RS executable named @file{udscm4}, which it starts and dumps to a low startup latency executable named @file{scm}. The build options are taken from @file{udscm4.opt}. If the build fails, then @samp{build scm4} instead. If the dumped executable fails to run, then send me a bug report (and use @w{@samp{build scm4}} until the problem with dump is corrected). @item make dscm5 Like @samp{make dscm4} but with @samp{-F macro}. The build options are taken from @file{udscm5.opt}. If the build fails, then @samp{build scm5} instead. If the dumped executable fails to run, then send me a bug report (and use @w{@samp{build scm5}} until the problem with dump is corrected). @end table @noindent If the above builds fail because of @w{@samp{-F dynamic-linking}}, then (because they can't be dynamically linked) you will likely want to add some other features to the build's @samp{.opt} file. See the @samp{-F} build option in @ref{Build Options}. @noindent If dynamic-linking is working, then you will likely want to compile most of the modules as @dfn{DLL}s. The build options for compiling DLLs are in @file{dlls.opt}. @table @code @item make x.so The @code{Xlib} module; @ref{Top, ,SCM Language X Interface , Xlibscm, Xlibscm}. @item make myturtle Creates a DLL named @file{turtlegr.so} which is a simple graphics API. @item make wbscm.so The @code{wb} module; @ref{Top, ,B-tree database implementation , wb, wb}. Compiling this requires that wb source be in a peer directory to scm. @item make dlls Compiles all the distributed library modules, but not @file{wbscm.so}. Many of the module compiles are recursively invoked in such a way that failure of one (which could be due to a system library not being installed) doesn't cause the top-level @samp{make dlls} to fail. If @samp{make dlls} fails as a whole, it is time to submit a bug report (@pxref{Reporting Problems}). @end table @node Building SCM, Saving Executable Images, GNU configure and make, Installing SCM @section Building SCM @cindex build @cindex build.scm The file @dfn{build} loads the file @dfn{build.scm}, which constructs a relational database of how to compile and link SCM executables. @file{build.scm} has information for the platforms which SCM has been ported to (of which I have been notified). Some of this information is old, incorrect, or incomplete. Send corrections and additions to agj@@alum.mit.edu. @menu * Invoking Build:: * Build Options:: build --help * Compiling and Linking Custom Files:: @end menu @node Invoking Build, Build Options, Building SCM, Building SCM @subsection Invoking Build This section teaches how to use @file{build}, a Scheme program for creating compilation scripts to produce SCM executables and library modules. The options accepted by @samp{build} are documented in @ref{Build Options}. @noindent Use the @emph{any} method if you encounter problems with the other two methods (MS-DOS, Unix). @table @asis @item MS-DOS From the SCM source directory, type @samp{build} followed by up to 9 command line arguments. @item Unix From the SCM source directory, type @samp{./build} followed by command line arguments. @item @emph{any} From the SCM source directory, start @samp{scm} or @samp{scmlit} and type @code{(load "build")}. Alternatively, start @samp{scm} or @samp{scmlit} with the command line argument @samp{-ilbuild}. This method will also work for MS-DOS and Unix. After loading various SLIB modules, the program will print: @example type (b "build ") to build type (b*) to enter build command loop @end example The @samp{b*} procedure enters into a @dfn{build shell} where you can enter commands (with or without the @samp{build}). Blank lines are ignored. To create a build script with all defaults type @samp{build}. If the build-shell encouters an error, you can reenter the build-shell by typing @samp{(b*)}. To exit scm type @samp{(quit)}. @end table @noindent Here is a transcript of an interactive (b*) build-shell. @example bash$ scmlit SCM version 5e7, Copyright (C) 1990-2006 Free Software Foundation. SCM comes with ABSOLUTELY NO WARRANTY; for details type `(terms)'. This is free software, and you are welcome to redistribute it under certain conditions; type `(terms)' for details. > (load "build") ;loading build ; loading /home/jaffer/slib/getparam ; loading /home/jaffer/slib/coerce ... ; done loading build.scm type (b "build ") to build type (b*) to enter build command loop ;done loading build # > (b*) ;loading /home/jaffer/slib/comparse ;done loading /home/jaffer/slib/comparse.scm build> -t exe #! /bin/sh # unix (linux) script created by SLIB/batch Wed Oct 26 17:14:23 2011 # [-p linux] # ================ Write file with C defines rm -f scmflags.h echo '#define IMPLINIT "Init5e7.scm"'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h echo '#define ARRAYS'>>scmflags.h # ================ Compile C source files 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 # ================ Link C object files 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 "scm" build> -t exe -w myscript.sh "scm" build> (quit) @end example @noindent No compilation was done. The @samp{-t exe} command shows the compile script. The @samp{-t exe -w myscript.sh} line creates a file @file{myscript.sh} containing the compile script. To actually compile and link it, type @samp{./myscript.sh}. @noindent Invoking build without the @samp{-F} option will build or create a shell script with the @code{arrays}, @code{inexact}, and @code{bignums} options as defaults. Invoking @samp{build} with @samp{-F lit -o scmlit} will make a script for compiling @samp{scmlit}. @example bash$ ./build @print{} #! /bin/sh # unix (linux) script created by SLIB/batch # ================ Write file with C defines rm -f scmflags.h echo '#define IMPLINIT "Init@value{SCMVERSION}.scm"'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h echo '#define ARRAYS'>>scmflags.h # ================ Compile C source files 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 # ================ Link C object files 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 @end example @noindent To cross compile for another platform, invoke build with the @samp{-p} or @samp{--platform=} option. This will create a script for the platform named in the @samp{-p} or @samp{--platform=} option. @example bash$ ./build -o scmlit -p darwin -F lit @print{} #! /bin/sh # unix (darwin) script created by SLIB/batch # ================ Write file with C defines rm -f scmflags.h echo '#define IMPLINIT "Init@value{SCMVERSION}.scm"'>>scmflags.h # ================ Compile C source files 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 # ================ Link C object files mv -f scmlit scmlit~ 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 @end example @node Build Options, Compiling and Linking Custom Files, Invoking Build, Building SCM @subsection Build Options @noindent The options to @dfn{build} specify what, where, and how to build a SCM program or dynamically linked module. These options are unrelated to the SCM command line options. @deffn {Build Option} -p @var{platform-name} @deffnx {Build Option} ---platform=@var{platform-name} specifies that the compilation should be for a computer/operating-system combination called @var{platform-name}. @emph{Note@:} The case of @var{platform-name} is distinguised. The current @var{platform-name}s are all lower-case. The platforms defined by table @dfn{platform} in @file{build.scm} are: @end deffn @example @include platform.txi @end example @deffn {Build Option} -f @var{pathname} specifies that the build options contained in @var{pathname} be spliced into the argument list at this point. The use of option files can separate functional features from platform-specific ones. The @file{Makefile} calls out builds with the options in @samp{.opt} files: @table @file @item dlls.opt Options for Makefile targets dlls, myturtle, and x.so. @item gdb.opt Options for udgdbscm and gdbscm. @item libscm.opt Options for libscm.a. @item pg.opt Options for pgscm, which instruments C functions. @item udscm4.opt Options for targets udscm4 and dscm4 (scm). @item udscm5.opt Options for targets udscm5 and dscm5 (scm). @end table The Makefile creates options files it depends on only if they do not already exist. @end deffn @deffn {Build Option} -o @var{filename} @deffnx {Build Option} ---outname=@var{filename} specifies that the compilation should produce an executable or object name of @var{filename}. The default is @samp{scm}. Executable suffixes will be added if neccessary, e.g. @samp{scm} @result{} @samp{scm.exe}. @end deffn @deffn {Build Option} -l @var{libname} @dots{} @deffnx {Build Option} ---libraries=@var{libname} specifies that the @var{libname} should be linked with the executable produced. If compile flags or include directories (@samp{-I}) are needed, they are automatically supplied for compilations. The @samp{c} library is always included. SCM @dfn{features} specify any libraries they need; so you shouldn't need this option often. @end deffn @deffn {Build Option} -D @var{definition} @dots{} @deffnx {Build Option} ---defines=@var{definition} specifies that the @var{definition} should be made in any C source compilations. If compile flags or include directories (@samp{-I}) are needed, they are automatically supplied for compilations. SCM @dfn{features} specify any flags they need; so you shouldn't need this option often. @end deffn @deffn {Build Option} ---compiler-options=@var{flag} specifies that that @var{flag} will be put on compiler command-lines. @end deffn @deffn {Build Option} ---linker-options=@var{flag} specifies that that @var{flag} will be put on linker command-lines. @end deffn @deffn {Build Option} -s @var{pathname} @deffnx {Build Option} ---scheme-initial=@var{pathname} specifies that @var{pathname} should be the default location of the SCM initialization file @file{Init@value{SCMVERSION}.scm}. SCM tries several likely locations before resorting to @var{pathname} (@pxref{File-System Habitat}). If not specified, the current directory (where build is building) is used. @end deffn @deffn {Build Option} -c @var{pathname} @dots{} @deffnx {Build Option} ---c-source-files=@var{pathname} specifies that the C source files @var{pathname} @dots{} are to be compiled. @end deffn @deffn {Build Option} -j @var{pathname} @dots{} @deffnx {Build Option} ---object-files=@var{pathname} specifies that the object files @var{pathname} @dots{} are to be linked. @end deffn @deffn {Build Option} -i @var{call} @dots{} @deffnx {Build Option} ---initialization=@var{call} specifies that the C functions @var{call} @dots{} are to be invoked during initialization. @end deffn @deffn {Build Option} -t @var{build-what} @deffnx {Build Option} ---type=@var{build-what} specifies in general terms what sort of thing to build. The choices are: @table @samp @item exe executable program. @item lib library module. @item dlls archived dynamically linked library object files. @item dll dynamically linked library object file. @end table The default is to build an executable. @end deffn @deffn {Build Option} -h @var{batch-syntax} @deffnx {Build Option} --batch-dialect=@var{batch-syntax} specifies how to build. The default is to create a batch file for the host system. The SLIB file @file{batch.scm} knows how to create batch files for: @itemize @bullet @item unix @item dos @item vms @item amigaos (was amigados) @item system This option executes the compilation and linking commands through the use of the @code{system} procedure. @item *unknown* This option outputs Scheme code. @end itemize @end deffn @deffn {Build Option} -w @var{batch-filename} @deffnx {Build Option} --script-name=@var{batch-filename} specifies where to write the build script. The default is to display it on @code{(current-output-port)}. @end deffn @deffn {Build Option} -F @var{feature} @dots{} @deffnx {Build Option} ---features=@var{feature} specifies to build the given features into the executable. The defined features are: @table @dfn @c @itemx none @c @cindex none @c Lightweight -- no features @include features.txi @end table @end deffn @node Compiling and Linking Custom Files, , Build Options, Building SCM @subsection Compiling and Linking Custom Files @noindent A correspondent asks: @quotation How can we link in our own c files to the SCM interpreter so that we can add our own functionality? (e.g. we have a bunch of tcp functions we want access to). Would this involve changing build.scm or the Makefile or both? @end quotation @noindent (@pxref{Changing Scm} has instructions describing the C code format). @cindex foo.c @cindex Extending Scm Suppose a C file @dfn{foo.c} has functions you wish to add to SCM. To compile and link your file at compile time, use the @samp{-c} and @samp{-i} options to build: @example bash$ ./build -c foo.c -i init_foo @print{} #! /bin/sh rm -f scmflags.h echo '#define IMPLINIT "/home/jaffer/scm/Init@value{SCMVERSION}.scm"'>>scmflags.h echo '#define COMPILED_INITS init_foo();'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h echo '#define ARRAYS'>>scmflags.h gcc -O2 -c continue.c scm.c findexec.c script.c time.c repl.c scl.c \ eval.c sys.c subr.c unif.c rope.c foo.c gcc -rdynamic -o scm continue.o scm.o findexec.o script.o time.o \ repl.o scl.o eval.o sys.o subr.o unif.o rope.o foo.o -lm -lc @end example @noindent To make a dynamically loadable object file use the @code{-t dll} option: @example bash$ ./build -t dll -c foo.c @print{} #! /bin/sh rm -f scmflags.h echo '#define IMPLINIT "/home/jaffer/scm/Init@value{SCMVERSION}.scm"'>>scmflags.h echo '#define BIGNUMS'>>scmflags.h echo '#define FLOATS'>>scmflags.h echo '#define ARRAYS'>>scmflags.h echo '#define DLL'>>scmflags.h gcc -O2 -fpic -c foo.c gcc -shared -o foo.so foo.o -lm -lc @end example @noindent Once @file{foo.c} compiles correctly (and your SCM build supports dynamic-loading), you can load the compiled file with the Scheme command @code{(load "./foo.so")}. See @ref{Configure Module Catalog} for how to add a compiled dll file to SLIB's catalog. @node Saving Executable Images, Installation, Building SCM, Installing SCM @section Saving Executable Images In SCM, the ability to save running program images is called @dfn{dump} (@pxref{Dump}). In order to make @code{dump} available to SCM, build with feature @samp{dump}. @code{dump}ed executables are compatible with dynamic linking. Most of the code for @dfn{dump} is taken from @file{emacs-19.34/src/unex*.c}. No modifications to the emacs source code were required to use @file{unexelf.c}. Dump has not been ported to all platforms. If @file{unexec.c} or @file{unexelf.c} don't work for you, try using the appropriate @file{unex*.c} file from emacs. The @samp{dscm4} and @samp{dscm5} targets in the SCM @file{Makefile} save images from @file{udscm4} and @file{udscm5} executables respectively. @dfn{Address space layout randomization} interferes with @code{dump}. Here are the fixes for various operating-systems: @table @asis @item Fedora-Core-1 Remove the @samp{#} from the line @samp{#SETARCH = setarch i386} in the @file{Makefile}. @item Fedora-Core-3 @url{http://jamesthornton.com/writing/emacs-compile.html} [For FC3] combreloc has become the default for recent GNU ld, which breaks the unexec/undump on all versions of both Emacs and XEmacs... Override by adding the following to @file{udscm5.opt}: @samp{--linker-options="-z nocombreloc"} @item Linux Kernels later than 2.6.11 @exdent @url{http://www.opensubscriber.com/message/emacs-devel@@gnu.org/1007118.html} mentions the @dfn{exec-shield} feature. Kernels later than 2.6.11 must do (as root): @example echo 0 > /proc/sys/kernel/randomize_va_space @end example before dumping. @file{Makefile} has this @file{randomize_va_space} stuffing scripted for targets @samp{dscm4} and @samp{dscm5}. You must either set @file{randomize_va_space} to 0 or run as root to dump. @item OS-X 10.6 @exdent @url{http://developer.apple.com/library/mac/#documentation/Darwin/Reference/Manpages/man1/dyld.1.html} The dynamic linker uses the following environment variables. They affect any program that uses the dynamic linker. DYLD_NO_PIE Causes dyld to not randomize the load addresses of images in a process where the main executable was built position independent. This can be helpful when trying to reproduce and debug a problem in a PIE. @end table @node Installation, Troubleshooting and Testing, Saving Executable Images, Installing SCM @section Installation Once @code{scmlit}, @code{scm}, and @code{dlls} have been built, these commands will install them to the locations specified when you ran @samp{./configure}: @example bash$ (cd scm; make install) bash$ (cd slib; make install) @end example Note that installation to system directories (like @samp{/usr/bin/}) will require that those commands be run as root: @example bash$ (cd scm; sudo make install) bash$ (cd slib; sudo make install) @end example @node Troubleshooting and Testing, , Installation, Installing SCM @section Troubleshooting and Testing @menu * Problems Compiling:: * Problems Linking:: * Testing:: * Problems Starting:: * Problems Running:: * Reporting Problems:: @end menu @node Problems Compiling, Problems Linking, Troubleshooting and Testing, Troubleshooting and Testing @subsection Problems Compiling @multitable @columnfractions .10 .45 .45 @item FILE @tab PROBLEM / MESSAGE @tab HOW TO FIX @item *.c @tab include file not found. @tab Correct the status of @t{STDC_HEADERS} in scmfig.h. @item @tab @tab fix @t{#include} statement or add @t{#define} for system type to scmfig.h. @item *.c @tab Function should return a value. @tab Ignore. @item @tab Parameter is never used. @tab @item @tab Condition is always false. @tab @item @tab Unreachable code in function. @tab @item scm.c @tab assignment between incompatible types. @tab Change @t{SIGRETTYPE} in scm.c. @item time.c @tab CLK_TCK redefined. @tab incompatablility between and . @item @tab @tab Remove @t{STDC_HEADERS} in scmfig.h. @item @tab @tab Edit to remove incompatability. @item subr.c @tab Possibly incorrect assignment in function lgcd. @tab Ignore. @item sys.c @tab statement not reached. @tab Ignore. @item @tab constant in conditional expression. @tab @item sys.c @tab undeclared, outside of functions. @tab @t{#undef STDC_HEADERS} in scmfig.h. @item scl.c @tab syntax error. @tab @t{#define SYSTNAME} to your system type in scl.c (softtype). @end multitable @node Problems Linking, Testing, Problems Compiling, Troubleshooting and Testing @subsection Problems Linking @multitable @columnfractions .5 .5 @item PROBLEM @tab HOW TO FIX @item _sin etc. missing. @tab Uncomment @t{LIBS} in makefile. @end multitable @node Testing, Problems Starting, Problems Linking, Troubleshooting and Testing @subsection Testing @noindent Loading @file{r4rstest.scm} in the distribution will run an [R4RS] conformance test on @code{scm}. @example > (load "r4rstest.scm") @print{} ;loading r4rstest.scm SECTION(2 1) SECTION(3 4) # # # # @dots{} @end example @noindent Loading @file{pi.scm} in the distribution will enable you to compute digits of pi. @example > (load "pi.scm") ;loading pi.scm ;done loading pi.scm # > (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 ms (60 in gc) 36976 cells work, 1548.B other # @end example @subheading Performance @noindent Loading @file{bench.scm} will compute and display performance statistics of SCM running @file{pi.scm}. @samp{make bench} or @samp{make benchlit} appends the performance report to the file @file{BenchLog}, facilitating tracking effects of changes to SCM on performance. @node Problems Starting, Problems Running, Testing, Troubleshooting and Testing @subsection Problems Starting @multitable @columnfractions .5 .5 @item PROBLEM @tab HOW TO FIX @item /bin/bash: scm: program not found @tab Is @samp{scm} in a @samp{$PATH} directory? @item /bin/bash: /usr/local/bin/scm: Permission denied @tab @code{chmod +x /usr/local/bin/scm} @item Opening message and then machine crashes. @tab Change memory model option to C compiler (or makefile). @item @tab Make sure @t{sizet} definition is correct in scmfig.h. @item @tab Reduce the size of @t{HEAP_SEG_SIZE} in setjump.h. @item Input hangs. @tab @t{#define NOSETBUF} @item ERROR: heap: need larger initial. @tab Increase initial heap allocation using -a or @t{INIT_HEAP_SIZE}. @item ERROR: Could not allocate. @tab Check @t{sizet} definition. @item @tab Use 32 bit compiler mode. @item @tab Don't try to run as subproccess. @item remove in scmfig.h and recompile scm. @tab Do so and recompile files. @item add in scmfig.h and recompile scm. @tab @item ERROR: Init@value{SCMVERSION}.scm not found. @tab Assign correct @t{IMPLINIT} in makefile or scmfig.h. @item @tab Define environment variable @t{SCM_INIT_PATH} to be the full pathname of Init@value{SCMVERSION}.scm. @item WARNING: require.scm not found. @tab Define environment variable @t{SCHEME_LIBRARY_PATH} to be the full pathname of the scheme library [SLIB]. @item @tab Change @t{library-vicinity} in Init@value{SCMVERSION}.scm to point to library or remove. @item @tab Make sure the value of @t{(library-vicinity)} has a trailing file separator (like @t{/} or @t{\}). @end multitable @node Problems Running, Reporting Problems, Problems Starting, Troubleshooting and Testing @subsection Problems Running @multitable @columnfractions .5 .5 @item PROBLEM @tab HOW TO FIX @item Runs some and then machine crashes. @tab See above under machine crashes. @item Runs some and then ERROR: @dots{} (after a GC has happened). @tab Remove optimization option to C compiler and recompile. @item @tab @t{#define SHORT_ALIGN} in @file{scmfig.h}. @item Some symbol names print incorrectly. @tab Change memory model option to C compiler (or makefile). @item @tab Check that @t{HEAP_SEG_SIZE} fits within @t{sizet}. @item @tab Increase size of @t{HEAP_SEG_SIZE} (or @t{INIT_HEAP_SIZE} if it is smaller than @t{HEAP_SEG_SIZE}). @item ERROR: Rogue pointer in Heap. @tab See above under machine crashes. @item Newlines don't appear correctly in output files. @tab Check file mode (define OPEN_@dots{} in @file{Init@value{SCMVERSION}.scm}). @item Spaces or control characters appear in symbol names. @tab Check character defines in @file{scmfig.h}. @item Negative numbers turn positive. @tab Check SRS in @file{scmfig.h}. @item ;ERROR: bignum: numerical overflow @tab Increase NUMDIGS_MAX in @file{scmfig.h} and recompile. @item VMS: Couldn't unwind stack. @tab @t{#define CHEAP_CONTINUATIONS} in @file{scmfig.h}. @item VAX: botched longjmp. @end multitable @c @table @asis @c @item Sparc(SUN-4) heap is growing out of control @c You are experiencing a GC problem peculiar to the Sparc. The problem @c is that SCM doesn't know how to clear register windows. Every @c location which is not reused still gets marked at GC time. This @c causes lots of stuff which should be collected to not be. This will @c be a problem with any @emph{conservative} GC until we find what @c instruction will clear the register windows. This problem is @c exacerbated by using lots of call-with-current-continuations. @c A possible fix for dynthrow() is commented out in @file{continue.c}. @c @end table @node Reporting Problems, , Problems Running, Troubleshooting and Testing @subsection Reporting Problems @noindent Reported problems and solutions are grouped under Compiling, Linking, Running, and Testing. If you don't find your problem listed there, you can send a bug report to @code{agj@@alum.mit.edu} or @code{scm-discuss@@gnu.org}. The bug report should include: @enumerate @item The version of SCM (printed when SCM is invoked with no arguments). @item The type of computer you are using. @item The name and version of your computer's operating system. @item The values of the environment variables @code{SCM_INIT_PATH} and @code{SCHEME_LIBRARY_PATH}. @item The name and version of your C compiler. @item 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. @end enumerate @node Operational Features, The Language, Installing SCM, Top @chapter Operational Features @menu * Invoking SCM:: * SCM Options:: * Invocation Examples:: * SCM Variables:: * SCM Session:: * Editing Scheme Code:: * Debugging Scheme Code:: * Debugging Continuations:: * Errors:: * Memoized Expressions:: * Internal State:: * Scripting:: @end menu @node Invoking SCM, SCM Options, Operational Features, Operational Features @section Invoking SCM @example @exdent @b{ scm } [-a @i{kbytes}] [-muvbiq] @w{[--version]} @w{[--help]} @w{[[-]-no-init-file]} @w{[--no-symbol-case-fold]} @w{[-p @i{int}]} @w{[-r @i{feature}]} @w{[-h @i{feature}]} @w{[-d @i{filename}]} @w{[-f @i{filename}]} @w{[-l @i{filename}]} @w{[-c @i{expression}]} @w{[-e @i{expression}]} @w{[-o @i{dumpname}]} @w{[-- | - | -s]} @w{[@i{filename}]} @w{[@i{arguments} @dots{}]} @end example @noindent Upon startup @code{scm} loads the file specified by by the environment variable @var{SCM_INIT_PATH}. @noindent If @var{SCM_INIT_PATH} is not defined or if the file it names is not present, @code{scm} tries to find the directory containing the executable file. If it is able to locate the executable, @code{scm} looks for the initialization file (usually @file{Init@value{SCMVERSION}.scm}) in platform-dependent directories relative to this directory. See @ref{File-System Habitat} for a blow-by-blow description. @noindent As a last resort (if initialization file cannot be located), the C compile parameter @var{IMPLINIT} (defined in the makefile or @file{scmfig.h}) is tried. @noindent Unless the option @code{-no-init-file} or @code{--no-init-file} occurs in the command line, or if @code{scm} is being invoked as a script, @file{Init@value{SCMVERSION}.scm} checks to see if there is file @file{ScmInit.scm} in the path specified by the environment variable @var{HOME} (or in the current directory if @var{HOME} is undefined). If it finds such a file, then it is loaded. @noindent @file{Init@value{SCMVERSION}.scm} then looks for command input from one of three sources: From an option on the command line, from a file named on the command line, or from standard input. @noindent This explanation applies to SCMLIT or other builds of SCM. @noindent Scheme-code files can also invoke SCM and its variants. @xref{Lexical Conventions, #!}. @node SCM Options, Invocation Examples, Invoking SCM, Operational Features @section Options @noindent The options are processed in the order specified on the command line. @deffn {Command Option} -a k specifies that @code{scm} should allocate an initial heapsize of @var{k} kilobytes. This option, if present, must be the first on the command line. If not specified, the default is @code{INIT_HEAP_SIZE} in source file @file{setjump.h} which the distribution sets at @code{25000*sizeof(cell)}. @end deffn @deffn {Command Option} -no-init-file @deffnx {Command Option} ---no-init-file Inhibits the loading of @file{ScmInit.scm} as described above. @end deffn @deffn {Command Option} --no-symbol-case-fold Symbol (and identifier) names will be case sensitive. @end deffn @deffn {Command Option} ---help prints usage information and URI; then exit. @end deffn @deffn {Command Option} ---version prints version information and exit. @end deffn @deffn {Command Option} -r feature requires @var{feature}. This will load a file from [SLIB] if that @var{feature} is not already provided. If @var{feature} is 2, 2rs, or r2rs; 3, 3rs, or r3rs; 4, 4rs, or r4rs; 5, 5rs, or r5rs; @code{scm} will require the features neccessary to support [R2RS]; [R3RS]; [R4RS]; or [R5RS], respectively. @end deffn @deffn {Command Option} -h feature provides @var{feature}. @end deffn @deffn {Command Option} -l filename @deffnx {Command Option} -f filename loads @var{filename}. @code{Scm} will load the first (unoptioned) file named on the command line if no @code{-c}, @code{-e}, @code{-f}, @code{-l}, or @code{-s} option preceeds it. @end deffn @deffn {Command Option} -d filename Loads SLIB @code{databases} feature and opens @var{filename} as a database. @end deffn @deffn {Command Option} -e expression @deffnx {Command Option} -c expression specifies that the scheme expression @var{expression} is to be evaluated. These options are inspired by @code{perl} and @code{sh} respectively. On Amiga systems the entire option and argument need to be enclosed in quotes. For instance @samp{"-e(newline)"}. @end deffn @deffn {Command Option} -o dumpname saves the current SCM session as the executable program @file{dumpname}. This option works only in SCM builds supporting @code{dump} (@pxref{Dump}). If options appear on the command line after @samp{-o @var{dumpname}}, then the saved session will continue with processing those options when it is invoked. Otherwise the (new) command line is processed as usual when the saved image is invoked. @end deffn @deffn {Command Option} -p level sets the prolixity (verboseness) to @var{level}. This is the same as the @code{scm} command (verobse @var{level}). @end deffn @deffn {Command Option} -v (verbose mode) specifies that @code{scm} will print prompts, evaluation times, notice of loading files, and garbage collection statistics. This is the same as @code{-p3}. @end deffn @deffn {Command Option} -q (quiet mode) specifies that @code{scm} will print no extra information. This is the same as @code{-p0}. @end deffn @deffn {Command Option} -m specifies that subsequent loads, evaluations, and user interactions will be with syntax-rules macro capability. To use a specific syntax-rules macro implementation from [SLIB] (instead of [SLIB]'s default) put @code{-r} @var{macropackage} before @code{-m} on the command line. @end deffn @deffn {Command Option} -u specifies that subsequent loads, evaluations, and user interactions will be without syntax-rules macro capability. Syntax-rules macro capability can be restored by a subsequent @code{-m} on the command line or from Scheme code. @end deffn @deffn {Command Option} -i specifies that @code{scm} should run interactively. That means that @code{scm} will not terminate until the @code{(quit)} or @code{(exit)} command is given, even if there are errors. It also sets the prolixity level to 2 if it is less than 2. This will print prompts, evaluation times, and notice of loading files. The prolixity level can be set by subsequent options. If @code{scm} is started from a tty, it will assume that it should be interactive unless given a subsequent @code{-b} option. @end deffn @deffn {Command Option} -b specifies that @code{scm} should run non-interactively. That means that @code{scm} will terminate after processing the command line or if there are errors. @end deffn @deffn {Command Option} -s specifies, by analogy with @code{sh}, that @code{scm} should run interactively and that further options are to be treated as program aguments. @end deffn @deffn {Command Option} - @deffnx {Command Option} --- specifies that further options are to be treated as program aguments. @end deffn @node Invocation Examples, SCM Variables, SCM Options, Operational Features @section Invocation Examples @table @code @item % scm foo.scm Loads and executes the contents of @file{foo.scm} and then enters interactive session. @item % scm -f foo.scm arg1 arg2 arg3 Parameters @code{arg1}, @code{arg2}, and @code{arg3} are stored in the global list @code{*argv*}; Loads and executes the contents of @file{foo.scm} and exits. @item % scm -s foo.scm arg1 arg2 Sets *argv* to @code{("foo.scm" "arg1" "arg2")} and enters interactive session. @item % scm -e `(write (list-ref *argv* *optind*))' bar Prints @samp{"bar"}. @item % scm -rpretty-print -r format -i Loads @code{pretty-print} and @code{format} and enters interactive session. @item % scm -r5 Loads @code{dynamic-wind}, @code{values}, and syntax-rules macros and enters interactive (with macros) session. @item % scm -r5 -r4 Like above but @code{rev4-optional-procedures} are also loaded. @end table @node SCM Variables, SCM Session, Invocation Examples, Operational Features @section Environment Variables @defvr {Environment Variable} SCM_INIT_PATH is the pathname where @code{scm} will look for its initialization code. The default is the file @file{Init@value{SCMVERSION}.scm} in the source directory. @end defvr @defvr {Environment Variable} SCHEME_LIBRARY_PATH is the [SLIB] Scheme library directory. @end defvr @defvr {Environment Variable} HOME is the directory where @file{Init@value{SCMVERSION}.scm} will look for the user initialization file @file{ScmInit.scm}. @end defvr @defvr {Environment Variable} EDITOR is the name of the program which @code{ed} will call. If @var{EDITOR} is not defined, the default is @samp{ed}. @end defvr @section Scheme Variables @defvar *argv* contains the list of arguments to the program. @code{*argv*} can change during argument processing. This list is suitable for use as an argument to [SLIB] @code{getopt}. @end defvar @defvar *syntax-rules* controls whether loading and interaction support syntax-rules macros. Define this in @file{ScmInit.scm} or files specified on the command line. This can be overridden by subsequent @code{-m} and @code{-u} options. @end defvar @defvar *interactive* controls interactivity as explained for the @code{-i} and @code{-b} options. Define this in @file{ScmInit.scm} or files specified on the command line. This can be overridden by subsequent @code{-i} and @code{-b} options. @end defvar @node SCM Session, Editing Scheme Code, SCM Variables, Operational Features @section SCM Session @itemize @bullet @item Options, file loading and features can be specified from the command line. @xref{System interface, , , scm, SCM}. @xref{Require, , , slib, SLIB}. @item Typing the end-of-file character at the top level session (while SCM is not waiting for parenthesis closure) causes SCM to exit. @item Typing the interrupt character aborts evaluation of the current form and resumes the top level read-eval-print loop. @end itemize @defun quit @defunx quit n @defunx exit @defunx exit n Aliases for @code{exit} (@pxref{System, exit, , slib, SLIB}). On many systems, SCM can also tail-call another program. @xref{I/O-Extensions, execp}. @end defun @deffn {Callback procedure} boot-tail dumped? @code{boot-tail} is called by @code{scm_top_level} just before entering interactive top-level. If @code{boot-tail} calls @code{quit}, then interactive top-level is not entered. @end deffn @defun program-arguments Returns a list of strings of the arguments scm was called with. @end defun @defun getlogin Returns the (login) name of the user logged in on the controlling terminal of the process, or #f if this information cannot be determined. @end defun @noindent For documentation of the procedures @code{getenv} and @code{system} @xref{System Interface, , , slib, SLIB}. SCM extends @code{getenv} as suggested by draft SRFI-98: @defun getenv name Looks up @var{name}, a string, in the program environment. If @var{name} is found a string of its value is returned. Otherwise, @code{#f} is returned. @end defun @defun getenv Returns names and values of all the environment variables as an association-list. @example (getenv) @result{} (("PATH" . "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin") ("USERNAME" . "taro")) @end example @end defun @defun vms-debug If SCM is compiled under VMS this @code{vms-debug} will invoke the VMS debugger. @end defun @node Editing Scheme Code, Debugging Scheme Code, SCM Session, Operational Features @section Editing Scheme Code @defun ed arg1 @dots{} The value of the environment variable @code{EDITOR} (or just @code{ed} if it isn't defined) is invoked as a command with arguments @var{arg1} @dots{}. @end defun @defun ed filename If SCM is compiled under VMS @code{ed} will invoke the editor with a single the single argument @var{filename}. @end defun @table @asis @item Gnu Emacs: Editing of Scheme code is supported by emacs. Buffers holding files ending in .scm are automatically put into scheme-mode. If your Emacs can run a process in a buffer you can use the Emacs command @samp{M-x run-scheme} with SCM. Otherwise, use the emacs command @samp{M-x suspend-emacs}; or see ``other systems'' below. @item Epsilon (MS-DOS): There is lisp (and scheme) mode available by use of the package @samp{LISP.E}. It offers several different indentation formats. With this package, buffers holding files ending in @samp{.L}, @samp{.LSP}, @samp{.S}, and @samp{.SCM} (my modification) are automatically put into lisp-mode. It is possible to run a process in a buffer under Epsilon. With Epsilon 5.0 the command line options @samp{-e512 -m0} are neccessary to manage RAM properly. It has been reported that when compiling SCM with Turbo C, you need to @samp{#define NOSETBUF} for proper operation in a process buffer with Epsilon 5.0. One can also call out to an editor from SCM if RAM is at a premium; See ``under other systems'' below. @item other systems: Define the environment variable @samp{EDITOR} to be the name of the editing program you use. The SCM procedure @code{(ed arg1 @dots{})} will invoke your editor and return to SCM when you exit the editor. The following definition is convenient: @example (define (e) (ed "work.scm") (load "work.scm")) @end example Typing @samp{(e)} will invoke the editor with the file of interest. After editing, the modified file will be loaded. @end table @node Debugging Scheme Code, Debugging Continuations, Editing Scheme Code, Operational Features @section Debugging Scheme Code @noindent The @code{cautious} option of @code{build} (@pxref{Build Options}) supports debugging in Scheme. @table @dfn @item CAUTIOUS If SCM is built with the @samp{CAUTIOUS} flag, then when an error occurs, a @dfn{stack trace} of certain pending calls are printed as part of the default error response. A (memoized) expression and newline are printed for each partially evaluated combination whose procedure is not builtin. See @ref{Memoized Expressions} for how to read memoized expressions. Also as the result of the @samp{CAUTIOUS} flag, both @code{error} and @code{user-interrupt} (invoked by @key{C-c}) to print stack traces and conclude by calling @code{breakpoint} (@pxref{Breakpoints, , , slib, SLIB}) instead of aborting to top level. Under either condition, program execution can be resumed by @code{(continue)}. In this configuration one can interrupt a running Scheme program with @key{C-c}, inspect or modify top-level values, trace or untrace procedures, and continue execution with @code{(continue)}. @end table If @code{verbose} (@pxref{Internal State, verbose}) is called with an argument greater than 2, then the interpreter will check stack size periodically. If the size of stack in use exceeds the C #define @code{STACK_LIMIT} (default is @code{HEAP_SEG_SIZE}), SCM generates a @samp{stack} @code{segment violation}. @noindent There are several SLIB macros which so useful that SCM automatically loads the appropriate module from SLIB if they are invoked. @defmac trace proc1 @dots{} Traces the top-level named procedures given as arguments. @end defmac @defmac trace With no arguments, makes sure that all the currently traced identifiers are traced (even if those identifiers have been redefined) and returns a list of the traced identifiers. @end defmac @defmac untrace proc1 @dots{} Turns tracing off for its arguments. @end defmac @defmac untrace With no arguments, untraces all currently traced identifiers and returns a list of these formerly traced identifiers. @end defmac The routines I use most frequently for debugging are: @defun print arg1 @dots{} @code{Print} writes all its arguments, separated by spaces. @code{Print} outputs a @code{newline} at the end and returns the value of the last argument. One can just insert @samp{(print '