From 1edcb9b62a1a520eddae8403c19d841c9b18737f Mon Sep 17 00:00:00 2001 From: Bryan Newbold Date: Mon, 20 Feb 2017 00:05:24 -0800 Subject: Import Upstream version 5b3 --- scm.texi | 3780 ++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 2214 insertions(+), 1566 deletions(-) (limited to 'scm.texi') diff --git a/scm.texi b/scm.texi index d7270f6..5d93f63 100644 --- a/scm.texi +++ b/scm.texi @@ -5,6 +5,13 @@ @setchapternewpage on @c Choices for setchapternewpage are {on,off,odd}. @paragraphindent 2 +@defcodeindex ft +@syncodeindex ft tp +@c @dircategory Scheme +@c @direntry +@c * SCM: (scm). A Scheme interpreter. +@c @end direntry + @c %**end of header @iftex @@ -17,13 +24,13 @@ @titlepage @title SCM @subtitle Scheme Implementation -@subtitle Version 4e6 -@subtitle March 1996 +@subtitle Version 5b3 +@subtitle May 1997 @author by Aubrey Jaffer @page @vskip 0pt plus 1filll -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software Foundation +Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -40,7 +47,7 @@ except that this permission notice may be stated in a translation approved by the author. @end titlepage -@node Top, Copying, (dir), (dir) +@node Top, Overview, (dir), (dir) @ifinfo @@ -49,7 +56,7 @@ information about SCM can be found on SCM's @dfn{WWW} home page: @center http://www-swiss.ai.mit.edu/~jaffer/SCM.html -Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software Foundation +Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997 Free Software Foundation Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -74,9 +81,9 @@ by the author. @end ifinfo @menu -* Copying:: Conditions for copying and changing SCM. -* Overview:: Whats here and how to start using it. -* Installing SCM:: Where it goes and how to get it there. +* Overview:: +* Installing SCM:: +* Operational Features:: * The Language:: Reference. * Packages:: Optional Capabilities. * The Implementation:: How it works. @@ -85,8 +92,37 @@ by the author. * Type Index:: @end menu -@node Copying, Overview, Top, Top -@chapter Copying +@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. + +@iftex +@noindent +The most recent information about SCM can be found on SCM's @dfn{WWW} +home page: +@ifset html + +@end ifset + +@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html + +@ifset html + +@end ifset +@end iftex + +@menu +* Copying:: +* SCM Features:: +* SCM Authors:: +* Bibliography:: +@end menu + +@node Copying, SCM Features, Overview, Overview +@section Copying @center COPYRIGHT (c) 1989 BY @center PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS. @@ -158,42 +194,7 @@ INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. -@node Overview, Installing SCM, Copying, 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. - -@iftex -@noindent -The most recent information about SCM can be found on SCM's @dfn{WWW} -home page: -@ifset html - -@end ifset - -@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html - -@ifset html - -@end ifset -@end iftex - -@menu -* SCM Features:: -* SCM Authors:: -* Bibliography:: -* Invoking SCM:: -* SCM Options:: -* SCM Variables:: -* SCM Examples:: -* SCM Session:: -* Editing Scheme Code:: -* Debugging Scheme Code:: -@end menu - -@node SCM Features, SCM Authors, Overview, Overview +@node SCM Features, SCM Authors, Copying, Overview @section Features @itemize @bullet @@ -267,7 +268,7 @@ C-stack and being able to garbage collect off the C-stack 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 Bibliography, Invoking SCM, SCM Authors, Overview +@node Bibliography, , SCM Authors, Overview @section Bibliography @table @asis @@ -365,1567 +366,1448 @@ Documentation on the internal representation and how to extend or include @code{scm} in other programs. @end table -@node Invoking SCM, SCM Options, Bibliography, Overview -@section Invoking SCM +@node Installing SCM, Operational Features, Overview, Top +@chapter Installing SCM -@quotation -@exdent @b{ scm } [-a @i{kbytes}] [-ibvqmu] [-p @i{number}] -@w{[-c @i{expression}]} @w{[-e @i{expression}]} @w{[-f @i{filename}]} -@w{[-l @i{filename}]} @w{[-r @i{feature}]} @w{[-- | - | -s]} -@w{[@i{filename}]} @w{[@i{arguments} @dots{}]} -@end quotation +@menu +* Making SCM:: Bootstrapping. +* SLIB:: REQUIREd reading. +* Building SCM:: +* Installing Dynamic Linking:: +* Configure Module Catalog:: +* Saving Images:: Make Fast-Booting Executables +* Automatic C Preprocessor Definitions:: +* Problems Compiling:: +* Problems Linking:: +* Problems Running:: +* Testing:: +* Reporting Problems:: +@end menu -@noindent -Upon startup @code{scm} loads the file specified by by the environment -variable @var{SCM_INIT_PATH}. +@node Making SCM, SLIB, Installing SCM, Installing SCM +@section Making SCM -@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.scm}) in -platform-dependent directories relative to this directory. -@xref{File-System Habitat} for a blow-by-blow description. +The SCM distribution has @dfn{Makefile} which contains rules for making +@dfn{scmlit}, a ``bare-bones'' version of SCM sufficient for running +@file{build.scm}. @file{build.scm} is used to compile (or create +scripts to compile) full featured versions. -@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. +Makefiles are not portable to the majority of platforms. If +@file{Makefile} works for you, good; If not, I don't want to hear about +it. If you need to compile SCM without build.scm, there are several +ways to proceed: -@noindent -Unless the option @code{-no-init-file} or @code{--no-init-file} occurs -in the command line, @file{Init.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 it is loaded. +@itemize @bullet +@item +Use SCM on a different platform to run @file{build.scm} to create a +script to build SCM; + +@item +Use another implementation of Scheme to run @file{build.scm} to create a +script to build SCM; + +@item +Create your own script or @file{Makefile}. + +@item +Buy a SCM executable from jaffer@@ai.mit.edu. See the end of the +@file{ANNOUNCE} file in the distribution for details. + +@item +Use scmconfig (From: bos@@scrg.cs.tcd.ie): + +Build and install scripts using GNU @dfn{autoconf} are available from +@file{scmconfig4e3.tar.gz} in the distribution directories. See +@file{README.unix} in @file{scmconfig4e3.tar.gz} for further +instructions. + +@emph{Note:} The last release of scmconfig (4e3) was on March 20, 1996. +I am moving it to the OLD subdirectory until someone submits an update. +@end itemize + + +@node SLIB, Building SCM, Making SCM, Installing SCM +@section SLIB @noindent -@file{Init.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. +[SLIB] is a portable Scheme library meant to provide compatibility and +utility functions for all standard Scheme implementations. Although +SLIB is not @emph{neccessary} to run SCM, I strongly suggest you obtain +and install it. Bug reports about running SCM without SLIB have very +low priority. SLIB is available from the same sites as SCM: + +@ifclear html +@itemize @bullet +@item +ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz +@item +prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz +@item +ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz +@item +ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2c0.tar.gz +@end itemize +@end ifclear + +@ifset html + +ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz + + +prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz + + +ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz + + +ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c0.tar.gz + +@end ifset @noindent -This explanation applies to SCMLIT or other builds of SCM. +Unpack SLIB (@samp{tar xzf slib2c0.tar.gz} or @samp{unzip -ao +slib2c0.zip}) in an appropriate directory for your system; both +@code{tar} and @code{unzip} will create the directory @file{slib}. @noindent -Scheme-code files can also invoke SCM and its variants. @xref{Syntax -Extensions, #!}. +Then create a file @file{require.scm} in the SCM +@dfn{implementation-vicinity} (this is the same directory as where the +file @file{Init.scm} is installed). @file{require.scm} should have the +contents: -@node SCM Options, SCM Variables, Invoking SCM, Overview -@section Options +@example +(define (library-vicinity) "/usr/local/lib/slib/") +(load (in-vicinity (library-vicinity) "require")) +@end example @noindent -The options are processed in the order specified on the command line. +where the pathname string @file{/usr/local/lib/slib/} is to be replaced +by the pathname into which you installed SLIB. 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: -@deffn {Command Option} -a kb -specifies that @code{scm} should allocate an initial heapsize of -@var{kb} 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 +@example +(define library-vicinity + (let ((lv (string-append (implementation-vicinity) "../slib/"))) + (lambda () lv))) +(load (in-vicinity (library-vicinity) "require")) +@end example -@deffn {Command Option} -no-init-file -@deffnx {Command Option} --no-init-file -Inhibits the loading of @file{ScmInit.scm} as described above. -@end deffn +@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, the environment variable overrides @file{require.scm}. Again, +absolute pathnames are recommended. -@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} -r feature -requires @var{feature}. This will load a file from [SLIB] if that -@var{feature} is not already supported. If @var{feature} is 2, 3, 4, or -5 @code{scm} will require the features neccessary to support [R2RS], -[R3RS], [R4RS], or proposed [R5RS], respectively. -@end deffn +@node Building SCM, Installing Dynamic Linking, SLIB, Installing SCM +@section Building SCM -@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 +The file @dfn{build.scm} builds and runs a relational database of how to +compile and link SCM executables. It has information for most 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 jaffer@@ai.mit.edu. -@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 +@menu +* Invoking Build:: +* Build Options:: +* Compiling and Linking Custom Files:: +@end menu -@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 +@node Invoking Build, Build Options, Building SCM, Building SCM +@subsection Invoking Build -@deffn {Command Option} -q -(quiet mode) specifies that @code{scm} will print no extra -information. This is the same as @code{-p0}. -@end deffn +@noindent +The @emph{all} method will also work for MS-DOS and unix. Use +the @emph{all} method if you encounter problems with @file{build.scm}. -@deffn {Command Option} -m -specifies that subsequent loads, evaluations, and user interactions will -be with [R4RS] macro capability. To use a specific [R4RS] 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 [R4RS] macro capability. [R4RS] 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 further options are to be -treated as program aguments. -@end deffn +@table @asis +@item MS-DOS +From the SCM source directory, type @samp{build} followed by up to 9 +command line arguments. -@deffn {Command Option} - -@deffnx {Command Option} -- -specifies that there are no more options on the command line. -@end deffn +@item unix +From the SCM source directory, type @samp{./build.scm} followed by command +line arguments. -@deffn {Command Option} -d filename -loads SLIB database-utilities and opens @var{filename} as a database. -@end deffn +@item @emph{all} +From the SCM source directory, start @samp{scm} or @samp{scmlit} and +type @code{(load "build.scm")}. Alternatively, start @samp{scm} or +@samp{scmlit} with the command line argument @samp{-ilbuild}. -@deffn {Command Option} -o filename -saves the current SCM session as the executable program @file{filename}. -This option works only in SCM builds supporting @code{dump} -(@pxref{Dump}). +@end table -If options appear on the command line after @samp{-o @var{filename}}, -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 +@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. -@deffn {Command Option} --help -prints usage information and URL; then exit. -@end deffn +@example +bash$ ./build.scm +@print{} +#!/bin/sh +rm -f scmflags.h +echo '#define IMPLINIT "/home/jaffer/scm/Init.scm"'>>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 +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 -lm -lc +@end example -@deffn {Command Option} --version -prints version information and exit. -@end deffn +@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. -@node SCM Variables, SCM Examples, SCM Options, Overview -@section Environment Variables +@example +bash$ ./build.scm -p vms +@print{} +$DELETE scmflags.h +$CREATE scmflags.h +$DECK +#define IMPLINIT "/home/jaffer/scm/Init.scm" +#define BIGNUMS +#define FLOATS +#define ARRAYS +$EOD +$ cc continue scm findexec script time repl scl eval sys subr unif rope +$ macro setjump +$ link continue,scm,findexec,script,time,repl,scl,eval,sys,subr,unif,rope,setjump,sys$input/opt + -lc,sys$share:vaxcrtl/share +$RENAME continue.exe scm.exe +@end example -@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.scm} in the source directory. -@end defvr -@defvr {Environment Variable} SCHEME_LIBRARY_PATH -is the [SLIB] Scheme library directory. -@end defvr +@node Build Options, Compiling and Linking Custom Files, Invoking Build, Building SCM +@subsection Build Options -@defvr {Environment Variable} HOME -is the directory where @file{Init.scm} will look for the user -initialization file @file{ScmInit.scm}. -@end defvr +@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. -@section Scheme Variables +@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. -@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 +The platforms defined by table @dfn{platform} in @file{build.scm} are: +@end deffn +@example +name processor operating-system compiler +symbol processor-family operating-system symbol +symbol atom symbol symbol +================= ================= ================= ================= +*unknown* *unknown* unix *unknown* +acorn-unixlib acorn *unknown* *unknown* +aix powerpc aix *unknown* +amiga-aztec m68000 amiga aztec +amiga-dice-c m68000 amiga dice-c +amiga-gcc m68000 amiga gcc +amiga-sas/c-5.10 m68000 amiga sas/c +atari-st-gcc m68000 atari.st gcc +atari-st-turbo-c m68000 atari.st turbo-c +borland-c-3.1 8086 ms-dos borland-c +djgpp i386 ms-dos gcc +gcc *unknown* unix gcc +highc.31 i386 ms-dos highc +hp-ux hp-risc hp-ux *unknown* +linux i386 linux gcc +linux-aout i386 linux gcc +microsoft-c 8086 ms-dos microsoft-c +microsoft-c-nt i386 ms-dos microsoft-c +microsoft-quick-c 8086 ms-dos microsoft-quick-c +ms-dos 8086 ms-dos *unknown* +os/2-cset i386 os/2 c-set++ +os/2-emx i386 os/2 gcc +sunos sparc sunos *unknown* +svr4 *unknown* unix *unknown* +turbo-c-2 8086 ms-dos turbo-c +unicos cray unicos *unknown* +unix *unknown* unix *unknown* +vms vax vms *unknown* +vms-gcc vax vms gcc +watcom-9.0 i386 ms-dos watcom +@end example -@defvar *R4RS-macro* -controls whether loading and interaction support [R4RS] 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 +@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 -@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 +@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 -@node SCM Examples, SCM Session, SCM Variables, Overview -@section Examples +@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 -@table @code -@item % scm foo.scm -Loads and executes the contents of @file{foo.scm} and then enters -interactive session. +@deffn {Build Option} ---compiler-options=@var{flag} +specifies that that @var{flag} will be put on compiler command-lines. +@end deffn -@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. +@deffn {Build Option} ---linker-options=@var{flag} +specifies that that @var{flag} will be put on linker command-lines. +@end deffn -@item % scm -s foo.scm arg1 arg2 -Sets *argv* to @code{("foo.scm" "arg1" "arg2")} and enters interactive -session. +@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.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 -@item % scm -e `(write (list-ref *argv* *optind*))' bar -Prints @samp{"bar"}. +@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 -@item % scm -rpretty-print -r format -i -Loads @code{pretty-print} and @code{format} and enters interactive -session. +@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 -@item % scm -r5 -Loads @code{dynamic-wind}, @code{values}, and [R4RS] macros and enters -interactive (with macros) session. +@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 -@item % scm -r5 -r4 -Like above but @code{rev4-optional-procedures} are also loaded. +@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 -@node SCM Session, Editing Scheme Code, SCM Examples, Overview -@section SCM Session +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 -Options, file loading and features can be specified from the command -line. @xref{System interface, , , scm, SCM}. @xref{Require, , , slib, -SLIB}. +unix @item -Typing the end-of-file character at the top level session (while SCM is -not waiting for parenthesis closure) causes SCM to exit. +dos @item -Typing the interrupt character aborts evaluation of the current form -and resumes the top level read-eval-print loop. -@end itemize +vms +@item +system -@node Editing Scheme Code, Debugging Scheme Code, SCM Session, Overview -@section Editing Scheme Code +This option executes the compilation and linking commands through the +use of the @code{system} procedure. +@item +*unknown* -@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. However, the run-scheme -(@file{xscheme.el}) which comes included with Gnu Emacs 18 will work -only with MIT Cscheme. If you are using Emacs 18, get the emacs -packages: - -@ifclear html -@itemize @bullet -@item -ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/cmuscheme.el -@item -ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/comint.el +This option outputs Scheme code. @end itemize -@end ifclear - -@ifset html - -ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/cmuscheme.el - - -ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/comint.el - -@end ifset +@end deffn -These files are already standard in Emacs 19. +@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 -If your Emacs can not run a process in a buffer, see ``under other -systems'' below. +@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: -@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. +@table @dfn +@item lit +@itemx none +Lightweight -- no features -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. +@item cautious +Normally, the number of arguments arguments to interpreted closures + (from LAMBDA) are checked if the function part of a form is not a +symbol or only the first time the form is executed if the function part +is a symbol. defining @samp{reckless} disables any checking. If you +want to have SCM always check the number of arguments to interpreted +closures define feature @samp{cautious}. -One can also call out to an editor from SCM if RAM is at a premium; See -``under other systems'' below. +@item careful-interrupt-masking +Define this for extra checking of interrupt masking. This is for +debugging C code in @file{sys.c} and @file{repl.c}. -@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: +@item debug +Turns on features @samp{cautious} @samp{careful-interrupt-masking} +@samp{stack-limit} and uses @code{-g} flags for debugging SCM source +code. -@example -(define (e) (ed "work.scm") (load "work.scm")) -@end example +@item reckless +If your scheme code runs without any errors you can disable almost all +error checking by compiling all files with @samp{reckless}. -Typing @samp{(e)} will invoke the editor with the file of interest. -After editing, the modified file will be loaded. -@end table +@item stack-limit +Use to enable checking for stack overflow. Define value of the C +preprocessor variable @var{STACK_LIMIT} to be the size to which SCM +should allow the stack to grow. STACK_LIMIT should be less than the +maximum size the hardware can support, as not every routine checks the +stack. -@node Debugging Scheme Code, , Editing Scheme Code, Overview -@section Debugging Scheme Code +@item bignums +Large precision integers. -@noindent -The @code{cautious} and @code{stack-limit} options of @code{build} -(@pxref{Build Options}) support debugging in Scheme. +@item arrays +Use if you want arrays, uniform-arrays and uniform-vectors. -@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. @xref{Memoized Expressions} for how to read memoized -expressions. +@item array-for-each +array-map! and array-for-each (arrays must also be defined). -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)}. +@item inexact +Use if you want floating point numbers. -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)}. +@item engineering-notation +Use if you want floats to display in engineering notation (exponents +always multiples of 3) instead of scientific notation. -@item STACK_LIMIT -If SCM is built with the @samp{STACK_LIMIT} flag, the interpreter will -check stack size periodically. If the size of stack exceeds a certain -amount (default is @code{HEAP_SEG_SIZE/2}), SCM generates a -@code{segment violation} interrupt. +@item single-precision-only +Use if you want all inexact real numbers to be single precision. This +only has an effect if SINGLES is also defined (which is the default). +This does not affect complex numbers. -The usefulness of @samp{STACK_LIMIT} depends on the user. I don't use -it; but the user I added this feature for got primarily this type of -error. -@end table +@item sicp +Use if you want to run code from: -@noindent -There are several SLIB macros which so useful that SCM automatically -loads the appropriate module from SLIB if they are invoked. +H. Abelson, G. J. Sussman, and J. Sussman, +Structure and Interpretation of Computer Programs, +The MIT Press, Cambridge, Massachusetts, USA -@defmac trace proc1 @dots{} -Traces the top-level named procedures given as arguments. -@defmacx 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 +@code{(eq? '() '#f)} is the major difference. -@defmac untrace proc1 @dots{} -Turns tracing off for its arguments. -@defmacx untrace -With no arguments, untraces all currently traced identifiers and returns -a list of these formerly traced identifiers. -@end defmac +@item rev2-procedures +These procedures were specified in the @cite{Revised^2 Report on Scheme} +but not in @cite{R4RS}. -The routine I use most for debugging is: +@item record +The Record package provides a facility for user to define their own +record data types. See SLIB for documentation. -@deffn Procedure print arg1 ... -@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. +@item compiled-closure +Use if you want to use compiled closures. -One can just insert @samp{(print '} and @samp{)} around an -expression in order to see its value as a program operates. -@end deffn +@item generalized-c-arguments +@code{make_gsubr} for arbitrary (< 11) arguments to C functions. -@noindent -Sometimes more elaborate measures are needed to print values in a useful -manner. When the values to be printed may have very large (or infinite) -external representations, @ref{Quick Print, , , slib, SLIB}, can be -used. +@item tick-interrupts +Use if you want the ticks and ticks-interrupt functions. -When @code{trace} is not sufficient to find program flow problems, -@ifset html - -@end ifset -SLIB-PSD, the Portable Scheme Debugger -@ifset html - -@end ifset -offers source code debugging from -GNU Emacs. PSD runs slowly, so start by instrumenting only a few -functions at a time. -@lisp -ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz -prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz -ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz -ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz -@end lisp +@item i/o-extensions +Commonly available I/O extensions: @dfn{exec}, line I/O, file +positioning, file delete and rename, and directory functions. +@item turtlegr +@dfn{Turtle} graphics calls for both Borland-C and X11 from +sjm@@ee.tut.fi. -@node Installing SCM, The Language, Overview, Top -@chapter Installing SCM +@item curses +For the @dfn{curses} screen management package. -@menu -* File-System Habitat:: All the usual suspects. -* Executable Pathname:: Where did I come from? -* Making SCM:: -* Building SCM:: -* SLIB:: REQUIREd reading. -* Installing Dynamic Linking:: -* Saving Images:: Make Fast-Booting Executables -* Automatic C Preprocessor Definitions:: -* Problems Compiling:: -* Problems Linking:: -* Problems Running:: -* Testing:: -* Reporting Problems:: -@end menu +@item edit-line +interface to the editline or GNU readline library. -@node File-System Habitat, Executable Pathname, Installing SCM, Installing SCM -@section File-System Habitat +@item regex +String regular expression matching. -@noindent -Where should software reside? Although individually a minor annoyance, -cumulatively this question represents many thousands of frustrated user -hours spent trying to find support files or guessing where packages need -to be installed. Even simple programs require proper habitat; games -need to find their score files. +@item socket +BSD @dfn{socket} interface. -@noindent -Aren't there standards for this? Some Operating Systems have devised -regimes of software habitats -- only to have them violated by large -software packages and imports from other OS varieties. +@item posix +Posix functions available on all @dfn{Unix-like} systems. fork and +process functions, user and group IDs, file permissions, and @dfn{link}. -@noindent -In some programs, the expected locations of support files are fixed at -time of compilation. This means that the program may not run on -configurations unanticipated by the authors. Compiling locations into a -program also can make it immovable -- necessitating recompilation to -install it. +@item unix +Those unix features which have not made it into the Posix specs: nice, +acct, lstat, readlink, symlink, mknod and sync. -@quotation -Programs of the world unite! You have nothing to lose but loss itself. -@end quotation +@item windows +Microsoft Windows executable. -@noindent -The function @code{scm_find_impl_file} in @file{scm.c} is an attempt to -create a utility (for inclusion in programs) which will hide the details -of platform-dependent file habitat conventions. It takes as input the -pathname of the executable file which is running. If there are systems -for which this information is either not available or unrelated to the -locations of support files, then a higher level interface will be -needed. +@item dynamic-linking +Be able to load compiled files while running. -@deftypefun char *scm_find_impl_file(char *@var{exec_path}, char -*@var{generic_name}, char *@var{initname}, char *@var{sep}) Given the -pathname of this executable (@var{exec_path}), test for the existence of -@var{initname} in the implementation-vicinity of this program. Return a -newly allocated string of the path if successful, 0 if not. The -@var{sep} argument is a @emph{mull-terminated string} of the character -used to separate directory components. -@end deftypefun +@item dump +Convert a running scheme program into an executable file. -@itemize @bullet -@item -One convention is to install the support files for an executable program -in the same directory as the program. This possibility is tried first, -which satisfies not only programs using this convention, but also -uninstalled builds when testing new releases, etc. - -@item -Another convention is to install the executables in a directory named -@file{bin}, @file{BIN}, @file{exe}, or @file{EXE} and support files in a -directroy named @file{lib}, which is a peer the executable directory. -This arrangement allows multiple executables can be stored in a single -directory. For example, the executable might be in -@samp{/usr/local/bin/} and initialization file in -@samp{/usr/local/lib/}. +@item heap-can-shrink +Use if you want segments of unused heap to not be freed up after garbage +collection. This may reduce time in GC for *very* large working sets. -If the executable directory name matches, the peer directroy @file{lib} -is tested for @var{initname}. +@item cheap-continuations +If you only need straight stack continuations, executables compile with +this feature will run faster and use less storage than not having it. +Machines with unusual stacks @emph{need} this. Also, if you incorporate +new C code into scm which uses VMS system services or library routines +(which need to unwind the stack in an ordrly manner) you may need to +use this feature. -@item -Sometimes @file{lib} directories become too crowded. So we look in any -subdirectories of @file{lib} or @file{src} having the name (sans type -suffix such as @samp{.EXE}) of the program we are running. For example, -the executable might be @samp{/usr/local/bin/foo} and initialization -file in @samp{/usr/local/lib/foo/}. +@item macro +C level support for hygienic and referentially transparent macros (R4RS +macros). -@item -But the executable name may not be the usual program name; So also look -in any @var{generic_name} subdirectories of @file{lib} or @file{src} -peers. +@end table +@end deffn -@item -Finally, if the name of the executable file being run has a (system -dependent) suffix which is not needed to invoke the program, then look -in a subdirectory (of the one containing the executable file) named for -the executable (without the suffix); And look in a @var{generic_name} -subdirectory. For example, the executable might be -@samp{C:\foo\bar.exe} and the initialization file in @samp{C:\foo\bar\}. -@end itemize +@node Compiling and Linking Custom Files, , Build Options, Building SCM +@subsection Compiling and Linking Custom Files +@noindent +A correspondent asks: -@node Executable Pathname, Making SCM, File-System Habitat, Installing SCM -@section Executable Pathname +@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 -When a program is executed by MS-DOS, the full pathname of that -executable is available in @code{argv[0]}. This value can be passed to -@code{dld_find_executable} (@pxref{File-System Habitat}). +(@pxref{Changing Scm} has instructions describing the C code format). +@cindex foo.c +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: -In order to find the habitat for a unix program, we first need to know -the full pathname for the associated executable file. +@example +bash$ build -c foo.c -i init_foo +@print{} +#!/bin/sh +rm -f scmflags.h +echo '#define IMPLINIT "/home/jaffer/scm/Init.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 -@deftypefun char *dld_find_executable (const char *@var{command}) -@code{dld_find_executable} returns the absolute path name of the file -that would be executed if @var{command} were given as a command. It -looks up the environment variable @var{PATH}, searches in each of the -directory listed for @var{command}, and returns the absolute path name -for the first occurrence. Thus, it is advisable to invoke -@code{dld_init} as: +@noindent +To make a dynamically loadable object file use the @code{-t dll} option: @example -main (int argc, char **argv) -@{ - @dots{} - if (dld_init (dld_find_executable (argv[0]))) @{ - @dots{} - @} - @dots{} -@} +bash$ build -t dll -c foo.c +@print{} +#!/bin/sh +rm -f scmflags.h +echo '#define IMPLINIT "/home/jaffer/scm/Init.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 -@quotation -@strong{Note:} If the current process is executed using the -@code{execve} call without passing the correct path name as argument 0, -@code{dld_find_executable (argv[0]) } will also fail to locate the -executable file. -@end quotation - -@code{dld_find_executable} returns zero if @code{command} is not found -in any of the directories listed in @code{PATH}. -@end deftypefun +@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")}. @xref{Configure Module Catalog} for how to +add a compiled dll file to SLIB's catalog. -@node Making SCM, Building SCM, Executable Pathname, Installing SCM -@section Making SCM +@node Installing Dynamic Linking, Configure Module Catalog, Building SCM, Installing SCM +@section Installing Dynamic Linking -The SCM distribution has @dfn{Makefile} which contains rules for making -@dfn{scmlit}, a ``bare-bones'' version of SCM sufficient for running -@file{build.scm}. @file{build.scm} is used to compile (or create -scripts to compile) full featured versions. +@noindent +Dynamic linking has not been ported to all platforms. Operating systems +in the BSD family (a.out binary format) can usually be ported to +@dfn{DLD}. The @dfn{dl} library (@code{#define SUN_DL} for SCM) was a +proposed POSIX standard and may be available on other machines with +@dfn{COFF} binary format. For notes about porting to MS-Windows and +finishing the port to VMS @ref{Finishing Dynamic Linking}. -Makefiles are not portable to the majority of platforms. If -@file{Makefile} works for you, good; If not, I don't want to hear about -it. If you need to compile SCM without build.scm, there are several -ways to proceed: +@noindent +@dfn{DLD} is a library package of C functions that performs @dfn{dynamic +link editing} on Linux, VAX (Ultrix), Sun 3 (SunOS 3.4 and 4.0), +SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and Atari ST. It is +available from: +@ifclear html @itemize @bullet @item -Use SCM on a different platform to run @file{build.scm} to create a -script to build SCM; +prep.ai.mit.edu:pub/gnu/dld-3.3.tar.gz +@end itemize +@end ifclear -@item -Use another implementation of Scheme to run @file{build.scm} to create a -script to build SCM; +@ifset html + +prep.ai.mit.edu:pub/gnu/dld-3.3.tar.gz + +@end ifset -@item -Create your own script or @file{Makefile}. +@noindent +These notes about using libdl on SunOS are from @file{gcc.info}: -@item -Buy a SCM executable from jaffer@@ai.mit.edu. See the end of the -@file{ANNOUNCE} file in the distribution for details. +@quotation +On a Sun, linking using GNU CC fails to find a shared library and +reports that the library doesn't exist at all. -@item -Use scmconfig (From: bos@@scrg.cs.tcd.ie): +This happens if you are using the GNU linker, because it does only +static linking and looks only for unshared libraries. If you have +a shared library with no unshared counterpart, the GNU linker +won't find anything. -Build and install scripts using GNU @dfn{autoconf} are available from -@file{scmconfig4e6.tar.gz} in the distribution directories. See -@file{README.unix} in @file{scmconfig4e6.tar.gz} for further -instructions. -@end itemize +We hope to make a linker which supports Sun shared libraries, but +please don't ask when it will be finished--we don't know. +Sun forgot to include a static version of @file{libdl.a} with some +versions of SunOS (mainly 4.1). This results in undefined symbols when +linking static binaries (that is, if you use @samp{-static}). If you +see undefined symbols @samp{_dlclose}, @samp{_dlsym} or @samp{_dlopen} +when linking, compile and link against the file +@file{mit/util/misc/dlsym.c} from the MIT version of X windows. +@end quotation -@node Building SCM, SLIB, Making SCM, Installing SCM -@section Building SCM -The file @dfn{build.scm} builds and runs a relational database of how to -compile and link SCM executables. It has information for most 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 jaffer@@ai.mit.edu. +@node Configure Module Catalog, Saving Images, Installing Dynamic Linking, Installing SCM +@section Configure Module Catalog -@menu -* Invoking Build:: -* Build Options:: -@end menu +@noindent +The SLIB module @dfn{catalog} can be extended to define other +@code{require}-able packages by adding calls to the Scheme source file +@file{mkimpcat.scm}. Within @file{mkimpcat.scm}, the following +procedures are defined. + +@defun add-link feature object-file lib1 @dots{} +@var{feature} should be a symbol. @var{object-file} should be a string +naming a file containing compiled @dfn{object-code}. Each @var{lib}n +argument should be either a string naming a library file or @code{#f}. + +If @var{object-file} exists, the @code{add-link} procedure registers +symbol @var{feature} so that the first time @code{require} is called +with the symbol @var{feature} as its argument, @var{object-file} and the +@var{lib1} @dots{} are dynamically linked into the executing SCM +session. -@node Invoking Build, Build Options, Building SCM, Building SCM -@subsection Invoking Build +If @var{object-file} exists, @code{add-link} returns @code{#t}, +otherwise it returns @code{#f}. -The @emph{all} method will also work for MS-DOS and unix. Use -the @emph{all} method if you encounter problems with @file{build.scm}. +For example, to install a compiled dll @file{foo}, add these lines to +@file{mkimpcat.scm}: -@table @asis -@item MS-DOS -From the SCM source directory, type @samp{build} followed by up to 9 -command line arguments. +@example + (add-link 'foo + (in-vicinity (implementation-vicinity) "foo" + link:able-suffix)) +@end example -@item unix -From the SCM source directory, type @samp{build.scm} followed by command -line arguments. -@item @emph{all} -From the SCM source directory, start @samp{scm} or @samp{scmlit} and -type @code{(load "build.scm")}. Alternatively, start @samp{scm} or -@samp{scmlit} with the command line argument @samp{-ilbuild}. +@end defun -@end table +@defun add-alias alias feature +@var{alias} and @var{feature} are symbols. The procedure +@code{add-alias} registers @var{alias} as an alias for @var{feature}. +An unspecified value is returned. -@node Build Options, , Invoking Build, Building SCM -@subsection Build Options +@code{add-alias} causes @code{(require '@var{alias})} to behave like +@code{(require '@var{feature})}. +@end defun + +@defun add-source feature filename +@var{feature} is a symbol. @var{filename} is a string naming a file +containing Scheme source code. The procedure @code{add-source} +registers @var{feature} so that the first time @code{require} is called +with the symbol @var{feature} as its argument, the file @var{filename} +will be @code{load}ed. An unspecified value is returned. +@end defun @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. +Remember to delete the file @file{slibcat} after modifying the file +@file{mkimpcat.scm} in order to force SLIB to rebuild its cache. -@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. +@node Saving Images, Automatic C Preprocessor Definitions, Configure Module Catalog, Installing SCM +@section Saving Images -The platforms defined by table @dfn{platform} in @file{build.scm} are: -@end deffn -@example -name processor operating-system compiler -symbol processor-family operating-system symbol -symbol atom symbol symbol -================= ================= ================= ================= -*unknown* *unknown* unix *unknown* -acorn-unixlib acorn *unknown* *unknown* -aix powerpc aix *unknown* -amiga-aztec m68000 amiga aztec -amiga-dice-c m68000 amiga dice-c -amiga-sas/c-5.10 m68000 amiga sas/c -atari-st-gcc m68000 atari.st gcc -atari-st-turbo-c m68000 atari.st turbo-c -borland-c-3.1 8086 ms-dos borland-c -djgpp i386 ms-dos gcc -gcc *unknown* unix gcc -highc.31 i386 ms-dos highc -hp-ux hp-risc hp-ux *unknown* -linux i386 linux gcc -linux-elf i386 linux gcc -microsoft-c 8086 ms-dos microsoft-c -microsoft-c-nt i386 ms-dos microsoft-c -microsoft-quick-c 8086 ms-dos microsoft-quick-c -ms-dos 8086 ms-dos *unknown* -os/2-cset i386 os/2 c-set++ -os/2-emx i386 os/2 gcc -sun sparc sun-os *unknown* -svr4 *unknown* unix *unknown* -turbo-c-2 8086 ms-dos turbo-c -unicos cray unicos *unknown* -unix *unknown* unix *unknown* -vms vax vms *unknown* -vms-gcc vax vms gcc -watcom-9.0 i386 ms-dos watcom -@end example +@noindent +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. -@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 +@noindent +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. -@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.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 -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 -@item lit -@itemx none -Lightweight -- no features - -@item cautious -Normally, the number of arguments arguments to interpreted closures - (from LAMBDA) are checked if the function part of a form is not a -symbol or only the first time the form is executed if the function part -is a symbol. defining @samp{reckless} disables any checking. If you -want to have SCM always check the number of arguments to interpreted -closures define feature @samp{cautious}. - -@item careful-interrupt-masking -Define this for extra checking of interrupt masking. This is for -debugging C code in @file{sys.c} and @file{repl.c}. - -@item debug -Turns on features @samp{cautious} @samp{careful-interrupt-masking} -@samp{stack-limit} and uses @code{-g} flags for debugging SCM source -code. - -@item reckless -If your scheme code runs without any errors you can disable almost all -error checking by compiling all files with @samp{reckless}. - -@item stack-limit -Use to enable checking for stack overflow. Define value of the C -preprocessor variable @var{STACK_LIMIT} to be the size to which SCM -should allow the stack to grow. STACK_LIMIT should be less than the -maximum size the hardware can support, as not every routine checks the -stack. - -@item bignums -Large precision integers. - -@item arrays -Use if you want arrays, uniform-arrays and uniform-vectors. +@node Automatic C Preprocessor Definitions, Problems Compiling, Saving Images, Installing SCM +@section Automatic C Preprocessor Definitions -@item array-for-each -array-map! and array-for-each (arrays must also be defined). +These @samp{#defines} are automatically provided by preprocessors of +various C compilers. SCM uses the presence or absence of these +definitions to configure @dfn{include file} locations and aliases for +library functions. If the definition(s) corresponding to your system +type is missing as your system is configured, add @code{-D@var{flag}} to +the compilation command lines or add a @code{#define @var{flag}} line to +@file{scmfig.h} or the beginning of @file{scmfig.h}. -@item inexact -Use if you want floating point numbers. +@example +#define Platforms: +------- ---------- +ARM_ULIB Huw Rogers free unix library for acorn archimedes +AZTEC_C Aztec_C 5.2a +_DCC Dice C on AMIGA +__GNUC__ Gnu CC (and DJGPP) +__EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0 +__HIGHC__ MetaWare High C +__IBMC__ C-Set++ on OS/2 2.1 +_MSC_VER MS VisualC++ 4.2 +MWC Mark Williams C on COHERENT +_QC Microsoft QuickC +__STDC__ ANSI C compliant +__TURBOC__ Turbo C and Borland C +__WATCOMC__ Watcom C on MS-DOS +__ZTC__ Zortech C -@item engineering-notation -Use if you want floats to display in engineering notation (exponents -always multiples of 3) instead of scientific notation. +_AIX AIX operating system +AMIGA SAS/C 5.10 or Dice C on AMIGA +__amigados__ Gnu CC on AMIGA +atarist ATARI-ST under Gnu CC +GNUDOS DJGPP (obsolete in version 1.08) +__GO32__ DJGPP (future?) +hpux HP-UX +linux Linux +MCH_AMIGA Aztec_c 5.2a on AMIGA +MSDOS Microsoft C 5.10 and 6.00A +__MSDOS__ Turbo C, Borland C, and DJGPP +nosve Control Data NOS/VE +SVR2 System V Revision 2. +__svr4__ SunOS +THINK_C developement environment for the Macintosh +ultrix VAX with ULTRIX operating system. +unix most Unix and similar systems and DJGPP (!?) +__unix__ Gnu CC and DJGPP +_UNICOS Cray operating system +vaxc VAX C compiler +VAXC VAX C compiler +vax11c VAX C compiler +VAX11 VAX C compiler +_Windows Borland C 3.1 compiling for Windows +_WIN32 MS VisualC++ 4.2 under Windows-NT +vms (and VMS) VAX-11 C under VMS. -@item single-precision-only -Use if you want all inexact real numbers to be single precision. This -only has an effect if SINGLES is also defined (which is the default). -This does not affect complex numbers. +__alpha DEC Alpha processor +__alpha__ DEC Alpha processor +hp9000s800 HP RISC processor +__i386__ DJGPP +i386 DJGPP +MULTIMAX Encore computer +pyr Pyramid 9810 processor +__sgi__ Silicon Graphics Inc. +sparc SPARC processor +sequent Sequent computer +tahoe CCI Tahoe processor +vax VAX processor +@end example -@item sicp -Use if you want to run code from: +@node Problems Compiling, Problems Linking, Automatic C Preprocessor Definitions, Installing SCM +@section Problems Compiling -H. Abelson, G. J. Sussman, and J. Sussman, -Structure and Interpretation of Computer Programs, -The MIT Press, Cambridge, Massachusetts, USA +@table @asis +@item FILE: PROBLEM +HOW TO FIX +@item *.c: include file not found +Correct the status of STDC_HEADERS in @file{scmfig.h} -@code{(eq? '() '#f)} is the major difference. +fix #include statement or add #define for system type to +@file{scmfig.h}. +@item *.c: Function should return a value in @dots{} +@itemx *.c: Parameter '@dots{}' is never used in @dots{} +@itemx *.c: Condition is always false in @dots{} +@itemx *.c: Unreachable code in function @dots{} +Ignore. +@item scm.c: assignment between incompatible types +change SIGRETTYPE in @file{scm.c}. +@item time.c: CLK_TCK redefined +incompatablility between and . remove +STDC_HEADERS in @file{scmfig.h}. -@item rev2-procedures -These procedures were specified in the @cite{Revised^2 Report on Scheme} -but not in @cite{R4RS}. +edit to remove incompatability. +@item subr.c: Possibly incorrect assignment in function lgcd +Ignore. +@item sys.c: statement not reached +@itemx sys.c: constant in conditional expression +ignore +@item sys.c: `???' undeclared, outside of functions +#undef STDC_HEADERS in @file{scmfig.h}. +@item scl.c: syntax error +#define SYSTNAME to your system type in @file{scl.c} (softtype) +@end table -@item record -The Record package provides a facility for user to define their own -record data types. See SLIB for documentation. +@node Problems Linking, Problems Running, Problems Compiling, Installing SCM +@section Problems Linking -@item compiled-closure -Use if you want to use compiled closures. +@table @asis +@item PROBLEM +HOW TO FIX +@item _sin etc. missing. +uncomment LIBS in makefile +@end table -@item generalized-c-arguments -@code{make_gsubr} for arbitrary (< 11) arguments to C functions. +@node Problems Running, Testing, Problems Linking, Installing SCM +@section Problems Running -@item tick-interrupts -Use if you want the ticks and ticks-interrupt functions. +@table @asis +@item PROBLEM +HOW TO FIX +@item Opening message and then machine crashes. +Change memory model option to C compiler (or makefile). -@item i/o-extensions -Commonly available I/O extensions: @dfn{exec}, line I/O, file -positioning, file delete and rename, and directory functions. +Make sure @code{sizet} definition is correct in @file{scmfig.h}. -@item turtlegr -@dfn{Turtle} graphics calls for both Borland-C and X11 from -sjm@@ee.tut.fi. +Reduce size of HEAP_SEG_SIZE in @file{setjump.h}. +@item Input hangs +#define NOSETBUF +@item ERROR: heap: need larger initial +Need to increase the initial heap allocation using -a or +INIT_HEAP_SIZE. +@item ERROR: Could not allocate @dots{} +Check @code{sizet} definition. -@item curses -For the @dfn{curses} screen management package. +Use 32 bit compiler mode. -@item edit-line -interface to the editline or GNU readline library. +Don't try to run as subproccess +@item remove @dots{} in scmfig.h and recompile scm +@itemx add @dots{} in scmfig.h and recompile scm +Do it and recompile files. +@item ERROR: @file{Init.scm} not found +Assign correct IMPLINIT in makefile or @file{scmfig.h} or define +environment variable @code{SCM_INIT_PATH} to be the full pathname of +@file{Init.scm} (@pxref{Installing SCM}). +@item WARNING: require.scm not found +define environment variable @code{SCHEME_LIBRARY_PATH} to be the full +pathname of the scheme library [SLIB] or change @code{library-vicinity} in +@file{Init.scm} to point to library or remove. @xref{Installation, , , slib, +SLIB}. -@item regex -String regular expression matching. +Make sure the value of @code{(library-vicinity)} has a trailing file +separator (like @key{/} or @key{\}). +@end table -@item socket -BSD @dfn{socket} interface. +@node Testing, Reporting Problems, Problems Running, Installing SCM +@section Testing -@item posix -Posix functions available on all @dfn{Unix-like} systems. fork and -process functions, user and group IDs, file permissions, and @dfn{link}. +@noindent +Loading @file{r4rstest.scm} in the distribution will run an [R4RS] +conformance test on @code{scm}. -@item unix -Those unix features which have not made it into the Posix specs: nice, -acct, lstat, readlink, symlink, mknod and sync. +@example +> (load "r4rstest.scm") +@print{} +;loading "r4rstest.scm" +SECTION(2 1) +SECTION(3 4) + # + # + # + # +@dots{} +@end example -@item windows -Microsoft Windows executable. +@noindent +Loading @file{pi.scm} in the distribution will enable you to compute +digits of pi. -@item dynamic-linking -Be able to load compiled files while running. +@example +> (load "pi") +;loading "pi" +;done loading "pi.scm" +;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other +# +> (pi 100 5) +00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 +37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 +70679 +;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other +# +@end example -@item dump -Convert a running scheme program into an executable file. +@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. -@item heap-can-shrink -Use if you want segments of unused heap to not be freed up after garbage -collection. This may reduce time in GC for *very* large working sets. +@table @asis +@item PROBLEM +HOW TO FIX +@item Runs some and then machine crashes. +See above under machine crashes. +@item Runs some and then ERROR: @dots{} (after a GC has happened) +Remove optimization option to C compiler and recompile. -@item cheap-continuations -If you only need straight stack continuations, executables compile with -this feature will run faster and use less storage than not having it. -Machines with unusual stacks @emph{need} this. Also, if you incorporate -new C code into scm which uses VMS system services or library routines -(which need to unwind the stack in an ordrly manner) you may need to -use this feature. +@code{#define SHORT_ALIGN} in @file{scmfig.h}. +@item Some symbol names print incorrectly. +Change memory model option to C compiler (or makefile). -@item memoize-local-bindings -Saves the interpeter from having to look up local bindings for every -identifier reference +Check that @code{HEAP_SEG_SIZE} fits within @code{sizet}. +Increase size of @code{HEAP_SEG_SIZE} (or @code{INIT_HEAP_SIZE} if it is +smaller than @code{HEAP_SEG_SIZE}). +@item ERROR: Rogue pointer in Heap. +See above under machine crashes. +@item Newlines don't appear correctly in output files. +Check file mode (define OPEN_@dots{} in @file{Init.scm} +@item Spaces or control characters appear in symbol names +Check character defines in @file{scmfig.h}. +@item Negative numbers turn positive. +Check SRS in @file{scmfig.h}. +@item VMS: Couldn't unwind stack +@itemx VAX: botched longjmp +@code{#define CHEAP_CONTIUATIONS} in @file{scmfig.h}. +@item Sparc(SUN-4) heap is growing out of control +You are experiencing a GC problem peculiar to the Sparc. The problem is +that SCM doesn't know how to clear register windows. Every location +which is not reused still gets marked at GC time. This causes lots of +stuff which should be collected to not be. This will be a problem with +any @emph{conservative} GC until we find what instruction will clear the +register windows. This problem is exacerbated by using lots of +call-with-current-continuations. @end table -@end deffn -@node SLIB, Installing Dynamic Linking, Building SCM, Installing SCM -@section SLIB +@node Reporting Problems, , Testing, Installing SCM +@section Reporting Problems @noindent -[SLIB] is a portable Scheme library meant to provide compatibility and -utility functions for all standard Scheme implementations. Although -SLIB is not @emph{neccessary} to run SCM, I strongly suggest you obtain -and install it. Bug reports about running SCM without SLIB have very -low priority. SLIB is available from the same sites as SCM: +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{jaffer@@ai.mit.edu}. The bug report +should include: -@ifclear html -@itemize @bullet +@enumerate @item -ftp-swiss.ai.mit.edu:/pub/scm/slib2a6.tar.gz +The version of SCM (printed when SCM is invoked with no arguments). @item -prep.ai.mit.edu:/pub/gnu/jacal/slib2a6.tar.gz +The type of computer you are using. @item -ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a6.tar.gz +The name and version of your computer's operating system. @item -ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2a6.tar.gz -@end itemize -@end ifclear - -@ifset html - -ftp-swiss.ai.mit.edu:/pub/scm/slib2a6.tar.gz - - -prep.ai.mit.edu:/pub/gnu/jacal/slib2a6.tar.gz - - -ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a6.tar.gz - - -ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2a6.tar.gz - -@end ifset - -@noindent -Unpack SLIB (@samp{tar xzf slib2a6.tar.gz} or @samp{unzip -ao -slib2a6.zip}) in an appropriate directory for your system; both -@code{tar} and @code{unzip} will create the directory @file{slib}. - -@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.scm} is installed). @file{require.scm} should have the -contents: - -@example -(define (library-vicinity) "/usr/local/lib/slib/") -(load (in-vicinity (library-vicinity) "require")) -@end example - -@noindent -where the pathname string @file{/usr/local/lib/slib/} is to be replaced -by the pathname into which you installed SLIB. 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: +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 -@example -(define library-vicinity - (let ((lv (string-append (implementation-vicinity) "../slib/"))) - (lambda () lv))) -(load (in-vicinity (library-vicinity) "require")) -@end example +@node Operational Features, The Language, Installing SCM, Top +@chapter Operational Features -@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, the environment variable overrides @file{require.scm}. Again, -absolute pathnames are recommended. +@menu +* Invoking SCM:: +* SCM Options:: +* Invocation Examples:: +* SCM Variables:: +* SCM Session:: +* Editing Scheme Code:: +* Debugging Scheme Code:: +* Errors:: +* Memoized Expressions:: +* Internal State:: +* Shell Scripts:: +@end menu +@node Invoking SCM, SCM Options, Operational Features, Operational Features +@section Invoking SCM -@node Installing Dynamic Linking, Saving Images, SLIB, Installing SCM -@section Installing Dynamic Linking +@quotation +@exdent @b{ scm } [-a @i{kbytes}] [-ibvqmu] [-p @i{number}] +@w{[-c @i{expression}]} @w{[-e @i{expression}]} @w{[-f @i{filename}]} +@w{[-l @i{filename}]} @w{[-r @i{feature}]} @w{[-- | - | -s]} +@w{[@i{filename}]} @w{[@i{arguments} @dots{}]} +@end quotation @noindent -Dynamic linking has not been ported to all platforms. Operating systems -in the BSD family (a.out binary format) can usually be ported to -@dfn{DLD}. The @dfn{dl} library (@code{#define SUN_DL} for SCM) was a -proposed POSIX standard and may be available on other machines with -@dfn{COFF} binary format. For notes about porting to MS-Windows and -finishing the port to VMS @ref{Finishing Dynamic Linking}. +Upon startup @code{scm} loads the file specified by by the environment +variable @var{SCM_INIT_PATH}. @noindent -@dfn{DLD} is a library package of C functions that performs @dfn{dynamic -link editing} on Linux, VAX (Ultrix), Sun 3 (SunOS 3.4 and 4.0), -SPARCstation (SunOS 4.0), Sequent Symmetry (Dynix), and Atari ST. It is -available from: - -@ifclear html -@itemize @bullet -@item -prep.ai.mit.edu:pub/gnu/dld-3.3.tar.gz -@end itemize -@end ifclear - -@ifset html - -prep.ai.mit.edu:pub/gnu/dld-3.3.tar.gz - -@end ifset +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.scm}) in +platform-dependent directories relative to this directory. +@xref{File-System Habitat} for a blow-by-blow description. @noindent -These notes about using libdl on SunOS are from @file{gcc.info}: - -@quotation -On a Sun, linking using GNU CC fails to find a shared library and -reports that the library doesn't exist at all. +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. -This happens if you are using the GNU linker, because it does only -static linking and looks only for unshared libraries. If you have -a shared library with no unshared counterpart, the GNU linker -won't find anything. +@noindent +Unless the option @code{-no-init-file} or @code{--no-init-file} occurs +in the command line, @file{Init.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 it is loaded. -We hope to make a linker which supports Sun shared libraries, but -please don't ask when it will be finished--we don't know. +@noindent +@file{Init.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. -Sun forgot to include a static version of @file{libdl.a} with some -versions of SunOS (mainly 4.1). This results in undefined symbols when -linking static binaries (that is, if you use @samp{-static}). If you -see undefined symbols @samp{_dlclose}, @samp{_dlsym} or @samp{_dlopen} -when linking, compile and link against the file -@file{mit/util/misc/dlsym.c} from the MIT version of X windows. -@end quotation +@noindent +This explanation applies to SCMLIT or other builds of SCM. +@noindent +Scheme-code files can also invoke SCM and its variants. @xref{Syntax +Extensions, #!}. -@node Saving Images, Automatic C Preprocessor Definitions, Installing Dynamic Linking, Installing SCM -@section Saving Images +@node SCM Options, Invocation Examples, Invoking SCM, Operational Features +@section Options @noindent -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. +The options are processed in the order specified on the command line. -@noindent -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. +@deffn {Command Option} -a kb +specifies that @code{scm} should allocate an initial heapsize of +@var{kb} 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} -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} -r feature +requires @var{feature}. This will load a file from [SLIB] if that +@var{feature} is not already supported. If @var{feature} is 2, 3, 4, or +5 @code{scm} will require the features neccessary to support [R2RS], +[R3RS], [R4RS], or proposed [R5RS], respectively. +@end deffn -@node Automatic C Preprocessor Definitions, Problems Compiling, Saving Images, Installing SCM -@section Automatic C Preprocessor Definitions +@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 -These @samp{#defines} are automatically provided by preprocessors of -various C compilers. SCM uses the presence or absence of these -definitions to configure @dfn{include file} locations and aliases for -library functions. If the definition(s) corresponding to your system -type is missing as your system is configured, add @code{-D@var{flag}} to -the compilation command lines or add a @code{#define @var{flag}} line to -@file{scmfig.h} or the beginning of @file{scmfig.h}. +@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 -@example -#define Platforms: -------- ---------- -ARM_ULIB Huw Rogers free unix library for acorn archimedes -AZTEC_C Aztec_C 5.2a -_DCC Dice C on AMIGA -__GNUC__ Gnu CC (and DJGPP) -__EMX__ Gnu C port (gcc/emx 0.8e) to OS/2 2.0 -__HIGHC__ MetaWare High C -__IBMC__ C-Set++ on OS/2 2.1 -_MSC_VER MS VisualC++ 4.2 -MWC Mark Williams C on COHERENT -_QC Microsoft QuickC -__STDC__ ANSI C compliant -__TURBOC__ Turbo C and Borland C -__WATCOMC__ Watcom C on MS-DOS -__ZTC__ Zortech C +@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 -_AIX AIX operating system -AMIGA SAS/C 5.10 or Dice C on AMIGA -atarist ATARI-ST under Gnu CC -GNUDOS DJGPP (obsolete in version 1.08) -__GO32__ DJGPP (future?) -hpux HP-UX -linux Linux -MCH_AMIGA Aztec_c 5.2a on AMIGA -MSDOS Microsoft C 5.10 and 6.00A -__MSDOS__ Turbo C, Borland C, and DJGPP -nosve Control Data NOS/VE -SVR2 System V Revision 2. -THINK_C developement environment for the Macintosh -ultrix VAX with ULTRIX operating system. -unix most Unix and similar systems and DJGPP (!?) -__unix__ Gnu CC and DJGPP -_UNICOS Cray operating system -_Windows Borland C 3.1 compiling for Windows -_WIN32 MS VisualC++ 4.2 under Windows-NT -vms (and VMS) VAX-11 C under VMS. +@deffn {Command Option} -q +(quiet mode) specifies that @code{scm} will print no extra +information. This is the same as @code{-p0}. +@end deffn -hp9000s800 HP RISC processor -__i386__ DJGPP -i386 DJGPP -MULTIMAX Encore computer -pyr Pyramid 9810 processor -sparc SPARC processor -sequent Sequent computer -tahoe CCI Tahoe processor -@end example +@deffn {Command Option} -m +specifies that subsequent loads, evaluations, and user interactions will +be with [R4RS] macro capability. To use a specific [R4RS] macro +implementation from [SLIB] (instead of [SLIB]'s default) put @code{-r} +@var{macropackage} before @code{-m} on the command line. +@end deffn -@node Problems Compiling, Problems Linking, Automatic C Preprocessor Definitions, Installing SCM -@section Problems Compiling +@deffn {Command Option} -u +specifies that subsequent loads, evaluations, and user interactions will +be without [R4RS] macro capability. [R4RS] macro capability can +be restored by a subsequent @code{-m} on the command line or from Scheme +code. +@end deffn -@table @asis -@item FILE: PROBLEM -HOW TO FIX -@item *.c: include file not found -Correct the status of STDC_HEADERS in @file{scmfig.h} +@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 -fix #include statement or add #define for system type to -@file{scmfig.h}. -@item *.c: Function should return a value in @dots{} -@itemx *.c: Parameter '@dots{}' is never used in @dots{} -@itemx *.c: Condition is always false in @dots{} -@itemx *.c: Unreachable code in function @dots{} -Ignore. -@item scm.c: assignment between incompatible types -change SIGRETTYPE in @file{scm.c}. -@item time.c: CLK_TCK redefined -incompatablility between and . remove -STDC_HEADERS in @file{scmfig.h}. +@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 -edit to remove incompatability. -@item subr.c: Possibly incorrect assignment in function lgcd -Ignore. -@item sys.c: statement not reached -@itemx sys.c: constant in conditional expression -ignore -@item sys.c: `???' undeclared, outside of functions -#undef STDC_HEADERS in @file{scmfig.h}. -@item scl.c: syntax error -#define SYSTNAME to your system type in @file{scl.c} (softtype) -@end table +@deffn {Command Option} -s +specifies, by analogy with @code{sh}, that further options are to be +treated as program aguments. +@end deffn -@node Problems Linking, Problems Running, Problems Compiling, Installing SCM -@section Problems Linking +@deffn {Command Option} - +@deffnx {Command Option} -- +specifies that there are no more options on the command line. +@end deffn -@table @asis -@item PROBLEM -HOW TO FIX -@item _sin etc. missing. -uncomment LIBS in makefile -@end table +@deffn {Command Option} -d filename +loads SLIB database-utilities and opens @var{filename} as a database. +@end deffn -@node Problems Running, Testing, Problems Linking, Installing SCM -@section Problems Running +@deffn {Command Option} -o filename +saves the current SCM session as the executable program @file{filename}. +This option works only in SCM builds supporting @code{dump} +(@pxref{Dump}). -@table @asis -@item PROBLEM -HOW TO FIX -@item Opening message and then machine crashes. -Change memory model option to C compiler (or makefile). +If options appear on the command line after @samp{-o @var{filename}}, +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 -Make sure @code{sizet} definition is correct in @file{scmfig.h}. +@deffn {Command Option} --help +prints usage information and URL; then exit. +@end deffn -Reduce size of HEAP_SEG_SIZE in @file{setjump.h}. -@item Input hangs -#define NOSETBUF -@item ERROR: heap: need larger initial -Need to increase the initial heap allocation using -a or -INIT_HEAP_SIZE. -@item ERROR: Could not allocate @dots{} -Check @code{sizet} definition. +@deffn {Command Option} --version +prints version information and exit. +@end deffn -Use 32 bit compiler mode. +@node Invocation Examples, SCM Variables, SCM Options, Operational Features +@section Invocation Examples -Don't try to run as subproccess -@item remove @dots{} in scmfig.h and recompile scm -@itemx add @dots{} in scmfig.h and recompile scm -Do it and recompile files. -@item ERROR: @file{Init.scm} not found -Assign correct IMPLINIT in makefile or @file{scmfig.h} or define -environment variable @code{SCM_INIT_PATH} to be the full pathname of -@file{Init.scm} (@pxref{Installing SCM}). -@item WARNING: require.scm not found -define environment variable @code{SCHEME_LIBRARY_PATH} to be the full -pathname of the scheme library [SLIB] or change @code{library-vicinity} in -@file{Init.scm} to point to library or remove. @xref{Installation, , , slib, -SLIB}. +@table @code +@item % scm foo.scm +Loads and executes the contents of @file{foo.scm} and then enters +interactive session. -Make sure the value of @code{(library-vicinity)} has a trailing file -separator (like @key{/} or @key{\}). -@end table +@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. -@node Testing, Reporting Problems, Problems Running, Installing SCM -@section Testing +@item % scm -s foo.scm arg1 arg2 +Sets *argv* to @code{("foo.scm" "arg1" "arg2")} and enters interactive +session. -@noindent -Loading @file{r4rstest.scm} in the distribution will run an [R4RS] -conformance test on @code{scm}. +@item % scm -e `(write (list-ref *argv* *optind*))' bar +Prints @samp{"bar"}. -@example -> (load "r4rstest.scm") -@print{} -;loading "r4rstest.scm" -SECTION(2 1) -SECTION(3 4) - # - # - # - # -@dots{} -@end example +@item % scm -rpretty-print -r format -i +Loads @code{pretty-print} and @code{format} and enters interactive +session. -@noindent -Loading @file{pi.scm} in the distribution will enable you to compute -digits of pi. +@item % scm -r5 +Loads @code{dynamic-wind}, @code{values}, and [R4RS] macros and enters +interactive (with macros) session. -@example -> (load "pi") -;loading "pi" -;done loading "pi.scm" -;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other -# -> (pi 100 5) -00003 14159 26535 89793 23846 26433 83279 50288 41971 69399 -37510 58209 74944 59230 78164 06286 20899 86280 34825 34211 -70679 -;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other -# -@end example +@item % scm -r5 -r4 +Like above but @code{rev4-optional-procedures} are also loaded. +@end table -@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 SCM Variables, SCM Session, Invocation Examples, Operational Features +@section Environment Variables -@table @asis -@item PROBLEM -HOW TO FIX -@item Runs some and then machine crashes. -See above under machine crashes. -@item Runs some and then ERROR: @dots{} (after a GC has happened) -Remove optimization option to C compiler and recompile. +@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.scm} in the source directory. +@end defvr -@code{#define SHORT_ALIGN} in @file{scmfig.h}. -@item Some symbol names print incorrectly. -Change memory model option to C compiler (or makefile). +@defvr {Environment Variable} SCHEME_LIBRARY_PATH +is the [SLIB] Scheme library directory. +@end defvr -Check that @code{HEAP_SEG_SIZE} fits within @code{sizet}. +@defvr {Environment Variable} HOME +is the directory where @file{Init.scm} will look for the user +initialization file @file{ScmInit.scm}. +@end defvr -Increase size of @code{HEAP_SEG_SIZE} (or @code{INIT_HEAP_SIZE} if it is -smaller than @code{HEAP_SEG_SIZE}). -@item ERROR: Rogue pointer in Heap. -See above under machine crashes. -@item Newlines don't appear correctly in output files. -Check file mode (define OPEN_@dots{} in @file{Init.scm} -@item Spaces or control characters appear in symbol names -Check character defines in @file{scmfig.h}. -@item Negative numbers turn positive. -Check SRS in @file{scmfig.h}. -@item VMS: Couldn't unwind stack -@itemx VAX: botched longjmp -@code{#define CHEAP_CONTIUATIONS} in @file{scmfig.h}. -@item Sparc(SUN-4) heap is growing out of control -You are experiencing a GC problem peculiar to the Sparc. The problem is -that SCM doesn't know how to clear register windows. Every location -which is not reused still gets marked at GC time. This causes lots of -stuff which should be collected to not be. This will be a problem with -any @emph{conservative} GC until we find what instruction will clear the -register windows. This problem is exacerbated by using lots of -call-with-current-continuations. -@end table +@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 -@node Reporting Problems, , Testing, Installing SCM -@section Reporting Problems +@section Scheme Variables -@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{jaffer@@ai.mit.edu}. The bug report -should include: +@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 -@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. +@defvar *R4RS-macro* +controls whether loading and interaction support [R4RS] 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 -The values of the environment variables @code{SCM_INIT_PATH} and -@code{SCHEME_LIBRARY_PATH}. +Options, file loading and features can be specified from the command +line. @xref{System interface, , , scm, SCM}. @xref{Require, , , slib, +SLIB}. @item -The name and version of your C compiler. +Typing the end-of-file character at the top level session (while SCM is +not waiting for parenthesis closure) causes SCM to exit. @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 +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 + +@defun program-arguments +Returns a list of strings of the arguments scm was called with. +@end defun + +@noindent +For documentation of the procedures @code{getenv} and @code{system} +@xref{System Interface, , , slib, SLIB}. + +@defun vms-debug +If SCM is compiled under VMS this @code{vms-debug} will invoke the VMS +debugger. +@end defun + -@node The Language, Packages, Installing SCM, Top -@chapter The Language +@node Editing Scheme Code, Debugging Scheme Code, SCM Session, Operational Features +@section Editing Scheme Code -This section describes features which are either present in all builds -of SCM or which must be enabled when SCM is compiled. +@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{}. -@menu -* Standards Compliance:: Links to sections in [R4RS] and [SLIB] -* System Interface:: Like how to exit -* Errors:: -* Memoized Expressions:: What #@@0+1 and #@@? mean -* Internal State:: GC, errors, and diagnostics -* Miscellaneous Procedures:: -* Time:: Both real time and processor time -* Interrupts:: and exceptions -* Process Synchronization:: Because interrupts are preemptive -* Files and Ports:: -* Soft Ports:: Emulate I/O devices -* Syntax Extensions:: and how to Define New Syntax -* Low Level Syntactic Hooks:: -@end menu +@defunx ed filename +If SCM is compiled under VMS @code{ed} will invoke the editor with a +single the single argument @var{filename}. +@end defun -@node Standards Compliance, System Interface, The Language, The Language -@section Standards Compliance -@noindent -Scm conforms to the -@ifset html -[IEEE], -@end ifset -@cite{IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming -Language.} +@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. EMACS for MS-DOS +and MS-Windows systems is available (free) from: + @ifclear html -(@pxref{Bibliography}), +@itemize @bullet +@item +http://simtel.coast.net/SimTel/gnu/demacs.html +@end itemize @end ifclear -and -@ifset html -[R4RS], -@end ifset -@cite{Revised(4) Report on the Algorithmic Language Scheme}. + @ifset html + +http://simtel.coast.net/SimTel/gnu/demacs.html @end ifset -@ifinfo -@ref{Top, , , r4rs, Revised(4) Report on the Algorithmic Language -Scheme}. -@end ifinfo -All the required features of these specifications are supported. -Many of the optional features are supported as well. -@subheading Optionals of [R4RS] Supported by SCM +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. -@table @asis -@item two clause @code{if}: @code{(if )} -@xref{Conditionals, , , r4rs, Revised(4) Scheme}. -@item @code{let*} -@itemx named @code{let} -@xref{Binding constructs, , , r4rs, Revised(4) Scheme}. -@item @code{do} -@xref{Iteration, , , r4rs, Revised(4) Scheme}. -@item All varieties of @code{define} -@xref{Definitions, , , r4rs, Revised(4) Scheme}. -@item @code{list-tail} -@xref{Pairs and lists, , , r4rs, Revised(4) Scheme}. -@item @code{string-copy} -@itemx @code{string-fill!} -@xref{Strings, , , r4rs, Revised(4) Scheme}. -@item @code{make-vector} of two arguments -@itemx @code{vector-fill!} -@xref{Vectors, , , r4rs, Revised(4) Scheme}. -@item @code{apply} of more than 2 arguments -@xref{Control features, , , r4rs, Revised(4) Scheme}. -@item @code{-} and @code{/} of more than 2 arguments -@itemx @code{exp} -@itemx @code{log} -@itemx @code{sin} -@itemx @code{cos} -@itemx @code{tan} -@itemx @code{asin} -@itemx @code{acos} -@itemx @code{atan} -@itemx @code{sqrt} -@itemx @code{expt} -@itemx @code{make-rectangular} -@itemx @code{make-polar} -@itemx @code{real-part} -@itemx @code{imag-part} -@itemx @code{magnitude} -@itemx @code{angle} -@itemx @code{exact->inexact} -@itemx @code{inexact->exact} -@xref{Numerical operations, , , r4rs, Revised(4) Scheme}. -@item @code{delay} -@itemx @code{force} -@xref{Control features, , , r4rs, Revised(4) Scheme}. -@itemx @code{with-input-from-file} -@itemx @code{with-output-to-file} -@xref{Ports, , , r4rs, Revised(4) Scheme}. -@itemx @code{char-ready?} -@xref{Input, , , r4rs, Revised(4) Scheme}. -@itemx @code{transcript-on} -@itemx @code{transcript-off} -@xref{System interface, , , r4rs, Revised(4) Scheme}. -@end table +@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. -@subheading Optionals of [R4RS] not Supported by SCM +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. -@table @asis -@item @code{numerator} -@itemx @code{denominator} -@itemx @code{rationalize} -@xref{Numerical operations, , , r4rs, Revised(4) Scheme}. -@item [R4RS] appendix Macros -@xref{Macros, , , r4rs, Revised(4) Scheme}. -@end table +One can also call out to an editor from SCM if RAM is at a premium; See +``under other systems'' below. -@subheading [SLIB] Features of SCM and SCMLIT +@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: -@table @code -@item delay -@itemx full-continuation -@itemx ieee-p1178 -@itemx object-hash -@itemx rev4-report -@itemx source -See SLIB file @file{Template.scm}. -@item current-time -@xref{Time, , , slib, SLIB}. -@item defmacro -@xref{Defmacro, , , slib, SLIB}. -@item dynamic-wind -@xref{Dynamic-Wind, , , slib, SLIB}. -@item eval -@xref{System, , , slib, SLIB}. -@item getenv -@itemx system -@xref{System Interface, , , slib, SLIB}. -@item hash -@xref{Hashing, , , slib, SLIB}. -@item logical -@xref{Bit-Twiddling, , , slib, SLIB}. -@item multiarg-apply -@xref{Multi-argument Apply, , , slib, SLIB}. -@item multiarg/and- -@xref{Multi-argument / and -, , , slib, SLIB}. -@item rev4-optional-procedures -@xref{Rev4 Optional Procedures, , , slib, SLIB}. -@item string-port -@xref{String Ports, , , slib, SLIB}. -@item tmpnam -@xref{Input/Output, , , slib, SLIB}. -@item transcript -@xref{Transcripts, , , slib, SLIB}. -@item vicinity -@xref{Vicinity, , , slib, SLIB}. -@item with-file -@xref{With-File, , , slib, SLIB}. +@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 -@subheading [SLIB] Features of SCM +@node Debugging Scheme Code, Errors, Editing Scheme Code, Operational Features +@section Debugging Scheme Code -@table @code -@item array -@xref{Arrays, , , slib, SLIB}. -@item array-for-each -@xref{Array Mapping, , , slib, SLIB}. -@item bignum -@itemx complex -@itemx inexact -@itemx rational -@itemx real -@xref{Require, , , slib, SLIB}. -@end table +@noindent +The @code{cautious} and @code{stack-limit} options of @code{build} +(@pxref{Build Options}) support 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. @xref{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)}. + +@item STACK_LIMIT +If SCM is built with the @samp{STACK_LIMIT} flag, the interpreter will +check stack size periodically. If the size of stack exceeds a certain +amount (default is @code{HEAP_SEG_SIZE/2}), SCM generates a +@code{segment violation} interrupt. -@node System Interface, Errors, Standards Compliance, The Language -@section System Interface +The usefulness of @samp{STACK_LIMIT} depends on the user. I don't use +it; but the user I added this feature for got primarily this type of +error. +@end table @noindent -For documentation of the procedures @code{getenv} and @code{system} -@xref{System Interface, , , slib, SLIB}. +There are several SLIB macros which so useful that SCM automatically +loads the appropriate module from SLIB if they are invoked. -@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 +@defmac trace proc1 @dots{} +Traces the top-level named procedures given as arguments. +@defmacx 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 -@defun vms-debug -If SCM is compiled under VMS these commands will invoke the editor or -debugger respectively. -@end defun +@defmac untrace proc1 @dots{} +Turns tracing off for its arguments. +@defmacx untrace +With no arguments, untraces all currently traced identifiers and returns +a list of these formerly traced identifiers. +@end defmac -@defun ed filename -If SCM is compiled under VMS @code{ed} will invoke the editor with a -single the single argument @var{filename}. +The routines I use most frequently for debugging are: -@defunx ed arg1 @dots{} -Otherwise, 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 +@deffn Procedure 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 '} and @samp{)} around an +expression in order to see its value as a program operates. +@end deffn + +@deffn Syntax print-args name1 @dots{} +Writes @var{name1} @dots{} (separated by spaces) and then writes the +values of the closest lexical bindings enclosing the call to +@code{Print-args}. + +@example +(define (foo a b) (print-args foo) (+ a b)) +(foo 3 6) +@print{} In foo: a = 3; b = 6; +@result{} 9 +@end example +@end deffn -@defun program-arguments -Returns a list of strings of the arguments scm was called with. -@end defun +@noindent +Sometimes more elaborate measures are needed to print values in a useful +manner. When the values to be printed may have very large (or infinite) +external representations, @ref{Quick Print, , , slib, SLIB}, can be +used. -@defun errno -@defunx errno n -With no argument returns the current value of the system variable -@code{errno}. When given an argument, @code{errno} sets the system -variable @code{errno} to @var{n} and returns the previous value of -@code{errno}. @code{(errno 0)} will clear outstanding errors. This is -recommended after @code{try-load} returns @code{#f} since this occurs -when the file could not be opened. -@end defun +When @code{trace} is not sufficient to find program flow problems, +@ifset html + +@end ifset +SLIB-PSD, the Portable Scheme Debugger +@ifset html + +@end ifset +offers source code debugging from +GNU Emacs. PSD runs slowly, so start by instrumenting only a few +functions at a time. +@lisp +ftp-swiss.ai.mit.edu:pub/scm/slib-psd1-3.tar.gz +prep.ai.mit.edu:pub/gnu/jacal/slib-psd1-3.tar.gz +ftp.maths.tcd.ie:pub/bosullvn/jacal/slib-psd1-3.tar.gz +ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz +@end lisp -@defun perror string -Prints on standard error output the argument @var{string}, a colon, -followed by a space, the error message corresponding to the current -value of @code{errno} and a newline. The value returned is unspecified. -@end defun -@node Errors, Memoized Expressions, System Interface, The Language +@node Errors, Memoized Expressions, Debugging Scheme Code, Operational Features @section Errors @noindent @@ -1983,21 +1865,49 @@ alarm @code{(alarm-interrupt)} @end enumerate @defvar errobj -If SCM encounters a non-fatal error it aborts evaluation of the current -form, prints a message explaining the error, and resumes the top level -read-eval-print loop. The value of @var{errobj} is the offending object -if appropriate. The builtin procedure @code{error} does @emph{not} set -@var{errobj}. +When SCM encounters a non-fatal error, it aborts evaluation of the +current form, prints a message explaining the error, and resumes the top +level read-eval-print loop. The value of @var{errobj} is the offending +object if appropriate. The builtin procedure @code{error} does +@emph{not} set @var{errobj}. @end defvar -@defun error arg1 arg2 arg3 @dots{} -Alias for @ref{System, error, , slib, SLIB}. Outputs an error message -containing the arguments, aborts evaluation of the current form and -resumes the top level read-eval-print loop. Error is defined in -@file{Init.scm}; Feel free to redefine it to suit your purposes. +@noindent +@code{errno} and @code{perror} report ANSI C errors encountered during a +call to a system or library function. + +@defun errno +@defunx errno n +With no argument returns the current value of the system variable +@code{errno}. When given an argument, @code{errno} sets the system +variable @code{errno} to @var{n} and returns the previous value of +@code{errno}. @code{(errno 0)} will clear outstanding errors. This is +recommended after @code{try-load} returns @code{#f} since this occurs +when the file could not be opened. +@end defun + +@defun perror string +Prints on standard error output the argument @var{string}, a colon, +followed by a space, the error message corresponding to the current +value of @code{errno} and a newline. The value returned is unspecified. +@end defun + +@noindent +@code{warn} and @code{error} provide a uniform way for Scheme code to +signal warnings and errors. + +@defun warn arg1 arg2 arg3 @dots{} +Alias for @ref{System, slib:warn, , slib, SLIB}. Outputs an error +message containing the arguments. @code{warn} is defined in +@file{Init.scm}. @end defun -@subsection CAUTIOUS enhancements +@defun error arg1 arg2 arg3 @dots{} +Alias for @ref{System, slib:error, , slib, SLIB}. Outputs an error +message containing the arguments, aborts evaluation of the current form +and resumes the top level read-eval-print loop. @code{Error} is defined +in @file{Init.scm}. +@end defun @noindent If SCM is built with the @samp{CAUTIOUS} flag, then when an error @@ -2021,7 +1931,7 @@ printed and @code{#f} otherwise. See @file{Init.scm} for an example of the use of @code{stack-trace}. @end defun -@node Memoized Expressions, Internal State, Errors, The Language +@node Memoized Expressions, Internal State, Errors, Operational Features @section Memoized Expressions @noindent @@ -2047,129 +1957,558 @@ top-level have @r{#@@} prepended. @end itemize @noindent -For instance, @code{open-input-file} is defined as follows in -@file{Init.scm}: +For instance, @code{open-input-file} is defined as follows in +@file{Init.scm}: + +@example +(define (open-input-file str) + (or (open-file str OPEN_READ) + (and (procedure? could-not-open) (could-not-open) #f) + (error "OPEN-INPUT-FILE couldn't open file " str))) +@end example + +@noindent +If @code{open-input-file} has not yet been used, the displayed procedure +is similar to the original definition (lines wrapped for readability): + +@example +open-input-file @result{} +# +@end example + +@noindent +If we open a file using @code{open-input-file}, the sections of code +used become memoized: + +@example +(open-input-file "r4rstest.scm") @result{} # +open-input-file @result{} +# +@end example + +@noindent +If we cause @code{open-input-file} to execute other sections of code, +they too become memoized: + +@example +(open-input-file "foo.scm") @result{} + +ERROR: No such file or directory +ERROR: OPEN-INPUT-FILE couldn't open file "foo.scm" + +open-input-file @result{} +# +@end example + + +@node Internal State, Shell Scripts, Memoized Expressions, Operational Features +@section Internal State + +@defvar *interactive* +The variable @var{*interactive*} determines whether the SCM session is +interactive, or should quit after the command line is processed. +@var{*interactive*} is controlled directly by the command-line options +@samp{-b}, @samp{-i}, and @samp{-s} (@pxref{Invoking SCM}). If none of +these options are specified, the rules to determine interactivity are +more complicated; see @file{Init.scm} for details. +@end defvar + +@defun abort +Resumes the top level Read-Eval-Print loop. +@end defun + +@defun restart +Restarts the SCM program with the same arguments as it was originally +invoked. All @samp{-l} loaded files are loaded again; If those files +have changed, those changes will be reflected in the new session. + +@emph{Note:} When running a saved executable (@pxref{Dump}), +@code{restart} is redefined to be @code{exec-self}. +@end defun + +@defun exec-self +Exits and immediately re-invokes the same executable with the same +arguments. If the executable file has been changed or replaced since +the beginning of the current session, the @emph{new} executable will be +invoked. This differentiates @code{exec-self} from @code{restart}. +@end defun + +@defun verbose n +Controls how much monitoring information is printed. +If @var{n} is: + +@table @asis +@item 0 +no prompt or information is printed. +@item >= 1 +a prompt is printed. +@item >= 2 +the CPU time is printed after each top level form evaluated. +@item >= 3 +messages about heap growth are printed. +@item >= 4 +garbage collection (@pxref{Garbage Collection}) messages are printed. +@item >= 5 +a warning will be printed for each top-level symbol which is defined +more than one time. +@end table +@end defun + +@defun gc +Scans all of SCM objects and reclaims for further use those that are +no longer accessible. +@end defun + +@defun room +@defunx room #t +Prints out statistics about SCM's current use of storage. @code{(room #t)} +also gives the hexadecimal heap segment and stack bounds. +@end defun + +@defvr Constant *scm-version* +Contains the version string (e.g. @file{5b3}) of SCM. +@end defvr + +@subsection Executable path + +@noindent +In order to dump a saved executable or to dynamically-link using DLD, +SCM must know where its executable file is. Sometimes SCM +(@pxref{Executable Pathname}) guesses incorrectly the location of the +currently running executable. In that case, the correct path can be set +by calling @code{execpath} with the pathname. + +@defun execpath +Returns the path (string) which SCM uses to find the executable file +whose invocation the currently running session is, or #f if the path is +not set. +@defunx execpath #f +@defunx execpath newpath +Sets the path to @code{#f} or @var{newpath}, respectively. The old path +is returned. +@end defun + +@noindent +For other configuration constants and procedures @xref{Configuration, , +, slib, SLIB}. + + +@node Shell Scripts, , Internal State, Operational Features +@section Shell Scripts + +@menu +* Unix Shell Scripts:: Same old same old +* SCSH scripts:: From Olin Shivers' Scheme Shell +* MS-DOS Compatible Scripts:: Run under both MS-DOS and Unix +@end menu + +@node Unix Shell Scripts, SCSH scripts, Shell Scripts, Shell Scripts +@subsection Unix Shell Scripts + +@noindent +In reading this section, keep in mind that the first line of a script +file has (different) meanings to SCM and the operating system +(@code{execve}). + +@deftp file #! interpreter +@deftpx file #! interpreter arg + +@tindex Shell Script +@tindex Shell-Script +On unix systems, a @dfn{Shell-Script} is a file (with execute +permissions) whose first two characters are @samp{#!}. The +@var{interpreter} argument must be the pathname of the program to +process the rest of the file. The directories named by environment +variable @code{PATH} are @emph{not} searched to find @var{interpreter}. +The @var{arg} is an optional argument encapsulating the rest of the +first line's contents, if not just whitespace. + +When executing a shell-script, the operating system invokes +@var{interpreter} with (if present) @var{arg}, the pathname of the shell +script file, and then any arguments which the shell-script was invoked +with. +@end deftp + +@deffn {Read syntax} #! ignored +When the first two characters of the file being loaded are @code{#!}, +the first line of that file will be ignored. +@end deffn + +@noindent +This combination of interpretatons allows SCM source files to be used as +POSIX shell-scripts if the first line is: + +@example +#!/usr/local/bin/scm +@end example +or +@example +#!/usr/local/bin/scm -l +@end example + +@noindent +When such a file is invoked, /usr/local/bin/scm is executed with the +name of this file as the first argument. +@example +#!/usr/local/bin/scm +(print (program-arguments)) +(quit) +@result{} ("scm" "./script") +@end example + +@example +#!/usr/local/bin/scm -l +(print (program-arguments)) +@result{} ("scm" "-l" "./script") +@end example + +@noindent +The following shell-script will print factorial of its argument: +@example +#!/usr/local/bin/scm -l +(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) +(print (fact (string->number (cadddr (program-arguments))))) +@end example + +@example +./fact 6 +@result{} 720 +@end example + +@noindent +Shell-scripts suffer from several drawbacks: +@itemize @bullet +@item +Some Unixes limit the length of the @samp{#!} interpreter line to the +size of an object file header, which can be as small as 32 bytes. +@item +A full, explicit pathname must be specified, perhaps requiring more than +32 bytes and making scripts vulnerable to breakage when programs are +moved. +@item +At most one argument is parsed from the first line of the shell-script. +Its position is fixed between the interpreter and any command line +arguments. +@end itemize + +@noindent +The following approach solves these problems at the expense of slower +startup. Make @samp{#!/bin/sh} the first line and prepend every +subsequent line to be executed by the shell with @code{:;} (@code{type;} +in older versions). The last line to be executed by the shell should +contain an @dfn{exec} command; @code{exec} tail-calls its argument. + +@noindent +@code{/bin/sh} is thus invoked with the name of the script file, which +it executes as a *sh script. Usually the second line starts +@samp{:;exec scm -f$0}, which executes scm, which in turn loads the +script file. When SCM loads the script file, it ignores the first and +second lines, and evaluates the rest of the file as Scheme source code. + +@noindent +The second line of the script file does not have the length restriction +mentioned above. Also, @code{/bin/sh} searches the directories listed +in the `PATH' environment variable for @samp{scm}, eliminating the need +to use absolute locations in order to invoke a program. @example -(define (open-input-file str) - (or (open-file str OPEN_READ) - (and (procedure? could-not-open) (could-not-open) #f) - (error "OPEN-INPUT-FILE couldn't open file " str))) +#!/bin/sh +:;exec scm -l$0 $* +(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) +(print (fact (string->number (caddr (program-arguments))))) +@end example + +@example +./fact 6 +@result{} 720 @end example +@node SCSH scripts, MS-DOS Compatible Scripts, Unix Shell Scripts, Shell Scripts +@subsection SCSH scripts + @noindent -If @code{open-input-file} has not yet been used, the displayed procedure -is similar to the original definition (lines wrapped for readability): +Olin Shivers' @dfn{Scheme Shell} project solves the one-argument +limitation by introducing @samp{\} as a @dfn{meta-argument}. This +extensions is also supported by SCM. + +@deftp file #! interpreter \ + +@tindex Shell Script +@tindex shell-script +@tindex meta-argument +This is an enhancement to the shell-script format. When the optional +@var{arg} is @samp{\}, the @var{interpreter} substitutes the second +line of @var{file} for @samp{\}, then appends any arguments given on +the command line invoking this shell-script. +@end deftp + +@deffn {Read syntax} #! ignored !# +When the first two characters of the file being loaded are @code{#!} and +a @samp{\} is present before a newline in the file, all characters up +to @samp{!#} will be ignored by SCM @code{read}. +@end deffn + +@noindent +This combination of interpretatons allows SCM source files to be used as +POSIX shell-scripts if the first line is: @example -open-input-file @result{} -# +#!/usr/local/bin/scm \ @end example @noindent -If we open a file using @code{open-input-file}, the sections of code -used become memoized: +The following shell-script will print its expanded argument list, then +factorial of its argument: @example -(open-input-file "r4rstest.scm") @result{} # -open-input-file @result{} -# +#!/usr/local/bin/scm \ + -p0 -l !# +(print (program-arguments)) +(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) +(print (fact (string->number (list-ref (program-arguments) *optind*)))) +@end example + +@example +./fact 5 +@result{} ("scm" "-p0" "-l" "./fact" "5") +120 @end example + +@node MS-DOS Compatible Scripts, , SCSH scripts, Shell Scripts +@subsection MS-DOS Compatible Scripts + @noindent -If we cause @code{open-input-file} to execute other sections of code, -they too become memoized: +It turns out that we can create shell-scripts which run both under unix +and MS-DOS. To implement this, I have written the MS-DOS programs: +@code{#!.bat} and @code{!#.exe}. +@pindex !# +@pindex !#.exe +@pindex #! +@pindex #!.bat -@example -(open-input-file "foo.scm") @result{} +@noindent +With these two programs installed in a @code{PATH} directory, we have +the following syntax for @var{.BAT} files. + +@deftp file #! interpreter \ %0 %1 %2 %3 %4 %5 %6 %7 %8 + +@tindex Shell Script +@tindex shell-script +The first two characters of the shell-script are @samp{#!}. The +@var{interpreter} can be either a unix style program path (using +@samp{/} between filename components) or a DOS program name or path. +The rest of the first line of the shell-script should be literally +@samp{\ %0 %1 %2 %3 %4 %5 %6 %7 %8}, as shown. + +If @var{interpreter} has @samp{/} in it, @var{interpreter} is converted +to a DOS style filename (@samp{/} @result{} @samp{\}). + +In looking for an executable named @var{interpreter}, @code{#!} first +checks this (converted) filename; if @var{interpreter} doesn't exist, it +then tries to find a program named like the string starting after the +last @samp{\} (or @samp{/}) in @var{interpreter}. When searching for +executables, @code{#!} tries all directories named by environment +variable @code{PATH}. + +Once the @var{interpreter} executable path is found, arguments are +processed in the manner of scheme-shell, with the all the text after the +@samp{\} taken as part of the meta-argument. More precisely, @code{#!} +calls @var{interpreter} with any options on the second line of the +shell-script up to @samp{!#}, the name of the shell-script file, and +then any of at most 8 arguments given on the command line invoking this +shell-script. +@end deftp -ERROR: No such file or directory -ERROR: OPEN-INPUT-FILE couldn't open file "foo.scm" +@noindent +The following shell-script will print its expanded argument list, then +factorial of its argument. This shell-script in both MS-DOS and unix +systems. -open-input-file @result{} -# +@example +#! /usr/local/bin/scm \ %0 %1 %2 %3 %4 %5 %6 %7 %8 + -p1 -l !# +(print (program-arguments)) +(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) +(print (fact (string->number (list-ref (program-arguments) *optind*)))) @end example -@node Internal State, Miscellaneous Procedures, Memoized Expressions, The Language -@section Internal State +@node The Language, Packages, Operational Features, Top +@chapter The Language -@defvar *interactive* -The variable @var{*interactive*} determines whether the SCM session is -interactive, or should quit after the command line is processed. -@var{*interactive*} is controlled directly by the command-line options -@samp{-b}, @samp{-i}, and @samp{-s} (@pxref{Invoking SCM}). If none of -these options are specified, the rules to determine interactivity are -more complicated; see @file{Init.scm} for details. -@end defvar +@menu +* Standards Compliance:: Links to sections in [R4RS] and [SLIB] +* Miscellaneous Procedures:: +* Time:: Both real time and processor time +* Interrupts:: and exceptions +* Process Synchronization:: Because interrupts are preemptive +* Files and Ports:: +* Soft Ports:: Emulate I/O devices +* Syntax Extensions:: +* Low Level Syntactic Hooks:: +* Syntactic Hooks for Hygienic Macros:: +@end menu -@defun abort -Resumes the top level Read-Eval-Print loop. -@end defun +@node Standards Compliance, Miscellaneous Procedures, The Language, The Language +@section Standards Compliance -@defun restart -Restarts the SCM program with the same arguments as it was originally -invoked. All @samp{-l} loaded files are loaded again; If those files -have changed, those changes will be reflected in the new session. +@noindent +Scm conforms to the +@ifset html +[IEEE], +@end ifset +@cite{IEEE Standard 1178-1990. IEEE Standard for the Scheme Programming +Language.} +@ifclear html +(@pxref{Bibliography}), +@end ifclear +and +@ifset html +[R4RS], +@end ifset +@cite{Revised(4) Report on the Algorithmic Language Scheme}. +@ifset html + +@end ifset +@ifinfo +@ref{Top, , , r4rs, Revised(4) Report on the Algorithmic Language +Scheme}. +@end ifinfo +All the required features of these specifications are supported. +Many of the optional features are supported as well. -@emph{Note:} When running a saved executable (@pxref{Dump}), -@code{restart} is redefined to be @code{exec-self}. -@end defun +@subheading Optionals of [R4RS] Supported by SCM -@defun exec-self -Exits and immediately re-invokes the same executable with the same -arguments. If the executable file has been changed or replaced since -the beginning of the current session, the @emph{new} executable will be -invoked. This differentiates @code{exec-self} from @code{restart}. -@end defun +@table @asis +@item two clause @code{if}: @code{(if )} +@xref{Conditionals, , , r4rs, Revised(4) Scheme}. +@item @code{let*} +@itemx named @code{let} +@xref{Binding constructs, , , r4rs, Revised(4) Scheme}. +@item @code{do} +@xref{Iteration, , , r4rs, Revised(4) Scheme}. +@item All varieties of @code{define} +@xref{Definitions, , , r4rs, Revised(4) Scheme}. +@item @code{list-tail} +@xref{Pairs and lists, , , r4rs, Revised(4) Scheme}. +@item @code{string-copy} +@itemx @code{string-fill!} +@xref{Strings, , , r4rs, Revised(4) Scheme}. +@item @code{make-vector} of two arguments +@itemx @code{vector-fill!} +@xref{Vectors, , , r4rs, Revised(4) Scheme}. +@item @code{apply} of more than 2 arguments +@xref{Control features, , , r4rs, Revised(4) Scheme}. +@item @code{-} and @code{/} of more than 2 arguments +@itemx @code{exp} +@itemx @code{log} +@itemx @code{sin} +@itemx @code{cos} +@itemx @code{tan} +@itemx @code{asin} +@itemx @code{acos} +@itemx @code{atan} +@itemx @code{sqrt} +@itemx @code{expt} +@itemx @code{make-rectangular} +@itemx @code{make-polar} +@itemx @code{real-part} +@itemx @code{imag-part} +@itemx @code{magnitude} +@itemx @code{angle} +@itemx @code{exact->inexact} +@itemx @code{inexact->exact} +@xref{Numerical operations, , , r4rs, Revised(4) Scheme}. +@item @code{delay} +@itemx @code{force} +@xref{Control features, , , r4rs, Revised(4) Scheme}. +@itemx @code{with-input-from-file} +@itemx @code{with-output-to-file} +@xref{Ports, , , r4rs, Revised(4) Scheme}. +@itemx @code{char-ready?} +@xref{Input, , , r4rs, Revised(4) Scheme}. +@itemx @code{transcript-on} +@itemx @code{transcript-off} +@xref{System interface, , , r4rs, Revised(4) Scheme}. +@end table -@defun verbose n -Controls how much monitoring information is printed. -If @var{n} is: +@subheading Optionals of [R4RS] not Supported by SCM @table @asis -@item 0 -no prompt or information is printed. -@item >= 1 -a prompt is printed. -@item >= 2 -the CPU time is printed after each top level form evaluated. -@item >= 3 -messages about heap growth are printed. -@item >= 4 -garbage collection (@pxref{Garbage Collection}) messages are printed. -@item >= 5 -a warning will be printed for each top-level symbol which is defined -more than one time. +@item @code{numerator} +@itemx @code{denominator} +@itemx @code{rationalize} +@xref{Numerical operations, , , r4rs, Revised(4) Scheme}. +@item [R4RS] appendix Macros +@xref{Macros, , , r4rs, Revised(4) Scheme}. @end table -@end defun -@defun gc -Scans all of SCM objects and reclaims for further use those that are -no longer accessible. -@end defun +@subheading [SLIB] Features of SCM and SCMLIT -@defun room -@defunx room #t -Prints out statistics about SCM's current use of storage. @code{(room #t)} -also gives the hexadecimal heap segment and stack bounds. -@end defun +@table @code +@item delay +@itemx full-continuation +@itemx ieee-p1178 +@itemx object-hash +@itemx rev4-report +@itemx source +See SLIB file @file{Template.scm}. +@item current-time +@xref{Time, , , slib, SLIB}. +@item defmacro +@xref{Defmacro, , , slib, SLIB}. +@item dynamic-wind +@xref{Dynamic-Wind, , , slib, SLIB}. +@item eval +@xref{System, , , slib, SLIB}. +@item getenv +@itemx system +@xref{System Interface, , , slib, SLIB}. +@item hash +@xref{Hashing, , , slib, SLIB}. +@item logical +@xref{Bit-Twiddling, , , slib, SLIB}. +@item multiarg-apply +@xref{Multi-argument Apply, , , slib, SLIB}. +@item multiarg/and- +@xref{Multi-argument / and -, , , slib, SLIB}. +@item rev4-optional-procedures +@xref{Rev4 Optional Procedures, , , slib, SLIB}. +@item string-port +@xref{String Ports, , , slib, SLIB}. +@item tmpnam +@xref{Input/Output, , , slib, SLIB}. +@item transcript +@xref{Transcripts, , , slib, SLIB}. +@item vicinity +@xref{Vicinity, , , slib, SLIB}. +@item with-file +@xref{With-File, , , slib, SLIB}. +@end table -@defvr Constant *scm-version* -Contains the version string (e.g. @file{4e6}) of SCM. -@end defvr +@subheading [SLIB] Features of SCM -@noindent -For other configuration constants and procedures @xref{Configuration, , -, slib, SLIB}. +@table @code +@item array +@xref{Arrays, , , slib, SLIB}. +@item array-for-each +@xref{Array Mapping, , , slib, SLIB}. +@item bignum +@itemx complex +@itemx inexact +@itemx rational +@itemx real +@xref{Require, , , slib, SLIB}. +@end table -@node Miscellaneous Procedures, Time, Internal State, The Language +@node Miscellaneous Procedures, Time, Standards Compliance, The Language @section Miscellaneous Procedures @defun try-load filename @@ -2218,8 +2557,10 @@ new object is returned. @end defun @defun copy-tree obj +@defunx @@copy-tree obj @xref{Tree Operations, copy-tree, , slib, SLIB}. This extends the SLIB -version by also copying vectors. +version by also copying vectors. Use @code{@@copy-tree} if you +depend on this feature; @code{copy-tree} could get redefined. @end defun @defun acons obj1 obj2 obj3 @@ -2235,7 +2576,7 @@ This command displays the GNU General Public License. Displays the text contents of @var{filename}. @end defun -@deffn Procedure print arg1 ... +@deffn Procedure 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. @@ -2414,7 +2755,7 @@ and with-error-to-file in that the first argument is a port, rather than a string naming a file. @end defun -@deffn {procedure} char-ready? +@deffn {procedure} char-ready? @deffnx {procedure} char-ready? port Returns @code{#t} if a character is ready on the input @var{port} and @@ -2497,6 +2838,26 @@ reached end-of-file. For example: @node Syntax Extensions, Low Level Syntactic Hooks, Soft Ports, The Language @section Syntax Extensions +@deffn {procedure} procedure-documentation proc +Returns the documentation string of @var{proc} if it exists, or +@code{#f} if not. + +If the body of a @code{lambda} (or the definition of a procedure) has +more than one expression, and the first expression (preceeding any +internal definitions) is a string, then that string is the +@dfn{documentation string} of that procedure. +@cindex documentation string + +@example +(procedure-documentation (lambda (x) "Identity" x)) @result{} "Identity" +(define (square x) + "Return the square of X." + (* x x)) +@result{} # +(procedure-documentation square) @result{} "Return the square of X." +@end example +@end deffn + @deffn {Read syntax} #. expression Is read as the object resulting from the evaluation of @var{expression}. This substitution occurs even inside quoted structure. @@ -2537,52 +2898,9 @@ ignored by the @code{read}. Nested @code{#|@dots{}|#} can occur inside @var{any thing}. @end deffn -@deffn {Read syntax} #! any thing -On the first line of a file will be ignored when loaded by SCM. This -makes SCM files usable as POSIX shell scripts if the first line is: - -@example -#!/usr/local/bin/scm -@end example - -When such a file is invoked it executes /usr/local/bin/scm with the -name of this file as the first argument. The following shell script -will print factorial of its argument: -@example -#!/usr/local/bin/scm -;;; -*-scheme-*- tells emacs this is a scheme file. -(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) -(display (fact (string->number (caddr (program-arguments))))) -(newline) -(quit) -@end example - -This technique has some drawbacks: -@itemize @bullet -@item -Some Unixes limit the length of the @samp{#!} interpreter line to the -size of an object file header, which can be as small as 32 bytes. -@item -A full, explicit pathname must be specified, perhaps requiring more than -32 bytes and making scripts vulnerable to programs being moved. -@end itemize - -The following approach solves both problems -- at the expense of -slightly slower startup. @code{type;} should appear on every line to be -executed by the shell. These lines do not have the length restriction -mentioned above. Also, @code{/bin/sh} searches the directories listed -in the `PATH' environment variable for @samp{scm}, eliminating the need -to know absolute locations in order to invoke a program. -@example -#!/bin/sh -type;exec scm $0 $* -;;; -*-scheme-*- tells emacs this is a scheme file. -(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n))))) -(display (fact (string->number (caddr (program-arguments))))) -(newline) -(quit) -@end example -@end deffn +@noindent +A similar read syntax @dfn{#!} (exclamation rather than vertical bar) is +supported for Posix shell-scripts (@pxref{Shell Scripts}). @defspec defined? symbol Equivalent to @code{#t} if @var{symbol} is a syntactic keyword (such as @@ -2606,7 +2924,7 @@ SCM also supports the following constructs from Common Lisp: @code{gentemp}. @xref{Defmacro, , , slib, SLIB}. -@node Low Level Syntactic Hooks, , Syntax Extensions, The Language +@node Low Level Syntactic Hooks, Syntactic Hooks for Hygienic Macros, Syntax Extensions, The Language @section Low Level Syntactic Hooks @deffn {Callback procedure} read:sharp c port @@ -2684,13 +3002,149 @@ have the same effect as @code{(@@call-with-current-continuation procedure)}. @end defspec +@node Syntactic Hooks for Hygienic Macros, , Low Level Syntactic Hooks, The Language +@section Syntactic Hooks for Hygienic Macros + +SCM provides a synthetic identifier type for efficient implementation of +hygienic macros (for example, @code{syntax-rules} @pxref{Macros, , , +r4rs, Revised(4) Scheme}) A synthetic identifier may be inserted in +Scheme code by a macro expander in any context where a symbol would +normally be used. Collectively, symbols and synthetic identifiers are +@emph{identifiers}. + +@defun identifier? obj +Returns @code{#t} if @var{obj} is a symbol or a synthetic +identifier, and @code{#f} otherwise. +@end defun + +If it is necessary to distinguish between symbols and synthetic identifiers, +use the predicate @code{symbol?}. + +A synthetic identifier includes two data: a parent, which is an +identifier, and an environment, which is either @code{#f} or a lexical +environment which has been passed to a macro expander +(a procedure passed as an argument to @code{procedure->macro}, +@code{procedure->memoizing-macro}, or @code{procedure->syntax}). + +@defun renamed-identifier parent env +Returns a synthetic identifier. @var{parent} must be an identifier, and +@var{env} must either be @code{#f} or a lexical environment passed to a +macro expander. @code{renamed-identifier} returns a distinct object for +each call, even if passed identical arguments. +@end defun + +There is no direct way to access the data internal to a synthetic +identifier, those data are used during variable lookup. If a synthetic +identifier is inserted as quoted data then during macro expansion it +will be repeatedly replaced by its parent, until a symbol is obtained. + +@subsection Use of synthetic identifiers +@code{renamed-identifier} may be used as a replacement for @code{gentemp}: +@lisp +(define gentemp + (let ((name (string->symbol "An unlikely variable"))) + (lambda () + (renamed-identifier name #f)))) +@end lisp + +If an identifier returned by this version of @code{gentemp} is inserted +in a binding position as the name of a variable then it is guaranteed +that no other identifier may denote that variable. If an identifier +returned by @code{gentemp} is inserted free, then it will denote the +top-level value bound to its parent, the symbol named ``An unlikely +variable''. This behavior, of course, is meant to be put to good use: + +@lisp +(define top-level-foo + (procedure->memoizing-macro + (lambda (exp env) + (renamed-identifier 'foo #f)))) +@end lisp + +Defines a macro which may always be used to refer to the top-level binding +of @code{foo}. + +@lisp +(define foo 'top-level) +(let ((foo 'local)) + (top-level-foo)) @result{} top-level +@end lisp + +In other words, we can avoid capturing @code{foo}. + +If a lexical environment is passed as the second argument to +@code{renamed-identifier} then if the identifier is inserted free +its parent will be looked up in that environment, rather than in +the top-level environment. The use of such an identifier @emph{must} +be restricted to the lexical scope of its environment. + +There is another restriction imposed for implementation convenience: +Macros passing their lexical environments to @code{renamed-identifier} +may be lexically bound only by the special forms @code{@@let-syntax} or +@code{@@letrec-syntax}. No error is signaled if this restriction is not +met, but synthetic identifier lookup will not work properly. + +@defspec @@let-syntax +@defspecx @@letrec-syntax +Behave as @code{let} and @code{letrec}, but may also put extra +information in the lexical environment so that @code{renamed-identifier} +will work properly during expansion of the macros bound by these forms. +@end defspec + +In order to maintain referential transparency it is necessary to +determine whether two identifiers have the same denotation. With +synthetic identifiers it is not necessary that two identifiers be +@code{eq?} in order to denote the same binding. + +@defun identifier-equal? id1 id2 env +Returns @code{#t} if identifiers @var{id1} and @var{id2} denote the same +binding in lexical environment @var{env}, and @code{#f} otherwise. +@var{env} must be a lexical environment passed to a macro transformer +during macro expansion. + +For example, +@lisp +(define top-level-foo? + (procedure->memoizing-macro + (let ((foo-name (renamed-identifier 'foo #f))) + (lambda (exp env) + (identifier-equal? (cadr exp) foo-name env))))) + +(top-level-foo? foo) @result{} #t + +(let ((foo 'local)) + (top-level-foo? foo)) @result{} #f +@end lisp +@end defun + +@defspec syntax-quote obj +Synthetic identifiers are converted to their parent symbols by @code{quote} +and @code{quasiquote} so that literal data in macro definitions will be +properly transcribed. @code{syntax-quote} behaves like @code{quote}, but +preserves synthetic identifier intact. +@end defspec + +@defspec the-macro mac +@code{the-macro} is the simplest of all possible macro transformers: +@var{mac} may be a syntactic keyword (macro name) or an expression +evaluating to a macro, otherwise an error is signaled. @var{mac} is +evaluated and returned once only, after which the same memoizied value is +returned. + +@code{the-macro} may be used to protect local copies of macros against +redefinition, for example: +@lisp +(@@let-syntax ((let (the-macro let))) + ;; code that will continue to work even if LET is redefined. + @dots{}) +@end lisp +@end defspec @node Packages, The Implementation, The Language, Top @chapter Packages @menu -* Executable path:: -* Compiling And Linking:: Hobbit and Dynamic Linking +* Compiling And Linking:: Hobbit * Dynamic Linking:: * Dump:: Create Fast-Booting Executables * Numeric:: Numeric Language Extensions @@ -2703,26 +3157,7 @@ procedure)}. * Sockets:: Cruise the Net @end menu -@node Executable path, Compiling And Linking, Packages, Packages -@section Executable path - -In order to dump a saved executable or to dynamically-link using DLD, -SCM must know where its executable file is. Sometimes SCM -(@pxref{Executable Pathname}) guesses incorrectly the location of the -currently running executable. In that case, the correct path can be set -by calling @code{execpath} with the pathname. - -@defun execpath -Returns the path (string) which SCM uses to find the executable file -whose invocation the currently running session is, or #f if the path is -not set. -@defunx execpath #f -@defunx execpath newpath -Sets the path to @code{#f} or @var{newpath}, respectively. The old path -is returned. -@end defun - -@node Compiling And Linking, Dynamic Linking, Executable path, Packages +@node Compiling And Linking, Dynamic Linking, Packages, Packages @section Compiling And Linking @defun compile-file name1 name2 @dots{} @@ -2775,10 +3210,28 @@ Compilation finished at Sun Jul 21 00:59:17 @noindent If SCM has been compiled with @file{dynl.c} then the additional -properties of load and require (from [SLIB]) specified here are -supported. The @code{require} forms are preferred. The variable -@code{*catalog*} can be extended to define other @code{require}-able -packages. See @file{Link.scm} for details. +properties of load and ([SLIB]) require specified here are supported. +The @code{require} form is preferred. + +@defun require feature +If the symbol @var{feature} has not already been given as an argument to +@code{require}, then the object and library files associated with +@var{feature} will be dynamically-linked, and an unspecified value +returned. If @var{feature} is not found in @code{*catalog*}, then an +error is signaled. +@end defun + +@defun usr:lib lib +Returns the pathname of the C library named @var{lib}. For example: +@code{(usr:lib "m")} returns @code{"/usr/lib/libm.a"}, the path of the C +math library. +@end defun + +@defun x:lib lib +Returns the pathname of the X library named @var{lib}. For example: +@code{(x:lib "X11")} returns @code{"/usr/X11/lib/libX11.sa"}, the path +of the X11 library. +@end defun @defun load filename lib1 @dots{} In addition to the [R4RS] requirement of loading Scheme expressions if @@ -2790,19 +3243,22 @@ instance). The object-suffix need not be given to load. For example, (load (in-vicinity (implementation-vicinity) "sc2")) or (load (in-vicinity (implementation-vicinity) "sc2.o")) or (require 'rev2-procedures) +@ftindex rev2-procedures or (require 'rev3-procedures) +@ftindex rev3-procedures @end example will load/link @file{sc2.o} if it exists. -The @var{lib1} @dots{} pathnames are for additional libraries which may be -needed for object files not produced by the Hobbit compiler. For +The @var{lib1} @dots{} pathnames specify additional libraries which may +be needed for object files not produced by the Hobbit compiler. For instance, crs is linked on Linux by @example (load (in-vicinity (implementation-vicinity) "crs.o") (usr:lib "ncurses") (usr:lib "c")) or (require 'curses) +@ftindex curses @end example Turtlegr graphics library is linked by: @@ -2811,6 +3267,7 @@ Turtlegr graphics library is linked by: (load (in-vicinity (implementation-vicinity) "turtlegr") (usr:lib "X11") (usr:lib "c") (usr:lib "m")) or (require 'turtle-graphics) +@ftindex turtle-graphics @end example And the string regular expression (@pxref{Regular Expression Pattern @@ -2822,16 +3279,10 @@ Matching}) package is linked by: or @example (require 'regex) +@ftindex regex @end example @end defun -@defun require 'db -@defunx require 'wb -Either form will dynamically load the WB database system from the -wb:vicinity (@file{../wb/}) specified in @file{Link.scm}. See -@file{scm/ANNOUNCE} for ftp sites where WB is available. -@end defun - @noindent The following functions comprise the low-level Scheme interface to dynamic linking. See the file @file{Link.scm} in the SCM distribution @@ -2885,15 +3336,12 @@ loaded file from the current SCM session. If successful, returned. @end defun -@defun usr:lib lib -Returns the pathname of the C library named lib. For example: -@code{(usr:lib "m")} could return @code{"/usr/lib/libm.a"}, the path of -the C math library. -@end defun @node Dump, Numeric, Dynamic Linking, Packages @section Dump +@ftindex dump +@ftindex unexec @dfn{Dump}, (also known as @dfn{unexec}), saves the continuation of an entire SCM session to an executable file, which can then be invoked as a program. Dumped executables start very quickly, since no Scheme code @@ -2956,7 +3404,7 @@ unspecified value. @end defun When a dumped executable is invoked, the variable @var{*interactive*} -(@pxref{System Interface}) has the value it possessed when @code{dump} +(@pxref{Internal State}) has the value it possessed when @code{dump} created it. Calling @code{dump} with a single argument sets @var{*interactive*} to @code{#f}, which is the state it has at the beginning of command line processing. @@ -3052,6 +3500,10 @@ must be a real number. It is an error if the value which should be returned by a call to these procedures is @emph{not} real. @end defun +@defun $log10 x +Real-only base 10 logarithm. +@end defun + @defun $atan2 y x Computes @code{(angle (make-rectangular x y))} for real numbers @var{y} and @var{x}. @@ -3251,6 +3703,9 @@ memory. @node Array Mapping, Uniform Array, Conventional Arrays, Arrays @subsection Array Mapping +@code{(require 'array-for-each)} +@ftindex array-for-each + @defun array-map! array0 proc array1 @dots{} If @var{array1}, @dots{} are arrays, they must have the same number of @@ -3826,7 +4281,7 @@ sender itself does not receive the signal. @item -1 If the process is privileged, send the signal to all -processes except for some special system processes. +processes except for some special system processes. Otherwise, send the signal to all processes with the same effective user ID. @@ -4663,7 +5118,7 @@ to most of the C @dfn{socket} library. For more information on sockets, @menu * Host Data:: -* Internet Addresses and Socket Names:: +* Internet Addresses and Socket Names:: * Socket:: @end menu @@ -4840,6 +5295,7 @@ This allows both reading and writing to the same port to work. If you want buffered ports you can (assuming sock-port is a socket i/o port): @example (require 'i/o-extensions) +@ftindex i/o-extensions (define i-port (duplicate-port sock-port "r")) (define o-port (duplicate-port sock-port "w")) @end example @@ -4936,7 +5392,9 @@ sockets for multiple connections without input blocking. ;;; To connect to chat `telnet localhost 8001' (require 'socket) +@ftindex socket (require 'i/o-extensions) +@ftindex i/o-extensions (let ((listener-socket (socket:bind (make-stream-socket af_inet) 8001)) (connections '())) @@ -4985,7 +5443,9 @@ or you can use a client written in scheme: ;;; characters from the socket to current-output-port. (require 'socket) +@ftindex socket (require 'i/o-extensions) +@ftindex i/o-extensions (define con (make-stream-socket af_inet)) (set! con (socket:connect con (inet:string->address "localhost") 8001)) @@ -5007,8 +5467,8 @@ or you can use a client written in scheme: @menu * Data Types:: * Operations:: +* Program Self-Knowledge:: What SCM needs to know about itself. * Improvements To Make:: -* Finishing Dynamic Linking:: @end menu @node Data Types, Operations, The Implementation, The Implementation @@ -5609,7 +6069,7 @@ iflag CCCCCCC101110100 isym CCCCCCC001110100} @r{ IMCAR: only in car of evaluated code, cdr has cell's GC bit} @t{ispcsym 000CCCC00CCCC100 -iloc 0DDDDDDDDDDDDDDDEFFFFFFF11111100 +iloc 0DDDDDDDDDDDEFFFFFFFFFFF11111100 pointer PPPPPPPPPPPPPPPPPPPPPPPPPPPPP000 gloc PPPPPPPPPPPPPPPPPPPPPPPPPPPPP001} @@ -5647,7 +6107,6 @@ asubr ..........int hpoff.....01100111 ...........SCM (*f)()........... subr_1o ..........int hpoff.....01101101 ...........SCM (*f)()........... subr_2o ..........int hpoff.....01101111 ...........SCM (*f)()........... lsubr_2 ..........int hpoff.....01110101 ...........SCM (*f)()........... -lsubr_2n..........int hpoff.....01110111 ...........SCM (*f)()........... rpsubr ..........int hpoff.....01111101 ...........SCM (*f)()...........} @r{ PTOBs:} @t{ port 0bwroxxxxxxxxG1110111 ..........FILE *stream.......... @@ -5675,7 +6134,7 @@ macro 000000000000000mxxxxxxxxG1111111 ...........SCM name............. array ...short rank..cxxxxxxxxG1111111 ............*array..............} @end format -@node Operations, Improvements To Make, Data Types, The Implementation +@node Operations, Program Self-Knowledge, Data Types, The Implementation @section Operations @menu @@ -6343,7 +6802,7 @@ the @var{argc} length array of null-terminated strings @var{argv}. If @code{NULL} terminated. @code{makfromstrs} is used by @code{run_scm} to convert the arguments SCM was called with to a @code{SCM} list which is the value of SCM procedure calls to @code{program-arguments} -(@pxref{System Interface, program-arguments}). +(@pxref{SCM Session, program-arguments}). @end deftypefun @deftypefun char **makargvfrmstrs (SCM @var{args}, char *@var{s_name}) @@ -6370,6 +6829,18 @@ continuations, but without all the rest of the SCM machinery. The concept of continuations is explained in @ref{Control features, call-with-current-continuation, , r4rs, Revised(4) Scheme}. +@noindent +The C constructs @code{jmp_buf}, @code{setjmp}, and @code{longjmp} +implement escape continuations. On VAX and Cray platforms, the setjmp +provided does not save all the registers. The source files +@file{setjump.mar}, @file{setjump.s}, and @file{ugsetjump.s} provide +implementations which do meet this criteria. + +@noindent +SCM uses the names @code{jump_buf}, @code{setjump}, and @code{longjump} +in lieu of @code{jmp_buf}, @code{setjmp}, and @code{longjmp} to prevent +name and declaration conflicts. + @deftp {Data type} CONTINUATION jmpbuf length stkbse other parent is a @code{typedef}ed structure holding all the information needed to represent a continuation. The @var{other} slot can be used to hold any @@ -6420,7 +6891,7 @@ Allocates (@code{malloc}) storage for a @code{CONTINUATION} of the current extent of stack. This newly allocated @code{CONTINUATION} is returned if successful, @code{0} if not. After @code{make_root_continuation} returns, the calling routine still needs -to @code{setjmp(@var{new_continuation}->jmpbuf)} in order to complete +to @code{setjump(@var{new_continuation}->jmpbuf)} in order to complete the capture of this continuation. @end deftypefun @@ -6430,7 +6901,7 @@ encapsulating) the stack state from @code{@var{parent_cont}->stkbse} to the current top of stack. The newly allocated @code{CONTINUATION} is returned if successful, @code{0}q if not. After @code{make_continuation} returns, the calling routine still needs to -@code{setjmp(@var{new_continuation}->jmpbuf)} in order to complete the +@code{setjump(@var{new_continuation}->jmpbuf)} in order to complete the capture of this continuation. @end deftypefun @@ -6444,7 +6915,7 @@ Sets @code{thrown_value} to @var{value} and returns from the continuation @var{cont}. If @code{CHEAP_CONTINUATIONS} is @code{#define}d, then -@code{throw_to_continuation} does @code{longjmp(@var{cont}->jmpbuf, val)}. +@code{throw_to_continuation} does @code{longjump(@var{cont}->jmpbuf, val)}. If @code{CHEAP_CONTINUATIONS} is not @code{#define}d, the CONTINUATION @var{cont} contains a copy of a portion of the C stack (whose bound must @@ -6456,7 +6927,7 @@ the stack is grown larger than the saved stack, if neccessary. @item the saved stack is copied back into it's original position. @item -@code{longjmp(@var{cont}->jmpbuf, val)}; +@code{longjump(@var{cont}->jmpbuf, val)}; @end itemize @end deftypefun @@ -6576,7 +7047,185 @@ environment. @code{eval} copies @code{expression} so that memoization does not modify @code{expression}. @end deftypefun -@node Improvements To Make, Finishing Dynamic Linking, Operations, The Implementation +@node Program Self-Knowledge, Improvements To Make, Operations, The Implementation +@section Program Self-Knowledge + +@menu +* File-System Habitat:: +* Executable Pathname:: +* Script Support:: +@end menu + +@node File-System Habitat, Executable Pathname, Program Self-Knowledge, Program Self-Knowledge +@subsection File-System Habitat + +@noindent +Where should software reside? Although individually a minor annoyance, +cumulatively this question represents many thousands of frustrated user +hours spent trying to find support files or guessing where packages need +to be installed. Even simple programs require proper habitat; games +need to find their score files. + +@noindent +Aren't there standards for this? Some Operating Systems have devised +regimes of software habitats -- only to have them violated by large +software packages and imports from other OS varieties. + +@noindent +In some programs, the expected locations of support files are fixed at +time of compilation. This means that the program may not run on +configurations unanticipated by the authors. Compiling locations into a +program also can make it immovable -- necessitating recompilation to +install it. + +@quotation +Programs of the world unite! You have nothing to lose but loss itself. +@end quotation + +@noindent +The function @code{scm_find_impl_file} in @file{scm.c} is an attempt to +create a utility (for inclusion in programs) which will hide the details +of platform-dependent file habitat conventions. It takes as input the +pathname of the executable file which is running. If there are systems +for which this information is either not available or unrelated to the +locations of support files, then a higher level interface will be +needed. + +@deftypefun char *scm_find_impl_file(char *@var{exec_path}, char +*@var{generic_name}, char *@var{initname}, char *@var{sep}) Given the +pathname of this executable (@var{exec_path}), test for the existence of +@var{initname} in the implementation-vicinity of this program. Return a +newly allocated string of the path if successful, 0 if not. The +@var{sep} argument is a @emph{null-terminated string} of the character +used to separate directory components. +@end deftypefun + +@itemize @bullet +@item +One convention is to install the support files for an executable program +in the same directory as the program. This possibility is tried first, +which satisfies not only programs using this convention, but also +uninstalled builds when testing new releases, etc. + +@item +Another convention is to install the executables in a directory named +@file{bin}, @file{BIN}, @file{exe}, or @file{EXE} and support files in a +directroy named @file{lib}, which is a peer the executable directory. +This arrangement allows multiple executables can be stored in a single +directory. For example, the executable might be in +@samp{/usr/local/bin/} and initialization file in +@samp{/usr/local/lib/}. + +If the executable directory name matches, the peer directroy @file{lib} +is tested for @var{initname}. + +@item +Sometimes @file{lib} directories become too crowded. So we look in any +subdirectories of @file{lib} or @file{src} having the name (sans type +suffix such as @samp{.EXE}) of the program we are running. For example, +the executable might be @samp{/usr/local/bin/foo} and initialization +file in @samp{/usr/local/lib/foo/}. + +@item +But the executable name may not be the usual program name; So also look +in any @var{generic_name} subdirectories of @file{lib} or @file{src} +peers. + +@item +Finally, if the name of the executable file being run has a (system +dependent) suffix which is not needed to invoke the program, then look +in a subdirectory (of the one containing the executable file) named for +the executable (without the suffix); And look in a @var{generic_name} +subdirectory. For example, the executable might be +@samp{C:\foo\bar.exe} and the initialization file in @samp{C:\foo\bar\}. +@end itemize + + +@node Executable Pathname, Script Support, File-System Habitat, Program Self-Knowledge +@subsection Executable Pathname + +@noindent +For purposes of finding @file{Init.scm}, dumping an executable, and +dynamic linking, a SCM session needs the pathname of its executable +image. + +@noindent +When a program is executed by MS-DOS, the full pathname of that +executable is available in @code{argv[0]}. This value can be passed +directly to @code{scm_find_impl_file} (@pxref{File-System Habitat}). + +@noindent +In order to find the habitat for a unix program, we first need to know +the full pathname for the associated executable file. + +@deftypefun char *dld_find_executable (const char *@var{command}) +@code{dld_find_executable} returns the absolute path name of the file +that would be executed if @var{command} were given as a command. It +looks up the environment variable @var{PATH}, searches in each of the +directory listed for @var{command}, and returns the absolute path name +for the first occurrence. Thus, it is advisable to invoke +@code{dld_init} as: + +@example +main (int argc, char **argv) +@{ + @dots{} + if (dld_init (dld_find_executable (argv[0]))) @{ + @dots{} + @} + @dots{} +@} +@end example + +@quotation +@strong{Note:} If the current process is executed using the +@code{execve} call without passing the correct path name as argument 0, +@code{dld_find_executable (argv[0]) } will also fail to locate the +executable file. +@end quotation + +@code{dld_find_executable} returns zero if @code{command} is not found +in any of the directories listed in @code{PATH}. +@end deftypefun + +@node Script Support, , Executable Pathname, Program Self-Knowledge +@subsection Script Support + +@noindent +Source code for these C functions is in the file @file{script.c}. +@ref{Shell Scripts} for a description of script argument processing. + +@noindent +@code{script_find_executable} is only defined on unix systems. + +@deftypefun char *script_find_executable (const char *@var{name}) +@code{script_find_executable} returns the path name of the +executable which will is invoked by the script file @var{name}; +@var{name} if it is a binary executable (not a script); or 0 if +@var{name} does not exist or is not executable. +@end deftypefun + +@deftypefun char **script_process_argv(int @var{argc}; char **@var{argv}) +Given an @dfn{main} style argument vector @var{argv} and the number of +arguments, @var{argc}, @code{script_process_argv} returns a newly +allocated argument vector in which the second line of the script being +invoked is substituted for the corresponding meta-argument. +@tindex meta-argument + +If the script does not have a meta-argument, or if the file named by the +argument following a meta-argument cannot be opened for reading, then 0 +is returned. + +@code{script_process_argv} correctly processes argument vectors of +nested script invocations. +@end deftypefun + +@deftypefun int script_count_argv(char **@var{argv}) +Returns the number of argument strings in @var{argv}. +@end deftypefun + + +@node Improvements To Make, , Program Self-Knowledge, The Implementation @section Improvements To Make @itemize @bullet @@ -6609,11 +7258,6 @@ with a frame which calls the contin just created. This in combination with checking stack depth could also be used to allow stacks deeper than 64K on the IBM PC. @item -lookupcar in @file{eval.c} should @emph{not} memoize (to @code{ILOC}s) -when it retrieves environments deeper or longer than 4095. The values -can still be retrieved (albeit slowly), but an @code{ILOC} should not be -made. The @code{MEMOIZE_LOCALS} flag could then be flushed. -@item The @code{must-} or @code{make-} routines need some sort of C macros or conditionalization so that they check: @@ -6632,8 +7276,12 @@ is also used for allocating heap segments, which do not have the @code{must_malloc()} should be tested for speed impact. @end itemize -@node Finishing Dynamic Linking, , Improvements To Make, The Implementation -@section Finishing Dynamic Linking +@menu +* Finishing Dynamic Linking:: +@end menu + +@node Finishing Dynamic Linking, , Improvements To Make, Improvements To Make +@subsection Finishing Dynamic Linking @noindent Scott Schwartz suggests: One way to @@ -6903,7 +7551,7 @@ This is an alphabetical list of all the global variables in SCM. @node Type Index, , Variable Index, Top @unnumbered Type Index -This is an alphabetical list of all the data types in SCM. +This is an alphabetical list of data types and feature names in SCM. @printindex tp -- cgit v1.2.3