diff options
Diffstat (limited to 'scm.texi')
| -rw-r--r-- | scm.texi | 2606 |
1 files changed, 1627 insertions, 979 deletions
@@ -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 +<A HREF="http://www-swiss.ai.mit.edu/~jaffer/SCM.html"> +@end ifset + +@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html + +@ifset html +</A> +@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 -<A HREF="http://www-swiss.ai.mit.edu/~jaffer/SCM.html"> -@end ifset - -@center http://www-swiss.ai.mit.edu/~jaffer/SCM.html - -@ifset html -</A> -@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,429 +366,15 @@ 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 - -@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 -Upon startup @code{scm} loads the file specified by by the environment -variable @var{SCM_INIT_PATH}. - -@noindent -If @var{SCM_INIT_PATH} is not defined or if the file it names is not -present, @code{scm} tries to find the directory containing the -executable file. If it is able to locate the executable, @code{scm} -looks for the initialization file (usually @file{Init.scm}) in -platform-dependent directories relative to this directory. -@xref{File-System Habitat} for a blow-by-blow description. - -@noindent -As a last resort (if initialization file cannot be located), the C -compile parameter @var{IMPLINIT} (defined in the makefile or -@file{scmfig.h}) is tried. - -@noindent -Unless the option @code{-no-init-file} or @code{--no-init-file} occurs -in the command line, @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. - -@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. - -@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 SCM Options, SCM Variables, Invoking SCM, Overview -@section Options - -@noindent -The options are processed in the order specified on the command line. - -@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 - -@deffn {Command Option} -l filename -@deffnx {Command Option} -f filename -loads @var{filename}. @code{Scm} will load the first (unoptioned) file -named on the command line if no @code{-c}, @code{-e}, @code{-f}, -@code{-l}, or @code{-s} option preceeds -it. -@end deffn - -@deffn {Command Option} -p level -sets the prolixity (verboseness) to @var{level}. This is the same as -the @code{scm} command (verobse @var{level}). -@end deffn - -@deffn {Command Option} -v -(verbose mode) specifies that @code{scm} will print prompts, evaluation -times, notice of loading files, and garbage collection statistics. This -is the same as @code{-p3}. -@end deffn - -@deffn {Command Option} -q -(quiet mode) specifies that @code{scm} will print no extra -information. This is the same as @code{-p0}. -@end deffn - -@deffn {Command Option} -m -specifies that subsequent loads, evaluations, and user interactions will -be with [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 - -@deffn {Command Option} - -@deffnx {Command Option} -- -specifies that there are no more options on the command line. -@end deffn - -@deffn {Command Option} -d filename -loads SLIB database-utilities and opens @var{filename} as a database. -@end deffn - -@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}). - -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 - -@deffn {Command Option} --help -prints usage information and URL; then exit. -@end deffn - -@deffn {Command Option} --version -prints version information and exit. -@end deffn - -@node SCM Variables, SCM Examples, SCM Options, Overview -@section Environment Variables - -@defvr {Environment Variable} SCM_INIT_PATH -is the pathname where @code{scm} will look for its initialization -code. The default is the file @file{Init.scm} in the source directory. -@end defvr - -@defvr {Environment Variable} SCHEME_LIBRARY_PATH -is the [SLIB] Scheme library directory. -@end defvr - -@defvr {Environment Variable} HOME -is the directory where @file{Init.scm} will look for the user -initialization file @file{ScmInit.scm}. -@end defvr - -@section Scheme Variables - -@defvar *argv* -contains the list of arguments to the program. @code{*argv*} can change -during argument processing. This list is suitable for use as an argument -to [SLIB] @code{getopt}. -@end defvar - -@defvar *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 Examples, SCM Session, SCM Variables, Overview -@section Examples - -@table @code -@item % scm foo.scm -Loads and executes the contents of @file{foo.scm} and then enters -interactive session. - -@item % scm -f foo.scm arg1 arg2 arg3 -Parameters @code{arg1}, @code{arg2}, and @code{arg3} are stored in the -global list @code{*argv*}; Loads and executes the contents of -@file{foo.scm} and exits. - -@item % scm -s foo.scm arg1 arg2 -Sets *argv* to @code{("foo.scm" "arg1" "arg2")} and enters interactive -session. - -@item % scm -e `(write (list-ref *argv* *optind*))' bar -Prints @samp{"bar"}. - -@item % scm -rpretty-print -r format -i -Loads @code{pretty-print} and @code{format} and enters interactive -session. - -@item % scm -r5 -Loads @code{dynamic-wind}, @code{values}, and [R4RS] macros and enters -interactive (with macros) session. - -@item % scm -r5 -r4 -Like above but @code{rev4-optional-procedures} are also loaded. -@end table - -@node SCM Session, Editing Scheme Code, SCM Examples, Overview -@section SCM Session - -@itemize @bullet -@item -Options, file loading and features can be specified from the command -line. @xref{System interface, , , scm, SCM}. @xref{Require, , , slib, -SLIB}. -@item -Typing the end-of-file character at the top level session (while SCM is -not waiting for parenthesis closure) causes SCM to exit. -@item -Typing the interrupt character aborts evaluation of the current form -and resumes the top level read-eval-print loop. -@end itemize - -@node Editing Scheme Code, Debugging Scheme Code, SCM Session, Overview -@section Editing Scheme Code - -@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 -@end itemize -@end ifclear - -@ifset html -<A HREF="file://ftp-swiss.ai.mit.edu/pub/scheme-editor-packages/cmuscheme.el"> -ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/cmuscheme.el -</A> -<A HREF="file://ftp-swiss.ai.mit.edu/pub/scheme-editor-packages/comint.el"> -ftp-swiss.ai.mit.edu:/pub/scheme-editor-packages/comint.el -</A> -@end ifset - -These files are already standard in Emacs 19. - -If your Emacs can not run a process in a buffer, see ``under other -systems'' below. - -@item Epsilon (MS-DOS): -There is lisp (and scheme) mode available by use of the package -@samp{LISP.E}. It offers several different indentation formats. With -this package, buffers holding files ending in @samp{.L}, @samp{.LSP}, -@samp{.S}, and @samp{.SCM} (my modification) are automatically put into -lisp-mode. - -It is possible to run a process in a buffer under Epsilon. With Epsilon -5.0 the command line options @samp{-e512 -m0} are neccessary to manage -RAM properly. It has been reported that when compiling SCM with Turbo -C, you need to @samp{#define NOSETBUF} for proper operation in a process -buffer with Epsilon 5.0. - -One can also call out to an editor from SCM if RAM is at a premium; See -``under other systems'' below. - -@item other systems: -Define the environment variable @samp{EDITOR} to be the name of the -editing program you use. The SCM procedure @code{(ed arg1 @dots{})} -will invoke your editor and return to SCM when you exit the editor. The -following definition is convenient: - -@example -(define (e) (ed "work.scm") (load "work.scm")) -@end example - -Typing @samp{(e)} will invoke the editor with the file of interest. -After editing, the modified file will be loaded. -@end table - -@node Debugging Scheme Code, , Editing Scheme Code, Overview -@section Debugging Scheme Code - -@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. - -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 -There are several SLIB macros which so useful that SCM automatically -loads the appropriate module from SLIB if they are invoked. - -@defmac trace proc1 @dots{} -Traces the top-level named procedures given as arguments. -@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 - -@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 - -The routine I use most for debugging is: - -@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. - -One can just insert @samp{(print '<proc-name>} and @samp{)} around an -expression in order to see its value as a program operates. -@end deffn - -@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. - -When @code{trace} is not sufficient to find program flow problems, -@ifset html -<A HREF="http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html"> -@end ifset -SLIB-PSD, the Portable Scheme Debugger -@ifset html -</A> -@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 - - -@node Installing SCM, The Language, Overview, Top +@node Installing SCM, Operational Features, Overview, Top @chapter Installing SCM @menu -* File-System Habitat:: All the usual suspects. -* Executable Pathname:: Where did I come from? -* Making SCM:: -* Building SCM:: +* 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:: @@ -797,133 +384,7 @@ ftp.cs.indiana.edu:/pub/scheme-repository/utl/slib-psd1-3.tar.gz * Reporting Problems:: @end menu -@node File-System Habitat, Executable Pathname, Installing SCM, Installing SCM -@section 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{mull-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, Making SCM, File-System Habitat, Installing SCM -@section Executable Pathname - -@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}). - -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 Making SCM, Building SCM, Executable Pathname, Installing SCM +@node Making SCM, SLIB, Installing SCM, Installing SCM @section Making SCM The SCM distribution has @dfn{Makefile} which contains rules for making @@ -956,13 +417,93 @@ Buy a SCM executable from jaffer@@ai.mit.edu. See the end of the Use scmconfig (From: bos@@scrg.cs.tcd.ie): 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 +@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 +[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 +<A HREF="file://ftp-swiss.ai.mit.edu/pub/scm/slib2c0.tar.gz"> +ftp-swiss.ai.mit.edu:/pub/scm/slib2c0.tar.gz +</A> +<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2c0.tar.gz"> +prep.ai.mit.edu:/pub/gnu/jacal/slib2c0.tar.gz +</A> +<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2c0.tar.gz"> +ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2c0.tar.gz +</A> +<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2c0.tar.gz"> +ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2c0.tar.gz +</A> +@end ifset + +@noindent +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 +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: + +@example +(define library-vicinity + (let ((lv (string-append (implementation-vicinity) "../slib/"))) + (lambda () lv))) +(load (in-vicinity (library-vicinity) "require")) +@end example + +@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. -@node Building SCM, SLIB, Making SCM, Installing SCM + +@node Building SCM, Installing Dynamic Linking, SLIB, Installing SCM @section Building SCM The file @dfn{build.scm} builds and runs a relational database of how to @@ -974,11 +515,13 @@ additions to jaffer@@ai.mit.edu. @menu * Invoking Build:: * Build Options:: +* Compiling and Linking Custom Files:: @end menu @node Invoking Build, Build Options, Building SCM, Building SCM @subsection Invoking Build +@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}. @@ -988,7 +531,7 @@ From the SCM source directory, type @samp{build} followed by up to 9 command line arguments. @item unix -From the SCM source directory, type @samp{build.scm} followed by command +From the SCM source directory, type @samp{./build.scm} followed by command line arguments. @item @emph{all} @@ -998,7 +541,51 @@ type @code{(load "build.scm")}. Alternatively, start @samp{scm} or @end table -@node Build Options, , Invoking Build, Building SCM +@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. + +@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 + +@noindent +To cross compile for another platform, invoke build with the @samp{-p} +or @samp{---platform=} option. This will create a script for the +platform named in the @samp{-p} or @samp{---platform=} option. + +@example +bash$ ./build.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 + + +@node Build Options, Compiling and Linking Custom Files, Invoking Build, Building SCM @subsection Build Options @noindent @@ -1025,6 +612,7 @@ 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 @@ -1034,14 +622,14 @@ 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 +linux-aout i386 linux gcc microsoft-c 8086 ms-dos microsoft-c -microsoft-c-nt i386 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* +sunos sparc sunos *unknown* svr4 *unknown* unix *unknown* turbo-c-2 8086 ms-dos turbo-c unicos cray unicos *unknown* @@ -1292,91 +880,73 @@ 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 memoize-local-bindings -Saves the interpeter from having to look up local bindings for every -identifier reference +@item macro +C level support for hygienic and referentially transparent macros (R4RS +macros). @end table @end deffn -@node SLIB, Installing Dynamic Linking, Building SCM, Installing SCM -@section SLIB +@node Compiling and Linking Custom Files, , Build Options, Building SCM +@subsection Compiling and Linking Custom Files @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: +A correspondent asks: -@ifclear html -@itemize @bullet -@item -ftp-swiss.ai.mit.edu:/pub/scm/slib2a6.tar.gz -@item -prep.ai.mit.edu:/pub/gnu/jacal/slib2a6.tar.gz -@item -ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a6.tar.gz -@item -ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2a6.tar.gz -@end itemize -@end ifclear - -@ifset html -<A HREF="file://ftp-swiss.ai.mit.edu/pub/scm/slib2a6.tar.gz"> -ftp-swiss.ai.mit.edu:/pub/scm/slib2a6.tar.gz -</A> -<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2a6.tar.gz"> -prep.ai.mit.edu:/pub/gnu/jacal/slib2a6.tar.gz -</A> -<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2a6.tar.gz"> -ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a6.tar.gz -</A> -<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2a6.tar.gz"> -ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2a6.tar.gz -</A> -@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}. +@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 -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: +(@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: @example -(define (library-vicinity) "/usr/local/lib/slib/") -(load (in-vicinity (library-vicinity) "require")) +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 @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: +To make a dynamically loadable object file use the @code{-t dll} option: @example -(define library-vicinity - (let ((lv (string-append (implementation-vicinity) "../slib/"))) - (lambda () lv))) -(load (in-vicinity (library-vicinity) "require")) +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 @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. +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 Installing Dynamic Linking, Saving Images, SLIB, Installing SCM +@node Installing Dynamic Linking, Configure Module Catalog, Building SCM, Installing SCM @section Installing Dynamic Linking @noindent @@ -1430,7 +1000,63 @@ when linking, compile and link against the file @end quotation -@node Saving Images, Automatic C Preprocessor Definitions, Installing Dynamic Linking, Installing SCM +@node Configure Module Catalog, Saving Images, Installing Dynamic Linking, Installing SCM +@section Configure Module Catalog + +@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. + +If @var{object-file} exists, @code{add-link} returns @code{#t}, +otherwise it returns @code{#f}. + +For example, to install a compiled dll @file{foo}, add these lines to +@file{mkimpcat.scm}: + +@example + (add-link 'foo + (in-vicinity (implementation-vicinity) "foo" + link:able-suffix)) +@end example + + +@end defun + +@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. + +@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 +Remember to delete the file @file{slibcat} after modifying the file +@file{mkimpcat.scm} in order to force SLIB to rebuild its cache. + +@node Saving Images, Automatic C Preprocessor Definitions, Configure Module Catalog, Installing SCM @section Saving Images @noindent @@ -1479,6 +1105,7 @@ __ZTC__ Zortech C _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?) @@ -1489,23 +1116,32 @@ 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. +__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 @node Problems Compiling, Problems Linking, Automatic C Preprocessor Definitions, Installing SCM @@ -1700,186 +1336,281 @@ and date of that distribution. In this case, corresponding with the vendor is recommended. @end enumerate -@node The Language, Packages, Installing SCM, Top -@chapter The Language - -This section describes features which are either present in all builds -of SCM or which must be enabled when SCM is compiled. +@node Operational Features, The Language, Installing SCM, Top +@chapter Operational Features @menu -* Standards Compliance:: Links to sections in [R4RS] and [SLIB] -* System Interface:: Like how to exit +* Invoking SCM:: +* SCM Options:: +* Invocation Examples:: +* SCM Variables:: +* SCM Session:: +* Editing Scheme Code:: +* Debugging Scheme Code:: * 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:: +* Memoized Expressions:: +* Internal State:: +* Shell Scripts:: @end menu -@node Standards Compliance, System Interface, The Language, The Language -@section Standards Compliance +@node Invoking SCM, SCM Options, Operational Features, Operational Features +@section Invoking 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 @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], <A HREF="r4rs_toc.html"> -@end ifset -@cite{Revised(4) Report on the Algorithmic Language Scheme}. -@ifset html -</A> -@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. +Upon startup @code{scm} loads the file specified by by the environment +variable @var{SCM_INIT_PATH}. -@subheading Optionals of [R4RS] Supported by 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. -@table @asis -@item two clause @code{if}: @code{(if <test> <consequent>)} -@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 +@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. -@subheading Optionals of [R4RS] not Supported by SCM +@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. -@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 +@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. -@subheading [SLIB] Features of SCM and SCMLIT +@noindent +This explanation applies to SCMLIT or other builds of SCM. -@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 +@noindent +Scheme-code files can also invoke SCM and its variants. @xref{Syntax +Extensions, #!}. -@subheading [SLIB] Features of SCM +@node SCM Options, Invocation Examples, Invoking SCM, Operational Features +@section Options + +@noindent +The options are processed in the order specified on the command line. + +@deffn {Command Option} -a 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 + +@deffn {Command Option} -l filename +@deffnx {Command Option} -f filename +loads @var{filename}. @code{Scm} will load the first (unoptioned) file +named on the command line if no @code{-c}, @code{-e}, @code{-f}, +@code{-l}, or @code{-s} option preceeds +it. +@end deffn + +@deffn {Command Option} -p level +sets the prolixity (verboseness) to @var{level}. This is the same as +the @code{scm} command (verobse @var{level}). +@end deffn + +@deffn {Command Option} -v +(verbose mode) specifies that @code{scm} will print prompts, evaluation +times, notice of loading files, and garbage collection statistics. This +is the same as @code{-p3}. +@end deffn + +@deffn {Command Option} -q +(quiet mode) specifies that @code{scm} will print no extra +information. This is the same as @code{-p0}. +@end deffn + +@deffn {Command Option} -m +specifies that subsequent loads, evaluations, and user interactions will +be with [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 + +@deffn {Command Option} - +@deffnx {Command Option} -- +specifies that there are no more options on the command line. +@end deffn + +@deffn {Command Option} -d filename +loads SLIB database-utilities and opens @var{filename} as a database. +@end deffn + +@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}). + +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 + +@deffn {Command Option} --help +prints usage information and URL; then exit. +@end deffn + +@deffn {Command Option} --version +prints version information and exit. +@end deffn + +@node Invocation Examples, SCM Variables, SCM Options, Operational Features +@section Invocation Examples @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}. +@item % scm foo.scm +Loads and executes the contents of @file{foo.scm} and then enters +interactive session. + +@item % scm -f foo.scm arg1 arg2 arg3 +Parameters @code{arg1}, @code{arg2}, and @code{arg3} are stored in the +global list @code{*argv*}; Loads and executes the contents of +@file{foo.scm} and exits. + +@item % scm -s foo.scm arg1 arg2 +Sets *argv* to @code{("foo.scm" "arg1" "arg2")} and enters interactive +session. + +@item % scm -e `(write (list-ref *argv* *optind*))' bar +Prints @samp{"bar"}. + +@item % scm -rpretty-print -r format -i +Loads @code{pretty-print} and @code{format} and enters interactive +session. + +@item % scm -r5 +Loads @code{dynamic-wind}, @code{values}, and [R4RS] macros and enters +interactive (with macros) session. + +@item % scm -r5 -r4 +Like above but @code{rev4-optional-procedures} are also loaded. @end table -@node System Interface, Errors, Standards Compliance, The Language -@section System Interface +@node SCM Variables, SCM Session, Invocation Examples, Operational Features +@section Environment Variables -@noindent -For documentation of the procedures @code{getenv} and @code{system} -@xref{System Interface, , , slib, SLIB}. +@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 + +@defvr {Environment Variable} HOME +is the directory where @file{Init.scm} will look for the user +initialization file @file{ScmInit.scm}. +@end defvr + +@defvr {Environment Variable} EDITOR +is the name of the program which @code{ed} will call. If @var{EDITOR} +is not defined, the default is @samp{ed}. +@end defvr + +@section Scheme Variables + +@defvar *argv* +contains the list of arguments to the program. @code{*argv*} can change +during argument processing. This list is suitable for use as an argument +to [SLIB] @code{getopt}. +@end defvar + +@defvar *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 +Options, file loading and features can be specified from the command +line. @xref{System interface, , , scm, SCM}. @xref{Require, , , slib, +SLIB}. +@item +Typing the end-of-file character at the top level session (while SCM is +not waiting for parenthesis closure) causes SCM to exit. +@item +Typing the interrupt character aborts evaluation of the current form +and resumes the top level read-eval-print loop. +@end itemize @defun quit @defunx quit n @@ -1890,42 +1621,193 @@ 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 these commands will invoke the editor or -debugger respectively. +If SCM is compiled under VMS this @code{vms-debug} will invoke the VMS +debugger. @end defun -@defun ed filename + +@node Editing Scheme Code, Debugging Scheme Code, SCM Session, Operational Features +@section Editing Scheme Code + +@defun ed arg1 @dots{} +The value of the environment variable @code{EDITOR} (or just @code{ed} +if it isn't defined) is invoked as a command with arguments @var{arg1} +@dots{}. + +@defunx ed filename If SCM is compiled under VMS @code{ed} will invoke the editor with a single the single argument @var{filename}. - -@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 -@defun program-arguments -Returns a list of strings of the arguments scm was called with. -@end defun -@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 +@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: -@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 +@ifclear html +@itemize @bullet +@item +http://simtel.coast.net/SimTel/gnu/demacs.html +@end itemize +@end ifclear + +@ifset html +<A HREF="http://simtel.coast.net/SimTel/gnu/demacs.html"> +http://simtel.coast.net/SimTel/gnu/demacs.html +</A> +@end ifset + +If your Emacs can run a process in a buffer you can use the Emacs +command @samp{M-x run-scheme} with SCM. Otherwise, use the emacs +command @samp{M-x suspend-emacs}; or see ``other systems'' below. + +@item Epsilon (MS-DOS): +There is lisp (and scheme) mode available by use of the package +@samp{LISP.E}. It offers several different indentation formats. With +this package, buffers holding files ending in @samp{.L}, @samp{.LSP}, +@samp{.S}, and @samp{.SCM} (my modification) are automatically put into +lisp-mode. + +It is possible to run a process in a buffer under Epsilon. With Epsilon +5.0 the command line options @samp{-e512 -m0} are neccessary to manage +RAM properly. It has been reported that when compiling SCM with Turbo +C, you need to @samp{#define NOSETBUF} for proper operation in a process +buffer with Epsilon 5.0. + +One can also call out to an editor from SCM if RAM is at a premium; See +``under other systems'' below. + +@item other systems: +Define the environment variable @samp{EDITOR} to be the name of the +editing program you use. The SCM procedure @code{(ed arg1 @dots{})} +will invoke your editor and return to SCM when you exit the editor. The +following definition is convenient: + +@example +(define (e) (ed "work.scm") (load "work.scm")) +@end example + +Typing @samp{(e)} will invoke the editor with the file of interest. +After editing, the modified file will be loaded. +@end table + +@node Debugging Scheme Code, Errors, Editing Scheme Code, Operational Features +@section Debugging Scheme Code + +@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)}. -@node Errors, Memoized Expressions, System Interface, The Language +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. + +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 +There are several SLIB macros which so useful that SCM automatically +loads the appropriate module from SLIB if they are invoked. + +@defmac trace proc1 @dots{} +Traces the top-level named procedures given as arguments. +@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 + +@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 + +The routines I use most frequently for debugging are: + +@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 '<proc-name>} 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 + +@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. + +When @code{trace} is not sufficient to find program flow problems, +@ifset html +<A HREF="http://www.cs.tut.fi/staff/pk/scheme/psd/article/article.html"> +@end ifset +SLIB-PSD, the Portable Scheme Debugger +@ifset html +</A> +@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 + + +@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 -@subsection CAUTIOUS enhancements +@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 + +@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 @@ -2097,7 +2007,7 @@ open-input-file @result{} @end example -@node Internal State, Miscellaneous Procedures, Memoized Expressions, The Language +@node Internal State, Shell Scripts, Memoized Expressions, Operational Features @section Internal State @defvar *interactive* @@ -2162,14 +2072,443 @@ also gives the hexadecimal heap segment and stack bounds. @end defun @defvr Constant *scm-version* -Contains the version string (e.g. @file{4e6}) of SCM. +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 Miscellaneous Procedures, Time, Internal State, The Language + +@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 +#!/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 +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 +#!/usr/local/bin/scm \ +@end example + +@noindent +The following shell-script will print its expanded argument list, then +factorial of its argument: + +@example +#!/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 +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 + +@noindent +With these two programs installed in a @code{PATH} directory, we have +the following syntax for @var{<program>.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 + +@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. + +@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 The Language, Packages, Operational Features, Top +@chapter The Language + +@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 + +@node Standards Compliance, Miscellaneous Procedures, 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.} +@ifclear html +(@pxref{Bibliography}), +@end ifclear +and +@ifset html +[R4RS], <A HREF="r4rs_toc.html"> +@end ifset +@cite{Revised(4) Report on the Algorithmic Language Scheme}. +@ifset html +</A> +@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 + +@table @asis +@item two clause @code{if}: @code{(if <test> <consequent>)} +@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 + +@subheading Optionals of [R4RS] not Supported by SCM + +@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 + +@subheading [SLIB] Features of SCM and SCMLIT + +@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 + +@subheading [SLIB] Features of SCM + +@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, 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{} #<unspecified> +(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 <schwartz@@galapagos.cse.psu.edu> 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 |